跳到主要内容

1 篇博文 含有标签「MCP」

查看所有标签

上下文工程与 Agent 笔记

· 阅读需 14 分钟

本文目的:替换 上下文工程异常问题总结 原笔记(原 557 行 20 类问题,内容质量尚可但缺 Prompt Engineering vs Context Engineering 边界、Manus 经验、Agent 框架对比、Memory 系统、MCP,已删除)。覆盖 2026 年工业级 Context Engineering + Agent 全栈。 配套笔记:RAG工业方案笔记、Prompt工程笔记、Rerank笔记 配套 demo:example/llm-demo/04_rag_evaluation

阅读地图​

§主题一句话定位
1Prompt Engineering vs Context EngineeringKarpathy 定义 + 4 维度对比
2Context Engineering 四大策略Write / Select / Compress / Isolate
3Manus 六条工程经验KV-cache / Mask / 文件系统 / Recitation / 保留错误 / 反模式化
4Anthropic Building Effective Agents5 种 Workflow + Tool = ACI + 透明性 > 智能
5Agent 框架对比8 大框架(LangGraph / CrewAI / AutoGen / Smolagents / Letta / Pydantic AI / Mastra / Agno)
6记忆系统Mem0 / Letta / Zep 对比 + 向量 vs 结构化
7上下文工程常见问题(精炼原 20 类)Context Rot / Pollution / Missing / Conflict / Overload / Lost-in-the-Middle 等
8MCP 与工具调用Model Context Protocol 生态 + 与 Function Calling 差异
9来源链接全部 GitHub 链接按章节分组

1. Prompt Engineering vs Context Engineering​

1.1 Karpathy 的定义​

"Context engineering is the delicate art and science of filling the context window with just the right information for the next step." — Andrej Karpathy(2025)

Cognition(Devin 团队)补充:"构建 AI agent 工程师的 #1 工作"。

1.2 4 维度对比​

维度Prompt EngineeringContext Engineering
关注对象system / user 指令本身整个 context window:instructions + knowledge + tools + 历史 + 反馈
时间尺度写一次每次推理都在动态管理
典型动作改写 prompt、加 few-shotwrite / select / compress / isolate 四类策略
适用对象单次 LLM 调用长链路 Agent(Manus 平均 50 次工具调用)

1.3 演进关系​

Prompt Engineering(写指令)
↓
Context Engineering(管理整个 context window)
↓
Agent Engineering(编排多步推理 + 工具调用 + 记忆 + 多 agent 协作)

结论:Prompt Engineering 是基础;Context Engineering 是中间层;Agent Engineering 是工业级落地的全集。三者层层递进,不是替代关系。


2. Context Engineering 四大策略(LangChain 总结)​

参考:Context Engineering for Agents

2.1 Write(写)​

把信息写进 context window,让模型"看到"。

手段作用何时用
Scratchpad(轮内笔记)Agent 在每步写 notes,沉淀当前推理ReAct / Plan-and-Execute
Memory(跨会话笔记)长期记忆用户偏好 / 项目状态ChatGPT / Cursor / Windsurf 都用
todo.md recitation每步重写 todo,把目标朗诵到 context 末端Manus 风格长任务
文件系统当 context128K 不够用 → 文件系统 = 无限、持久、可操作Manus / Claude Code

2.2 Select(选)​

从大量候选中选出当前需要的,喂给模型。

手段作用数据
Tool-RAG工具太多时,先 RAG 出当前需要的工具LangChain 实测:工具选择准确率提升 3×
Memory retrieval从长期记忆库 RAG 出相关记忆Mem0 / Letta
Context RAG从文档库 RAG 出相关 contextRAG 完整链路
Episodic / Procedural / Semantic memory三类记忆分层检索Letta / Zep

2.3 Compress(压)​

当 context 接近上限时,压缩信息以腾出空间。

手段作用何时用
Summarization长对话压缩成摘要Claude Code 在 95% 容量自动 compact
Trimming直接裁掉不重要的历史 token滑动窗口
LLM-based compression用 LLM 重新组织 context关键信息提取
Token-level pruning按 attention 权重剪枝实验性

2.4 Isolate(隔)​

把上下文隔离到不同 agent / sandbox,避免互相污染。

手段作用何时用
Multi-agent主 agent + sub-agent,每个只看自己的 contextAnthropic research 用并行 sub-agent
SandboxAgent 工具调用隔离在 sandboxHuggingFace CodeAgent 用 e2b
Per-node selectionLangGraph 每个 node 独立选择 context复杂 workflow
Thread state每个 thread 独立 stateLangGraph thread

