第 6 章 Chapter Outline：Context Engineering

本文件是正文写作蓝图。Context Packet、预算、来源字段、刷新规则和污染诊断是本书工程模型，不是任何产品共同的上下文 API、记忆格式或安全机制。涉及 Anthropic、OpenAI Agents SDK 或 Gemini 的行为时，正文写作当天必须重新核验 REF-015 至 REF-019，并只陈述来源直接支持的范围。

章节契约

读者完成后的能力： 能为任务写出带来源、用途、时效、预算、敏感性、刷新条件和未知项的 Context Brief；能区分本地可访问状态与模型实际可见输入；能在资料过多、历史重复或来源过期时做出可审查的选择、排除和升级，而不是静默拼接全部文本。

前置知识： 已理解第 5 章中规则、任务 Brief、数据和输出契约的不同职责；已理解第 4 章中完成需要独立验证；能阅读数组、对象、token 预算和简单测试断言。

章节边界： 本章不定义长期记忆写入与保留策略（第 7 章）、工具协议或 MCP（第 11 章）、知识库构建与检索基础设施（第 13 章）、长任务压缩实现（第 19 章）、成本优化（第 40 章）或安全与审计（第 41 章）。它不把任何资料选择、缓存命中、长上下文窗口、上下文压缩或检索结果表述为模型理解、事实正确、无注入风险或已获授权的保证。

小节蓝图

1. Context Engineering 不是“塞进更多资料”

• 读者问题： 模型能接收更多 token 时，为什么不把整个仓库、所有聊天记录和全部日志都带入？
• 叙述任务： 从原创教学场景开始：测试失败后，Agent 收到完整仓库树、三个月对话、所有 CI 日志和无关设计文档，反而无法解释当前失败。区分“资料存在”“运行时代码能读取”“资料已经送入模型”和“资料值得进入当前调用”。
• 证据边界： 场景、资料噪声分类和“最小高信号包”均是本书工程模型；REF-015 仅提供 Context Engineering 是持续选择有限上下文的工程观点，REF-018 仅在 Gemini 语境下建议避免不需要的 token。
• 计划工件： “候选资料 / 当前包 / 可按需引用 / 排除项”对照表，字段包含来源、任务关联、时效、风险、大小和下一步。
• 验证： 读者能指出至少三类“存在但不应立即送入模型”的资料，并说明它们在何种条件下才需要加载。
• 过渡： 要做选择，先要知道某份信息究竟给谁使用：本地运行时还是模型。

2. 本地 context 与模型 context：能访问不等于已经看见

• 读者问题： 代码里的对象、环境依赖、会话状态和模型输入是同一份上下文吗？
• 叙述任务： 用 OpenAI Agents SDK 的本地 context 与 LLM context 区分作为产品例子，随后提出本书的“可访问面 / 模型输入面 / 持久状态面”三面检查。说明把对象传给工具不等于模型自动获得其内容；将秘密、重对象或未验证资料留在本地也不等于安全措施已经完成。
• 证据边界： REF-016 仅说明该 SDK 的 local context 不会自动发送给 LLM，并列举其提供信息的方式；三面检查是本书模型，不能外推为所有框架或安全隔离。
• 计划工件： “资料位置—谁能读取—何时显式投影到模型—不能证明什么”责任表。
• 验证： 给出用户档案、数据库连接、失败日志和任务 Brief；读者能说明它们应留在本地、进入 Context Packet、仅保留引用或停止等待人工的理由。
• 过渡： 明确资料所在位置后，下一步是把被选入模型的每一项变成可审查证据，而不是匿名文本块。

3. Context Brief 与证据条目：先写选择理由，再装配输入

• 读者问题： 谁决定一段历史、文档或工具输出是否相关，决定过程如何被复核？
• 叙述任务： 定义本书 Context Brief：任务锚点、验证对象、候选资料、选择理由、排除理由、来源、时效、敏感性、大小、预算、刷新条件和未知项。强调“相关”不是形容词，而是针对当前任务的可检查理由。
• 证据边界： 字段、评分、默认权重和 Context Packet 格式均为本书设计；不声称任一供应商自动记录这些元数据，也不设定通用 token 上限。
• 计划工件： Context Brief 模板及“直接证据 / 约束 / 背景 / 历史摘要 / 可按需引用”的优先级表。
• 验证： 每个选中条目都能回答“它来自哪里、解决什么问题、何时失效、为什么不由另一个资料替代”；答不出时保留为候选或标记 TODO(verify)：。
• 过渡： 资料带有元数据并不自动解决容量问题，下一步需要预算与排除顺序。

