@autobest-ui/agent 1.0.5 → 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

@@ -1,21 +1,24 @@
 ---
 name: code-pr-submit
-description: 编排 Azure DevOps 反向 PR：将用户所说的目标分支作为携带变更的 PR 源，将来源分支作为接收合并的 PR 目标；校验参数、显式确认方向、基于 spec.md 与 diff 生成描述，并通过 code-mcp-pr MCP 创建 PR 和发送钉钉通知。用户要求创建 Azure PR、反向 PR，或把目标分支变更合并到来源分支时使用。只负责编排与文本生成，不直接请求 ADO 或钉钉 API。
+description: 从当前 Git 项目自动识别 Azure DevOps 仓库、当前分支及其父分支，生成 PR 标题和描述，并通过 code-mcp-pr 创建从当前分支合并到父分支的 PR。用户要求创建或提交 Azure PR、为当前分支提 PR，或预览待提交 PR 时使用。用户显式参数优先；只在本地项目无法推断必要信息时询问。
 ---
 
-# Azure DevOps 反向 PR 编排
+# Azure DevOps PR 提交
 
-## 角色与边界
+## 目标
 
-将用户的业务分支语义编排为 Azure DevOps PR。这里的术语与常规 PR 表述相反，首次响应、分支确认和最终创建确认都要明确提醒：
+在当前项目中创建普通方向的 PR：
 
-- 用户的“目标分支”是携带变更的 PR 源分支，映射为 `businessTargetBranch`。
-- 用户的“来源分支”是接收合并的 PR 目标分支，映射为 `businessSourceBranch`。
-- 流向始终是 `targetBranch -> sourceBranch`，禁止交换两个 MCP 参数。
+```text
+from = 当前开发分支（携带变更）
+to   = 当前分支的父分支（创建该分支时所基于的分支）
+```
+
+面向用户始终使用 `from -> to`、源分支和目标分支等常规 Git 术语。MCP 的历史字段命名只在最终参数映射时内部处理。
 
-只调用 `code-mcp-pr` MCP 服务提供的工具。由 MCP 访问 ADO 和钉钉；不拼接 API、不发起 HTTP 请求、不直接调用 webhook。PAT 和钉钉 token 分别由 MCP 从 `AZURE_DEVOPS_PAT`、`DINGDING_ALERT_TOKEN` 读取，不读取、持有或传递凭据。
+只通过 `code-mcp-pr` MCP 访问 Azure DevOps 和钉钉。PAT 与钉钉 token 由 MCP 从 `AZURE_DEVOPS_PAT`、`DINGDING_ALERT_TOKEN` 读取；Skill 不读取、持有或传递凭据。
 
-可用工具：
+可用 MCP 工具：
 
 - `code-mcp-pr.code-mcp-pr`
 - `code-mcp-pr.get_repo_default_branch`
@@ -23,218 +26,186 @@ description: 编排 Azure DevOps 反向 PR：将用户所说的目标分支作
 - `code-mcp-pr.get_branch_diff`
 - `code-mcp-pr.read_file_at_ref`
 
-## 输入与输出
-
-从用户自然语言和明确的会话上下文收集：
-
-| 字段 | 必填 | 含义 |
-| --- | --- | --- |
-| `orgName` | 是 | ADO 组织 |
-| `projectName` | 是 | ADO 项目 |
-| `repoId` | 是 | 仓库 ID/Guid |
-| `currentBranch` | 否 | 运行环境明确提供的当前分支；远程 ADO 无法探测 |
-| `targetBranch` | 条件必填 | 用户所说的目标分支，携带变更 |
-| `sourceBranch` | 条件必填 | 用户所说的来源分支，接收合并 |
-| `prTitle` | 是 | PR 标题 |
-| `prDescription` | 否 | 用户手动提供的 PR 描述；未提供时自动生成 |
-| `reviewers` | 否 | 评审人 ID 列表 |
-
-最终输出为创建结果：成功时给出 PR ID、访问链接、再次说明分支流向及钉钉状态；失败时给出可行动的错误说明，并明确未发送钉钉通知。
-
-## 确认状态
-
-把候选值与已确认值分开管理。用户只是提供分支名，不等于已经确认反向 PR 方向；必须在展示“PR 源/PR 目标”语义后取得明确肯定答复，才将两个分支标记为已确认。
-
-任何一方分支发生变化时：
-
-1. 撤销该分支及最终创建确认。
-2. 撤销自动生成描述的确认，使用新分支重新读取 diff 和 `spec.md`。
-3. 重新检查两个分支是否相同。
+## 输入优先级
 
