figma-cache-toolchain 2.0.2 → 2.0.3

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

@@ -1,50 +1,37 @@
----
-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. 未决问题（如有）
+---
+name: figma-ui-dual-mode-execution
+description: 仅用 nodeId 或 Figma 链接触发 UI 实现，支持 L0/L1/L2 压缩级别，并内置基线判型与 B0/B1/B2 选择。
+---
+
+# Figma UI Dual Mode Execution（分级）
+
+## 执行步骤（固定）
+1. 规范化 nodeId 并命中缓存目录。
+2. 读取 `spec/raw/state-map/design-context`。
+3. 选择压缩级别：L0/L1/L2（默认 L1）。
+4. 输出事实对齐清单并实现挂载。
+5. lint 验证并输出映射结论。
+
+## 压缩级别
+- L0：高保真严格流程（预检文档 + 完整状态）。
+- L1：标准流程（精简清单 + 核心状态）。
+- L2：快速看效果（先静态后补交互）。
+
+## 基线治理（并入）
+- 项目判型：新项目 / 老项目 / 不确定（不确定按老项目）。
+- 基线级别：B0/B1/B2（老项目默认 B0）。
+- B0（默认）：
+  - 复制模板到 `src/styles/generated-ui-reset.css`
+  - 入口单次引入
+  - 生成组件根节点加 `generate-ui-reset`
+- B1：仅新页面/模块范围启用作用域基线。
+- B2：全局基线，仅新项目或明确授权。
+- 若与规则冲突，以 `.cursor/rules/04-ui-baseline-governance.mdc` 为准。
+
+## 标签口径
+- 默认 `div/span/img`
+- 默认禁 `p/ul/li/ol/h1-h6`
+- `input/select/textarea/a` 允许
+- 原生 `button` 默认禁用（封装/UI 库按钮除外）
+- `role/aria-*` 默认不强制
+- `data-node-id/data-name` 默认不输出

package/figma-cache/docs/README.md

@@ -134,7 +134,7 @@ npm run figma:cache:init
 - **项目根**仍需：`figma-cache.config.js`、`.cursor/` 规则与 Skill、`AGENT-SETUP-PROMPT.md`（或由等价流程生成）。
 - Vue2+Vuetify2 参考 Adapter：`cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`（npm 安装时在 `node_modules/.../cursor-bootstrap/examples/`）。
 
-说明：Cursor **不会**在 `npm install` 时写入 `.cursor/`；`npx figma-cache cursor init` 负责从包内复制模板。`cursor init` 默认**覆盖**同名模板为最新版本（`--force` 可改为保留已有模板并跳过覆盖）；并会下发通用低 token 规则 `00-output-token-budget.mdc`；**`AGENT-SETUP-PROMPT.md` 每次 `cursor init` 均刷新**。
+说明：Cursor **不会**在 `npm install` 时写入 `.cursor/`；`npx figma-cache cursor init` 负责从包内复制模板。`cursor init` 默认**保留**同名模板（安全模式）；使用 `--overwrite` 可覆盖为最新版本；并会下发通用低 token 规则 `00-output-token-budget.mdc`；**`AGENT-SETUP-PROMPT.md` 每次 `cursor init` 均刷新**。
 
 ## package.json scripts 示例
 

package/figma-cache/figma-cache.js

@@ -353,7 +353,7 @@ function run() {
     console.log(`  ${ex} flow show --flow=<flowId>`);
     console.log(`  ${ex} flow mermaid --flow=<flowId>`);
     console.log(
-      `${ex} cursor init [--force]  # default: overwrite .cursor templates with latest bootstrap; --force keeps existing templates (skip overwrite)`,
+      `${ex} cursor init [--overwrite] [--force]  # default safe mode; --overwrite forces replacement; --force keeps legacy behavior (no overwrite)`,
     );
     process.exit(1);
   }
