figma-cache-toolchain 1.4.5 → 2.0.1

package/README.md

@@ -32,7 +32,9 @@ npx figma-cache cursor init
 
 该命令会：
 
-- 写入或跳过（已存在且未使用 `--force`）`.cursor/rules/`、`.cursor/skills/`
+- 默认覆盖写入最新 `.cursor/rules/`、`.cursor/skills/` 模板
+- 新增通用规则：`.cursor/rules/00-output-token-budget.mdc`（全任务低 token 输出基线）
+- 若需保留已存在模板，可使用 `npx figma-cache cursor init --force`（跳过同名覆盖）
 - 确保根目录存在 `figma-cache.config.js`
 - 刷新根目录 `AGENT-SETUP-PROMPT.md`
 - 同步刷新 `figma-cache/docs/colleague-guide-zh.md`
@@ -68,6 +70,20 @@ npm run figma:cache:validate
 
 ---
 
+## Cursor 模板固定流程（强制建议）
+
+- 单一真源：仅手工维护 `cursor-bootstrap/` 下的 rules/skills。
+- 镜像目录：`.cursor/` 视为生成产物，不手工编辑。
+- 日常步骤：
+  1) 修改 `cursor-bootstrap/*`
+  2) 运行 `npm run cursor:shadow:sync`
+  3) 运行 `npm run cursor:shadow:check`
+- 守护机制：
+  - CI 会执行 `cursor:shadow:check`，若 `.cursor` 与 `cursor-bootstrap` 不一致将直接失败。
+  - `npm test` 与 `prepack` 也已包含该检查，避免本地漏同步。
+
+---
+
 ## 默认 completeness 与 token 开销
 
 默认 completeness：`layout,text,tokens,interactions,states,accessibility`（默认不含 `flow/assets`）。

package/bin/figma-cache.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 require("../figma-cache/figma-cache.js");

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

@@ -2,6 +2,7 @@
 
 > **给 Cursor Agent 的指令**：你正在操作的是**用户业务项目**的根目录。以下文件应已存在（由 `npx figma-cache cursor init` 从 npm 包 **`{{NPM_PACKAGE_NAME}}`** 复制到当前仓库根）：
 > - `.cursor/rules/01-figma-cache-core.mdc`
+> - `.cursor/rules/00-output-token-budget.mdc`（通用低 token 输出基线）
 > - `.cursor/rules/02-figma-stack-adapter.mdc`（**占位**，任务完成后需删除）
 > - `.cursor/rules/figma-local-cache-first.mdc`（可选保留）
 > - `.cursor/skills/figma-mcp-local-cache/SKILL.md`
@@ -37,6 +38,11 @@
    - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。  
       - **可选**：若项目已通过 `cursor init` 同步 `figma-cache/docs/colleague-guide-zh.md`，提示团队默认只使用 **§5.1「最推荐主提示词」**，只有特殊诉求再追加 **§5.2** 的一句附加要求。
 
+## 输出与 token 约束（强制）
+- 默认“只要结果”：不输出思考过程，不粘贴 MCP 长回包。
+- 执行 Figma MCP 后，用户可见回复只保留：缓存状态、调用次数、产物路径、校验结论、失败修复动作。
+- 除非用户明确要求，禁止在 chat 中贴出 `get_design_context` 全文；原始内容仅保存到 `mcp-raw/*`。
+
 ## 硬约束（违反则视为未完成）
 
 - **不要**修改 `node_modules/{{NPM_PACKAGE_NAME}}/` 下已发布包内文件（应无此必要）。  
@@ -51,4 +57,4 @@
 
 ---
 
-**开始执行：**读完本文件后立刻按上述顺序操作仓库文件，直至全部完成。
+**开始执行：**读完本文件后立刻按上述顺序操作仓库文件，直至全部完成。

package/cursor-bootstrap/rules/00-output-token-budget.mdc

@@ -0,0 +1,29 @@
+---
+description: 通用低 token 输出基线（结果优先，最小回显）
+alwaysApply: true
+---
+
+# Output Token Budget（通用）
+
+适用于所有任务。默认只输出“可执行结果”，避免过程噪音与长回包。
+
+## 默认策略（强制）
+- 结果优先：只给结论、关键变更、验证结果、下一步。
+- 原文最小化：不贴 MCP/终端长日志；仅在用户明确要求时展示。
+- 文件优先：大内容落盘，回复只给路径与摘要。
+- 进度最小化：默认不发中间过程；仅在阻塞/失败时反馈。
+
+## 任务分级（强制）
+- UI/组件实现：读取完整设计证据，回复仅给最终差异与验证。
+- 逻辑/流程/校验：优先 `raw.json` / `spec.md` / `manifest`，避免读无关大文件。
+
+## 失败反馈格式（强制）
+- 固定三段：失败原因 / 定位信息 / 修复动作。
+
+## 例外
+- 用户明确要求“完整输出/日志/原文”时可放宽上述限制。
+
+## 模板维护约定（强制）
+- `cursor-bootstrap` 是规则/技能模板唯一手写来源。
+- 仓库内 `.cursor/*` 视为镜像产物，不作为手工编辑入口。
+- 模板变更后执行 `npm run cursor:shadow:sync`，再提交。

package/cursor-bootstrap/rules/01-figma-cache-core.mdc

@@ -5,104 +5,43 @@ alwaysApply: true
 
 # Figma Cache Core（数据层）
 
