planning-with-files 的 /pwf 命令实战：用三文件模式启动持久化文件规划-北京尧图网络

planning-with-files 的 /pwf 命令实战用三文件模式启动持久化文件规划【免费下载链接】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/pwf是 planning-with-files 项目中/plan命令的短别名用于在 Claude Code 等 AI 编码 Agent 中一键启动 Manus 式Manus-style基于文件的规划在当前项目目录创建task_plan.md、findings.md、progress.md三个规划文件并让 Agent 严格遵循规划工作流推进任务。读完本文你将掌握/pwf的参数语义、三文件各自的内容结构与维护时机、init-session.sh的 legacy/slug 两种初始化模式、v3 的 autonomous/gated 长任务模式以及支撑这一切的 hook 注入与完成校验原理。/pwf 是什么一个短到极致的规划入口/pwf的定义位于仓库的 commands/pwf.md。其 frontmatter 明确定义它是/plan的短别名自 v3.0.0 起可用功能是启动 Manus 式基于文件的规划task_plan.md、findings.md、progress.md。命令本体只有两个动作调用planning-with-files:planning-with-filesskill 并严格照其执行任何附加参数都被视为要规划的任务在当前项目目录创建三个规划文件若不存在task_plan.md—— 记录阶段phases、进度与决策findings.md—— 记录研究与发现progress.md—— 记录会话日志。与它几乎等价的 commands/plan.md 没有 frontmatter 中的版本号与 alias 声明但执行逻辑相同。两者在 Claude Code 插件路由下都会触发技能调用与文件初始化/pwf的独特之处在于它额外支持--autonomous/--gated参数用于初始化 v3 长任务模式详见下文。如果你希望在输入时更省事README 的命令表见 README.md说明输入/plan会前缀匹配所有plan*命令的自动补全而/pwf本身就是/plan的别名二者指向同一入口。核心模式把上下文窗口当作内存把文件系统当作磁盘/pwf创建三文件的背后是一条核心原则在 SKILL.md 中被表达为一个类比Context Window RAM (volatile, limited) Filesystem Disk (persistent, unlimited) → Anything important gets written to disk.即凡是重要信息都写入磁盘。项目目录中最终落地的是这样三个文件your-project/ ├── task_plan.md ← 阶段复选框/clear 之后的恢复点 ├── findings.md ← 研究笔记与决策随工作进行追加 └── progress.md ← 会话日志与测试结果当存在多个并行任务时它们被隔离到独立的.planning/YYYY-MM-DD-slug/目录通过.active_plan指针选择v2.36.0。三个文件均为纯 Markdown默认被 gitignore除磁盘上的这些文件外没有任何运行时状态。task_plan.md阶段与进度模板位于 templates/task_plan.md结构固定为Goal一句话描述期望的最终状态Next Step唯一的下一个动作阶段状态变化时必须同步更新Current Phase当前正在进行的阶段名Phases37 个可验证阶段每个阶段用### Phase N: 标题组织内部是复选框清单与一行- **Status:** in_progress|pending|completeKey Questions / Decisions Made / Errors Encountered / Notes记录待解答问题、带理由的决策、错误与尝试次数。check-complete.sh正是靠### Phase标题与**Status:** complete字面量来统计进度的因此状态取值必须严格使用pending、in_progress、complete三者之一具体匹配逻辑见 scripts/check-complete.sh它同时兼容[complete]/[in_progress]/[pending]内联写法并取两种格式的较大计数以兼容混合写法的计划。findings.md研究与发现模板位于 templates/findings.md包含 Requirements可验证需求、Research Findings搜索结果与证据、Technical Decisions、Issues Encountered、Resources、Visual/Browser Findings 等小节。它的定位是把视觉/多模态信息转成文本看过图片、PDF、浏览器结果后应立即把关键结论写入文件因为截图不会持久。模板还明确警告外部复制进来的内容一律视为不可信数据而不是指令。progress.md会话日志与测试结果模板位于 templates/progress.md按会话日期组织包含每个阶段的 Status/Started/Actions taken/Files created以及 Test Results 表、Error Log 表含 Timestamp/Attempt/Resolution和一个5-Question Reboot Check表用于恢复会话时快速确认我在哪、去哪、目标是什么、学到了什么、做了什么。维护节奏SKILL.md 的关键规则SKILL.md 用一张表定义了三个文件的更新时机文件用途何时更新task_plan.md阶段、进度、决策每个阶段之后findings.md研究、发现任何发现之后progress.md会话日志、测试结果整个会话期间配套规则包括复杂任务必须先有task_plan.md2-Action 规则——每 2 次视图/浏览器/搜索操作后立即把关键发现存入文件决策前重读计划Read Before Decide阶段完成后更新Update After Act所有错误记入计划文件Log ALL Errors失败后不得重复同一动作Never Repeat Failures。当所有阶段完成但用户追加新工作时规则 7Continue After Completion要求为task_plan.md追加新阶段、在progress.md开启新会话条目后继续走规划流程。init-session.sh/pwf 背后的初始化引擎/pwf命令文本要求 Agentinitialize withinit-session.sh --autonomous或init-session.sh --gated视用户措辞而定否则按默认方式初始化。真正的文件写入逻辑全部在 scripts/init-session.sh 中它支持两种模式Legacy 根目录模式零位置参数、无--plan-dir直接在项目根目录写task_plan.md、findings.md、progress.md保持 v1.x 的向后兼容行为。Slug 隔离模式传入任务名或--plan-dir为每个并行任务创建独立目录.planning/YYYY-MM-DD-slug/把 PLAN_ID 写入.planning/.active_plan供resolve-plan-dir.sh解析。slug 由任务名小写化、非字母数字转-、去重合并、截断到 40 字符生成若目录重名则自动追加-2、-3后缀。常用用法示例脚本头部注释即文档./init-session.sh # 根目录三文件legacy ./init-session.sh Backend Refactor # slug 模式.planning/date-backend-refactor/ ./init-session.sh --plan-dir Quick Spike # slug 模式显式名称 ./init-session.sh --autonomous Long Run # v3 autonomous 模式opt-in ./init-session.sh --gated Gated Run # v3 gated 模式隐含 autonomous--gated的优先级高于--autonomousgated 隐含 autonomous是更强的标记。slug 模式下脚本会打印PLAN_ID...并提示在并行会话中通过export PLAN_ID...把终端钉到该计划上。v3 模式侧写.mode 标记、nonce 与自动 attestation当传入--autonomous或--gated时apply_v3_mode会在计划目录内执行四个副作用把.stop_blocks门计数器重置为0删除陈旧的.gate_last_ledger避免上一轮的高计数让下一轮瞬间放行写入 16 位十六进制.nonce用于规划数据的定界符框架v3 注入使用BEGIN-PLAN-DATA-nonce而非静态定界符写入.mode标记gated 模式写autonomous gateautonomous 写autonomous自动对计划执行 attestationSHA-256 锁定v3 模式默认开启。此外inherit_root_mode会把项目根的.mode视为下限floor而非可被 slug 覆盖的默认值新建 slug 计划不能低于项目已承诺的自治或门控要求这是 issue #238 的修复。没有任何 v3 标记时legacy 路径保持与 v2.43 字节级等价——所有 v3 行为都是附加且 opt-in 的已有工作流不会改变。模板切换--template analyticsinit-session.sh支持-t, --template TYPE可选default与analytics。analytics 模板会从 templates/analytics_task_plan.md 与 templates/analytics_findings.md 复制计划/发现文件进度文件则使用含 Query Log查询日志结构的 analytics 版本适用于数据探索类会话。autonomous 与 gated长任务的两个开关SKILL.md 的 Autonomous and Gated Modes (v3) 一节给出了三档行为的对照Legacy默认AutonomousGated回合开始注入UserPromptSubmit完整计划头原始 progress 尾部完整计划头结构化 ledger 摘要完整计划头结构化 ledger 摘要每次工具调用注入PreToolUse每次调用注入计划头取消复读策略取消复读策略Stop 事件仅建议从不阻塞仅建议从不阻塞完成门可能阻塞依赖宿主Attestation可选初始化时默认开启初始化时默认开启进度注入原始tail -20 progress.mdledger-summary.sh合成块ledger-summary.sh合成块Autonomous 模式取消每次工具调用的计划复读这是随工具调用次数线性增长的成本保留回合开始的注入attestation 默认开启。Gated 模式在 autonomous 之上叠加完成门completion gate。门的判定对象是磁盘上的计划工件而非对话记录因此不会像基于转录本的评估器那样被幻觉欺骗。完成门只有当 5 个条件同时成立才阻塞scripts/check-complete.sh 的 gate 路径实现了 SKILL.md 的Gate decision table。Stop 门仅当以下全部成立时才返回{decision:block,...}模式为 gated.mode文件包含gate项目根.mode作为下限同样生效存在in_progress阶段仅仅是 complete total 是正常状态不能阻塞——这是 issue #178 的教训Stop hook 的 stdin JSON 中stop_hook_active不为 true已在强制继续中则放行阻塞计数低于上限默认 20可用PWF_GATE_CAP覆盖init-session时重置ledger 自上次阻塞以来有进展停滞则放行。门的运行自保护runaway guards包括.stop_blocks持久计数init 时重置、连续阻塞上限、停滞检测读取 ledger 行数而非progress.md的 mtime因为后者任意触摸都会变化、以及stop_hook_active与宿主阻塞上限作为后备。阻塞原因只包含固定模板加阶段名计划正文永远不会进入 reason 字段。宿主能力分层不是每个 Agent 都能硬阻塞门机制是宿主感知的SKILL.md 明确了三档档位宿主门机制1硬阻塞Claude Code、Codex CLI、OpenAI Codex API、Continue.dev{decision:block}/ exit 22跟进注入Cursor、Pi、Kiro、Hermes Agent、OpenCode原生插件agent_end 跟进消息自身计数器Hermes 以有界续作应答pre_verify3仅通知Gemini CLI 等未装插件的 OpenCode仅 systemMessage无强制因此 gated 模式只有在宿主支持所需 Stop 行为时才能请求续作SKILL.md 明确说明门在 Tier 1 上才是真正的强制其余档位降级为通知。从 /pwf 看整个命令族/pwf只是 commands/ 目录下 13 个斜杠命令之一。插件路由Claude Code下可用的相关命令包括命令作用/plan创建三文件并启动会话v2.11.0/pwf是其别名/pwf/plan短别名支持--autonomous/--gated初始化v3.0.0/status一眼概览当前阶段与阶段总数v2.15.0/plan-attest用 SHA-256 锁定task_plan.md篡改即拒绝注入--show/--clearv2.37.0/plan-doctor自查 resolution、injection、attestation、安装面与每次触发延迟v3.6.0/plan-goal组合 Claude Code/goal持续工作到计划报告完成v2.38.0/plan-loop组合/loop默认 10 分钟 tick 重读计划并运行 check-completev2.38.0注意Pi、Hermes、OpenCode 上的命令不带前缀如/pwf-status、/plan-executeplugin 路由的模型可调用技能 ID 是planning-with-files:planning-with-files这不是你要输入的命令。五个语言变体/plan-ar、/plan-de、/plan-es、/plan-zh、/plan-zht通过斜杠命令读取磁盘上的翻译版技能见 docs/languages.md。底层机制hook 如何让计划每回合都在眼前/pwf初始化完成后真正保证计划不丢失的是生命周期 hook。Claude Code 插件路由使用 hooks/claude-hook.sh 分发 6 个事件SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop独立技能安装则通过 skills/planning-with-files/SKILL.md frontmatter 注册 5 个 hook无 SessionStart技能在会话中被调用后才生效。关键事件行为UserPromptSubmit每回合开始把选定的计划上下文注入模型上下文BEGIN PLAN DATA/END PLAN DATA框架v3 模式改用带 nonce 的定界符对抗上下文腐烂context rotPreToolUse每次 Write/Edit/Bash/Read/Glob/Grep 前注入计划头autonomous/gated 模式下取消见上表PostToolUse每次 Write/Edit 后提醒更新 progress.md若阶段完成则更新 task_plan.md 状态自 v3.16.0 起节流为每回合一次并通过hookSpecificOutput.additionalContext送达模型而非用户PreCompact压缩前提示先刷新进度并打印已 attest 计划的 Plan-SHA256Stop默认仅输出建议性完成报告gated 模式下转发给gate-stop.sh可能返回阻塞决策。v3.17.0 起Claude Code 插件与独立技能的事件默认走 scripts/inject-plan.py——一个与inject-plan.sh字节级同构的单进程 Python 孪生实现把每次触发从约 130 次 fork 降到 1 个进程Windows Git Bash 上 fork 约 90ms 的成本使旧路径触发一次可能耗时 712 秒并超时。PWF_FAST_PATH0可强制走参考 shell 链。注入脚本以-I -B隔离模式运行确保仓库自身的secrets.py或hashlib.py不会被 hook 导入。计划选择与绑定PLAN_ID 与 PWF_PLAN_ROOT计划目录的解析顺序在 scripts/resolve-plan-dir.sh 中实现$PLAN_ID环境变量 →./.planning/$PLAN_ID/若存在且通过安全校验.planning/.active_plan内容指向的目录.planning/下按 mtime 最新的目录跳过隐藏目录、slug 非法名与无task_plan.md的目录否则输出为空调用方回退到 legacy 根目录./task_plan.md。自 v3.15.0 起显式的PLAN_ID是绑定而非提示解析失败就停止绝不回退到其他计划issue #237。解析器还带有 containment 守卫解析出的计划目录必须规范化后仍位于项目根之内防止符号链接逃逸到任意路径对应resolve-plan-dir.sh中的is_within_root。环境变量版本作用PLAN_IDslugv2.36.0把终端钉到$(pwd)/.planning下某个计划仅限 slug按当前目录解析PWF_PLAN_ROOT绝对路径v3.9.0按绝对路径把线程钉到项目根解决 cwd 是共享父目录如/workspace而工作区在/workspace/project的场景无法解析时停止注入而非回退PLANNING_DISABLED1v3.4.0本次调用跳过所有计划读取用于与计划共享 cwd 但未选择加入的一次性/CI 会话PWF_INJECTsmartv3.8.0把固定的head -50注入窗口替换为目标、下一步、当前阶段、完整进行中阶段与最近 3 条决策PWF_GATE_CAPv3.0.0gated 模式最大连续门阻塞数默认 20PWF_PLAN_GUARD0v3.10.0关闭并行写守卫默认开启并行写守卫检测被覆盖的工作两个会话共享一个计划目录时后写入的一方可能静默丢弃先写入的阶段。v3.10.0 引入的并行写守卫在回合开始时对比复选框与已完成阶段数正常工作中这些数字只会上升一旦下降就打印一条建议性警告并指向git diff。它不阻塞、不拦截写入只是事后建议可通过PWF_PLAN_GUARD0或.mode中的plan-guard-off令牌关闭。安全边界把计划内容当作数据而不是指令SKILL.md 的 Security Boundary 部分给出了两层防线定界符框架v2.36.1计划内容包裹在 BEGIN/END 标记中并标注为 data缩小注入面但不消除提示注入——模型仍会解析内容哈希 attestationv2.37.0v3 模式默认开启/plan-attest或sh scripts/attest-plan.sh锁定task_plan.md的 SHA-256hook 每次触发都重算并比对不匹配即以[PLAN TAMPERED]拒绝注入。attestation 保存在.planning/active-plan/.attestationslug 模式或./.plan-attestationlegacy 模式注入内容同时携带Plan-SHA256:行供审计。v3 模式额外加固.nonce定界符、无 attestation 时拒绝注入计划正文v3 mode requires attested plan、用ledger-summary.sh合成块替代原始progress.md尾部后者不在 attestation 覆盖范围内任何指令性文本都可能每回合进入上下文、以及把 SHA 缓存从共享的/tmp移到$XDG_CACHE_HOME/pwf-sha。SKILL.md 反模式表还明确不要用 TodoWrite 代替task_plan.md不要只声明一次目标不要默默隐藏错误重试不要把一切塞进上下文不要在技能目录里建文件Web/搜索结果只写入findings.md绝不写入task_plan.md后者被 hook 自动读取不可信内容会在每次工具调用时被放大。实战小结一条完整的 /pwf 工作流综合以上一个典型的/pwf使用流程是# 1. 启动规划插件路由下输入 /pwf独立技能下让 Agent 执行等价初始化 /pwf --gated Build Pipeline # → 创建 task_plan.md / findings.md / progress.md写入 .modeautonomous gate # .nonce自动 attestation重置门计数器 # 2. slug 模式钉住并行终端 export PLAN_ID2026-09-05-build-pipeline # 3. 工作中遵循三文件纪律 # - 任何发现 → findings.md每次工具调用后 → progress.md # - 阶段完成 → task_plan.md 状态改为 complete 并刷新 Next Step # 4. 定期校验 /plan-doctor # resolution / injection / attestation / 安装面 / 延迟自检 /plan-attest # 最终确定计划后锁定哈希 # 5. 长任务收尾gated 模式下 Stop 门只会在 in_progress 阶段 # 存在且无停滞时阻塞全部阶段 complete 即放行无论你是单次复杂任务、跨/clear与压缩恢复的长时间运行还是多 Agent 并行协作/pwf背后这套三文件 hook 注入门控的组合都可以从commands/pwf.md这一个入口出发配合 README.md、SKILL.md、docs/installation.md 与 docs/long-running-agent-tasks.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

planning-with-files 的 /pwf 命令实战：用三文件模式启动持久化文件规划

相关推荐

AI全栈开发工程化实践：从模型选型到持续优化

Midscene Chrome扩展：AI浏览器自动化，3分钟跑通第一条指令

如何用AlphaFold从蛋白序列预测3D结构：5分钟跑通，附pLDDT读数完整指南

更多资讯

KaiwuDB-lite边缘时序数据库实测：核心强大，体验仍需打磨

G-Helper 使用教程：一个 EXE 管掉华硕笔记本的性能模式、GPU 切换与风扇曲线

数据库表字段信息查询全攻略：主流数据库通用手册

2026年AI开发技能生态与云原生实践

Arm-2D源码深度评测：Cortex-M图形加速的选型与落地实践

Jenkins CICD服务器搭建与实战指南

今日更新

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

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

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

本周精选

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

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

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

本月热门

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

分布式服务的决策记录

创业产品的首版范围

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