-用户修改自动生成的描述后，将新文本展示给用户并取得明确确认。确认必须对应当前展示的具体值，不能把含糊回复或对旧候选值的确认沿用到新值。
+用户显式提供的值始终优先。用户没有提供时，从当前 Git 项目自动发现，不先展示参数清单，不要求用户重复填写能够查到的信息。
 
-## 工作流
+内部使用以下清晰字段：
 
-### 1. 校验基础参数
+| 字段 | 自动来源 |
+| --- | --- |
+| `orgName` | Azure DevOps `origin` URL |
+| `projectName` | Azure DevOps `origin` URL |
+| `repoId` | Azure DevOps `origin` URL 中的仓库名；ADO API 接受仓库名或 GUID |
+| `fromBranch` | 当前 Git 分支 |
+| `toBranch` | 分支创建 reflog、本地 merge-base 或 MCP 启发结果 |
+| `prTitle` | 用户输入；否则使用当前分支最新的非合并 commit 标题，并结合分支名清理 |
+| `prDescription` | 用户输入；否则根据远端 diff、`spec.md`、`spec-traceability.json` 和已有 Checker 证据自动生成 |
+| `reviewers` | 仅使用用户明确提供的评审人 ID；缺失时省略 |
 
-检查 `orgName`、`projectName`、`repoId`、`prTitle`。一次列出全部缺失项并请用户补齐，不推造默认值。
+## 自动发现项目
 
-在首次交互中说明：
+收到请求后立即在当前工作目录执行只读 Git 命令，不先向用户索要字段：
 
-> ⚠️ 这是反向 PR：你所说的“目标分支”会作为 PR 源（携带变更），“来源分支”会作为 PR 目标（接收合并），方向与常规 PR 表述相反。
-
-### 2. 确认 targetBranch
-
-- 用户提供了 `targetBranch`：将其作为候选值，仍需询问：
-
-  > ⚠️ 反向 PR 方向确认：是否使用分支【${candidate}】作为携带变更的 PR 源分支？
-
-- 用户未提供 `targetBranch`，但会话上下文明确提供了非空 `currentBranch`：以它作为候选值并询问同一问题。用户确认后才能赋值给 `targetBranch`。
-- 用户未提供 `targetBranch`，且 `currentBranch` 为空：直接询问用户提供“目标分支（携带变更的分支）”。远程 ADO API 没有全局当前分支，不能调用 MCP 或根据仓库信息编造当前分支。
+```bash
+git rev-parse --show-toplevel
+git branch --show-current
+git remote get-url origin
+```
 
-### 3. 确认 sourceBranch
+从 `origin` 解析 ADO 信息，至少支持：
 
-前提是 `targetBranch` 已确认。
+```text
+https://dev.azure.com/{org}/{project}/_git/{repo}
+https://{user}@dev.azure.com/{org}/{project}/_git/{repo}
+https://{org}.visualstudio.com/{project}/_git/{repo}
+git@ssh.dev.azure.com:v3/{org}/{project}/{repo}
+ssh://git@ssh.dev.azure.com/v3/{org}/{project}/{repo}
+```
 
-- 用户提供了 `sourceBranch`：将其作为候选值，明确它是接收合并的 PR 目标并取得确认。
-- 用户未提供 `sourceBranch`：调用 `code-mcp-pr.guess_parent_branch`：
+对 URL decode 后的值去除仓库名末尾 `.git`。如果有多个 remote，优先 `origin`；`origin` 不存在时检查唯一的 ADO remote。不要把 remote 用户名误当成组织名。
 
-```yaml
-orgName: ${orgName}
-projectName: ${projectName}
-repoId: ${repoId}
-branchName: ${targetBranch}
-```
+以下情况才询问用户对应的最少信息：当前目录不在 Git 仓库；处于 detached HEAD 且用户未给 `fromBranch`；没有可解析的 ADO remote；必要字段存在多个冲突候选。一次只汇总真正无法发现的字段。
 
-调用成功且 `guessedParentBranch` 非空时，原样带上返回的 `hint` 询问：
+## 自动发现父分支
 
-> ⚠️ 无法获取该分支真实创建父分支，启发推测父分支为：${guessedParentBranch}，${hint}
-> 是否使用 ${guessedParentBranch} 作为 PR 目标分支（接收合并）？
+目标是找出 `fromBranch` 创建时所基于的分支，而不是无条件返回默认分支。按以下优先级执行：
 
