figma-cache-toolchain 1.3.1 → 1.3.2

package/README.md

@@ -2,7 +2,7 @@
 
 通过 **npm** 分发的 Figma 本地缓存工具链：链接标准化、`figma-cache/` 索引与校验、零运行时依赖的 Node CLI。Core **不绑定**具体 UI 框架；表现层由 Agent 按你项目栈生成 **`figma-cache.config.js`** 与 **`.cursor/rules/02-figma-<栈>-adapter.mdc`**（见下方「三步走」）。
 
-## 消费方：三步完成适配（仅需 npm，无需克隆其它仓库）
+## 消费方：四步完成适配（仅需 npm，无需克隆其它仓库）
 
 以下路径均在**你的业务项目根目录**（已执行 `npm i -D figma-cache-toolchain` 或等价安装）。
 
@@ -22,15 +22,29 @@ npx figma-cache cursor init
 
 - 会写入 / 更新：`.cursor/rules/`、`.cursor/skills/`、`figma-cache.config.example.js` 等（已存在则默认跳过，除非加 `--force`）。
 - **每次**都会刷新项目根下的 **`AGENT-SETUP-PROMPT.md`**（由包内模板生成，含完整 Agent 指令）。
+- 终端会提示下一步：请 **`@AGENT-SETUP-PROMPT.md`** 交给 Agent；**Agent 完成后再**执行第 4 步。
 
-### 3. 交给 Cursor Agent（最少人工）
+### 3. 交给 Cursor Agent（推荐唯一方式）
 
-在 Cursor 中打开 **`AGENT-SETUP-PROMPT.md`**，任选其一：
+在 Cursor 对话中输入 **`@AGENT-SETUP-PROMPT.md`**，并说明「按该文档执行」即可（每次 `cursor init` 都会刷新该文件，一般**不必**再整篇复制粘贴）。
 
-- 在对话里 **`@AGENT-SETUP-PROMPT.md`** 并说「按该文档执行」；或  
-- 全选文件内容，粘贴到 Agent。
+Agent 将按文档自动：推断栈、生成/合并 **`figma-cache.config.js`**、生成栈专属 Adapter、**删除占位** `02-figma-stack-adapter.mdc`、按需补全 **`figma:cache:*` scripts** 等。
 
-Agent 将按文档自动：推断栈、生成/合并 **`figma-cache.config.js`**、生成栈专属 Adapter、**删除占位** `02-figma-stack-adapter.mdc`、按需补全 **`figma:cache:*` scripts** 等。完成后按文档提示跑一次 **`npx figma-cache validate`**（或已加的 npm script）。
+### 4. 初始化本地缓存索引（在 Agent 完成之后）
+
+与第 2 步的 **`cursor init` 不同**：本步创建业务仓库根下的 **`figma-cache/index.json`**（空索引）及缓存目录，供后续 `ensure` / `get` 写入节点。
+
+```bash
+npm run figma:cache:init
+```
+
+若 Agent 尚未补全 `figma:cache:*` scripts，请改用：
+
+```bash
+npx figma-cache init
+```
+
+然后可按需执行 **`npm run figma:cache:validate`**（或 `npx figma-cache validate`）。
 
 更细的约定见随包安装的 **`figma-cache/migration-guide.md`**（在 `node_modules/figma-cache-toolchain/figma-cache/` 内，无需单独仓库）。
 

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

@@ -27,6 +27,7 @@
 
 6. **收尾**  
    - 用简短列表向用户汇报：新建/修改/删除了哪些路径。  
+   - 若项目根**尚无** `figma-cache/index.json`，提示用户执行：`npm run figma:cache:init`（若已加 script）或 `npx figma-cache init`（与 `cursor init` 不同，用于创建空索引与缓存目录）。  
    - 提示用户在本项目根执行：`npm run figma:cache:validate`（若已加 script）或 `npx figma-cache validate`。  
    - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。
 

package/figma-cache/README.md

@@ -2,6 +2,17 @@
 
 该目录集中管理 Figma 缓存流程（脚本、索引、规范、样例缓存）。
 
+## 从 npm 包接入业务项目（顺序一览）
+
+若通过 **`figma-cache-toolchain`** 安装（而非整仓拷贝本目录），推荐顺序为：
+
+1. `npm i -D figma-cache-toolchain`
+2. `npx figma-cache cursor init`（写入 `.cursor/` 等，并刷新根目录 **`AGENT-SETUP-PROMPT.md`**）
+3. 在 Cursor 中 **`@AGENT-SETUP-PROMPT.md`** 并让 Agent 按文档执行（栈配置、Adapter、`figma:cache:*` scripts 等）
+4. **`npm run figma:cache:init`**（若尚无 script，用 **`npx figma-cache init`**）→ 生成 **`figma-cache/index.json`**
+
+说明：**`cursor init`** 与 **`figma-cache init`** 是两件事；后者才是本地缓存数据目录与空索引。仓库根 **`README.md`**（npm 包首页文档）中有与上述一致的「四步」说明。
+
 ## 使用方式（重要）
 
 - 日常只需要把 Figma 链接发给 agent。

package/figma-cache/figma-cache.js

@@ -501,7 +501,7 @@ function copyCursorBootstrap(force) {
           : "Done.",
         agentPromptFile: normalizeSlash(agentDest),
         agentPromptNote:
-          "AGENT-SETUP-PROMPT.md is refreshed every run; open it in Cursor and @-mention or paste to Agent.",
+          "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,
@@ -511,9 +511,12 @@ function copyCursorBootstrap(force) {
   console.log(
     "\n" +
       "================================================================\n" +
-      "下一步：在 Cursor 中打开本仓库根目录的「AGENT-SETUP-PROMPT.md」\n" +
-      "  方式 A：在对话里输入 @AGENT-SETUP-PROMPT.md 并说「按该文档执行」\n" +
-      "  方式 B：打开该文件，全选复制后粘贴到 Agent\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"
   );
 }

package/figma-cache/migration-guide.md

@@ -15,7 +15,8 @@
 
 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 等）。
+3. 在 Cursor 对话中 **`@AGENT-SETUP-PROMPT.md`**，并说明「按该文档执行」（**每次** `cursor init` 都会从包内模板刷新该文件；一般不必再整篇粘贴）。Agent **按文档顺序**完成：生成/合并 `figma-cache.config.js`、栈专属 Adapter、**删除** `02-figma-stack-adapter.mdc`、补全 `figma:cache:*` scripts 等。
+4. **Agent 完成后**，在项目根执行 **`npm run figma:cache:init`**（若尚无对应 script，用 **`npx figma-cache init`**），生成 **`figma-cache/index.json`**（空索引）及缓存目录；与第 2 步的 `cursor init` **不是**同一命令。
 
 说明：Cursor **不会**在 `npm install` 时自动写入 `.cursor/`；`cursor init` 负责复制模板；**栈适配**由 Agent 执行 `AGENT-SETUP-PROMPT.md` 完成。若模板文件已存在，`cursor init` 默认**跳过**（加 `--force` 可覆盖）；**`AGENT-SETUP-PROMPT.md` 不受跳过逻辑影响，每次 init 均刷新**，以便包升级后用户重新 `@` 同一文件即拿到最新指令。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
   "homepage": "https://www.npmjs.com/package/figma-cache-toolchain",
   "keywords": [