figma-cache-toolchain 1.4.3 → 1.4.4

package/figma-cache/{colleague-guide-zh.md → docs/colleague-guide-zh.md}

@@ -1,6 +1,6 @@
 # figma-cache-toolchain：团队使用说明（可转发）
 
-本文面向**业务仓库**里要用 Figma 本地缓存的同事：说明**是什么、何时用、怎么接、日常怎么用、怎么升级**。技术细节仍以包内**根 `README.md`**、**`figma-cache/README.md`** 为准；链接与键、Flow 边类型分别见 **`link-normalization-spec.md`**、**`flow-edge-taxonomy.md`**。**专用名词**见**文首「术语与专用名词（速查）」**表格。
+本文面向**业务仓库**里要用 Figma 本地缓存的同事：说明**是什么、何时用、怎么接、日常怎么用、怎么升级**。技术细节仍以包内**根 `README.md`**、**`figma-cache/docs/README.md`** 为准；链接与键、Flow 边类型分别见 **`link-normalization-spec.md`**、**`flow-edge-taxonomy.md`**。**专用名词**见**文首「术语与专用名词（速查）」**表格。
 
 ---
 
@@ -82,7 +82,7 @@ npm i -D figma-cache-toolchain
 npx figma-cache cursor init
 ```
 
-作用：在项目里生成/更新 **`.cursor/`**、`figma-cache.config.example.js`，并**每次刷新**根目录的 **`AGENT-SETUP-PROMPT.md`**。  
+作用：在项目里生成/更新 **`.cursor/`**、`figma-cache.config.js`（并在安全场景清理 legacy 的 `figma-cache.config.example.js`），并**每次刷新**根目录的 **`AGENT-SETUP-PROMPT.md`**。  
 **注意**：这一步**还不会**创建业务用的 **`figma-cache/index.json`**。
 
 ### 步骤 3：在 Cursor 里交给 Agent 执行一次
@@ -141,10 +141,10 @@ npx figma-cache init
 请按项目 figma 缓存规则处理下面这条 Figma 链接，并遵循“缓存优先 + 按需 MCP + 最小调用集”：
 1) 先查本地 figma-cache，命中则直接复用，不做刷新；
 2) 仅在未命中或我明确要求刷新时，才调用 figma-mcp 拉取并写入 mcp-raw（随后再 ensure/upsert）；
-3) completeness 默认使用 layout,text,tokens（若我补充再扩展 interactions/flow/states/assets/accessibility）；
+3) completeness 默认使用 layout,text,tokens,interactions,states,accessibility；仅在命中 flow 白名单时自动补 flow（关系关键词：关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch，或同轮/断续多链接且明确串联意图）；单链接且无关系意图、仅视觉微调、仅资产导出时不要补 flow；资产场景再补 assets；
 4) 原始 MCP 数据统一保存到节点目录 mcp-raw/ 子目录；
 5) 默认不保存 whoami 原始文件（仅鉴权排障或我明确要求时保存）；
-6) 完成后执行 figma:cache:validate，并汇报：缓存状态、实际 MCP 调用次数、输出文件清单。
+6) 完成后执行 figma:cache:validate，并汇报：缓存状态、实际 MCP 调用次数、输出文件清单；若自动补了 flow，额外说明触发原因（关键词命中或多链接串联意图）。
 
 [Figma 链接]
 ```
@@ -196,11 +196,12 @@ npx figma-cache cursor init
 
 ## 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`**。
+- **业务项目（推荐）**：在仓库根执行 **`npx figma-cache cursor init`** 后，本说明会**自动写入或刷新**到 **`figma-cache/docs/colleague-guide-zh.md`**（与 `FIGMA_CACHE_DIR` 一致，默认目录名 `figma-cache/`）。同事 **`@figma-cache/docs/colleague-guide-zh.md`** 即可，**不必**从 `node_modules` 手抄。每次升级包后再跑一次 `cursor init` 即可同步正文。
+- **包内原件**：`node_modules/figma-cache-toolchain/figma-cache/docs/colleague-guide-zh.md`（与上者内容一致，发版随包附带）。
+- **维护工具链源码的仓库**：同路径 **`figma-cache/docs/colleague-guide-zh.md`**。
 
 将本文件全文复制到 IM / 邮件 / 内部文档即可给同事使用。
 
 
 
+

package/figma-cache/docs/figma-cache-adapter-hint.md

@@ -0,0 +1,14 @@
+# Figma 缓存 → UI 实现（目录级提示）
+
+本文件由示例 `postEnsure` 生成，默认放在 **figma-cache 目录级**，用于避免“每个节点重复生成同一提示”。
+
+- **默认来源优先级**：先用 `raw.json` / `spec.md` / `meta.json` / `state-map.md`，仅在缺口或冲突时再读 `mcp-raw/*`
+- **证据约束**：同一设计事实只保留一个主证据来源，避免重复引用
+- **命中检查**：先查本地缓存命中与字段覆盖，再决定是否需要 MCP 补齐
+
+可选模式（环境变量）：
+- `FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root`（默认）
+- `FIGMA_CACHE_ADAPTER_DOC_MODE=node`（按节点写入）
+- `FIGMA_CACHE_ADAPTER_DOC_MODE=off`（关闭）
+
+最近触发：`abcABCd0123456789vWxyZ#1:2`（`2026-04-15T07:24:18.617Z`）