-本规则只约束 **Figma → 本地通用缓存** 的流程：标准化 URL、读写 `figma-cache/`、`index.json`、必要时 MCP、校验。**不**在此阶段编写 Vue/React 组件或映射到任何 UI 库；实现代码时由项目 Adapter 规则约束。
-
-## 目标
-- 对用户提供的 Figma 链接，优先复用项目内已落地的结构化文档（`meta.json`、`spec.md`、`raw.json`、`state-map.md` 等）。
-- 仅在本地信息不足以完成任务时调用 Figma MCP。
-- 默认采用 MCP 最小调用集，并按 `completeness` 精确裁剪调用：优先在满足字段目标前提下最少调用工具。
-- 项目级扩展通过仓库根目录的 `figma-cache.config.js` / `.figmacacherc.js` 的 `hooks.postEnsure` 完成；Core 脚本不包含任何具体 UI 框架名。
-
-<Trigger Conditions>
-
-以下任一成立时，Agent **必须**按本规则执行缓存流水线，并在回复**开头**输出「缓存状态 Blockquote」：
-
-1. **显式 Figma URL**：消息含 `figma.com` / `www.figma.com` 的可识别设计链接（`file`、`design`、`proto`、`embed` 等，含或不含 `node-id=`）。
-2. **隐式但可解析为 Figma**：含 `figma` 域名的短链、重定向说明，或「fileKey + node-id」且意图为某一画布节点。
-3. **本地缓存语义**：「figma 缓存」「本地缓存」「先查缓存」「figma-cache」「index.json」「spec.md」「state-map」等，且任务与该缓存相关。
-4. **设计落地/对齐（仅数据侧）**：需先拉齐/刷新设计事实、写入或读取 `figma-cache`，且上下文可解析链接或 `fileKey`/`node-id`。
-5. **显式跳过/刷新**：「跳过缓存」「强制刷新」「以 Figma 最新为准」——可走 MCP，Blockquote 标「更新」、来源 MCP。
-
-**不触发**：纯概念讨论、无可解析链接/键/节点线索、且与缓存目录无关。
-
-</Trigger Conditions>
-
-## 执行顺序
-1. 按 `figma-cache/docs/link-normalization-spec.md` 标准化链接。
-2. 读本地 `index.json` 判断是否命中。
-3. 命中且字段满足任务 → 只读本地，不调 MCP。
-4. 未命中或不足 → MCP 拉取并回写通用缓存文件。
-5. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅负责索引与骨架文件，不视为 MCP 拉取动作；不得把“执行 ensure”当作“已完成 MCP 调用”。
-6. **MCP 最小调用集（默认）**：以单个 `fileKey + nodeId` 为粒度，默认只调用 `get_design_context`（建议 `excludeScreenshot=true`）、`get_metadata`、`get_variable_defs`；禁止同参数重复调用同一工具。
-7. **按需调用策略**：`get_screenshot` 仅在用户显式要求可视留档/截图回包，或上述三项仍不足以消除结构歧义时调用；`whoami` 仅在鉴权/权限报错时调用，不作为常规流程步骤。
-8. **按 completeness 的调用矩阵（强制）**：
-   - `layout` → `get_metadata`（若结构层级不足，再补 `get_design_context`）
-   - `text` → `get_design_context`
-   - `tokens` → `get_variable_defs`
-   - `interactions` / `flow` / `states` → `get_design_context` + `state-map.md`/`flows` 回写
-   - `accessibility`（若任务声明）→ 优先 `get_design_context` 的语义线索，不足时标注缺口
-   - `assets`（若任务声明）→ `get_design_context` 中资产 URL；仅当用户要求截图留档再调 `get_screenshot`
-   - **flow 自动追加白名单（强制）**：默认 completeness 基线为 `layout,text,tokens,interactions,states,accessibility`（不含 `flow`）；仅在命中白名单时自动追加 `flow`：
-     - 用户明确表达关系/流程意图，且语义命中关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
-     - 同轮或断续出现多个 Figma 链接，且存在明确先后或串联意图（如 A->B）
-     - 单链接且无关系意图、仅视觉微调、仅资产导出时，禁止自动追加 `flow`
-9. **两阶段拉取**：先按最小必要工具取数并检查字段缺口；仅在缺口存在时进入第二阶段补调工具。
-10. **写入一致性门禁（强制）**：当 `source=figma-mcp` 或输出来源标注 MCP 时，节点目录必须存在 `mcp-raw/` 与对应原始文件；若缺失则视为未完成，必须停止并报告，不得宣称“更新成功”。
-11. **严格证据门禁（强制）**：当 `source=figma-mcp` 且未显式传入 `--allow-skeleton-with-figma-mcp` 时，`upsert/ensure` 必须在写入前校验 `mcp-raw` 证据：
-   - `layout` 至少命中 `get_metadata` 或 `get_design_context`
-   - `text/interactions/states/accessibility/flow/assets` 必须命中 `get_design_context`
-   - `tokens` 必须命中 `get_variable_defs`
-   任一维度缺证据即失败退出，不得写入成功状态。
-12. **严格 validate（强制）**：`validate` 不仅校验索引字段，还校验证据完整性：
-   - `completeness` 声明的维度必须在 `raw.json.coverageSummary.evidence` 中提供非空证据
-   - 对 `source=figma-mcp` 且声明 `interactions/states/accessibility` 的节点，禁止保留 TODO 占位内容
-13. **大文件读取策略（强制）**：仅在 UI 还原/像素对齐/组件实现任务中读取 `mcp-raw-get-design-context.txt` 全文；非 UI 任务（命中检查、预算统计、校验、流程维护）默认仅读取 `raw.json` / `spec.md` / `mcp-raw-manifest.json`。
-14. **闭环校验（强制）**：每次 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`** 成功结束后，**自动静默**执行 `npm run figma:cache:validate`。
-15. validate 失败 → **自行修复并重复 validate 直至通过**，不得宣称缓存已就绪。
-16. **不写前端**：本阶段禁止输出业务组件实现；若用户要求写 UI，在缓存就绪后转由 **栈专属 Adapter 规则**（如 `02-figma-stack-adapter.mdc` 占位，或项目内 `02-figma-<栈>-adapter.mdc`）接管。
-
-## Agent 最终输出格式（强制）
-凡触发 `<Trigger Conditions>` 且本轮涉及缓存读写的回复，**正文第一段**必须为单行 Blockquote：
-
-`> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
-
-（语义与 `index.json` 中 `nodeId` / `__FILE__` 约定同前；Blockquote 后再写结论。）
-
-- 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
-
-## 配置与钩子
-- `npm run figma:cache:config` 可查看是否加载 `hooks.postEnsure`。
-- `ensure` 在写入通用骨架后会调用 `hooks.postEnsure`；钩子异常**不得**阻断 ensure 成功退出（由 Core 捕获）。
-- `ensure` 不是 MCP 拉取入口；若命令声明 `source=figma-mcp`，应先完成 MCP 工具调用并落盘 `mcp-raw/`，再进行 upsert/ensure。
-
-## 其余约定
-- 缓存目录、环境变量、`flows`、陈旧策略、提交前校验等与原「Local Cache First」一致，参见 `figma-cache/` 内文档及 `npm run figma:cache:*`。
-- 对同一节点写缓存时，优先复用本轮已拿到的 MCP 响应做落盘，避免“仅为生成原始文件而重复调同一工具”。
-- 若保存原始数据，统一写入节点目录下 `mcp-raw/` 子目录（如 `mcp-raw/mcp-raw-get-design-context.txt`），与加工缓存文件分层。
-- 默认不写 `whoami` 原始文件；仅在鉴权排障或用户显式要求账号态审计时才写入。
-- 单节点 MCP 调用预算默认不超过 3 次；超过时必须在输出中说明缺口字段与补调原因。
-- 仅对超时/5xx做指数退避重试；对参数错误/权限错误不重试，直接报告并等待用户指令。
-- 不在未校验时假定 Figma 为最新；用户显式要求实时读取时须遵守。
-## Encoding, Shell 兼容与安全写入（强制）
-- 仓库内 README / mdc / SKILL / json / js 等文本文件默认使用 **UTF-8 无 BOM**。
-- Node 写文件必须显式指定 utf8（如 writeFileSync(path, text, "utf8")）。
-- 在 Windows PowerShell 下，**禁止**把 Set-Content / Out-File -Encoding utf8 作为 js/mdc/md/json 的默认写入方式（可能写出 BOM）。
-- 若必须用 PowerShell 写文本文件，使用无 BOM 写法：
-  - `$enc = New-Object System.Text.UTF8Encoding($false)`
-  - `[System.IO.File]::WriteAllText($path, $text, $enc)`
-
-## Shell 语法兼容（PowerShell 强制）
-- 当前终端为 PowerShell 时，**禁止**使用 bash heredoc（如 `<<'EOF'`、`<<'PY'`）。
-- 当前终端为 PowerShell 时，命令串联默认使用 `;`（或拆成多次调用），**禁止**使用 `&&`。
-- 多行文本注入优先使用 PowerShell here-string（`@' ... '@` 或 `@" ... "@`）。
-- 文本替换时，禁止把字面量 `\n` / `` `n `` 当作真实换行依赖；必须写入真实换行并回读确认。
-
-## 写后必检（强制）
-- 每次脚本化写入后，必须立刻回读目标文件，确认无字面量 `\n`、`` `n ``、乱码、截断。
-- 对 shebang 文件（如 `#!/usr/bin/env node`），必须确认文件首字节无 BOM。
-- 修改 README / rules / skills 后，必须执行 `npm run docs:encoding:check`（或等价编码检查）并确认通过。
-
-## 故障恢复（强制）
-- 一旦出现 BOM、乱码、PowerShell 语法不兼容、转义换行误写，立即停止增量替换。
-- 先回读定位受影响文件，再用 UTF-8 无 BOM 方式整段重写，最后重新执行验证命令。
+边界：仅处理 Figma -> 本地缓存数据（标准化、索引、MCP、校验）；本阶段禁止写业务 UI。
+
+## 触发条件（任一命中即执行）
+- 消息包含可解析 Figma 链接、`fileKey+nodeId`、或明确“figma-cache/本地缓存/刷新”语义。
+- 非触发：纯概念讨论且无可解析链接/节点线索。
+
+## 标准流程（强制）
+1. 标准化链接并读取 `figma-cache/index.json`。
+2. 命中且字段足够：只读本地，不调 MCP。
+3. 未命中或字段不足：调用 MCP 最小集并落盘：
+   - `get_design_context`（默认 `excludeScreenshot=true`）
+   - `get_metadata`
+   - `get_variable_defs`
+4. 同参数工具不得重复调用；`get_screenshot` 仅在显式要求截图或结构仍有歧义时调用；`whoami` 仅鉴权报错时调用。
+5. `source=figma-mcp` 时必须先有 `mcp-raw/*` 证据与 `mcp-raw-manifest.json`（含 `files/fileHashes/fileSizes/toolCalls`）。
+6. 每次写完 `mcp-raw` 立即做反精简检查（截断标记 + hash/size 一致性）。
+7. 执行 `upsert/ensure` 后必须自动执行 `validate`；失败需自修复并循环直到通过。
+
+## completeness 规则（强制）
+- 默认基线：`layout,text,tokens,interactions,states,accessibility`。
+- 映射：
+  - `layout` -> `get_metadata`（不足再补 `get_design_context`）
+  - `text/interactions/states/accessibility` -> `get_design_context`
+  - `tokens` -> `get_variable_defs`
+- `flow` 仅在白名单触发时追加：
+  - 关系关键词命中（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch）
+  - 或多链接且有明确串联意图
+- `assets` 按需开启，非默认维度。
+
+## 输出格式（强制）
+- 命中触发且涉及缓存读写时，首行必须：
+  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
+- 仅输出：`mcp-raw anti-truncation`、MCP 调用统计、completeness、产物路径、validate 结果。
+- 自动追加 `flow` 时必须标注触发原因（关键词命中/多链接串联意图）。
+
+## 低 token 与编码（强制）
+- 用户可见回复禁止粘贴 MCP 长原文；除非用户明确要求。
+- 进度默认 0-1 条；仅阻塞或失败时补充。
+- 文档与脚本写入统一 UTF-8（无 BOM）；PowerShell 禁用 bash heredoc，写后回读并执行必要校验（如 `npm run docs:encoding:check`）。
 

