paseo-req-kit 1.14.0-beta.2 → 1.14.0-beta.4

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.14.0-beta.4
+
+### 使用者会看到的变化
+
+- **代码审查**（插件需求页面上的"代码审查"，`req code-review <需求>`）：列出需求分支相对起点的全部改动（需求文档放最后、折叠），AI 代码评审的意见放在对应的代码行旁边，带级别和修复步骤的处理结果；评审人可以在任意一行写意见、把 AI 意见标为"要改 / 不用改"、写总体意见。
+- **审核人默认取自 `CODEOWNERS`**（支持 GitLab / GitHub 格式和 GitLab 的分节），按改动的文件给出，提交前可以修改，以后建合并请求时使用。
+- **退回修改**：意见写进 `code-review.md` 的"人工评审"一节（HR-1 起）和 `changes.md` 并提交，流水线开始新的一次尝试（`req review-fix`），需求说明不变、方案确认不用重来，从方案设计开始只处理这些意见，之后照常经过 AI 代码评审和验证。**评审通过**：记下评审人、审核人和评审的提交；之后又有新提交时提示需要重新评审。
+- AI 代码评审的结果文件新增 `findings`（每条意见的级别、文件、行号、问题、修复方向）；没有它的旧需求从 `code-review.md` 的 CR 条目中读取。
+
+### 升级须知
+
+- 合并请求还没有接入：等 shenbing 提供类似 `gh pr create / gh pr merge` 的命令后，用评审通过时记下的审核人建合并请求。
+- `req api status` 新增 `humanReview`；`req api review-url` 的 `--page` 新增 `code`；启动参数新增 `--review-fix`（`req review-fix <需求>`）。
+
+## 1.14.0-beta.3
+
+### 使用者会看到的变化
+
+- **验收清单**（`req checklist <需求>`，插件需求页面上的"验收清单（可一键试用）"）：按需求说明的验收标准生成清单，每条写着前置条件、操作、预期结果和流水线的验证结果，没验证或没通过的排在前面，报告里"需要你确认的决定"也列上。逐条点"通过 / 不对 / 先不验"，进度自动保存；提交后写成 `acceptance.md` 并提交，不通过时把不对的地方转给需求的对话。
+- **一键试用**（`req try <需求>`，验收清单页右上角"把它跑起来试用"）：用项目的 Paseo 服务脚本在需求自己的工作区里启动，给出访问地址和提测说明里的测试账号、数据；`--stop` 或"停止试用"停掉。没有服务脚本的项目给出提测说明里的启动方法。
+
+### 升级须知
+
+- `req api review-url` 新增 `--page check`；`req reply` 新增 `--acceptance`（验收页用）。验收页和原型审查页是同一个本机服务。
+
 ## 1.14.0-beta.2
 
 ### 使用者会看到的变化

package/bin/req.mjs

