figma-cache-toolchain 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) figma-cache-toolchain contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# figma-cache-toolchain
+
+从业务仓库拆出的 **Figma 本地缓存工具链**：链接标准化、`figma-cache/` 索引与校验、零运行时依赖的 Node CLI。Core 不绑定具体 UI 框架；Vue 2 + Vuetify 2 等适配通过项目根 `figma-cache.config.js` 的 `hooks.postEnsure` 与 `.cursor/rules/02-*-adapter.mdc` 完成。
+
+## 安装
+
+在发布到 npm 之前，请在本仓库根目录执行 `npm link`（或发布后使用你在 `package.json` 中声明的最终包名，例如 `npm i -D <你的作用域>/figma-cache-toolchain`）。**请勿假设**某个尚未发布的固定包名已存在于公共 registry。
+
+安装后，消费方项目的 `package.json` 可注册与下文「脚本」一致的 `npm run figma:cache:*` 命令。
+
+## 脚本（消费方）
+
+与 `figma-cache/migration-guide.md` 一致：作为 **依赖安装** 后，可用 `figma-cache config` 等形式（由 `node_modules/.bin` 解析）。在本仓库根目录开发时，`package.json` 使用 `node bin/figma-cache.js …`，避免仅含当前包、无其他依赖时本地 `.bin` 未生成导致命令找不到。
+
+若**不**通过 npm 安装、而是复制 `figma-cache/` 目录到业务仓库，可继续使用：
+
+- `node figma-cache/figma-cache.js <子命令> ...`
+
+## 项目级配置与钩子
+
+- 在消费项目根目录放置 `figma-cache.config.js` 或 `.figmacacherc.js`（加载顺序见 `figma-cache/figma-cache.js` 内注释：`FIGMA_CACHE_PROJECT_CONFIG` → `figma-cache.config.js` → `.figmacacherc.js`）。
+- `hooks.postEnsure`：在 Core 完成 `ensure` 写入通用骨架后调用；钩子异常不会导致 `ensure` 失败退出。
+
+## 环境变量（节选）
+
+完整列表见 `figma-cache/migration-guide.md` 与 `figma-cache/README.md`。
+
+| 变量 | 作用 |
+|------|------|
+| `FIGMA_CACHE_DIR` | 缓存根目录，默认 `figma-cache` |
+| `FIGMA_CACHE_INDEX_FILE` | 索引文件名或绝对路径 |
+| `FIGMA_ITERATIONS_DIR` | `backfill` 扫描的 Markdown 目录；**目录不存在时**仅导致 `backfill` 扫描结果为空，不影响 `validate` |
+| `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
+| `FIGMA_DEFAULT_FLOW` | 默认 `flowId` |
+| `FIGMA_CACHE_PROJECT_CONFIG` | 覆盖项目配置文件路径 |
+
+## Cursor 规则与 Skill
+
+将本仓库中的下列文件复制到消费项目（路径保持一致即可）：
+
+- `.cursor/rules/01-figma-cache-core.mdc`（数据层，建议 always on）
+- `.cursor/rules/02-figma-vuetify2-adapter.mdc`（本仓库示例栈；其他栈请自建 `02-figma-*-adapter.mdc`）
+- `.cursor/rules/figma-local-cache-first.mdc`（入口说明，可选）
+- `.cursor/skills/figma-mcp-local-cache/SKILL.md`
+
+详见 `figma-cache/migration-guide.md`。
+
+## 默认不把业务缓存打进 npm 包
+
+`package.json` 的 `files` 白名单仅包含 CLI 与 `figma-cache` 下的脚本及 `*.md` 规范文档；**不包含** `figma-cache/files/` 与 `figma-cache/index.json`。消费方应在自有项目中执行 `figma-cache init` 与 `ensure` 生成数据目录。
+
+## 自用与偶发发版
+
+1. 日常：保持本仓库内 `figma-cache/index.json` 与 `figma-cache/files/` 与你们约定一致，并定期跑 `npm run figma:cache:validate`。
+2. 发版前：在 `package.json` 中补全 `repository` / `bugs` / `homepage`（若有公开 Git 地址），按 semver 提升 `version`，把变更摘要写入 `CHANGELOG.md` 对应版本。
+3. `npm pack` 或 `npm publish` 前会执行 **`prepack`**（即 `figma-cache validate`）；若故意去掉本地缓存做「纯工具 tarball」，需先保证能通过校验或临时调整流程（默认假设本仓库带可校验的示例/真实索引）。
+
+## 开发自检
+
+```bash
+npm run figma:cache:config
+npm run figma:cache:validate
+npm pack
+npm publish --dry-run
+```

package/bin/figma-cache.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../figma-cache/figma-cache.js");

package/figma-cache/README.md

@@ -0,0 +1,87 @@
+# Figma Cache
+
+该目录集中管理 Figma 缓存流程（脚本、索引、规范、样例缓存）。
+
+## 使用方式（重要）
+
+- 日常只需要把 Figma 链接发给 agent。
+- agent 会自动完成：缓存查询 -> 必要时调用 MCP -> 回写缓存 -> 校验。
+- 你不需要手动执行命令，命令主要用于排障和迁移验证。
+
+## 目录结构
+
+- `figma-cache/figma-cache.js`：缓存流程脚本主入口
+- `figma-cache/index.json`：全量索引
+- `figma-cache/files/...`：节点缓存内容
+- `figma-cache/link-normalization-spec.md`：链接标准化规则
+- `figma-cache/validation-checklist.md`：缓存校验清单
+- `figma-cache/backfill-guide.md`：历史回填指南
+- `figma-cache/migration-guide.md`：跨项目移植指南
+- `figma-cache/flow-edge-taxonomy.md`：流程边类型约定
+
+## 默认配置
+
+- `FIGMA_CACHE_DIR=figma-cache`
+- `FIGMA_CACHE_INDEX_FILE=index.json`
+- `FIGMA_ITERATIONS_DIR=library/figma-iterations`
+- `FIGMA_CACHE_STALE_DAYS=14`
+- `FIGMA_DEFAULT_FLOW`：默认 flowId；设置后 `flow add-node/link/chain/show/mermaid` 可省略 `--flow=...`
+
+查看当前配置：
+
+```bash
+npm run figma:cache:config
+```
+
+PowerShell 示例（设置默认 flow，减少重复参数）：
+
+```powershell
+$env:FIGMA_DEFAULT_FLOW="sip-calling-phase1"
+npm run figma:cache:config
+```
+
+## 常用命令（通常由 agent 自动执行）
+
+- `npm run figma:cache:init`
+- `npm run figma:cache:get -- "<figma-url>"`
+- `npm run figma:cache:ensure -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions`
+- `npm run figma:cache:validate`
+- `npm run figma:cache:stale`
+- `npm run figma:cache:backfill`
+
+## 流程关系（Flow）
+
+`index.json` 现在包含 `flows`，用于维护“业务/交互流程”的节点集合与边关系。
+
+常用命令：
+
+- `npm run figma:cache:flow:init -- --id=sip-calling-flow --title="SIP Calling"`
+- `npm run figma:cache:flow:add-node -- --flow=sip-calling-flow "<figma-url>"`（要求 `items` 已存在；如需同时创建缓存项可加 `--ensure`）
+- `npm run figma:cache:flow:link -- --flow=sip-calling-flow "<fromUrl>" "<toUrl>" --type=next_step`
+- `npm run figma:cache:flow:chain -- --flow=sip-calling-flow "<url1>" "<url2>" "<url3>" --type=related`
+- `npm run figma:cache:flow:show -- --flow=sip-calling-flow`
+- `npm run figma:cache:flow:mermaid -- --flow=sip-calling-flow`
+
+说明：
+
+- `items` 仍然是单节点缓存索引。
+- `flows` 负责把多个 `cacheKey` 组织成流程图，并记录边类型（如 `next_step/branch/related`）。
+
+## 大迭代工作流（推荐）
+
+1. `flow init` 固定一个 `flowId`（整个迭代只用这一个，或配合 `FIGMA_DEFAULT_FLOW`）
+2. 每个新节点：先 `ensure` 写入 `items`，再 `flow add-node` 挂到 flow（必要时 `--ensure`）
+3. 当你描述跳转/下一步/分支：用 `flow link`；批量默认串联可用 `flow chain`
+4. 定期 `validate`；需要看图用 `flow mermaid`
+
+边类型约定见：`figma-cache/flow-edge-taxonomy.md`
+
+## 纯净版初始化
+
+- 如果你准备移植“纯净版”（删除 `index.json` 和 `files/`），可先执行：
+
+```bash
+npm run figma:cache:init
+```
+
+- 该命令只创建空索引，不会创建任何节点缓存文件。

package/figma-cache/backfill-guide.md

@@ -0,0 +1,18 @@
+# Figma 历史数据回填指南
+
+目标：扫描历史文档中的 Figma 链接并补入缓存索引。
+
+## 执行
+
+```bash
+npm run figma:cache:backfill
+```
+
+默认扫描目录由 `FIGMA_ITERATIONS_DIR` 决定，默认值是 `library/figma-iterations`。
+
+## 回填后检查
+
+```bash
+npm run figma:cache:validate
+npm run figma:cache:stale
+```

package/figma-cache/figma-cache.js

@@ -0,0 +1,918 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+const { createRequire } = require("module");
+const { URL } = require("url");
+
+const ROOT = process.cwd();
+const NORMALIZATION_VERSION = 1;
+const SCHEMA_VERSION = 2;
+
+function parsePositiveInt(input, fallback) {
+  const n = Number(input);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+
+function normalizeSlash(input) {
+  return input.replace(/\\/g, "/");
+}
+
+function resolveMaybeAbsolutePath(input) {
+  if (path.isAbsolute(input)) {
+    return path.normalize(input);
+  }
+  return path.join(ROOT, input);
+}
+
+function toProjectRelativeOrAbsolute(absPath) {
+  const relative = path.relative(ROOT, absPath);
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return normalizeSlash(relative);
+  }
+  return normalizeSlash(absPath);
+}
+
+const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
+const ITERATIONS_DIR_INPUT =
+  process.env.FIGMA_ITERATIONS_DIR || "library/figma-iterations";
+const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
+const DEFAULT_FLOW_ID = process.env.FIGMA_DEFAULT_FLOW || "";
+const DEFAULT_STALE_DAYS = parsePositiveInt(
+  process.env.FIGMA_CACHE_STALE_DAYS,
+  14
+);
+
+const CACHE_DIR = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
+const ITERATIONS_DIR = resolveMaybeAbsolutePath(ITERATIONS_DIR_INPUT);
+const INDEX_PATH = path.isAbsolute(INDEX_FILE_NAME)
+  ? INDEX_FILE_NAME
+  : path.join(CACHE_DIR, INDEX_FILE_NAME);
+const CACHE_BASE_FOR_STORAGE = toProjectRelativeOrAbsolute(CACHE_DIR);
+
+/** @type {object | null} null = not loaded yet; after load always an object (possibly empty) */
+let memoProjectConfig = null;
+/** @type {string | null} */
+let memoProjectConfigPath = null;
+
+/**
+ * Load optional project-level config from (first match):
+ * 1) FIGMA_CACHE_PROJECT_CONFIG (absolute or relative to ROOT)
+ * 2) figma-cache.config.js
+ * 3) .figmacacherc.js
+ * Core stays agnostic: only reads `hooks` and other neutral keys.
+ */
+function loadProjectConfig() {
+  if (memoProjectConfig) {
+    return memoProjectConfig;
+  }
+  const candidates = [];
+  if (process.env.FIGMA_CACHE_PROJECT_CONFIG) {
+    candidates.push(resolveMaybeAbsolutePath(process.env.FIGMA_CACHE_PROJECT_CONFIG));
+  }
+  candidates.push(path.join(ROOT, "figma-cache.config.js"));
+  candidates.push(path.join(ROOT, ".figmacacherc.js"));
+
+  const requireFromRoot = createRequire(path.join(ROOT, "package.json"));
+
+  for (const absPath of candidates) {
+    if (!fs.existsSync(absPath)) {
+      continue;
+    }
+    try {
+      const mod = requireFromRoot(absPath);
+      const cfg = mod && mod.default ? mod.default : mod;
+      memoProjectConfig = cfg && typeof cfg === "object" ? cfg : {};
+      memoProjectConfigPath = absPath;
+      return memoProjectConfig;
+    } catch (err) {
+      console.error(`[figma-cache] project config failed (${absPath}): ${err.message}`);
+    }
+  }
+
+  memoProjectConfig = {};
+  memoProjectConfigPath = null;
+  return memoProjectConfig;
+}
+
+/**
+ * After generic entry files exist, run optional hooks.postEnsure from project config.
+ * Never throws; never changes process exit code of the caller.
+ * @param {string} cacheKey
+ * @param {object} item index item
+ */
+function runPostEnsureHook(cacheKey, item) {
+  if (!item || !item.paths) {
+    return;
+  }
+  const cfg = loadProjectConfig();
+  const hooks = cfg && cfg.hooks;
+  if (!hooks || typeof hooks.postEnsure !== "function") {
+    return;
+  }
+  const ctx = {
+    cacheKey,
+    fileKey: item.fileKey,
+    nodeId: item.nodeId == null ? null : item.nodeId,
+    scope: item.scope,
+    paths: {
+      raw: item.paths.raw,
+      spec: item.paths.spec,
+      meta: item.paths.meta,
+      stateMap: item.paths.stateMap,
+    },
+    root: ROOT,
+  };
+  try {
+    hooks.postEnsure(ctx);
+  } catch (err) {
+    console.error(`[figma-cache] hooks.postEnsure: ${err.message}`);
+  }
+}
+
+function resolveFlowIdFromArgs(rest) {
+  const flowArg = rest.find((x) => x.startsWith("--flow="));
+  if (flowArg) {
+    return flowArg.split("=")[1];
+  }
+  if (DEFAULT_FLOW_ID) {
+    return DEFAULT_FLOW_ID;
+  }
+  return "";
+}
+
+function ensureCacheDir() {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+  }
+}
+
+function readIndex() {
+  ensureCacheDir();
+  if (!fs.existsSync(INDEX_PATH)) {
+    return buildEmptyIndex();
+  }
+  const raw = fs.readFileSync(INDEX_PATH, "utf8");
+  return normalizeIndexShape(JSON.parse(raw));
+}
+
+function buildEmptyIndex() {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    version: 1,
+    normalizationVersion: NORMALIZATION_VERSION,
+    updatedAt: null,
+    flows: {},
+    items: {},
+  };
+}
+
+function normalizeIndexShape(index) {
+  if (!index || typeof index !== "object") {
+    return buildEmptyIndex();
+  }
+  if (!index.schemaVersion) {
+    index.schemaVersion = SCHEMA_VERSION;
+  }
+  if (!index.flows || typeof index.flows !== "object") {
+    index.flows = {};
+  }
+  if (!index.items || typeof index.items !== "object") {
+    index.items = {};
+  }
+  if (!index.version) {
+    index.version = 1;
+  }
+  if (!index.normalizationVersion) {
+    index.normalizationVersion = NORMALIZATION_VERSION;
+  }
+  return index;
+}
+
+function writeIndex(index) {
+  const normalized = normalizeIndexShape(index);
+  normalized.version = 1;
+  normalized.schemaVersion = SCHEMA_VERSION;
+  normalized.normalizationVersion = NORMALIZATION_VERSION;
+  normalized.updatedAt = new Date().toISOString();
+  fs.writeFileSync(INDEX_PATH, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+}
+
+function sanitizeNodeId(nodeId) {
+  return String(nodeId).replace(/:/g, "-");
+}
+
+function normalizeNodeIdValue(nodeId) {
+  const raw = String(nodeId).trim();
+  const dashPattern = /^(\d+)-(\d+)$/;
+  if (dashPattern.test(raw)) {
+    return raw.replace(dashPattern, "$1:$2");
+  }
+  return raw;
+}
+
+function normalizeFigmaUrl(inputUrl) {
+  let parsed;
+  try {
+    parsed = new URL(inputUrl);
+  } catch (error) {
+    throw new Error(`非法 URL: ${inputUrl}`);
+  }
+
+  const hostOk = /(^|\.)figma\.com$/i.test(parsed.hostname);
+  if (!hostOk) {
+    throw new Error(`非 Figma 域名: ${parsed.hostname}`);
+  }
+
+  const parts = parsed.pathname.split("/").filter(Boolean);
+  const routeType = parts[0];
+  const fileKey = parts[1];
+  if (!["file", "design"].includes(routeType) || !fileKey) {
+    throw new Error(`无法从路径提取 fileKey: ${parsed.pathname}`);
+  }
+
+  const nodeIdRaw = parsed.searchParams.get("node-id");
+  const nodeId = nodeIdRaw ? normalizeNodeIdValue(decodeURIComponent(nodeIdRaw)) : null;
+  const isNodeScope = !!nodeId;
+  const scope = isNodeScope ? "node" : "file";
+  const cacheKey = isNodeScope ? `${fileKey}#${nodeId}` : `${fileKey}#__FILE__`;
+
+  return {
+    fileKey,
+    nodeId,
+    scope,
+    cacheKey,
+    normalizedUrl: isNodeScope
+      ? `https://www.figma.com/file/${fileKey}/?node-id=${encodeURIComponent(nodeId)}`
+      : `https://www.figma.com/file/${fileKey}/`,
+    originalUrl: inputUrl,
+    normalizationVersion: NORMALIZATION_VERSION,
+  };
+}
+
+function buildPaths(normalized) {
+  if (normalized.scope === "file") {
+    return {
+      meta: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/meta.json`,
+      spec: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/spec.md`,
+      stateMap: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/state-map.md`,
+      raw: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/raw.json`,
+    };
+  }
+
+  const safeNode = sanitizeNodeId(normalized.nodeId);
+  return {
+    meta: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/meta.json`,
+    spec: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/spec.md`,
+    stateMap: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/state-map.md`,
+    raw: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/raw.json`,
+  };
+}
+
+function getItem(index, cacheKey) {
+  const normalized = normalizeIndexShape(index);
+  return normalized.items && normalized.items[cacheKey] ? normalized.items[cacheKey] : null;
+}
+
+function upsertByUrl(inputUrl, extra) {
+  const normalized = normalizeFigmaUrl(inputUrl);
+  const index = normalizeIndexShape(readIndex());
+  const oldItem = getItem(index, normalized.cacheKey);
+  const mergedUrls = Array.from(
+    new Set([...(oldItem ? oldItem.originalUrls || [] : []), normalized.originalUrl])
+  );
+  const now = new Date().toISOString();
+
+  const item = {
+    fileKey: normalized.fileKey,
+    nodeId: normalized.nodeId,
+    scope: normalized.scope,
+    url: normalized.normalizedUrl,
+    originalUrls: mergedUrls,
+    normalizationVersion: NORMALIZATION_VERSION,
+    paths: oldItem && oldItem.paths ? oldItem.paths : buildPaths(normalized),
+    syncedAt: now,
+    completeness: Array.isArray(extra.completeness)
+      ? extra.completeness
+      : oldItem && Array.isArray(oldItem.completeness)
+      ? oldItem.completeness
+      : [],
+    source: extra.source || (oldItem && oldItem.source) || "manual",
+  };
+
+  index.items = index.items || {};
+  index.items[normalized.cacheKey] = item;
+  writeIndex(index);
+  return { normalized, item };
+}
+
+function ensureFileWithDefault(relativePath, fallbackContent) {
+  const absPath = resolveMaybeAbsolutePath(relativePath);
+  const dir = path.dirname(absPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  if (!fs.existsSync(absPath)) {
+    fs.writeFileSync(absPath, fallbackContent, "utf8");
+  }
+}
+
+function ensureEntryFiles(item) {
+  ensureFileWithDefault(
+    item.paths.meta,
+    `${JSON.stringify(
+      {
+        fileKey: item.fileKey,
+        nodeId: item.nodeId,
+        scope: item.scope,
+        source: item.source,
+        syncedAt: item.syncedAt,
+      },
+      null,
+      2
+    )}\n`
+  );
+  ensureFileWithDefault(
+    item.paths.spec,
+    `# Figma Spec\n\n- fileKey: ${item.fileKey}\n- scope: ${item.scope}\n- nodeId: ${item.nodeId || "N/A"}\n- source: ${item.source}\n- syncedAt: ${item.syncedAt}\n`
+  );
+  ensureFileWithDefault(
+    item.paths.stateMap,
+    `# State Map\n\n- TODO: 补充状态与交互映射。\n`
+  );
+  ensureFileWithDefault(item.paths.raw, "{}\n");
+}
+
+/**
+ * Writes generic cache skeleton files, then invokes optional lifecycle hook.
+ * @param {string} cacheKey
+ * @param {object} item
+ */
+function ensureEntryFilesAndHook(cacheKey, item) {
+  ensureEntryFiles(item);
+  runPostEnsureHook(cacheKey, item);
+}
+
+function validateIndex(index) {
+  const errors = [];
+  const normalized = normalizeIndexShape(index);
+  const keys = Object.keys(normalized.items || {});
+  keys.forEach((cacheKey) => {
+    const item = normalized.items[cacheKey];
+    const required = [
+      "fileKey",
+      "scope",
+      "url",
+      "originalUrls",
+      "normalizationVersion",
+      "paths",
+      "syncedAt",
+      "completeness",
+    ];
+    required.forEach((field) => {
+      if (item[field] === undefined || item[field] === null) {
+        errors.push(`${cacheKey}: 缺少字段 ${field}`);
+      }
+    });
+    if (item.scope === "node" && !item.nodeId) {
+      errors.push(`${cacheKey}: node 作用域必须包含 nodeId`);
+    }
+  });
+
+  const flowKeys = Object.keys(normalized.flows || {});
+  flowKeys.forEach((flowId) => {
+    const flow = normalized.flows[flowId];
+    if (!flow || typeof flow !== "object") {
+      errors.push(`flow ${flowId}: 非法结构`);
+      return;
+    }
+    if (!flow.id || flow.id !== flowId) {
+      errors.push(`flow ${flowId}: id 字段缺失或不一致`);
+    }
+    if (!Array.isArray(flow.nodes)) {
+      errors.push(`flow ${flowId}: nodes 必须是数组`);
+    }
+    if (!Array.isArray(flow.edges)) {
+      errors.push(`flow ${flowId}: edges 必须是数组`);
+    }
+    if (Array.isArray(flow.edges)) {
+      flow.edges.forEach((edge, idx) => {
+        if (!edge || typeof edge !== "object") {
+          errors.push(`flow ${flowId}: edge[${idx}] 非法`);
+          return;
+        }
+        if (!edge.from || !edge.to) {
+          errors.push(`flow ${flowId}: edge[${idx}] 缺少 from/to`);
+        }
+        if (!edge.type) {
+          errors.push(`flow ${flowId}: edge[${idx}] 缺少 type`);
+        }
+        if (edge.from && !normalized.items[edge.from]) {
+          errors.push(`flow ${flowId}: edge[${idx}] from 不存在于 items: ${edge.from}`);
+        }
+        if (edge.to && !normalized.items[edge.to]) {
+          errors.push(`flow ${flowId}: edge[${idx}] to 不存在于 items: ${edge.to}`);
+        }
+      });
+    }
+    if (Array.isArray(flow.nodes)) {
+      flow.nodes.forEach((cacheKey) => {
+        if (!normalized.items[cacheKey]) {
+          errors.push(`flow ${flowId}: nodes 引用不存在于 items: ${cacheKey}`);
+        }
+      });
+    }
+  });
+
+  return errors;
+}
+
+function collectMarkdownFiles(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  const output = [];
+  const list = fs.readdirSync(dir, { withFileTypes: true });
+  list.forEach((entry) => {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      output.push(...collectMarkdownFiles(fullPath));
+      return;
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      output.push(fullPath);
+    }
+  });
+  return output;
+}
+
+function extractFigmaUrls(content) {
+  const pattern = /https:\/\/www\.figma\.com\/(?:file|design)\/[^\s)\]]+/g;
+  return content.match(pattern) || [];
+}
+
+function backfillFromIterations() {
+  const files = collectMarkdownFiles(ITERATIONS_DIR);
+  let hit = 0;
+  files.forEach((filePath) => {
+    const content = fs.readFileSync(filePath, "utf8");
+    const urls = extractFigmaUrls(content);
+    urls.forEach((url) => {
+      try {
+        upsertByUrl(url, { source: "backfill" });
+        hit += 1;
+      } catch (error) {
+        // 忽略无法解析的 URL
+      }
+    });
+  });
+  console.log(`Backfill done. scanned files=${files.length}, urls=${hit}`);
+}
+
+function slugifyFlowId(name) {
+  const raw = String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return raw || `flow-${Date.now()}`;
+}
+
+function ensureFlow(index, flowId, meta) {
+  const normalized = normalizeIndexShape(index);
+  normalized.flows = normalized.flows || {};
+  if (!normalized.flows[flowId]) {
+    normalized.flows[flowId] = {
+      id: flowId,
+      title: meta && meta.title ? meta.title : flowId,
+      description: meta && meta.description ? meta.description : "",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      nodes: [],
+      edges: [],
+      assumptions: [],
+      openQuestions: [],
+    };
+  }
+  return normalized.flows[flowId];
+}
+
+function upsertFlowNode(index, flowId, cacheKey) {
+  const flow = ensureFlow(index, flowId, {});
+  if (!flow.nodes.includes(cacheKey)) {
+    flow.nodes.push(cacheKey);
+  }
+  flow.updatedAt = new Date().toISOString();
+}
+
+function addFlowEdge(index, flowId, fromKey, toKey, type, note) {
+  const flow = ensureFlow(index, flowId, {});
+  const edge = {
+    id: `${fromKey}->${toKey}:${type}:${Date.now()}`,
+    from: fromKey,
+    to: toKey,
+    type,
+    note: note || "",
+    createdAt: new Date().toISOString(),
+  };
+  flow.edges.push(edge);
+  flow.updatedAt = new Date().toISOString();
+}
+
+/** @returns {string} */
+function inferCliExample() {
+  const n = normalizeSlash(String(process.argv[1] || ""));
+  if (/\/bin\/figma-cache\.js$/i.test(n)) {
+    return "node bin/figma-cache.js";
+  }
+  if (/\/figma-cache\/figma-cache\.js$/i.test(n)) {
+    return "node figma-cache/figma-cache.js";
+  }
+  return "figma-cache";
+}
+
+function printStale(days) {
+  const index = readIndex();
+  const now = Date.now();
+  const threshold = days * 24 * 60 * 60 * 1000;
+  const keys = Object.keys(index.items || {});
+  const stale = keys.filter((cacheKey) => {
+    const item = index.items[cacheKey];
+    const ts = item.syncedAt ? Date.parse(item.syncedAt) : NaN;
+    if (Number.isNaN(ts)) {
+      return true;
+    }
+    return now - ts > threshold;
+  });
+  if (!stale.length) {
+    console.log(`No stale entries (>${days}d).`);
+    return;
+  }
+  console.log(`Stale entries (>${days}d):`);
+  stale.forEach((key) => {
+    console.log(`- ${key}`);
+  });
+}
+
+function run() {
+  const [, , cmd, ...args] = process.argv;
+  if (!cmd) {
+    const ex = inferCliExample();
+    console.log("Usage:");
+    console.log(`  (invoke examples: ${ex} | node bin/figma-cache.js | node figma-cache/figma-cache.js)`);
+    console.log(`  ${ex} normalize <figmaUrl>`);
+    console.log(`  ${ex} get <figmaUrl>`);
+    console.log(`  ${ex} upsert <figmaUrl> [--source=manual] [--completeness=a,b]`);
+    console.log(`  ${ex} validate`);
+    console.log(`  ${ex} stale [--days=14]`);
+    console.log(`  ${ex} backfill`);
+    console.log(`  ${ex} ensure <figmaUrl> [--source=manual] [--completeness=a,b]`);
+    console.log(`  ${ex} init`);
+    console.log(`  ${ex} config`);
+    console.log(
+      "  (optional) figma-cache.config.js | .figmacacherc.js | FIGMA_CACHE_PROJECT_CONFIG — hooks.postEnsure after ensure"
+    );
+    console.log(`  ${ex} flow init --id=<flowId> [--title=...]`);
+    console.log(
+      `${ex} flow add-node --flow=<flowId> <figmaUrl> [--ensure] [--source=manual] [--completeness=a,b]`
+    );
+    console.log(
+      `${ex} flow link --flow=<flowId> <fromUrl> <toUrl> --type=next_step [--note=...]`
+    );
+    console.log(
+      `${ex} flow chain --flow=<flowId> <url1> <url2> ... [--type=next_step|related]`
+    );
+    console.log(`  ${ex} flow show --flow=<flowId>`);
+    console.log(`  ${ex} flow mermaid --flow=<flowId>`);
+    process.exit(1);
+  }
+
+  if (cmd === "normalize") {
+    const url = args[0];
+    const normalized = normalizeFigmaUrl(url);
+    console.log(JSON.stringify(normalized, null, 2));
+    return;
+  }
+
+  if (cmd === "get") {
+    const url = args[0];
+    const normalized = normalizeFigmaUrl(url);
+    const index = readIndex();
+    const item = getItem(index, normalized.cacheKey);
+    console.log(
+      JSON.stringify(
+        {
+          found: !!item,
+          cacheKey: normalized.cacheKey,
+          item: item || null,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (cmd === "upsert") {
+    const url = args[0];
+    const sourceArg = args.find((x) => x.startsWith("--source="));
+    const completenessArg = args.find((x) => x.startsWith("--completeness="));
+    const source = sourceArg ? sourceArg.split("=")[1] : "manual";
+    const completeness = completenessArg
+      ? completenessArg
+          .split("=")[1]
+          .split(",")
+          .map((x) => x.trim())
+          .filter(Boolean)
+      : [];
+    const result = upsertByUrl(url, { source, completeness });
+    console.log(
+      JSON.stringify(
+        { cacheKey: result.normalized.cacheKey, scope: result.item.scope, syncedAt: result.item.syncedAt },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (cmd === "ensure") {
+    const url = args[0];
+    const sourceArg = args.find((x) => x.startsWith("--source="));
+    const completenessArg = args.find((x) => x.startsWith("--completeness="));
+    const source = sourceArg ? sourceArg.split("=")[1] : "manual";
+    const completeness = completenessArg
+      ? completenessArg
+          .split("=")[1]
+          .split(",")
+          .map((x) => x.trim())
+          .filter(Boolean)
+      : [];
+    const result = upsertByUrl(url, { source, completeness });
+    ensureEntryFilesAndHook(result.normalized.cacheKey, result.item);
+    console.log(
+      JSON.stringify(
+        {
+          cacheKey: result.normalized.cacheKey,
+          ensured: true,
+          paths: result.item.paths,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (cmd === "validate") {
+    const index = readIndex();
+    const errors = validateIndex(index);
+    if (!errors.length) {
+      console.log("Validation passed.");
+      return;
+    }
+    console.error("Validation failed:");
+    errors.forEach((err) => console.error(`- ${err}`));
+    process.exit(2);
+  }
+
+  if (cmd === "stale") {
+    const daysArg = args.find((x) => x.startsWith("--days="));
+    const days = daysArg ? Number(daysArg.split("=")[1]) : DEFAULT_STALE_DAYS;
+    printStale(days);
+    return;
+  }
+
+  if (cmd === "backfill") {
+    backfillFromIterations();
+    return;
+  }
+
+  if (cmd === "config") {
+    const cfg = loadProjectConfig();
+    const hooks = cfg && cfg.hooks;
+    console.log(
+      JSON.stringify(
+        {
+          root: normalizeSlash(ROOT),
+          cacheDir: normalizeSlash(CACHE_DIR),
+          indexPath: normalizeSlash(INDEX_PATH),
+          iterationsDir: normalizeSlash(ITERATIONS_DIR),
+          staleDays: DEFAULT_STALE_DAYS,
+          defaultFlowId: DEFAULT_FLOW_ID || null,
+          normalizationVersion: NORMALIZATION_VERSION,
+          projectConfigPath: memoProjectConfigPath
+            ? normalizeSlash(memoProjectConfigPath)
+            : null,
+          hooks: {
+            postEnsure: !!(hooks && typeof hooks.postEnsure === "function"),
+          },
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (cmd === "init") {
+    ensureCacheDir();
+    if (fs.existsSync(INDEX_PATH)) {
+      console.log(
+        JSON.stringify(
+          {
+            created: false,
+            reason: "index_exists",
+            indexPath: normalizeSlash(INDEX_PATH),
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    writeIndex(buildEmptyIndex());
+    console.log(
+      JSON.stringify(
+        {
+          created: true,
+          indexPath: normalizeSlash(INDEX_PATH),
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (cmd === "flow") {
+    const sub = args[0];
+    const rest = args.slice(1);
+    if (!sub) {
+      console.error("Missing flow subcommand");
+      process.exit(1);
+    }
+
+    if (sub === "init") {
+      const idArg = rest.find((x) => x.startsWith("--id="));
+      const titleArg = rest.find((x) => x.startsWith("--title="));
+      const descArg = rest.find((x) => x.startsWith("--description="));
+      const flowId = idArg ? idArg.split("=")[1] : slugifyFlowId("flow");
+      const title = titleArg ? titleArg.split("=").slice(1).join("=") : flowId;
+      const description = descArg ? descArg.split("=").slice(1).join("=") : "";
+      const index = normalizeIndexShape(readIndex());
+      ensureFlow(index, flowId, { title, description });
+      writeIndex(index);
+      console.log(JSON.stringify({ flowId, created: true }, null, 2));
+      return;
+    }
+
+    if (sub === "add-node") {
+      const flowId = resolveFlowIdFromArgs(rest);
+      if (!flowId) {
+        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
+        process.exit(1);
+      }
+      const url = rest.find((x) => !x.startsWith("--"));
+      const ensureArg = rest.includes("--ensure");
+      const sourceArg = rest.find((x) => x.startsWith("--source="));
+      const completenessArg = rest.find((x) => x.startsWith("--completeness="));
+      const source = sourceArg ? sourceArg.split("=")[1] : "manual";
+      const completeness = completenessArg
+        ? completenessArg
+            .split("=")[1]
+            .split(",")
+            .map((x) => x.trim())
+            .filter(Boolean)
+        : [];
+      const index = normalizeIndexShape(readIndex());
+      const normalized = normalizeFigmaUrl(url);
+      if (!ensureArg && !getItem(index, normalized.cacheKey)) {
+        console.error(
+          `Missing cache item for ${normalized.cacheKey}. Run figma:cache:ensure first, or pass --ensure.`
+        );
+        process.exit(2);
+      }
+      if (ensureArg) {
+        upsertByUrl(url, { source, completeness });
+        const refreshed = normalizeIndexShape(readIndex());
+        const item = getItem(refreshed, normalized.cacheKey);
+        if (item) {
+          ensureEntryFilesAndHook(normalized.cacheKey, item);
+        }
+        Object.assign(index, refreshed);
+      }
+      upsertFlowNode(index, flowId, normalized.cacheKey);
+      writeIndex(index);
+      console.log(
+        JSON.stringify(
+          { flowId, cacheKey: normalized.cacheKey, added: true, ensured: ensureArg },
+          null,
+          2
+        )
+      );
+      return;
+    }
+
+    if (sub === "link") {
+      const flowId = resolveFlowIdFromArgs(rest);
+      const typeArg = rest.find((x) => x.startsWith("--type="));
+      const noteArg = rest.find((x) => x.startsWith("--note="));
+      const urls = rest.filter((x) => !x.startsWith("--"));
+      if (!flowId) {
+        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
+        process.exit(1);
+      }
+      if (urls.length < 2) {
+        console.error("Missing <fromUrl> <toUrl>");
+        process.exit(1);
+      }
+      const type = typeArg ? typeArg.split("=")[1] : "related";
+      const note = noteArg ? noteArg.split("=").slice(1).join("=") : "";
+      const from = normalizeFigmaUrl(urls[0]).cacheKey;
+      const to = normalizeFigmaUrl(urls[1]).cacheKey;
+      const index = normalizeIndexShape(readIndex());
+      if (!getItem(index, from) || !getItem(index, to)) {
+        console.error("Missing cache item for from/to. Cache urls first with ensure/upsert.");
+        process.exit(2);
+      }
+      upsertFlowNode(index, flowId, from);
+      upsertFlowNode(index, flowId, to);
+      addFlowEdge(index, flowId, from, to, type, note);
+      writeIndex(index);
+      console.log(JSON.stringify({ flowId, from, to, type, linked: true }, null, 2));
+      return;
+    }
+
+    if (sub === "chain") {
+      const flowId = resolveFlowIdFromArgs(rest);
+      const typeArg = rest.find((x) => x.startsWith("--type="));
+      const type = typeArg ? typeArg.split("=")[1] : "related";
+      const urls = rest.filter((x) => !x.startsWith("--"));
+      if (!flowId) {
+        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
+        process.exit(1);
+      }
+      if (urls.length < 2) {
+        console.error("Need at least 2 urls");
+        process.exit(1);
+      }
+      const index = normalizeIndexShape(readIndex());
+      const keys = urls.map((u) => normalizeFigmaUrl(u).cacheKey);
+      keys.forEach((k) => {
+        if (!getItem(index, k)) {
+          console.error(`Missing cache item for ${k}. Ensure each url is cached first.`);
+          process.exit(2);
+        }
+      });
+      keys.forEach((k) => upsertFlowNode(index, flowId, k));
+      for (let i = 0; i < keys.length - 1; i += 1) {
+        addFlowEdge(index, flowId, keys[i], keys[i + 1], type, "");
+      }
+      writeIndex(index);
+      console.log(JSON.stringify({ flowId, chained: keys.length - 1, type }, null, 2));
+      return;
+    }
+
+    if (sub === "show") {
+      const flowId = resolveFlowIdFromArgs(rest);
+      if (!flowId) {
+        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
+        process.exit(1);
+      }
+      const index = normalizeIndexShape(readIndex());
+      const flow = index.flows[flowId];
+      console.log(JSON.stringify({ flowId, flow: flow || null }, null, 2));
+      return;
+    }
+
+    if (sub === "mermaid") {
+      const flowId = resolveFlowIdFromArgs(rest);
+      if (!flowId) {
+        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
+        process.exit(1);
+      }
+      const index = normalizeIndexShape(readIndex());
+      const flow = index.flows[flowId];
+      if (!flow) {
+        console.error(`Unknown flow: ${flowId}`);
+        process.exit(1);
+      }
+      const lines = ["flowchart LR"];
+      (flow.edges || []).forEach((edge) => {
+        const label = edge.type || "edge";
+        lines.push(`  ${edge.from} -->|${label}| ${edge.to}`);
+      });
+      console.log(lines.join("\n"));
+      return;
+    }
+
+    console.error(`Unknown flow subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  process.exit(1);
+}
+
+run();

package/figma-cache/flow-edge-taxonomy.md

@@ -0,0 +1,33 @@
+# Flow 边类型约定（单人迭代版）
+
+用于 `flows[].edges[].type` 字段。优先少而精，后续可扩展。
+
+## 主路径
+
+- `next_step`：主流程下一步（同模块线性推进）
+- `next_page`：跨页面/跨大区块的下一步（仍属主路径）
+
+## 弱关联
+
+- `related`：同迭代相关，但不确定先后或类型（占位，后续可升级）
+
+## 分支
+
+- `branch_true`：条件成立分支
+- `branch_false`：条件不成立分支
+- `branch_default`：默认分支
+
+## 结构关系
+
+- `child`：UI 结构父子（例如弹层属于某屏）
+- `variant`：同一节点的不同状态变体（A 与 A-error）
+
+## 逆向/回退
+
+- `back`：返回上一步
+- `cancel`：取消/关闭导致回到某节点
+
+## 备注
+
+- 不确定时先用 `related`，不要硬编 `next_step`。
+- 边上可用 `note` 写人话解释（例如“号码校验失败出现警告条”）。

package/figma-cache/link-normalization-spec.md

@@ -0,0 +1,16 @@
+# Figma 链接标准化规范
+
+本规范用于把不同形态的 Figma 分享链接归一为同一个缓存键，避免重复缓存与重复 MCP 拉取。
+
+## 标准键定义
+
+- `fileKey`: 从路径提取（支持 `/file/` 与 `/design/`）
+- `nodeId`: 从 `node-id` 提取并归一到冒号格式
+- `cacheKey`: `<fileKey>#<nodeId>`
+- 无 `node-id` 时：`<fileKey>#__FILE__`
+
+## 规则
+
+1. URL 解码并去除首尾空白。
+2. `9278-30678` 这类值转换为 `9278:30678`。
+3. 仅 `node-id` 参与定位；`t/page-id/mode/...` 视为无关参数。

package/figma-cache/migration-guide.md

@@ -0,0 +1,79 @@
+# Figma 缓存流程移植指南
+
+## 需要复制的文件
+
+- `figma-cache/`（**建议**：脚本与规范文档全量复制；**业务缓存** `figma-cache/files/` 与 `figma-cache/index.json` 可按需不带——在新项目执行 `npm run figma:cache:init` 再 `ensure` 重建）
+- （**可选**，与本仓库「npm 包」形态一致时）根目录 `bin/figma-cache.js`：CLI 薄封装；若仅复制 `figma-cache/` 并以 `node figma-cache/figma-cache.js` 调用，可不复制 `bin/`
+- **`figma-cache.config.js`（项目根）**：`postEnsure` 与适配文档模板；无则钩子不执行，Core 仍可用
+- `.cursor/rules/01-figma-cache-core.mdc`（数据层，always on）
+- `.cursor/rules/02-figma-vuetify2-adapter.mdc`（本仓库：Vue2+Vuetify2；**其他栈**请用下文 Agent 模板生成自己的 `02-figma-*-adapter.mdc`）
+- `.cursor/rules/figma-local-cache-first.mdc`（入口说明，可选）
+- `.cursor/skills/figma-mcp-local-cache/SKILL.md`
+
+## package.json scripts
+
+**方式 A（复制 `figma-cache/` 进业务仓库、不安装本工具 npm 包）**：用 `node` 直接调用脚本。
+
+```json
+{
+  "figma:cache:normalize": "node figma-cache/figma-cache.js normalize",
+  "figma:cache:get": "node figma-cache/figma-cache.js get",
+  "figma:cache:upsert": "node figma-cache/figma-cache.js upsert",
+  "figma:cache:ensure": "node figma-cache/figma-cache.js ensure",
+  "figma:cache:validate": "node figma-cache/figma-cache.js validate",
+  "figma:cache:stale": "node figma-cache/figma-cache.js stale",
+  "figma:cache:backfill": "node figma-cache/figma-cache.js backfill",
+  "figma:cache:init": "node figma-cache/figma-cache.js init",
+  "figma:cache:config": "node figma-cache/figma-cache.js config",
+  "figma:cache:flow:init": "node figma-cache/figma-cache.js flow init",
+  "figma:cache:flow:add-node": "node figma-cache/figma-cache.js flow add-node",
+  "figma:cache:flow:link": "node figma-cache/figma-cache.js flow link",
+  "figma:cache:flow:chain": "node figma-cache/figma-cache.js flow chain",
+  "figma:cache:flow:show": "node figma-cache/figma-cache.js flow show",
+  "figma:cache:flow:mermaid": "node figma-cache/figma-cache.js flow mermaid"
+}
+```
+
+**方式 B（将本工具作为 devDependency 安装）**：包内 `bin/figma-cache.js` 注册为可执行名 `figma-cache`；消费方 `npm run` 通常可直接写 `figma-cache <子命令>`（会走 `node_modules/.bin`）。**本工具链仓库根目录**在无依赖时部分 npm 版本不会把当前包自身写入 `.bin`，故根 `package.json` 使用 `node bin/figma-cache.js <子命令>` 以保证自检可运行；二者等价。
+
+## 迁移后验证
+
+1. `npm run figma:cache:config`
+2. `npm run figma:cache:validate`
+3. 用真实链接执行一次 `get -> ensure`
+
+## 可选环境变量
+
+- `FIGMA_CACHE_DIR`：缓存根目录
+- `FIGMA_CACHE_INDEX_FILE`：索引文件路径
+- `FIGMA_ITERATIONS_DIR`：历史文档扫描目录（**仅** `backfill` 使用）。目录不存在时扫描结果为空、`validate` 不受影响；需要回填时可选择：创建该目录并放入历史 `.md`、设置本变量指向已有目录、或从旧库拷贝迭代文档树
+- `FIGMA_CACHE_STALE_DAYS`：陈旧阈值（天）
+- `FIGMA_DEFAULT_FLOW`：默认 flowId（大迭代推荐设置）
+- `FIGMA_CACHE_ADAPTER_DOC`：覆盖 `postEnsure` 写入的适配说明文件名（默认见各项目 `figma-cache.config.js`）
+
+## 用 Agent 生成「其他技术栈」的 Adapter 规则
+
+可以。把下面整段丢给 Cursor（把花括号里的内容换成你的栈），让它在 `.cursor/rules/` 下新建或覆盖 `02-figma-*-adapter.mdc`，并视情况改 `figma-cache.config.js` 里生成的节点侧文件名与模板文案。
+
+```text
+请为本仓库生成 Cursor 规则文件：`.cursor/rules/02-figma-{框架}-adapter.mdc`（alwaysApply: false）。
+
+约束：
+- 本仓库 UI 栈：{例如 Vue 3 + Element Plus + UnoCSS / 或 React + MUI}。
+- 必须先读 01-figma-cache-core 的边界：Core 只维护 figma-cache 通用文件；本文件只约束「读缓存后如何写业务 UI」。
+- 写明：必读 raw.json、spec.md、state-map.md；禁止在 meta/raw/spec 里写框架专有内容。
+- 与 figma-cache.config.js 的 postEnsure 生成的「节点目录下的 *-mapping.*」如何呼应（文件名建议与栈一致）。
+- 中文撰写，简洁可执行。
+```
+
+生成后把 **01-figma-cache-core.mdc** 里「Adapter 规则」的示例文件名改成你实际文件名（一处引用即可）。
+
+## 将 Core 抽成独立 npm 包（维护方式概要）
+
+1. **包内容**：只发布「中立」部分：`bin/figma-cache.js`（薄封装，加载同包内 `figma-cache/figma-cache.js`）、各 `*.md` 规范与指南；**不要**把某项目的 `figma-cache.config.js`、`.cursor/rules/02-*`、业务缓存目录 `figma-cache/files/` 打进包（默认用 `files` 白名单约束）。
+2. **package.json**：`"bin": { "figma-cache": "bin/figma-cache.js" }`（或 `@scope/figma-cache`）；`engines` 写明 Node 16+；`files` 白名单避免把样例 `index.json` 与大体积 `files/` 打进包。
+3. **消费方**：`npm i -D @scope/figma-cache`，scripts 改为 `node node_modules/@scope/figma-cache/cli.js ...` 或直接用 `figma-cache` 命令；项目根保留自己的 `figma-cache.config.js` 与 `.cursor/rules`。
+4. **版本与变更**：遵循 semver；钩子 `ctx` 字段变更算 **minor** 并写 CHANGELOG；破坏性改 `ctx` 或 CLI 行为算 **major**。
+5. **本仓库过渡**：可先 `npm link` 本地包验证，再发布；发布后将本仓库 `figma-cache/` 中「脚本与 spec」替换为依赖包，目录名可保留 `figma-cache/` 仅放数据与 index（或整目录改名为 `.cache/figma` 由 env 指定）。
+
+更细的发布 checklist 可在发包前补：LICENSE、仓库 URL、`npm publish --dry-run`、`.npmignore`。

package/figma-cache/validation-checklist.md

@@ -0,0 +1,15 @@
+# Figma 缓存校验清单
+
+- [ ] `index.json` 存在对应 `cacheKey`
+- [ ] 记录包含 `fileKey/scope/url/syncedAt`
+- [ ] `normalizationVersion` 与当前规范一致
+- [ ] `paths.meta` 与 `paths.spec` 已定义
+- [ ] `completeness` 覆盖当前任务字段
+- [ ] `scope=node` 时存在 `nodeId`
+- [ ] 若维护了 `flows`，边的 `from/to` 必须存在于 `items`
+
+快速检查：
+
+```bash
+npm run figma:cache:validate
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "figma-cache-toolchain",
+  "version": "1.0.0",
+  "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
+  "keywords": [
+    "figma",
+    "cache",
+    "cli",
+    "design-tokens",
+    "mcp"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.20.0"
+  },
+  "bin": {
+    "figma-cache": "bin/figma-cache.js"
+  },
+  "files": [
+    "LICENSE",
+    "bin",
+    "figma-cache/figma-cache.js",
+    "figma-cache/*.md"
+  ],
+  "scripts": {
+    "prepack": "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",
+    "figma:cache:ensure": "node bin/figma-cache.js ensure",
+    "figma:cache:validate": "node bin/figma-cache.js validate",
+    "figma:cache:stale": "node bin/figma-cache.js stale",
+    "figma:cache:backfill": "node bin/figma-cache.js backfill",
+    "figma:cache:init": "node bin/figma-cache.js init",
+    "figma:cache:config": "node bin/figma-cache.js config",
+    "figma:cache:flow:init": "node bin/figma-cache.js flow init",
+    "figma:cache:flow:add-node": "node bin/figma-cache.js flow add-node",
+    "figma:cache:flow:link": "node bin/figma-cache.js flow link",
+    "figma:cache:flow:chain": "node bin/figma-cache.js flow chain",
+    "figma:cache:flow:show": "node bin/figma-cache.js flow show",
+    "figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid"
+  },
+  "volta": {
+    "node": "16.20.2"
+  }
+}