OpenMax
免费试用

取数协调

createChatThreadLoader:首次取一窗、翻页、打开与关掉补洞、单条消息按需取,不依赖 React;读接口 ChatThreadSource 和读取状态。

取数协调

@openmaxai/chat-store 根入口里关于取数协调的导出。状态、在宿主里怎么接和全部导出的索引见概览。

取数协调器替读仓库的一方去后端取:首次取一窗、往上翻和往下翻、打开和关掉补洞、不在窗口里的单条消息、跳到一条消息时围着它的一窗,并按会话记在途和失败。它不依赖 React,不碰 DOM;取回的数据一律经仓库的写入口写回,读取状态由仓库快照和这些记录派生。React 绑定的 hook 只订阅它、调它;不用 React 的页面直接用它。

chat-thread-loader.ts

import {
  createChatGapFillScheduler,
  createChatStore,
  createChatThreadLoader,
} from "@openmaxai/chat-store";

// 每个宿主(每个登录用户)一份。
const store = createChatStore();
const gapFill = createChatGapFillScheduler({ store, source: host.messaging });
const loader = createChatThreadLoader({ store, source: host.messaging, gapFill });

// 进入会话:第一个读者到来时取最新一窗(或直接补洞),返回离开时调的函数。
const leave = loader.openThread(conversationId);
const unsubscribe = loader.subscribeThread(conversationId, () => {
  const { messages, status, error, hasOlder } = loader.getThread(conversationId);
  render(messages, status, error, hasOlder);
});

// 往上翻、失败重试。
await loader.loadOlder(conversationId);
loader.retry(conversationId);

// 离开会话:最后一个读者离开时关掉补洞。
unsubscribe();
leave();

重连、回到前台和 messages 信号仍由你交给补洞调度(gapFill.reconnected() 等),见概览 · 在宿主里怎么用。

createChatThreadLoader

function createChatThreadLoader(options: ChatThreadLoaderOptions): ChatThreadLoader;

建一个取数协调器。每个仓库(每个宿主)一个;ChatStoreProvider 用它的参数自己建一个。options.store 不是 createChatStore 建的仓库时抛 TypeError。

ChatThreadLoaderOptions

interface ChatThreadLoaderOptions {
  store: ChatStore;
  source: ChatThreadSource;
  gapFill?: ChatGapFillScheduler;
  requestCache?: ChatRequestCache;
  newerPageLimit?: number;
}
字段 说明
store 读写的仓库。
source 读接口,见 ChatThreadSource。
gapFill 补洞调度器,必须建在同一个 store 上。会话打开时调它的 open,最后一个读者离开时调 close;几个协调器共用一个补洞调度时按会话合计读者,所有协调器的读者都离开了才调 close。不给时不补洞。
requestCache 存取回的单条消息用的请求结果缓存,键是 ["@openmaxai/chat-store", "message", conversationId, messageId]。不给时自己建一个。
newerPageLimit loadNewer 按 newerCursor 往更新翻时一页要几条,作为 options.limit 交给 source.loadThread。不给时不带 limit,页大小由读接口自己定。没有游标、按 seq 往后取(本机那一段、loadThreadSince)时不用它。

ChatThreadLoader

