OpenMax
免费试用

已知限制

哪些还不能用、哪些要你自己接,以及怎么绕过去。

已知限制

所有导出都标着 @experimental。@experimental 的导出不受语义化版本约束:任何版本(包括次版本和补丁版本)都可能改动或移除它们。

数据形状

  • 消息和会话的字段名与 OpenMax 相同。 ChatMessage、ChatConversation、ChatAttachment 由 SDK 定义,字段名和 OpenMax 网关相同(sender_id、created_at、fallback_text 等)。接别的后端要做映射;漏掉可选字段不报错,只是少显示内容,需逐个核对。
  • 每条消息都要有整数 seq。 会话内从 1 递增、不重复。排序和断线后补洞都靠它,时间戳替代不了。

默认宿主(createChatHost)

  • 只接 OpenMax。 别的后端用 createLocalPorts 自己拼宿主,见接入自有后端。
  • 只支持令牌鉴权。 auth: { mode: "logto" } 和 { mode: "cookie" } 在类型里有,构造时抛 ChatSdkConfigError。
  • 编辑不带结构化 @。 自己的表态、编辑、撤回当场生效;别人的表态、编辑、撤回实时出现,被审核删除的消息整条去掉;离线、切走期间别人的改动在重连、切回会话时按改动日志补回来。
  • 群管理只能来自适配器。 createChatHost 从适配器的 groupManagement 取它(OpenMax 适配器有);ports 加不进。名片要适配器有 profiles、createChatHost 收到 profileCardActions 才有,见名片。
  • 首次渲染时自己的消息短暂显示成别人的。 当前用户加载前 id 是 "",数据到达后 ChatProvider 重渲染纠正。
  • 当前用户加载前写的草稿只在内存里,加载后不会带过去。
  • 草稿不跨标签页同步,要等下次读取。
  • realtime: "off" 时,别人的新消息和卡片操作结果都不会自动出现。
  • 没有请求超时。
  • 回执关闭的会话每次打开都多一次被拒的请求。 宿主不先读会话上的回执设置,读游标请求照发、得到 412;不画回执,也不提示。
  • 实时同步帧不回确认,重连后可能重复推送。
  • 只收不发「正在输入」。 SDK 的实时连接解 typing 帧,ConversationHeader 据此显示别人在输入;输入框不发,所以接 OpenMax 时只有 Agent 运行时发 typing 才会亮。只用组件库时 ChatHeader 的 typingText 仍由你算好传入。GET /me 一直取不到时,整个作用域都不显示「正在输入」。
  • 没有连接状态提示。 断线、补洞失败时界面都不提示。登录过期(含换票被拒,之后连接停止重连)只经 attention.notify 提示一次「登录已过期」,没有「已登出」的界面状态;宿主没接 attention 时什么都看不到。要自己处理,用 { adapter } 写法传 onUnauthorized。
  • 一行配置不收 onUnauthorized。 类型上就不收;JS 里给了,建宿主时抛 ChatSdkConfigError,所以登录过期时你的代码拿不到回调去跳转登录。要回调改用 createChatHost({ adapter: createOpenMaxAdapter(config), onUnauthorized }),见错误模型 · onUnauthorized。
  • 一行配置同样不收 onEvent。 给了建宿主时抛 ChatSdkConfigError;要接消息展示插件发的事件,改用 createChatHost({ adapter: createOpenMaxAdapter(config), onEvent })。
  • 同意 Analytics 之前的引导卡曝光不会自动补报。 SDK 不收「现在能发了」的信号:用户同意之前就在眼前的引导卡,要你在 onEvent 里记下 card.onboarding 事件、能发了再补报。cards.openCreateAgent 建宿主时读一次,要按角色给,就得在角色变了时重建宿主。

数据与缓存

Agent

  • Agent 正在做什么,今天经 agentActivity(只读进度(实验性 · 过渡))看得到进度与工具步骤,没有停止按钮。 适配器经实时通道交 agentActivity 信号就有消息区的执行过程块、孤儿列表与头部执行摘要,在消息上填 agent_run_summary 就有回复上的摘要条(OpenMax 默认都给,工厂选项 agentActivity: false 关掉),不用声明。没有回复的运行刷新后看不到,打开会话、重连时不补拉进行中的运行;终态帧可能丢,只按帧上的 ttl_ms 判失联;旁观者收不到帧。规划中的 Agent 运行落地时替换它。
  • AGENT_STREAM 消息按普通文本显示,没有逐字更新。
  • 选择卡不和运行关联,Agent 一侧要自己把答案对应回问题。

