@autobest-ui/agent 1.0.6 → 1.0.8

package/plugins/autobest-delivery/skills/e2e-gen-spec/SKILL.md

@@ -14,10 +14,14 @@ description: 在首版实现可运行后，为 Autobest Delivery 运行器编写
 - 可运行的首版实现。
 - 仅在修订回合读取 `test_defect` 人工决议及其指向的 Blocked runner/checker 证据。
 
+存在 `featureDir/spec-traceability.json` 时必须读取并校验；它定义本场景允许使用的完整 active REQ ID 集合。
+
 产品预期只由 spec 决定。按契约解析具体执行事实。存在通配路由，或者 spec 未直接写出命令、视口或定位器，并不自动构成阻断。
 
 ## 流程
 
+追踪模式下，每项运行检查和视觉映射都写入所属 `requirementId`，不得创建或重编号。`metadata` 必须声明 `traceabilitySchemaVersion: 1` 和完整、唯一的 `requirementIds`；冻结前确认每个 active ID 至少有一项运行或视觉覆盖。
+
 1. 将每条原子 spec 预期准确映射到一个运行检查或一个视觉映射。为每项分配通用的 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，让同一 UI 组件、页面位置或完整用户操作流的文案、样式、布局、响应式行为和相关功能检查在报告中合并；同组的模块、标题和检查方式必须完全一致。不同组件、独立业务能力、状态转换或风险边界保持不同组。分组只表达当前 spec 的功能语义，不得按 scene 或执行顺序分组，不得写死特定页面族词汇或依赖导出器猜测业务语义。覆盖所有必需页面变体、状态转换、空态或错误态、导航结果和响应式变体。
 2. 解析并探测具体 URL、启动行为、受控 API 数据、持久化状态和面向用户的稳定定位器。通过解码后的状态或受控 fixture 确认通配路由变体。
 3. 首次编写只写入 `featureDir/e2e/e2e.feature.mjs`，保持旧 `.spec.ts` 不变。该文件不得包含 import，只导出 `metadata` 和一个默认异步函数，并且只能使用运行器注入的 `scene`、`page`、`expect`、`check`、`route`、`capture`、`artifact`、`baseUrl` 和 `parseUrl`。新建或修订场景在 metadata 中声明 `reportSchemaVersion: 1`，使运行器校验所有检查和视觉映射的通用报告分组字段。每个 `metadata.scenes` 项通过 `scene(id, callback)` 恰好执行一次；每个 scene 自包含页面导航、API fixture 和必要状态。冻结后只有用户通过 `resolve_blocked_run` 明确选择 `test_defect` 才能修订；修订结果必须记录旧、新 SHA-256 和决议证据路径。

package/plugins/autobest-delivery/skills/e2e-ui-checker/SKILL.md

@@ -16,6 +16,8 @@ description: 使用 Autobest Delivery MCP 运行器在可见浏览器中独立
 
 ## 流程
 
+存在 `spec-traceability.json` 时，先确认冻结场景声明的 REQ ID 与 active 集合完全一致。合并 Runner 和视觉结果时原样保留每项 `requirementId`，逐个汇总 passed、failed 或 blocked；未知编号、缺失编号或 active 需求无证据都属于证据链阻断，不能判为通过。
+
 1. 建立原子 spec 检查清单，确认冻结运行检查和 metadata 视觉映射完整且不重复地划分了全部检查项。`reportSchemaVersion: 1` 的场景须核对每个运行检查包含 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，同组字段一致且表达真实组件或完整功能，而不是 E2E scene；同时核对视觉映射的同组字段和 `reportDevice` 正确区分桌面端与移动端。历史场景没有报告 schema 时不据此阻断。
 2. 调用 `autobest-delivery` MCP 的 `check_environment` 工具并传入 `headed: true`。环境未就绪时，以返回的版本和错误证据形成 `tool` 阻断；不得降级使用通用 Playwright MCP 或目标仓库依赖。
 3. 只解析并启动仓库已声明且本次必需的开发服务，记录其 PID，并确认基础 URL。复用冻结的 `1400px` 和 `375px` 视口及受控路由或 API 状态。

