企业官网建设流程全解析

Progress Log

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

Use this file as the chronological record of work performed, files changed, validation results, and errors.

Session: [DATE]

Replace[DATE]with the date of this work session.

文件头明确界定了 progress.md 的四种记录对象：**执行的工作（work performed）**、**变更的文件（files changed）**、**验证结果（validation results）**、**错误（errors）**。每次新的工作会话（Session）都应追加一个 `## Session: [日期]` 区块，而不是覆盖旧内容——这保证了日志的时间顺序完整性，也是后续"重启恢复"时能回溯到任意历史会话的前提。 ### 2.2 阶段（Phase）进度区块 ```markdown ### Phase 1: [Title] - **Status:** in_progress - **Started:** [timestamp] - Actions taken: - - Files created/modified: - Use the same status values as `task_plan.md`: `pending`, `in_progress`, or `complete`. Add concrete actions and paths as the phase advances. ### Phase 2: [Title] - **Status:** pending - Actions taken: - - Files created/modified: -

这是模板中与task_plan.md耦合最紧密的区块，要点有三：

1. 状态值必须与 task_plan.md 完全一致：只有pending、in_progress、complete三个取值。这不是随意的约定——check-complete.sh 用grep -cF "**Status:** complete"和grep -cF "**Status:** in_progress"精确统计阶段完成数，ledger-summary.sh 也使用完全相同的 grep 模式；任何拼写偏差都会导致完成门禁（completion gate）误判。模板还兼容[complete]/[in_progress]/[pending]内联格式，两种格式按字段取较大值混合计数。
2. 记录粒度是"具体动作 + 具体路径"：Actions taken与Files created/modified要求写出真实操作和文件路径，而不是模糊描述。从源码结构看，这正是为了让后续会话或另一个 Agent（worker）能从日志中精确还原已做的工作。
3. 开始时间戳（Started）是可选增强项：模板在 Phase 1 中示范了Started: [timestamp]，Phase 2 则省略——说明时间戳按需添加，但注意 v3 的 ledger 摘要注入（见第五节）会刻意剥离时间戳以保证 KV-cache 稳定。

2.3 测试结果表

## Test Results Record each validation command or scenario, its expected result, and the observed outcome. | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | | | | | |

测试结果表要求每次验证都记录四要素：测试名称、输入、预期结果、实际结果，外加状态列。这与仓库的测试驱动理念一致——check-complete.sh 本身就是"验证所有阶段是否完成"的校验工具，而tests/目录下 90+ 个测试文件（如 test_phase_status_locking.py、test_check_complete_resolver.py）验证的正是这套规划机制自身的可靠性。progress.md 中的测试结果表让"预期 vs 实际"的偏差显式化，任何未通过的测试都会在日志中留下可追踪的记录。

2.4 错误日志表

## Error Log Record errors promptly, including the attempt number and resolution. Change the approach before retrying a failed action. | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | | | 1 | |

错误日志表与 SKILL.md 的"Critical Rules"直接呼应：

• Rule 5: Log ALL Errors——每个错误都必须记入规划文件，"这能积累知识并防止重复"；
• Rule 6: Never Repeat Failures——if action_failed: next_action != same_action，日志要记录尝试过的方案并强制改变下一次行动。

模板中的Attempt列从 1 开始递增，配合 SKILL.md 的3-Strike Error Protocol使用效果最佳：第 1 次尝试诊断修复，第 2 次换一种方法（绝不复用失败的相同动作），第 3 次重新审视假设、考虑更新计划，3 次失败后升级给用户。错误日志就是这套协议的落地载体。

2.5 五问重启检查表（5-Question Reboot Check）

## 5-Question Reboot Check Use this table when resuming to confirm the current phase, destination, goal, findings, and completed work. | Question | Answer | |----------|--------| | Where am I? | Phase X | | Where am I going? | Remaining phases | | What's the goal? | [goal statement] | | What have I learned? | See findings.md | | What have I done? | See above |

这是模板中最具实战价值的区块，专门服务于会话中断后的状态恢复。五个问题的答案来源在 SKILL.md 的 5-Question Reboot Test 中给出：

注意最后一行——"我做了什么"直接指向 progress.md，说明 progress.md 是恢复会话时唯一可信的"已完成工作"证据源。配合 SKILL.md 的"Read vs Write Decision Matrix"中"Resuming after gap → Read all planning files"的指引，中断恢复的标准动作就是：读取 task_plan.md（目标与阶段）、findings.md（已学知识）、progress.md（已完成工作），再用这个表格确认五个答案，即可无缝继续。

