figma-cache-toolchain 1.4.5 → 2.0.0

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`

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,26 @@
+---
+description: 通用低 token 输出基线（结果优先，最小回显）
+alwaysApply: true
+---
+
+# Output Token Budget（通用）
+
+适用于所有任务（不仅限 Figma）。目标：减少对话 token 消耗，只输出结果与可执行结论。
+
+## 默认输出策略（强制）
+- 结果优先：不输出思考过程，不做长篇背景铺垫。
+- 最小必要：只输出结论、关键变更、验证结果、下一步动作。
+- 工具原文最小化：禁止在回复中粘贴大段工具原始回包/日志，除非用户明确要求查看原文。
+- 文件优先：大内容落到文件，再汇报路径；回复仅给摘要与定位。
+
+## 任务分级（强制）
+- UI/组件实现：默认读取并使用完整设计证据，不反复讨论“是否需要读取”；完成后仅汇报最终差异与验证。
+- 逻辑/流程/校验类任务：优先读取摘要产物（如 `raw.json`、`spec.md`、`manifest`），避免无关大文件。
+
+## 交互与进度（强制）
+- 仅在必要阻塞时提问；可自行推断时不追问。
+- 中间进度最多 1 条（长任务可 2 条），其余一次性收敛到最终结果。
+- 失败反馈固定三段：失败原因、定位信息、修复动作。
+
+## 例外
+- 用户明确要求“展示完整输出/完整日志/原文”时，才突破上述限制。

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

@@ -42,10 +42,10 @@ alwaysApply: true
    - `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`
+   - **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` 证据：
@@ -56,7 +56,9 @@ alwaysApply: true
 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`。
+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`）接管。
@@ -68,8 +70,15 @@ alwaysApply: true
 
 （语义与 `index.json` 中 `nodeId` / `__FILE__` 约定同前；Blockquote 后再写结论。）
 
-- 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
-
+- 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
+
+## 低 Token 输出模式（强制）
+- 默认采用“结果优先”输出：仅保留最终结论与必要审计字段，不输出思考过程。
+- MCP 工具回包（尤其 `get_design_context`）禁止在用户可见回复中粘贴全文或大段复述；仅报告调用计数、来源、文件路径与校验结果。
+- 除非用户明确要求查看原文，`mcp-raw` 内容仅落盘到文件，不在 chat 回显。
+- 进度反馈最小化：缓存任务默认 0-1 条简短进度更新；完成后一次性给出结果。
+- 失败场景也保持精简：仅输出失败原因、定位文件、下一步修复动作。
+
 ## 配置与钩子
 - `npm run figma:cache:config` 可查看是否加载 `hooks.postEnsure`。
 - `ensure` 在写入通用骨架后会调用 `hooks.postEnsure`；钩子异常**不得**阻断 ensure 成功退出（由 Core 捕获）。
@@ -79,30 +88,33 @@ alwaysApply: true
 - 缓存目录、环境变量、`flows`、陈旧策略、提交前校验等与原「Local Cache First」一致，参见 `figma-cache/` 内文档及 `npm run figma:cache:*`。
 - 对同一节点写缓存时，优先复用本轮已拿到的 MCP 响应做落盘，避免“仅为生成原始文件而重复调同一工具”。
 - 若保存原始数据，统一写入节点目录下 `mcp-raw/` 子目录（如 `mcp-raw/mcp-raw-get-design-context.txt`），与加工缓存文件分层。