package/plugins/autobest-delivery/skills/export-report/SKILL.md

@@ -14,6 +14,8 @@ description: 从已完成或已阻断的 Autobest Delivery Maker、Runner 和 Ch
 
 ## 执行
 
+追踪模式下，底层检查、视觉映射和 `report/report-groups.json` 必须保留真实 `requirementIds` 供审计；Excel 可见列仍按产品功能展示，不新增编号列。
+
 1. 将功能目录和可选输出路径解析为绝对路径，并使用 `git rev-parse --show-toplevel` 取得工作区。
 2. 从当前 Skill 路径定位插件根目录，不依赖业务仓库中的 `plugins/` 路径。
 3. 执行：
@@ -51,6 +53,7 @@ node <plugin-root>/scripts/export-delivery-report.mjs <feature-dir> \
       "module": "页面或模块",
       "title": "组件或完整功能名称",
       "method": "合并描述该功能的文案、视觉、布局、响应式和行为检查方式。",
+      "requirementIds": ["REQ-PD-001"],
       "storyIds": ["story-01", "story-02"],
       "desktopCapture": "可选的桌面截图文件名或证据路径",
       "mobileCapture": "可选的移动端截图文件名或证据路径"

package/skills/README.md

@@ -12,9 +12,14 @@ npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync common
 
 当前包含：
 
+- `code-pr-submit`
 - `figma-ui-capture`
+- `make-spec`
+- `review-from-docs`
 - `ui-prd-scope`
 
+其中 `ui-prd-scope` 使用 `REQ-<页面或Scope简称>-<三位序号>` 分配稳定需求 ID；`review-from-docs` 为每个 REQ 建立决策树，逐轮询问当前完整 frontier 并记录用户确认的结论；`make-spec` 只从已完成的 review 生成逐项可验收的 `spec.md` 和机器可校验的映射。后续交付角色只引用编号，不重新编号。
+
 ## React
 
 React Skills 只应用于单个项目。进入项目根目录后运行：

package/skills/common/code-pr-submit/SKILL.md

@@ -40,7 +40,7 @@ to   = 当前分支的父分支（创建该分支时所基于的分支）
 | `fromBranch` | 当前 Git 分支 |
 | `toBranch` | 分支创建 reflog、本地 merge-base 或 MCP 启发结果 |
 | `prTitle` | 用户输入；否则使用当前分支最新的非合并 commit 标题，并结合分支名清理 |
-| `prDescription` | 用户输入；否则根据远端 diff 和当前分支的 `spec.md` 自动生成 |
+| `prDescription` | 用户输入；否则根据远端 diff、`spec.md`、`spec-traceability.json` 和已有 Checker 证据自动生成 |
 | `reviewers` | 仅使用用户明确提供的评审人 ID；缺失时省略 |
 
 ## 自动发现项目
@@ -99,7 +99,7 @@ sourceBranch: ${fromBranch}
 targetBranch: ${toBranch}
 ```
 
-随后调用 `code-mcp-pr.read_file_at_ref` 读取当前分支根目录的 `spec.md`：
+随后调用 `code-mcp-pr.read_file_at_ref` 读取当前分支中的 `spec.md`。能够从用户输入、diff 或 spec 定位功能目录时，也读取同目录的 `spec-traceability.json` 和最新 `checker/checker-result.json`：
 
 ```yaml
 orgName: ${orgName}
@@ -109,7 +109,7 @@ refName: ${fromBranch}
 filePath: spec.md
 ```
 
-文件不存在时继续。其他读取错误保留错误事实，但只要 diff 可用就继续生成描述。diff 失败时报告 MCP 的 `errorMsg`，不要基于猜测创建 PR。
+文件不存在时继续。其他读取错误保留错误事实，但只要 diff 可用就继续生成描述。diff 失败时报告 MCP 的 `errorMsg`，不要基于猜测创建 PR。不得为了寻找产物扫描或猜测无关目录。
 
 用户未给标题时，先读取：
 
@@ -127,9 +127,12 @@ git log --no-merges -1 --format=%s -- "${fromBranch}"
 
 ## 变更详情
 - `path/to/file`：说明可由材料证明的改动。
+
+## 需求追踪
+- `REQ-PD-001`：已实现；Checker 通过 / 失败 / 阻断 / 缺少验收证据
 ```
 
