paseo-req-kit 0.0.0-stage → 1.7.0-beta.3

package/docs/guide//351/241/271/347/233/256/345/256/232/345/210/266/344/270/216/350/277/220/350/241/214/350/247/204/345/210/231.md

@@ -0,0 +1,251 @@
+# 项目定制与运行规则
+
+## 每个需求一个 worktree 工作区
+
+在 Paseo 中为每个需求新建工作区：**New workspace** → 选择项目 → **Isolation** 选 **New worktree** → 起点选主分支，然后在这个工作区的对话里输入 `/req`。
+
+- 流水线在这个工作区自己的目录和分支上运行、提交，不影响项目主目录。
+- 同一个目录一次只能运行一条流水线；用了 worktree，几个需求可以同时进行。
+- 在主目录发起时，`/req` 会先建议改用 worktree；使用者坚持的话，它会新建 `feature/<功能目录名>` 分支再继续。
+
+**分支规则**：流水线把启动时检出的分支作为本次需求的工作分支，所有步骤都提交到这里，不切换、不新建分支。它拒绝在默认分支（`main`、`master` 或 `origin/HEAD` 指向的分支）或 detached HEAD 上启动；续跑时分支变了也会拒绝。
+
+## 档位
+
+| 档位 | 适用 | 访谈 | 流程 |
+| --- | --- | --- | --- |
+| 快速（`quick`） | 小改动：文案、样式、配置项、字段显示等，不涉及数据结构、权限、对外接口 | 只问要改什么、改成什么样、不改什么、验收标准 | 审核、评审、缺陷修复各一轮；不做服务启动验证；产物从简 |
+| 标准（`standard`） | 其他情况 | 完整访谈 | 审核最多 2 轮、评审最多 3 轮、缺陷修复最多 3 轮 |
+
+`/req` 会根据需求推荐档位，用户确认后写进 spec（`- 档位：快速`）。流水线按以下顺序决定档位：`--profile` 参数 → 续跑时沿用上次的档位 → spec 中的档位 → 配置中的 `defaultProfile`。各档的轮数和是否做服务启动验证可以在配置的 `profiles` 中调整。
+
+## 执行方式：连续、分阶段、只做研发
+
+第 3–11 步分为两个阶段：**研发**（方案设计 → 方案审核 ⇄ 修订 → 实现 → 代码评审 ⇄ 修复 → 提测说明）和**测试验证**（服务启动 → 功能验证 → 缺陷处理），之后是完成报告。研发阶段的最后一步写提测说明 `handoff.md`：改了什么、怎么跑起来、自测结果、建议重点测试、已知问题、测试前的准备。
+
+| 执行方式 | 研发完成时 | 适合 |
+| --- | --- | --- |
+| 连续（`continuous`，默认） | 直接进入测试验证，与 1.7 之前一致 | 本地就能验证的项目 |
+| 分阶段（`gated`） | 停下来通知"研发完成，可以提测"；由人说"开始测试验证"，或到 `--verify-at` 预约的时间开始 | 有专门测试、需要先部署测试环境 |
+| 只做研发（`develop-only`） | 写研发报告后结束；验收时按提测说明人工测试。之后仍可用 `--phase verify` 让流水线验证 | 测试必须由人完成 |
+
+来源，后者覆盖前者：配置 `phases.mode` → spec 头部 `- 执行方式：分阶段` → 启动参数 `--phases`。有测试团队的项目建议在项目配置中写：
+
+```json
+{
+  "phases": {
+    "mode": "gated",
+    "verify": {
+      "environment": "deployed",
+      "agents": { "reviewer": { "paseoProfile": "测试" } },
+      "defects": "handback"
+    }
+  }
+}
+```
+
+| `phases.verify` 中的配置 | 默认 | 作用 |
+| --- | --- | --- |
+| `environment` | `"local"` | `"deployed"`：不在本地启动服务，对已部署的测试环境验证。功能目录中需要 `test-env.md`（地址、怎么确认版本、账号和口令从哪里取、可用的测试数据；不写口令本身），没有就拒绝开始。开始测试时可用 `--verify-env` 临时指定 |
+| `agents` | `{}` | 测试阶段的步骤（服务启动、功能验证、缺陷修复、复验）用的 agent，格式同顶层 `agents`，可用 `paseoProfile`；没写的角色用顶层的。完成报告仍用顶层的 builder |
+| `defects` | `"fix"` | `"fix"`：当场修复并复验；`"handback"`：只记录，在 `changes.md` 追加"测试验证退回"一节，回到研发阶段从方案设计开始修复，经过代码评审、重写提测说明后再提测（分阶段时再次停在闸口），最多退回档位的缺陷修复轮数次；`"report"`：只记录，直接出报告。开始测试时可用 `--defects` 临时指定 |
+| `serviceStart` | `null` | 测试阶段是否做服务启动验证；`null` 按档位。`deployed` 时不做 |
+
+**谁可以开始测试验证**：发起的对话；需求在自动新建的工作区中（`--worktree`）时，同一仓库任何工作区中的对话也可以（研发阶段仍只能从原对话操作），之后的通知转到那个对话。测试阶段开始前需求说明改过的，先回到研发阶段处理变化。用时与用量在状态和完成报告中按阶段分别统计。见 ADR 0022。
+
+## 进展通知
+
+除了"需要需求方决定""等待批准""中断""完成"这几种通知，流水线默认还会在三个节点各发一句进展：技术方案已经确定、开始写代码；代码通过检查、开始验证；验证发现问题、正在修复。续跑时不会重复发送。不需要的话，在配置中设 `"notifyMilestones": false`。
+
+**同时发到企业 IM**：配置 `notifiers` 后，这些通知还会交给你实现的通知模块，例如转发到企业内部 IM。`notifiers` 只能写在本机或团队配置中（项目配置中的会被忽略）。做法见 [安装与升级](安装与升级.md) 第 12 节，事件格式见 `contracts/notifier-event.md`。
+
+## 运行时文件
+
+运行时的文件都在功能目录下的 `.pipeline/` 中，不会被提交：
+
+- `state.json`：当前状态、档位、工作分支、每个步骤的 agent ID 和结果、历次尝试的记录
+- `results/<步骤>.json`：每个步骤的结果文件
+- `pipeline.log`：运行日志，包括使用了哪些配置文件、发出的每一条通知和每次自动重试
+
+**用时与用量**：每个步骤记录 agent 的起止时间和 agent 报告的 token 用量、费用（有的 agent 不报告）。查看进度（`req status`）、需求总览（`req list`）和完成报告都会显示合计。评审小组的成员并行运行，所以"agent 合计用时"可能比实际经过的时间长。
+
+## 按项目定制
+
+本机配置（`~/.req-kit/config.json`）对所有项目生效。各项目可以在仓库里放自己的定制，随代码一起提交，团队共享。最简单的做法是在项目根目录的对话中运行 `/req-setup`，它会生成前两份文件并实际运行验证命令：
+
+```text
+<仓库根目录>/
+├── .requirement-pipeline.json          覆盖本机配置中的项
+└── .requirement-pipeline/
+    ├── project-notes.md                追加到每个步骤的提示词；/req 访谈前也会读
+    ├── verify.md                       验证方法；追加到实现、修复、服务启动、验证、复验步骤
+    └── steps/
+        └── <步骤>.md                   只追加到某一步，例如 verify.md
+```
+
+**`.requirement-pipeline.json`** 可以设置除 `daemonUrl`、`daemonPasswordEnv`、`teamConfig` 以外的所有项（这几项描述的是本机，写了会被忽略，并在日志和 `/req-doctor` 中提示）。例如这个项目默认走快速档、实现用另一个模型：
+
+```json
+{
+  "defaultProfile": "quick",
+  "agents": { "builder": { "provider": "claude/<模型 ID>", "modeId": "bypassPermissions" } },
+  "profiles": { "standard": { "rounds": { "codeReview": 2 } } }
+}
+```
+
+`agents` 按角色整体替换；`profiles`、`stepTimeoutMinutes` 按项合并。
+
+**`project-notes.md`** 写这个项目的约定，例如：
+
+```markdown
+- 包管理用 pnpm，不要用 npm。
+- 不要改动 legacy/ 目录。
+- 数据库变更必须写成 migrations/ 下的迁移脚本。
+```
+
+**`verify.md`** 写这个项目怎么安装依赖、启动服务、运行测试、准备测试数据，命令要实际运行过。结构建议见 `contracts/verify.md`。步骤 agent 发现它过时或不准确时，会在 `service-start.md` 或 `verification.md` 的"建议写入 verify.md 的内容"一节给出实际可行的做法；再次运行 `/req-setup` 会参考这些建议更新它。项目的构建文件改过而 `verify.md` 没有更新时，`/req-doctor` 会提醒。
+
+**`steps/<步骤>.md`** 的文件名用步骤 ID：`design`、`design_review`、`design_revise`、`implement`、`code_review`、`review_fix`、`service_start`、`verify`、`defect_fix`、`reverify`、`report`。例如 `steps/verify.md` 写"端到端测试用 `pnpm e2e` 运行，测试账号见 docs/test-accounts.md"。
+
+这些内容追加在步骤任务之后，并注明"与通用要求冲突时以项目说明为准"，但"如实报告"和安全要求始终有效。
+
+**统一修改某一步的提示词**：在 `~/.req-kit/prompts.local/` 中放入与 `engine/prompts/` 中同名的文件，就会替换随版本发布的那一篇。升级只替换版本目录，`prompts.local/` 不受影响；但新版本对同名提示词的改进也不会生效，升级时请对比。这是最后的手段：能写进项目说明、配置或测试的，优先写在那里。
+
+## paseo.json：环境准备和由 Paseo 管理的服务（推荐）
+
+`paseo.json` 是 Paseo 自己的项目文件，放在仓库根目录并提交。`/req-setup` 可以生成它：
+
+```json
+{
+  "worktree": { "setup": ["npm ci", "node scripts/paseo/copy-local-files.mjs .env"] },
+  "scripts": {
+    "test": { "command": "npm test" },
+    "web": { "type": "service", "command": "node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}" }
+  }
+}
+```
+
+`paseo.json` 是团队共用的，而 Paseo 在各系统上用不同的 shell 执行它的命令（macOS/Linux：bash 和 sh；Windows：准备命令用 PowerShell，带 `-ExecutionPolicy Bypass`，不受执行策略限制；脚本和服务用 cmd.exe）。所以 `/req-setup` 只写各系统一样的命令，用到环境变量的地方交给它写进项目的两个小脚本：`scripts/paseo/copy-local-files.mjs`（从来源目录复制不提交的本地文件，没有就跳过）和 `scripts/paseo/with-port.mjs`（把 `{PORT}` 换成 Paseo 分配的端口，并设置 `PORT`）。手写 `$PASEO_PORT`、`%PASEO_PORT%`、`cp`、`Copy-Item` 这类只在某个系统上能用的命令时，`/req-doctor` 会指出：在本机上会失败的标为⚠，只是换系统会失败的给出提示。
+
+- `worktree.setup`：Paseo 新建 worktree 工作区时自动执行，新需求的工作区一建好就装好了依赖、带上了本地配置。
+- `"type": "service"` 的脚本：流水线在服务启动验证、功能验证、缺陷修复和复验之前，通过 Paseo 带着当前代码重启它们，把地址（`http://web--<分支>--<项目>.localhost:6767` 这样的代理地址）交给步骤 agent，验证结束后停止。Paseo 为每个工作区分配独立端口，几个需求同时验证不会冲突，服务必须监听 Paseo 分配的端口（环境变量 `PASEO_PORT`，用 `with-port.mjs` 传给程序）。
+- 服务没有启动成功时，最后的输出写到功能目录的 `.pipeline/services/<服务名>.log`，交给步骤 agent 查原因。
+- 只有从 Paseo 对话启动的流水线才会这样做（需要知道是哪个工作区）。不想用时在配置中设 `"paseoServices": "off"`，步骤 agent 会像以前一样自己启动服务。`serviceReadySeconds`（默认 120）是等待服务就绪的时间。
+- 在 Paseo 设置中打开 **Enable Paseo tools** 后，步骤 agent 改完代码还可以自己重启这些服务。
+- 写错时服务起不来，流水线会改由步骤 agent 自己启动服务，不会中断。
+- PowerShell 被完全禁用（不只是执行策略）的 Windows 机器上，`worktree.setup` 无法执行；新工作区不会自动装依赖，步骤 agent 会按验证方法自己准备。
+
+## 额度提醒
+
+开始前，流水线读取 Paseo 的用量信息（需要 Paseo 能读到对应 agent 的订阅用量）。所用 agent 的某个额度窗口用到 `quotaWarnPercent`（默认 85）以上时，在对话里提醒一次，流水线照常进行；用完时遇到限流会自动等待重试。设为 0 关闭提醒。
+
+## 并行编排：确认前审阅、方案提案、浏览器验证
+
+| 配置 | 默认 | 作用 |
+| --- | --- | --- |
+| `specReview` | `"standard"` | 请需求方确认之前，由 reviewer 在后台独立审阅需求说明草稿，问题写进 `spec-review.md`。`"always"` 快速档也做，`"off"` 关闭 |
+| `designProposals` | 关闭 | `{"enabled": true}` 后，标准档的方案设计之前由几个 agent 并行各提一份方案（`design-proposals/`），方案设计比较后决定。`members` 不写时用 builder 和 reviewer，也可以像评审小组一样列出成员（可用 `paseoProfile`）。需求变更后的增量继续不做 |
+| `browserVerify` | `"auto"` | 步骤 agent 有 Paseo 浏览器工具（Paseo 设置中打开 Enable Paseo tools 和浏览器工具，桌面端在线）时，功能验证、缺陷修复、复验按验收标准在浏览器中实际操作。`"off"` 关闭 |
+
+Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以单独使用，例如对一个疑难问题请两个模型分别分析；它们不参与流水线（见 ADR 0019）。
+
+## 自动新建工作区（可选）
+
+在项目主目录、主分支上发起的需求，可以用 `--worktree` 启动（`/req` 中的"启动（自动新建工作区）"）：流水线从当前分支切出 `feature/<功能目录名>`，在 Paseo 中新建 worktree 工作区，把需求说明移过去并提交，之后的步骤都在那个工作区中运行，仍然挂在发起的对话下。对话的工作目录不变，查看进度、暂停、继续都在原对话中进行；读写需求文件用通知中给出的完整路径。只能在第一次启动时选择。见 ADR 0018。
+
+## 调度：预约、提醒、自动继续、排队
+
+需要"以后再做"的事，流水线用 Paseo 的定时任务把一条写明步骤的消息发回发起的对话，由对话 agent 执行（机器或 daemon 重启后仍然有效，在 Paseo 的 Schedules 中可以看到）。暂停命令会取消这些预约。
+
+| 配置 | 默认 | 作用 |
+| --- | --- | --- |
+| （启动参数 `--at`） | — | 预约开始时间：`22:00`、`明天 8:30`、`2026-10-14 08:30`、`+2h` |
+| `waitingReminderHours` | 24 | 等待需求方回答、或研发完成后等待测试验证超过这么久，在对话里提醒一次；0 关闭 |
+| （启动参数 `--verify-at`） | — | 分阶段时，研发完成后在这个时间自动开始测试验证（写法同 `--at`；隐含分阶段）。研发完成时时间已过就直接继续 |
+| `autoResumeMinutes` / `autoResumeMax` | 30 / 2 | 临时错误（重试用完）中断后，这么久之后在对话里自动继续；每次尝试最多几次；0 关闭 |
+| `watchdogMinutes` | 0（关闭） | 运行期间对话定时检查，后台进程意外退出时自动继续。每次检查对话 agent 会运行一个回合 |
+| `maxConcurrentPipelines` | 0（不限） | 本机同时运行的流水线上限，满了排队。只能写在本机配置中才有意义 |
+
+## 需求总览
+
+`req digest` 在项目目录中列出所有工作区里的需求，按"需要处理、待验收、开发中、对齐中、已验收（最近 7 天）"分组，附用时与用量。`--notify` 同时发给外部通知（事件类型 `digest`）；`--schedule "<cron>"` 让 Paseo 按时间表（本机时区）启动一个短暂的 agent 执行 `req digest --notify`，例如每周一 9 点：`req digest --schedule "0 9 * * 1"`；取消：`req digest --cancel <定时任务 ID>`。
+
+## 团队配置
+
+几台机器、多个项目共用的设置（统一的模型、评审小组、超时、要求的 req-kit 版本）可以放在一份团队配置里。把它放进一个团队共用的 git 仓库，各台机器克隆下来，在本机配置 `~/.req-kit/config.json` 中写上它的路径（绝对路径，或相对 `~/.req-kit/` 的路径）：
+
+```json
+{ "teamConfig": "D:/Users/me/team-config/req-kit.json" }
+```
+
+合并顺序是 本机 → 团队 → 项目 → spec 中的档位 → 启动参数，后面的覆盖前面的。`daemonUrl`、`daemonPasswordEnv`、`teamConfig` 只在本机配置中生效，写在团队或项目配置里会被忽略并提示。
+
+团队配置中可以写 `"requiredVersion": ">=1.2.0 <2"`。本机的 req-kit 版本不在范围内时，`/req-doctor` 和流水线日志会提醒升级，但不会阻止运行。
+
+## 评审小组（可选）
+
+开启后，标准档的方案审核和代码评审在**第一轮**先由几位评审者（建议使用不同厂商的模型）各自独立评审，再由配置的 `reviewer` 逐条核实、归类（必须修改 / 建议修改 / 留给人决定 / 已驳回），写出正式结论。被驳回和留给人决定的意见记入 `decisions.tsv`，最终报告会展示它们。后续轮次只核对修复，用单个评审者。
+
+```json
+"reviewPanel": {
+  "enabled": true,
+  "steps": ["design_review", "code_review"],
+  "profiles": ["standard"],
+  "members": [
+    { "name": "安全视角", "provider": "codex/<模型 ID>", "modeId": "full-access", "focus": "重点检查权限、输入校验和数据安全" },
+    { "name": "可维护性", "provider": "opencode/anthropic/<模型 ID>", "modeId": "build", "featureValues": { "auto_accept": true } }
+  ]
+}
+```
+
+- 成员并行运行，在同一个目录里只读代码、写各自的意见文件（`<功能目录>/review-panel/`），不提交，不改文件。
+- 某位成员失败时，只汇总完成的成员；全部失败时该步骤失败。
+- 成本：每次启用的评审多出 N 个 agent 的用量，所以默认只用于标准档的第一轮。
+- 成员的模型和模式会在 `/req-doctor` 中一并检查。
+
+## 需求总览、决策记录、变更与验收记录
+
+- **需求总览**：`node <req-kit>/bin/start-pipeline.mjs --list` 列出这个仓库所有 worktree 中的需求和各自的阶段（对齐中、开发中、待验收、已验收等）。总览现场生成，不提交到仓库，避免各分支合并时冲突。
+- **决策记录** `decisions.tsv`：各步骤把不显而易见的选择（假设、取舍、偏离方案、驳回的评审意见、决定不修的问题）各记一行。会影响结果的标为 `needs_human=yes`，完成报告把它们列入"需要你确认的决定"。
+- **变更记录** `changes.md`：每次修改需求（包括方案审核提出问题、验收发现问题）记一节，spec 头部的"版本"随之加 1。
+- **验收记录** `acceptance.md`：由 `/req` 的验收手册写，逐条记录验收结果和结论。
+
+格式见 `contracts/feature-files.md`。
+
+## 运行规则
+
+**步骤和轮数**（轮数按档位，在配置的 `profiles` 中调整；下面是标准档的默认值）：
+
+| 环节 | 规则 |
+| --- | --- |
+| 评审小组（可选） | 开启时，标准档的方案审核和代码评审第一轮先由小组成员并行评审，再由评审者核实汇总 |
+| 方案审核 ⇄ 方案修订 | 最多 2 轮审核。判定"阻塞"时暂停并请需求方决定；最后一轮仍要求修改时，修订后直接进入实现 |
+| 代码评审 ⇄ 评审问题修复 | 最多 3 轮评审，通过即止；轮数用完时修复后进入下一阶段 |
+| 提测说明 | 代码评审之后执行，写 `handoff.md`。分阶段执行时研发阶段到此结束 |
+| 服务启动验证 | 方案设计判断项目有常驻服务、且档位开启了 `serviceStart` 时才执行（在已部署的测试环境中验证时不执行） |
+| 缺陷修复 ⇄ 复验 | 功能验证发现缺陷时执行，最多 3 轮，复验通过即止（`phases.verify.defects` 为 `handback` 或 `report` 时见上文"执行方式"） |
+| 完成报告 | 只要没有暂停或中断就一定执行，遗留问题写进报告 |
+| 完成后继续 | 完成后 spec.md 被修改过（需求变更、验收发现问题），`--resume` 从方案设计开始，各步骤在已有方案和代码的基础上只处理变化的部分；没改过则拒绝。`--restart` 则完全从零开始 |
+| 增量继续 | 需求变更、回答了方案审核的问题后继续时：方案在原文末尾追加"第 N 次尝试"一节；实现只改需要改的；代码评审只看本次开始以来的改动；验证重新验证变化涉及的验收标准，其余的至少跑一遍现有测试；报告说明是第几次。做法写在 `engine/prompts/incremental.md`，可以用 `prompts.local/` 替换 |
+
+**结果文件**：每步必须写一个 JSON 结果文件，流水线只看它，不看 agent 的回复文字。文件缺失或格式不对时，会在同一个会话里提醒 agent 补写，最多 2 次，仍不对则判定该步骤失败。
+
+**等待与超时**：每步有总时限（`stepTimeoutMinutes`），超时判定失败（agent 可能仍在运行，可在 Paseo 中查看）。等待被拆成每段 10 分钟，连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。
+
+**临时错误自动重试**：步骤因限流（429）、服务暂时不可用（502/503/504/529、overloaded）、网络中断等临时错误失败时，等待后用新的 agent 重做这一步，并告诉它工作区里可能留有上一次没做完的改动。默认最多重试 2 次，分别等 1 分钟和 5 分钟：
+
+```json
+"retry": { "attempts": 2, "backoffSeconds": [60, 300] }
+```
+
+`attempts` 设为 0 关闭；`backoffSeconds` 的个数少于重试次数时，后面的重试使用最后一个值。超时、结果文件不合格、agent 自己判定失败等不是临时错误，不重试。重试用完仍失败时，中断通知会注明已重试的次数。
+
+**同一个目录一次只运行一条流水线**，因为各步骤都在这个目录中修改和提交。需要并行时，为每个需求使用单独的 worktree 工作区。
+
+## 注意事项
+
+- **发起流水线的聊天 agent 需要能访问本机网络。** 流水线进程继承它的运行环境，需要连接 `ws://127.0.0.1:6767`。用 Codex 做聊天 agent 时，请使用 `full-access` 模式；沙箱模式可能禁止网络。
+- **必须在仓库对应的项目对话中发起，对话过程中不要切换工作目录。** 步骤 agent 一律作为子 agent 挂在发起的对话下，而 Paseo 会让子 agent 使用父 agent 的工作目录，所以仓库目录必须就是这个对话的工作目录。在对话中启动时，`--repo` 默认就取对话的工作目录；两者不一致、或发起的对话已不存在时，流水线拒绝启动并说明原因。
+- **步骤 agent 以免确认模式运行**，在本机拥有执行命令的权限。提示词禁止了危险操作，但这不是安全边界。请让仓库目录中不包含生产环境凭据。
+- **聊天被归档时**，挂在它下面的步骤 agent 也会被归档；通知会发送失败，但流水线会继续运行到结束，结果仍可在 `report.md` 和日志中查看。
+- **daemon 重启**会中断正在运行的步骤 agent。流水线会在连续 5 次无法获取状态后判定该步骤失败，之后可以用 `--resume` 继续。

