参考资料

• OpenAI Agents SDK
• OWASP Agentic Security

Harness Engineering（06） - 上下文管理与 Token 预算

读完后，你应能完成以下任务：

• 绘制“Harness Engineering（06） - 上下文管理与 Token 预算 / 先搞懂：Context Window 是什么，为什么会满”的关键对象与数据流，解释“每个模型一次能"看"的文字量是有上限的，”，并用源码位置、日志或 Trace 标注证据。
• 为“Harness Engineering（06） - 上下文管理与 Token 预算 / 四种武器：截断、摘要、压缩、外置”设计正常与异常输入，验证“这正是本 harness 在对话变长时做的事——"压缩（compaction）"。”，输出首个偏差位置与回归测试结果。
• 实现“Harness Engineering（06） - 上下文管理与 Token 预算 / 武器 1：截断（Truncation）—— 简单粗暴”的最小代码或配置，检验“直接砍掉最老的对话，只保留最近 N 条。”，输出命令、结果与 Diff，并说明不适用边界。

还记得第 01 章那句话吗——"模型每次调用都是失忆的，它之所以记得，是因为 harness 每次都把历史重新塞给它看"。 问题来了：对话越来越长，这个"历史"越塞越大，迟早会超过模型一次能读的上限。这一章就讲 harness 怎么应对这个绕不开的难题。

---

一、先建立全局：上下文管理与 Token 预算 是什么？

理解“上下文管理与 Token 预算”，先要把标题中的对象放进同一条处理链：它接收什么输入，经过哪些状态变化，最终用什么证据判断结果。下表不另造概念，只把作者正文已经解释的章节按依赖顺序连起来。

“上下文管理与 Token 预算”的第一个核心判断是：每个模型一次能"看"的文字量是有上限的，。先弄清这个判断中的对象和输入输出，后面的实现、故障和验收才有共同语境。

顺序	章节	读完本节应抓住的结论
1	先搞懂：Context Window 是什么，为什么会满	每个模型一次能"看"的文字量是有上限的，
2	四种武器：截断、摘要、压缩、外置	这正是本 harness 在对话变长时做的事——"压缩（compaction）"。
3	组合拳：真实 harness 是怎么做的	窗口是稀缺资源，只放"现在必须看的"；
4	一个常被忽略的点：上下文质量 > 上下文数量	失败的、已被纠正的尝试，没必要一直留着。
5	常见误区	长对话必须主动管理上下文。
6	最佳实践	✅ 给每条工具结果设长度上限，从源头防止单条内容撑爆窗口。

1.1 核心对象之间怎样衔接

flowchart LR
  S1["先搞懂：Context Window 是什么，为什么会满"] --> S2
  S2["四种武器：截断、摘要、压缩、外置"] --> S3
  S3["组合拳：真实 harness 是怎么做的"] --> S4
  S4["一个常被忽略的点：上下文质量 > 上下文数量"] --> S5
  S5["常见误区"]

这张图只表达本文的讲解顺序，不替代正文机制。判断“上下文管理与 Token 预算”是否真正掌握，需要能从最后一个结果沿图回到前面每个章节的输入、状态变化和证据。

1.2 再看失败：问题最早会出现在哪一步？

在“上下文管理与 Token 预算”的对象和顺序已经明确后，再看可观察的失败：只看均值、耗时未分段或吞吐以正确率为代价。定位时不从最后一条错误猜原因，而是沿上图找第一个偏离正文结论的节点。

二、先搞懂：Context Window 是什么，为什么会满

每个模型一次能"看"的文字量是有上限的， 这个上限叫 Context Window（上下文窗口）， 用 token 衡量（1 token 约等于半个汉字或 0.75 个英文单词）。

关键认知：

每一轮对话，harness 都要把"从头到现在的所有内容"重新打包发给模型。 包括：system prompt + 全部历史对话 + 所有工具调用和结果 + 这次的新输入。

所以一个干活的 Agent，上下文涨得特别快：

