快速开始

不连后端，把带会话列表的完整界面跑起来。示例使用内置的 Mock 适配器（createMockAdapter），它不连接后端，按脚本回放对话，用于本地开发、演示和测试。

安装

npm

yarn

pnpm

bun

deno

npm install @volcengine/chatkit

截至 2026-10-15，公网 npm 已发布 0.1.0-alpha.1，alpha 与 latest 当时都指向此版本。安装时建议锁定具体版本，并核对版本与兼容承诺。文档站源码可能领先于已发布包。

需要 React 18 或 19（peer 是 ^18 || ^19）：项目里还没有 React 时，安装会一并装上最新的 React 19。根入口在浏览器里经打包工具（Vite、webpack、Next.js 客户端组件）运行；服务端渲染时放进客户端组件并关掉 SSR，见上线清单。

最小接入

quick-start.tsx

import { useDemoSessions } from '../sessions';

import { Chatkit, SessionList } from '@volcengine/chatkit';
import { createMockAdapter } from '@volcengine/chatkit/adapters/mock';
import '@volcengine/chatkit/styles.css';
import { useState } from 'react';

// 整个应用一个适配器实例，引用要稳定（模块级或 useMemo）：引用一变运行时就会重建。
// Mock 适配器不连后端，自带三个预置会话，发送后按脚本回放「思考 → 调工具 → 流式回答」。
const adapter = createMockAdapter();

// 最小接入：适配器 → useChatSessions → 会话列表和聊天区用同一个返回值。随便发一句话试试。
export default function QuickStart() {
  const { chat: sessions, listProps } = useDemoSessions({ adapter });
  const [open, setOpen] = useState(false);
  return (
    <div className="demo-column demo-session-layout" data-placement="left" data-open={open}>
      {/* demo-session-* 是示例页的响应式样式：窄屏默认收起列表，聊天区保持全宽。 */}
      <div className="demo-bar demo-session-toggle-bar">
        <button
          type="button"
          className="demo-chip"
          aria-expanded={open}
          aria-controls="quick-start-sessions"
          onClick={() => setOpen(value => !value)}
        >
          {open ? '收起会话' : '全部会话'}
        </button>
      </div>
      <div className="demo-row">
        <div id="quick-start-sessions" className="demo-session-sidebar">
          <SessionList {...listProps} style={{ width: '100%' }} />
        </div>
        <div className="demo-main">
          <Chatkit sessions={sessions} settings={{ welcome: '有什么可以帮忙的？' }} />
        </div>
      </div>
    </div>
  );
}

不连后端的最小接入：切换会话，或随便发一句话新窗口打开

上方同时展示接入组件源码与交互预览。复制到 React 18 或 19 项目后，让父容器具有明确高度；示例里的 height: '100%' 依赖父容器的高度。

四步：

建适配器。这里用 createMockAdapter()；接真实后端时换成 createAdkAdapter、createOpenAiAdapter 等，或者自己写的适配器。适配器必须是稳定引用（模块级或 useMemo），引用一变运行时就会重建。
useChatSessions({ adapter, activeSessionId })。管理已打开的 runtime 并返回当前选中的运行时。只要单个对话时用 useChatRuntime，见两种用法。
<Chatkit sessions={sessions} /> 是聊天区。它占满所在容器的宽高，所以容器要有明确的高度。
SessionList 接收应用的 sessions 数组、activeSessionId 和 onSelect 回调；创建、改名、删除和 fork 由应用实现。

样式在 @volcengine/chatkit/styles.css，需要单独引入。

示例的 useDemoSessions 维护目录数组；历史、重新生成和编辑等能力由适配器在内存里模拟。复制示例时需同时复制该示例 hook，真实应用替换成自己的目录与路由。发一句带「失败」的话可以看到失败时的样子；其他回放场景见 Mock 适配器。

接真实的后端

已经有后端时，可保留聊天区和会话列表的组件结构，替换适配器，并核对上传、业务卡片和请求 metadata 的约定。适配器只做协议翻译：每项能力写一个发请求的函数，请求发到哪、带什么凭据由函数决定。只有 run 必须给。

接一个 OpenAI 兼容的模型接口：

adapter.ts

import { createOpenAiAdapter } from '@volcengine/chatkit/adapters/openai';

// 直连模型服务，只用于本地开发：密钥从本机的环境变量读，不要提交、不要上线
const BASE = 'https://llm.example.com/v1';
const KEY = import.meta.env.VITE_LLM_KEY;
const MODEL = 'your-model-id';

export const adapter = createOpenAiAdapter({
  run: ({ body }) =>
    fetch(`${BASE}/chat/completions`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}` },
      // 请求内容里没有模型名，在这里补
      body: JSON.stringify({ model: MODEL, ...body }),
    }),
});

要点	说明
给了什么就有什么	只给 `run` 时界面只有对话。再给 `history`、`regenerate`、`edit` 等函数，界面上就多出对应的功能
函数名都一样	ADK、A2A、OpenAI 兼容接口、Hermes 四个适配器的函数名相同，只是请求内容不同
上面是直连的写法	只用于本地开发。生产环境让请求走自己的代理：密钥留在服务端，用户是谁由登录态决定
不在浏览器中持久化对话	会话和历史只来自后端。没给 `history` 时刷新页面后对话清空

各协议的写法见接入后端，两种后端的完整写法见完整示例：接入真实后端。

加上配置与插槽

<Chatkit
  sessions={sessions}
  settings={{ welcome: '有什么可以帮忙的？', recommendations: ['帮我查一下明天北京的天气'] }}
  features={{ attachments: { upload } }}
  slots={{ 'composer.bottom': <p>内容由 AI 生成，请核实后使用</p> }}
/>

接下来

看一个包含多项内置功能和业务定制的应用：完整示例。
换成真实后端：接入后端。
看有哪些内置功能、各自什么条件下显示：内置功能总览。
放业务组件、改显示方式：settings / features / slots / renderers 怎么选。
可传 theme={{ appearance: 'dark' }} 切换暗色，用 root.className/style 覆盖实例 token：主题与样式覆盖。

#快速开始

#安装

#最小接入

#接真实的后端

#加上配置与插槽

#接下来

快速开始

安装

最小接入

接真实的后端

加上配置与插槽

接下来