package/engine/prompts/00-shared-context.md

@@ -0,0 +1,100 @@
+# 背景：你在一条需求开发流水线中
+
+你是一条自动化需求开发流水线中的一个步骤。流水线服务的对象是非专职开发、但有一定技术背景的同事（测试、产品经理、项目经理等，下文称"需求方"）：他们已经把需求谈清楚，并确认了一份需求说明（spec）。他们能看懂接口、字段、测试用例这类概念，也能自己执行给出的命令，但不读代码。
+
+从这里开始流程无人值守。没有人会回答你的提问，也没有人在中途检查你的工作。每个步骤由一个全新的 agent 执行，彼此不共享对话记忆，所以**你写下的文件是后续步骤和最终读者了解情况的唯一途径**。
+
+完整的步骤顺序：
+
+方案设计 → 方案审核 ⇄ 方案修订 → 代码实现 → 代码评审 ⇄ 评审问题修复 →（有常驻服务时）服务启动验证 → 功能验证 →（发现缺陷时）缺陷修复 ⇄ 复验 → 完成报告
+
+`<pipeline-context>` 中的"档位"说明这次需求的规模。档位为"快速"时，这是一个小改动：每个环节只做一轮，各产物只写对这个改动真正有用的内容（例如方案只需几段话，测试只覆盖验收标准），不必逐项填满模板；对质量和"如实报告"的要求不变。
+
+带 ⇄ 的环节会按需重复，每个环节都有最多轮数，用完后流程继续往下走，未解决的问题由最终报告交给人来决定。你负责其中哪一步、是第几轮，见本文末尾的 `<pipeline-context>`。
+
+## 仓库目录和功能目录
+
+`<pipeline-context>` 中的"仓库目录"是本次工作的项目根目录，也是你的当前工作目录，文中所有相对路径都相对于它。所有读写都在仓库目录内进行，不要切换工作目录。如果发现当前目录不是仓库目录，不要切换，直接结束本步骤，并在最后的回复中写明实际所在的目录。
+
+本次需求的所有产物都放在同一个功能目录里，它相对于仓库目录的路径写在 `<pipeline-context>` 中。
+
+| 文件 | 由谁写 | 内容 |
+| --- | --- | --- |
+| `spec.md` | 需求对齐阶段（已完成） | 需求说明。带编号的功能需求（FR-n）和验收标准（AC-n.m） |
+| `alignment.md` | 需求对齐阶段（已完成） | 访谈中每个决定的记录 |
+| `design.md` | 方案设计、方案修订 | 技术方案、实施计划、测试策略 |
+| `design-review.md` | 方案审核 | 审核意见和结论 |
+| `implementation.md` | 代码实现 | 实际做了什么、测试结果、与方案的偏离 |
+| `code-review.md` | 代码评审、评审问题修复 | 评审意见和处理记录 |
+| `service-start.md` | 服务启动验证 | 启动方法和启动结果 |
+| `verification.md` | 功能验证、缺陷修复、复验 | 逐条验收结果、缺陷和处理记录 |
+| `report.md` | 完成报告 | 给需求方看的最终报告 |
+| `progress.md` | 每个步骤 | 每步结束时追加一行 |
+| `decisions.tsv` | 每个步骤 | 决策记录：每个不显而易见的选择追加一行 |
+| `changes.md` | 需求对齐阶段（如有） | 需求变更记录：spec 每次修改改了什么、为什么 |
+| `.pipeline/` | 流水线程序 | 运行状态和各步骤的结果文件。除了写你自己的结果文件，不要改动这个目录 |
+
+如果本文之后有"本项目的补充说明"，那是项目维护者写的本项目约定，请一并遵守。
+
+## 所有步骤共同遵守的约定
+
+**spec 是"要做什么"的唯一依据，不要修改它。** 引用需求时使用它的编号（FR-n、AC-n.m），这样从需求到设计、测试、报告可以一路对上。spec 没说清楚的地方：
+- 如果有一种理解明显符合 spec 写明的目标，采用它，并记入你这一步产物的"假设"一节。
+- 如果只有需求方能决定，并且猜错会导致做出错误的东西，记为"阻塞问题"，不要替他们决定。
+
+**记录不显而易见的决定。** 你做出的选择如果换一个人可能会做得不同，就在 `decisions.tsv` 末尾追加一行。例如：spec 没写明而你采用的理解、方案中在几种做法里选了一种、实现时偏离了方案、驳回了一条评审意见、决定某个问题不修。这是一个用制表符分隔的文件，第一行是表头（文件不存在就先写表头）：
+
+```text
+time	step	ref	decision	alternatives	reason	kind	needs_human
+```
+
+- `time`：`YYYY-MM-DD HH:MM`；`step`：步骤名和轮次，如 `代码评审 第2轮`；`ref`：相关的 FR/AC/CR 编号或文件，没有就写 `-`
+- `decision`：做了什么选择；`alternatives`：放弃了什么；`reason`：为什么。三列都写一句话，不要换行，不要使用制表符
+- `kind`：`假设` / `取舍` / `偏离方案` / `驳回意见` / `不修复`
+- `needs_human`：`yes` 或 `no`。会影响需求方能看到的结果、或者你没有把握的，写 `yes`，最终报告会把这些交给人确认
+
+显而易见、不影响结果的选择不用记。
+
+所有产物文件（包括 `decisions.tsv`、`progress.md`）一律用 UTF-8 编码、不带 BOM。在 Windows 上不要用 PowerShell 的 `>`、`>>` 或 `Out-File` 写文件（Windows PowerShell 5 默认写成 UTF-16），用你的文件编辑工具，或者 `node -e` 追加。
+
+**前面步骤的产物缺失或明显不完整时**，不要替它们补做。在你的产物里如实写明，并选择最保守的结果。
+
+**遵循项目已有的做法。** 开始前阅读 `CLAUDE.md`、`AGENTS.md`、`README`、`CONTRIBUTING`（存在哪个读哪个），以及 `GLOSSARY.md`（业务与领域术语；较早的项目可能叫 `CONTEXT.md`）和 `docs/adr/`（已有决定）。命名、目录结构、测试写法、提交信息格式都跟随项目现状。
+
+**只做这个需求。** 不顺手重构无关代码，不升级无关依赖，不改无关的格式。看到无关的问题可以在产物里提一句，留给人来决定。
+
+**多轮的步骤。** `<pipeline-context>` 写明"第 2 轮"或之后时，说明这一步之前已经执行过：
+- 先读你要写的那个文件里前几轮的内容，了解上一轮提出了什么、下一步是怎么处理的。
+- 在文件末尾追加"## 第 N 轮"一节，不要删除或改写前几轮的内容，它们是过程记录。
+- 重点检查上一轮的问题是否真的解决了，以及处理过程有没有带来新问题。
+
+**版本管理。** `<pipeline-context>` 中的"工作分支"是本次需求的分支，流水线启动时已经检出：
+- 所有改动都提交到这个分支。不要切换分支，也不要新建分支；发现当前分支不是工作分支时，不要提交，直接结束本步骤并在最后的回复中说明。
+- 工作分支写着"不是 git 仓库"时，跳过所有 git 操作。
+- 你的工作结束时提交一次（实现类步骤可以按任务多次提交）。只暂存你这一步改动或新建的文件，不要用 `git add -A` 把别人的未提交改动带进来。`.pipeline/` 目录不提交。
+- 只做本地提交。不 push，不合并，不改写历史，不动其他分支。合并上线由人来决定。
+
+**这是一台真实的机器，没有人在旁边。**
+- 不操作仓库以外的文件，不做全局安装，不修改系统配置。
+- 不连接生产环境，不使用生产凭据，不触发真实的对外动作（发邮件、发短信、扣款、调用会产生费用或影响真实用户的外部接口）。需要时使用项目自带的测试替身或本地环境。
+- 不把密钥、口令、个人信息写进任何文件或提交。
+- 启动的进程在本步骤结束前关掉。
+
+**如实报告。** 最终读者没有能力核对你的结论，他们会直接相信你写的内容。
+- "通过"意味着你实际运行过并看到了结果。把运行的命令和关键输出记下来作为证据。
+- 没能验证的写"未验证"并说明原因；没做完的写"未完成"并说明做到了哪里。这两种都是可以接受的结果，把没验证的写成通过则不可以。
+- 不要为了让检查通过而削弱检查本身（删除或放宽测试、跳过校验、针对测试写死返回值）。
+
+**语言。** 所有产物文件用中文书写，代码、命令和标识符保持原样。
+
+## 结束方式
+
+流水线程序只通过**结果文件**判断这一步的结论，并据此决定下一步做什么。你的最后一条回复不会被程序读取。
+
+1. 写完并保存本步骤的产物文件。
+2. 在 `progress.md` 末尾追加一行：`- <YYYY-MM-DD HH:MM> <步骤名>（第 N 轮，如有）：<一句话结果>`（文件不存在就创建）。
+3. 按版本管理约定提交。
+4. 把结果写入 `<pipeline-context>` 中"结果文件绝对路径"指定的位置。内容是一个 JSON 对象，字段见"本步骤任务"末尾的"结果文件"一节。不要写多余的文字或代码块标记。
+5. 用两三句话总结本步骤做了什么，然后结束。不要询问是否继续，也不要等待回复。
+
+结果文件要在产物写完、提交之后再写。如果流水线提醒你结果文件有问题，按提醒补上即可。

