figma-cache-toolchain 1.0.0 → 1.3.1

package/README.md

@@ -1,65 +1,78 @@
 # 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** 分发的 Figma 本地缓存工具链：链接标准化、`figma-cache/` 索引与校验、零运行时依赖的 Node CLI。Core **不绑定**具体 UI 框架；表现层由 Agent 按你项目栈生成 **`figma-cache.config.js`** 与 **`.cursor/rules/02-figma-<栈>-adapter.mdc`**（见下方「三步走」）。
 
-## 安装
+## 消费方：三步完成适配（仅需 npm，无需克隆其它仓库）
 
-在发布到 npm 之前，请在本仓库根目录执行 `npm link`（或发布后使用你在 `package.json` 中声明的最终包名，例如 `npm i -D <你的作用域>/figma-cache-toolchain`）。**请勿假设**某个尚未发布的固定包名已存在于公共 registry。
+以下路径均在**你的业务项目根目录**（已执行 `npm i -D figma-cache-toolchain` 或等价安装）。
 
-安装后，消费方项目的 `package.json` 可注册与下文「脚本」一致的 `npm run figma:cache:*` 命令。
+### 1. 安装
 
-## 脚本（消费方）
+```bash
+npm i -D figma-cache-toolchain
+```
+
+### 2. 初始化 Cursor 模板与 Agent 任务书
+
+在项目根执行：
 
-与 `figma-cache/migration-guide.md` 一致：作为 **依赖安装** 后，可用 `figma-cache config` 等形式（由 `node_modules/.bin` 解析）。在本仓库根目录开发时，`package.json` 使用 `node bin/figma-cache.js …`，避免仅含当前包、无其他依赖时本地 `.bin` 未生成导致命令找不到。
+```bash
+npx figma-cache cursor init
+```
 
-若**不**通过 npm 安装、而是复制 `figma-cache/` 目录到业务仓库，可继续使用：
+- 会写入 / 更新：`.cursor/rules/`、`.cursor/skills/`、`figma-cache.config.example.js` 等（已存在则默认跳过，除非加 `--force`）。
+- **每次**都会刷新项目根下的 **`AGENT-SETUP-PROMPT.md`**（由包内模板生成，含完整 Agent 指令）。
 
-- `node figma-cache/figma-cache.js <子命令> ...`
+### 3. 交给 Cursor Agent（最少人工）
 
-## 项目级配置与钩子
+在 Cursor 中打开 **`AGENT-SETUP-PROMPT.md`**，任选其一：
 
-- 在消费项目根目录放置 `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` 失败退出。
+- 在对话里 **`@AGENT-SETUP-PROMPT.md`** 并说「按该文档执行」；或  
+- 全选文件内容，粘贴到 Agent。
 
-## 环境变量（节选）
+Agent 将按文档自动：推断栈、生成/合并 **`figma-cache.config.js`**、生成栈专属 Adapter、**删除占位** `02-figma-stack-adapter.mdc`、按需补全 **`figma:cache:*` scripts** 等。完成后按文档提示跑一次 **`npx figma-cache validate`**（或已加的 npm script）。
+
+更细的约定见随包安装的 **`figma-cache/migration-guide.md`**（在 `node_modules/figma-cache-toolchain/figma-cache/` 内，无需单独仓库）。
 
-完整列表见 `figma-cache/migration-guide.md` 与 `figma-cache/README.md`。
+---
+
+## 脚本（可选）
+
+在业务项目 `package.json` 的 `scripts` 中可使用 `npx figma-cache <子命令>`，避免依赖本机全局安装。常用子命令与示例见 **`figma-cache/migration-guide.md`** 中的 JSON 片段。
+
+---
+
+## 环境变量（节选）
 
 | 变量 | 作用 |
 |------|------|
 | `FIGMA_CACHE_DIR` | 缓存根目录，默认 `figma-cache` |
 | `FIGMA_CACHE_INDEX_FILE` | 索引文件名或绝对路径 |
-| `FIGMA_ITERATIONS_DIR` | `backfill` 扫描的 Markdown 目录；**目录不存在时**仅导致 `backfill` 扫描结果为空，不影响 `validate` |
+| `FIGMA_ITERATIONS_DIR` | 仅 `backfill` 扫描的 Markdown 目录 |
 | `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
 | `FIGMA_DEFAULT_FLOW` | 默认 `flowId` |
 | `FIGMA_CACHE_PROJECT_CONFIG` | 覆盖项目配置文件路径 |
 
-## Cursor 规则与 Skill
-
-将本仓库中的下列文件复制到消费项目（路径保持一致即可）：
+完整说明见 **`figma-cache/README.md`**（同在 npm 包内）。
 
-- `.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` 生成数据目录。
+发布的 tarball 仅含 CLI、规范文档、`cursor-bootstrap` 等；**不包含**你项目里的 `figma-cache/files/` 与 `index.json`。数据目录由你在业务仓库内通过 **`figma-cache init`** 与后续 **`ensure`** 等生成。
+
+---
 
-## 自用与偶发发版
+## 维护者（发布 npm 包）
 
-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」，需先保证能通过校验或临时调整流程（默认假设本仓库带可校验的示例/真实索引）。
+1. 改包内代码或 `cursor-bootstrap/` 后 bump **`package.json` 的 `version`**，并更新 **`CHANGELOG.md`**。  
+2. **`npm publish`**（已配置 `publishConfig.registry` 时指向 npm 官方）。  
+3. **`prepack`** 会在 pack/publish 前执行本仓库内的 `validate`；若发布用工作区故意无缓存，需自行处理校验策略。
 
-## 开发自检
+自检示例：
 
 ```bash
