chatkit

上线清单

本页是接入 chatkit 的整体上线清单和界面侧排错。适配器、代理和后端的逐项检查与排错表见接入后端 · 上线前检查。

清单

  • 适配器实例引用稳定（useMemo 或模块级），同一组会话共用一个实例；单个对话的 sessionId 只在真正切换对话时变化。
  • 请求走自己的代理：适配器的能力函数把请求发给自己的服务，由它转发给模型或 Agent。
  • 浏览器里不出现任何后端密钥：密钥留在服务端，不写进前端代码，也不经过浏览器。
  • 用户是谁由登录态决定：代理根据登录态校验用户和会话归属，不信任前端传来的用户标识。
  • 适配器跑过一致性测试（runAdapterConformance），给出的每一项能力都对着真实的后端检查过，见上线前检查。
  • 区分远端执行失败和连接错误：远端失败通过 turn_summary 的 errorCode 统计；onError 在 <ChatkitProvider>（或 <Chatkit>）上接一处到错误监控，会话 hook 没写 onError 时它的错误也交到这里，按第二个参数的 source 区分来源。
  • 上报经 createTelemetry 接入（接入上报）：给了 track、beacon（离开页面通道）与 reportError；检查自定义属性、工具名、错误码中没有敏感内容；开发模式下控制台没有 [chatkit] telemetry 告警。
  • 核心指标（首字延迟、会话完成率、空回复率、回复中断率、任务失败率、工具调用成功率）按 指标 的汇总口径（turn_summary）接进看板，没有与原始事件口径相加； 自己的维度（应用版本、场景、模型）写在 createTelemetry 的 attributes 里。
  • 用 Mock 适配器的 telemetry-acceptance 场景跑完五轮，verifyTelemetry（@volcengine/chatkit/testing）通过。
  • 历史：确认刷新页面后的表现符合预期。给了 history 函数、后端按后端约定返回时对话能还原；没给时刷新后对话清空，见会话与历史从哪来。
  • 会话列表：由应用维护目录与创建、重命名、删除操作，将列表交给 SessionList，将当前会话 ID 交给 useChatSessions({ adapter, activeSessionId })。
  • 后端确实支持取消、续接、重新生成时才提供对应函数。没有取消接口时不提供停止按钮；释放本地资源不等于停止后端任务。
  • 没给 history 时，切换路由、切换页签不会让对话丢失：useChatSessions / useChatRuntime 写在不会卸载的上层组件里，或者隐藏而不是移除对话界面。
  • 依赖后端的功能在界面上的显示与实际能力一致。重新生成、编辑后重发用 features 关闭；会话列表通过是否渲染 SessionList 控制。
  • 插槽里的业务组件抛错只影响它自己：确认 onError 能收到，界面其余部分正常。
  • 样式：页面上没进 @layer 的全局 reset 不会压坏 chatkit（主题），暗色背景下对比度可接受。
  • 锁定准备上线的具体版本，在预发环境跑完完整流程，再用同一版本上线，见版本与兼容承诺。

界面侧排错

点发送没反应、草稿还在。 先检查 onSend 是否返回了 false 或抛错、运行时是否已就绪、空会话是否具备创建能力。使用 useChatSessions 或 useChatRuntime 管理运行时；自行创建 ChatCoreRuntime 时还需确认没有继续使用已释放的实例。

服务端渲染 Chatkit UI 时报 DOM 相关错误。 Chatkit UI 需要浏览器环境。SSR 框架里把 Chatkit 放在客户端组件里并关掉服务端渲染：

'use client';
import dynamic from 'next/dynamic';
const Chat = dynamic(() => import('./chat'), { ssr: false });

/core、/adapters/*、/testing 不依赖 DOM，可以在 Node 里直接用。

安装时报 ERESOLVE，peer react@"^18 || ^19"。 支持 React 18 与 19：项目里的 React 低于 18 时，先升级到 18 或 19 再安装。

chatkit 的按钮、段落样式被页面的全局样式改了。 chatkit 的样式在 @layer chatkit 里，页面上没进层的全局样式（Tailwind v3 preflight、normalize、全局组件库 CSS）优先级更高。 把它们放进排在 chatkit 前面的层，见 主题。

界面上没有重新生成 / 编辑后重发。 这些功能依赖后端：给了适配器对应的能力函数才显示，见能力一览。

界面上没有会话列表。 会话列表不由适配器提供，是应用自己渲染的 SessionList 组件：传入应用的会话数组、activeSessionId 和 onSelect，通常配合 useChatSessions 使用，见会话列表。

切换页面再回来，对话没了。 useChatSessions / useChatRuntime 所在的组件被卸载，运行时随之释放，见会话与历史从哪来。

每次渲染都重连、一直停在运行中、刷新后回答重复等与适配器和后端相关的问题，见上线前检查 · 常见错误与排查。