四步流水线与上下文工具箱

一句话概要：上下文工程落到框架里变成三个组件——构建器把信息筛好摆好、笔记工具把重要的事存到上下文之外、终端工具让智能体按需探索文件系统；三者组合即可撑起能连续干好几天的长程智能体。

本章要点

一、上下文构建器的四个设计目标

• 统一入口：把「获取—选择—结构化—压缩」抽象为可复用流水线，避免每个智能体重复写上下文管理逻辑；
• 稳定形态：输出固定骨架的上下文模板，便于调试与评估；
• 预算守护：在词元预算内保留高价值信息，对超限内容提供兜底压缩；
• 最小规则：不引入来源、优先级等分类维度，仅用「相关性 + 新近性」评分，避免复杂度增长。

设计理念是「简单高效」。两个核心数据结构：候选信息包（内容、时间戳、词元数、相关性分数）与配置对象（「预留比例」参数确保系统指令始终有空间）。

二、四步流水线

这条流水线的缩写取自四个英文单词首字母，即汇集、选择、结构化、压缩。

1. 汇集：多源收集。容错机制（每个数据源调用都被异常捕获，单源失败不影响整体）、优先级处理（系统指令标记为高优先级，始终保留）、历史限制（只保留最近若干条对话，避免窗口被历史占满）。
2. 选择：整条流水线的核心。相关性（跟当前任务有没有关）与新近性（是不是刚发生）加权组合、权重可配；按分数从高到低贪心填充；用最低相关性阈值过滤低质量信息——宁可少放，也别放进噪声。
3. 结构化：把散乱信息组织成清晰分区，带来可读性、可调试性（快速定位哪个区有问题）、可扩展性（新信息源 = 新分区）。
4. 压缩：兜底而非常态。原则是保持结构完整，预算紧张时也要尽量保留每个分区的关键信息，而不是整块砍掉。天天触发压缩说明前三步没做好或预算太紧。

三、稳定骨架的六个分区

角色与行为准则、当前任务、当前状态、检索到的证据、历史对话与记忆、期望输出格式。

五条最佳实践：按任务复杂度动态调预算；生产环境把关键词重叠换成向量相似度；对不变内容做缓存；记录每次构建的统计信息；对关键权重做对照实验而非拍脑袋。

四、笔记工具：把记忆放到上下文之外

为长时程任务准备的外部记忆组件，用标记语言文件作载体，头部元数据记录关键信息，正文记录状态、结论、阻塞与行动项。此前介绍的记忆工具主要关注对话式记忆（短期工作记忆、情景记忆、语义记忆），笔记工具填补了「长期追踪、结构化管理」的空档。

四大特性：结构化记录（机器可解析 + 人类可读）、版本友好（纯文本天然支持版本控制）、低开销（无需数据库）、灵活分类（类型 + 标签，支持多维度检索）。

五、笔记的存储与操作

两层存储：笔记文件（头部元数据可精确提取、正文人类可读、文件名即唯一标识）与索引文件（免开文件快速检索、集中管理元数据、完整性校验）。七个核心操作覆盖完整生命周期：创建、读取、更新、搜索、列出、摘要、删除。

四条最佳实践：合理分类五类（任务状态 / 结论 / 阻塞项，优先级最高 / 行动项 / 参考资料）；定期清理归档（已解决的阻塞转结论、过时行动项及时更新）；配合构建器时按类型设置相关性分数（阻塞项 > 行动项 > 结论）并限制数量；人机协作（支持手动编辑、版本控制追踪、关键阶段人工审核）。

六、终端工具：即时访问与四层安全

为智能体提供安全的命令行执行能力，把「即时上下文」落到文件系统访问上——不预加载所有文件，而是按需探索。

四层安全机制：命令白名单（只允许安全只读命令，禁止任何修改操作）、工作目录沙箱（只能访问指定目录及其子目录）、超时控制（防无限循环与资源耗尽）、输出大小限制（防内存溢出）。白名单和沙箱保命，超时和输出限制保稳。

两个核心功能：命令执行（当前目录感知、合并标准错误、非零返回码标记警告、超时与异常容错）与目录导航（切换目录特殊处理，支持多步骤探索）。可与记忆工具、笔记工具、构建器协同。

七、实战：代码库维护助手

场景：维护一个中型网络应用，约五十个文件，涵盖数据模型、业务逻辑、接口等模块，存在待清理的技术债务。

三个挑战与对应解法：

• 信息量超出上下文窗口（数万行代码塞不进）→ 终端工具即时按需探索；
• 跨会话状态管理（重构持续数天）→ 笔记工具记录阶段性进展、待办与关键决策；
• 上下文质量与相关性 → 构建器智能筛选组织，确保高信号密度。

最终四个关键特性：跨会话连贯性（第一天的问题在第二天被自动考虑，一周后历史完整）、智能上下文管理（自动汇集阻塞项笔记，预算内选最相关信息）、即时文件系统访问（无需预索引）、自动化知识管理（发现问题自动建阻塞笔记，讨论计划自动建行动笔记）。

音频章节时间戳

时间	章节
00:00	开场
00:52	为什么要造一个上下文构建器
03:14	流水线第一步 汇集
04:58	流水线后两步 结构化与压缩
06:06	稳定骨架与五条最佳实践
07:41	笔记工具 把记忆放到上下文外面
09:08	笔记怎么存怎么用
10:46	终端工具 即时访问与四层安全
12:42	实战与收尾

总时长 16 分 28 秒。

原书对应小节

Datawhale《Hello-Agents：从零开始构建智能体》第九章「上下文工程」，第 9.3 节「在 Hello-Agents 中的实践：上下文构建器」（9.3.1 设计动机与目标、9.3.2 核心数据结构、9.3.3 四步流水线详解、9.3.4 完整使用示例、9.3.5 最佳实践与优化建议）、第 9.4 节「结构化笔记工具」（9.4.1 设计理念与应用场景、9.4.2 存储格式详解、9.4.3 核心操作详解、9.4.4 与构建器深度集成、9.4.5 最佳实践）、第 9.5 节「终端工具：即时文件系统访问」（9.5.1 设计理念与安全机制、9.5.2 核心功能、9.5.3 典型使用模式、9.5.4 与其他工具协同）、第 9.6 节「长程智能体实战：代码库维护助手」。

更完整的图文内容请直接阅读原书，本页仅为音频配套要点。

授权

本内容改编自 Datawhale《Hello-Agents：从零开始构建智能体》，采用 CC BY-NC-SA 4.0 授权，为二次演绎配音版。