-ADO Git 不持久保存分支创建时的父分支；此结果只是启发式猜测。用户确认后才赋值给 `sourceBranch`。用户拒绝时请其手动输入来源分支，再展示其 PR 目标语义并确认。
+1. 用户明确提供 `toBranch` 时直接使用。
+2. 检查当前分支最早的 reflog 记录：
 
-当工具失败、`guessedParentBranch` 为空，或目标分支本身是默认分支而无法推测时，说明工具返回的 `errorMsg`/`hint`，请用户手动提供来源分支。`get_repo_default_branch` 仅在用户明确查询仓库默认分支时使用，不能用其结果静默代替父分支确认。
+   ```bash
+   git reflog show --format='%H%x09%gs' -- "${fromBranch}"
+   ```
 
-两个分支均确定后，按去除 `refs/heads/` 前缀后的规范分支名比较；若相同，拒绝创建并要求用户修正，不能仅依赖 MCP 校验。
+   从最早记录中的 `branch: Created from <ref>` 提取父分支。`<ref>` 是明确分支名且能被 `git rev-parse --verify` 解析时采用；`HEAD`、commit SHA 或已失效 ref 继续下一步。
+3. 使用本地 refs 做 merge-base 启发：列出 `refs/heads` 和 `refs/remotes/origin`，排除当前分支、其远端同名分支、`*/HEAD`，计算各候选与 `fromBranch` 的 merge-base。优先选择 merge-base 等于 reflog 创建 commit 的候选；多个候选并列时，优先远端跟踪分支和 `origin` 默认分支。仍并列时根据从 merge-base 到 `fromBranch` 的提交距离选择最近者。
+4. 本地历史不足时调用 `code-mcp-pr.guess_parent_branch`，传入自动发现的仓库信息和 `fromBranch`。
+5. 所有方式均失败或仍有多个同等可信候选时，展示候选及推断依据，请用户只选择 `toBranch`。
 
-### 4. 确认 PR 描述
+将 `origin/foo`、`refs/remotes/origin/foo` 和 `refs/heads/foo` 规范成业务分支名 `foo`。父分支推断完成后比较规范化的 `fromBranch` 与 `toBranch`；相同时停止并请求修正。
 
-用户已手动提供 `prDescription` 时，保留其原文并视为用户明确选择；最终创建确认仍需在该描述已确定后进行。
+父分支推断属于启发式，但不要在正常成功路径输出长篇限制说明。只在置信度较低或需要用户选择时简短说明依据。
 
-用户未提供时，只有在两个分支均已确认后才执行以下读取：
+## 收集 PR 内容
 
-1. 调用 `code-mcp-pr.get_branch_diff`，固定以携带变更的分支为 source、接收合并的分支为 target：
+分支确定后调用 `code-mcp-pr.get_branch_diff`：
 
 ```yaml
 orgName: ${orgName}
 projectName: ${projectName}
 repoId: ${repoId}
-sourceBranch: ${targetBranch}
-targetBranch: ${sourceBranch}
+sourceBranch: ${fromBranch}
+targetBranch: ${toBranch}
 ```
 
-2. 调用 `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}
 projectName: ${projectName}
 repoId: ${repoId}
-refName: ${targetBranch}
+refName: ${fromBranch}
 filePath: spec.md
 ```
 
-3. `get_branch_diff` 失败时无法可靠生成描述：报告 `errorMsg` 并停止在预览之前。`read_file_at_ref` 返回 `success=true, fileExists=false` 时令 `specMdContent=null` 并继续；其他读取失败则告知用户，并询问是仅基于 diff 继续还是稍后重试，不能把读取错误表述成文件不存在。
-4. 当前 LLM 使用原始 `diffFiles`、`diffShortText` 和 `specMdContent` 生成描述；MCP 只负责读取材料，不承担总结。
+文件不存在时继续。其他读取错误保留错误事实，但只要 diff 可用就继续生成描述。diff 失败时报告 MCP 的 `errorMsg`，不要基于猜测创建 PR。不得为了寻找产物扫描或猜测无关目录。
 
-生成规则：
+用户未给标题时，先读取：
+
+```bash
+git log --no-merges -1 --format=%s -- "${fromBranch}"
+```
 
-- `specMdContent` 非空时，将需求说明与实际代码变更对齐，逐条写出已实现的变更。
-- `specMdContent` 为空时，仅根据 diff 按文件维度说明修改内容。
-- 使用简洁、面向评审人的 Markdown；开头是短概述，详情只用 `- ` 无序列表。
-- 不粘贴大段原始 diff，不声称材料中无法证明的行为。diff 被截断时只总结可见材料，不推测缺失部分。
+用最新提交标题作为基础；仅在它为空或明显无意义时，根据分支名、`spec.md` 和 diff 生成简洁标题。不要为标题单独询问用户。
 