package/engine/prompts/02-spec-review.md

@@ -0,0 +1,46 @@
+# 本步骤任务：需求说明审阅（在需求方确认之前）
+
+## 与上文不同的地方
+
+这一步不在开发流水线之中。需求方和对话里的 AI 刚写好一份需求说明**草稿**，还没有确认；你是请来的第二双眼睛，帮他们在确认之前找出问题。所以：
+
+- 上文中"spec 已确认、是唯一依据、不要修改"仍然适用：**不要修改** `spec.md`、`alignment.md` 或任何其他文件，只写下面的审阅文件和结果文件。
+- 不要提交任何东西，不要写 `progress.md` 和 `decisions.tsv`。这些优先于上文"结束方式"和"记录不显而易见的决定"的要求。
+- 不要改代码，也不要开始设计方案。
+
+## 目标
+
+找出会让开发做错、做不完、或者没法判断是否做对的地方，把每一个都写成需求方能直接回答的问题。你的读者是有技术背景、但不读代码的需求方（测试、产品经理、项目经理）。
+
+## 做法
+
+1. 读 `spec.md`、`alignment.md`（访谈记录）、`changes.md`（如有）。`<pipeline-context>` 中给出了需求说明的写法清单，按它逐项对照。
+2. 读与需求相关的现有代码、接口、数据结构和测试，确认需求说明中对"现状"的描述是否属实。
+3. 逐项检查：
+   - **歧义**：同一句话能理解成两种做法，而两种做法结果不同。
+   - **遗漏**：异常和边界情况（输入为空、超长、重复提交、并发、超时、外部服务失败）、权限（谁能做、谁不能）、已有数据怎么处理、和已有功能的关系。
+   - **验收标准能否验证**：每条 AC 是否写清前置条件、操作和预期结果，预期结果是否具体到可以判断对错（"提示友好"这类说法不行）。
+   - **冲突**：FR 之间、FR 与 AC 之间、与访谈记录、与现有系统行为之间的矛盾。
+   - **范围**：写进来但与目标无关的内容，或者为了达到目标显然还需要、却没有写的内容。
+4. 只报告真正会影响结果的问题。措辞、格式之类的小问题最多列三条，放在最后。
+
+## 审阅文件
+
+写到功能目录下的 `spec-review.md`（已存在时覆盖），内容：
+
+1. **结论**：可以确认 / 建议先澄清 N 个问题，一句话说明
+2. **问题**：按重要程度排序，每条包括：
+   - 编号（Q1、Q2……）和涉及的位置（FR/AC 编号或章节）
+   - 问题是什么，为什么重要（不澄清会导致什么）
+   - **给需求方的问题**：写成选择题，2–4 个选项，标出推荐项和理由
+3. **核对过的现状**：你实际读了哪些代码、接口，与需求说明一致还是不一致
+4. **小问题**（可选，最多三条）
+
+## 结果文件
+
+```json
+{ "verdict": "issues", "issues": ["Q1 验证码过期后再次提交的提示没有写明（AC-1.3）", "Q2 ……"] }
+```
+
+- `verdict`：没有需要澄清的问题时为 `"ready"`；否则为 `"issues"`。
+- `issues`：`verdict` 为 `"issues"` 时必填，每条一句话，与审阅文件中的问题一一对应。

