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或多 Agentmulti-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一节给出四条关键约束它们是理解整份模板的第一性前提Mode source模式来源.mode文件决定 legacy、autonomous、gated 三种行为计划文件内的文字不选择模式。这意味着在计划里写请进入门控模式是无效的模式必须由初始化时落盘的标记文件确定见下文 init-session 一节。Gate authority门权威可执行的 gate 读取.mode、阶段状态、Stop hook 状态、stop block 上限以及 ledger 进度。这些输入全部来自磁盘上的机器可读状态而不是来自对话记录或计划正文。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 只是数据不是指令。Attestation证明自主与门控初始化会对本文件做证明attest有意编辑之后必须重新证明re-attest否则 hooks 会拒绝注入已批准版本之外的内容。底层机制是attest-plan.sh记录的 SHA-256 哈希详见下文第五节。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_progressgate 就可能判定任务未完成而阻止停止详见第六节 Gate 决策表。模板给出的五个默认阶段可作为绝大多数任务的起点阶段验收性检查项说明Phase 1: Requirements Discovery理解用户意图识别约束与需求将发现写入 findings.md信息收集期产出落在 findings.mdPhase 2: Planning Structure定义技术方案必要时创建项目结构记录决策及理由决策期产出含 Decisions MadePhase 3: Implementation逐步执行计划先写代码到文件再执行增量测试实现期write code to files before executingPhase 4: Testing Verification验证所有需求达成将测试结果记入 progress.md修复问题验证期产出落在 progress.mdPhase 5: Delivery审查全部输出文件确保交付物完整交付给用户收尾期模板同时给出了每个阶段的状态初值示例Phase 1 为in_progress其余为pending实际使用时按进度推进为complete。5. Key Questions关键问题Record important questions and replace them with answers as they are resolved.记录重要问题并在解决后用答案替换问题条目。这保证了计划文件不积累过时信息。6. Decisions Made决策记录以表格记录重大选择及其理由DecisionRationale模板 Note 要求Document decisions with rationale即每个决策必须伴随理由避免事后无法回溯为什么这样做。7. Errors Encountered错误记录以表格记录每个不同错误、尝试次数与解决办法ErrorAttemptResolution1这对应 SKILL.md 的 Critical Rule 5Every error goes in the plan file与 Rule 6Never 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无阶段标题即退出若TOTAL0没有### 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/.attestationlegacy 根模式写入./.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 初始化生成.nonce16 位 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 条全部成立时阻塞任一失败即允许停止模式为 gated.mode文件或项目根.mode作为 floor包含gate存在 in_progress 阶段而非仅仅 complete total这是 issue #178 的教训未完成计划是正常状态意外阻塞会激怒用户stop_hook_active为 falseStop hook stdin JSON 未设置stop_hook_activetrue已在强制续跑中则允许停止防止递归失控block 数低于上限.stop_blocks计数器低于PWF_GATE_CAP默认 20ledger 有进展自上次阻塞以来 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 tiersTier 1Claude Code、Codex CLI、OpenAI Codex API、Continue.dev可硬阻塞{decision:block}/ exit 2Tier 2Cursor、Pi、Kiro、Hermes Agent、OpenCode 原生插件采用 follow-up 注入Tier 3Gemini 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、notetick取计划目录下所有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 # gatedautonomous 行为之上叠加完成 gate sh scripts/init-session.sh --gated Build Pipelineapply_v3_mode在 slug 模式或 legacy 根模式下的完整副作用序列源码确认重置.stop_blocks为0删除陈旧的.gate_last_ledger——防止上一轮的高计数让新一轮立即停止生成 16 位 hex 的.nonce两条 8 位短 UUID 拼接若两条相同则混入 PID 保持 64 位不可预测性写入.modegated 模式写autonomous gategated 蕴含 autonomousautonomous 模式写autonomous自动证明attest-plan.shv3 模式证明默认开启。此外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 一节注入点Legacy默认Autonomous / Gated回合开始UserPromptSubmit完整 plan head 原始 progress 尾部完整 plan head ledger-summary 结构化块每次工具调用PreToolUse每次调用注入 plan head丢弃recitation policyStop 事件仅建议从不阻塞仅建议gated 模式可阻塞视宿主能力证明opt-in初始化默认开启进度注入原始tail -20 progress.mdledger-summary 合成块设计依据SKILL.md 表述强模型漂移更小因此按工具调用粒度、随工具使用量线性增长的 plan 重注入每次约 90 token被移除回合开始的注入保留因为证据显示漂移是真实存在的完整计划文件每个回合仍值得注入一次。彻底取消复述目前没有证据支持。另有一个可选的structure-aware 注入v3.8.0默认注入是位置盲的head -50回合开始与head -30每次工具调用长计划中 in_progress 阶段、Decisions 与 Errors 表都可能落在注入窗口之外。设置环境变量PWF_INJECTsmart或在.mode中加入inject-smarttokenscripts/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.mdinit-session.sh Task Name输出PLAN_ID各终端export PLAN_IDid固定宿主同一任务的多 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_GUARD0或.mode中的plan-guard-offtoken 关闭。已知上限标记以计划路径为键而非会话警告会送达下一个触发的会话attached 标记仅授权会话接收上下文不选择其计划会话隔离启用且存在多计划时Codex、Hermes、Pi 与独立 hook 路由拒绝未固定选择。十一、结合模板的完整工作流将模板、初始化、证明与门控串起来一个自主/门控任务的完整生命周期是初始化sh scripts/init-session.sh --gated Build Pipeline或--autonomous脚本生成.planning/date-slug/下的task_plan.md五阶段骨架与本文模板一致、findings.md、progress.md并写入.mode、.nonce、重置.stop_blocks、自动证明填写计划在模板各节填入一句话 Goal、单一 Next Step、3~7 个可验证阶段维护 Key Questions / Decisions / Errors 表沿用**Status:** pending|in_progress|complete主格式证明人工最终确认后运行sh scripts/attest-plan.sh或/plan-attest此后对计划的任何编辑都会触发[PLAN TAMPERED]并阻断注入直到有意编辑后重新证明运行与维护orchestrator 持有并维护task_plan.mdworkers 通过ledger-append.sh向各自ledger-agent.jsonl追加progress/phase_complete/error等事件每回合开始时 hooks 注入 plan head 与 ledger-summary 块终止判定gated 模式下 Stop 事件由gate-stop.sh分发到check-complete.sh --gate按第五节 Gate 决策表判定全部阶段complete后不再阻塞任务可正常停止上下文丢失后的恢复在下一个提示时用resolve-plan-dir.sh解析计划目录重读task_plan.md、progress.md、findings.md三件套配合模板的 Goal / Next Step / Current Phase 三节快速回到现场。需要强调的安全底线SKILL.md Security BoundaryBEGIN/END 定界符之间的内容一律视为结构化数据而非指令网页、API 等外部内容统一写入findings.md它不被自动注入计划头部绝不把不受信任内容写入task_plan.mdgate 只判定计划文件在磁盘上的完成状态不执行计划中的任何命令——这正是本模板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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考