planning-with-files

像 Manus 一样工作：planning-with-files 让 AI 编程工具拥有持久记忆

想象一个场景：你让 AI 编程助手去构建一个完整的后端系统，任务复杂到需要 50 步才能完成。就在 AI 勤勤恳恳写到第 30 步时，你不小心关闭了终端——进度全部丢失，一切从头开始。传统的 AI Agent 工具，每一个新对话都是一次失忆。而 planning-with-files 这款开源工具，正是来解决这个问题的。

该项目在 24 小时内获得 23,000+ GitHub Stars，被 SkillsPlayground、SkillCheck 等多个技能平台收录，支持 60+ AI 编程工具，v2.21.0 版本在内部评测中达到 96.7% 通过率，A/B 盲测 3:0 全胜。

图1：planning-with-files 核心机制示意

它是什么：AI 编程工具的「持久记忆层」

planning-with-files 本质上是一套基于 Markdown 文件的持久化任务规划系统，专为长时间运行的 AI Agent 任务设计。它通过 SKILL.md 标准（一个 AI Agent 技能规范）接入各类 AI 编程工具，为其提供三大核心能力：

1. 防崩溃的计划文件：所有任务计划以 Markdown 格式持久化存储在项目目录中，任何时候重启会话都能从断点继续，不会因网络中断、工具崩溃而丢失进度。

2. 确定性完成门控（Completion Gate）：这是 v3.0.0 引入的核心特性。AI 必须主动标记每个子任务的完成状态，系统会在任务真正完成后才释放会话，防止"看起来在做但实际没完成"的情况。这模拟了 Manus 被 Meta 以 $2B 收购时展示的工作模式。

3. 多 Agent 共享状态：多个 AI 编程工具可以基于同一份 plan 文件协同工作，disk 上的状态文件成为天然的通信总线。

技术实现：轻量到令人惊讶

翻看源码你会发现，这个项目几乎没有「重型依赖」。核心代码主要是 Bash 脚本 + 极少量 Python：

• init-session.sh — 初始化会话，创建/恢复 plan.md
• inject-plan.sh — 在每次工具调用前注入计划内容
• gate-stop.sh — v3.0 新增的完成门控脚本
• ledger-append.sh/ledger-summary.sh — JSONL 格式的运行记录追加与汇总
• attest-plan.sh — 计划签名验证，防篡改

此外还有 .hermes/、.claude/、.cursor/、.codex/ 等各 AI 工具的专属 hook 目录，对应接入 Claude Code、Cursor、Codex CLI 等平台。语言覆盖 Bash/Shell 为主，Python 为辅，代码行数较少，整体复杂度极低。

技术亮点：

• SKILL.md 标准：一个元数据规范文件，声明工具名、触发指令、依赖命令等，任何支持该标准的 AI 工具都可以一键安装此技能
• JSONL 运行账本：v3 引入的 append-only JSONL 日志，替代纯文本 progress.md，支持更结构化的状态追踪
• XDG 规范兼容：SHA 缓存路径支持 $XDG_CACHE_HOME/pwf-sha
• 多平台 Shell 支持：每个核心脚本均有 .sh（Bash）和 .ps1（PowerShell）双版本

谁在用它：社区生态已成型

README 披露了大量社区 fork 和扩展：

真实使用案例包括：Copilot Agent 完整项目仓库（lincolnwan）、AI 金融框架 ClarityFinance（cooragent）、Claude Code 工具集（oeftimie/vv-claude-harness）等。

上手体验：安装极简，但需配合 AI 工具

安装方式因工具而异，核心是安装 SKILL.md：

• Claude Code：claude mcp add skill othmanadi/planning-with-files 或通过 SkillsPlayground 一键安装
• 其他工具：克隆仓库后，在目标项目的 .{tool}/ 目录下创建软链接或复制相关 hook 文件

使用流程：

1. init-session 初始化项目，创建 plan.md 和 progress.md
2. 用 /plan <任务描述> 告诉 AI 要做什么，AI 自动写入 Markdown 计划
3. 每次工具调用前，inject-plan.sh 自动将计划内容注入到上下文中
4. AI 按计划逐步执行，progress.md 实时更新
5. check-continue 验证进度，决定是否继续

门槛说明：planning-with-files 本身是纯脚本集，安装复杂度极低。但它不是一个独立应用——必须有 Claude Code、Codex、Cursor 等 AI 编程工具才能发挥作用。如果你的工作流不涉及 AI 编程，这个工具没有独立价值。

局限与争议

• 不适用于纯 CLI 场景：如果没有 AI Agent 工具，这个项目几乎没有独立使用价值
• 计划文件的维护成本：AI 生成的 Markdown 计划有时过于冗长或格式混乱，需要人工干预
• v3 完成门控的学习曲线：新引入的 gated 模式增加了配置复杂度，从 v2 升级的用户需要理解新参数
• 仅限文件系统：完全依赖磁盘文件，无网络协作能力，多人远程协作场景受限
• 安全性考量：attest-plan 签名验证可以防止计划被篡改，但 AI 生成的内容本身不经过安全审核

行业意义：AI Agent 的「持久化」范式

planning-with-files 的爆发式增长（23K+ Stars 24h内）折射出一个明确趋势：AI Agent 需要记忆。当前主流的上下文窗口方案，在超长任务面前捉襟见肘。文件系统的简单持久化，成为了最轻量的解法。

项目遵循 SKILL.md 标准——这意味着它不绑定任何特定 AI 工具，而是以「技能包」的形式自由分发。这和 VS Code 插件生态的思路异曲同工，但面向的是 AI Agent 的行为规范层面。

随着 Claude Code、Codex、Cursor、OpenCode 等工具的竞争加剧，围绕 AI 编程工具的技能生态正在快速形成，planning-with-files 是这个生态中最成功的基础设施项目之一。

图2：v3.0.0 新增自主模式与完成门控特性