figma-cache-toolchain 1.4.2 → 1.4.4

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

@@ -1,139 +1,239 @@
-/**
- * 项目级 Figma 缓存扩展（示例模板，**不绑定任何 UI 框架**）。
- *
- * 安装本 npm 包并执行 `npx figma-cache cursor init` 后，项目根会出现 **AGENT-SETUP-PROMPT.md**：
- * 请用 Cursor Agent **按该文件全文**执行，以自动生成 `figma-cache.config.js`、栈专属 Adapter、并删除占位规则等（尽量少手动步骤）。
- *
- * 若你已有 `figma-cache.config.js`，可由 Agent 合并而非覆盖。
- *
- * 加载顺序见 `figma-cache/figma-cache.js`：FIGMA_CACHE_PROJECT_CONFIG → figma-cache.config.js → .figmacacherc.js
- */
-
-const fs = require("fs");
-const path = require("path");
-
-/** 节点目录下由 postEnsure 写入的说明文件（可用环境变量 FIGMA_CACHE_ADAPTER_DOC 覆盖） */
-const ADAPTER_DOC_BASENAME =
-  process.env.FIGMA_CACHE_ADAPTER_DOC || "figma-cache-adapter-hint.md";
-
-/**
- * 人类可读的「流程 / 需求总览」骨架路径（相对项目根）。仅本示例写入；可在业务项目中改路径或删除相关逻辑。
- * @type {string}
- */
-const FLOW_README_REL =
-  process.env.FIGMA_CACHE_FLOW_README || "docs/figma-flow-readme.md";
-
-const FLOW_README_REGISTRY_BEGIN = "<!-- figma-cache-flow-readme: registry -->";
-
-/**
- * @param {object} ctx
- * @returns {string}
- */
-function buildNeutralHint(ctx) {
-  const nodeLabel = ctx.nodeId == null ? "" : String(ctx.nodeId);
-  return `# Figma 缓存 → UI 实现（占位提示）
-
-本文件由 **空示例** \`postEnsure\` 生成；请用 Agent 按项目栈替换为具体说明，或删除本文件并在 \`figma-cache.config.js\` 中实现自定义逻辑。
-
-- **设计事实来源**（勿改写成框架代码）：同目录 \`raw.json\`、\`spec.md\`、\`state-map.md\`、\`meta.json\`
-- cacheKey: \`${ctx.cacheKey}\`
-- fileKey: \`${ctx.fileKey}\`
-- nodeId: \`${nodeLabel}\`
-
-**流程 / 交互总览（可选）**：若使用本示例默认钩子，项目根下另有 **\`${FLOW_README_REL}\`**，随每次 \`ensure\` 追加节点小节，便于与 \`index.json\` 里的 \`flows\` 互补（人读 md，机读索引）。
-
-下一步：打开项目根 \`AGENT-SETUP-PROMPT.md\`，整篇交给 Cursor Agent 执行以完成栈适配（含本钩子的具体实现与 \`02-figma-<栈>-adapter.mdc\`）。
-`;
-}
-
-/**
- * @param {object} ctx
- * @param {string} ctx.root
- * @param {{ meta: string }} ctx.paths
- */
-function writeAdapterHint(ctx) {
-  const metaAbs = path.resolve(ctx.root, ctx.paths.meta);
-  const dir = path.dirname(metaAbs);
-  const target = path.join(dir, ADAPTER_DOC_BASENAME);
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(target, buildNeutralHint(ctx), "utf8");
-}
-
-/**
- * 在单文件里维护「已缓存节点」登记（按 cacheKey 幂等追加），与 index.json / flows 互补：适合评审与新人阅读。
- * @param {object} ctx
- */
-function appendFlowReadmeRegistry(ctx) {
-  const abs = path.resolve(ctx.root, FLOW_README_REL);
-  const marker = `<!-- cache-node:${ctx.cacheKey} -->`;
-  const specRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.spec)));
-  const metaRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.meta)));
-  const completeness = Array.isArray(ctx.completeness) && ctx.completeness.length ? ctx.completeness.join(", ") : "—";
-  const block =
-    `\n${marker}\n` +
-    `### \`${ctx.cacheKey}\`\n\n` +
-    `- **Figma**: ${ctx.url || "—"}\n` +
-    `- **syncedAt**: ${ctx.syncedAt || "—"}\n` +
-    `- **source**: ${ctx.source || "—"}\n` +
-    `- **completeness**: ${completeness}\n` +
-    `- **spec**: \`${specRel}\` · **meta**: \`${metaRel}\`\n` +
-    `- **提示**: 像素级还原以 \`spec.md\` / \`raw.json\` 为准；用户路径请维护 \`flows\` 后把 \`npm run figma:cache:flow mermaid\` 输出贴到下方「流程总览」。\n`;
-
-  if (!fs.existsSync(abs)) {
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    const head =
-      `# 设计与流程说明（示例骨架）\n\n` +
-      `> 本文件由 **figma-cache.config.example.js** 的 \`postEnsure\` 自动创建并增量更新；**可整文件改写**或复制逻辑到自有 \`figma-cache.config.js\`。\n\n` +
-      `## 流程总览（手填 / 或粘贴 mermaid）\n\n` +
-      `用自然语言写用户路径，或粘贴 \`npm run figma:cache:flow mermaid -- --flow=<flowId>\` 的输出：\n\n` +
-      `\`\`\`mermaid\n%% flow mermaid 输出贴此处\n\`\`\`\n\n` +
-      `## 交互与边界（手填）\n\n` +
-      `- 分支条件：\n` +
-      `- 异常与空状态：\n\n` +
-      `## 已从 Figma 写入缓存的节点（钩子按节点幂等追加）\n\n` +
-      `${FLOW_README_REGISTRY_BEGIN}\n`;
-    fs.writeFileSync(abs, head + block + "\n", "utf8");
-    return;
-  }
-
-  let body = fs.readFileSync(abs, "utf8");
-  if (body.includes(marker)) {
-    return;
-  }
-  if (!body.includes(FLOW_README_REGISTRY_BEGIN)) {
-    body =
-      body.trimEnd() +
-      `\n\n## 已从 Figma 写入缓存的节点（钩子按节点幂等追加）\n\n${FLOW_README_REGISTRY_BEGIN}\n`;
-  }
-  fs.writeFileSync(abs, body.trimEnd() + block + "\n", "utf8");
-}
-
-/**
- * @param {string} p
- * @returns {string}
- */
-function normalizePosixPath(p) {
-  return p.split(path.sep).join("/");
-}
-
-module.exports = {
-  buildNeutralHint,
-  ADAPTER_DOC_BASENAME,
-  FLOW_README_REL,
-  appendFlowReadmeRegistry,
-
-  hooks: {
-    /**
-     * 默认实现：写入节点内占位说明 + 项目根下「流程/需求」总览骨架（单文件、幂等追加节点块）。
-     * 用 Agent 生成业务方案后，可整体替换本模块逻辑。
-     */
-    postEnsure(ctx) {
-      try {
-        writeAdapterHint(ctx);
-        appendFlowReadmeRegistry(ctx);
-      } catch (err) {
-        console.error(`[figma-cache.config] postEnsure: ${err.message}`);
-      }
-    },
-  },
+/**
+ * 项目级 Figma 缓存扩展（示例模板，**不绑定任何 UI 框架**）。
+ *
+ * 安装本 npm 包并执行 `npx figma-cache cursor init` 后，项目根会出现 **AGENT-SETUP-PROMPT.md**：
+ * 请用 Cursor Agent **按该文件全文**执行，以自动生成 `figma-cache.config.js`、栈专属 Adapter、并删除占位规则等（尽量少手动步骤）。
+ *
+ * 若你已有 `figma-cache.config.js`，可由 Agent 合并而非覆盖。
+ *
+ * 加载顺序见 `figma-cache/figma-cache.js`：FIGMA_CACHE_PROJECT_CONFIG → figma-cache.config.js → .figmacacherc.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Adapter 提示文档基础名：
+ * - node 模式时用于节点目录文件名
+ * - cache-root 模式时用于 figma-cache 根目录文件名
+ */
+const ADAPTER_DOC_BASENAME =
+  process.env.FIGMA_CACHE_ADAPTER_DOC || "figma-cache-adapter-hint.md";
+
+/**
+ * Adapter 提示写入模式：
+ * - cache-root（默认）：仅在 figma-cache 目录维护单文件，避免每节点重复
+ * - node：按节点目录写入提示
+ * - off：关闭提示文件写入
+ */
+const ADAPTER_DOC_MODE = normalizeAdapterDocMode(
+  process.env.FIGMA_CACHE_ADAPTER_DOC_MODE || "cache-root"
+);
+
+/**
+ * cache-root 模式下的提示文档路径（相对项目根）
+ */
+const ADAPTER_DOC_CACHE_REL =
+  process.env.FIGMA_CACHE_ADAPTER_DOC_CACHE ||
+  `figma-cache/docs/${ADAPTER_DOC_BASENAME}`;
+
+/**
+ * 提示文档写入策略：
+ * - if-missing（默认）：仅目标不存在时写入
+ * - always：每次 ensure 都覆盖更新
+ */
+const ADAPTER_DOC_WRITE_POLICY =
+  process.env.FIGMA_CACHE_ADAPTER_DOC_WRITE_POLICY || "if-missing";
+
+/**
+ * 人类可读的「流程 / 需求总览」骨架路径（相对项目根）。仅本示例写入；可在业务项目中改路径或删除相关逻辑。
+ * @type {string}
+ */
+const FLOW_README_REL =
+  process.env.FIGMA_CACHE_FLOW_README || "docs/figma-flow-readme.md";
+
+const FLOW_README_REGISTRY_BEGIN = "<!-- figma-cache-flow-readme: registry -->";
+
+/**
+ * @param {string} raw
+ * @returns {"cache-root" | "node" | "off"}
+ */
+function normalizeAdapterDocMode(raw) {
+  const value = String(raw || "")
+    .trim()
+    .toLowerCase();
+  if (value === "node" || value === "node-each") {
+    return "node";
+  }
+  if (value === "off" || value === "none" || value === "disable") {
+    return "off";
+  }
+  return "cache-root";
+}
+
+/**
+ * @returns {boolean}
+ */
+function shouldOverwriteAdapterDoc() {
+  return String(ADAPTER_DOC_WRITE_POLICY || "")
+    .trim()
+    .toLowerCase() === "always";
+}
+
+/**
+ * @param {string} absPath
+ * @param {string} content
+ * @returns {boolean}
+ */
+function writeTextByPolicy(absPath, content) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  if (!shouldOverwriteAdapterDoc() && fs.existsSync(absPath)) {
+    return false;
+  }
+  fs.writeFileSync(absPath, content, "utf8");
+  return true;
+}
+
+/**
+ * @param {object} ctx
+ * @returns {string}
+ */
+function buildCacheRootHint(ctx) {
+  return `# Figma 缓存 → UI 实现（目录级提示）
+
+本文件由示例 \`postEnsure\` 生成，默认放在 **figma-cache 目录级**，用于避免“每个节点重复生成同一提示”。
+
+- **默认来源优先级**：先用 \`raw.json\` / \`spec.md\` / \`meta.json\` / \`state-map.md\`，仅在缺口或冲突时再读 \`mcp-raw/*\`
+- **证据约束**：同一设计事实只保留一个主证据来源，避免重复引用
+- **命中检查**：先查本地缓存命中与字段覆盖，再决定是否需要 MCP 补齐
+
+可选模式（环境变量）：
+- \`FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root\`（默认）
+- \`FIGMA_CACHE_ADAPTER_DOC_MODE=node\`（按节点写入）
+- \`FIGMA_CACHE_ADAPTER_DOC_MODE=off\`（关闭）
+
+最近触发：\`${ctx.cacheKey}\`（\`${ctx.syncedAt || ""}\`）
+`;
+}
+
+/**
+ * @param {object} ctx
+ * @returns {string}
+ */
+function buildNodeHint(ctx) {
+  const nodeLabel = ctx.nodeId == null ? "" : String(ctx.nodeId);
+  return `# Figma 缓存 → UI 实现（节点提示）
+
+本文件由示例 \`postEnsure\` 生成。若你希望减少重复，可改用目录级模式：\`FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root\`。
+
+- **设计事实来源**（勿改写成框架代码）：同目录 \`raw.json\`、\`spec.md\`、\`state-map.md\`、\`meta.json\`
+- cacheKey: \`${ctx.cacheKey}\`
+- fileKey: \`${ctx.fileKey}\`
+- nodeId: \`${nodeLabel}\`
+
+**流程 / 交互总览（可选）**：若使用本示例默认钩子，项目根下另有 **\`${FLOW_README_REL}\`**，随每次 \`ensure\` 追加节点小节，便于与 \`index.json\` 里的 \`flows\` 互补（人读 md，机读索引）。
+`;
+}
+
+/**
+ * @param {object} ctx
+ */
+function writeAdapterHint(ctx) {
+  if (ADAPTER_DOC_MODE === "off") {
+    return;
+  }
+
+  if (ADAPTER_DOC_MODE === "node") {
+    const metaAbs = path.resolve(ctx.root, ctx.paths.meta);
+    const nodeDir = path.dirname(metaAbs);
+    const target = path.join(nodeDir, ADAPTER_DOC_BASENAME);
+    writeTextByPolicy(target, buildNodeHint(ctx));
+    return;
+  }
+
+  const cacheRootTarget = path.resolve(ctx.root, ADAPTER_DOC_CACHE_REL);
+  writeTextByPolicy(cacheRootTarget, buildCacheRootHint(ctx));
+}
+
+/**
+ * 在单文件里维护「已缓存节点」登记（按 cacheKey 幂等追加），与 index.json / flows 互补：适合评审与新人阅读。
+ * @param {object} ctx
+ */
+function appendFlowReadmeRegistry(ctx) {
+  const abs = path.resolve(ctx.root, FLOW_README_REL);
+  const marker = `<!-- cache-node:${ctx.cacheKey} -->`;
+  const specRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.spec)));
+  const metaRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.meta)));
+  const completeness = Array.isArray(ctx.completeness) && ctx.completeness.length ? ctx.completeness.join(", ") : "—";
+  const block =
+    `\n${marker}\n` +
+    `### \`${ctx.cacheKey}\`\n\n` +
+    `- **Figma**: ${ctx.url || "—"}\n` +
+    `- **syncedAt**: ${ctx.syncedAt || "—"}\n` +
+    `- **source**: ${ctx.source || "—"}\n` +
+    `- **completeness**: ${completeness}\n` +
+    `- **spec**: \`${specRel}\` · **meta**: \`${metaRel}\`\n` +
+    `- **提示**: 像素级还原以 \`spec.md\` / \`raw.json\` 为准；用户路径请维护 \`flows\` 后把 \`npm run figma:cache:flow mermaid\` 输出贴到下方「流程总览」。\n`;
+
+  if (!fs.existsSync(abs)) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const head =
+      `# 设计与流程说明（示例骨架）\n\n` +
+      `> 本文件由 **figma-cache.config.example.js** 的 \`postEnsure\` 自动创建并增量更新；**可整文件改写**或复制逻辑到自有 \`figma-cache.config.js\`。\n\n` +
+      `## 流程总览（手填 / 或粘贴 mermaid）\n\n` +
+      `用自然语言写用户路径，或粘贴 \`npm run figma:cache:flow mermaid -- --flow=<flowId>\` 的输出：\n\n` +
+      `\`\`\`mermaid\n%% flow mermaid 输出贴此处\n\`\`\`\n\n` +
+      `## 交互与边界（手填）\n\n` +
+      `- 分支条件：\n` +
+      `- 异常与空状态：\n\n` +
+      `## 已从 Figma 写入缓存的节点（钩子按节点幂等追加）\n\n` +
+      `${FLOW_README_REGISTRY_BEGIN}\n`;
+    fs.writeFileSync(abs, head + block + "\n", "utf8");
+    return;
+  }
+
+  let body = fs.readFileSync(abs, "utf8");
+  if (body.includes(marker)) {
+    return;
+  }
+  if (!body.includes(FLOW_README_REGISTRY_BEGIN)) {
+    body =
+      body.trimEnd() +
+      `\n\n## 已从 Figma 写入缓存的节点（钩子按节点幂等追加）\n\n${FLOW_README_REGISTRY_BEGIN}\n`;
+  }
+  fs.writeFileSync(abs, body.trimEnd() + block + "\n", "utf8");
+}
+
+/**
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizePosixPath(p) {
+  return p.split(path.sep).join("/");
+}
+
+module.exports = {
+  buildCacheRootHint,
+  buildNodeHint,
+  ADAPTER_DOC_BASENAME,
+  ADAPTER_DOC_MODE,
+  ADAPTER_DOC_CACHE_REL,
+  ADAPTER_DOC_WRITE_POLICY,
+  FLOW_README_REL,
+  appendFlowReadmeRegistry,
+
+  hooks: {
+    /**
+     * 默认实现：目录级 adapter 提示（避免节点重复）+ 项目根下「流程/需求」总览骨架（单文件、幂等追加节点块）。
+     * 用 Agent 生成业务方案后，可整体替换本模块逻辑。
+     */
+    postEnsure(ctx) {
+      try {
+        writeAdapterHint(ctx);
+        appendFlowReadmeRegistry(ctx);
+      } catch (err) {
+        console.error(`[figma-cache.config] postEnsure: ${err.message}`);
+      }
+    },
+  },
 };

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

