@autobest-ui/agent 1.0.0

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

@@ -0,0 +1,66 @@
+---
+name: export-report
+description: 从已完成或已阻断的 Autobest Delivery Maker、Runner 和 Checker 产物手动导出自测 Excel 报告。仅用于用户明确要求生成交付报告时。
+---
+
+# 导出交付报告
+
+本 Skill 是手动只读汇总步骤，不属于 delivery-loop 状态机。它读取既有交付证据并生成 Excel，不运行或重试 Maker、测试编写者、Checker、代码审计或浏览器。
+
+## 输入
+
+- 用户指定的功能目录，其中包含 `spec.md`、`checker/checker-result.json` 和对应 Runner 结果。
+- 可选的报告输出路径；必须位于功能目录内。默认写入 `featureDir/delivery-report.xlsx`。
+
+## 执行
+
+1. 将功能目录和可选输出路径解析为绝对路径，并使用 `git rev-parse --show-toplevel` 取得工作区。
+2. 从当前 Skill 路径定位插件根目录，不依赖业务仓库中的 `plugins/` 路径。
+3. 执行：
+
+```bash
+node <plugin-root>/scripts/export-delivery-report.mjs <feature-dir> \
+  --workspace-root <workspace-root> \
+  [--output <output-path>] \
+  [--grouping <feature-dir>/report/report-groups.json]
+```
+
+4. 复读脚本的 JSON 输出，向用户报告文件路径、Runner iteration、Checker/Runner 状态、功能行数、状态计数、唯一嵌入截图数、截图放置数和分组来源。
+
+报告固定使用插件资产 `assets/delivery-report-template.xlsx`，且只能生成一个名为 `自测报告` 的工作表。列固定为：页面/模块、自测点、自测方式、通过、截图1（桌面端）、截图2（移动端）。不得生成原子检查明细 Sheet，不得在可见单元格中输出 story ID、scene 名、历史场景或其他执行结构。
+
+每一行代表一个用户能识别的真实 UI 组件或完整业务功能。属于同一组件、同一页面位置或同一完整操作流的文案、样式、布局、响应式行为和相关功能检查必须合并到一行；仅仅修改了文字、颜色、间距或设备变体，不得拆成多行。不同组件、独立业务能力、状态转换或风险边界不得为了减少行数而强行合并。分组依据是 `spec.md` 描述的产品语义，不是 E2E scene、检查数量、story 顺序或截图文件名。
+
+新证据由测试编写者在每个运行检查中提供 `reportModule`、`reportGroup`、`reportTitle`、`reportMethod`，并在视觉映射中提供同组字段和 `reportDevice`。同一 `reportGroup` 的模块、标题和自测方式必须一致。组内状态按 `Blocked > 不通过 > 通过` 取最严重值；桌面端和移动端代表截图放在同一行，每种设备最多一张。相同截图二进制只嵌入一次。
+
+## 历史证据
+
+历史证据缺少报告分组字段时，不得按 scene 猜测。执行本 Skill 的代理必须先阅读完整 `spec.md`、Checker 结果及其引用的 Runner 结果，按上述产品语义生成 `featureDir/report/report-groups.json`，然后通过 `--grouping` 显式传给脚本。清单格式为：
+
+```json
+{
+  "version": 1,
+  "source": {
+    "specSha256": "当前 spec.md 内容的 SHA-256",
+    "iteration": 2,
+    "scenarioSha256": "当前 Runner 记录的冻结场景 SHA-256"
+  },
+  "groups": [
+    {
+      "id": "稳定的 ASCII 功能组 ID",
+      "module": "页面或模块",
+      "title": "组件或完整功能名称",
+      "method": "合并描述该功能的文案、视觉、布局、响应式和行为检查方式。",
+      "storyIds": ["story-01", "story-02"],
+      "desktopCapture": "可选的桌面截图文件名或证据路径",
+      "mobileCapture": "可选的移动端截图文件名或证据路径"
+    }
+  ]
+}
+```
+
+清单必须与当前 spec、iteration 和冻结场景哈希完全一致，并让每个 story 恰好出现一次。截图字段只能指向 Runner 已记录且能唯一匹配的截图。脚本负责验证清单和生成工作簿，不对缺失的业务语义进行自动猜测。
+
+## 完成条件
+
+只有脚本成功返回且报告文件存在时才报告完成。输入不完整、JSON 损坏或路径越界时原样说明错误；保留所有交付输入和 `delivery-state.json` 不变。

package/plugins/autobest-delivery/skills/export-report/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "导出交付报告"
+  short_description: "把 Maker、Runner 和 Checker 证据导出为自测 Excel"
+  default_prompt: "使用 $export-report 为指定功能目录生成交付自测 Excel 报告。"
+
+policy:
+  allow_implicit_invocation: false
+

