@dev-workflow/skill 0.1.0

package/skills/execution/devFlow/domains/requirement/references/prd-review.md

@@ -0,0 +1,129 @@
+# prd-review 子命令
+
+`prd-review` 用于在需求进入 `page-tech` / `api-tech` 之前，按固定 checklist 审查一份 PRD，找出缺失、风险和技术冲突，产出可决策的问题清单。它不是需求整理、不是方案设计、不是视觉一致性检查，也不产出业务判断。
+
+## 边界
+
+- 不改 PRD：只输出问题清单，让人决策。
+- 不推方案：具体解法留给 `page-tech` / `api-tech`。
+- 不做视觉一致性：属于 `consistency-checker` skill 的对齐边。
+- 不做业务价值评估：只从技术侧给判断，产品价值由 PM 或用户拍板。
+- 不做 L0 / L1 的快速审查：那种档位走不到本子命令。
+
+## 输入规则
+
+支持三种输入来源，处理方式不同：
+
+1. 本地 Markdown 文件：直接读取，路径必须相对仓库根目录。
+2. 飞书文档链接：必须先执行 `lark-read`，读取并结构化后再作为输入，不得只凭链接标题或用户转述猜测。
+3. 其他形式（Word、PDF、图片、聊天记录）：必须先转成 Markdown 或粘贴到本地 md 文件后再进入本子命令。
+
+读取失败时停止审查并说明原因，不得基于空上下文生成问题清单。
+
+## 审查维度 checklist
+
+审查维度分三类，每次审查按顺序过一遍。PRD 未涉及的维度写入「本次未审查的项」段，不得静默跳过。
+
+### 缺失维度（M-Missing）
+
+产品口径本应写清但未写清。
+
+| 码 | 维度 | 要点 |
+| --- | --- | --- |
+| M1 | 需求列表完整性 | 编号连续或跳号明确；优先级、功能模块归属、飞书追溯链接齐全 |
+| M2 | 权限口径 | 谁能看、谁能改；前端 route guard 还是后端 API 校验；超级管理员豁免规则 |
+| M3 | 数据口径 | 数据范围（ALL / DEPT / GROUP / SELF）；计算原则；离职、停用、复职的联动 |
+| M4 | 字段格式 | 命名规则、长度上限、是否可重复、大小写敏感、变量插值占位符标注 |
+| M5 | 状态机 | 所有状态节点、允许的流转、每次流转的触发者和触发时机 |
+| M6 | 边界与异常 | 空数据、失败、无权限、重复提交、并发冲突、部分数据缺失 |
+| M7 | 操作日志覆盖率 | 每个新增、编辑、删除、状态变更、批量操作是否在日志范围内 |
+| M8 | 兼容策略 | 历史数据迁移、旧版本用户和角色的映射、废弃能力的收敛路径 |
+| M9 | 文案与 i18n | 变量插值占位符是否标明、中英文覆盖、错误提示是否统一 |
+| M10 | 交互细节 | 溢出、loading、空态、未保存离开、失败重试、批量确认 |
+
+### 风险维度（R-Risk）
+
+技术能做但代价大或依赖多，需要主动指出让人决策。
+
+| 码 | 维度 | 要点 |
+| --- | --- | --- |
+| R1 | 高成本 / 低价值 | 实现成本高但业务价值不明显的功能点 |
+| R2 | 依赖上下游未定 | 依赖尚未确定或尚未开发的上下游系统 |
+| R3 | 跨团队协作未明责 | 涉及多方协作但未明确谁负责哪部分 |
+| R4 | 数据迁移无回滚 | 涉及数据迁移但未定义回滚策略 |
+| R5 | 权限重构无灰度 | 涉及权限重构但未定义灰度或降级方案 |
+
+### 冲突维度（C-Conflict）
+
+技术做不了、成本远超收益、或与现有系统 / 规范 / PRD 内部矛盾。
+
+| 码 | 维度 | 要点 |
+| --- | --- | --- |
+| C1 | 技术无法实现 | 例：依赖飞书 Open API 不支持的能力；依赖浏览器不允许的 API |
+| C2 | 与代码 / 组件契约冲突 | 与仓库中现有 route、service、组件 props、状态模式冲突 |
+| C3 | 与产品设计规范冲突 | 与 `domains/frontend/references/product-design-specs/` 中已确定的字段、交互、反馈规范冲突 |
+| C4 | 需求内部矛盾 | A 章节说 X，B 章节说非 X；表格与正文表述不一致 |
+| C5 | 与接口能力冲突 | 需求依赖某接口能力但接口文档或仓库代码显示不支持 |
+
+## 严重度分级
+
+只用三档，不用 P0 / P1 / P2，因为产品评审语境下三档更直观。
+
+| 档 | 判定口径 | 处理时机 |
+| --- | --- | --- |
+| 🔴 阻塞 | 不解决无法进入 `page-tech` / `api-tech`；缺失该项会直接影响方案主结构；技术无法实现 | 必须在进入下游子命令前解决 |
+| 🟡 严重 | 可以启动方案生成，但必须在 `page-build` 或后端联调前解决；影响接口契约、数据结构、状态机 | 必须在下游落地前解决 |
+| 🟢 商榷 | 不影响主链路，但评审会需要同步；影响交互细节、文案、边界体验 | 评审会同步即可 |
+
+分档硬规则：
+
+- 冲突维度中的 C1（技术无法实现）、C4（需求内部矛盾）默认 🔴。
+- 缺失维度中的 M2、M3、M5 默认至少 🟡；影响入口可见性或核心状态流转时升 🔴。
+- 风险维度中的 R4（数据迁移无回滚）、R5（权限重构无灰度）默认 🟡。
+- 其他条目根据具体影响判定，判定理由必须写进条目的「影响」字段。
+
+## 工作流程
+
+1. 读入 PRD 上下文（本地 md 或 `lark-read` 输出）。
+2. 按 M1-M10、R1-R5、C1-C5 顺序逐维度扫一遍；每条命中都要锚到 `文件:行号` 或章节标题。
+3. 分档：按上面的分档硬规则和判定口径给每条问题标 🔴 / 🟡 / 🟢。
+4. 分组输出：阻塞、严重、商榷三段；同段内按维度码升序排列。
+5. 补写「通过的检查项」和「本次未审查的项」两段，让人能看出覆盖范围。
+6. 按档位决定产物形态：
+   - L0 / L1：不跑本子命令。
+   - L2：允许对话内出结论，也允许落 md，由用户选择。
+   - L3：必须落 `prd-review.md`。
+
+## 产物路径规则
+
+- 默认落到 PRD 所在目录，命名 `prd-review.md`。
+- 如同目录已存在 `prd-review.md`，追加时间戳后缀，例如 `prd-review-20260713.md`；不覆盖已有报告。
+- L0 / L1 不强制落 md，对话内给结论即可。
+
+## 与下游的衔接
+
+- 🔴 阻塞项未消除，不得进入 `page-tech` / `api-tech`；如用户强行推进，必须在下游产物的「风险与待确认项」中把阻塞项原样带过去。
+- 🟡 严重项可以进入 `page-tech` / `api-tech`，但必须在下游文档的「风险与待确认项」中出现。
+- 🟢 商榷项不阻塞任何下游动作，但必须保留在 `prd-review.md` 中作为评审留痕。
+
+## 飞书上下文规则
+
+如果 PRD 是飞书链接，必须先 `lark-read`，再进入本子命令；不得只根据链接标题猜测。读取失败时停止审查，说明失败原因，不得基于空上下文出问题清单。
+
+## 写作原则
+
+- 每条问题都要锚到 `文件:行号` 或明确的章节标题。
+- 每条问题的「建议」字段必须具体到能直接问 PM、后端或前端负责人，例如：「入口可见性判断口径是前端 route guard 还是后端 API 校验？」。
+- 不臆想需求、接口字段、组件、权限、指标。
+- 冲突项不得自行取舍，必须列出冲突双方，由用户或对应负责人决策。
+- 通过的检查项也要列出来，让人能看出覆盖范围，避免只看到问题不看到扫过的面。
+
+## 交付前自检
+
+生成问题清单后，人工自检以下项：
+
+- 每条问题都有位置锚点（文件:行号或章节标题）。
+- 每条问题都有明确的档位（🔴 / 🟡 / 🟢）。
+- 每条问题的「建议」字段具体、可直接提问。
+- 「通过的检查项」和「本次未审查的项」两段都存在。
+- 未把 PM 决策范围的问题（业务价值、优先级）当成技术问题输出。

