已知限制
哪些还不能用、哪些要你自己接,以及怎么绕过去。
已知限制
所有导出都标着 @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建宿主时读一次,要按角色给,就得在角色变了时重建宿主。
数据与缓存
- 消息默认只存在内存里,刷新页面后重新加载。要保留,用
localData把消息存在本机,见@openmaxai/chat-sdk· 本机数据。规划中
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 正式版。