package/plugins/autobest-delivery/skills/ui-structure-guard/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ui-structure-guard
+description: 在 UI 实现、响应式布局、截图还原或布局缺陷修复中守卫 React JSX/TSX 与 CSS/SCSS 结构。
+---
+
+# UI 结构守卫
+
+布局前先确定语义所有权和 DOM 层级。普通内容使用正常文档流、Flex 和 Grid；用 CSS 排列语义结构，不为匹配截图坐标而改变内容所有权。
+
+## 流程
+
+1. 阅读目标 UI 和相邻实现，识别组件所有权、BEM class、布局容器和响应式规则。
+2. 只保留承担语义、布局、状态、交互或样式作用域职责的容器。除非明确要求重命名，否则保留既有业务 class 含义。
+3. 使用正常文档流以及 Flex/Grid、gap、padding 和 margin 实现普通对齐、换行、间距、网格和响应式重排。
+4. 以桌面样式为默认值，在仓库既有断点内编写移动端差异；当前交付页面族定义断点时使用 `max-width: 767px`。
+5. 验证长内容、可选元素缺失、列表数量变化以及断点两侧布局，不复制桌面端和移动端 DOM。
+
+## 绝对定位
+
+`position: absolute` 只用于 tooltip、dialog 和浮层等真正覆盖层。最近的锚点必须建立定位上下文；覆盖层不得决定父元素高度或兄弟元素流；桌面端和移动端的锚定及溢出行为都必须定义。普通控件、卡片、文本、行和响应式重排保持在正常文档流中。
+
+## 完成条件
+
+每个容器都有明确职责，业务 class 语义保持完整，普通布局基于文档流，允许的覆盖层具有有效锚点，并且代表性的桌面端和移动端内容不重叠、不依赖截图专用坐标时，任务才算完成。

package/plugins/autobest-delivery/skills/ui-structure-guard/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "UI 结构守卫"
+  short_description: "在实现或修复响应式 React 界面时守卫组件与布局结构"
+  default_prompt: "实现或修复当前 React UI 及其样式时使用 $ui-structure-guard。"
+
+policy:
+  allow_implicit_invocation: true

package/skills/README.md

