RAG/client

ChatbotSDK — 前端对接文档

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

---

一、快速开始

最简接入（3 行代码）

<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()	清空当前会话

---

四、完整接入示例

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

数据结构：

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

---

十一、开发与构建

# 进入 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 的实际对话（需后端运行）