第九章 上下文工程 学习笔记

第九章 上下文工程 学习笔记

9.1 什么是上下文工程

上下文工程是提示工程的自然演进，关注在推理阶段如何策划和维护最优的信息集合（tokens）。

核心区别：

  • 提示工程：关注指令的编写与组织方式
  • 上下文工程：关注所有进入上下文窗口的信息的配置与优化

在智能体持续运行过程中，会产生大量潜在相关信息。上下文工程的核心任务是从这些信息中筛选出应当进入有限上下文窗口的内容。

9.2 为什么上下文工程重要

9.2.1 上下文腐蚀现象

随着上下文窗口中 tokens 数量增加，模型准确回忆信息的能力会下降。这一现象源于 Transformer 架构的注意力机制特性：

  • 注意力关系随序列长度呈平方级增长
  • 训练数据中短序列更为常见
  • 位置编码插值技术会牺牲部分位置理解精度

因此，上下文应被视为有限资源，需要谨慎分配注意力预算。

9.2.2 有效上下文的组成

构建有效上下文需要关注以下组件：

组件 要点
系统提示 信息层级适中，分区组织（背景、指令、工具指引、输出描述）
工具 职责单一、接口清晰、错误鲁棒，避免工具集臃肿
示例 精选典型样本，避免过度列举边界条件

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

从预检索（embedding检索）转向即时（JIT）上下文检索：

  • 维护轻量化引用（文件路径、存储查询、URL）
  • 运行时通过工具动态加载数据
  • 支持渐进式信息披露

混合策略通常更为有效：前置加载少量高价值上下文，允许智能体按需探索。

9.2.4 长时程任务的上下文管理

针对超出上下文窗口的长时程任务，有三种主要方法：

  1. 压缩整合（Compaction）

    • 对话接近上限时进行高保真总结
    • 保留架构决策、未解决问题、实现细节
    • 新窗口携带压缩摘要和近期高相关工件

  2. 结构化笔记（Structured note-taking）

    • 将关键信息写入持久化存储
    • 维持低开销的持久状态和依赖关系
    • 可与 MemoryTool 结合使用

  3. 子代理架构（Sub-agent architectures）

    • 主代理负责规划与综合
    • 子代理在独立上下文窗口中探索
    • 仅回传凝练摘要（约1000-2000 tokens）

9.3 Hello-Agents 中的 ContextBuilder

9.3.1 设计目标

ContextBuilder 旨在实现：

  • 统一入口：抽象 GSSC（Gather-Select-Structure-Compress）流水线
  • 稳定形态：输出固定骨架的上下文模板
  • 预算守护：在 token 预算内保留高价值信息
  • 最小规则：基于相关性和新近性评分

9.3.2 核心数据结构

ContextPacket（候选信息包）：

  • content：信息内容
  • timestamp：时间戳
  • token_count：Token 数量
  • relevance_score：相关性分数（0.0-1.0）
  • metadata：元数据

ContextConfig（配置管理）：

  • max_tokens：最大 token 数量
  • reserve_ratio：系统指令预留比例
  • min_relevance：最低相关性阈值
  • enable_compression：是否启用压缩
  • recency_weight：新近性权重
  • relevance_weight：相关性权重

9.3.3 GSSC 流水线

Gather（汇集）

从多源收集候选信息：

  1. 系统指令（最高优先级）
  2. 记忆系统检索结果
  3. RAG 系统检索结果
  4. 近期对话历史（默认最近5条）
  5. 自定义信息包

各数据源调用均有容错处理，单源失败不影响整体流程。

Select（选择）

基于相关性和新近性进行信息筛选：

  1. 分离系统指令与其他信息
  2. 计算剩余可用 token
  3. 为每个信息包计算综合分数：
    综合分数 = 相关性权重 × 相关性分数 + 新近性权重 × 新近性分数
  4. 按分数降序排序
  5. 贪心选择直至达到 token 上限

相关性计算默认使用 Jaccard 相似度，新近性采用指数衰减模型。

Structure（结构化）

将选中的信息组织为固定模板：

