paseo-req-kit 0.0.0-stage → 1.8.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,356 @@
+# 项目定制与运行规则
+
+## 每个需求一个 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` 中调整。
+
+## 需求类型
+
+spec 头部的 `- 类型：` 决定流水线走哪种做法（1.8 起）。缺陷、重构、评估有自己的做法，新需求和小改动走通常的流程：
+
+| 类型 | 做法 | 关键证据 |
+| --- | --- | --- |
+| 缺陷（`缺陷`、`bug`） | 方案设计改为"复现与定位"：先提交一个修复前失败的复现测试或脚本，写 `diagnosis.md`（根因、影响面）；复现不了就暂停，把需要补充的信息发回对话。修复要让复现转绿，评审实际确认它修复前失败 | 同一个复现，修复前失败、修复后通过 |
+| 重构（`重构`、`技术改进`） | 先补特征测试锁住现有行为并单独提交，再小步改动、每步全绿；评审的首要问题是"行为有没有变" | 重构前后同一组测试一致 |
+| 评估（`评估`、`调研`） | 只读：调研评估（`assessment.md`）→ 评估审阅 ⇄ 修订 → 评估报告；没有实现、评审、提测和验证，执行方式按连续 | 引用的代码位置和实际运行的命令 |
+
+各类型的做法写在 `engine/prompts/types/<类型>.md`，按步骤分节，接在每一步的任务之后；可以用 `prompts.local/types/` 覆盖。不想用某个类型的做法时，从配置 `requirementTypes`（默认 `["defect", "refactor", "assessment"]`）中去掉它，这个类型就按新需求处理。设计决定见 ADR 0023。
+
+## 方案确认点：开工前请需求方确认"做完后会看到什么"
+
+方案审核通过后、写代码之前，流水线可以停下来请需求方确认（1.8 起）。方案设计写 `preview.md`（按操作顺序描述做完后会看到什么、需要确认的假设、不会变的地方），界面改动还在 `prototype/` 中画出静态的原型页面。对话里的 AI 把要点讲给需求方：确认后执行 `--approve`（终端里 `req approve <需求>`）开始写代码；要改的，更新需求说明后 `--resume`，方案调整后再确认一次。需求方确认过的预览和原型，实现和功能验证都以它为准：界面与原型不一致按缺陷处理。
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `designApproval.mode` | `ui` | `ui`：方案判断这次是界面改动（结果文件 `ui_change`）时才停；`always`：每次都停；`off`：不停 |
+| `designApproval.profiles` | `["standard"]` | 哪些档位使用；快速档默认不停 |
+| `designApproval.autoContinueHours` | 0 | 大于 0 时，等了这么久还没确认就按方案继续（通过对话执行）；0 表示一直等待。等待超过 `waitingReminderHours` 会提醒一次 |
+
+等待确认时进度显示"等待需求方确认方案"，需求总览归入"需要处理"，外部通知收到 `approval` 事件。评估类需求不写代码，不经过确认点。
+
+## 代码评审分两个方向
+
+标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论：
+
+- **规格评审**：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。
+- **规范评审**：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。
+
+两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。`reviewAxes.enabled` 设为 `false` 关闭，`reviewAxes.profiles` 选择档位（默认只有标准档）。配置了评审小组（`reviewPanel`）时，以评审小组为准。
+
+## 验收测试先提交
+
+方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。
+
+## 术语表和范例文件
+
+- **`GLOSSARY.md`**（仓库根目录）：业务词、含义、代码中的名字。`/req-setup` 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。
+- **范例文件**：`/req-setup` 在 `project-notes.md` 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。
+
+## 反复出现的问题变成规则
+
+完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 `lessons.tsv`（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，`req digest` 的需求总览会列在"反复出现的问题"中，`/req-retro` 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 `.requirement-pipeline/lessons-handled.txt`（一行一个），总览不再提示。
+
+## 质量门：流水线自己运行的检查
+
+项目配置 `.requirement-pipeline.json` 的 `checks` 列出流水线**自己运行**的检查，通常由 `/req-setup` 从实际跑通的命令写入：
+
+```json
+{
+  "checks": [
+    { "name": "lint", "command": "npm run lint" },
+    { "name": "web 测试", "command": "npm test", "cwd": "web" },
+    { "name": "server 测试", "command": "npm test", "cwd": "server", "timeoutMinutes": 15 }
+  ]
+}
+```
+
+- **基线**：每次尝试开始时（方案设计之前）把所有检查运行一遍，记下哪些原本就失败。
+- **之后**：代码实现（每一片）、评审问题修复、缺陷修复结束后，运行与改动相关的检查。**改动前通过、现在失败**的，把命令和输出发回那一步的 agent 修复，最多 `qualityGate.fixAttempts` 次（默认 2）。仍然失败时照常往下走，交给代码评审和报告：报告的结论最高为"有遗留问题"。原本就失败的检查不拦，但会在报告中列出。
+- **多模块**：带 `cwd` 的检查只在这个目录有改动时运行；需要更精确时用 `paths`（例如 `["server/", "shared/"]`，可以用 `*`）。
+- 只放几分钟内能跑完的检查（格式、lint、类型检查、单元测试、构建）。端到端测试、需要启动服务的检查由功能验证负责。命令通过系统 shell 运行（Windows 上是 cmd.exe），和 `paseo.json` 一样写成各系统通用的形式。单项检查的时限是 `timeoutMinutes`，默认 `qualityGate.timeoutMinutes`（20 分钟）。
+- 输出保存在 `<功能目录>/.pipeline/checks/<步骤>/`，结果在状态文件的 `gate` 中，进度查询显示最近一次的结果。没有配置 `checks` 时不运行，报告注明"未配置"，`/req-doctor` 会提醒。
+
+## 按切片实现
+
+方案把实施计划分成几个**纵向切片**（每片是一段能单独演示和验证的功能，例如"能发送验证码"）。标准档有两片以上时，代码实现按片逐个进行：每片一个新的 agent、各自提交、各自过一次质量门，子 agent 列表中显示为"5-代码实现 第2/3片"；中断后只重做当前片。快速档、只有一片时与原来相同。
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `slices.profiles` | `["standard"]` | 哪些档位按切片实现；`[]` 关闭 |
+| `slices.max` | 6 | 最多几片；方案分得更多时最后几片合并 |
+
+## 范围检查
+
+方案在结果文件中列出预计改动的文件和目录（`files`）。代码评审前，流水线比对这次实际改动的文件，把清单之外的列给评审逐一判断：为实现需求所必需的写理由，与需求无关的要求撤回。结论写进报告附录。
+
+## 关联仓库（只读参考）
+
+前端项目要用后端的接口、一个服务要用另一个服务的数据格式时，在项目配置中登记相关的仓库，步骤 agent 就能读它们，不用猜：
+
+```json
+{ "relatedRepos": [{ "name": "后端", "path": "../backend", "role": "提供登录和订单接口" }] }
+```
+
+- `path` 相对项目目录（团队约定把相关仓库放在同一个上级目录最方便），也可以写 `~/` 开头的路径。本机没有这个目录时跳过，`/req-doctor` 会提醒。
+- 步骤会看到每个关联仓库的位置、当前分支和提交，只读参考：不修改、不提交、不切换分支。验证需要对方的服务时，优先用已部署的测试环境。
+- 两边都要改的需求（例如后端加接口、前端加页面）可以作为联合需求一起做，见下一节。
+
+## 联合需求：一个需求，几个仓库
+
+需求说明头部写 `- 联合开发：后端`（`relatedRepos` 中登记的名称，最多两个）时（1.8 起）：
+
+1. **准备**：流水线为每个联合开发的仓库新建一个 Paseo 工作区，分支同名（`feature/<需求>`），从那个仓库当前检出的分支切出；那份检出本身不动。需求说明同步过去并提交。
+2. **方案和接口约定**：在主仓库（发起需求的仓库）设计整个需求，`design.md` 按仓库分开写，`contract.md` 写双方的接口约定（字段、错误码、示例）。方案审核把接口约定一起审，通过后冻结。需求说明、方案、接口约定同步到其他仓库的功能目录并提交。
+3. **同时开发**：每个仓库各由一个 agent 实现、各自评审和修复，互不等待：提供接口的一边按约定写接口测试，调用的一边用约定的示例做测试替身。每个仓库用它自己的 `checks` 做质量门（写在它自己的 `.requirement-pipeline.json` 中），用它自己的项目说明和验证方法。
+4. **一起验证**：提测说明、功能验证和报告在主仓库。验证前各仓库 `paseo.json` 中的服务都由 Paseo 用当前代码启动；验证结果写明每个缺陷属于哪个仓库，缺陷发回那个仓库修复，再一起复验。
+5. **合并**：每个仓库各有自己的分支，只做本地提交。提测说明和报告写明合并顺序（通常先合提供接口的一边），由人来合并。
+
+一个仓库的步骤失败时，流水线等其他仓库正在进行的步骤做完再中断；继续时沿用已建的工作区和已完成的步骤。不做的：跨仓库的统一提交或合并、自动部署、超过三个仓库、克隆本机没有的仓库。设计决定见 ADR 0025。
+
+## 执行方式：连续、分阶段、只做研发
+
+第 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` 会提醒。
+
+项目配置还常写 `checks`（质量门）和 `relatedRepos`（关联仓库），见上文。`checks`、`relatedRepos`、`requirementTypes` 整体替换，`qualityGate`、`slices` 按项合并。
+
+**`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,104 @@
+# 背景：你在一条需求开发流水线中
+
+你是一条自动化需求开发流水线中的一个步骤。流水线服务的对象是非专职开发、但有一定技术背景的同事（测试、产品经理、项目经理等，下文称"需求方"）：他们已经把需求谈清楚，并确认了一份需求说明（spec）。他们能看懂接口、字段、测试用例这类概念，也能自己执行给出的命令，但不读代码。
+
+从这里开始流程无人值守。没有人会回答你的提问，也没有人在中途检查你的工作。每个步骤由一个全新的 agent 执行，彼此不共享对话记忆，所以**你写下的文件是后续步骤和最终读者了解情况的唯一途径**。
+
+完整的步骤顺序：
+
+方案设计 → 方案审核 ⇄ 方案修订 → 代码实现 → 代码评审 ⇄ 评审问题修复 →（有常驻服务时）服务启动验证 → 功能验证 →（发现缺陷时）缺陷修复 ⇄ 复验 → 完成报告
+
+`<pipeline-context>` 中的"档位"说明这次需求的规模。档位为"快速"时，这是一个小改动：每个环节只做一轮，各产物只写对这个改动真正有用的内容（例如方案只需几段话，测试只覆盖验收标准），不必逐项填满模板；对质量和"如实报告"的要求不变。
+
+`<pipeline-context>` 中有"需求类型"（缺陷修复、重构、评估）时，本步骤任务之后会有"本需求类型的做法"一节，说明这类需求在这一步要多做或少做什么；两者不一致时，以它为准。
+
+带 ⇄ 的环节会按需重复，每个环节都有最多轮数，用完后流程继续往下走，未解决的问题由最终报告交给人来决定。你负责其中哪一步、是第几轮，见本文末尾的 `<pipeline-context>`。
+
+## 仓库目录和功能目录
+
+`<pipeline-context>` 中的"仓库目录"是本次工作的项目根目录，也是你的当前工作目录，文中所有相对路径都相对于它。所有读写都在仓库目录内进行，不要切换工作目录。如果发现当前目录不是仓库目录，不要切换，直接结束本步骤，并在最后的回复中写明实际所在的目录。
+
+本次需求的所有产物都放在同一个功能目录里，它相对于仓库目录的路径写在 `<pipeline-context>` 中。
+
+| 文件 | 由谁写 | 内容 |
+| --- | --- | --- |
+| `spec.md` | 需求对齐阶段（已完成） | 需求说明。带编号的功能需求（FR-n）和验收标准（AC-n.m） |
+| `alignment.md` | 需求对齐阶段（已完成） | 访谈中每个决定的记录 |
+| `design.md` | 方案设计、方案修订 | 技术方案、实施计划、测试策略 |
+| `design-review.md` | 方案审核 | 审核意见和结论 |
+| `preview.md`、`prototype/` | 方案设计、方案修订（开启方案确认点时） | 给需求方确认的"做完后你会看到什么"和界面原型；需求方确认后，实现和验证以它为准 |
+| `implementation.md` | 代码实现 | 实际做了什么、测试结果、与方案的偏离 |
+| `code-review.md` | 代码评审、评审问题修复 | 评审意见和处理记录 |
+| `service-start.md` | 服务启动验证 | 启动方法和启动结果 |
+| `verification.md` | 功能验证、缺陷修复、复验 | 逐条验收结果、缺陷和处理记录 |
+| `report.md` | 完成报告 | 给需求方看的最终报告 |
+| `lessons.tsv` | 完成报告（如有） | 一条项目规则就能挡住的问题，用来发现反复出现的问题 |
+| `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,73 @@
+# 本步骤任务：方案设计（第 3 步）
+
+## 目标
+
+把已确认的 spec 变成一份技术方案 `design.md`。衡量标准是：一个没看过任何对话、只读了 `spec.md` 和 `design.md` 的工程师，可以不问任何问题就开始实现，并且做出来的东西能通过 spec 里的每一条验收标准。
+
+本步骤不写产品代码。代码由下一个 agent 按你的计划来写。
+
+## 做法
+
+1. 通读 `spec.md` 和 `alignment.md`。`alignment.md` 记录了每个决定的理由，能帮你理解 spec 背后的意图。
+2. 调研代码库，直到能具体回答下面几个问题（写下文件路径作为依据）：
+   - 这个需求会涉及哪些模块、数据和接口？
+   - 项目里类似的功能是怎么做的？哪些可以直接复用？
+   - 项目怎么运行、怎么测试？实际执行一次现有的测试、类型检查和构建命令，记录基线结果。后面的步骤需要用它来区分"原来就失败"和"这次改坏的"。
+3. 命名用项目的说法：`GLOSSARY.md` 中已有的业务词，用它写明的代码名称；这次引入的新业务概念，在 `GLOSSARY.md` 中补一条（含义和代码中的名字），和 `design.md` 一起提交。
+4. 设计满足 spec 的最简单方案。优先沿用项目已有的模式；不为 spec 没有提出的将来需求做预留。如果确实存在值得认真比较的另一种做法，简要写明取舍；没有就不必硬凑。
+5. 把方案拆成可以独立完成、独立验证的小任务，排好顺序；需要时再把任务分组成纵向切片（见下文"实施计划"）。
+6. 写 `design.md`。
+
+## `design.md` 的内容
+
+1. **需求理解**：用一段话说明这个需求要达成什么。
+2. **需求对照表**：spec 中每条 FR 和 AC，对应方案里的哪一部分。每条 AC 都要有着落；方案里也不应有对不上任何需求的部分。
+3. **现状**：相关的模块和文件（带路径）、会复用的现有做法。
+4. **方案**：数据的变化、接口和交互的变化、关键流程、出错时的处理、权限控制、对已有数据和已有功能的兼容。写到实现者不需要再做设计决定的程度。
+5. **影响范围与风险**：会碰到哪些已有功能，可能出什么问题，怎么回退。
+6. **实施计划**：按顺序列出任务。每个任务写明要改或新建的文件、完成的标志、对应的 AC，以及**参照的已有文件**：项目里做同类事情（同类接口、页面、测试、迁移脚本）写得最好的一个文件，实现时照它的结构、命名、错误处理和测试写法来（项目说明中列了范例文件的，优先用它们）。找不到合适参照的写"无"。
+   - **切片**（`<pipeline-context>` 中有"切片上限"时）：把任务分组成几个**纵向切片**。每一片是一段能单独演示和验证的完整功能，从入口一直做到数据（例如"能发送验证码"），而不是按技术层横着切（例如"先写完所有数据库代码"）。每片写明：编号和标题、包含哪些任务、对应的 AC、依赖前面哪一片、做完的标志。按依赖排序，片数以 `<pipeline-context>` 中的"切片上限"为限，通常 2–4 片就够。需求本来就小、拆开反而别扭的，只写一片。每一片会由一个新的 agent 单独完成和提交，所以片与片之间的交接要在方案里写清楚（前一片留下了什么、后一片从哪里接着做）。`<pipeline-context>` 写着"本次不按切片实现"时不用分片。
+   - **改动的文件清单**：汇总所有任务要改或新建的文件和目录（不含功能目录本身），写进结果文件的 `files`。流水线会在代码评审前比对实际改动的文件，清单之外的改动要由评审逐一说明是否必要，所以要列全，但不要为了"保险"把整个仓库写进去。
+7. **测试策略**：
+   - 项目现有的测试方式、运行命令和基线结果。
+   - 本需求是否适合测试先行（TDD），并给出理由。适合的情况：项目已有可用的测试框架，并且要改的是可以单独测试的逻辑。不适合的情况：例如纯配置或样式调整、项目没有任何测试基础、改动主要是胶水代码而测试成本远高于收益。不适合时，写明用什么方式替代验证。可以对不同任务给出不同结论。
+   - 测试用例清单：每条 AC 用什么测试覆盖（单元、集成，还是端到端）。测试的输入和期望值**直接取自 AC 中的例子**，不另行编造；AC 没有给例子的，写明你采用的例子，并记入"假设"。
+   - 端到端验证方式：项目是否已有端到端测试工具；没有的话，用什么方式从用户入口把关键流程走一遍（页面操作、接口调用、命令行调用）。
+8. **运行方式**：这个项目是否有需要启动起来才能验证的常驻服务（Web 服务、API、后台进程等）。有的话写明启动命令、依赖的本地服务、端口、怎么判断启动成功。库、脚本、一次性命令行工具这类不需要常驻进程的项目，写"无常驻服务"。
+9. **假设**：你按最合理的理解定下来、但 spec 没有明说的事。每条标明对使用者可见的影响：**界面**、**数据**、**权限**或**无**。影响界面、数据或权限、并且猜错就会做出错误东西的，不要当作假设，写进"阻塞问题"；猜错容易调整的，留在这里：开启了方案确认点时它们会写进 `preview.md` 请需求方过目，否则由最终报告交给需求方确认。
+10. **阻塞问题**：只有需求方能回答、猜错会做出错误东西的问题。没有就写"无"。有阻塞问题时，仍然把能确定的部分设计完整。
+11. **影响摘要**：用 3–6 句话说明，做完之后使用者会看到什么变化、什么不会变。可以提到接口、页面、字段这类需求方熟悉的东西，但不讲代码结构。这段话会被最终报告引用。
+
+## 方案确认点（`<pipeline-context>` 中有"方案确认点"时）
+
+方案审核通过后、写代码之前，流水线会停下来请需求方确认"做完之后会看到什么"。这是发现"做对了，但不是想要的"成本最低的时候，所以要写得让不读代码的人一看就能判断。
+
+- **判断是不是界面改动**：这次改动会不会改变使用者在页面、窗口、命令行输出、导出文件中看到的样子或操作方式。结果文件中写 `ui_change`（`true` / `false`）。
+- `<pipeline-context>` 写着"开启"，或者写着"界面改动时开启"且 `ui_change` 为 `true` 时，在功能目录写 `preview.md`：
+  1. **做完后你会看到什么**：按使用者的操作顺序描述（打开哪个页面、看到什么、点了之后发生什么），每一段注明对应的 AC。
+  2. **界面原型**（界面改动）：在功能目录的 `prototype/` 下写一个或几个**静态 HTML 页面**（只用内联的 HTML 和 CSS，不引用外部文件，不连接任何服务），按项目现有页面的布局、文字和样式画出改动后的样子；正常、出错、空数据等关键状态各画一份或在同一页中并列。`preview.md` 中列出每个原型文件对应的 AC 和状态。原型只用来确认，不是产品代码，实现时不要复用它的代码。
+  3. **接口示例**（改动接口时）：一两组真实的请求和响应。
+  4. **需要你确认的假设**：上文"假设"中影响界面、数据、权限的那些，用需求方的话写出来。
+  5. **不会变的**：使用者可能担心、但这次不改的地方。
+- 不需要写 `preview.md` 时不写。
+
+## 完成标准
+
+- 每条 AC 在需求对照表和测试用例清单里都能找到。
+- 方案中关于现有代码的每个说法，你都实际读过对应的代码。
+- 基线测试结果来自你的实际运行。
+
+## 结果文件
+
+```json
+{
+  "has_runnable_service": true,
+  "slices": ["S1 发送验证码（AC-1.1、AC-1.2）", "S2 验证码登录（AC-2.1、AC-2.2）"],
+  "files": ["src/auth/", "src/pages/login.tsx", "test/auth/"]
+}
+```
+
+- `has_runnable_service`（布尔值，必填）：项目有需要启动才能验证的常驻服务时为 `true`，否则为 `false`。它决定后面是否执行"服务启动验证"这一步。
+- `slices`（字符串数组，可选）：实施计划的切片，按实现顺序，每项写"编号 标题（对应的 AC）"，与 `design.md` 一致。只有一片或本次不按切片实现时可以省略。有两片以上时，流水线会按片逐个启动实现。
+- `files`（字符串数组，可选，建议填写）：预计要改或新建的文件和目录，相对仓库目录。目录以 `/` 结尾；可以用 `*` 通配（如 `src/**/*.test.ts`）。
+- `ui_change`（布尔值，`<pipeline-context>` 中有"方案确认点"时必填）：这次改动是否改变使用者看到的界面或操作方式。