planning-with-files 自主任务计划模板解析：用 task_plan_autonomous 驱动无人值守的长时 Agent 任务

planning-with-files 自主任务计划模板解析：用 task_plan_autonomous 驱动无人值守的长时 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

本文围绕 planning-with-files 技能中面向自主（autonomous）与门控（gated）模式的任务计划模板 task_plan_autonomous.md，系统讲解如何在多阶段、无人值守、多 Agent 协作场景下把一份 Markdown 计划文件变成可执行的"磁盘上的工作记忆"：包括模板各章节的填写规范、阶段状态机的唯一合法取值、运行时行为契约（.mode模式来源、Gate 决策表、命令边界、证明与协调），并结合仓库源码说明init-session.sh、check-complete.sh、ledger-*与attest-plan.sh在底层如何支撑这套机制。读完本文，你将掌握用该模板初始化、维护、证明并正确终止一个自主/门控任务的全过程。

一、模板定位：为什么需要一份"自主模式专用"的任务计划

planning-with-files 的常规模板 templates/task_plan.md 面向普通多步任务；而 templates/task_plan_autonomous.md 专为长时运行、自主（autonomous）、门控（gated）或多 Agent（multi-agent）任务设计。两者共享相同的阶段骨架，但自主模板在文件头部额外声明了四条运行时行为契约，明确该文件在整个运行期间的角色边界。

模板开头的使用说明非常直接：

Use this file as the durable roadmap for a long-running, autonomous, gated, or multi-agent task. Keep its goal, next step, and phase status current throughout the run.

即：这份文件是任务的持久化路线图，运行期间必须持续保持"目标、下一步、阶段状态"三项信息的实时性。它与 SKILL.md 中"Context Window = RAM（易失、有限），Filesystem = Disk（持久、无限）"的核心模式一脉相承——重要信息必须先落盘，上下文窗口只负责"读取-决策"。

与 legacy 模式的关系

在 SKILL.md 的 "Autonomous and Gated Modes (v3)" 一节中明确：v3 的两种模式都是**显式加入（opt-in）**的。模式由计划目录旁的.mode文件决定（.planning/<id>/.mode，或 legacy 根模式的./.mode）。没有.mode文件时，行为与 v2.43 完全字节等价——模板正文中的文字并不会选择模式，这一点在模板的 Runtime Behavior 中被反复强调。

二、Runtime Behavior：自主/门控计划的四条运行时契约

模板在## Runtime Behavior一节给出四条关键约束，它们是理解整份模板的第一性前提：

1. Mode source（模式来源）：.mode文件决定 legacy、autonomous、gated 三种行为；计划文件内的文字不选择模式。这意味着在计划里写"请进入门控模式"是无效的，模式必须由初始化时落盘的标记文件确定（见下文 init-session 一节）。

2. Gate authority（门权威）：可执行的 gate 读取.mode、阶段状态、Stop hook 状态、stop block 上限以及 ledger 进度。这些输入全部来自磁盘上的机器可读状态，而不是来自对话记录或计划正文。

3. Command boundary（命令边界）：gate 永远不会执行计划文件中声明的命令。任何写在计划里的任务指派、依赖、验收命令或模型选择都只是描述性的（descriptive only），不是 gate 的输入。这是 SKILL.md 安全边界中"Optional gated mode can request continuation only through a capable host. It evaluates mode, phase status, Stop-hook state, block count, and ledger progress; it never executes commands declared in Markdown"的直接对应——Markdown 只是数据，不是指令。

4. Attestation（证明）：自主与门控初始化会对本文件做证明（attest）；有意编辑之后必须重新证明（re-attest），否则 hooks 会拒绝注入已批准版本之外的内容。底层机制是attest-plan.sh记录的 SHA-256 哈希（详见下文第五节）。

5. Coordination（协调）：始终保持**一个 orchestrator（编排者）**负责计划状态；workers 应通过各自的 ledger 或 findings 报告结果，而不是并发编辑同一份task_plan.md。这与 SKILL.md 的 "Assign one plan owner" 规则以及 ledger 契约（"Workers append to their own ledger; the orchestrator owns task_plan.md"）完全一致。

