Planning With Files

使用文件进行规划

像 Manus 一样工作：使用持久化的 markdown 文件作为你的"磁盘工作记忆"。

快速开始

在任何复杂任务之前：

1. 在工作目录中创建 `task_plan.md` 2. 定义阶段，使用复选框 3. 每个阶段后更新 - 标记 [x] 并更改状态 4. 决策前读取 - 刷新注意力窗口中的目标

三文件模式

对于每个非平凡任务，创建三个文件：

核心工作流

循环 1：创建包含目标和阶段的 task_plan.md
循环 2：研究 → 保存到 notes.md → 更新 task_plan.md
循环 3：读取 notes.md → 创建交付物 → 更新 task_plan.md
循环 4：交付最终输出

详细循环说明

每次主要操作前：

Read task_plan.md  # 刷新注意力窗口中的目标

每个阶段后：

Edit task_plan.md  # 标记 [x]，更新状态

存储信息时：

Write notes.md     # 不要塞满上下文，存储到文件中

task_plan.md 模板

对于任何复杂任务，首先创建此文件：

# 任务计划：[简要描述]

## 目标
[一句话描述最终状态]

## 阶段
- [ ] 阶段 1：规划和设置
- [ ] 阶段 2：研究/收集信息
- [ ] 阶段 3：执行/构建
- [ ] 阶段 4：审查和交付

## 关键问题
1. [需要回答的问题]
2. [需要回答的问题]

## 已做出的决策
- [决策]：[理由]

## 遇到的错误
- [错误]：[解决方案]

## 状态
**当前处于阶段 X** - [我现在正在做的事情]

notes.md 模板

用于研究和发现：

# 笔记：[主题]

## 来源

### 来源 1：[名称]
- URL：[链接]
- 关键点：
  - [发现]
  - [发现]

## 综合发现

### [类别]
- [发现]
- [发现]

关键规则

1. 始终先创建计划

在没有 task_plan.md 的情况下永远不要开始复杂任务。这是不可协商的。

2. 决策前先读取

在任何重大决策之前，读取计划文件。这可以将目标保持在你的注意力窗口中。

3. 行动后更新

完成任何阶段后，立即更新计划文件：

• 用 [x] 标记已完成的阶段
• 更新状态部分
• 记录遇到的任何错误

4. 存储，不要塞满

大型输出放入文件，而不是上下文。在工作记忆中只保留路径。

5. 记录所有错误

每个错误都进入"遇到的错误"部分。这为未来的任务积累知识。

何时使用此模式

对以下情况使用三文件模式：

• 多步骤任务（3+ 步骤）
• 研究任务
• 构建/创建某物
• 跨多个工具调用的任务
• 任何需要组织的事情

以下情况跳过：

• 简单问题
• 单文件编辑
• 快速查找

避免的反模式

高级模式

参见 reference.md 了解：

• 注意力操作技巧
• 错误恢复模式
• 来自 Manus 的上下文优化

参见 examples.md 了解：

• 真实任务示例
• 复杂工作流模式

示例：实践中的文件规划

示例 1：研究任务

用户请求："研究晨练的好处并写一个摘要"

循环 1：创建计划

Write task_plan.md

# 任务计划：晨练好处研究

## 目标
创建关于晨练好处的研究摘要。

## 阶段
- [x] 阶段 1：创建此计划 ✓
- [ ] 阶段 2：搜索和收集来源
- [ ] 阶段 3：综合发现
- [ ] 阶段 4：交付摘要

## 关键问题
1. 身体健康的好处是什么？
2. 心理健康的好处是什么？
3. 有哪些科学研究支持这一点？

## 状态
**当前处于阶段 1** - 创建计划

循环 2：研究

Read task_plan.md           # 刷新目标
WebSearch "morning exercise benefits"
Write notes.md              # 存储发现
Edit task_plan.md           # 标记阶段 2 完成

循环 3：综合

Read task_plan.md           # 刷新目标
Read notes.md               # 获取发现
Write morning_exercise_summary.md
Edit task_plan.md           # 标记阶段 3 完成

循环 4：交付

Read task_plan.md           # 验证完成
Deliver morning_exercise_summary.md

---

示例 2：错误修复任务

用户请求："修复认证模块中的登录错误"

task_plan.md

# 任务计划：修复登录错误

## 目标
识别并修复阻止成功登录的错误。

## 阶段
- [x] 阶段 1：理解错误报告 ✓
- [x] 阶段 2：定位相关代码 ✓
- [ ] 阶段 3：识别根本原因（当前）
- [ ] 阶段 4：实施修复
- [ ] 阶段 5：测试和验证

## 关键问题
1. 出现什么错误消息？
2. 哪个文件处理认证？
3. 最近有什么变化？

## 已做出的决策
- 认证处理器位于 src/auth/login.ts
- 错误发生在 validateToken() 函数中

## 遇到的错误
- [初始] TypeError: Cannot read property 'token' of undefined
  → 根本原因：用户对象未正确等待

## 状态
**当前处于阶段 3** - 发现根本原因，准备修复

---

示例 3：功能开发

用户请求："在设置页面添加深色模式切换"