4. 上下文预算：为约束、证据和未知项保留位置

• 读者问题： 当稳定规则、任务、日志、历史摘要和文档都很重要时，先删什么？
• 叙述任务： 建立本书预算模型：稳定约束和任务锚点优先保留；当前直接证据其次；历史摘要必须保留覆盖范围与来源；大对象改为可按需访问的引用；超过预算先记录排除理由，再删除低相关、过期或重复项。明确预算是容量和注意力的共同约束，不只是字数限制。
• 证据边界： REF-015 的有限上下文和高信号观点、REF-018 的无用 token 建议只提供背景；预算百分比、优先级和删减算法是本书工程扩展，不代表厂商推荐配置。
• 计划工件： 预算表与超限决策树，包含“保留、摘要、指针化、排除、升级”五种动作。
• 验证： 给定固定预算与八项候选资料，读者能产出明确的保留/排除清单，并说明验证命令、直接失败证据为何不能被无关历史替代。
• 过渡： 预算会促使系统保留指针而非全量内容，于是需要决定何时真正检索或读取。

5. 预先检索与按需加载：给模型入口，不预装整个世界

• 读者问题： 何时先检索资料，何时只提供文件路径、查询名或网页引用？
• 叙述任务： 对比预先装入少量高置信资料与按需调用工具加载资料。用 REF-015 的 just-in-time 标识符思路和 REF-016 的工具/retrieval/web search 方式作为来源背景；要求 Harness 记录触发条件、返回范围、来源、时间和失败结果。
• 证据边界： 这些来源不保证工具会选择正确资料，也不证明按需加载优于预检索；检索质量、向量库、MCP 和权限实现不在本章。
• 计划工件： “预载 / 按需 / 禁止加载”决策表，覆盖稳定项目规则、当前 diff、巨大日志、敏感文件和未知网页。
• 验证： 每个按需引用都有可解析标识和加载条件；工具失败、来源过期或结果超范围时，返回未决项而不是用旧摘要伪装答案。
• 过渡： 随着调用跨轮进行，选择策略还必须避免历史被重复传入。

6. 跨轮状态：选择一个权威承载方式并防止重复

• 读者问题： 会话、历史消息、应用状态和服务端 continuation 同时存在时，如何避免重复上下文和错误恢复？
• 叙述任务： 以 REF-017 的四种状态承载策略及其混用警告为特定 SDK 例子，提出本书建议：每段连续对话声明一个权威承载方式；把已投影给模型的摘要与原始状态分开；恢复时记录快照版本和重复风险。
• 证据边界： 本书不选择某个 SDK 的 session、conversation ID 或 response ID，也不承诺跨提供商可移植；长期记忆和工作流恢复留给第 7、10、19 章。
• 计划工件： “状态位置—权威来源—下一轮传入内容—去重检查—恢复条件”表。
• 验证： 读者能识别把完整客户端历史和同一服务端 continuation 同时传入为何可能重复；未知承载方式必须停止并查证，而不是猜测。
• 过渡： 即使没有重复，资料也会过期、阶段变化或被新观察推翻，需要刷新闭环。

7. 刷新、摘要与污染诊断：上下文也需要失效处理

• 读者问题： 什么时候应重新选择资料、更新摘要或把某段内容移出当前包？
• 叙述任务： 定义刷新触发器：任务阶段改变、来源到期、观察与摘要冲突、验证失败、资料重复、预算超限或敏感性改变。将摘要视为带覆盖范围和未知项的派生工件；将伪装成规则的数据、过期状态、无出处断言和无关历史登记为污染风险。
• 证据边界： 压缩算法、TTL 数值、缓存和产品保留期不在本章；REF-018 的 caching 与 REF-019 的 retrieval 背景不能被表述为自动刷新或防污染能力。
• 计划工件： 污染诊断表与刷新事件记录模板。
• 验证： 当失败测试的新输出与旧摘要冲突时，读者能让旧摘要失效、保留其来源和历史范围，并把下一步验证请求写入 Context Brief。
• 过渡： 最后将选择、预算、指针、刷新与验证放入一个无外部副作用的调试案例。

8. 完整工程案例：为测试失败构造最小上下文包