package/cursor-bootstrap/skills/figma-mcp-local-cache/SKILL.md

@@ -5,178 +5,33 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 
 # Figma MCP Local Cache
 
-本 Skill 与仓库规则 **`.cursor/rules/01-figma-cache-core.mdc`** **对齐**（表现层见栈占位 `02-figma-stack-adapter.mdc` 或你项目内的 `02-figma-<栈>-adapter.mdc`）：触发条件、闭环校验、回复开头 Blockquote **均为强制**。
+本 Skill 仅定义“执行次序与最小输出”。权威约束以 `.cursor/rules/01-figma-cache-core.mdc` 为准；若冲突，以规则文件为准。
 
-<Trigger Conditions>
+## 触发
+- 用户消息包含 Figma URL、`fileKey+nodeId`、或“figma 缓存/本地缓存/刷新”语义时触发。
 
-满足以下任一模式时，Agent **必须**进入本 Skill 的标准流程（标准化 → 读索引 → 本地或 MCP → 写回 → **upsert/ensure 后 validate**），并在用户可见回复**首段**输出规则所要求的缓存状态 Blockquote：
-
-| 类型 | 用户原话 / 消息特征（示例模式，非穷举） |
-| --- | --- |
-| URL | 含 `https://www.figma.com/`、`http://figma.com/`、`figma.com/file/`、`figma.com/design/`、`figma.com/proto/`、`figma.com/embed` 等 |
-| 参数 | 含 `node-id=`、`type=design` 等与 Figma 链接常见的查询串 |
-| 键值 | 出现 `figma` 文件 key（约 22 字符）且同时出现 `node-id` /「节点」描述，意图为对齐某一节点 |
-| 缓存词 | 「figma 缓存」「本地缓存」「先查缓存」「figma-cache」「index.json」「spec.md」「state-map」「命中/未命中」等且与具体设计任务绑定 |
-| 落地词 | 「按 Figma 做」「还原设计稿」「对齐 Figma」「实现该节点」且上下文可解析出链接或 fileKey/node |
-| 刷新词 | 「跳过缓存」「强制刷新」「以 Figma 最新为准」——走 MCP 与回写，状态标「更新」、来源 MCP |
-
-未出现可解析链接/键/节点且纯概念讨论时，可不执行缓存流水线。
-
-</Trigger Conditions>
-
-## 适用场景
-- 用户提供新的 Figma 链接并要求解析设计信息。
-- 用户再次提供同一 Figma 文件或同一 node-id，期望复用历史结果。
-- 用户明确要求「先查本地，不够再调 MCP」。
-
-## 目录约定
-- 缓存根目录（默认）：`figma-cache/`
-- 索引文件（默认）：`figma-cache/index.json`
-- 单链接缓存目录：`figma-cache/files/<fileKey>/nodes/<nodeId>/`
-- 单链接缓存文件：
-  - `meta.json`：基础元数据与来源信息
-  - `spec.md`：可读规格摘要
-  - `state-map.md`：状态与交互映射（如适用）
-  - `raw.json`：必要的原始结构化数据摘录
-- 可配置项：
-  - `FIGMA_CACHE_DIR`：缓存根目录
-  - `FIGMA_CACHE_INDEX_FILE`：索引文件名或绝对路径
-  - `FIGMA_ITERATIONS_DIR`：历史回填目录
-  - `FIGMA_CACHE_STALE_DAYS`：陈旧阈值（天）
-  - `FIGMA_DEFAULT_FLOW`：默认 flowId（大迭代可减少重复 `--flow`）
-
-## 流程关系（Flow）
-- `figma-cache/index.json` 中的 `flows` 用于维护业务/交互流程的节点集合与边关系。
-- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
-- 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
-- flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
-- 不触发：单链接且无关系意图、仅视觉微调、仅资产导出。
-
-## 标准流程
-1. 按 `figma-cache/docs/link-normalization-spec.md` 标准化链接并生成键：
-   - 节点级：`cacheKey = <fileKey>#<nodeId>`
-   - 文件级（无 `node-id`）：`cacheKey = <fileKey>#__FILE__`
-2. 读取 `index.json`：
-   - 若命中且字段满足当前任务，直接读取本地缓存并继续实现。
-   - 若未命中或信息不足，再调用 Figma MCP 拉取缺失数据。
-3. 若需调用 MCP，默认按 **最小调用集**执行（同一 `fileKey + nodeId`）：
-   - `get_design_context`（建议 `excludeScreenshot=true`）
+## 执行清单（按序）
+1. 标准化链接，先查 `figma-cache/index.json`（`figma:cache:get`）。
+2. 命中且字段足够：复用本地缓存，结束。
+3. 未命中/不足：仅调最小 MCP 集（默认）：
+   - `get_design_context`（`excludeScreenshot=true`）
    - `get_metadata`
    - `get_variable_defs`
