# ChatbotSDK — 前端对接文档

> P0 核心链路 ✅ | P1 体验增强 ✅ | P2 运营完善 ✅ | 版本：1.2.0 | 更新日期：2026-06-26

---

## 一、快速开始

### 最简接入（3 行代码）

```html
<script src="https://your-domain.com/sdk/chatbot-sdk.min.js"></script>
<script>
  ChatbotSDK.init({
    integrateId: 1,                  // 必传：客服角色 ID（对应后端 roleId）
    requestDomain: 'https://your-domain.com', // 必传：后端地址
  });
</script>
```

引入后在页面右下角出现悬浮客服按钮，点击即可对话。

### 完整配置接入

```html
<script src="/sdk/chatbot-sdk.min.js"></script>
<script>
  ChatbotSDK.init({
    // 必传
    integrateId: 'hr-portal-v2',      // 客服角色 ID（对应后端 roleId）
    requestDomain: 'https://ai.example.com',

    // 用户身份
    userId: 'zhangsan',
    roleId: 1,

    // 知识库联动（P1）
    categoryId: 5,
    showCategorySwitch: true,

    // UI 定制
    title: 'HR 智能助手',
    width: 420,
    position: 'right-bottom',
    primaryColor: '#2563EB',
    showClear: true,

    // 行为
    streaming: true,
    locale: 'zh-CN',       // 多语言（P2）：zh-CN / en
    debug: false,
  });
</script>
```

### 集成到现有项目

SDK 产物位于 `client/dist/` 目录：

| 文件 | 大小 | 说明 |
|------|------|------|
| `chatbot-sdk.js` | 93KB | 未压缩开发版（含 sourcemap） |
| `chatbot-sdk.min.js` | 45KB | 压缩生产版（gzip ~15KB） |

**部署路径：** 将 `.min.js` 文件上传到后端 `static/sdk/` 目录或任意 CDN。

---

## 二、SDKConfig 完整参数

| 参数 | 类型 | 必传 | 默认值 | 阶段 | 说明 |
|------|------|------|--------|------|------|
| `integrateId` | `string \| number` | ✅ | — | P0 | 集成标识 → 后端 `roleId`（客服角色 ID，决定 AI 人设和知识库范围） |
| `requestDomain` | `string` | ✅ | — | P0 | 后端 API 域名 |
| `userId` | `string` | ❌ | — | P0 | 宿主用户标识 → 后端 `accountId` |
| `roleId` | `number` | ❌ | — | P0 | 客服角色 ID |
| `categoryId` | `number` | ❌ | — | P1 | 默认知识库分类 |
| `showCategorySwitch` | `boolean` | ❌ | `false` | P1 | 是否显示知识库下拉切换 |
| `title` | `string` | ❌ | `"AI 智能助手"` | P0 | 弹窗标题 |
| `width` | `number` | ❌ | `380` | P0 | 弹窗宽度(px) |
| `position` | `string` | ❌ | `"right-bottom"` | P0 | 悬浮按钮位置 |
| `primaryColor` | `string` | ❌ | `"#4F46E5"` | P0 | 主色调 |
| `launcherIcon` | `string` | ❌ | SVG 图标 | P0 | 悬浮按钮图标 |
| `showClear` | `boolean` | ❌ | `true` | P0 | 是否显示清空按钮 |
| `streaming` | `boolean` | ❌ | `true` | P0 | 是否启用 SSE 流式输出 |
| `locale` | `string` | ❌ | `"zh-CN"` | P2 | 界面语言：`zh-CN` / `en` |
| `debug` | `boolean` | ❌ | `true` | P0 | 是否输出调试日志 |

---

## 三、公开 API

| 方法 | 阶段 | 说明 |
|------|------|------|
| `ChatbotSDK.init(config)` | P0 | 初始化 SDK |
| `ChatbotSDK.destroy()` | P0 | 销毁实例（清理 DOM + 样式 + 事件） |
| `ChatbotSDK.open()` | P0 | 打开聊天窗口 |
| `ChatbotSDK.close()` | P0 | 关闭聊天窗口 |
| `ChatbotSDK.toggle()` | P0 | 切换窗口显示/隐藏 |
| `ChatbotSDK.clearHistory()` | P0 | 清空当前会话 |

---

## 四、P1 体验增强功能

### 4.1 SSE 流式打字机效果

默认开启（`streaming: true`），AI 回复逐字输出，支持：
- 流式追加到气泡，实时滚动到底部
- 流中断兜底：保留已接收内容 + 灰色提示
- 无流内容时自动降级为同步请求

### 4.2 Markdown 渲染

AI 回复支持 Markdown 格式渲染，包括：
- 代码块（深色背景 ` ``` ` 语法）
- 行内代码（`` `code` ``）
- 标题（`##` `###` 等）
- 粗体（`**text**`）、斜体（`*text*`）、删除线（`~~text~~`）
- 有序/无序列表
- 链接（`[text](url)`，仅允许 http/https 协议）
- 引用块（`>` ）
- 水平线（`---`）

> **XSS 安全**：所有非代码块内容先转义 HTML，再转换 Markdown 语法为安全 HTML 标签。代码块内容同样转义。

