figma-cache-toolchain 2.0.0 → 2.0.2

package/README.md

@@ -70,6 +70,20 @@ npm run figma:cache:validate
 
 ---
 
+## Cursor 模板固定流程（强制建议）
+
+- 单一真源：仅手工维护 `cursor-bootstrap/` 下的 rules/skills。
+- 镜像目录：`.cursor/` 视为生成产物，不手工编辑。
+- 日常步骤：
+  1) 修改 `cursor-bootstrap/*`
+  2) 运行 `npm run cursor:shadow:sync`
+  3) 运行 `npm run cursor:shadow:check`
+- 守护机制：
+  - CI 会执行 `cursor:shadow:check`，若 `.cursor` 与 `cursor-bootstrap` 不一致将直接失败。
+  - `npm test` 与 `prepack` 也已包含该检查，避免本地漏同步。
+
+---
+
 ## 默认 completeness 与 token 开销
 
 默认 completeness：`layout,text,tokens,interactions,states,accessibility`（默认不含 `flow/assets`）。

package/cursor-bootstrap/AGENT-SETUP-PROMPT.md

@@ -3,9 +3,12 @@
 > **给 Cursor Agent 的指令**：你正在操作的是**用户业务项目**的根目录。以下文件应已存在（由 `npx figma-cache cursor init` 从 npm 包 **`{{NPM_PACKAGE_NAME}}`** 复制到当前仓库根）：
 > - `.cursor/rules/01-figma-cache-core.mdc`
 > - `.cursor/rules/00-output-token-budget.mdc`（通用低 token 输出基线）
+> - `.cursor/rules/04-ui-baseline-governance.mdc`（UI 全局基线治理：新项目/老项目双轨 + 生成约束）
 > - `.cursor/rules/02-figma-stack-adapter.mdc`（**占位**，任务完成后需删除）
 > - `.cursor/rules/figma-local-cache-first.mdc`（可选保留）
 > - `.cursor/skills/figma-mcp-local-cache/SKILL.md`
+> - `.cursor/skills/ui-baseline-governance/SKILL.md`（执行清单：基线判定与落地步骤）
+> - `.cursor/skills/figma-ui-dual-mode-execution/SKILL.md`（仅给 nodeId/链接即可触发端到端 UI 实现）
 > - `figma-cache.config.js`（示例 `postEnsure`：目录级 adapter hint + 可选 `docs/figma-flow-readme.md`）
 > - （兼容旧项目）`figma-cache.config.example.js` 可能存在；仅当内容被用户自定义且无法安全迁移时保留
 
@@ -35,9 +38,16 @@
    - 用简短列表向用户汇报：新建/修改/删除了哪些路径。  
    - 若项目根**尚无** `figma-cache/index.json`，提示用户执行：`npm run figma:cache:init`（若已加 script）或 `npx figma-cache init`（与 `cursor init` 不同，用于创建空索引与缓存目录）。  
    - 提示用户在本项目根执行：`npm run figma:cache:validate`（若已加 script）或 `npx figma-cache validate`。  
-   - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。  
+   - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + figma-mcp-local-cache Skill** 驱动；涉及全局样式与组件生成稳定性时叠加 **04-ui-baseline-governance + ui-baseline-governance Skill**。  
       - **可选**：若项目已通过 `cursor init` 同步 `figma-cache/docs/colleague-guide-zh.md`，提示团队默认只使用 **§5.1「最推荐主提示词」**，只有特殊诉求再追加 **§5.2** 的一句附加要求。
 
+8. **UI 全局基线治理（强烈推荐，与 UI 实现任务绑定）**  
+   - 确认 `.cursor/rules/04-ui-baseline-governance.mdc` 与 `.cursor/skills/ui-baseline-governance/SKILL.md` 已存在于项目根（随 `cursor init` 同步）；若缺失，从 npm 包内 **`cursor-bootstrap/rules/`** 与 **`cursor-bootstrap/skills/`** 补拷到当前仓库 `.cursor/`，并提示团队升级 **`{{NPM_PACKAGE_NAME}}`** 版本以便后续 init 自带。  
+   - 读取 **`04-ui-baseline-governance.mdc` §1.0**：按机械启发式判定「新项目 / 老项目」，在汇报中写明**结论 + 命中证据**（文件路径、计数、依赖名）。  
+   - 按判定结果执行：新项目可规划一次性全局基线；老项目仅允许分层/分批/可回滚方案，禁止首轮全量全局 reset 叠加大规模业务重构。  
+   - 在 Cursor 中建议团队对「写业务 UI / 调全局样式」类任务 **@** 引用：`04-ui-baseline-governance.mdc` 或 `ui-baseline-governance` Skill，以统一生成行为（`border-box` 假设、flex 溢出、弹层锚定、图标策略等）。
+   - 降噪策略：默认使用短流程；仅在老项目、高风险任务或冲突场景升级严格流程。`ui-1to1-preflight.template.md` 仅在严格流程下强制填写，短流程可只输出精简事实清单。
+
 ## 输出与 token 约束（强制）
 - 默认“只要结果”：不输出思考过程，不粘贴 MCP 长回包。
 - 执行 Figma MCP 后，用户可见回复只保留：缓存状态、调用次数、产物路径、校验结论、失败修复动作。

package/cursor-bootstrap/examples/ui-1to1-preflight.template.md

@@ -0,0 +1,80 @@
+# UI 1:1 实现前预检模板
+
+> 用途：在“开始写组件前”完成事实快照、状态对照与预检，降低返工。  
+> 适用：Figma 缓存驱动实现（任意 nodeId）。
+
+## 0. 基本信息
+
+- fileKey:
+- nodeId:
+- cachePath:
+- 实现目标页面/组件路径:
+- 执行模式（短流程 / 严格流程）:
+
+## 1. 设计值快照（Design Facts）
+
+### 1.1 结构与尺寸
+
+- 根容器（宽/高/圆角/边框/背景）:
+- 关键子容器尺寸:
+- 宽度策略（固定 / 自适应，仅可选一）:
+- 对齐策略（左/右/居中）:
+
+### 1.2 文案
+
+- 标签文本:
+- 值文本:
+- 选项文本:
+
+### 1.3 Token
+
+- 字体（size/line-height/weight/letter-spacing）:
+- 主文本色:
+- 次文本色:
+- 背景色:
+- 边框色:
+- 状态色（hover/focus/selected）:
+
+### 1.4 交互与语义
+
+- 交互触发（click/esc/outside/keyboard）:
+- 语义角色（combobox/listbox/option 等）:
+- 禁止项（本任务）:
+
+## 2. 状态对照表（必须填写）
+
+| 状态 | 背景 | 边框 | 文本 | 图标 | 数据状态 | 是否实现 |
+| --- | --- | --- | --- | --- | --- | --- |
+| default |  |  |  |  |  | [ ] |
+| hover |  |  |  |  |  | [ ] |
+| focus |  |  |  |  |  | [ ] |
+| active |  |  |  |  |  | [ ] |
+| expanded |  |  |  |  |  | [ ] |
+| selected |  |  |  |  |  | [ ] |
+| unselected |  |  |  |  |  | [ ] |
+| disabled（若存在） |  |  |  |  |  | [ ] |
+
+## 3. 1:1 预检清单（实现前）
+
+- [ ] 已读取 `spec.md` / `raw.json` / `state-map.md` / `mcp-raw-get-design-context.txt`
+- [ ] 冲突裁决规则确认：`mcp-raw-get-design-context.txt` 优先
+- [ ] 全组件盒模型策略一致（建议 `box-border`）
+- [ ] 文本溢出策略明确（`min-w-0` + `truncate` 或等效）
+- [ ] 弹层锚定触发器（非页面硬编码定位）
+- [ ] 图标策略确认（项目图标库优先；兜底 `inline svg`）
+- [ ] 禁止使用 Figma 临时远程资产 URL 作为运行时图标
+- [ ] 禁止无意义标签嵌套
+- [ ] 默认无横向滚动
+
+## 4. 实现后验收（最小）
+
+- [ ] 改动文件 lint 通过
+- [ ] 关键状态可见且可切换（至少 default/expanded/selected/unselected）
+- [ ] 关键视觉项（尺寸/对齐/图标居中）通过
+- [ ] 输出“设计值 -> 代码映射”
+
+## 5. 失败反馈（固定三段）
+
+1. 失败原因
+2. 定位信息（文件/字段/样式项）
+3. 修复动作