2.5 四大策略与 LangGraph / Claude Code 的对应​

策略LangGraph 实现Claude Code 实现
Writethread state + 持久化scratchpad + memory
Selectper-node selectiontool-RAG
Compressbuilt-in 摘要 / trimming95% 自动 compact
Isolatemulti-agent / sandboxsub-agent

3. Manus 六条工程经验​

参考:Manus: Context Engineering for AI Agents

3.1 KV-cache 设计(最重要的指标)​

缓存命中率 = 生产 agent 最重要指标

指标数值
Manus 平均输入输出比100:1
Cached input(Claude Sonnet)$0.30 / MTok
Uncached input$3 / MTok
价格差10×

核心原则:

  • 稳定 prompt prefix → 提高 cache 命中率
  • 避免在 prompt 中插入时间戳 / 随机 ID(破坏 cache)
  • 把可变部分放在 prompt 末尾

3.2 Mask 而不是 Remove​

动态增删 tool 会废掉 KV-cache。改用:

  • State machine:固定 tool 列表,通过状态控制是否可用
  • Logit masking:在生成阶段 mask 掉非法 token
  • Response prefill:assistant 消息前缀引导生成方向

3.3 文件系统当 Context​

  • 128K 不够用 → 文件系统 = 无限、持久、可操作的外部记忆
  • Agent 可以 read / write / search 文件,突破 context window 限制
  • Claude Code / Manus / Devin 都重度依赖文件系统

3.4 Recitation 对抗注意力漂移​

  • 每步重写 todo.md,把目标朗诵到 context 末端
  • 防止"lost in the middle"——长 context 末尾信息更容易被关注
  • 与 Anthropic 的 extended thinking 同源

3.5 保留错误​

删除失败记录 = 抹掉模型需要用来纠错的证据

  • 错误日志、stacktrace、failed patches 都要保留
  • Agent 需要"知道自己哪里错了"才能调整
  • 完整 DECISIONS.md / FAILED_ATTEMPTS.md / KNOWN_ISSUES.md

3.6 不要 Few-shot 出模式化​

  • 注入结构化变化(不同序列化、不同措辞、轻微噪声)打破模仿
  • 否则模型会机械模仿示例,失去泛化能力
  • 与 Anthropic 原则"示例胜于描述"形成互补

4. Anthropic Building Effective Agents​

参考:Building Effective Agents

4.1 Workflow > Agent​

能用 workflow 解决的,就不要上 Agent。

5 种 Workflow(按复杂度递增):

Workflow模式何时用
Prompt chaining串行:步骤 1 → 步骤 2 → ... → 步骤 N流水线任务,每步确定性强
Routing分类后分流到不同子流程多类型 query 分类处理
Parallelization多任务并行 → 聚合结果多个独立子问题
Orchestrator-workers主 agent 拆解 → 多 worker 并行 → 聚合复杂任务并行处理
Evaluator-optimizer生成 → 评分 → 反馈 → 重生成答案质量优先场景

4.2 Tool = ACI(Agent-Computer Interface)​

Tool 描述要像产品 docstring,不是 API 签名。

维度差的 tool 描述好的 tool 描述
签名get_user(id)get_user(id: str) → User
示例无get_user("u_123") → User(name="李雷", age=30)
边界无"id 必须是 string,若用户不存在抛 NotFoundError"
错误处理无"返回的 User 可能为 None,调用方需检查"
Poka-yoke(防呆)无"id 不能为空字符串,否则抛 ValueError"

4.3 透明性 > 智能​

  • 让 agent 把计划显式写出来,用户能看见
  • 不要让 agent 在暗处决策
  • Claude Code 的 todo list / Manus 的 todo.md 都是这个原则的体现

4.4 Tool 投资回报率​

投资 tool 描述和工具测试的回报率,比调 prompt 高。

  • 调 prompt 提升 510%,调 tool 描述提升 2050%
  • 每个 tool 都要有单元测试 + 集成测试
  • Anthropic 建议把 tool 视为产品来打磨

5. Agent 框架对比​

5.1 8 大框架​

