# 2026-06-04 工作日志

## AI Wingman 坐席智能辅助设计（调研+方案+文档化）

### 背景
用户提出设计逻辑：IT智能咨询不仅要帮助员工，也要帮助坐席人员摆脱机械重复工作和情绪消耗。基于此进行了行业调研和方案设计。

### 行业调研
调研了 7 家主流解决方案：
- NiCE Copilot — 实时辅导+情绪分析+自动摘要
- Helpshift AI Copilot — 情绪推送+建议回复+自动化
- Zendesk Agent Assist — 知识推荐+工单自动化
- 天润融通 — 智能填单（1分钟→10秒）、话术推荐
- 循环智能 — 流程引导+SOP导航（新人上手-50%）
- 合力亿捷 — 自动摘要（70%文书时间节省）
- Assembled — 7种copilot功能对比

### 设计方案
- **三层架构**：效率层（消灭重复）/ 认知层（降低认知负荷）/ 情感层（减少情绪消耗）
- **5大设计原则**：非侵入式、坐席主导、反馈闭环、上下文继承、渐进式赋能
- **双区布局**：内嵌区（AI草稿回复）+ 侧栏区（摘要/标签/知识推荐）
- **底层实现**：扩展现有Dify，新增坐席端Wingman Agent（与员工端Agent共用知识库）

### 用户确认的方案选择
1. **实施阶段**：全部都要，但先做MVP（Phase 1 效率层）
2. **AI方案**：扩展现有Dify（新增assistant类型Agent）
3. **呈现方式**：针对性回复内嵌、通用功能侧栏

### 文档更新
- **PRD.md**：新增 §14 AI Wingman 坐席智能辅助（设计理念/行业验证/用户故事/实施方案/需求池）
- **ARCHITECTURE.md**：新增 §1.2.2 坐席端AI Wingman智能辅助架构（双区布局+三层架构+AI Agent架构）
- **团队沟通文档**：新增 §4.6 AI Wingman坐席端智能辅助（三层渐进式+双区布局+实现方案）

## 共享基础设施修复（续昨日）

### 已完成（含今日）
- ✅ Task 7: 坐席登录安全加固（企微通讯录验证）
- ✅ Task 9: 启动时配置占位符校验
- ✅ Message模型扩展（media_id等5个字段 + Alembic迁移）
- ✅ Task 1: 修复H5端AI降级回复误计数 — 降级/打招呼/呼叫人工均不计数，仅AI命中+1
- ✅ Task 2: 统一AI调用逻辑 — 新建 ai_handler.py（AIHandler），h5.py和message_router.py共用
- ✅ Task 3: 修复资源泄漏 — 新建 dependencies.py（共享服务DI），callback/h5不再手动创建实例
- 🔧 主理人补修：main.py 接入 init_shared_services()/cleanup_shared_services()

### 关键文件变更
| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `backend/app/services/ai_handler.py` | **新建** | 统一AI处理器：打招呼/呼叫人工/AI调用/计数/转人工 |
| `backend/app/dependencies.py` | **新建** | 共享服务DI管理：Redis/AIService/WecomService/AIHandler |
| `backend/app/services/message_router.py` | 重构 | 替换 ai_service → ai_handler，计数逻辑统一 |
| `backend/app/api/h5.py` | 重构 | 移除本地AI逻辑/Redis管理，全面改用AIHandler+DI |
| `backend/app/api/wecom_callback.py` | 重构 | 移除手动创建服务，改用 get_shared_*() |
| `backend/app/main.py` | 修改 | lifespan接入共享服务初始化/清理 |

### 待处理
- Task 4: 非文本消息处理（图片/文件/语音）
- Task 5: 消息去重（MsgId检查）
- Task 6: ScoringService硬编码关键词修复
- Task 8: 状态机校验补全
- Task 10: 回调事件处理业务逻辑
- Task 11: QA验证

## AI Wingman Phase 1 代码实现（完成 ✅）

### 后端
- `backend/app/services/wingman_service.py` — **新建** WingmanService：`generate_draft()` / `generate_summary()` / `suggest_tags()`，含 JSON 解析、置信度估算、API 降级处理
- `backend/app/api/wingman.py` — **新建** 3个API端点：`/api/conversations/{id}/wingman/draft|summary|tags`
- `backend/app/config.py` — 新增 `dify_wingman_api_url` / `dify_wingman_api_key` / `dify_wingman_timeout` 配置项

### 后端测试
- `backend/tests/test_wingman_service.py` — 32 个单元测试（消息映射/JSON解析/置信度/降级/初始化）
- `backend/tests/test_wingman.py` — 12 个 API 端点测试（正常路径/认证/404/降级）
- **44/44 全部通过** ✅

### 前端
- `frontend-agent/src/api/wingman.ts` — Wingman API 调用封装
- 坐席端双区布局（内嵌AI草稿 + 侧栏摘要/标签）

### QA 验证
- 严过关请求因 DNS 解析不到 `copilot.tencent.com` 报错，非代码质量问题
- 本地跑全部 44 个测试通过，确认功能正常