ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter5/log-diagnosis/data/PRD.md

@@ -0,0 +1,15 @@
+# 产品需求文档（PRD，精简版）—— 订单退款 Agent
+
+## R1 退款合规校验（P0）
+发起任何退款（`process_refund`）之前，**必须**先调用 `verify_refund_eligibility` 完成退款资格校验。
+未校验直接退款属于严重合规/资损风险，禁止出现。
+
+## R2 支付重试与上报（P0）
+`process_refund` 调用第三方支付网关。网关偶发失败时，系统应带退避重试；
+若最终仍失败，必须将任务标记为 `failed` 并通知用户，**不得**在多次失败后静默结束或误报成功。
+
+## R3 库存查询延迟（P1）
+`check_stock` 单次调用延迟必须小于 **5000ms**。超过阈值应触发降级（返回缓存或"库存查询繁忙"提示），不得让用户长时间等待。
+
+## R4 结果通知（P2）
+任务结束（成功或失败）都应通过 `notification_service.notify_user` 通知用户最终结果。

chapter5/log-diagnosis/data/architecture.md

@@ -0,0 +1,28 @@
+# 订单退款 Agent 系统架构
+
+本系统是一个电商客服场景下的多模块 Agent，负责处理用户的订单查询与退款请求。
+
+## 模块划分
+
+- **intent_parser（意图识别）**：解析用户自然语言，判断意图（`refund` / `order_status` / `chitchat`），抽取订单号等实体。
+- **order_service（订单服务）**：负责订单相关的读写。
+  - 工具 `query_order(order_id)`：查询订单状态与金额。
+  - 工具 `verify_refund_eligibility(order_id)`：校验订单是否满足退款条件（是否已支付、是否在退款时限内、是否已退过款）。**退款流程中此步骤为强制前置校验。**
+- **payment_service（支付服务）**：对接第三方支付网关。
+  - 工具 `process_refund(order_id, amount)`：发起退款。第三方网关偶发不稳定，要求实现**重试 + 退避**并在最终失败时上报，不得静默丢弃。
+- **inventory_service（库存服务）**：查询与回补库存。
+  - 工具 `check_stock(sku)`：查询库存。**要求单次调用延迟不超过 5000ms**，超时应走降级路径而非阻塞主流程。
+- **notification_service（通知服务）**：向用户发送结果通知。
+
+## 关键调用链（退款）
+
+```
+user -> intent_parser -> order_service.query_order
+      -> order_service.verify_refund_eligibility   # 强制前置校验
+      -> payment_service.process_refund            # 需重试+退避
+      -> notification_service.notify_user
+```
+
+## 可观测性
+
+系统为每次任务落一条 trajectory（轨迹）日志，记录每一交互轮次（turn）的模块、工具、输入输出、状态与延迟（latency_ms）。轨迹用于线上问题诊断与回归测试重放。

chapter5/log-diagnosis/data/trajectories.jsonl