• 读者问题： 面对一条失败测试，如何避免把“整个项目”误当作上下文？
• 叙述任务： 设计原创、纯教学案例：任务锚点是定位单一测试失败；稳定规则指定允许目录和验证命令；直接证据是失败断言、相关 diff 与受影响模块；历史摘要只保留上一次修复尝试；大日志保留路径与过滤条件；输出契约要求选中、排除、预算、刷新理由和未知项。Harness 先构造 Context Packet，再由独立检查验证所有选中项都有来源且未超预算。
• 证据边界： 案例不读取真实仓库、不调用测试、模型、文件、网络、检索服务或向量数据库；它不证明模型找到了根因或真实测试已运行。
• 计划示例： 06-context-engineering.example-plan.md 将定义纯内存 buildContextPacket。输入为任务锚点、预算和带元数据的候选条目；输出为选中、排除、预算、刷新理由和待验证项。实现只演示本书的显式选择规则。
• 验证： 最小测试至少覆盖直接证据优先、过期条目排除、超预算指针化、缺少来源阻塞、冲突摘要触发刷新；所有预期来自本书纯函数契约，而非模型输出。
• 过渡： 第 7 章讨论哪些经历与决策应跨任务保存；第 13 章再讨论知识库与检索基础设施。本章只负责当前调用前的证据选择。

章节工件状态

1. 已完成：Research Brief 与候选参考资料。REF-015 至 REF-019 的允许陈述、外推边界和正文当天复核要求已登记。
2. 本阶段完成：Chapter Outline。为正文、事实核验、图示、示例与后续审查定义了输入、输出、证据边界和跨章节责任。
3. 已完成：Fact Check。REF-015 至 REF-019 的产品事实、来源观点、本书工程模型、教学案例和待当天复核的动态范围已逐项分开。
4. 已完成：Mermaid 图源。diagrams/mermaid/chapter-06-context-packet-flow.mmd 只呈现本书的资料检查、预算选择、按需引用、刷新与记录闭环；已做语法渲染，尚未导出发布图或完成视觉审查。
5. 已完成：Example Plan。06-context-engineering.example-plan.md 定义纯内存 buildContextPacket 的元数据、预算、选择、指针、刷新和五条确定性测试路径；尚未实现或运行。
6. 已完成：First Draft。正文以任务锚点、三面检查、Context Brief、预算、按需引用、跨轮状态、刷新污染诊断和失败测试案例组织原创叙述；示例仍为计划，图示尚未完成导出与视觉审查。
7. 已完成：Technical Review。来源归因、本书模型边界、相邻章节责任、图文一致性、示例阶段语义和验证状态已审查；两项表述漂移已修正，记录位于 .memory/reviews/2026-07-15-chapter-06-technical-review.md。
8. 已完成：Example Implementation。buildContextPacket 的五条纯内存测试与演示已实际运行；红灯、绿灯、输出和不包含的外部副作用记录位于 .memory/reviews/2026-07-15-chapter-06-example-integration.md。
9. 已完成：Diagram Review。Mermaid CLI 11.16.0 已导出 SVG/PNG 并实际查看 PNG；节点、路径、文字、图文一致性和边界均已记录于 .memory/reviews/2026-07-15-chapter-06-diagram-review.md。
10. 已完成：Language Editing。术语首次出现、中文表述与来源—模型—边界的叙述顺序已收束；未修改来源、示例接口、Mermaid 源或导出图，记录位于 .memory/reviews/2026-07-15-chapter-06-language-edit.md。
11. 已完成：Validation 与 Final Review。重新运行纯内存示例、演示、Mermaid SVG/PNG 导出、图源一致性检查和完整工具链；记录位于 .memory/reviews/2026-07-15-chapter-06-final-review.md。

Outline 完成检查

• [x] 每个主要小节包含读者问题、叙述任务、证据边界、计划工件、验证和过渡。
• [x] 明确区分模型可见输入、本地运行时 context、跨轮状态、检索背景与本书 Context Packet 模型。
• [x] 明确了与第 5、7、11、13、19、40、41 章的边界，未将缓存、检索、预算或摘要写成安全或正确性保证。
• [x] 图示、案例与示例都要求记录来源、范围、时效、预算、排除理由、刷新条件和未决项。
• [x] 未提前写入正文、产品 SDK、窗口/费用数字、检索性能主张、真实工具行为或未验证的安全结论。