figma-cache-toolchain 2.0.2 → 2.0.4

package/README.md

@@ -1,170 +1,201 @@
-# figma-cache-toolchain
-
-面向业务项目的 Figma 本地缓存工具链：默认采用“本地缓存优先 + 按需 MCP + 最小调用集 + 严格证据校验 + validate 闭环”，提供链接标准化、索引与流程关系维护、缓存读写、校验与预算分析能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
-
-- npm 包：`figma-cache-toolchain`
-- Git 仓库：<https://github.com/907086379/figma-cache-toolchain.git>
-
----
-
-## 这份 README 面向谁
-
-- npm 用户：把工具链接入业务项目并日常使用
-- git 用户：在仓库内开发、测试、提交改动
-
-> npm 发布由仓库维护者负责；普通用户和贡献者无需执行 `npm publish`。
-
----
-
-## npm 用户快速开始
-
-### 1) 安装
-
-```bash
-npm i -D figma-cache-toolchain
-```
-
-### 2) 初始化 Cursor 模板与任务书
-
-```bash
-npx figma-cache cursor init
-```
-
-该命令会：
-
-- 默认覆盖写入最新 `.cursor/rules/`、`.cursor/skills/` 模板
-- 新增通用规则：`.cursor/rules/00-output-token-budget.mdc`（全任务低 token 输出基线）
-- 若需保留已存在模板，可使用 `npx figma-cache cursor init --force`（跳过同名覆盖）
-- 确保根目录存在 `figma-cache.config.js`
-- 刷新根目录 `AGENT-SETUP-PROMPT.md`
-- 同步刷新 `figma-cache/docs/colleague-guide-zh.md`
-
-### 3) 初始化本地缓存索引
-
-```bash
-npm run figma:cache:init
-```
-
-若项目还没配置 scripts，可临时使用：
-
-```bash
-npx figma-cache init
-```
-
-### 4) 执行校验
-
-```bash
-npm run figma:cache:validate
-```
-
----
-
-## 团队协作建议（来自同事指南精简版）
-
-- 默认执行链：**先查缓存** -> 按需 MCP -> 原始回包写 `mcp-raw/` -> `upsert/ensure` -> `validate`
-- 当 `source=figma-mcp` 时，`mcp-raw` 证据不完整会被门禁拦截，不能只写骨架宣称成功
-- 默认 completeness：`layout,text,tokens,interactions,states,accessibility`
-- `flow` 仅在关系关键词命中或多链接明确串联意图时自动追加
-- 回报建议包含：缓存状态、来源（Local/MCP）、MCP 调用次数、输出文件清单
-- 团队可直接复用 `figma-cache/docs/colleague-guide-zh.md` 中的主提示词模板
-
----
-
-## 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`）。
-
-- `flow` 默认关闭，避免常规场景冗余
-- 自动追加 `flow` 仅命中白名单时触发：
-  - 关系关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
-  - 同轮或断续出现多个 Figma 链接，且明确存在先后/串联意图（如 A->B）
-- 以下场景不自动追加 `flow`：单链接且无关系意图、仅视觉微调/文案修改、仅资产导出
-- `assets` 仍按需开启，避免资产留档体积膨胀
-- token 开销通常在启用 `flow` 且节点复杂时上升更明显
-- 触发自动补 `flow` 时，建议在执行日志/回复中记录触发原因（关键词命中或多链接串联意图），便于审计
-
-按需覆盖示例：
-
-```bash
-# 常规场景
-npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
-
-# 关联节点/同轮或断续多链接串联场景（自动或显式）
-npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow
-
-# 同时需要资产留档
-npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow,assets
-```
-
----
-
-## 常用命令
-
-```bash
-npm run figma:cache:init
-npm run figma:cache:config
-npm run figma:cache:get -- "<figma-url>"
-npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility
-npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
-npm run figma:cache:validate
-npm run figma:cache:budget
-npm run figma:cache:stale
-npm run figma:cache:backfill
-```
-
-严格证据模式（默认开启）：
-
-- 当 `source=figma-mcp` 时，`upsert/ensure` 会先校验 `mcp-raw` 证据映射
-- 仅在你明确需要先落索引骨架时，才使用 `--allow-skeleton-with-figma-mcp`
-- `validate` 会校验 `coverageSummary.evidence`，缺失或 TODO 占位会失败
-
----
-
-## git 用户（仓库开发）
-
-### 1) 克隆并安装依赖
-
-```bash
-git clone https://github.com/907086379/figma-cache-toolchain.git
-cd figma-cache-toolchain
-npm ci
-```
-
-### 2) 本地自检
-
-```bash
-npm run docs:encoding:check
-npm test
-```
-
-### 3) 提交前建议
-
-- 确认 `README.md`、`figma-cache/docs/*.md` 编码为 UTF-8 无 BOM
-- 变更 CLI 行为后，同步更新文档与示例命令
-- 只提交与本次任务相关文件
-
----
-
-## 文档入口
-
-- `figma-cache/docs/README.md`：完整脚本、环境变量、回填与维护说明
-- `figma-cache/docs/colleague-guide-zh.md`：团队协作指南与提示词模板
-- `figma-cache/docs/quick-start-zh.md`：一页式同事速查卡（3 分钟上手）
-- `figma-cache/docs/link-normalization-spec.md`：链接标准化规范
-- `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
-- `AGENT-SETUP-PROMPT.md`：项目接入任务书（`cursor init` 会刷新）
-- `docs/mobile-native-adapter-template.md`：iOS/Android 双端适配模板与最小转换脚本说明
+# figma-cache-toolchain
+
+面向业务项目的 Figma 本地缓存工具链：默认采用“本地缓存优先 + 按需 MCP + 最小调用集 + 严格证据校验 + validate 闭环”，提供链接标准化、索引与流程关系维护、缓存读写、校验与预算分析能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
+
+- npm 包：`figma-cache-toolchain`
+- Git 仓库：<https://github.com/907086379/figma-cache-toolchain.git>
+
+---
+
+## 这份 README 面向谁
+
+- npm 用户：把工具链接入业务项目并日常使用
+- git 用户：在仓库内开发、测试、提交改动
+
+> npm 发布由仓库维护者负责；普通用户和贡献者无需执行 `npm publish`。
+
+---
+
+## npm 用户快速开始
+
+### 1) 安装
+
+```bash
+npm i -D figma-cache-toolchain
+```
+
+### 2) 初始化 Cursor 模板与任务书
+
+```bash
+npx figma-cache cursor init
+```
+
+该命令会：
+
+- 默认安全模式：保留已有 `.cursor/rules/`、`.cursor/skills/`，仅补缺失文件
+- 新增通用规则：`.cursor/rules/00-output-token-budget.mdc`（全任务低 token 输出基线）
+- 若需覆盖现有模板，可使用 `npx figma-cache cursor init --overwrite`
+- 确保根目录存在 `figma-cache.config.js`
+- 刷新根目录 `AGENT-SETUP-PROMPT.md`
+- 同步刷新 `figma-cache/docs/colleague-guide-zh.md`
+
+### 3) 初始化本地缓存索引
+
+```bash
+npm run figma:cache:init
+```
+
+若项目还没配置 scripts，可临时使用：
+
+```bash
+npx figma-cache init
+```
+
+### 4) 执行校验
+
+```bash
+npm run figma:cache:validate
+```
+
+---
+
+## 团队协作建议（来自同事指南精简版）
+
+- 默认执行链：**先查缓存** -> 按需 MCP -> 原始回包写 `mcp-raw/` -> `upsert/ensure` -> `validate`
+- 当 `source=figma-mcp` 时，`mcp-raw` 证据不完整会被门禁拦截，不能只写骨架宣称成功
+- 默认 completeness：`layout,text,tokens,interactions,states,accessibility`
+- `flow` 仅在关系关键词命中或多链接明确串联意图时自动追加
+- 回报建议包含：缓存状态、来源（Local/MCP）、MCP 调用次数、输出文件清单
+- 团队可直接复用 `figma-cache/docs/colleague-guide-zh.md` 中的主提示词模板
+
+---
+
+## 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`）。
+
+- `flow` 默认关闭，避免常规场景冗余
+- 自动追加 `flow` 仅命中白名单时触发：
+  - 关系关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
+  - 同轮或断续出现多个 Figma 链接，且明确存在先后/串联意图（如 A->B）
+- 以下场景不自动追加 `flow`：单链接且无关系意图、仅视觉微调/文案修改、仅资产导出
+- `assets` 仍按需开启，避免资产留档体积膨胀
+- token 开销通常在启用 `flow` 且节点复杂时上升更明显
+- 触发自动补 `flow` 时，建议在执行日志/回复中记录触发原因（关键词命中或多链接串联意图），便于审计
+
+按需覆盖示例：
+
+```bash
+# 常规场景
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
+
+# 关联节点/同轮或断续多链接串联场景（自动或显式）
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow
+
+# 同时需要资产留档
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow,assets
+```
+
+---
+
+## 常用命令
+
+```bash
+npm run figma:cache:init
+npm run figma:cache:config
+npm run figma:cache:get -- "<figma-url>"
+npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
+npm run figma:cache:validate
+npm run figma:ui:preflight
+npm run figma:ui:audit -- --min-score=85
+npm run figma:ui:report:aggregate
+npm run figma:ui:accept -- --target=src/components/YourComponent.tsx
+npm run figma:ui:e2e:cross -- --target-project=E:/Work/vue-demo --fileKey=<fileKey> --nodeId=9277-28772 --target=E:/Work/vue-demo/src/components/YourComponent.vue
+npm run figma:ui:gate
+npm run figma:ui:gate:pr
+npm run figma:ui:gate:main
+npm run figma:cache:budget
+npm run figma:cache:stale
+npm run figma:cache:backfill
+```
+
+UI preflight/gate 说明：
+
+- `figma:ui:preflight` 会读取缓存索引与 adapter contract，输出 `figma-cache/reports/ui-preflight-report.json`
+- 若存在阻断项（如关键文件缺失、coverage evidence 缺失、contract 映射为空），命令返回退出码 `2`
+- `figma:ui:audit` 会输出 `figma-cache/reports/ui-1to1-report.json`，提供 `score.total/layout/text/token/state/interaction`、`diffs`、`blocking`、`warnings`
+- `figma:ui:audit` 基于 `figma-cache/js/ui-facts-normalizer.js` 统一标准化 `spec/raw/state-map/mcp-raw` 事实，默认更偏通用规则而非单组件特化
+- `figma:ui:audit` 会加载 `figma-cache/adapters/recipes/`（前10类高频组件库），仅做可选命中与建议，不做全局强制绑定
+- `figma:ui:gate` 会先跑 preflight + audit（默认阈值 `85`），再串联 `validate`、`cursor:shadow:check` 与 `npm test`
+- `figma:ui:report:aggregate` 会聚合 preflight + audit 报告，输出 `figma-cache/reports/ui-quality-summary.json`
+- `figma:ui:accept` 是一键自动验收：自动跑 preflight + audit + aggregate，并按效果阈值直接返回 pass/fail（退出码）
+- `figma:ui:e2e:cross` 是跨项目联调：自动 `npm pack` 当前包 -> 安装到目标项目 -> 执行自动验收 -> 回收报告路径与摘要
+- 支持 `--auto-ensure-on-miss`：cache miss 时自动尝试 `--source=figma-mcp ensure`
+- 支持 `--batch-file=<json>`：批量节点联调并汇总结果（单条失败即整体失败）
+- 支持 `--fix-loop=<N>`：失败后自动执行自修复重试（补 contract / 刷新缓存后重跑）
+- CI 建议矩阵：`figma:ui:gate:pr`（PR 最低门槛）与 `figma:ui:gate:main`（主干严格门槛）
+
+UI profile 分层（P3）：
+
+- `FIGMA_UI_PROFILE=fast|standard|strict`（默认 `standard`）
+- `fast`：低门槛快速反馈（audit 默认阈值 70）
+- `standard`：团队默认（audit 默认阈值 85）
+- `strict`：preflight warning 视为阻断，audit 默认阈值 92 且要求 `--target`
+
+严格证据模式（默认开启）：
+
+- 当 `source=figma-mcp` 时，`upsert/ensure` 会先校验 `mcp-raw` 证据映射
+- 仅在你明确需要先落索引骨架时，才使用 `--allow-skeleton-with-figma-mcp`
+- `validate` 会校验 `coverageSummary.evidence`，缺失或 TODO 占位会失败
+
+---
+
+## git 用户（仓库开发）
+
+### 1) 克隆并安装依赖
+
+```bash
+git clone https://github.com/907086379/figma-cache-toolchain.git
+cd figma-cache-toolchain
+npm ci
+```
+
+### 2) 本地自检
+
+```bash
+npm run docs:encoding:check
+npm test
+```
+
+### 3) 提交前建议
+
+- 确认 `README.md`、`figma-cache/docs/*.md` 编码为 UTF-8 无 BOM
+- 变更 CLI 行为后，同步更新文档与示例命令
+- 只提交与本次任务相关文件
+
+---
+
+## 文档入口
+
+- `figma-cache/docs/README.md`：完整脚本、环境变量、回填与维护说明
+- `figma-cache/docs/colleague-guide-zh.md`：团队协作指南与提示词模板
+- `figma-cache/docs/quick-start-zh.md`：一页式同事速查卡（3 分钟上手）
+- `figma-cache/docs/link-normalization-spec.md`：链接标准化规范
+- `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
+- `AGENT-SETUP-PROMPT.md`：项目接入任务书（`cursor init` 会刷新）
+- `docs/mobile-native-adapter-template.md`：iOS/Android 双端适配模板与最小转换脚本说明

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

@@ -1,4 +1,4 @@
-# Figma Cache：请 Agent 一次性完成项目适配
+# Figma Cache：请 Agent 一次性完成项目适配
 
 > **给 Cursor Agent 的指令**：你正在操作的是**用户业务项目**的根目录。以下文件应已存在（由 `npx figma-cache cursor init` 从 npm 包 **`{{NPM_PACKAGE_NAME}}`** 复制到当前仓库根）：
 > - `.cursor/rules/01-figma-cache-core.mdc`
@@ -7,45 +7,50 @@
 > - `.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.js`（示例 `postEnsure`：目录级 adapter hint + 全局 adapter contract + 可选 `docs/figma-flow-readme.md`）
 > - （兼容旧项目）`figma-cache.config.example.js` 可能存在；仅当内容被用户自定义且无法安全迁移时保留
 
 ## 你必须完成的任务（按顺序执行，尽量少问用户）
 
-1. **读取工程事实**  
+1. **读取工程事实**
    阅读 `package.json` 及存在的构建配置（如 `vite.config.*`、`vue.config.js`、`next.config.*`、`tsconfig.json` 等），**自行推断** UI 技术栈（框架、组件库、样式方案、状态管理若有则记录）。仅在关键信息完全无法从仓库推断时，再向用户提一个极简问题。
 
-2. **检查并合并 `figma-cache.config.js`**  
-   - 若根目录**不存在** `figma-cache.config.js`：基于当前文件创建完整配置，并实现与栈匹配的 `hooks.postEnsure`。  
-   - 若**已存在** `figma-cache.config.js`：**合并**而非盲目覆盖——保留用户已有非 figma-cache 字段，仅补充或调整 `hooks.postEnsure` 及与 figma-cache 相关的导出；冲突时以「不破坏用户现有逻辑」优先并注释说明。  
+2. **检查并合并 `figma-cache.config.js`**
+   - 若根目录**不存在** `figma-cache.config.js`：基于当前文件创建完整配置，并实现与栈匹配的 `hooks.postEnsure`。
+   - 若**已存在** `figma-cache.config.js`：**合并**而非盲目覆盖——保留用户已有非 figma-cache 字段，仅补充或调整 `hooks.postEnsure` 及与 figma-cache 相关的导出；冲突时以「不破坏用户现有逻辑」优先并注释说明。
    - 默认建议：`FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root`（目录级单文件，减少重复）；仅在团队明确需要节点文档时改为 `node`。
 
-3. **清理 legacy example（若安全）**  
+3. **落地全局 adapter contract（新增强制）**
+   - 若项目不存在 `figma-cache/adapters/ui-adapter.contract.json`：
+     - 从 `cursor-bootstrap/examples/ui-adapter.contract.template.json` 复制生成（或等价内容生成）。
+   - 若已存在：保留用户版本，不覆盖。
+   - 后续 UI 实现必须先读该 contract，将 token/state 映射到项目实现；未映射项先补 contract 或询问用户，禁止猜测。
+
+4. **清理 legacy example（若安全）**
    若根目录存在 `figma-cache.config.example.js` 且其内容与 `figma-cache.config.js` 等价（或为未改动模板），请删除该 example 文件，避免后续协作混淆。
 
-4. **生成栈专属 Adapter 规则**  
+5. **生成栈专属 Adapter 规则**
    新建 **`.cursor/rules/02-figma-<栈简名>-adapter.mdc`**（`alwaysApply: false`）。内容须与 **`01-figma-cache-core.mdc`** 边界一致：只约束「在通用缓存可读之后如何写业务 UI」；**禁止**要求在 `meta.json` / `raw.json` / `spec.md` 中写入框架专有实现。
 
-5. **删除占位规则**  
-   确认第 4 步文件已写入且无语法问题后，**删除** `.cursor/rules/02-figma-stack-adapter.mdc`。若用户在 Cursor 设置里固定引用了该文件名，请在汇报中提示用户改为引用新的 `02-figma-<栈>-adapter.mdc`。
+6. **删除占位规则**
+   确认第 5 步文件已写入且无语法问题后，**删除** `.cursor/rules/02-figma-stack-adapter.mdc`。若用户在 Cursor 设置里固定引用了该文件名，请在汇报中提示用户改为引用新的 `02-figma-<栈>-adapter.mdc`。
 
-6. **补全 npm scripts（若缺失）**  
+7. **补全 npm scripts（若缺失）**
    若 `package.json` 中没有任何 `figma:cache:*` 脚本，请追加一组，命令使用 **`npx figma-cache`** 或 **`figma-cache`**（与项目是否已安装本包、以及 `node_modules/.bin` 是否可用一致即可，优先 `npx figma-cache` 以减少环境差异）。至少包含：`init`、`config`、`validate`、`ensure`、`get`（名称与 `figma-cache --help` 或包内 **`figma-cache/docs/README.md`** 中 scripts 示例一致即可）。
 
-7. **收尾**  
-   - 用简短列表向用户汇报：新建/修改/删除了哪些路径。  
-   - 若项目根**尚无** `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 + 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 溢出、弹层锚定、图标策略等）。
+8. **收尾**
+   - 用简短列表向用户汇报：新建/修改/删除了哪些路径。
+   - 若项目根**尚无** `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 + figma-mcp-local-cache Skill** 驱动；涉及全局样式与组件生成稳定性时叠加 **04-ui-baseline-governance**。
+   - **可选**：若项目已通过 `cursor init` 同步 `figma-cache/docs/colleague-guide-zh.md`，提示团队默认只使用 **§5.1「最推荐主提示词」**，只有特殊诉求再追加 **§5.2** 的一句附加要求。
+
+9. **UI 全局基线治理（强烈推荐，与 UI 实现任务绑定）**
+   - 确认 `.cursor/rules/04-ui-baseline-governance.mdc` 已存在于项目根（随 `cursor init` 同步）；若缺失，从 npm 包内 `cursor-bootstrap/rules/` 补拷到当前仓库 `.cursor/`，并提示团队升级 **`{{NPM_PACKAGE_NAME}}`** 版本以便后续 init 自带。
+   - 读取 **`04-ui-baseline-governance.mdc` §1.0**：按机械启发式判定「新项目 / 老项目」，在汇报中写明**结论 + 命中证据**（文件路径、计数、依赖名）。
+   - 按判定结果执行：新项目可规划一次性全局基线；老项目仅允许分层/分批/可回滚方案，禁止首轮全量全局 reset 叠加大规模业务重构。
+   - 在 Cursor 中建议团队对「写业务 UI / 调全局样式」类任务 **@** 引用：`04-ui-baseline-governance.mdc`，以统一生成行为（`border-box` 假设、flex 溢出、弹层锚定、图标策略等）。
    - 降噪策略：默认使用短流程；仅在老项目、高风险任务或冲突场景升级严格流程。`ui-1to1-preflight.template.md` 仅在严格流程下强制填写，短流程可只输出精简事实清单。
 
 ## 输出与 token 约束（强制）
@@ -55,15 +60,15 @@
 
 ## 硬约束（违反则视为未完成）
 
-- **不要**修改 `node_modules/{{NPM_PACKAGE_NAME}}/` 下已发布包内文件（应无此必要）。  
-- **不要**修改 `figma-cache/figma-cache.js` 或破坏 Core「框架中立」语义。  
+- **不要**修改 `node_modules/{{NPM_PACKAGE_NAME}}/` 下已发布包内文件（应无此必要）。
+- **不要**修改 `figma-cache/figma-cache.js` 或破坏 Core「框架中立」语义。
 - **不要**把业务路由名、具体组件库 API 写进 `figma-cache/files/**` 下的 `meta.json` / `raw.json` / `spec.md`。
 
 ## 可选参考（仅在用户需要 Vue2+Vuetify2 时）
 
-包内附带参考文本（**不在 init 时复制到 .cursor**）：  
-`node_modules/{{NPM_PACKAGE_NAME}}/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`  
-若用户明确要求该栈，可读入后改写为第 4 步的 Adapter 规则内容。
+包内附带参考文本（**不在 init 时复制到 .cursor**）：
+`node_modules/{{NPM_PACKAGE_NAME}}/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`
+若用户明确要求该栈，可读入后改写为第 5 步的 Adapter 规则内容。
 
 ---
 

package/cursor-bootstrap/examples/README.md

@@ -1,11 +1,26 @@
-# 栈相关参考（不随 `cursor init` 复制）
-
-本目录存放 **可选** 的完整 Adapter 示例，供人工或 Agent 对照；**通用默认**请使用 `cursor init` 生成的 `02-figma-stack-adapter.mdc` 与根目录 `figma-cache.config.js`。
-
-| 文件 | 说明 |
-|------|------|
-| `vue2-vuetify2-adapter.reference.mdc` | 历史 Vue 2 + Vuetify 2 表现层规则全文，可复制为 `.cursor/rules/02-figma-vuetify2-adapter.mdc` 并按项目改名 |
-
-将参考规则复制进 `.cursor/rules/` 后，建议同步 `figma-cache.config.js` 的 adapter 提示策略：默认使用 `FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root`（目录级单文件），仅在明确需要节点文档时改为 `node`。
-
-
+# 栈相关参考（不随 `cursor init` 复制）
+
+本目录存放可选参考与模板文件：
+
+| 文件 | 说明 |
+|---|---|
+| `vue2-vuetify2-adapter.reference.mdc` | 历史 Vue2 + Vuetify2 参考规则 |
+| `generated-ui-reset.css.template` | 老项目 B0 局部 reset 模板（推荐默认） |
+| `ui-adapter.contract.template.json` | 全局 UI adapter contract 模板（token/state 映射单一真源） |
+| `ui-override.template.json` | 节点级 override 模板（仅处理局部差异） |
+| `ui-execution-template.fast.md` | 快速模式执行模板（fast） |
+| `ui-execution-template.strict.md` | 严格模式执行模板（strict） |
+
+## B0 推荐用法（目标业务项目）
+1. 复制模板到项目：`src/styles/generated-ui-reset.css`
+2. 在入口（如 `src/main.ts`）引入一次
+3. 生成组件根节点加 `generate-ui-reset`
+
+说明：B0 仅做局部基线，不污染全局；B1/B2 见 `04-ui-baseline-governance.mdc`。
+
+## 全局 adapter contract（推荐）
+
+- 在业务项目保留单文件：`figma-cache/adapters/ui-adapter.contract.json`
+- 该文件负责把 Figma token/state 映射到项目实现（变量、class、主题 token）。
+- 建议默认由 `figma-cache.config.js` 的 `postEnsure` 在“缺失时”自动创建，避免每个节点重复维护。
+- 节点级差异才使用 `figma-cache/files/<fileKey>/nodes/<nodeId>/ui-override.json`，且不得反向污染全局 contract。

package/cursor-bootstrap/examples/generated-ui-reset.css.template

@@ -0,0 +1,32 @@
+/* Generated UI local reset (scoped) */
+
+:where(.generate-ui-reset),
+:where(.generate-ui-reset *) {
+  box-sizing: border-box;
+}
+
+:where(.generate-ui-reset img),
+:where(.generate-ui-reset svg),
+:where(.generate-ui-reset video),
+:where(.generate-ui-reset canvas) {
+  display: block;
+  max-width: 100%;
+}
+
+:where(.generate-ui-reset input),
+:where(.generate-ui-reset select),
+:where(.generate-ui-reset textarea),
+:where(.generate-ui-reset button),
+:where(.generate-ui-reset a) {
+  font: inherit;
+  color: inherit;
+  letter-spacing: inherit;
+}
+
+/* Optional strict mode for high-fidelity pages only */
+:where(.generate-ui-reset--strict input),
+:where(.generate-ui-reset--strict select),
+:where(.generate-ui-reset--strict textarea) {
+  margin: 0;
+  border-radius: 0;
+}