-格式：
+用户未给描述时，根据 `spec.md` 和 diff 生成面向评审人的 Markdown：
 
 ```markdown
 ## 变更概述
-本次提交完成 xx 能力改造。
+一句话说明本次改动。
 
 ## 变更详情
-- `path/to/file`：新增 xx 逻辑，实现 xx。
-- `path/to/file`：修复 xx 问题。
+- `path/to/file`：说明可由材料证明的改动。
+
+## 需求追踪
+- `REQ-PD-001`：已实现；Checker 通过 / 失败 / 阻断 / 缺少验收证据
 ```
 
-生成后完整展示并询问：
+存在 `spec-traceability.json` 时按真实 REQ ID 列出本 PR 涉及的 active 需求。只有 Checker 结果明确覆盖且通过时才能写“Checker 通过”；没有对应证据时写“缺少验收证据”，不得从代码、Maker 结果或整体 Checker 状态推断单项通过。不存在追踪产物时省略“需求追踪”，不临时发明编号。只总结可见材料，不粘贴大段 diff，不补造功能。用户提供标题或描述时保留其原意，不擅自替换。
 
-> 📝 自动生成的 PR 描述如下，是否直接使用？如果需要修改，请直接告诉我新的描述。
+## 创建授权
 
-只有用户明确确认后才赋值给 `prDescription`。用户给出替换文本时，展示替换后的描述并重新确认；不得静默提交自动生成内容。
+如果用户本次请求明确包含“创建 PR”“提交 PR”“提 PR”等写操作意图，该请求本身就是创建授权。完成自动发现和内容生成后直接创建，不再逐项确认分支、描述或重复询问最终授权。
 
-### 5. 最终创建确认
+如果用户只要求“准备”“生成”“预览”PR，则展示以下简洁预览并停止，不调用创建工具：
 
-基础参数齐全、两个分支及 PR 描述均确定后，逐字明确方向并等待用户确认：
+```text
+PR: ${fromBranch} -> ${toBranch}
+标题：${prTitle}
+描述：${prDescription}
+```
 
-> ⚠️【反向 PR 确认】
-> PR 源（携带变更）：${targetBranch}
-> PR 目标（合并进入）：${sourceBranch}
-> PR 标题：${prTitle}
-> 是否确认调用 MCP 工具 code-mcp-pr 创建 Azure DevOps PR？
+如果用户的表达无法判断是创建还是预览，只询问这一项，不重新询问已自动发现的数据。
 
-这一步是外部写操作授权。未得到明确肯定答复时停止，不调用创建工具。用户修改任一字段时回到相应确认步骤。
+创建前检查当前工作区：
 
-### 6. 组装钉钉消息并创建 PR
+```bash
+git status --short
+git ls-remote --exit-code origin "refs/heads/${fromBranch}"
+```
 
-用户最终确认后，由当前 LLM 从已确认的 `prDescription` 提炼 3 至 5 条核心变更。只组装文本，不调用钉钉 webhook：
+未提交改动不会包含在 PR 中，发现时明确告知并停止创建。远端不存在 `fromBranch` 时告知需要先推送；Skill 不自行 push。
 
-```text
-dingtalkMarkdownTitle = "✅ ADO PR已创建完成"
-```
+## 创建与通知
+
+根据最终描述提炼 3 至 5 条钉钉变更要点，保留字面量 `{{PR_WEB_URL}}`：
 
 ```markdown
 **PR 标题：${prTitle}**
 
 PR 链接：[{{PR_WEB_URL}}]({{PR_WEB_URL}})
 
-分支流向：${targetBranch} ➔ ${sourceBranch}
+分支流向：${fromBranch} -> ${toBranch}
 
 变更要点：
 
 - 要点 1
 - 要点 2
-- 要点 3
 ```
 
