OpenMax
免费试用

架构总览

聊天界面、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 绑定。

架构:组件库、SDK 与适配器
箭头指向使用它(或由它供数)的那一层;适配器和自己的后端之间是网络请求。红块是唯一和 OpenMax 相关的包。
  • 适配器(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 会闩住、让实时停止重连,其余种类不闩,实时照常重连。
包依赖图
箭头从一个包指向它依赖的包(package.json 的 dependencies 与 peerDependencies)。@openmaxai/chat-internals 是共用的内部构件,随其他几个包一起装上,不要直接 import。@openmaxai/chat-sdk 既不依赖 @openmaxai/chat-openmax,也不用 OpenMax 的 REST 客户端,包内测试守着这一条。@openmaxai/chat-store 不依赖任何其他聊天包。顶上两个应用框只画了这类应用的入口包。

依赖只朝一个方向:@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。
  • 适配器的其余成员和错误模型的其余部分:取一个不在已取成员列表里的人、由后端算的未读总数,以及错误 · 还没做的里列的错误处理。