# ChatbotSDK — 前端对接文档

> P0 核心链路已完成 | 构建时间：2026-06-25 | 版本：1.0.0

---

## 一、快速开始

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

```html
<script src="https://your-domain.com/sdk/chatbot-sdk.min.js"></script>
<script>
  ChatbotSDK.init({
    integrateId: 'my-app',            // 必传：集成标识
    requestDomain: 'https://your-domain.com', // 必传：后端地址
  });
</script>
```

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

### 集成到现有项目

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

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

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

---

## 二、SDKConfig 完整参数

| 参数 | 类型 | 必传 | 默认值 | 说明 |
|------|------|------|--------|------|
| `integrateId` | `string` | ✅ | — | 集成标识 → 后端 `chatId` + 数据隔离 key |
| `requestDomain` | `string` | ✅ | — | 后端 API 域名（如 `https://ai.example.com`） |
| `userId` | `string` | ❌ | — | 宿主用户标识 → 后端 `accountId` |
| `roleId` | `number` | ❌ | — | 客服角色 ID |
| `categoryId` | `number` | ❌ | — | 默认知识库分类 |
| `showCategorySwitch` | `boolean` | ❌ | `false` | 是否显示知识库下拉 |
| `title` | `string` | ❌ | `"AI 智能助手"` | 弹窗标题 |
| `width` | `number` | ❌ | `380` | 弹窗宽度(px)，移动端自适应 |
| `position` | `string` | ❌ | `"right-bottom"` | 悬浮按钮位置：`left-bottom` \| `right-bottom` |
| `primaryColor` | `string` | ❌ | `"#4F46E5"` | 主色调（适用于按钮/用户气泡/链接） |
| `launcherIcon` | `string` | ❌ | SVG 图标 | 悬浮按钮图标（URL 或 SVG 字符串） |
| `showClear` | `boolean` | ❌ | `true` | 是否显示清空对话按钮 |
| `showAdminPanel` | `boolean` | ❌ | `false` | 是否显示管理面板 |
| `streaming` | `boolean` | ❌ | `true` | 是否启用 SSE 流式输出 |
| `locale` | `string` | ❌ | `"zh-CN"` | 界面语言（预留） |
| `debug` | `boolean` | ❌ | `true` | 是否输出调试日志 |

---

## 三、公开 API

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

---

## 四、完整接入示例

```html
<script src="/sdk/chatbot-sdk.min.js"></script>
<script>
  ChatbotSDK.init({
    // 必传
    integrateId: 'hr-portal-v2',
    requestDomain: 'https://ai.example.com',

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

    // 知识库
    categoryId: 5,
    showCategorySwitch: true,

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

    // 行为
    streaming: true,
    locale: 'zh-CN',
    debug: false,
  });
</script>
```

---

## 五、参数映射关系

SDK 入参与后端 API 参数对照：

| SDK 入参 | 后端参数 | 说明 |
|----------|----------|------|
| `integrateId` | `chatId` | 会话标识 + 数据隔离 key |
| `userId` | `accountId` | 宿主用户标识 |
| `roleId` | `roleId` | 客服角色 ID |
| `categoryId` | `categoryId` | 知识库分类过滤 |

---

## 六、对接的后端接口

### 同步对话
```
GET /ai/assistant_app/chat/sync
  ?message={message}
  &chatId={integrateId}
  &accountId={userId}
  &roleId={roleId}
```

### SSE 流式对话
```
GET /ai/assistant_app/chat/sse
  ?message={message}
  &chatId={integrateId}
  &accountId={userId}
  &roleId={roleId}
```

### RAG 增强对话（P1 阶段启用）
```
GET /ai/assistant_app/chat/rag/sse
  ?message={message}
  &chatId={integrateId}
  &categoryId={categoryId}
  &rewriteStrategy=REWRITE
```

### RAG 引用来源（P1 阶段启用）
```
GET /ai/assistant_app/rag/sources
  ?message={message}
  &chatId={integrateId}
  &categoryId={categoryId}
```

### 分类列表（P1 阶段启用）
```
GET /category/list
GET /category/tree
```

---

## 七、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` |
| 样式标签 | `style[data-csk-sdk]` |

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

---

## 八、localStorage 缓存

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

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

- 消息上限 200 条，超出自动裁剪最早 50 条
- 按 `integrateId` 隔离，不同接入方互不影响
- `init()` 时自动恢复历史消息
- `clearHistory()` 清空本地缓存

---

## 九、错误处理

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

| 错误场景 | 提示信息 |
|----------|----------|
| 缺失 `integrateId` | `integrateId 是必传参数` |
| 缺失 `requestDomain` | `requestDomain 是必传参数` |
| 非法 URL | `requestDomain 不是合法的 URL 格式` |
| 网络断开 | `网络连接失败，请检查网络` |
| 请求超时 | `请求超时，请稍后重试`（超时时间 30s） |
| HTTP 401 | `鉴权失败，请联系管理员` |
| HTTP 403 | `无访问权限，请联系管理员配置` |
| HTTP 500 | `服务器异常，请稍后重试` |
| 跨域阻断 | `跨域请求被拦截，请联系管理员将当前域名加入 API 白名单` |
| localStorage 满 | `localStorage 空间不足，会话历史保存失败` |

---

## 十、技术栈

- **语言**：TypeScript → ES2017
- **打包**：Rollup → IIFE 格式
- **压缩**：Terser
- **浏览器兼容**：Chrome 70+, Firefox 70+, Safari 13+, Edge 79+
- **产物大小**：`.min.js` ~22KB（gzip ~8KB）

---

## 十一、开发与构建

```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     # 日志模块
│   ├── storage.ts    # localStorage 封装
│   ├── api.ts        # HTTP 封装 + SSE 流式
│   ├── dom.ts        # DOM 构建 + 拖拽
│   ├── styles.ts     # CSS 注入 + 主题定制
│   ├── chat.ts       # 对话核心
│   └── utils.ts      # UUID、防抖、XSS 转义
├── dist/             # 构建产物
│   ├── chatbot-sdk.js
│   ├── chatbot-sdk.min.js
│   └── *.map
├── package.json
├── tsconfig.json
├── rollup.config.js
└── README.md
```

---

## 十二、P0 → P1 → P2 路线图

| 阶段 | 状态 | 内容 |
|------|------|------|
| **P0 核心链路** | ✅ 已完成 | 项目骨架、配置校验、样式注入、悬浮按钮+弹窗、HTTP 通信、对话核心、本地缓存、打包构建 |
| **P1 体验增强** | 🔜 待开发 | SSE 流式打字机效果、知识库下拉切换、RAG 引用来源展示、UI 全配置化、Markdown 渲染、弹窗拖拽 |
| **P2 运营完善** | 🔜 待开发 | 会话管理面板、控制台日志体系、多语言国际化、知识库管理嵌入 |

---

## 十三、验证测试

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

测试覆盖：
1. ✅ `window.ChatbotSDK` 全局挂载
2. ✅ 配置校验（必传参数 + 默认值 + 错误提示）
3. ✅ DOM 挂载（悬浮按钮 + 弹窗 + 输入框 + 样式注入）
4. ✅ localStorage 缓存读写
5. ✅ 与后端 API 的实际对话（需后端运行）