Planning-with-Files 完整指南：用三个文件让 AI 代理的工作记忆持久化-编程实验室

Planning-with-Files 完整指南：用三个文件让 AI 代理的工作记忆持久化

【免费下载链接】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

Planning-with-Files 是一款面向 AI 编码代理的文件规划技能：它把task_plan.md、findings.md、progress.md写到磁盘上，并在每轮交互中重新注入，让任务在/clear、崩溃或上下文压缩后依然可以接着做。下面按机制、数据、模式选择和落地方式，把它讲透。

一次 /clear 之后，任务去哪儿了

想象一个常见场景：你让编码代理执行一个跨多文件的重构，工具调用了二十多次，上下文窗口接近上限。你敲下/clear准备轻装上阵，代理却反问："之前的任务目标是什么？进展到哪里了？"它开始重读整个仓库，重复已经犯过的错误，把做了一半的阶段从头再来一遍。

这类"上下文丢失"的根源在于一个简单类比：上下文窗口相当于内存，断电即清空；而文件系统相当于磁盘，数据可以一直留在那里。Planning-with-Files 做的事情，就是把代理的工作记忆从内存搬到磁盘——凡是重要信息，全部落盘，任何时刻都能重新读回。

本节核心结论：代理失忆不是模型能力问题，而是存储位置选错了地方；把状态放进文件，问题就变成工程问题。

先看数据：这套方法到底有没有用

结论放在前面：在正式评估中，启用该技能的代理以 96.7% 的断言通过率（30 条中通过 29 条）完成结构化工作流检查，而未启用技能的对照组仅通过 6.7%。

评估方法参考了 Anthropic 的 skill-creator 框架，设计上有三点值得注意。其一，并行跑了 10 个子代理，5 个加载技能、5 个裸跑；其二，覆盖 5 类真实任务，包括 CLI 工具规划、研究对比、调试会话、Django 迁移和 CI/CD 流水线设计；其三，全部 30 条断言都是客观可验证的，例如文件是否生成、章节标题是否存在、状态字段是否齐全，没有主观打分。

更严格的一轮是 3 次盲测 A/B 对比：独立的评审代理不知道哪份产出来自哪个配置，结果是加载技能的一方 3 次全胜，平均分从约 6.8 分提到 10.0 分。所有启用技能的运行都产出了标准的三文件结构，而对照组几乎没有遵循结构化规划流程。

本节核心结论：数据表明差距不在"会不会规划"，而在"是否稳定地按结构执行"——技能的本质是把工作流固化下来。

核心机制：三个文件加钩子循环

整个系统由两部分构成：磁盘上的三个文件，负责存状态；生命周期钩子，负责搬状态。

三个文件分工明确：

task_plan.md 阶段清单与完成状态，是恢复现场的关键 findings.md 调研结果与关键决策，边做边追加 progress.md 会话日志与测试结果

它把"记忆"拆成三块，任何一块丢失都不会让全局信息断层。

钩子部分是一个"输入→动作→结果"的闭环：代理准备调用工具前，PreToolUse 钩子从磁盘读回task_plan.md，把目标状态写进当前上下文，再放行工具执行；工具执行后，PostToolUse 钩子检查状态是否变化，提示代理把结果更新回文件。于是"读计划→干活→写回结果"成为每个回合的固定节拍，目标漂移被周期性刷新压制住。

日常行为的判断顺序也很直接：任务预计超过三步或五次工具调用，先建三个文件；有调研结论，追加进findings.md；做完动作，记入progress.md；阶段完成，在task_plan.md里打勾；上下文真的没了（/clear或崩溃），会话恢复流程重读全部三个文件，从当前阶段继续。

这套闭环的关键洞察是：认知连续性不靠扩大窗口实现，而是靠"每次行动前把计划读回来"这个机械动作维持。

本节核心结论：文件负责持久化，钩子负责自动化，两者组合后"记得住"不再依赖模型的自觉。

并行会话：目录隔离加哈希认证

多个代理同时干活时，如果都读写同一份计划文件，就出现了竞争条件：A 会话写了一半的阶段状态，被 B 会话覆盖。v3.0.0 的解法是给每个会话一个独立目录：

.planning/ ├── 2026-01-10-backend-refactor/ └── 2026-01-10-incident-investigation/

每个日期加短名的子目录里各有一套完整的三文件，互不干扰；当前活动计划则通过.planning/.active_plan这个入口来解析，切换会话就等于切换上下文，无需文件锁。

隔离解决了"谁写哪份"，认证解决"这份能不能信"。attest-plan.sh会为活动计划生成 SHA-256 哈希并存档，钩子在注入计划内容前先比对当前文件哈希：一旦计划文件在两次读取之间被改动，哈希对不上，注入就被拦下。

写入路径上，脚本先把哈希写进临时文件再原子重命名到位，保证读者永远看不到半成品的认证文件；同时基于 mtime 的哈希缓存放在$XDG_CACHE_HOME/pwf-sha/下，避免每次调用都重复计算，也避开了/tmp这类公共目录的隐患。这套行为在 Linux、macOS、Windows Git Bash 和 WSL 上保持一致。

本节核心结论：并行靠目录隔离消除竞争，认证靠哈希比对防止篡改内容混入上下文，两者是同一目标的两道防线。

模式选择：自主模式与门控模式各适合谁

v3 提供了两种工作方式，区别在于"多久重新注入一次计划"。

传统模式在每个工具调用前都重新注入计划，认知连续性最强，代价是令牌开销逐轮累积。自主模式（autonomous）面向长注意力能力的模型，把重新注入压缩到会话开始时一次，测试数据显示长任务中令牌消耗降低 30%~50%，而任务完成率不变：

