figma-cache-toolchain 1.4.3 → 1.4.5

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,154 +1,154 @@
-# figma-cache-toolchain
-
-面向业务项目的 Figma 本地缓存工具链：提供链接标准化、索引管理、缓存读写、校验与流程维护能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
-
-## 快速接入（4 步）
-
-以下步骤建议在业务项目根目录执行。
-
-### 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`
-
-### 3) 交给 Cursor Agent 执行一次项目接入
-
-在 Cursor 对话中引用 `@AGENT-SETUP-PROMPT.md`，并让 Agent 按文档执行。
-
-通常会完成：
-
-- 推断技术栈并生成/合并 Adapter 规则
-- 合并或生成 `figma-cache.config.js`
-- 补全 `figma:cache:*` 相关 scripts
-
-### 4) 初始化本地缓存索引
-
-```bash
-npm run figma:cache:init
-```
-
-若项目尚未配置 scripts，可临时使用：
-
-```bash
-npx figma-cache init
-```
-
-随后建议执行一次：
-
-```bash
-npm run figma:cache:validate
-```
-
-> `cursor init` 与 `figma-cache init` 是两件事：
-> - `cursor init` 负责模板与任务书
-> - `figma-cache init` 负责创建本地空索引
-
----
-
-## 日常使用方式
-
-日常通常只需把 Figma 链接发给 Agent，Agent 会按规则自动执行：
-
-1. 查询本地缓存是否命中
-2. 信息不足时调用 MCP 拉取最小必要数据
-3. 回写 `figma-cache/` 缓存文件
-4. 执行 `upsert/ensure` 后自动 `validate`
-
-你一般不需要手工跑命令，命令主要用于排障、迁移和验收。
-
----
-
-## 升级 npm 包后的推荐流程（业务项目）
-
-### 1) 升级依赖
-
-```bash
-npm i -D figma-cache-toolchain@latest
-```
-
-### 2) 刷新模板与说明文档
-
-```bash
-npx figma-cache cursor init
-```
-
-### 3) 对齐 `figma-cache.config.js`
-
-- 若你的正式配置是 `require` 包内示例：通常只需重新加载即可。
-- 若你的正式配置是历史复制版/自定义版：请与最新 `figma-cache.config.example.js` 做增量合并，避免整文件覆盖导致自定义钩子丢失。
-
-### 4) 校验
-
-```bash
-npm run figma:cache:validate
-```
-
-并结合 `CHANGELOG.md` 检查是否存在破坏性变更。
-
----
-
-## 常用文档入口
-
-- `figma-cache/README.md`：完整脚本、环境变量、回填与维护说明
-- `figma-cache/colleague-guide-zh.md`：团队协作指南与提示词模板
-- `figma-cache/link-normalization-spec.md`：Figma 链接标准化规范
-- `figma-cache/flow-edge-taxonomy.md`：流程边类型约定
-- `AGENT-SETUP-PROMPT.md`：项目接入任务书（由 `cursor init` 每次刷新）
-
----
-
-## 常用命令（参考）
-
-```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
-npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions
-npm run figma:cache:validate
-npm run figma:cache:budget
-npm run figma:cache:stale
-npm run figma:cache:backfill
-```
-
----
-
-## 防乱码约定（Windows / PowerShell）
-
-为避免中文文档出现乱码，请统一遵循：
-
-- 文本文件统一使用 UTF-8 编码（建议与仓库既有风格保持一致）
-- Node 写文件必须显式指定 `utf8`
-- PowerShell 写文件必须显式指定编码，例如：
-
-```powershell
-Set-Content -Path .\README.md -Value $text -Encoding utf8
-Out-File -FilePath .\README.md -InputObject $text -Encoding utf8
-```
-
-- 不要把终端里已经乱码的内容直接复制回文件再保存
-- 文档改动后，至少回读抽查 20 行，确认中文可读
-
----
-
-## 维护者说明
-
-维护本工具链源码时，请优先参考：
-
-- 根目录 `CHANGELOG.md`
-- `figma-cache/README.md` 的维护说明
-
-修改 `cursor-bootstrap/` 模板或 CLI 行为后，请按发布流程更新版本并发布，以便消费方通过 `cursor init` 获取最新模板。
+# figma-cache-toolchain
+
+面向业务项目的 Figma 本地缓存工具链：默认采用“本地缓存优先 + 按需 MCP + 最小调用集 + 严格证据校验 + validate 闭环”，提供链接标准化、索引与流程关系维护、缓存读写、校验与预算分析能力。该工具链聚焦“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
+```
+
+---
+
+## 团队协作建议（来自同事指南精简版）
+
+- 默认执行链：**先查缓存** -> 按需 MCP -> 原始回包写 `mcp-raw/` -> `upsert/ensure` -> `validate`
+- 当 `source=figma-mcp` 时，`mcp-raw` 证据不完整会被门禁拦截，不能只写骨架宣称成功
+- 默认 completeness：`layout,text,tokens,interactions,states,accessibility`
+- `flow` 仅在关系关键词命中或多链接明确串联意图时自动追加
+- 回报建议包含：缓存状态、来源（Local/MCP）、MCP 调用次数、输出文件清单
+- 团队可直接复用 `figma-cache/docs/colleague-guide-zh.md` 中的主提示词模板
+
+---
+
+## 默认 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/quick-start-zh.md`：一页式同事速查卡（3 分钟上手）
+- `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`。
+
+