figma-cache-toolchain 1.3.2 → 1.4.1

package/README.md

@@ -1,10 +1,16 @@
 # figma-cache-toolchain
 
-通过 **npm** 分发的 Figma 本地缓存工具链：链接标准化、`figma-cache/` 索引与校验、零运行时依赖的 Node CLI。Core **不绑定**具体 UI 框架；表现层由 Agent 按你项目栈生成 **`figma-cache.config.js`** 与 **`.cursor/rules/02-figma-<栈>-adapter.mdc`**（见下方「三步走」）。
+面向**业务项目**的 Figma 本地缓存：链接标准化、项目内 **`figma-cache/`** 索引与校验、零依赖 Node CLI。**不绑定**具体 UI 框架；栈相关由 Cursor Agent 按 **`@AGENT-SETUP-PROMPT.md`** 生成 **`figma-cache.config.js`** 与 **`.cursor/rules/02-figma-<栈>-adapter.mdc`**。
 
-## 消费方：四步完成适配（仅需 npm，无需克隆其它仓库）
+## 团队说明与提示词（给同事）
 
-以下路径均在**你的业务项目根目录**（已执行 `npm i -D figma-cache-toolchain` 或等价安装）。
+**`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. 安装
 
@@ -12,81 +18,81 @@
 npm i -D figma-cache-toolchain
 ```
 
-### 2. 初始化 Cursor 模板与 Agent 任务书
-
-在项目根执行：
+### 2. 初始化 Cursor 与任务书（并同步团队说明）
 
 ```bash
 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（推荐唯一方式）
+- 写入或跳过（已存在且未 `--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 步。
 
-在 Cursor 对话中输入 **`@AGENT-SETUP-PROMPT.md`**，并说明「按该文档执行」即可（每次 `cursor init` 都会刷新该文件，一般**不必**再整篇复制粘贴）。
+### 3. 交给 Cursor Agent
 
-Agent 将按文档自动：推断栈、生成/合并 **`figma-cache.config.js`**、生成栈专属 Adapter、**删除占位** `02-figma-stack-adapter.mdc`、按需补全 **`figma:cache:*` scripts** 等。
+在对话中 **`@AGENT-SETUP-PROMPT.md`**，说明「按该文档执行」。Agent 会推断栈、生成/合并配置与 Adapter、补全 **`figma:cache:*`** scripts 等。
 
-### 4. 初始化本地缓存索引（在 Agent 完成之后）
+### 4. 初始化本地索引（与 `cursor init` 不同）
 
-与第 2 步的 **`cursor init` 不同**：本步创建业务仓库根下的 **`figma-cache/index.json`**（空索引）及缓存目录，供后续 `ensure` / `get` 写入节点。
+创建 **`figma-cache/index.json`**（空索引）等，供后续 `ensure` / `get` 写入节点：
 
 ```bash
 npm run figma:cache:init
 ```
 
-若 Agent 尚未补全 `figma:cache:*` scripts，请改用：
+若无对应 script：`npx figma-cache init`。然后可按需 **`npm run figma:cache:validate`**。
 
-```bash
-npx figma-cache init
-```
+**说明**：发布的 npm 包**不含**你业务仓库里的 **`figma-cache/files/`** 与 **`index.json`**；数据由上述 init 与后续命令在本地生成。
 
-然后可按需执行 **`npm run figma:cache:validate`**（或 `npx figma-cache validate`）。
+---
 
-更细的约定见随包安装的 **`figma-cache/migration-guide.md`**（在 `node_modules/figma-cache-toolchain/figma-cache/` 内，无需单独仓库）。
+## 升级 npm 包后推荐流程（业务项目）
 
----
+已在用本包时，**每升一次版本**建议在业务仓库根按下面做一遍，避免模板与配置长期落后。
+
+### 1. 升级依赖
 
-## 脚本（可选）
+```bash
+npm i -D figma-cache-toolchain@latest
+```
 
-在业务项目 `package.json` 的 `scripts` 中可使用 `npx figma-cache <子命令>`，避免依赖本机全局安装。常用子命令与示例见 **`figma-cache/migration-guide.md`** 中的 JSON 片段。
+（或锁定具体版本号。）
 
----
+### 2. 刷新 Cursor 模板与说明文件
 
-## 环境变量（节选）
+```bash
+npx figma-cache cursor init
+```
 
-| 变量 | 作用 |
-|------|------|
-| `FIGMA_CACHE_DIR` | 缓存根目录，默认 `figma-cache` |
-| `FIGMA_CACHE_INDEX_FILE` | 索引文件名或绝对路径 |
-| `FIGMA_ITERATIONS_DIR` | 仅 `backfill` 扫描的 Markdown 目录 |
-| `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
-| `FIGMA_DEFAULT_FLOW` | 默认 `flowId` |
-| `FIGMA_CACHE_PROJECT_CONFIG` | 覆盖项目配置文件路径 |
+- 会刷新项目根 **`AGENT-SETUP-PROMPT.md`**、**`FIGMA_CACHE_DIR/colleague-guide-zh.md`**，并更新（或跳过）**`.cursor/`** 与根目录 **`figma-cache.config.example.js`**。  
+- 若需**强制覆盖**已存在的 `.cursor` 模板，使用 **`npx figma-cache cursor init --force`**（会覆盖已有规则文件，慎用）。
 
-完整说明见 **`figma-cache/README.md`**（同在 npm 包内）。
+### 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～§5.10**。
+
+### 4. 索引与校验
+
+- **已有** **`figma-cache/index.json`**：通常**不必**再跑 **`figma:cache:init`**。  
+- 执行 **`npm run figma-cache:validate`**（或 **`npx figma-cache validate`**）。  
+- 阅读 **`CHANGELOG.md`**（npm 包内或 GitHub）了解破坏性变更（若有）。
 
-## 默认不把业务缓存打进 npm 包
+### 5. 提交与协作
 
-发布的 tarball 仅含 CLI、规范文档、`cursor-bootstrap` 等；**不包含**你项目里的 `figma-cache/files/` 与 `index.json`。数据目录由你在业务仓库内通过 **`figma-cache init`** 与后续 **`ensure`** 等生成。
+将本次升级涉及的 **`package.json` / lock**、若合并过则 **`figma-cache.config.js`**、以及刷新后的 **`AGENT-SETUP-PROMPT.md` / `.cursor/` / `figma-cache/colleague-guide-zh.md`** 等按团队规范提交；**`figma-cache/files/`** 是否入库仍按原团队约定。
 
 ---
 
-## 维护者（发布 npm 包）
+## 更完整的说明在哪
 
-1. 改包内代码或 `cursor-bootstrap/` 后 bump **`package.json` 的 `version`**，并更新 **`CHANGELOG.md`**。  
-2. **`npm publish`**（已配置 `publishConfig.registry` 时指向 npm 官方）。  
-3. **`prepack`** 会在 pack/publish 前执行本仓库内的 `validate`；若发布用工作区故意无缓存，需自行处理校验策略。
+| 需求 | 文档（随包在 `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`**。
 
-```bash
-npm test
-npx figma-cache validate
-npm publish --dry-run
-```
+常用环境变量节选：`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`（示例钩子写「流程总览」md 的路径）— 释义与完整表见 **`figma-cache/README.md`**。

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

@@ -5,7 +5,7 @@
 > - `.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` 示例）
+> - `figma-cache.config.example.js`（示例 `postEnsure`：adapter hint + 可选 `docs/figma-flow-readme.md`）
 
 ## 你必须完成的任务（按顺序执行，尽量少问用户）
 
@@ -23,13 +23,14 @@
    确认第 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 示例一致即可）。
+   若 `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** 驱动。
+   - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。  
+   - **可选**：若项目已通过 `cursor init` 同步 **`figma-cache/colleague-guide-zh.md`**，可提示团队阅读；**大批量链接**与**业务流程文档（`docs/figma-flow-readme.md`）** 的推荐写法见该文件 **§5.9～§5.10**。
 
 ## 硬约束（违反则视为未完成）
 

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