@@ -28,7 +28,7 @@ alwaysApply: true
 </Trigger Conditions>
 
 ## 执行顺序
-1. 按 `figma-cache/link-normalization-spec.md` 标准化链接。
+1. 按 `figma-cache/docs/link-normalization-spec.md` 标准化链接。
 2. 读本地 `index.json` 判断是否命中。
 3. 命中且字段满足任务 → 只读本地，不调 MCP。
 4. 未命中或不足 → MCP 拉取并回写通用缓存文件。
@@ -42,12 +42,24 @@ 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`
 9. **两阶段拉取**：先按最小必要工具取数并检查字段缺口；仅在缺口存在时进入第二阶段补调工具。
 10. **写入一致性门禁（强制）**：当 `source=figma-mcp` 或输出来源标注 MCP 时，节点目录必须存在 `mcp-raw/` 与对应原始文件；若缺失则视为未完成，必须停止并报告，不得宣称“更新成功”。
-11. **大文件读取策略（强制）**：仅在 UI 还原/像素对齐/组件实现任务中读取 `mcp-raw-get-design-context.txt` 全文；非 UI 任务（命中检查、预算统计、校验、流程维护）默认仅读取 `raw.json` / `spec.md` / `mcp-raw-manifest.json`。
-12. **闭环校验（强制）**：每次 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`** 成功结束后，**自动静默**执行 `npm run figma:cache:validate`。
-13. validate 失败 → **自行修复并重复 validate 直至通过**，不得宣称缓存已就绪。
-14. **不写前端**：本阶段禁止输出业务组件实现；若用户要求写 UI，在缓存就绪后转由 **栈专属 Adapter 规则**（如 `02-figma-stack-adapter.mdc` 占位，或项目内 `02-figma-<栈>-adapter.mdc`）接管。
+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：
@@ -56,6 +68,8 @@ alwaysApply: true
 
 （语义与 `index.json` 中 `nodeId` / `__FILE__` 约定同前；Blockquote 后再写结论。）
 
