/references/reference.md

# 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