interface ChatThreadLoader {
  openThread(conversationId: string): () => void;
  getThread(conversationId: string): ChatThreadReadState;
  subscribeThread(conversationId: string, listener: () => void): () => void;
  loadOlder(conversationId: string): Promise<void>;
  loadNewer(conversationId: string): Promise<void>;
  retry(conversationId: string): void;
  openMessage(conversationId: string, messageId: string): () => void;
  getMessage(conversationId: string, messageId: string): ChatMessageReadState;
  subscribeMessage(conversationId: string, messageId: string, listener: () => void): () => void;
  retryMessage(conversationId: string, messageId: string): void;
  openMessageByClientId(conversationId: string, clientMessageId: string): () => void;
  getMessageByClientId(conversationId: string, clientMessageId: string): ChatMessageReadState;
  subscribeMessageByClientId(conversationId: string, clientMessageId: string, listener: () => void): () => void;
  retryMessageByClientId(conversationId: string, clientMessageId: string): void;
  jumpTo(conversationId: string, target: ChatMessageTarget, options?: ChatJumpOptions): Promise<ChatJumpResult>;
}
方法 说明
openThread 一个读者开始读这个会话,返回离开时调的函数(重复调用无害)。第一个读者到来算打开:仓库里还没有这个会话的区间时先换入一窗,然后调补洞调度的 open;已有区间时直接 open。换入的一窗:仓库的本机数据打开着、本机存着这个会话、又能补洞(给了补洞调度、读接口有 loadThreadSince)时,是本机那一段最新的一页(至多 50 条),补洞从它的末尾往后取;否则调 source.loadThread 取最新一窗。读本机失败、或读的期间本机那一段作废了(见写进本机)、换了用户时,照样取最新一窗。读接口有改动日志(loadChangesSince 和 getMessagesByIds)而本机那一段没有改动水位(改动日志上线之前存下的)时,作废这一段、取最新一窗:不知道它补到了哪一笔改动。补洞调度在补完新消息后接着补改动,补改动失败也记成补洞那一步失败,retry 再补一次。最后一个读者离开时调 close,并经写入口发 conversationClosed:这个会话的消息从内存去掉、只留水位,再打开时重新换入一窗(本机有就从本机读)。几个协调器读同一个仓库时按会话合计读者,都离开了才关。离开推迟到微任务里判断,所以离开后立刻又来的读者(StrictMode 的卸载又挂载)接着用,不会关了又开。关掉之后这个会话不再补洞,补洞失败时的 retry 也什么都不做。读者都走了以后才取回的一窗照样写进仓库,随即关掉。几个读者同时读同一个会话只换入一窗、只补一次洞。
getThread / subscribeThread 这个会话此刻的读取状态(见 ChatThreadReadState),和它的变化通知。不用先 openThread:仓库里已有的会话直接是 ready。
loadOlder 更早还有时取一页,接到窗口前面(olderLoaded)。有 olderCursor 时按它调 loadThread;没有游标(更早一端被卸掉了、窗口是从本机读的)时按 seq 从区间最早那条往前取:本机那一段里有就读本机的(至多 50 条),否则调 loadThread(conversationId, undefined, { aroundSeq }) 取围着区间最早那条的一窗、留下它之前的部分,之后按这一窗的 nextCursor 接着翻。读接口不认 aroundSeq(回的一窗既没有 newerCursor、也够不着区间最早那条)时 reject。失败时 reject,已有消息不动。
loadNewer 窗口没接到最新时,有 newerCursor 就按它调 loadThread 往更新取一页(给了 newerPageLimit 时带上 limit);没有就按 seq 从区间末尾往后取:本机那一段里有就读本机的,否则调 loadThreadSince。接到窗口后面(newerLoaded)。从本机读的一页总说后面还有,接到最新那一步由后端说。读接口没有 loadThreadSince、又没有游标、本机也没有时 reject。补洞调度开了 latestWindowOnGap、留着一份还接不上的最新那一窗时(见补洞调度),翻之前先按区间末尾判一次:接得上就当场接上、不发请求;否则照常翻一页,翻回来之后再判一次。接上之后再补一次洞。
retry 重做失败的那一步(取一窗、补洞、往上翻或往下翻);没有失败的时什么都不做。重做再失败只记下,不 reject。最后一个读者离开后补洞已停:失败的是补洞时,这时调它什么都不做,要等下一次 openThread。
openMessage 一个读者开始读这条消息,返回离开时调的函数。这条不在会话的内存窗口里时调 source.loadMessage 取一次;读着的期间这条离开了窗口也再取。取回的那条存在请求结果缓存里(同一条只取一次),不写进仓库:仓库的写入口只收和已加载区间接得上的消息。
getMessage / subscribeMessage 这条消息此刻的读取状态(见 ChatMessageReadState),和它的变化通知。
retryMessage 这条不在窗口里、上一次取失败了时再取一次;其他情况什么都不做。请求结果缓存连失败也缓存(没失效时 load 直接以缓存的原因 reject),所以它先让缓存里这条失效再取;重取在途时再调等同一次,不发第二个请求。
openMessageByClientId 一个读者开始按 client_msg_id 读自己发出的那条,返回离开时调的函数。还没换成服务端那条时什么都不取(本端那条就在仓库里);换上之后、服务端那条不在窗口里时,同 openMessage 按服务端那条的 id 取。
getMessageByClientId / subscribeMessageByClientId 自己发出的那条此刻的读取状态,和它的变化通知,见下文按 client_msg_id 读一条。
retryMessageByClientId 已经换成服务端那条时,同 retryMessage 重取那一条;其他情况什么都不做。
jumpTo 跳到一条消息:让它进到这个会话的窗口里,见下文跳到一条消息。

