模块 3 动手实验 — Claude API 实战

Lab 3.1–3.4 无需 key；Lab 3.5 可选需 key。预计 75–100 分钟。

Lab 3.1 — 错误分类与退避策略（必做，无 key）

任务：运行并改造 examples/retry_backoff.py：

跑通五个场景，对照官方错误表逐条核对分类（来源: https://platform.claude.com/docs/en/api/errors（访问于 2026-08-30））。
把 504 timeout_error 的分类从"不可重试"改为"可重试 1 次"——思考官方为什么建议 504 换 streaming/Batches 而非重试（提示：同样的输入再跑 10 分钟）。
给场景 2 增加"连续 3 次 429 且 retry-after 递增"的注入，观察服从策略。
回答：为什么 jitter 对多实例部署尤其重要？

验收：能画出自己的重试决策树（错误类型 × retry-after × 预算三层）。

任务：扩展 examples/api_walkthrough.py 的校验器：

增加规则：messages 超过 100,000 条报错；system 为 list 时校验每个 block 的 type。
构造一个"缓存自杀"请求：system 尾部放 "当前时间: 2026-08-30 20:00" 且断点在它之后——写一段注释解释为什么这个请求永远 cache miss（对照 README §8.2 的 hash 机制）。
把批处理请求扩到 3 项：一项合法、一项 custom_id 带 /、一项 params 里塞 stream: true，验证三条错误都抓到。

验收：校验器输出与官方 Batches 限制表一一对应（来源: https://platform.claude.com/docs/en/build-with-claude/batch-processing（访问于 2026-08-30））。

任务：某评估任务 10,000 次/晚，输入 8,000 token（其中 7,500 为共享评估说明，稳定）、输出 1,000 token，Sonnet 5（$2/$10）。

同步无缓存成本 = ?（提示：输入 8K×$2/1M×10K 次 + 输出 1K×$10/1M×10K 次）
同步 + 前缀缓存（命中 7,500，读 0.1x）= ?
Batch（整体 5 折）+ 1h 缓存写入 1.25x = ?
结论：三种方案各适合什么场景？注意 Batch 内缓存读也打 5 折吗？（查官方 pricing 表脚注："These multipliers stack with other pricing modifiers such as the Batch API discount"——来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching（访问于 2026-08-30））

验收：算出三档成本并解释 stacking 规则。

任务：设计你的调用日志 schema，至少包含：request_id、model、usage 四字段、stop_reason、耗时（TTFT/总时长分开）、缓存命中数、重试次数、错误 type。回答：

哪些字段直接来自响应/响应头？（来源: https://platform.claude.com/docs/en/api/errors（访问于 2026-08-30））
"input_tokens 突涨 10 倍"的告警对应哪两类事故？（缓存失效 / 上下文注入膨胀）
为什么 spend-cap 429 要与普通 429 分开告警？

任务：python3 examples/api_walkthrough.py --live（key 从环境变量注入）：

记录 usage 与 request-id。
同一请求再发一次，对比 cache_read_input_tokens（若未达最小可缓存长度——Sonnet 5 为 1,024 token——则双字段为 0，正好验证"静默不缓存"）。
把 model 改成不存在的 ID，观察 404 not_found_error 的 JSON 错误体结构。