package/cursor-bootstrap/rules/00-output-token-budget.mdc

@@ -5,22 +5,25 @@ alwaysApply: true
 
 # Output Token Budget（通用）
 
-适用于所有任务（不仅限 Figma）。目标：减少对话 token 消耗，只输出结果与可执行结论。
+适用于所有任务。默认只输出“可执行结果”，避免过程噪音与长回包。
 
-## 默认输出策略（强制）
-- 结果优先：不输出思考过程，不做长篇背景铺垫。
-- 最小必要：只输出结论、关键变更、验证结果、下一步动作。
-- 工具原文最小化：禁止在回复中粘贴大段工具原始回包/日志，除非用户明确要求查看原文。
-- 文件优先：大内容落到文件，再汇报路径；回复仅给摘要与定位。
+## 默认策略（强制）
+- 结果优先：只给结论、关键变更、验证结果、下一步。
+- 原文最小化：不贴 MCP/终端长日志；仅在用户明确要求时展示。
+- 文件优先：大内容落盘，回复只给路径与摘要。
+- 进度最小化：默认不发中间过程；仅在阻塞/失败时反馈。
 
 ## 任务分级（强制）
-- UI/组件实现：默认读取并使用完整设计证据，不反复讨论“是否需要读取”；完成后仅汇报最终差异与验证。
-- 逻辑/流程/校验类任务：优先读取摘要产物（如 `raw.json`、`spec.md`、`manifest`），避免无关大文件。
+- UI/组件实现：读取完整设计证据，回复仅给最终差异与验证。
+- 逻辑/流程/校验：优先 `raw.json` / `spec.md` / `manifest`，避免读无关大文件。
 
-## 交互与进度（强制）
-- 仅在必要阻塞时提问；可自行推断时不追问。
-- 中间进度最多 1 条（长任务可 2 条），其余一次性收敛到最终结果。
-- 失败反馈固定三段：失败原因、定位信息、修复动作。
+## 失败反馈格式（强制）
+- 固定三段：失败原因 / 定位信息 / 修复动作。
 
 ## 例外
-- 用户明确要求“展示完整输出/完整日志/原文”时，才突破上述限制。
+- 用户明确要求“完整输出/日志/原文”时可放宽上述限制。
+
+## 模板维护约定（强制）
+- `cursor-bootstrap` 是规则/技能模板唯一手写来源。
+- 仓库内 `.cursor/*` 视为镜像产物，不作为手工编辑入口。
+- 模板变更后执行 `npm run cursor:shadow:sync`，再提交。

package/cursor-bootstrap/rules/01-figma-cache-core.mdc

@@ -5,116 +5,43 @@ alwaysApply: true
 
 # Figma Cache Core（数据层）
 
