第 12 章 上下文调试方法¶
上下文工程真正难的地方，不只是设计，而是调试。一个 Agent 表现不好时，团队很容易把问题归结为“模型不稳定”，但如果看不到当时的实际输入结构，就几乎不可能知道问题究竟出在什么地方。上下文调试的目标，就是把这种模糊判断变成可定位问题。
12.1 先确认实际输入¶
上下文调试的第一原则是：不要调一个你没看见的输入。很多系统日志只记录用户问题和最终输出，却不记录模型当时真正看到的完整上下文包。这样一来，所有定位都只能靠猜。
至少要能回放以下内容：
- 本轮 System Prompt 或规则片段。
- 当前任务状态摘要。
- 注入的知识或工具结果。
- 历史裁剪后的实际内容。
- 工具清单和可见权限。
只有看见真实输入，才能讨论“为什么模型没用某条信息”。
12.2 区分三类问题¶
上下文问题大致可以分成三类。
第一类是“没进来”。本该影响当前决策的信息根本没有进入输入，例如关键检索结果没被召回，或状态更新没有进入下一轮。
第二类是“进错了”。信息虽然进来了，但形式、位置、顺序或粒度不对，例如长日志原样注入、状态摘要缺乏重点、关键约束被埋在不相关文本中。
第三类是“进来了但没被用上”。这往往意味着信息竞争、规则冲突或上下文密度过高，导致模型没有稳定优先使用关键信号。
调试时必须先判断属于哪一类，否则优化动作会失焦。
12.3 建立可解释的输入结构¶
如果上下文本身是一个不可解释的大字符串，调试几乎无从下手。因此工程上最好让输入保留结构痕迹，例如明确区分：
- 规则区。
- 状态区。
- 知识区。
- 工具区。
- 历史区。
这样一来，当模型遗漏某类信息时，团队至少知道问题来自哪个输入层，而不是从整段长文本里逐字搜证。
12.4 结合输出和动作回看¶
上下文调试不应该只看输入，还要结合输出和后续动作回看。因为模型有没有真正利用某条信息，不只体现在文字回答里，也体现在：
- 是否选择了合适工具。
- 是否重复执行了已失败动作。
- 是否在证据不足时主动澄清。
- 是否在高风险阶段越过门禁。
也就是说，上下文调试最终是行为调试，而不只是文本调试。
12.5 小规模回归集¶
一旦系统进入迭代阶段，上下文装配改动就不应只靠人工感觉。最少也要有一小批高价值回归样例，覆盖：
- 规则容易被忽略的场景。
- 长历史干扰场景。
- 检索结果与状态冲突场景。
- 多工具切换场景。
这样每次调整摘要、排序或裁剪策略后，团队都能快速知道哪些行为被修复了，哪些行为被破坏了。
12.6 本章小结¶
上下文调试的关键，不是继续猜模型为什么“突然不聪明”，而是先看见真实输入，再区分问题属于“没进来”“进错了”还是“进来了但没被用上”。只有把上下文本身设计成可观察、可回放、可比较的对象，Context Engineering 才能真正进入工程闭环。
下一部分将从上下文供给继续延伸到知识系统，也就是 Agent 为什么需要 RAG，以及 RAG 在工程上究竟要解决哪些模型本身解决不了的问题。