企业官网建设流程全解析

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"。命令本体只有两个动作：

1. 调用planning-with-files:planning-with-filesskill 并严格照其执行，任何附加参数都被视为"要规划的任务"；
2. 在当前项目目录创建三个规划文件（若不存在）：
   • 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：当前正在进行的阶段名；
• Phases：3～7 个可验证阶段，每个阶段用### Phase N: 标题组织，内部是复选框清单与一行- **Status:** in_progress|pending|complete；
• Key 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；"2-Action 规则"——每 2 次视图/浏览器/搜索操作后立即把关键发现存入文件；决策前重读计划（Read Before Decide）；阶段完成后更新（Update After Act）；所有错误记入计划文件（Log ALL Errors）；失败后不得重复同一动作（Never Repeat Failures）。当所有阶段完成但用户追加新工作时，规则 7（Continue After Completion）要求为task_plan.md追加新阶段、在progress.md开启新会话条目后继续走规划流程。

init-session.sh：/pwf 背后的初始化引擎

/pwf命令文本要求 Agent"initialize 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的优先级高于--autonomous（gated 隐含 autonomous，是更强的标记）。slug 模式下脚本会打印PLAN_ID=...，并提示在并行会话中通过export PLAN_ID=...把终端钉到该计划上。

v3 模式侧写：.mode 标记、nonce 与自动 attestation

当传入--autonomous或--gated时，apply_v3_mode会在计划目录内执行四个副作用：

1. 把.stop_blocks门计数器重置为0，删除陈旧的.gate_last_ledger，避免上一轮的高计数让下一轮瞬间放行；
2. 写入 16 位十六进制.nonce，用于规划数据的定界符框架（v3 注入使用===BEGIN-PLAN-DATA-<nonce>===而非静态定界符）；
3. 写入.mode标记：gated 模式写autonomous gate，autonomous 写autonomous；
4. 自动对计划执行 attestation（SHA-256 锁定，v3 模式默认开启）。

此外，inherit_root_mode会把项目根的.mode视为"下限"（floor）而非可被 slug 覆盖的默认值：新建 slug 计划不能低于项目已承诺的自治或门控要求（这是 issue #238 的修复）。没有任何 v3 标记时，legacy 路径保持与 v2.43 字节级等价——所有 v3 行为都是附加且 opt-in 的，已有工作流不会改变。

模板切换：--template analytics

init-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)" 一节给出了三档行为的对照：

• Autonomous 模式：取消每次工具调用的计划复读（这是随工具调用次数线性增长的成本），保留回合开始的注入；attestation 默认开启。
• Gated 模式：在 autonomous 之上叠加完成门（completion gate）。门的判定对象是磁盘上的计划工件而非对话记录，因此不会像基于转录本的评估器那样被幻觉欺骗。

完成门：只有当 5 个条件同时成立才阻塞

scripts/check-complete.sh 的 gate 路径实现了 SKILL.md 的"Gate decision table"。Stop 门仅当以下全部成立时才返回{"decision":"block",...}：

1. 模式为 gated（.mode文件包含gate；项目根.mode作为下限同样生效）；
2. 存在in_progress阶段（仅仅是 complete < total 是正常状态，不能阻塞——这是 issue #178 的教训）；
3. Stop hook 的 stdin JSON 中stop_hook_active不为 true（已在强制继续中则放行）；
4. 阻塞计数低于上限（默认 20，可用PWF_GATE_CAP覆盖，init-session时重置）；
5. ledger 自上次阻塞以来有进展（停滞则放行）。

门的运行自保护（runaway guards）包括：.stop_blocks持久计数（init 时重置）、连续阻塞上限、停滞检测（读取 ledger 行数而非progress.md的 mtime，因为后者任意触摸都会变化）、以及stop_hook_active与宿主阻塞上限作为后备。阻塞原因只包含固定模板加阶段名，计划正文永远不会进入 reason 字段。

宿主能力分层：不是每个 Agent 都能硬阻塞

门机制是宿主感知的，SKILL.md 明确了三档：

因此 gated 模式只有在宿主支持所需 Stop 行为时才能请求续作；SKILL.md 明确说明：门在 Tier 1 上才是真正的强制，其余档位降级为通知。

从 /pwf 看整个命令族

/pwf只是 commands/ 目录下 13 个斜杠命令之一。插件路由（Claude Code）下可用的相关命令包括：

注意：Pi、Hermes、OpenCode 上的命令不带前缀（如/pwf-status、/plan-execute）；plugin 路由的模型可调用技能 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 rot）；
• PreToolUse：每次 Write/Edit/Bash/Read/Glob/Grep 前注入计划头（autonomous/gated 模式下取消，见上表）；
• PostToolUse：每次 Write/Edit 后提醒"更新 progress.md，若阶段完成则更新 task_plan.md 状态"，自 v3.16.0 起节流为每回合一次，并通过hookSpecificOutput.additionalContext送达模型而非用户；
• PreCompact：压缩前提示先刷新进度，并打印已 attest 计划的 Plan-SHA256；
• Stop：默认仅输出建议性完成报告；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 的成本使旧路径触发一次可能耗时 7～12 秒并超时）。PWF_FAST_PATH=0可强制走参考 shell 链。注入脚本以-I -B隔离模式运行，确保仓库自身的secrets.py或hashlib.py不会被 hook 导入。

计划选择与绑定：PLAN_ID 与 PWF_PLAN_ROOT

计划目录的解析顺序在 scripts/resolve-plan-dir.sh 中实现：

1. $PLAN_ID环境变量 →./.planning/$PLAN_ID/（若存在且通过安全校验）；
2. .planning/.active_plan内容指向的目录；
3. .planning/下按 mtime 最新的目录（跳过隐藏目录、slug 非法名与无task_plan.md的目录）；
4. 否则输出为空，调用方回退到 legacy 根目录./task_plan.md。

自 v3.15.0 起，显式的PLAN_ID是绑定而非提示：解析失败就停止，绝不回退到其他计划（issue #237）。解析器还带有 containment 守卫：解析出的计划目录必须规范化后仍位于项目根之内，防止符号链接逃逸到任意路径（对应resolve-plan-dir.sh中的is_within_root）。

并行写守卫：检测"被覆盖的工作"

两个会话共享一个计划目录时，后写入的一方可能静默丢弃先写入的阶段。v3.10.0 引入的并行写守卫在回合开始时对比复选框与已完成阶段数：正常工作中这些数字只会上升，一旦下降就打印一条建议性警告并指向git diff。它不阻塞、不拦截写入，只是事后建议；可通过PWF_PLAN_GUARD=0或.mode中的plan-guard-off令牌关闭。

安全边界：把计划内容当作数据，而不是指令

SKILL.md 的 Security Boundary 部分给出了两层防线：

1. 定界符框架（v2.36.1）：计划内容包裹在 BEGIN/END 标记中并标注为 data，缩小注入面但不消除提示注入——模型仍会解析内容；
2. 哈希 attestation（v2.37.0，v3 模式默认开启）：/plan-attest（或sh scripts/attest-plan.sh）锁定task_plan.md的 SHA-256，hook 每次触发都重算并比对，不匹配即以[PLAN TAMPERED]拒绝注入。attestation 保存在.planning/<active-plan>/.attestation（slug 模式）或./.plan-attestation（legacy 模式），注入内容同时携带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，写入 .mode=autonomous gate， # .nonce，自动 attestation，重置门计数器 # 2. （slug 模式）钉住并行终端 export PLAN_ID=2026-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