-本规则只约束 **Figma → 本地通用缓存** 的流程：标准化 URL、读写 `figma-cache/`、`index.json`、必要时 MCP、校验。**不**在此阶段编写 Vue/React 组件或映射到任何 UI 库；实现代码时由项目 Adapter 规则约束。
-
-## 目标
-- 对用户提供的 Figma 链接，优先复用项目内已落地的结构化文档（`meta.json`、`spec.md`、`raw.json`、`state-map.md` 等）。
-- 仅在本地信息不足以完成任务时调用 Figma MCP。
-- 默认采用 MCP 最小调用集，并按 `completeness` 精确裁剪调用：优先在满足字段目标前提下最少调用工具。
-- 项目级扩展通过仓库根目录的 `figma-cache.config.js` / `.figmacacherc.js` 的 `hooks.postEnsure` 完成；Core 脚本不包含任何具体 UI 框架名。
-
-<Trigger Conditions>
-
-以下任一成立时，Agent **必须**按本规则执行缓存流水线，并在回复**开头**输出「缓存状态 Blockquote」：
-
-1. **显式 Figma URL**：消息含 `figma.com` / `www.figma.com` 的可识别设计链接（`file`、`design`、`proto`、`embed` 等，含或不含 `node-id=`）。
-2. **隐式但可解析为 Figma**：含 `figma` 域名的短链、重定向说明，或「fileKey + node-id」且意图为某一画布节点。
-3. **本地缓存语义**：「figma 缓存」「本地缓存」「先查缓存」「figma-cache」「index.json」「spec.md」「state-map」等，且任务与该缓存相关。
-4. **设计落地/对齐（仅数据侧）**：需先拉齐/刷新设计事实、写入或读取 `figma-cache`，且上下文可解析链接或 `fileKey`/`node-id`。
-5. **显式跳过/刷新**：「跳过缓存」「强制刷新」「以 Figma 最新为准」——可走 MCP，Blockquote 标「更新」、来源 MCP。
-
-**不触发**：纯概念讨论、无可解析链接/键/节点线索、且与缓存目录无关。
-
-</Trigger Conditions>
-
-## 执行顺序
-1. 按 `figma-cache/docs/link-normalization-spec.md` 标准化链接。
-2. 读本地 `index.json` 判断是否命中。
-3. 命中且字段满足任务 → 只读本地，不调 MCP。
-4. 未命中或不足 → MCP 拉取并回写通用缓存文件。
-5. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅负责索引与骨架文件，不视为 MCP 拉取动作；不得把“执行 ensure”当作“已完成 MCP 调用”。
-6. **MCP 最小调用集（默认）**：以单个 `fileKey + nodeId` 为粒度，默认只调用 `get_design_context`（建议 `excludeScreenshot=true`）、`get_metadata`、`get_variable_defs`；禁止同参数重复调用同一工具。
-7. **按需调用策略**：`get_screenshot` 仅在用户显式要求可视留档/截图回包，或上述三项仍不足以消除结构歧义时调用；`whoami` 仅在鉴权/权限报错时调用，不作为常规流程步骤。
-8. **按 completeness 的调用矩阵（强制）**：
-   - `layout` → `get_metadata`（若结构层级不足，再补 `get_design_context`）
-   - `text` → `get_design_context`
-   - `tokens` → `get_variable_defs`
-   - `interactions` / `flow` / `states` → `get_design_context` + `state-map.md`/`flows` 回写
-   - `accessibility`（若任务声明）→ 优先 `get_design_context` 的语义线索，不足时标注缺口
-   - `assets`（若任务声明）→ `get_design_context` 中资产 URL；仅当用户要求截图留档再调 `get_screenshot`
-   - **flow 自动追加白名单（强制）**：默认 completeness 基线为 `layout,text,tokens,interactions,states,accessibility`（不含 `flow`）；仅在命中白名单时自动追加 `flow`：
-     - 用户明确表达关系/流程意图，且语义命中关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
-     - 同轮或断续出现多个 Figma 链接，且存在明确先后或串联意图（如 A->B）
-     - 单链接且无关系意图、仅视觉微调、仅资产导出时，禁止自动追加 `flow`
-9. **两阶段拉取**：先按最小必要工具取数并检查字段缺口；仅在缺口存在时进入第二阶段补调工具。
-10. **写入一致性门禁（强制）**：当 `source=figma-mcp` 或输出来源标注 MCP 时，节点目录必须存在 `mcp-raw/` 与对应原始文件；若缺失则视为未完成，必须停止并报告，不得宣称“更新成功”。
-11. **严格证据门禁（强制）**：当 `source=figma-mcp` 且未显式传入 `--allow-skeleton-with-figma-mcp` 时，`upsert/ensure` 必须在写入前校验 `mcp-raw` 证据：
-   - `layout` 至少命中 `get_metadata` 或 `get_design_context`
-   - `text/interactions/states/accessibility/flow/assets` 必须命中 `get_design_context`
-   - `tokens` 必须命中 `get_variable_defs`
-   任一维度缺证据即失败退出，不得写入成功状态。
-12. **严格 validate（强制）**：`validate` 不仅校验索引字段，还校验证据完整性：
-   - `completeness` 声明的维度必须在 `raw.json.coverageSummary.evidence` 中提供非空证据
-   - 对 `source=figma-mcp` 且声明 `interactions/states/accessibility` 的节点，禁止保留 TODO 占位内容
-13. **大文件读取策略（强制）**：
-   - **UI 还原/像素对齐/组件实现任务**：默认必须读取 `mcp-raw-get-design-context.txt` 全文，不反复讨论是否需要读取。
-   - **非 UI 任务**（命中检查、预算统计、校验、流程维护）：默认仅读取 `raw.json` / `spec.md` / `mcp-raw-manifest.json`。
-14. **闭环校验（强制）**：每次 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`** 成功结束后，**自动静默**执行 `npm run figma:cache:validate`。
-15. validate 失败 → **自行修复并重复 validate 直至通过**，不得宣称缓存已就绪。
-16. **不写前端**：本阶段禁止输出业务组件实现；若用户要求写 UI，在缓存就绪后转由 **栈专属 Adapter 规则**（如 `02-figma-stack-adapter.mdc` 占位，或项目内 `02-figma-<栈>-adapter.mdc`）接管。
-
-## Agent 最终输出格式（强制）
-凡触发 `<Trigger Conditions>` 且本轮涉及缓存读写的回复，**正文第一段**必须为单行 Blockquote：
-
-`> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
-
-（语义与 `index.json` 中 `nodeId` / `__FILE__` 约定同前；Blockquote 后再写结论。）
-
-- 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
-
-## 低 Token 输出模式（强制）
-- 默认采用“结果优先”输出：仅保留最终结论与必要审计字段，不输出思考过程。
-- MCP 工具回包（尤其 `get_design_context`）禁止在用户可见回复中粘贴全文或大段复述；仅报告调用计数、来源、文件路径与校验结果。
-- 除非用户明确要求查看原文，`mcp-raw` 内容仅落盘到文件，不在 chat 回显。
-- 进度反馈最小化：缓存任务默认 0-1 条简短进度更新；完成后一次性给出结果。
-- 失败场景也保持精简：仅输出失败原因、定位文件、下一步修复动作。
-
-## 配置与钩子
-- `npm run figma:cache:config` 可查看是否加载 `hooks.postEnsure`。
-- `ensure` 在写入通用骨架后会调用 `hooks.postEnsure`；钩子异常**不得**阻断 ensure 成功退出（由 Core 捕获）。
-- `ensure` 不是 MCP 拉取入口；若命令声明 `source=figma-mcp`，应先完成 MCP 工具调用并落盘 `mcp-raw/`，再进行 upsert/ensure。
-
-## 其余约定
-- 缓存目录、环境变量、`flows`、陈旧策略、提交前校验等与原「Local Cache First」一致，参见 `figma-cache/` 内文档及 `npm run figma:cache:*`。
-- 对同一节点写缓存时，优先复用本轮已拿到的 MCP 响应做落盘，避免“仅为生成原始文件而重复调同一工具”。
-- 若保存原始数据，统一写入节点目录下 `mcp-raw/` 子目录（如 `mcp-raw/mcp-raw-get-design-context.txt`），与加工缓存文件分层。
-- `mcp-raw` 原始文件**禁止**写入任何摘要/截断标记（如 `omitted for brevity`、`...response omitted...`、`省略`、`截断`）；必须直存完整 MCP 回包。
-- `mcp-raw/mcp-raw-manifest.json` 必须记录每个工具原始文件的 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数）；`validate` 会逐项比对，不一致即失败。
-- **落盘后即时反精简检查（强制）**：每次写入 `mcp-raw` 后，必须立刻检查是否出现摘要/截断标记与 hash/size 不一致；检查结果必须在用户回复中显式输出为 `mcp-raw anti-truncation: pass|fail`（失败时附修复动作）。
-- 默认不写 `whoami` 原始文件；仅在鉴权排障或用户显式要求账号态审计时才写入。
-- 单节点 MCP 调用预算默认不超过 3 次；超过时必须在输出中说明缺口字段与补调原因。
-- 仅对超时/5xx做指数退避重试；对参数错误/权限错误不重试，直接报告并等待用户指令。
-- 不在未校验时假定 Figma 为最新；用户显式要求实时读取时须遵守。
-## Encoding, Shell 兼容与安全写入（强制）
-- 仓库内 README / mdc / SKILL / json / js 等文本文件默认使用 **UTF-8 无 BOM**。
-- Node 写文件必须显式指定 utf8（如 writeFileSync(path, text, "utf8")）。
-- 在 Windows PowerShell 下，**禁止**把 Set-Content / Out-File -Encoding utf8 作为 js/mdc/md/json 的默认写入方式（可能写出 BOM）。
-- 若必须用 PowerShell 写文本文件，使用无 BOM 写法：
-  - `$enc = New-Object System.Text.UTF8Encoding($false)`
-  - `[System.IO.File]::WriteAllText($path, $text, $enc)`
-
-## Shell 语法兼容（PowerShell 强制）
-- 当前终端为 PowerShell 时，**禁止**使用 bash heredoc（如 `<<'EOF'`、`<<'PY'`）。
-- 当前终端为 PowerShell 时，命令串联默认使用 `;`（或拆成多次调用），**禁止**使用 `&&`。
-- 多行文本注入优先使用 PowerShell here-string（`@' ... '@` 或 `@" ... "@`）。
-- 文本替换时，禁止把字面量 `\n` / `` `n `` 当作真实换行依赖；必须写入真实换行并回读确认。
-
-## 写后必检（强制）
-- 每次脚本化写入后，必须立刻回读目标文件，确认无字面量 `\n`、`` `n ``、乱码、截断。
-- 对 shebang 文件（如 `#!/usr/bin/env node`），必须确认文件首字节无 BOM。
-- 修改 README / rules / skills 后，必须执行 `npm run docs:encoding:check`（或等价编码检查）并确认通过。
-
-## 故障恢复（强制）
-- 一旦出现 BOM、乱码、PowerShell 语法不兼容、转义换行误写，立即停止增量替换。
-- 先回读定位受影响文件，再用 UTF-8 无 BOM 方式整段重写，最后重新执行验证命令。
+边界：仅处理 Figma -> 本地缓存数据（标准化、索引、MCP、校验）；本阶段禁止写业务 UI。
+
+## 触发条件（任一命中即执行）
+- 消息包含可解析 Figma 链接、`fileKey+nodeId`、或明确“figma-cache/本地缓存/刷新”语义。
+- 非触发：纯概念讨论且无可解析链接/节点线索。
+
+## 标准流程（强制）
+1. 标准化链接并读取 `figma-cache/index.json`。
+2. 命中且字段足够：只读本地，不调 MCP。
+3. 未命中或字段不足：调用 MCP 最小集并落盘：
+   - `get_design_context`（默认 `excludeScreenshot=true`）
+   - `get_metadata`
+   - `get_variable_defs`
+4. 同参数工具不得重复调用；`get_screenshot` 仅在显式要求截图或结构仍有歧义时调用；`whoami` 仅鉴权报错时调用。
+5. `source=figma-mcp` 时必须先有 `mcp-raw/*` 证据与 `mcp-raw-manifest.json`（含 `files/fileHashes/fileSizes/toolCalls`）。
+6. 每次写完 `mcp-raw` 立即做反精简检查（截断标记 + hash/size 一致性）。
+7. 执行 `upsert/ensure` 后必须自动执行 `validate`；失败需自修复并循环直到通过。
+
+## completeness 规则（强制）
+- 默认基线：`layout,text,tokens,interactions,states,accessibility`。
+- 映射：
+  - `layout` -> `get_metadata`（不足再补 `get_design_context`）
+  - `text/interactions/states/accessibility` -> `get_design_context`
+  - `tokens` -> `get_variable_defs`
+- `flow` 仅在白名单触发时追加：
+  - 关系关键词命中（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch）
+  - 或多链接且有明确串联意图
+- `assets` 按需开启，非默认维度。
+
+## 输出格式（强制）
+- 命中触发且涉及缓存读写时，首行必须：
+  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
+- 仅输出：`mcp-raw anti-truncation`、MCP 调用统计、completeness、产物路径、validate 结果。
+- 自动追加 `flow` 时必须标注触发原因（关键词命中/多链接串联意图）。
+
+## 低 token 与编码（强制）
+- 用户可见回复禁止粘贴 MCP 长原文；除非用户明确要求。
+- 进度默认 0-1 条；仅阻塞或失败时补充。
+- 文档与脚本写入统一 UTF-8（无 BOM）；PowerShell 禁用 bash heredoc，写后回读并执行必要校验（如 `npm run docs:encoding:check`）。
 