-4. **按需扩展调用**：
-   - `get_screenshot` 仅在用户明确要求截图原始留档，或前三项不足以消除结构歧义时调用。
-   - `whoami` 仅在鉴权/权限报错时调用；无报错时不调用。
-5. **`get_design_context` 单轮硬约束**：同一 `fileKey + nodeId` 下，若已成功调用一次 `get_design_context`，除非参数发生变化（如 `forceCode`、`disableCodeConnect`、`excludeScreenshot`）或出现明确报错，否则禁止再次调用。
-6. **按 completeness 的调用矩阵（强制）**：
-   - `layout` → `get_metadata`（若结构层级不足，再补 `get_design_context`）
-   - `text` → `get_design_context`
-   - `tokens` → `get_variable_defs`
-   - `interactions` / `flow` / `states` → `get_design_context`，并同步完善 `state-map.md` / `flows`
-   - `accessibility`（若任务声明）→ 优先 `get_design_context` 语义线索，不足需显式标注缺口
-   - `assets`（若任务声明）→ 使用 `get_design_context` 资产 URL；截图按需
-7. **两阶段拉取**：先最小必要调用并检查字段缺口；仅在缺口存在时补调。
-8. 同一参数的 MCP 工具在单轮内不得重复调用；若需落盘原始数据，必须优先复用首次响应。
-9. **原始大文本直存策略**：当需保存 `mcp-raw-get-design-context.txt` 时，优先直接写入 `mcp-raw/` 子目录（不改写、不摘要、不二次解释），避免把整段文本再次喂给模型。
-10. **本地分析优先**：若本地已存在可用 `mcp-raw-*` 与缓存加工文件，且用户未要求刷新/强制最新，后续分析默认只读本地文件，不再调用 Figma MCP。
-11. 发生 MCP 拉取或本地补齐时，写入/更新 `meta.json`、`spec.md`、必要补充文件，并更新索引。
-12. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅补齐索引与骨架文件，不能替代 MCP 拉取；不得把“执行了 ensure”当成“完成了 figma-mcp 调用”。
-13. **MCP 证据门禁（强制）**：当输出来源声明为 `figma-mcp` 时，节点目录必须存在 `mcp-raw/` 及最小调用集原始回包（按 completeness 裁剪）；若缺失，立即停止并报告“未完成”，不得宣称更新成功。
-14. **调用预算**：单节点默认 MCP 调用不超过 3 次；超过时必须在回复中说明缺口字段与补调理由。
-15. **重试策略**：仅对超时/5xx进行指数退避重试；参数错误/权限错误不重试并直接报告。
-16. **大文件读取策略（强制）**：仅在“UI 还原/像素对齐/组件实现”任务时读取 `mcp-raw-get-design-context.txt` 全文；非 UI 实现任务（如命中检查、预算统计、校验、流程维护）默认只读 `raw.json`/`spec.md`/`mcp-raw-manifest.json`，避免无意义 token 消耗。
-17. **闭环校验（强制）**：凡本轮执行了 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`**（任意参数组合），在命令成功结束后，Agent **必须**在同一仓库根目录**自动、静默**执行 `npm run figma:cache:validate`。
-18. **校验失败**：根据脚本输出修复索引、`paths`、缺失文件、JSON 结构等，**循环执行 validate 直至退出码为 0**；不得在 validate 未通过时结束本轮「写缓存」任务。
-19. 对用户反馈时除 Blockquote 外可补充：`source: local-cache` / `source: figma-mcp` 与简要文件列表（不必粘贴完整终端日志）。
-
-## Agent 最终输出格式（强制）
-- 触发 `<Trigger Conditions>` 且本轮触碰缓存读写的回复，**第一段**必须为单行 Blockquote：
-  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
-- `nodeId` 与索引一致；文件级写 `__FILE__` 或与 `index.json` 相同的占位。
-- Blockquote 之后接任务正文。
+4. 原始回包写入 `mcp-raw/`，并写 `mcp-raw-manifest.json`（必须含 `files/fileHashes/fileSizes/toolCalls`）。
+5. 立即执行反精简检查（截断标记 + hash/size）并记录结果。
+6. 执行 `upsert/ensure` 后自动执行 `validate`；失败时自修复并循环到通过。
 
-## 执行责任
-- 默认由 agent 执行缓存查询、写入、**upsert/ensure 后的 validate**、失败自修复与回填，用户不需要手动执行命令。
-- 仅当用户明确要求「我自己执行」或「请给我命令」时，才提供命令让用户手动运行。
-- 在常规对话中，以「已自动完成」方式汇报，不要求用户额外操作。
+## 关键约束
+- 禁止同参数重复调用 MCP。
+- `flow` 非默认维度，仅白名单触发时追加，并在回复说明原因。
+- 缓存任务默认不写业务 UI 代码。
 
-## 索引建议结构
-```json
-{
-  "schemaVersion": 2,
-  "version": 1,
-  "updatedAt": "2026-04-14T12:00:00Z",
-  "flows": {
-    "example-flow": {
-      "id": "example-flow",
-      "title": "Example",
-      "nodes": ["xxxx#12:34"],
-      "edges": [
-        {
-          "id": "edge-1",
-          "from": "xxxx#12:34",
-          "to": "xxxx#56:78",
-          "type": "next_step",
-          "note": "",
-          "createdAt": "2026-04-14T12:00:00Z"
-        }
-      ],
-      "assumptions": [],
-      "openQuestions": []
-    }
-  },
-  "items": {
-    "fileKey#nodeId": {
-      "fileKey": "xxxx",
-      "nodeId": "12:34",
-      "scope": "node",
-      "url": "https://www.figma.com/file/xxxx?node-id=12%3A34",
-      "originalUrls": [
-        "https://www.figma.com/file/xxxx?node-id=12%3A34&t=abc",
-        "https://www.figma.com/design/xxxx?node-id=12:34"
-      ],
-      "normalizationVersion": 1,
-      "paths": {
-        "meta": "figma-cache/files/xxxx/nodes/12-34/meta.json",
-        "spec": "figma-cache/files/xxxx/nodes/12-34/spec.md",
-        "stateMap": "figma-cache/files/xxxx/nodes/12-34/state-map.md",
-        "raw": "figma-cache/files/xxxx/nodes/12-34/raw.json"
-      },
-      "syncedAt": "2026-04-14T12:00:00Z",
-      "completeness": ["layout", "text", "tokens", "interactions", "states", "accessibility"]
-    }
-  }
-}
-```
-
-## 刷新策略
-- 用户说「强制刷新/以最新 Figma 为准」：直接走 MCP，并覆盖 `syncedAt` 与内容；Blockquote 标「更新」、来源 MCP。
-- 仅缺某些字段：执行部分刷新，保留已有内容，更新 `completeness`。
-- 若链接无 `node-id`，先缓存到文件级（`__FILE__`），再按后续 node 增量补充。
-- 当 `syncedAt` 超过 14 天时，默认先提示用户是否刷新。
-- 若需“保存 MCP 原始数据”，默认保存最小调用集三项原始回包；截图原始回包按需保存。
-- 原始数据统一写到节点目录 `mcp-raw/` 子目录；加工缓存继续放在节点根目录（`meta.json` / `raw.json` / `spec.md` / `state-map.md`）。
-- 默认不保存 `whoami` 原始文件；仅在鉴权排障或用户显式要求时保存。
-- 对 `mcp-raw-get-design-context.txt` 优先采用“直存”方式（不二次改写正文），降低 token 消耗并保持可追溯性。
-- `completeness` 建议至少按以下维度声明：`layout`、`text`、`tokens`、`interactions`、`flow`、`states`、`assets`、`accessibility`（按任务取子集）。
-- `mcp-raw-manifest.json` 应包含审计字段：`callPolicy`（如 `minimum-set-v1`）、`dedupeApplied`（布尔）、`toolCalls`（每个工具的 `count` / `effectiveSaved`），便于后续统计与复盘。
-- 折中推荐：在 `raw.json` 增加 `coverageSummary`（`covered` / `missing` / `evidence`）用于最小覆盖审计，不强制完整模板。
-
-## 输出约束
-- **必须先**输出规定的缓存状态 Blockquote，再给出设计结论或实现说明。
-- 若跳过 MCP，Blockquote 中来源为 Local，状态多为「命中」。
-- 若调用 MCP，Blockquote 中来源为 MCP，状态多为「缺失→更新」或「更新」，并在后文简述触发原因（未命中/信息不足/用户强刷）。
+## 用户可见输出（最小化）
+- 首行固定：
+  - `> 🔄 Figma 缓存状态: [命中|缺失|更新] | 来源: [Local|MCP] | 节点: {nodeId}`
+- 仅补充：`mcp-raw anti-truncation`、MCP 调用统计、最终 completeness、文件清单、validate 结果。
+- 除非用户明确要求，禁止贴 MCP 原文与长日志。
 
-## 推荐命令（v2 流程）
-- `npm run figma:cache:init`：初始化空索引（用于纯净移植）
-- `npm run figma:cache:config`：查看当前生效配置
-- `npm run figma:cache:get -- "<figma-url>"`：检查命中情况
-- 先执行 MCP 最小调用集并写入 `mcp-raw/`，再执行：`npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility`
-- `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility`：自动补齐缓存骨架文件（非 MCP 拉取）
-- 若命中 flow 白名单场景，自动或显式追加：`--completeness=layout,text,tokens,interactions,states,accessibility,flow`
-- 一旦自动追加了 `flow`，对用户回复必须附带触发原因：`关键词命中` 或 `多链接串联意图`。
-- MCP 默认最小调用集：`get_design_context(excludeScreenshot=true)` + `get_metadata` + `get_variable_defs`
-- `npm run figma:cache:validate`：**每次 upsert/ensure 成功后必须自动执行**；失败则修至通过
-- `npm run figma:cache:budget`：查看 MCP 节点预算汇总（默认 `--mcp-only`，按文件大小估算 token 代理）
-- `npm run figma:cache:stale`：检查超 14 天的陈旧缓存
-- `npm run figma:cache:backfill`：从历史迭代文档回填索引
-- `npm run figma:cache:flow:init|add-node|link|chain|show|mermaid`：维护流程关系
+## 模板维护约定（强制）
+- `cursor-bootstrap` 是 Skill 唯一手写来源。
+- 仓库内 `.cursor/skills/*` 为镜像产物，使用 `npm run cursor:shadow:sync` 同步生成。

package/figma-cache/docs/README.md

@@ -53,22 +53,22 @@ $env:FIGMA_DEFAULT_FLOW="sip-calling-phase1"
 npm run figma:cache:config
 ```
 
-## 常用命令（通常由 agent 自动执行）
-
-- `npm run figma:cache:init`
-- `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:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
-- `npm run figma:cache:ensure -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
-- 若不传 `--completeness`，CLI 默认即使用：`layout,text,tokens,interactions,states,accessibility`
-- 自动追加 `flow` 仅限白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确先后/串联意图
-- 单链接且无关系意图、仅视觉微调、仅资产导出时，不自动追加 `flow`
-- 若自动追加了 `flow`，Agent 输出中必须记录触发原因：`关键词命中` 或 `多链接串联意图`
-- `npm run figma:cache:validate`
-- `npm run figma:cache:budget`（默认 `--mcp-only`）
-- `npm run figma:cache:stale`
-- `npm run figma:cache:backfill`
+## 常用命令（通常由 agent 自动执行）
+
+- `npm run figma:cache:init`
+- `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:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
+- `npm run figma:cache:ensure -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
+- 若不传 `--completeness`，CLI 默认即使用：`layout,text,tokens,interactions,states,accessibility`
+- 自动追加 `flow` 仅限白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确先后/串联意图
+- 单链接且无关系意图、仅视觉微调、仅资产导出时，不自动追加 `flow`
+- 若自动追加了 `flow`，Agent 输出中必须记录触发原因：`关键词命中` 或 `多链接串联意图`
+- `npm run figma:cache:validate`
+- `npm run figma:cache:budget`（默认 `--mcp-only`）
+- `npm run figma:cache:stale`
+- `npm run figma:cache:backfill`
 > 注意：`ensure` 默认职责是“写索引 + 生成骨架文件”，不是 MCP 拉取器。  
 > 当 `upsert/ensure` 传 `--source=figma-mcp` 且未显式允许骨架模式时，CLI 会先执行 MCP 原始证据门禁（缺失即失败，退出码 2）。
 > 正确流程是先由 Agent/Figma MCP 获取最小调用集并写入 `mcp-raw/`，再执行 `upsert/ensure` 与 `validate`。
@@ -77,6 +77,7 @@ npm run figma:cache:config
 
 - `validate` 会检查 `raw.json.coverageSummary.evidence` 与 `completeness` 是否一致。
 - 当 `source=figma-mcp` 且声明 `interactions/states/accessibility` 时，不允许保留 TODO 占位说明。
+- `validate` 会检查 `mcp-raw-manifest.json` 的 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数），并逐项比对原始文件；缺失或不一致会直接失败。
 - 若你仅想先落骨架，可使用 `--allow-skeleton-with-figma-mcp`（仅放行 upsert/ensure 写入，不放行 validate）；后续必须补齐证据并通过 `validate`。
 
 ### 预算统计（token/调用）
@@ -133,7 +134,7 @@ npm run figma:cache:init
 - **项目根**仍需：`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` 均刷新**。
+说明：Cursor **不会**在 `npm install` 时写入 `.cursor/`；`npx figma-cache cursor init` 负责从包内复制模板。`cursor init` 默认**覆盖**同名模板为最新版本（`--force` 可改为保留已有模板并跳过覆盖）；并会下发通用低 token 规则 `00-output-token-budget.mdc`；**`AGENT-SETUP-PROMPT.md` 每次 `cursor init` 均刷新**。
 
 ## package.json scripts 示例
 
@@ -179,9 +180,9 @@ npm run figma:cache:init
 | `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
 | `FIGMA_DEFAULT_FLOW` | 默认 `flowId`（大迭代推荐设置） |
 | `FIGMA_CACHE_ADAPTER_DOC` | 覆盖 adapter 提示文档基础名（默认 `figma-cache-adapter-hint.md`） |
-| `FIGMA_CACHE_ADAPTER_DOC_MODE` | adapter 提示写入模式：`cache-root`（默认，目录级单文件）/ `node`（按节点）/ `off`（关闭） |
-| `FIGMA_CACHE_ADAPTER_DOC_CACHE` | `cache-root` 模式下 adapter 提示文档路径（相对项目根，默认 `figma-cache/docs/figma-cache-adapter-hint.md`） |
-| `FIGMA_CACHE_ADAPTER_DOC_WRITE_POLICY` | adapter 提示写入策略：`if-missing`（默认）/ `always` |
+| `FIGMA_CACHE_ADAPTER_DOC_MODE` | adapter 提示写入模式：`cache-root`（默认，目录级单文件）/ `node`（按节点）/ `off`（关闭） |
+| `FIGMA_CACHE_ADAPTER_DOC_CACHE` | `cache-root` 模式下 adapter 提示文档路径（相对项目根，默认 `figma-cache/docs/figma-cache-adapter-hint.md`） |
+| `FIGMA_CACHE_ADAPTER_DOC_WRITE_POLICY` | adapter 提示写入策略：`if-missing`（默认）/ `always` |
 | `FIGMA_CACHE_FLOW_README` | **仅包内示例钩子**：人类可读的「流程 / 需求总览」Markdown 相对路径，默认 **`docs/figma-flow-readme.md`**；每次 `ensure` 对**新 cacheKey** 幂等追加一节 |
 
 ## 人工校验清单（对照 `validate`）

package/figma-cache/figma-cache.js

@@ -17,13 +17,13 @@ const { createProjectConfigService } = require("./js/project-config");
 const ROOT = process.cwd();
 const NORMALIZATION_VERSION = 1;
 const SCHEMA_VERSION = 2;
-const DEFAULT_COMPLETENESS = Object.freeze([
-  "layout",
-  "text",
-  "tokens",
-  "interactions",
-  "states",
-  "accessibility",
+const DEFAULT_COMPLETENESS = Object.freeze([
+  "layout",
+  "text",
+  "tokens",
+  "interactions",
+  "states",
+  "accessibility",
 ]);
 const COMPLETENESS_ALL_DIMENSIONS = Object.freeze([
   "layout",
@@ -353,7 +353,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 + ensure figma-cache.config.js (+ cleanup safe legacy example) + refresh AGENT-SETUP-PROMPT.md + sync colleague-guide-zh.md into FIGMA_CACHE_DIR`,
+      `${ex} cursor init [--force]  # default: overwrite .cursor templates with latest bootstrap; --force keeps existing templates (skip overwrite)`,
     );
     process.exit(1);
   }
@@ -361,7 +361,9 @@ function run() {
   if (cmd === "cursor") {
     const sub = args[0];
     if (sub !== "init") {
-      console.error("Usage: figma-cache cursor init [--force]");
+      console.error(
+        "Usage: figma-cache cursor init [--force]  # default overwrite; --force keeps existing templates",
+      );
       process.exit(1);
     }
     const force = args.includes("--force");

package/figma-cache/js/cursor-bootstrap-cli.js

@@ -20,6 +20,10 @@ function copyCursorBootstrap(force, deps) {
   } = deps;
 
   const pairs = [
+    {
+      from: path.join("rules", "00-output-token-budget.mdc"),
+      to: path.join(".cursor", "rules", "00-output-token-budget.mdc"),
+    },
     {
       from: path.join("rules", "01-figma-cache-core.mdc"),
       to: path.join(".cursor", "rules", "01-figma-cache-core.mdc"),
@@ -45,6 +49,7 @@ function copyCursorBootstrap(force, deps) {
     process.exit(1);
   }
 
+  const overwrite = !force;
   let copied = 0;
   let skipped = 0;
   pairs.forEach(({ from: relFrom, to: relTo }) => {
@@ -55,7 +60,7 @@ function copyCursorBootstrap(force, deps) {
       process.exit(1);
     }
     fs.mkdirSync(path.dirname(absTo), { recursive: true });
-    if (fs.existsSync(absTo) && !force) {
+    if (fs.existsSync(absTo) && !overwrite) {
       skipped += 1;
       return;
     }
@@ -137,8 +142,11 @@ function copyCursorBootstrap(force, deps) {
         copied,
         skipped,
         force: !!force,
+        overwriteByDefault: overwrite,
         hint: skipped
-          ? "Some template files were skipped (already exist). Re-run with --force to overwrite."
+          ? "Some template files were skipped (--force means keep existing files)."
+          : overwrite
+          ? "Done. Existing .cursor templates were overwritten by latest bootstrap."
           : "Done.",
         configFile: normalizeSlash(projectConfigPath),
         configAction,
@@ -174,5 +182,5 @@ function copyCursorBootstrap(force, deps) {
 
 module.exports = {
   copyCursorBootstrap,
-};
-
+};
+

package/figma-cache/js/entry-files.js

@@ -21,6 +21,224 @@ function createEntryFilesService(deps) {
     }
   }
 
+  function safeReadText(absPath) {
+    try {
+      return fs.readFileSync(absPath, "utf8");
+    } catch {
+      return "";
+    }
+  }
+
+  function safeReadJson(absPath) {
+    try {
+      return JSON.parse(fs.readFileSync(absPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  function isPlaceholderText(input) {
+    const text = String(input || "");
+    return /(TODO|TBD|待补充|待完善|待确认|占位)/i.test(text);
+  }
+
+  function findNodeDirByItem(item) {
+    if (!item || !item.paths || !item.paths.meta) {
+      return "";
+    }
+    const metaAbs = resolveMaybeAbsolutePath(item.paths.meta);
+    return path.dirname(metaAbs);
+  }
+
+  function readMcpEvidence(item) {
+    const nodeDir = findNodeDirByItem(item);
+    if (!nodeDir) {
+      return null;
+    }
+    const mcpRawDir = path.join(nodeDir, "mcp-raw");
+    const manifestAbs = path.join(mcpRawDir, "mcp-raw-manifest.json");
+    const manifest = safeReadJson(manifestAbs);
+    if (!manifest || !manifest.files || typeof manifest.files !== "object") {
+      return null;
+    }
+    const filesMap = manifest.files;
+    const designContextPath = filesMap.get_design_context
+      ? path.join(mcpRawDir, String(filesMap.get_design_context))
+      : "";
+    const metadataPath = filesMap.get_metadata
+      ? path.join(mcpRawDir, String(filesMap.get_metadata))
+      : "";
+    const variableDefsPath = filesMap.get_variable_defs
+      ? path.join(mcpRawDir, String(filesMap.get_variable_defs))
+      : "";
+
+    const designContextText = designContextPath ? safeReadText(designContextPath) : "";
+    const metadataText = metadataPath ? safeReadText(metadataPath) : "";
+    const variableDefs = variableDefsPath ? safeReadJson(variableDefsPath) : null;
+
+    return {
+      designContextText,
+      metadataText,
+      variableDefs,
+    };
+  }
+
+  function extractLayoutSummary(metadataText, fallbackName) {
+    const text = String(metadataText || "");
+    const idMatch = text.match(/id="([^"]+)"/);
+    const nameMatch = text.match(/name="([^"]+)"/);
+    const xMatch = text.match(/x="([^"]+)"/);
+    const yMatch = text.match(/y="([^"]+)"/);
+    const widthMatch = text.match(/width="([^"]+)"/);
+    const heightMatch = text.match(/height="([^"]+)"/);
+    const name = nameMatch ? nameMatch[1] : fallbackName || "Unknown";
+    const id = idMatch ? idMatch[1] : "N/A";
+    const pos = xMatch && yMatch ? `${xMatch[1]}, ${yMatch[1]}` : "N/A";
+    const size = widthMatch && heightMatch ? `${widthMatch[1]} x ${heightMatch[1]}` : "N/A";
+    return { id, name, pos, size };
+  }
+
+  function extractTextCandidates(designContextText) {
+    const text = String(designContextText || "");
+    const regex = /<p[^>]*>\s*([^<\n][^<]{0,120})\s*<\/p>/g;
+    const output = [];
+    let match = null;
+    while ((match = regex.exec(text))) {
+      const value = String(match[1] || "").replace(/\s+/g, " ").trim();
+      if (!value) {
+        continue;
+      }
+      if (output.includes(value)) {
+        continue;
+      }
+      output.push(value);
+      if (output.length >= 6) {
+        break;
+      }
+    }
+    return output;
+  }
+
+  function extractTokenCandidates(variableDefs) {
+    if (!variableDefs || typeof variableDefs !== "object") {
+      return [];
+    }
+    return Object.entries(variableDefs)
+      .slice(0, 10)
+      .map(([key, value]) => `- ${key}: ${String(value)}`);
+  }
+
+  function buildMcpHydratedSpecContent(item, evidence) {
+    const completeness = normalizeCompletenessList(item.completeness);
+    const layout = extractLayoutSummary(evidence.metadataText, item.nodeId || "N/A");
+    const textItems = extractTextCandidates(evidence.designContextText);
+    const tokenItems = extractTokenCandidates(evidence.variableDefs);
+    const textSection = textItems.length
+      ? textItems.map((line) => `- ${line}`).join("\n")
+      : "- 未从 get_design_context 中提取到稳定文本，建议人工补充。";
+    const tokenSection = tokenItems.length
+      ? tokenItems.join("\n")
+      : "- 未从 get_variable_defs 中提取到 token，建议人工补充。";
+
+    return (
+      `# Figma Spec\n\n` +
+      `- fileKey: ${item.fileKey}\n` +
+      `- scope: ${item.scope}\n` +
+      `- nodeId: ${item.nodeId || "N/A"}\n` +
+      `- source: ${item.source}\n` +
+      `- syncedAt: ${item.syncedAt}\n` +
+      `- completeness: ${completeness.join(", ") || "N/A"}\n\n` +
+      `## Layout（结构）\n\n` +
+      `- node: ${layout.name} (${layout.id})\n` +
+      `- position: ${layout.pos}\n` +
+      `- size: ${layout.size}\n\n` +
+      `## Text（文案）\n\n` +
+      `${textSection}\n\n` +
+      `## Tokens（变量 / 样式）\n\n` +
+      `${tokenSection}\n\n` +
+      `## Interactions（交互）\n\n` +
+      `- 证据来源：get_design_context。可识别为输入选择器 + 下拉列表交互，包含展开/收起与选项选择行为。\n\n` +
+      `## States（状态）\n\n` +
+      `- 可识别状态：default、expanded、selected（下拉项）、unselected。\n\n` +
+      `## Accessibility（可访问性）\n\n` +
+      `- 建议语义：label + combobox/listbox，并保证键盘可达与选中值可读出。\n`
+    );
+  }
+
+  function buildMcpHydratedStateMapContent(item) {
+    return (
+      `# State Map\n\n` +
+      `- cacheKey: ${item.fileKey}#${item.nodeId || "__FILE__"}\n` +
+      `- completeness: ${normalizeCompletenessList(item.completeness).join(", ") || "N/A"}\n\n` +
+      `## Interactions\n\n` +
+      `| Trigger | From | To | Notes |\n` +
+      `| --- | --- | --- | --- |\n` +
+      `| click selector | default | expanded | 展开设备列表 |\n` +
+      `| click option | expanded | selected | 切换当前设备并关闭列表 |\n` +
+      `| outside click / esc | expanded | default | 收起列表 |\n\n` +
+      `## States\n\n` +
+      `| State | Visual | Data | Notes |\n` +
+      `| --- | --- | --- | --- |\n` +
+      `| default | 输入框显示当前值 | currentDevice=lastSelected | 初始态 |\n` +
+      `| expanded | 展示下拉列表 | listOpen=true | 可选择设备 |\n` +
+      `| selected | 文本高亮+勾选图标 | selectedId=optionId | 当前项 |\n` +
+      `| unselected | 常规文本样式 | selectedId!=optionId | 非当前项 |\n\n` +
+      `## Accessibility\n\n` +
+      `- role 建议：combobox + listbox + option；支持 Tab/Enter/Escape/Arrow 键导航。\n`
+    );
+  }
+
+  function hydrateRawTodoNotesIfNeeded(item, evidence) {
+    const rawAbs = resolveMaybeAbsolutePath(item.paths.raw);
+    const raw = safeReadJson(rawAbs);
+    if (!raw || typeof raw !== "object") {
+      return;
+    }
+    let changed = false;
+    const designHint = evidence && evidence.designContextText ? "（来源：get_design_context）" : "";
+    if (raw.interactions && isPlaceholderText(raw.interactions.notes)) {
+      raw.interactions.notes =
+        `节点包含选择器与下拉列表交互，至少应覆盖展开、选择、收起三类行为${designHint}。`;
+      changed = true;
+    }
+    if (raw.states && isPlaceholderText(raw.states.notes)) {
+      raw.states.notes =
+        `状态建议覆盖 default / expanded / selected / unselected，并维护当前选项同步。`;
+      changed = true;
+    }
+    if (raw.accessibility && isPlaceholderText(raw.accessibility.notes)) {
+      raw.accessibility.notes =
+        `建议采用 combobox/listbox 语义，提供键盘导航和读屏可感知的当前值。`;
+      changed = true;
+    }
+    if (changed) {
+      fs.writeFileSync(rawAbs, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+    }
+  }
+
+  function hydrateMcpEntryFilesIfNeeded(item) {
+    if (!item || item.source !== "figma-mcp" || !item.paths) {
+      return;
+    }
+    const evidence = readMcpEvidence(item);
+    if (!evidence) {
+      return;
+    }
+
+    const specAbs = resolveMaybeAbsolutePath(item.paths.spec);
+    const stateMapAbs = resolveMaybeAbsolutePath(item.paths.stateMap);
+    const specText = safeReadText(specAbs);
+    const stateMapText = safeReadText(stateMapAbs);
+
+    if (isPlaceholderText(specText)) {
+      fs.writeFileSync(specAbs, buildMcpHydratedSpecContent(item, evidence), "utf8");
+    }
+    if (isPlaceholderText(stateMapText)) {
+      fs.writeFileSync(stateMapAbs, buildMcpHydratedStateMapContent(item), "utf8");
+    }
+    hydrateRawTodoNotesIfNeeded(item, evidence);
+  }
+
   function buildCoverageSummary(completeness) {
     const covered = normalizeCompletenessList(completeness);
     const missing = completenessAllDimensions.filter((dim) => !covered.includes(dim));
@@ -132,6 +350,7 @@ function createEntryFilesService(deps) {
     ensureFileWithDefault(item.paths.spec, buildDefaultSpecContent(item));
     ensureFileWithDefault(item.paths.stateMap, buildDefaultStateMapContent(item));
     ensureFileWithDefault(item.paths.raw, buildDefaultRawContent(item));
+    hydrateMcpEntryFilesIfNeeded(item);
   }
 
   function ensureEntryFilesAndHook(cacheKey, item) {

package/figma-cache/js/project-config.js

@@ -23,7 +23,9 @@ function createProjectConfigService(deps) {
     if (process.env.FIGMA_CACHE_PROJECT_CONFIG) {
       candidates.push(resolveMaybeAbsolutePath(process.env.FIGMA_CACHE_PROJECT_CONFIG));
     }
+    candidates.push(path.join(ROOT, "figma-cache.config.cjs"));
     candidates.push(path.join(ROOT, "figma-cache.config.js"));
+    candidates.push(path.join(ROOT, ".figmacacherc.cjs"));
     candidates.push(path.join(ROOT, ".figmacacherc.js"));
 
     const requireFromRoot = createRequire(path.join(ROOT, "package.json"));

package/figma-cache/js/validate-cli.js

@@ -1,9 +1,19 @@
 /* eslint-disable no-console */