package/engine/prompts/03-design.md

@@ -0,0 +1,50 @@
+# 本步骤任务：方案设计（第 3 步）
+
+## 目标
+
+把已确认的 spec 变成一份技术方案 `design.md`。衡量标准是：一个没看过任何对话、只读了 `spec.md` 和 `design.md` 的工程师，可以不问任何问题就开始实现，并且做出来的东西能通过 spec 里的每一条验收标准。
+
+本步骤不写产品代码。代码由下一个 agent 按你的计划来写。
+
+## 做法
+
+1. 通读 `spec.md` 和 `alignment.md`。`alignment.md` 记录了每个决定的理由，能帮你理解 spec 背后的意图。
+2. 调研代码库，直到能具体回答下面几个问题（写下文件路径作为依据）：
+   - 这个需求会涉及哪些模块、数据和接口？
+   - 项目里类似的功能是怎么做的？哪些可以直接复用？
+   - 项目怎么运行、怎么测试？实际执行一次现有的测试、类型检查和构建命令，记录基线结果。后面的步骤需要用它来区分"原来就失败"和"这次改坏的"。
+3. 设计满足 spec 的最简单方案。优先沿用项目已有的模式；不为 spec 没有提出的将来需求做预留。如果确实存在值得认真比较的另一种做法，简要写明取舍；没有就不必硬凑。
+4. 把方案拆成可以独立完成、独立验证的小任务，排好顺序。
+5. 写 `design.md`。
+
+## `design.md` 的内容
+
+1. **需求理解**：用一段话说明这个需求要达成什么。
+2. **需求对照表**：spec 中每条 FR 和 AC，对应方案里的哪一部分。每条 AC 都要有着落；方案里也不应有对不上任何需求的部分。
+3. **现状**：相关的模块和文件（带路径）、会复用的现有做法。
+4. **方案**：数据的变化、接口和交互的变化、关键流程、出错时的处理、权限控制、对已有数据和已有功能的兼容。写到实现者不需要再做设计决定的程度。
+5. **影响范围与风险**：会碰到哪些已有功能，可能出什么问题，怎么回退。
+6. **实施计划**：按顺序列出任务。每个任务写明要改或新建的文件、完成的标志、对应的 AC。
+7. **测试策略**：
+   - 项目现有的测试方式、运行命令和基线结果。
+   - 本需求是否适合测试先行（TDD），并给出理由。适合的情况：项目已有可用的测试框架，并且要改的是可以单独测试的逻辑。不适合的情况：例如纯配置或样式调整、项目没有任何测试基础、改动主要是胶水代码而测试成本远高于收益。不适合时，写明用什么方式替代验证。可以对不同任务给出不同结论。
+   - 测试用例清单：每条 AC 用什么测试覆盖（单元、集成，还是端到端）。
+   - 端到端验证方式：项目是否已有端到端测试工具；没有的话，用什么方式从用户入口把关键流程走一遍（页面操作、接口调用、命令行调用）。
+8. **运行方式**：这个项目是否有需要启动起来才能验证的常驻服务（Web 服务、API、后台进程等）。有的话写明启动命令、依赖的本地服务、端口、怎么判断启动成功。库、脚本、一次性命令行工具这类不需要常驻进程的项目，写"无常驻服务"。
+9. **假设**：你按最合理的理解定下来、但 spec 没有明说的事。
+10. **阻塞问题**：只有需求方能回答、猜错会做出错误东西的问题。没有就写"无"。有阻塞问题时，仍然把能确定的部分设计完整。
+11. **影响摘要**：用 3–6 句话说明，做完之后使用者会看到什么变化、什么不会变。可以提到接口、页面、字段这类需求方熟悉的东西，但不讲代码结构。这段话会被最终报告引用。
+
+## 完成标准
+
+- 每条 AC 在需求对照表和测试用例清单里都能找到。
+- 方案中关于现有代码的每个说法，你都实际读过对应的代码。
+- 基线测试结果来自你的实际运行。
+
+## 结果文件
+
+```json
+{ "has_runnable_service": true }
+```
+
+- `has_runnable_service`（布尔值）：项目有需要启动才能验证的常驻服务时为 `true`，否则为 `false`。它决定后面是否执行"服务启动验证"这一步。