框架仓库Stars最新版本定位何时用
LangGraphlangchain-ai/langgraph—持续发布LangChain 主力 stateful graph;thread state + checkpoint复杂 Agent + 多步推理
CrewAIcrewAIInc/crewAI—持续发布Role-playing 多 agent 协作(Captain / Engineer / Researcher)多 agent 角色扮演场景
AutoGenmicrosoft/autogen—v0.4+(重写后)Microsoft 出品;群聊式 multi-agent研究 / 多 agent 群聊
Smolagentshuggingface/smolagents—持续发布HuggingFace 出品;极简 + code agent + sandbox (e2b)轻量 code agent
Letta(原 MemGPT)letta-ai/letta—持续发布带长期记忆的 agent;core memory + archival memory需要持久记忆的 agent
Pydantic AIpydantic/pydantic-ai—持续发布Pydantic 官方;FastAPI 风格;强类型Python 后端 + 强类型
Mastramastra-ai/mastra—持续发布TypeScript Agent 框架;workflow + RAG + MCPNode.js / TS 技术栈
Agno(原 Fixpoint)agno-agi/agno—持续发布高性能多模态 agent;速度比 LangGraph 快 10×高性能 + 多模态场景

5.2 各框架核心差异​

框架核心抽象多 agent记忆系统Tool 生态学习曲线
LangGraphStateGraph + Node + Edge✅ subgraph外部(MemoryStore / Zep)LangChain 全套中(要理解 graph 概念)
CrewAICrew + Agent + Task✅ 内建(role-based)外部自定义 + LangChain低(role 直观)
AutoGenUserProxyAgent + AssistantAgent✅ 内建(群聊)外部自定义中(要理解群聊协议)
SmolagentsCodeAgent + Tool⚠️ 简单无(自带 file system)自定义低(极简)
LettaAgent + Memory Blocks✅ 内建✅ 内建(core + archival)自定义中(记忆模型特殊)
Pydantic AIAgent + Deps + Result⚠️ 简单外部自定义 + MCP低(Pydantic 风格)
MastraAgent + Workflow + Tool✅ 内建外部MCP + 自定义低(TS 友好)
AgnoAgent + Team + Workflow✅ 内建(Team)外部MCP + 自定义中

5.3 选型决策​

场景推荐
Python + LangChain 生态LangGraph(首选)
多 agent 角色扮演CrewAI(直观)
群聊式 multi-agentAutoGen(学术 / 研究)
轻量 code agentSmolagents(极简)
需要长期记忆Letta(自带 memory)
强类型 + FastAPI 后端Pydantic AI
TypeScript / Node.jsMastra
高性能 + 多模态Agno

6. 记忆系统​

6.1 三大记忆框架对比​

框架仓库核心机制何时用
Mem0mem0ai/mem0向量 + 结构化双层记忆;自动 extract / update / delete通用 agent 记忆;生产稳定
Letta(原 MemGPT)letta-ai/lettaCore memory(in-context)+ Archival memory(向量);core memory 会自动压缩 + 滚动长对话 + 角色一致性
Zepgetzep/zep生产级长期记忆服务;Graphiti 时序知识图谱 + 语义搜索企业级 + 多用户记忆

6.2 向量记忆 vs 结构化记忆​

维度向量记忆结构化记忆
存储Embedding + metadata表 / KV / 知识图谱
检索相似度精确查询 / 关系查询
可解释性低(黑盒)高(可读)
更新成本中(重建索引)低(直接改)
适用场景模糊匹配 / 语义搜索精确状态 / 关系推理

2026 主流:向量 + 结构化双层(Mem0 模式)。语义记忆走向量,状态 / 关系走结构化。

6.3 Memory 设计模式​

  • Tier 1:Core / Working Memory:放 context window 内;用户偏好、当前任务状态
  • Tier 2:Episodic Memory:历史事件;按时间序列存储
  • Tier 3:Semantic Memory:事实知识;走向量 RAG
  • Tier 4:Procedural Memory:技能 / 工具调用模板

7. 上下文工程常见问题(精炼原 20 类)​

7.1 核心问题清单(按影响排序)​

