project-plan

---
name: project-plan
description: 写计划、审计划，直到能动手为止的一套流程。主会话当 planner，只负责派单；起草者、审查者（多方向、盲审）、执行者、验收者都是子 agent，各写各的文件。问题带 F 编号跨轮追到关掉，预算按档位计数，用户说「批准 vN」才许执行。用户说「帮我写个计划」「这份计划靠谱吗」「审一下这个方案」「先别写代码，先出计划」「多找几个人挑毛病」「计划做好了吗」，或要在做多步、不可逆的改动前先把方案定死时使用。
---

# 计划审查与执行

一句话：**五个角色、两本账，跑完「需求 → 起草 → 审查 → 合并处置 → 批准 → 执行 → 验收 → 报告」。**

只有主会话能派单。其余四个角色都是子 agent，没有派单权——它们能做什么、能写哪个文件，写在各自的 prompt 里，派单时**整段贴过去**。

## 什么时候用 / 不用

**用**：要做的东西超过一个文件、有几步、会改真实数据或不可逆；或者用户已经在问「这计划行不行」。
**用 plan-only**：用户只要一份可评审的计划、不打算让 DSH 动手时，用 plan-only。
**不用**：一句话能说完的改动、纯问答、用户只要一段代码。直接做，别套流程——流程的成本是几十次派单。
需求含糊时先澄清，别直接开 REQ：先按「阶段 0 之前：需求澄清」问清再落盘。

用户只想听意见时，别开跑：先给结论和依据。

## 开工前：四件事，顺序不能换

1. **建目录**：`<项目>/runs/<slug>/` 下建 `run/`、`reviews/`、`evidence/`、`verify/`；`git init`（项目本身不是 git 就记「降级检查」）。
2. **原话落盘**：用户的原话**逐字**写进 `run/user-words.md`。不改写、不总结、不补标点。起草者只读这个文件，不看对话历史。
3. **定档位**：按 §「档位」判断，把档位和部件清单写进 `run/dispatch.log` 第一行：
   `档位: 普通 | 部件 12 | planner | 2026-11-06T10:00`
4. **定模式**：决定这次跑 `plan-only` 还是 `full`，把模式写进 `runDir/run/mode`（文件里只写一个词）。缺省 `full`：文件不存在或用户没说要只出计划时，按 `full` 走；用户只要可评审的计划、不让 DSH 动手时写 `plan-only`。plan-only 的范围见「九个阶段」表后的说明。

新会话开始，或被上下文压缩后，**第一条命令先跑 `node scripts/status.mjs <runDir>`**，读完输出再动手。`runDir` 还不存在时，先按上一节建目录，再跑。

## 阶段 0 之前：需求澄清（可选）

这是可选前置，不算阶段 0、不占九阶段表；plan-only 与 full 都适用，澄清本身不消耗审查轮。澄清完成后才进阶段 0。

**三条触发（命中任一条必须做，不许跳过）**：

- 说不清验收标准：说不清怎么算做完。
- 两条需求互斥：两条需求同时要又互相排斥。
- 范围含糊：这次做什么、明确不做什么没定。

**出口**：用户说「直接办 / 不用问 / 就按我说的」→ 不澄清，记 `需求澄清: 不需要 | 用户要求直接办`，直接进阶段 0。

**走法**：先看当前可用 skill 列表有没有 grill。有就 `skill(name="grill")` 加载，按它的节奏问，强度由用户定、默认常规；没有就用 `prompts/05-需求澄清.md` 的内置 5 问。

**记录行**：在阶段 0 之前，把逐字一行 `需求澄清: grill|fallback|不需要 | 一句话理由` 记进 `run/dispatch.log`。

**写回**：用户回答**逐字追加**到 `run/user-words.md` 的新节 `## 需求澄清（问答）`，不许重写文件开头的原话；结论、取舍、待定项写进 `run/decisions.md`。澄清完成后才进阶段 0。

**停止条件**：最多问 1–2 轮；剩余未知不挡下一步就停。

## 派单怎么写

子 agent 没有记忆、不知道上一轮。派单 = **对应的 prompt 文件全文** + 本次任务段：

```
<把 prompts/10-起草者.md 整段贴进来>

## 本次任务
runDir: runs/<slug>
轮号: R1
你要读: …/run/user-words.md
你要写: …/REQ.md
```

