调试与错误处理
先判 integration layer 还是 model output，再选恢复策略

TS 4.1 不奖励「看到 exception 就重试」。它考的是从 trace 识别错误类型、隔离失败源头，再把代码／配置／网络问题与 prompt／schema／输出校验问题交给不同修复路径。

一、第一刀：这次调用有没有形成完整 Message

诊断从证据边界开始，而不是从异常栈最末一行开始。先找 HTTP status、SDK exception、SSE event 与最终 Message：请求若在认证、权限、payload、rate limit、网络或服务端处理阶段失败，源头在 integration layer（集成层）；API 若已经返回成功的 Message，再看 stop_reason 与 content，才能判断是正常完成、截断、工具交接，还是 model output（模型输出）不满足业务契约。

二、错误名决定恢复；stop_reason 决定下一步

API 错误 body 是 JSON：顶层 error 对象含 type 与 message，另有 request_id；每个响应也有唯一 request-id header。把这些字段写进 trace，才能按类型聚合，而不是 string-match 一段会变化的自然语言错误。

官方 SDK 会对 connection errors、rate limits 与 5xx 等瞬时失败用 exponential backoff 自动重试，默认两次，并在存在时遵守 retry-after。Trace 因此要记录 attempt：否则你会把「SDK 已重试三次总尝试」误读为三位用户各发了一次，或在外层再套无界重试。

三、让 trace 能分堆，而不是只会报一个 “parse_error”

最小可用 trace 至少保留：request_id、attempt、elapsed_ms、HTTP status / SDK exception、最后一个 SSE event、stop_reason、content block types、tool / permission stage，以及独立的 validation result。关键是不要把上游事实覆盖成下游症状：

{"req":"req_A","attempt":2,"http":529,"error":"overloaded_error","message":null}
{"req":"req_B","http":200,"stop_reason":"max_tokens","validation":"truncated_json"}
{"req":"req_C","http":200,"stop_reason":"end_turn","validation":"missing:currency"}

Streaming 更要保留层级：SSE event stream 可能出现 event: error，而正常 flow 以 final message_stop 收口；收到 partial blocks 甚至 HTTP 200 都不能覆盖后续 error event。Claude 4.6 及之后如因 network / timeout 中断，可保存已收 text，再以 user message 携带 partial response 并要求继续；partial tool use 与 thinking block 不能这样恢复。没有 message_stop 的 partial text 不能直接当完整 model output 入库。

Claude Code 的 permission path 也是 integration/control plane 的子层：auto mode classifier 在 permissions system 之后运行；managed permissions.deny 会在 classifier 被咨询前阻断且不可覆盖。Trace 若写着 deny_match=true、classifier_invoked=false、tool_started=false，应修 permission 配置或应用的状态传播，不能靠改 prompt 让被 deny 的动作“更可信”。

本章题组