wehub-skill-sync
8.5 KiB
Reference: Manus Context Engineering Principles
本技能基于 Manus（2025 年 12 月被 Meta 以 20 亿美元收购的 AI 智能体公司）的上下文工程原则。
Manus 六大原则
原则 1：围绕 KV-Cache 设计
"KV-cache 命中率是生产级 AI 智能体唯一最重要的指标。"
统计：
- 输入与输出 Token 比例约 100:1
- 缓存 Token：$0.30/MTok 对比 未缓存：$3/MTok
- 成本相差 10 倍！
实现方式：
- 保持 Prompt 前缀稳定（单个 Token 的变化就会使缓存失效）
- 系统 Prompt 中不要包含时间戳
- 采用只追加的上下文结构，并配合确定性序列化
原则 2：屏蔽，而非移除
不要动态移除工具（这会破坏 KV-cache）。改用 logit 屏蔽。
最佳实践： 使用一致的操作前缀（例如 browser_、shell_、file_），以便于屏蔽。
原则 3：文件系统作为外部记忆
"Markdown 是我在磁盘上的'工作记忆'。"
公式：
上下文窗口 = 内存（易失、有限）
文件系统 = 磁盘（持久、无限）
压缩必须可恢复：
- 即使丢弃了网页内容，也要保留 URL
- 丢弃文档内容时，保留文件路径
- 绝不能丢失指向完整数据的指针
原则 4：通过复述操控注意力
"在整个任务过程中持续创建和更新 todo.md，将全局计划推入模型最近的注意力范围。"
问题： 大约 50 次工具调用之后，模型会忘记原始目标（"中间迷失"效应）。
解决方案： 在每次决策前重新读取 task_plan.md。目标会出现在注意力窗口中。
上下文开头：[原始目标——很远，已被遗忘]
...大量工具调用...
上下文结尾：[最近读取的 task_plan.md——获得注意力！]
原则 5：保留错误信息
"把错误的弯路留在上下文中。"
原因：
- 带有堆栈跟踪的失败动作能让模型隐式更新认知
- 减少重复犯同样错误
- 错误恢复是"真正智能体行为的清晰信号之一"
原则 6：不要被 Few-Shot 固化
"一致性滋生脆弱性。"
问题： 重复的动作-观察对会导致漂移和幻觉。
解决方案： 引入受控变化：
- 稍微变换措辞
- 不要盲目复制粘贴模式
- 在重复性任务上进行重新校准
三大上下文工程策略
基于 Lance Martin 对 Manus 架构的分析。
策略 1：上下文缩减
压缩：
工具调用有两种表示形式：
├── 完整版：原始工具内容（存储在文件系统中）
└── 精简版：仅保留引用/文件路径
规则：
- 对较旧的工具结果应用压缩
- 保留近期结果的完整内容（以便指导下一步决策）
摘要：
- 在压缩达到收益递减时应用
- 使用完整的工具结果生成
- 创建标准化的摘要对象
策略 2：上下文隔离（多智能体）
架构：
┌─────────────────────────────────┐
│ 规划智能体 │
│ └─ 将任务分配给子智能体 │
├─────────────────────────────────┤
│ 知识管理器 │
│ └─ 审查对话 │
│ └─ 决定文件系统存储 │
├─────────────────────────────────┤
│ 执行子智能体 │
│ └─ 执行分配的任务 │
│ └─ 拥有各自的上下文窗口 │
└─────────────────────────────────┘
关键洞察： Manus 最初使用 todo.md 进行任务规划，但发现大约 33% 的操作都花在更新它上。后来转向由专用规划智能体调用执行子智能体的架构。
策略 3：上下文卸载
工具设计：
- 总共使用不超过 20 个原子函数
- 完整结果存储在文件系统中，而不是上下文中
- 使用
glob和grep进行搜索 - 渐进式披露：只在需要时加载信息
智能体循环
Manus 运行在一个连续的 7 步循环中：
┌─────────────────────────────────────────┐
│ 1. 分析上下文 │
│ - 理解用户意图 │
│ - 评估当前状态 │
│ - 审视最近的观察结果 │
├─────────────────────────────────────────┤
│ 2. 思考 │
│ - 我是否需要更新计划？ │
│ - 下一个合理的操作是什么？ │
│ - 是否存在阻碍？ │
├─────────────────────────────────────────┤
│ 3. 选择工具 │
│ - 选择一个工具 │
│ - 确保参数可用 │
├─────────────────────────────────────────┤
│ 4. 执行操作 │
│ - 工具在沙箱中运行 │
├─────────────────────────────────────────┤
│ 5. 接收观察结果 │
│ - 结果追加到上下文中 │
├─────────────────────────────────────────┤
│ 6. 迭代 │
│ - 返回步骤 1 │
│ - 持续执行直到完成 │
├─────────────────────────────────────────┤
│ 7. 交付结果 │
│ - 将结果发送给用户 │
│ - 附上所有相关文件 │
└─────────────────────────────────────────┘
Manus 创建的文件类型
| 文件 | 用途 | 创建时机 | 更新时机 |
|---|---|---|---|
task_plan.md |
阶段追踪、进度 | 任务开始时 | 完成阶段后 |
findings.md |
发现、决策 | 任何发现之后 | 查看图片/PDF 后 |
progress.md |
会话日志、已完成事项 | 在断点处 | 整个会话期间 |
| 代码文件 | 实现 | 执行前 | 出错后 |
关键约束
- 单操作执行（Manus 2025 原始约束）： 每轮仅限一次工具调用，不并行执行。这记录了 Manus 2025 年沙箱实践的约束。2026 年更新： 现代宿主环境（Claude Code、Codex CLI）支持并行工具调用和子智能体，因此该约束已不再适用。计划文件（而非每轮一次调用的规则）仍然是协调点：并行调用和子智能体通过磁盘上持久的 Markdown 计划文件共享状态。
- 必须制定计划： 智能体必须始终知道：目标、当前阶段、剩余阶段
- 文件即记忆： 上下文 = 易失。文件系统 = 持久。
- 绝不重复失败： 如果某个操作失败，下一步操作必须不同
- 沟通也是一种工具： 消息类型：
info（进度）、ask（阻塞）、result（终止）
Manus 统计数据
| 指标 | 数值 |
|---|---|
| 每次任务平均工具调用次数 | ~50 |
| 输入与输出 Token 比例 | 100:1 |
| 收购价格 | 20 亿美元 |
| 达到 1 亿美元收入用时 | 8 个月 |
| 上线以来的框架重构次数 | 5 次 |
关键语录
"上下文窗口 = 内存（易失、有限）。文件系统 = 磁盘（持久、无限）。所有重要的内容都要写入磁盘。"
"如果操作失败，下一步操作不要与失败操作相同。记录你尝试过的方法。改变策略。"
"错误恢复是真正智能体行为的清晰信号之一。"
"KV-cache 命中率是生产级 AI 智能体唯一最重要的指标。"
"把错误的弯路留在上下文中。"
来源
基于 Manus 官方上下文工程文档： https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus