名称： planning-with-files
版本： "2.10.0"
描述： 实现类 Manus 的基于文件的复杂任务规划。创建 task_plan.md、findings.md 和 progress.md 文件。适用于启动复杂的多步骤任务、研究项目或任何需要超过 5 次工具调用的任务。现支持在 /clear 后自动恢复会话。
user-invocable: true
允许工具：
- Read
- Write
- Edit
- Bash
- Glob
- Grep
- WebFetch
- WebSearch
hooks:
PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
hooks:
- type: command
command: "cat task_plan.md 2>/dev/null | head -30 || true"
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "echo '[planning-with-files] 文件已更新。如果此操作完成了一个阶段，请更新 task_plan.md 中的状态。'"
Stop:
- hooks:
- type: command
command: |
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"

        IS_WINDOWS=0
        if [ "${OS-}" = "Windows_NT" ]; then
          IS_WINDOWS=1
        else
          UNAME_S="$(uname -s 2>/dev/null || echo '')"
          case "$UNAME_S" in
            CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;
          esac
        fi

        if [ "$IS_WINDOWS" -eq 1 ]; then
          if command -v pwsh >/dev/null 2>&1; then
            pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
            powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
            sh "$SCRIPT_DIR/check-complete.sh"
          else
            powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null ||
            sh "$SCRIPT_DIR/check-complete.sh"
          fi
        else
          sh "$SCRIPT_DIR/check-complete.sh"
        fi

基于文件的规划

像 Manus 一样工作：使用持久的 Markdown 文件作为你的“磁盘上的工作记忆”。

第一步：检查前次会话 (v2.2.0)

在开始工作之前，检查前次会话中未同步的上下文：

# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

如果同步报告显示有未同步的上下文：
1. 运行 git diff --stat 查看实际的代码变更
2. 阅读当前的规划文件
3. 根据同步报告和 git diff 更新规划文件
4. 然后继续执行任务

重要：文件存放位置

• 模板 位于 ${CLAUDE_PLUGIN_ROOT}/templates/
• 你的规划文件 应放在 你的项目目录 中

快速开始

在执行任何复杂任务之前：

1. 创建 task_plan.md — 参考 templates/task_plan.md
2. 创建 findings.md — 参考 templates/findings.md
3. 创建 progress.md — 参考 templates/progress.md
4. 在决策前重读计划 — 刷新注意力窗口中的目标
5. 在每个阶段后更新 — 标记完成，记录错误

注意： 规划文件应放在你的项目根目录，而不是技能安装文件夹。

核心模式

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

→ 任何重要内容都应写入磁盘。

文件用途

关键规则

1. 先创建计划

绝不可以在没有 task_plan.md 的情况下开始复杂任务。这是硬性要求。

2. 2-操作规则

“每进行 2 次查看/浏览/搜索操作后，立即将关键发现保存到文本文件中。”

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

3. 决策前先阅读

在做出重大决策前，阅读计划文件。这能确保目标保持在你的注意力窗口中。

4. 行动后即更新

完成任何阶段后：
- 更新阶段状态：in_progress → complete
- 记录遇到的任何错误
- 注明创建/修改的文件

5. 记录所有错误

每个错误都应记录在计划文件中。这有助于积累知识并避免重复犯错。

## 遇到的错误
| 错误 | 尝试次数 | 解决方案 |
|------|----------|----------|
| FileNotFoundError | 1 | 创建了默认配置 |
| API 超时 | 2 | 添加了重试逻辑 |

6. 绝不重复失败

if action_failed:
    next_action != same_action

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

3 次尝试错误协议

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

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

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

3 次失败后：向用户寻求帮助
  → 解释你尝试过的方法
  → 分享具体的错误信息
  → 请求指导

读取与写入决策矩阵

5 个问题的重启测试

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

何时使用此模式

适用于：
- 多步骤任务（3 步以上）
- 研究任务
- 构建/创建项目
- 涉及多次工具调用的任务
- 任何需要组织性的任务

不适用于：
- 简单问题
- 单文件编辑
- 快速查找

模板

复制这些模板以开始：

• templates/task_plan.md — 阶段跟踪
• templates/findings.md — 研究存储
• templates/progress.md — 会话日志

脚本

用于自动化的辅助脚本：

• scripts/init-session.sh — 初始化所有规划文件
• scripts/check-complete.sh — 验证所有阶段是否完成
• scripts/session-catchup.py — 从前次会话恢复上下文 (v2.2.0)

高级主题

• Manus 原则： 参见 reference.md
• 真实示例： 参见 examples.md

反模式