# chatkit > 面向 Agent 应用的对话界面：适配器对接后端，配置与插槽定制界面 ## 文档 - [介绍](/guide/introduction.md): chatkit 是给 Agent 应用用的对话界面：一个 npm 包 @volcengine/chatkit，提供会话列表、流式回答、思考与工具调用、输入框、附件等组件。依赖后端或业务实现的功能，需要接入对应能力后才能使用。 - [快速开始](/guide/quick-start.md): 先用 Mock 完成第一条对话，再替换真实后端。这个示例使用单个会话，所有必要文件都包含在下载归档中。 本站文档与 Demo 对应当前本地代码，示例消费本地包构建产物。使用下载示例时，同时下载示例旁的本地 SDK，无需依赖某个 npm 发布版本。 - [嵌入已有产品与侧边助手](/customize/embedding.md): 在现有页面放入聊天区，或将它作为侧边助手。布局由宿主 CSS 控制，不需要改 ChatKit 内部组件。 - [两种用法](/guide/usage.md): chatkit 有两种用法：多个会话的完整应用用 useChatSessions，嵌在页面里的单个对话用 useChatRuntime。两者用同一个适配器、同一个 。 sessions 与 runtime 二选一。 - [核心概念](/guide/concepts.md): 接入 chatkit 要理解三个概念：适配器、配置、插槽。本页各用一段话说清楚，再补上读文档时会遇到的几个名词。 - [完整示例：对话应用](/guide/full-example.md): 一个对话应用的接入示例，组件代码放在一个文件中、使用公开接口：左边会话列表，中间聊天区，右边是任务进度和常用提问；附件、赞踩、@ 提及都开着；页面自己加了公告、知识库选择、业务卡片、轮次计数和右侧栏。代码从上到下每一段对应文档里的一页。示例的 demo-* 类名使用演示页样式，复制到自己的项目时需补充页面布局和卡片样式。 - [组合教程：业务助手](/guide/composed-app.md): 把知识库选择、请求上下文、工具执行、业务卡片和回答收藏连成一条完整路径。示例使用本地内存和 Mock，不提供真实知识库、下单或收藏服务。 - [完整示例：接入真实后端](/guide/full-example-backends.md): 完整示例用 Mock 适配器按脚本回放示例数据。换成真实后端时，可以沿用 与 SessionList 的结构和多数配置。 业务卡片的 transformOutput、上传服务和 metadata 传递方式仍需按真实协议调整。下面的代码展示适配器和页面骨架，省略了完整示例中的业务配置。 重新生成、编辑等操作按已提供的能力显示；能力函数仍可能因网络或服务端错误而失败，需要接入 onError。 两条原则： 适配器只做协议翻译。每项能力写一个发请求的函数，请求发到哪、带什么凭据、用哪个模型或应用，都在函数里决定。不在浏览器存储中持久化对话。刷新后通过历史接口恢复后端已保存的内容；没有历史接口时，内存中的对话会丢失。 下面两个例子的请求都发给自己的代理。直连后端的写法见各协议的页面。 - [定制场景 SOP](/customize/overview.md): 先确定目标，再选择公开扩展入口。每篇包含效果、入口选择理由、分步接入、验证、排错与完整代码。业务服务和数据权限由应用负责。 需要“左侧对话、右侧业务表单”时，阅读对话辅助填表：Agent 更新草稿、用户手动修正、拒绝旧版本修改，再由用户确认提交。 - [settings / features / slots / renderers 怎么选](/customize/choosing.md): 定制界面有四个入口。本页说明它们各管什么，以及遇到一个需求时该用哪个。 - [主题与样式覆盖](/customize/theming.md) - [定制空会话内容与位置](/customize/empty-state.md): 空会话默认显示欢迎内容。只改文字和推荐问题，使用 settings.welcome 和 settings.recommendations；需要调整布局或换成业务内容时，使用 slots['session.empty']。下面的示例用完整的“项目助手”空态替换默认欢迎内容，可切换同一组件在顶部或居中显示。卡片里的推荐入口可以直接发送消息。左侧展示的就是右侧运行的完整组件源码。 - [调整内置功能](/customize/built-in-features.md): 内置功能可以调整到三个程度：开关、换位置、自己摆放。 - [插槽](/customize/slots.md): 聊天区有 17 个固定位置可以放业务组件，通过 slots 按位置名登记。 - [业务卡片](/customize/custom-card.md): 后端想在回答里显示订单卡片、引用来源、图表时，用业务卡片：后端返回数据，界面按数据类型找登记的组件来显示。 - [工具展示](/customize/tools.md): Agent 调用业务自己的工具时，用 renderers.tools 按工具名登记它怎么显示。 - [失败卡片与系统提示](/customize/errors-and-events.md): **适用范围：**本页说明当前本地源码，示例消费同一 checkout 的构建产物。完整示例提供配套本地 SDK。 一轮失败时通过 renderers.errors 按错误码选择渲染器。渲染器可用内置样式覆盖标题和正文，也可换掉整张卡片；对话里的系统提示可按类型自定义。 - [发送前处理 onSend](/customize/on-send.md): 通过聊天界面或公开操作 hook 发送之前，onSend 可以改写输入，或者拦下这次发送。它是界面侧的发送回调，不是所有后端请求的统一拦截器。 - [不能定制的部分](/customize/limits.md): chatkit 有几处不开放定制：核心交互与指标口径。本页列出它们，并说明原因和替代做法。 - [对话辅助填表](/recipes/form-assist.md): 用户在左侧说“申请两台云服务器，地域选北京”，右侧表单自动填入数量和地域。用户可以继续对话，也可以直接修改表单，检查后再确认提交。 这项功能不依赖 OpenAI，也不限定某一种 Agent。 ChatKit 显示对话，业务应用负责表单，Agent 提出修改。需要接通的是“修改请求”和“执行结果”的往返。 先点击 Demo 的第一条推荐问题，看右侧字段发生什么变化。本例用本地规则模拟 Agent，没有连接真实模型或业务后端；“确认提交（本地）”不会创建真实资源。 窄屏下对话与表单上下排列，可在预览中滚动；也可以打开全屏。完整源码与预览一致，下载工程时同时下载旁边的本地 SDK。 - [知识库](/recipes/knowledge-base.md): 让用户选择回答时参考哪些知识库，并在回答下方显示引用来源。本页用插槽、onSend 和业务卡片实现它。 - [技能选择](/recipes/skills.md): 在输入框里选一个技能（写周报、做表格、查资料），随消息一起发给后端。本页用插槽和公开 hooks 实现它。 - [收藏与分享](/recipes/favorites.md): 在回答下方加「收藏」按钮，在会话列表里给会话加「分享」和收藏标记。本页用插槽和会话列表自己的两个位置实现它。 - [连接器](/recipes/connectors.md): 让用户选择这次对话可以使用哪些外部服务（日历、邮箱、代码仓库）。本页用插槽和 onSend 实现它。 在线示例使用示例数据，不连接日历、邮箱或代码仓库，也没有授权流程。右侧数据由 onSend 保存，仅证明发送前配置了这些字段，不证明后端已接收或执行。 - [定时任务](/recipes/schedules.md): 让 Agent 按计划自动执行（每天早上汇总新闻），并在界面上查看和管理这些任务。本页用业务卡片、插槽和会话列表自己的位置实现它。 在线示例使用固定任务和示例数据。「暂停／恢复」只修改页面状态，会话标记来自固定示例 id；没有真正的调度、删除接口或后台执行。下方代码展示接入位置，pauseSchedule、removeSchedule、ScheduleManager 等需要业务应用实现。 - [接入上报](/observability/quick-start.md): 三步接好埋点和错误监控。chatkit 自己不发任何请求，数据交给你的埋点 SDK。 - [事件](/observability/events.md): 只想把上报接起来：看 接入上报，一页讲完代码、会收到什么、看板怎么算。 这一页是完整参考：全部事件与字段、错误来源、扩充属性。指标口径见 指标。 - [指标](/observability/metrics.md): 只想知道看板怎么算：看 接入上报 的「看板怎么算」。 这份文档定完整口径：每个指标怎么定义、用哪些事件算、分子分母是什么、哪些情况排除。 chatkit 只负责发出事件（事件），上报、存储、看板、告警由接入方做。口径写在这里， 结论字段（outcome）由 Core 直接算好，接入方可直接使用该字段，不必另写结论分类；最终指标仍取决于事件完整性、去重和归并。 - [上线清单](/guide/go-live.md): 本页是接入 chatkit 的整体上线清单和界面侧排错。适配器、代理和后端的逐项检查与排错表见接入后端 · 上线前检查。 - [版本与兼容承诺](/guide/versioning.md): ChatKit 当前的版本号是 0.x。接口稳定之前，0.x 的 minor 版本可能包含破坏性变更，变更和迁移方法都会写进 CHANGELOG.md；patch 版本不包含破坏性变更。接入时建议锁定具体版本，升级前阅读该版本的 CHANGELOG.md，并在测试环境验证实际使用的功能。 本站文档以当前 main 对应的本地代码为依据，Demo 使用同一 checkout 构建的包。完整示例提供配套本地 SDK；站点不维护 npm 标签快照或多版本目录。 ## 功能 - [完整功能与接入 SOP](/features/overview.md): 按目标寻找功能，再按步骤接入。清单以当前本地公开代码为依据，覆盖 features、settings、独立组件、Hooks 和按需入口。 - [消息与 Markdown](/features/streaming.md): 适配器逐步提供内容时，回答边生成边显示，正文默认按 Markdown 渲染。非流式后端不会因使用聊天界面而自动变成流式输出。 - [思考与工具调用](/features/reasoning-and-tools.md): 适配器提供的思考片段和工具调用默认逐步显示：每段思考、每次工具调用各占一行，带图标、名称、耗时与状态，无需额外开启。只有普通正文时不会凭空生成思考或工具步骤。 - [运行状态](/features/run-status.md): 每一轮的第一条回答顶部默认有一行状态：左边是这一轮进行到哪里、用了多久，右边是首字耗时（TTFT）、Token 数与模型，下方一条分隔线。右侧指标运行中一直显示（还不知道的写「—」），结束后鼠标移到回答上才显示。可以配置隐藏。 - [失败与停止](/features/failure-and-stop.md): 一轮回答失败时默认显示失败卡片，运行中提供停止入口，无需额外开启。 - [对话轮次导航](/features/conversation-navigation.md): 对话长了以后，消息区左侧显示一列短横线，每条对应一轮对话。用来在长对话里快速找到某一轮。默认打开，对话满三轮才显示。 - [会话列表](/features/sessions.md): 会话列表是应用自己渲染的 SessionList 组件，不由适配器提供：会话目录（有哪些会话、标题、新建、改名、删除）由应用维护，可来自业务后端；SessionList 只展示传入的数组并调用应用的回调。当前会话 ID 由路由或状态传给 useChatSessions 的 activeSessionId，切换后原会话继续在后台接收回答。 - [模型与推理强度](/features/models.md): 让用户为当前会话选择后端可用的模型与推理强度，设置随每一轮发送。模型列表由后端提供，ChatKit 不提供模型托管。 - [上下文用量、压缩与额度](/features/context-usage.md): 上下文圆环展示已用 token 与窗口大小；额度提醒展示账号用量。二者来自适配器通知，ChatKit 不自行估算模型实际消耗。 - [从回答分叉会话](/features/fork.md): 从一条已结束的回答创建新会话，保留该轮及之前的上下文。新建、复制上下文与导航由业务后端和应用完成。 - [发送排队](/features/queue.md): 同一会话的执行由 Core 调度。用户连续发送时，应区分输入受理、等待与真正开始执行，不能用自定义按钮绕过运行时。 - [回答操作](/features/answer-actions.md): 对已有的对话重新来过：重新生成、编辑后重发。给了适配器对应的能力函数时显示。 - [追问与审批](/features/interactions.md): 智能体在执行中停下来问用户（追问），或在执行命令、改文件前请用户放行（审批），chatkit 画默认卡片，用户回答后交给适配器继续。 - [划词追问](/features/selection-ask.md): 选中回答里的一段文字，点「追问」把它作为引用放进输入框。默认启用，浮条在有有效选区时出现。 - [附件](/features/attachments.md): 支持附件栏形式和附件、文字内容内联混排两种交互模式，发送、编辑和历史沿用同一模式。 - [赞踩](/features/feedback.md): 回答下方的点赞与点踩。在 features.feedback 里给了 onRate 才显示。 - [@ 与 /](/features/mentions.md): 在输入框里输入 @ 选择提及对象，输入 / 选择指令。在 features.mentions 里给了候选项才开启，给了哪个开哪个。 - [语音输入](/features/voice.md): 点语音按钮说话，识别出的文字填进输入框。在 features.voice 里给了 recognize 才显示。 - [输入框](/features/composer.md): 输入框的文字与状态在 settings 里配置，业务组件放进输入框周围的插槽。 - [欢迎语与推荐问题](/features/welcome.md): 空会话默认显示欢迎内容；推荐问题需要通过 settings.recommendations 提供，点选后直接尝试发送。示例左侧展示完整源码，右侧可以点击推荐问题体验。 - [多语言](/features/locale.md): 界面文字跟随 settings.locale：zh-CN（默认）或 en-US。 - [OpenUI 渲染](/features/openui.md): 后端返回一段 OpenUI 描述（声明式的界面 DSL），chatkit 把它渲染成指标卡、图表、表格、表单等组件。适合报告、看板这类需要结构化展示、又不值得为每种版式写业务卡片的回答。 OpenUI 是按需引入的功能：它不在默认入口里，不引入就不会进包。 - [产物预览](/features/artifacts.md): Agent 生成了文件（报告、表格、网页、代码、PDF、Office 文档、整个项目），在回答里显示成文件卡片，点「预览」在右侧面板里打开。 产物预览是按需引入的功能：它不在默认入口里，不引入就不会进包。文件放在哪、怎么鉴权、怎么下载都由应用负责，chatkit 只调用应用给的 load 函数拿内容并显示。 ## 后端接入 - [后端选型与接入](/backends/overview.md): 先选择已经匹配的适配器，再接通最小能力。这里的“连接内置”不代表已配置你的部署；条件支持需要业务实现与真实后端共同满足。 已有对应协议优先使用内置适配器；自有协议见编写适配器。 这一页说明适配器做什么、不做什么，以及接一个后端时各方要写什么。 - [能力函数 API](/backends/capabilities.md) - [发送和接收：单接口、分离接口与 WebSocket](/backends/connections.md): run 表示“发起一轮”；subscribe 表示“建立一个会话的持续接收通道”。订阅不依赖本页面先发送消息，也可以接收其他客户端或后端主动发起的轮次。函数个数由交互方式决定，与 HTTP 或 WebSocket 的名称无关。 - [后端约定](/backends/backend-contract.md): 这一页描述内置适配器实际读取的格式和 SDK 接入约定，可供后端团队对接。它不是外部协议官方规范或版本兼容清单；示例扩展需由部署明确支持。 - [ADK](/backends/adk.md): ADK（Agent Development Kit）是用来开发和部署 Agent 的框架，它的服务端通过 run_sse 接口以 SSE 事件流返回 Agent 的执行过程。 这一页说明怎么接一个提供 ADK run_sse 接口的后端：每个函数收到什么、要返回什么，以及这个协议要注意的地方。 - [A2A](/backends/a2a.md): 这一页说明怎么接一个 A2A（JSON-RPC over SSE）的 Agent：每个函数收到什么、要返回什么，以及这个协议要注意的地方。 - [OpenAI 兼容接口](/backends/openai.md): 这一页说明怎么接一个 OpenAI 兼容的 Chat Completions 接口：每个函数收到什么、要返回什么，以及这个协议要注意的地方。 - [Hermes](/backends/hermes.md): Hermes Agent 是 Nous Research 的开源 Agent，它的 API server 在服务端保存会话上下文与历史。 这一页说明怎么接 Hermes Agent 的 API server：每个函数收到什么、要返回什么，以及这个协议要注意的地方。 - [Hermes Dashboard](/backends/hermes-gateway.md): Hermes Agent 是 Nous Research 的开源 Agent。它的 Dashboard（Hermes 内部叫 tui_gateway，TUI 与网页 Dashboard 共用）在一条 WebSocket 上跑 JSON-RPC，服务端保存会话与历史。 这一页说明怎么接 Hermes Dashboard：建连接、建会话、审批与追问卡片、会话级事件，以及这个协议要注意的地方。它和 Hermes（API server）是两套协议、两个入口（adapters/hermes-gateway 与 adapters/hermes），接 Dashboard 不需要开启 API server。请求与事件的字段见 Hermes Dashboard 协议参考。 - [DSH](/backends/dsh.md): DeepSeek Harness（DSH）是一个编程 Agent，Web 服务在服务端保存会话、历史与执行状态。 这一页说明怎么接 DSH 的 Web 远程协议：建连接、建会话、审批与追问卡片、会话级事件，以及这个协议要注意的地方。请求与事件的字段见 DSH 协议参考。 - [Codex](/backends/codex.md): OpenAI Codex 的 app-server 是一条 WebSocket 上的双向 JSON-RPC，服务端保存 thread、历史与执行状态。 这一页说明怎么接 Codex 的 app-server 协议：建连接、建会话、审批与追问卡片、会话级事件，以及这个协议要注意的地方。请求与事件的字段见 Codex 协议参考。 - [OpenCode](/backends/opencode.md): OpenCode 是一个编程 Agent，opencode serve 起的 server 在服务端保存会话、历史与执行状态。 这一页说明怎么接 OpenCode server：建连接、建会话、审批与追问卡片、会话级事件，以及这个协议要注意的地方。请求与事件的字段见 OpenCode 协议参考。 - [Mock 适配器](/backends/mock.md): Mock 适配器（createMockAdapter）不连接后端，按脚本回放对话，用于本地开发、演示和测试，不用于生产环境。这一页说明怎么用它在不连后端的情况下看效果，以及怎么演示后端缺少某项能力时界面的样子。 - [适配器与内容扩展 API](/backends/extensions.md): ChatKit 负责通用的对话交互、协议翻译和运行状态。接入方提供后端能力函数，决定地址、鉴权与部署参数。普通接入只需要 run；有特殊内容时，再使用下面三个入口。 适配器没有业务状态订阅回调。独立业务状态由应用请求并保存，再交给插槽组件；不经过聊天消息也能显示。 - [DSH 协议参考](/backends/protocols/dsh.md): 这一页列出 DSH 适配器读写的 DeepSeek Harness（DSH）Web 远程协议字段，以及它们怎么映射成 ChatKit 的消息、片段和轮次结论。怎么接入见 DSH。 - [Codex 协议参考](/backends/protocols/codex.md): 这一页列出 Codex app-server 适配器在线上读写的字段，以及它们映射成 ChatKit 的什么。怎么接入见 Codex；本页没写的字段以 Codex app-server 文档为准。 - [OpenCode 协议参考](/backends/protocols/opencode.md): 这一页列出 OpenCode server 适配器读写的请求与事件字段，以及它们怎么映射成 ChatKit 的消息、片段、交互请求与轮次结果。接入写法见 OpenCode；字段的完整定义以 OpenCode server 文档 与 server 的 GET /doc 为准。 - [Hermes Dashboard 协议参考](/backends/protocols/hermes-gateway.md): 这一页列出 Hermes Dashboard 适配器（@volcengine/chatkit/adapters/hermes-gateway）在 tui_gateway 上读写的字段，以及它们怎么变成 ChatKit 的消息、片段和轮次。接入写法见 Hermes Dashboard；API server 入口见 Hermes。 - [会话与历史从哪来](/backends/sessions-and-history.md): 会话目录（有哪些会话、标题、排序）由应用自己的后端提供，应用渲染 SessionList 展示；适配器不提供会话目录能力。目录的状态可以交给 useSessionCatalog：应用实现一个 SessionCatalog（或用适配器包自带的，如 Codex 的 createCodexSessionCatalog），见会话列表与 API 契约。某个会话里的消息由适配器的 history 能力从后端读取。本页是两者的完整说明；界面效果见会话列表。 - [断线恢复与停止确认](/backends/recovery.md): 执行结果与接收连接分别记录。网络断开、超时、普通流结束都不等于后端已经失败或完成。 - [后端不符合约定时](/backends/nonconforming.md): 这一页说明后端的格式或能力和后端约定不一样时怎么办。 - [上线前检查](/backends/go-live.md): 这一页列出接后端这部分上线前要检查的事，以及出了问题从哪查。界面侧的整体上线清单（埋点、样式、插槽、SSR）见上线清单。 - [写一个新的适配器](/backends/custom-adapter.md): 内置协议不适用时，从 @volcengine/chatkit/core 引入 createAdapter，提供协议转换与能力函数。最小实现只有 protocol.encodeInput、protocol.decodeEvent 和 run；业务方无需实现 start、底层 run，也无需保存运行时的写入入口。 如果只是地址、鉴权、字段位置不同，先使用内置适配器与扩展 API。完全不同的消息协议才需要新建适配器。 - [ChatKit Adapter 与会话 API 契约](/backends/api.md): 本契约确定接入方可使用的接口与行为。只发布 @volcengine/chatkit；会话业务由接入方管理，Adapter 负责消息执行协议，Core 维护单个会话的消息与执行状态，UI 负责展示。本文的能力名称与代码保持一致，不保留旧方法别名。 接入与开发导航：接入内置 adapter、实现自定义 adapter。 阅读前提：先认识这些编号 这些字段出现时都是字符串；是否必填以各接口参数表为准。内置协议处理自身定义的编号映射；独立订阅入口还必须满足下文的统一 runId 约束，自定义协议遵守同样规则。 例如：会话 s1 中发起执行 r1，产生消息 m1；消息里的文本片段是 p1。流事件 e1、e2 可以持续追加到同一个 m1 / p1，因此一条事件不等于一条消息。再次发送会产生新的 runId，会话仍是 s1。 编号使用规则：同一消息／片段在实时输出与历史中必须使用一致的 id，才能正确合并；新消息／片段使用新 id。eventId 用于流续接，cursor 用于历史分页，二者不能混用。 - [接入文件服务和 TOS](/backends/attachment-storage.md): ChatKit 负责附件交互，不替接入方保存文件。要让附件在刷新和历史会话中仍然可用，并让用户和模型安全读取私有文件，需要接入自己的文件服务。 ## 示例 - [在线示例](/demos.md): 按场景筛选真实 ChatKit 示例，获取多文件源码和完整归档。 - [主题工作台](/examples/theme-studio.md): 调整 ChatKit 外观，同步文档站与真实示例，导出完整代码。 - [示例详情](/examples/view.md) ## API 参考 - [配置参考](/reference/config.md): 的属性与嵌套字段参考。说明和默认值来自当前版本的类型声明。较长的类型显示摘要，完整签名以安装包的 TypeScript 声明为准。 独立使用时提供 sessions 或 runtime；位于 ChatkitProvider 内时可继承。表中的“必填”指对应对象内部的字段要求；默认值可能受到其他设置或后端能力影响，详见说明。 - [Hook 参考](/reference/hooks.md): 会话业务与路由在外部管理。useChatRuntime 管一个会话；useChatSessions 复用多个已打开会话。 - [入口与导出](/reference/entry-points.md): 对外只有一个包 @volcengine/chatkit，按入口引入。本页列出各入口的用途和常用导出；完整类型以所安装版本的声明为准。 - [chatkit 适配器协议 v1](/reference/protocol.md): 本文是「任何后端怎么接进 chatkit」的规范。类型定义在 @volcengine/chatkit/core， 可执行的版本是随包发布的一致性套件 runAdapterConformance（@volcengine/chatkit/testing）： 下文每条带 【套件】 标记的规则，都有一条对应的断言。一致性套件验证通用行为，不能替代真实后端的协议、并发与恢复联调。 - [组件与扩展入口](/reference/components.md): 本页按接入任务定位公开入口，精确导出以当前本地门面为准。内部模块与私有 DOM 不是接入 API。 - [更新日志](/reference/changelog.md): 以下内容来自当前本地包 CHANGELOG；不表示公网发布状态。