@@ -0,0 +1,38 @@
+# Skills 使用说明
+
+`@autobest-ui/agent` 将 Skills 分为全局通用能力和项目技术栈能力。安装命令会复制完整 Skill 目录，包括 `SKILL.md`、`agents`、`references` 和 `scripts`。
+
+## Common
+
+Common Skills 适用于当前用户的所有项目，安装到 `~/.agents/skills`：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync common
+```
+
+当前包含：
+
+- `figma-ui-capture`
+- `ui-prd-scope`
+
+## React
+
+React Skills 只应用于单个项目。进入项目根目录后运行：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync react
+```
+
+安装目标为当前项目的 `.agents/skills`。也可以显式指定项目目录：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync react /absolute/path/to/project
+```
+
+当前包含：
+
+- `react-code-standards`
+
+再次运行相同命令会更新包内已有的同名文件，不会删除目标 Skill 目录中的额外文件。生产环境可将 `@latest` 替换为明确版本。
+
+Codex 会自动检测 Skill 变更；如果新安装的 Skill 没有出现，请重启 Codex。目录规则参考 [OpenAI Codex Skills 文档](https://developers.openai.com/codex/skills/)。

package/skills/common/figma-ui-capture/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: figma-ui-capture
+description: 采集本地 Figma 当前选中的一个或多个同业务 UI 节点，递归提取可见子树，并按业务、页面及 mobile/desktop 归档为视觉保真精简 JSON 和原始尺寸 PNG；仅在用户明确要求时额外导出图片资源。用户提到 `figma-ui-capture`、要求采集当前 Figma 选择，或需要把选中设计保存为代码生成上下文和截图时使用。只做设计采集和文件保存，不生成或修改业务代码。
+---
+
+# Figma UI 采集
+
+## 工作流
+
+1. 检查当前可用的 Figma MCP 工具并映射能力：
+   - 连接与选择上下文：优先 `connect_figma` / `get_design_context`；本地桥接可用 `figma_server_info` / `figma_get_context`。
+   - 节点读取：本地桥接使用 `figma_get_nodes`，并设置 `depth="full"`。
+   - 截图保存：优先 `save_screenshots`；本地桥接可用 `figma_export_node`。
+   - 仅在图片资源导出模式下检查按图片哈希或节点导出资源的能力。
+2. 确认 Figma 插件已连接。未连接时报告当前桥接端口并停止采集，等待用户完成插件连接；不写入空 JSON 或占位截图。
+3. 获取当前 selection。没有选中节点时停止并要求用户先选择；存在多个节点时保持 Figma 返回顺序，不合并不同根节点。
+4. 在读取完整子树前，按“归档分组与端类型”确定本次唯一的 `businessKey`、`pageKey` 和每个根节点的 `device`。任一信息无法可靠确定时先向用户确认，不根据 UI 内部文案猜测。
+5. 对每个根节点分别递归处理 `childIds`，直到没有未处理的后代。实例内部形如 `I<instanceId>;<childId>` 的复合节点 ID 也必须读取；分批请求以避免响应截断，并记录无法解析的 ID。
+6. 采集阶段保留工具返回的完整字段用于判断；落盘阶段按“视觉保真精简结构”整理成嵌套的可见 UI 树。只删除重复索引、画布坐标和不影响渲染的默认值，不把 MCP 原始批次响应直接落盘。
+7. 按“图片资源模式”和“输出文件”保存每个根节点的 JSON 与原始尺寸 PNG；仅在图片资源导出模式下额外保存图片填充资源。所有实际导出使用 `scale=1`。
+8. 完成“校验标准”的全部检查后再报告结果。
+
+## 归档分组与端类型
+
+### 业务标识
+
+- 每次采集只能对应一个业务，使用规范化后的 `businessKey` 作为目录名。
+- 优先采用用户明确提供的业务标识，例如 `$figma-ui-capture 业务标识 vehicle-selection`。
+- 用户未提供时，仅当所有选中根节点具有可稳定归一的共同业务名称时，才从根节点名称或当前页面的明确业务名称生成。
+- `businessKey` 使用小写 kebab-case，只允许字母、数字和连字符；去除端类型、状态和无业务含义的序号。
+- 同一次 selection 出现不同业务时停止并要求用户分批采集。
+- 无法可靠确定共同业务时停止并询问用户，不从节点内部文字内容推测业务。
+
+### 页面标识
+
+- 每次采集只能对应一个页面，使用规范化后的 `pageKey` 作为 `businessKey` 下的二级目录名。
+- 优先采用用户明确提供的页面标识，例如“home 页面”解析为 `pageKey=home`；同时提供业务和页面时必须分别保留，例如“home 页面车型 vehicle”归档为 `vehicle/home`，不能合并为单个业务标识。
+- 用户未提供时，仅当 Figma 当前页面名称或所有选中根节点的共同命名能明确表示同一页面时，才据此生成 `pageKey`。
+- `pageKey` 使用小写 kebab-case，只允许字母、数字和连字符；去除端类型、状态和无页面含义的序号。
+- 同一次 selection 出现不同页面时停止并要求用户分批采集。无法可靠确定页面时停止并询问用户，不默认写入业务根目录。
+
+### 端类型
+
+每个选中根节点独立判定 `device`，值只能是 `mobile` 或 `desktop`，按以下优先级：
+
+1. 用户为节点明确指定的端类型。
+2. 根节点名称中明确的 `[mobile]`、`[desktop]`、`-mobile`、`-desktop` 或等价端类型标记。
+3. 当名称没有端类型且尺寸语义无冲突时，根节点宽度不大于 767 px 判定为 `mobile`，大于 767 px 判定为 `desktop`。
+
+尺寸与名称或设计语义冲突、根节点不是完整端视图而宽度不足以判断，或者结果存在歧义时，停止并询问用户。
+
+### 变体与冲突
+
+- 同一业务可以在一次 selection 中同时包含一个 mobile 根节点和一个 desktop 根节点。
+- 同一端类型存在多个根节点时，必须从用户输入或明确的根节点名称取得稳定的 `variant`；不能用 selection 序号表达业务含义。
+- `variant` 使用小写 kebab-case，并生成 `{device}-{variant}` 文件名前缀。
+- 目标文件已存在时，仅在用户明确要求更新同一设计时覆盖；否则停止并报告冲突。
+
+## 视觉保真精简结构
+
+### 保真预算
+
+- 精简目标是减少重复字段，不是追求固定压缩率。不得为了缩小 JSON 删除会影响尺寸、间距、背景、裁切、文字换行或视觉效果的字段。
+- 每个节点同时保留最终几何结果和布局语义：生成器用布局语义实现结构，用相对位置校准实际间距。
+- 不保存 MCP 原始批次响应；将节点按当前可见层级嵌套，每个字段只保留一份。
+
+### 基础信息
+
+- 所有可见节点保留 `id`、`name`、`type`、`size: [width, height]`。
+- 所有非根节点保留相对父节点的 `position: [x, y]`，包括 Auto Layout 子节点。该字段是最终渲染位置的校准基准，不用画布绝对坐标替代。
+- 通过嵌套 `children` 表达层级，不重复保存 `parentId`、`childIds` 或 `childCount`。
+- 仅当节点旋转角度不为 0 时保留 `rotation`。
+- 顶层记录 `businessKey`、`pageKey`、`device`、`assets`、`unresolvedNodeIds`、`unresolvedTextStyleNodeIds` 和 `unresolvedImageAssetNodeIds`；存在变体时记录 `variant`。
+
+### 布局与间距
+
+- 有 Auto Layout 时输出 `layout` 对象。
+- `direction` 使用 `horizontal` 或 `vertical`。
+- `sizing` 使用 `[primaryAxisSizingMode, counterAxisSizingMode]`。
+- `justify`、`align` 分别保存主轴和交叉轴对齐。
+- `padding` 使用 `[top, right, bottom, left]`；四边均为 0 时省略。
+- `itemSpacing` 输出为 `gap`；值为 0 时省略。
+- 工具返回时，在非默认状态下输出 `wrap`、`counterGap`、`layoutGrow`、`layoutAlign`、`layoutPositioning`、`minWidth`、`maxWidth`、`minHeight`、`maxHeight` 和 `constraints`。
+- `clipsContent=true` 时输出 `clip: true`；false 时省略。
+- 节点存在非默认 `blendMode`、遮罩属性或影响渲染的布局属性时必须保留。
+
+### 背景、边框与视觉样式
+
+- 单一纯色填充输出为 `fill: "#RRGGBB"`；颜色统一转换为 CSS 十六进制，存在透明度时使用 `#RRGGBBAA`。
+- 渐变、图片或多重填充使用 `fills`。
+- 渐变保留类型、全部色标、色标位置、`gradientTransform` 或等价变换、填充透明度和非默认混合模式。
+- 图片填充保留 `imageRef` / `imageHash`、`scaleMode`、`scalingFactor`、非零旋转、非默认 `imageTransform`、非零 filters、透明度和非默认混合模式。
+- 存在边框时输出 `border`，包含 `color`、`width`、`align`；四边宽度不同时再输出各边宽度。
+- 统一圆角且大于 0 时输出 `radius`；四角不同时输出四角值。
+- `opacity` 仅在不等于 1 时输出。
+- `effects` 仅在非空时输出，保留类型、颜色及 alpha、offset、radius、spread、非默认混合模式和其他改变当前渲染的字段。
+
+### 文字内容与字体
+
+所有可见 TEXT 节点输出 `text` 对象，并保留：
+
+- `content`：完整 `characters`，不得截断或概括。
+- `family`、`style`、`weight`、`size`。
+- `lineHeight`、`letterSpacing`。
+- `align: [textAlignHorizontal, textAlignVertical]`。
+- 非默认的 `textCase`、`textDecoration`、`paragraphSpacing`、`paragraphIndent` 和 `textAutoResize`。
+- 文字颜色使用节点的 `fill`；存在文字描边或透明度时保留对应值。
+- 存在混合文字样式时，保留每个文本区间及其对应样式。
+- 工具无法返回混合文字分段时，不推测字体，也不终止其他产物：对应文字字段写 `null`，并将节点 ID 记录到顶层 `unresolvedTextStyleNodeIds`。
+
+### 组件与变量
+
+- 组件或变量仅在会改变当前渲染结果，或代码生成需要映射设计 token 时保留引用。
+- 空的 `boundVariables`、空的 `explicitVariableModes` 和未使用的 `styleId` 一律省略。
+- 最终 JSON 必须保留当前模式下解析后的实际尺寸、颜色和文字样式，不能只保存变量引用。
+
+### 隐藏分支
+
+- 遇到 `visible=false` 的节点时省略整个隐藏分支。
+- 在顶层记录 `omittedHiddenBranches` 数量。
+- 隐藏节点不参与当前截图对应的代码生成上下文和采集节点计数。
+
+### 图片资源模式
+
+- 默认使用元数据模式：不导出设计图中的图片填充资源，不创建 `assets/` 目录，不调用仅用于资源导出的工具，也不在 paint 中写 `assetPath`。
+- 只有用户明确要求“导出图片资源”“拉取原图”“生成 assets 文件夹”或同等含义时，才使用图片资源导出模式。不能仅因设计中存在 IMAGE fill、用户要求截图或用户要求视觉保真 JSON 而自动启用。
+- 两种模式都必须保留完整图片 paint 元数据，包括 `imageRef` / `imageHash`、`scaleMode`、`scalingFactor`、裁切与变换、filters、透明度和混合模式。
+- 为保持 JSON 结构稳定，元数据模式下顶层 `assets` 和 `unresolvedImageAssetNodeIds` 均写空数组；有意不导出的图片不属于缺失资源或解析失败。
+- 图片资源导出模式下，对每个包含可见 IMAGE fill 的节点导出 `scale=1` PNG，并在顶层 `assets` 中记录 `nodeId`、相对 `path`、`imageRef`、`size` 和 `includesVisibleChildren`。
+- 图片资源导出模式下，叶子图片节点的资源可直接实现该 fill，将相对路径同时写入对应 paint 的 `assetPath`。图片填充容器含可见子节点时，导出结果是节点合成图，设置 `includesVisibleChildren: true`，不得误当作纯背景图。
+- 图片资源导出模式下，工具能按 image hash 导出原始填充时，优先导出原始填充并设置 `includesVisibleChildren: false`；导出失败时保留完整图片 paint 信息，并将节点 ID 记录到顶层 `unresolvedImageAssetNodeIds`。
+
+## 必须省略的噪声
+
+- `pageId`、`parentId`、`childIds`、`childCount` 和画布级 `absoluteBoundingBox`；用嵌套层级、节点 `id`、相对 `position` 和 `size` 表达同一信息。
+- `locked=false`、`visible=true`、`rotation=0`、`opacity=1`。
+- 空的 `fills`、`strokes`、`effects`、`boundVariables` 和变量模式。
+- 默认 `constraints`、0 圆角、0 padding、0 gap 和 false 布尔值。
+- paint 上重复的 `visible=true`、`opacity=1`、`blendMode=NORMAL`、单位 image transform、全零 filters 和空 `boundVariables`。
+- Figma 画布绝对坐标、重复的节点计数和可由嵌套树恢复的关系索引。
+- 不得省略节点 `id`、相对 `position`、图片裁切/变换、渐变变换、分边框、文字换行字段或其他影响当前 PNG 的值。
+
+## 输出文件
+
+- 输出目录为 `.scratch/figma-captures/{businessKey}/{pageKey}/`。业务是一级分组，页面是二级分组，不得省略或调换层级。
+- 每个无变体根节点分别生成：
+  - `.scratch/figma-captures/{businessKey}/{pageKey}/{device}.json`
+  - `.scratch/figma-captures/{businessKey}/{pageKey}/{device}.png`
+- 同一端类型存在多个变体时分别生成：
+  - `.scratch/figma-captures/{businessKey}/{pageKey}/{device}-{variant}.json`
+  - `.scratch/figma-captures/{businessKey}/{pageKey}/{device}-{variant}.png`
+- 每个 JSON 只包含对应根节点的可见子树。
+- JSON 与 PNG 必须使用相同文件名前缀。
+- 仅在图片资源导出模式下创建 `assets/` 并将每个根节点的图片资源保存到：
+  - `.scratch/figma-captures/{businessKey}/{pageKey}/assets/{device}/`
+  - 有变体时保存到 `.scratch/figma-captures/{businessKey}/{pageKey}/assets/{device}-{variant}/`
+- 资源文件名使用规范化节点名加节点 ID，确保同名节点不会覆盖。
+- 截图使用节点原始尺寸：调用 `save_screenshots` 时设置 `scale=1`；没有该工具时调用 `figma_export_node`，设置 `format="PNG"`、`scale=1` 和目标输出路径。
+
+示例：
+
+```text
+.scratch/figma-captures/vehicle/home/
+|-- desktop.json
+|-- desktop.png
+|-- mobile.json
+|-- mobile.png
+```
+
+图片资源导出模式会在同级额外生成 `assets/{device}/`；存在变体时使用 `assets/{device}-{variant}/`。
+
+## 校验标准
+
+- 除明确省略的隐藏分支外，所有已发现的 `childIds` 都能在 `children` 树中找到对应节点，且所有节点 `id` 唯一。
+- 所有非根可见节点都有相对 `position`；检查同一父级下的 position、size、padding 和 gap 能解释截图中的最终间距。
+- 所有可见 TEXT 节点都包含完整 `content` 和文字几何字段；缺失的混合样式只允许出现在 `unresolvedTextStyleNodeIds`。
+- 所有可见容器都包含实现当前 UI 所需的尺寸、布局、间距、背景、边框和圆角信息。
+- 将无法解析的节点 ID 写入顶层 `unresolvedNodeIds`；全部解析成功时写空数组。
+- 元数据模式下确认 `assets` 和 `unresolvedImageAssetNodeIds` 均为空数组、paint 不含 `assetPath`，并且输出目录中没有为本次采集创建 `assets/`。
+- 图片资源导出模式下，每个 IMAGE fill 都有可用资源或出现在 `unresolvedImageAssetNodeIds`，且 `assets` 记录与文件系统逐项一致。
+- 确认 `businessKey` 和 `pageKey` 已规范化，输出路径严格位于对应的 `{businessKey}/{pageKey}/` 目录。
+- 确认每个根节点的 `device` 为 `mobile` 或 `desktop`；存在变体时 `variant` 已规范化。
+- 确认 JSON 与 PNG 使用相同文件名前缀，并且没有未确认的同名文件覆盖。
+- 确认 JSON 可以解析，PNG 文件存在且像素尺寸与选中节点的原始尺寸一致。
+- 检查最终 JSON 中不存在“必须省略的噪声”。文件较大时只继续删除重复关系、画布坐标和默认值，不以固定压缩率为目标，也不删除视觉保真字段。
+
+## 边界
+
+- 只读取 Figma，并只在项目 `.scratch/` 下创建或更新本次采集的 JSON、PNG，以及用户明确要求导出时的图片资源。
+- 保持 Figma 当前 selection 和文档内容不变，不调用节点、样式、变量或页面修改工具。
+- 不创建、修改或建议业务组件、样式、配置、依赖和测试代码。
+- 不终止其他 Codex/Figma 桥接进程，不改 MCP 配置来抢占端口。
+- 工具能力不足以满足规则时，报告缺失能力和未完成产物，不以推测数据补齐。
+
+## 完成响应
+
+成功时只汇总每个选中节点的 JSON 路径、PNG 路径、图片资源模式、业务标识、页面标识、端类型、变体（如有）、节点名称、节点 ID、采集节点数、未解析节点数和缺失文字样式数；仅在图片资源导出模式下额外汇总资源目录、资源数和缺失图片资源数。失败时只报告阻塞原因、所需用户动作和未生成的文件。