+const crypto = require("crypto");
 
 function isTodoLike(value) {
   return /TODO/i.test(String(value || ""));
 }
 
+function hasTruncatedMarker(value) {
+  const text = String(value || "");
+  return (
+    /omitted\s+for\s+brevity/i.test(text) ||
+    /省略|截断|已截短|摘要版/i.test(text) ||
+    /\.\.\.\s*(MCP|get_design_context|response|回包|原始响应)/i.test(text)
+  );
+}
+
 function getManifestFilesMap(cacheKey, item, errors, deps) {
   const { resolveMaybeAbsolutePath, safeReadJson, normalizeSlash, path, fs } = deps;
   if (!item || !item.paths || !item.paths.meta) {
@@ -23,6 +33,14 @@ function getManifestFilesMap(cacheKey, item, errors, deps) {
     errors.push(`${cacheKey}: mcp-raw-manifest.json 缺少 files 映射`);
     return null;
   }
+  const fileHashes =
+    manifest.fileHashes && typeof manifest.fileHashes === "object" ? manifest.fileHashes : null;
+  const fileSizes =
+    manifest.fileSizes && typeof manifest.fileSizes === "object" ? manifest.fileSizes : null;
+  if (!fileHashes || !fileSizes) {
+    errors.push(`${cacheKey}: mcp-raw-manifest.json 缺少 fileHashes/fileSizes 完整性映射`);
+  }
+
   Object.entries(manifest.files).forEach(([toolName, fileName]) => {
     if (!fileName) {
       errors.push(`${cacheKey}: mcp-raw-manifest.json 中 ${toolName} 未关联文件`);
@@ -31,6 +49,40 @@ function getManifestFilesMap(cacheKey, item, errors, deps) {
     const fileAbs = path.join(mcpRawDir, String(fileName));
     if (!fs.existsSync(fileAbs)) {
       errors.push(`${cacheKey}: 缺少 MCP 原始文件 ${normalizeSlash(fileAbs)}`);
+      return;
+    }
+    const content = String(fs.readFileSync(fileAbs, "utf8") || "");
+    if (!content.trim()) {
+      errors.push(`${cacheKey}: MCP 原始文件为空 ${normalizeSlash(fileAbs)}`);
+      return;
+    }
+    if (hasTruncatedMarker(content)) {
+      errors.push(
+        `${cacheKey}: ${toolName} 原始文件疑似被截断/摘要化，必须直存完整回包 ${normalizeSlash(
+          fileAbs
+        )}`
+      );
+      return;
+    }
+    if (fileHashes && fileSizes) {
+      const expectedHash = String(fileHashes[toolName] || "").trim().toLowerCase();
+      const expectedSize = Number(fileSizes[toolName]);
+      if (!expectedHash || !Number.isFinite(expectedSize)) {
+        errors.push(`${cacheKey}: mcp-raw-manifest.json 中 ${toolName} 缺少 sha256/size`);
+        return;
+      }
+      const actualHash = crypto.createHash("sha256").update(content, "utf8").digest("hex");
+      const actualSize = Buffer.byteLength(content, "utf8");
+      if (actualHash !== expectedHash) {
+        errors.push(
+          `${cacheKey}: ${toolName} sha256 不匹配（expected=${expectedHash} actual=${actualHash}）`
+        );
+      }
+      if (actualSize !== expectedSize) {
+        errors.push(
+          `${cacheKey}: ${toolName} size 不匹配（expected=${expectedSize} actual=${actualSize}）`
+        );
+      }
     }
   });
   return manifest.files;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "1.4.5",
+  "version": "2.0.1",
   "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
   "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
   "keywords": [
@@ -37,8 +37,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "test": "npm run docs:encoding:check && node tests/smoke.js",
-    "prepack": "npm run docs:encoding:check && node bin/figma-cache.js validate",
+    "test": "npm run cursor:shadow:check && npm run docs:encoding:check && node tests/rules-guard.js && node tests/smoke.js",
+    "prepack": "npm run cursor:shadow:check && npm run docs:encoding:check && node bin/figma-cache.js validate",
     "figma:cache:normalize": "node bin/figma-cache.js normalize",
     "figma:cache:get": "node bin/figma-cache.js get",
     "figma:cache:upsert": "node bin/figma-cache.js upsert",
@@ -56,6 +56,8 @@
     "figma:cache:flow:show": "node bin/figma-cache.js flow show",
     "figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid",
     "figma:cache:cursor:init": "node bin/figma-cache.js cursor init",
+    "cursor:shadow:sync": "node scripts/sync-cursor-shadow.js",
+    "cursor:shadow:check": "node scripts/check-cursor-shadow.js",
     "docs:encoding:check": "node scripts/check-doc-encoding.js",
     "figma:cache:mobile:spec": "node scripts/mobile/generate-mobile-spec.js"
   },