@@ -0,0 +1,4 @@
+{"trajectory_id": "T-1001", "task": "用户要求对订单 A1001 退款", "task_input": {"intent": "refund", "order_id": "A1001", "order_status": "paid", "payment_flaky": false, "slow_inventory": false}, "final_status": "success", "turns": [{"index": 0, "role": "user", "content": "我要退款，订单号 A1001"}, {"index": 1, "role": "assistant", "module": "intent_parser", "content": "意图=refund, order_id=A1001"}, {"index": 2, "role": "tool", "module": "order_service", "tool": "query_order", "input": {"order_id": "A1001"}, "output": {"status": "paid", "amount": 199}, "status": "success", "latency_ms": 210}, {"index": 3, "role": "assistant", "module": "order_service", "content": "订单已支付，直接发起退款", "note": "未调用 verify_refund_eligibility"}, {"index": 4, "role": "tool", "module": "payment_service", "tool": "process_refund", "input": {"order_id": "A1001", "amount": 199}, "output": {"refund_id": "R-9001"}, "status": "success", "latency_ms": 540}, {"index": 5, "role": "tool", "module": "notification_service", "tool": "notify_user", "input": {"msg": "退款成功"}, "output": {"sent": true}, "status": "success", "latency_ms": 60}]}
+{"trajectory_id": "T-1002", "task": "用户要求对订单 A1002 退款", "task_input": {"intent": "refund", "order_id": "A1002", "order_status": "paid", "payment_flaky": true, "slow_inventory": false}, "final_status": "success", "turns": [{"index": 0, "role": "user", "content": "订单 A1002 退款"}, {"index": 1, "role": "assistant", "module": "intent_parser", "content": "意图=refund, order_id=A1002"}, {"index": 2, "role": "tool", "module": "order_service", "tool": "query_order", "input": {"order_id": "A1002"}, "output": {"status": "paid", "amount": 88}, "status": "success", "latency_ms": 230}, {"index": 3, "role": "assistant", "module": "order_service", "content": "订单已支付，直接发起退款", "note": "未调用 verify_refund_eligibility"}, {"index": 4, "role": "tool", "module": "payment_service", "tool": "process_refund", "input": {"order_id": "A1002", "amount": 88}, "output": {"error": "gateway_timeout"}, "status": "error", "latency_ms": 3010}, {"index": 5, "role": "tool", "module": "payment_service", "tool": "process_refund", "input": {"order_id": "A1002", "amount": 88}, "output": {"error": "gateway_timeout"}, "status": "error", "latency_ms": 3005}, {"index": 6, "role": "tool", "module": "payment_service", "tool": "process_refund", "input": {"order_id": "A1002", "amount": 88}, "output": {"error": "gateway_timeout"}, "status": "error", "latency_ms": 3020}, {"index": 7, "role": "assistant", "module": "payment_service", "content": "重试多次失败，按成功结束", "note": "无退避；最终误报成功"}, {"index": 8, "role": "tool", "module": "notification_service", "tool": "notify_user", "input": {"msg": "退款成功"}, "output": {"sent": true}, "status": "success", "latency_ms": 55}]}
+{"trajectory_id": "T-1003", "task": "用户查询订单 A1003 的库存/发货状态", "task_input": {"intent": "order_status", "order_id": "A1003", "sku": "SKU-77", "payment_flaky": false, "slow_inventory": true}, "final_status": "success", "turns": [{"index": 0, "role": "user", "content": "A1003 还有货吗，什么时候发"}, {"index": 1, "role": "assistant", "module": "intent_parser", "content": "意图=order_status, order_id=A1003"}, {"index": 2, "role": "tool", "module": "order_service", "tool": "query_order", "input": {"order_id": "A1003"}, "output": {"status": "paid", "sku": "SKU-77"}, "status": "success", "latency_ms": 240}, {"index": 3, "role": "tool", "module": "inventory_service", "tool": "check_stock", "input": {"sku": "SKU-77"}, "output": {"stock": 12}, "status": "success", "latency_ms": 8300, "note": "延迟超过 5000ms 阈值，未降级"}, {"index": 4, "role": "tool", "module": "notification_service", "tool": "notify_user", "input": {"msg": "有货，1天内发货"}, "output": {"sent": true}, "status": "success", "latency_ms": 70}]}
+{"trajectory_id": "T-1004", "task": "用户查询订单 A1004 状态（正常轨迹，对照组）", "task_input": {"intent": "order_status", "order_id": "A1004", "sku": "SKU-12", "payment_flaky": false, "slow_inventory": false}, "final_status": "success", "turns": [{"index": 0, "role": "user", "content": "A1004 到哪了"}, {"index": 1, "role": "assistant", "module": "intent_parser", "content": "意图=order_status, order_id=A1004"}, {"index": 2, "role": "tool", "module": "order_service", "tool": "query_order", "input": {"order_id": "A1004"}, "output": {"status": "shipped", "sku": "SKU-12"}, "status": "success", "latency_ms": 200}, {"index": 3, "role": "tool", "module": "inventory_service", "tool": "check_stock", "input": {"sku": "SKU-12"}, "output": {"stock": 5}, "status": "success", "latency_ms": 300}, {"index": 4, "role": "tool", "module": "notification_service", "tool": "notify_user", "input": {"msg": "已发货"}, "output": {"sent": true}, "status": "success", "latency_ms": 65}]}