概览
消息仓库包 @openmaxai/chat-store 的概览:状态、两个入口、在宿主里怎么接,以及全部导出的索引。
概览
@openmaxai/chat-store 是 Chat SDK 的消息仓库包:每个会话一段按 seq 排好的已加载区间和一个水位,数据只经一个写入口进来,缺的消息由补洞调度从水位往后取。它不依赖 React,不碰 DOM,不发请求,也不依赖任何其它聊天包。
这一组页面按包里现有的源码写,是这个包自己的接口参考:本页是概览(状态、入口、在宿主里怎么接、全部导出的索引),每个导出的签名和说明分在下面八页。补洞的时刻和规则见实时与同步 · 补洞。
本节内容
- 仓库:
createChatStore、ChatStore、仓库参数ChatStoreOptions、会话快照ChatConversationSnapshot、请求结果缓存createChatRequestCache、只在内存的成员仓库createChatMemberStore、只在内存的会话仓库createChatConversationStore,只在内存的已读游标块createChatReadCursorStore和它的取数层createChatReadCursorLoader,以及 Agent 执行过程的归并纯函数applyAgentActivityFrame、sweepAgentActivityRuns、selectConversationAgentActivityRuns和只在内存的运行表createChatAgentActivityStore。 - 写入事件:唯一写入口
dispatch收的ChatStoreEvent和它的十三种事件,含请求时的水位requestWatermark、乐观发送和乐观改动。 - 订阅:订阅回调
ChatStoreListener、一次变化ChatStoreChange和区间变化ChatStoreDataEvent。 - 补洞调度:
createChatGapFillScheduler和它的参数、读接口、各个时刻的入口与结果,以及按改动日志补改动。 - 存储与数据类型:存储接口
ChatStorage与createMemoryStorage、createIndexedDbStorage、本机数据参数ChatLocalDataOptions与加密ChatStorageEncryption、ChatMessage等消息数据类型、CHAT_STORE_VERSION。 - 取数协调:
createChatThreadLoader和它的参数、读接口ChatThreadSource、会话和单条消息的读取状态、跳到一条消息(ChatMessageTarget、ChatJumpResult);不用 React 的页面也能用。 - React 绑定:
@openmaxai/chat-store/react的ChatStoreProvider和读仓库的 hookuseMessages、useMessage、useMessageByClientId,以及读会话仓库的useConversationList、useConversation、useUnread,和读已读游标块的useReadCursors。 - 检查接口:
@openmaxai/chat-store/inspect的inspectChatStore:每个会话和全局的只读检查快照、仓库事件流、存储用量估算。
状态
- 代码已在 main 上。 下面「已有」一条列的都在仓库里,本组页面按这些源码写。
- 还没接到界面。 今天
@openmaxai/chat的组件不读它,@openmaxai/chat-sdk也还没再导出它。例外是成员仓库:@openmaxai/chat-sdk的宿主一份一个,宿主上同步的identity.getMember、listMembers从它读,取回的成员表写进它。 - API 还可能变。 所有导出都标
@experimental,名字和形状都可能调整。 - 已有: 仓库本体和唯一写入口
dispatch(含乐观发送对账和表态、编辑、撤回的乐观改动)、补洞调度、请求结果缓存、只在内存的成员仓库(参与者、每个会话的成员关系、当前用户的会话内角色与组织角色)、只在内存的会话仓库(会话列表的分页与重取、合并失效、「在默认列表里」与行缓存分开记、按 id 取一个会话、置顶隐藏静音未读的补丁、明确移除、可注入的重试策略)、只在内存的已读游标块和它的取数层(自己的已读位置与回执游标、快照与实时信号的合并、按代号丢掉清空之前发出的请求的结果、每会话一笔在途的已读上报)、Agent 执行过程的归并纯函数与只在内存的运行表(前端去重、跳号、失联、淘汰、总量上限,时刻由调用方给)、取数协调、存储接口ChatStorage和它的内存、IndexedDB 实现(单标签页锁、配额满时淘汰、加密开关)、仓库句柄上打开与清掉本机数据的openLocalData、clearLocalData(含换了用户登录时的自动清)与按会话清的clearConversation、写进来的服务端消息和水位落到本机、打开会话时先画本机已有的消息再补洞、按改动日志补回离开期间对已有消息的改动(编辑、撤回、删除、表态、卡片落定)、切走的会话只留水位、卸掉的一端按seq读回(本机有就读本机的)、从外部跳到一条消息(按服务端 id,或按自己发出的那条的client_msg_id;不在窗口里时换入围着它的一窗,本机有就读本机的)、按client_msg_id读自己发出的那条、消息数据类型,React 入口里的ChatStoreProvider和useMessages、useMessage、useMessageByClientId、useConversationList、useConversation、useUnread、useReadCursors七个 hook,以及检查入口里的只读检查接口inspectChatStore。 - 还没有: 读仓库里还没有的数据(未读总数、Agent 运行等)的 hook。会话仓库还没接到
@openmaxai/chat-sdk。按会话的配额淘汰只认 IndexedDB 存储里「最久没读过」的会话,不认仓库里哪些会话正开着。
入口
| 入口 | 里面有什么 | 依赖 |
|---|---|---|
@openmaxai/chat-store |
仓库、补洞调度、请求结果缓存、成员仓库、会话仓库、Agent 执行过程的归并纯函数与运行表、取数协调、存储接口与内存、IndexedDB 实现、消息数据类型、版本常量 | 没有运行期依赖 |
@openmaxai/chat-store/react |
把仓库交给组件的 Provider、读仓库的 hook、版本常量 | peer react 19(可选),只有这个入口可以依赖它 |
@openmaxai/chat-store/inspect |
只读检查接口:检查快照、事件流、存储用量估算 | 没有运行期依赖 |
在宿主里怎么用
仓库不认识宿主,也不发请求:宿主(或将来的 SDK 通用层)负责取数,把结果交给 dispatch;界面从 getSnapshot 读,用 subscribe 知道什么时候重读。补洞调度只需要两个读接口,形状和宿主的 messaging 相同,可以直接把它交进去。
chat-store-wiring.ts
import { createChatGapFillScheduler, createChatStore } from "@openmaxai/chat-store";
// 每个宿主(每个登录用户)一份。
const store = createChatStore();
const gapFill = createChatGapFillScheduler({ store, source: host.messaging });
async function openConversation(conversationId: string) {
// 发请求前记下水位,交给 windowLoaded:迟到的一窗和「水位那条被删了」由此分得清。
const requestWatermark = store.getSnapshot(conversationId).watermark;
const page = await host.messaging.loadThread(conversationId);
store.dispatch({
type: "windowLoaded",
conversationId,
messages: page.messages,
hasOlder: page.nextCursor !== undefined,
olderCursor: page.nextCursor,
hasNewer: false,
requestWatermark,
});
await gapFill.open(conversationId);
}
// 界面:变化通知只说「哪个会话、区间怎么变的」,数据从快照读。
const unsubscribe = store.subscribe(conversationId, (change) => {
render(store.getSnapshot(conversationId), change);
});
其余时刻交给对应的入口:
| 什么时候 | 调什么 |
|---|---|
| 推送带来一条消息的新内容(新消息、编辑、撤回、表态、卡片结果) | store.dispatch({ type: "messageUpserted", conversationId, message }) |
| 一条消息被硬删除 | store.dispatch({ type: "messageDeleted", conversationId, messageId }) |
| 往上翻历史取到一页 | store.dispatch({ type: "olderLoaded", … }),beforeSeq 是发请求时区间最早那条的 seq |
| 往下翻(窗口没接到最新时)取到一页 | store.dispatch({ type: "newerLoaded", … }) |
| 视图停在哪条消息附近变了 | store.dispatch({ type: "viewChanged", conversationId, anchorMessageId }) |
| 自己发出一条(或重试) | store.dispatch({ type: "sendStarted", conversationId, message }),message.client_msg_id 必填,同时交给后端 |
| 发送有了结果 | store.dispatch({ type: "sendSettled", conversationId, clientMsgId, outcome, … });成功但发送接口没返回消息时再调 gapFill.sent(conversationId) |
| 自己表态、编辑、撤回 | 先 store.dispatch({ type: "patchStarted", … }),请求结束后 patchSettled |
| 实时信号里的表态变化(谁、哪种、加还是减) | store.dispatch({ type: "reactionChanged", conversationId, messageId, reactorId, code, added, byMe }) |
实时 messages 信号(会话有新消息) |
gapFill.messages(conversationId) |
| 实时连接重连成功 | gapFill.reconnected() |
| 页面从后台回到前台 | gapFill.foreground() |
| 切走或关掉会话 | gapFill.close(conversationId) |
| 登录后、打开会话之前 | await store.openLocalData(userId) |
退出登录、收到无法恢复的 401 |
await store.clearLocalData();草稿由宿主自己删,设备 id 保留 |
| 退群、群被解散、被移出 | await store.clearConversation(conversationId);按 id 取回的单条消息另用 requestCache.remove(["@openmaxai/chat-store", "message", conversationId]) 删,草稿由宿主自己删 |
| 退出登录、拆掉宿主 | gapFill.dispose() |
快照在没有变化时是同一个对象,没变的消息也是同一个对象,所以 React 里可以直接用 useSyncExternalStore 接 subscribe 和 getSnapshot。
@openmaxai/chat-store
根入口。下表是它的全部导出,链接指向写着签名和说明的那一页。
签名块从源码生成,说明是手写的;包内测试检查两者都没落下任何导出。
@openmaxai/chat-store/react
React 绑定入口。只有这个入口可以依赖 react(包的 peer 依赖,标为可选)。hook 只订阅,取数交给根入口的取数协调器。
| 导出 | 种类 | 说明 |
|---|---|---|
ChatStoreProvider |
组件 | 把仓库交给下面的组件 |
ChatStoreProviderProps |
接口 | Provider 的参数 |
useChatStore |
hook | 拿到 Provider 交下来的仓库 |
useMessages |
hook | 读一个会话的消息窗口,带翻页 |
UseMessagesResult |
接口 | useMessages 的返回值 |
useMessage |
hook | 读一条消息 |
useMessageByClientId |
hook | 按 client_msg_id 读自己发出的那条 |
UseMessageResult |
接口 | useMessage、useMessageByClientId 的返回值 |
useConversationList |
hook | 读会话列表,带翻页 |
UseConversationListResult |
接口 | useConversationList 的返回值 |
useConversation |
hook | 读一个会话,不在仓库里时按 id 取 |
UseConversationResult |
接口 | useConversation 的返回值 |
useUnread |
hook | 读一个会话的未读 |
useReadCursors |
hook | 读一个会话的已读游标 |
CHAT_STORE_VERSION |
常量 | 同根入口 |
应用代码将来读仓库用的 hook,本入口目前只实现了其中的 useMessages、useMessage、useConversation、useUnread(另有 useMessageByClientId 和 useConversationList),与目标的差别见 React 绑定。
@openmaxai/chat-store/inspect
检查入口:只读地看仓库此刻的内部状态,调试面板建在它上面。不依赖 React;不用它的应用不受影响,第一次调 inspectChatStore 之前仓库不为它多记任何东西(只常记 IndexedDB 存储改用内存的原因)。
| 导出 | 种类 | 说明 |
|---|---|---|
inspectChatStore |
函数 | 拿到一个仓库的检查器 |
ChatStoreInspector |
接口 | 检查器:两个快照、一个事件流、一个存储估算 |
ChatStoreConversationInspection |
接口 | 一个会话的检查快照 |
ChatStoreWindowInspection |
接口 | 内存里的区间 |
ChatStoreGap |
接口 | 一段还没拿到的 seq |
ChatStoreGapFillInspection |
接口 | 补洞的进度 |
ChatStoreGapFillRun |
接口 | 补完的一次补洞 |
ChatGapFillTrigger |
类型 | 触发补洞的时刻 |
ChatStoreChangeLogInspection |
接口 | 改动水位与补改动的进度 |
ChatStoreCatchUpRun |
接口 | 上一次补改动 |
ChatStoreSendInspection |
接口 | 一条本端消息 |
ChatStorePatchInspection |
接口 | 一笔在途改动 |
ChatStoreLocalSegmentInspection |
接口 | 本机那一段 |
ChatStoreGlobalInspection |
接口 | 全局的检查快照:会话、存储、实时信号 |
ChatStoreStorageInspection |
接口 | 本机存储 |
ChatStoreWriteError |
接口 | 最近一次写失败 |
ChatStoreRealtimeInspection |
接口 | 实时信号 |
ChatStoreSignal |
接口 | 补洞调度收到的一个实时信号 |
ChatStoreInspectRecord |
类型 | 事件流里的一条 |
ChatStoreSnapshotArea |
类型 | snapshot 记录说快照的哪一块变了 |
ChatStoreEventSource |
类型 | 一次 dispatch 是谁发的 |
ChatStoreInspectListener |
类型 | 事件流的回调 |
ChatStoreStorageEstimate |
接口 | 本机存储大约占多大 |
