[Hello-Agents] Day 12: 第九章 上下文工程 阅读日期：2026年4月6日 章节范围：第九章 上下文工程（Context Engineering） 原文来源：Hello-Agents 开源教程 "上下文工程的'艺与术'，在于从持续扩张的'候选信息宇宙'中，甄别哪些内容应当进入有限的上下文窗口。" 一、章节摘要 第九章「上下文工程」是 Hello-Agents 教程中承上启下的关键章节。在前八章介绍了智能体的基础概念、发展历史、大语言模型基础、经典范式构建、低代码平台搭建、框架开发实践、Agent框架构建以及记忆与检索系统之后，本章聚焦于一个看似简单却极具深度的核心问题：如何在每一次模型调用前，以可复用、可度量、可演进的方式，拼装并优化输入上下文？ 本章首先厘清了「上下文工程」与「提示工程」的本质区别：提示工程关注如何编写和组织 LLM 的指令以获得更优结果，而上下文工程则是在推理阶段策划和维护「最优的信息集合（tokens）」，不仅包含提示本身，还包含系统指令、工具定义、外部数据、消息历史等所有进入上下文窗口的信息。 接着，本章深入探讨了「上下文腐蚀」现象——随着上下文窗口中 tokens 增加，模型从上下文中准确回忆信息的能力反而下降。这一观察引出了「上下文必须被视作有限资源」的核心认知，进而提出了 GSSC（Gather-Select-Structure-Compress）流水线作为系统性解决方案。 最后，本章提供了三个生产级工具的实现：ContextBuilder（上下文构建器）、NoteTool（结构化笔记工具）、TerminalTool（终端工具），展示了从理论到实践的完整路径。 二、核心概念解析 2.1 上下文工程 vs 提示工程 这是本章最重要的概念区分。在 LLM 工程的早期阶段，提示工程往往是主要工作，因为大多数用例需要针对单轮分类或文本生成做精调式的提示优化。然而，随着智能体工程化的深入，它们需要在更长的时间范围内、跨多次推理轮次地工作，仅仅优化提示已远远不够。 提示工程（Prompt Engineering） 关注「如何写出有效提示」 聚焦系统提示的写法与结构化策略 适用于单轮任务 强调指令的精确性与完整性 上下文工程（Context Engineering） 关注「如何策划和维护最优信息集合」 包含系统指令、工具、外部数据、消息历史 适用于多轮、长时程任务 强调信息的筛选、结构与压缩 2.2 上下文腐蚀（Context Rot） 「针堆找针」（needle-in-a-haystack）基准测试揭示了一个关键现象：随着上下文窗口中 tokens 增加，模型从上下文中准确回忆信息的能力反而下降。这不是某个模型的缺陷，而是几乎所有 LLM 共同的特征。 这种「上下文腐蚀」的根源在于 Transformer 架构本身的约束：每个 token 需要与上下文中的所有 token 建立关联，理论上形成 n² 级别的两两注意力关系。随着上下文长度增长，模型对这些两两关系的建模能力会被「拉薄」，产生「上下文规模」与「注意力集中度」的张力。 实践启示：上下文必须被视作一种有限资源，具有边际收益递减特性。每新增一个 token，都会消耗模型的「注意力预算」。 2.3 GSSC 流水线：上下文管理的四阶段框架 ContextBuilder 的核心是 GSSC（Gather-Select-Structure-Compress）流水线，这是一个清晰的四阶段上下文构建框架： 阶段 核心任务 Gather 从多个来源汇集候选信息：系统指令、记忆检索、RAG知识、对话历史、自定义信息包 Select 根据相关性和新近性对候选信息进行评分，使用贪心算法在 token 预算内选择最有价值的信息 Structure 将选中的信息组织成结构化模板：[Role & Policies]、[Task]、[Evidence]、[Context]、[Output] Compress 对超限上下文进行兜底压缩，保持结构完整性 2.4 长时程任务的三种策略 针对超出上下文窗口的长序列行动，本章提出了三种互补的工程手段： 1. 压缩整合（Compaction） 当对话接近上下文上限时，对历史进行高保真总结，用摘要重启新窗口。适合需要长对话连续性的任务，强调上下文的「接力」。 2. 结构化笔记（Structured Note-taking） 智能体以固定频率将关键信息写入上下文外的持久化存储，在后续阶段按需拉回。适合有里程碑/阶段性成果的迭代式开发与研究。 3. 子代理架构（Sub-agent architectures） 主代理负责高层规划与综合，多个专长子代理在干净上下文中深挖，仅回传凝练摘要。适合复杂研究与分析，能从并行探索中获益。 三、代码示例与实现解析 3.1 ContextPacket 与 ContextConfig 数据结构 ContextBuilder 使用两个核心数据结构来管理上下文： @dataclass class ContextPacket: """候选信息包 - 系统中信息的基本单元""" content: str # 信息内容 timestamp: datetime # 时间戳 token_count: int # Token 数量 relevance_score: float = 0.5 # 相关性分数(0.0-1.0) metadata: Optional[Dict[str, Any]] = None # 可选的元数据 @dataclass class ContextConfig: """上下文构建配置""" max_tokens: int = 3000 # 最大 token 数量 reserve_ratio: float = 0.2 # 为系统指令预留的比例 min_relevance: float = 0.1 # 最低相关性阈值 enable_compression: bool = True # 是否启用压缩 recency_weight: float = 0.3 # 新近性权重 relevance_weight: float = 0.7 # 相关性权重 3.2 Select 阶段的核心算法 选择阶段是 GSSC 流水线的核心，采用相关性和新近性的加权组合进行评分： # 综合分数计算 combined_score = ( self.config.relevance_weight * packet.relevance_score + self.config.recency_weight * recency ) # 贪心选择：按分数从高到低填充，直到达到 token 上限 for score, packet in scored_packets: if current_tokens + packet.token_count <= available_tokens: selected.append(packet) current_tokens += packet.token_count else: break # Token 预算已满，停止选择 3.3 NoteTool 的存储格式 NoteTool 采用 Markdown + YAML 混合格式，兼顾结构化和可读性： --- id: note_20250119_153000_0 title: 项目进展 - 第一阶段 type: task_state tags: [refactoring, phase1, backend] created_at: 2025-01-19T15:30:00 updated_at: 2025-01-19T15:30:00 --- # 项目进展 - 第一阶段 ## 完成情况 已完成数据模型层的重构,测试覆盖率达到85%。 ## 下一步计划 1. 重构业务逻辑层 2. 解决依赖冲突问题 3.4 TerminalTool 的安全机制 TerminalTool 通过四层安全机制确保系统安全： 第一层：命令白名单 — 只允许安全的只读命令（ls, cat, head, tail, grep, find, wc 等） 第二层：工作目录沙箱 — 只能访问指定工作目录及其子目录，禁止路径逃逸 第三层：超时控制 — 每个命令有执行时间限制，防止无限循环 第四层：输出大小限制 — 限制命令输出大小，防止内存溢出 四、个人思考与反思 4.1 从「写提示」到「管理上下文」的思维转变 读完本章，我意识到一个根本性的思维转变：传统提示工程教我们「如何写出有效提示」，而上下文工程要求我们思考「什么样的上下文配置最有可能让模型产出期望的行为」。这不是措辞的优化，而是系统性的信息管理。 这种转变有几个深刻的含义： 信息筛选成为核心能力：不是「更多信息更好」，而是「更精准的信息更好」。每个进入上下文的 token 都在消耗注意力预算。 时间维度变得重要：信息的「新近性」成为评分维度之一，旧信息可能不仅无用，还会稀释关键信号的浓度。 结构即价值：杂乱的信息堆砌 vs 分区组织的结构化上下文，后者让模型更容易定位和利用信息。 4.2 GSSC 流水线的工程智慧 GSSC 流水线的设计体现了几个重要的工程原则： 分离关注点： Gather 负责数据收集、Select 负责价值判断、Structure 负责格式组织、Compress 负责兜底处理。每个阶段职责单一，便于独立测试和优化。 可配置性： 通过 ContextConfig 暴露关键参数（max_tokens、reserve_ratio、min_relevance、权重配置），使得不同场景可以调整策略。 贪心选择的实用主义： 按分数从高到低填充的贪心算法虽然不一定找到全局最优解，但在工程实践中足够高效且可解释。 4.3 NoteTool 与 MemoryTool 的互补关系 本章明确区分了两种「记忆」工具的定位： MemoryTool（第八章） 关注「对话式记忆」 短期工作记忆、情景记忆、语义记忆 向量检索为核心 适合单会话内的信息追踪 NoteTool（第九章） 关注「项目式记忆」 结构化的状态、结论、阻塞、行动项 Markdown + YAML 格式 适合跨会话的长期项目追踪 这种设计体现了「不同问题需要不同工具」的工程智慧。MemoryTool 擅长模糊检索和语义匹配，而 NoteTool 擅长精确状态追踪和结构化记录。在实际应用中，两者应该配合使用： MemoryTool：存储对话中涌现的零散洞察、用户偏好、临时约定 NoteTool：存储明确的项目状态、待办事项、已知阻塞、重要决策 4.4 TerminalTool 与 JIT 上下文的范式意义 TerminalTool 实现了本章 9.2.2 节提出的「即时上下文」（Just-in-time, JIT）理念： 传统方式：预先索引所有文件 → 建立向量数据库 → 查询时检索 JIT 方式：维护轻量化引用（文件路径、查询）→ 运行时通过工具动态加载所需数据 这种范式的优势在于： 数据新鲜度：总是获取最新文件内容，无需担心索引过期 存储效率：不需要为所有文件建立向量索引，节省存储空间 元数据价值：文件路径、时间戳、大小等信息本身就传达了「目的与时效」 探索能力：智能体可以按需决定深入程度，用 head/tail 预览再决定是否读取全部 4.5 关于「工具集臃肿」的警示 本章提出了一个重要的设计原则：「如果人类工程师都说不准用哪个工具，别指望智能体做得更好。」这指向了工具设计的核心挑战： 最小可行工具集（MVTS）原则：精心甄别一个职责单一、相互低重叠的工具集，往往比提供大量「全能型」工具更有效。 这让我反思在实际项目中是否过度追求「功能全面」，而忽视了「职责清晰」。一个接口语义明确、对错误鲁棒、入参描述无歧义的工具，远比一个功能复杂但边界模糊的工具更有价值。 五、实践建议 5.1 动态调整 Token 预算 根据任务复杂度动态调整 max_tokens。简单分类任务用较小预算（如 2000 tokens），复杂推理任务增加预算（如 4000+ tokens）。可以通过监控 token 使用率来优化配置。 5.2 相关性计算优化 本章示例使用简单的 Jaccard 相似度计算相关性。生产环境中应替换为向量相似度计算： 对候选信息进行 embedding 编码 计算与查询向量的余弦相似度 考虑混合检索（关键词 + 向量）以提升召回率 5.3 笔记分类的最佳实践 使用 NoteTool 时，合理分类笔记类型： blocker：阻塞问题，优先级最高，应优先检索 action：下一步行动计划，次优先级 task_state：阶段性进展和状态 conclusion：重要结论和发现 reference：重要参考资料 5.4 定期清理和归档 笔记系统需要定期维护： 已解决的 blocker 更新为 conclusion 过时的 action 及时删除或更新 使用 tags 进行版本管理（如 ["v1.0", "completed"]） 5.5 A/B 测试与持续优化 上下文工程不是一次性配置，而是需要持续优化的系统： 记录每次上下文构建的统计信息（选中信息数量、token 使用率等） 对关键参数（相关性权重、新近性权重）进行 A/B 测试 监控「上下文命中率」：模型是否有效利用了提供的信息 六、章节总结 第九章「上下文工程」是 Hello-Agents 教程中承上启下的关键章节。它系统地回答了一个核心问题：在智能体工程中，如何让模型「看见」最该看见的信息？ 本章的核心贡献包括： 理论层面：厘清了上下文工程与提示工程的区别，提出了「上下文腐蚀」概念，建立了 GSSC 流水线框架 工具层面：提供了 ContextBuilder、NoteTool、TerminalTool 三个生产级工具的完整实现 实践层面：给出了长时程任务的三种策略（压缩整合、结构化笔记、子代理架构）及其实践建议 在 AI 应用从「单轮问答」走向「多轮智能体」的时代，上下文工程正在成为新的核心能力。它要求我们不仅关注「如何写提示」，更要关注「如何管理信息流」——在有限资源约束下，最大化信号、最小化噪声。 正如本章所言：「即便模型能力持续提升，'在长交互中维持连贯性与聚焦'仍是构建强健智能体的核心挑战。谨慎而系统的上下文工程将长期保持其关键价值。」 下一章预告：第十章「智能体通信协议」将探讨智能体之间如何进行标准化通信，包括 MCP（Model Context Protocol）等新兴协议的设计理念与实践。