- **模型和沙箱跟着主对话走**，不要另行指定。
- **推理强度显式传**：起草 `high`、审查 `high`、执行 `low`、验收 `high`。
- 审查者**盲**：只给路径清单，不给 `reviews/`、不给上一轮摘要、不给对话历史。
- 验收者**盲**：只给 `plan.md` + `evidence/` + `run/decisions.md`，不给 `reviews/`。
- **回执固定格式**：`dispatch.log` 每轮一行 `R{n} | 审查 N 路 one-message | 审查者×N | reasoning=low|high | 时间`；行首必须是 `R{n}`，否则 `budget-check` 认不出轮次。
- **两个检查脚本分工**：`budget-check.mjs` 管轮次上限 / 重开 / 回炉；`check-dispatch.mjs` 管每轮审查人数、`one-message`、推理强度值域、`VOID` 原因。

## 等子智能体

子任务没有固定期限。结束回合**不会**终止子智能体，完成通知会开一个新回合，不用守着等。

- 派单后先做不依赖它的活；手头没有活就结束回合，不要用 `sleep` 等完成。
- 禁止无上限 `sleep` 轮询。
- 挂起判定：30 分钟没有任何完成通知，或通知到了但交付物缺失 → 按超时作废、重派，并在 `dispatch.log` 记一行。
- 单回合上限：15 分钟或 40 次工具调用，先到者写 `run/STATE.md` 收尾，字段固定为「停在哪 / 为什么 / 下一步」。

## 九个阶段，每个都有出口

| 阶段 | 谁 | 产出 | 出口 |
|---|---|---|---|
| 0 需求 | 起草者 → 用户 | `REQ.md` | 用户回一次话 → `状态: confirmed` |
| 1 起草 | 起草者 | `plan.md` | `check-plan` 无错误 |
| 2 审查 | 审查者 ×N（盲） | `reviews/R{n}-{方向}.md` | 各方向齐全 |
| 3 合并处置 | 主会话 → 起草者 | `R{n}-index.md`、`R{n}-answer.md`、`R{n}-fixcheck.md` | 每条 F 有结局 |
| 3.5 确认延后 | 用户 | deferred 清单 | 收敛 → 4；不收敛 → 2 |
| 4 批准 | 用户 | `fingerprint.txt`、`decisions.md` | 用户说「批准 v{N}」 |
| 5 执行 | 执行者（一次一个 Task） | `evidence/<Task-#>.md` | 全部 Task 有归宿 |
| 6 验收 | 验收者（新实例） | `verify/V{n}.md` | 全 pass → 7；有 fail → 5 或回 3 |
| 7 报告 | 主会话 | `run/report.md` | 过 `check-final` |

**plan-only 模式的范围**：只跑阶段 0–4 与 7；阶段 7 只写报告，不执行、不验收，跳过 5/6。`full` 模式仍按上表跑全部阶段。

修复复核：起草者交 `R{n}-answer.md` 后，主会话派一个新实例做修复复核，读 `plan.md`、`R{n}-answer.md`、`R{n}-index.md`，不读原始 findings；只查每条 `fixed` 的「改在哪」与「波及」；输出 `ok / repair claimed — still reported / unresolved`；产出 `reviews/R{n}-fixcheck.md`。

阶段 2 同一轮的 N 个审查者必须在**一条消息**里派完；分多条消息派出的，按「未派满」处理，补齐后重派。

阶段 5 的变更批只在**回炉**时用：把多条小变更合成一个 Task 写进 `plan.md`（Task 内用 `变更-1/2/3` 分节）；**必须重新批准并重算指纹后才执行**；指纹不一致即批准作废、回阶段 2；不许用变更批绕过批准；变更清单的批准原话记 `run/decisions.md`；执行者只做已批准的 `变更-N`；一批 3–5 条；只做清单列出的事；含不可逆步骤的变更不许合批；`evidence` 按变更分节。

阶段 7 必须产出 `run/report.md`，写清 `pass` / `fail` / `unresolved` 三个数字，并引用 `verify/V{n}.md`；然后跑 `node scripts/check-final.mjs <runDir>`，不过闸不许宣布 DONE。plan-only 模式的 `run/report.md` 必须标 `模式: plan-only`，不要求 `verify/`；full 走上面这套规则。

