Chatbot Widget — 管理后台悬浮问答组件设计
文档版本：v1.0 更新日期：2026-07-13 文档定位：为管理后台页面增加悬浮 Chatbot 按钮 + 右侧抽屉问答组件的产品设计 试点页面：
iot-semantics.html（标准化语义库）
1. 背景与目标
1.1 动机
管理后台（标准化语义库、空间/设备资产管理等）目前是纯配置界面，管理员在操作过程中遇到概念疑问时，需要切换到其他页面或系统查询。通过嵌入轻量 Chatbot，管理员可在不离开当前页面的情况下快速获取答案。
1.2 设计目标
- 不侵入现有页面 — 通过独立 Widget 方式叠加，不修改现有布局和样式
- 仅保留核心问答能力 — 猜你想问 + QA sub-agent（带 G-Cite 引用归因）
- 可复用 — 后续其他管理页面一行代码即可接入
- 交互一致 — 悬浮按钮 → 右侧抽屉，符合管理后台现有 UI 模式
1.3 排除范围
| 能力 | 排除原因 |
|---|---|
| 设备控制（调温/开关灯） | Web 端管理后台不需要实时控制 |
| 设备查询（查状态/温度） | 同左 |
| 会议室预定流程 | 管理后台场景不需要 |
| 空间控制面板（整备） | 同左 |
2. 布局设计
2.1 浮动按钮
- 位置：页面右下角，距右/下各 24px
- 尺寸：52×52px 圆形
- 样式：主色背景
#4f46e5+ 白色💬图标 + 阴影0 4px 16px rgba(79,70,229,0.4) - 定位：
position: fixed; z-index: 500 - Hover 微放大效果
2.2 右侧抽屉
- 宽度：420px
- 打开/关闭：
right属性过渡动画 0.3s - 遮罩层：
rgba(15,23,42,0.4)+backdrop-filter: blur(2px) - 关闭方式：✕ 按钮、点击遮罩、ESC 键
2.3 抽屉内部结构
┌──────────────────────┐
│ Header: "AI 智能问答" ✕ │
├──────────────────────┤
│ │
│ 消息列表 (flex:1) │
│ ┌──────────────────┐│
│ │ 猜你想问卡片 ││
│ │ 问题1 ││
│ │ 问题2 ││
│ └──────────────────┘│
│ │
│ 🤖 回答文本[1][2] │
│ ┌──────────────┐ │
│ │ 引用来源 (2) │ │
│ └──────────────┘ │
│ │
├──────────────────────┤
│ [输入框...] [➤] │
└──────────────────────┘3. 文件结构
space-agent/
├── css/
│ └── chatbot-widget.css ← 新增：Widget 专属样式（命名空间隔离）
├── js/
│ └── chatbot-widget/ ← 新增目录
│ ├── chatbot-widget.js ← 入口：浮窗/抽屉创建 + 开关控制
│ ├── chatbot-widget-chat.js ← 对话：猜你想问 + 消息渲染 + 输入
│ └── chatbot-widget-citation.js ← G-Cite 引用系统
│
└── iot-semantics.html ← 修改：加 2 行引用3.1 组件职责
chatbot-widget.js（入口）
- 暴露全局
ChatbotWidget对象 ChatbotWidget.init()— 创建浮动按钮 + 抽屉 DOM，绑定事件ChatbotWidget.open()/ChatbotWidget.close()— 打开/关闭抽屉- 事件绑定：按钮点击切换、ESC 关闭、遮罩点击关闭
chatbot-widget-chat.js（对话）
- 猜你想问预设问题列表 → 点击填充并发送
- 输入框 Enter 发送
appendUserMessage()/appendBotMessage()/showTyping()/removeTyping()- Toast 提示、自动滚动
chatbot-widget-citation.js（引用）
- 从
chat-citation.js精简移植 - QA_CITATIONS 模拟数据（10 个 chunk，RAG + Web 双源）
renderQACitation()— 流式逐字渲染 +[C:N]→<sup>实时转换- idMap 重映射（按 LLM 首次出现顺序编号）
- 引用摘要面板（展开/折叠）+ 点击上标打开半屏详情
- 引用详情半屏 + 完整原文 Webview
chatbot-widget.css（样式）
- 命名空间前缀
.chatbot-widget-*，避免与宿主页面冲突 - 浮动按钮 + 抽屉动画 + 对话气泡 + G-Cite 引用样式
4. 交互流程
场景 1：猜你想问 → 快速问答
- 用户点击 💬 浮动按钮 → 抽屉从右侧滑入
- 猜你想问卡片显示预设问题列表（如"暖通空调的标准语义有哪些？"）
- 用户点击问题 → 问题作为用户消息追加 → 打字机动画
- 延迟 1.2s → 移除 typing → 流式逐字输出回答
- 回答中的
[C:N]实时渲染为蓝色上标 - 回答结束 → 引用摘要面板自动渲染
场景 2：用户自行输入
- 用户在输入框输入文本 → Enter 发送
- 同场景 1 的消息追加 → typing → 回答渲染流程
- 带 G-Cite 引用渲染（如果回答包含
[C:N]标记）
场景 3：引用交互
- 点击上标
<sup>1</sup>→ 从底部弹出半屏显示 chunk 详情 - 点击"展开引用来源" → 摘要面板展开显示引用条目列表
- 点击引用条目 → 半屏详情；有 URL 的可在"完整原文"查看 iframe Webview
退出场景
- 点击 ✕ → 抽屉滑出
- 点击遮罩 → 抽屉滑出
- 按 ESC → 抽屉滑出
5. 集成方式
在 iot-semantics.html 中：
<head> 末尾（与现有样式并列）：
html
<link rel="stylesheet" href="css/chatbot-widget.css"><body> 末尾（与现有脚本并列）：
html
<script src="js/chatbot-widget/chatbot-widget.js"></script>
<script>ChatbotWidget.init()</script>无需修改页面原有的 HTML 结构、CSS 样式或 JS 逻辑。
6. 技术要点
6.1 样式隔离
所有样式选择器使用 .chatbot-widget-* 前缀，避免与宿主页面的 Bootstrap 风格样式（如 .btn、.modal）冲突。
6.2 G-Cite 移植策略
chat-citation.js 中 renderQACitation() + _renderCitationPanel() + toggleCitationPanel() + openCiteSheet() + closeCiteSheet() + openCiteWebview() + closeCiteWebview() + _initCiteSupClick 全部原样移植。
唯一修改：_initCiteSupClick 中的事件委托目标从 chatbox-body 改为 chatbot 消息容器。
6.3 猜你想问内容
初始预设问题适配语义库场景示例：
- "暖通空调的标准语义 Key 有哪些？"
- "Boolean 类型的语义用在什么场景？"
- "[C:N] 在 G-Cite 中怎么工作的？"
7. 后续扩展
- 其他管理页面（
iot-assets.html、iot-devices.html等）只需加同样的 2 行引用 - 猜你想问内容可根据页面上下文动态配置（后续可对接 FAQ 配置管理后台）