### 4.3 知识库联动

开启 `showCategorySwitch: true` 后，输入区上方出现知识库分类下拉框：

```html
ChatbotSDK.init({
  integrateId: 'my-app',
  requestDomain: 'https://ai.example.com',
  showCategorySwitch: true,   // 显示分类下拉框
  categoryId: 5,              // 默认选中分类
});
```

- 选择分类后，后续对话自动走 RAG 增强接口（`/ai/assistant_app/chat/rag/sse`）
- 选择「全部分类」则走普通流式接口
- 分类数据从 `/category/tree` 接口动态加载，支持树形缩进显示

### 4.4 RAG 引用来源展示

使用 RAG 对话后，AI 气泡底部自动展示引用来源卡片：

```
┌─────────────────────────────────┐
│ 📚 3 条参考来源               ▼ │
├─────────────────────────────────┤
│ 员工手册.pdf                    │
│ 员工可以享受年假...            │
│ 员工手册.pdf · 分块 #3 · 85%   │
│                                 │
│ HR制度.md                       │
│ 年假计算规则如下...            │
│ HR制度.md · 分块 #1 · 72%      │
└─────────────────────────────────┘
```

- 默认折叠，只显示标题行，点击展开/折叠
- 显示文档名称、摘要、来源文件、分块编号、相关度
- 来源数据从 `/ai/assistant_app/rag/sources` 接口获取

---

## 五、P2 运营完善功能

### 5.1 多语言国际化

支持 `zh-CN`（中文）和 `en`（英文）两种语言：

```html
ChatbotSDK.init({
  integrateId: 'my-app',
  requestDomain: 'https://ai.example.com',
  locale: 'en',  // 英文界面
});
```

国际化覆盖范围：
- 弹窗标题、输入框占位符、发送按钮
- 最小化/关闭按钮提示
- 清空对话按钮及确认弹窗
- Loading 状态文字
- 所有错误提示（网络/超时/服务器/跨域等）
- 知识库下拉框默认选项
- RAG 引用来源标题
- 历史会话面板文本

### 5.2 会话管理面板

弹窗头部新增时钟图标按钮，点击展开历史会话面板：
- 展示当前用户的历史会话列表（从 `/conversation/list` 接口获取）
- 支持导出会话（下载文本文件）
- 支持删除会话（二次确认）
- 空状态提示

### 5.3 控制台日志体系

SDK 全流程结构化日志，带 `[ChatbotSDK]` 前缀：

| 生命周期 | 日志内容 |
|----------|---------|
| `init()` | `初始化完成 integrateId={} requestDomain={}` |
| `sendMessage()` | `发送消息 integrateId={} length={}` |
| `收到回复` | `AI 回复 integrateId={} length={} duration={}ms` |
| `流式完成` | `流式回复完成 integrateId={} length={} duration={}ms` |
| `请求失败` | `请求失败 integrateId={} status={} message={}` |
| `clearHistory()` | `清空会话 integrateId={}` |
| `destroy()` | `销毁实例 integrateId={}` |
| `分类切换` | `切换知识库分类 categoryId={}` |

- `config.debug = false` 关闭 info/warn 日志，error 始终输出
- 内置性能计时器，自动记录 AI 回复耗时

---

## 六、对接的后端接口

### P0 — 基础对话
```
GET /ai/assistant_app/chat/sync
GET /ai/assistant_app/chat/sse
```

### P1 — 知识库联动
```
GET /ai/assistant_app/chat/rag/sse      # RAG 增强流式对话
GET /ai/assistant_app/rag/sources       # RAG 引用来源
GET /category/tree                       # 分类树（下拉框数据源）
GET /category/list                       # 分类列表
```

### P2 — 会话管理
```
GET  /conversation/list                  # 会话列表
GET  /conversation/{id}/messages         # 会话消息
DELETE /conversation/{id}                # 删除会话
GET  /conversation/{id}/export           # 导出会话
```

---

## 七、参数映射关系

**核心映射（SDK → 后端）：**

| SDK 入参 | 后端参数 | 说明 |
|----------|----------|------|
| `integrateId` | `roleId` | 客服角色 ID（决定 AI 人设和知识库检索范围） |
| `userId` | `accountId` | 客户账号 ID（账号可绑定角色，绑定后服务端覆盖 roleId） |
| （自动管理） | `chatId` | 对话 ID（自动从 `/conversation/list` 获取或生成，格式 `sdk_时间戳_随机串`） |

**chatId 自动管理逻辑：**
1. SDK 初始化时，查询 `/conversation/list?accountId={userId}&roleId={integrateId}`
2. 有匹配会话 → 使用最新会话的 `conversationId` 作为 `chatId`
3. 无匹配会话 → 自动生成新 `chatId`（格式：`sdk_时间戳_随机串`）
4. `chatId` 缓存在 localStorage（key: `csk_chatId_{integrateId}_{userId}`）
5. `clearHistory()` 会生成新的 `chatId`，开始全新对话

---

## 八、CSS 命名空间隔离

所有 DOM 元素的 class/id 均使用 `csk-` 前缀，不会与宿主页面样式冲突：