+- 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
+
 ## 配置与钩子
 - `npm run figma:cache:config` 可查看是否加载 `hooks.postEnsure`。
 - `ensure` 在写入通用骨架后会调用 `hooks.postEnsure`；钩子异常**不得**阻断 ensure 成功退出（由 Core 捕获）。
@@ -69,3 +83,26 @@ alwaysApply: true
 - 单节点 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 方式整段重写，最后重新执行验证命令。
+

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

@@ -47,10 +47,13 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 
 ## 流程关系（Flow）
 - `figma-cache/index.json` 中的 `flows` 用于维护业务/交互流程的节点集合与边关系。
-- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
+- 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
+- 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
+- flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
+- 不触发：单链接且无关系意图、仅视觉微调、仅资产导出。
 
 ## 标准流程
-1. 按 `figma-cache/link-normalization-spec.md` 标准化链接并生成键：
+1. 按 `figma-cache/docs/link-normalization-spec.md` 标准化链接并生成键：
    - 节点级：`cacheKey = <fileKey>#<nodeId>`
    - 文件级（无 `node-id`）：`cacheKey = <fileKey>#__FILE__`
 2. 读取 `index.json`：
@@ -139,7 +142,7 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
         "raw": "figma-cache/files/xxxx/nodes/12-34/raw.json"
       },
       "syncedAt": "2026-04-14T12:00:00Z",
