CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

这是 AI 智能客服系统的前端 SDK 工程（chatbot-sdk），与仓库根目录的 Spring Boot 后端、src/main/resources/static/ 下的 Vue 3 管理后台是三个独立部分。SDK 产物是一行 <script> 标签即可嵌入第三方站点的悬浮客服窗口，IIFE 格式挂载到 window.ChatbotSDK。

根目录的 ../CLAUDE.md 描述后端架构，本文件只覆盖 client/ 工程。

构建与开发

cd client/

# 安装依赖
npm install

# 构建（输出 dist/chatbot-sdk.js 与 dist/chatbot-sdk.min.js）
npm run build

# 开发 watch 模式
npm run dev

构建工具：Rollup + @rollup/plugin-typescript + @rollup/plugin-terser，配置见 rollup.config.js
TypeScript 配置：tsconfig.json，target: ES2017，strict: true，rootDir: ./src，不生成 .d.ts
产物双份：chatbot-sdk.js（未压缩 + sourcemap，~93KB）和 chatbot-sdk.min.js（压缩，~45KB）
无测试框架：验证通过后端的 http://localhost:9090/sdk/test.html 运行 22 个浏览器端用例（见 README 第十四节），本工程内没有可运行的自动化测试

运行时依赖

SDK 本身不独立运行，需要后端在 requestDomain（通常 http://localhost:9090）提供以下接口：

基础对话：GET /ai/assistant_app/chat/sync、GET /ai/assistant_app/chat/sse
RAG：GET /ai/assistant_app/chat/rag/sse、GET /ai/assistant_app/rag/sources
分类：GET /category/tree、GET /category/list
会话：GET /conversation/list、GET /conversation/{id}/messages、DELETE /conversation/{id}、GET /conversation/{id}/export

完整接口契约见 README.md 第六节。修改 api.ts 时务必与后端 AiController / ConversationController 保持参数一致。

架构

模块职责与数据流

入口 src/index.ts 是单例，按固定顺序串联各模块（init() 中的 12 个步骤即生命周期）：

init(rawConfig)
  → config.ts    parseConfig()        解析 + 校验，返回 ResolvedConfig（失败返回 null，不抛异常）
  → i18n.ts      setLocale()          设置语言字典（zh-CN / en）
  → logger.ts    setDebug()           控制日志级别
  → api.ts       setApiConfig()       注入 requestDomain 等，供后续 HTTP/SSE 调用复用
  → styles.ts    injectStyles()       注入 <style data-csk-sdk>，按 primaryColor 生成主题
  → dom.ts       createLauncher() / createChatWindow()  构建 DOM，返回元素引用与 loading 控制函数
  → dom.ts       enableDrag()         弹窗头部拖拽，返回 cleanup 函数
  → chat.ts      initChat()           绑定事件、注入 DOM 引用，建立对话核心状态
  → chat.ts      initChatHistory()    异步加载 chatId 与历史（不阻塞 UI）

模块间通过两种方式通信：

闭包状态：index.ts、chat.ts、api.ts 各自持有模块级变量，靠 init* 函数注入
CustomEvent：DOM 层（dom.ts）派发 csk:categoryChange、csk:loadHistory，index.ts 监听后转发给 chat.ts

关键模块

chat.ts（最大、最核心）：对话状态机。处理发送、SSE 流式追加、Markdown 渲染、RAG 来源展示、流中断兜底、无流内容降级为同步、chatId 自动管理逻辑、清空会话。修改对话行为优先改这里。
api.ts：HTTP 封装 + SSE 流解析。三种 SSE 接口（普通流式、RAG 流式、同步）的解析逻辑都在这里，注意流式解析的边界处理。
dom.ts：纯 DOM 构建与事件绑定，含知识库下拉、RAG 来源卡片、历史会话面板的渲染。
styles.ts：所有 CSS 字符串模板，按 primaryColor 动态着色。改动 UI 视觉改这里，不要在 dom.ts 里写内联样式。
markdown.ts：零依赖轻量 Markdown 渲染器。安全模型：所有非代码块内容先 HTML 转义再转换语法，代码块内容同样转义；链接只允许 http/https。修改渲染器时必须维持这一 XSS 防护顺序。

单例与生命周期

index.ts 用模块级变量持有 config 和所有 DOM 引用，isInitialized 防止重复初始化。destroy() 必须清理：移除 DOM、调用 dragCleanup()、removeStyles()、置空所有引用。新增 DOM 引用时记得在 destroy() 中同步置空。

关键约定

参数映射（SDK → 后端）

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

chatId 缓存在 localStorage（key: csk_chatId_{integrateId}_{userId}），clearHistory() 会重新生成。改 chat.ts 的 chatId 逻辑时注意与后端 ConversationController 的会话匹配规则一致。

CSS 命名空间

所有 class/id 用 csk- 前缀，样式注入到 <style data-csk-sdk>，z-index：悬浮按钮 9998，弹窗 9999。新增 DOM 元素必须带前缀，避免污染宿主页面。

localStorage

消息历史 key：csk_history_{integrateId}，上限 200 条，超出裁剪最早 50 条
chatId key：csk_chatId_{integrateId}_{userId}
不同 integrateId 隔离，互不影响

错误处理

所有错误不抛异常、不阻塞宿主页面，仅 console.error 输出（error 始终输出，info/warn 受 debug 控制）。新增异步逻辑要 try/catch 包裹，失败走 logger.warn / logger.error。

部署

构建后将 dist/chatbot-sdk.min.js 上传到后端 src/main/resources/static/sdk/（或 CDN），宿主页面通过 <script src="/sdk/chatbot-sdk.min.js"></script> 引入。README.md 有完整接入示例与全部配置参数表，文档是 SDK 对外契约的一部分，改公开 API（init/destroy/open/close/toggle/clearHistory）或 SDKConfig 字段时同步更新 README。

6.1 KiB Raw Blame History