三、模板骨架逐节拆解与填写规范

自主模板在 Runtime Behavior 之后是八个业务章节。以下按模板顺序逐节说明其语义与维护时机。

1. Goal（目标）

State the intended end result in one clear sentence.

用一句话描述期望的最终状态。模板要求把抽象意图压缩为一个可判定的终点描述，因为它是每次重大决策前重新阅读的锚点（模板 Notes 中明确要求 "Re-read the goal and next step before major decisions"），也是/plan-goal类机制推导终止条件的语义来源之一。

2. Next Step（下一步）

Record the single action that should happen next. Update it whenever the active phase or immediate action changes.

记录唯一的下一个动作。每当活动阶段或即时动作变化时必须更新。它是上下文旋转/压缩（compaction）后快速恢复执行的指针；SKILL.md 的 Critical Rule 4 明确："Whenever a phase status changes, also refresh## Next Stepintask_plan.mdso it names the single next action."

3. Current Phase（当前阶段）

命名当前正在进行的阶段，例如Phase 1。它与各阶段内的**Status:**行配合，为"5-Question Reboot Test"中的"Where am I?"提供答案来源。

4. Phases（阶段划分与状态机）

Break the task into three to seven verifiable phases. Use onlypending,in_progress, orcompletefor each status and update the value when work advances. In gated mode, anin_progressphase is one of the gate inputs.

阶段划分的两条硬性约束：

• 数量：3 到 7 个可验证阶段（verifiable phases）。太少则粒度不足，太多则超出模板与 gate 的合理负担。
• 状态取值：只允许pending/in_progress/complete三种；且在门控模式下，in_progress阶段是 gate 的输入之一——只要有阶段处于in_progress，gate 就可能判定"任务未完成"而阻止停止（详见第六节 Gate 决策表）。

模板给出的五个默认阶段，可作为绝大多数任务的起点：

模板同时给出了每个阶段的状态初值示例（Phase 1 为in_progress，其余为pending），实际使用时按进度推进为complete。

5. Key Questions（关键问题）

Record important questions and replace them with answers as they are resolved.

记录重要问题，并在解决后用答案替换问题条目。这保证了计划文件不积累过时信息。

6. Decisions Made（决策记录）

以表格记录重大选择及其理由：

模板 Note 要求"Document decisions with rationale"，即每个决策必须伴随理由，避免事后无法回溯"为什么这样做"。

7. Errors Encountered（错误记录）

以表格记录每个不同错误、尝试次数与解决办法：

这对应 SKILL.md 的 Critical Rule 5（"Every error goes in the plan file"）与 Rule 6（"Never Repeat Failures"）以及 3-Strike Error Protocol——失败后必须改变方法再重试，而不是原样重复同一动作。模板明确指出："Change the approach before retrying a failed action."

8. Notes（维护纪律）

模板以四条注意事项收尾，是整份文件的维护守则：

• 阶段状态按pending→in_progress→complete单向推进；
• 重大决策前重读 Goal 与 Next Step；
• 及时记录错误，避免重复失败路径；
• 多 Agent 活动时串行化计划编辑（serialize plan edits）——与 Runtime Behavior 的协调条款呼应。

四、阶段状态机的完成判定：check-complete.sh 的读取规则

模板规定阶段状态只能取三种值，但 gate 与 hooks 如何"读懂"这些值？答案是 scripts/check-complete.sh。该脚本是完成判定的权威实现，其读取逻辑对模板编写有直接影响：

