# baoyu-sales-copilot — details

### IMA API 能力边界（2026-07-29 实测）

| 能力 | API | 状态 | 备注 |
|------|-----|:--:|------|
| 列出/搜索文件 | `get_knowledge_list` / `search_knowledge` | ✅ | 返回标题+文件名 |
| 创建文件夹 | `create_folder` | ✅ | 需传 `name` 参数 |
| 文件列表含 `parent_folder_id` | — | ✅ | 文件有归属文件夹概念 |
| **读取文件内容** | 不存在 | ❌ | 只能做索引，内容靠本地匹配 |
| **移动文件到文件夹** | `move_knowledge` 仅跨KB | ❌ | 同KB内需在IMA App手动拖入 |
| 创建笔记并添加 | `import_doc` + `add_knowledge` | ✅ | media_type=11 |


### 签收判断（19关键词）
```
delivered: 派送至本人/派送成功/签收/已通知客户取件/已取件/快递柜/丰巢/驿站/已投递/前台/门卫/保安/物业代收...
delivering: 正在派/派送中/派件中  ← 必须在 delivered 之后判断
picked_up: opCode==54
```


### 服务端（`脚本/销售工作台服务.py`）

`/api/ima` POST端点，支持两个action：
- `search`: 搜索知识库 → `openapi/wiki/v1/search_knowledge`
- `create_note`: 创建笔记并添加到KB → `import_doc` → `add_knowledge(media_type=11)`


### IMA凭证
- 路径：`~/.config/ima/client_id` + `~/.config/ima/api_key`
- 知识库：`fwEO41E0Ef0CfulmtQHYgYQy_jBsbl6tXE5x6VYLIoA=`（宝锐诊断原料销售）
- API基路径：`openapi/wiki/v1`（知识库操作），`openapi/v1/note`（笔记操作）

## 铁三角→职能模块

拜访卡的协同推进部分使用具体职能而非AR/SR/FR角色标签：
- 客户对接（原AR）/ 技术支持（原SR）/ 交付保障（原FR）

## 设计原则
1. **零额外输入** / 2. **嵌入现有工具不另开** / 3. **MVP先行** / 4. **移动端优先** / 5. **字段≤7个/次**

## 数据源：物流单号追踪（MCP + 顺丰API）✅ 已上线

飞书项目 `销售管理` → `销售订单` 含 `物流单号`(field_96a245) 和 `收货人联系电话#`(field_3f38c1)。3165条记录均为顺丰SF开头。

**顺丰开放平台 EXP_RECE_SEARCH_ROUTES API**：
- 费用：免费，50万次/月，30次/秒
- 生产凭证：partnerID=BRSWK5CQ08HV, secret 见 `references/sf-express-tracking-api.md`
- **必须用 accessToken 鉴权（msgDigest 生产环境返回 A1006）**
- **必须传 checkPhoneNo（收件人手机号后4位），不传则路由为空**
- **trackingNumber 必须是数组 `["SFxxx"]`，trackingType 必须是数字 1**
- 沙箱测试在控制台网页端完成（3次成功→申请上线），不要用 API 调沙箱
- 完整接口文档和实测返回示例：`references/sf-express-tracking-api.md`

## 公司级LTC管理层培训

当用户要求为全公司管理层（非仅销售）做LTC培训时，核心转换：


### 受众适配表

| 部门 | LTC角色 | 最小可用化问题 |
|------|--------|-------------|
| 销售 | 前端触角：线索→机会→合同 | CRM记录含产品/原话/竞品/时限 |
| 研发/产品 | IPD环节：需求→方案→产品 | 销售提交需求72h内给回复 |
| 生产/供应链 | 交付履约：排产→发货→签收 | 样品寄送可视化共享表 |
| 质量/QC | ITR环节：客诉→根因→闭环 | 每客诉一条追踪记录，不闭环不下线 |
| 财务 | 终点站：开票→催款→回款 | 每月5号出逾期清单→销售3天反馈 |
| HR | 人才底座：招聘→培养→交接 | 销售离职前CRM补全+交接清单 |
| IT/行政 | 数据管道：系统→打通→培训 | 管理层工具使用培训 |


### 铁三角通用化
- 不只是"销售+技术+交付"，任何两个部门都可以签"协同契约"
- 格式：我给你__ / 你给我__ / __天内
- 两个人，一张纸，三句话


### 培训材料位置
- 管理层培训PPT：`培训资料/宝锐全公司_LTC管理层培训.html`（14页暗色滑动演示）
- 管理层一纸禅：`培训资料/宝锐_LTC管理层一纸禅.html`（A4可打印）
- 部门自查清单：`培训资料/宝锐_各部门LTC自查清单.html`（交互式，localStorage记忆状态）
- 参考书库：`~/work/library/华为各大管理体系电子书汇总/`（27册，含IPD/市场营销体系/流程管理）
- 详细框架：`references/ltc-management-training-framework.md`

## 智能工作助手（AI 助手，2026-08-19 上线，2026-08-21 全面升级）

> **2026-08-21 升级**：从「单轮气泡」升级为完整 AI 助手。新增：多轮记忆、独立「AI 助手」Tab（与气泡共享 chatHistory）、文件上传（Excel/CSV/Word/PDF/图片OCR）、sources 溯源、历史持久化（按人分桶+admin全见）、生成落盘、IMA 回写审核。