package/cursor-bootstrap/rules/03-figma-ui-implementation-hard-constraints.mdc

@@ -0,0 +1,91 @@
+---
+description: Figma 缓存驱动的 UI 实现硬约束（严格 1:1）
+alwaysApply: true
+---
+
+# Figma UI 实现硬约束（Hard Mode）
+
+边界：本规则仅约束业务 UI 实现阶段（已具备可读缓存数据后），不负责 MCP 拉取与缓存写入。
+
+## 0. 目标（强制）
+
+- 首版必须 1:1 还原缓存事实。
+- 禁止“贴近”“近似”“经验值补全”。
+- 若信息冲突或不足，先停下澄清，不得猜测实现。
+
+## 1. 首版必读数据源（强制）
+
+实现前必须读取并建立事实对齐清单，缺一不可：
+
+1. `spec.md`
+2. `raw.json`
+3. `state-map.md`
+4. `mcp-raw-get-design-context.txt`（首版强制必读）
+
+补充说明：
+
+- `mcp-raw-manifest.json` 用于确认证据完整性与来源一致性。
+- `mcp-raw-get-variable-defs.txt` 用于 token 变量补充。
+
+## 2. 数据职责与裁决顺序（强制）
+
+- `spec.md`：结构化布局/文案/token 概览。
+- `raw.json`：覆盖度与完整性约束。
+- `state-map.md`：状态与交互映射。
+- `mcp-raw-get-design-context.txt`：首版视觉与结构落地的一手细节依据。
+
+当 `spec.md` / `raw.json` / `state-map.md` 信息抽象、缺失、或相互冲突时：
+
+- 必须回到 `mcp-raw-get-design-context.txt` 裁决。
+- 仍无法裁决时，必须停止实现并向用户确认。
+- 禁止凭经验补齐。
+
+## 3. 视觉 1:1 规则（强制）
+
+- 颜色：必须使用缓存 token 或明确值，禁止近似替换。
+- 文本：字号/字重/行高/字距逐项对齐，禁止“近似 class”替代。
+- 几何：圆角/边框/背景/间距逐项对齐，不做推测。
+- 盒模型：统一 `box-border`（或等效策略）并保持全组件一致。
+- 状态切换不得引发布局占位变化（避免抖动/超宽/变窄）。
+
+## 4. 标签与语义规则（强制）
+
+- 布局与展示优先使用安全标签：`div` / `span` / `p` / `img`。
+- 不禁用功能标签（如 `button` / `input` / `select` / `ul` / `li`），但使用时必须：
+  - 明确其语义必要性，或来自本地封装组件复用。
+  - 完整接管默认样式（基础态 + hover/focus/active/selected）。
+  - 保证视觉结果与设计事实 1:1，不受浏览器默认样式干扰。
+- 禁止“为了方便”滥用功能标签。
+
+## 5. 结构与尺寸一致性（强制）
+
+- 首版必须先确定单一宽度策略（固定值或自适应），同组件内不得混用。
+- 左右对齐策略必须统一；同类块（如双下拉）必须同构实现。
+- 默认禁止横向滚动；非设计明确要求不得出现横向滚动条。
+- 文本溢出必须显式处理（如 `min-w-0` + `truncate`）。
+
+## 6. 状态与交互还原（强制）
+
+- 必须覆盖缓存声明状态：`default / expanded / selected / unselected`（若存在）。
+- 每个状态必须映射背景/边框/文本/图标样式。
+- 交互行为（展开、收起、选择、Esc、outside click）按缓存或用户要求实现。
+- 禁止新增未请求交互；禁止删除已声明交互。
+
+## 7. 执行节奏（强制）
+
+- 每轮只允许改一个维度：结构 / 颜色 / 尺寸 / 交互。
+- 禁止“顺手”捆绑多维改动，除非用户明确要求整包改。
+- 变更后必须做改动文件 lint 校验。
+
+## 8. 失败判定（任一命中即失败）
+
+- 未读取 `mcp-raw-get-design-context.txt` 就开始实现。
+- 使用“近似值”替代缓存明确值。
+- 状态样式未完整覆盖或与缓存定义不一致。
+- 出现横向滚动、尺寸漂移、对齐不一致且无设计依据。
+
+## 9. 失败反馈格式（固定）
+
+1. 失败原因（违反哪条硬约束）
+2. 定位信息（文件 + 样式/结构项）
+3. 修复动作（如何回到 1:1）

