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-filesPlanning-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_DEBUG1后脚本会打印更详细的决策过程。完整安装指南和排障手册覆盖了更多边界情况。企业级部署还有四个可选扩展用 NFS 或云存储做团队共享文件系统把计划文件纳入 Git 获得版本跟踪基于进度文件的时间戳监控任务停滞用文件操作的时间戳做审计日志。本节核心结论落地路径很短——装、初始化、干活、用三个脚本排障其余扩展按需叠加。进阶实践与未来方向日常使用建议渐进式推进先在一个项目里跑通三文件流程再推广到团队同时培训成员理解什么信息进哪个文件的分工并定期清理计划文件防止它们膨胀到失去可读性。模式选择上遵循一条简单规则——强模型配自主模式弱模型配传统高频注入安全侧则定期审查计划文件中的敏感信息、确认文件权限设置、建立备份与恢复演练。从项目自身的演进看接下来几个方向值得留意增量同步只传输变化的部分面向大型计划文件的高效序列化格式跨代理协作编辑的分布式锁以及基于实时通道的多端文件同步与冲突解决。这些方向都围绕同一个主题——当文件成为代理的记忆文件系统的同步、协作与一致性就成了主战场。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辅助生成（AIGC），仅供参考