#问题核心含义解决方案
1Context Rot 上下文腐烂上下文长期积累后变旧、变乱、变矛盾定期 compact;维护 CURRENT_STATE.md
2Context Pollution 上下文污染错误、无关、过期信息进入上下文输入过滤 + 来源标注
3Context Missing 上下文缺失模型没拿到完成任务所需信息提供 SPEC.md + DATABASE_SCHEMA.md 等结构化文档
4Context Conflict 上下文冲突多个信息源互相矛盾明确优先级:用户最新指令 > CURRENT_STATE.md > SPEC.md > README > 历史对话
5Context Overload 上下文过载信息太多,模型有效利用能力下降任务级裁剪 + 摘要 + 分层
6Lost in the Middle长上下文中间信息被忽略关键信息放开头 / 末尾;用 XML tags 标记
7State Drift 状态漂移模型理解和真实项目状态不一致Agent 重新扫描文件 + git worktree 隔离
8Requirement Drift 需求漂移实现逐渐偏离最初目标维护 requirements.md / out_of_scope.md / change_log.md
9RAG Pollution 检索污染检索到错误或过期资料区分 docs/archived 与 docs/current + 过滤
10Summary Distortion 摘要失真长上下文压缩后丢失关键约束人工校验摘要 + 保留原始 + 元数据标记
11Tool-State Desync 工具状态不同步Agent 看到的文件/分支/环境和真实执行环境不一致patch 验证 + git worktree + 状态文件
12Memory Pollution 记忆污染长期记忆保存了不再准确的信息记忆加 TTL + 定期审计 + 来源标注
13Prompt Bloat Prompt 膨胀不断往 prompt 加规则,最后臃肿定期清理 + 分场景 prompt + 动态加载
14Format Collapse 格式崩坏上下文复杂后开始破坏格式结构化输出(Instructor)+ schema 校验
15Task Boundary Leakage 任务边界失控模型把当前任务以外的事情也一起做明确 Allowed Changes / Forbidden Changes
16Source of Truth Missing 事实源不明确没有告诉模型哪个文件是事实源明确优先级:CURRENT_STATE.md > SPEC.md > ...
17Failed Attempt Residue 历史失败残留之前失败的实现路径留在上下文里,模型重复尝试维护 DECISIONS.md / FAILED_ATTEMPTS.md
18Multi-Agent Context Inconsistency 多 Agent 上下文不一致多 agent 协作时各自拿到的上下文不一致共享状态文件 + 主 agent 同步
19Instruction Hierarchy Confusion 指令层级混乱模型不知道哪些指令优先级最高明确规则:安全 > 用户最新 > spec > 任务 > 历史
20Implicit Assumption Accumulation 隐式假设累积模型在没有确认的情况下做了假设,后续沿用假设必须落到 spec 文件,不允许隐式

7.2 核心原则​

不要依赖对话历史维持项目状态,要把项目状态沉淀到结构化文档里,并明确事实源、优先级、当前任务和变更记录。


8. MCP 与工具调用​

8.1 MCP 概述​

Model Context Protocol(MCP) 是 Anthropic 2024 年开源的开放标准,让 LLM 应用与外部工具 / 数据源标准化连接。

项目信息数值
发布时间2024-11
当前版本持续演进(2026 已是事实标准)
官方 server 数100+
生态 server 数1000+(社区贡献)
支持客户端Claude Desktop / Claude Code / Cursor / Windsurf / Cline / Continue / ...

8.2 MCP vs OpenAI Function Calling vs Anthropic Tool Use​

维度OpenAI Function CallingAnthropic Tool UseMCP
定位模型能力模型能力协议标准
范围单次调用单次调用跨工具、跨应用、跨模型
生态OpenAI 独占Anthropic 独占开放,任何人都能实现 server/client
Tool 定义JSON SchemaJSON SchemaJSON Schema + MCP 协议
状态管理无无✅ session / progress / cancellation
多模态⚠️ 部分⚠️ 部分✅ 完整支持

结论:MCP 是工业级 Tool Use 的标准协议,2026 年已成为事实标准。

8.3 MCP 生态(2026)​

类别代表 server
文件 / 代码Filesystem / Git / GitHub / GitLab
数据库PostgreSQL / SQLite / MySQL / MongoDB
搜索Brave Search / Tavily / Google
协作Slack / Notion / Linear / Jira / Confluence
云AWS / GCP / Azure / Cloudflare
浏览器Playwright / Puppeteer
AI / MLHuggingFace / Replicate
生产工具Sentry / Datadog / Grafana

8.4 MCP 适用场景​

场景是否用 MCP
Claude Desktop / Claude Code 集成第三方工具✅ 强烈推荐
多模型统一接入一套工具✅ 强烈推荐
企业内部工具标准化✅ 强烈推荐
简单一次性工具调用❌ 直接用 Function Calling
OpenAI-only 场景❌ 用 Function Calling

9. 来源链接(按章节分组)​

9.1 Context Engineering 概念​

9.2 Agent 框架​

9.3 记忆系统​

9.4 MCP​

9.5 历史归档​

  • 原 上下文工程异常问题总结.md(项目根目录)已删除,核心 20 类问题提炼到本笔记 §7

标签:#agent #mcp #prompt-engineering