读了一个 500 行的文件        → +几千 token
执行了一条命令、拿到一屏输出  → +几百 token
来回对话十几轮              → 累积几万 token
...

转着转着，"历史"就把窗口塞满了。 塞满会怎样？ 要么 API 直接报错拒绝，要么模型"看不全"早期内容——它会忘掉对话开头说过的话。 这就是为什么长对话里 Agent 有时会"失忆"。

---

三、四种武器：截断、摘要、压缩、外置

应对"装不下"，harness 有四种常见手段，从糙到精：

3.1 武器 1：截断（Truncation）—— 简单粗暴

直接砍掉最老的对话，只保留最近 N 条。

• 优点：实现极简，几行代码。
• 缺点：被砍掉的信息彻底丢失。如果开头有重要约定（"全程用中文"），砍了就忘了。
• 适用：闲聊类、上下文关联不强的场景。

3.2 武器 2：摘要 / 压缩（Summarization / Compaction）—— 聪明但有成本

当上下文快满时，让模型自己把前面一大段对话浓缩成一段摘要，用摘要替换掉原文。

• 优点：保留了关键信息（摘要里有"用户要求用中文""已经修改了 a.py"），又大幅省空间。
• 缺点：摘要会丢细节；而且生成摘要本身要额外调一次模型，有成本和延迟。
• 适用：长任务、需要记住前情的场景。这正是本 harness 在对话变长时做的事——"压缩（compaction）"。

3.3 武器 3：工具结果裁剪 —— 治本

很多时候撑爆窗口的元凶是工具返回的巨量内容（读了个上万行的文件、命令吐了一屏日志）。 针对性裁剪：

• 文件太大就只读相关片段，而不是整个文件灌进去。
• 命令输出太长就只保留头尾 + 关键行。
• 给工具结果设单条长度上限，超了就截断并标注"（已截断）"。

💡 这往往比通用的截断/摘要更有效——从源头控制每条内容的大小，窗口就不容易爆。

3.4 武器 4：外置记忆 —— 把"该记的"挪到窗口外

把不需要每轮都看的信息写到文件/数据库里，需要时再用工具读回来。 这其实就是下一章"记忆系统"的核心思路——上下文窗口只放"当前要用的"，长期信息外置存储。

---

四、组合拳：真实 harness 是怎么做的

实际中不会只用一种，而是组合：

平时：每条工具结果设上限（武器3），别让单条内容爆掉
  ↓
上下文用到约 70-80% 时：触发压缩（武器2），把早期对话浓缩成摘要
  ↓
关键信息（用户偏好、任务目标）：外置到记忆文件（武器4），不占窗口
  ↓
兜底：真要溢出时截断（武器1），但尽量保住 system 和最近内容

核心思想一句话：

窗口是稀缺资源，只放"现在必须看的"；其余的要么压缩成摘要，要么挪到窗口外。

---

五、一个常被忽略的点：上下文质量 > 上下文数量

塞得多 ≠ 效果好。 上下文里塞满无关内容， 反而会干扰模型、稀释重点（业界叫"context rot"——上下文腐烂）。

所以好的上下文管理不只是"别超限"，还要"保持干净"：

• 无关的旧工具结果，该清就清。
• 失败的、已被纠正的尝试，没必要一直留着。
• 相关、精准的少量上下文，胜过海量但嘈杂的上下文。

---

六、常见误区

❌ **误区 1：以为模型能"无限记住"。 ** 不能。 窗口有硬上限，超了就报错或丢信息。 长对话必须主动管理上下文。

❌ **误区 2：截断时把 system prompt 也砍了。 ** system prompt 是"宪法"，一砍 Agent 立刻"人格分裂"。 **截断永远要保住 system（和关键的近期内容）。 **

❌ **误区 3：把整个大文件无脑灌进上下文。 ** 这是窗口爆炸最常见的原因。 该读片段读片段，该裁剪裁剪。

❌ **误区 4：信息越多越好。 ** 错。 无关上下文会干扰模型。 质量比数量重要。

---

七、最佳实践