-只总结可见材料，不粘贴大段 diff，不补造功能。用户提供标题或描述时保留其原意，不擅自替换。
+存在 `spec-traceability.json` 时按真实 REQ ID 列出本 PR 涉及的 active 需求。只有 Checker 结果明确覆盖且通过时才能写“Checker 通过”；没有对应证据时写“缺少验收证据”，不得从代码、Maker 结果或整体 Checker 状态推断单项通过。不存在追踪产物时省略“需求追踪”，不临时发明编号。只总结可见材料，不粘贴大段 diff，不补造功能。用户提供标题或描述时保留其原意，不擅自替换。
 
 ## 创建授权
 

package/skills/common/make-spec/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: make-spec
+description: 根据带稳定 REQ 编号的页面 scope 和 review-result 生成可追踪的 spec.md 与 spec-traceability.json。用户要求从已质询范围生成或刷新功能规格时使用；不质询未决业务问题、不实现代码或执行验收。
+---
+
+# 生成可追踪功能规格
+
+把已确认的页面需求转换为 Delivery Plugin 可执行的规格。开始前完整读取 [需求追踪契约](../ui-prd-scope/references/requirement-traceability.md) 和 [Spec Schema](references/spec-schema.md)。
+
+## 输入
+
+- 页面目录中的 `scope.md` 和范围包根目录的 `scope-manifest.json`。
+- `review/review-result.json`，以及它引用的 Figma 和证据。
+- 可选的既有 `spec.md` 与 `spec-traceability.json`；刷新时保留稳定编号和仍适用的验收边界。
+
+Manifest 必须声明 `traceabilitySchemaVersion: 1`，Review 必须使用 Schema v2、`sessionStatus: complete` 且已经由用户确认。任何 `active` 需求缺少质询记录、仍为 `unresolved`，或 scope、review 的编号和状态不一致时停止，返回需要继续 `$review-from-docs` 或回写 scope 的具体编号。
+
+## 生成
+
+1. 按 manifest 顺序建立需求覆盖台账。`active` 需求进入规格正文；`deferred` 和 `removed` 进入排除清单并保留原因。
+2. 对每个 active `REQ-ID` 合并原始陈述与已确认决策，写出可观察、可判定的验收条件。不得根据相似需求补造业务规则；执行命令、路由、fixture 和定位器等仓库事实可放在执行上下文，不冒充产品预期。
+3. 将适用的 Figma 资产映射到对应 `REQ-ID`、设备、变体和语义节点。功能文字、数据内容和业务图片主体由功能验收条件描述，视觉基准只约束结构与样式。
+4. 按 Schema 写入 `spec.md` 和 `spec-traceability.json`。计算并记录 `scope.md`、`review-result.json`、`spec.md` 的 SHA-256；每个 active 编号在 `spec.md` 中有且仅有一个需求章节，在追踪 JSON 中有且仅有一个需求条目。
+5. 执行：
+
+```bash
+node .agents/skills/make-spec/scripts/validate-spec-traceability.mjs <页面 scope 目录>
+```
+
+根据实际安装位置调整脚本路径。校验失败时修正规格产物，不放宽需求覆盖。
+
+## 完成条件
+
+- 每个 active 需求有非空规格章节、至少一条验收条件，以及 `runtime`、`visual` 或 `manual` 验证方式。
+- 每个视觉预期都引用存在的本地基准；没有视觉要求的需求明确使用功能验证，不制造截图要求。
+- 追踪文件的输入哈希与当前文件一致，active、deferred、removed 集合与 manifest 一致。
+- 最终答复给出 Spec 路径、active 覆盖数量、排除数量和校验结果；不修改 scope、review、业务代码或交付证据。

