尧图网站建设 
planning-with-files 进度日志progress.md实战指南会话记录、测试结果与五问重启恢复【免费下载链接】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-filesprogress.md是 planning-with-files 文件规划体系中负责「记录已发生之事」的持久化日志层它以时间线形式保存每个阶段执行了什么、改动过哪些文件、测试验证结果如何、出现过哪些错误从而让 AI 编码 Agent 在经历/clear、上下文压缩compaction、崩溃甚至多天跨会话任务后仍能仅凭磁盘上的 Markdown 文件无损恢复工作状态。本文以 progress.md 阿拉伯语模板 为骨架逐段拆解其结构设计并结合仓库中的模板生成脚本、生命周期钩子、完成度检查脚本与 v3 账本机制说明这张「会话日志」表在长任务中如何被写入、被注入、被用于恢复以及如何安全地避免它成为上下文注入的攻击面。progress.md 在文件规划体系中的位置planning-with-files 的核心思路是把 Agent 的「工作记忆」从易失的上下文窗口迁移到磁盘上的三个 Markdown 文件。在 阿拉伯语版 SKILL.md 的「文件用途」表中三者的分工被定义得很清楚文件用途更新时机task_plan.md阶段、进度、决策每个阶段完成后findings.md研究、发现任何发现之后progress.md会话日志、测试结果整个会话期间持续用该模板自己的话说progress.md 是一份「持续不断的日志记录已执行的内容与发生的事件」应当在每个阶段完成时、每次出现错误时、以及任何需要留下可供恢复工作的证据时被更新。它与task_plan.md计划未来要做什么和findings.md沉淀学到了什么形成互补计划回答「要去哪」发现回答「知道了什么」而 progress.md 回答「做了什么、验证了什么、踩过什么坑」。值得注意的边界是progress.md 与task_plan.md、findings.md、.planning/目录默认都会被 gitignore属于「工作记忆」而非受跟踪的交付物——任务结束后由下一次任务覆盖值得留存的内容应被提升为代码、提交或文档这一点在 README.md 中有明确说明。模板结构逐段拆解一个完整会话日志长什么样阿拉伯语模板与 英文标准模板 逐段对应定义了一份 progress.md 应当包含的全部区块。下面按原模板顺序完整展开并逐项说明。文件头与「会话」分区文件以# 进度日志# Progress Log开头随后是「会话」分区## 会话: [日期]用清晰格式的工作日期替换占位符例如2026-01-15。一个文件可以容纳多个会话分区——当任务跨天、或在/clear后重新恢复时新的一天追加一个新的## 会话:分区形成完整的时间线而不是覆盖旧记录。阶段条目状态、开始时间、动作与文件清单每个阶段使用三级标题组织### 阶段 1: [标题] - **状态:** in_progress - **开始于:** [时间戳] - 已采取的动作: - - 已创建/修改的文件: -模板明确要求状态取值只能使用pending、in_progress、complete三者之一与task_plan.md使用的状态词汇保持一致开始时间用可读格式记录。动作与文件路径要在阶段推进过程中不断补充具体内容——这正是恢复会话时判断「我到底干到哪一步」的第一手证据。注意与task_plan.md的分工task_plan.md里也有阶段状态但那是「路线图上的标记」progress.md 里的阶段条目则是「已经发生的动作流水账」。task_plan.md负责告诉你「阶段 1 处于 in_progress」progress.md 负责告诉你「in_progress 期间我实际执行了哪些命令、改了哪些文件」。测试结果表验证证据的结构化沉淀模板为验证工作预留了五列表格测试输入预期实际状态每个验证命令或场景都应记录测的是什么、输入是什么、预期结果、实际观测结果、最终状态。这保证了「某个改动是否通过验证」不依赖 Agent 的记忆而是落在磁盘上可复查的结构化数据。在 analytics 专用变体中见下文这张表会被替换为「查询日志表」。错误日志表杜绝重复失败的机制模板的第二张表专用于错误时间戳错误尝试次数解决方案1模板的要求是每个错误在发生当下立即记录即使很快被修复保留尝试次数与解决方案使「失败的路径」不会再次被走一遍。这与 SKILL.md 的规则 5「记录所有错误」、规则 6「绝不重复失败」if 操作失败: 下一步 ! 同一步骤以及「三重失败协议」尝试 1 诊断修复 → 尝试 2 换一种方法 → 尝试 3 重新质疑假设 → 仍失败则询问用户直接呼应。错误日志表就是这套纪律落盘的地方。五问重启检查表会话恢复的自检清单模板最后一张表是整个 progress.md 的灵魂问题答案我在哪里阶段 X我要去哪里剩余阶段目标是什么[目标陈述]我学到了什么参见 findings.md我做了什么参见上文这五个问题的设计意图是恢复会话时Agent或人类只需打开 progress.md 和兄弟文件就能回答「当前进度、剩余工作、目标、知识沉淀、已完成动作」五个维度从而把上下文窗口里已经丢失的状态完整重建。阿拉伯语版 SKILL.md 的「五问重启测试」一节给出了同样的五个问题及其答案来源——其中「我做了什么」的答案来源明确指向 progress.md。换言之这五问是否都能答上来就是检验「上下文管理是否健康」的判据。模板从哪来init-session.sh 的工程化生成progress.md 不必手写。仓库中的 scripts/init-session.sh 会在初始化规划会话时自动生成三个文件task_plan.md、findings.md、progress.md。其write_default_progress函数scripts/init-session.sh生成的默认版本采用了一套简化但自洽的结构# Progress Log ## Session: 日期 ### Current Status - **Phase:** 1 - Requirements Discovery - **Started:** 日期 ### Actions Taken - ### Test Results | Test | Expected | Actual | Status | |------|----------|--------|--------| ### Errors | Error | Resolution | |-------|------------|可以看到默认生成版与模板版在区块命名上略有差异如### Actions Taken对应模板的动作列表但「当前状态 动作 测试 错误」四要素完全一致。此外还有write_analytics_progress函数scripts/init-session.sh面向数据分析类任务生成变体将测试结果表替换为「查询日志表」Query Log列结构为Query | Result Summary | Interpretation——这与仓库中 analytics 专用模板 的配套思路一致说明 progress.md 的表结构是按任务类型可裁剪的。从源码看scripts/init-session.sh生成逻辑是幂等的目标目录已存在progress.md时直接跳过并打印「already exists, skipping」绝不覆盖已有日志——这保证了跨会话恢复时历史记录安全。init-session.sh还支持通过参数选择 legacy 根目录模式或命名任务目录slug 模式生成的三个文件会落到被选中的任务目录中。状态联动progress.md 与 check-complete.sh 和 Stop 钩子progress.md 与完成度检查脚本存在直接联动。在 scripts/check-complete.sh 的默认advisory仅提示路径中当任务尚未全部完成时脚本输出[planning-with-files] Task in progress (X/Y phases complete). Update progress.md before stopping.也就是说Agent 每次被 Stop 钩子拦下时都会收到「先更新 progress.md 再停止」的显式提示。这形成了一条强制纪律停止工作 先把会话日志写盘。如果所有阶段完成脚本则提示「ALL PHASES COMPLETE」如需继续应先在task_plan.md中新增阶段——此时 SKILL.md 的规则 7「完成后继续」要求追加一个新的会话条目到 progress.md再按既定流程继续。在 v3 的 gate完成闸门模式下check-complete.sh --gate用「账本行数」而非 progress.md 的 mtime 来判断任务是否停滞stall 检测因为 mtime 在文件被任何触碰时都会变化而账本行数是语义信号——这从侧面说明 progress.md 在 v3 长任务设计中更多承担「人类可读日志」的角色机器判定则交给结构化账本详见下文。钩子如何驱动 progress.md 的写入与恢复progress.md 的价值来自「每轮都被记住、每轮都被想起」。仓库的钩子系统围绕它做了三件事PostToolUse 提醒。SKILL.md 的钩子调度中PostToolUse匹配Write|Edit事件并触发skill-hook.sh --eventposttool。历史上的实现是用 systemMessage 提示「Update progress.md with what you just did」但该字段只展示给用户、模型看不到后续版本改为通过hookSpecificOutput.additionalContext注入使提示真正进入模型上下文见 CHANGELOG.md 中对应条目。这是「Agent 每写完一个文件就被提醒落盘日志」的工程细节。PreCompact 提醒。在 Claude Code 的自动压缩和手动/compact触发PreCompact钩子事件时若存在task_plan.md钩子会提醒模型在压缩完成前先把上下文中的进度冲刷到 progress.md见 CHANGELOG.md。这正是为「压缩即失忆」设计的最后防线。/plan-loop 心跳。/plan-loop斜杠命令与 Claude Code 的/loop原语组合默认以 10 分钟为心跳间隔重新读取规划文件并运行check-complete如果自上一拍以来 progress.md 没有新增条目就在其中追加一条汇总当前状态提交、改动文件、错误的记录。其配套的 循环模板 给出了完整的 tick 动作序列重读task_plan.md、progress.md与findings.md最近 20 行 → 运行完成度检查 → 若无新条目则追加 → 若有阶段完成则更新**Status:**→ 依检查结果推进下一阶段或停止。这使长时无人值守任务具备自我记录的心跳机制。五问重启的完整链路从 /clear 到上下文恢复「五问重启检查」不只是模板里的一张表它与整个恢复链路绑定。根据 MIGRATION.md 的恢复说明五个问题的答案来源分别是task_plan.md的当前阶段、剩余阶段、目标陈述、findings.md、以及 progress.md 中的记录。恢复流程的实际执行路径是会话恢复时钩子通过resolve-plan-dir.sh或.ps1依据PLAN_ID与PWF_PLAN_ROOT解析出被选中的任务目录从该目录读取task_plan.md、progress.md、findings.md重建「我在哪、我做过什么、我知道什么」运行git diff --stat查看尚未记录的代码变更五问自检通过即可继续工作。/clear、崩溃、压缩之后Agent 不需要任何会话记录存储——它只读项目规划文件即可恢复这正是 planning-with-files 被称为 crash-proof 的原因。阿拉伯语 SKILL.md 明确自动恢复路径只读取项目规划文件绝不自动读取 Agent 会话记录存储只有用户显式请求时才能通过session-catchup.py --metadata聚合计数或--replay受限回放访问本地会话记录。性能与安全边界时间戳归一化与 v3 账本替代progress.md 是「上下文注入」的一部分因此它的格式直接关系到 KV-cache 命中率与安全边界KV-cache 卫生v2.40。早期实现注入的是tail -20 progress.md的字面内容其中带亚秒级的时间戳如THH:MM:SS.fracZ或带时区后缀的形式每次触发都变化破坏了前缀缓存。v2.40 起注入前先用sed -E把这类时间戳归一化为稳定的T00:00:00Z形式见 CHANGELOG.md。模型看到的仍是相同的进度结构只有易变的子字段被折叠——这是把 Manus 上下文工程原则中的「保持提示前缀稳定」落到 progress.md 的具体实现。v3 账本替代原始 tail。在 autonomous 与 gated 模式下原始progress.md尾部不再被注入取而代之的是ledger-summary.sh合成的固定形状摘要tick 数、阶段完成数、in_progress 阶段标题、各 Agent 最后事件类型该块不含时间戳、不含磁盘自由文本天然 KV-cache 稳定。动机记录在 CHANGELOG.md 中progress.md 不受 attestation完整性认证覆盖无人值守运行期间追加到其中的指令式文本原本每轮都会进入上下文存在注入风险。机器账本存放于.planning/id/ledger-agent.jsonl每 Agent 一行一个 JSON 事件追加写入协调者只拥有task_plan.md工人追加自己的账本——这意味着在 v3 长任务模式下progress.md 退居为人类可读的时间线索引结构化状态由账本承载这同时解决了注入风险与缓存稳定性两个问题。此外还有「平行写入防护」若后续轮次检测到勾选项或已完成阶段数量回退会给出警示——这是写后咨询式检查而非锁机制它无法检测每一次被覆盖的 progress.md 或 findings.md因此 SKILL.md 的规则要求共享摘要保持单一写入者工人使用各自的账本或专属文件。更新时机与反模式速查综合模板尾部说明「在完成每个阶段、执行验证、或遇到错误后更新本文件」与 SKILL.md 的读写决策矩阵progress.md 的更新时机可归纳为每个阶段完成时更新状态并记录动作、受影响文件每次验证/测试后填写测试结果表每个错误发生时立即写入错误日志表即使已修复会话中断/压缩前冲刷当前进度完成全部阶段但用户要求继续时追加新的会话条目长时间无进展时由/plan-loop心跳自动追加汇总条目。对应地仓库明确列出的反模式包括把 TodoWrite 当作可持续的计划机制、把错误藏起来静默重试、把大块内容塞进上下文而不是磁盘、把外部不可信内容网页/API 结果写进task_plan.md它会被钩子高频注入放大——外部内容应只进findings.md而 progress.md 中的一切内容在读取时也应被当作结构化数据而非指令见 循环模板 的注意事项。小结progress.md 表面上只是一份 Markdown 日志模板实际上是 planning-with-files「持久化工作记忆」三角中最活跃的一角它被 init-session.sh 幂等生成被 PostToolUse 与 PreCompact 钩子驱动写入被/plan-loop心跳维持新鲜度被check-complete.sh的提示与 gate 机制约束更新纪律其尾部注入经过时间戳归一化与 v3 账本替代双重改造以兼顾缓存性能与注入安全。无论任务历经多少次/clear与压缩「我做了什么」这个问题的答案都永远留在磁盘上——这正是 Agent 长任务得以跨会话续跑的地基。【免费下载链接】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），仅供参考 planning-with-files 进度日志（progress.md）实战指南：会话记录、测试结果与五问重启恢复
planning-with-files 进度日志progress.md实战指南会话记录、测试结果与五问重启恢复【免费下载链接】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-filesprogress.md是 planning-with-files 文件规划体系中负责「记录已发生之事」的持久化日志层它以时间线形式保存每个阶段执行了什么、改动过哪些文件、测试验证结果如何、出现过哪些错误从而让 AI 编码 Agent 在经历/clear、上下文压缩compaction、崩溃甚至多天跨会话任务后仍能仅凭磁盘上的 Markdown 文件无损恢复工作状态。本文以 progress.md 阿拉伯语模板 为骨架逐段拆解其结构设计并结合仓库中的模板生成脚本、生命周期钩子、完成度检查脚本与 v3 账本机制说明这张「会话日志」表在长任务中如何被写入、被注入、被用于恢复以及如何安全地避免它成为上下文注入的攻击面。progress.md 在文件规划体系中的位置planning-with-files 的核心思路是把 Agent 的「工作记忆」从易失的上下文窗口迁移到磁盘上的三个 Markdown 文件。在 阿拉伯语版 SKILL.md 的「文件用途」表中三者的分工被定义得很清楚文件用途更新时机task_plan.md阶段、进度、决策每个阶段完成后findings.md研究、发现任何发现之后progress.md会话日志、测试结果整个会话期间持续用该模板自己的话说progress.md 是一份「持续不断的日志记录已执行的内容与发生的事件」应当在每个阶段完成时、每次出现错误时、以及任何需要留下可供恢复工作的证据时被更新。它与task_plan.md计划未来要做什么和findings.md沉淀学到了什么形成互补计划回答「要去哪」发现回答「知道了什么」而 progress.md 回答「做了什么、验证了什么、踩过什么坑」。值得注意的边界是progress.md 与task_plan.md、findings.md、.planning/目录默认都会被 gitignore属于「工作记忆」而非受跟踪的交付物——任务结束后由下一次任务覆盖值得留存的内容应被提升为代码、提交或文档这一点在 README.md 中有明确说明。模板结构逐段拆解一个完整会话日志长什么样阿拉伯语模板与 英文标准模板 逐段对应定义了一份 progress.md 应当包含的全部区块。下面按原模板顺序完整展开并逐项说明。文件头与「会话」分区文件以# 进度日志# Progress Log开头随后是「会话」分区## 会话: [日期]用清晰格式的工作日期替换占位符例如2026-01-15。一个文件可以容纳多个会话分区——当任务跨天、或在/clear后重新恢复时新的一天追加一个新的## 会话:分区形成完整的时间线而不是覆盖旧记录。阶段条目状态、开始时间、动作与文件清单每个阶段使用三级标题组织### 阶段 1: [标题] - **状态:** in_progress - **开始于:** [时间戳] - 已采取的动作: - - 已创建/修改的文件: -模板明确要求状态取值只能使用pending、in_progress、complete三者之一与task_plan.md使用的状态词汇保持一致开始时间用可读格式记录。动作与文件路径要在阶段推进过程中不断补充具体内容——这正是恢复会话时判断「我到底干到哪一步」的第一手证据。注意与task_plan.md的分工task_plan.md里也有阶段状态但那是「路线图上的标记」progress.md 里的阶段条目则是「已经发生的动作流水账」。task_plan.md负责告诉你「阶段 1 处于 in_progress」progress.md 负责告诉你「in_progress 期间我实际执行了哪些命令、改了哪些文件」。测试结果表验证证据的结构化沉淀模板为验证工作预留了五列表格测试输入预期实际状态每个验证命令或场景都应记录测的是什么、输入是什么、预期结果、实际观测结果、最终状态。这保证了「某个改动是否通过验证」不依赖 Agent 的记忆而是落在磁盘上可复查的结构化数据。在 analytics 专用变体中见下文这张表会被替换为「查询日志表」。错误日志表杜绝重复失败的机制模板的第二张表专用于错误时间戳错误尝试次数解决方案1模板的要求是每个错误在发生当下立即记录即使很快被修复保留尝试次数与解决方案使「失败的路径」不会再次被走一遍。这与 SKILL.md 的规则 5「记录所有错误」、规则 6「绝不重复失败」if 操作失败: 下一步 ! 同一步骤以及「三重失败协议」尝试 1 诊断修复 → 尝试 2 换一种方法 → 尝试 3 重新质疑假设 → 仍失败则询问用户直接呼应。错误日志表就是这套纪律落盘的地方。五问重启检查表会话恢复的自检清单模板最后一张表是整个 progress.md 的灵魂问题答案我在哪里阶段 X我要去哪里剩余阶段目标是什么[目标陈述]我学到了什么参见 findings.md我做了什么参见上文这五个问题的设计意图是恢复会话时Agent或人类只需打开 progress.md 和兄弟文件就能回答「当前进度、剩余工作、目标、知识沉淀、已完成动作」五个维度从而把上下文窗口里已经丢失的状态完整重建。阿拉伯语版 SKILL.md 的「五问重启测试」一节给出了同样的五个问题及其答案来源——其中「我做了什么」的答案来源明确指向 progress.md。换言之这五问是否都能答上来就是检验「上下文管理是否健康」的判据。模板从哪来init-session.sh 的工程化生成progress.md 不必手写。仓库中的 scripts/init-session.sh 会在初始化规划会话时自动生成三个文件task_plan.md、findings.md、progress.md。其write_default_progress函数scripts/init-session.sh生成的默认版本采用了一套简化但自洽的结构# Progress Log ## Session: 日期 ### Current Status - **Phase:** 1 - Requirements Discovery - **Started:** 日期 ### Actions Taken - ### Test Results | Test | Expected | Actual | Status | |------|----------|--------|--------| ### Errors | Error | Resolution | |-------|------------|可以看到默认生成版与模板版在区块命名上略有差异如### Actions Taken对应模板的动作列表但「当前状态 动作 测试 错误」四要素完全一致。此外还有write_analytics_progress函数scripts/init-session.sh面向数据分析类任务生成变体将测试结果表替换为「查询日志表」Query Log列结构为Query | Result Summary | Interpretation——这与仓库中 analytics 专用模板 的配套思路一致说明 progress.md 的表结构是按任务类型可裁剪的。从源码看scripts/init-session.sh生成逻辑是幂等的目标目录已存在progress.md时直接跳过并打印「already exists, skipping」绝不覆盖已有日志——这保证了跨会话恢复时历史记录安全。init-session.sh还支持通过参数选择 legacy 根目录模式或命名任务目录slug 模式生成的三个文件会落到被选中的任务目录中。状态联动progress.md 与 check-complete.sh 和 Stop 钩子progress.md 与完成度检查脚本存在直接联动。在 scripts/check-complete.sh 的默认advisory仅提示路径中当任务尚未全部完成时脚本输出[planning-with-files] Task in progress (X/Y phases complete). Update progress.md before stopping.也就是说Agent 每次被 Stop 钩子拦下时都会收到「先更新 progress.md 再停止」的显式提示。这形成了一条强制纪律停止工作 先把会话日志写盘。如果所有阶段完成脚本则提示「ALL PHASES COMPLETE」如需继续应先在task_plan.md中新增阶段——此时 SKILL.md 的规则 7「完成后继续」要求追加一个新的会话条目到 progress.md再按既定流程继续。在 v3 的 gate完成闸门模式下check-complete.sh --gate用「账本行数」而非 progress.md 的 mtime 来判断任务是否停滞stall 检测因为 mtime 在文件被任何触碰时都会变化而账本行数是语义信号——这从侧面说明 progress.md 在 v3 长任务设计中更多承担「人类可读日志」的角色机器判定则交给结构化账本详见下文。钩子如何驱动 progress.md 的写入与恢复progress.md 的价值来自「每轮都被记住、每轮都被想起」。仓库的钩子系统围绕它做了三件事PostToolUse 提醒。SKILL.md 的钩子调度中PostToolUse匹配Write|Edit事件并触发skill-hook.sh --eventposttool。历史上的实现是用 systemMessage 提示「Update progress.md with what you just did」但该字段只展示给用户、模型看不到后续版本改为通过hookSpecificOutput.additionalContext注入使提示真正进入模型上下文见 CHANGELOG.md 中对应条目。这是「Agent 每写完一个文件就被提醒落盘日志」的工程细节。PreCompact 提醒。在 Claude Code 的自动压缩和手动/compact触发PreCompact钩子事件时若存在task_plan.md钩子会提醒模型在压缩完成前先把上下文中的进度冲刷到 progress.md见 CHANGELOG.md。这正是为「压缩即失忆」设计的最后防线。/plan-loop 心跳。/plan-loop斜杠命令与 Claude Code 的/loop原语组合默认以 10 分钟为心跳间隔重新读取规划文件并运行check-complete如果自上一拍以来 progress.md 没有新增条目就在其中追加一条汇总当前状态提交、改动文件、错误的记录。其配套的 循环模板 给出了完整的 tick 动作序列重读task_plan.md、progress.md与findings.md最近 20 行 → 运行完成度检查 → 若无新条目则追加 → 若有阶段完成则更新**Status:**→ 依检查结果推进下一阶段或停止。这使长时无人值守任务具备自我记录的心跳机制。五问重启的完整链路从 /clear 到上下文恢复「五问重启检查」不只是模板里的一张表它与整个恢复链路绑定。根据 MIGRATION.md 的恢复说明五个问题的答案来源分别是task_plan.md的当前阶段、剩余阶段、目标陈述、findings.md、以及 progress.md 中的记录。恢复流程的实际执行路径是会话恢复时钩子通过resolve-plan-dir.sh或.ps1依据PLAN_ID与PWF_PLAN_ROOT解析出被选中的任务目录从该目录读取task_plan.md、progress.md、findings.md重建「我在哪、我做过什么、我知道什么」运行git diff --stat查看尚未记录的代码变更五问自检通过即可继续工作。/clear、崩溃、压缩之后Agent 不需要任何会话记录存储——它只读项目规划文件即可恢复这正是 planning-with-files 被称为 crash-proof 的原因。阿拉伯语 SKILL.md 明确自动恢复路径只读取项目规划文件绝不自动读取 Agent 会话记录存储只有用户显式请求时才能通过session-catchup.py --metadata聚合计数或--replay受限回放访问本地会话记录。性能与安全边界时间戳归一化与 v3 账本替代progress.md 是「上下文注入」的一部分因此它的格式直接关系到 KV-cache 命中率与安全边界KV-cache 卫生v2.40。早期实现注入的是tail -20 progress.md的字面内容其中带亚秒级的时间戳如THH:MM:SS.fracZ或带时区后缀的形式每次触发都变化破坏了前缀缓存。v2.40 起注入前先用sed -E把这类时间戳归一化为稳定的T00:00:00Z形式见 CHANGELOG.md。模型看到的仍是相同的进度结构只有易变的子字段被折叠——这是把 Manus 上下文工程原则中的「保持提示前缀稳定」落到 progress.md 的具体实现。v3 账本替代原始 tail。在 autonomous 与 gated 模式下原始progress.md尾部不再被注入取而代之的是ledger-summary.sh合成的固定形状摘要tick 数、阶段完成数、in_progress 阶段标题、各 Agent 最后事件类型该块不含时间戳、不含磁盘自由文本天然 KV-cache 稳定。动机记录在 CHANGELOG.md 中progress.md 不受 attestation完整性认证覆盖无人值守运行期间追加到其中的指令式文本原本每轮都会进入上下文存在注入风险。机器账本存放于.planning/id/ledger-agent.jsonl每 Agent 一行一个 JSON 事件追加写入协调者只拥有task_plan.md工人追加自己的账本——这意味着在 v3 长任务模式下progress.md 退居为人类可读的时间线索引结构化状态由账本承载这同时解决了注入风险与缓存稳定性两个问题。此外还有「平行写入防护」若后续轮次检测到勾选项或已完成阶段数量回退会给出警示——这是写后咨询式检查而非锁机制它无法检测每一次被覆盖的 progress.md 或 findings.md因此 SKILL.md 的规则要求共享摘要保持单一写入者工人使用各自的账本或专属文件。更新时机与反模式速查综合模板尾部说明「在完成每个阶段、执行验证、或遇到错误后更新本文件」与 SKILL.md 的读写决策矩阵progress.md 的更新时机可归纳为每个阶段完成时更新状态并记录动作、受影响文件每次验证/测试后填写测试结果表每个错误发生时立即写入错误日志表即使已修复会话中断/压缩前冲刷当前进度完成全部阶段但用户要求继续时追加新的会话条目长时间无进展时由/plan-loop心跳自动追加汇总条目。对应地仓库明确列出的反模式包括把 TodoWrite 当作可持续的计划机制、把错误藏起来静默重试、把大块内容塞进上下文而不是磁盘、把外部不可信内容网页/API 结果写进task_plan.md它会被钩子高频注入放大——外部内容应只进findings.md而 progress.md 中的一切内容在读取时也应被当作结构化数据而非指令见 循环模板 的注意事项。小结progress.md 表面上只是一份 Markdown 日志模板实际上是 planning-with-files「持久化工作记忆」三角中最活跃的一角它被 init-session.sh 幂等生成被 PostToolUse 与 PreCompact 钩子驱动写入被/plan-loop心跳维持新鲜度被check-complete.sh的提示与 gate 机制约束更新纪律其尾部注入经过时间戳归一化与 v3 账本替代双重改造以兼顾缓存性能与注入安全。无论任务历经多少次/clear与压缩「我做了什么」这个问题的答案都永远留在磁盘上——这正是 Agent 长任务得以跨会话续跑的地基。【免费下载链接】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），仅供参考