@@ -16,6 +16,15 @@ const path = require("path");
 const ADAPTER_DOC_BASENAME =
   process.env.FIGMA_CACHE_ADAPTER_DOC || "figma-cache-adapter-hint.md";
 
+/**
+ * 人类可读的「流程 / 需求总览」骨架路径（相对项目根）。仅本示例写入；可在业务项目中改路径或删除相关逻辑。
+ * @type {string}
+ */
+const FLOW_README_REL =
+  process.env.FIGMA_CACHE_FLOW_README || "docs/figma-flow-readme.md";
+
+const FLOW_README_REGISTRY_BEGIN = "<!-- figma-cache-flow-readme: registry -->";
+
 /**
  * @param {object} ctx
  * @returns {string}
@@ -31,6 +40,8 @@ function buildNeutralHint(ctx) {
 - fileKey: \`${ctx.fileKey}\`
 - nodeId: \`${nodeLabel}\`
 
+**流程 / 交互总览（可选）**：若使用本示例默认钩子，项目根下另有 **\`${FLOW_README_REL}\`**，随每次 \`ensure\` 追加节点小节，便于与 \`index.json\` 里的 \`flows\` 互补（人读 md，机读索引）。
+
 下一步：打开项目根 \`AGENT-SETUP-PROMPT.md\`，整篇交给 Cursor Agent 执行以完成栈适配（含本钩子的具体实现与 \`02-figma-<栈>-adapter.mdc\`）。
 `;
 }
@@ -48,18 +59,78 @@ function writeAdapterHint(ctx) {
   fs.writeFileSync(target, buildNeutralHint(ctx), "utf8");
 }
 
+/**
+ * 在单文件里维护「已缓存节点」登记（按 cacheKey 幂等追加），与 index.json / flows 互补：适合评审与新人阅读。
+ * @param {object} ctx
+ */
+function appendFlowReadmeRegistry(ctx) {
+  const abs = path.resolve(ctx.root, FLOW_README_REL);
+  const marker = `<!-- cache-node:${ctx.cacheKey} -->`;
+  const specRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.spec)));
+  const metaRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.meta)));
+  const completeness = Array.isArray(ctx.completeness) && ctx.completeness.length ? ctx.completeness.join(", ") : "—";
+  const block =
+    `\n${marker}\n` +
+    `### \`${ctx.cacheKey}\`\n\n` +
+    `- **Figma**: ${ctx.url || "—"}\n` +
+    `- **syncedAt**: ${ctx.syncedAt || "—"}\n` +
+    `- **source**: ${ctx.source || "—"}\n` +
+    `- **completeness**: ${completeness}\n` +
+    `- **spec**: \`${specRel}\` · **meta**: \`${metaRel}\`\n` +
+    `- **提示**: 像素级还原以 \`spec.md\` / \`raw.json\` 为准；用户路径请维护 \`flows\` 后把 \`npm run figma:cache:flow mermaid\` 输出贴到下方「流程总览」。\n`;
+
+  if (!fs.existsSync(abs)) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const head =
+      `# 设计与流程说明（示例骨架）\n\n` +
+      `> 本文件由 **figma-cache.config.example.js** 的 \`postEnsure\` 自动创建并增量更新；**可整文件改写**或复制逻辑到自有 \`figma-cache.config.js\`。\n\n` +
+      `## 流程总览（手填 / 或粘贴 mermaid）\n\n` +
+      `用自然语言写用户路径，或粘贴 \`npm run figma:cache:flow mermaid -- --flow=<flowId>\` 的输出：\n\n` +
+      `\`\`\`mermaid\n%% flow mermaid 输出贴此处\n\`\`\`\n\n` +
+      `## 交互与边界（手填）\n\n` +
+      `- 分支条件：\n` +
+      `- 异常与空状态：\n\n` +
+      `## 已从 Figma 写入缓存的节点（钩子按节点幂等追加）\n\n` +
+      `${FLOW_README_REGISTRY_BEGIN}\n`;
+    fs.writeFileSync(abs, head + block + "\n", "utf8");
+    return;
+  }
+
+  let body = fs.readFileSync(abs, "utf8");
+  if (body.includes(marker)) {
+    return;
+  }
+  if (!body.includes(FLOW_README_REGISTRY_BEGIN)) {
+    body =
+      body.trimEnd() +
+      `\n\n## 已从 Figma 写入缓存的节点（钩子按节点幂等追加）\n\n${FLOW_README_REGISTRY_BEGIN}\n`;
+  }
+  fs.writeFileSync(abs, body.trimEnd() + block + "\n", "utf8");
+}
+
+/**
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizePosixPath(p) {
+  return p.split(path.sep).join("/");
+}
+
 module.exports = {
   buildNeutralHint,
   ADAPTER_DOC_BASENAME,
+  FLOW_README_REL,
+  appendFlowReadmeRegistry,
 
   hooks: {
     /**
-     * 默认实现：仅写入中性占位 Markdown，便于确认钩子已接通。
+     * 默认实现：写入节点内占位说明 + 项目根下「流程/需求」总览骨架（单文件、幂等追加节点块）。
      * 用 Agent 生成业务方案后，可整体替换本模块逻辑。
      */
     postEnsure(ctx) {
       try {
         writeAdapterHint(ctx);
+        appendFlowReadmeRegistry(ctx);
       } catch (err) {
         console.error(`[figma-cache.config] postEnsure: ${err.message}`);
       }

package/figma-cache/README.md

@@ -13,6 +13,8 @@
 
 说明：**`cursor init`** 与 **`figma-cache init`** 是两件事；后者才是本地缓存数据目录与空索引。仓库根 **`README.md`**（npm 包首页文档）中有与上述一致的「四步」说明。
 
+团队向长文（可转发同事）：**`colleague-guide-zh.md`**。
+
 ## 使用方式（重要）
 
 - 日常只需要把 Figma 链接发给 agent。
@@ -24,10 +26,9 @@
 - `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/README.md`**：接入、scripts、环境变量、人工校验与回填（本文件，随包分发的主文档）
+- **`figma-cache/colleague-guide-zh.md`**：团队向说明与提示词模板；**`npx figma-cache cursor init` 会写入/刷新**（与 `FIGMA_CACHE_DIR` 下路径一致），便于纳入版本库、不必从 `node_modules` 手抄
+- `figma-cache/link-normalization-spec.md`：链接标准化规则（Core / Skill 会引用）
 - `figma-cache/flow-edge-taxonomy.md`：流程边类型约定
 
 ## 默认配置
@@ -96,3 +97,104 @@ npm run figma:cache:init
 ```
 
 - 该命令只创建空索引，不会创建任何节点缓存文件。
+
+---
+
+## 复制 `figma-cache/` 接入（不安装 npm 包）
+
+将脚本与规范**整目录**拷入业务仓库、**不**通过 `npm i figma-cache-toolchain` 安装时：
+
+- **建议**拷贝：`figma-cache.js` 与本目录下规范 `.md`；业务数据 `files/`、`index.json` 可按需不带，在新项目执行 **`figma-cache init`** 再 **`ensure`** 重建。
+- **可选**：仓库根薄封装 `bin/figma-cache.js`；也可始终 `node figma-cache/figma-cache.js <子命令>`。
+- **项目根**仍需：`figma-cache.config.js`、`.cursor/` 规则与 Skill、`AGENT-SETUP-PROMPT.md`（或由等价流程生成）。
+- Vue2+Vuetify2 参考 Adapter：`cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`（npm 安装时在 `node_modules/.../cursor-bootstrap/examples/`）。
+
+说明：Cursor **不会**在 `npm install` 时写入 `.cursor/`；`npx figma-cache cursor init` 负责从包内复制模板。已存在模板时 `cursor init` 默认**跳过**（`--force` 覆盖）；**`AGENT-SETUP-PROMPT.md` 每次 `cursor init` 均刷新**。
+
+## package.json scripts 示例
+
+**方式 A**（目录拷进仓库，用 `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",
+  "figma:cache:cursor:init": "node figma-cache/figma-cache.js cursor init"
+}
+```
+
+**方式 B**（`npm i -D figma-cache-toolchain`）：`package.json` 的 `bin` 提供 `figma-cache`，`npm run` 里可写 `figma-cache <子命令>`（走 `node_modules/.bin`）。本工具链**自身仓库根**在无自依赖时部分 npm 版本不会把当前包写入 `.bin`，故可用 `node bin/figma-cache.js <子命令>` 做自检，与方式 B 等价。
+
+## 接入后自检
+
+1. `npm run figma:cache:config`（或 `npx figma-cache config`）
+2. `npm run figma:cache:validate`
+3. 用真实链接试一次 `get` / `ensure`
+
+## 环境变量（完整列表）
+
+| 变量 | 作用 |
+|------|------|
+| `FIGMA_CACHE_DIR` | 缓存根目录 |
+| `FIGMA_CACHE_INDEX_FILE` | 索引文件路径 |
+| `FIGMA_ITERATIONS_DIR` | **仅** `backfill` 扫描的历史 Markdown 目录；不存在时扫描为空，`validate` 不受影响 |
+| `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
+| `FIGMA_DEFAULT_FLOW` | 默认 `flowId`（大迭代推荐设置） |
+| `FIGMA_CACHE_ADAPTER_DOC` | 覆盖 `postEnsure` 写入的适配说明文件名（默认见各项目 `figma-cache.config.js`） |
+| `FIGMA_CACHE_FLOW_README` | **仅包内示例钩子**：人类可读的「流程 / 需求总览」Markdown 相对路径，默认 **`docs/figma-flow-readme.md`**；每次 `ensure` 对**新 cacheKey** 幂等追加一节 |
+
+## 人工校验清单（对照 `validate`）
+
+- `index.json` 存在对应 `cacheKey`
+- 记录包含 `fileKey` / `scope` / `url` / `syncedAt`
+- `normalizationVersion` 与当前规范一致
+- `paths.meta` 与 `paths.spec` 已定义
+- `completeness` 覆盖当前任务字段
+- `scope=node` 时存在 `nodeId`
+- 若维护了 `flows`，边的 `from` / `to` 必须存在于 `items`
+
+## 历史链接回填（backfill）
+
+扫描历史文档中的 Figma 链接并补入缓存索引。
+
+```bash
+npm run figma:cache:backfill
+```
+
+默认扫描目录由 `FIGMA_ITERATIONS_DIR` 决定（默认 `library/figma-iterations`）。完成后建议：
+
+```bash
+npm run figma:cache:validate
+npm run figma:cache:stale
+```
+
+## Adapter 与 postEnsure
+
+- **推荐**：`npx figma-cache cursor init` 后，在 Cursor 中 **`@AGENT-SETUP-PROMPT.md`** 由 Agent 一次性完成栈 Adapter、合并 `figma-cache.config.js`（含删除占位 `02-figma-stack-adapter.mdc`）。
+- **手写**时须遵守：Core 只维护通用缓存；Adapter 只约束「读缓存后如何写业务 UI」；禁止在 `meta.json` / `raw.json` / `spec.md` 写框架专有实现。
+
+### 包内 `figma-cache.config.example.js` 默认钩子（像素事实 + 可读流程）
+
+`hooks.postEnsure` 会做两件事（均在 **Core 写完通用骨架之后**）：
+
+1. **节点目录内**：写入 **`figma-cache-adapter-hint.md`**（文件名可由 `FIGMA_CACHE_ADAPTER_DOC` 覆盖）— 提醒实现侧对齐 `spec.md` / `raw.json` 等。
+2. **项目根**：维护或创建 **`docs/figma-flow-readme.md`**（路径可由 **`FIGMA_CACHE_FLOW_README`** 覆盖）— 含「流程总览 / 交互边界」**手填区**，以及按 **`cacheKey` 幂等追加**的「已从 Figma 写入缓存的节点」登记（含 Figma 链接、`syncedAt`、`completeness`、相对 `spec`/`meta` 路径）。**像素级还原**仍以各节点 **`spec.md`** 为准；**用户路径图**请继续用 CLI **`flow`** 维护 `index.json`，再把 **`flow mermaid`** 贴进该 md 的 mermaid 代码块，便于评审与新人阅读。
+
+`postEnsure` 的 **`ctx`** 还包含 **`url` / `source` / `syncedAt` / `completeness`**（与 `index.json` 中 item 一致），便于自定义钩子写文档或触发 CI。
+
+## 包维护者
+
+维护 **`figma-cache-toolchain` 源码**时：见**仓库根** `README.md`（发布）与 `CHANGELOG.md`；修改 `cursor-bootstrap/`（含 `AGENT-SETUP-PROMPT.md`）或 CLI 后 bump 版本并 `npm publish`，消费方 `cursor init` 才会刷新到最新任务书。将 Core 抽成独立包、semver 与 `ctx` 约定等，可在发包前对照 `CHANGELOG` 与 `npm publish --dry-run`。

