OthmanAdi/planning-with-files：让编码智能体的计划活过上下文重置
针对 AI 编码代理和长时间运行的任务进行基于文件的持久规划。防崩溃降价计划、/清除和压缩后的会话恢复、针对上下文腐烂的每轮重新注入、确定性完成门。马努斯风格。 Claude Code、Codex、Cursor、Kiro、OpenCode 和 60 多个基于代理技能标准的代理。
秒懂
- 它是什么？
- 给编码智能体用的持久化文件规划技能。本文按 README 梳理它的三文件模式、每轮重新注入的钩子机制、并行任务的目录隔离、两组自报评测数字，以及 v3 针对长任务加入的门控与计划认证。
- 适合谁用？
- 适合经常让编码智能体跑多阶段长任务、并且已经受够上下文重置后从头再来的人；不适合指望它提升任务正确率的场景，作者自己也说恢复基准衡量的是重新定位成本而非正确率。先验证两件事：装完跑 /plan-doctor 确认钩子已注册，再挑一个真实任务看 task_plan.md 的复选框是否随阶段推进被勾上。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
把上下文当内存、把磁盘当硬盘
这个项目解决的是一个几乎所有编码智能体使用者都遇到过的问题：上下文窗口一重置，智能体的工作记忆就没了。它的核心主张写得很直白，把上下文窗口类比为内存，把文件系统类比为硬盘，凡是重要的东西都写到磁盘上。项目自称是 Manus 风格的磁盘工作记忆实现，载体是三个纯 Markdown 文件，默认加进 gitignore，不依赖任何运行时状态。
README 列出的四类症状分别是：内置待办列表在上下文重置后消失、工具调用超过五十次之后原始目标被挤出去、失败没有被记录导致同样的错误反复出现、以及所有东西都塞进上下文而不是存下来。第三点最容易被忽略，错误不落盘意味着下一次会话会重复踩同一个坑。背景上，README 提到 Meta 在 2025 年 12 月 29 日以二十亿美元收购 Manus，并把这个方案定位为对那套工作记忆思路的开源复刻，这条属于背景描述，与技能本身的实现无关。
task_plan、findings、progress 三文件分工
三个文件的分工是固定的。task_plan.md 记录阶段划分与进度复选框，是上下文重置之后的恢复起点；findings.md 存放研究笔记与决策，随着进展不断追加；progress.md 记录会话日志与测试结果。落到项目目录里的只有这三个文件，没有别的。
触发条件也被写进了技能定义：任务需要三个以上步骤或五次以上工具调用时才创建它们，简单任务不凑这套流程。智能体被要求学到新东西就追加 findings.md，执行了操作就写 progress.md，完成一个阶段就勾选 task_plan.md 里的复选框，上下文丢失时重新读取全部文件。门控模式下，只有所有阶段都完成才放行停止门。
把阶段与复选框放在文件里而不是留在对话中还有个附带好处：人可以直接看到进度。想知道智能体做到哪一步，打开这个文件即可，不必去翻长篇会话记录。
每轮重新注入是怎么做到的
关键在于每轮重新注入。README 展示了以 BEGIN PLAN DATA 标记包裹的注入块，它由 UserPromptSubmit 钩子从磁盘上的 task_plan.md 读出来写进上下文。也就是说，计划不靠智能体自觉去读，而是由钩子在每一轮开始之前塞进去，这正是它和普通提示词模板的分界线。
钩子数量按客户端不同：Claude Code 五个，Codex 七个，Pi 八个，职责覆盖每轮重新注入计划、提醒写入与完成状态检查。环境层面还有几个开关，PLANNING_DISABLED 让单次调用跳过计划读取，PLAN_ID 锁定到指定计划，PWF_INJECT 启用结构化注入，而不是固定截取前五十行的窗口。
并行任务的目录隔离与 .active_plan
并行任务的处理方式在 v2.36.0 之后变了。多个任务各自落在以日期加短名命名的 .planning 子目录下，每个目录里仍是同样三个文件，当前生效的那一个由 .active_plan 指定。
价值在于同时推进两条任务线时不会互相覆盖计划文件。落到磁盘上的都是纯 Markdown，可以直接被人读改，也可以随项目一起忽略掉，不会污染版本历史。README 强调除了这三个文件之外，任何地方都不保存运行时状态，因此把目录删掉就等于把计划状态清空，备份时也要记得一并带走。
自报评测的两组数字与它们的口径
评测数字要按自报来读。用 Anthropic 的 skill-creator 框架跑的那组，技能版本 v2.21.0，模型 claude-sonnet-4-6，日期 2026 年 3 月 6 日，十个并行子智能体、五种任务类型、三十条可客观验证的断言、三组盲测 A/B。结果是三十条断言里通过 29 条，未使用时通过 2 条，即 96.7% 对 6.7%；三文件模式在五次评测中全部遵循，未使用时为零次；盲测三战全胜；平均评分 10.0 对 6.8。
第二组是内部恢复基准，版本 v1，日期 2026 年 7 月 6 日，作者本人运行，对照版本 v3.4.0。做法是任务做到大约一半时强行中断，新会话只被告知继续这个目录里的工作。带计划文件的会话平均用 5.0 轮恢复，裸智能体用 13.3 轮；所有受评运行最终都跑到 pytest 全绿（77/77），差别在重新定位的成本而不是正确性。
两组数字的共同局限是都由作者本人设计与运行，且绑定在固定模型与固定日期上，模型更新之后结论是否成立需要重新验证。README 自己也提醒，这组衡量的是文件模式的保真度，不是长时间自主运行中的目标漂移，更新的模型与自主模式尚未被覆盖，方法与局限单独写在 docs/evals.md 里。
安装要走插件，而不是只装技能包
安装有两条路，官方推荐的是插件那条。Claude Code 用户在插件市场添加仓库后安装插件，一次拿到技能、钩子与斜杠命令；其他客户端用 npx skills add，借助 Agent Skills 标准覆盖六十多个客户端，包括 Codex、Cursor、Kiro、OpenCode 等。
两条路的差别很关键：走技能包安装时钩子可能没有注册，而钩子正是每轮重新注入的执行者，缺了它，整套方案就退化成一段可能被忽略的提示词。官方建议装完之后运行 /plan-doctor 验证钩子是否就位。这一步不该省，否则你以为装上了，实际只是多了三个没人去读的文件。
v3 的自主模式、计划认证与运行账本
v3 这条线上有四项针对长任务的能力。自主模式减少每轮对计划内容的复述，同时保留轮次开始时的注入；门控模式加了一道停止门，只有所有完成条件都满足才放行；会话恢复在上下文重置之后从 IDE 的会话存储里重新读取文件；SHA-256 计划认证锁定 task_plan.md，一旦计划被篡改就拒绝注入。
另外还有一份追加式的 JSONL 运行账本，记录阶段转换，便于事后回溯。仓库快照为 26404 个 star、2208 个 fork、9 个开放 issue，默认分支 master，最近一次推送在 2026 年 8 月 22 日，当前版本 v3.11.2，许可证 MIT，版权归 Ahmad Adi，README 提到测试套件有 417 项通过。未说明的部分包括任务完成后计划文件是否自动归档，以及除 MIT 的免责条款之外是否有任何支持承诺。
编辑结论
适合经常让编码智能体跑多阶段长任务、并且已经受够上下文重置后从头再来的人；不适合指望它提升任务正确率的场景，作者自己也说恢复基准衡量的是重新定位成本而非正确率。先验证两件事：装完跑 /plan-doctor 确认钩子已注册，再挑一个真实任务看 task_plan.md 的复选框是否随阶段推进被勾上。
社区笔记