### 从 plan-only 切到 full（四步）

plan-only 下用户说「执行」，先按下面四步切换；四步都过了才算进入 full 执行。

1. **先校验指纹**：用现有 `run/fingerprint.txt` 校验 `plan.md` 的 sha256。不一致就**拒绝切换**，要求用户重新说 `批准 v{N}`（先升版本再重新批准）；此时不写任何日志，留在 plan-only。
2. **改模式**：一致才把 `run/mode` 写成 `full`。切换不重写 `fingerprint.txt`，指纹只在批准时生成。
3. **记批准**：追加 `批准执行 v{N} | plan sha256 <前 12 位> | 用户原话…` 到 `run/dispatch.log`；`N` 取 `plan.md` 头部版本号。
4. **记切换**：再向 `run/dispatch.log` 追加 `模式切换: plan-only → full | 用户原话…`。

失败语义：①② 失败就留在 plan-only、不写任何日志；③④ 失败时 mode 已是 `full`，只重试日志，不回退 mode。plan-only 的「批准」只代表计划被接受。

验收归属分三档：短档且无不可逆 → 主会话可自验，但 `run/report.md` 必须标「自验」；普通档 / 长档 / 含不可逆步骤 → 必须由独立验收者验收，report 出现「自验」即失败。`不可逆` 按 `plan.md` 里每个 Task 的 `是否不可逆：是` 判定，不按档位。

完整规则在 `plan-v3.md`（384 行；改流程改 `flow.model.json` 再重新生成，别手改）。日常照这张表走，出事再翻。

## 十二条硬规则

1. **没批准，不动手。** 只有用户说「批准 v{N}」才算，主会话要复述一句「批准的是 v{N} 的这份文件」。
2. **问题带号，下一轮必须给结局。** `F-###` 全局唯一，审查者只写本地号 `A-1`，合并时统一分配。
3. **只写自己那一栏的文件。** 写了别人的，该阶段产出作废、重跑。
4. **完不成如实报，不写「通过」。** 判据没全满足，报告里不许出现那两个字。
5. **验收项写不出「怎么才会失败」，就不算验收项。**
6. **改完先跑 `check-plan`**，错误清零不进下一轮。
7. **改计划前先提交快照**（`git add -A && git commit`），没有快照不许改——不然后一轮拿不到 diff。
8. **每轮开派之前先跑 `budget-check`**。它说超了，就停在该轮之前，去出口 A 等用户裁决；**不许自己开下一轮**再补记。日志照实记，`VOID` 只用于作废误派，不用于掩盖超预算。
9. **一条问题一处改。** 要多处，先写为什么。
10. **每条 `fixed` 写三样**：改在哪、怎么改的、波及哪几处。
11. **预算不许自己数。** 跑 `budget-check`，念它的输出。
12. **需求只回一次话**：顶部 `## 需要你定` 只放挡路的几条，其余一句「照收」。不许写「用户逐条确认」——那是没发生的事。

（编号不许跳号；加规则就往后接，标题里的数字跟着改。）

## 三条收敛纪律（决定这轮循环是收敛还是发散）

1. **每轮只修 P1**。`answer.md` 里 P2/P3 只能 `deferred` 或 `unresolved`，不许 `fixed`。修 P2 要动结构，结构一动就带出新 P1——每轮全修，问题只会越来越多。
2. **改动面硬停**。`check-diff` 平均每条 `fixed` 超 15 行 → 停，拆两批，第二批下一轮。超了说明这轮在重写。
3. **起草者复用、审查者新开，R2 起给 diff**。起草者用 `send_message` 接着改（新实例要重读 plan + 所有审查稿）；审查者必须新开才看得见重点，但第 2 轮起只给它 diff，别让它重读全文。

三条缺一条，循环就发散：实测一次三轮的 run，每轮全修 + 无 diff，计划从 143 行涨到 287 行，后两轮报的几乎全是修复带出来的新问题。

**还有一个省不掉的**：盲审本身贵。4 个方向就是 4 份独立阅读，diff 只省「读」，省不了「想」。所以轮数上限是硬的——短 1 / 普通 2 / 长 3，到了就停、去出口 A 交用户裁决，别自己加轮。实测那次超预算，就是第三轮没忍住。

## 档位与预算