[Role & Policies]    # 角色与行为准则
[Task]              # 当前任务
[Evidence]          # 检索到的证据
[Context]           # 历史对话与相关记忆
[Output]            # 输出要求

Compress（压缩）

当上下文超限时执行兜底压缩：

  • 按分区进行截断
  • 保持结构完整性
  • 优先保留高价值区域

9.3.4 使用示例

# 初始化
builder = ContextBuilder(
    memory_tool=memory_tool,
    rag_tool=rag_tool,
    config=ContextConfig(max_tokens=3000)
)

# 构建上下文
context = builder.build(
    user_query="如何优化Pandas的内存占用?",
    conversation_history=conversation_history,
    system_instructions="你是一位资深的Python数据工程顾问..."
)

9.3.5 最佳实践

  • 根据任务复杂度动态调整 token 预算
  • 生产环境使用向量相似度替代关键词重叠
  • 对不变内容实现缓存机制
  • 记录构建统计信息用于监控
  • 对关键参数进行 A/B 测试

9.4 NoteTool：结构化笔记

9.4.1 设计理念

NoteTool 以 Markdown + YAML 格式存储结构化笔记，适用于：

  • 长期项目追踪
  • 研究任务管理
  • 与 ContextBuilder 配合提供持久化上下文

相比 MemoryTool，NoteTool 更适合项目式任务的结构化管理。

9.4.2 存储格式

每个笔记文件包含：

  • YAML 前置元数据（id、标题、类型、标签、时间戳）
  • Markdown 正文（支持格式化内容）

同时维护 notes_index.json 索引文件，支持快速检索。

9.4.3 核心操作

操作 功能
create 创建笔记
read 读取笔记
update 更新笔记
search 搜索笔记（支持类型、标签过滤）
list 列出笔记
summary 生成统计摘要
delete 删除笔记

9.4.4 与 ContextBuilder 集成

典型集成流程：

  1. 检索相关笔记
  2. 转换为 ContextPacket
  3. 注入上下文构建流程
  4. 根据交互结果自动生成新笔记

9.4.5 最佳实践

  • 合理使用笔记类型：task_state、conclusion、blocker、action、reference
  • 定期清理和归档已完成项目
  • 利用 Git 进行版本控制
  • 设置差异化的相关性分数（blocker > action > conclusion）
  • 支持人机协作，允许手动编辑

9.5 TerminalTool：即时文件系统访问

9.5.1 设计理念与安全机制

TerminalTool 支持智能体按需探索文件系统，实现 JIT 上下文检索。

四层安全机制：

  1. 命令白名单：仅允许只读命令（ls、cat、grep、head、tail 等）
  2. 工作目录限制：仅能访问指定 workspace 及其子目录
  3. 超时控制：默认30秒执行超时
  4. 输出大小限制：默认10MB输出上限

9.5.2 核心功能

命令执行：

  • 在指定工作目录中执行命令
  • 合并标准输出与标准错误
  • 检查返回码并标记异常
  • 截断超量输出

目录导航：

  • 支持 cd 命令切换目录
  • 验证路径合法性（防止目录逃逸）
  • 维护当前工作目录状态

9.5.3 典型应用场景

  • 代码库探索（find、grep、tree）
  • 日志分析（tail、wc、sort、uniq）
  • 数据文件预览（head、cut、wc）

9.5.4 与上下文工程的关系

TerminalTool 使智能体能够：

  • 避免预加载全部文件造成的上下文浪费
  • 根据任务需求精准检索相关信息
  • 通过渐进式探索构建对复杂系统的理解

本章小结

上下文工程是构建稳健智能体的核心技术，通过 GSSC 流水线实现信息的有效管理。ContextBuilder 提供了统一的上下文构建框架，NoteTool 解决了长时程任务的持久化记忆问题，TerminalTool 实现了即时文件系统访问。三者协同工作，构成了完整的上下文工程解决方案。

学习日期：2026-01-19
参考版本：hello-agents==0.2.8

posted @ 2026-07-17 16:50  好像是Cwk  阅读(3)  评论(0)    收藏  举报