拓冰网站定制 
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三轮全赢。选型建议适合什么以及两个常见坑适合三步以上的长任务——重构、数据迁移、事故排查、跨天调研以及会跨会话继续的工作。不适合一次性问答、一两步的小指令建文件的开销不划算。技能自带的判断标准是任务超过 3 步或 5 次工具调用才建三文件。模式挑法强模型且在意成本用自主模式模型偏弱、或想要不完成不许停的保证用门控模式。坑一把网页检索结果直接灌进 task_plan.md。应该进 findings.md否则外部指令会被注入循环逐轮放大。坑二两个会话共用同一套计划目录。正确姿势是每个任务用隔离目录.planning/机制各写各的别共享一套文件。今天就能做的一步挑一个三步以上的任务在项目目录里跑一次./scripts/init-session.sh 任务名让代理干几轮后/clear一下再问它继续。看到它从磁盘上把三个文件读回来、不追问就接着干你就把代理的第二大脑装好了——长任务从此有落点。【免费下载链接】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），仅供参考 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三轮全赢。选型建议适合什么以及两个常见坑适合三步以上的长任务——重构、数据迁移、事故排查、跨天调研以及会跨会话继续的工作。不适合一次性问答、一两步的小指令建文件的开销不划算。技能自带的判断标准是任务超过 3 步或 5 次工具调用才建三文件。模式挑法强模型且在意成本用自主模式模型偏弱、或想要不完成不许停的保证用门控模式。坑一把网页检索结果直接灌进 task_plan.md。应该进 findings.md否则外部指令会被注入循环逐轮放大。坑二两个会话共用同一套计划目录。正确姿势是每个任务用隔离目录.planning/机制各写各的别共享一套文件。今天就能做的一步挑一个三步以上的任务在项目目录里跑一次./scripts/init-session.sh 任务名让代理干几轮后/clear一下再问它继续。看到它从磁盘上把三个文件读回来、不追问就接着干你就把代理的第二大脑装好了——长任务从此有落点。【免费下载链接】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），仅供参考