-      "completeness": ["layout", "text", "tokens", "interactions"]
+      "completeness": ["layout", "text", "tokens", "interactions", "states", "accessibility"]
     }
   }
 }
@@ -167,8 +170,10 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
 - `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,flow,states`
-- `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,flow,states`：自动补齐缓存骨架文件（非 MCP 拉取）
+- 先执行 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 代理）

package/figma-cache/{README.md → docs/README.md}

@@ -26,10 +26,10 @@
 - `figma-cache/figma-cache.js`：缓存流程脚本主入口
 - `figma-cache/index.json`：全量索引
 - `figma-cache/files/...`：节点缓存内容
-- **`figma-cache/README.md`**：接入、scripts、环境变量、人工校验与回填（本文件，随包分发的主文档）
-- **`figma-cache/colleague-guide-zh.md`**：团队向说明与提示词模板；**`npx figma-cache cursor init` 会写入/刷新**（与 `FIGMA_CACHE_DIR` 下路径一致），便于纳入版本库、不必从 `node_modules` 手抄
-- `figma-cache/link-normalization-spec.md`：链接标准化规则（Core / Skill 会引用）
-- `figma-cache/flow-edge-taxonomy.md`：流程边类型约定
+- **`figma-cache/docs/README.md`**：接入、scripts、环境变量、人工校验与回填（本文件，随包分发的主文档）
+- **`figma-cache/docs/colleague-guide-zh.md`**：团队向说明与提示词模板；**`npx figma-cache cursor init` 会写入/刷新**（与 `FIGMA_CACHE_DIR` 下路径一致），便于纳入版本库、不必从 `node_modules` 手抄
+- `figma-cache/docs/link-normalization-spec.md`：链接标准化规则（Core / Skill 会引用）
+- `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
 
 ## 默认配置
 
@@ -52,19 +52,31 @@ $env:FIGMA_DEFAULT_FLOW="sip-calling-phase1"
 npm run figma:cache:config
 ```
 