同一会话同一时刻只有一次取最新一窗、一次往上翻、一次往下翻在途,重复调用拿到同一个 promise;跳转见下文跳到一条消息。

失败后不自动重试:只有 retry、retryMessage,或会话的下一次打开、消息的下一次 openMessage(以及读着的期间这条离开窗口)才再取;单条消息上一次取失败时,这几处都先让请求结果缓存里这条失效再取,取成功过的照旧直接用缓存里的。订阅通知(包括请求结果缓存里这条失效)不会触发取数,所以照着通知重读状态不会形成重试循环。

跳到一条消息

jumpTo(conversationId, target, options?) 是视口控制器收到 jump(要滚到某条消息)时要的那一窗:目标在已加载的窗口里就不取,不在就换入围着它的一窗。来源不限于消息列表里的点击(引用、@提及),聊天之外的模块要定位到某条消息(例如从一次 Agent 运行跳到触发它的那条),也是调它;目标可以是服务端那条的 id,也可以是自己发出的那条的 client_msg_id(刚发出、还没有服务端 id 的也行),见 ChatMessageTarget。

  • 在窗口里(在 getSnapshot(conversationId).messages 里):不取,直接得到 found。
  • 知道 seq(target.seq,只是提示):换入围着它的一窗。本机数据打开着、本机那一段覆盖这个 seq、读出的一窗里有它、读接口有 loadThreadSince 时,读本机那一段里它和它之前的至多 25 条、之后的至多 25 条,不发请求;否则调 loadThread(conversationId, undefined, { aroundSeq })。读接口有改动日志而本机那一段没有改动水位时不用本机的(同 openThread)。
  • 不知道 seq,或按提示的 seq 取的那一窗里没有它:先调 loadMessage 取它(和 openMessage 共用请求结果缓存,取过的不再取),再按它的 seq 换入一窗。loadMessage 返回 undefined、或读接口没有这个方法时得到 notFound。
  • 自己发出的那条:已经换成服务端那条的,按服务端那条跳(服务端那条没带回 client_msg_id 时,靠仓库记下的对应关系找到它,至多记最近 500 条)。还是本端那条的,发送中、已确认还没对上的排在最新那条之后:窗口没接到最新时换入最新一窗,之后照常补洞;失败、被拦的按它所在的位置换入一窗。
  • 换入的一窗按 windowLoaded 的规则写进仓库:至多 500 条;没接到最新时不补洞、不写进本机,messages 信号只记数;之后往上翻、往下翻按游标或 seq 接着取,同 loadOlder、loadNewer;换窗时在途的翻页是对着旧窗口取的,回来后接不上、被丢掉,换窗后的第一次 loadOlder、loadNewer 不复用它,直接按新窗口取;被丢下的那次之后不管成败都不记进读取状态(失败不留 error、retry 不为它重翻,成功也不清掉新那次的失败),调用方拿到的 promise 照样按它的成败落定。删掉过的那条直接得到 notFound,不取。