./scripts/init-session.sh --autonomous "长期任务"

它适合模型强、任务周期长的场景；对注意力维持较弱的模型，传统的高频注入更稳妥。

门控模式解决的是另一个问题：怎么防止代理在计划没做完时就宣布收尾。它用五个条件做确定性判断，只有全部成立时停止钩子才会拦下会话：当前处于门控模式、计划中仍有进行中的阶段、停止钩子本身处于激活状态、累计拦截次数未超过上限、且自上次拦截以来分类账有新进展。最后一个条件尤其关键——它保证了一个卡住的会话不会被无限期困住。

本节核心结论：模式选择本质是"连续性"与"开销"的权衡；模型强就用自主模式省钱，追求确定性收尾就开门控。

跨平台适配：一套逻辑覆盖 17 以上平台

Planning-with-Files 目前支持 17 个以上 AI 开发平台、60 多种代理，靠的是一套分层适配器结构。对外它采用 SKILL.md 开放标准，统一定义技能发现、钩子注册和配置管理的接口；对内，各平台把自己的钩子机制映射到同一个事件模型上：

平台钩子 → 抽象层 → 统一事件处理器 → 文件系统操作

这样，核心文件管理与平台细节彻底解耦：新增一个平台只需要补一层适配器，不用动任何核心逻辑。

语言适配也走同样的分目录结构，每种语言是一个独立技能包：

skills/ ├── planning-with-files/ ├── planning-with-files-ar/ ├── planning-with-files-de/ ├── planning-with-files-es/ ├── planning-with-files-zh/ └── planning-with-files-zht/

默认包是英语，另有阿拉伯语、德语、西班牙语、简体和繁体中文版，每个包内脚本与模板齐全，可独立安装。

本节核心结论：标准化接口加钩子抽象层，让"一个技能、多平台行为一致"成为可能，而不是为每个平台重写一遍。

安全边界：外部内容会被怎么处理

这套机制的强项——每轮重读计划文件——在安全视角下恰恰是放大风险的地方：2025 年的主动安全审计发现，如果允许代理抓取网页内容，外部文本一旦写进task_plan.md，就会在之后的每次工具调用中被反复注入上下文，形成提示注入的放大回路。

v2.21.0 的应对是三条明确的边界规则。第一，工具权限最小化：从allowed-tools声明中移除 WebFetch 和 WebSearch，从源头断掉写入通道。第二，内容隔离：外部来源的信息只允许进入findings.md，不得进入会被自动回灌的task_plan.md。第三，用户确认：凡是外部来源带有指令性质的内容，必须先经用户确认才能生效。

认证机制在这里还扮演第二道闸：计划文件若被外部手段修改，哈希比对失败会直接阻止该内容注入。威胁模型想清楚之后，防护就不神秘了——问题从"外部内容本身"转变为"外部内容能否进入循环注入路径"。

本节核心结论：安全设计的关键不是屏蔽外部内容，而是掐断它进入自动注入回路的通道。

从安装到排障：落地清单

安装渠道有三条：npm、Claude Code 插件市场、npx skills，装完即带钩子和斜杠命令。容器和 CI 场景下建议显式指定计划目录，避免共享环境串扰：

./scripts/init-session.sh --plan-dir "ci-build-$(date +%s)"

它用时间戳生成独立目录，每次构建互不污染。会话中断后恢复则交给一个脚本：

python3 scripts/session-catchup.py

它会定位上次会话的计划文件并生成追平报告。文件格式方面项目选择了 Markdown，理由有四点：人类可直接查看编辑、模型对它的理解与生成质量高、Git 的 diff 与合并友好、周边工具生态成熟。

出问题时按"先看状态、再看账本、再看阶段"的顺序排查：

./scripts/check-complete.sh 检查计划是否完整 ./scripts/ledger-summary.sh 查看分类账摘要 ./scripts/phase-status.sh 验证各阶段状态

需要深挖时打开调试输出即可：export PWF_DEBUG=1后脚本会打印更详细的决策过程。完整安装指南和排障手册覆盖了更多边界情况。

企业级部署还有四个可选扩展：用 NFS 或云存储做团队共享文件系统；把计划文件纳入 Git 获得版本跟踪；基于进度文件的时间戳监控任务停滞；用文件操作的时间戳做审计日志。

本节核心结论：落地路径很短——装、初始化、干活、用三个脚本排障，其余扩展按需叠加。

进阶实践与未来方向

日常使用建议渐进式推进：先在一个项目里跑通三文件流程，再推广到团队；同时培训成员理解"什么信息进哪个文件"的分工，并定期清理计划文件，防止它们膨胀到失去可读性。模式选择上遵循一条简单规则——强模型配自主模式，弱模型配传统高频注入；安全侧则定期审查计划文件中的敏感信息、确认文件权限设置、建立备份与恢复演练。

从项目自身的演进看，接下来几个方向值得留意：增量同步，只传输变化的部分；面向大型计划文件的高效序列化格式；跨代理协作编辑的分布式锁；以及基于实时通道的多端文件同步与冲突解决。这些方向都围绕同一个主题——当文件成为代理的记忆，文件系统的同步、协作与一致性就成了主战场。

Planning-with-Files 的价值不在功能清单，而在它示范的一种架构取舍：用最朴素的文件系统，解决代理长期运行中最顽固的失忆问题。如果你的代理也会"做完二十步忘掉最初目标"，这套三文件加钩子的方案，是目前能直接落地的答案之一。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考