-## 常用命令（通常由 agent 自动执行）
+## 常用命令（通常由 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`。
 
-- `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`
-- `npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions`
-- `npm run figma:cache:validate`
-- `npm run figma:cache:budget`（默认 `--mcp-only`）
-- `npm run figma:cache:stale`
-- `npm run figma:cache:backfill`
+### 严格 validate 规则（默认）
 
-> 注意：`ensure` 默认职责是“写索引 + 生成骨架文件”，不是 MCP 拉取器。  
-> 当传 `--source=figma-mcp` 时，当前 CLI 会阻止“假成功”（若未显式允许骨架模式）；正确流程是先由 Agent/Figma MCP 获取最小调用集数据并写入 `mcp-raw/`，再执行 `upsert/ensure` 与 `validate`。
+- `validate` 会检查 `raw.json.coverageSummary.evidence` 与 `completeness` 是否一致。
+- 当 `source=figma-mcp` 且声明 `interactions/states/accessibility` 时，不允许保留 TODO 占位说明。
+- 若你仅想先落骨架，可使用 `--allow-skeleton-with-figma-mcp`（仅放行 upsert/ensure 写入，不放行 validate）；后续必须补齐证据并通过 `validate`。
 
 ### 预算统计（token/调用）
 
@@ -97,7 +109,7 @@ npm run figma:cache:config
 3. 当你描述跳转/下一步/分支：用 `flow link`；批量默认串联可用 `flow chain`
 4. 定期 `validate`；需要看图用 `flow mermaid`
 