@@ -31,6 +31,10 @@ const HELP = `req-kit ${version}（${kitRoot}）
                                让 Paseo 按时间表发送需求总览（例子为每周一 9:00）；取消：req digest --cancel <ID>
   req sync <需求>              把需求同步到对接的外部系统（补发失败的调用、补建卡片、更新状态）
   req review <需求>            在浏览器打开原型审查页：点选要改的地方、直接改文字，提交意见或确认方案
+  req code-review <需求>       代码审查页：看这次的改动和 AI 评审意见，在代码行上写意见，退回修改或评审通过
+  req review-fix <需求>        按代码审查页上退回的意见开始修改（插件里提交"退回修改"时自动执行）
+  req try <需求> [--stop]      把做好的需求跑起来试用：给出访问地址和测试数据（--stop 停止）
+  req checklist <需求>         验收清单：按验收标准逐条勾选，提交后写成验收记录
   req ui-check <网址> [--prototype <原型文件>] [--width 1280,390]
                                不靠看图检查网页：显示不全、遮挡、超出屏幕、文字太淡、报错，和原型对文字
   req reply <需求> <回复>      把回答或方案意见转给需求的对话（插件的"等你处理"用它）
@@ -166,6 +170,12 @@ switch (command) {
   case "approve":
     code = node([launcher, "--approve", ...feature(rest, true)]);
     break;
+  case "review-fix":
+    code = node([launcher, "--review-fix", ...feature(rest, true)]);
+    break;
+  case "code-review":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "review.ts"), "--page", "code", ...rest]) : 1;
+    break;
   case "start":
     // From a card in the requirement management system (1.10): no chat needed to begin.
     if (rest.some((a) => a === "--from" || a.startsWith("--from="))) code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "card-cmd.ts"), "start", ...rest]) : 1;
@@ -221,6 +231,12 @@ switch (command) {
   case "review":
     code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "review.ts"), ...rest]) : 1;
     break;
+  case "try":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "try.ts"), ...rest]) : 1;
+    break;
+  case "checklist":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "checklist-cmd.ts"), ...rest]) : 1;
+    break;
   case "ui-check":
     code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "ui-check.ts"), ...rest]) : 1;
     break;

package/contracts/cli-json.md

@@ -32,7 +32,7 @@
 | `req api config [--repo <目录>] [--machine]` | 1.12 起。`{ sources, ignored, error, repo, groups }`：`sources` 是生效的配置文件（`layer` 为 `machine` / `team` / `project`，按叠加顺序）；`groups` 按主题分组，每项 `{ key, label, description, display, value, setBy, scope, changed }`：`display` 是用大白话写的值，`value` 中看起来像密钥的值和个人账号替换为 `••••`，`setBy` 是写了它的文件，`changed` 表示与默认值不同。配置有错误时 `error` 写明原因，值按各文件所写。`--machine` 不看项目配置 |
 | `req api set-agents --json <设置>` | 1.12 起。`{ ok, message }`。`<设置>` 是 `{ builder, reviewer, fallback }`（`fallback` 可以为 null），检查后写入本机配置的 `agents`，原文件备份 |
 | `req api watchdog [--by plugin\|factory] [--dry-run]` | 1.13 起。`{ checked, resumed, failed, skipped }`：把本机"运行中但后台进程已不在"的需求直接继续（`req resume`）。每个进程只继续一次，每个需求 24 小时内最多 3 次；`--by plugin` 同时记下插件在检查（流水线据此不再预约对话的定时检查） |
-| `req api review-url <需求> [--repo <目录>] [--read-only]` | 1.13 起。`{ url, readOnly }`：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。`--read-only` 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 `prototype/` 时报 `not_found` |
+| `req api review-url <需求> [--repo <目录>] [--read-only] [--page check]` | 1.13 起；`--page check`（1.14）给出同一服务上的验收清单页地址（需要 `spec.md`），`--page code`（1.14）给出代码审查页地址（需要已经写过代码）。`{ url, readOnly }`：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。`--read-only` 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 `prototype/` 时报 `not_found` |
 
 `<需求>` 的写法与 `req status` 相同：功能目录、目录名或名称中能唯一确定的一部分。需求在为它新建的工作区中开发时，`--repo` 写对话所在的目录或那个工作区都可以。
 

package/docs/guide//344/275/277/347/224/250/350/200/205/346/214/207/345/215/227.md

@@ -97,6 +97,21 @@ req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 P
 
 然后说"我要验收"。AI 会按验收标准一条一条带你核对：告诉你怎么操作、应该看到什么；能用命令验证的给出命令，你可以自己执行。每条结果记入功能目录的 `acceptance.md`。
 
+**代码审查（1.14 起，给开发同事和评审人）。** 需求页面上点**"代码审查"**（终端里是 `req code-review <需求>`），代码审查页在 Paseo 里打开：
+
+- 列出这次改动的全部文件（相对需求分支的起点，需求文档排在最后、默认折叠），上面是提测说明里"这次改了什么"。
+- AI 代码评审的每条意见放在它说的那一行旁边，标着级别（阻塞 / 重要 / 建议）和修复步骤的处理结果（已修复、判为不成立、决定不修复）；可以标**要改**或**不用改**，补一句话。
+- 点任意一行代码写意见；最下面可以写总体意见。
+- **审核人**默认取自仓库的 `CODEOWNERS`（按改动的文件），提交前可以改；以后建合并请求时会用它。
+- **退回修改**：意见写进 `code-review.md` 的"人工评审"一节（HR-1 起）和 `changes.md`，流水线随即开始新的一次尝试，需求说明不变，从方案设计开始只处理这些意见，改完再经过 AI 代码评审和验证，进展发回需求的对话。**评审通过**：记下评审人和审核人；之后代码又有改动时，页面会提示需要重新评审。
+
+**在插件里自己验收（1.14 起）。** 需求页面上点**"验收清单（可一键试用）"**（终端里是 `req checklist <需求>`），验收清单在 Paseo 里打开：
+
+- 每条验收标准写着前置条件、怎么操作、应该看到什么，以及流水线的验证结果；流水线没验证或没通过的排在最前面，报告里"需要你确认的决定"也列在后面请你表态。
+- 右上角**"把它跑起来试用"**（终端里是 `req try <需求>`）：用项目的 Paseo 服务脚本（`paseo.json`）在这个需求自己的工作区里把它启动起来，给出访问地址和提测说明里的测试账号、数据；用完点"停止试用"。项目没有服务脚本时，会给出提测说明里写的启动方法，也可以在需求的对话里说"帮我把它跑起来"。
+- 每条点"通过"、"不对"（写下看到了什么）或"先不验"，进度自动保存。必须验的都核对完才能提交"通过"；有"不对"的就提交"不通过"。
+- 提交后写成 `acceptance.md` 并提交。不通过时，不对的地方会转给这个需求的对话，它会和你一起确定怎么处理。
+
 - **全部通过**：请开发同事审阅代码并合并上线。流水线只做本地提交，不会自己合并或上线。
 - **有不通过的**：逐项决定怎么处理：做得不对的，补进需求说明后继续开发；发现想要的不是这样的，按改需求处理；也可以接受现状并记下理由。
 

package/engine/prompts/06-code-review.md

@@ -49,6 +49,10 @@
 6. **评审意见**：按级别排列
 7. **处理记录**：留空，由下一步填写
 
+## 人工评审意见
+
+`code-review.md` 中有"人工评审"一节、列出 HR-1、HR-2… 时，那是评审人在插件的代码审查页上提出的意见，这一次尝试就是为了处理它们。逐条核对是否已经解决：没有解决的按"重要"重新提出（在 CR 意见里注明对应的 HR 编号）；评审人的意见与 spec 冲突时，按 spec 判断，并写明冲突、记入 `decisions.tsv`（`needs_human` 写 `yes`）。
+
 ## 第 2 轮及以后
 
 上一轮的意见已经由修复步骤处理，处理记录在 `code-review.md` 中。这一轮：
@@ -60,11 +64,18 @@
 ## 结果文件
 
 ```json