模板结尾的*Update this file after completing a phase, running validation, or encountering an error.*是对更新时机的总纲：阶段完成时、运行验证后、遇到错误时，三个触发点覆盖了整个任务生命周期。

三、与 task_plan.md 的状态联动与更新纪律

progress.md 不是孤立文件，它与 task_plan.md 存在强制的状态联动。SKILL.md 的 "Update After Act" 规则规定，每完成一个阶段必须：

1. 将阶段状态从in_progress更新为complete（在两个文件中同步）；
2. 记录遇到的任何错误；
3. 记录创建/修改的文件；
4. 同时刷新task_plan.md的## Next Step，使其指向下一个单一动作。

模板开头 "Use the same status values astask_plan.md" 的说明，正是为了保证这种双向一致：progress.md 里的阶段记录与 task_plan.md 里的状态字段必须使用同一组字面量（**Status:** complete等），因为 check-complete.sh 和 ledger-summary.sh 都基于这些精确字符串做机械统计——这也是为什么所有语言的 i18n 模板（如 planning-with-files-zh 的 progress.md）都刻意保留英文的**Status:** in_progress原文，以便并行写入守卫等机制在语言无关的前提下工作。

任务全部完成后若用户提出新需求，规则是"Continue After Completion"：在 task_plan.md 追加新阶段（Phase 6、Phase 7……），并在 progress.md 中新增一个 Session 记录，然后按常规流程继续——progress.md 作为追加式日志天然支持这种持续增长。

四、progress.md 与生命周期 Hook 的注入机制（源码级）

progress.md 的价值不仅在于人工阅读，更在于它会被系统自动注入到 Agent 的上下文中。理解这一点，你才会明白为什么模板要求"具体动作 + 具体路径"的记录格式。

4.1 默认模式：raw tail 注入

在 inject-plan.sh 的默认（legacy）分支中，每次 Hook 触发都会执行：

tail -20 "$PROGRESS_SOURCE_SNAPSHOT" 2>/dev/null | sed -E 's/T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z/T00:00:00Z/g; ...' | head -c 32769 > "$RAW_PROGRESS"

这段代码揭示了三层设计：

1. 只注入最近 20 行（tail -20），把 token 开销限制在固定预算内，同时head -c 32769设置 32KB 硬上限防止单次注入失控；
2. 时间戳归一化：用sed把所有 ISO 时间戳（含时区偏移）替换为T00:00:00Z形式，这是 KV-cache 稳定性的关键——同一内容在不同时刻注入时字节级一致，避免缓存失效；
3. 快照隔离：注入读取的是私有目录中的快照文件（$PROGRESS_SOURCE_SNAPSHOT），而非实时文件，保证注入内容在 Hook 执行期间不被并发写入破坏。

4.2 PostToolUse 的进度提醒

skill-hook.sh 在每次工具调用后通过additionalContext发出提醒：

[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status.

这条提醒每轮最多触发一次，配合 SKILL.md 的2-Action Rule（每 2 次查看/浏览/搜索操作后立即把关键发现保存到文件）与Read Before Decide（重大决策前先读计划文件），形成"先记录、后决策"的闭环，防止多模态信息（图片、PDF、浏览器结果）在上下文滚动中被丢失。

4.3 PreCompact 钩子中的进度检查

Claude Code 的PreCompact事件（上下文压缩前）会输出诊断提醒（inject-plan.sh）：

[planning-with-files] PreCompact: context compaction is about to occur. Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase. task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.

这正体现了 progress.md 的抗上下文丢失价值：即使会话经历/clear或上下文压缩，三个规划文件始终留在磁盘上，下次提示词到来时会被重新读取，任务状态不会丢失。

五、v3 模式下的演进：从 raw tail 到结构化 ledger 摘要

v3 引入了自治（autonomous）与门控（gated）两种可选模式，其中对 progress.md 最大的改变是注入内容从原始 tail 替换为结构化 ledger 摘要。从 ledger-summary.sh 的头部注释可以看出设计动机：

This replaces rawtail -20 progress.mdinjection in autonomous mode. The output is synthesized from the machine ledger and task_plan.md status counts only: NO free text from disk reaches the model context, and there are NO timestamps, so the injected block is KV-cache stable by construction.

原因在于安全模型：progress.md 不受 attestation（哈希见证）保护，未经审核的长时运行中追加到 progress.md 的任意文本（例如工具输出、抓取的页面摘要）会在每轮被注入上下文，构成提示注入面。v3 因此改为注入固定形状的合成摘要块：

=== RUN LEDGER === entries: <N> phases: <complete>/<total> complete in_progress: <phase heading or none> agent <name>: <last event type> ==================

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