第九章 agent上下文工程

第九章 上下文工程

9.1 什么是上下文工程

在经历了数年提示工程（Prompt Engineering）成为应用型AI的焦点之后，一个新的术语开始走到台前：上下文工程（Context Engineering）。如今，用语言模型构建系统不再只是找对提示词里的句式和措辞，而是要回答一个更宏观的问题：什么样的上下文配置，最有可能让模型产出我们期望的行为？

9.2为什么上下文工程重要

针堆找针（needle-in-a-haystack）类基准揭示了一个现象：上下文腐蚀（context rot）——随着上下文窗口中的 tokens 增加，模型从上下文中准确回忆信息的能力反而下降。 上下文必须被视作一种有限资源，且具有边际收益递减。就像人类有有限的工作记忆容量一样，LLM 也有一笔“注意力预算”。每新增一个 token，都会消耗这笔预算的一部分，因此我们更需要谨慎地筛选哪些 tokens 应该被提供给 LLM。 为什么会导致这种现象？ 因为transformer Transformer 让每个 token 能够与上下文中的所有 token 建立关联，理论上形成 (n^2) 级别的两两注意力关系，随着上下文长度增长，模型对这些两两关系的建模能力会被“拉薄”，从而自然地产生“上下文规模”与“注意力集中度”的张力

9.2.1 有效上下文的“解剖学”

在“有限注意力预算”的约束下，优秀的上下文工程目标是：用尽可能少、但高信号密度的 tokens，最大化获得期望结果的概率。落实到实践中，我们建议围绕以下组件开展工程化建设：

**系统提示（System Prompt）：**语言清晰、直白，信息层级把握在“刚刚好”的高度。常见两极误区： 工具（Tools）：工具定义了智能体与信息/行动空间的契约，必须促进效率：既要返回token 友好的信息，又要鼓励高效的智能体行为。工具应当：

**示例（Few-shot）：**始终推荐提供示例，但不建议把“所有边界条件”的罗列一股脑塞进提示。请精挑细选一组多样且典型的示例，直接画像“期望行为”。对 LLM 而言，好的示例胜过千言万语。

9.2.2 上下文检索与智能体式搜索

工程实践正在从“推理前一次性检索（embedding 检索）”逐步过渡到“及时（Just-in-time, JIT）上下文”。后者不再预先加载所有相关数据，而是维护轻量化引用（文件路径、存储查询、URL 等），在运行时通过工具动态加载所需数据。这样可让模型撰写针对性查询、缓存必要结果，并用诸如 head/tail 之类的命令分析大体量数据——无需把整块数据一次性塞入上下文。其认知模式更贴近人类：我们不会死记硬背全部信息，而是用文件系统、收件箱、书签等外部索引按需提取。 允许智能体自主导航与检索还能实现渐进式披露（progressive disclosure）：每一步交互都会产生新的上下文，反过来指导下一步决策——文件大小暗示复杂度、命名暗示用途、时间戳暗示相关性。智能体得以按层构建理解，只在工作记忆中保留“当前必要子集”，并用“记笔记”的方式做补充持久化，从而维持聚焦而非“被大而全拖垮”。

9.2.3 面向长时程任务的上下文工程

主要有三种手段： 1、压缩整合（Compaction） 定义：当对话接近上下文上限时，对其进行高保真总结，并用该摘要重启一个新的上下文窗口，以维持长程连贯性。 实践：让模型压缩并保留架构性决策、未解决缺陷、实现细节，丢弃重复的工具输出与噪声；新窗口携带压缩摘要 + 最近少量高相关工件（如“最近访问的若干文件”）。 调参建议：先优化召回（确保不遗漏关键信息），再优化精确度（剔除冗余内容）；一种安全的“轻触式”压缩是对“深历史中的工具调用与结果”进行清。

2、结构化笔记（Structured note-taking） **定义：**也称“智能体记忆”。智能体以固定频率将关键信息写入上下文外的持久化存储，在后续阶段按需拉回。 **价值：**以极低的上下文开销维持持久状态与依赖关系。例如维护 TODO 列表、项目 NOTES.md、关键结论/依赖/阻塞项的索引，跨数十次工具调用与多轮上下文重置仍能保持进度与一致性。 说明：在非编码场景中同样有效（如长期策略性任务、游戏/仿真中的目标管理与统计计数）。结合第八章的 MemoryTool，可轻松实现文件式/向量式的外部记忆并在运行时检索。

3、子代理架构（Sub-agent architectures） 思想：由主代理负责高层规划与综合，多个专长子代理在“干净的上下文窗口”中各自深挖、调用工具并探索，最后仅回传凝练摘要（常见 1,000–2,000 tokens）。 **好处：**实现关注点分离。庞杂的搜索上下文留在子代理内部，主代理专注于整合与推理；适合需要并行探索的复杂研究/分析任务。 **经验：**公开的多智能体研究系统显示，该模式在复杂研究任务上相较单代理基线具有显著优势。

方法取舍可以遵循以下经验法则：