package/skills/common/make-spec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "生成需求规格"
+  short_description: "根据 scope 和质询结论生成可追踪的功能 spec"
+  default_prompt: "使用 $make-spec 根据当前 scope 和 review-result 生成带需求编号的 spec.md。"

package/skills/common/make-spec/references/spec-schema.md

@@ -0,0 +1,82 @@
+# 可追踪 Spec Schema
+
+## spec.md
+
+```markdown
+# <页面族> 功能规格
+
+## 输入与版本
+
+- Scope: `scope.md`
+- Review: `review/review-result.json`
+- Azure PR: <URL>
+
+## 需求覆盖
+
+| 需求 ID | 规格章节 | 验证方式 | 状态 |
+| --- | --- | --- | --- |
+| `REQ-PD-001` | 商品主图 | `runtime`、`visual` | `specified` |
+
+## REQ-PD-001 商品主图
+
+### 需求与质询结论
+
+<保留原始要求及已确认决策。>
+
+### 验收条件
+
+- <可观察、可判定的结果。>
+
+### 视觉映射
+
+| 设备 | 状态/变体 | 基准 | 语义节点 |
+| --- | --- | --- | --- |
+
+## 排除需求
+
+| 需求 ID | 状态 | 原因 |
+| --- | --- | --- |
+```
+
+每个 active ID 使用一个二级标题；同一需求需要多项检查时保持在同一章节。需求覆盖表不得使用没有对应章节的编号。
+
+## spec-traceability.json
+
+```json
+{
+  "schemaVersion": 1,
+  "scope": {
+    "manifestPath": "../scope-manifest.json",
+    "directory": "01-product-detail",
+    "scopePath": "scope.md",
+    "scopeSha256": "64位小写十六进制"
+  },
+  "review": {
+    "path": "review/review-result.json",
+    "sha256": "64位小写十六进制"
+  },
+  "spec": {
+    "path": "spec.md",
+    "sha256": "64位小写十六进制"
+  },
+  "requirements": [
+    {
+      "id": "REQ-PD-001",
+      "status": "specified",
+      "heading": "REQ-PD-001 商品主图",
+      "acceptanceCriteria": ["商品主图容器保持 4:3 比例"],
+      "verification": ["runtime", "visual"],
+      "figmaRefs": ["mobile-default.png#12:34"]
+    }
+  ],
+  "excludedRequirements": [
+    {
+      "id": "REQ-PD-003",
+      "status": "deferred",
+      "reason": "本迭代不实现"
+    }
+  ]
+}
+```
+
+`verification` 只使用 `runtime`、`visual`、`manual`。`manual` 仅用于自动化无法可靠观察的预期，并在验收时形成明确人工证据，不能用于规避可自动化检查。