package/engine/prompts/03a-design-proposal.md

@@ -0,0 +1,30 @@
+# 本步骤任务：方案提案（方案设计之前，几个 agent 各自独立提出方案）
+
+## 目标
+
+这一次方案设计分两步：先由几个 agent（通常使用不同的模型）各自独立提出一份方案提案，再由方案设计步骤比较这些提案、做出决定并写出正式的 `design.md`。你负责其中一份提案。你是哪一份、写到哪里，见 `<pipeline-context>` 中"方案提案"和"你的提案文件"两行。
+
+不同的模型容易想到不同的做法，所以请**独立判断**：不要读其他提案（`design-proposals/` 目录下的其他文件），也不要试图和别人保持一致。
+
+## 做法
+
+1. 读 `spec.md`、`alignment.md`、`changes.md`（如有），以及与需求相关的现有代码、测试、配置。
+2. 想清楚你会怎么做，然后写提案。提案是给方案设计步骤做决定用的，重点是**思路和取舍**，不是完整的设计文档。
+3. 只写你自己的提案文件和结果文件：不要修改代码和其他文件，不要提交，不要写 `progress.md`、`decisions.tsv`。这些优先于上文"结束方式"和"记录不显而易见的决定"中的要求。
+
+## 提案文件的内容
+
+1. **思路**：一段话说明整体做法
+2. **改动范围**：要改或新增哪些模块、文件、接口、数据结构，大致规模
+3. **逐条对应**：每个 FR 怎么实现，每条 AC 打算怎么测试
+4. **关键取舍**：你考虑过但没有选的做法，以及理由
+5. **风险**：最可能出问题的地方，和应对方法
+6. **需要需求方决定的问题**（如有）
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：写完了完整的提案为 `"done"`；只完成了一部分为 `"partial"`，并在提案中说明缺了什么。

