企业官网建设流程全解析

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-files

progress.md是 planning-with-files 文件规划体系中负责「记录已发生之事」的持久化日志层：它以时间线形式保存每个阶段执行了什么、改动过哪些文件、测试验证结果如何、出现过哪些错误，从而让 AI 编码 Agent 在经历/clear、上下文压缩（compaction）、崩溃甚至多天跨会话任务后，仍能仅凭磁盘上的 Markdown 文件无损恢复工作状态。本文以 progress.md 阿拉伯语模板 为骨架，逐段拆解其结构设计，并结合仓库中的模板生成脚本、生命周期钩子、完成度检查脚本与 v3 账本机制，说明这张「会话日志」表在长任务中如何被写入、被注入、被用于恢复，以及如何安全地避免它成为上下文注入的攻击面。

progress.md 在文件规划体系中的位置

planning-with-files 的核心思路是把 Agent 的「工作记忆」从易失的上下文窗口迁移到磁盘上的三个 Markdown 文件。在 阿拉伯语版 SKILL.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 专用变体中（见下文），这张表会被替换为「查询日志表」。

错误日志表：杜绝重复失败的机制

模板的第二张表专用于错误：

模板的要求是：每个错误在发生当下立即记录，即使很快被修复；保留尝试次数与解决方案，使「失败的路径」不会再次被走一遍。这与 SKILL.md 的规则 5「记录所有错误」、规则 6「绝不重复失败」（if 操作失败: 下一步 != 同一步骤）以及「三重失败协议」（尝试 1 诊断修复 → 尝试 2 换一种方法 → 尝试 3 重新质疑假设 → 仍失败则询问用户）直接呼应。错误日志表就是这套纪律落盘的地方。

五问重启检查表：会话恢复的自检清单

模板最后一张表是整个 progress.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 --event=posttool。历史上的实现是用 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 中的记录。恢复流程的实际执行路径是：

1. 会话恢复时，钩子通过resolve-plan-dir.sh（或.ps1）依据PLAN_ID与PWF_PLAN_ROOT解析出被选中的任务目录；
2. 从该目录读取task_plan.md、progress.md、findings.md，重建「我在哪、我做过什么、我知道什么」；
3. 运行git diff --stat查看尚未记录的代码变更；
4. 五问自检通过，即可继续工作。

/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的字面内容，其中带亚秒级的时间戳（如T<HH:MM:SS>.<frac>Z或带时区后缀的形式），每次触发都变化，破坏了前缀缓存。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