# 宝锐销售工作台 · AI 问答助手升级方案

> 版本 v1.0 · 2026-08-21 · 供讨论定稿，未开始实施

---

## 一、背景与现状

工作台右下角有悬浮 🤖 气泡（FAB），点击弹出 360×520px 聊天面板，调用后端 `/api/chat`（`脚本/ai_chat.py`）→ DeepSeek V4 Pro。

**现有能力**
- 单轮问答：每次只发 `question` 字段，**无上下文记忆**，无法追问
- 三条铁律（system prompt 硬约束）：① 只答工作问题 ② 客户数据权限隔离 ③ 行业/市场/竞品自由回答
- 输出纯文本：前端 `mdRender` 渲染表格/加粗/列表，**不能导出、不能落盘**

**现有技术栈（改造成本低）**
| 层 | 文件 | 说明 |
|---|---|---|
| 前端（双入口） | `工具/index.html`（CloudBase 源）+ `工具/app.html`（飞书内嵌） | `TABS` 数组驱动 tab，现有 10 个 tab |
| 后端服务 | `脚本/销售工作台服务.py`（:8765，Tailscale Funnel 暴露） | `/api/chat` 端点已存在 |
| AI 模块 | `脚本/ai_chat.py`（214 行，标准库 + yaml） | 权限过滤 + system prompt 已实现 |

---

## 二、问题诊断（三大短板）

| # | 短板 | 现状 | 后果 |
|---|---|---|---|
| 1 | **单轮无记忆** | `handle()` 只收 `question`，无 `history` | 无法追问"那这个客户呢"，每问一次像失忆 |
| 2 | **只吃文本** | 后端入参仅 `question` | ERP 订单 Excel / 合同 PDF / 拍照单全部喂不进去 |
| 3 | **输出只有文字** | 只返回 `answer` 字符串 | 拜访卡/报告/表格需手动复制粘贴，无法落盘、无法溯源 |

**结论**：三条短板导致 AI 助手停在"能聊天"而非"能干活"。只做表面增强、不换形态，走不远。

---

## 三、设计原则

对齐现有 Copilot 设计原则，新增一条：

1. **零额外输入** — 能自动取到的数据不让人手填
2. **嵌入现有工具不另开** — 复用现有 tab、数据源、生成技能
3. **MVP 先行** — 先跑通最小闭环，再叠加
4. **移动端优先** — 飞书内嵌场景，触控优先
5. **权限铁律不破** — 上传/输出/历史一律沿用三条铁律隔离
6. **数据来源可溯源** — AI 说的数字必须能指回具体数据文件（新增）

---

## 四、形态方案对比与推荐

### 方案 A：气泡 + 独立 Tab 并存（✅ 推荐）

- 气泡保留做**快问**：客户页翻到一半随手问一句，不断心流
- 新增「AI 助手」独立 Tab 做**深问**：上传、生成、溯源、长表格、多轮深度对话
- 气泡加「⤢ 展开到全屏」按钮 → 跳转 AI 助手 Tab

### 方案 B：只做独立 Tab，移除气泡

- 干净，但丢失"随时问"的便利性，销售要切到 Tab 才能问，高频快问体验变差

### 方案 C：保持气泡，只增强不另开

- 小窗（360×520）物理上装不下上传、生成、溯源，增强空间受限

### 对比

| 维度 | A 并存 | B 仅 Tab | C 仅气泡 |
|---|---|---|---|
| 快问便利性 | ✅ | ❌ | ✅ |
| 深问/上传/生成 | ✅ | ✅ | ❌ 受限 |
| 实施复杂度 | 中（加 1 tab + 展开跳转） | 低 | 高（硬塞进小窗） |
| 用户心智 | 清晰（快/深分层） | 单一 | 模糊 |

**推荐 A**。理由：不牺牲便利性，又给增强功能足够画布；实施上"加一个 tab + 一个跳转"成本可控。

---

## 五、功能设计

### 5.1 多轮上下文记忆（P0，最关键）

- 前端维护 `chatHistory` 数组，发送时把 `messages` 传给后端
- 后端 `handle()` 接收 `messages`（含角色 + 内容），拼成完整 history 调用 DeepSeek
- **安全**：历史按 `user.name` 隔离存储，不跨用户泄漏；历史中的客户数据同样受权限过滤约束

### 5.2 上传增强（P1，价值最高）

**支持类型与解析方式（全部本地解析，不落 CloudBase）**

| 类型 | 场景 | 解析 |
|---|---|---|
| Excel/CSV | ERP 订单、客诉、客户名单 | pandas（`/usr/bin/python3`） |
| PDF/Word | 合同、产品资料 | textutil / pymupdf |
| 图片 | 拍照订单、实验报告 | OCR（macOS Vision / 中文 OCR） |