-npm run figma:cache:config
-npm run figma:cache:validate
-npm pack
+npm test
+npx figma-cache validate
 npm publish --dry-run
 ```

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

@@ -0,0 +1,47 @@
+# Figma Cache：请 Agent 一次性完成项目适配
+
+> **给 Cursor Agent 的指令**：你正在操作的是**用户业务项目**的根目录。以下文件应已存在（由 `npx figma-cache cursor init` 从 npm 包 **`{{NPM_PACKAGE_NAME}}`** 复制到当前仓库根）：
+> - `.cursor/rules/01-figma-cache-core.mdc`
+> - `.cursor/rules/02-figma-stack-adapter.mdc`（**占位**，任务完成后需删除）
+> - `.cursor/rules/figma-local-cache-first.mdc`（可选保留）
+> - `.cursor/skills/figma-mcp-local-cache/SKILL.md`
+> - `figma-cache.config.example.js`（默认中性 `postEnsure` 示例）
+
+## 你必须完成的任务（按顺序执行，尽量少问用户）
+
+1. **读取工程事实**  
+   阅读 `package.json` 及存在的构建配置（如 `vite.config.*`、`vue.config.js`、`next.config.*`、`tsconfig.json` 等），**自行推断** UI 技术栈（框架、组件库、样式方案、状态管理若有则记录）。仅在关键信息完全无法从仓库推断时，再向用户提一个极简问题。
+
+2. **生成 `figma-cache.config.js`**  
+   - 若根目录**尚不存在** `figma-cache.config.js`：以 `figma-cache.config.example.js` 为参考，新建完整 `figma-cache.config.js`，实现与栈匹配的 `hooks.postEnsure`（节点目录下 hint 文件名与第 3 步 Adapter 规则中的命名一致；可用环境变量 `FIGMA_CACHE_ADAPTER_DOC` 约定文件名）。  
+   - 若**已存在** `figma-cache.config.js`：**合并**而非盲目覆盖——保留用户已有非 figma-cache 字段，仅补充或调整 `hooks.postEnsure` 及与 figma-cache 相关的导出；冲突时以「不破坏用户现有逻辑」优先并注释说明。
+
+3. **生成栈专属 Adapter 规则**  
+   新建 **`.cursor/rules/02-figma-<栈简名>-adapter.mdc`**（`alwaysApply: false`）。内容须与 **`01-figma-cache-core.mdc`** 边界一致：只约束「在通用缓存可读之后如何写业务 UI」；**禁止**要求在 `meta.json` / `raw.json` / `spec.md` 中写入框架专有实现。
+
+4. **删除占位规则**  
+   确认第 3 步文件已写入且无语法问题后，**删除** `.cursor/rules/02-figma-stack-adapter.mdc`。若用户在 Cursor 设置里固定引用了该文件名，请在汇报中提示用户改为引用新的 `02-figma-<栈>-adapter.mdc`。
+
+5. **补全 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` 或包内 `migration-guide.md` 中 scripts 示例一致即可）。
+
+6. **收尾**  
+   - 用简短列表向用户汇报：新建/修改/删除了哪些路径。  
+   - 提示用户在本项目根执行：`npm run figma:cache:validate`（若已加 script）或 `npx figma-cache validate`。  
+   - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。
+
+## 硬约束（违反则视为未完成）
+
+- **不要**修改 `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`  
+若用户明确要求该栈，可读入后改写为第 3 步的 Adapter 规则内容。
+
+---
+
+**开始执行：**读完本文件后立刻按上述顺序操作仓库文件，直至全部完成。

package/cursor-bootstrap/examples/README.md

@@ -0,0 +1,9 @@
+# 栈相关参考（不随 `cursor init` 复制）
+
+本目录存放 **可选** 的完整 Adapter 示例，供人工或 Agent 对照；**通用默认**请使用 `cursor init` 生成的 `02-figma-stack-adapter.mdc` 与根目录 `figma-cache.config.example.js`。
+
+| 文件 | 说明 |
+|------|------|
+| `vue2-vuetify2-adapter.reference.mdc` | 历史 Vue 2 + Vuetify 2 表现层规则全文，可复制为 `.cursor/rules/02-figma-vuetify2-adapter.mdc` 并按项目改名 |
+
+将参考规则复制进 `.cursor/rules/` 后，记得同步 `figma-cache.config.js` 里 `FIGMA_CACHE_ADAPTER_DOC` 与 `postEnsure` 生成文件名，与 Adapter 规则中的描述一致。

