夜雨聆风你有没有想过，为什么 AI 智能体在长对话中会"走神"？为什么它有时候会忘记你刚才说的重要信息？
答案藏在一个新兴的领域：上下文工程（Context Engineering）。
这不是简单的"提示词优化"，而是一套系统化的方法——在每次模型调用前，如何以可复用、可度量、可演进的方式，拼装并优化输入上下文。
带你理解上下文工程的核心理念，并亲手搭建一个生产级的上下文管理系统。
一、从提示工程到上下文工程
1.1 什么是上下文工程？
提示工程关注"如何写出有效提示"——系统提示的写法、结构化策略、Few-shot 示例等。
上下文工程则更宏观——在推理阶段，如何策划与维护"最优的信息集合（tokens）"，其中不仅包含提示本身，还包含其他会进入上下文窗口的一切信息：
系统指令 工具定义 外部数据（RAG 检索结果） 对话历史 记忆系统的检索结果 MCP（Model Context Protocol）数据
一个循环运行的智能体，会不断产生下一轮推理可能相关的数据，这些信息必须被周期性地提炼。因此，上下文工程的核心在于：从持续扩张的"候选信息宇宙"中，甄别哪些内容应当进入有限的上下文窗口。
1.2 为什么上下文工程重要？
尽管模型的上下文窗口越来越大（从 4K 到 128K 甚至 1M tokens），但我们观察到一个现象：上下文腐蚀（context rot）。
针堆找针（needle-in-a-haystack）类基准揭示：随着上下文窗口中的 tokens 增加，模型从上下文中准确回忆信息的能力反而下降。
为什么会这样？
Transformer 让每个 token 能够与上下文中的所有 token 建立关联，理论上形成 级别的两两注意力关系。随着上下文长度增长，模型对这些两两关系的建模能力会被"拉薄"，从而自然地产生"上下文规模"与"注意力集中度"的张力。
此外，模型的注意力模式来源于训练数据分布——短序列通常比长序列更常见，因此模型对"全上下文依赖"的经验更少。
结论：上下文必须被视作一种有限资源，且具有边际收益递减。就像人类有有限的工作记忆容量一样，LLM 也有一笔"注意力预算"。
二、有效上下文的"解剖学"
在"有限注意力预算"的约束下，优秀的上下文工程目标是：用尽可能少、但高信号密度的 tokens，最大化获得期望结果的概率。
2.1 核心组件
系统提示（System Prompt）
语言清晰、直白，信息层级把握在"刚刚好"的高度 避免两极误区： 过度硬编码：在提示中写入复杂、脆弱的 if-else 逻辑 过于空泛：只给出宏观目标，缺少对期望输出的具体信号 建议分区组织（如 <background_information>、<instructions>、工具指引、输出描述等）
工具（Tools）
职责单一、相互低重叠，接口语义清晰 对错误鲁棒 入参描述明确、无歧义 如果人类工程师都说不准用哪个工具，别指望智能体做得更好
示例（Few-shot）
始终推荐提供示例，但不建议把"所有边界条件"的罗列一股脑塞进提示 精挑细选一组多样且典型的示例，直接画像"期望行为" 好的示例胜过千言万语
2.2 智能体式搜索：从预加载到即时检索
传统 RAG：推理前一次性检索（embedding 检索）
现代智能体：及时（Just-in-time, JIT）上下文
后者不再预先加载所有相关数据，而是维护轻量化引用（文件路径、存储查询、URL 等），在运行时通过工具动态加载所需数据。
优势：
模型可以撰写针对性查询 缓存必要结果 用 head/tail之类的命令分析大体量数据——无需把整块数据一次性塞入上下文引用的元数据本身也能帮助精化行为：目录层级、命名约定、时间戳等
权衡：
运行时探索往往比预计算检索更慢 需要有"主见"的工程设计来确保模型拥有正确的工具与启发式
混合策略更有效：前置加载少量"高价值"上下文以保证速度，然后允许智能体按需继续自主探索。
三、面向长时程任务的三大策略
长时程任务要求智能体在超出上下文窗口的长序列行动中，仍能保持连贯性、上下文一致与目标导向。
3.1 压缩整合（Compaction）
定义：当对话接近上下文上限时，对其进行高保真总结，并用该摘要重启一个新的上下文窗口。
实践：
让模型压缩并保留架构性决策、未解决缺陷、实现细节 丢弃重复的工具输出与噪声 新窗口携带压缩摘要 + 最近少量高相关工件
调参建议：
先优化召回（确保不遗漏关键信息） 再优化精确度（剔除冗余内容）
3.2 结构化笔记（Structured note-taking）
定义：智能体以固定频率将关键信息写入上下文外的持久化存储，在后续阶段按需拉回。
价值：
以极低的上下文开销维持持久状态与依赖关系 维护 TODO 列表、项目 NOTES.md、关键结论/依赖/阻塞项的索引 跨数十次工具调用与多轮上下文重置仍能保持进度与一致性
示例：
# 记录任务状态notes.run({"action": "create","title": "重构项目 - 第一阶段","content": "已完成数据模型层的重构,测试覆盖率达到85%。","note_type": "task_state","tags": ["refactoring", "phase1"]})# 记录阻塞点notes.run({"action": "create","title": "依赖冲突问题","content": "发现某些第三方库版本不兼容,需要解决。","note_type": "blocker","tags": ["dependency", "urgent"]})3.3 子代理架构（Sub-agent architectures）
思想：由主代理负责高层规划与综合，多个专长子代理在"干净的上下文窗口"中各自深挖、调用工具并探索，最后仅回传凝练摘要（常见 1,000–2,000 tokens）。
好处：
实现关注点分离 庞杂的搜索上下文留在子代理内部，主代理专注于整合与推理 适合需要并行探索的复杂研究/分析任务
四、HelloAgents 的实践：ContextBuilder
4.1 设计目标
ContextBuilder 的设计理念是"简单高效"，统一以"相关性+新近性"的分数进行选择。
四大目标：
统一入口：将"获取(Gather)- 选择(Select)- 结构化(Structure)- 压缩(Compress)"抽象为可复用流水线 稳定形态：输出固定骨架的上下文模板，便于调试、A/B 测试与评估 预算守护：在 token 预算内尽量保留高价值信息 最小规则：不引入来源/优先级等分类维度，避免复杂度增长
4.2 核心数据结构
ContextPacket：候选信息包
@dataclassclassContextPacket: content: str # 信息内容 timestamp: datetime # 时间戳 token_count: int # Token 数量 relevance_score: float = 0.5# 相关性分数(0.0-1.0) metadata: Optional[Dict] = None# 可选的元数据ContextConfig：配置管理
@dataclassclassContextConfig: 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# 相关性权重4.3 GSSC 流水线详解
（1）Gather：多源信息汇集
从多个来源汇集候选信息：
def_gather(self, user_query, conversation_history, system_instructions, custom_packets): packets = []# 1. 添加系统指令(最高优先级)if system_instructions: packets.append(ContextPacket( content=system_instructions, relevance_score=1.0, # 系统指令始终保留 metadata={"type": "system_instruction", "priority": "high"} ))# 2. 从记忆系统检索相关记忆if self.memory_tool: memory_results = self.memory_tool.run({"action": "search", "query": user_query}) packets.extend(self._parse_memory_results(memory_results))# 3. 从 RAG 系统检索相关知识if self.rag_tool: rag_results = self.rag_tool.run({"action": "search", "query": user_query}) packets.extend(self._parse_rag_results(rag_results))# 4. 添加对话历史(仅保留最近的 N 条)if conversation_history: recent_history = conversation_history[-5:]for msg in recent_history: packets.append(ContextPacket(content=f"{msg.role}: {msg.content}", ...))# 5. 添加自定义信息包if custom_packets: packets.extend(custom_packets)return packets（2）Select：智能信息选择
根据相关性和新近性对候选信息进行评分和选择：
def_select(self, packets, user_query, available_tokens):# 1. 分离系统指令和其他信息 system_packets = [p for p in packets if p.metadata.get("type") == "system_instruction"] other_packets = [p for p in packets if p.metadata.get("type") != "system_instruction"]# 2. 为其他信息计算综合分数 scored_packets = []for packet in other_packets: relevance = self._calculate_relevance(packet.content, user_query) recency = self._calculate_recency(packet.timestamp)# 综合分数 = 相关性权重 × 相关性 + 新近性权重 × 新近性 combined_score = ( self.config.relevance_weight * relevance + self.config.recency_weight * recency )if relevance >= self.config.min_relevance: scored_packets.append((combined_score, packet))# 3. 按分数降序排序 scored_packets.sort(key=lambda x: x[0], reverse=True)# 4. 贪心选择:按分数从高到低填充,直到达到 token 上限 selected = system_packets.copy() current_tokens = sum(p.token_count for p in system_packets)for score, packet in scored_packets:if current_tokens + packet.token_count <= available_tokens: selected.append(packet) current_tokens += packet.token_countelse:breakreturn selected评分算法的关键：
相关性计算：使用 Jaccard 相似度（简单实现）或向量相似度（生产环境） 新近性计算：指数衰减模型，24小时内保持高分，之后逐渐衰减
（3）Structure：结构化输出
将选中的信息组织成结构化的上下文模板：
def_structure(self, selected_packets, user_query):# 按类型分组 system_instructions = [] evidence = [] context = []for packet in selected_packets: packet_type = packet.metadata.get("type", "general")if packet_type == "system_instruction": system_instructions.append(packet.content)elif packet_type in ["rag_result", "knowledge"]: evidence.append(packet.content)else: context.append(packet.content)# 构建结构化模板 sections = []if system_instructions: sections.append("[Role & Policies]\n" + "\n".join(system_instructions)) sections.append(f"[Task]\n{user_query}")if evidence: sections.append("[Evidence]\n" + "\n---\n".join(evidence))if context: sections.append("[Context]\n" + "\n".join(context)) sections.append("[Output]\n请基于以上信息,提供准确、有据的回答。")return"\n\n".join(sections)输出示例：
[Role & Policies]你是一位资深的Python数据工程顾问。[Task]如何优化Pandas的内存占用?[Evidence]Pandas内存优化的核心策略包括:1. 使用合适的数据类型(如category代替object)2. 分块读取大文件---数据类型优化可以显著减少内存占用。[Context]user: 我正在开发一个数据分析工具assistant: 很好!数据分析工具通常需要处理大量数据。记忆: 用户正在开发数据分析工具,使用Python和Pandas[Output]请基于以上信息,提供准确、有据的回答。（4）Compress：兜底压缩
对超限上下文进行压缩处理：
def_compress(self, context, max_tokens): current_tokens = self._count_tokens(context)if current_tokens <= max_tokens:return context # 无需压缩# 分区压缩:保持结构完整性 sections = context.split("\n\n") compressed_sections = [] current_total = 0for section in sections: section_tokens = self._count_tokens(section)if current_total + section_tokens <= max_tokens: compressed_sections.append(section) current_total += section_tokenselse: remaining_tokens = max_tokens - current_totalif remaining_tokens > 50: truncated = self._truncate_text(section, remaining_tokens) compressed_sections.append(truncated + "\n[... 内容已压缩 ...]")breakreturn"\n\n".join(compressed_sections)4.4 完整使用示例
from hello_agents.context import ContextBuilder, ContextConfigfrom hello_agents.tools import MemoryTool, RAGTool# 1. 初始化工具memory_tool = MemoryTool(user_id="user123")rag_tool = RAGTool(knowledge_base_path="./knowledge_base")# 2. 创建 ContextBuilderconfig = 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数据工程顾问。")print(context)五、NoteTool：结构化笔记工具
NoteTool 是为"长时程任务"提供的结构化外部记忆组件。它以 Markdown 文件作为载体，头部使用 YAML 前置元数据记录关键信息。
5.1 为什么需要 NoteTool？
MemoryTool 主要关注对话式记忆——短期工作记忆、情景记忆和语义记忆。
NoteTool 填补了项目式任务的 gap：
结构化记录：Markdown + YAML 格式，既适合机器解析，也方便人类阅读 版本友好：纯文本格式，天然支持 Git 等版本控制系统 低开销：无需复杂的数据库操作 灵活分类：通过 type和tags灵活组织笔记
5.2 笔记文件格式
每个笔记都是一个独立的 .md 文件：
---id: note_20250119_153000_0title: 项目进展 - 第一阶段type: task_statetags: [refactoring, phase1, backend]created_at: 2025-01-19T15:30:00updated_at: 2025-01-19T15:30:00---# 项目进展 - 第一阶段## 完成情况已完成数据模型层的重构,主要改动包括:1. 统一了实体类的命名规范2. 引入了类型提示,提升代码可维护性3. 优化了数据库查询性能## 测试覆盖- 单元测试覆盖率: 85%- 集成测试覆盖率: 70%## 下一步计划1. 重构业务逻辑层2. 解决依赖冲突问题5.3 核心操作
NoteTool 提供了七个核心操作：
| create | ||
| read | ||
| update | ||
| search | ||
| list | ||
| summary | ||
| delete |
使用示例：
from hello_agents.tools import NoteToolnotes = NoteTool(workspace="./project_notes")# 创建笔记note_id = notes.run({"action": "create","title": "重构项目 - 第一阶段","content": "已完成数据模型层的重构,测试覆盖率达到85%。","note_type": "task_state","tags": ["refactoring", "phase1"]})# 搜索笔记results = notes.run({"action": "search","query": "重构","limit": 5})# 列出特定类型的笔记blockers = notes.run({"action": "list","note_type": "blocker","limit": 10})5.4 与 ContextBuilder 的深度集成
NoteTool 的真正威力在于与 ContextBuilder 的配合使用：
classProjectAssistant(SimpleAgent):defrun(self, user_input: str) -> str:# 1. 从 NoteTool 检索相关笔记 relevant_notes = self.note_tool.run({"action": "search","query": user_input,"limit": 3 })# 2. 将笔记转换为 ContextPacket note_packets = []for note in relevant_notes: note_packets.append(ContextPacket( content=note['content'], timestamp=note['updated_at'], token_count=self._count_tokens(note['content']), relevance_score=0.7, metadata={"type": "note", "note_type": note['type']} ))# 3. 构建上下文时传入笔记 context = self.context_builder.build( user_query=user_input, custom_packets=note_packets, ... )# 4. 调用 LLM response = self.llm.invoke(context)return response六、小结
上下文工程是构建强健智能体的关键技术，它解决了三个核心问题：
| 上下文腐蚀 | ||
| 长时程任务 | ||
| 信息过载 |
HelloAgents 的上下文工程实践：
ContextBuilder：统一的上下文管理流水线，自动处理信息的收集、筛选和组织 NoteTool：轻量级的结构化笔记工具，支持长期项目追踪 混合策略：结合预加载和即时检索，平衡速度和灵活性
设计哲学的核心：
简单高效：统一以"相关性+新近性"评分，避免过度复杂化 结构化输出：固定的上下文模板，便于调试和优化 预算守护：在有限的 token 预算内，最大化信息价值
当你理解了上下文工程的核心理念，就能构建出真正"聪明"的智能体——它们不会被信息淹没，而是能够精准地聚焦于最相关的上下文，做出更准确的决策。
参考资料：
Anthropic, Prompt engineering vs Context engineering, 2024
