架构总览
聊天界面、SDK、适配器和你的应用怎么拼在一起:分层、包与入口、宿主怎么接起来,以及 SDK 与后端之间的适配器接口。
架构总览
界面只负责画;取数据、实时连接、提示、草稿等都交给宿主对象。宿主在最外层装一次,所有组件从它取能力。
分层
| 层 | 包 | 做什么 |
|---|---|---|
| 界面 | @openmaxai/chat |
会话列表、消息区、输入框、会话头部、群管理、浮窗 / 停靠面,以及 ChatHost 契约(@openmaxai/chat/host)。不调 fetch、路由或 window。 |
| 宿主与通用层 | @openmaxai/chat-sdk |
与后端无关:createChatHost({ adapter }) 从一个适配器造宿主;适配器接口 ChatSdkAdapter、统一错误 ChatSdkError、凭据失效回调 onUnauthorized;createLocalPorts(...) 提供与后端无关的能力(草稿、附件与上传任务台、正文渲染、提示、文案、实例作用域)。 |
| 后端适配器 | @openmaxai/chat-openmax |
createOpenMaxAdapter(config) 接 OpenMax 的 REST、实时和上传;@openmaxai/chat-openmax/react 的 createChatHost(config) 一行接好。 |
| 数据 | @openmaxai/chat-store |
消息仓库、线程加载、补洞、请求结果缓存、本机存储 ChatStorage;@openmaxai/chat-store/react 是读仓库的 hook。 |
| 基础 | @openmaxai/chat-internals(作为上面几个包的依赖自动装上,不要直接 import) |
基础组件与主题 CSS 变量;中英文文案;OpenMax REST 客户端、网关类型和实时帧解码。 |
本节其余几页按数据流往下走:
| 页面 | 讲什么 |
|---|---|
| 能力 | 宿主上有哪些字段,缺了某项会怎样 |
| 实时与同步 | 服务端的变化怎么推到客户端,断线或漏帧后怎么补齐 |
| 质量(暂未公开) | 分层、数据流向、性能、可用性和稳定性方面的设计目标,还没实现的部分标「规划中」 |
包与入口
| 包 | 角色 | 依赖 |
|---|---|---|
@openmaxai/chat |
界面组件和宿主契约 ChatHost |
@openmaxai/chat-store、@openmaxai/chat-internals;peer react 19、@tanstack/react-query 5(可选,只有老消息区 @openmaxai/chat/message-thread 用) |
@openmaxai/chat-sdk |
与后端无关的宿主:适配器接口、createChatHost({ adapter })、手写宿主也能用的本地能力、错误模型、测试用的内存适配器 |
@openmaxai/chat、@openmaxai/chat-store(精确版本)、@openmaxai/chat-internals;peer 同上 |
@openmaxai/chat-openmax |
OpenMax 适配器 createOpenMaxAdapter 和一行入口 createChatHost(config) |
@openmaxai/chat-internals;peer @openmaxai/chat、@openmaxai/chat-sdk、@openmaxai/chat-store(精确版本),以及同上 |
@openmaxai/chat-store |
消息仓库与读仓库的 hook,见 @openmaxai/chat-store |
不依赖其他聊天包;peer react 19(可选) |
@openmaxai/chat-internals |
上面几个包共用的内部构件:基础组件与主题 CSS 变量、中英文文案、OpenMax REST 客户端、网关类型、实时帧解码。随它们一起装上;不是公开 API,不要直接 import | 不依赖其他聊天包;peer react、react-dom 19 |
「依赖」一栏照各包 package.json 的 dependencies 和 peerDependencies,只列聊天的这几个包和 peer,第三方依赖不列。它们都以同一个版本号一起发布,见已知限制 · 打包。调试面板在 @openmaxai/chat-sdk 包里,经 @openmaxai/chat-sdk/devtools 使用,见调试面板。
@openmaxai/chat 的入口按界面区域划分:/host、/conversation-list、/message-thread、/composer、/header、/group-management、/surfaces,根入口 @openmaxai/chat 再导出常用部分。@openmaxai/chat-sdk 有四个公开入口:不依赖 React 的根入口 @openmaxai/chat-sdk(适配器接口、ChatSdkError、配置与存储类型)、@openmaxai/chat-sdk/react(createChatHost、ChatProvider、ConversationScope、createLocalPorts 等)、@openmaxai/chat-sdk/testing(createMemoryAdapter)和 @openmaxai/chat-sdk/devtools(调试面板)。@openmaxai/chat-openmax 有根入口(createOpenMaxAdapter)和 @openmaxai/chat-openmax/react(createChatHost(config),并再导出 ChatProvider、ConversationScope 和会话列表 hook,接 OpenMax 只从这一个入口 import)。逐个导出见 @openmaxai/chat、@openmaxai/chat-sdk、@openmaxai/chat-openmax 和 @openmaxai/chat-store。
宿主怎么接起来
- 接 OpenMax:
@openmaxai/chat-openmax/react的createChatHost(config)造宿主,ChatProvider安装,见接入 OpenMax。它就是createOpenMaxAdapter(config)交给@openmaxai/chat-sdk的createChatHost({ adapter });要自己处理凭据失效(onUnauthorized)时直接写成后者。 - 接别的后端: 写一个
ChatSdkAdapter,交给@openmaxai/chat-sdk/react的createChatHost({ adapter }),同样用ChatProvider安装,见接入自有后端 · 适配器 API。后端还没好时先用@openmaxai/chat-sdk/testing的createMemoryAdapter把界面跑起来。 - 手写宿主: 自己写
identity、messaging、inboundDelivery(通常还有conversations),其余用createLocalPorts(...)补齐,见接入自有后端。用createChatHost({ adapter })时,groupManagement、cards、mentions、workItems、agentConfig这类可选能力不用手写宿主:它们来自适配器上的同名成员,profileCard来自适配器的profiles加profileCardActions。只想换掉草稿或附件的实现不用手写宿主:createChatHost的ports可以整格替换drafts、attachments。
三种方式下组件和安装入口完全相同。规划中
设计取舍
- 界面不直接调后端。 换后端或换成 mock 都不用改组件,本站演示就跑在 mock 上。
- 一个功能对应一项能力。 宿主缺某项可选能力只少一个功能,见能力。
- 难写的状态只写一遍。 乐观发送、断线补洞、消息缓存、草稿、上传任务台都在库里,宿主不用重写。
createChatHost造的宿主已经把消息存进@openmaxai/chat-store的消息仓库,CwsMessageThread从仓库读;手写宿主用的MessageThread还没改成从仓库读,Agent 的运行也还没存进仓库,这两部分仍在规划中。 - 人和 Agent 走同一条链路。 Agent 是会话成员,它的回复是普通消息;运行进度经同一条实时连接推送,可见范围沿用会话的规则。
SDK 与后端之间:适配器
@openmaxai/chat-sdk 与后端无关:它从一个适配器对象造宿主(createChatHost({ adapter })),@openmaxai/chat-openmax 是第一个适配器。组件只认 ChatHost 契约,不知道背后是哪个适配器。适配器的完整接口见适配器接口,统一错误见错误模型,应用代码读仓库的 hook 见 React 绑定。
- 适配器(
ChatSdkAdapter):必填identity、messaging,可选conversations、realtime、uploads、session,另带adapterVersion(值为CHAT_SDK_ADAPTER_VERSION)和name。失败时抛ChatSdkError,kind是 12 种之一,例如unauthorized、network、rate_limited。 @openmaxai/chat-sdk把适配器包成宿主:身份变成同步可读、会话列表的缓存与合并失效、每个createChatHost造的宿主只开一条实时连接(第一个订阅者到来时才建连)、createLocalPorts的本地能力;消息存进@openmaxai/chat-store的仓库。凭据失效由一个闩处理:第一次见到kind为unauthorized的错误时调一次onUnauthorized,闩住期间再失败不再调,闩住之后发起的调用成功一次才松开;没给回调时经attention提示一次。这条实时连接不和应用已有的连接共用:应用自己还常驻一条连同一后端的连接时,就开着两条。@openmaxai/chat-openmax的createOpenMaxAdapter(config)接 OpenMax 的 REST、实时(先换一次性票再建 WebSocket,帧在适配器内部解码)和上传。请求被401拒时,带{ refresh: true }再调一次getToken(同时被拒的几个请求共用这一次续期),再把原请求重发一次。续不出令牌时按原因定种类:getToken抛的是ChatSdkError,种类照它自己的kind(例如network、timeout、unavailable);抛的是裸TypeError、TimeoutError、AbortError,种类是network、timeout、cancelled;其余的值(例如普通Error)和回空串算unauthorized。只有unauthorized会闩住、让实时停止重连,其余种类不闩,实时照常重连。
依赖只朝一个方向:@openmaxai/chat-openmax → @openmaxai/chat-sdk → @openmaxai/chat → @openmaxai/chat-store。@openmaxai/chat-sdk 也直接依赖 @openmaxai/chat-store,根入口再导出它的存储接口 ChatStorage 和 createMemoryStorage、createIndexedDbStorage。@openmaxai/chat-store 不依赖任何其他聊天包。@openmaxai/chat-sdk 自己既不用 OpenMax 的 REST 客户端,也不依赖 @openmaxai/chat-openmax,包内测试守着这一条。共用的内部构件在 @openmaxai/chat-internals 里:@openmaxai/chat 用它的 Agent 运行帧定义(带进 @bufbuild/protobuf),@openmaxai/chat-openmax 用它的 OpenMax REST 客户端和实时帧解码。
还在规划中的
规划中
- 一致性测试。
@openmaxai/chat-sdk/testing的chatSdkAdapterConformance对你的适配器跑整套用例。 - SDK 再导出读仓库的 hook。
@openmaxai/chat-sdk/react再导出useMessages、useMessage;今天从@openmaxai/chat-store/react导入。 - Agent 运行组件放在新入口
@openmaxai/chat/agent-runs。 - 适配器的其余成员和错误模型的其余部分:取一个不在已取成员列表里的人、由后端算的未读总数,以及错误 · 还没做的里列的错误处理。
