> 「手写中文版 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`：

```python
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`：走到哪查到哪，错序当场现形。

## 设计启示

把它做成**独立纯函数 + 流水线固定收尾**，而不是散在各处打补丁，好处是：任何新加的"动消息"操作（未来的压缩层、会话编辑功能）自动获得对账保护，忘了调用手动刀的风险归零。

## 小结

1. 动历史必产生孤儿配对，孤儿必 400——对账是压缩的标配收尾
2. 补结果的**位置**要紧贴调用序列；判孤儿要用**增量集合**防错序漏判
3. 收尾动作做成统一纯函数，新操作自动继承保护

下一篇：**数硬币别占收银台——asyncio 的 to_thread 与 contextvars 一坑两命**。

---

仓库在这，注释全中文，欢迎 Star ⭐：https://github.com/Harvil1/codeAgent

**标签**：`Python` `asyncio` `Agent` `大模型API`

「手写中文版 claude code」教学系列：codeAgent 是我从零手写的 claude code 复刻——不套壳不翻译，从界面到 Agent 主循环一行行实现，注释全是中文大白话，适合当 Agent 开发教材从头读到尾。 上一课解决了"合并着端回去"；这一课处理端回去之前的对账——压缩和裁剪会把「调用↔结果」拆散，拆散了就是 400。 仓库：https://github.com/Harvil1/codeAgent

孤儿 tool_call：对账补漏

上下文压缩从中间裁消息，很容易把「工具调用↔工具结果」拆散——孤儿 tool_call 让下一次请求直接 400。本文附 codeAgent 真实源码 _fix_tool_call_pairs：正向孤儿紧贴结果序列末尾补假结果，位置差一条都不行；反向孤儿直接删；判断用逐步累加的 seen 集合防错序漏判。压缩每动一次刀，对账必须跟一次。

编程语言

人工智能

架构设计

本文深入解析手写中文版Claude Code的Agent开发教学，聚焦工具调用与结果配对的对账机制。通过修复压缩造成的孤儿tool_call问题，阐述协议严格配对要求及正向/反向孤儿的处理策略，提供增量集合防错序的实用技巧，并强调独立纯函数设计的复用价值，适合Agent开发者学习。

代码解释

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

孤儿 tool_call：对账补漏-腾讯云开发者社区-腾讯云

孤儿 tool_call：对账补漏

孤儿 tool_call：对账补漏

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