@@ -362,12 +362,18 @@ function run() {
     const sub = args[0];
     if (sub !== "init") {
       console.error(
-        "Usage: figma-cache cursor init [--force]  # default overwrite; --force keeps existing templates",
+        "Usage: figma-cache cursor init [--overwrite] [--force]  # --overwrite replaces existing templates; --force keeps legacy no-overwrite behavior",
       );
       process.exit(1);
     }
-    const force = args.includes("--force");
-    copyCursorBootstrap(force, {
+    const hasOverwrite = args.includes("--overwrite");
+    const hasForce = args.includes("--force");
+    if (hasOverwrite && hasForce) {
+      console.error("Do not use --overwrite and --force together. Choose one mode.");
+      process.exit(1);
+    }
+    const overwrite = hasOverwrite;
+    copyCursorBootstrap({ overwrite, legacyForce: hasForce }, {
       fs,
       path,
       ROOT,

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

@@ -1,202 +1,218 @@
-/* eslint-disable no-console */
-
-function readUtf8IfExists(fs, absPath) {
-  if (!fs.existsSync(absPath)) {
-    return "";
-  }
-  return fs.readFileSync(absPath, "utf8");
-}
-
-function copyCursorBootstrap(force, deps) {
-  const {
-    fs,
-    path,
-    ROOT,
-    CACHE_DIR,
-    CURSOR_BOOTSTRAP_DIR,
-    normalizeSlash,
-    readSelfNpmPackageName,
-    packageDir,
-  } = deps;
-
-  const pairs = [
-    {
-      from: path.join("rules", "00-output-token-budget.mdc"),
-      to: path.join(".cursor", "rules", "00-output-token-budget.mdc"),
-    },
-    {
-      from: path.join("rules", "01-figma-cache-core.mdc"),
-      to: path.join(".cursor", "rules", "01-figma-cache-core.mdc"),
-    },
-    {
-      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"),
-    },
-    {
-      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)) {
-    console.error(
-      `[figma-cache] cursor-bootstrap not found at ${normalizeSlash(CURSOR_BOOTSTRAP_DIR)} (broken package install?)`
-    );
-    process.exit(1);
-  }
-
-  const overwrite = !force;
-  let copied = 0;
-  let skipped = 0;
-  pairs.forEach(({ from: relFrom, to: relTo }) => {
-    const absFrom = path.join(CURSOR_BOOTSTRAP_DIR, relFrom);
-    const absTo = path.join(ROOT, relTo);
-    if (!fs.existsSync(absFrom)) {
-      console.error(`[figma-cache] missing template file: ${normalizeSlash(absFrom)}`);
-      process.exit(1);
-    }
-    fs.mkdirSync(path.dirname(absTo), { recursive: true });
-    if (fs.existsSync(absTo) && !overwrite) {
-      skipped += 1;
-      return;
-    }
-    fs.copyFileSync(absFrom, absTo);
-    copied += 1;
-  });
-
-  const configTemplatePath = path.join(CURSOR_BOOTSTRAP_DIR, "figma-cache.config.example.js");
-  const projectConfigPath = path.join(ROOT, "figma-cache.config.js");
-  const legacyExamplePath = path.join(ROOT, "figma-cache.config.example.js");
-
-  if (!fs.existsSync(configTemplatePath)) {
-    console.error(`[figma-cache] missing template file: ${normalizeSlash(configTemplatePath)}`);
-    process.exit(1);
-  }
-
-  const hadProjectConfig = fs.existsSync(projectConfigPath);
-  const hadLegacyExample = fs.existsSync(legacyExamplePath);
-  const configTemplateBody = fs.readFileSync(configTemplatePath, "utf8");
-
-  let configAction = "skipped";
-  let configSource = "existing";
-  if (hadProjectConfig && !force) {
-    configAction = "skipped";
-    configSource = "existing";
-  } else if (!hadProjectConfig && hadLegacyExample && !force) {
-    fs.copyFileSync(legacyExamplePath, projectConfigPath);
-    configAction = "created";
-    configSource = "legacy-example";
-  } else {
-    fs.writeFileSync(projectConfigPath, configTemplateBody, "utf8");
-    configAction = hadProjectConfig ? "overwritten" : "created";
-    configSource = "template";
-  }
-
-  let legacyExampleStatus = "not-found";
-  if (fs.existsSync(legacyExamplePath)) {
-    const legacyBody = readUtf8IfExists(fs, legacyExamplePath);
-    const projectBody = readUtf8IfExists(fs, projectConfigPath);
-    const sameAsTemplate = legacyBody === configTemplateBody;
-    const sameAsProject = projectBody && legacyBody === projectBody;
-    if (sameAsTemplate || sameAsProject) {
-      fs.unlinkSync(legacyExamplePath);
-      legacyExampleStatus = "deleted";
-    } else {
-      legacyExampleStatus = "kept-customized";
-    }
-  }
-
-  const agentSrc = path.join(CURSOR_BOOTSTRAP_DIR, "AGENT-SETUP-PROMPT.md");
-  const agentDest = path.join(ROOT, "AGENT-SETUP-PROMPT.md");
-  if (!fs.existsSync(agentSrc)) {
-    console.error(`[figma-cache] missing ${normalizeSlash(agentSrc)}`);
-    process.exit(1);
-  }
-
-  let agentBody = fs.readFileSync(agentSrc, "utf8");
-  const npmPkg = readSelfNpmPackageName();
-  agentBody = agentBody.replace(/\{\{NPM_PACKAGE_NAME\}\}/g, npmPkg);
-  fs.writeFileSync(agentDest, agentBody, "utf8");
-
-  const colleagueSrc = path.join(packageDir, "docs", "colleague-guide-zh.md");
-  const colleagueDest = path.join(CACHE_DIR, "docs", "colleague-guide-zh.md");
-  if (!fs.existsSync(colleagueSrc)) {
-    console.error(`[figma-cache] missing ${normalizeSlash(colleagueSrc)} (broken package install?)`);
-    process.exit(1);
-  }
-  const colleagueSameFile = path.resolve(colleagueSrc) === path.resolve(colleagueDest);
-  if (!colleagueSameFile) {
-    fs.mkdirSync(path.dirname(colleagueDest), { recursive: true });
-    fs.copyFileSync(colleagueSrc, colleagueDest);
-  }
-
-  console.log(
-    JSON.stringify(
-      {
-        ok: true,
-        root: normalizeSlash(ROOT),
-        copied,
-        skipped,
-        force: !!force,
-        overwriteByDefault: overwrite,
-        hint: skipped
-          ? "Some template files were skipped (--force means keep existing files)."
-          : overwrite
-          ? "Done. Existing .cursor templates were overwritten by latest bootstrap."
-          : "Done.",
-        configFile: normalizeSlash(projectConfigPath),
-        configAction,
-        configSource,
-        legacyExampleFile: normalizeSlash(legacyExamplePath),
-        legacyExampleStatus,
-        agentPromptFile: normalizeSlash(agentDest),
-        colleagueGuideFile: normalizeSlash(colleagueDest),
-        colleagueGuideSynced: !colleagueSameFile,
-        colleagueGuideNote: colleagueSameFile
-          ? "colleague-guide-zh.md already at package path (toolchain dev tree); no copy."
-          : "colleague-guide-zh.md refreshed under FIGMA_CACHE_DIR/docs (default figma-cache/docs/).",
-        agentPromptNote:
-          "AGENT-SETUP-PROMPT.md is refreshed every run. Next: @ it in Cursor; after Agent finishes, run npm run figma:cache:init (or npx figma-cache init if scripts are missing).",
-        npmPackageName: npmPkg,
-      },
-      null,
-      2
-    )
-  );
-  console.log(
-    "\n" +
-      "================================================================\n" +
-      "下一步（请按顺序）：\n" +
-      "1) 在 Cursor 对话中输入 @AGENT-SETUP-PROMPT.md，并说明「按该文档执行」\n" +
-      "   （每次 cursor init 都会刷新该文件；无需再整篇粘贴。）\n" +
-      "2) 待 Agent 完成后，在项目根初始化本地缓存索引：\n" +
-      "   npm run figma:cache:init\n" +
-      "   若尚未补全 npm scripts，请改用：npx figma-cache init\n" +
-      "================================================================\n"
-  );
-}
-
-module.exports = {
-  copyCursorBootstrap,
-};
-
+/* eslint-disable no-console */
+
+function readUtf8IfExists(fs, absPath) {
+  if (!fs.existsSync(absPath)) {
+    return "";
+  }
+  return fs.readFileSync(absPath, "utf8");
+}
+
+function loadManagedManifest({ fs, path, CURSOR_BOOTSTRAP_DIR, normalizeSlash }) {
+  const manifestPath = path.join(CURSOR_BOOTSTRAP_DIR, "managed-files.json");
+  if (!fs.existsSync(manifestPath)) {
+    console.error(`[figma-cache] missing managed files manifest: ${normalizeSlash(manifestPath)}`);
+    process.exit(1);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    console.error(`[figma-cache] invalid managed files manifest: ${error.message}`);
+    process.exit(1);
+  }
+
+  const { managedFiles, retiredFiles } = parsed || {};
+  if (!Array.isArray(managedFiles) || managedFiles.length === 0) {
+    console.error("[figma-cache] managed-files.json must contain non-empty managedFiles");
+    process.exit(1);
+  }
+
+  const pairs = managedFiles.map((item, index) => {
+    if (!item || typeof item.from !== "string" || typeof item.to !== "string") {
+      console.error(`[figma-cache] invalid managedFiles[${index}] item`);
+      process.exit(1);
+    }
+    return {
+      from: item.from,
+      to: item.to,
+    };
+  });
+
+  const retired = Array.isArray(retiredFiles)
+    ? retiredFiles.filter((item) => typeof item === "string" && item.trim())
+    : [];
+
+  return { pairs, retired };
+}
+
+function copyCursorBootstrap(options, deps) {
+  const {
+    fs,
+    path,
+    ROOT,
+    CACHE_DIR,
+    CURSOR_BOOTSTRAP_DIR,
+    normalizeSlash,
+    readSelfNpmPackageName,
+    packageDir,
+  } = deps;
+  const {
+    overwrite = false,
+    legacyForce = false,
+  } = options || {};
+
+  const { pairs, retired } = loadManagedManifest({ fs, path, CURSOR_BOOTSTRAP_DIR, normalizeSlash });
+
+  if (!fs.existsSync(CURSOR_BOOTSTRAP_DIR)) {
+    console.error(
+      `[figma-cache] cursor-bootstrap not found at ${normalizeSlash(CURSOR_BOOTSTRAP_DIR)} (broken package install?)`
+    );
+    process.exit(1);
+  }
+
+  let copied = 0;
+  let skipped = 0;
+  pairs.forEach(({ from: relFrom, to: relTo }) => {
+    const absFrom = path.join(CURSOR_BOOTSTRAP_DIR, relFrom);
+    const absTo = path.join(ROOT, relTo);
+    if (!fs.existsSync(absFrom)) {
+      console.error(`[figma-cache] missing template file: ${normalizeSlash(absFrom)}`);
+      process.exit(1);
+    }
+    fs.mkdirSync(path.dirname(absTo), { recursive: true });
+    if (fs.existsSync(absTo) && !overwrite) {
+      skipped += 1;
+      return;
+    }
+    fs.copyFileSync(absFrom, absTo);
+    copied += 1;
+  });
+
+  const retiredDeleted = retired
+    .map((relPath) => {
+      const abs = path.join(ROOT, relPath);
+      if (!fs.existsSync(abs)) {
+        return null;
+      }
+      fs.unlinkSync(abs);
+      return normalizeSlash(relPath);
+    })
+    .filter(Boolean);
+
+  const configTemplatePath = path.join(CURSOR_BOOTSTRAP_DIR, "figma-cache.config.example.js");
+  const projectConfigPath = path.join(ROOT, "figma-cache.config.js");
+  const legacyExamplePath = path.join(ROOT, "figma-cache.config.example.js");
+
+  if (!fs.existsSync(configTemplatePath)) {
+    console.error(`[figma-cache] missing template file: ${normalizeSlash(configTemplatePath)}`);
+    process.exit(1);
+  }
+
+  const hadProjectConfig = fs.existsSync(projectConfigPath);
+  const hadLegacyExample = fs.existsSync(legacyExamplePath);
+  const configTemplateBody = fs.readFileSync(configTemplatePath, "utf8");
+
+  let configAction = "skipped";
+  let configSource = "existing";
+  if (hadProjectConfig && !overwrite) {
+    configAction = "skipped";
+    configSource = "existing";
+  } else if (!hadProjectConfig && hadLegacyExample && !overwrite) {
+    fs.copyFileSync(legacyExamplePath, projectConfigPath);
+    configAction = "created";
+    configSource = "legacy-example";
+  } else {
+    fs.writeFileSync(projectConfigPath, configTemplateBody, "utf8");
+    configAction = hadProjectConfig ? "overwritten" : "created";
+    configSource = "template";
+  }
+
+  let legacyExampleStatus = "not-found";
+  if (fs.existsSync(legacyExamplePath)) {
+    const legacyBody = readUtf8IfExists(fs, legacyExamplePath);
+    const projectBody = readUtf8IfExists(fs, projectConfigPath);
+    const sameAsTemplate = legacyBody === configTemplateBody;
+    const sameAsProject = projectBody && legacyBody === projectBody;
+    if (sameAsTemplate || sameAsProject) {
+      fs.unlinkSync(legacyExamplePath);
+      legacyExampleStatus = "deleted";
+    } else {
+      legacyExampleStatus = "kept-customized";
+    }
+  }
+
+  const agentSrc = path.join(CURSOR_BOOTSTRAP_DIR, "AGENT-SETUP-PROMPT.md");
+  const agentDest = path.join(ROOT, "AGENT-SETUP-PROMPT.md");
+  if (!fs.existsSync(agentSrc)) {
+    console.error(`[figma-cache] missing ${normalizeSlash(agentSrc)}`);
+    process.exit(1);
+  }
+
+  let agentBody = fs.readFileSync(agentSrc, "utf8");
+  const npmPkg = readSelfNpmPackageName();
+  agentBody = agentBody.replace(/\{\{NPM_PACKAGE_NAME\}\}/g, npmPkg);
+  fs.writeFileSync(agentDest, agentBody, "utf8");
+
+  const colleagueSrc = path.join(packageDir, "docs", "colleague-guide-zh.md");
+  const colleagueDest = path.join(CACHE_DIR, "docs", "colleague-guide-zh.md");
+  if (!fs.existsSync(colleagueSrc)) {
+    console.error(`[figma-cache] missing ${normalizeSlash(colleagueSrc)} (broken package install?)`);
+    process.exit(1);
+  }
+  const colleagueSameFile = path.resolve(colleagueSrc) === path.resolve(colleagueDest);
+  if (!colleagueSameFile) {
+    fs.mkdirSync(path.dirname(colleagueDest), { recursive: true });
+    fs.copyFileSync(colleagueSrc, colleagueDest);
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        root: normalizeSlash(ROOT),
+        copied,
+        skipped,
+        overwrite,
+        legacyForce,
+        retiredDeleted,
+        hint: skipped
+          ? "Some template files were skipped (default safe mode keeps existing files)."
+          : overwrite
+          ? "Done. Existing .cursor templates were overwritten by latest bootstrap."
+          : "Done.",
+        configFile: normalizeSlash(projectConfigPath),
+        configAction,
+        configSource,
+        legacyExampleFile: normalizeSlash(legacyExamplePath),
+        legacyExampleStatus,
+        agentPromptFile: normalizeSlash(agentDest),
+        colleagueGuideFile: normalizeSlash(colleagueDest),
+        colleagueGuideSynced: !colleagueSameFile,
+        colleagueGuideNote: colleagueSameFile
+          ? "colleague-guide-zh.md already at package path (toolchain dev tree); no copy."
+          : "colleague-guide-zh.md refreshed under FIGMA_CACHE_DIR/docs (default figma-cache/docs/).",
+        agentPromptNote:
+          "AGENT-SETUP-PROMPT.md is refreshed every run. Next: @ it in Cursor; after Agent finishes, run npm run figma:cache:init (or npx figma-cache init if scripts are missing).",
+        npmPackageName: npmPkg,
+      },
+      null,
+      2
+    )
+  );
+  console.log(
+    "\n" +
+      "================================================================\n" +
+      "下一步（请按顺序）：\n" +
+      "1) 在 Cursor 对话中输入 @AGENT-SETUP-PROMPT.md，并说明「按该文档执行」\n" +
+      "   （每次 cursor init 都会刷新该文件；无需再整篇粘贴。）\n" +
+      "2) 待 Agent 完成后，在项目根初始化本地缓存索引：\n" +
+      "   npm run figma:cache:init\n" +
+      "   若尚未补全 npm scripts，请改用：npx figma-cache init\n" +
+      "================================================================\n"
+  );
+}
+
+module.exports = {
+  copyCursorBootstrap,
+};