实践中的三文件模式

task_plan.md:

# 任务计划：深色模式切换

## 目标
向设置中添加功能性的深色模式切换。

## 阶段
- [x] 阶段 1：研究现有主题系统 ✓
- [x] 阶段 2：设计实施方法 ✓
- [ ] 阶段 3：实施切换组件（当前）
- [ ] 阶段 4：添加主题切换逻辑
- [ ] 阶段 5：测试和完善

## 已做出的决策
- 使用 CSS 自定义属性作为主题
- 将偏好存储在 localStorage 中
- 切换组件位于 SettingsPage.tsx

## 状态
**当前处于阶段 3** - 构建切换组件

notes.md:

# 笔记：深色模式实施

## 现有主题系统
- 位置：src/styles/theme.ts
- 使用：CSS 自定义属性
- 当前主题：仅浅色

## 需要修改的文件
1. src/styles/theme.ts - 添加深色主题颜色
2. src/components/SettingsPage.tsx - 添加切换
3. src/hooks/useTheme.ts - 创建新钩子
4. src/App.tsx - 用 ThemeProvider 包装

## 颜色决策
- 深色背景：#1a1a2e
- 深色表面：#16213e
- 深色文本：#eaeaea

dark_mode_implementation.md:（交付物）

# 深色模式实施

## 所做的更改

### 1. 添加深色主题颜色
文件：src/styles/theme.ts
...

### 2. 创建 useTheme 钩子
文件：src/hooks/useTheme.ts
...

---

示例 4：错误恢复模式

当某事失败时，不要隐藏它：

之前（错误）

Action: Read config.json
Error: File not found
Action: Read config.json  # 静默重试
Action: Read config.json  # 再次重试

之后（正确）

Action: Read config.json
Error: File not found

# 更新 task_plan.md:
## 遇到的错误
- config.json 未找到 → 将创建默认配置

Action: Write config.json（默认配置）
Action: Read config.json
Success!

---

读取-决策-之前模式

始终在重大决策前读取你的计划：

[已发生许多工具调用...]
[上下文变长...]
[原始目标可能被遗忘...]

→ Read task_plan.md          # 这将目标带回注意力中！
→ 现在做出决策              # 目标在上下文中是新鲜的

这就是 Manus 可以处理约 50 次工具调用而不失去跟踪的原因。计划文件充当"目标刷新"机制。

参考：Manus 上下文工程原则

此技能基于 Manus 的上下文工程原则，Manus 是一家 AI 代理公司，于 2025 年 12 月被 Meta 以 20 亿美元收购。

Manus 的 6 条原则

1. 文件系统作为外部记忆

"Markdown 是我在磁盘上的'工作记忆'。"

问题：上下文窗口有限制。将所有内容塞入上下文会降低性能并增加成本。

解决方案：将文件系统视为无限内存：

• 将大型内容存储在文件中
• 在上下文中仅保留路径
• 代理可以在需要时"查找"信息
• 压缩必须是可逆的

2. 通过重复进行注意力操作

问题：在约 50 次工具调用后，模型会忘记原始目标（"中间迷失"效应）。

解决方案：保留一个 task_plan.md 文件，在整个执行过程中重新读取：

上下文开始：[原始目标 - 遥远，被遗忘]
...许多工具调用...
上下文结束：[最近读取的 task_plan.md - 获得注意力！]

通过在每个决策前读取计划文件，目标会出现在注意力窗口中。

3. 保留失败追踪

"错误恢复是真正代理行为的最明显信号之一。"

问题：本能说隐藏错误，静默重试。这浪费令牌并失去学习机会。

解决方案：在计划文件中保留失败的操作：

## 遇到的错误
- [2025-01-03] FileNotFoundError: config.json 未找到 → 创建了默认配置
- [2025-01-03] API 超时 → 使用指数退避重试，成功

模型在看到失败时会更新其内部理解。

4. 避免少样本过拟合

"一致性滋生脆弱性。"

问题：重复的动作-观察对导致漂移和幻觉。

解决方案：引入受控变化：

• 稍微改变措辞
• 不要盲目复制粘贴模式
• 在重复任务上重新校准

5. 稳定前缀用于缓存优化

问题：代理是输入密集型的（100:1 比率）。每个令牌都花钱。

解决方案：为缓存命中构建结构：

• 首先放置静态内容
• 仅追加上下文（从不修改历史）
• 一致的序列化

6. 仅追加上下文

问题：修改先前的消息会使 KV 缓存无效。

解决方案：从不修改先前的消息。始终追加新信息。

代理循环

Manus 在连续循环中运行：

1. 分析 → 2. 思考 → 3. 选择工具 → 4. 执行 → 5. 观察 → 6. 迭代 → 7. 交付

循环中的文件操作：

Manus 统计数据

关键引用

"如果模型改进是涨潮，我们希望 Manus 成为船只，而不是 stuck 在海底的桩子。"

"对于复杂任务，我将笔记、代码和发现保存到文件中，以便在工作时可以参考它们。"

"我使用 file.edit 更新计划中的复选框，而不是重写整个文件。"

来源

基于 Manus 的官方上下文工程文档： https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus