@autobest-ui/agent 1.0.6 → 1.0.7

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` 以该编号记录质询结论；`make-spec` 生成逐项可验收的 `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`。任何 `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,130 @@
+#!/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');
+  }
+
+  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,33 @@
+---
+name: review-from-docs
+description: 围绕已有页面 scope、PRD、RAG、Figma 和仓库证据逐条质询需求，保留稳定 REQ 编号并生成结构化 review-result。用户要求评审、质询或澄清 scope，或需要在生成 spec 前消除需求冲突时使用；不生成最终 spec 或业务代码。
+---
+
+# 基于文档质询需求
+
+以用户指定的页面 `scope.md` 为入口，把每个需求的冲突、歧义和缺失决策质询到可生成规格的状态。开始前完整读取 [需求追踪契约](../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` 需求检查行为、状态转换、权限、空态/错误态、响应式、UI 状态、数据前置和可观察验收结果。已有证据能唯一回答时记录证据结论；需要业务取舍时向用户提问。
+3. 每次只提出一个相互关联的决策组，明确列出 `REQ-ID`、证据冲突、缺失信息和该回答会影响的验收边界。不得用默认值替用户消解业务冲突。
+4. 用户回答后立即更新内存台账；结论必须落到对应 `REQ-ID`。用户明确暂缓或取消时记录状态和原因，但不修改 scope manifest 的生命周期状态；将需要回写 scope 的差异列入 `scopeUpdatesRequired`。
+5. 所有问题处理完毕，按 Schema 写入并复读 `review/review-result.json` 和 `review/review-result.md`。两份产物结论一致，Markdown 使用简体中文，JSON 保持机器字段。
+6. 执行 `node .agents/skills/review-from-docs/scripts/validate-review-traceability.mjs <页面 scope 目录>`；根据实际安装位置调整脚本路径。校验失败时修正质询产物，不修改或放宽 scope 编号。
+
+## 完成条件
+
+- Manifest 中每个需求在结果中恰好出现一次，没有未知编号。
+- 每个 `active` 需求为 `confirmed` 或 `unresolved`；只有证据或用户回答足以确定验收边界时才能标为 `confirmed`。
+- `confirmed` 需求至少包含一条 `decisions`，`unresolved` 需求至少包含一条 `remainingIssues`。
+- 用户要求生成可交付 Spec 时，任何 `active` 需求仍为 `unresolved` 都是明确阻断，不得伪装为默认结论。
+- 最终答复列出 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: "按需求编号质询 scope 中的冲突、歧义和缺失信息"
+  default_prompt: "使用 $review-from-docs 逐条质询当前 scope，并生成带需求编号的 review-result。"

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

@@ -0,0 +1,42 @@
+# Review Result Schema
+
+质询结果写入页面 scope 目录下的 `review/review-result.json`：
+
+```json
+{
+  "schemaVersion": 1,
+  "scope": {
+    "manifestPath": "../scope-manifest.json",
+    "directory": "01-product-detail",
+    "scopePath": "scope.md"
+  },
+  "requirements": [
+    {
+      "id": "REQ-PD-001",
+      "scopeStatus": "active",
+      "reviewStatus": "confirmed",
+      "questions": [
+        {
+          "question": "图片加载失败时是否保留 4:3 占位？",
+          "answer": "是，显示默认占位图",
+          "answeredBy": "user"
+        }
+      ],
+      "decisions": ["加载失败时保持 4:3 容器并显示默认占位图"],
+      "evidenceRefs": ["scope.md#REQ-PD-001", "mobile-default.json#12:34"],
+      "remainingIssues": []
+    }
+  ],
+  "scopeUpdatesRequired": []
+}
+```
+
+## 约束
+
+- `scope.manifestPath`、`scope.scopePath` 和所有本地产物路径相对于页面 scope 目录。
+- `scopeStatus` 使用 `active`、`deferred`、`removed`。
+- `reviewStatus` 使用 `confirmed`、`unresolved`、`deferred`、`removed`；后两者必须与 scope 状态相同。
+- `answeredBy` 使用 `user` 或 `evidence`。证据回答必须在同一需求的 `evidenceRefs` 中可定位。
+- `scopeUpdatesRequired` 只记录用户在质询中改变生命周期的需求，例如 `{ "id": "REQ-PD-003", "targetStatus": "deferred", "reason": "本迭代不实现" }`。它不是对 manifest 的静默修改授权。
+
+`review-result.md` 按需求编号展示原始需求、证据、问题、回答、最终决策和未解决项，并在顶部汇总各状态数量。

package/skills/common/review-from-docs/scripts/validate-review-traceability.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+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 reviewStatuses = new Set(['confirmed', 'unresolved', 'deferred', 'removed']);
+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;
+  }
+}
+
+const reviewPath = path.join(featureDir, 'review/review-result.json');
+const review = readJson(reviewPath, 'review-result.json');
+
+if (review) {
+  if (review.schemaVersion !== 1) fail('review-result.schemaVersion 必须为 1');
+  const manifestPath = path.resolve(featureDir, review.scope?.manifestPath || '');
+  const scopePath = path.resolve(featureDir, review.scope?.scopePath || '');
+  const manifest = readJson(manifestPath, 'scope-manifest.json');
+  if (!review.scope?.manifestPath) fail('review-result 缺少 scope.manifestPath');
+  if (!review.scope?.scopePath) fail('review-result 缺少 scope.scopePath');
+  if (!fs.existsSync(scopePath)) fail(`Scope 不存在：${review.scope?.scopePath}`);
+  if (manifest?.traceabilitySchemaVersion !== 1) {
+    fail('Manifest 未启用 traceabilitySchemaVersion: 1');
+  }
+  const manifestScope = manifest?.scopes?.find(
+    item => item.directory === review.scope?.directory
+  );
+  if (!manifestScope) fail(`Manifest 未找到 scope：${review.scope?.directory}`);
+  const expected = new Map(
+    (manifestScope?.requirements || []).map(item => [item.id, item])
+  );
+  const requirements = Array.isArray(review.requirements) ? review.requirements : [];
+  const ids = requirements.map(item => item?.id);
+  if (new Set(ids).size !== ids.length) fail('review-result 包含重复需求 ID');
+
+  for (const id of expected.keys()) {
+    if (!ids.includes(id)) fail(`review-result 缺少需求：${id}`);
+  }
+  for (const item of requirements) {
+    if (!requirementPattern.test(item?.id || '')) {
+      fail(`需求编号格式无效：${item?.id}`);
+      continue;
+    }
+    const source = expected.get(item.id);
+    if (!source) {
+      fail(`review-result 包含未知需求：${item.id}`);
+      continue;
+    }
+    if (item.scopeStatus !== source.status) {
+      fail(`${item.id} 的 scopeStatus 与 manifest 不一致`);
+    }
+    if (!reviewStatuses.has(item.reviewStatus)) {
+      fail(`${item.id} 的 reviewStatus 无效：${item.reviewStatus}`);
+    }
+    if (source.status === 'active' && !['confirmed', 'unresolved'].includes(item.reviewStatus)) {
+      fail(`${item.id} 是 active，reviewStatus 必须为 confirmed 或 unresolved`);
+    }
+    if (source.status !== 'active' && item.reviewStatus !== source.status) {
+      fail(`${item.id} 的排除状态必须保持为 ${source.status}`);
+    }
+    if (item.reviewStatus === 'confirmed' &&
+      (!Array.isArray(item.decisions) || item.decisions.length === 0)) {
+      fail(`${item.id} 已 confirmed 但缺少 decisions`);
+    }
+    if (item.reviewStatus === 'unresolved' &&
+      (!Array.isArray(item.remainingIssues) || item.remainingIssues.length === 0)) {
+      fail(`${item.id} 仍 unresolved 但缺少 remainingIssues`);
+    }
+  }
+  if (!Array.isArray(review.scopeUpdatesRequired)) {
+    fail('review-result.scopeUpdatesRequired 必须是数组');
+  }
+}
+
+for (const error of errors) console.error(`错误 ${error}`);
+console.log(`Review 追踪校验：${errors.length} 个错误`);
+process.exit(errors.length === 0 ? 0 : 1);

package/skills/common/ui-prd-scope/SKILL.md

@@ -18,8 +18,10 @@ description: 通过 MCP 拉取 Azure DevOps PRD PR，按共享 UI 页面族拆
 
 1. 读取仓库 `AGENTS.md`，检查现有输出目录和 Figma 采集目录，保留无关文件及用户创建的文件。
 2. 使用完整 PR 链接调用 `mcp__azurepr_mcp_bridge__get_azure_pull_request`。记录 PR 元数据、所有变更 PRD 文件，以及 bridge 返回的是完整文档还是仅新增片段。
-3. 写入前确定输出身份：
-   - 创建 `scope-manifest.json`，记录 PR 链接/ID/path、RAG 平台、来源到 scope 的映射、页面族决策、每个 scope 的 RAG 覆盖、生成目录、未匹配来源和 Figma 溯源。
+3. 写入前完整读取 [references/requirement-traceability.md](references/requirement-traceability.md)，确定输出身份和编号：
+   - 创建 `scope-manifest.json`，声明 `traceabilitySchemaVersion: 1`，记录 PR 链接/ID/path、RAG 平台、来源到 scope 的映射、页面族决策、每个 scope 的 RAG 覆盖、生成目录、未匹配来源和 Figma 溯源。
+   - 为每个非全局 scope 选择稳定的 2 至 16 位大写 ASCII 简称，并以 `REQ-<简称>-<三位序号>` 分配需求 ID。一个可独立确认、实现和验收的需求使用一个 ID。
+   - 刷新已有范围包时，先按业务含义和来源定位已有需求并复用 ID；调整顺序不改号，删除或暂缓保留原 ID 和原因，新增需求使用该 scope 从未使用过的下一序号。不得回收或静默重排编号。
    - 输出根目录已有相同 PR/path 的 manifest 时，只刷新该 manifest 所属文件。在 manifest 或报告中标记失效 scope；只有用户确认后才能删除。
    - 目录属于其他 PR，或包含没有身份信息的旧文件时，默认写入 `<output-root>/pr-<id>`；用户明确授权迁移时除外。不得静默混合两个 PR。
 4. 写入前建立来源清单。先分离全局规则和页面规则，再按共享 UI 模板分组，不能按文档或 URL 机械拆分。用户提供的页面族分类优先。否则依据布局/DOM、工作流/状态、模块所有权和数据契约记录合并或拆分理由。同一 UI 的不同 URL 作为变体；用户明确认定为一个页面族时，局部差异本身不构成拆分理由。
@@ -39,7 +41,7 @@ description: 通过 MCP 拉取 Azure DevOps PRD PR，按共享 UI 页面族拆
    - 将无歧义的匹配资产复制到页面目录，并在 manifest 记录原路径。只有用户明确要求时才移动源文件。未匹配资产保留原位。
    - 在 `scope.md` 中列出每一组本地 JSON/PNG；只总结设计证据直接支持的布局和状态，不转储原始 JSON。
    - 按 PRD 改动点标明每个资产覆盖的组件、设备和状态。只在改动点缺少必需视觉证据时记录待补采；局部组件改动不要求完整页面截图。不得把组件截图静默当作完整页面设计，也不得因它不是整页而把已覆盖的局部改动误报为缺失。
-9. 创建或重写页面 scope 前，读取 [references/scope-schema.md](references/scope-schema.md)。把适用的全局规则展开到各页面文档中。每个页面 scope 都要重复 Azure PR 链接、证据类型和完整 RAG 溯源，不依赖 README、全局文件或研究笔记才能理解。RAG 事实放在它所补充的功能或状态附近并附引用；不要另建后续提示必须读取的 RAG 或问题文档。
+9. 创建或重写页面 scope 前，读取 [references/scope-schema.md](references/scope-schema.md)。把适用的全局规则展开到各页面文档中。每个页面 scope 都要包含与 manifest 一致的“需求清单”，重复 Azure PR 链接、证据类型和完整 RAG 溯源，不依赖 README、全局文件或研究笔记才能理解。RAG 事实放在它所补充的功能或状态附近并附引用；不要另建后续提示必须读取的 RAG 或问题文档。
 10. 按以下优先级处理证据：当前 PRD 明确业务规则、当前 Figma 视觉证据、RAG 历史 PRD、仓库当前实现。冲突保留在“待质询”；实现证据只描述当前约束，不能覆盖新需求。
 11. 执行校验：
 
@@ -56,6 +58,7 @@ node .agents/skills/ui-prd-scope/scripts/validate-scope-bundle.mjs <实际输出
 - 每个页面 scope 都包含需求来源、运行环境/模块、改动边界、URL、权限/前置条件、Figma 状态、带溯源的页面级 RAG 和待质询问题。
 - 每个 RAG 覆盖领域都标记为命中、未命中、不适用或由用户明确暂缓；隐含的未检索缺口视为错误。
 - 每个页面族的合并/拆分都有依据，或明确引用用户提供的分类。
+- 每个非全局 scope 的简称和需求 ID 格式有效且全范围包唯一；manifest 与 `scope.md` 的编号、正文、状态和来源一致。
 - 每个本地资产链接有效，同目录 JSON 均可解析。
 - 缺少不可从仓库获得的路由/环境前置、业务数据、权限、改动点所需 Figma 状态或 RAG 证据时，明确由开发、产品、设计或后续质询补充。仓库可发现的运行事实由后续角色自行解析，不转嫁为用户实时输入。
 - 最终答复链接范围索引，列出页面族，汇总未命中和阻塞缺口，并说明未修改业务代码。

package/skills/common/ui-prd-scope/references/requirement-traceability.md

@@ -0,0 +1,82 @@
+# 需求追踪契约
+
+本契约定义页面 scope 从 PRD 到交付证据使用的稳定需求编号。`ui-prd-scope` 创建并拥有编号；后续质询、规格、实现、验收、审计和 PR 只能引用，不得重编号。
+
+## 编号
+
+格式固定为：
+
+```text
+REQ-<页面或Scope简称>-<三位序号>
+```
+
+- 简称使用 2 至 16 位大写 ASCII 字母或数字，以字母开头，例如 `PD`、`PL`、`GLOBAL`。
+- 完整编号匹配 `^REQ-[A-Z][A-Z0-9]{1,15}-\d{3}$`。
+- 每个页面族在 `scope-manifest.json` 中声明唯一的 `requirementPrefix`。
+- 序号从 `001` 递增。调整展示顺序时保留原编号；新增需求使用该前缀下从未使用过的下一个序号。
+- 一个编号只描述一个可独立实现或验收的原子需求。背景、目标、会议记录和普通备注不编号。
+
+## 生命周期
+
+需求状态只使用：
+
+| 状态 | 含义 |
+| --- | --- |
+| `active` | 本次必须进入质询、规格、实现和验收 |
+| `deferred` | 用户明确暂缓，保留编号和原因 |
+| `removed` | 用户明确取消，保留编号和原因 |
+
+刷新已有 scope 时先读取旧 manifest，按来源和语义复用原编号。需求被拆分时保留原编号并为新增原子需求分配新编号；需求合并展示时仍保留所有原编号。不得用内容哈希、表格行号、E2E scene、检查 ID 或 `reportGroup` 代替需求编号。
+
+## Manifest 结构
+
+声明 `traceabilitySchemaVersion: 1` 的新范围包必须在每个非全局 scope 中包含：
+
+```json
+{
+  "directory": "01-product-detail",
+  "pageFamily": "product-detail",
+  "requirementPrefix": "PD",
+  "requirements": [
+    {
+      "id": "REQ-PD-001",
+      "statement": "商品主图容器保持 4:3 比例",
+      "status": "active",
+      "sourceRefs": [
+        {
+          "type": "azure-prd",
+          "path": "/Frontend_Web/product-detail.md",
+          "section": "商品图片"
+        }
+      ],
+      "figmaRefs": ["mobile-default.json#12:34"],
+      "ragRefs": ["doc_id=81"],
+      "statusReason": null
+    }
+  ]
+}
+```
+
+`sourceRefs` 至少包含一个一手 PRD 来源；RAG 和当前实现只能补充，不能成为新增需求的唯一来源。`deferred` 和 `removed` 必须提供非空 `statusReason`。
+
+## Scope 文档
+
+每个非全局 `scope.md` 在“改动范围”之前包含：
+
+```markdown
+## 需求清单
+
+| 需求 ID | 原子需求 | 状态 | PRD 来源 | Figma | RAG |
+| --- | --- | --- | --- | --- | --- |
+| `REQ-PD-001` | 商品主图容器保持 4:3 比例 | `active` | `/Frontend_Web/product-detail.md` 商品图片 | `mobile-default.json#12:34` | `doc_id=81` |
+```
+
+正文中讨论需求、冲突和待质询项时引用同一编号。Manifest 是机器追踪源，`scope.md` 是自包含的人读入口，两者的编号、描述和状态必须一致。
+
+## 覆盖不变量
+
+- 每个 `active` 需求必须在质询结果中出现且最终为 `confirmed`，之后才能生成可交付 Spec。
+- 每个 `active` 需求必须在 `spec.md` 和 `spec-traceability.json` 中出现。
+- 每个 Spec 需求必须由至少一个运行检查或视觉映射覆盖；同一需求可对应多个检查。
+- Maker、Checker、Auditor 和 PR 描述只报告已有编号，不根据文本猜测或创建编号。
+- `deferred` 和 `removed` 不进入实现与验收覆盖，但必须在质询和 Spec 的排除清单中保留。