wehub-skill-sync
219 lines
8.5 KiB
Markdown
219 lines
8.5 KiB
Markdown
# 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
|