package/skills/execution/devFlow/domains/requirement/templates/prd-review.md

@@ -0,0 +1,57 @@
+<!-- prd-review 模板。生成正式文档时删除所有 HTML 注释。 -->
+<!-- 分档标记：🔴 阻塞（不解决无法进入 page-tech / api-tech）｜🟡 严重（必须在 page-build 或联调前解决）｜🟢 商榷（评审会同步即可）。 -->
+
+# PRD 审查报告：<PRD 相对路径>
+
+## 审查范围
+
+- 文档：`<PRD 相对路径>`
+- 审查时间：`<YYYY-MM-DD>`
+- 审查维度：M1-M10、R1-R5、C1-C5
+- 输入来源：<本地 md / 飞书链接（已 lark-read）>
+
+## 🔴 阻塞
+
+<!-- 空则写「本轮审查未发现阻塞项」。 -->
+
+### #1 [维度码] <一句话摘要>
+
+- 位置：`<file:line 或 章节标题>`
+- 现状：<PRD 中是怎么写的>
+- 影响：<不解决会导致什么，为什么定为阻塞>
+- 建议：<可直接问 PM / 后端 / 前端的问题，或建议方向>
+
+## 🟡 严重
+
+<!-- 空则写「本轮审查未发现严重项」。 -->
+
+### #1 [维度码] <一句话摘要>
+
+- 位置：`<file:line 或 章节标题>`
+- 现状：<PRD 中是怎么写的>
+- 影响：<不解决会导致什么>
+- 建议：<可直接提问或建议方向>
+
+## 🟢 商榷
+
+<!-- 空则写「本轮审查未发现商榷项」。 -->
+
+### #1 [维度码] <一句话摘要>
+
+- 位置：`<file:line 或 章节标题>`
+- 现状：<PRD 中是怎么写的>
+- 影响：<不解决会导致什么>
+- 建议：<可直接提问或建议方向>
+
+## 通过的检查项
+
+<!-- 按维度码升序列出扫过并通过的项，让审阅者看到覆盖范围。 -->
+
+- ✅ <维度码> <被检查项摘要>
+- ✅ <维度码> <被检查项摘要>
+
+## 本次未审查的项
+
+<!-- PRD 完全未涉及该维度时，写在这里，避免静默跳过。 -->
+
+- ⏭ <维度码> <被检查项>：<跳过原因，如「本期不做」「PRD 未提及且不属于本次范围」> 

