figma-cache-toolchain 1.4.2 → 1.4.4

package/LICENSE

@@ -1,21 +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.
+MIT License
+
+Copyright (c) 2026 李民章
+
+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

@@ -1,98 +1,142 @@
-# figma-cache-toolchain
-
-闈㈠悜**涓氬姟椤圭洰**鐨?Figma 鏈湴缂撳瓨锛氶摼鎺ユ爣鍑嗗寲銆侀」鐩唴 **`figma-cache/`** 绱㈠紩涓庢牎楠屻€侀浂渚濊禆 Node CLI銆?*涓嶇粦瀹?*鍏蜂綋 UI 妗嗘灦锛涙爤鐩稿叧鐢?Cursor Agent 鎸?**`@AGENT-SETUP-PROMPT.md`** 鐢熸垚 **`figma-cache.config.js`** 涓?**`.cursor/rules/02-figma-<鏍?-adapter.mdc`**銆?
-
-## 鍥㈤槦璇存槑涓庢彁绀鸿瘝锛堢粰鍚屼簨锛?
-
-**`figma-cache/colleague-guide-zh.md`**锛氫娇鐢ㄥ満鏅€佸崟鏉?澶氭潯閾炬帴銆佹笎杩涘紡鍏宠仈鐨?**Cursor 鎻愮ず璇嶆ā鏉?*銆佸崌绾ц鏄庣瓑銆?
-
-姣忔墽琛屼竴娆?**`npx figma-cache cursor init`**锛屼細鎶婂寘鍐呮渶鏂扮増**鍚屾鍐欏叆**椤圭洰涓嬬殑 **`figma-cache/colleague-guide-zh.md`**锛堢洰褰曠敱 **`FIGMA_CACHE_DIR`** 鍐冲畾锛岄粯璁?`figma-cache/`锛夛紝**鏃犻渶**浠?`node_modules` 鎵嬫妱锛涗笌鍚屼簨鐩存帴鐪嬩粨搴撻噷璇ユ枃浠跺嵆鍙€?
-
----
-
-## 鍥涙鎺ュ叆锛堝潎鍦ㄤ笟鍔￠」鐩牴鐩綍锛?
-
-### 1. 瀹夎
-
-```bash
-npm i -D figma-cache-toolchain
-```
-
-### 2. 鍒濆鍖?Cursor 涓庝换鍔′功锛堝苟鍚屾鍥㈤槦璇存槑锛?
-
-```bash
-npx figma-cache cursor init
-```
-
-- 鍐欏叆鎴栬烦杩囷紙宸插瓨鍦ㄤ笖鏈?`--force`锛夛細`.cursor/rules/`銆乣.cursor/skills/`銆乣figma-cache.config.example.js`銆?
-- **姣忔**鍒锋柊锛?*`AGENT-SETUP-PROMPT.md`**锛堥」鐩牴锛夈€?*`figma-cache/colleague-guide-zh.md`**锛堢紦瀛樼洰褰曚笅锛夈€?
-- 缁堢浼氭彁绀猴細鍏?**`@AGENT-SETUP-PROMPT.md`** 浜ょ粰 Agent锛?*Agent 瀹屾垚鍚庡啀**鍋氱 4 姝ャ€?
-
-### 3. 浜ょ粰 Cursor Agent
-
-鍦ㄥ璇濅腑 **`@AGENT-SETUP-PROMPT.md`**锛岃鏄庛€屾寜璇ユ枃妗ｆ墽琛屻€嶃€侫gent 浼氭帹鏂爤銆佺敓鎴?鍚堝苟閰嶇疆涓?Adapter銆佽ˉ鍏?**`figma:cache:*`** scripts 绛夈€?
-
-### 4. 鍒濆鍖栨湰鍦扮储寮曪紙涓?`cursor init` 涓嶅悓锛?
-
-鍒涘缓 **`figma-cache/index.json`**锛堢┖绱㈠紩锛夌瓑锛屼緵鍚庣画 `ensure` / `get` 鍐欏叆鑺傜偣锛?
-
-```bash
-npm run figma:cache:init
-```
-
-鑻ユ棤瀵瑰簲 script锛歚npx figma-cache init`銆傜劧鍚庡彲鎸夐渶 **`npm run figma:cache:validate`**銆?
-
-**璇存槑**锛氬彂甯冪殑 npm 鍖?*涓嶅惈**浣犱笟鍔′粨搴撻噷鐨?**`figma-cache/files/`** 涓?**`index.json`**锛涙暟鎹敱涓婅堪 init 涓庡悗缁懡浠ゅ湪鏈湴鐢熸垚銆?
-
----
-
-## 鍗囩骇 npm 鍖呭悗鎺ㄨ崘娴佺▼锛堜笟鍔￠」鐩級
-
-宸插湪鐢ㄦ湰鍖呮椂锛?*姣忓崌涓€娆＄増鏈?*寤鸿鍦ㄤ笟鍔′粨搴撴牴鎸変笅闈㈠仛涓€閬嶏紝閬垮厤妯℃澘涓庨厤缃暱鏈熻惤鍚庛€?
-
-### 1. 鍗囩骇渚濊禆
-
-```bash
-npm i -D figma-cache-toolchain@latest
-```
-
-锛堟垨閿佸畾鍏蜂綋鐗堟湰鍙枫€傦級
-
-### 2. 鍒锋柊 Cursor 妯℃澘涓庤鏄庢枃浠?
-
-```bash
-npx figma-cache cursor init
-```
-
-- 浼氬埛鏂伴」鐩牴 **`AGENT-SETUP-PROMPT.md`**銆?*`FIGMA_CACHE_DIR/colleague-guide-zh.md`**锛屽苟鏇存柊锛堟垨璺宠繃锛?*`.cursor/`** 涓庢牴鐩綍 **`figma-cache.config.example.js`**銆? 
-- 鑻ラ渶**寮哄埗瑕嗙洊**宸插瓨鍦ㄧ殑 `.cursor` 妯℃澘锛屼娇鐢?**`npx figma-cache cursor init --force`**锛堜細瑕嗙洊宸叉湁瑙勫垯鏂囦欢锛屾厧鐢級銆?
-
-### 3. 瀵归綈 `figma-cache.config.js`锛堝悆杩涙柊鑳藉姏锛?
-
-- **鑻ユ寮忛厤缃槸 `require` 鍖呭唴绀轰緥**锛氫竴鑸?*涓嶅繀鏀规枃浠?*锛屽崌绾у悗閲嶆柊 `require` 鍗冲姞杞芥柊閫昏緫銆? 
-- **鑻ユ寮忛厤缃槸褰撳垵澶嶅埗/鑷啓鐨?*锛氭牴鐩綍鐨?**`figma-cache.config.example.js`** 宸叉槸**鏈€鏂板鐓?*锛岃**鍚堝苟**杩?**`figma-cache.config.js`**锛堜緥濡?1.4+ 鐨?**`docs/figma-flow-readme.md`**銆乣postEnsure` 鐨?**`ctx`** 鎵╁睍绛夛級锛?*鍕挎暣鏂囦欢瑕嗙洊**瀵艰嚧涓㈠け鑷畾涔夐挬瀛愩€? 
-- 鍙湪 Cursor 閲?**`@figma-cache.config.example.js`** + **`@figma-cache.config.js`** + **`@AGENT-SETUP-PROMPT.md`**锛岃 Agent銆屾寜浠诲姟涔︽鏌ヨˉ缂?+ 鍚堝苟绀轰緥鏂板閮ㄥ垎銆嶏紱澶ф壒閲忛摼鎺ヤ笌涓氬姟娴佺▼鏂囨。鍐欐硶瑙?**`figma-cache/colleague-guide-zh.md` 搂5.9锝灺?.10**銆?
-
-### 4. 绱㈠紩涓庢牎楠?
-
-- **宸叉湁** **`figma-cache/index.json`**锛氶€氬父**涓嶅繀**鍐嶈窇 **`figma:cache:init`**銆? 
-- 鎵ц **`npm run figma:cache:validate`**锛堟垨 **`npx figma-cache validate`**锛夈€? 
-- 闃呰 **`CHANGELOG.md`**锛坣pm 鍖呭唴鎴?GitHub锛変簡瑙ｇ牬鍧忔€у彉鏇达紙鑻ユ湁锛夈€?
-
-### 5. 鎻愪氦涓庡崗浣?
-
-灏嗘湰娆″崌绾ф秹鍙婄殑 **`package.json` / lock**銆佽嫢鍚堝苟杩囧垯 **`figma-cache.config.js`**銆佷互鍙婂埛鏂板悗鐨?**`AGENT-SETUP-PROMPT.md` / `.cursor/` / `figma-cache/colleague-guide-zh.md`** 绛夋寜鍥㈤槦瑙勮寖鎻愪氦锛?*`figma-cache/files/`** 鏄惁鍏ュ簱浠嶆寜鍘熷洟闃熺害瀹氥€?
-
----
-
-## 鏇村畬鏁寸殑璇存槑鍦ㄥ摢
-
-| 闇€姹?| 鏂囨。锛堥殢鍖呭湪 `node_modules/figma-cache-toolchain/figma-cache/`锛?|
-|------|------------------------------------------------------------------|
-| scripts 鍏ㄩ噺 JSON銆佺幆澧冨彉閲忋€佹棤 npm 澶嶅埗鎺ュ叆銆佸洖濉€佺淮鎶ゅ彂鐗?| 鍖呭唴 **`figma-cache/README.md`** |
-| 閾炬帴閿鍒?| **`link-normalization-spec.md`** |
-| Flow 杈圭被鍨?| **`flow-edge-taxonomy.md`** |
-
-npm 鍖呴椤靛嵆鏈枃浠讹紱**缁存姢鑰呭彂鐗堟祦绋?*鍐欏湪 **`figma-cache/README.md`** 鏂囨湯銆屽寘缁存姢鑰呫€嶄笌浠撳簱 **`CHANGELOG.md`**銆?
-
-甯哥敤鐜鍙橀噺鑺傞€夛細`FIGMA_CACHE_DIR`銆乣FIGMA_CACHE_INDEX_FILE`銆乣FIGMA_ITERATIONS_DIR`銆乣FIGMA_CACHE_STALE_DAYS`銆乣FIGMA_DEFAULT_FLOW`銆乣FIGMA_CACHE_PROJECT_CONFIG`銆乣FIGMA_CACHE_FLOW_README`锛堢ず渚嬮挬瀛愬啓銆屾祦绋嬫€昏銆峬d 鐨勮矾寰勶級鈥?閲婁箟涓庡畬鏁磋〃瑙?**`figma-cache/README.md`**銆?
+# figma-cache-toolchain
+
+面向业务项目的 Figma 本地缓存工具链：提供链接标准化、索引管理、缓存读写、校验与流程维护能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
+
+- npm 包：`figma-cache-toolchain`
+- Git 仓库：<https://github.com/907086379/figma-cache-toolchain.git>
+
+---
+
+## 这份 README 面向谁
+
+- npm 用户：把工具链接入业务项目并日常使用
+- git 用户：在仓库内开发、测试、提交改动
+
+> npm 发布由仓库维护者负责；普通用户和贡献者无需执行 `npm publish`。
+
+---
+
+## npm 用户快速开始
+
+### 1) 安装
+
+```bash
+npm i -D figma-cache-toolchain
+```
+
+### 2) 初始化 Cursor 模板与任务书
+
+```bash
+npx figma-cache cursor init
+```
+
+该命令会：
+
+- 写入或跳过（已存在且未使用 `--force`）`.cursor/rules/`、`.cursor/skills/`
+- 确保根目录存在 `figma-cache.config.js`
+- 刷新根目录 `AGENT-SETUP-PROMPT.md`
+- 同步刷新 `figma-cache/docs/colleague-guide-zh.md`
+
+### 3) 初始化本地缓存索引
+
+```bash
+npm run figma:cache:init
+```
+
+若项目还没配置 scripts，可临时使用：
+
+```bash
+npx figma-cache init
+```
+
+### 4) 执行校验
+
+```bash
+npm run figma:cache:validate
+```
+
+---
+
+## 默认 completeness 与 token 开销
+
+默认 completeness：`layout,text,tokens,interactions,states,accessibility`（默认不含 `flow/assets`）。
+
+- `flow` 默认关闭，避免常规场景冗余
+- 自动追加 `flow` 仅命中白名单时触发：
+  - 关系关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
+  - 同轮或断续出现多个 Figma 链接，且明确存在先后/串联意图（如 A->B）
+- 以下场景不自动追加 `flow`：单链接且无关系意图、仅视觉微调/文案修改、仅资产导出
+- `assets` 仍按需开启，避免资产留档体积膨胀
+- token 开销通常在启用 `flow` 且节点复杂时上升更明显
+- 触发自动补 `flow` 时，建议在执行日志/回复中记录触发原因（关键词命中或多链接串联意图），便于审计
+
+按需覆盖示例：
+
+```bash
+# 常规场景
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
+
+# 关联节点/同轮或断续多链接串联场景（自动或显式）
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow
+
+# 同时需要资产留档
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow,assets
+```
+
+---
+
+## 常用命令
+
+```bash
+npm run figma:cache:init
+npm run figma:cache:config
+npm run figma:cache:get -- "<figma-url>"
+npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility
+npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
+npm run figma:cache:validate
+npm run figma:cache:budget
+npm run figma:cache:stale
+npm run figma:cache:backfill
+```
+
+严格证据模式（默认开启）：
+
+- 当 `source=figma-mcp` 时，`upsert/ensure` 会先校验 `mcp-raw` 证据映射
+- 仅在你明确需要先落索引骨架时，才使用 `--allow-skeleton-with-figma-mcp`
+- `validate` 会校验 `coverageSummary.evidence`，缺失或 TODO 占位会失败
+
+---
+
+## git 用户（仓库开发）
+
+### 1) 克隆并安装依赖
+
+```bash
+git clone https://github.com/907086379/figma-cache-toolchain.git
+cd figma-cache-toolchain
+npm ci
+```
+
+### 2) 本地自检
+
+```bash
+npm run docs:encoding:check
+npm test
+```
+
+### 3) 提交前建议
+
+- 确认 `README.md`、`figma-cache/docs/*.md` 编码为 UTF-8 无 BOM
+- 变更 CLI 行为后，同步更新文档与示例命令
+- 只提交与本次任务相关文件
+
+---
+
+## 文档入口
+
+- `figma-cache/docs/README.md`：完整脚本、环境变量、回填与维护说明
+- `figma-cache/docs/colleague-guide-zh.md`：团队协作指南与提示词模板
+- `figma-cache/docs/link-normalization-spec.md`：链接标准化规范
+- `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
+- `AGENT-SETUP-PROMPT.md`：项目接入任务书（`cursor init` 会刷新）
+- `docs/mobile-native-adapter-template.md`：iOS/Android 双端适配模板与最小转换脚本说明

package/README.owner.md

@@ -0,0 +1,37 @@
+# README.owner.md（仅本地，发布者自用）
+
+这份文档仅供仓库维护者本地查看，不提交仓库。
+
+## 目的
+
+- 固化发版前检查动作，减少漏项。
+- 统一版本升级、打包验证、发布与回滚口径。
+
+## 发版前检查
+
+```bash
+npm run docs:encoding:check
+npm test
+npm run figma:cache:validate
+npm pack --dry-run
+```
+
+## 建议发版流程（维护者）
+
+1. 更新代码与文档，确认工作区干净。
+2. 更新 `CHANGELOG.md`（把 Unreleased 归并到新版本）。
+3. 升级版本：`npm version patch|minor|major`（或手动同步 `package.json` 与 `package-lock.json`）。
+4. 本地再次执行：`npm test && npm pack --dry-run`。
+5. 推送提交与 tag：`git push` + `git push --tags`。
+6. 发布：`npm publish`。
+7. 发布后记录“版本号 -> 关键变更 -> 回滚方式”。
+
+## 回滚预案（示例）
+
+- npm：必要时执行 `npm deprecate` 标注问题版本。
+- git：基于 tag 快速定位并 hotfix。
+
+## 备注
+
+- 对外 README 仅保留 npm/git 用户需要的信息。
+- 这份文件由 `.gitignore` 忽略。

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

@@ -1,63 +1,54 @@
-# 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`：adapter hint + 可选 `docs/figma-flow-readme.md`）
-
-## 你必须完成的任务（按顺序执行，尽量少问用户）
-
-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` 或包内 **`figma-cache/README.md`** 中 scripts 示例一致即可）。
-
-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** 驱动。  
-      - **可选**：若项目已通过 `cursor init` 同步 `figma-cache/colleague-guide-zh.md`，提示团队默认只使用 **§5.1「最推荐主提示词」**，只有特殊诉求再追加 **§5.2** 的一句附加要求。
-   - 若用户希望你直接给可复制文本，可贴这段（与 `colleague-guide-zh.md` §5.1 保持一致）：
-
-     ```text
-     请按项目 figma 缓存规则处理下面这条 Figma 链接，并遵循“缓存优先 + 按需 MCP + 最小调用集”：
-     1) 先查本地 figma-cache，命中则直接复用，不做刷新；
-     2) 仅在未命中或我明确要求刷新时，才调用 figma-mcp 拉取并写入 mcp-raw（随后再 ensure/upsert）；
-     3) completeness 默认使用 layout,text,tokens（若我补充再扩展 interactions/flow/states/assets/accessibility）；
-     4) 原始 MCP 数据统一保存到节点目录 mcp-raw/ 子目录；
-     5) 默认不保存 whoami 原始文件（仅鉴权排障或我明确要求时保存）；
-     6) 完成后执行 figma:cache:validate，并汇报：缓存状态、实际 MCP 调用次数、输出文件清单。
-
-     [Figma 链接]
-     ```
-
-## 硬约束（违反则视为未完成）
-
-- **不要**修改 `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 规则内容。
-
----
-
+# 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.js`（示例 `postEnsure`：目录级 adapter hint + 可选 `docs/figma-flow-readme.md`）
+> - （兼容旧项目）`figma-cache.config.example.js` 可能存在；仅当内容被用户自定义且无法安全迁移时保留
+
+## 你必须完成的任务（按顺序执行，尽量少问用户）
+
+1. **读取工程事实**  
+   阅读 `package.json` 及存在的构建配置（如 `vite.config.*`、`vue.config.js`、`next.config.*`、`tsconfig.json` 等），**自行推断** UI 技术栈（框架、组件库、样式方案、状态管理若有则记录）。仅在关键信息完全无法从仓库推断时，再向用户提一个极简问题。
+
+2. **检查并合并 `figma-cache.config.js`**  
+   - 若根目录**不存在** `figma-cache.config.js`：基于当前文件创建完整配置，并实现与栈匹配的 `hooks.postEnsure`。  
+   - 若**已存在** `figma-cache.config.js`：**合并**而非盲目覆盖——保留用户已有非 figma-cache 字段，仅补充或调整 `hooks.postEnsure` 及与 figma-cache 相关的导出；冲突时以「不破坏用户现有逻辑」优先并注释说明。  
+   - 默认建议：`FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root`（目录级单文件，减少重复）；仅在团队明确需要节点文档时改为 `node`。
+
+3. **清理 legacy example（若安全）**  
+   若根目录存在 `figma-cache.config.example.js` 且其内容与 `figma-cache.config.js` 等价（或为未改动模板），请删除该 example 文件，避免后续协作混淆。
+
+4. **生成栈专属 Adapter 规则**  
+   新建 **`.cursor/rules/02-figma-<栈简名>-adapter.mdc`**（`alwaysApply: false`）。内容须与 **`01-figma-cache-core.mdc`** 边界一致：只约束「在通用缓存可读之后如何写业务 UI」；**禁止**要求在 `meta.json` / `raw.json` / `spec.md` 中写入框架专有实现。
+
+5. **删除占位规则**  
+   确认第 4 步文件已写入且无语法问题后，**删除** `.cursor/rules/02-figma-stack-adapter.mdc`。若用户在 Cursor 设置里固定引用了该文件名，请在汇报中提示用户改为引用新的 `02-figma-<栈>-adapter.mdc`。
+
+6. **补全 npm scripts（若缺失）**  
+   若 `package.json` 中没有任何 `figma:cache:*` 脚本，请追加一组，命令使用 **`npx figma-cache`** 或 **`figma-cache`**（与项目是否已安装本包、以及 `node_modules/.bin` 是否可用一致即可，优先 `npx figma-cache` 以减少环境差异）。至少包含：`init`、`config`、`validate`、`ensure`、`get`（名称与 `figma-cache --help` 或包内 **`figma-cache/docs/README.md`** 中 scripts 示例一致即可）。
+
+7. **收尾**  
+   - 用简短列表向用户汇报：新建/修改/删除了哪些路径。  
+   - 若项目根**尚无** `figma-cache/index.json`，提示用户执行：`npm run figma:cache:init`（若已加 script）或 `npx figma-cache init`（与 `cursor init` 不同，用于创建空索引与缓存目录）。  
+   - 提示用户在本项目根执行：`npm run figma:cache:validate`（若已加 script）或 `npx figma-cache validate`。  
+   - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。  
+      - **可选**：若项目已通过 `cursor init` 同步 `figma-cache/docs/colleague-guide-zh.md`，提示团队默认只使用 **§5.1「最推荐主提示词」**，只有特殊诉求再追加 **§5.2** 的一句附加要求。
+
+## 硬约束（违反则视为未完成）
+
+- **不要**修改 `node_modules/{{NPM_PACKAGE_NAME}}/` 下已发布包内文件（应无此必要）。  
+- **不要**修改 `figma-cache/figma-cache.js` 或破坏 Core「框架中立」语义。  
+- **不要**把业务路由名、具体组件库 API 写进 `figma-cache/files/**` 下的 `meta.json` / `raw.json` / `spec.md`。
+
+## 可选参考（仅在用户需要 Vue2+Vuetify2 时）
+
+包内附带参考文本（**不在 init 时复制到 .cursor**）：  
+`node_modules/{{NPM_PACKAGE_NAME}}/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`  
+若用户明确要求该栈，可读入后改写为第 4 步的 Adapter 规则内容。
+
+---
+
 **开始执行：**读完本文件后立刻按上述顺序操作仓库文件，直至全部完成。
-

package/cursor-bootstrap/examples/README.md

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