package/figma-cache/colleague-guide-zh.md

@@ -0,0 +1,420 @@
+# figma-cache-toolchain：团队使用说明（可转发）
+
+本文面向**业务仓库**里要用 Figma 本地缓存的同事：说明**是什么、何时用、怎么接、日常怎么用、怎么升级**。技术细节仍以包内**根 `README.md`**、**`figma-cache/README.md`** 为准；链接与键、Flow 边类型分别见 **`link-normalization-spec.md`**、**`flow-edge-taxonomy.md`**。**专用名词**见**文首「术语与专用名词（速查）」**表格。
+
+---
+
+## 术语与专用名词（速查）
+
+读后续提示词前，可先扫一眼本表。**路径**均相对业务项目根，默认缓存目录名为 **`figma-cache/`**（可用环境变量 **`FIGMA_CACHE_DIR`** 改掉）。
+
+| 名词 | 一句话解释 |
+|------|------------|
+| **`ensure`** | 针对一条 Figma 链接：在 **`figma-cache/index.json`** 里登记/更新一条 **`items`** 记录，并在磁盘上生成/补齐该节点的 **`meta.json` / `spec.md` / `raw.json` / `state-map.md`** 等骨架；常由 Agent 调用 CLI `figma-cache ensure` 完成。 |
+| **`get`** | 按链接查看缓存是否命中、或拉取条目信息；不一定写盘。 |
+| **`validate`** | 检查 **`index.json`** 结构是否合法（必填字段、`flows` 里的边是否指向存在的 `items` 等）。合并前可跑。 |
+| **`completeness`** | `ensure` 时可传的**标签列表**（如 `layout`、`text`、`tokens`、`interactions`），表示「希望这次把哪些方面的设计信息写进缓存/交给 MCP」。**不是 Figma 官方枚举**，而是你们流程里约定「要记多细」；具体写入内容仍落在 **`spec.md` / `raw.json`** 等文件里。 |
+| **`spec.md`** | 某节点目录下的 **Markdown**，人类可读的设计摘要/规格说明，**对齐 UI、走查像素时最常对照**的文件之一。 |
+| **`meta.json`** | 同目录下的 **JSON**，记录该缓存项的元信息（如 `fileKey`、`nodeId`、`syncedAt`、`source` 等），偏「这条缓存是谁、何时写的」。 |
+| **`raw.json`** | 同目录下的 **JSON**，偏**结构化原始快照**（可能较大），适合机器读或 Agent 从中抽字段；**像素/间距等细节**以团队约定为准，常见与 **`spec.md`** 一起看。 |
+| **`state-map.md`** | 占位/扩展用 Markdown，用于**状态机、屏间跳转、交互说明**等；初始可能是 TODO，由你们或 Agent 补全。 |
+| **`index.json`** | 缓存库的**总索引**：里面有所有节点的 **`items`**，以及可选的多屏流程 **`flows`**。 |
+| **`items` / 一条 item** | `index.json` 里 **`items`** 对象：键为 **`cacheKey`**，值为该 Figma 节点（或整文件）的索引记录（含 `url`、`paths`、`completeness` 等）。**「进缓存」≈ 有一条 item。** |
+| **`cacheKey`** | 标准化后的**唯一键**，一般形如 **`fileKey#nodeId`**（无节点时可能是 **`fileKey#__FILE__`**）。用于去重、校验、`flow` 里引用节点。算法见 **`link-normalization-spec.md`**。 |
+| **`fileKey` / `nodeId`** | **fileKey**：Figma 文件 ID。**nodeId**：画布上某个节点的 ID（常为 `数字:数字`）。都来自链接解析。 |
+| **`flow`（流程）** | 在 **`index.json` 的 `flows`** 里的一条记录，表示**一条业务用户路径**（多屏/多节点），含 **`flowId`**、节点列表、**边（edges）** 等。与「单条 Figma 链接」不同：**flow 描述的是关系与顺序**。 |
+| **`flowId`** | 某条流程的 ID 字符串（如 `my-onboarding-flow`），`flow init` 时创建；后续 **`flow add-node` / `flow link`** 都要指明落在哪条 flow 上。可用 **`FIGMA_DEFAULT_FLOW`** 省略重复参数。 |
+| **`flow link` / `flow chain`** | CLI 子命令：在指定 **`flowId`** 下**加边**（从屏 A 到屏 B、类型 `next_step` 等），或**按顺序一串链式连接**多个 URL。 |
+| **`flow mermaid` / `flow show`** | 把当前 flow **导出成 Mermaid 图**或 **JSON 文本**，方便贴进文档或评审。 |
+| **边类型（`type`）** | `flow link` 时的 **`--type=`**，如 `next_step`、`related`、`child`、`branch_true` 等；**完整列表与语义**见 **`flow-edge-taxonomy.md`**。 |
+| **`note`** | 可选：附在边上的一句**人话说明**（如「点击设置进入」），方便以后读 `index.json` 或导出图时理解。 |
+| **MCP / `figma-mcp`** | **Figma MCP**：在 Cursor 里从 Figma **实时读**画布/节点信息的通道。缓存**优先**；本地不够或你要最新稿时，再由 Agent 调 MCP。 |
+| **Core 规则** | 通常指 **`.cursor/rules/01-figma-cache-core.mdc`**：只管**数据层**（标准化链接、读写 `figma-cache`、何时 MCP、校验），**不写** Vue/React 具体代码。 |
+| **Adapter** | 通常指 **`.cursor/rules/02-figma-<栈>-adapter.mdc`**：约定**在缓存可读之后**，如何在你司技术栈里写业务 UI。 |
+| **Skill** | **`.cursor/skills/figma-mcp-local-cache/SKILL.md`**：教 Agent **何时查缓存、何时调 MCP、如何跑 CLI** 的步骤化说明，与 Core / Adapter 配合使用。 |
+| **`AGENT-SETUP-PROMPT.md`** | 项目根下的 **Agent 任务书**（`cursor init` 每次刷新）：用于**一次性接入**栈配置、合并 `figma-cache.config.js`、补 npm scripts 等。 |
+| **`postEnsure`** | **`figma-cache.config.js`** 里的钩子：**每次 `ensure` 写完通用骨架文件之后**调用一次，可写适配说明、维护 **`docs/figma-flow-readme.md`** 等；**抛错不会让整个 ensure 失败**（由 Core 捕获日志）。 |
+| **`cursor init` vs `figma-cache init`** | **`cursor init`**：拷 `.cursor` 模板、刷新 **`AGENT-SETUP-PROMPT.md`**、同步 **`colleague-guide-zh.md`**。**`figma-cache init`**：只建 **`figma-cache/index.json`** 空索引，**不管 Cursor**。 |
+| **`npm run figma:cache:*`** | 项目在 **`package.json` 的 `scripts`** 里封装的 CLI；未配置时可用 **`npx figma-cache <子命令>`** 代替。 |
+| **业务流程文档（推荐）** | 通常指项目里的 **`docs/figma-flow-readme.md`**（路径可改）：用**中文叙事**写清主路径/分支/边界，并粘贴 **`flow mermaid`**；与 **`index.json` 的 `flows`** 双轨对齐，**人和 Agent 都优先读它建立上下文**。详见 **§5.8～§5.10**。 |
+
+---
+
+## 1. 这个包是干什么的
+
+- **把 Figma 链接变成项目里可复用的本地缓存**（`figma-cache/index.json` + `figma-cache/files/...`），并带 **Node CLI** 做标准化、写入、校验。
+- **不绑定** Vue/React 等具体 UI；你们项目里的 **Cursor 规则 + `figma-cache.config.js`** 会约定「缓存好之后代码怎么对齐设计」。
+- **日常多数时候**：把 Figma 链接丢给 **Cursor Agent**，由 Agent 按规则走「先查本地缓存 → 不够再 MCP → 回写 → 校验」即可；**不必**每人背命令。
+
+---
+
+## 2. 适用场景（什么时候有用）
+
+| 场景 | 说明 |
+|------|------|
+| **单屏 / 单组件对齐** | 只有一条 Figma 链接，要把布局、文案、状态写进代码。 |
+| **多屏 / 多节点同一业务流** | 登录 → 首页 → 设置等多条链接，希望在缓存里保留**先后或分支关系**，便于迭代与评审。 |
+| **渐进式补设计** | 今天先拉一条链接进缓存，过几天再给下一条，并要求**关联到之前某屏**（下一屏、弹层挂在某屏上、分支等）。 |
+| 多人协作同一套设计稿 | 减少重复拉 Figma、口径统一（以本地缓存 + 校验为准）。 |
+| 希望对话可复现、可审计 | 设计事实落在仓库的 `figma-cache/`（是否提交 git 由团队约定）。 |
+| 用 Cursor 做设计落地 | 配合 `.cursor` 规则与 Skill，Agent 行为一致。 |
+
+若项目**从未**装过本包，需要有人做一次**接入**（第 3 节）。
+
+**和「提示词」的关系**：下面第 5 节给的句子是**自然语言指令**；Agent 在 **Core 规则**下会优先读本地 `figma-cache/`，不足再走 Figma MCP，并调用 **`npm run figma:cache:*` / `npx figma-cache`** 维护索引。你**不需要**自己敲 CLI，但**说清楚意图与关系**，结果会稳定很多。
+
+---
+
+## 3. 一次性接入（业务项目根目录执行）
+
+顺序建议固定为下面 **4 步**，避免和「只刷新 Cursor 模板」混淆。
+
+### 步骤 1：安装依赖
+
+```bash
+npm i -D figma-cache-toolchain
+```
+
+### 步骤 2：写入 Cursor 模板并刷新任务书
+
+```bash
+npx figma-cache cursor init
+```
+
+作用：在项目里生成/更新 **`.cursor/`**、`figma-cache.config.example.js`，并**每次刷新**根目录的 **`AGENT-SETUP-PROMPT.md`**。  
+**注意**：这一步**还不会**创建业务用的 **`figma-cache/index.json`**。
+
+### 步骤 3：在 Cursor 里交给 Agent 执行一次
+
+在 Cursor 对话中输入 **`@AGENT-SETUP-PROMPT.md`**，并说「**按该文档执行**」。  
+Agent 会按你们仓库栈生成/合并 **`figma-cache.config.js`**、栈专属 Adapter、补全 **`figma:cache:*` npm scripts** 等（**每个项目通常只需成功做一次**；以后升级包见第 7 节）。
+
+### 步骤 4：初始化本地缓存目录（空索引）
+
+在 **步骤 3 完成之后**执行（有 script 优先用 script）：
+
+```bash
+npm run figma:cache:init
+```
+
+若尚未有对应 script：
+
+```bash
+npx figma-cache init
+```
+
+成功后，项目根会出现 **`figma-cache/`** 目录及 **`figma-cache/index.json`**（开始时可能只有索引，**没有**具体节点文件是正常的）。
+
+**易混点**：**`cursor init`**（步骤 2）≠ **`figma-cache init`**（步骤 4）；前者管 Cursor 模板，后者管**本地缓存数据骨架**。
+
+---
+
+## 4. 同事日常怎么用（接入完成之后）
+
+1. **有 Figma 相关需求时**：在 Cursor 里把 **Figma 链接**和任务说明发给 Agent；Agent 会按项目里的 **Core 规则 + 你们栈 Adapter + Skill** 处理缓存与落地边界。  
+2. **需要自检时**（例如合并前、怀疑索引坏了）：
+
+   ```bash
+   npm run figma:cache:validate
+   ```
+
+   或：
+
+   ```bash
+   npx figma-cache validate
+   ```
+
+3. **规范文档在哪**：包内自带说明（安装后在 **`node_modules/figma-cache-toolchain/figma-cache/`** 下的多个 `.md`）。一般**不必**再复制一份到业务仓库；需要时让 Agent **`@` 该路径**即可。
+
+---
+
+## 5. 使用场景详解与提示词（单条 / 多条 / 渐进关联）
+
+以下示例均假设：**项目已完成第 3～4 节接入**，且你在 **Cursor 同一条对话线程**里持续补充上下文（便于 Agent 把「上一条链接」和「这一条」对上号）。可把方括号 `[]` 换成你的真实描述或链接。文中 **`ensure` / `completeness` / `spec` / `flow` / `cacheKey`** 等含义见**文首术语表**。
+
+### 5.1 单条 Figma 链接：只做缓存、不写业务代码
+
+**意图**：把该节点写入本地 `figma-cache`（含 `ensure`、必要时 MCP、最后 `validate`），先不实现页面。
+
+**可复制提示词示例**：
+
+```text
+请按项目 figma 缓存规则处理下面这条链接：只做本地缓存（ensure），来源用 figma-mcp，
+completeness 至少包含 layout、text、tokens；完成后执行 figma:cache:validate。
+
+[Figma 链接]
+```
+
+**变体（你还不确定 completeness）**：
+
+```text
+[Figma 链接]
+先按缓存规范写入 figma-cache；若本地没有或过期再调 MCP。完成后 validate。
+```
+
+---
+
+### 5.2 单条链接：缓存 + 对照设计做具体开发任务
+
+**意图**：在缓存就绪的前提下，让 Agent 改你们栈里的页面/组件（具体由项目 **Adapter 规则**约束）。
+
+```text
+[Figma 链接]
+请先确保该节点已在 figma-cache 中（必要时 ensure），再按我们项目的 Adapter：
+把 [某路由/某组件名] 对齐到该设计（间距、字体、颜色与状态）。
+完成后运行 figma:cache:validate。
+```
+
+**变体（只问规格、不写代码）**：
+
+```text
+[Figma 链接]
+缓存若缺失请先 ensure。请根据 spec/meta 用中文列出与当前代码 [文件路径] 的差异清单，先不改代码。
+```
+
+---
+
+### 5.3 多条 Figma 链接：希望「有关联」（流程 / 跳转）
+
+**背景**：索引里除单条 `items` 外，还可以维护 **`flows`**：多个节点用**边**连接，类型见包内 **`flow-edge-taxonomy.md`**（如 `next_step`、`related`、`child` 等）。适合「多屏同一条用户路径」。
+
+**第一次拉多条、且你已知道顺序（推荐先说清 flow 名字）**：
+
+```text
+我们要维护一条用户流程，flowId 叫 [my-onboarding-flow]，中文标题 [新用户引导]。
+请若尚无则 flow init；然后按顺序 ensure 下面这些链接并把它们加入该 flow，
+相邻两屏之间用 flow link，类型 next_step（若你不确定先后关系则先用 related 并加 note 说明）：
+
+1) [Figma 链接 A]
+2) [Figma 链接 B]
+3) [Figma 链接 C]
+
+最后 flow show 或 flow mermaid 输出让我确认，并 validate。
+```
+
+**已经 ensure 过、只想补关系**：
+
+```text
+在 flow [my-onboarding-flow] 里：
+从 [Figma 链接 A] 到 [Figma 链接 B] 是主流程下一步，请 flow link，类型 next_step，note：[例如：点击首页「设置」进入]。
+完成后 validate。
+```
+
+**一次性串联（链式，适合一条直线）**：
+
+```text
+对 flow [my-onboarding-flow]，把下面链接按顺序 flow chain，类型 next_step：
+[URL1] [URL2] [URL3]
+若某条尚未在 items 里，可带 --ensure 再 add-node。最后 mermaid 给我看一眼。
+```
+
+---
+
+### 5.4 渐进式：每次只给一条新链接，但要挂到「之前的」上面
+
+典型情况：**上周缓存了登录页**，这周发**首页**链接，并说「首页是登录成功后的下一屏」。
+
+**写法 A（依赖同线程上文：最省事）**  
+
+在同一条 Cursor 对话里，先有过登录页的讨论或你明确粘贴过登录链接，然后发：
+
+```text
+新链接（下一屏）：[Figma 链接-首页]
+
+请 ensure 这条；然后把它与**本对话里前面那条登录页 Figma 链接**在流程上连起来：
+flowId 仍用 [my-onboarding-flow]，边类型 next_step，note：[登录成功进入首页]。
+若 flow 不存在请先 flow init。最后 validate。
+```
+
+**写法 B（不依赖上下文：两条都写全）**  
+
+新开对话或怕 Agent 对不上时，**两条 URL 都贴上**，并说明谁接谁：
+
+```text
+已有节点（上一屏）：[Figma 链接-登录]
+新节点（下一屏）：[Figma 链接-首页]
+
+请 ensure 两条（若已缓存可跳过重复拉取）；在 flow [my-onboarding-flow] 里 add-node（若缺）并用 flow link 从登录到首页，类型 next_step。
+validate。
+```
+
+**写法 C（弹层 / 子结构挂在某一屏上）**  
+
+边类型常用 **`child`**（结构父子）或 **`related`**，不确定时先用 `related`，见 `flow-edge-taxonomy.md`。
+
+```text
+主屏：[Figma 链接-通话中页面]
+弹层（依附该主屏）：[Figma 链接-更多菜单抽屉]
+
+请 ensure 两条；在同一 flow [sip-calling-flow] 里建立从主屏到弹层的边，类型 child，note：[点击「更多」打开抽屉]。
+validate。
+```
+
+**写法 D（分支：成功 / 失败两种下一屏）**  
+
+```text
+决策点屏：[Figma 链接-表单页]
+成功分支下一屏：[Figma 链接-成功页]
+失败分支下一屏：[Figma 链接-错误提示]
+
+请 ensure 三屏；在 flow [form-submit-flow] 中：
+从表单到成功页 flow link，类型 branch_true，note：[校验通过]；
+从表单到错误页 flow link，类型 branch_false，note：[校验失败]。
+validate。
+```
+
+---
+
+### 5.5 只有 node-id、或只有「文件里之前那个 key」时怎么说
+
+- **两条都是完整 Figma URL**：最稳，直接粘贴即可（Agent 会按 **`link-normalization-spec.md`** 生成同一 `cacheKey` 体系）。
+- **你只有 node-id、和 fileKey**：可以写「与登录页**同一 Figma 文件**，node-id 为 `123:456`」，并贴上**该文件任意带 node-id 的链接**作为锚点，让 Agent 拼出规范 URL 再 ensure。
+- **想指「index 里已有的一项」**：可以说「`cacheKey` 为 `xxxx#yyyy` 的那条」（若你打开过 `figma-cache/index.json`）；一般同事**不必**手写 cacheKey，**两条 URL 都贴上**即可。
+
+---
+
+### 5.6 多条链接但**暂时不想**建 flow 关系
+
+可以只要求**批量进缓存**，不建边：
+
+```text
+请分别 ensure 下面这些链接（同一文件不同节点也可以），completeness [layout,text,tokens]；
+**不要**修改现有 flows，除非我明确说要建立关系。
+
+- [URL1]
+- [URL2]
+- [URL3]
+
+完成后 validate。
+```
+
+以后若要补关系，再用 **5.3 / 5.4** 的 `flow link` 话术即可。
+
+---
+
+### 5.7 易错提醒（给使用者看的）
+
+| 情况 | 建议 |
+|------|------|
+| **新开对话** | Agent 可能看不到「上一条链接」，请用 **5.4 写法 B** 两条 URL 写全，或 **`@` 含链接/含 cacheKey 的本地文件**。 |
+| **flow 子命令要 `--flow=`** | 若项目设置了环境变量 **`FIGMA_DEFAULT_FLOW`**，可省略；否则在提示词里写清 `flowId`。 |
+| **add-node 报缺 item** | 提示词里写明「若缺则对某 URL **带 --ensure** 先写入 items 再 add-node」。 |
+| **不确定边类型** | 写「边类型不确定，先用 **related**，并在 note 里用一句话描述设计关系」。 |
+
+### 5.8 自动维护的「流程 / 需求总览」单文件（可选）
+
+若项目使用包内默认 **`figma-cache.config.example.js`**（或由 Agent 合并后的等价 **`postEnsure`**），每次对某节点 **`ensure`** 成功后，钩子会在项目根下维护 **`docs/figma-flow-readme.md`**（可用环境变量 **`FIGMA_CACHE_FLOW_README`** 改路径）：
+
+- 文件里预留 **「流程总览」**（可粘贴 **`npm run figma:cache:flow mermaid`** 输出）和 **「交互与边界」** 手填区，方便产品/评审阅读。
+- **「已从 Figma 写入缓存的节点」** 区会按 **`cacheKey` 幂等追加**小节（含 Figma 链接、`completeness`、指向 **`spec.md`** 的相对路径），与 **`figma-cache/index.json`** 里的 **`flows`** 互补：**索引 + mermaid 给机器与校验，本 md 给人读**。
+- **像素级细节**仍以各节点目录下的 **`spec.md` / `raw.json`** 为准；本文件不做第二份设计稿，只做**导航与流程叙事**。
+
+在提示词里可 **`@docs/figma-flow-readme.md`**，要求 Agent 根据刚 ensure 的节点更新手填区或补充用户故事。  
+**大批量链接**与**少量但已建 flow** 时如何把「业务逻辑」写成人话，见 **§5.9、§5.10**。
+
+---
+
+### 5.9 大批量链接（几十条）：推荐两阶段
+
+**说明**：缓存 **不会**自动从几十个 URL 推断页面跳转；**业务关系**靠 **`flows` + `flow link`** 与/或 **Agent 归纳** 写进文档。
+
+**阶段 1 — 先全部进缓存（事实层）**
+
+```text
+本迭代有一批 Figma 节点需要先写入 figma-cache（只做 ensure，暂不新建 flow、不改现有 flows）：
+completeness 统一为 layout,text,tokens,interactions（可按项目约定改）。
+
+请逐条 ensure 下列链接（若已存在可跳过重复 MCP），最后 validate：
+
+- [URL1]
+- [URL2]
+…（可继续列，或分多条消息粘贴，但请在同一任务内做完再汇报）
+
+完成后简要列出：新增了几个 cacheKey、有无失败项。
+```
+
+**阶段 2 — 再整理业务逻辑 + 写进 index 的 flows + 给人看的文档**
+
+```text
+上一步已 ensure 的链接如下（或请直接读 figma-cache/index.json 里本迭代相关 items）：
+[可再贴一遍 URL 列表，或 @figma-cache/index.json]
+
+请结合设计稿/MCP（如需）与产品常识，完成：
+1) 归纳**用户主路径、分支、异常与空状态**（用中文写清假设）；
+2) 在 flowId [my-iteration-flow] 下维护 flows：若无则 flow init；用 flow add-node / flow link（类型见 flow-edge-taxonomy.md，不确定用 related + note）把屏与屏关系写进 index.json；
+3) 运行 flow mermaid，把输出贴进 docs/figma-flow-readme.md 的「流程总览」代码块，并更新「交互与边界」手填区；
+4) validate。
+
+若与产品文档冲突，在 docs/figma-flow-readme.md 里用「待产品确认」标出差异点。
+```
+
+链接特别多时，可让 Agent **分批 ensure**（每批 10～15 条）以免单次上下文过长，**阶段 2 尽量用 `@index.json` + 抽样 `@spec.md`** 归纳。
+
+---
+
+### 5.10 少量链接，但只要建了 flow 或有人专门补了提示：也要有一份「人 + Agent 都读得懂」的业务流程文档吗？
+
+**建议：要。** 链接少不代表关系简单；**只要存在 `flows` 或有人用自然语言补过「谁接谁」**，就值得在 **`docs/figma-flow-readme.md`**（或你们约定的路径）里维护**同一份**「业务流程说明」，和 **`index.json` 里的机器结构**对齐：
+
+| 做法 | 说明 |
+|------|------|
+| **谁写** | **专人**可只写手填区（主路径、分支、边界）；**Agent** 可根据 `flow show` / `flow mermaid` + 各屏 `spec.md` 起草再让人改。 |
+| **何时更新** | 每次 **`flow link` / `flow chain` 有变**、或产品改口径、或某屏 **re-ensure** 后行为变了，就同步改 md（可与 PR 一起审）。 |
+| **和 Agent 的关系** | Agent 读 **`@docs/figma-flow-readme.md`** 比纯读 `index.json` 更快建立业务上下文；新人 onboarding 同理。 |
+
+**可复制提示词（flow 已建好，补「人话」文档）**：
+
+```text
+flowId：[my-iteration-flow]
+请读取 figma-cache/index.json 里该 flow 的 nodes 与 edges，并运行 flow mermaid。
+
+请更新 @docs/figma-flow-readme.md：
+1) 「流程总览」贴上当前 mermaid；
+2) 「交互与边界」用中文写：主路径、分支条件、异常与空状态（没有信息就写「待补充」并列出需问产品的问题）；
+3) 在文末加一小节「与开发对齐的检查清单」（可勾选）便于实现与测试。
+
+不要改各节点 spec.md 里的设计事实，只整理叙事层。
+```
+
+**结论**：**链接多少不是门槛**；**只要开始有 flow 关系或有人愿意用提示补业务语义**，就应用**同一份业务流程 md** 把「给人看的逻辑」固定下来，与 **`flows` + `validate`** 形成双轨（机读 + 人读），更利于开发与评审。
+
+---
+
+## 6. 仓库里建议提交什么（和团队对齐即可）
+
+常见做法（**以你们团队约定为准**）：
+
+- **建议提交**：`.cursor/`（若团队希望共享同一套 Agent 行为）、`figma-cache.config.js`、`AGENT-SETUP-PROMPT.md`（会随 `cursor init` 刷新）、`package.json` / lock。  
+- **按需提交**：`figma-cache/index.json` 与 **`figma-cache/files/`**（若希望「拉过即入库」、CI 可校验）；若采用默认 **`postEnsure`**，还可提交 **`docs/figma-flow-readme.md`**（或你在 `FIGMA_CACHE_FLOW_README` 中自定义的路径）供评审与新人阅读。  
+- **可不提交**：纯个人试验缓存（则同事本地需自行 `ensure`）。
+
+---
+
+## 7. 升级 npm 包之后怎么做
+
+```bash
+npm i -D figma-cache-toolchain@latest
+npx figma-cache cursor init
+```
+
+- **`AGENT-SETUP-PROMPT.md`** 每次 `cursor init` 都会刷新，便于看到新版说明。  
+- 若你们**已经完成过**步骤 3，**不必**为升级而完整重跑一遍 Agent；除非任务书里有你们需要合并的新要求。  
+- **已有** `figma-cache/index.json` 时，**一般不必**重复执行 `figma:cache:init`。
+
+---
+
+## 8. 排障与谁维护
+
+- 命令帮助：`npx figma-cache`（无子命令时通常会打印用法）。  
+- 配置预览：`npm run figma:cache:config`（若已配置 script）。  
+- **维护责任人**：建议在团队 README 或内部 wiki 里写一句「谁负责升级 `figma-cache-toolchain`、谁审批 `.cursor` 规则变更」。
+
+---
+
+## 9. 本文档位置（方便你转发）
+
+- **业务项目（推荐）**：在仓库根执行 **`npx figma-cache cursor init`** 后，本说明会**自动写入或刷新**到 **`figma-cache/colleague-guide-zh.md`**（与 `FIGMA_CACHE_DIR` 一致，默认目录名 `figma-cache/`）。同事 **`@figma-cache/colleague-guide-zh.md`** 即可，**不必**从 `node_modules` 手抄。每次升级包后再跑一次 `cursor init` 即可同步正文。
+- **包内原件**：`node_modules/figma-cache-toolchain/figma-cache/colleague-guide-zh.md`（与上者内容一致，发版随包附带）。
+- **维护工具链源码的仓库**：同路径 **`figma-cache/colleague-guide-zh.md`**。
+
+将本文件全文复制到 IM / 邮件 / 内部文档即可给同事使用。