package/cursor-bootstrap/rules/04-ui-baseline-governance.mdc

@@ -0,0 +1,86 @@
+---
+description: UI 全局基线治理（新项目与老项目双轨），并约束组件生成行为
+alwaysApply: false
+---
+
+# UI Baseline Governance（生成约束）
+
+边界：本规则只约束“全局样式基线与组件生成策略”，不替代 `01-figma-cache-core.mdc` 与具体栈 Adapter。
+
+## 0. 目标（强制）
+
+- 在不破坏现有页面的前提下，建立可复用的 UI 默认基线。
+- 将“新项目一次性定标”与“老项目渐进治理”统一到同一执行模型。
+- 将基线策略约束到 Agent 的组件生成行为，降低返工。
+
+## 1. 双轨策略（强制）
+
+### 1.0 项目类型判定（机械启发式，强制先判再改）
+
+> 目的：减少主观判断；**拿不准时一律按老项目**（安全默认）。
+
+在动手改全局样式前，Agent 必须完成一次快速扫描并输出「判定结论 + 命中证据（路径或计数）」。
+
+**老项目（走 §1.2 分层分批）**，满足**任一**即判定为老项目：
+
+- **存量页面信号**：`src/`（无 `src` 则看项目约定的主源码根）下 `*.vue` / `*.tsx` / `*.jsx` 文件数 **≥ 40**。
+- **已有全局 reset / normalize**：入口或样式目录存在或引入命中以下之一（文件名或 import 字符串）：`normalize`、`reset`、`preflight`、`@unocss/reset`、`sanitize`。
+- **已接入成熟 UI 框架**：`package.json` 的 `dependencies` 命中其一：`element-plus`、`ant-design-vue`、`vuetify`、`naive-ui`、`@mui/material`、`@chakra-ui/react` 等。
+- **全局样式覆盖风险**：根样式或全局入口中存在通配选择器（如 `* {`、`html, body` 大包）、或抽样可见大量 `!important` 与深度选择器混用（仅作辅助信号，命中则偏老项目）。
+
+**新项目（可走 §1.1 一次性全局基线）**，需**同时**满足：
+
+- 上述「老项目」四条**均未**命中。
+- 且 `*.vue` / `*.tsx` / `*.jsx` 计数 **< 15**（或主业务目录下可数的页面级组件极少）。
+
+**不确定**：凡计数落在 **15～39** 之间、或仅有弱信号时，**按老项目处理**，仅允许局部基线或单模块试点，禁止首轮全量全局 reset。
+
+### 1.1 新项目（无历史负担）
+
+- 可一次性启用全局基线（推荐）。
+- 首版建议最小集合：
+  - `box-sizing: border-box`（含 `*::before/*::after`）
+  - 常见标签 margin/padding reset
+  - 媒体元素 `display:block` 与 `max-width:100%`
+  - 统一字体基线（family/size/line-height）
+  - 焦点可见策略（`focus-visible`）
+
+### 1.2 老项目（已有线上页面）
+
+- 禁止直接全量覆盖全局 reset。
+- 采用“分层 + 分阶段 + 可回滚”：
+  1. 新增 `baseline layer`（仅声明基线，不改业务样式）。
+  2. 先对“新页面/新组件”生效（范围隔离或入口分批）。
+  3. 用视觉回归与缺陷工单推进存量页迁移。
+  4. 每轮迁移可独立回滚。
+
+## 2. 生成时行为约束（强制）
+
+- 未显式声明前，生成组件默认假设 `border-box`。
+- 在 `flex` 文本容器中必须显式处理溢出：`min-w-0` + `truncate`（或等效策略）。
+- 弹层/下拉必须“锚定触发器”，禁止页面坐标硬定位。
+- 图标优先复用项目图标系统；若缺失，用本地 `inline svg`，禁止运行时依赖 Figma 临时资产 URL。
+- 默认覆盖 `default/hover/focus/active/selected/disabled`（按设计需求裁剪）。
+- 禁止为“临时对齐”引入无意义嵌套；结构必须最小可读。
+
+## 3. 老项目安全闸（强制）
+
+- 当检测到项目未完成 reset 或存在历史样式冲突：
+  - 先输出“风险清单”（组件、影响面、回滚点）再改。
+  - 优先局部基线（页面容器或组件命名空间）而非全局覆盖。
+  - 不得在同一轮同时做“全局 reset + 大规模业务重构”。
+
+## 4. 验证与验收（强制）
+
+- 每次变更后至少执行：改动文件 lint + 关键页面可视化验证。
+- 验收输出必须包含：
+  1. 本轮基线策略（新项目全局/老项目分层）
+  2. 影响范围
+  3. 回滚方式
+  4. 与组件生成约束的一致性说明
+
+## 5. 失败反馈格式（固定）
+
+1. 失败原因（违反哪条基线或安全闸）
+2. 定位信息（文件 + 规则项）
+3. 修复动作（分阶段方案与回滚点）

package/cursor-bootstrap/skills/figma-mcp-local-cache/SKILL.md

@@ -5,185 +5,33 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 
 # Figma MCP Local Cache
 
-本 Skill 与仓库规则 **`.cursor/rules/01-figma-cache-core.mdc`** **对齐**（表现层见栈占位 `02-figma-stack-adapter.mdc` 或你项目内的 `02-figma-<栈>-adapter.mdc`）：触发条件、闭环校验、回复开头 Blockquote **均为强制**。
+本 Skill 仅定义“执行次序与最小输出”。权威约束以 `.cursor/rules/01-figma-cache-core.mdc` 为准；若冲突，以规则文件为准。
 
-<Trigger Conditions>
+## 触发
+- 用户消息包含 Figma URL、`fileKey+nodeId`、或“figma 缓存/本地缓存/刷新”语义时触发。
 
