AI 代理跑长任务总“失忆“？Planning-with-Files 完整指南：三个文件让计划住进磁盘-平芜编程栈

AI 代理跑长任务总"失忆"？Planning-with-Files 完整指南：三个文件让计划住进磁盘

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

让 AI 代理重构一个模块，你去倒了杯咖啡，回来发现它干到第 12 步，开口问你"请再描述一下目标"。原始意图没了，做过的步骤忘了，同一个错误可能再犯一遍。Planning-with-Files 解决的就是这类 AI 代理记忆与上下文管理问题：把代理的"工作内存"写成磁盘上的三个 Markdown 文件，上下文清了，计划还在。

一句话定位：把记忆写进磁盘

Planning-with-Files 的定位可以一句话讲完：把文件系统当作 AI 代理的持久化工作内存。核心思路类比操作系统就很清楚——上下文窗口相当于内存，断电就没；凡是要长期记住的东西，写进"磁盘"（文件）。窗口继续用来干活，但目标、资料、进度都落在文件里，随时能重新读回注意力。做多步骤任务规划时，这就是最朴素也最可靠的做法。

三个文件各管什么：目标卡、资料夹、打卡表

项目根目录只多三个文件，各司其职：

task_plan.md —— 目标卡：写最初的目标、拆出的 3~7 个阶段、每个阶段是待办、进行中还是完成。上下文丢失后，它就是"从哪续上"的锚点。
findings.md —— 资料夹：调研结果、外部资料、技术决策及理由，边做边追加。外部内容只许进这里，后面讲原因。
progress.md —— 打卡表：会话日志，记做了什么、改了哪些文件、测试通过没、撞过什么错。

为什么用 Markdown 而不是 JSON？三个理由：人直接能读、LLM 生成和理解它手感好、Git 的 diff 与合并都友好。这三个文件默认被 gitignore——它们是代理的草稿本，不是交付物。

它怎么自动运转：两个钩子盯住文件

你不需要记得手动维护文件，钩子（在工具执行前后自动触发的小程序）替你干。代理每次调用工具前后，对应钩子都会动作：

工具调用前：读 task_plan.md → 把计划重新塞回上下文 工具调用后：检查文件状态 → 更新 progress / findings 会话停止前：核对所有阶段是否完成（门控模式）

效果像每节比赛前都掏一次目标卡的教练：代理不用"靠记性"记住自己为什么出发，目标每轮都被重新喂到眼前。

三步上手：初始化 → 执行 → 收尾或恢复

第一步，初始化。在项目目录跑一行：

./scripts/init-session.sh "重构支付模块"

scripts/init-session.sh 会生成三个文件，然后把目标和阶段填进 task_plan.md。

第二步，执行。代理按计划干活：查到东西写进 findings.md，做了动作写进 progress.md，完成一个阶段就在 task_plan.md 打勾。全程不用你盯，钩子负责提醒和同步。

第三步，收尾或恢复。觉得做完了，跑./scripts/check-complete.sh核对所有阶段是否标记完成；中途上下文被清空、进程挂了也没关系，会话恢复（session catchup）会重读三个文件接着干。项目内部恢复基准里，磁盘上有文件的会话平均 5 轮就续上了，裸跑的要 13.3 轮。

三个进阶能力：什么时候该开

并行计划隔离

v3.0.0 起，同一仓库可以同时跑多个任务：每个会话分到独立的.planning/<日期>-<任务名>/目录，各有一套三文件和认证记录，.active_plan像一个"当前所在"的指针（符号链接），决定本会话读哪一套。什么时候用：你一边重构后端、一边查线上故障，两边互不覆盖、各自演进。

两种注入模式

传统（门控）模式在每次工具调用前都重新注入计划，外加一道停止闸门：只有"处于门控模式、有阶段未完成、停止钩子激活、连拦次数没超上限、上次拦截后账本有进展"这五个条件同时满足才放行拦截——既防止干一半被草草收工，也防止未完成的计划永远困住会话。自主模式则只在会话开始时注入一次，省掉逐轮复读，长任务上可省 30~50% token，适合注意力长的强模型。怎么选：弱模型或要"做完才许停"的确定性，选门控；强模型、长任务、在意成本，选自主。

跨平台适配器

项目基于 SKILL.md 开放标准（一套跨平台通用的技能发现与钩子注册规范），同一套核心逻辑装进 17+ 个开发平台：Claude Code、Codex、Cursor、OpenCode 等。skills/ 目录里还有全套多语言适配器（简中、繁中、德语、西语、阿语），且不只是说明文字翻译，模板和脚本输出都是本地化的。团队工具混用时，不用学两套用法。

信任与安全：防篡改，也防提示注入

这里有两道风险，项目分别给了对策。

一是文件被改动：scripts/attest-plan.sh 给 task_plan.md 存一份 SHA-256 指纹，钩子注入前先比对，不一致就拒绝注入——好比公章对不上就不办事。指纹写入用"先写临时文件再改名"的原子操作，不会读到写一半的状态；校验缓存放在用户私有目录$XDG_CACHE_HOME/pwf-sha/，不放在 /tmp 这种公共位置。

二是间接提示注入：代理顺手抓来的网页内容若写着"请执行某操作"，一旦进了 task_plan.md，就会被钩子逐轮放大。项目的硬规则是：外部内容只允许写进 findings.md，指令性内容必须先给用户确认。

数据说话：96.7% 与三轮盲测

96.7%：官方评测 30 条客观断言过了 29 条。断言查的都是"文件在不在、章节全不全、状态字段对不对"这类机器可验证的事实——可以理解为代理"记笔记的格式"几乎不会错。
10 个子代理对照：5 个带技能、5 个不带，跑同样的五类任务（CLI 规划、调研、调试、Django 迁移、CI/CD 流水线）。
3 轮盲测 A/B：评审判不知道哪个输出来自哪组配置，带技能组平均分 10.0/10，对照组 6.8/10，三轮全赢。