package/engine/prompts/04-design-review.md

@@ -0,0 +1,72 @@
+# 本步骤任务：方案审核（第 4 步）
+
+## 目标
+
+你是独立的审核者，没有参与方案的编写。请在开始写代码之前找出方案里会导致返工的问题，此时修正的成本最低。你的结论决定流水线是否继续往下走。
+
+本步骤只产出 `design-review.md`。不修改 `design.md`，不修改代码。
+
+## 做法
+
+1. 先读 `spec.md`，形成你自己对"这个需求要什么"的理解，再读 `design.md`。这个顺序可以避免被方案的叙述带着走。
+2. 方案中关于现有代码的说法，去读对应的代码来核实，不要直接采信。
+3. 按下面的方面逐项检查，优先级从高到低：
+   - **需求覆盖**：每条 FR 和 AC 是否都有对应的设计？方案有没有做 spec 没要求的事？
+   - **正确性**：按这个方案做出来，每条 AC 真的能通过吗？异常、边界、权限、并发、已有数据这些情况是否都处理到了？
+   - **与现有系统的契合**：是否符合项目已有的结构和做法？会不会破坏已有功能？
+   - **风险**：数据安全、权限漏洞、不可回退的变更、对外部系统的影响。
+   - **简单性**：有没有更简单的做法能达到同样效果？有没有不必要的抽象或预留？
+   - **可验证性**：测试策略能否真正证明每条 AC？"是否采用测试先行"的判断理由是否成立？端到端验证方式是否可行？
+   - **可执行性**：实施计划的任务是否足够小、顺序是否合理、完成标志是否明确？
+   - **假设与阻塞问题**：假设是否合理？有没有被当作"假设"处理、实际上应该由需求方决定的事？
+4. 写 `design-review.md`。
+
+## 审核意见的写法
+
+每条意见包含：
+
+- 编号（DR-1、DR-2…）
+- 级别：
+  - **必须修改**：不改会导致做错、做不出来，或带来明显风险
+  - **建议**：改了更好，不改也能交付
+  - **备注**：供参考的信息
+- 位置：`design.md` 的哪一节，或涉及的代码路径
+- 问题是什么，以及依据（引用 spec 编号或代码位置）
+- 为什么重要：不处理会有什么后果
+- 修改方向：指出方向即可，不必替设计者重写
+
+请按实际情况判断。没有发现问题时如实写"未发现需要修改的问题"，这是正常的结果；不要为了显得认真而凑意见，也不要对不影响交付的写法偏好提"必须修改"。不确定的问题标明"待核实"并说明你查了什么。
+
+## `design-review.md` 的结构
+
+1. **结论**：通过 / 需要修改 / 阻塞，以及一句话理由
+2. **需求覆盖核对表**：逐条 AC，方案是否覆盖
+3. **审核意见**：按级别排列
+4. **需要需求方决定的问题**（如有）：围绕需求和行为来问，给出选项和影响，需求方不读代码也能回答
+
+## 第 2 轮及以后
+
+设计者已按上一轮意见修订了 `design.md`，修订记录在它的末尾。这一轮请逐条核对上一轮"必须修改"的意见是否真正解决，并检查修订是否引入了新问题或前后矛盾。已经解决的不要重复提出。结论写在 `design-review.md` 新增的"## 第 N 轮"一节中。
+
+## 结果文件
+
+```json
+{ "verdict": "approved" }
+```
+
+或者，存在必须由需求方决定的问题时：
+
+```json
+{
+  "verdict": "blocked",
+  "questions": ["需求方不读代码也能回答的问题一", "问题二"]
+}
+```
+
+- `verdict`，三选一：
+  - `approved`：没有"必须修改"的意见，可以直接进入实现。
+  - `changes_required`：有"必须修改"的意见，但设计者不需要询问需求方就能改好。之后会执行方案修订，再进行下一轮审核（轮数用完则直接进入实现）。
+  - `blocked`：`spec.md` 或 `design.md` 缺失；或者存在必须由需求方决定的问题，而且在答案出来之前动手实现很可能做出错误的东西。选择它会让流水线暂停，并把 `questions` 中的问题转给需求方。
+- `questions`（字符串数组）：`verdict` 为 `blocked` 时必填。每个问题都要让不懂技术的人能直接回答，必要时在问题里给出选项，例如"历史订单是否也需要显示新的配送状态？可选：A. 只有新订单显示；B. 历史订单也显示（需要补录数据）"。
+
+只在继续实现确实弊大于利时选择 `blocked`。可以靠合理假设推进、并且假设错了也容易调整的问题，记为意见即可。