package/skills/common/figma-ui-capture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Figma UI Capture"
+  short_description: "Capture Figma UI as fidelity-focused JSON and PNG"
+  default_prompt: "Use $figma-ui-capture to capture the selected Figma UI as visual-fidelity JSON and original-size PNG files grouped by business and page. Export image assets only when I explicitly request them."

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

@@ -0,0 +1,67 @@
+---
+name: ui-prd-scope
+description: 通过 MCP 拉取 Azure DevOps PRD PR，按共享 UI 页面族拆分变更需求，并用应用端 RAG、本地 Figma 采集、仓库启动/路由/权限信息和待质询问题补全各 scope，最终生成可用于后续质询和规格编写的自包含页面范围包。用户提供 Azure PRD PR 链接，或要求从 PRD 变更生成、刷新 UI 页面 scope 时使用。不要用于实现 UI 代码或评审实现结果。
+---
+
+# UI PRD 范围拆分
+
+为每个共享 UI 页面族生成一个自包含的 `scope.md`。后续提示只需读取该文件及其中声明的本地图片。
+
+## 必需输入
+
+- Azure DevOps PR 链接。保留用户提供的 `path` 查询参数，使 PR bridge 只读取指定 PRD 子树。
+- RAG 平台：只有来源明确属于 APP（例如 `/Frontend_APP`）时才推断为 `app`；否则检索前询问用户。
+- 输出根目录：用户未指定时使用 `.scratch/page-scope`。不同 PR 必须隔离，不能混入同一范围包。
+- Figma 采集根目录：存在 `.scratch/figma-captures` 时使用该目录。
+
+## 工作流程
+
+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 溯源。
+   - 输出根目录已有相同 PR/path 的 manifest 时，只刷新该 manifest 所属文件。在 manifest 或报告中标记失效 scope；只有用户确认后才能删除。
+   - 目录属于其他 PR，或包含没有身份信息的旧文件时，默认写入 `<output-root>/pr-<id>`；用户明确授权迁移时除外。不得静默混合两个 PR。
+4. 写入前建立来源清单。先分离全局规则和页面规则，再按共享 UI 模板分组，不能按文档或 URL 机械拆分。用户提供的页面族分类优先。否则依据布局/DOM、工作流/状态、模块所有权和数据契约记录合并或拆分理由。同一 UI 的不同 URL 作为变体；用户明确认定为一个页面族时，局部差异本身不构成拆分理由。
+5. 每个页面族创建一个目录，以单一 `scope.md` 作为后续提示入口，并在同目录放置匹配的 Figma JSON/PNG。根目录保留精简的 `README.md` 索引，可选创建 `00-global/scope.md` 作为全局规则依据。
+6. 对每个页面族分别调用 `mcp__rag_mcp_bridge__retrieve_knowledge`：
+   - 始终传入明确的 `platform`。
+   - 知识库分类支持时传入 page/module 过滤条件。
+   - 分别检索页面行为、适用的跨页能力、状态、状态转换、空态/错误态和权限。使用多个聚焦查询，而不是一个宽泛查询。
+   - 保留 `doc_name`、`doc_id`、相关原文和未命中结果。
+   - 在 scope 中写入精简查询台账：查询重点、platform/module/page 过滤条件、命中文档或未命中。只查询一个跨页模块，却未检索其他范围内行为时，该 scope 不完整。
+   - 用 `hit`、`no-hit`、`not-applicable` 标记 `businessRules`、`statesTransitions`、`emptyErrors`、`permissions`、`crossPage` 的覆盖状态。只有用户明确缩小检索范围时才能使用 `deferred-by-user`，并记录原因。
+   - 跨页命中只有在原文明确提及目标页面或确属共享规则时，才能作为该页面证据。
+   - 本流程不得调用 `add_prd_file` 或 `update_spec_file`。
+7. 从仓库一手来源确认运行信息。每个 scope 都要确认 workspace/package、源码模块、路由模式、本地 URL、启动命令/端口、登录门禁、必需 URL 参数、API/运营数据、第三方依赖和需开发补充的 fixture。只按需读取配置，不修改红区文件，不暴露密钥或环境值。
+8. 整合 Figma：
+   - 根据目录语义，以及 JSON 中的 `businessKey`、`pageKey`、`device`、`variant`、`root.id`、`root.size` 匹配采集物。
+   - 将无歧义的匹配资产复制到页面目录，并在 manifest 记录原路径。只有用户明确要求时才移动源文件。未匹配资产保留原位。
+   - 在 `scope.md` 中列出每一组本地 JSON/PNG；只总结设计证据直接支持的布局和状态，不转储原始 JSON。
+   - 按 PRD 改动点标明每个资产覆盖的组件、设备和状态。只在改动点缺少必需视觉证据时记录待补采；局部组件改动不要求完整页面截图。不得把组件截图静默当作完整页面设计，也不得因它不是整页而把已覆盖的局部改动误报为缺失。
+9. 创建或重写页面 scope 前，读取 [references/scope-schema.md](references/scope-schema.md)。把适用的全局规则展开到各页面文档中。每个页面 scope 都要重复 Azure PR 链接、证据类型和完整 RAG 溯源，不依赖 README、全局文件或研究笔记才能理解。RAG 事实放在它所补充的功能或状态附近并附引用；不要另建后续提示必须读取的 RAG 或问题文档。
+10. 按以下优先级处理证据：当前 PRD 明确业务规则、当前 Figma 视觉证据、RAG 历史 PRD、仓库当前实现。冲突保留在“待质询”；实现证据只描述当前约束，不能覆盖新需求。
+11. 执行校验：
+
+```bash
+node .agents/skills/ui-prd-scope/scripts/validate-scope-bundle.mjs <实际输出根目录>
+```
+
+同时运行 `git diff --check`，并用 `git status --short --ignored` 检查输出。本仓库没有自动化测试脚本，最终说明应准确描述文档校验结果。
+
+## 完成标准
+
+- 每个变更 PRD 文件都映射到全局 scope、页面族 scope 或明确的证据缺口。
+- `scope-manifest.json` 能识别 PR，并与 README 和实际 scope 目录完全一致。
+- 每个页面 scope 都包含需求来源、运行环境/模块、改动边界、URL、权限/前置条件、Figma 状态、带溯源的页面级 RAG 和待质询问题。
+- 每个 RAG 覆盖领域都标记为命中、未命中、不适用或由用户明确暂缓；隐含的未检索缺口视为错误。
+- 每个页面族的合并/拆分都有依据，或明确引用用户提供的分类。
+- 每个本地资产链接有效，同目录 JSON 均可解析。
+- 缺少不可从仓库获得的路由/环境前置、业务数据、权限、改动点所需 Figma 状态或 RAG 证据时，明确由开发、产品、设计或后续质询补充。仓库可发现的运行事实由后续角色自行解析，不转嫁为用户实时输入。
+- 最终答复链接范围索引，列出页面族，汇总未命中和阻塞缺口，并说明未修改业务代码。
+
+## 边界
+
+- 只生成 scope 上下文。除非用户另行要求，否则不实现 UI、不启动固定端口服务、不创建 `spec.md`、不执行质询。
+- 仓库只能证明本地路由模板或运行时域名时，不得声称存在公开或生产网站链接。
+- 审计所需的来源研究笔记放在 page-scope 根目录之外；`scope.md` 始终是页面的唯一提示入口。