同一目标在途、而且它就是最近一次跳转时,返回同一个 promise(A → B → A 连着跳时,第三次自己取,不复用已被 B 顶替的那次)。换了目标(包括目标已在窗口里、不用取的那一次)时,在途的那次不再写进仓库,得到 superseded;在途的首次取窗(openThread 换入的那一窗)也一样,不再冲掉跳到的那一窗。最近一次跳转落定却没换入窗口(notFound、失败了)、这个会话有读者却还没有窗口时,照常换入最新一窗(同 openThread;首次取窗还在途时等它回来换入),不会一直停在 loading。读接口 reject 时 jumpTo reject,已有消息不动,记成这一步失败:retry 重跳最近一次跳转的目标,error 留着到再跳成功;之后再跳一次(包括目标已在窗口里、不用取的那一次)就换掉这次失败,error 清掉,retry 不再重跳它;仓库里还没有这个会话时 status 为 error,直到上面那一窗换入;那一窗也失败时记成取窗失败,retry 重取最新一窗。这个会话没有读者时取回的一窗随即关掉(同 openThread),所以先 openThread、再 jumpTo。协调器不读时间:取窗超时由调用方自己定,到点中止 options.signal(见 ChatJumpOptions):这次调用立即得到 aborted,取数不停,晚到的一窗照上面的规则写进仓库;调用前已中止的不发起跳转。

按 client_msg_id 读一条

getMessageByClientId(conversationId, clientMessageId) 读自己发出的那条:发送入口返回的只有 client_msg_id,本端那条换成服务端那条以后 id 会变,按 id 读的 getMessage 跟不上它。

  • 还没换成服务端那条时,message 是本端那条(delivery_status 是发送中、失败或被拦,或已确认还没对上),status 为 ready;窗口没接到最新、它不在快照里时也给。
  • 换上之后,同 getMessage 读服务端那条:在窗口里时是仓库里那条,不在时是按它的 id 取回的那条(要有读者 openMessageByClientId)。服务端那条没带回 client_msg_id 时,靠仓库记下的对应关系找到它(至多记最近 500 条,会话关掉后仍记得)。
  • 仓库里没有这个 client_msg_id、或换上的那条已被删掉时,status 为 ready、message 为 undefined。

ChatThreadReadState

interface ChatThreadReadState {
  readonly messages: readonly ChatMessage[];
  readonly status: ChatReadStatus;
  readonly error: unknown;
  readonly isFetching: boolean;
  readonly hasOlder: boolean;
  readonly hasNewer: boolean;
}

一个会话的读取状态,没有变化时是同一个对象(可以直接交给 useSyncExternalStore)。

字段 说明
messages 这个会话在内存里的窗口,同 getSnapshot(conversationId).messages。没变的消息保持同一个对象。
status 见 ChatReadStatus。只有第一次取一窗(或跳转)就失败、仓库里还没有这个会话时是 error;重取期间回到 loading。
error 最近一次失败的原因,那一步之后成功了才清掉。已有数据时补洞或翻页失败,数据不动,status 仍是 ready。
isFetching 经这个协调器发出的取数正在进行:首次加载、打开时的补洞、翻页、跳转。重连、回到前台、messages 信号触发的补洞由调用方直接交给补洞调度,不计入。status 为 loading 时总是 true。
hasOlder 更早还有。
hasNewer 窗口没接到最新。

error 是读接口 reject 的原样值,仓库包这一层不包装;@openmaxai/chat-sdk/react 再导出这些 hook 时由 SDK 把它包成 SDK 的错误类型,那一步不在本包。ChatMessageReadState 的 error 同样如此。

ChatMessageReadState

interface ChatMessageReadState {
  readonly message: ChatMessage | undefined;
  readonly status: ChatReadStatus;
  readonly error: unknown;
  readonly isFetching: boolean;
}

一条消息的读取状态,没有变化时是同一个对象。这条在窗口里时 message 是仓库里那条、status 为 ready;不在时是取回的那条,不随实时更新变化,之后这条进了窗口就换成仓库里那条。loadMessage 返回 undefined(已删除、无权访问)或读接口没有这个方法时,status 为 ready、message 为 undefined。error 是最近一次取失败的原因。

ChatReadStatus

type ChatReadStatus =
  | "loading"
  | "ready"
  | "error";