-{ "verdict": "pass" }
+{
+  "verdict": "changes_required",
+  "findings": [
+    { "id": "CR-1", "severity": "阻塞", "file": "src/order/export.ts", "line": 42, "title": "导出没有校验权限，普通用户也能导出全部订单", "suggestion": "调用 checkPermission('order:export')" }
+  ]
+}
 ```
 
 - `verdict`，二选一：
   - `pass`：没有尚未解决的"阻塞"或"重要"级别意见。
   - `changes_required`：存在尚未解决的"阻塞"或"重要"级别意见，接下来会执行评审问题修复。
 
+- `findings`：这一轮提出的每条意见（和 `code-review.md` 中的 CR 编号一致），给 Paseo 插件的代码审查页使用：人在改动的代码旁边看到它们，决定要不要改。`severity` 写"阻塞"、"重要"、"建议"或"待核实"；`file` 是相对仓库根目录的路径，`line` 是改动后文件中的行号（不确定就省略）；`title` 一句话说清问题，`suggestion` 一句话说修复方向。没有意见时写空数组。
+
 代码改动不存在，或者无法确定评审范围时，选择 `changes_required` 并在结论里说明情况。

package/engine/prompts/incremental.md

@@ -20,3 +20,5 @@
 - **完成报告**：在开头说明这是第几次尝试、因为什么变化，验收对照表中标出哪些 AC 是这次新增或修改的。
 
 上一次没有写过代码时（`<pipeline-context>` 中"上一次是否已经写过代码：否"），实现类步骤按正常方式进行，只是方案设计要在已有的 `design.md` 基础上修订。
+
+**人工代码评审退回的**（`changes.md` 最后一节的来源是"人工代码评审"）：这次要处理的是 `code-review.md` 中最后一个"人工评审"小节里的 HR-1、HR-2…意见，需求说明没有变。方案只写针对这些意见的改法；实现逐条处理，并在 `implementation.md` 中逐条写明每个 HR 怎么改的（或为什么不改，记入 `decisions.tsv`，`needs_human` 写 `yes`）；不要借机做意见之外的改动。

package/engine/src/api.ts

@@ -27,6 +27,7 @@ import { defaultConfigPath, KIT_ROOT, kitVersion } from "./locations.js";
 import { configView } from "./config-view.js";
 import { pruneIndex, readIndex, registerRequirement, requirementKey } from "./records.js";
 import { listWorktreeRecords } from "./worktree.js";
+import { readHumanReview } from "./code-review.js";
 import { isAlive, type PipelineState, readState, statePath, type StepRecord } from "./state.js";
 import { parsePeriod, summarizeRuns } from "./stats.js";
 import { readRuns, runsFile } from "./records.js";
@@ -376,12 +377,21 @@ export function apiStatus(repoArg: string, feature: string) {
     steps: state ? state.history.map((h) => stepJson(h, state)) : [],
     // 1.13: what to expect, from this machine's completed requirements of the same profile.
     estimate: estimateOf(state),
+    // 1.14: the person's code review (plugin's code review page).
+    humanReview: humanReviewOf(repo, featureDir),
     gate: state?.gate ?? null,
     external: Object.entries(state?.external ?? {}).map(([name, r]) => ({ name, id: r.id, url: r.url, status: r.status, syncedAt: r.syncedAt, pending: r.pending.length, lastError: r.pending.at(-1)?.error ?? null })),
     joint: (state?.joint ?? []).map((j) => ({ name: j.name, slug: j.slug, repo: j.repo, sourceRepo: j.sourceRepo, branch: j.branch, workspaceId: j.workspaceId, gate: j.gate ?? null })),
   };
 }
 
+function humanReviewOf(repo: string, featureDir: string) {
+  const r = readHumanReview(path.join(repo, featureDir));
+  if (!r) return null;
+  const head = spawnSync("git", ["rev-parse", "HEAD"], { cwd: repo, encoding: "utf8", windowsHide: true }).stdout?.trim() || null;
+  return { status: r.status, reviewer: r.reviewer, at: r.at, reviewers: r.reviewers, items: r.items.length, stale: r.status === "approved" && !!head && r.head !== head, consumedAttempt: r.consumedAttempt };
+}
+
 function estimateOf(state: PipelineState | null) {
   if (!state || state.status === "completed") return null;
   const t = typical(state.profile ?? "standard");
@@ -579,12 +589,18 @@ export function apiMain(argvIn: string[], cwd = process.cwd()): unknown {
       // 1.13: the prototype review page of a requirement (starts the page's server when needed).
       const feature = need("需求");
       const readOnly = flag(argv, "--read-only");
+      // 1.14 --page check: the acceptance checklist page of the same server.
+      const pageArg = option(argv, "--page");
+      const page = pageArg === "check" ? "check" : pageArg === "code" ? "code" : "prototype";
       const { repo: r, featureDir } = locate(repo, feature);
       return import("./review.js").then(async ({ ensureReviewServer, keyOf, reviewUrl }) => {
         const key = keyOf(r, featureDir);
         if (!key) throw new ApiError("not_found", `${featureDir} 不在本机的需求列表中`);
-        if (!fs.existsSync(path.join(r, featureDir, "prototype"))) throw new ApiError("not_found", `${featureDir} 还没有界面原型`);
-        return { url: reviewUrl(await ensureReviewServer(), key, readOnly), readOnly };
+        if (page === "prototype" && !fs.existsSync(path.join(r, featureDir, "prototype"))) throw new ApiError("not_found", `${featureDir} 还没有界面原型`);
+        if (page === "check" && !fs.existsSync(path.join(r, featureDir, "spec.md"))) throw new ApiError("not_found", `${featureDir} 中没有 spec.md`);
+        if (page === "code" && !["implementation.md", "code-review.md"].some((f) => fs.existsSync(path.join(r, featureDir, f)))) throw new ApiError("not_found", `${featureDir} 还没有写代码，没有可以审查的改动`);
+        const url = reviewUrl(await ensureReviewServer(), key, readOnly);
+        return { url: page === "check" ? `${url}check/` : page === "code" ? `${url}code/` : url, readOnly };
       });
     }
     default:

package/engine/src/checklist-cmd.ts

@@ -0,0 +1,37 @@
+// `req checklist <需求> [--no-open]` (1.14): the acceptance checklist in words, and the page where
+// the requester ticks it (served by the review page's server).
+import fs from "node:fs";
+import path from "node:path";
+import { buildChecklist, checklistText } from "./checklist.js";
+
+async function main(argv: string[]): Promise<number> {
+  const feature = argv.find((a) => !a.startsWith("--"));
+  if (!feature || argv.includes("--help") || argv.includes("-h")) {
+    console.log("用法：req checklist <需求> [--no-open] [--text]\n\n按需求说明的验收标准生成验收清单（流水线没验证、没通过的排在前面），在浏览器里逐条勾选，提交后写成 acceptance.md。--text 只在终端里列出清单。");
+    return feature ? 0 : 2;
+  }
+  const { locate } = await import("./api.js");
+  const { repo, featureDir } = locate(process.cwd(), feature);
+  if (!fs.existsSync(path.join(repo, featureDir, "spec.md"))) {
+    console.error(`${featureDir} 中没有 spec.md`);
+    return 1;
+  }
+  const list = buildChecklist(path.join(repo, featureDir));
+  let url: string | null = null;
+  if (!argv.includes("--text")) {
+    const { ensureReviewServer, keyOf, reviewUrl } = await import("./review.js");
+    const key = keyOf(repo, featureDir);
+    if (key) url = `${reviewUrl(await ensureReviewServer(), key)}check/`;
+  }
+  console.log(checklistText(list, url));
+  if (url && !argv.includes("--no-open")) (await import("./review.js")).openBrowser(url);
+  return 0;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(error.message);
+    process.exit(1);
+  },
+);

package/engine/src/checklist.ts

@@ -0,0 +1,254 @@
+// The acceptance checklist (1.14): what the requester checks by hand, built from the spec's
+// acceptance criteria, with what the pipeline found for each one. People tick each item on a
+// page (or read it with `req checklist`); the result is written as acceptance.md, the same record
+// the /req acceptance playbook writes. Plain parsing, no model.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export type PipelineResult = "pass" | "fail" | "unverified" | "unknown";
+
+export interface ChecklistItem {
+  /** AC-2.1, or D-1 for a decision the report asks the requester to confirm. */
+  id: string;
+  kind: "criterion" | "decision";
+  title: string;
+  /** 前置条件 / 操作 / 预期结果 and any example rows, as written in the spec. */
+  details: string[];
+  /** False for criteria of a "可以以后再说" requirement: they do not decide the verdict. */
+  required: boolean;
+  pipeline: PipelineResult;
+  /** The line of verification.md / report.md the pipeline result was read from. */
+  evidence: string | null;
+}
+
+export interface Checklist {
+  title: string;
+  specVersion: string | null;
+  reportVerdict: string | null;
+  items: ChecklistItem[];
+  /** handoff.md: what to watch for (已知问题) and where test data comes from, for the page. */
+  notes: string[];
+}
+
+const clean = (s: string) => s.replace(/\*\*|__|`/g, "").replace(/\s+/g, " ").trim();
+
+function read(file: string): string {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function header(text: string, name: string): string | null {
+  const m = new RegExp(`^[-*]\\s*${name}[:：]\\s*(.+)$`, "m").exec(text);
+  return m ? m[1].trim() : null;
+}
+
+/** The lines under the first heading whose text matches `title` (until the next heading of the same or higher level). */
+export function section(text: string, title: RegExp): string[] {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && title.test(l));
+  if (start < 0) return [];
+  const level = /^(#+)/.exec(lines[start])![1].length;
+  const out: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    const h = /^(#+)\s/.exec(line);
+    if (h && h[1].length <= level) break;
+    out.push(line);
+  }
+  return out;
+}
+
+/** The criteria of a spec, with their details and whether their requirement is a must. */
+export function parseCriteria(spec: string): Array<Omit<ChecklistItem, "pipeline" | "evidence">> {
+  const items: Array<Omit<ChecklistItem, "pipeline" | "evidence">> = [];
+  let required = true;
+  let current: (typeof items)[number] | null = null;
+  for (const raw of spec.split(/\r?\n/)) {
+    const heading = /^#{1,6}\s+(.*)$/.exec(raw);
+    if (heading) {
+      current = null;
+      if (/FR-\d+/.test(heading[1])) required = !/可以以后再说|可选|以后再说/.test(heading[1]);
+      continue;
+    }
+    const ac = /^\s{0,3}[-*]\s+(.*?\bAC-(\d+(?:\.\d+)*)\b.*)$/.exec(raw);
+    if (ac) {
+      const line = ac[1];
+      if (/~~/.test(line) || /已取消/.test(line)) {
+        current = null;
+        continue;
+      }
+      const id = `AC-${ac[2]}`;
+      if (items.some((i) => i.id === id)) {
+        current = null;
+        continue;
+      }
+      const title = clean(line.replace(new RegExp(`.*?\\bAC-${ac[2].replace(/\./g, "\\.")}\\b[\\s*_\`)）\\]】:：-]*`), ""));
+      current = { id, kind: "criterion", title: title || id, details: [], required };
+      items.push(current);
+      continue;
+    }
+    if (!current) continue;
+    if (/^\s*$/.test(raw)) continue;
+    // Its details: indented bullets, or a table under it.
+    if (/^\s{2,}\S/.test(raw) || /^\s*\|/.test(raw)) {
+      const t = raw.trim();
+      if (/^\|?\s*-{3,}/.test(t)) continue;
+      current.details.push(clean(t.replace(/^[-*]\s+/, "")));
+    } else current = null;
+  }
+  return items;
+}
+
+/** A table row as words: "| AC-1.2 | 未验证 | 没有空数据 |" → "AC-1.2，未验证，没有空数据". */
+const evidenceOf = (line: string) =>
+  clean(line.trim().replace(/^\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim()).filter(Boolean).join("，")).slice(0, 300);
+
+/** What the pipeline wrote about one criterion, from verification.md (preferred) and report.md. */
+export function pipelineResult(id: string, ...documents: string[]): { result: PipelineResult; evidence: string | null } {
+  const re = new RegExp(`\\b${id.replace(/\./g, "\\.")}\\b(?![.\\d])`);
+  for (const doc of documents) {
+    const lines = doc.split(/\r?\n/).filter((l) => re.test(l));
+    // The last mention wins: a later round (复验) supersedes an earlier one.
+    for (const line of lines.reverse()) {
+      if (/未验证|没有验证|无法验证|未验/.test(line)) return { result: "unverified", evidence: evidenceOf(line) };
+      if (/未通过|不通过|失败|未达成|没有达成|✗|❌/.test(line)) return { result: "fail", evidence: evidenceOf(line) };
+      if (/通过|达成|✓|✅|pass/i.test(line)) return { result: "pass", evidence: evidenceOf(line) };
+    }
+  }
+  return { result: "unknown", evidence: null };
+}
+
+/** The decisions the report asks the requester to confirm ("需要你确认的决定"). */
+function decisions(report: string): ChecklistItem[] {
+  return section(report, /需要你确认/)
+    .map((l) => /^\s*(?:[-*]|\d+[.、)])\s+(.+)$/.exec(l)?.[1])
+    .filter((x): x is string => !!x && clean(x).length > 0 && !/^(无|没有)/.test(clean(x)))
+    .map((text, i) => ({ id: `D-${i + 1}`, kind: "decision" as const, title: clean(text).slice(0, 300), details: [], required: true, pipeline: "unknown" as const, evidence: null }));
+}
+
+const ORDER: Record<PipelineResult, number> = { fail: 0, unverified: 1, unknown: 2, pass: 3 };
+
+export function buildChecklist(featureAbs: string): Checklist {
+  const spec = read(path.join(featureAbs, "spec.md"));
+  const report = read(path.join(featureAbs, "report.md"));
+  const verification = read(path.join(featureAbs, "verification.md"));
+  const handoff = read(path.join(featureAbs, "handoff.md"));
+  const criteria = parseCriteria(spec).map((c) => {
+    const { result, evidence } = pipelineResult(c.id, verification, report);
+    return { ...c, pipeline: result, evidence };
+  });
+  // What the pipeline did not verify, or found wrong, first: that is where a person's eyes help most.
+  criteria.sort((a, b) => ORDER[a.pipeline] - ORDER[b.pipeline]);
+  const notes = [...section(handoff, /已知问题|未完成/), ...section(handoff, /测试需要的准备|测试数据|准备/)]
+    .map((l) => clean(l.replace(/^\s*[-*]\s+/, "")))
+    .filter((l) => l && !/^(无|没有)[。.]?$/.test(l))
+    .slice(0, 20);
+  return {
+    title: (/^#\s+(.+)$/m.exec(spec)?.[1] ?? path.basename(featureAbs)).replace(/^需求说明[:：\s]*/, "").trim(),
+    specVersion: header(spec, "版本"),
+    reportVerdict: header(report, "结论") ?? (/结论[:：]\s*(.+)/.exec(report)?.[1]?.trim() ?? null),
+    items: [...criteria, ...decisions(report)],
+    notes,
+  };
+}
+
+export type Mark = "pass" | "fail" | "skip";
+
+export interface Answer {
+  id: string;
+  mark: Mark;
+  note?: string;
+}
+
+export interface Verdict {
+  verdict: "通过" | "不通过";
+  failed: ChecklistItem[];
+  /** Required items not checked yet: the verdict cannot be "通过" while there are any. */
+  missing: ChecklistItem[];
+}
+
+export function verdictOf(list: Checklist, answers: Answer[]): Verdict {
+  const by = new Map(answers.map((a) => [a.id, a]));
+  const failed = list.items.filter((i) => by.get(i.id)?.mark === "fail" && i.required);
+  const missing = list.items.filter((i) => i.required && (!by.get(i.id) || by.get(i.id)!.mark === "skip"));
+  return { verdict: failed.length > 0 ? "不通过" : "通过", failed, missing };
+}
+
+const MARK_TEXT: Record<Mark, string> = { pass: "通过", fail: "不通过", skip: "未验" };
+
+/** acceptance.md in the format of contracts/feature-files.md. Keeps a "不通过的处理" section already there. */
+export function acceptanceText(list: Checklist, answers: Answer[], input: { verdict: "通过" | "不通过"; reviewer: string; date: string; previous?: string }): string {
+  const by = new Map(answers.map((a) => [a.id, a]));
+  const cell = (s: string) => s.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+  const rows = list.items.map((i) => {
+    const a = by.get(i.id);
+    const mark = a ? MARK_TEXT[a.mark] : "未验";
+    const how = i.kind === "decision" ? "需求方表态（同意 / 不同意）" : "在验收页上亲自核对";
+    const note = [i.kind === "decision" ? i.title : null, a?.note?.trim() || null, !i.required ? "可以以后再说，不影响结论" : null].filter(Boolean).join("；");
+    return `| ${i.id} | ${i.kind === "decision" ? (a?.mark === "pass" ? "同意" : a?.mark === "fail" ? "不同意" : "未表态") : mark} | ${how} | ${cell(note)} |`;
+  });
+  const kept = input.previous ? section(input.previous, /不通过的处理/).join("\n").trim() : "";
+  const failed = list.items.filter((i) => by.get(i.id)?.mark === "fail");
+  const handling = kept || failed.map((i) => `- ${i.id}：${cell(by.get(i.id)?.note?.trim() || i.title)} → 待和需求方确定处理方式（作为缺陷处理 / 作为需求修改 / 接受现状）`).join("\n");
+  return [
+    `# 验收记录：${list.title}`,
+    "",
+    `- 验收结论：${input.verdict}（${input.date}）`,
+    `- 验收人：${input.reviewer}`,
+    `- 对照的需求版本：${list.specVersion ?? "未写明"}`,
+    `- 对照的报告：report.md${list.reportVerdict ? `（流水线结论：${list.reportVerdict}）` : ""}`,
+    "",
+    "| AC | 结果 | 怎么验证的 | 备注 |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+    ...(handling ? ["", "## 不通过的处理", "", handling] : []),
+    "",
+  ].join("\n");
+}
+
+/** Writes acceptance.md and commits it alone (when the feature directory is in a git repository). */
+export function recordAcceptance(repo: string, featureDir: string, text: string): { committed: boolean } {
+  const file = path.join(repo, featureDir, "acceptance.md");
+  fs.writeFileSync(file, text);
+  try {
+    const rel = path.join(featureDir, "acceptance.md");
+    execFileSync("git", ["add", "--", rel], { cwd: repo, stdio: "pipe" });
+    const staged = execFileSync("git", ["diff", "--cached", "--name-only", "--", rel], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    if (!staged) return { committed: false };
+    execFileSync("git", ["commit", "-q", "-m", `docs(${path.basename(featureDir)}): 验收记录`, "--", rel], { cwd: repo, stdio: "pipe" });
+    return { committed: true };
+  } catch {
+    return { committed: false };
+  }
+}
+
+/** What the requirement's chat is told when the requester found problems. */
+export function acceptanceFailMessage(featureDir: string, list: Checklist, answers: Answer[]): string {
+  const by = new Map(answers.map((a) => [a.id, a]));
+  const failed = list.items.filter((i) => by.get(i.id)?.mark === "fail");
+  return [
+    `【需求开发流水线通知】需求方在验收页上完成了验收（${featureDir}），结论：不通过。验收记录已写入 acceptance.md 并提交。`,
+    "",
+    "不通过的项：",
+    ...failed.map((i) => `- ${i.id} ${i.title}${by.get(i.id)?.note?.trim() ? `：${by.get(i.id)!.note!.trim()}` : ""}`),
+    "",
+    `请按 /req 的"验收"手册第 5 步，和需求方逐项确定处理方式（实现与需求不符 / 需求本身要改 / 接受现状），记入 acceptance.md 的"不通过的处理"一节，再按对应的手册继续。`,
+  ].join("\n");
+}
+
+/** `req checklist` in a terminal: the list in words. */
+export function checklistText(list: Checklist, url: string | null): string {
+  const mark: Record<PipelineResult, string> = { pass: "流水线：通过", fail: "流水线：没通过", unverified: "流水线：没验证", unknown: "流水线：没有记录" };
+  const lines = [`# 验收清单：${list.title}`, ""];
+  if (list.reportVerdict) lines.push(`流水线结论：${list.reportVerdict}`, "");
+  list.items.forEach((i, n) => {
+    lines.push(`${n + 1}. ${i.id} ${i.title}${i.required ? "" : "（可以以后再说）"}${i.kind === "criterion" ? `　[${mark[i.pipeline]}]` : "　[请表态：同意 / 不同意]"}`);
+    for (const d of i.details) lines.push(`   ${d}`);
+  });
+  if (list.notes.length) lines.push("", "注意（提测说明）：", ...list.notes.map((n) => `- ${n}`));
+  if (url) lines.push("", `在验收页上逐条勾选、写下哪里不对：${url}`);
+  return lines.join("\n");
+}

package/engine/src/cli-args.ts

@@ -56,6 +56,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
       list: { type: "boolean", default: false },
       "card-fields": { type: "boolean", default: false },
       track: { type: "boolean", default: false },
+      "review-fix": { type: "boolean", default: false },
       "spec-review": { type: "boolean", default: false },
       worktree: { type: "boolean", default: false },
       "source-repo": { type: "string" },
@@ -118,7 +119,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
     repo: path.resolve(values.repo ?? process.env.PASEO_AGENT_CWD ?? process.cwd()),
     featureDir: values.feature ?? "",
     originAgentId: origin ? origin : null,
-    resume: (values.resume ?? false) || phase === "verify" || (values.approve ?? false),
+    resume: (values.resume ?? false) || phase === "verify" || (values.approve ?? false) || (values["review-fix"] ?? false),
     restart: values.restart ?? false,
     configPath: values.config ? path.resolve(values.config) : null,
     profile: (profile as ProfileName | undefined) ?? null,
@@ -127,6 +128,7 @@ export function parseLaunchArgs(argv: string[]): LaunchArgs {
     list: values.list ?? false,
     cardFields: values["card-fields"] ?? false,
     track: values.track ?? false,
+    reviewFix: values["review-fix"] ?? false,
     specReview: values["spec-review"] ?? false,
     worktree: values.worktree ?? false,
     sourceRepo: values["source-repo"] ? path.resolve(values["source-repo"]) : null,
@@ -210,6 +212,7 @@ export function launchArgv(args: LaunchArgs): string[] {
   if (args.profile) out.push("--profile", args.profile);
   if (args.resume) out.push("--resume");
   if (args.restart) out.push("--restart");
+  if (args.reviewFix) out.push("--review-fix");
   if (args.sourceRepo) out.push("--source-repo", args.sourceRepo);
   if (args.workspaceId) out.push("--workspace-id", args.workspaceId);
   if (args.specReview) out.push("--spec-review");