package/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc

@@ -0,0 +1,25 @@
+---
+description: 在通用 figma-cache 就绪后，将设计事实映射为 Vue 2 + Vuetify 2 实现（参考示例，按需复制到 .cursor/rules/）
+alwaysApply: false
+---
+
+# Figma → Vuetify 2 Adapter（表现层）
+
+当任务为 **编写或修改 Vue 2 前端代码** 且依赖 Figma 设计稿时，在 **01-figma-cache-core** 已完成或确认可读的通用缓存（`raw.json`、`spec.md`、`state-map.md`）基础上，遵守本规则做 **Vuetify 2** 映射。
+
+## 前置
+1. 缓存状态由 Core 规则处理；若尚无缓存，先按 Core 流程 `ensure` / MCP / `validate`。
+2. 若节点目录下存在由 `postEnsure` 生成的栈说明文件（如 **`vuetify2-mapping.mdc`**），实现前可快速浏览其中的引导。
+
+## 映射原则
+- **单一事实来源**：尺寸、颜色、文案、状态以 `figma-cache` 中通用文件为准，不在业务代码里硬抄未经验证的截图值。
+- **组件与主题**：优先使用 **Vuetify 2** 内置组件（`v-btn`、`v-card`、`v-text-field` 等）与现有工程里的主题/SCSS/Uno（`tw-*`）约定；Options API、与项目既有约定一致。
+- **不污染 Core**：不在 `figma-cache/files/**` 的 `meta.json`、`raw.json`、`spec.md` 中写入 Vuetify 或路由等业务专有内容；框架说明写在节点侧 hint 或业务源码中。
+
+## 与 Core 的边界
+| 阶段 | 负责规则 | 产出 |
+| --- | --- | --- |
+| 拉数与索引 | 01-figma-cache-core | 通用 JSON/Markdown |
+| 组件与样式落地 | 本规则 | Vue 2 SFC、Vuetify 模板与样式 |
+
+若任务仅为更新缓存、无 UI 编码，**不要**应用本规则中的组件映射条款。

package/cursor-bootstrap/figma-cache.config.example.js