| 档 | 条件（任一命中） | 审查人数 |
|---|---|---|
| 短 | 单系统 · 部件 < 8 · 无不可逆 | 3 = A + B + C |
| 普通 | 跨 1~2 系统 · 部件 8~20 · 1~2 个不可逆 | 4 = A + B + C + 现写方向 |
| 长 | 跨 3+ 系统 · 部件 > 20 · ≥2 个不可逆 · 迁移/发布/删除 | 5~6 |

部件只数**被规划的那个东西**：它自己的角色、阶段/步骤、被两个以上角色共用的文件、Task。**不数审查流程自己的角色与阶段**——那是每轮都一样的常数，算进去会让任何计划都变成「长档」。写完 plan 再数一次，数变了就改档并在 log 记一行。

- 审查轮：短 1 / 普通 2 / 长 3（一轮派 5 个也只算一轮；作废写 `VOID R2 | 原因`）
- 重开：2 次，执行重试与验收共用
- 回炉：每次批准给 1 次

**降档**：用户说「小修改 / 别重开」→ 降档；改 `dispatch.log` 首行（原来那行 `档位: …`）写入新档位与理由，不新增档位行；已开轮次不重开，未开的按下调后人数派。

## 卡住了怎么办

| 情况 | 处理 |
|---|---|
| 执行者报 `BLOCKED-###` | Task 不算完成；转 `F-###` 写进 `run/F-log.md`，回阶段 3 |
| 验收 fail，根因在**执行** | 重开对应 Task，回阶段 5，计一次重开 |
| 验收 fail，根因在**计划**（白名单缺文件、判据指不到东西） | **不重开**（重开一百次也过不了）；转 `F-###` → 回阶段 3 → 解冻升版 → 回炉 |
| 子 agent 超时 / 没写文件 | 该轮作废、不计预算，重派同轮新实例，全量覆盖文件 |
| 用户不回话 | 终态 `waiting-user`，不自动推进。审批永不自动完成 |
| 指纹不一致（批准后） | 批准作废，回阶段 2，log 记一行原因 |

## 检查脚本（都在本 skill 的 `scripts/`）

```bash
node scripts/check-plan.mjs plan.md REQ.md      # 编号/覆盖/字段/命令/路径/判据模糊词
node scripts/check-index.mjs R1-index.md R1-answer.md   # 合并表对账、F 号双向齐
node scripts/check-diff.mjs <runDir> plan.md <answer.md> # 改动面大小、波及写没写
node scripts/check-batch.mjs plan.md            # Task 间涉及文件有交集 → 应合批
node scripts/budget-check.mjs <runDir> [短|普通|长]      # 轮次/重开/回炉，只认磁盘
node scripts/flow-check.mjs                     # 流程模型有没有死路
node scripts/flow-check.mjs && node scripts/test-templates.mjs   # 改过模板就跑
```

`check-plan` 的错误不清零不进下一轮；提醒逐条看一眼。

## 文件与所有权

| 文件 | 写的人 |
|---|---|
| `run/user-words.md`、`run/dispatch.log`、`run/fingerprint.txt`、`run/decisions.md`、`run/F-log.md`、`run/report.md` | 主会话 |
| `REQ.md`、`plan.md`、`reviews/R{n}-answer.md` | 起草者 |
| `reviews/R{n}-{方向}.md` | 审查者（每人一个方向） |
| `reviews/R{n}-fixcheck.md` | 修复复核者 |
| `evidence/<Task-#>.md` | 执行者 |
| `verify/V{n}.md` | 验收者 |

模板在 `templates/`，十二份，照抄即可。

## 三条诚实的边界

1. **阶段 8（冻结）从没真跑过**；阶段 5～7 只跑过一次，那次执行被 pnpm 的构建审批挡住、验收两条都 fail。执行者和验收者的 prompt 经过一次实战，但样本只有一次（该次记录已删）。
2. **`判据来源` 是起草者自评**：把「推断」标成「直述」就能少几行给用户看，脚本判不出中文是不是推断。
3. **审查是抽样的**，多方向也不能保证发现所有问题；这套流程保证的是「每条问题有结局、预算可见、批准有据」，不是「计划一定对」。

• .gitattributes 1 KB
• .gitignore 1 KB
• LICENSE 1 KB
• README.md 24 KB
• SKILL.md 15 KB
• flow.model.json 19 KB
• plan-v3.md 32 KB