package/skills/execution/figmaSync/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: figmaSync
+description:
+  Figma → 原生 CSS 落地规划工作流。命令路由：`figmaSync prepare`
+  检查环境；`figmaSync plan <figma-url>` 先读取真实页面基建和
+  foundation-summary，再分析设计稿，匹配 /theme CSS 变量、 Apex UI、common
+  component 与 assets，并落地 PLAN.md + figma-plan.css 草案； `figmaSync apply
+  [path]` 根据已审核 PLAN.md 和 CSS 草案实施编码。
+---
+
+# Figma to Native CSS (`/figmaSync`)
+
+## 对齐边诊断
+
+| 项 | 值 |
+|---|---|
+| 服务对齐边 | UI↔前端 |
+| 现状分级 | 结构性不健康 |
+| AI 形态 | 兜底 + 校准 |
+| 主战场 | 开发中 |
+
+## 这个 skill 解决什么问题
+
+把 Figma 视觉稿落成可审核的原生 CSS 方案，避免"UI 稿细节 → 前端实现"这条边只靠 UI 评审兜底导致的漏还原。
+
+## 什么时候用
+
+- 用户显式输入 `figmaSync prepare / plan / apply`
+- 用户提供 Figma URL 并要求"还原视觉 / 生成页面样式"
+- 页面基建就绪，进入视觉落地阶段
+
+## 前置产物
+
+| 产物 | 来源 | 是否必需 |
+|---|---|---|
+| Figma URL | 人工提供 | 必需 |
+| `foundation-summary.md` | `devFlow foundation-freeze` | plan 必需 |
+| 已存在的页面 route / components / service | admin-fe 仓库 | 必需 |
+
+## 输出产物
+
+| 产物 | 位置 | 下游消费者 |
+|---|---|---|
+| `PLAN.md` | 项目文档目录 | 人工评审 → apply |
+| `figma-plan.css` | 项目文档目录 | 人工评审(不直接接入业务) |
+| 页面 CSS 与组件代码 | admin-fe 仓库 | 前端开发 |
+
+## 下一步
+
+- `prepare` 通过 → `figmaSync plan <figma-url>`
+- `plan` 输出 `PLAN.md` 人工评审后 → `figmaSync apply`
+- `apply` 完成 → 自测 / 联调
+
+## 明确不做
+
+- 不重新规划路由、不重写 service 契约、不改核心状态模型 —— 归属 `devFlow`
+- 不生成 API 契约文档 —— 归属 `devFlow api-tech`
+- 不做 PM↔UI 一致性检查 —— 归属 `consistency-checker`
+- 不因为 Figma 图层结构重拆业务组件 —— 只补视觉、布局、Apex UI 选型、CSS
+
+---
+
+## 详细规则
+
+此技能用于把 Figma 业务设计稿转换为可审核、可落地的 React + 原生 CSS 方案。
+
+核心原则：
+
+- 执行 admin-fe 任务时必须遵守项目根目录 `ADMIN_FE_WORKFLOW.md`。
+- L0/L1 小需求不强制进入 figmaSync；只有 Figma 视觉落地、新页面或页面级视觉重构才进入 plan/apply。
+- 代码事实优先于设计稿推断；plan 阶段必须读取目标页面 route、components、service、types、constants 和最新
+  `foundation-summary.md`。
+- 样式优先复用 `/theme` 中已有 CSS variables。
+- 能用 Apex UI props 解决的视觉，不写 CSS 覆盖。
+- 能复用 common component、业务组件、icons/assets 的，不重新造。
+- `figmaSync` 只补视觉、布局、Apex
+  UI 选型、CSS 和局部展示细节；不能重新规划路由、重写 service 契约、改变核心状态模型或因为 Figma 图层结构重拆业务组件。
+- `plan` 阶段必须同时产出 `PLAN.md` 和
+  `figma-plan.css`，便于用户在编码前审核样式结构。
+- `plan` 阶段产出的 `figma-plan.css` 是审核草案，不直接接入业务代码。
+
+## 命令路由
+
+| 用户输入                            | 跳到                                         | 用途                                     |
+| ----------------------------------- | -------------------------------------------- | ---------------------------------------- |
+| `figmaSync prepare`                 | [chapters/prepare.md](./chapters/prepare.md) | 检查技术栈、/theme、Apex UI 与资产可用性 |
+| `figmaSync plan <figma-url>`        | [chapters/plan.md](./chapters/plan.md)       | 分析设计稿，落地 PLAN.md + CSS 审核草案  |
+| `figmaSync apply [path/to/PLAN.md]` | [chapters/apply.md](./chapters/apply.md)     | 根据已审核 PLAN.md 和 CSS 草案实施页面   |
+| 未指明命令，仅给 Figma 链接         | 询问用户是 `plan` 还是 `apply`               | —                                        |
+
+第一次使用必须先跑 `figmaSync prepare`。
+
+## 0. CSS 变量体系一览
+
+项目的标准变量源是 `/theme`，当前重点读取：
+
+- `theme/dark/primitives.css`
+- `theme/dark/aliases.css`
+
+变量层级按语义分为：
+
+| 层级   | Set          | 用途                                           | 示例                               |
+| ------ | ------------ | ---------------------------------------------- | ---------------------------------- |
+| 调色板 | `palette`    | 原始颜色色卡，业务 CSS 不直接优先引用          | `palette.grey.3`                   |
+| 语义   | `foundation` | 中性、品牌、状态等语义色                       | `foundation.fill.neutral.tertiary` |
+| 基础   | `baseValue`  | spacing、radius、border、size、fontSize 等数值 | `baseValue.spacing.8`              |
+
+推荐顺序：
+
+- 颜色：优先 `foundation`，只有没有语义变量时才考虑 `palette`。
+- 数字：优先 `baseValue`。
+- 未命中：写入 `figma-plan.css`
+  注释，等待用户确认是否新增变量或接受一次性 CSS 值。
+
+## 1. 上下文准备
+
+通过 Figma MCP 获取目标节点的结构、截图、variables 与 design context：
+
+- `get_metadata`
+- `get_screenshot`
+- `get_variable_defs`
+- `get_design_context`
+
+## 2. 匹配流程
+
+对每个节点按以下顺序处理，命中即停。
+
+### Fast Path 0 — Apex UI 组件复用
+
+阅读 `node_modules/@frontend/apex-ui--react/dist/llms.txt` 或单组件
+`dist/llm/<component>.txt`，判断当前 Figma 节点是否能映射到已有组件：
+
+- Button / Input / Select / Table / Modal / Drawer / Card / Tag / Tabs / Tooltip
+  / Menu / Pagination …
+- 命中后直接使用 Apex UI 组件。
+- 视觉差异优先走组件 props，例如 `type`、`size`、`variant`。
+- 能通过 props 表达的样式，不写入 `figma-plan.css`。
+
+不走 Apex UI 的场景：节点明显是自定义容器、业务卡片、特殊布局、复杂组合模块。
+
+### Fast Path 1 — Figma variables 直连 /theme
+
+如果 `get_variable_defs` 返回变量名或变量路径，先在 `/theme` 变量记录中查找。
+
+命中后在 PLAN.md 记录：
+
+- `cssVariable`：真实 CSS variable，例如 `--fill-neutral-primary`
+- `themePath`：变量路径，例如 `foundation.fill.neutral.primary`
+- `cssValue`：原始值或 alias 表达式
+- `usage`：建议用在哪些 CSS 属性上
+
+在 `figma-plan.css` 中使用真实 CSS variable：
+
+```css
+.client-page {
+  background: var(--fill-neutral-primary);
+}
+```
+
+### Fast Path 2 — CSS `var(--xxx)` 查表
+
+如果 Figma CSS 含 `var(--xxx, fallback)`，运行：
+
+```bash
+node .agent/skills/figmaSync/scripts/lookup-var.mjs "var(--fill-neutral-primary, #090A0B)"
+```
+
+成功输出示例：
+
+```json
+{
+  "success": true,
+  "cssVariable": "--fill-neutral-primary",
+  "themePath": "foundation.fill.neutral.primary",
+  "cssValue": "{grey.14}",
+  "usage": ["color"],
+  "layer": "foundation",
+  "shortRef": "fill.neutral.primary"
+}
+```
+
+必须把 `cssVariable` 写入 CSS，把 `themePath` 写入 PLAN.md 便于审核。
+
+### Slow Path — 反向值匹配
+
+仅当设计师把值写死为裸 `#hex`、`rgb()` 或 `Npx` 时运行：
+
+```bash
+node .agent/skills/figmaSync/scripts/match-token.mjs "<value>"
+```
+
+成功输出推荐的 CSS variable 与 `/theme` 路径。命中后仍然在 `figma-plan.css`
+中使用 CSS variable，不直接写死值。
+
+### Reuse Path — common component 与 assets
+
+在进入自定义 CSS 前，必须扫描并记录复用机会：
+
+- `src/common/**`
+- 目标业务目录附近已有组件
+- `assets/`
+- `public/`
+- `src/**/assets/`
+- `src/**/icons/`
+
+判断标准：
+
+- 组件语义一致且 props 能覆盖当前需求 → 复用。
+- icon/assets 文件名或组件名能和 Figma 节点语义匹配 → 复用。
+- 仅视觉相似但语义不同 → 不确认命中，写入待确认清单。
+
+### 样式归属判定
+
+生成 CSS 草案前，必须先判断每条 Figma 样式属于谁控制。不能因为
+`get_design_context` 返回了颜色、边框、圆角或字号，就机械写入 `figma-plan.css`。
+
+按以下顺序判定：
+
+1. **Apex UI 组件自管样式**
+   - 由 Apex UI 组件 props、内置状态、组件内部 token 控制。
+   - 只写入 PLAN.md 的组件映射决策，不写入 `figma-plan.css`。
+   - 典型例子：
+     - `Button`：`type`、`size`、`disabled`、`loading`、`icon`。
+     - `Tag`：`color`、`variant`、`size`、`icon`。
+     - `Tabs`：`type`、`activeKey`、`disabled`。
+     - `Input`、`Select`、`DatePicker`：`size`、`status`、`disabled`。
+     - `Table`：`size`、`loading`、`pagination`、`scroll`、列宽、固定列。
+     - `Pagination`：`showSizeChanger`、`disabled`、`pageSizeOptions`。
+     - `Drawer`、`Modal`：`size`、`mask`、按钮 props。
+   - 若 Figma 中出现的是组件状态色，例如 primary、success、warning、error、active、disabled、hover、selected，应优先映射为对应组件 prop 或状态，不写 CSS 色值。
+2. **业务组件自管样式**
+   - 由业务组件内部状态映射或已有 class 控制，例如业务状态 tag、业务卡片、业务列单元格。
+   - 可写 CSS，但必须限定在业务组件私有 class 下。
+   - 如果业务组件内部最终使用 Apex UI 组件，颜色、尺寸、状态仍优先交给 Apex UI
+     props。
+3. **页面布局样式**
+   - 页面容器、grid、flex、gap、padding、position、overflow、responsive、局部尺寸约束等。
+   - 可以写入 `figma-plan.css`，并优先使用 `/theme` CSS variables。
+4. **未命中或无法归属样式**
+   - 写入 PLAN.md 待确认。
+   - `figma-plan.css` 只写 TODO 注释，不直接写死裸值。
+
+PLAN.md 的组件映射决策必须说明样式归属：`Apex UI props`、`业务组件 CSS`、
+`页面 CSS` 或 `待确认`。`figma-plan.css` 只允许出现 `业务组件 CSS` 和 `页面 CSS`
+需要承载的样式。
+
+## 3. 原生 CSS 落地策略
+
+### Level 1 — 组件局部 CSS
+
+适用：页面或业务组件私有布局、容器、间距、无法由 Apex UI props 表达的简单状态。
+
+动作：
+
+- plan 阶段写入 `figma-plan.css`。
+- apply 阶段按项目结构迁移为正式 CSS 文件，例如 `route.css`、`styles.css`
+  或组件旁 CSS。
+- class 使用 kebab-case。
+
+### Level 2 — 已有 common component 扩展
+
+适用：设计稿对应的能力已在 common component 中存在，但缺少少量状态或 class
+slot。
+
+动作：
+
+- PLAN.md 中列出扩展点和影响面。
+- apply 前必须让用户确认是否改公共组件。
+
+### Level 3 — 新增 /theme 变量
+
+适用：明确跨页面复用、且现有 `/theme` 找不到合适变量。
+
+动作：
+
+- PLAN.md 记录建议新增变量名、来源值、用途和影响面。
+- plan 阶段不直接修改 `/theme`。
+- apply 阶段只有在用户明确确认后才修改 `/theme`。
+
+## 4. CSS 草案规则
+
+`figmaSync plan` 必须在 PLAN.md 同目录生成：
+
+```text
+figma-plan.css
+```
+
+该文件必须包含：
+
+- 页面根 class。
+- 主要区块 class。
+- 关键状态 class。
+- 真实 CSS variable 引用。
+- 只属于页面或业务组件的样式。
+- 未命中变量的注释，格式为：
+
+```css
+/* TODO(figmaSync): unmatched color #123456 from node 1:2; needs user confirmation */
+```
+
+该文件禁止包含：
+
+- 能通过 Apex UI props 表达的样式覆盖。
+- Apex UI 组件自管状态色、状态背景、状态边框、内置圆角、内置字号等。
+- 从 Figma 组件实例中抄出的 Apex UI 内部 token 覆盖。
+
+## 5. 任务边界
+
+### 任务开始
+
+每次 figmaSync 任务启动前必须清空旧 session 记录：
+
+```bash
+pnpm figma:report --reset
+```
+
+### plan 收尾
+
+必须运行：
+
+```bash
+pnpm figma:verify-plan <path/to/PLAN.md>
+pnpm figma:report --command=plan --plan=<PLAN.md 路径> --target-dir=<PLAN.md 所在目录>
+```
+
+### apply 收尾
+
+必须运行：
+
+```bash
+pnpm figma:report --command=apply --plan=<PLAN.md 路径> --target-dir=<PLAN.md 所在目录>
+pnpm typecheck
+pnpm format:check
+pnpm lint
+```
+
+若格式检查失败，运行 `pnpm format` 后重新检查。
+
+## 6. 速查命令
+
+| 命令                                                          | 用途                                       |
+| ------------------------------------------------------------- | ------------------------------------------ |
+| `pnpm figma:prepare`                                          | 检查 /theme、Apex UI、common/assets 可用性 |
+| `pnpm figma:report --reset`                                   | 清空本次 session 记录                      |
+| `node .agent/skills/figmaSync/scripts/lookup-var.mjs "--xxx"` | CSS variable → /theme 路径                 |
+| `node .agent/skills/figmaSync/scripts/match-token.mjs "#xxx"` | 裸值 → 推荐 CSS variable                   |
+| `node .agent/skills/figmaSync/scripts/icon-inventory.mjs`     | 扫描 icon/assets                           |
+| `pnpm figma:verify-plan <PLAN.md>`                            | 校验 PLAN.md 与 figma-plan.css             |
+| `pnpm figma:report --command=plan ...`                        | 生成 plan session report                   |