SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场planning-with-files

planning-with-files

智能体与模型

查看项目

更新于 10-16 02:11

技能介绍

用途

planning-with-files 是一个用于 AI 编程智能体的技能，实现 Manus 风格的“基于文件的规划”模式。其核心理念是：把上下文窗口当作易失且有限的 RAM，把文件系统当作持久且无限的磁盘，因此任何重要信息都应写入磁盘，作为“磁盘上的工作记忆”。该技能适用于需要组织与跟踪的复杂任务，例如多步任务（3 步以上）、研究任务、构建或创建项目、跨越大量工具调用的任务。对于简单问题、单文件编辑和快速查询，则建议跳过此模式。

主要能力

技能围绕三个规划文件展开：

  • task_plan.md：记录阶段、进度与决策，在每个阶段结束后更新。
  • findings.md：记录研究与发现，在任何发现之后更新。
  • progress.md：记录会话日志与测试结果，贯穿整个会话持续更新。

技能还提供模板与辅助脚本：

  • 模板：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）。

使用方式

在开始任何复杂任务之前：

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

注意：规划文件应放在项目根目录，而不是技能安装目录。模板位于 ${CLAUDE_PLUGIN_ROOT}/templates/，规划文件放在项目目录中。

技能包含会话恢复步骤（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)

如果恢复报告显示存在未同步的上下文：运行 git diff --stat 查看实际代码变更；阅读当前规划文件；根据恢复报告与 git diff 更新规划文件；然后继续任务。

关键规则

  1. 先创建计划：没有 task_plan.md 绝不开始复杂任务，这是不可协商的。
  2. 2-Action 规则：每进行 2 次查看/浏览器/搜索操作后，立即将关键发现保存到文本文件，防止视觉/多模态信息丢失。
  3. 决策前先阅读：在重大决策前阅读计划文件，使目标保持在注意力窗口内。
  4. 行动后更新：完成任何阶段后，将阶段状态从 in_progress 标记为 complete，记录遇到的错误，注明创建/修改的文件。
  5. 记录所有错误：每个错误都写入计划文件，以积累知识并防止重复。
  6. 绝不重复失败：如果某个操作失败，下一次操作不应是同一操作；跟踪尝试过的内容并改变方法。

3-Strike 错误协议：

  • 第 1 次尝试：诊断并修复——仔细阅读错误、识别根因、应用针对性修复。
  • 第 2 次尝试：替代方案——若出现相同错误，尝试不同方法、不同工具或不同库，绝不重复完全相同的失败操作。
  • 第 3 次尝试：更广泛的重新思考——质疑假设、搜索解决方案、考虑更新计划。
  • 3 次失败后：升级给用户——解释尝试过的内容、分享具体错误、请求指导。

读写决策矩阵：

  • 刚写完文件：不要读取，内容仍在上下文中。
  • 查看过图片/PDF：立即写入发现，多模态信息在丢失前转为文本。
  • 浏览器返回数据：写入文件，截图不会持久保存。
  • 开始新阶段：阅读计划/发现，若上下文陈旧则重新定位。
  • 发生错误：阅读相关文件，需要当前状态来修复。
  • 间隔后恢复：阅读所有规划文件，恢复状态。

5 问重启测试（若能回答这些问题，说明上下文管理扎实）：

  • 我在哪里？——task_plan.md 中的当前阶段。
  • 我要去哪里？——剩余阶段。
  • 目标是什么？——计划中的目标陈述。
  • 我学到了什么？——findings.md。
  • 我做了什么？——progress.md。

反模式

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

适用场景与限制

适用场景：多步任务（3 步以上）、研究任务、构建/创建项目、跨越许多工具调用的任务、任何需要组织的任务。

限制：简单问题、单文件编辑、快速查询不建议使用。规划文件必须放在项目根目录而非技能安装目录。会话恢复脚本依赖 Python 环境。

归属

该技能基于 Othman Adi 的 planning-with-files，采用 MIT 许可。原始实现记录了面向 AI 编程智能体的“Manus 风格”基于文件的规划模式。更多文档可参考原始仓库：Manus 原则见 docs/workflow.md，真实示例见 examples/，IDE 集成支持 Cursor、Codex、Gemini 等。