这三条由规划中的 Agent 运行解决:运行进度、工具步骤和停止按钮经 agent_event 帧实现,卡片可以带 run_id、tool_call_id、expires_at 成为审批卡;逐字输出见消息区 · 逐字输出,思考过程排在后面。规划中

规划中的版本也有一个已知限制:停止一个正在 Agent 主会话里执行的运行,可能连带打断主会话,见停止按钮。规划中

组件

  • 没有错误边界。 任一模块抛错(如没给 conversations 却渲染 ConversationList)会卸掉整棵 React 树,需要隔离就自己包错误边界(带 componentDidCatch 的类组件,或 react-error-boundary 这类库)。每个区域自带错误边界是规划中的,见错误与会话过期 · 渲染错误。
  • 部分文案依赖 react-i18next。 少数面板(含 @ 提及面板)用 useTranslation,需包你自己装的 react-i18next 的 <I18nextProvider>,实例用 createChatI18n 建;浮窗类组件在 ChatProvider 之内先走 i18n 能力,认不得的词和挂在 ChatProvider 之外时才用 useTranslation。有些组件调用你的 i18n.t 时带 { ns }(agent、common),你的 t 不转发这个参数,对应文案会为空或显示 key。见国际化。
  • MessageThread 不含会话头部。 用 SDK 时在上方放 ConversationHeader;只用组件库时摆 ChatHeader,标题、副标题、徽标由你传。
  • ConversationHeader 还没有「开通中」;Agent 执行摘要的出现与消失不播报给读屏。 对端在线状态画在头像上;与人单聊要等收到这个人的 presence 信号之后才画点(OpenMax 后端还不给人的状态);Agent 协作、旁观会话的标题不画每个 Agent 前的在线点。后端漏发 offline(对端所在的服务端实例崩溃、或一次在线状态更新丢了)时,错的「在线」最坏约 105 秒(60 秒的重读周期加 45 秒的租约 TTL);服务端共享的在线状态存储不可用时 REST 也只按单个实例判,定时重读纠正不了,没有上界;presence 帧乱序时到下一次重读才纠正。适配器没有 profiles 时在线状态要等第一声 presence。副行(正在输入、对端状态)的变化不播报给读屏。
  • ConversationHeader 的模型切换与只读模型名,Owner 身份靠 profiles。 适配器没有 profiles(或成员资料读不到)时只能按配置的 configurable 认 Owner:配置读到之前、或读失败时,Owner 看不到「我的」字签与模型入口。Agent 开通中 → 就绪时模型按钮不会自己恢复,要重新打开会话;别人改了模型不会实时更新;消息气泡上 Agent 发送者旁的模型名,每个露出的 Agent 除了读一次配置还要读一次成员资料。
  • 外部接入 / 自托管的 Agent 要在成员资料里给 agentOrigin。 适配器的成员资料不带 agentOrigin / memberStatus 时,SDK 判不出托管资格、仍照常判 Owner:外部接入 / 自托管的 Agent 没给这两格时,它的 Owner 每次打开都看到一颗禁用(灰色)的模型按钮,并多发一次会被服务端拒的 GET …/model-config。适配器给 Agent 时请给 agentOrigin(离开了的再给 memberStatus: "departed"),见适配器接口 · agentConfig。
  • 已读位置要靠 onVisibleSeqChange。 不处理的话,读过的会话刷新后又是未读。
  • 群操作是回调。 ChatInfoPanel 的 onLeave、onDelete、onRemoveMembers、onAddMembers 没传时,确认弹窗照弹,确认后无事发生。不传 memberStatus,成员全显示离线。
  • 没有 cards 能力时卡片只读。 卡片插件不装,卡片正文和结果行照常,按钮和选项不能点,不能作答。createChatHost 造的宿主在适配器有 cards 时能作答(OpenMax 一行写法不收 cards 配置,业务卡不画按钮);别人的作答(包括选择卡已由别人提交)实时出现,但「已被取代」「已过期」要等那条被重新读到才变(它们没有实时帧)。选择卡草稿存在 SDK 的本机存储里,只在这台设备上。
  • 刷新后草稿里的附件会丢,正文和引用回复会保留。
  • 拖放文件要 ChatFileDropZone,浮窗和停靠列不接收拖放。
  • SDK 的浮窗 ChatFloatingSurfaces / 停靠列 ChatDockColumn 还不完整。 storage: "memory" 时窗不跨刷新;当前用户还不知道时不还原;被移出、会话被删时窗静默收掉、不提示;收进坞的窗刷新后不补水,已无权限的会话带着标题留在坞里,点开才收掉。窗里的正文与主页面同一套组件、缺口相同,也不显示国内版 AI 生成提示。弹出成浮窗与拖进拖出有了(ConversationHeader 的 onPopOut、CwsConversationList 的 dragOut);会话列表不画已开在浮窗或停靠标签里的会话。一页只能各挂一份。逐条见已知缺口。
  • 表态选择器是固定列表。 列表外的表态码能显示,但选不到。
  • 只有 Agent 回复是 Markdown。 默认 render 把 Agent 回复(renderMarkdown)按 Markdown 画;人发的文字消息(TEXT)仍是纯文本,带链接和提及。代码块没有语法高亮。
  • 消息操作只有操作栏上的五个按钮(复制、表态、回复、编辑、撤回):没有「更多」菜单和右键菜单,不能置顶,也不能加自己的操作。

