npm package: @finogeeks2026/chatkit-web
Description: 面向 Web / H5 的 AI 对话 UI SDK，支持流式对话、多会话管理、主题定制
Latest version: 0.0.13

# 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）

## 安装

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

## 快速集成

### 方式一：使用 useChat（推荐）

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

```tsx
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?)`

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

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

### 方式二：使用 ChatKit 门面 API

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

```tsx
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 发送消息、监听事件等
```

### 方式三：按需组合组件

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

```tsx
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 的样式文件：

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

## 主题定制

通过 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