vault: split Smart Support phases into separate files with detailed tasks

2026-03-29 21:30:09 +02:00
parent cf6e1f4be3
commit 407b455f19
6 changed files with 956 additions and 58 deletions
--- a/Projects/Smart
+++ b/Projects/Smart
@@ -0,0 +1,172 @@
+---
+created: "2026-03-29"
+type: project
+status: 未开始
+parent: "[[Smart Support]]"
+phase: 2
+timeline: "第 3-4 周"
+---
+
+# Phase 2：多 Agent + 安全
+
+## 目标
+
+让 Supervisor 具备真正的多 Agent 路由能力，能根据用户意图选择正确的 Agent。同时完善安全机制：中断超时处理、Webhook 升级通知。这个阶段结束时，系统能处理多种类型的客服请求，并在无法解决时通过 Webhook 通知人工。
+
+## 前置条件
+
+- [[Smart Support/Phase 1 - 核心框架]] 完成
+- 核心聊天闭环端到端可用
+- PostgresSaver + interrupt() 基础流程工作正常
+
+## 阶段产出
+
+- Supervisor 能准确路由不同类型的请求到对应 Agent
+- 多意图请求（「取消订单并给我折扣」）能被拆分并按序处理
+- 无法解决的问题通过 Webhook 通知人工客服
+- 过期中断自动取消并提供重试选项
+- 2-3 个垂直行业模板开箱可用
+
+## 集成检查点
+
+第 4 周末验证：
+1. 发送订单查询 → 路由到 order_lookup agent
+2. 发送「取消订单并退款」→ 按序处理两个操作
+3. 发送无法处理的请求 → Webhook POST 发出
+4. 触发确认 → 30 分钟不操作 → 自动取消 → 重新发消息收到重试提示
+5. 加载电商模板 YAML → 相关 agents 自动注册
+
+---
+
+## 任务清单
+
+### 1. 完善 Supervisor 路由
+
+- [ ] 优化 supervisor 的 agent 描述，使路由更准确
+- [ ] 多意图处理：supervisor 识别复合请求，拆分为多个子任务，按序执行
+  - 例如「取消订单 1042 并给我一个 10% 折扣码」→ 先路由到 order_actions（取消），再路由到 discount（发码）
+- [ ] 模糊/冲突意图处理：supervisor 无法判断时，返回澄清问题（「您是想查询订单还是取消订单？」）
+- [ ] 路由失败日志：每次路由记录 `{intent, selected_agent, confidence}`，为后续评估提供数据
+
+### 2. 过期中断处理
+
+- [ ] 中断触发时记录 `interrupt_timestamp` 到 graph state
+- [ ] 用户恢复对话时检查：`current_time - interrupt_timestamp > 30 min`
+- [ ] 超时行为：
+  1. 将该操作标记为已取消（不执行）
+  2. 返回消息：「您之前请求的[操作描述]已因超时取消。订单状态可能已变化，需要我重新查看吗？」
+  3. Agent 重新评估当前状态（重新调用查询工具），而不是直接重试旧操作
+- [ ] 未超时：正常恢复 interrupt 流程（approve/reject）
+
+### 3. Webhook 升级通知
+
+- [ ] 配置项：`webhook_url`（在 agents.yaml 或环境变量中配置）
+- [ ] 触发条件：
+  - Agent 明确表示无法处理（返回 escalation 标记）
+  - Supervisor 连续 3 次路由失败（用户重复同一问题）
+  - 用户主动请求人工客服
+- [ ] Webhook payload 格式：
+
+```json
+{
+  "event": "escalation",
+  "thread_id": "uuid",
+  "timestamp": "2026-04-10T14:30:00Z",
+  "reason": "agent_unable_to_resolve",
+  "conversation_summary": "客户询问关于批量退货的问题，order_lookup agent 无法找到相关功能",
+  "messages": [
+    {"role": "user", "content": "..."},
+    {"role": "assistant", "content": "..."}
+  ],
+  "customer_context": {
+    "resolved_entities": {"order_id": "1042"}
+  }
+}
+```
+
+- [ ] HTTP POST 发送，设置 10 秒 timeout
+- [ ] 失败重试：最多 3 次，指数退避（1s, 2s, 4s）
+- [ ] 重试全部失败 → 记录日志（ERROR 级别），不阻塞聊天流程
+- [ ] 在聊天 UI 中通知用户：「已通知人工客服，他们会尽快联系您」
+
+### 4. 垂直行业模板
+
+- [ ] 创建模板目录 `backend/templates/`
+- [ ] 电商模板 `ecommerce.yaml`：
+
+```yaml
+name: ecommerce
+description: 电商客服模板 - 订单管理、物流查询、退换货
+agents:
+  - name: order_lookup
+    description: 查询订单状态、物流跟踪、收货确认
+    permission: read
+    personality:
+      tone: professional
+      greeting: "您好！我可以帮您查询订单相关信息。"
+    tools: [get_order, get_tracking, list_orders]
+
+  - name: order_actions
+    description: 取消订单、修改地址、申请退换货
+    permission: write
+    personality:
+      tone: careful
+      greeting: "我可以帮您处理订单变更，所有操作都会先确认。"
+    tools: [cancel_order, modify_address, request_return]
+
+  - name: promotions
+    description: 查询优惠活动、发放折扣码
+    permission: write
+    personality:
+      tone: enthusiastic
+    tools: [apply_discount, check_promotions]
+```
+
+- [ ] SaaS 模板 `saas.yaml`：账号管理、订阅变更、功能咨询
+- [ ] 金融科技模板 `fintech.yaml`：账户查询、交易记录、转账操作
+- [ ] 模板加载机制：启动时指定 `--template ecommerce` 或在配置中设置 `template: ecommerce`
+- [ ] 模板与自定义 agents.yaml 合并：模板提供默认值，自定义配置覆盖
+
+### 5. 新增演示 Agent
+
+在 Phase 1 的基础上增加写操作 Agent：
+
+- [ ] `order_actions` agent：取消订单（`cancel_order`）、修改地址（`modify_address`）
+- [ ] `discount` agent：发放优惠券（`apply_discount`）、生成折扣码（`generate_coupon`）
+- [ ] 所有写操作工具标记 `permission: write` → 自动触发 interrupt
+
+### 6. 测试
+
+- [ ] **路由测试：** 「查询订单」→ order_lookup，「取消订单」→ order_actions，「给我折扣」→ discount
+- [ ] **路由测试：** 模糊请求 → 返回澄清问题
+- [ ] **多意图测试：** 「取消订单并退款」→ 按序执行两个操作
+- [ ] **超时测试：** interrupt 后 mock 时间超过 30 分钟 → 自动取消 + 重试提示
+- [ ] **超时测试：** interrupt 后 mock 时间未超过 30 分钟 → 正常 approve/reject
+- [ ] **Webhook 测试：** 升级触发 → HTTP POST 发出，payload 格式正确
+- [ ] **Webhook 测试：** 目标 URL 不可达 → 重试 3 次 → 记录日志 → 聊天不中断
+- [ ] **模板测试：** 加载电商模板 → agents 正确注册
+- [ ] **模板测试：** 自定义配置覆盖模板默认值
+- [ ] **E2E 测试：** 完整升级流程（无法处理 → webhook 发出 → 用户收到通知）
+
+## 技术要点
+
+| 功能 | 实现方式 |
+|------|---------|
+| 多意图拆分 | Supervisor LLM 识别并按序调度 |
+| 超时检测 | graph state 记录 timestamp，resume 时比较 |
+| Webhook | httpx.AsyncClient POST，asyncio 重试 |
+| 模板加载 | PyYAML 加载 + 与自定义 YAML 深度合并 |
+
+## 风险与缓解
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| 多意图拆分不准确 | 操作顺序错误或遗漏 | 先处理常见组合，复杂情况要求用户分步操作 |
+| Webhook 目标服务不稳定 | 升级通知丢失 | 重试 + 日志 + 聊天内告知用户 |
+| 超时时间 30 分钟不合适 | 过早或过晚取消 | 配置化，允许每个 agent 自定义 TTL |
+
+## Related
+
+- [[Smart Support/Phase 1 - 核心框架]]
+- [[Smart Support/Phase 3 - OpenAPI 自动发现]]
+- [[Smart Support]]