-正文必须保留字面量 `{{PR_WEB_URL}}`，由 MCP 在 PR 创建成功后替换为真实 `prWebUrl`。随后只调用一次 `code-mcp-pr.code-mcp-pr`，映射如下：
+调用一次 `code-mcp-pr.code-mcp-pr`。MCP 的业务字段名与普通 Git 术语不同，严格按以下映射，不向用户展示该内部差异：
 
 ```yaml
 orgName: ${orgName}
 projectName: ${projectName}
 repoId: ${repoId}
-businessTargetBranch: ${targetBranch}
-businessSourceBranch: ${sourceBranch}
+businessTargetBranch: ${fromBranch}
+businessSourceBranch: ${toBranch}
 prTitle: ${prTitle}
 prDescription: ${prDescription}
 reviewers: ${reviewers}
-dingtalkMarkdownTitle: "✅ ADO PR已创建完成"
-dingtalkMarkdownContent: ${assembledMarkdownWithLiteralPrWebUrlPlaceholder}
+dingtalkMarkdownTitle: "ADO PR 已创建"
+dingtalkMarkdownContent: ${markdownWithLiteralPrWebUrlPlaceholder}
 ```
 
-`reviewers` 未提供时省略该参数。PR 创建失败时 MCP 不会发送钉钉；钉钉发送失败不改变 PR 创建成功状态。创建工具非幂等：响应不明确或调用中断时，不自动重试，先向用户说明可能已创建并要求核查，避免重复 PR。
-
-## MCP 返回处理
+`reviewers` 未提供时省略。创建工具非幂等：调用中断或响应不明确时不自动重试，先查询或请用户核查是否已经创建。
 
-### 创建成功
+## 返回结果
 
-当 `success=true`，读取 `prId`、`prWebUrl`、`dingtalkSendSuccess` 并输出：
+成功时简洁输出：
 
 ```text
-✅ PR 创建成功
-PR ID: ${prId}
-PR 访问链接：${prWebUrl}
-本次 PR 流向：${targetBranch} → 合并至 ${sourceBranch}
-${dingtalkSendSuccess === true ? "✅ 已推送通知至钉钉群" : "⚠️ PR 创建成功，但钉钉群通知发送失败，请检查环境变量 DINGDING_ALERT_TOKEN"}
+PR 创建成功
+${fromBranch} -> ${toBranch}
+${prWebUrl}
+钉钉通知：已发送 | 发送失败 | 已跳过
 ```
 
-`dingtalkSendSuccess` 为 `false` 或 `null` 均按通知失败提示处理，不重试 PR 创建。
-
-### 创建失败
-
-当 `success=false`，根据 `errorMsg` 中的状态码和资源信息转为自然语言，并附上不会发送钉钉通知：
+`dingtalkSendSuccess=true` 表示已发送，`false` 表示失败，`null` 表示未请求通知；不要把 `null` 说成发送失败。
 
-- `401`：`AZURE_DEVOPS_PAT` 权限不足或失效，请检查 PAT 是否拥有代码读取和 PR 创建权限。
-- `404` 且指向仓库：请检查 `projectName`、`repoId` 是否正确。
-- `404` 且指向分支/ref：分支不存在，请核对分支名。
-- `404` 且指向文件：文件读取失败；自动描述阶段的 `spec.md` 正常不存在应由 `fileExists=false` 表示，不归入此错误。
-- 其他错误：保留原始 `errorMsg`，不要臆测原因。
-
-输出格式：
-
-```text
-❌ PR 创建失败
-${friendlyError}
-PR 创建失败不会触发钉钉通知。
-```
+失败时保留 `errorMsg` 的关键信息并说明 PR 未创建、钉钉未触发。钉钉失败不改变 PR 创建成功状态。
 
-## 完成检查
+## 完成条件
 
-调用创建工具前逐项确认：必填基础参数齐全；两个分支分别按反向语义得到确认且不相同；自动生成描述已经预览确认；钉钉正文含字面量 `{{PR_WEB_URL}}`；`businessTargetBranch=targetBranch`、`businessSourceBranch=sourceBranch`；已取得最终外部写操作授权。任一项不满足就停留在对应交互步骤。
+结束前确认：用户值覆盖自动值；仓库信息来自当前项目；`fromBranch` 是当前或用户指定的开发分支；`toBranch` 是可解释的父分支；远端已有源分支；描述由实际材料支持；MCP 映射为 `businessTargetBranch=fromBranch`、`businessSourceBranch=toBranch`；创建结果与钉钉状态准确呈现。

package/skills/common/code-pr-submit/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Code PR Submit"
-  short_description: "编排并确认 Azure DevOps 反向 PR"
-  default_prompt: "使用 $code-pr-submit 将目标分支的变更创建反向 PR，合并到来源分支，并在每个关键步骤等待我确认。"
+  short_description: "从当前 Git 项目自动创建 Azure DevOps PR"
+  default_prompt: "使用 $code-pr-submit 自动读取当前项目和分支，创建合并到父分支的 Azure DevOps PR。"

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);