**核心设计**：上传后**不直接喂给大模型**，而是后端解析 → 提取文本 → **沿用三条铁律做权限过滤** → 注入。既吃到内容，又不破坏隔离。

**典型场景**
- 丢 ERP 订单 Excel → "这个客户今年买了多少、主销货号是啥"
- 丢合同 → "提取账期、付款条件、违约条款"

### 5.3 输出增强（P1/P2）

| 能力 | 说明 |
|---|---|
| 表格导出 | mdRender 已渲染表格 → 加「复制为表格 / 导出 CSV」 |
| 生成落盘 | 复用拜访卡/调研卡/话术库技能，AI 输出一键生成 HTML 落盘 `客户管理/` |
| 引用溯源 | 回答附带「数据来源：`kpi_dashboard.json` / `mcp_customers.json`」 |
| 对话导出 | 一键存 md / 回写经验库 |

### 5.4 引用溯源（P2，信任基石）

AI 回答客户/KPI 问题时，后端在响应中附带 `sources` 字段（引用了哪些数据文件、哪条客户记录），前端渲染为可点击的"来源"标签。让销售敢信 AI 的数字。

---

## 六、技术架构改造

### 6.1 后端（`ai_chat.py` + `销售工作台服务.py`）

```
/api/chat 入参扩展：
{
  "question": "...",          // 兼容旧版，保留
  "messages": [...],           // 新增：多轮 history
  "files": [                   // 新增：上传文件（base64 或临时路径）
    {"name": "订单.xlsx", "mime": "...", "data": "..."}
  ],
  "user": {name, role, dept, line}  // 不变
}
```

`ai_chat.py` 新增两个函数：
- `_parse_upload(file)` — 按 mime 分派到 pandas/textutil/OCR 解析，返回文本
- `_filter_upload_text(text, user)` — 上传文本同样走权限过滤（含客户名黑名单剔除）

### 6.2 前端（`index.html` + `app.html` 同步改）

1. `TABS` 数组加一项：`{ id: 'aiAssistant', label: 'AI 助手', icon: '🤖', lines: ['da','ls'] }`
2. 新增 `aiAssistant` 渲染函数（大画布三栏：左对话区 + 右上传/资料面板）
3. 气泡 `chat-fab` 加「⤢ 展开」按钮 → `switchTab('aiAssistant')`
4. 上传组件：`<input type="file">` + 拖拽，前端读文件 → base64 → POST `/api/chat`

### 6.3 数据流

```
销售提问/传文件
  → 前端封装 {question, messages, files, user}
  → /api/chat (Funnel → :8765)
  → ai_chat.handle()
      ├─ 解析上传文件（本地）
      ├─ 权限过滤（三条铁律）
      ├─ 拼 system prompt + history
      └─ DeepSeek V4 Pro（thinking: disabled）
  → 返回 {answer, sources, visible_customers}
  → 前端渲染 + 溯源标签 + 导出按钮
```

---

## 七、权限与安全设计

| 项 | 设计 |
|---|---|
| 客户隔离 | 沿用 `_visible_for_user`（admin/gm 全量 → manager 本部门 → sales 仅自己） |
| 上传内容隔离 | 解析出的文本含非授权客户名时，同样过滤 |
| 会话历史隔离 | 按 `user.name` 分桶，不跨用户 |
| 文件不落盘 | 上传文件内存解析，不写 CloudBase，不留本地残留 |
| 文件大小上限 | 建议 10MB（订单 Excel 足够，PDF 大图需限制） |
| 铁律不破 | 上传的合同/资料同样只答工作问题，家庭/私人问题照旧拒绝 |

---

## 八、分阶段落地路线图

| 阶段 | 内容 | 工作量（agent 实现） | 依赖 | 验收标准 |
|---|---|---|---|---|
| **P0 快赢** | 气泡「展开」跳转 + 多轮记忆 | ~0.5 天 | 无 | 能连续追问"那这个客户呢"，上下文不丢 |
| **P1 核心** | 独立 Tab + 文件上传（Excel/CSV 先行） | ~2 天 | P0 | 丢 Excel 能问出客户金额/主销货号，权限隔离正确 |
| **P2 增强** | 生成落盘 + 引用溯源 + 对话导出 | ~2 天 | P1 | AI 输出可生成 HTML 落盘、附来源标签、可导出 |

> 上传 PDF/Word/图片解析（textutil/OCR）可与 P1 并行，作为 P1.5 补充。

---

## 九、风险与注意事项

