figma-cache-toolchain 2.0.1 → 2.0.2

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/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-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.1",
+  "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": [