# Planning with Files - Manus 风格文件规划

像 Manus（Meta 以 20 亿美元收购的 AI Agent）一样工作：使用持久化的 Markdown 文件作为"磁盘上的工作记忆"。

## 核心原则

```
上下文窗口 = RAM（易失、有限）
文件系统 = 磁盘（持久化、无限）

→ 所有重要信息都写入磁盘。
```

## 3 文件模式

对于每个复杂任务，在项目目录中创建三个文件：

```
task_plan.md      → 跟踪阶段和进度
findings.md       → 存储研究和发现
progress.md       → 会话日志和测试结果
```

**模板文件位置：** `assistant/planning-with-files/templates/`

## 何时使用此模式

**适用于：**

- 多步骤任务（3+ 步骤）
- 研究型任务
- 构建/创建项目
- 需要多次工具调用的任务
- 任何需要组织的任务

**不适用于：**

- 简单问题
- 单文件编辑
- 快速查询

## 关键时机规则

这些规则模拟 hooks 以确保正确的工作流程：

### 📌 任务开始时（SessionStart）

**必须**在任何其他工作之前首先创建所有三个文件：

1. 使用模板创建 `task_plan.md`
2. 使用模板创建 `findings.md`
3. 使用模板创建 `progress.md`
4. 填写 task_plan.md 中的目标部分

**原因：** 没有规划文件，在 50+ 次工具调用后你会忘记目标。

### 📌 重大决策前（PreToolUse）

**必须**在以下操作前重新阅读 `task_plan.md`：

- 写入或编辑文件
- 执行命令
- 做架构决策
- 实现功能

**如何操作：** 使用 Read 工具刷新上下文中的计划。

**原因：** 这使目标在注意力窗口中保持新鲜（Manus 的"注意力操控"）。

### 📌 文件操作后（PostToolUse）

**必须**在以下操作后立即更新状态：

- 写入文件
- 编辑文件
- 完成任务阶段

**如何操作：** 编辑 task_plan.md 更新阶段状态：

```markdown
- **Status:** pending → in_progress → complete
```

**原因：** 跟踪进度，防止忘记已完成的工作。

### 📌 任务结束前（Stop）

**必须**验证完成度：

- 检查所有阶段是否标记为 `complete`
- 审查交付物部分
- 确保没有未解决的错误

**原因：** 防止任务未完成就提前结束。

## 6 条关键规则

### 1. 先创建计划

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

```markdown
## 目标

[一句话描述最终状态]

## 当前阶段

Phase 1

## 阶段

### Phase 1: 需求和发现

- [ ] 理解用户意图
- [ ] 识别约束条件
- **Status:** in_progress
```

### 2. 2-Action 规则

> "每 2 次查看/浏览/搜索操作后，立即将关键发现保存到 findings.md。"

这防止视觉/多模态信息丢失。

```markdown
## 视觉/浏览器发现

- 截图显示登录表单有邮箱和密码字段
- API 文档指示 JSON 响应格式
```

### 3. 决策前先读

在重大决策前，读取计划文件。这使目标保持在注意力窗口中。

```bash
# 在实现功能前：
Read 工具 → task_plan.md
# 现在继续实现
```

### 4. 行动后更新

完成任何阶段后：

- 标记阶段状态：`pending` → `in_progress` → `complete`
- 记录遇到的任何错误
- 注明创建/修改的文件

```markdown
## 遇到的错误

| 错误              | 尝试次数 | 解决方案     |
| ----------------- | -------- | ------------ |
| FileNotFoundError | 1        | 创建默认配置 |
```

### 5. 记录所有错误

每个错误都记入计划文件。这建立知识库并防止重复。

### 6. 永不重复失败

```
if 操作失败:
    下一个操作 != 相同操作
```

跟踪你尝试过的方法。改变策略。

## 3 次尝试错误协议

```
尝试 1：诊断和修复
  → 仔细阅读错误
  → 识别根本原因
  → 应用针对性修复

尝试 2：替代方法
  → 相同错误？尝试不同方法
  → 不同工具？不同库？
  → 绝不重复完全相同的失败操作

尝试 3：更广泛的重新思考
  → 质疑假设
  → 搜索解决方案
  → 考虑更新计划

3 次失败后：上报用户
  → 解释你尝试了什么
  → 分享具体错误
  → 寻求指导
```

## 文件用途

| 文件           | 用途               | 何时更新     |
| -------------- | ------------------ | ------------ |
| `task_plan.md` | 阶段、进度、决策   | 每个阶段后   |
| `findings.md`  | 研究、发现         | 任何发现后   |
| `progress.md`  | 会话日志、测试结果 | 整个会话期间 |

## 读取 vs 写入决策矩阵