-满足以下任一模式时，Agent **必须**进入本 Skill 的标准流程（标准化 → 读索引 → 本地或 MCP → 写回 → **upsert/ensure 后 validate**），并在用户可见回复**首段**输出规则所要求的缓存状态 Blockquote：
-
-| 类型 | 用户原话 / 消息特征（示例模式，非穷举） |
-| --- | --- |
-| URL | 含 `https://www.figma.com/`、`http://figma.com/`、`figma.com/file/`、`figma.com/design/`、`figma.com/proto/`、`figma.com/embed` 等 |
-| 参数 | 含 `node-id=`、`type=design` 等与 Figma 链接常见的查询串 |
-| 键值 | 出现 `figma` 文件 key（约 22 字符）且同时出现 `node-id` /「节点」描述，意图为对齐某一节点 |
-| 缓存词 | 「figma 缓存」「本地缓存」「先查缓存」「figma-cache」「index.json」「spec.md」「state-map」「命中/未命中」等且与具体设计任务绑定 |
-| 落地词 | 「按 Figma 做」「还原设计稿」「对齐 Figma」「实现该节点」且上下文可解析出链接或 fileKey/node |
-| 刷新词 | 「跳过缓存」「强制刷新」「以 Figma 最新为准」——走 MCP 与回写，状态标「更新」、来源 MCP |
-
-未出现可解析链接/键/节点且纯概念讨论时，可不执行缓存流水线。
-
-</Trigger Conditions>
-
-## 适用场景
-- 用户提供新的 Figma 链接并要求解析设计信息。
-- 用户再次提供同一 Figma 文件或同一 node-id，期望复用历史结果。
-- 用户明确要求「先查本地，不够再调 MCP」。
-
-## 目录约定
-- 缓存根目录（默认）：`figma-cache/`
-- 索引文件（默认）：`figma-cache/index.json`
-- 单链接缓存目录：`figma-cache/files/<fileKey>/nodes/<nodeId>/`
-- 单链接缓存文件：
-  - `meta.json`：基础元数据与来源信息
-  - `spec.md`：可读规格摘要
-  - `state-map.md`：状态与交互映射（如适用）
-  - `raw.json`：必要的原始结构化数据摘录
-- 可配置项：
-  - `FIGMA_CACHE_DIR`：缓存根目录
-  - `FIGMA_CACHE_INDEX_FILE`：索引文件名或绝对路径
-  - `FIGMA_ITERATIONS_DIR`：历史回填目录
-  - `FIGMA_CACHE_STALE_DAYS`：陈旧阈值（天）
-  - `FIGMA_DEFAULT_FLOW`：默认 flowId（大迭代可减少重复 `--flow`）
-
-## 流程关系（Flow）
-- `figma-cache/index.json` 中的 `flows` 用于维护业务/交互流程的节点集合与边关系。
-- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
-- 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
-- flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
-- 不触发：单链接且无关系意图、仅视觉微调、仅资产导出。
-
-## 标准流程
-1. 按 `figma-cache/docs/link-normalization-spec.md` 标准化链接并生成键：
-   - 节点级：`cacheKey = <fileKey>#<nodeId>`
-   - 文件级（无 `node-id`）：`cacheKey = <fileKey>#__FILE__`
-2. 读取 `index.json`：
-   - 若命中且字段满足当前任务，直接读取本地缓存并继续实现。
-   - 若未命中或信息不足，再调用 Figma MCP 拉取缺失数据。
-3. 若需调用 MCP，默认按 **最小调用集**执行（同一 `fileKey + nodeId`）：
-   - `get_design_context`（建议 `excludeScreenshot=true`）
+## 执行清单（按序）
+1. 标准化链接，先查 `figma-cache/index.json`（`figma:cache:get`）。
+2. 命中且字段足够：复用本地缓存，结束。
+3. 未命中/不足：仅调最小 MCP 集（默认）：
+   - `get_design_context`（`excludeScreenshot=true`）
    - `get_metadata`
    - `get_variable_defs`