package/cursor-bootstrap/examples/ui-adapter.contract.template.json

@@ -0,0 +1,90 @@
+{
+  "version": 1,
+  "scope": "project-global",
+  "description": "Figma UI adapter contract (project-level single source of truth).",
+  "usage": [
+    "Agent实现UI前必须先读取此文件，用于将Figma token/state映射到项目实现。",
+    "优先使用projectBinding，未映射项必须先补充contract或向用户确认，禁止猜测。",
+    "默认只维护这一份全局contract；仅在节点特殊化时才新增节点override。"
+  ],
+  "tokenMappings": [
+    {
+      "id": "color.interactive.selected.controlBg",
+      "figmaToken": "Textr Team Blue/Textr Team Blue 500",
+      "figmaValue": "#305AFE",
+      "required": true,
+      "projectBinding": {
+        "type": "literal",
+        "value": "#305AFE",
+        "notes": "可替换为项目真实token（如CSS变量或主题变量），但视觉值必须等效。"
+      }
+    },
+    {
+      "id": "color.text.inverse",
+      "figmaToken": "Defaults/White",
+      "figmaValue": "#FFFFFF",
+      "required": true,
+      "projectBinding": {
+        "type": "literal",
+        "value": "#FFFFFF",
+        "notes": "用于深色控件上的前景文案/图标。"
+      }
+    },
+    {
+      "id": "color.surface.panel",
+      "figmaToken": "Neutral Grey/Neutral Grey 800",
+      "figmaValue": "#383C48",
+      "required": false,
+      "projectBinding": {
+        "type": "literal",
+        "value": "#383C48",
+        "notes": "面板背景常用色。"
+      }
+    }
+  ],
+  "stateMappings": {
+    "select": {
+      "requiredStates": [
+        "default",
+        "expanded",
+        "selected",
+        "unselected"
+      ],
+      "hoverScope": "option-only",
+      "selectedCheckbox": {
+        "backgroundTokenId": "color.interactive.selected.controlBg",
+        "iconTokenId": "color.text.inverse"
+      }
+    }
+  },
+  "layoutRules": [
+    {
+      "id": "layout.hasContainer",
+      "pattern": "(container|panel|wrapper)",
+      "required": true
+    }
+  ],
+  "typographyRules": [
+    {
+      "id": "typography.hasReadableText",
+      "pattern": "(font|text|label|title)",
+      "required": true
+    }
+  ],
+  "interactionRules": [
+    {
+      "id": "interaction.hasStateOrEvent",
+      "pattern": "(state|hover|click|expanded|selected)",
+      "required": true
+    }
+  ],
+  "rules": {
+    "singleSourceOfTruth": true,
+    "fallbackPolicy": "ask-user-when-unmapped",
+    "nodeOverride": {
+      "enabled": true,
+      "pathPattern": "figma-cache/files/<fileKey>/nodes/<nodeId>/ui-override.json",
+      "policy": "仅用于节点级差异，且不得反向污染全局contract。"
+    }
+  }
+}

package/cursor-bootstrap/examples/ui-execution-template.fast.md

@@ -0,0 +1,11 @@
+# UI 执行模板（fast）
+
+适用：只需快速看效果、先跑通路径。
+
+1. `npm run figma:ui:preflight`
+2. `npm run figma:ui:audit -- --min-score=70`
+3. 允许 warning，但记录差异项并进入下一轮迭代
+
+建议：
+- `FIGMA_UI_PROFILE=fast`
+- 仅用于原型验证，不用于主干发布门禁