| 元素 | ID/Class |
|------|----------|
| 悬浮按钮 | `#csk-launcher` `.csk-launcher` |
| 聊天弹窗 | `#csk-window` `.csk-window` |
| 消息区 | `#csk-messages` `.csk-messages` |
| 输入框 | `#csk-input` `.csk-input` |
| 发送按钮 | `#csk-send-btn` `.csk-send-btn` |
| 知识库下拉 | `#csk-category-select` `.csk-category-select` |
| 历史面板 | `.csk-history-panel` |
| 样式标签 | `style[data-csk-sdk]` |

z-index 分层：悬浮按钮 9998，弹窗 9999。

---

## 九、localStorage 缓存

缓存 key 格式：`csk_history_{integrateId}`

数据结构：
```json
{
  "messages": [
    {
      "id": "uuid",
      "role": "user|ai",
      "content": "消息内容",
      "timestamp": 1700000000000,
      "sources": []
    }
  ],
  "updatedAt": 1700000000000
}
```

- 消息上限 200 条，超出自动裁剪最早 50 条
- 按 `integrateId` 隔离，不同接入方互不影响
- `init()` 时自动恢复历史消息
- RAG 引用来源同步缓存到 `sources` 字段

---

## 十、错误处理

所有错误不抛异常、不阻塞宿主页面，仅 `console.error` 输出。

| 错误场景 | 中文提示 | 英文提示 |
|----------|---------|---------|
| 网络断开 | 网络连接失败，请检查网络 | Network connection failed |
| 请求超时 | 请求超时，请稍后重试 | Request timed out |
| HTTP 500 | 服务器异常，请稍后重试 | Server error |
| 跨域阻断 | 跨域请求被拦截... | CORS request blocked... |
| HTTP 401 | 鉴权失败，请联系管理员 | Authentication failed |
| HTTP 403 | 无访问权限 | Access denied |
| 流中断 | 回复被中断 | Response interrupted |

---

## 十一、技术栈

- **语言**：TypeScript → ES2017
- **打包**：Rollup → IIFE 格式
- **压缩**：Terser
- **Markdown**：内置轻量级渲染器（零外部依赖）
- **国际化**：内置 i18n 字典
- **浏览器兼容**：Chrome 70+, Firefox 70+, Safari 13+, Edge 79+
- **产物大小**：`.min.js` ~45KB（gzip ~15KB）

---

## 十二、开发与构建

```bash
# 进入 SDK 工程目录
cd client/

# 安装依赖
npm install

# 构建（输出到 dist/）
npm run build

# 开发模式（watch）
npm run dev
```

源码结构：

```
client/
├── src/
│   ├── index.ts      # 入口：window.ChatbotSDK 挂载
│   ├── types.ts      # TypeScript 类型定义
│   ├── config.ts     # 配置解析 + 参数校验
│   ├── logger.ts     # 日志模块（P2 增强：计时+生命周期）
│   ├── storage.ts    # localStorage 封装
│   ├── api.ts        # HTTP 封装 + SSE 流式 + P1 RAG + P2 会话
│   ├── dom.ts        # DOM 构建 + 拖拽 + P1 来源/分类 + P2 面板
│   ├── styles.ts     # CSS 注入 + 主题 + P1 Markdown/来源 + P2 面板
│   ├── chat.ts       # 对话核心 + P1 Markdown/RAG + P2 i18n
│   ├── markdown.ts   # P1 轻量级 Markdown 渲染器
│   ├── i18n.ts       # P2 多语言国际化
│   └── utils.ts      # UUID、防抖、XSS 转义
├── dist/             # 构建产物
├── package.json
├── tsconfig.json
├── rollup.config.js
└── README.md
```

---

## 十三、功能路线图

| 阶段 | 状态 | 内容 |
|------|------|------|
| **P0 核心链路** | ✅ 已完成 | 项目骨架、配置校验、样式注入、悬浮按钮+弹窗、HTTP 通信、对话核心、本地缓存、打包构建 |
| **P1 体验增强** | ✅ 已完成 | SSE 流式打字机、Markdown 渲染、知识库下拉切换、RAG 引用来源展示、UI 全配置化、弹窗拖拽 |
| **P2 运营完善** | ✅ 已完成 | 多语言国际化（zh-CN/en）、控制台日志体系、会话管理面板（列表/导出/删除） |
| **可选扩展** | 🔜 待定 | 知识库管理嵌入（`showAdminPanel`）、更多语言、主题皮肤 |

---

## 十四、验证测试

访问 `http://localhost:9090/sdk/test.html` 运行自动化验证。

测试覆盖（22 个用例）：

| 编号 | 阶段 | 功能 |
|------|------|------|
| T1-T13 | P0 | 全局挂载、参数校验、DOM 创建、open/close、默认值、主题色、位置、destroy、缓存、API 对话 |
| T14-T19 | P1 | Markdown 样式、知识库分类切换、RAG 来源样式、RAG SSE 接口、RAG 来源接口、分类树接口 |
| T20-T22 | P2 | 多语言国际化、会话管理面板、会话列表接口 |