RAG/client

ChatbotSDK — 前端对接文档

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

---

一、快速开始

最简接入（3 行代码）

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

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

完整配置接入

<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 后，输入区上方出现知识库分类下拉框：

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（英文）两种语言：

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}

数据结构：

{
  "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）

---

十二、开发与构建

# 进入 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	多语言国际化、会话管理面板、会话列表接口