# AI 问答助手升级方案 v1.0（2026-08-21 讨论定稿）

方案全量文档：`~/Desktop/Hermes输出-工作类/AI助手升级方案.md`

## 现状（2026-08-19 上线）

- 右下角悬浮 🤖 气泡 → 360×520 聊天面板 → `/api/chat`（`脚本/ai_chat.py`）→ DeepSeek V4 Pro
- 单轮无记忆（`handle()` 只收 `question`）、只吃文本、输出纯文本（mdRender）
- 三条铁律：只答工作 / 客户权限隔离（`_visible_for_user`）/ 行业竞品自由回答
- 前端双入口：`工具/index.html`（CloudBase 源）+ `工具/app.html`（飞书内嵌），`CHAT_APIS=[Funnel,localhost]` 降级

## 用户锁定的 5 个决策（实施必须遵守，勿再重问）

1. **形态**：气泡 + 独立 Tab 并存；Tab 必须能读气泡的会话记忆（共享同一份历史，切过去接着聊）
2. **上传**：一步到位（Excel/CSV + PDF/Word + 图片 OCR 全做）
3. **生成落盘**：先预览 → 点「保存」才写盘；默认存本地 `客户管理/`（后端 `/api/save_doc` 写文件 + 刷新 `file_manifest.json`），CloudBase 仅作对外共享的可选通道
4. **引用溯源**：所有问答都附 `sources` 溯源标签
5. **历史**：保留、按人分桶不交叉，admin（刘新元）可见所有人历史

## 三大短板 → 解法

| 短板 | 解法 |
|---|---|
| 单轮失忆 | 多轮上下文：前端维护 `chatHistory`，后端 `handle()` 收 `messages` 拼 history |
| 只吃文本 | 上传增强：本地解析（pandas/textutil/OCR）→ 沿三条铁律权限过滤 → 注入 |
| 输出只有文字 | 生成落盘 + 引用溯源 + 对话导出 |

## 待用户拍板 3 个疑问（下次会话先问再开工）

① 存储：本地为主 + CloudBase 可选，是否认可？
② 历史落点：本地 `数据/chat_history.json`（按 name 分桶）+ 明确排除 CloudBase 同步清单；admin 查看他人历史入口放哪（AI 助手 Tab 下拉 or 数据管理 Tab）？
③ 回写：生成的拜访卡/报告，销售员本人是否也回写 IMA 经验库？

## ⚠️ 安全铁律

历史 JSON 含客户数据，**绝不能进 CloudBase 同步**（`cb_sync.sh` / cron 部署清单），否则客户数据泄漏公网。

## 技术要点

- 后端 `/api/chat` 入参扩展：`{question, messages[], files[], user}`（`question` 兼容旧版保留）
- `ai_chat.py` 新增 `_parse_upload(file)`（按 mime 分派 pandas/textutil/OCR）+ `_filter_upload_text(text, user)`（上传文本同样过权限）
- 前端 `TABS` 数组加 `{id:'aiAssistant', label:'AI 助手', icon:'🤖', lines:['da','ls']}`；气泡加「⤢ 展开」→ `switchTab('aiAssistant')`
- 分阶段：P0 多轮记忆（~0.5天）→ P1 Tab+上传（~2天）→ P2 生成落盘+溯源+导出（~2天）
- 模型：保持 DeepSeek V4 Pro（分析型），不换 Kimi K3（叙事型）
- 生成落盘复刻拜访卡/调研卡技能，存 `客户管理/`，通过 `file_manifest.json` 索引进访前准备 Tab