• 总数统计：grep -c "### Phase"统计### Phase标题行数；
• 三种状态统计：优先匹配**Status:** complete/**Status:** in_progress/**Status:** pending主格式；同时兼容[complete]/[in_progress]/[pending]行内格式，并按两种格式计数的较大值取值（源码注释说明这是为了兼容混用两种格式的计划，防止漏判 in_progress）；
• 无阶段标题即退出：若TOTAL=0（没有### Phase标题），脚本直接退出，不输出虚假的 "0/0 phases complete"，此时 gate 也不可能合法阻塞。

因此，使用本模板时请保持阶段标题以### Phase N:开头、状态行使用**Status:** <值>主格式，这是让完成判定、ledger 汇总与注入全部正确工作的最低要求。相应的测试覆盖见 tests/test_gate.py 与 tests/test_check_complete_resolver.py。

五、证明（Attestation）与编辑纪律

模板 Runtime Behavior 要求"Re-attest after an intentional edit"。这一机制由 scripts/attest-plan.sh 实现：

• 用法：sh scripts/attest-plan.sh对当前活动计划做 SHA-256 证明；--show打印已存哈希；--clear移除证明；
• 存储位置：slug 模式写入.planning/<id>/.attestation，legacy 根模式写入./.plan-attestation；
• 行为：证明之后，hooks 每次触发都会重新计算task_plan.md的 SHA-256 并与已存哈希比对，不一致时拒绝注入计划内容并以[PLAN TAMPERED]警告代替；
• 注入上下文中会附带Plan-SHA256:行，供模型记录已证明哈希以便审计；
• 诚实边界（SKILL.md 明示）：该摘要只是普通本地 SHA-256，而非密钥签名——能同时替换计划与证明文件的过程可以让新内容通过；自动证明记录的是初始化时生成的字节，并不等同于人工审查证明。

v3 模式的额外强化（仅对加入 v3 的计划生效）：

• 默认开启证明：autonomous/gated 初始化即证明计划，非 opt-in；
• 无证明拒绝注入：v3 模式在无证明时根本不注入计划正文，hook 输出[planning-with-files] v3 mode requires attested plan; run attest-plan代替计划内容；
• nonce 分隔符：v3 初始化生成.nonce（16 位 hex），注入分隔符变为===BEGIN-PLAN-DATA-<nonce>===/===END-PLAN-DATA-<nonce>===，提高分隔符混淆（delimiter-confusion）注入的难度；
• 用户私有 SHA 缓存：缓存从/tmp移至$XDG_CACHE_HOME/pwf-sha；门控模式下缓存仅为性能提示，gate 路径始终重新哈希。

六、门控（Gated）模式：Gate 决策表与停止门控

模板指出"in gated mode, anin_progressphase is one of the gate inputs"。完整的 gate 判定由 scripts/check-complete.sh 的--gate分支实现，scripts/gate-stop.sh 作为 Stop-hook 分发器把 Stop hook 的 stdin JSON 透传给 check-complete。

Gate 决策表：全部满足才阻塞

SKILL.md 与 check-complete.sh 源码一致确认，Stop gate仅在以下 5 条全部成立时阻塞（任一失败即允许停止）：

1. 模式为 gated：.mode文件（或项目根.mode作为 floor）包含gate；
2. 存在 in_progress 阶段：而非仅仅 complete < total（这是 issue #178 的教训：未完成计划是正常状态，意外阻塞会激怒用户）；
3. stop_hook_active为 false：Stop hook stdin JSON 未设置stop_hook_active=true（已在强制续跑中则允许停止，防止递归失控）；
4. block 数低于上限：.stop_blocks计数器低于PWF_GATE_CAP（默认 20）；
5. ledger 有进展：自上次阻塞以来 ledger 行数有增长（停滞即允许停止）。

阻塞时输出单行 JSON：

{"decision":"block","reason":"[planning-with-files] Gated plan incomplete: phase '<phase-name>' is in_progress (N/M complete, gate block X/Y). Finish or update the plan, then stop."}

注意 reason 是固定模板加阶段名，计划正文永不出现在 reason 中——这正是模板"Command boundary"条款在实现层的落地：即使是 reason 字段也不会携带计划正文里的指令性文本。

失控防护（Runaway guards）

• .stop_blocks持久计数在 init-session 时重置，防止上一次运行的计数让下一次立即停止；
• 连续阻塞达上限（默认 20）后 gate 允许停止；
• 停滞检测：自上次阻塞无新 ledger 行则允许停止；
• 宿主能力分级（SKILL.md Host capability tiers）：Tier 1（Claude Code、Codex CLI、OpenAI Codex API、Continue.dev）可硬阻塞（{"decision":"block"}/ exit 2）；Tier 2（Cursor、Pi、Kiro、Hermes Agent、OpenCode 原生插件）采用 follow-up 注入；Tier 3（Gemini CLI 等）仅通知。文档如实声明：gate 只有在 Tier 1 才是真正的强制。

七、Ledger：机器层的进度账本

自主/门控模式下，注入的进度信息不再是原始progress.md尾部，而是由 scripts/ledger-summary.sh 从机器 ledger 合成的结构化块，输出格式固定为：

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

该块只含 tick 计数、阶段完成数、in_progress 阶段标题与各 Agent 最后事件类型，不含磁盘上的任何自由文本、不含时间戳，因此天然 KV-cache 稳定——这是"no free text from disk reaches the model context"的实现保证（对应模板 Notes 中"workers report through their own ledgers"的机制基础）。

写入侧由 scripts/ledger-append.sh 完成，向<plan-dir>/ledger-<agent>.jsonl追加一行 JSON：

{"tick":N,"ts":"ISO8601Z","agent":"...","phase":"...","event":"...","summary":"...","files":["..."]}

要点：

• 事件类型白名单：progress、phase_complete、error、gate_block、attest、note；
• tick取计划目录下所有ledger 文件中的最大 tick + 1，多 Agent 共享单调递增计数器（gate 停滞检测读的就是这条有序流）；
• summary 截断至 200 字符并保持合法 UTF-8；--agent名会被消毒为[A-Za-z0-9_-]；
• 有flock时在锁内计算 tick 并写入，避免并发取到同一 tick。

八、初始化：init-session.sh --autonomous / --gated 的完整行为

模板与 scripts/init-session.sh 是配套关系：这份模板正是--autonomous/--gated初始化时所用的计划骨架（write_default_task_plan内嵌的五阶段结构与自主模板一致）。初始化命令：

# autonomous：低复述 + 默认证明 + ledger 摘要 sh scripts/init-session.sh --autonomous "Long Research Run" # gated：autonomous 行为之上叠加完成 gate sh scripts/init-session.sh --gated "Build Pipeline"

apply_v3_mode在 slug 模式或 legacy 根模式下的完整副作用序列（源码确认）：

1. 重置.stop_blocks为0，删除陈旧的.gate_last_ledger——防止上一轮的高计数让新一轮立即停止；
2. 生成 16 位 hex 的.nonce（两条 8 位短 UUID 拼接；若两条相同则混入 PID 保持 64 位不可预测性）；
3. 写入.mode：gated 模式写autonomous gate（gated 蕴含 autonomous），autonomous 模式写autonomous；
4. 自动证明（attest-plan.sh）：v3 模式证明默认开启。

此外，inherit_root_mode保证项目根目录的.mode是下限（floor）：若项目根已提交gate或autonomous，新建 slug 计划不能低于该设定（issue #238）。显式传入的--gated不会被降级。

legacy 模式（无 v3 参数、无.mode文件）时上述副作用全部跳过，行为与 v2.43 字节等价——这与模板 Runtime Behavior 中"Text in this plan does not select the mode"互相印证。

九、自主模式下的注入策略：recitation policy 与 smart 注入

模板所服务的 autonomous 模式回答了"复述（recitation）"问题（SKILL.md v3 一节）：

设计依据（SKILL.md 表述）：强模型漂移更小，因此按工具调用粒度、随工具使用量线性增长的 plan 重注入（每次约 90 token）被移除；回合开始的注入保留，因为证据显示漂移是真实存在的，完整计划文件每个回合仍值得注入一次。彻底取消复述目前没有证据支持。

另有一个可选的structure-aware 注入（v3.8.0）：默认注入是位置盲的head -50（回合开始）与head -30（每次工具调用），长计划中 in_progress 阶段、Decisions 与 Errors 表都可能落在注入窗口之外。设置环境变量PWF_INJECT=smart或在.mode中加入inject-smarttoken（scripts/inject-plan.py 源码：env.get("PWF_INJECT","")=="smart" or mode_has("inject-smart")）后，注入改为：计划标题、Goal / Next Step / Current Phase 三节、阶段数、第一个 in_progress 阶段的完整小节、Decisions Made 最后 3 行。无### Phase标题的计划回退到普通头部。inject-smart独立于 v3 模式，不激活其他 v3 行为，且与 autonomous/gated 可组合（.mode中 token 以空格分隔）。

十、多 Agent 协作与并发写保护

模板要求"Keep one orchestrator responsible for plan status"，与此配套的机制包括：

• 并行任务工作流（SKILL.md）：init-session.sh "Task Name"输出PLAN_ID，各终端export PLAN_ID=<id>固定宿主；同一任务的多 Agent 共享PLAN_ID，一个 orchestrator 持有计划，workers 使用各自 ledger；
• 解析顺序（scripts/resolve-plan-dir.sh）：$PLAN_ID环境变量 →.planning/.active_plan→ 按 mtime 最新的.planning/<dir>/→ legacy 项目根；PWF_PLAN_ROOT以绝对路径固定计划根，优先级最高；显式选择器是绑定而非提示，解析失败即停止，绝不回退到其他计划（issue #237）；
• 并行写保护（v3.10.0，默认开启）：对比回合开始之间勾选项与完成阶段的进度变化，数量下降意味着磁盘上的工作丢失，输出一条建议性警告并指向git diff，随后正常注入——它从不阻塞（hook 总是 exit 0），也不拦截写入；可用PWF_PLAN_GUARD=0或.mode中的plan-guard-offtoken 关闭。已知上限：标记以计划路径为键而非会话，警告会送达下一个触发的会话；
• attached 标记仅授权会话接收上下文，不选择其计划；会话隔离启用且存在多计划时，Codex、Hermes、Pi 与独立 hook 路由拒绝未固定选择。

十一、结合模板的完整工作流

将模板、初始化、证明与门控串起来，一个自主/门控任务的完整生命周期是：

1. 初始化：sh scripts/init-session.sh --gated "Build Pipeline"（或--autonomous），脚本生成.planning/<date>-<slug>/下的task_plan.md（五阶段骨架与本文模板一致）、findings.md、progress.md，并写入.mode、.nonce、重置.stop_blocks、自动证明；
2. 填写计划：在模板各节填入一句话 Goal、单一 Next Step、3~7 个可验证阶段，维护 Key Questions / Decisions / Errors 表；沿用**Status:** pending|in_progress|complete主格式；
3. 证明：人工最终确认后运行sh scripts/attest-plan.sh（或/plan-attest），此后对计划的任何编辑都会触发[PLAN TAMPERED]并阻断注入，直到有意编辑后重新证明；
4. 运行与维护：orchestrator 持有并维护task_plan.md；workers 通过ledger-append.sh向各自ledger-<agent>.jsonl追加progress/phase_complete/error等事件；每回合开始时 hooks 注入 plan head 与 ledger-summary 块；
5. 终止判定：gated 模式下 Stop 事件由gate-stop.sh分发到check-complete.sh --gate，按第五节 Gate 决策表判定：全部阶段complete后不再阻塞，任务可正常停止；
6. 上下文丢失后的恢复：在下一个提示时用resolve-plan-dir.sh解析计划目录，重读task_plan.md、progress.md、findings.md三件套，配合模板的 Goal / Next Step / Current Phase 三节快速回到现场。

需要强调的安全底线（SKILL.md Security Boundary）：BEGIN/END 定界符之间的内容一律视为结构化数据而非指令；网页、API 等外部内容统一写入findings.md（它不被自动注入计划头部），绝不把不受信任内容写入task_plan.md；gate 只判定"计划文件在磁盘上的完成状态"，不执行计划中的任何命令——这正是本模板"Command boundary"条款在整条链路上的最终落点。

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