ChatKit Web SDK

面向 Web / H5 的 AI 对话 UI SDK，支持流式对话、多会话管理、主题定制、MCP-UI 渲染、Tool Call 展示等能力。

特性

• 流式对话：基于 SSE 的 AG-UI 协议，实时展示 AI 回复
• 多会话管理：会话列表、历史消息持久化（IndexedDB）
• 主题系统：支持浅色 / 深色切换，CSS 变量定制
• MCP-UI 渲染：支持服务端下发的自定义 UI 组件渲染
• Tool Call 展示：工具调用进度与结果卡片
• Consent 授权：敏感操作前的用户同意弹窗

环境要求

• React 18+
• 现代浏览器（Chrome、Edge、Safari、Firefox）

安装

npm install @finogeeks2026/chatkit-web
# 或
pnpm add @finogeeks2026/chatkit-web
# 或
yarn add @finogeeks2026/chatkit-web

快速集成

方式一：使用 useChat（推荐）

最简接入方式，适合完整聊天界面场景。

import React from 'react'
import {
  useChat,
  ChatView,
  ChatHeader,
  HistoryPanel,
  ThemeProvider,
} from '@finogeeks2026/chatkit-web'
import '@finogeeks2026/chatkit-web/dist/index.css'

function App() {
  const {
    messages,
    sendMessage,
    isLoading,
    runtime,
    sessions,
    currentSessionId,
    switchSession,
    deleteSession,
    pinSession,
    createSession,
    historyPanelOpen,
    openHistory,
    closeHistory,
    startNewConversation,
  } = useChat({
    apiUrl: 'https://your-api.example.com/agent',
    getBearerToken: () => yourAuth.getToken() ?? '',
    persist: true,
  })

  return (
    <ThemeProvider defaultMode="light">
      <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
        <ChatHeader
          title="AI Assistant"
          onMenuClick={openHistory}
          onAddClick={startNewConversation}
        />
        <ChatView
          messages={messages}
          onSend={sendMessage}
          isLoading={isLoading}
          promptStarters={['推荐相关资源', '帮我分析这个问题']}
          runtime={runtime}
        />
        <HistoryPanel
          open={historyPanelOpen}
          onClose={closeHistory}
          sessions={sessions}
          currentSessionId={currentSessionId}
          onSelect={switchSession}
          onDelete={deleteSession}
          onPin={pinSession}
          title="历史对话"
        />
      </div>
    </ThemeProvider>
  )
}

不使用 ChatHeader 时，可通过 API 打开历史面板或开启新对话：

• openHistory()：打开历史对话面板（等同于点击 header 菜单）
• closeHistory()：关闭历史面板
• startNewConversation()：创建并切换到新会话（等同于点击 header 加号）；也可使用 createSession(title?)

const { openHistory, closeHistory, startNewConversation, historyPanelOpen, ... } = useChat(config)

// 自定义按钮触发
<button onClick={openHistory}>打开历史</button>
<button onClick={startNewConversation}>新对话</button>
<HistoryPanel open={historyPanelOpen} onClose={closeHistory} ... />

方式二：使用 ChatKit 门面 API

适合需要精细控制运行时和会话生命周期的场景。

import { ChatKit } from '@finogeeks2026/chatkit-web'

const instance = ChatKit.create({
  apiUrl: 'https://your-api.example.com/agent',
  getBearerToken: () => yourAuth.getToken() ?? '',
})

const conversation = instance.startConversation()
// 使用 conversation 发送消息、监听事件等

方式三：按需组合组件

按需引入组件，自由组合布局。

import {
  useChat,
  ChatView,
  MessageList,
  Composer,
  ThemeProvider,
} from '@finogeeks2026/chatkit-web'
import '@finogeeks2026/chatkit-web/dist/index.css'

// 或更细粒度：MessageList + Composer 自定义布局

配置说明

| 配置项 | 类型 | 必填 | 说明 | |--------|------|------|------| | apiUrl | string | 是 | 后端 AG-UI 协议接口地址 | | getBearerToken | () => string \| Promise<string> | 否 | 返回鉴权 Token，请求时自动添加到 Authorization 头 | | persist | boolean | 否 | 是否启用 IndexedDB 持久化会话和消息 |

主要导出

Hooks

• useChat：完整聊天能力（消息、发送、会话管理）
• useMessages：仅消息与发送
• useConversations：仅会话管理
• useNetworkStatus：网络状态

组件

• ChatView：聊天主视图（消息列表 + 输入框 + 推荐问题）
• ChatHeader：顶部栏
• HistoryPanel：历史会话侧边栏
• MessageList / MessageBubble：消息展示
• Composer：输入框
• ConsentDialog：授权确认弹窗
• ThemeProvider / useTheme：主题

门面

• ChatKit / createChatKit：门面 API

样式

务必引入 SDK 的样式文件：

import '@finogeeks2026/chatkit-web/dist/index.css'

主题定制

通过 CSS 变量覆盖默认主题：

:root {
  --chatkit-bg-primary: #ffffff;
  --chatkit-bg-secondary: #f5f5f5;
  --chatkit-text-primary: #111111;
  --chatkit-border: #e5e5e5;
  /* 更多变量见 SDK 源码 theme/variables.css */
}

使用 ThemeProvider 可切换浅色 / 深色模式。

在 WebView 中使用

SDK 支持在 App 内 WebView 中加载的 H5 页面使用。需确保：

• 页面通过 HTTPS 加载（安全上下文）
• WebView 已授予麦克风权限（若使用后续语音功能）
• apiUrl 与鉴权配置正确

License

MIT