package/skills/common/ui-prd-scope/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UI PRD 范围拆分"
+  short_description: "将 Azure PRD PR 拆成页面族范围包"
+  default_prompt: "使用 $ui-prd-scope 拉取这个 Azure PRD PR，按页面族拆分，并为每个 scope 补充 RAG、Figma、运行方式、URL、权限和待质询信息。"

package/skills/common/ui-prd-scope/references/scope-schema.md

@@ -0,0 +1,158 @@
+# Scope 范围包规范
+
+创建或重写 page-scope 文档前必须完整读取本规范。
+
+## 目录结构
+
+```text
+.scratch/page-scope/
+|-- README.md
+|-- scope-manifest.json
+|-- 00-global/
+|   `-- scope.md
+`-- <nn-page-family>/
+    |-- scope.md
+    |-- <device>[-<variant>].json
+    |-- <device>[-<variant>].png
+    `-- spec.md                  # 后续创建，本技能不得生成
+```
+
+目录名使用稳定、有序、小写的 kebab-case。页面族代表共享 UI 模板；URL 变体保留在同一文档中。
+
+`scope-manifest.json` 是审计元数据，不是后续提示输入。字段名和状态枚举是机器契约，保持以下英文原值：
+
+```json
+{
+  "schemaVersion": 1,
+  "prId": "<Azure PR ID>",
+  "prUrl": "<完整 PR 链接>",
+  "requestedPath": "<PR path 过滤条件或 null>",
+  "ragPlatform": "app",
+  "changedSources": ["<Azure bridge 返回的每个变更 PRD 路径>"],
+  "scopes": [
+    {
+      "directory": "01-page-family",
+      "pageFamily": "<页面族>",
+      "decision": "<用户分类或合并/拆分依据>",
+      "sourceFiles": ["/Frontend_APP/..."],
+      "ragCoverage": {
+        "businessRules": "hit",
+        "statesTransitions": "hit",
+        "emptyErrors": "no-hit",
+        "permissions": "no-hit",
+        "crossPage": "not-applicable"
+      }
+    }
+  ],
+  "unmappedSources": [],
+  "figmaSources": [
+    {
+      "scope": "01-page-family",
+      "source": ".scratch/figma-captures/example",
+      "destination": ".scratch/page-scope/01-page-family",
+      "operation": "copy",
+      "sourceStatus": "present"
+    }
+  ]
+}
+```
+
+每条 Figma 溯源记录必须指向 manifest 中已有的 scope 和实际存在的目标目录。默认使用 `operation: "copy"`，并要求源文件继续存在。只有用户明确要求移动时才能使用 `operation: "move"`。`operation: "legacy-move"` 与 `sourceStatus: "not-present-after-move"` 只用于审计本技能采用默认复制策略之前已移动的历史资产。
+
+## 页面 Scope 模板
+
+```markdown
+# <章节> <页面族> 范围
+
+## 需求来源
+
+- Azure PR: <URL>
+- PRD: `<变更文档路径>`
+- 证据类型：`PR 增量` | `完整基线` | `用户提供的摘要`
+
+## 项目运行与访问
+
+| 项目 | 内容 |
+| --- | --- |
+| 工作区 | `<workspace/package>` |
+| 页面模块 | `<源码目录和 ModuleType>` |
+| 启动 | `<仓库已有命令和端口>` |
+| 本地 URL | `<localhost 路由模板>` |
+| 权限 | `<登录门禁或明确无门禁>` |
+| 数据前置 | `<decode、车型、站点、API、第三方 fixture>` |
+
+依据：`<一手来源路径>`。<由开发补充的缺失输入>。
+
+## 页面族
+
+合并依据：<用户提供的分类，或共享布局/工作流/所有权证据>。
+
+| 变体 | 共用 UI | 差异 |
+| --- | --- | --- |
+
+## 改动范围
+
+- <PRD 变更边界>
+
+## 范围外
+
+- <明确排除或暂缓的页面>
+
+## Figma 输入
+
+| 覆盖内容 | 设备 | 变体 | JSON | 截图 | 根节点/尺寸 |
+| --- | --- | --- | --- | --- | --- |
+
+说明采集物覆盖完整页面还是局部组件，并把每项资产映射到 PRD 改动点。只列出改动点缺失的必需设备和状态；局部组件改动不要求完整页面截图，不得把局部资产当作整页证据，也不得把已覆盖的局部改动误报为缺少整页设计。
+
+## RAG 补充
+
+来源：RAG `<platform / module / page>`，`<doc_name>`（doc_id: `<id>`）。
+
+| 查询重点 | 过滤条件 | 结果 |
+| --- | --- | --- |
+| <行为/状态/错误/权限> | `platform=... module=... page=...` | `<doc_name> / doc_id` 或 `未命中` |
+
+| 覆盖领域 | 状态 |
+| --- | --- |
+| businessRules | `hit` / `no-hit` / `not-applicable` / `deferred-by-user` |
+| statesTransitions | ... |
+| emptyErrors | ... |
+| permissions | ... |
+| crossPage | ... |
+
+把检索事实放到它所解释的页面功能或状态下。明确标记未命中查询和证据缺口。仓库代码证据不能描述成 RAG PRD 证据。
+
+任一状态为 `deferred-by-user` 时，用一句话引用用户缩小检索范围的要求。否则所有范围内领域都必须查询，即使结果为未命中。
+
+## 待质询
+
+- <冲突、歧义、缺失的 URL/数据/权限/设计/行为>
+```
+
+PR 或 RAG 提供了有用的状态、转换、SEO 或响应式规则时，可以在“改动范围”和“Figma 输入”之间增加功能章节。scope 只描述边界和必要细节；组件实现与完整验收场景留给后续 `spec.md`。
+
+## 全局 Scope
+
+全局文档可以省略“页面族”，并用“范围”代替“改动范围”。它记录共享来源、默认启动方式、设计约定、SEO、车型/会话规则、跨页转换和全局问题。
+
+页面文档保持自包含：精简重复适用的全局结论，不要求后续提示额外读取 `00-global/scope.md`。
+
+## 溯源规则
+
+- Azure 来源路径必须与 bridge 返回值完全一致。
+- RAG 引用包含 platform、过滤条件、`doc_name` 和 `doc_id`。
+- 运行环境、模块和路由结论引用仓库路径；可行时附行号。
+- 本地链接是 localhost URL；网站链接必须由环境/品牌来源证明或由开发提供，两者不能互相替代。
+- “无登录门禁”不代表“没有前置条件”。分别记录 session GUID、Save Vehicle、解码路由、运营目录、API、测试账号和第三方配置。
+- 每个页面 scope 重复 PR 链接和证据类型。README 和 manifest 只是索引，不能作为必需上下文。
+
+## 缺失信息归属
+
+| 缺失项 | 负责人/处理方式 |
+| --- | --- |
+| 完整 PRD 基线或冲突的业务行为 | 产品/后续质询 |
+| Desktop/Mobile/状态采集 | 设计/人工 Figma 采集 |
+| 有效动态 URL、测试车型、API fixture、未实现的路由/模块 | 开发 |
+| 登录账号、外部服务凭据、环境权限 | 开发/QA；使用前申请授权 |
+| RAG 未命中 | 保留为证据缺口，不从相似页面推断 |