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

planning-with-files

办公与效率

查看项目

更新于 10-16 06:40

技能介绍

用途

planning-with-files 是一个用于复杂任务的“基于文件的规划”技能，目标是像 Manus 那样工作：使用持久化的 Markdown 文件作为磁盘上的“工作记忆”。它把上下文窗口类比为易失且有限的 RAM，把文件系统类比为持久且无限的磁盘，因此任何重要信息都应写入磁盘，而不是只留在上下文中。

主要能力

该技能围绕三个规划文件组织工作：

  • 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）。

使用方式

快速开始：在任何复杂任务之前，先创建 task_plan.md、findings.md、progress.md（参考对应模板）；在做决策前重新阅读计划文件，以刷新注意力窗口中的目标；在每个阶段完成后更新文件，标记完成并记录错误。规划文件应放在项目根目录，而不是技能安装目录。

会话恢复（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)

如果 catchup 报告显示存在未同步的上下文：运行 git diff --stat 查看实际代码变更；阅读当前规划文件；根据 catchup 与 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）？

适用场景

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

不适用于：简单问题、单文件编辑、快速查询。

限制与注意事项

规划文件必须创建在项目目录中，而不是技能目录中；技能目录只存放模板、脚本和参考文档。反模式包括：用 TodoWrite 做持久化（应改为创建 task_plan.md 文件）、只陈述一次目标就忘记（应在决策前重读计划）、隐藏错误并静默重试（应将错误记录到计划文件）、把所有内容塞进上下文（应将大内容存入文件）、立即开始执行（应先创建计划文件）、重复失败动作（应跟踪尝试并改变方法）。更多内容可参考 reference.md（Manus 原则）与 examples.md（真实示例）。