-4. **按需扩展调用**：
-   - `get_screenshot` 仅在用户明确要求截图原始留档，或前三项不足以消除结构歧义时调用。
-   - `whoami` 仅在鉴权/权限报错时调用；无报错时不调用。
-5. **`get_design_context` 单轮硬约束**：同一 `fileKey + nodeId` 下，若已成功调用一次 `get_design_context`，除非参数发生变化（如 `forceCode`、`disableCodeConnect`、`excludeScreenshot`）或出现明确报错，否则禁止再次调用。
-6. **按 completeness 的调用矩阵（强制）**：
-   - `layout` → `get_metadata`（若结构层级不足，再补 `get_design_context`）
-   - `text` → `get_design_context`
-   - `tokens` → `get_variable_defs`
-   - `interactions` / `flow` / `states` → `get_design_context`，并同步完善 `state-map.md` / `flows`
-   - `accessibility`（若任务声明）→ 优先 `get_design_context` 语义线索，不足需显式标注缺口
-   - `assets`（若任务声明）→ 使用 `get_design_context` 资产 URL；截图按需
-7. **两阶段拉取**：先最小必要调用并检查字段缺口；仅在缺口存在时补调。
-8. 同一参数的 MCP 工具在单轮内不得重复调用；若需落盘原始数据，必须优先复用首次响应。
-9. **原始大文本直存策略**：当需保存 `mcp-raw-get-design-context.txt` 时，优先直接写入 `mcp-raw/` 子目录（不改写、不摘要、不二次解释），避免把整段文本再次喂给模型。
-10. **反截断约束（强制）**：`mcp-raw` 文件中禁止出现摘要/截断标记（如 `omitted for brevity`、`...response omitted...`、`省略`、`截断`）；一旦出现，必须视为无效证据并重新落盘完整回包。
-11. **完整性签名（强制）**：`mcp-raw-manifest.json` 必须提供 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数）；任一工具文件不匹配即视为证据损坏。
-12. **落盘后即时反精简检查（强制）**：每次写入 `mcp-raw` 后，必须立即执行反精简检查（截断标记 + hash/size）；并在用户回复中显式输出 `mcp-raw anti-truncation: pass|fail`。
-13. **本地分析优先**：若本地已存在可用 `mcp-raw-*` 与缓存加工文件，且用户未要求刷新/强制最新，后续分析默认只读本地文件，不再调用 Figma MCP。
-14. 发生 MCP 拉取或本地补齐时，写入/更新 `meta.json`、`spec.md`、必要补充文件，并更新索引。
-15. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅补齐索引与骨架文件，不能替代 MCP 拉取；不得把“执行了 ensure”当成“完成了 figma-mcp 调用”。
-16. **MCP 证据门禁（强制）**：当输出来源声明为 `figma-mcp` 时，节点目录必须存在 `mcp-raw/` 及最小调用集原始回包（按 completeness 裁剪）；若缺失，立即停止并报告“未完成”，不得宣称更新成功。
-17. **调用预算**：单节点默认 MCP 调用不超过 3 次；超过时必须在回复中说明缺口字段与补调理由。
-18. **重试策略**：仅对超时/5xx进行指数退避重试；参数错误/权限错误不重试并直接报告。
-19. **大文件读取策略（强制）**：
-   - UI 还原/像素对齐/组件实现任务：默认必须读取 `mcp-raw-get-design-context.txt` 全文，不反复拉扯“是否需要读全文”。
-   - 非 UI 任务（命中检查、预算统计、校验、流程维护）：默认只读 `raw.json`/`spec.md`/`mcp-raw-manifest.json`。
-20. **闭环校验（强制）**：凡本轮执行了 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`**（任意参数组合），在命令成功结束后，Agent **必须**在同一仓库根目录**自动、静默**执行 `npm run figma:cache:validate`。
-21. **校验失败**：根据脚本输出修复索引、`paths`、缺失文件、JSON 结构等，**循环执行 validate 直至退出码为 0**；不得在 validate 未通过时结束本轮「写缓存」任务。
-22. 对用户反馈时除 Blockquote 外可补充：`source: local-cache` / `source: figma-mcp`、`mcp-raw anti-truncation: pass|fail` 与简要文件列表（不必粘贴完整终端日志）。
-
-## Agent 最终输出格式（强制）
-- 触发 `<Trigger Conditions>` 且本轮触碰缓存读写的回复，**第一段**必须为单行 Blockquote：
-  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
-- `nodeId` 与索引一致；文件级写 `__FILE__` 或与 `index.json` 相同的占位。
-- Blockquote 之后接任务正文。
+4. 原始回包写入 `mcp-raw/`，并写 `mcp-raw-manifest.json`（必须含 `files/fileHashes/fileSizes/toolCalls`）。
+5. 立即执行反精简检查（截断标记 + hash/size）并记录结果。
+6. 执行 `upsert/ensure` 后自动执行 `validate`；失败时自修复并循环到通过。
 
-## 执行责任
-- 默认由 agent 执行缓存查询、写入、**upsert/ensure 后的 validate**、失败自修复与回填，用户不需要手动执行命令。
-- 仅当用户明确要求「我自己执行」或「请给我命令」时，才提供命令让用户手动运行。
-- 在常规对话中，以「已自动完成」方式汇报，不要求用户额外操作。
+## 关键约束
+- 禁止同参数重复调用 MCP。
+- `flow` 非默认维度，仅白名单触发时追加，并在回复说明原因。
+- 缓存任务默认不写业务 UI 代码。
 
-## 索引建议结构
-```json
-{
-  "schemaVersion": 2,
-  "version": 1,
-  "updatedAt": "2026-04-14T12:00:00Z",
-  "flows": {
-    "example-flow": {
-      "id": "example-flow",
-      "title": "Example",
-      "nodes": ["xxxx#12:34"],
-      "edges": [
-        {
-          "id": "edge-1",
-          "from": "xxxx#12:34",
-          "to": "xxxx#56:78",
-          "type": "next_step",
-          "note": "",
-          "createdAt": "2026-04-14T12:00:00Z"
-        }
-      ],
-      "assumptions": [],
-      "openQuestions": []
-    }
-  },
-  "items": {
-    "fileKey#nodeId": {
-      "fileKey": "xxxx",
-      "nodeId": "12:34",
-      "scope": "node",
-      "url": "https://www.figma.com/file/xxxx?node-id=12%3A34",
-      "originalUrls": [
-        "https://www.figma.com/file/xxxx?node-id=12%3A34&t=abc",
-        "https://www.figma.com/design/xxxx?node-id=12:34"
-      ],
-      "normalizationVersion": 1,
-      "paths": {
-        "meta": "figma-cache/files/xxxx/nodes/12-34/meta.json",
-        "spec": "figma-cache/files/xxxx/nodes/12-34/spec.md",
-        "stateMap": "figma-cache/files/xxxx/nodes/12-34/state-map.md",
-        "raw": "figma-cache/files/xxxx/nodes/12-34/raw.json"
-      },
-      "syncedAt": "2026-04-14T12:00:00Z",
-      "completeness": ["layout", "text", "tokens", "interactions", "states", "accessibility"]
-    }
-  }
-}
-```
-
-## 刷新策略
-- 用户说「强制刷新/以最新 Figma 为准」：直接走 MCP，并覆盖 `syncedAt` 与内容；Blockquote 标「更新」、来源 MCP。
-- 仅缺某些字段：执行部分刷新，保留已有内容，更新 `completeness`。
-- 若链接无 `node-id`，先缓存到文件级（`__FILE__`），再按后续 node 增量补充。
-- 当 `syncedAt` 超过 14 天时，默认先提示用户是否刷新。
-- 若需“保存 MCP 原始数据”，默认保存最小调用集三项原始回包；截图原始回包按需保存。
-- 原始数据统一写到节点目录 `mcp-raw/` 子目录；加工缓存继续放在节点根目录（`meta.json` / `raw.json` / `spec.md` / `state-map.md`）。
-- 默认不保存 `whoami` 原始文件；仅在鉴权排障或用户显式要求时保存。
-- 对 `mcp-raw-get-design-context.txt` 优先采用“直存”方式（不二次改写正文），降低 token 消耗并保持可追溯性。
-- `completeness` 建议至少按以下维度声明：`layout`、`text`、`tokens`、`interactions`、`flow`、`states`、`assets`、`accessibility`（按任务取子集）。
-- `mcp-raw-manifest.json` 应包含审计字段：`callPolicy`（如 `minimum-set-v1`）、`dedupeApplied`（布尔）、`toolCalls`（每个工具的 `count` / `effectiveSaved`），便于后续统计与复盘。
-- 折中推荐：在 `raw.json` 增加 `coverageSummary`（`covered` / `missing` / `evidence`）用于最小覆盖审计，不强制完整模板。
-
-## 输出约束
-- **必须先**输出规定的缓存状态 Blockquote，再给出设计结论或实现说明。
-- 若跳过 MCP，Blockquote 中来源为 Local，状态多为「命中」。
-- 若调用 MCP，Blockquote 中来源为 MCP，状态多为「缺失→更新」或「更新」，并在后文简述触发原因（未命中/信息不足/用户强刷）。
-- 默认采用低 token 输出：不回显 MCP 原始正文，仅输出调用统计、文件落盘与校验结果。
-- 用户若明确要求“查看原文/贴出回包”时，才输出必要片段；默认引导用户查看 `mcp-raw/*` 本地文件。
+## 用户可见输出（最小化）
+- 首行固定：
+  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
+- 仅补充：`mcp-raw anti-truncation`、MCP 调用统计、最终 completeness、文件清单、validate 结果。
+- 除非用户明确要求，禁止贴 MCP 原文与长日志。
 
-## 推荐命令（v2 流程）
-- `npm run figma:cache:init`：初始化空索引（用于纯净移植）
-- `npm run figma:cache:config`：查看当前生效配置
-- `npm run figma:cache:get -- "<figma-url>"`：检查命中情况
-- 先执行 MCP 最小调用集并写入 `mcp-raw/`，再执行：`npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility`
-- `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility`：自动补齐缓存骨架文件（非 MCP 拉取）
-- 若命中 flow 白名单场景，自动或显式追加：`--completeness=layout,text,tokens,interactions,states,accessibility,flow`
-- 一旦自动追加了 `flow`，对用户回复必须附带触发原因：`关键词命中` 或 `多链接串联意图`。
-- MCP 默认最小调用集：`get_design_context(excludeScreenshot=true)` + `get_metadata` + `get_variable_defs`
-- `npm run figma:cache:validate`：**每次 upsert/ensure 成功后必须自动执行**；失败则修至通过
-- `npm run figma:cache:budget`：查看 MCP 节点预算汇总（默认 `--mcp-only`，按文件大小估算 token 代理）
-- `npm run figma:cache:stale`：检查超 14 天的陈旧缓存
-- `npm run figma:cache:backfill`：从历史迭代文档回填索引
-- `npm run figma:cache:flow:init|add-node|link|chain|show|mermaid`：维护流程关系
+## 模板维护约定（强制）
+- `cursor-bootstrap` 是 Skill 唯一手写来源。
+- 仓库内 `.cursor/skills/*` 为镜像产物，使用 `npm run cursor:shadow:sync` 同步生成。

package/cursor-bootstrap/skills/figma-ui-dual-mode-execution/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: figma-ui-dual-mode-execution
+description: 仅用 nodeId（如 9277-28772）或 Figma 链接触发 UI 实现，自动在短流程与严格流程间切换。
+---
+
+# Figma UI Dual Mode Execution
+
+本 Skill 用于：用户仅提供节点线索（节点目录名、nodeId、或带 node-id 的 Figma 链接）时，自动完成“定位缓存 -> 判定模式 -> 实现与验证”。
+
+## 支持输入
+
+- 节点目录名：如 `9277-28772`
+- nodeId：如 `9277:28772`
+- Figma 链接：`...node-id=9277-28772`（需转换为 `9277:28772`）
+
+## 执行步骤（强制）
+
+1. 规范化节点标识：
+   - `9277-28772` -> `9277:28772`
+2. 在 `figma-cache/index.json` 查命中并定位节点目录。
+3. 读取四份必读文件：
+   - `spec.md`
+   - `raw.json`
+   - `state-map.md`
+   - `mcp-raw-get-design-context.txt`
+4. 模式选择：
+   - 默认短流程；
+   - 命中任一升级条件（老项目/全局样式改动/复杂状态/历史漂移问题/信息冲突）-> 切严格流程。
+5. 预检文档策略（降噪）：
+   - 默认短流程：可跳过完整预检文档，仅输出精简事实清单。
+   - 严格流程：必须基于 `cursor-bootstrap/examples/ui-1to1-preflight.template.md` 生成并填写“预检文档”（可落到项目 `figma-cache/docs/` 或节点目录旁），至少完成：设计值快照、状态对照表、1:1 预检清单。
+6. 先输出“事实对齐清单”，再实现组件与挂载。
+7. 改动后执行 lint，并输出映射与验证结论。
+
+## 关键硬约束
+
+- 冲突裁决顺序：`mcp-raw-get-design-context.txt` 优先。
+- 禁止猜测设计值；无法裁决必须先提问。
+- 禁止使用 Figma 临时远程资产 URL 作为运行时图标。
+- 图标优先项目图标系统；无则 `inline svg`。
+- 默认按 `border-box` 思维实现；弹层必须锚定触发器。
+
+## 固定输出
+
+1. 缓存定位结果（命中节点目录）
+2. 事实对齐清单（结构/文案/token/状态/交互）
+3. 变更文件列表
+4. 关键设计值 -> 代码映射
+5. lint/验证结果
+6. 未决问题（如有）

package/cursor-bootstrap/skills/ui-baseline-governance/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ui-baseline-governance
+description: 为新项目或老项目建立可执行的全局样式基线，并把约束固化到组件生成行为。
+---
+
+# UI Baseline Governance Skill
+
+本 Skill 用于“要不要上全局 reset / 如何在老项目安全落地 / 如何约束后续组件生成”三类问题。
+若与规则冲突，以 `.cursor/rules/04-ui-baseline-governance.mdc` 为准。
+
+## 触发场景
+
+- 用户询问：全局 `border-box`、reset、默认样式基线。
+- 用户反馈：组件反复出现超高/超宽/对齐漂移/图标不可见。
+- 用户要求：把经验沉淀为长期规范，约束后续 Agent 生成行为。
+
+## 执行步骤（按序）
+
+1. 判断项目类型：`新项目` 或 `老项目`（**必须**按 `.cursor/rules/04-ui-baseline-governance.mdc` §1.0 机械启发式执行，输出结论 + 命中证据；不确定则按老项目）。
+2. 输出一份“基线实施决策”：
+   - 新项目：一次性全局基线
+   - 老项目：分层分批迁移
+3. 给出最小基线清单（不与栈强耦合）：
+   - `border-box`
+   - margin/padding reset
+   - 媒体元素 display 规则
+   - 字体基线
+   - focus-visible
+4. 同步“生成约束”到执行口径：
+   - 默认 `box-border`
+   - 文本溢出显式处理
+   - 弹层锚定触发器
+   - 图标优先项目库，兜底 `inline svg`
+   - 状态覆盖完整
+5. 给出验证与回滚方案：
+   - lint + 视觉检查
+   - 影响范围
+   - 回滚点
+
+## 用户可见输出模板（精简）
+
+1. 当前项目类型与推荐策略（全局 or 分层）
+2. 本轮要落的基线条目（最多 5 条）
+3. 对后续组件生成的强约束（最多 5 条）
+4. 验证与回滚
+
+## 禁止事项
+
+- 不得在老项目直接“全局 reset + 大规模重构”同轮执行。
+- 不得把框架私有实现写入 `figma-cache/files/**` 的通用缓存文档。
+- 不得在未声明风险的情况下修改大范围全局样式。

package/figma-cache/js/cursor-bootstrap-cli.js

@@ -32,6 +32,14 @@ function copyCursorBootstrap(force, deps) {
       from: path.join("rules", "02-figma-stack-adapter.mdc"),
       to: path.join(".cursor", "rules", "02-figma-stack-adapter.mdc"),
     },
+    {
+      from: path.join("rules", "03-figma-ui-implementation-hard-constraints.mdc"),
+      to: path.join(".cursor", "rules", "03-figma-ui-implementation-hard-constraints.mdc"),
+    },
+    {
+      from: path.join("rules", "04-ui-baseline-governance.mdc"),
+      to: path.join(".cursor", "rules", "04-ui-baseline-governance.mdc"),
+    },
     {
       from: path.join("rules", "figma-local-cache-first.mdc"),
       to: path.join(".cursor", "rules", "figma-local-cache-first.mdc"),
@@ -40,6 +48,14 @@ function copyCursorBootstrap(force, deps) {
       from: path.join("skills", "figma-mcp-local-cache", "SKILL.md"),
       to: path.join(".cursor", "skills", "figma-mcp-local-cache", "SKILL.md"),
     },
+    {
+      from: path.join("skills", "ui-baseline-governance", "SKILL.md"),
+      to: path.join(".cursor", "skills", "ui-baseline-governance", "SKILL.md"),
+    },
+    {
+      from: path.join("skills", "figma-ui-dual-mode-execution", "SKILL.md"),
+      to: path.join(".cursor", "skills", "figma-ui-dual-mode-execution", "SKILL.md"),
+    },
   ];
 
   if (!fs.existsSync(CURSOR_BOOTSTRAP_DIR)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
   "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
   "keywords": [
@@ -37,8 +37,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "test": "npm run docs:encoding:check && node tests/smoke.js",
-    "prepack": "npm run docs:encoding:check && node bin/figma-cache.js validate",
+    "test": "npm run cursor:shadow:check && npm run docs:encoding:check && node tests/rules-guard.js && node tests/smoke.js",
+    "prepack": "npm run cursor:shadow:check && npm run docs:encoding:check && node bin/figma-cache.js validate",
     "figma:cache:normalize": "node bin/figma-cache.js normalize",
     "figma:cache:get": "node bin/figma-cache.js get",
     "figma:cache:upsert": "node bin/figma-cache.js upsert",
@@ -56,6 +56,8 @@
     "figma:cache:flow:show": "node bin/figma-cache.js flow show",
     "figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid",
     "figma:cache:cursor:init": "node bin/figma-cache.js cursor init",
+    "cursor:shadow:sync": "node scripts/sync-cursor-shadow.js",
+    "cursor:shadow:check": "node scripts/check-cursor-shadow.js",
     "docs:encoding:check": "node scripts/check-doc-encoding.js",
     "figma:cache:mobile:spec": "node scripts/mobile/generate-mobile-spec.js"
   },