figma-cache-toolchain 2.0.0 → 2.0.1

package/README.md

@@ -70,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/cursor-bootstrap/rules/00-output-token-budget.mdc

@@ -5,22 +5,25 @@ alwaysApply: true
 
 # Output Token Budget（通用）
 
-适用于所有任务（不仅限 Figma）。目标：减少对话 token 消耗，只输出结果与可执行结论。
+适用于所有任务。默认只输出“可执行结果”，避免过程噪音与长回包。
 
-## 默认输出策略（强制）
-- 结果优先：不输出思考过程，不做长篇背景铺垫。
-- 最小必要：只输出结论、关键变更、验证结果、下一步动作。
-- 工具原文最小化：禁止在回复中粘贴大段工具原始回包/日志，除非用户明确要求查看原文。
-- 文件优先：大内容落到文件，再汇报路径；回复仅给摘要与定位。
+## 默认策略（强制）
+- 结果优先：只给结论、关键变更、验证结果、下一步。
+- 原文最小化：不贴 MCP/终端长日志；仅在用户明确要求时展示。
+- 文件优先：大内容落盘，回复只给路径与摘要。
+- 进度最小化：默认不发中间过程；仅在阻塞/失败时反馈。
 
 ## 任务分级（强制）
-- UI/组件实现：默认读取并使用完整设计证据，不反复讨论“是否需要读取”；完成后仅汇报最终差异与验证。
-- 逻辑/流程/校验类任务：优先读取摘要产物（如 `raw.json`、`spec.md`、`manifest`），避免无关大文件。
+- UI/组件实现：读取完整设计证据，回复仅给最终差异与验证。
+- 逻辑/流程/校验：优先 `raw.json` / `spec.md` / `manifest`，避免读无关大文件。
 
-## 交互与进度（强制）
-- 仅在必要阻塞时提问；可自行推断时不追问。
-- 中间进度最多 1 条（长任务可 2 条），其余一次性收敛到最终结果。
-- 失败反馈固定三段：失败原因、定位信息、修复动作。
+## 失败反馈格式（强制）
+- 固定三段：失败原因 / 定位信息 / 修复动作。
 
 ## 例外
-- 用户明确要求“展示完整输出/完整日志/原文”时，才突破上述限制。
+- 用户明确要求“完整输出/日志/原文”时可放宽上述限制。
+
+## 模板维护约定（强制）
+- `cursor-bootstrap` 是规则/技能模板唯一手写来源。
+- 仓库内 `.cursor/*` 视为镜像产物，不作为手工编辑入口。
+- 模板变更后执行 `npm run cursor:shadow:sync`，再提交。

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

@@ -5,116 +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`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
-
-## 低 Token 输出模式（强制）
-- 默认采用“结果优先”输出：仅保留最终结论与必要审计字段，不输出思考过程。
-- MCP 工具回包（尤其 `get_design_context`）禁止在用户可见回复中粘贴全文或大段复述；仅报告调用计数、来源、文件路径与校验结果。
-- 除非用户明确要求查看原文，`mcp-raw` 内容仅落盘到文件，不在 chat 回显。
-- 进度反馈最小化：缓存任务默认 0-1 条简短进度更新；完成后一次性给出结果。
-- 失败场景也保持精简：仅输出失败原因、定位文件、下一步修复动作。
-
-## 配置与钩子
-- `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`），与加工缓存文件分层。
-- `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 方式整段重写，最后重新执行验证命令。
+边界：仅处理 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,185 +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` 文件中禁止出现摘要/截断标记（如 `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：
-  - `> 🔄 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，状态多为「缺失→更新」或「更新」，并在后文简述触发原因（未命中/信息不足/用户强刷）。
-- 默认采用低 token 输出：不回显 MCP 原始正文，仅输出调用统计、文件落盘与校验结果。
-- 用户若明确要求“查看原文/贴出回包”时，才输出必要片段；默认引导用户查看 `mcp-raw/*` 本地文件。
+## 用户可见输出（最小化）
+- 首行固定：
+  - `> 🔄 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "2.0.0",
+  "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"
   },