vault backup: 2026-04-06 16:23:54

2 - Projects/Smart Support/Phase 2 - 多 Agent + 安全.md

@@ -1,7 +1,8 @@
 ---
 created: 2026-03-29
+updated: 2026-04-06
 type: project
-status: 未开始
+status: COMPLETED (2026-03-30)
 parent: "[[Smart Support]]"
 phase: 2
 timeline: 第 3-4 周
@@ -20,161 +21,51 @@ tags:
 
 # Phase 2：多 Agent + 安全
 
+> Status: COMPLETED (2026-03-30)
+
 ## 目标
 
-让 Supervisor 具备真正的多 Agent 路由能力，能根据用户意图选择正确的 Agent。同时完善安全机制：中断超时处理、Webhook 升级通知。这个阶段结束时，系统能处理多种类型的客服请求，并在无法解决时通过 Webhook 通知人工。
-
-## 前置条件
-
-- [[Smart Support/Phase 1 - 核心框架]] 完成
-- 核心聊天闭环端到端可用
-- PostgresSaver + interrupt() 基础流程工作正常
+让 Supervisor 具备真正的多 Agent 路由能力，能根据用户意图选择正确的 Agent。同时完善安全机制：中断超时处理、Webhook 升级通知。
 
 ## 阶段产出
 
-- Supervisor 能准确路由不同类型的请求到对应 Agent
-- 多意图请求（「取消订单并给我折扣」）能被拆分并按序处理
-- 无法解决的问题通过 Webhook 通知人工客服
-- 过期中断自动取消并提供重试选项
-- 2-3 个垂直行业模板开箱可用
+- Intent 分类器：LLM 结构化输出，支持单意图/多意图/模糊检测
+- Discount Agent：apply_discount（write + interrupt）+ generate_coupon（read）
+- 中断管理器：30 分钟 TTL 自动过期，register/check/resolve/cleanup
+- Webhook 升级：HTTP POST + 指数退避重试（最多 3 次）
+- 增强 Supervisor 路由：动态 Agent 描述、多意图提示注入
+- 垂直行业模板：电商、SaaS、金融科技
+- 模板加载：load_template() / list_templates()
 
-## 集成检查点
+## 新增文件
 
-第 4 周末验证：
-1. 发送订单查询 → 路由到 order_lookup agent
-2. 发送「取消订单并退款」→ 按序处理两个操作
-3. 发送无法处理的请求 → Webhook POST 发出
-4. 触发确认 → 30 分钟不操作 → 自动取消 → 重新发消息收到重试提示
-5. 加载电商模板 YAML → 相关 agents 自动注册
+| 文件 | 用途 |
+|------|------|
+| `app/intent.py` | 意图分类模型 + LLM 分类器 |
+| `app/agents/discount.py` | 折扣 Agent 工具 |
+| `app/interrupt_manager.py` | 中断 TTL 管理 |
+| `app/escalation.py` | Webhook 升级 + 重试 |
+| `templates/e-commerce.yaml` | 电商模板 |
+| `templates/saas.yaml` | SaaS 模板 |
+| `templates/fintech.yaml` | 金融科技模板 |
 
----
+## 测试覆盖
 
-## 任务清单
+- 总测试：153（Phase 1: 87 + Phase 2: 66）
+- 覆盖率：90.18%
+- 新模块覆盖：intent 100%, discount 96%, interrupt_manager 100%, escalation 100%
 
-### 1. 完善 Supervisor 路由
+## 与计划的偏差
 
-- [ ] 优化 supervisor 的 agent 描述，使路由更准确
-- [ ] 多意图处理：supervisor 识别复合请求，拆分为多个子任务，按序执行
-  - 例如「取消订单 1042 并给我一个 10% 折扣码」→ 先路由到 order_actions（取消），再路由到 discount（发码）
-- [ ] 模糊/冲突意图处理：supervisor 无法判断时，返回澄清问题（「您是想查询订单还是取消订单？」）
-- [ ] 路由失败日志：每次路由记录 `{intent, selected_agent, confidence}`，为后续评估提供数据
+- 多意图处理用 Supervisor 提示注入而非自定义预路由节点（更简单）
+- Webhook 升级已接入 app.state 但未连接到具体 Agent 工具（模块就绪，集成推迟）
+- `escalate_to_human` 工具未创建（升级模块可独立触发）
 
-### 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 |
+- SaaS/Fintech 模板工具名称无实现（配置蓝图）
+- 中断清理未定时调度
+- main.py 覆盖率 44%（需真实 DB）
 
 ## Related