值 含义
loading 仓库里还没有这份数据,正在取。
ready 有数据(后台可能还在补洞)。
error 第一次取就失败了,没有数据。

ChatThreadSource

interface ChatThreadSource extends ChatGapFillSource {
  loadThread(conversationId: string, cursor?: string, options?: {
    direction?: "older" | "newer";
    aroundSeq?: number;
    limit?: number;
  }): Promise<ChatThreadSourcePage>;
  loadMessage?(conversationId: string, messageId: string): Promise<ChatMessage | undefined>;
}

取数协调用的读接口,由调用方注入。形状和宿主的 messaging 相同,可以直接把宿主的 messaging 交进来;它也是一个 ChatGapFillSource,同一个对象可以交给补洞调度。

方法 说明
loadThread 取一页。不带 cursor 是最新一窗;带了 cursor 时,options.direction 缺省或为 "older" 表示往更早翻(cursor 是上一页的 nextCursor),"newer" 表示往更新翻(cursor 是 newerCursor)。不带 cursor、带了 options.aroundSeq 时是围着这个 seq 的一窗,同宿主 messaging.loadThread 的这一格;loadOlder 没有游标时用它。 options.limit 是这一页最多要几条的上限提示,只用于往更新翻与最新一窗(同宿主 ChatThreadLoadOptions.limit):读接口可以不认、也可以截短,协调器只认返回的游标判有没有更多。
loadThreadSince 从某个 seq 往后取,同补洞调度。loadNewer 在窗口没有往更新的游标时用它。
loadMessage 按 id 取一条消息;取不到时返回 undefined。不给时只读仓库里有的。

改动日志的两个方法 loadChangesSince、getMessagesByIds 来自 ChatGapFillSource,由补洞调度用来补改动;同一个对象交给取数协调和补洞调度时,取数协调据此判断本机那一段能不能用。

ChatThreadSourcePage

interface ChatThreadSourcePage extends ChatGapFillLatestPage {
  newerCursor?: string;
}

loadThread 取到的一页,同宿主 messaging.loadThread 的返回值。nextCursor 给了表示更早还有;newerCursor 给了表示这一页没接到最新(围着某条取的一窗、往更新翻还没到头的一页)。headChangeSeq(来自 ChatGapFillLatestPage)是同一快照的改动编号:换入的一窗以它为改动水位,往前、往后接的一页比改动水位旧时让它退回。

ChatMessageTarget

type ChatMessageTarget =
  | {
      messageId: string;
      seq?: number;
    }
  | {
      clientMessageId: string;
    };

jumpTo 跳到哪条消息:服务端那条的 id(seq 只是取窗的提示,可以不给),或自己发出的那条的 client_msg_id(刚发出、还没有服务端 id 和 seq 的,或已经换成服务端那条的)。字段名用 clientMessageId,和消息上的 client_msg_id、写入口事件里的 clientMsgId 是同一个值。

ChatJumpResult

type ChatJumpResult =
  | {
      outcome: "found";
      messageId: string;
    }
  | {
      outcome: "notFound";
    }
  | {
      outcome: "superseded";
    }
  | {
      outcome: "aborted";
    };

一次 jumpTo 的结果。

outcome 含义
found 目标此刻在会话的消息里。messageId 是那一行的 id:还没换成服务端那条的本端消息就是它的 client_msg_id,换上之后是服务端那条的 id。
notFound 没有这条:服务端说不在(已删除、看不到)、仓库里删掉过,或取不到它的 seq。要取的那一窗照样换入了,落在它原来所在的位置。
superseded 还没取完,这个会话又有了一次 jumpTo,这一次的结果不再写进仓库。
aborted 调用方交的 signal 在结果出来之前中止了。取数不停,晚到的一窗照样写进仓库;调用方据此不再落位。

ChatJumpOptions

interface ChatJumpOptions {
  signal?: AbortSignal;
}

jumpTo 的选项。signal 中止后这次调用立即以 aborted 结束;调用前已中止的不发起跳转。取数本身不停。