| 情况           | 操作             | 原因                     |
| -------------- | ---------------- | ------------------------ |
| 刚写入文件     | 不要读取         | 内容仍在上下文中         |
| 查看了图像/PDF | 立即写入发现     | 多模态 → 文本，避免丢失  |
| 浏览器返回数据 | 写入文件         | 截图不会持久化           |
| 开始新阶段     | 读取计划/发现    | 如果上下文过时则重新定向 |
| 发生错误       | 读取相关文件     | 需要当前状态来修复       |
| 间隔后恢复     | 读取所有规划文件 | 恢复状态                 |

## 5 问题重启测试

如果你能回答这些问题，说明你的上下文管理很好：

| 问题           | 答案来源                  |
| -------------- | ------------------------- |
| 我在哪里？     | task_plan.md 中的当前阶段 |
| 我要去哪里？   | 剩余阶段                  |
| 目标是什么？   | 计划中的目标陈述          |
| 我学到了什么？ | findings.md               |
| 我做了什么？   | progress.md               |

## 模板结构

### task_plan.md 模板

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

## 目标

[一句话描述最终状态]

## 当前阶段

Phase 1

## 阶段

### Phase 1: 需求和发现

- [ ] 理解用户意图
- [ ] 识别约束和需求
- [ ] 在 findings.md 中记录发现
- **Status:** in_progress

### Phase 2: 规划和结构

- [ ] 定义技术方法
- [ ] 如需要则创建项目结构
- [ ] 记录决策及理由
- **Status:** pending

### Phase 3: 实现

- [ ] 逐步执行计划
- [ ] 执行前先将代码写入文件
- [ ] 增量测试
- **Status:** pending

### Phase 4: 测试和验证

- [ ] 验证所有需求已满足
- [ ] 在 progress.md 中记录测试结果
- [ ] 修复发现的任何问题
- **Status:** pending

### Phase 5: 交付

- [ ] 审查所有输出文件
- [ ] 确保交付物完整
- [ ] 交付给用户
- **Status:** pending

## 关键问题

1. [要回答的问题]
2. [要回答的问题]

## 已做决策

| 决策 | 理由 |
| ---- | ---- |
|      |      |

## 遇到的错误

| 错误 | 尝试次数 | 解决方案 |
| ---- | -------- | -------- |
|      | 1        |          |
```

### findings.md 模板

```markdown
# 发现和决策

## 需求

## <!-- 从用户请求中捕获 -->

## 研究发现

## <!-- 探索期间的关键发现 -->

## 技术决策

<!-- 已做决策及理由 -->

| 决策 | 理由 |
| ---- | ---- |
|      |      |

## 遇到的问题

<!-- 错误及其解决方式 -->

| 问题 | 解决方案 |
| ---- | -------- |
|      |          |

## 资源

## <!-- URL、文件路径、API 引用 -->

## 视觉/浏览器发现

## <!-- 关键：每 2 次查看/浏览操作后更新 -->
```

### progress.md 模板

```markdown
# 进度日志

## 会话：[日期]

### Phase 1: [标题]

- **Status:** in_progress
- **开始时间：** [时间戳]
- ## 采取的行动：
- ## 创建/修改的文件：

## 测试结果

| 测试 | 输入 | 预期 | 实际 | 状态 |
| ---- | ---- | ---- | ---- | ---- |
|      |      |      |      |      |

## 错误日志

| 时间戳 | 错误 | 尝试次数 | 解决方案 |
| ------ | ---- | -------- | -------- |
|        |      | 1        |          |

## 5 问题重启检查

| 问题           | 答案           |
| -------------- | -------------- |
| 我在哪里？     | Phase X        |
| 我要去哪里？   | 剩余阶段       |
| 目标是什么？   | [目标陈述]     |
| 我学到了什么？ | 见 findings.md |
| 我做了什么？   | 见上文         |
```

## 反模式

| 不要做                | 应该做                 |
| --------------------- | ---------------------- |
| 使用 TodoWrite 持久化 | 创建 task_plan.md 文件 |
| 陈述一次目标就忘记    | 决策前重新读取计划     |
| 隐藏错误并静默重试    | 将错误记录到计划文件   |
| 所有内容塞进上下文    | 将大内容存储在文件中   |
| 立即开始执行          | 首先创建计划文件       |
| 重复失败的操作        | 跟踪尝试，改变方法     |

## Manus 原则

| 原则             | 实现                     |
| ---------------- | ------------------------ |
| 文件系统作为内存 | 存储在文件中，而非上下文 |
| 注意力操控       | 决策前重新读取计划       |
| 错误持久化       | 在计划文件中记录失败     |
| 目标跟踪         | 复选框显示进度           |
| 完成验证         | 停止前检查所有阶段       |

---

**记住：** 你在前期收集并写入磁盘的上下文越多，执行就会越好。文件是你的持久化记忆。