package/engine/prompts/04b-design-revise.md

@@ -0,0 +1,34 @@
+# 本步骤任务：方案修订（第 4 步的后续，在审核结论为"需要修改"时执行）
+
+## 目标
+
+根据 `design-review.md` 的审核意见修订 `design.md`，让下一步的实现者拿到一份可以直接执行的方案。修订之后可能还有一轮审核，也可能因为轮数用完而直接进入实现；无论哪种情况，审核者和实现者都会对照你的修订记录，所以每条意见是怎么处理的要写清楚。
+
+本步骤不写产品代码，不修改 `design-review.md`。
+
+## 做法
+
+1. 读 `spec.md`、`design.md`、`design-review.md`。
+2. 逐条处理审核意见：
+   - **必须修改**：先去读相关代码或 spec，确认问题成立，然后修改方案。修改时检查受影响的其他章节（需求对照表、实施计划、测试策略）并一并更新，保持方案前后一致。
+   - 如果核实后你认为某条"必须修改"不成立，不要直接忽略。写明你的依据（代码位置或 spec 编号），并在两种做法中选择更稳妥的那一种。
+   - **建议**：采纳成本低且确实更好的就采纳；不采纳的写明原因。
+3. 在 `design.md` 末尾新增"修订记录（第 N 轮）"一节，N 与你处理的那一轮审核一致：
+
+   | 意见编号 | 级别 | 处理结果（已修改 / 部分采纳 / 未采纳） | 说明，以及改动了哪些章节 |
+   | --- | --- | --- | --- |
+
+4. 审核中提出的"需要需求方决定的问题"，原样保留在方案的"阻塞问题"或"假设"一节中，写明你暂时采用的处理方式。最终报告会把它们交给需求方。
+
+## 完成标准
+
+- 每条"必须修改"和"建议"都出现在修订记录里。
+- 修订后的方案自身没有矛盾，每条 AC 仍然都有着落。
+
+## 结果文件
+
+```json
+{ "status": "done" }
+```
+
+- `status`：所有"必须修改"的意见都已处理（修改或说明了不采纳的依据）时为 `"done"`；有意见没能处理时为 `"partial"`，并在修订记录中说明。