样式与弹出层

在 ChatRoot 里,样式表只作用在 SDK 组件自己的节点上(见安装);你直接放进 ChatRoot 或放进 SDK 组件插槽的内容不被我们的基础重置改动。作用域靠类选择器实现,所以有几样东西仍会越过边界:

  • SDK 样式表和 ChatRoot 缺一不可。 少了 @openmaxai/chat-sdk/styles.css,或者组件不在 ChatRoot 里,聊天都没有样式,也不报错。
  • 你写的与我们同名的类规则会作用进聊天区。 你的 .hidden、.border、.collapse 这类规则,同样匹配聊天区里带这些类的元素。
  • 你的高优先级规则会赢。 我们的工具类是 (0,2,0)(.omx-chat .flex)。你优先级 (0,2,0) 及以上、或带 id 的规则(如 #app button、.page a)照样改得到聊天区里的元素。
  • 你传给 SDK 组件的类会输给我们的。 你经 className 传的类(.my-x,(0,1,0))盖不过聊天的工具类。改变量,或者写成 .omx-chat .my-x,见主题 · 覆盖组件样式。
  • 聊天没设的属性,你的元素选择器和通配规则照样作用进来。 聊天自己的样式只在它设了的属性上赢过 * {}、button {}、a {} 这类规则(盒模型、外边距、内边距和边框,按钮的背景和字体,链接的颜色……)。别的属性,比如 letter-spacing、word-spacing、text-transform,照样从你的规则作用到聊天区的元素上:页面上写 * { letter-spacing: 3px },聊天区里几乎每个元素的字间距都会变;写 button { text-transform: uppercase },聊天区的按钮也会变。ChatShadowRoot 解决了这一条,见 Shadow DOM。
  • 插槽里的内容会继承 SDK 组件的字体和变量。 插槽在 SDK 组件之内:组件根上的字体、字号、行高、颜色,以及 --primary、--border、--color-* 这类变量,会继承到你放进插槽的内容上。你在插槽里用了引用这些同名变量的工具类(如 bg-primary、border-border),取到的是聊天的值;用了与我们同名的类,命中的也是我们那条规则(多数取值相同)。我们带后代变体的工具类(如作用到里面所有 <a> 的 [&_a]:underline)也会命中插槽里你的节点,比如消息气泡里你的自定义消息卡片中的链接。做法:插槽里别依赖与聊天同名的变量类;要用,就在插槽内容的外层把这些变量重新设成你自己的值。
  • 快速开始的写法下,SDK 自带的看图器没有样式。 ChatProvider 包在 ChatRoot 外面时,ChatProvider 自带的看图器渲染在 ChatRoot 之外,拿不到聊天的样式。把 ChatProvider 放进 ChatRoot 里,或经 createChatHost({ ports: { mediaViewer } }) 换成你自己的看图器。
  • 插槽嵌套超过 3 层时,最里层的内容回到被重置。 SDK 组件的插槽里再放带插槽的 SDK 组件、一层套一层超过 3 层时,最里面插槽里你的节点会被我们的基础重置改到(外边距、边框等)。
  • 你在祖先上设的可继承属性会进聊天区。 作用域根设了字体、字号、行高和颜色,没有设 letter-spacing、word-spacing、text-align、font-style、text-transform 等其他可继承属性:设在 body 或 ChatRoot 的其他祖先上,它们会作用到聊天区里。
  • 聊天运行时会改 body。 聊天里的模态框打开期间锁住整页滚动(Radix 的默认行为,不提供开关);拖动浮窗时设置 body.style.userSelect。两者事后都会还原。
  • 容器的祖先会限制弹出层。 弹出层落在 ChatRoot 容器里。祖先带 transform、filter、contain,或者建了 z 值低的层叠上下文时,对话框的遮罩只盖住那一块,弹出层可能压在你页面的元素或浮窗下面。给 overlayContainer 一个 body 一级的节点;挂了 ChatFloatingSurfaces 或 ChatDockColumn 时一律给(见安装 · 浮出面与 overlayContainer)。
  • 首帧弹出层在 body 里(只限 ChatRoot)。 落点节点挂上之前(ChatRoot 首次提交那一帧),或 ChatRoot 的 overlayContainer 是 null 时,弹出层渲染进 body,不带作用域类。ChatShadowRoot 没有这一条:落点在 children 第一次渲染之前就建好,overlayContainer 给 null 与不给相同,弹出层落在 shadow 里的默认落点,不回 body(见 ChatShadowRootProps)。
  • 光标和滚动条的细节与 OpenMax 不同。 OpenMax 里按钮的手形光标和滚动条颜色来自基础规则,赢过同一元素上的工具类;作用域化之后它们输给工具类,比如带 cursor-default 的按钮在这里显示默认光标。布局和颜色相同。
  • @property 注册在整个页面上。 样式表在整页注册 Tailwind v4 的 --tw-* 属性和我们自己的八个(--scroll-fade-t、--scroll-fade-b、--scroll-fade-s、--scroll-fade-e、--scroll-fade-mask、--shimmer-angle、--shimmer-image、--shimmer-text-fill);@property 没法限定作用域。你的页面用不同的定义注册了同名属性(比如别的 Tailwind 版本)时,先注册的生效。
  • 容器查询的断点不跟 --omx-rem 缩放。 它们是按 16.8px 折算的固定像素值。
  • React 事件沿 React 树冒泡。 渲染在 body(或 overlayContainer)下的弹出层,React 事件照样传到 ChatRoot 的 React 祖先。
  • 你挂进 ChatShadowRoot 的悬停 enter 处理函数可能收不到。 指针从你页面上由 React 渲染的节点直接移到 ChatShadowRoot 里的元素上时,React 不会在它上面派 onMouseEnter / onPointerEnter:enter 的两半(mouseout 与 mouseover)落在不同的 React 监听上(你的根容器、shadow root 里的 portal 容器),根容器那一半看到的是 shadow 宿主元素而不是真实节点。SDK 自己的组件用 onMouseOver 响应悬停;你自己挂进 ChatShadowRoot 的处理函数 SDK 不动,要悬停触发的改用 onMouseOver / onPointerOver。见编写输入框插件。
  • 你的 Radix 层开着时按 Esc。 只有焦点在聊天的某一层里时,Esc 才先由聊天处理(见安装 · 在你的对话框里按 Esc)。否则 Esc 先到你的层:它关掉,把焦点还给它的触发按钮,开着的聊天层随后因为焦点移到外面也关。这些情况会这样:用鼠标点开表情选择器(焦点留在按钮上);输入框里的 @ 提及候选开着;焦点在浮窗的输入框里、聊天的对话框开着;焦点在 body 上。在 closed shadow root 里聊天看不到焦点在哪,同样如此;ChatShadowRoot 用的是 open。聊天层 portal 到别处、自身又不是层的内容,算在层外。你的对话框是模态时,焦点根本进不了聊天的层,用 modal={false}。

Shadow DOM

用 ChatShadowRoot(实验性)时,样式与弹出层里的限制有的没了、有的还在,另外多出几条新的。

ChatRoot 下 ChatShadowRoot 下
你写的与我们同名的类规则会作用进聊天区 解决:你的选择器匹配不到 shadow root 里的任何元素
你的高优先级规则会赢 解决,原因同上
聊天没设的属性,你的元素选择器和通配规则照样作用进来 解决,原因同上。* { letter-spacing: 3px } 这样的通配规则仍会匹配 <omx-chat-host> 本身,它的值里可继承的那部分归下一行处理
你在祖先上设的可继承属性会进聊天区 靠重置层解决,不是靠 shadow 边界:可继承的值仍会从你的祖先、也从 <omx-chat-host> 本身传进来,由 shadow root 里的重置层(all: initial)挡住。重置层只注入 shadow root,从不进你的页面。自定义属性和 direction 有意照常继承
你传给 SDK 组件的类会输给我们的 仍在:优先级相同,而且你的类规则根本进不了 shadow root
聊天运行时会改 body 仍在:滚动锁和拖动浮窗仍会改你页面的 body
容器的祖先会限制弹出层 主聊天区仍在(它的落点在 <omx-chat-host> 里):给 overlayContainer="body"。浮出面和 body 一级的 overlayContainer 岛不受影响
首帧弹出层在 body 里 解决:落点在 children 第一次渲染之前就建好了
@property 注册在整个页面上 仍在:@property 只在你页面自己的文档里生效。同一页面上两个版本的 SDK 带来不同的注册时,SDK 把第二份也追加进去并 console.warn

ChatShadowRoot 新带来的:

  • ChatShadowRoot 祖先上的 React 处理函数,点一下可能跑两次。 我们实测在 ChatShadowRoot 里点一下消息,<omx-chat-host> 父节点上的 onClick 跑了两次,Chromium、WebKit、Firefox 都一样:第一次 e.target 是被点的元素,第二次 e.target 是 <omx-chat-host> 元素。聊天在你的 React 树里 portal 进 shadow root,React 事件照 portal 的规矩冒泡到 ChatShadowRoot 的 React 祖先;原生事件也会冒泡到你的 React 根容器,那时目标已被重定向成 shadow 宿主,React 又派发一次。在意的话,跳过 e.target 是 <omx-chat-host> 元素的那一次。
  • 你在 document 上的监听拿到的目标是 <omx-chat-host>。 shadow root 里的事件(如 focusin、keydown)到达 document 上的监听时,目标已被重定向成 shadow 宿主。这是 Shadow DOM 的正常行为;要真实目标就读 event.composedPath()[0]。
  • 旧浏览器的退路要用内联样式。 浏览器不支持可构造样式表时,SDK 改在 shadow root 里写一个 <style>;页面的内容安全策略(CSP)禁了内联样式时,这条退路用不了。
  • 你的 Radix 和聊天的 Radix 各有一份弹层栈。 聊天自带一份 Radix,你的对话框、弹出层和聊天的层互相看不见。点外面由每一层各自判断,结果和只有一份时相同;Esc 只有在焦点在聊天某一层里时才先给聊天(见安装 · 在你的对话框里按 Esc和上面的你的 Radix 层开着时按 Esc)。
  • 你自己渲染进 ChatShadowRoot 的弹出层用的是你的 Radix。 聊天自己的对话框、侧滑面板和抽屉带着 SDK 为 Shadow DOM 打的修补:在你的页面上和 shadow root 里都锁焦点、隐藏背景。你的代码渲染在 ChatShadowRoot 里的弹出层(对话框、模态菜单、Select)用的是你那份不带这些修补的 Radix,在 shadow root 里锁焦点和隐藏背景都不保证。这类弹出层请在你的页面里、ChatShadowRoot 外面打开。
  • 富文本选区在 WebKit 和 Firefox 上不作承诺。 在 Chromium 上,输入框在 shadow root 里打字、选中文字再粘贴覆盖、粘贴、@ 提及和输入法组字都正常。WebKit 上我们用模拟的粘贴事件测了同样的步骤,都通过(没测输入法);我们的自动化环境里 WebKit 的键盘粘贴带不出 HTML,所以没有用真实剪贴板粘贴的读数。Firefox 上用真实的剪贴板粘贴,同样的步骤在用和不用 Shadow DOM 时都通过(没测输入法)。WebKit 和 Firefox 上我们不作承诺。
  • vaul 往你的页面加一张全局样式。 SDK 用的抽屉库一加载就往你页面的 head 追加一个 <style>,不管有没有挂 ChatShadowRoot(或任何聊天);用 ChatRoot 时也一样。它的规则只选 [data-vaul-*] 属性,不碰你的元素,但同一张表里还有不带前缀的全局 @keyframes(fadeIn、fadeOut、slideFromBottom 等):你的页面有同名 keyframes 时,以文档里后出现的那份为准。
  • aria-hidden 只在主聊天区里补。 聊天的模态框开着时,body 一级的岛(浮出面)对读屏仍然可达;它们是可交互的浮出面,本来就要可达。

无障碍

打包

这些包已作为 3.0.0 预发布版本(3.0.0-beta.*)发布到 npm,以同一个版本号一起发布。所有导出都标着 @experimental,预发布版本之间可能变动:锁定确切版本号,所有 @openmaxai/chat* 包用同一个(见安装)。接口冻结后再发 3.0.0 正式版。