✅ 给每条工具结果设长度上限，从源头防止单条内容撑爆窗口。 ✅ 接近窗口上限时触发压缩（摘要替换早期对话），别等爆了才处理。 ✅ 截断/压缩时死保 system prompt 和最近几轮。 ✅ 长期信息外置（记忆文件/数据库），窗口只留当前所需。 ✅ 主动清理无关上下文，追求"干净"而非"塞满"。

---

八、动手实践：上下文压缩：看着窗口从"快爆"到"瘦身"

8.1 怎么跑

默认离线，无需 API Key（用字符长度模拟 token 估算，压缩用规则模拟）：

python demo.py

你会看到：

1. 对话一轮轮增长，token 占用逼近上限（进度条直观显示）
2. 触发压缩：早期对话被一段【前情摘要】替换
3. 压缩后 token 大幅下降，但关键信息（"用户要求用中文"）仍被保留

8.2 看点

1. 触发时机：占用达到约 75% 才压缩，不是一满就处理——对照第 06 章"组合拳"。
2. 保住 system：压缩永远不动第一条 system 消息。
3. 关键信息存活：摘要里特意保留了用户的关键偏好，演示"压缩 ≠ 无脑丢弃"。
4. 改 MAX_TOKENS 调小一点再跑，看压缩触发得更频繁。

真实版：把 mock_summarize 换成调用模型生成摘要即可，整体流程不变。

九、动手验证：先跑通 上下文管理与 Token 预算，再改变一个变量

前面的章节已经建立问题、概念和机制。现在把“上下文管理与 Token 预算”放进同一套基线中运行；本节不再引入新术语，只验证前文结论能否被复现。

9.1 基线与候选只允许一个变量不同

验证“上下文管理与 Token 预算”时，先固定请求集、Token 分布、并发梯度、模型和机器版本。候选方案只能改变本次要验证的变量；如果同时更换数据、依赖和配置，即使结果改善，也不能知道是哪一项产生作用。

执行“上下文管理与 Token 预算”时，动作是：执行冷启动与稳态压测，拆分排队、Prefill、Decode。原始结果不能只保留截图或汇总分数，必须同步保存：P95/P99、TTFT、tokens/s、错误率、缓存率、成本，使下一次复查可以在同一输入上重放。

实验要素	本文要求
固定条件	固定请求集、Token 分布、并发梯度、模型和机器版本
唯一变量	本次候选方案与基线之间的一项明确差异
原始证据	P95/P99、TTFT、tokens/s、错误率、缓存率、成本
通过阈值	质量不降，峰值并发仍满足延迟与成本预算
立即停止	只看均值、耗时未分段或吞吐以正确率为代价

9.2 执行前先排除不可比较条件

“上下文管理与 Token 预算”开始前先确认下面四项；任一项不成立，都应先修复实验条件，而不是解释结果。

• 基线能够在“上下文管理与 Token 预算”的当前环境重复运行。
• 候选只改变一个与“上下文管理与 Token 预算”结论直接相关的条件。
• “上下文管理与 Token 预算”的基线和候选使用同一批输入、同一版本依赖与同一通过阈值。
• “上下文管理与 Token 预算”的原始输出和失败现场不会被重试、格式化或汇总覆盖。

9.3 执行后先核对证据完整性

结果出来后先检查证据，再讨论“上下文管理与 Token 预算”是否通过。缺少中间状态时，最终输出只能说明现象，不能证明机制。

检查项	当前文章的判定
输入可追溯	固定请求集、Token 分布、并发梯度、模型和机器版本
过程可回放	执行冷启动与稳态压测，拆分排队、Prefill、Decode
结果可审计	P95/P99、TTFT、tokens/s、错误率、缓存率、成本

“上下文管理与 Token 预算”的一次合格基线对照按以下顺序执行：