@@ -0,0 +1,68 @@
+/**
+ * 项目级 Figma 缓存扩展（示例模板，**不绑定任何 UI 框架**）。
+ *
+ * 安装本 npm 包并执行 `npx figma-cache cursor init` 后，项目根会出现 **AGENT-SETUP-PROMPT.md**：
+ * 请用 Cursor Agent **按该文件全文**执行，以自动生成 `figma-cache.config.js`、栈专属 Adapter、并删除占位规则等（尽量少手动步骤）。
+ *
+ * 若你已有 `figma-cache.config.js`，可由 Agent 合并而非覆盖。
+ *
+ * 加载顺序见 `figma-cache/figma-cache.js`：FIGMA_CACHE_PROJECT_CONFIG → figma-cache.config.js → .figmacacherc.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/** 节点目录下由 postEnsure 写入的说明文件（可用环境变量 FIGMA_CACHE_ADAPTER_DOC 覆盖） */
+const ADAPTER_DOC_BASENAME =
+  process.env.FIGMA_CACHE_ADAPTER_DOC || "figma-cache-adapter-hint.md";
+
+/**
+ * @param {object} ctx
+ * @returns {string}
+ */
+function buildNeutralHint(ctx) {
+  const nodeLabel = ctx.nodeId == null ? "" : String(ctx.nodeId);
+  return `# Figma 缓存 → UI 实现（占位提示）
+
+本文件由 **空示例** \`postEnsure\` 生成；请用 Agent 按项目栈替换为具体说明，或删除本文件并在 \`figma-cache.config.js\` 中实现自定义逻辑。
+
+- **设计事实来源**（勿改写成框架代码）：同目录 \`raw.json\`、\`spec.md\`、\`state-map.md\`、\`meta.json\`
+- cacheKey: \`${ctx.cacheKey}\`
+- fileKey: \`${ctx.fileKey}\`
+- nodeId: \`${nodeLabel}\`
+
+下一步：打开项目根 \`AGENT-SETUP-PROMPT.md\`，整篇交给 Cursor Agent 执行以完成栈适配（含本钩子的具体实现与 \`02-figma-<栈>-adapter.mdc\`）。
+`;
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.root
+ * @param {{ meta: string }} ctx.paths
+ */
+function writeAdapterHint(ctx) {
+  const metaAbs = path.resolve(ctx.root, ctx.paths.meta);
+  const dir = path.dirname(metaAbs);
+  const target = path.join(dir, ADAPTER_DOC_BASENAME);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(target, buildNeutralHint(ctx), "utf8");
+}
+
+module.exports = {
+  buildNeutralHint,
+  ADAPTER_DOC_BASENAME,
+
+  hooks: {
+    /**
+     * 默认实现：仅写入中性占位 Markdown，便于确认钩子已接通。
+     * 用 Agent 生成业务方案后，可整体替换本模块逻辑。
+     */
+    postEnsure(ctx) {
+      try {
+        writeAdapterHint(ctx);
+      } catch (err) {
+        console.error(`[figma-cache.config] postEnsure: ${err.message}`);
+      }
+    },
+  },
+};

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

@@ -0,0 +1,51 @@
+---
+description: Figma 本地缓存优先 — 仅负责链接标准化、索引、MCP 与通用文件，不写业务前端代码
+alwaysApply: true
+---
+
+# Figma Cache Core（数据层）
+
+本规则只约束 **Figma → 本地通用缓存** 的流程：标准化 URL、读写 `figma-cache/`、`index.json`、必要时 MCP、校验。**不**在此阶段编写 Vue/React 组件或映射到任何 UI 库；实现代码时由项目 Adapter 规则约束。
+
+## 目标
+- 对用户提供的 Figma 链接，优先复用项目内已落地的结构化文档（`meta.json`、`spec.md`、`raw.json`、`state-map.md` 等）。
+- 仅在本地信息不足以完成任务时调用 Figma MCP。
+- 项目级扩展通过仓库根目录的 `figma-cache.config.js` / `.figmacacherc.js` 的 `hooks.postEnsure` 完成；Core 脚本不包含任何具体 UI 框架名。
+
+<Trigger Conditions>
+
+以下任一成立时，Agent **必须**按本规则执行缓存流水线，并在回复**开头**输出「缓存状态 Blockquote」：
+
+1. **显式 Figma URL**：消息含 `figma.com` / `www.figma.com` 的可识别设计链接（`file`、`design`、`proto`、`embed` 等，含或不含 `node-id=`）。
+2. **隐式但可解析为 Figma**：含 `figma` 域名的短链、重定向说明，或「fileKey + node-id」且意图为某一画布节点。
+3. **本地缓存语义**：「figma 缓存」「本地缓存」「先查缓存」「figma-cache」「index.json」「spec.md」「state-map」等，且任务与该缓存相关。
+4. **设计落地/对齐（仅数据侧）**：需先拉齐/刷新设计事实、写入或读取 `figma-cache`，且上下文可解析链接或 `fileKey`/`node-id`。
+5. **显式跳过/刷新**：「跳过缓存」「强制刷新」「以 Figma 最新为准」——可走 MCP，Blockquote 标「更新」、来源 MCP。
+
+**不触发**：纯概念讨论、无可解析链接/键/节点线索、且与缓存目录无关。
+
+</Trigger Conditions>
+
+## 执行顺序
+1. 按 `figma-cache/link-normalization-spec.md` 标准化链接。
+2. 读本地 `index.json` 判断是否命中。
+3. 命中且字段满足任务 → 只读本地，不调 MCP。
+4. 未命中或不足 → MCP 拉取并回写通用缓存文件。
+5. **闭环校验（强制）**：每次 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`** 成功结束后，**自动静默**执行 `npm run figma:cache:validate`。
+6. validate 失败 → **自行修复并重复 validate 直至通过**，不得宣称缓存已就绪。
+7. **不写前端**：本阶段禁止输出业务组件实现；若用户要求写 UI，在缓存就绪后转由 **栈专属 Adapter 规则**（如 `02-figma-stack-adapter.mdc` 占位，或项目内 `02-figma-<栈>-adapter.mdc`）接管。
+
+## Agent 最终输出格式（强制）
+凡触发 `<Trigger Conditions>` 且本轮涉及缓存读写的回复，**正文第一段**必须为单行 Blockquote：
+
+`> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
+
+（语义与 `index.json` 中 `nodeId` / `__FILE__` 约定同前；Blockquote 后再写结论。）
+
+## 配置与钩子
+- `npm run figma:cache:config` 可查看是否加载 `hooks.postEnsure`。
+- `ensure` 在写入通用骨架后会调用 `hooks.postEnsure`；钩子异常**不得**阻断 ensure 成功退出（由 Core 捕获）。
+
+## 其余约定
+- 缓存目录、环境变量、`flows`、陈旧策略、提交前校验等与原「Local Cache First」一致，参见 `figma-cache/` 内文档及 `npm run figma:cache:*`。
+- 不在未校验时假定 Figma 为最新；用户显式要求实时读取时须遵守。

package/cursor-bootstrap/rules/02-figma-stack-adapter.mdc

@@ -0,0 +1,23 @@
+---
+description: 栈占位：由 Agent 按项目 UI 技术栈生成 02-figma-<stack>-adapter.mdc 后再实现业务 UI（本文件可删除或 alwaysApply 保持 false）
+alwaysApply: false
+---
+
+# Figma → UI Stack Adapter（占位）
+
+本文件是 **通用脚手架**，不绑定 Vue / React / 任何组件库。若你已有具体栈的 Adapter 规则（例如 `02-figma-vuetify2-adapter.mdc`、`02-figma-react-mui-adapter.mdc`），可将本文件删除，或在 Cursor 设置中不再引用本文件。
+
+## 第一步：用 Agent 生成栈专属规则
+
+在项目根执行 `npx figma-cache cursor init` 后，打开 **`AGENT-SETUP-PROMPT.md`**，在 Cursor 里 **`@AGENT-SETUP-PROMPT.md`** 或整篇粘贴给 Agent，让其按文档顺序执行（含推断栈、生成配置、删除本占位文件）。若你更习惯手写，也可自行新建 `02-figma-<栈>-adapter.mdc` 与 `figma-cache.config.js`，再删除本文件。
+
+生成后，**01-figma-cache-core** 仍只负责缓存与校验；**表现层**仅由你的 `02-figma-*-adapter` 约束。
+
+## 与 01 的固定边界
+
+- **单一事实来源**：实现 UI 时只从 `raw.json`、`spec.md`、`state-map.md`、`meta.json` 取数；不在这些通用文件里写入框架专有代码或路由名。
+- **仅当任务包含「写/改业务 UI」且缓存可读**时，才应用具体栈的 Adapter；纯缓存维护、只跑 CLI，不触发表现层规则。
+
+## 参考实现（非默认）
+
+安装本包后，示例路径为 **`node_modules/figma-cache-toolchain/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`**（Vue 2 + Vuetify 2 全文参考），需时由 Agent 读入并改写为你的 `.cursor/rules/02-figma-...`。

package/cursor-bootstrap/rules/figma-local-cache-first.mdc

@@ -0,0 +1,13 @@
+---
+description: 已拆分为 01（缓存 Core）与 02（栈占位 Adapter）；本文件仅作入口说明，不参与 always-on 约束
+alwaysApply: false
+---
+
+# Figma Local Cache First（入口）
+
+本仓库的 Figma 缓存与 Agent 约定已拆分为：
+
+1. **`.cursor/rules/01-figma-cache-core.mdc`** — 链接标准化、本地索引、MCP、validate、Blockquote 状态；**不写业务前端**。
+2. **`.cursor/rules/02-figma-stack-adapter.mdc`**（占位）— 提示用 Agent 生成 **`02-figma-<你的栈>-adapter.mdc`**；具体 Vue / React / 组件库约定只在栈专属文件中描述。
+
+请以上述规则为准；本文件保留作入口说明与人工查阅。

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

@@ -0,0 +1,144 @@
+---
+name: figma-mcp-local-cache
+description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优先读取。用于用户提供 Figma 链接、需要减少重复 MCP 调用、或要求复用历史规格文档的场景。
+---
+
+# Figma MCP Local Cache
+
+本 Skill 与仓库规则 **`.cursor/rules/01-figma-cache-core.mdc`** **对齐**（表现层见栈占位 `02-figma-stack-adapter.mdc` 或你项目内的 `02-figma-<栈>-adapter.mdc`）：触发条件、闭环校验、回复开头 Blockquote **均为强制**。
+
+<Trigger Conditions>
+
+满足以下任一模式时，Agent **必须**进入本 Skill 的标准流程（标准化 → 读索引 → 本地或 MCP → 写回 → **upsert/ensure 后 validate**），并在用户可见回复**首段**输出规则所要求的缓存状态 Blockquote：
+
+| 类型 | 用户原话 / 消息特征（示例模式，非穷举） |
+| --- | --- |
+| URL | 含 `https://www.figma.com/`、`http://figma.com/`、`figma.com/file/`、`figma.com/design/`、`figma.com/proto/`、`figma.com/embed` 等 |
+| 参数 | 含 `node-id=`、`type=design` 等与 Figma 链接常见的查询串 |
+| 键值 | 出现 `figma` 文件 key（约 22 字符）且同时出现 `node-id` /「节点」描述，意图为对齐某一节点 |
+| 缓存词 | 「figma 缓存」「本地缓存」「先查缓存」「figma-cache」「index.json」「spec.md」「state-map」「命中/未命中」等且与具体设计任务绑定 |
+| 落地词 | 「按 Figma 做」「还原设计稿」「对齐 Figma」「实现该节点」且上下文可解析出链接或 fileKey/node |
+| 刷新词 | 「跳过缓存」「强制刷新」「以 Figma 最新为准」——走 MCP 与回写，状态标「更新」、来源 MCP |
+
+未出现可解析链接/键/节点且纯概念讨论时，可不执行缓存流水线。
+
+</Trigger Conditions>
+
+## 适用场景
+- 用户提供新的 Figma 链接并要求解析设计信息。
+- 用户再次提供同一 Figma 文件或同一 node-id，期望复用历史结果。
+- 用户明确要求「先查本地，不够再调 MCP」。
+
+## 目录约定
+- 缓存根目录（默认）：`figma-cache/`
+- 索引文件（默认）：`figma-cache/index.json`
+- 单链接缓存目录：`figma-cache/files/<fileKey>/nodes/<nodeId>/`
+- 单链接缓存文件：
+  - `meta.json`：基础元数据与来源信息
+  - `spec.md`：可读规格摘要
+  - `state-map.md`：状态与交互映射（如适用）
+  - `raw.json`：必要的原始结构化数据摘录
+- 可配置项：
+  - `FIGMA_CACHE_DIR`：缓存根目录
+  - `FIGMA_CACHE_INDEX_FILE`：索引文件名或绝对路径
+  - `FIGMA_ITERATIONS_DIR`：历史回填目录
+  - `FIGMA_CACHE_STALE_DAYS`：陈旧阈值（天）
+  - `FIGMA_DEFAULT_FLOW`：默认 flowId（大迭代可减少重复 `--flow`）
+
+## 流程关系（Flow）
+- `figma-cache/index.json` 中的 `flows` 用于维护业务/交互流程的节点集合与边关系。
+- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
+
+## 标准流程
+1. 按 `figma-cache/link-normalization-spec.md` 标准化链接并生成键：
+   - 节点级：`cacheKey = <fileKey>#<nodeId>`
+   - 文件级（无 `node-id`）：`cacheKey = <fileKey>#__FILE__`
+2. 读取 `index.json`：
+   - 若命中且字段满足当前任务，直接读取本地缓存并继续实现。
+   - 若未命中或信息不足，再调用 Figma MCP 拉取缺失数据。
+3. 发生 MCP 拉取或本地补齐时，写入/更新 `meta.json`、`spec.md`、必要补充文件，并更新索引。
+4. **闭环校验（强制）**：凡本轮执行了 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`**（任意参数组合），在命令成功结束后，Agent **必须**在同一仓库根目录**自动、静默**执行 `npm run figma:cache:validate`。
+5. **校验失败**：根据脚本输出修复索引、`paths`、缺失文件、JSON 结构等，**循环执行 validate 直至退出码为 0**；不得在 validate 未通过时结束本轮「写缓存」任务。
+6. 对用户反馈时除 Blockquote 外可补充：`source: local-cache` / `source: figma-mcp` 与简要文件列表（不必粘贴完整终端日志）。
+
+## Agent 最终输出格式（强制）
+- 触发 `<Trigger Conditions>` 且本轮触碰缓存读写的回复，**第一段**必须为单行 Blockquote：
+  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
+- `nodeId` 与索引一致；文件级写 `__FILE__` 或与 `index.json` 相同的占位。
+- Blockquote 之后接任务正文。
+
+## 执行责任
+- 默认由 agent 执行缓存查询、写入、**upsert/ensure 后的 validate**、失败自修复与回填，用户不需要手动执行命令。
+- 仅当用户明确要求「我自己执行」或「请给我命令」时，才提供命令让用户手动运行。
+- 在常规对话中，以「已自动完成」方式汇报，不要求用户额外操作。
+
+## 索引建议结构
+```json
+{
+  "schemaVersion": 2,
+  "version": 1,
+  "updatedAt": "2026-04-14T12:00:00Z",
+  "flows": {
+    "example-flow": {
+      "id": "example-flow",
+      "title": "Example",
+      "nodes": ["xxxx#12:34"],
+      "edges": [
+        {
+          "id": "edge-1",
+          "from": "xxxx#12:34",
+          "to": "xxxx#56:78",
+          "type": "next_step",
+          "note": "",
+          "createdAt": "2026-04-14T12:00:00Z"
+        }
+      ],
+      "assumptions": [],
+      "openQuestions": []
+    }
+  },
+  "items": {
+    "fileKey#nodeId": {
+      "fileKey": "xxxx",
+      "nodeId": "12:34",
+      "scope": "node",
+      "url": "https://www.figma.com/file/xxxx?node-id=12%3A34",
+      "originalUrls": [
+        "https://www.figma.com/file/xxxx?node-id=12%3A34&t=abc",
+        "https://www.figma.com/design/xxxx?node-id=12:34"
+      ],
+      "normalizationVersion": 1,
+      "paths": {
+        "meta": "figma-cache/files/xxxx/nodes/12-34/meta.json",
+        "spec": "figma-cache/files/xxxx/nodes/12-34/spec.md",
+        "stateMap": "figma-cache/files/xxxx/nodes/12-34/state-map.md",
+        "raw": "figma-cache/files/xxxx/nodes/12-34/raw.json"
+      },
+      "syncedAt": "2026-04-14T12:00:00Z",
+      "completeness": ["layout", "text", "tokens", "interactions"]
+    }
+  }
+}
+```
+
+## 刷新策略
+- 用户说「强制刷新/以最新 Figma 为准」：直接走 MCP，并覆盖 `syncedAt` 与内容；Blockquote 标「更新」、来源 MCP。
+- 仅缺某些字段：执行部分刷新，保留已有内容，更新 `completeness`。
+- 若链接无 `node-id`，先缓存到文件级（`__FILE__`），再按后续 node 增量补充。
+- 当 `syncedAt` 超过 14 天时，默认先提示用户是否刷新。
+
+## 输出约束
+- **必须先**输出规定的缓存状态 Blockquote，再给出设计结论或实现说明。
+- 若跳过 MCP，Blockquote 中来源为 Local，状态多为「命中」。
+- 若调用 MCP，Blockquote 中来源为 MCP，状态多为「缺失→更新」或「更新」，并在后文简述触发原因（未命中/信息不足/用户强刷）。
+
+## 推荐命令
+- `npm run figma:cache:init`：初始化空索引（用于纯净移植）
+- `npm run figma:cache:config`：查看当前生效配置
+- `npm run figma:cache:get -- "<figma-url>"`：检查命中情况
+- `npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens`
+- `npm run figma:cache:ensure -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens`：自动补齐缓存骨架文件
+- `npm run figma:cache:validate`：**每次 upsert/ensure 成功后必须自动执行**；失败则修至通过
+- `npm run figma:cache:stale`：检查超 14 天的陈旧缓存
+- `npm run figma:cache:backfill`：从历史迭代文档回填索引
+- `npm run figma:cache:flow:init|add-node|link|chain|show|mermaid`：维护流程关系

package/figma-cache/figma-cache.js

@@ -44,7 +44,21 @@ const DEFAULT_STALE_DAYS = parsePositiveInt(
 );
 
 const CACHE_DIR = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
+/** 与 `figma-cache/figma-cache.js` 同级的 `cursor-bootstrap/`（随 npm 包分发） */
+const CURSOR_BOOTSTRAP_DIR = path.join(__dirname, "..", "cursor-bootstrap");
 const ITERATIONS_DIR = resolveMaybeAbsolutePath(ITERATIONS_DIR_INPUT);
+
+/** 当前安装包在 package.json 中的 name（用于写入 AGENT-SETUP-PROMPT.md） */
+function readSelfNpmPackageName() {
+  try {
+    const pkgPath = path.join(__dirname, "..", "package.json");
+    const raw = fs.readFileSync(pkgPath, "utf8");
+    const j = JSON.parse(raw);
+    return j && j.name ? String(j.name) : "figma-cache-toolchain";
+  } catch {
+    return "figma-cache-toolchain";
+  }
+}
 const INDEX_PATH = path.isAbsolute(INDEX_FILE_NAME)
   ? INDEX_FILE_NAME
   : path.join(CACHE_DIR, INDEX_FILE_NAME);
@@ -427,6 +441,83 @@ function validateIndex(index) {
   return errors;
 }
 
+/** @param {boolean} force 为 true 时覆盖已存在文件 */
+function copyCursorBootstrap(force) {
+  const pairs = [
+    { 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", "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: "figma-cache.config.example.js", to: "figma-cache.config.example.js" },
+  ];
+  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) && !force) {
+      skipped += 1;
+      return;
+    }
+    fs.copyFileSync(absFrom, absTo);
+    copied += 1;
+  });
+
+  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");
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        root: normalizeSlash(ROOT),
+        copied,
+        skipped,
+        force: !!force,
+        hint: skipped
+          ? "Some template files were skipped (already exist). Re-run with --force to overwrite."
+          : "Done.",
+        agentPromptFile: normalizeSlash(agentDest),
+        agentPromptNote:
+          "AGENT-SETUP-PROMPT.md is refreshed every run; open it in Cursor and @-mention or paste to Agent.",
+        npmPackageName: npmPkg,
+      },
+      null,
+      2
+    )
+  );
+  console.log(
+    "\n" +
+      "================================================================\n" +
+      "下一步：在 Cursor 中打开本仓库根目录的「AGENT-SETUP-PROMPT.md」\n" +
+      "  方式 A：在对话里输入 @AGENT-SETUP-PROMPT.md 并说「按该文档执行」\n" +
+      "  方式 B：打开该文件，全选复制后粘贴到 Agent\n" +
+      "================================================================\n"
+  );
+}
+
 function collectMarkdownFiles(dir) {
   if (!fs.existsSync(dir)) {
     return [];
@@ -584,9 +675,23 @@ function run() {
     );
     console.log(`  ${ex} flow show --flow=<flowId>`);
     console.log(`  ${ex} flow mermaid --flow=<flowId>`);
+    console.log(
+      `${ex} cursor init [--force]  # copy .cursor templates + figma-cache.config.example.js + refresh AGENT-SETUP-PROMPT.md`
+    );
     process.exit(1);
   }
 
