planning-with-files 长时间运行指南：用 Autonomous / Gated 模式、完成闸门与运行账本让编码 Agent 连续工作数小时不漂移、不空转-北京尧图网络

planning-with-files 长时间运行指南用 Autonomous / Gated 模式、完成闸门与运行账本让编码 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导读当编码 Agent 连续运行数小时最常见的两种失败是「偏离原始目标」和「反复循环却永远不判定完成」。本文基于 docs/long-running-agent-tasks.md 展开完整讲解 planning-with-files 自 v3 起为无人值守长任务提供的两个 opt-in 模式——Autonomous自主与 Gated带完成闸门——以及支撑它们的磁盘计划文件、逐轮再注入、运行账本run ledger、SHA-256 计划认证attestation与失控防护机制。读完你将掌握如何用一条命令启动长任务会话、完成闸门在何种条件下才会真正拦住 Agent 停止、账本如何做到 KV-cache 稳定以及这套机制实测的 token 与时间成本边界。长时间运行的 Agent 为什么会漂移一个运行数小时的编码 Agent其失败方式高度可预测本质都是状态问题目标不在注意力窗口里或者什么时候算完成没有可判定的依据。目标被挤出窗口超过 50 次工具调用后最初的 goal 会被后续上下文逐渐挤占错误重复发生没有落盘的错误不会被记住同一个错误反复犯上下文塞爆所有信息都塞进 context window 而不是写进文件一旦窗口刷新一切归零。planning-with-files 对此的基线对策是3-file pattern在磁盘上维护task_plan.md、findings.md、progress.md三个文件并由生命周期 hooks 在每一轮开始时重新注入计划。目标之所以能留在注意力窗口里是因为存在一个机制每轮把它放回去而不是寄希望于模型记得去看。这套文件同时让「上下文死亡」在任务中途变得可存活如果会话在第 3 小时崩溃新会话直接从磁盘恢复而不是从头开始。恢复机制详见 docs/agent-forgets-plan-after-clear.md/clear 后的文件化修复与 docs/claude-code-lost-context-after-compaction.mdcompaction 后的恢复与预防。Autonomous 模式去掉随调用次数放大的背诵开销Autonomous 模式是为无人值守运行设计的第一个 v3 模式启动方式两种等价/pwf --autonomous Task name sh scripts/init-session.sh --autonomous Task name从 scripts/init-session.sh 的源码可以看到--autonomous标志的实际副作用写入.mode标记文件内容为autonomous、生成 16 位十六进制 nonce.nonce用于注入定界符防混淆、重置.stop_blocks门控计数器、清理陈旧的.gate_last_ledger并自动对计划执行 attestationapply_v3_mode 段。它保留了每轮开头的计划注入但去掉了每次工具调用时的计划复诵plan recitation。复诵的成本约为每个匹配工具调用 90 tokens是唯一随工具使用量线性增长的组件。为什么只去掉它而保留每轮注入项目的判断是强模型漂移更少每轮一次的锚定已足够但完全去掉锚定没有证据支持——这也是 SKILL.md 中legacy invariant承诺的一部分不加任何模式标记时hooks 输出与 v2.43 逐字节一致两个 v3 模式都是显式 opt-in存量安装零变化。Autonomous 模式还做了两件默认行为变更默认开启 attestation无人值守循环会放大任何一次注入攻击见下文以及用结构化账本摘要替换原始progress.md尾部注入。Gated 模式与完成闸门计划不完会话不能说服自己完成Gated 模式在 Autonomous 行为之上叠加了一个Stop gate完成闸门/pwf --gated Task name sh scripts/init-session.sh --gated Gated Run--gated是更强的标记从源码看它会覆盖先前的--autonomousinit-session.sh并把.mode写成autonomous gate两个 token。闸门的核心设计哲学是它评判的是磁盘上的计划产物而不是对话记录——因此一个会话无法靠嘴炮把自己说成已完成。在实现层闸门由 scripts/gate-stop.sh 作为 Stop hook 分发器调用 scripts/check-complete.sh 的--gate模式实现。check-complete.sh的判定表Gate mode 段要求以下所有条件同时成立才拦截停止.mode文件包含gate显式 opt-in且项目根的.mode是地板约束slug 计划只能提高严格度、不能降低见 check-complete.sh Guard 1存在in_progress阶段——注意不是完成数总数单纯 incomplete 是正常状态绝不拦截这是 issue #178 的教训Guard 2stop_hook_active为 false——若已处于强制续跑内部则放行停止避免递归失控Guard 3拦截计数低于上限默认 20可用PWF_GATE_CAP覆盖Guard 4自上次拦截以来账本有推进——停滞即放行Guard 5。任何一个条件不满足都放行停止因此计划不完整单独永远不会困住会话。拦截时的 reason 是固定模板加上唯一的阶段名json_escape 与 first_in_progress_phase计划正文文本永不进入 reason非 Gated 模式下措辞永远是 advisory建议式绝不用命令式——这是 PR #180 的教训reason 字段里的命令式文本会被当成续跑指令。主机能力分层闸门是真拦截还是通知闸门是否需要主机具备阻塞式 Stop hook按能力分三层见 SKILL.md Host capability tiers层级平台行为Tier 1硬拦截Claude Code、Codex、ContinueStop 被真正阻塞Tier 2续跑注入Cursor、Pi、Kiro、Hermes Agent、OpenCode原生插件agent_end后续注入自带计数器Hermes 以pre_verify应答有界续跑Tier 3仅通知Gemini CLI 等其余平台仅systemMessage无强制没有阻塞式 Stop hook 的主机仍然能获得 Autonomous 模式低复诵账本只是闸门退化为通知——文档对此是诚实披露的真正强制只在 Tier 1 生效。Runaway guards无人值守循环必须有界无人值守循环的失控防护不依赖宿主脾气全部是确定性机制check-complete.sh 实现持久化拦截计数器.planning/id/.stop_blocks在 init-session 时重置为 0连续拦截上限默认 20 次PWF_GATE_CAP可改达到上限后闸门放行停止保证任务在极端情况下也能收敛退出停滞检测自上次拦截以来没有新的账本行说明模型没有在推进闸门放行停止而非空转。其中计数器与停滞检测是确定性的stop_hook_active与宿主的拦截上限是兜底backstop。配合前面提到的主机能力分层形成确定性判定宿主感知执行的双层结构。Run ledger机器的运行记录v3 模式中运行的机器记录是一个追加式 JSONL 文件.planning/id/ledger-agent.jsonl每行一个 JSON 对象。写入侧是 scripts/ledger-append.sh它支持的合法事件类型有progress、phase_complete、error、gate_block、attest、note每行结构为{tick:N,ts:ISO8601Z,agent:...,phase:...,event:...,summary:...,files:[...]}其中tick是跨所有ledger-*.jsonl的最大值 1max_tick_in_dir多 Agent 并发共享同一单调计数器停滞检测看到的是一条有序流summary截断到 200 字符并保证 UTF-8 合法utf8_trim_incomplete写入在可用时用 advisoryflock保护避免并发追加拿到相同 tick。典型用法sh scripts/ledger-append.sh phase_complete Phase 2 verified --agent worker-a --phase 2 sh scripts/ledger-append.sh progress wrote test cases --files tests/test_x.py,tests/test_y.py每个回合真正进入模型上下文的是 scripts/ledger-summary.sh 合成的固定形状摘要 RUN LEDGER entries: N phases: complete/total complete in_progress: phase heading or none agent name: last event type ... 这一设计有三点值得注意见 ledger-summary.sh 头部注释磁盘上的自由文本零进入上下文摘要只由账本条目数与task_plan.md的阶段计数合成不注入progress.md的原始尾部无时间戳输出块逐字节稳定因此按构造就是 KV-cache 稳定的——这对 KV 缓存敏感的长会话至关重要闸门的停滞检测读的是账本语义信号而不是progress.md的 mtime任何触摸都会移动它若计划目录不可确定显式PLAN_ID/PWF_PLAN_ROOT被拒绝、resolver 缺失会输出明确标记的ledger: unavailable (...)块而非自信的phases: 0/0 complete——后者会被自治循环误读为终止信号emit_unavailable。无人值守循环的 Attestation注入前先验明正身无人值守循环会在每个 tick 放大任何一次提示注入因此 v3 模式在 init 时就对计划做 attestationattest-plan.sh用 SHA-256 锁定task_plan.mdhooks 每次触发时重新哈希比对一旦计划正文与已认证哈希不符注入被拒绝并给出[PLAN TAMPERED]提示。scripts/attest-plan.sh 提供三种操作sh scripts/attest-plan.sh # 认证当前活动计划 sh scripts/attest-plan.sh --show # 打印存储的哈希及 nonce sh scripts/attest-plan.sh --clear # 清除认证重新开放计划实现要点attest 分支哈希先写入临时文件再原子 rename可用时加 advisoryflock写入后回读校验哈希不一致则大声失败rc ! 0绝不静默留下陈旧认证。legacy 根模式存./.plan-attestationslug 模式存.planning/id/.attestation。两个 v3 模式更进一步拒绝注入任何未认证的计划——没有 attestation 时 hook 输出[planning-with-files] v3 mode requires attested plan; run attest-plan而不是计划正文。这意味着无人值守的 v3 循环永远不会注入没有匹配记录摘要的计划正文。任务中途编辑计划需要显式重新 attest。完整的安全边界说明见 SKILL.md 安全章节与 docs/attestation-locking.md。实测成本多花约 68% token、17% 时间换来什么稳态下 hooks 每轮用户回合重新注入约330 tokens外加每个匹配工具调用约90 tokensAutonomous 模式去掉的正是按调用计费的那部分。项目的正式评测详见 docs/evals.md含完整方法与披露的限制显示完整工作流平均比无结构运行多消耗约68% token、17% 时间19,926 vs 11,899 tokens。回报则在恢复基准上体现项目内部 recovery benchmarkv1作者运行、确定性评分中硬清上下文后续跑的新会话平均 5.0 轮恢复裸 Agent 为13.3 轮且所有分组、所有评分运行都 pytest-green 通过——差异是重新定向成本而非正确性。文档给出明确的适用边界如果任务在 5 次工具调用内完成跳过这个 skill——这套结构只在工作长到会丢失时才值得付出成本。安装两条主要路径Claude Code 走插件路线附带 skill、hooks 与斜杠命令/plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-filesplanning-with-files其余 Agent 走 Agent Skills 标准一行安装npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g完整的安装路径矩阵与验证方法见 README 与 docs/installation.md。相关页面Claude Code lost context after compaction: how to recover and prevent itMy coding agent forgets the plan after /clear: the file-based fixAttestation locking计划认证与并行会话的锁语义Evals基准方法、原始数据与披露的限制SKILL.mdv3 Autonomous and Gated Modes 契约【免费下载链接】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 长时间运行指南：用 Autonomous / Gated 模式、完成闸门与运行账本让编码 Agent 连续工作数小时不漂移、不空转

相关推荐

Docker-Android：零配置在 Docker 里跑起安卓模拟器

Remix `auth` 包版本演进全解：从组合式认证原语到 `createOAuthProvider()` 开放扩展

MuJoCo相机系统实战：3种机位模式+关键调参，拍出专业仿真画面

更多资讯

Java递归中Scanner资源管理的优化实践

亲测8个降AIGC平台：从AI率53%降到6%的完整方法论

Modbus转MQTT实战：边缘网关协议转换与数据透传全解析

440V三相逆变器各相保护设计与实现

虚拟机环境下的ROS SLAM算法调试与优化实践

MySQL大小写与存储引擎：表名规则、InnoDB/MyISAM选型及排查指南

今日更新

Linux 内核 ARM 虚拟内存布局全解析：从 4GB 地址空间划分到源码级验证

AIGC降重工具测评与教育应用指南

数据容灾核心指标与实战方案解析

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？