1. **权限回归风险**：上传/历史/输出三处新增数据入口，都要过 `_visible_for_user`，改完必须用不同角色账号实测（admin/manager/sales 各测一遍）
2. **双入口同步**：`index.html` 与 `app.html` 必须同步改，否则本地/云端口径不一致（老规矩）
3. **DeepSeek thinking**：调用必须带 `thinking: {'type':'disabled'}`，否则答案在 `reasoning_content` 拿不到（已踩坑）
4. **上传文件安全**：base64 传大文件会拖慢，Excel 用原始 bytes + pandas 读更稳，需在前端限制体积
5. **模型选型**：AI 助手保持 DeepSeek V4 Pro（分析型、AI 消费），不换 Kimi K3（叙事型、人看）

---

## 十、决策记录（2026-08-21 已拍板）

| # | 决策项 | 结论 |
|---|---|---|
| 1 | 形态 | 方案 A：气泡 + 独立 Tab 并存；**Tab 与气泡共享同一份会话历史**，切过去接着聊 |
| 2 | 上传范围 | 一步到位：Excel/CSV + PDF + Word + 图片 OCR |
| 3 | 生成落盘 | 先预览 → 点「保存」→ 落盘本地 `客户管理/`（刷新 `file_manifest.json`）；CloudBase 仅作「对外共享」可选通道 |
| 4 | 引用溯源 | **所有问答**附 `sources` 来源标签 |
| 5 | 历史保留 | 保留，存后端本地 `数据/chat_history.json`（按 `name` 分桶、不交叉），**排除 CloudBase 同步**；admin 全见，入口放管理员 Tab |
| 6 | 回写经验库 | 销售员可一键回写 IMA，回写进入**待审核队列** → 飞书通知 admin 审核 → 通过才真正写库 |
| 7 | 经验归档 | AI Tab 加「⭐ 归档为经验」+「＋ 新建对话」；把**整段多轮追问链**提炼成结构化经验（标题/问题背景/涉及客户/货号/关键结论/建议动作 + 原始问答链），预览确认后走既有 IMA 审核入库 |

### 回写审核流程（疑问③落地方案）

```
销售员点「回写 IMA」
  → 内容写入待审核队列（本地 数据/ima_pending_review.json）
  → 飞书推送通知刘新元（App cli_aaee6a2f90b89bc1）
  → 刘新元在管理员 Tab 审核（通过/驳回）
      ├─ 通过 → 调 IMA create_note 真正写库，标记已审核
      └─ 驳回 → 通知销售员 + 附驳回理由，销售员可修改重提
```

### 历史存储安全红线

- `数据/chat_history.json` **禁止**进入 `cb_sync.sh` / cron 的 CloudBase 部署清单
- 历史按 `user.name` 分桶，`/api/history` 端点做权限校验：非 admin/gm 只能读写自己的桶
- admin 在管理员 Tab（`dataMgmt`）可切换查看任意销售员的对话历史

### 经验归档 · 完整链路验证结论（2026-08-22 实测）

以硕世 M2181/M2331 多轮追问为真实案例，全流程 5 步走通：

| 步骤 | 端点 | 结果 |
|---|---|---|
| ① 提炼 | `/api/archive_experience`（`ai_chat.archive_experience`） | ✅ 多轮问答链 → 结构化经验 + 原始问答链 |
| ② 提交审核 | `/api/ima_review` submit | ✅ 进入待审核队列 |
| ③ 队列查询 | `/api/ima_review` list | ✅ pending 状态正确 |
| ④ 审核通过 | `/api/ima_review` approve | ✅ 真实写入 IMA「宝锐诊断原料销售」知识库 |
| ⑤ 状态回写 | — | ✅ `approved`，审核人=刘新元 |

**验证中发现并修复 2 个隐藏 bug**（此前 approve 环节从未真正测通，一直停在 submit+飞书通知）：

| Bug | 现象 | 修复 |
|---|---|---|
| 笔记 API 路径写反 | `openapi/v1/note/import_doc` → 404 | 改为 `openapi/note/v1/import_doc`（IMA v3.0：笔记用 `/note/v1/`，知识库才用 `/wiki/v1/`） |
| 返回字段取错 | 代码找 `doc_id`，实际返回 `data.note_id` → 永远拿不到 ID、误报"创建失败" | 提取逻辑改为 `note_id` 优先 |

**关键结论**：`import_doc` 返回 `data.note_id`，`add_knowledge` 返回 `data.media_id`，两者构成「创建笔记 → 加入知识库」两步闭环。经验归档功能已端到端可用。

---

*决策已定，实施任务见 TASK.md 及本方案第八节路线图。*