OpenMax
免费试用

概览

消息仓库包 @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 和读仓库的 hook useMessages、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

根入口。下表是它的全部导出,链接指向写着签名和说明的那一页。

导出 种类 说明
createChatStore 函数 建一个消息仓库
ChatStore 接口 仓库:dispatch、subscribe、getSnapshot
ChatStoreOptions 接口 createChatStore 的参数
ChatConversationSnapshot 接口 一个会话此刻的数据
createChatRequestCache 函数 建一个请求结果缓存
ChatRequestCache 接口 请求结果缓存
ChatRequestEntry 接口 一个键此刻的结果
ChatRequestKey 类型 请求的键
ChatRequestListener 类型 一个键的结果变了时的回调
createChatMemberStore 函数 建一个只在内存的成员仓库
ChatMemberStore 接口 成员仓库:dispatch、getMembers、getParticipant、getMyRoles、subscribe、clear
ChatMemberStoreEvent 类型 成员仓库写入口收的事件,下面四种的联合
ChatMemberStoreMembersLoadedEvent 接口 取到一个会话的成员表,整表换入
ChatMemberStoreMemberUpsertedEvent 接口 一个人进了会话或角色变了
ChatMemberStoreMemberRemovedEvent 接口 一个人离开了会话
ChatMemberStoreCurrentUserLoadedEvent 接口 当前用户和他的组织角色
ChatMemberStoreListener 类型 一个会话的成员数据变了时的回调
ChatStoreParticipant 接口 一个参与者,跨会话按 id 一份
ChatParticipantKind 类型 参与者的类别(没有 bot)
ChatMembership 接口 一个人在一个会话里的成员关系
ChatConversationRole 类型 会话内角色
ChatOrgRole 类型 组织角色 slug
ChatMyRoles 接口 当前用户在一个会话里的会话内角色和组织角色
ChatLoadedMember 接口 membersLoaded 里的一行
createChatConversationStore 函数 建一个只在内存的会话仓库
ChatConversationStore 接口 会话仓库:会话列表、按 id 读的会话、未读,和取它们的那部分
ChatConversationStoreOptions 接口 createChatConversationStore 的参数
ChatConversationSource 接口 会话仓库用的读接口
ChatConversationSourcePage 接口 会话列表的一页
ChatStoreConversationRow 接口 会话行至少要有的几格
ChatUnreadMention 类型 未读 @ 标记
ChatConversationStoreEvent 类型 会话仓库写入口收的事件
ChatConversationPatch 接口 对一个会话的当前用户态的改动
ChatConversationListState 接口 会话列表的读取状态
ChatConversationReadState 接口 一个会话的读取状态
ChatUnreadState 接口 一个会话的未读
createChatReadCursorStore 函数 建一个只在内存的已读游标块
ChatReadCursorStore 接口 已读游标块:dispatch、getState、has、subscribe、clear、epoch
ChatReadCursorState 接口 一个会话的游标状态
ChatMemberCursor 接口 一个成员的游标
ChatReadCursorEvent 类型 游标块写入口收的事件
ChatReadCursorSnapshotShape 接口 一个会话的游标快照
ChatReadCursorSignal 类型 取数层认的三种实时信号
createChatReadCursorLoader 函数 建已读游标的取数层
ChatReadCursorLoader 接口 取数层:打开、已读上报、释放
ChatReadCursorLoaderOptions 接口 取数层的端口
createChatAgentActivityStore 函数 建一个只在内存的运行表(Agent 执行过程,只读进度(实验性 · 过渡);从本行到 ChatAgentActivitySummaryRef 都属这项能力)
ChatAgentActivityStore 接口 运行表:applyFrame、sweep、getRuns、size、subscribe、clear
applyAgentActivityFrame 函数 按一帧推进一份运行表
sweepAgentActivityRuns 函数 扫失联与淘汰
selectConversationAgentActivityRuns 函数 取某会话的 run
agentActivityRunKey 函数 run 的键
AGENT_ACTIVITY_MAX_STEPS 常量 每个 run 的步骤上限
AGENT_ACTIVITY_EVICT_AFTER_MS 常量 终态或失联之后留多久
AGENT_ACTIVITY_MAX_RUNS 常量 一份表的 run 总数上限
ChatAgentActivityFrame 接口 解码、校验过的一帧
ChatAgentActivityRun 接口 归并出的一个 run
ChatAgentActivityRuns 类型 一份运行表
ChatAgentActivityState 类型 帧与 run 上的状态
ChatAgentActivityStep 类型 解码后的一步
ChatAgentActivityEndReason 类型 失败的结束原因
ChatAgentActivitySummary 类型 消息上的中立运行字段(ChatMessage.agent_run_summary)
ChatAgentActivitySummaryFull 接口 中立运行字段的完整形态
ChatAgentActivitySummaryRef 接口 中立运行字段的引用形态
ChatStoreEvent 类型 写入口收的事件,下面十三种的联合
ChatStoreWindowLoadedEvent 接口 取到一窗,整窗换入
ChatStoreOlderLoadedEvent 接口 取到更早的一页,接到前面
ChatStoreNewerLoadedEvent 接口 取到更新的一批,接到后面
ChatStoreMessageUpsertedEvent 接口 一条消息的新内容
ChatStoreMessageDeletedEvent 接口 一条消息被删掉
ChatStoreConversationClosedEvent 接口 关掉一个会话,只留水位
ChatStoreViewChangedEvent 接口 视图停在哪条消息附近
ChatStoreSendStartedEvent 接口 自己发出一条,先写入「发送中」
ChatStoreSendSettledEvent 类型 一次发送的结果
ChatStoreLocalMessageRemovedEvent 接口 去掉一条本端消息
ChatStorePatchStartedEvent 接口 自己对一条消息动手,先改仓库
ChatStorePatchSettledEvent 接口 一次改动的请求结束了
ChatStoreReactionChangedEvent 接口 一次表态变化(增量),直接改底版
ChatStoreListener 类型 订阅回调
ChatStoreCardChangedEvent 接口 卡片那几格的新值(增量),直接改底版
ChatStoreChange 接口 一次 dispatch 给一个会话带来的变化
ChatStoreDataEvent 类型 已加载区间的一种变化
createChatGapFillScheduler 函数 建补洞调度器
ChatGapFillSchedulerOptions 接口 建调度器的参数
ChatGapFillSource 接口 注入的两个读接口
ChatGapFillSincePage 接口 从水位往后取的一批
ChatGapFillLatestPage 接口 最新一窗
ChatGapFillChange 接口 改动日志里的一条
ChatGapFillChangesPage 接口 改动日志的一页
ChatGapFillMessagesPage 接口 按 id 取回的一批消息
ChatGapFillScheduler 接口 调度器:各个补洞时刻的入口
ChatGapFillResult 接口 一次补洞的结果
ChatGapFillOutcome 类型 一次补洞怎么结束的
ChatGapFillChangesResult 接口 一次补改动的结果
ChatGapFillChangesOutcome 类型 一次补改动怎么结束的
createChatThreadLoader 函数 建取数协调器
ChatThreadLoaderOptions 接口 建取数协调器的参数
ChatThreadLoader 接口 取数协调器:打开、读取状态、翻页、重试
ChatThreadReadState 接口 一个会话的读取状态
ChatMessageReadState 接口 一条消息的读取状态
ChatReadStatus 类型 加载状态
ChatThreadSource 接口 取数协调用的读接口
ChatThreadSourcePage 接口 loadThread 取到的一页
ChatMessageTarget 类型 跳到哪条消息
ChatJumpResult 类型 一次跳转的结果
ChatJumpOptions 类型 跳转的选项(中止信号)
ChatStorage 接口 本机存储接口
createMemoryStorage 函数 内存里的 ChatStorage
createIndexedDbStorage 函数 IndexedDB 里的 ChatStorage
IndexedDbStorageOptions 接口 createIndexedDbStorage 的参数
ChatLocalDataOptions 接口 本机数据放在哪、是否加密
ChatStorageOpenOptions 接口 打开本机数据的选项(只读打开)
LocalDataUnavailable 类 只读打开时本机数据用不了
LocalDataUnavailableReason 类型 只读打开被拒的原因
ChatStorageEncryption 接口 静态加密的密钥
ChatMessage 接口 一条消息
ChatAttachment 接口 附件元数据
ChatMessageReaction 接口 一种表态的汇总
ChatMessageMention 接口 一个 @ 提及
ChatCardState 接口 卡片最近一次已生效的操作
ChatCardFormAnswer 接口 选择卡一道题的落定答案
ChatMessageType 类型 消息类型
ChatMessageSenderType 类型 发送者类型
ChatMessageDeliveryStatus 类型 只在本端存在的发送状态
CHAT_STORE_VERSION 常量 包的版本
registerPackageInstance 函数(@internal) 在整页的登记表上登记一份包;其余 @openmaxai/chat* 包用它,接入方不用
isProductionBuild 函数(@internal) 是不是生产构建;@openmaxai/chat-sdk 用它,接入方不用
PackageInstanceEnv 接口(@internal) registerPackageInstance 的运行环境
DuplicateWarningSink 接口(@internal) 双份告警的去处

签名块从源码生成,说明是手写的;包内测试检查两者都没落下任何导出。

@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 接口 本机存储大约占多大