### 文件解析库（服务 venv = ~/.hermes/hermes-agent/venv/bin/python3）
- Excel .xlsx → `openpyxl`（**venv 无 pandas**，别用）；CSV → 标准库；Word → `textutil`（macOS）；PDF → `pymupdf`（`pip install pymupdf`，用 `import pymupdf` 非 `fitz`）；图片 → `tesseract -l chi_sim+eng`


### ⚠️ 服务重启三坑（高频）
1. **tmux server 会掉**：`tmux send-keys -t workbench` 报 `no server running`。改用 `terminal background=true` 启动服务更稳。
2. **process kill 杀不死 python 子进程**：background 启动用 `exec` 后，`process(action=kill)` 只杀 shell wrapper，python 还占着 8765 端口，新进程启动即死。**必须 `kill -9 PID` + `lsof -i :8765` 确认端口释放**，再重启。
3. **patch 大段 JS 用精确锚点**：曾因锚点 `function toggleChat() {` 不够唯一，导致函数嵌套进 toggleChat 体内。凡涉及 `tryNext();\n}` 结尾的多个函数，锚点要带函数特有代码行。


### 安全红线
- `数据/chat_history.json`、`数据/ima_pending_review.json` **禁止**进入 `cb_sync.sh`/cron 的 CloudBase 部署清单（含客户数据 + 待审核内容）


### 背景检索（2026-08-21 关键补丁）

AI 助手曾答"无法访问飞书信息"，根因是 system prompt 只注入客户名单（`_key_customers.json` 444 条），没注入活动/产品。修复：`ai_chat.py` 加 `_search_background()`，收到问题后按需检索注入：

- **活动源**：`数据/daily_activities_mcp.json`（3145 条），字段 `field_b99055`=活动描述、`field_5f20fc.label`=关联客户、`owner.name_cn`=跟进人、`start_time`=日期
- **产品源**：`数据/pricing/_all_products.json`（30711 条），`sku`→`name` 映射
- **检索逻辑**：`_extract_skus()` 提取货号（`M\d{3,4}(?:-\d+)*...`）；`_has_common_bigram()` 用"非通用 2 字公共子串"匹配客户名

**⚠️ 三个坑**：
1. **通用词必须排除**：客户名 2 字子串"公司/客户/生物/科技"等会误匹配（"公司内部资源"里的"公司"误命中所有含"公司"的客户）。`_COMMON_BIGRAM` 集合要维护。
2. **货号太热门**：M2181 等热门货号几十家客户都用，货号匹配会淹没客户名匹配。**优先级：客户名匹配(3) > 货号匹配(2) > 活动名匹配(1)**，客户名是最精准的意图信号。
3. **`_key_customers.json` 不完整**：硕世等客户在 `mcp_customers.json`（1704 条）而不在 `_key_customers.json`（444 条）。背景检索必须**直接查活动数据**（按问题关键词），不能依赖 vcust 可见客户名单。
4. **IMA 知识库检索（2026-08-22 接入）**：`ai_chat._search_knowledge_base()` 双通道——IMA `search_knowledge` 拿标题（索引层）+ 本地 `知识库-copilot/` glob 读内容（内容层）。**关键坑**：IMA `search_knowledge` 只用**单一专有名词**搜索效果好（"诺唯赞"→2条），多词空格或长句反而 **0 条**（"诺唯赞 宝锐"/完整句子→0条）。故先 `_STOP` 虚词过滤 + 按非中文切分提取 core_words，用 `core_words[0]` 搜 IMA、`core_words[:6]` glob 本地。返回结构 `data.info_list[].title`（只给标题不给内容）。另：`/api/ima` 的 `create_note` 端点与 approve 同款两个 bug（`import_doc` 路径 `openapi/v1/note` → 应 `openapi/note/v1`；返回 `note_id` 非 `doc_id`），已同步修复。





工作台右下角悬浮 🤖 气泡 → 聊天窗 → 后端 `/api/chat`（`脚本/ai_chat.py`）→ DeepSeek API。

**三条铁律**（system prompt 硬约束，`ai_chat._build_system_prompt`）：
1. 只答工作问题（客户/订单/KPI/行业/市场/竞品/方法论），家庭个人问题统一拒绝
2. 客户问题权限隔离：`_visible_for_user` 按角色过滤（admin/gm全量 → manager本部门 → sales仅自己），只注入可见客户摘要
3. 行业/市场/竞品自由回答（不注入客户数据）

**隔离数据源**：`_key_customers.json`（444条，`salesperson`字段）+ `ls_groups.json`（课题组，`sales`字段）。manager 归属用 `_personnel.json` 的 dept 推导（`_norm_dept` 归一化），生命科学区域经理按 region 浙江/广东过滤。

**前端**：`app.html` + `index.html` 同步改。`CHAT_APIS = [Funnel, localhost]` 降级链。`state.user` 传 `{name, role, dept, line}`。mdRender 轻量渲染表格/加粗/列表。


### ⚠️ DeepSeek V4 Pro 是推理模型，答案在 reasoning_content 不在 content

调 `/chat/completions` 时**必须传 `thinking: {'type': 'disabled'}`**，否则返回 `content: ''` 且答案在 `reasoning_content` 里（`completion_tokens_details.reasoning_tokens` 占满全部 token）。这是 v4-pro 与普通 chat 模型的最大区别，前端拿不到答案的根因就是它。

```python
body = {'model': cfg['model'], 'messages': [...], 'max_tokens': 2000,
        'thinking': {'type': 'disabled'}}  # ← 必须
```

## Pitfalls