package/skills/common/make-spec/scripts/validate-spec-traceability.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const featureDir = path.resolve(process.argv[2] || '.');
+const errors = [];
+const requirementPattern = /^REQ-[A-Z][A-Z0-9]{1,15}-\d{3}$/;
+const hashPattern = /^[a-f0-9]{64}$/;
+const allowedVerification = new Set(['runtime', 'visual', 'manual']);
+const fail = message => errors.push(message);
+
+function readJson(filePath, label) {
+  if (!fs.existsSync(filePath)) {
+    fail(`缺少 ${label}：${filePath}`);
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    fail(`${label} JSON 无效：${error.message}`);
+    return null;
+  }
+}
+
+function sha256(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function resolveInput(relativePath, label) {
+  if (typeof relativePath !== 'string' || !relativePath.trim()) {
+    fail(`${label} 路径必须是非空字符串`);
+    return null;
+  }
+  const resolved = path.resolve(featureDir, relativePath);
+  const relative = path.relative(featureDir, resolved);
+  if (relative.startsWith('..') && label !== 'Manifest') {
+    fail(`${label} 路径必须位于页面 scope 目录内`);
+  }
+  if (!fs.existsSync(resolved)) fail(`${label} 不存在：${relativePath}`);
+  return resolved;
+}
+
+const tracePath = path.join(featureDir, 'spec-traceability.json');
+const trace = readJson(tracePath, 'spec-traceability.json');
+
+if (trace) {
+  if (trace.schemaVersion !== 1) fail('spec-traceability.schemaVersion 必须为 1');
+  const manifestPath = resolveInput(trace.scope?.manifestPath, 'Manifest');
+  const scopePath = resolveInput(trace.scope?.scopePath, 'Scope');
+  const reviewPath = resolveInput(trace.review?.path, 'Review');
+  const specPath = resolveInput(trace.spec?.path, 'Spec');
+  const manifest = manifestPath ? readJson(manifestPath, 'scope-manifest.json') : null;
+  const review = reviewPath ? readJson(reviewPath, 'review-result.json') : null;
+  if (manifest && manifest.traceabilitySchemaVersion !== 1) {
+    fail('Manifest 未启用 traceabilitySchemaVersion: 1');
+  }
+  if (review && review.schemaVersion !== 2) fail('Review schemaVersion 必须为 2');
+  if (review && (review.sessionStatus !== 'complete' || review.userConfirmed !== true)) {
+    fail('Review 必须完成多轮质询并由用户确认');
+  }
+
+  for (const [label, filePath, expected] of [
+    ['Scope', scopePath, trace.scope?.scopeSha256],
+    ['Review', reviewPath, trace.review?.sha256],
+    ['Spec', specPath, trace.spec?.sha256]
+  ]) {
+    if (!hashPattern.test(expected || '')) fail(`${label} SHA-256 格式无效`);
+    else if (filePath && fs.existsSync(filePath) && sha256(filePath) !== expected) {
+      fail(`${label} SHA-256 与当前文件不一致`);
+    }
+  }
+
+  const manifestScope = manifest?.scopes?.find(item => item.directory === trace.scope?.directory);
+  if (!manifestScope) fail(`Manifest 未找到 scope：${trace.scope?.directory}`);
+  const manifestRequirements = Array.isArray(manifestScope?.requirements)
+    ? manifestScope.requirements
+    : [];
+  const activeIds = manifestRequirements.filter(item => item.status === 'active').map(item => item.id);
+  const excludedIds = manifestRequirements.filter(item => ['deferred', 'removed'].includes(item.status)).map(item => item.id);
+  const traceRequirements = Array.isArray(trace.requirements) ? trace.requirements : [];
+  const traceIds = traceRequirements.map(item => item.id);
+  const traceExcluded = Array.isArray(trace.excludedRequirements) ? trace.excludedRequirements : [];
+  const traceExcludedIds = traceExcluded.map(item => item.id);
+
+  for (const id of [...activeIds, ...excludedIds, ...traceIds, ...traceExcludedIds]) {
+    if (!requirementPattern.test(id || '')) fail(`需求编号格式无效：${id}`);
+  }
+  if (new Set(traceIds).size !== traceIds.length) fail('Spec 追踪包含重复 active 需求编号');
+  if (new Set(traceExcludedIds).size !== traceExcludedIds.length) fail('Spec 追踪包含重复排除需求编号');
+  for (const id of activeIds) if (!traceIds.includes(id)) fail(`Spec 缺少 active 需求：${id}`);
+  for (const id of traceIds) if (!activeIds.includes(id)) fail(`Spec 包含非 active 或未知需求：${id}`);
+  for (const id of excludedIds) if (!traceExcludedIds.includes(id)) fail(`Spec 排除清单缺少：${id}`);
+  for (const id of traceExcludedIds) if (!excludedIds.includes(id)) fail(`Spec 排除清单包含未知或 active 需求：${id}`);
+
+  for (const item of traceExcluded) {
+    const source = manifestRequirements.find(requirement => requirement.id === item.id);
+    if (source && item.status !== source.status) fail(`${item.id} 的排除状态与 manifest 不一致`);
+    if (!item.reason || typeof item.reason !== 'string') fail(`${item.id} 的排除原因不能为空`);
+  }
+
+  const reviewRequirements = Array.isArray(review?.requirements) ? review.requirements : [];
+  const reviewed = new Map(reviewRequirements.map(item => [item.id, item]));
+  if (reviewed.size !== reviewRequirements.length) fail('Review 包含重复需求编号');
+  for (const item of reviewRequirements) {
+    if (!manifestRequirements.some(requirement => requirement.id === item.id)) {
+      fail(`Review 包含未知需求：${item.id}`);
+    }
+  }
+  for (const id of activeIds) {
+    const item = reviewed.get(id);
+    if (item?.reviewStatus !== 'confirmed') fail(`需求尚未确认：${id}`);
+    if (item && item.scopeStatus !== 'active') fail(`${id} 的 Review scopeStatus 与 manifest 不一致`);
+  }
+
+  const specText = specPath && fs.existsSync(specPath) ? fs.readFileSync(specPath, 'utf8') : '';
+  for (const item of traceRequirements) {
+    if (item.status !== 'specified') fail(`${item.id} 的 Spec 状态必须为 specified`);
+    if (!Array.isArray(item.acceptanceCriteria) || item.acceptanceCriteria.length === 0 || item.acceptanceCriteria.some(value => typeof value !== 'string' || !value.trim())) {
+      fail(`${item.id} 必须包含非空验收条件`);
+    }
+    if (!Array.isArray(item.verification) || item.verification.length === 0 || item.verification.some(value => !allowedVerification.has(value))) {
+      fail(`${item.id} 的 verification 无效`);
+    }
+    if (!new RegExp(`^## ${item.id}(?:\\s|$)`, 'm').test(specText)) {
+      fail(`spec.md 缺少需求章节：${item.id}`);
+    }
+  }
+}
+
+for (const error of errors) console.error(`错误 ${error}`);
+console.log(`Spec 追踪校验：${errors.length} 个错误`);
+process.exit(errors.length === 0 ? 0 : 1);

package/skills/common/review-from-docs/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: review-from-docs
+description: 基于页面 scope、PRD、RAG、Figma 和仓库证据，对带 REQ 编号的需求进行决策树式多轮质询并生成结构化 review-result。用户要求评审、质询或澄清 scope，或需要在生成 spec 前消除需求冲突时使用；不生成最终 spec 或业务代码。
+---
+
+# 基于文档质询需求
+
+以用户指定的页面 `scope.md` 为入口，把每个需求的冲突、歧义和缺失决策质询到可生成规格的状态。质询方式沿用 Matt `grilling` 的决策树和 frontier 机制，同时用 REQ ID 保持范围、问题、结论和后续 Spec 的映射。开始前完整读取 [需求追踪契约](../ui-prd-scope/references/requirement-traceability.md) 和 [质询结果 Schema](references/review-result-schema.md)。
+
+## 输入
+
+- 必需的页面 `scope.md`，以及其范围包根目录的 `scope-manifest.json`。
+- scope 声明的 PRD 来源、RAG 引用、Figma JSON/PNG 和仓库事实。
+- 可选的既有 `review/review-result.json`；继续质询时保留已确认结论。
+
+输入未声明 `traceabilitySchemaVersion: 1`、非全局 scope 缺少需求编号，或 scope 与 manifest 的编号不一致时停止并要求先用 `$ui-prd-scope` 刷新范围包。本 Skill 不创建、修改或重排需求编号。
+
+## 建立决策树
+
+1. 建立 manifest 中全部需求的台账，保留 `active`、`deferred` 和 `removed`。逐条核对 scope 原文、PRD、RAG、Figma 与仓库事实；证据优先级沿用 scope，不把历史 RAG 或当前实现升级为新需求。
+2. 为每个 active REQ，以及影响多个 REQ 的跨需求决策，建立有依赖关系的决策树。至少覆盖 Schema 中定义的七个决策领域；不适用的领域显式标为 `not-applicable`，不能因未检查而省略。
+3. 事实查证由 Agent 完成：继续阅读可用文档、代码、配置和本地资产。证据能够唯一回答的节点标为 `evidence` 并记录引用；只有需要产品、设计或业务取舍的节点进入用户质询。不得把可以从材料查到的事实转嫁给用户，也不得用推荐答案替用户作业务决定。
+4. 每个决策节点记录前置节点。当前所有前置条件已经解决的未决节点共同构成 frontier；依赖本轮答案的下游问题留到下一轮。
+
+## 多轮质询
+
+1. 每一轮一次性询问整个 frontier，而不是只问一个 REQ 或一个最明显的问题。一个 REQ 可以有多个问题，一个问题也可以关联多个 REQ。
+2. 问题按 `Q1`、`Q2` 顺序展示。每题必须包含：关联 REQ ID、简短标题、具体缺口或冲突、问题及必要选项、受影响的验收边界，以及推荐答案和理由。没有真实选择时不要制造选项。
+3. 一轮只包含彼此不依赖、用户现在即可回答的问题。输出本轮问题后停止并等待用户回答，不生成最终结果，也不把未回答问题标为已确认。
+4. 用户回答后，将答案映射回对应问题和全部关联 REQ，更新决策树并重新计算 frontier。继续提出下一轮，直到所有分支均已访问且 frontier 为空。
+5. 用户回答顺带暴露新分支、矛盾或边界时，把它加入决策树；不能因最初清单没有列出而忽略。用户明确暂缓、取消或暂停质询时记录原因，不自行推断。
+6. frontier 为空后，先向用户汇总每个 REQ 的决策和验收边界，请用户确认已达成共同理解。只有用户确认后，才能把会话标为 `complete` 并生成最终产物。
+
+## 写入结果
+
+用户确认完成后，按 Schema 写入并复读 `review/review-result.json` 和 `review/review-result.md`。用户明确暂停时可以写入 `sessionStatus: paused` 的中间结果，并保留全部开放问题；普通问答回合不写成完成结果。两份产物结论一致，Markdown 使用简体中文，JSON 保持机器字段。
+
+执行 `node .agents/skills/review-from-docs/scripts/validate-review-traceability.mjs <页面 scope 目录>`；根据实际安装位置调整脚本路径。校验失败时修正质询产物，不修改或放宽 scope 编号。
+
+## 完成条件
+
+- Manifest 中每个需求在结果中恰好出现一次，没有未知编号。
+- 每个 active REQ 的七个决策领域都有明确状态；一个 REQ 可关联任意数量问题，不能把 REQ 当作单个问题。
+- `sessionStatus: complete` 时所有问题已回答、所有 active REQ 均为 `confirmed`、不存在 `open` 决策领域或 `remainingIssues`，并且用户已确认共同理解。
+- `sessionStatus: paused` 只用于用户明确暂停；未决问题和 frontier 必须原样保留，后续从该位置继续。
+- 任何 active 需求仍为 `unresolved` 都会阻断 `$make-spec`，不得用默认结论或推荐答案伪装成已确认。
+- 最终答复列出 confirmed/unresolved/deferred/removed 数量、产物路径和需要回写 scope 的生命周期变化；不生成 `spec.md`、不修改业务代码。

package/skills/common/review-from-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "需求文档质询"
+  short_description: "按需求编号进行决策树式多轮质询"
+  default_prompt: "使用 $review-from-docs 对当前 scope 建立决策树，逐轮询问完整 frontier，并生成带需求编号的 review-result。"

package/skills/common/review-from-docs/references/review-result-schema.md

@@ -0,0 +1,88 @@
+# Review Result Schema v2
+
+质询结果写入页面 scope 目录下的 `review/review-result.json`。v2 用问题轮次和决策覆盖证明质询已遍历完整决策树，而不是只记录一个最明显的缺失项。
+
+```json
+{
+  "schemaVersion": 2,
+  "sessionStatus": "complete",
+  "userConfirmed": true,
+  "scope": {
+    "manifestPath": "../scope-manifest.json",
+    "directory": "01-product-detail",
+    "scopePath": "scope.md"
+  },
+  "rounds": [{ "round": 1, "questionIds": ["Q001", "Q002"] }],
+  "questions": [
+    {
+      "id": "Q001",
+      "requirementIds": ["REQ-PD-001"],
+      "area": "emptyError",
+      "parentQuestionIds": [],
+      "question": "图片加载失败时是否保留 4:3 占位？",
+      "recommendation": "保留容器比例并显示默认占位图，避免页面跳动。",
+      "affectedAcceptance": "决定错误态的布局和视觉验收条件。",
+      "status": "answered",
+      "answer": "是，显示默认占位图",
+      "answeredBy": "user"
+    }
+  ],
+  "requirements": [
+    {
+      "id": "REQ-PD-001",
+      "scopeStatus": "active",
+      "reviewStatus": "confirmed",
+      "decisionCoverage": {
+        "scopeBoundary": "evidence",
+        "dataContract": "user",
+        "emptyError": "user",
+        "stateInteraction": "not-applicable",
+        "permission": "not-applicable",
+        "responsiveVisual": "evidence",
+        "acceptanceEvidence": "user"
+      },
+      "questionIds": ["Q001"],
+      "decisions": ["加载失败时保持 4:3 容器并显示默认占位图"],
+      "evidenceRefs": ["scope.md#REQ-PD-001", "mobile-default.json#12:34"],
+      "remainingIssues": []
+    }
+  ],
+  "openFrontier": [],
+  "scopeUpdatesRequired": []
+}
+```
+
+## 决策领域
+
+每个 active REQ 必须包含全部领域，不能省略未检查项：
+
+| area | 检查内容 |
+| --- | --- |
+| `scopeBoundary` | PR 增量归属、范围内外、与其他 REQ 的边界 |
+| `dataContract` | 字段来源、格式、空值、编码、兼容和前后端责任 |
+| `emptyError` | 空态、缺失值、异常、失败和回退行为 |
+| `stateInteraction` | 初始状态、转换、交互、导航和副作用 |
+| `permission` | 登录、权限、角色和不可访问状态 |
+| `responsiveVisual` | Desktop/Mobile、断点、Figma 状态和视觉差异 |
+| `acceptanceEvidence` | 可观察结果、fixture、验证方式和证据来源 |
+
+领域状态只使用 `evidence`、`user`、`not-applicable`、`open`。`evidence` 必须能由 `evidenceRefs` 定位；`user` 必须至少关联一个已回答问题；`not-applicable` 表示已经检查并确认不适用，不能代表未检查。
+
+## 问题与轮次
+
+- 问题 ID 使用当前 review 内稳定且唯一的 `Q001`、`Q002` 格式；REQ 映射由非空 `requirementIds` 表达。
+- `parentQuestionIds` 记录必须先解决的问题，依赖关系不得成环；子问题必须出现在所有父问题之后的轮次。每轮只包含当时没有未解决父问题的完整 frontier。
+- `area` 必须是七个决策领域之一。跨领域问题拆开；跨 REQ 的同一业务决策可在一个问题中列出多个 `requirementIds`。
+- `status` 使用 `open` 或 `answered`。`answered` 必须包含 `answer` 和 `answeredBy`；`answeredBy` 使用 `user` 或 `evidence`。
+- 每个问题恰好出现在一个 `rounds[].questionIds` 中。`openFrontier` 只列当前可立即回答的开放问题；依赖未解决父问题的节点不属于 frontier。
+
+## 会话状态
+
+- `sessionStatus` 只使用 `complete` 或 `paused`。
+- `complete` 必须满足：`userConfirmed: true`、所有问题均为 `answered`、`openFrontier` 为空、所有 active REQ 均为 `confirmed`、全部决策领域不为 `open`、`remainingIssues` 为空。
+- `paused` 只在用户明确暂停时使用，`userConfirmed` 必须为 `false`；保留所有开放问题、依赖关系、当前 frontier 和未解决项，供下一次继续。
+- `deferred` 和 `removed` REQ 的 `reviewStatus` 必须与 scope 状态一致，不要求七领域覆盖。
+
+`scopeUpdatesRequired` 只记录用户在质询中改变生命周期的需求，例如 `{ "id": "REQ-PD-003", "targetStatus": "deferred", "reason": "本迭代不实现" }`。它不是对 manifest 的静默修改授权。
+
+`review-result.md` 按轮次列出问题、建议与回答，再按 REQ 汇总七领域覆盖、最终决策和未解决项。推荐答案与用户最终答案必须明确区分。