package/figma-cache/figma-cache.js

@@ -129,6 +129,10 @@ function runPostEnsureHook(cacheKey, item) {
     fileKey: item.fileKey,
     nodeId: item.nodeId == null ? null : item.nodeId,
     scope: item.scope,
+    url: item.url == null ? "" : String(item.url),
+    source: item.source == null ? "" : String(item.source),
+    syncedAt: item.syncedAt == null ? "" : String(item.syncedAt),
+    completeness: Array.isArray(item.completeness) ? item.completeness : [],
     paths: {
       raw: item.paths.raw,
       spec: item.paths.spec,
@@ -488,6 +492,18 @@ function copyCursorBootstrap(force) {
   agentBody = agentBody.replace(/\{\{NPM_PACKAGE_NAME\}\}/g, npmPkg);
   fs.writeFileSync(agentDest, agentBody, "utf8");
 
+  const colleagueSrc = path.join(__dirname, "colleague-guide-zh.md");
+  const colleagueDest = path.join(CACHE_DIR, "colleague-guide-zh.md");
+  if (!fs.existsSync(colleagueSrc)) {
+    console.error(`[figma-cache] missing ${normalizeSlash(colleagueSrc)} (broken package install?)`);
+    process.exit(1);
+  }
+  const colleagueSameFile = path.resolve(colleagueSrc) === path.resolve(colleagueDest);
+  if (!colleagueSameFile) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.copyFileSync(colleagueSrc, colleagueDest);
+  }
+
   console.log(
     JSON.stringify(
       {
@@ -500,6 +516,11 @@ function copyCursorBootstrap(force) {
           ? "Some template files were skipped (already exist). Re-run with --force to overwrite."
           : "Done.",
         agentPromptFile: normalizeSlash(agentDest),
+        colleagueGuideFile: normalizeSlash(colleagueDest),
+        colleagueGuideSynced: !colleagueSameFile,
+        colleagueGuideNote: colleagueSameFile
+          ? "colleague-guide-zh.md already at package path (toolchain dev tree); no copy."
+          : "colleague-guide-zh.md refreshed under FIGMA_CACHE_DIR (default figma-cache/).",
         agentPromptNote:
           "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,
@@ -679,7 +700,7 @@ 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`
+      `${ex} cursor init [--force]  # copy .cursor templates + figma-cache.config.example.js + refresh AGENT-SETUP-PROMPT.md + sync colleague-guide-zh.md into FIGMA_CACHE_DIR`
     );
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "1.3.2",
+  "version": "1.4.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": [

package/figma-cache/backfill-guide.md

@@ -1,18 +0,0 @@
-# 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/migration-guide.md

@@ -1,83 +0,0 @@
-# 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 仍可用。安装 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-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 **按文档顺序**完成：生成/合并 `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.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",
-  "figma:cache:cursor:init": "node figma-cache/figma-cache.js cursor init"
-}
-```
-
-**方式 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 与 postEnsure
-
-**推荐（最少步骤）**：`npx figma-cache cursor init` 后，在 Cursor 中 **`@AGENT-SETUP-PROMPT.md`** 或粘贴其全文，由 Agent 按文档一次性完成（含删除占位 `02-figma-stack-adapter.mdc`）。
-
-**手写/补充时**可自拟提示词，须遵守：Core 只维护通用缓存；Adapter 只约束「读缓存后如何写业务 UI」；禁止在 `meta.json` / `raw.json` / `spec.md` 写框架专有实现。**01-figma-cache-core.mdc** 一般无需改。
-
-## 将 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`。
-
-## 包维护者备忘（仅维护 npm 包源码时）
-
-若你同时维护 `figma-cache-toolchain` 包本身：修改 `cursor-bootstrap/`（含 `AGENT-SETUP-PROMPT.md`）或 CLI 后，记得 bump 版本并发布 npm，以便消费方 `cursor init` 刷新到最新 Agent 指令。

package/figma-cache/validation-checklist.md

@@ -1,15 +0,0 @@
-# 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
-```