+  if (cmd === "cursor") {
+    const sub = args[0];
+    if (sub !== "init") {
+      console.error("Usage: figma-cache cursor init [--force]");
+      process.exit(1);
+    }
+    const force = args.includes("--force");
+    copyCursorBootstrap(force);
+    return;
+  }
+
   if (cmd === "normalize") {
     const url = args[0];
     const normalized = normalizeFigmaUrl(url);

package/figma-cache/migration-guide.md

@@ -4,11 +4,20 @@
 
 - `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 仍可用
+- **`figma-cache.config.js`（项目根）**：`postEnsure` 等钩子；无则钩子不执行，Core 仍可用。安装 npm 包并执行 `cursor init` 后，根目录会有 **`figma-cache.config.example.js`** 与 **`AGENT-SETUP-PROMPT.md`**；请用 Cursor Agent **按后者全文执行** 以生成/合并正式配置（见下文「npm 推荐流程」）。
 - `.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/02-figma-stack-adapter.mdc`（**栈占位**，不绑定具体框架；用 Agent 生成 `02-figma-<你的栈>-adapter.mdc` 后可删占位）
 - `.cursor/rules/figma-local-cache-first.mdc`（入口说明，可选）
 - `.cursor/skills/figma-mcp-local-cache/SKILL.md`
+- （**可选参考**，不随 `cursor init` 复制）安装 npm 包后路径为：`node_modules/figma-cache-toolchain/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`（Vue2+Vuetify2 全文示例，需时由 Agent 读入并改写为你的 `.cursor/rules/02-figma-...`）
+
+### npm 推荐流程（最少人工）
+
+1. `npm i -D figma-cache-toolchain`
+2. 在业务项目根：`npx figma-cache cursor init`（或已配置 script：`npm run figma:cache:cursor:init`）
+3. 在 Cursor 中打开项目根的 **`AGENT-SETUP-PROMPT.md`**（**每次** `cursor init` 都会从包内模板刷新该文件），用 **`@AGENT-SETUP-PROMPT.md`** 或整篇粘贴，让 Agent **按文档顺序执行**（生成 `figma-cache.config.js`、栈专属 Adapter、**删除** `02-figma-stack-adapter.mdc`、补全 `figma:cache:*` scripts 等）。
+
+说明：Cursor **不会**在 `npm install` 时自动写入 `.cursor/`；`cursor init` 负责复制模板；**栈适配**由 Agent 执行 `AGENT-SETUP-PROMPT.md` 完成。若模板文件已存在，`cursor init` 默认**跳过**（加 `--force` 可覆盖）；**`AGENT-SETUP-PROMPT.md` 不受跳过逻辑影响，每次 init 均刷新**，以便包升级后用户重新 `@` 同一文件即拿到最新指令。
 
 ## package.json scripts
 
@@ -30,7 +39,8 @@
   "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"
+  "figma:cache:flow:mermaid": "node figma-cache/figma-cache.js flow mermaid",
+  "figma:cache:cursor:init": "node figma-cache/figma-cache.js cursor init"
 }
 ```
 
@@ -51,22 +61,11 @@
 - `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` 里生成的节点侧文件名与模板文案。
+## 用 Agent 生成「栈专属」Adapter 与 postEnsure
 
-```text
-请为本仓库生成 Cursor 规则文件：`.cursor/rules/02-figma-{框架}-adapter.mdc`（alwaysApply: false）。
+**推荐（最少步骤）**：`npx figma-cache cursor init` 后，在 Cursor 中 **`@AGENT-SETUP-PROMPT.md`** 或粘贴其全文，由 Agent 按文档一次性完成（含删除占位 `02-figma-stack-adapter.mdc`）。
 
-约束：
-- 本仓库 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 只维护通用缓存；Adapter 只约束「读缓存后如何写业务 UI」；禁止在 `meta.json` / `raw.json` / `spec.md` 写框架专有实现。**01-figma-cache-core.mdc** 一般无需改。
 
 ## 将 Core 抽成独立 npm 包（维护方式概要）
 
@@ -77,3 +76,7 @@
 5. **本仓库过渡**：可先 `npm link` 本地包验证，再发布；发布后将本仓库 `figma-cache/` 中「脚本与 spec」替换为依赖包，目录名可保留 `figma-cache/` 仅放数据与 index（或整目录改名为 `.cache/figma` 由 env 指定）。
 
 更细的发布 checklist 可在发包前补：LICENSE、仓库 URL、`npm publish --dry-run`、`.npmignore`。
+
+## 包维护者备忘（仅维护 npm 包源码时）
+
+若你同时维护 `figma-cache-toolchain` 包本身：修改 `cursor-bootstrap/`（含 `AGENT-SETUP-PROMPT.md`）或 CLI 后，记得 bump 版本并发布 npm，以便消费方 `cursor init` 刷新到最新 Agent 指令。

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "1.0.0",
+  "version": "1.3.1",
   "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
+  "homepage": "https://www.npmjs.com/package/figma-cache-toolchain",
   "keywords": [
     "figma",
     "cache",
@@ -19,10 +20,15 @@
   "files": [
     "LICENSE",
     "bin",
+    "cursor-bootstrap",
     "figma-cache/figma-cache.js",
     "figma-cache/*.md"
   ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
+    "test": "node tests/smoke.js",
     "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",
@@ -38,7 +44,8 @@
     "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"
+    "figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid",
+    "figma:cache:cursor:init": "node bin/figma-cache.js cursor init"
   },
   "volta": {
     "node": "16.20.2"