-边类型约定见：`figma-cache/flow-edge-taxonomy.md`
+边类型约定见：`figma-cache/docs/flow-edge-taxonomy.md`
 
 ## 纯净版初始化
 
@@ -165,7 +177,10 @@ npm run figma:cache:init
 | `FIGMA_ITERATIONS_DIR` | **仅** `backfill` 扫描的历史 Markdown 目录；不存在时扫描为空，`validate` 不受影响 |
 | `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
 | `FIGMA_DEFAULT_FLOW` | 默认 `flowId`（大迭代推荐设置） |
-| `FIGMA_CACHE_ADAPTER_DOC` | 覆盖 `postEnsure` 写入的适配说明文件名（默认见各项目 `figma-cache.config.js`） |
+| `FIGMA_CACHE_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_FLOW_README` | **仅包内示例钩子**：人类可读的「流程 / 需求总览」Markdown 相对路径，默认 **`docs/figma-flow-readme.md`**；每次 `ensure` 对**新 cacheKey** 幂等追加一节 |
 
 ## 人工校验清单（对照 `validate`）
@@ -174,8 +189,9 @@ npm run figma:cache:init
 - 记录包含 `fileKey` / `scope` / `url` / `syncedAt`
 - `normalizationVersion` 与当前规范一致
 - `paths.meta` 与 `paths.spec` 已定义
-- `completeness` 覆盖当前任务字段
+- `completeness` 覆盖当前任务字段，且在 `raw.json.coverageSummary.evidence` 有非空对应证据
 - `scope=node` 时存在 `nodeId`
+- 对 `source=figma-mcp` 节点，`interactions/states/accessibility` 不得仅为 TODO 占位
 - 若维护了 `flows`，边的 `from` / `to` 必须存在于 `items`
 
 ## 历史链接回填（backfill）
@@ -202,7 +218,7 @@ npm run figma:cache:stale
 
 `hooks.postEnsure` 会做两件事（均在 **Core 写完通用骨架之后**）：
 
-1. **节点目录内**：写入 **`figma-cache-adapter-hint.md`**（文件名可由 `FIGMA_CACHE_ADAPTER_DOC` 覆盖）— 提醒实现侧对齐 `spec.md` / `raw.json` 等。
+1. **adapter 提示文档（默认目录级）**：默认在 **`figma-cache/docs/figma-cache-adapter-hint.md`** 写入单文件（可由 `FIGMA_CACHE_ADAPTER_DOC_CACHE` 覆盖），避免每节点重复；如需按节点写入，可设 `FIGMA_CACHE_ADAPTER_DOC_MODE=node`。
 2. **项目根**：维护或创建 **`docs/figma-flow-readme.md`**（路径可由 **`FIGMA_CACHE_FLOW_README`** 覆盖）— 含「流程总览 / 交互边界」**手填区**，以及按 **`cacheKey` 幂等追加**的「已从 Figma 写入缓存的节点」登记（含 Figma 链接、`syncedAt`、`completeness`、相对 `spec`/`meta` 路径）。**像素级还原**仍以各节点 **`spec.md`** 为准；**用户路径图**请继续用 CLI **`flow`** 维护 `index.json`，再把 **`flow mermaid`** 贴进该 md 的 mermaid 代码块，便于评审与新人阅读。
 
 `postEnsure` 的 **`ctx`** 还包含 **`url` / `source` / `syncedAt` / `completeness`**（与 `index.json` 中 item 一致），便于自定义钩子写文档或触发 CI。
@@ -210,3 +226,10 @@ npm run figma:cache:stale
 ## 包维护者
 
 维护 **`figma-cache-toolchain` 源码**时：见**仓库根** `README.md`（发布）与 `CHANGELOG.md`；修改 `cursor-bootstrap/`（含 `AGENT-SETUP-PROMPT.md`）或 CLI 后 bump 版本并 `npm publish`，消费方 `cursor init` 才会刷新到最新任务书。将 Core 抽成独立包、semver 与 `ctx` 约定等，可在发包前对照 `CHANGELOG` 与 `npm publish --dry-run`。
+
+
+
+
+
+
+