上下文工程

原文：Hello-Agents · 第九章 上下文工程 · 在线阅读

一句话

上下文工程(Context Engineering)关注"在每次模型调用前，如何以可复用、可度量、可演进的方式，拼装并优化输入上下文"，从而提升正确性、鲁棒性与效率。

什么时候翻这页

当需要构建能在真实复杂场景中稳定"思考"与"行动"的智能体，且已有记忆系统与RAG但仍需系统性地管理上下文时。

核心概念

• 上下文工程(Context Engineering)：在每次模型调用前，以可复用、可度量、可演进的方式拼装并优化输入上下文
• 上下文腐蚀(Context Rot)：随着上下文窗口中的tokens增加，模型从上下文中准确回忆信息的能力反而下降的现象
• GSSC流水线：Gather(收集)-Select(选择)-Structure(结构化)-Compress(压缩)的上下文构建流程
• 渐进式披露(Progressive Disclosure)：每一步交互产生新的上下文，反过来指导下一步决策的认知模式
• 智能体式搜索：维护轻量化引用，在运行时通过工具动态加载所需数据

怎么做

ContextBuilder实现

1. Gather阶段：从多个来源汇集候选信息，包括系统指令、记忆系统检索、RAG系统检索、对话历史和自定义信息包
2. Select阶段：根据相关性和新近性对候选信息进行评分和选择，使用贪心算法在token预算内选择最有价值的信息
3. Structure阶段：将选中的信息组织成结构化的上下文模板，包括[Role & Policies]、[Task]、[Evidence]、[Context]、[Output]等分区
4. Compress阶段：对超限上下文进行压缩处理，保持结构完整性

长时程任务管理策略

1. 压缩整合(Compaction)：当对话接近上下文上限时，进行高保真总结，用摘要重启新上下文窗口
2. 结构化笔记(Structured note-taking)：智能体以固定频率将关键信息写入上下文外的持久化存储
3. 子代理架构(Sub-agent architectures)：主代理负责高层规划与综合，专长子代理在"干净的上下文窗口"中各自深挖

工具集成

1. NoteTool：支持创建、搜索、更新笔记，使用Markdown+YAML混合格式
2. TerminalTool：提供安全的文件系统操作能力，支持命令执行和文件访问
3. ContextBuilder：整合记忆系统和RAG系统，提供统一的上下文管理接口

命令 / 代码速查

# 安装本章对应的版本
pip install "hello-agents[all]==0.2.8"

# ContextPacket：候选信息包
@dataclass
class ContextPacket:
    """候选信息包

    Attributes:
        content: 信息内容
        timestamp: 时间戳
        token_count: Token 数量
        relevance_score: 相关性分数(0.0-1.0)
        metadata: 可选的元数据
    """
    content: str
    timestamp: datetime
    token_count: int
    relevance_score: float = 0.5
    metadata: Optional[Dict[str, Any]] = None

# ContextConfig：配置管理
@dataclass
class ContextConfig:
    """上下文构建配置

    Attributes:
        max_tokens: 最大 token 数量
        reserve_ratio: 为系统指令预留的比例(0.0-1.0)
        min_relevance: 最低相关性阈值
        enable_compression: 是否启用压缩
        recency_weight: 新近性权重(0.0-1.0)
        relevance_weight: 相关性权重(0.0-1.0)
    """
    max_tokens: int = 3000
    reserve_ratio: float = 0.2
    min_relevance: float = 0.1
    enable_compression: bool = True
    recency_weight: float = 0.3
    relevance_weight: float = 0.7

# 基础使用ContextBuilder
from hello_agents.context import ContextBuilder, ContextConfig
from hello_agents.tools import MemoryTool, RAGTool
from hello_agents.core.message import Message
from datetime import datetime

# 1. 初始化工具
memory_tool = MemoryTool(user_id="user123")
rag_tool = RAGTool(knowledge_base_path="./knowledge_base")

# 2. 创建 ContextBuilder
config = ContextConfig(
    max_tokens=3000,
    reserve_ratio=0.2,
    min_relevance=0.2,
    enable_compression=True
)

builder = ContextBuilder(
    memory_tool=memory_tool,
    rag_tool=rag_tool,
    config=config
)

# 3. 构建上下文
context = builder.build(
    user_query="如何优化Pandas的内存占用?",
    conversation_history=conversation_history,
    system_instructions="你是一位资深的Python数据工程顾问。你的回答需要:1) 提供具体可行的建议 2) 解释技术原理 3) 给出代码示例"
)

# 使用TerminalTool探索代码库
terminal = TerminalTool(workspace="./codebase")

# 统计代码行数
print(terminal.run({"command": "find . -name '*.py' -exec wc -l {} + | tail -n 1"}))

# 查找所有TODO注释
print(terminal.run({"command": "grep -rn 'TODO' --include='*.py'"}))

# 查看函数实现
print(terminal.run({"command": "sed -n '/def process_data/,/^def /p' src/processor.py | head -n -1"}))

与 Python / Claude Code 手册的联系

• 上下文工程扩展了Python中的提示工程概念，关注如何在有限token预算下优化LLM输入
• ContextBuilder的实现体现了Python中数据类、类型注解和面向对象设计的最佳实践
• TerminalTool的安全机制与Python中的文件路径验证和权限检查相关
• NoteTool的结构化笔记设计借鉴了Python中的数据序列化技术

初学者易错点

1. 过度硬编码系统提示：在提示中写入复杂、脆弱的if-else逻辑，长期维护成本高、易碎
2. 过于空泛的系统提示：只给出宏观目标与泛化指引，缺少对期望输出的具体信号
3. 臃肿工具集：功能边界模糊，导致"选哪个工具"这一决策本身就含混不清
4. 一次性加载所有上下文：对于大型代码库，一次性加载所有文件内容会导致上下文窗口溢出
5. 忽视上下文腐蚀：随着上下文长度增长，模型对信息的回忆能力下降，需要定期压缩和总结

相关词条

• 提示工程(Prompt Engineering)
• 记忆系统(Memory System)
• RAG(检索增强生成)
• 智能体(Agent)
• 工具调用(Tool Calling)