「手写中文版 claude code」教学系列：codeAgent 是我从零手写的 claude code 复刻——不套壳不翻译，从界面到 Agent 主循环一行行实现，注释全是中文大白话，适合当 Agent 开发教材从头读到尾。
上一课解决了"合并着端回去"；这一课处理端回去之前的对账——压缩和裁剪会把「调用↔结果」拆散，拆散了就是 400。
仓库：https://github.com/Harvil1/codeAgent
什么叫孤儿 tool_call
协议要求严格配对：assistant 发出的每个工具调用（tool_calls 里的 id），后面必须跟着同 id 的工具结果；反过来，工具结果前面必须有发起它的调用。
压缩、裁剪、恢复会话——任何从中间动消息的操作，都可能把一对搭档切成两半：
- 正向孤儿：调用了，结果没了（被裁掉）
- 反向孤儿：结果还在，发起它的调用被裁了
两种都让 API 直接 400，报错信息还不直说是配对问题。
对账函数（源码）
agent/context_compressor.py：
def _fix_tool_call_pairs(messages: list) -> list:
"""修复压缩切坏了的「工具调用 ↔ 工具结果」配对。
处理两类问题：
- 正向孤儿（调用了但没结果）：在 assistant(tool_calls) 后面的结果序列末尾
补一条假结果（内容注明「因压缩丢失」）。⚠️ 位置必须紧贴结果序列末尾，
**不能**补到整个消息列表最后——中间隔了别的消息照样违反「紧跟其后」
（Anthropic 查得最严），还是 400
- 反向孤儿（有结果但前面没发起它的调用）：直接删掉
（压缩边界或上游 bug 都可能造出这种孤儿）
"""
# 反向孤儿按「截至当前位置见过哪些 id」判断（逐步累加）；
# 用全量集合会漏判错序——结果 B 出现在发起 B 的调用之前也会放行
# （B 已在全量集合里），导致 API 400。
seen_so_far = set()
...
这个函数在我项目里是压缩流水线的固定收尾动作——七层压缩不管哪层动了刀（昨天第 3 篇的 compress_if_needed），最后统一过一遍对账。紧急压缩（第 2 篇的 reactive_compact）砍完消息也调它。
注释里藏的两个深坑
坑一：补假结果的位置。 正向孤儿补结果，直觉是补到消息列表末尾——错。协议要求结果紧跟 assistant 的调用序列，中间隔了别的消息照样 400。必须紧贴该轮结果序列的末尾补。
坑二：判断反向孤儿不能用全量集合。 我一开始的写法是先收集全部 tool_call id 再查结果——会漏判"结果出现在发起它的调用之前"这种错序（全量集合里已经有这个 id，检查放行，实际顺序是非法的）。正确做法是逐步累加的 seen_so_far：走到哪查到哪，错序当场现形。
设计启示
把它做成独立纯函数 + 流水线固定收尾，而不是散在各处打补丁，好处是：任何新加的"动消息"操作（未来的压缩层、会话编辑功能）自动获得对账保护，忘了调用手动刀的风险归零。
小结
- 动历史必产生孤儿配对，孤儿必 400——对账是压缩的标配收尾
- 补结果的位置要紧贴调用序列；判孤儿要用增量集合防错序漏判
- 收尾动作做成统一纯函数，新操作自动继承保护
下一篇：数硬币别占收银台——asyncio 的 to_thread 与 contextvars 一坑两命。
仓库在这，注释全中文，欢迎 Star ⭐：https://github.com/Harvil1/codeAgent
标签：Python asyncio Agent 大模型API
