@finogeeks2026/chatkit-web 0.0.1

package/README.md

@@ -0,0 +1,194 @@
+# 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 [historyOpen, setHistoryOpen] = useState(false)
+  const {
+    messages,
+    sendMessage,
+    isLoading,
+    runtime,
+    sessions,
+    currentSessionId,
+    switchSession,
+    deleteSession,
+    pinSession,
+    createSession,
+  } = useChat({
+    apiUrl: 'https://your-api.example.com/agent',
+    getBearerToken: () => yourAuth.getToken() ?? '',
+    persist: true, // 启用 IndexedDB 持久化
+  })
+
+  return (
+    <ThemeProvider defaultMode="light">
+      <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
+        <ChatHeader
+          title="AI Assistant"
+          onMenuClick={() => setHistoryOpen(true)}
+          onAddClick={() => createSession()}
+        />
+        <ChatView
+          messages={messages}
+          onSend={sendMessage}
+          isLoading={isLoading}
+          promptStarters={['推荐相关资源', '帮我分析这个问题']}
+          runtime={runtime}
+        />
+        <HistoryPanel
+          open={historyOpen}
+          onClose={() => setHistoryOpen(false)}
+          sessions={sessions}
+          currentSessionId={currentSessionId}
+          onSelect={switchSession}
+          onDelete={deleteSession}
+          onPin={pinSession}
+          title="历史对话"
+        />
+      </div>
+    </ThemeProvider>
+  )
+}
+```
+
+### 方式二：使用 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

package/dist/index.css

@@ -0,0 +1,10 @@
+:root[data-theme=light],:root:not([data-theme]){--chatkit-bg-primary: #ffffff;--chatkit-bg-secondary: #f5f5f5;--chatkit-bg-tertiary: #fafafa;--chatkit-text-primary: #333333;--chatkit-text-secondary: #666666;--chatkit-text-tertiary: #999999;--chatkit-text-disabled: #cccccc;--chatkit-border: #e0e0e0;--chatkit-border-light: #f0f0f0;--chatkit-border-dark: #d1d5db;--chatkit-user-bubble-bg: #007aff;--chatkit-user-bubble-text: #ffffff;--chatkit-assistant-bubble-bg: #f5f5f5;--chatkit-assistant-bubble-text: #333333;--chatkit-prompt-bg: linear-gradient(to right, #EFF6FF, #FAF5FF);--chatkit-prompt-text: #1976d2;--chatkit-prompt-icon: #1976d2;--chatkit-input-bg: #ffffff;--chatkit-input-border: #d1d5db;--chatkit-input-placeholder: #999999;--chatkit-input-focus-border: #007aff;--chatkit-button-primary: #007aff;--chatkit-button-primary-hover: #0056b3;--chatkit-button-primary-disabled: #cccccc;--chatkit-button-text: #ffffff;--chatkit-error: #ff3b30;--chatkit-warning: #ff9500;--chatkit-success: #34c759;--chatkit-scrollbar-track: #f5f5f5;--chatkit-scrollbar-thumb: #cccccc;--chatkit-scrollbar-thumb-hover: #999999}:root[data-theme=dark]{--chatkit-bg-primary: #1a1a1a;--chatkit-bg-secondary: #2d2d2d;--chatkit-bg-tertiary: #252525;--chatkit-text-primary: #ffffff;--chatkit-text-secondary: #b3b3b3;--chatkit-text-tertiary: #808080;--chatkit-text-disabled: #4d4d4d;--chatkit-border: #404040;--chatkit-border-light: #333333;--chatkit-border-dark: #4d4d4d;--chatkit-user-bubble-bg: #007aff;--chatkit-user-bubble-text: #ffffff;--chatkit-assistant-bubble-bg: #2d2d2d;--chatkit-assistant-bubble-text: #ffffff;--chatkit-assistant-bubble-border: #404040;--chatkit-prompt-bg: #1e3a5f;--chatkit-prompt-text: #90caf9;--chatkit-prompt-icon: #90caf9;--chatkit-input-bg: #2d2d2d;--chatkit-input-border: #404040;--chatkit-input-placeholder: #808080;--chatkit-input-focus-border: #007aff;--chatkit-button-primary: #007aff;--chatkit-button-primary-hover: #0056b3;--chatkit-button-primary-disabled: #4d4d4d;--chatkit-button-text: #ffffff;--chatkit-error: #ff3b30;--chatkit-warning: #ff9500;--chatkit-success: #34c759;--chatkit-scrollbar-track: #2d2d2d;--chatkit-scrollbar-thumb: #4d4d4d;--chatkit-scrollbar-thumb-hover: #666666}pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: GitHub
+  Description: Light theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+
+  Outdated base version: https://github.com/primer/github-syntax-light
+  Current colors taken from GitHub's CSS
+*/.hljs{color:#24292e;background:#fff}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#d73a49}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#6f42c1}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#005cc5}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#032f62}.hljs-built_in,.hljs-symbol{color:#e36209}.hljs-code,.hljs-comment,.hljs-formula{color:#6a737d}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#22863a}.hljs-subst{color:#24292e}.hljs-section{color:#005cc5;font-weight:700}.hljs-bullet{color:#735c0f}.hljs-emphasis{color:#24292e;font-style:italic}.hljs-strong{color:#24292e;font-weight:700}.hljs-addition{color:#22863a;background-color:#f0fff4}.hljs-deletion{color:#b31d28;background-color:#ffeef0}