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

package/notifiers/im-template.mjs

@@ -0,0 +1,60 @@
+// req-kit 外部通知模板：接入企业内部 IM（或任何其他渠道）。
+//
+// 用法：
+//   1. 复制到 ~/.req-kit/notifiers/im.mjs（或团队配置仓库中），按下面的 TODO 实现发送。
+//   2. 在本机配置 ~/.req-kit/config.json（或团队配置）中加上：
+//        "notifiers": [
+//          { "module": "~/.req-kit/notifiers/im.mjs",
+//            "events": ["blocked", "failed", "completed"],
+//            "options": { "webhook": "https://im.example.internal/hook/xxxx" } }
+//        ]
+//      module 可以是绝对路径、"~/" 开头的路径，或相对配置文件所在目录的路径。
+//      events 不写时发送全部事件：milestone、blocked、permission、failed、completed、phase_done、approval、digest。
+//   3. 在终端运行 `req notify-test`（或 `req notify-test --type blocked`）发一条测试通知，不需要运行流水线。
+//
+// 约定（详见 contracts/notifier-event.md）：
+//   - 导出 default（或名为 notify 的）函数，参数为 (event, options)，可以是 async。
+//   - 15 秒内没有完成按失败处理；抛出的错误只写进流水线日志，不影响流水线。
+//   - 只能使用 Node.js 22 内置的能力（例如全局 fetch），req-kit 不会为它安装依赖。
+//   - 不要把口令写在这个文件里：放在环境变量中，用 process.env 读取。
+
+/**
+ * @param {object} event     通知事件，字段见 contracts/notifier-event.md
+ * @param {Record<string, unknown>} options  配置中的 options
+ */
+export default async function notify(event, options) {
+  const title = {
+    milestone: "进展",
+    blocked: "需要你决定",
+    permission: "等待批准",
+    failed: "开发中断",
+    completed: "开发完成",
+    digest: "需求总览",
+    phase_done: "研发完成，可以提测",
+    approval: "请确认方案",
+  }[event.type] ?? event.type;
+
+  // 一条通用的纯文本消息，大多数 IM 机器人都能直接使用。
+  // 需求总览（digest）的 text 已经是完整的多行文字。
+  const lines = event.type === "digest" ? [event.text] : [`【req-kit · ${title}】${event.feature.title}`, event.text];
+  if (event.type === "completed" && event.details.summary) lines.push("", String(event.details.summary));
+  if (event.type === "phase_done") lines.push("", `提测说明：${event.details.handoffPath}`);
+  if (event.type === "approval") lines.push("", `要确认的内容：${event.details.previewPath}`);
+  if (event.type === "blocked") lines.push("", ...event.details.questions.map((q, i) => `${i + 1}. ${q}`));
+  if (event.type !== "digest") lines.push("", `需求目录：${event.feature.dir}${event.branch ? `（分支 ${event.branch}）` : ""}`);
+  const text = lines.join("\n");
+
+  // TODO：按企业内部 IM 的接口实现发送。例如一个接收 JSON 的群机器人：
+  //
+  // const response = await fetch(String(options.webhook), {
+  //   method: "POST",
+  //   headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.MY_IM_TOKEN}` },
+  //   body: JSON.stringify({ msgtype: "text", text: { content: text } }),
+  // });
+  // if (!response.ok) throw new Error(`IM 返回 ${response.status}`);
+  //
+  // 还没有实现时，先什么也不做（流水线日志中会记录"外部通知已发送"）。
+  // 用 req notify-test 测试时，把将要发送的内容打印出来，方便核对排版。
+  if (process.env.REQ_KIT_NOTIFY_TEST === "1") console.log(`--- 将要发送的内容 ---\n${text}\n---------------------`);
+  void options;
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "paseo-req-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.8.0-beta.3",
+  "description": "req-kit: a requirement-development workflow for Paseo. /req aligns a requirement in chat; the engine runs design, implementation, review and verification as Paseo agents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yiyisf/paseo-req-kit.git"
+  },
+  "homepage": "https://yiyisf.github.io/paseo-req-kit/",
+  "bugs": "https://github.com/yiyisf/paseo-req-kit/issues",
+  "keywords": [
+    "paseo",
+    "agents",
+    "requirements",
+    "workflow",
+    "claude-code",
+    "codex"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "reqKit": {
+    "paseo": ">=0.11.0 <0.12.0"
+  },
+  "bin": {
+    "req": "bin/req.mjs",
+    "req-kit": "bin/req.mjs",
+    "start-pipeline": "bin/start-pipeline.mjs"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test --test-concurrency=1 engine/test/*.test.ts test/*.test.ts",
+    "smoke": "tsx engine/src/smoke-test.ts",
+    "doctor": "node bin/req-doctor.mjs",
+    "eval": "tsx engine/src/eval.ts",
+    "eval:self-check": "tsx engine/src/eval.ts --reference"
+  },
+  "dependencies": {
+    "@getpaseo/client": "^0.11.2",
+    "tsx": "^4.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "files": [
+    "bin/",
+    "engine/src/",
+    "engine/prompts/",
+    "skills/",
+    "principles/",
+    "contracts/",
+    "notifiers/",
+    "docs/guide/",
+    "docs/adr/",
+    "install.mjs",
+    "config.example.json",
+    "CHANGELOG.md",
+    "SCOPE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/principles/INDEX.md

@@ -0,0 +1,11 @@
+# req-kit 工作原则索引
+
+这七条原则同时用于聊天中的 `/req`（需求对齐）和流水线的各个步骤。每条一句话，括号里是对应的 skill，展开说明了为什么、正反例和常见借口。
+
+1. **按读者说话**（`principle-speak-to-reader`）：对需求方讲需求和结果，不讲代码实现；接口、字段、测试用例这类他们熟悉的概念可以直接用，类名、函数名、堆栈留在文件里。
+2. **证明它能用**（`principle-prove-it-works`）："通过"必须有实际运行过的命令和看到的输出作为证据；没运行过就不是通过。
+3. **如实报告**（`principle-report-honestly`）：未验证、未完成、有分歧、被驳回的意见都写出来；读者会直接相信你写的内容。
+4. **修根因**（`principle-fix-root-cause`）：找到问题真正的原因再改；不削弱测试或检查来让它通过；能用测试、类型、配置挡住的问题，就不只写在文档里。
+5. **只做这个需求**（`principle-this-requirement-only`）：不顺手重构、不升级无关依赖、不改无关文件；看到无关问题记下来交给人决定。
+6. **先删再加**（`principle-delete-before-add`）：能复用已有代码、删掉多余部分解决的，不新增；新增时选最简单可行的做法。
+7. **别卡在等人**（`principle-dont-block-on-humans`）：能合理假设的就假设并记录下来，继续往前走；只有猜错会做出错误东西的问题才停下来问。

package/skills/acceptance-criteria/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: acceptance-criteria
+description: req-kit 方法：把功能需求（FR）拆成可以亲手试用、也可以直接转为测试用例的验收标准（AC-n.m），覆盖正常流程、异常和边界。由 /req 的手册和 spec-writing 调用。
+---
+
+# 验收标准
+
+验收标准（AC）是需求方验收、流水线验证和测试同事编写用例的共同依据。写到一个没参加过对话的人也能据此判断"通过还是不通过"的程度。
+
+## 格式
+
+每条 AC 有编号 `AC-<FR 编号>.<序号>`，例如 FR-2 的第一条是 `AC-2.1`。写成三段：
+
+```markdown
+- **AC-2.1** <一句话标题>
+  - 前置条件：<数据、账号、环境、开关等起始状态>
+  - 操作：<用户做了什么，或调用了什么接口、执行了什么命令>
+  - 预期结果：<应该看到什么。具体到页面上的文字、接口返回的字段和值、数据的变化>
+```
+
+简单的 AC 可以写成一句话："在<什么情况>下，当<做了什么>，应该<看到什么>。"只要三个要素都在。
+
+## 要求
+
+- **用具体的例子。** 每条 AC 至少带一组真实的数据：输入什么、得到什么（"输入手机号 13800000000，60 秒内再点发送，提示'请 45 秒后重试'"），而不是"在限制时间内重复发送会被拒绝"。按规则计算的（金额、时间、状态变化），给出两三组覆盖边界的例子，可以写成表格。这些例子会直接成为测试的期望值：需求方确认的，就是测试会检查的东西。
+- **可检查。** 不用"快速""友好""合理""正常"这类词，除非给出具体标准（"3 秒内返回""错误提示为'验证码已过期，请重新获取'"）。
+- **每条 FR 至少一条 AC。** 并且不只写正常流程：输入不合法、权限不足、重复操作、边界值、依赖不可用，凡是访谈中谈到的都要有对应的 AC。
+- **一条 AC 只检查一件事。** 一条里出现"并且……并且……"时，考虑拆开。
+- **写明测试数据。** 需要特定数据或账号时，在前置条件里写清楚；访谈中定下的测试账号、测试环境也写进来。
+- **写明怎么验证（可选）。** 已知可以用命令或接口验证的，写出来，例如"`GET /api/orders?status=paid` 返回的列表中不包含已退款订单"。这方便流水线和测试同事直接复用。
+- **不写实现。** AC 描述可观察的行为，不描述代码怎么写。
+
+## 例子
+
+```markdown
+### FR-2 验证码登录（优先级：必须有）
+
+- **AC-2.1** 正确的验证码可以登录
+  - 前置条件：手机号 13800000001 已注册，已获取验证码 123456（5 分钟内）
+  - 操作：在登录页输入手机号和验证码，点"登录"
+  - 预期结果：进入首页，右上角显示该用户的昵称
+- **AC-2.2** 验证码过期
+  - 前置条件：同上，但验证码获取于 6 分钟前
+  - 操作：输入该验证码登录
+  - 预期结果：停留在登录页，提示"验证码已过期，请重新获取"，不进入首页
+- **AC-2.3** 连续输错被锁定：同一手机号连续输错 3 次后，第 4 次无论对错都提示"尝试次数过多，请 5 分钟后再试"。
+- **AC-2.4** 重发间隔（按规则计算，用表格给出例子）
+
+  | 上次发送后过了 | 点"重新发送" | 结果 |
+  | --- | --- | --- |
+  | 15 秒 | 是 | 提示"请 45 秒后重试"，不发送 |
+  | 59 秒 | 是 | 提示"请 1 秒后重试"，不发送 |
+  | 60 秒 | 是 | 发送新的验证码，旧的立即失效 |
+```
+
+## 自查
+
+- 每条 FR 都有 AC，异常和边界情况都有 AC
+- 每条 AC 的预期结果都是能看到、能比较的东西，并且至少有一组具体的输入和期望输出
+- 按规则计算的 AC，例子覆盖了边界（刚好达到、差一点、超过）
+- 拿着 AC 的人不需要再问任何问题就能执行

package/skills/principle-delete-before-add/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: principle-delete-before-add
+description: req-kit 工作原则：先删再加。能复用已有代码或删掉多余部分解决的，不新增。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 先删再加
+
+**能复用已有代码或删掉多余部分解决的，不新增。**
+
+## 为什么
+
+每一行新代码都要被阅读、测试和维护。先看项目里有没有现成的做法可以复用，再考虑新增；新增时选最简单可行的方案，而不是为想象中的未来需求预留扩展。
+
+## 例子
+
+好的做法：
+
+"项目里已有发送短信的封装 sendSms()，直接复用；新增的只是验证码的生成和校验，约 60 行。"
+
+不好的做法：
+
+"新建了一个通用的通知框架，支持短信、邮件、推送三种渠道，本次只用到短信。"
+
+## 常见借口
+
+- **"以后肯定会用到。"** 以后需要时再加。现在加的扩展点多半猜不准以后的需求。
+- **"复用旧代码要先读懂它，太慢。"** 读懂已有做法正是避免重复和冲突的前提。
+
+## 用在哪里
+
+方案设计（方案中说明复用了什么）、代码实现、代码评审。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/principle-dont-block-on-humans/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: principle-dont-block-on-humans
+description: req-kit 工作原则：别卡在等人。能合理假设的就假设并记录，只有猜错会做出错误东西的问题才停下来问。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 别卡在等人
+
+**能合理假设的就假设并记录，只有猜错会做出错误东西的问题才停下来问。**
+
+## 为什么
+
+流水线无人值守，停下来等人会让需求方等上几个小时；但不该猜的事情猜错了，代价更大。区分两者的标准是：如果猜错，做出来的东西是不是就错了。
+
+## 例子
+
+好的做法：
+
+"spec 没写分页大小，按项目中其他列表页的 20 条处理，记为假设 A-3。"
+
+"spec 没说过期的优惠券能否退款，两种理解会导致完全不同的结果，记为阻塞问题，请需求方决定。"
+
+不好的做法：
+
+"不确定按钮颜色，流水线暂停等待确认。"（可以按现有风格假设）；或者"退款规则不清楚，按我的理解实现了"（应当询问）
+
+## 常见借口
+
+- **"问一下总没错。"** 在无人值守的流程里，每一次停下来都有成本。能从代码、文档、spec 推断的就推断。
+- **"假设了就不用记了。"** 每条假设都要写进产物的"假设"一节，报告会汇总给需求方确认。
+
+## 用在哪里
+
+需求对齐时区分"必须问"和"可以假设"；方案设计和方案审核中的"阻塞问题"。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/principle-fix-root-cause/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: principle-fix-root-cause
+description: req-kit 工作原则：修根因。找到问题真正的原因再改，不削弱检查来让它通过。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 修根因
+
+**找到问题真正的原因再改，不削弱检查来让它通过。**
+
+## 为什么
+
+删掉失败的测试、放宽断言、针对测试写死返回值，都会让检查失去意义，并把问题留到线上。能用测试、类型检查、lint、CI 挡住的问题，比写进文档或提示词更可靠。
+
+## 例子
+
+好的做法：
+
+"测试失败是因为时区：服务端按 UTC 计算截止日期。改为按用户所在时区计算，并新增一条跨零点的测试用例。"
+
+不好的做法：
+
+"测试在 CI 上偶尔失败，已把超时从 5 秒调到 60 秒并加了重试。"（没有查原因）
+
+## 常见借口
+
+- **"先让它过，回头再查。"** "回头"通常不会发生。查不出原因时，如实写明现象和已排查的范围。
+- **"这个测试本来就写得不好。"** 可以改进测试，但要说明它原来想检查什么、新的写法如何仍然检查到。
+
+## 用在哪里
+
+评审问题修复、缺陷修复、/req-retro（按"CI → 配置 → 项目说明 → 提示词"的顺序选择落点）。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/principle-prove-it-works/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: principle-prove-it-works
+description: req-kit 工作原则：证明它能用。"通过"必须有实际运行过的命令和看到的输出作为证据。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 证明它能用
+
+**"通过"必须有实际运行过的命令和看到的输出作为证据。**
+
+## 为什么
+
+需求方会根据报告决定是否验收，往往不会、也不应该把每一条都重新跑一遍。没有证据的"通过"把风险悄悄转给了他们，而且往往要到上线后才暴露。
+
+## 例子
+
+好的做法：
+
+"AC-2.1 通过：执行 `pnpm test sms-login` ，12 个用例全部通过（输出见 verification.md 第 3 节）；手工在本地页面输入错误验证码 3 次，第 4 次被锁定 5 分钟，截图 evidence/ac-2.1.png。"
+
+不好的做法：
+
+"AC-2.1 通过：代码逻辑已覆盖该场景。"
+
+## 常见借口
+
+- **"代码一看就是对的，没必要跑。"** 看起来对和运行起来对是两回事。跑不了就写"未验证"并说明原因。
+- **"测试环境起不来，先标通过，后面再补。"** 标"未验证"，写明环境问题。把未验证写成通过是唯一不可接受的结果。
+
+## 用在哪里
+
+代码实现、服务启动验证、功能验证、复验、完成报告的验收对照表。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/principle-report-honestly/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: principle-report-honestly
+description: req-kit 工作原则：如实报告。未验证、未完成、有分歧、被驳回的意见都写出来。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 如实报告
+
+**未验证、未完成、有分歧、被驳回的意见都写出来。**
+
+## 为什么
+
+读者没有能力也没有时间核对每一句话，他们会直接相信你写的内容。一份"都很好"的报告如果有一处不实，整份报告就失去了价值；而如实写出的"未完成"可以让人及时补救。
+
+## 例子
+
+好的做法：
+
+"结论：已完成，有遗留问题。导出 Excel 在 1 万行以上时超过 30 秒（AC-4.2 未达成）；评审中关于缓存的一条建议被驳回，理由是需求没有并发场景，请开发同事确认。"
+
+不好的做法：
+
+"结论：已完成。性能方面后续可以继续优化。"
+
+## 常见借口
+
+- **"写出问题会显得没做好。"** 隐瞒的问题迟早会被发现，那时代价更大。如实报告是被明确要求的结果，而不是失败。
+- **"这个分歧不重要，就不提了。"** 重不重要由读者判断。一句话写出来，成本很低。
+
+## 用在哪里
+
+每个步骤的产物、结果文件、完成报告、发回对话的通知。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/principle-speak-to-reader/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: principle-speak-to-reader
+description: req-kit 工作原则：按读者说话。对需求方讲需求和结果，不讲代码实现。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 按读者说话
+
+**对需求方讲需求和结果，不讲代码实现。**
+
+## 为什么
+
+需求方是测试、产品、项目经理这类有技术背景但不读代码的同事。他们能判断"这个接口返回的字段对不对""这个用例覆盖了没有"，但没法判断"这个类拆得合不合理"。把实现细节讲给他们，只会得到猜测式的回答，还会让真正需要他们决定的事被淹没。
+
+## 例子
+
+好的做法：
+
+"提交后状态会变成'待审批'，审批人在待办列表里能看到这一条；如果审批人 3 天没处理，会再提醒一次。这条规则要不要对周末也生效？"
+
+不好的做法：
+
+"我们在 ApprovalService 里加了一个定时任务，用 cron 每小时扫一次 pending 状态的记录。你看 cron 表达式用哪个？"
+
+## 常见借口
+
+- **"他们是测试，懂技术，讲细一点没关系。"** 懂测试不等于读代码。讲到接口、字段、状态、用例这一层就够了，再往下是开发同事的事。
+- **"不讲实现，他们不知道我做了多少。"** 他们关心的是结果对不对、怎么验证。工作量体现在验收对照表和证据里。
+
+## 用在哪里
+
+聊天中的提问、spec、通知转述、报告正文。类名、函数名、提交号放进附录或文件里。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/principle-this-requirement-only/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: principle-this-requirement-only
+description: req-kit 工作原则：只做这个需求。不顺手重构、不升级无关依赖、不改无关文件。在使用 /req 对齐需求、或作为需求开发流水线的步骤工作时参考。
+---
+
+# 只做这个需求
+
+**不顺手重构、不升级无关依赖、不改无关文件。**
+
+## 为什么
+
+无关的改动会让评审变难、让风险变大，也会让需求方无法判断"这次到底改了什么"。一个需求的提交应该能单独审阅、单独回退。
+
+## 例子
+
+好的做法：
+
+"发现 utils/date.ts 中有一个与本需求无关的时区隐患，已记入报告的'经验与改进建议'，未修改。"
+
+不好的做法：
+
+"顺便把整个 utils 目录改成了新的写法，并升级了日期库。"
+
+## 常见借口
+
+- **"反正都在改这个文件。"** 只改与需求相关的部分。整理代码可以作为单独的需求提出。
+- **"升级依赖能修好一个警告。"** 与本需求无关就不升级，把警告记下来。
+
+## 用在哪里
+
+方案设计、代码实现、评审问题修复、缺陷修复；聊天中一个对话只处理一个需求。
+
+所有原则的一句话版本见 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。

package/skills/req/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: req
+description: req-kit 需求开发入口。提新需求或小改动、查看进度、暂停或继续、修改需求、验收、报告上线后的问题、接手别人的需求时使用；也可以直接调用 /req 加一句话描述。由它判断走哪本手册，需求确认后在后台启动开发流水线（设计、实现、评审、验证、报告）。
+metadata:
+  opencode/slash: "true"
+---
+
+# req-kit 需求开发入口（{{REQ_KIT_VERSION}}）
+
+用户的话：$ARGUMENTS
+
+（上面显示的是占位符本身或为空时，以用户在本次消息中说的为准。）
+
+## 对面是谁
+
+使用者通常是测试、产品经理或项目经理：有一定技术背景，熟悉接口、字段、状态、测试用例和测试环境，能在终端执行给定的命令，但不读代码。和他们说话时讲需求和结果，不讲代码实现。
+
+## 先读原则
+
+读 `{{REQ_KIT_ROOT}}/principles/INDEX.md`。七条原则在整个对话中都适用，流水线的每一步也遵守同样的原则。
+
+## 选手册
+
+根据用户的话和当前目录的情况选一本手册，然后读取它并照做：
+
+| 用户想做的事 | 典型说法 | 手册 |
+| --- | --- | --- |
+| 提一个新需求，包括修一个缺陷、重构代码、先评估能不能做 | "我想加一个……""这里有个 bug……""整理一下……的代码""帮我评估一下能不能做……" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/new.md` |
+| 一个范围很小的改动 | "把这个按钮的文字改成……""加一个配置项" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/small.md` |
+| 查看进度、暂停、继续 | "做到哪了""先停一下""继续开发" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/status.md` |
+| 研发完成后开始测试验证（提测） | "可以提测了""开始测试""我是测试，来测这个需求" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/verify.md` |
+| 修改已经确认的需求 | "刚才那个需求我想改一下""再加一条规则" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/change.md` |
+| 验收 | "做完了，我来验收""帮我对一下验收标准" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/accept.md` |
+| 上线后发现问题 | "线上发现……不对""用户反馈……" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/incident.md` |
+| 接手或回顾一个需求 | "这个需求是之前同事提的""这个需求现在什么情况" | `{{REQ_KIT_ROOT}}/skills/req/playbooks/takeover.md` |
+
+判断方法：
+
+- 先看这个项目里有哪些需求：执行"列出需求"命令（见下面"开发流水线命令"），它会列出所有工作区中的需求和各自的阶段。用户说"继续""进度""验收"之类，且只有一个相关的需求时，直接用它。
+- 新需求和小改动拿不准时，先按"新需求"开始。新需求手册在复述之后会判断规模，必要时改走快速档。
+- 用户想改的是已经验收或上线的功能：修改按"新需求"或"小改动"处理，问题按"上线后发现问题"处理。
+- 实在判断不了，用一个选择题问用户。
+
+项目还没有接入（没有 `.requirement-pipeline/verify.md`）时，在开始前提醒一句：建议请开发同事或测试同事先运行一次 `/req-setup`，这样开发和验证步骤会更快、更稳定；不接入也可以继续。
+
+## 公布步骤
+
+选定手册后，把手册开头"步骤"一节的各项原样放进你的待办列表（有待办工具时），让用户随时看到做到哪一步。每完成一项就勾掉。没有待办工具时，开始时用一句话列出步骤即可。
+
+同一个对话中，用户之后说的话（"做到哪了""先停一下""继续"）不需要再带 `/req`，仍然按本 skill 处理。
+
+## 通用规则
+
+- **一次只问一个问题**，给 2–4 个选项，推荐项放第一个并说明理由。有选择题式的提问工具就用它。
+- **一个对话只处理一个需求。** 用户提出第二个无关需求时，建议新开一个对话（最好是新的工作区）。
+- **不切换工作目录。** 流水线会把这个对话的工作目录当作仓库目录，每个步骤都作为子 agent 挂在这个对话下、在同一个目录中工作。不要 `cd` 到别的目录再执行命令；功能目录必须建在当前工作目录之内；需求属于其他项目时，请用户到那个项目中新开对话。
+- **不在对话中途切换分支。**
+- **需求在自动新建的工作区中时**（用"启动（自动新建工作区）"启动过）：这个对话的工作目录不变，命令照常在这里执行，功能目录写原来的相对路径即可，流水线会找到它。需求文件已移到新工作区，读写时用流水线输出或通知中给出的完整路径。
+- 需要检查安装或配置时，告诉用户运行 `/req-doctor`（或请开发同事运行），不要自己去改安装目录或配置文件。
+
+## 开发流水线命令
+
+以下命令在 bash、PowerShell、cmd 中写法相同，在当前工作目录执行。它们会自动识别当前对话（Paseo 提供的 `PASEO_AGENT_ID`、`PASEO_AGENT_CWD`），不需要传对话 ID 或仓库目录。`<功能目录>` 换成实际路径，例如 `docs/features/20261012-sms-login`。
+
+| 做什么 | 命令 |
+| --- | --- |
+| 需求说明审阅 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --spec-review` |
+| 启动 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录>` |
+| 启动（自动新建工作区） | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --worktree` |
+| 预约启动 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --at <时间>`（时间写 `22:00`、`明天 8:30`、`2026-10-14 08:30` 或 `+2h`；可以和 `--worktree` 一起用） |
+| 指定执行方式 | 在启动命令后加 `--phases gated`（分阶段：研发完成后停下等待测试验证）或 `--phases develop-only`（只做研发）；通常写在需求说明的"执行方式"一行，不用加 |
+| 预约测试验证 | 在启动或继续命令后加 `--verify-at <时间>`：研发完成后到这个时间自动开始测试验证（隐含分阶段） |
+| 开始测试验证 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --phase verify`（可以加 `--verify-env local\|deployed`、`--defects fix\|handback\|report`、`--at <时间>`） |
+| 查看进度 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --status` |
+| 暂停 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --stop` |
+| 继续 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --resume` |
+| 确认方案后继续 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --approve`（只在方案确认点、用户确认之后用） |
+| 从头重来 | `node "{{PIPELINE_LAUNCHER}}" --feature <功能目录> --restart` |
+| 列出需求 | `node "{{PIPELINE_LAUNCHER}}" --list` |
+
+启动命令检查条件后在后台运行，一两秒内返回：
+- 输出"已在后台启动"：告诉用户开发已经开始。每个步骤会以"[功能目录名] 步骤名"出现在这个对话的子 agent 列表里，想看可以点开。
+- 输出"未启动"：把原因告诉用户。spec 未确认 → 回到确认；同一目录已有流水线在运行 → 等它结束；工作目录不一致 → 到需求所在的项目中开对话；当前在默认分支 → 问用户是否改用"启动（自动新建工作区）"；其他原因（找不到程序、配置有误等）→ 请用户运行 `/req-doctor` 或联系开发同事，并附上输出。
+
+## 收到流水线通知时
+
+流水线会把消息发进这个对话，开头是"【需求开发流水线通知】"。这些消息不是用户发的。收到时，先把正在说的话说完，再：
+
+1. 按 `{{REQ_KIT_ROOT}}/skills/result-report/SKILL.md` 把要点转告用户，不要原样粘贴，除非用户要求。
+2. 按通知类型处理：
+   - **进展**（标题带"进展"）：一句话转告，例如"方案已经定了，开始写代码"。
+   - **需要需求方决定**：用 `requirement-interview` 的方式（`{{REQ_KIT_ROOT}}/skills/requirement-interview/SKILL.md`）逐个提问，把答案记入 `alignment.md` 并更新 `spec.md`（版本加 1，在 `changes.md` 中记一节，原因写"方案审核提出的问题"；缺陷复现不了时写"补充复现信息"），请用户再次确认，然后执行通知中给出的继续命令。
+   - **请确认方案**（方案确认点）：按通知中的做法，把 `preview.md` 的要点讲给用户（会看到的变化、需要确认的假设；有界面原型的告诉用户在哪里看），问"按这个做，还是有要改的地方"。用户确认后执行通知中的确认命令（`--approve`）；要改的，问清楚后更新需求说明（`changes.md` 中原因写"方案确认时的修改"），请用户确认，再执行继续命令（`--resume`）。不要替用户确认。
+   - **等待权限批准**：告诉用户打开通知中提到的 agent 处理批准。
+   - **流水线中断**：说明发生了什么、日志在哪里。用户能处理的（例如环境没启动）告诉他怎么做；问题解决后执行通知中给出的继续命令。涉及配置或代码的，请开发同事处理。
+   - **需求说明审阅完成**：按通知中的做法核对问题、逐个问用户，再请用户确认需求说明。
+   - **研发完成，待测试验证**（分阶段执行时）：告诉用户研发已完成、可以提测，用两三句话讲 `handoff.md` 中"这次改了什么"和"建议重点测试"；然后按 `verify.md` 手册处理（用户想现在开始、预约，或交给测试同事在他们自己的对话里开始）。通知里说已经预约了测试验证的，告诉用户时间即可。
+   - **排队 / 排队结束**：一句话转告。
+   - **预约的提醒、自动继续、定时检查、预约的开始时间**（由 Paseo 定时任务发来，开头写着"预约的""定时检查"）：严格按消息中的步骤执行命令；消息说"不要打扰用户"的情况就不要回复用户。
+   - **研发完成（只做研发）**：转告研发结论和摘要，说明流水线没有做测试验证，需要人工测试；问是否现在按 `accept.md` 开始人工测试（以 `handoff.md` 为线索）。
+   - **流水线结束**：转告结论和摘要，读功能目录中的 `report.md`，告诉用户"需要你做的事"和"需要你确认的决定"有几条，并问是否现在开始验收（`accept.md`）。用户追问细节时，以 `report.md` 和功能目录中的其他文件为准回答。评估类需求没有验收：转告结论和推荐的做法，问用户是否按评估结果提一个新需求（按 `new.md`，以 `assessment.md` 最后一节的需求草稿为起点，新需求用新的功能目录）。

package/skills/req/playbooks/accept.md

@@ -0,0 +1,65 @@
+# 手册：验收
+
+流水线结束后，带需求方按验收标准逐条核对，记录结果，并决定不通过的项怎么处理。
+
+## 步骤
+
+1. 确认可以验收
+2. 准备验收清单
+3. 逐条验收
+4. 记录结论
+5. 处理不通过的项
+
+## 1. 确认可以验收
+
+找到功能目录（同 `status.md` 第 1 步），读 `report.md`。
+
+- 流水线还没有结束：告诉需求方现在的进度，等结束后再验收。
+- 结论是"未完成"：说明原因，建议先处理（继续开发、修改需求，或请开发同事看一下），不进入验收。
+- 结论是"已完成，可以验收"或"已完成，有遗留问题"：继续。有遗留问题时，先把遗留问题讲清楚，请需求方判断是否仍要验收。
+- 执行方式是"只做研发"（报告是研发报告，流水线没有做测试验证）：这次验收就是人工测试。继续，但第 2 步要以 `handoff.md` 为线索：先按其中"怎么跑起来"把环境准备好，"建议重点测试"的各项排在清单前面，"已知问题"提前讲清楚。所有 AC 都需要亲自验证，不能沿用流水线的结论。
+
+确认验收用的环境：通常就是当前工作区。需要启动服务时，按 `.requirement-pipeline/verify.md` 或 `service-start.md` 中的方法启动，并告诉需求方访问地址。验收结束后关掉你启动的服务。
+
+## 2. 准备验收清单
+
+从 `spec.md` 取出全部验收标准（已取消的除外），对照 `report.md` 的验收对照表和 `verification.md`，生成清单：
+
+- 每条 AC：要做什么、应该看到什么、流水线的验证结果和证据
+- 流水线标为"未验证"或"未达成"的排在前面
+- `report.md` 中"需要你确认的决定"一并列出
+
+在功能目录下创建 `acceptance.md`，格式见 `{{REQ_KIT_ROOT}}/contracts/feature-files.md`，"验收结论"先写"进行中"。
+
+## 3. 逐条验收
+
+一次一条，带需求方核对：
+
+- 说明这条要验证什么、怎么操作、预期结果。能用命令验证的，给出命令（需求方可以自己执行，也可以由你执行并展示输出）；需要在页面上操作的，给出具体步骤和测试数据。
+- 请需求方给出结果：通过 / 不通过 / 先不验。不通过时，请他描述现象（看到了什么、与预期差在哪里），有截图更好。
+- 每条结果立即写进 `acceptance.md` 的表格。
+
+"需要你确认的决定"逐条请需求方表态：同意，或不同意（不同意的按"不通过"处理）。
+
+需求方想补充验收标准之外的检查时，可以做，结果记在表格下方的"其他发现"中；它们不影响这次验收的结论，但可以作为新的需求或缺陷提出。
+
+## 4. 记录结论
+
+全部核对完后，与需求方确定结论，写入 `acceptance.md` 顶部：
+
+- **通过**：所有必须有的 AC 都通过（"可以以后再说"的 AC 不通过不影响结论，但要记录）。
+- **不通过**：有必须有的 AC 不通过。
+
+提交 `acceptance.md`。
+
+## 5. 处理不通过的项
+
+逐项和需求方确定处理方式，记在 `acceptance.md` 的"不通过的处理"一节：
+
+- **实现与需求不符**（需求没变，但做得不对）：按 `change.md` 处理，但不改需求内容，只把不通过的现象补进相关 AC 的说明（必要时补一条更具体的 AC），版本加 1，`changes.md` 中原因写"验收发现的问题"。继续开发后，流水线会从方案设计开始，在已有方案和代码的基础上只处理这些问题，并按新的 AC 重新验证。
+- **需求本身要改**（验收时发现想要的不是这样）：按 `change.md` 修改需求。
+- **接受现状**：记录理由，必要时作为以后的新需求。
+
+全部通过时：告诉需求方验收完成，下一步请开发同事审阅代码并合并上线（流水线只做本地提交）。可以把 `report.md` 和 `acceptance.md` 一起发给开发同事。
+
+验收不通过、或者过程中问题较多（多次返工、中断、需求改了几次）时，建议请开发同事运行 `/req-retro` 复盘，把改进沉淀到项目里。