常见问题
集成时最常遇到的问题和解决办法。
常见问题
组件没有样式
没引入 SDK 的样式表,或者组件不在 ChatRoot 里。样式表只作用在 SDK 组件在 ChatRoot 里各自带的 .omx-chat 组件根之内。检查全局 CSS 里是否引入了 @openmaxai/chat-sdk/styles.css、这个 CSS 文件本身是否被引入、聊天是否包在 <ChatRoot> 里,见安装。
组件显示的是文案 key
少了 I18nextProvider。部分组件(提及面板、群管理、浮窗和抽屉)通过 useTranslation 取文案,需要用 <I18nextProvider i18n={createChatI18n({ locale: "zh-CN" })}>(I18nextProvider 来自 react-i18next,createChatI18n 来自 @openmaxai/chat-sdk) 包住整棵树。见国际化。
报 Invalid hook call
页面加载了两份 React。用 Vite 时设置 resolve.dedupe: ["react", "react-dom"],见安装 · 配置打包器。
不接后端能用吗
能。用内存函数加 createLocalPorts 拼一个宿主,见快速开始。本站所有演示都是这样运行的。
能接自己的后端吗
能。自己实现必填的 identity、messaging、inboundDelivery,要会话列表再加 conversations,其余必填能力交给 createLocalPorts。见接入自己的后端。也可以写一个适配器交给 createChatHost({ adapter }),由它造出宿主;两种写法都在同一篇指南里。
移动端支持
支持,不需要传设备开关。组件按自己容器的宽度切换排版(容器窄于 768 px 用窄排版),按输入方式决定触屏交互,见组件 · 响应式。@openmaxai/chat/surfaces 另有底部抽屉 ChatMobileDrawer,用不用由应用决定。
深色模式
在祖先元素(一般是 <html>)上加 dark 类。聊天不自动跟随 prefers-color-scheme。见主题。
某个功能没有出现
可选功能只在宿主提供对应能力时出现:
| 功能 | 需要的能力 |
|---|---|
| 「@我」跳转 | mentions |
# 引用工作项 |
workItems |
| Agent 模型选择 | agentConfig |
| 建群、群信息面板 | groupManagement |
| 卡片上的按钮和选项 | cards |
| 点头像弹出名片 | profileCard |
| 点图片放大 | mediaViewer |
| 表情回应、撤回、编辑、已读回执 | messaging 上对应的可选方法 |
| 附件按钮 | attachments,且附件上限大于 0 |
createChatHost 提供哪些见已知限制 · 默认宿主;它的上传还要求外层有 <ConversationScope>。完整说明见能力。
自己的消息短暂显示成别人的
createChatHost 在首次渲染后才取回当前用户,期间用户 id 为空,<ChatProvider> 会在数据到达后重渲染。
能看到 Agent 正在做什么、能停下它吗
能。宿主提供 agentRuns 能力、后端推 agent_event 帧后,消息区显示运行进度、工具步骤、逐字输出和停止按钮,见接入自有后端。规划中
能从 npm 安装吗
能。这些包已作为 3.0.0 预发布版本(3.0.0-beta.*)发布到 npm。所有导出都标着 @experimental,预发布版本之间可能变动,所以要锁定确切版本号,所有 @openmaxai/chat* 包用同一个,见安装。变化记录在更新日志。