压缩整合：适合需要长对话连续性的任务，强调上下文的“接力”。 结构化笔记：适合有里程碑/阶段性成果的迭代式开发与研究。 子代理架构：适合复杂研究与分析，能从并行探索中获益。

9.3 在 Hello-Agents 中的实践：ContextBuilder

在构建 ContextBuilder 之前，我们首先需要明确其设计目标和核心价值。一个优秀的上下文管理系统应该解决以下几个关键问题：

统一入口：将"获取(Gather)- 选择(Select)- 结构化(Structure)- 压缩(Compress)"抽象为可复用流水线，减少在 Agent 实现中的重复模板代码。这种统一的接口设计让开发者无需在每个 Agent 中重复编写上下文管理逻辑。

稳定形态：输出固定骨架的上下文模板，便于调试、A/B 测试与评估。我们采用了分区组织的模板结构：

[Role & Policies]：明确 Agent 的角色定位和行为准则 [Task]：当前需要完成的具体任务 [State]：Agent 的当前状态和上下文信息 [Evidence]：从外部知识库检索的证据信息 [Context]：历史对话和相关记忆 [Output]：期望的输出格式和要求

9.3.3 GSSC 流水线详解

ContextBuilder 的核心是 GSSC(Gather-Select-Structure-Compress)流水线，它将上下文构建过程分解为四个清晰的阶段。让我们深入了解每个阶段的实现细节。 （1）Gather：多源信息汇集 这个实现展示了几个重要的设计考虑：

容错机制：每个外部数据源的调用都被 try-except 包裹，确保单个源的失败不会影响整体流程 优先级处理：系统指令被标记为高优先级，确保始终被保留 历史限制：对话历史只保留最近的几条，避免上下文窗口被历史信息占据

（2）Select：智能信息选择 第二阶段是根据相关性和新近性对候选信息进行评分和选择。这是整个流水线的核心，直接决定了最终上下文的质量。 评分机制：采用相关性和新近性的加权组合，权重可配置 贪心算法：按分数从高到低填充，确保在有限预算内选择最有价值的信息 过滤机制：通过 min_relevance 参数过滤低质量信息

（3）Structure：结构化输出

第三阶段是将选中的信息组织成结构化的上下文模板。 可读性：清晰的分区让人类和模型都更容易理解上下文结构 可调试性：问题定位更容易，可以快速识别哪个区域的信息有问题 可扩展性：添加新的信息源只需要创建新的分区

（4）Compress：兜底压缩 第四阶段是对超限上下文进行压缩处理。

9.4 NoteTool：结构化笔记

NoteTool 填补了这个gap，它提供了：

结构化记录：使用 Markdown + YAML 格式，既适合机器解析，也方便人类阅读和编辑 版本友好：纯文本格式，天然支持 Git 等版本控制系统 低开销：无需复杂的数据库操作，适合轻量级的状态追踪 灵活分类：通过 type 和 tags 灵活组织笔记，支持多维度检索

NoteTool 提供了七个核心操作，覆盖了笔记的完整生命周期管理。 （1）create：创建笔记 （2）read：读取笔记 （3）update：更新笔记 （4）search：搜索笔记 （5）list：列出笔记 （6）summary：笔记摘要 （7）delete：删除笔记

9.5 TerminalTool：即时文件系统访问

在前面的章节中，我们介绍了 MemoryTool 和 RAGTool，它们分别提供了对话记忆和知识检索能力。然而，在许多实际场景中，智能体需要即时访问和探索文件系统——查看日志文件、分析代码库结构、检索配置文件等。这就是 TerminalTool 的用武之地。

TerminalTool 为智能体提供了安全的命令行执行能力，支持常用的文件系统和文本处理命令，同时通过多层安全机制确保系统安全。这种设计实现了 9.2.2 节提到的"即时(Just-in-time, JIT)上下文"理念——智能体不需要预先加载所有文件，而是按需探索和检索。

9.5.4 与其他工具的协同

TerminalTool 的真正威力在于与 MemoryTool、NoteTool 和 ContextBuilder 的协同使用。

（1）与 MemoryTool 协同 （2）与 NoteTool 协同

重要的发现可以记录为结构化笔记

9.7 本章总结

在本章中，我们深入探讨了上下文工程的理论基础和工程实践：

理论层面

上下文工程的本质：从"提示工程"到"上下文工程"的演进，核心是管理有限的注意力预算 上下文腐蚀：理解长上下文带来的性能下降，认识到上下文是稀缺资源 三大策略：压缩整合、结构化笔记、子代理架构

工程实践

ContextBuilder：实现了 GSSC 流水线，提供统一的上下文管理接口 NoteTool：Markdown+YAML 的混合格式，支持结构化的长期记忆 TerminalTool：安全的命令行工具，支持即时的文件系统访问 长程智能体：整合三大工具，构建了跨会话的代码库维护助手

核心收获

分层设计：即时访问(TerminalTool) + 会话记忆(MemoryTool) + 持久笔记(NoteTool) 智能筛选：基于相关性和新近性的评分机制 安全第一：多层安全机制确保系统稳定 人机协作：自动化与可控性的平衡