1. 保存“上下文管理与 Token 预算”基线版本及输入摘要，确认基线本身可以重复运行。
2. 写下“上下文管理与 Token 预算”候选方案唯一变化的变量，以及它预期影响的指标。
3. 在同一环境执行“上下文管理与 Token 预算”：执行冷启动与稳态压测，拆分排队、Prefill、Decode。
4. 为“上下文管理与 Token 预算”保存：P95/P99、TTFT、tokens/s、错误率、缓存率、成本。
5. 使用“上下文管理与 Token 预算”预登记条件判断：质量不降，峰值并发仍满足延迟与成本预算。
6. 如果“上下文管理与 Token 预算”未通过，不修改第二个变量，先恢复基线并保留失败现场。

十、用一张矩阵验证 上下文管理与 Token 预算 的关键结论

矩阵按正文顺序列出“上下文管理与 Token 预算”的结论。一次实验只选择一行，只改变这一行对应的条件；不要把多行合并成一个无法归因的大实验。

正文章节	已解释的结论	本轮唯一变量	必须保存的证据
先搞懂：Context Window 是什么，为什么会满	每个模型一次能"看"的文字量是有上限的，	只改变与“先搞懂：Context Window 是什么，为什么会满”相关的条件	P95/P99、TTFT、tokens/s、错误率、缓存率、成本
四种武器：截断、摘要、压缩、外置	这正是本 harness 在对话变长时做的事——"压缩（compaction）"。	只改变与“四种武器：截断、摘要、压缩、外置”相关的条件	P95/P99、TTFT、tokens/s、错误率、缓存率、成本
组合拳：真实 harness 是怎么做的	窗口是稀缺资源，只放"现在必须看的"；	只改变与“组合拳：真实 harness 是怎么做的”相关的条件	P95/P99、TTFT、tokens/s、错误率、缓存率、成本
一个常被忽略的点：上下文质量 > 上下文数量	失败的、已被纠正的尝试，没必要一直留着。	只改变与“一个常被忽略的点：上下文质量 > 上下文数量”相关的条件	P95/P99、TTFT、tokens/s、错误率、缓存率、成本
常见误区	长对话必须主动管理上下文。	只改变与“常见误区”相关的条件	P95/P99、TTFT、tokens/s、错误率、缓存率、成本
最佳实践	✅ 给每条工具结果设长度上限，从源头防止单条内容撑爆窗口。	只改变与“最佳实践”相关的条件	P95/P99、TTFT、tokens/s、错误率、缓存率、成本

10.1 记录本次实际实验

下面的记录用于“上下文管理与 Token 预算”当前这一次实验，不是第二套知识目录。先从矩阵选择一个章节，再填写实际值；没有填写的字段表示尚未验证。

topic: "上下文管理与 Token 预算"
selected_chapter: required
claim_from_article: required
baseline_version: required
changed_condition: exactly_one
execution: "执行冷启动与稳态压测，拆分排队、Prefill、Decode"
evidence: "P95/P99、TTFT、tokens/s、错误率、缓存率、成本"
pass_when: "质量不降，峰值并发仍满足延迟与成本预算"
stop_when: "只看均值、耗时未分段或吞吐以正确率为代价"
observed_result: required
first_deviation: null_or_evidence
recovery_replay: required_after_failure

10.2 边界实验必须证明能够停止和恢复

成功路径只能证明“上下文管理与 Token 预算”在当前样本上工作，不能证明它可以进入生产。边界实验需要主动制造：只看均值、耗时未分段或吞吐以正确率为代价，并观察系统是否在产生不可逆副作用前停止。

场景	只改变什么	应保存什么	通过标准
正常路径	使用已知有效输入	P95/P99、TTFT、tokens/s、错误率、缓存率、成本	质量不降，峰值并发仍满足延迟与成本预算
边界路径	把一个输入推进到约束临界值	临界值前后的输出与指标	不静默降级，不把部分结果冒充成功
明确失败	注入：只看均值、耗时未分段或吞吐以正确率为代价	原始错误、首个异常阶段和最终状态	失败被正确分类且没有扩大副作用
恢复重放	执行：调整上下文、批处理、缓存或路由，保留旧配置回滚	原失败样本的复测证据	原样本恢复，正常样本没有回归