+- `mcp-raw` 原始文件**禁止**写入任何摘要/截断标记（如 `omitted for brevity`、`...response omitted...`、`省略`、`截断`）；必须直存完整 MCP 回包。
+- `mcp-raw/mcp-raw-manifest.json` 必须记录每个工具原始文件的 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数）；`validate` 会逐项比对，不一致即失败。
+- **落盘后即时反精简检查（强制）**：每次写入 `mcp-raw` 后，必须立刻检查是否出现摘要/截断标记与 hash/size 不一致；检查结果必须在用户回复中显式输出为 `mcp-raw anti-truncation: pass|fail`（失败时附修复动作）。
 - 默认不写 `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 方式整段重写，最后重新执行验证命令。
+## 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 方式整段重写，最后重新执行验证命令。
 

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

@@ -47,9 +47,9 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 
 ## 流程关系（Flow）
 - `figma-cache/index.json` 中的 `flows` 用于维护业务/交互流程的节点集合与边关系。
-- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
-- 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
-- flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
+- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
+- 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
+- flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
 - 不触发：单链接且无关系意图、仅视觉微调、仅资产导出。
 
 ## 标准流程
@@ -77,16 +77,21 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 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` 与简要文件列表（不必粘贴完整终端日志）。
+10. **反截断约束（强制）**：`mcp-raw` 文件中禁止出现摘要/截断标记（如 `omitted for brevity`、`...response omitted...`、`省略`、`截断`）；一旦出现，必须视为无效证据并重新落盘完整回包。
+11. **完整性签名（强制）**：`mcp-raw-manifest.json` 必须提供 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数）；任一工具文件不匹配即视为证据损坏。
+12. **落盘后即时反精简检查（强制）**：每次写入 `mcp-raw` 后，必须立即执行反精简检查（截断标记 + hash/size）；并在用户回复中显式输出 `mcp-raw anti-truncation: pass|fail`。
+13. **本地分析优先**：若本地已存在可用 `mcp-raw-*` 与缓存加工文件，且用户未要求刷新/强制最新，后续分析默认只读本地文件，不再调用 Figma MCP。
+14. 发生 MCP 拉取或本地补齐时，写入/更新 `meta.json`、`spec.md`、必要补充文件，并更新索引。
+15. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅补齐索引与骨架文件，不能替代 MCP 拉取；不得把“执行了 ensure”当成“完成了 figma-mcp 调用”。
+16. **MCP 证据门禁（强制）**：当输出来源声明为 `figma-mcp` 时，节点目录必须存在 `mcp-raw/` 及最小调用集原始回包（按 completeness 裁剪）；若缺失，立即停止并报告“未完成”，不得宣称更新成功。
+17. **调用预算**：单节点默认 MCP 调用不超过 3 次；超过时必须在回复中说明缺口字段与补调理由。
+18. **重试策略**：仅对超时/5xx进行指数退避重试；参数错误/权限错误不重试并直接报告。
+19. **大文件读取策略（强制）**：
+   - UI 还原/像素对齐/组件实现任务：默认必须读取 `mcp-raw-get-design-context.txt` 全文，不反复拉扯“是否需要读全文”。
+   - 非 UI 任务（命中检查、预算统计、校验、流程维护）：默认只读 `raw.json`/`spec.md`/`mcp-raw-manifest.json`。
+20. **闭环校验（强制）**：凡本轮执行了 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`**（任意参数组合），在命令成功结束后，Agent **必须**在同一仓库根目录**自动、静默**执行 `npm run figma:cache:validate`。
+21. **校验失败**：根据脚本输出修复索引、`paths`、缺失文件、JSON 结构等，**循环执行 validate 直至退出码为 0**；不得在 validate 未通过时结束本轮「写缓存」任务。
+22. 对用户反馈时除 Blockquote 外可补充：`source: local-cache` / `source: figma-mcp`、`mcp-raw anti-truncation: pass|fail` 与简要文件列表（不必粘贴完整终端日志）。
 
 ## Agent 最终输出格式（强制）
 - 触发 `<Trigger Conditions>` 且本轮触碰缓存读写的回复，**第一段**必须为单行 Blockquote：
@@ -165,14 +170,16 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 - **必须先**输出规定的缓存状态 Blockquote，再给出设计结论或实现说明。
 - 若跳过 MCP，Blockquote 中来源为 Local，状态多为「命中」。
 - 若调用 MCP，Blockquote 中来源为 MCP，状态多为「缺失→更新」或「更新」，并在后文简述触发原因（未命中/信息不足/用户强刷）。
+- 默认采用低 token 输出：不回显 MCP 原始正文，仅输出调用统计、文件落盘与校验结果。
+- 用户若明确要求“查看原文/贴出回包”时，才输出必要片段；默认引导用户查看 `mcp-raw/*` 本地文件。
 
 ## 推荐命令（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`
+- `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 成功后必须自动执行**；失败则修至通过

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.0",
   "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
   "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
   "keywords": [