取数协调
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 结束;调用前已中止的不发起跳转。取数本身不停。