恢复动作不是简单重启。对于“上下文管理与 Token 预算”，第一步是：调整上下文、批处理、缓存或路由，保留旧配置回滚。完成后使用原始失败样本复测；只验证一个新样本成功，不能证明触发条件已经消失。

“上下文管理与 Token 预算”边界实验结束后，应把正常、临界、失败和恢复四类记录放在同一个运行批次中。这样才能区分“候选方案真的修复问题”和“环境变化让问题暂时没有出现”。

十一、上下文管理与 Token 预算 的结果解释

解释“上下文管理与 Token 预算”实验时先看首个偏差，而不是最后一条错误。最后的异常通常只是上游状态错误的结果；从末端反推容易误把症状当根因。

观察结果	可以支持的判断	下一步
主链路没有达到预期	只看均值、耗时未分段或吞吐以正确率为代价	先执行：调整上下文、批处理、缓存或路由，保留旧配置回滚
异常链路无法恢复	只看均值、耗时未分段或吞吐以正确率为代价	先执行：调整上下文、批处理、缓存或路由，保留旧配置回滚
新样本成功但原样本仍失败	修复没有覆盖原始触发条件	固定原失败输入，恢复基线后重新比较
指标改善但证据无法回链	数据、版本或中间状态没有固定	暂停发布，补齐可追溯记录后重跑

“上下文管理与 Token 预算”只有同时满足“质量不降，峰值并发仍满足延迟与成本预算”，并且没有出现“只看均值、耗时未分段或吞吐以正确率为代价”，才可以认为主链路通过。这里的“通过”只对当前固定版本、样本和环境有效，不能外推到尚未测试的容量、权限或数据分布。

如果“上下文管理与 Token 预算”候选方案与基线差异很小，先检查证据分辨率是否足够；如果差异很大，先排除数据泄漏、环境漂移和版本不一致。两种情况都不能只看一个汇总均值，需要回到逐样本输出和中间状态。

“上下文管理与 Token 预算”故障定位完成后，记录“现象、首个偏差、根因、改动、原样本复测”五项。缺少原样本复测时，只能标记为待观察，不能标记为已解决。

十二、上下文管理与 Token 预算 的发布判断

发布判断需要把“上下文管理与 Token 预算”的质量、失败边界和恢复能力放在同一份记录中。以下任一条件缺失，都应停止扩量，而不是用“基本正常”替代证据。

• “上下文管理与 Token 预算”的基线与候选只存在一个计划内变量。
• “上下文管理与 Token 预算”的输入、代码、依赖、配置和数据版本可以追溯。
• “上下文管理与 Token 预算”的正常、临界、失败和恢复样本使用同一套断言。
• “上下文管理与 Token 预算”的原始输出、中间状态和失败现场已经保留。
• “上下文管理与 Token 预算”的日志、Trace、截图和测试数据已经脱敏。
• “上下文管理与 Token 预算”的停止条件、负责人和回滚入口已经演练。
• “上下文管理与 Token 预算”尚未覆盖的输入、权限、容量和外部依赖已经登记。

最终记录至少包含基线版本、唯一变量、原始证据、首个偏差、恢复复测和发布责任人。没有参与本次修改的人如果不能据此重放“上下文管理与 Token 预算”的判断，就不能发布。

十三、总结

• 先搞懂：Context Window 是什么，为什么会满：每个模型一次能"看"的文字量是有上限的，
• 四种武器：截断、摘要、压缩、外置：这正是本 harness 在对话变长时做的事——"压缩（compaction）"。
• 组合拳：真实 harness 是怎么做的：窗口是稀缺资源，只放"现在必须看的"；
• 一个常被忽略的点：上下文质量 > 上下文数量：失败的、已被纠正的尝试，没必要一直留着。
• 常见误区：长对话必须主动管理上下文。
• 武器 3：工具结果裁剪 —— 治本：很多时候撑爆窗口的元凶是工具返回的巨量内容（读了个上万行的文件、命令吐了一屏日志）。