figma-cache-toolchain 2.0.5 → 2.0.7

package/figma-cache/docs/README.md

@@ -70,7 +70,7 @@ npm run figma:cache:config
 - `npm run figma:ui:audit -- --min-score=85`
 - `npm run figma:ui:report:aggregate`
 - `npm run figma:ui:accept -- --target=<componentPath>`
-- `npm run figma:ui:e2e:cross -- --target-project=E:/Work/vue-demo --fileKey=<fileKey> --nodeId=9277-28772 --target=E:/Work/vue-demo/src/components/YourComponent.vue`
+- `npm run figma:ui:e2e:cross -- --target-project=../vue-demo --fileKey=<fileKey> --nodeId=9277-28772 --target=./src/pages/main/components/AudioSettingsPanel.vue`（路径均相对于各自根目录；`../vue-demo` 表示与 toolchain 并列）
 - `npm run figma:ui:gate`
 - `npm run figma:ui:gate:pr`
 - `npm run figma:ui:gate:main`
@@ -81,9 +81,18 @@ npm run figma:cache:config
 > 当 `upsert/ensure` 传 `--source=figma-mcp` 且未显式允许骨架模式时，CLI 会先执行 MCP 原始证据门禁（缺失即失败，退出码 2）。
 > 正确流程是先由 Agent/Figma MCP 获取最小调用集并写入 `mcp-raw/`，再执行 `upsert/ensure` 与 `validate`。
 
+### Fresh 重生成回归（推荐）
+
+- 目标项目推荐一条命令：`npm run figma:workflow:fresh:one-shot`（删 -> 等文件 -> 验收 + build）
+- 备选拆分：
+  - `npm run figma:workflow:fresh:start`（删除 target，并要求“缺失目标失败”）
+  - `npm run figma:workflow:fresh:verify`（Agent 重生成后验收通过）
+  - `npm run figma:workflow:fresh:wait-verify`（仅等待 target 出现后自动验收）
+- `cross-project-e2e` 默认开启真实组件链路保护：`target` 缺失或出现 `code-level comparison skipped` 会直接失败
+
 ### UI preflight（P0 门禁）
 
-- `npm run figma:ui:preflight`：读取 `index.json`、adapter contract 与节点关键文件，输出结构化报告到 `figma-cache/reports/runtime/ui-preflight-report.json`
+- `npm run figma:ui:preflight`：读取 `index.json`、adapter contract 与节点关键文件，输出结构化报告到 `figma-cache/reports/ui-preflight-report.json`
 - 支持参数：`--cacheKey=<fileKey#nodeId>`、`--contract=<path>`、`--report=<path>`、`--allow-warn`
 - 阻断项返回退出码 `2`：包括 cacheKey 不存在、关键文件缺失、coverage evidence 不完整、contract 缺失或映射为空、`source=figma-mcp` 时缺失 `mcp-raw-manifest.json`
 - warning 项（不阻断）会提示 `spec.md`/`state-map.md` 中的 TODO 占位
@@ -97,7 +106,7 @@ npm run figma:cache:config
 ### UI 1:1 audit（P1 质量评分）
 
 - `npm run figma:ui:audit -- --cacheKey=<fileKey#nodeId> --target=<componentPath> --min-score=85`
-- 默认报告：`figma-cache/reports/runtime/ui-1to1-report.json`
+- 默认报告：`figma-cache/reports/ui-1to1-report.json`
 - 报告结构遵循：`figma-cache/docs/ui-1to1-report.schema.json`
 - 评分字段：`score.total/layout/text/token/state/interaction`
 - `score.total` 低于 `--min-score` 会返回退出码 `2`（可用于 CI 门禁）
@@ -128,7 +137,7 @@ npm run figma:cache:config
 - `standard`：audit 默认阈值 85
 - `strict`：preflight warning 计入阻断、audit 默认阈值 92 且要求 `--target`
 - 报告聚合：`npm run figma:ui:report:aggregate`
-  - 输出：`figma-cache/reports/runtime/ui-quality-summary.json`
+  - 输出：`figma-cache/reports/ui-quality-summary.json`
 
 ### 一键自动验收（效果导向）
 
@@ -140,25 +149,6 @@ npm run figma:cache:config
   - 必须提供并命中 `targetPath`
   - warning/diff 需在阈值内（可通过 `--max-warnings`、`--max-diffs` 调整）
 
-### 跨项目联调（toolchain -> 业务项目）
-
-- 命令：`npm run figma:ui:e2e:cross`
-- 自动流程：
-  1) 在当前 toolchain 项目执行 `npm pack`
-  2) 在目标项目安装本地 tgz
-  3) 在目标项目执行 `ui-auto-acceptance`
-  4) 输出目标项目报告路径与汇总指标
-- 推荐参数：
-  - `--target-project=E:/Work/vue-demo`
-  - `--fileKey=<fileKey>` + `--nodeId=9277-28772`（会自动标准化为 `9277:28772`）
-  - 或直接 `--cacheKey=<fileKey#9277:28772>`
-- 可选增强：
-  - `--auto-ensure-on-miss`：cache miss 时自动触发 figma-mcp ensure
-  - `--allow-skeleton-with-figma-mcp`：允许 skeleton 写入（仅建议应急）
-  - `--batch-file=<json>`：批量执行，多节点一次联调
-  - `--fix-loop=<N>`：失败自动重试 N 轮（重试前会补 contract 并刷新缓存）
-  - `--emit-agent-task-on-fail`：失败自动产出 `agent-task.md`，用于交给 Cursor Agent 接力修复
-
 ### 严格 validate 规则（默认）
 
 - `validate` 会检查 `raw.json.coverageSummary.evidence` 与 `completeness` 是否一致。

package/figma-cache/docs/raw-json-extensions.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://figma-cache-toolchain/raw-json-extensions",
+  "title": "figma-cache raw.json optional extensions",
+  "description": "Loose schema for machine-derived fields merged during MCP hydrate. Core raw.json fields are not fully specified here.",
+  "type": "object",
+  "properties": {
+    "iconMetrics": {
+      "type": "array",
+      "description": "Icon box + inset metrics extracted from get_design_context (heuristic)."
+    },
+    "layoutMetrics": {
+      "type": "array",
+      "description": "Layout numbers merged from mcp-raw/figma-geometry-metrics.json (e.g. spacer_between_nodes_y)."
+    },
+    "relatedCacheKeys": {
+      "type": "array",
+      "description": "Peer cacheKeys linked via index.json flows (edge.type starts with \"related\", e.g. related_auto). Hydrate refresh overwrites from current index.",
+      "items": { "type": "string" }
+    },
+    "evidenceSummary": {
+      "type": "object",
+      "description": "Non-gating observability counts after hydrate (design context size, refs, geometry sidecar presence).",
+      "properties": {
+        "version": { "type": "integer" },
+        "generatedAt": { "type": "string" },
+        "designContextBytes": { "type": "integer", "minimum": 0 },
+        "metadataBytes": { "type": "integer", "minimum": 0 },
+        "dataNodeIdRefs": { "type": "integer", "minimum": 0 },
+        "dataNodeIdContainsScope": { "type": ["boolean", "null"] },
+        "designContextImgConstDefinitions": { "type": "integer", "minimum": 0 },
+        "imgTagOccurrences": { "type": "integer", "minimum": 0 },
+        "figmaAssetUrlOccurrences": { "type": "integer", "minimum": 0 },
+        "approximateHexColorLiterals": { "type": "integer", "minimum": 0 },
+        "variableDefKeys": { "type": "integer", "minimum": 0 },
+        "geometryFilePresent": { "type": "boolean" },
+        "iconMetricsCount": { "type": "integer", "minimum": 0 },
+        "layoutMetricsCount": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/figma-cache/figma-cache.js

@@ -10,6 +10,7 @@ const { buildBudgetReport } = require("./js/budget-cli");
 const { createIndexStore } = require("./js/index-store");
 const { copyCursorBootstrap } = require("./js/cursor-bootstrap-cli");
 const { createEntryFilesService } = require("./js/entry-files");
+const { getRelatedCacheKeysFromIndex } = require("./js/related-cache-keys");
 const { backfillFromIterations } = require("./js/backfill-cli");
 const { createUpsertService } = require("./js/upsert-core");
 const { createProjectConfigService } = require("./js/project-config");
@@ -179,6 +180,8 @@ const entryFilesService = createEntryFilesService({
   normalizeCompletenessList,
   completenessAllDimensions: COMPLETENESS_ALL_DIMENSIONS,
   runPostEnsureHook,
+  getRelatedCacheKeys: (cacheKey) =>
+    getRelatedCacheKeysFromIndex(cacheKey, normalizeIndexShape(readIndex())),
 });
 const { ensureEntryFilesAndHook } = entryFilesService;
 
@@ -403,6 +406,12 @@ function run() {
     console.log(
       `  ${ex} ensure <figmaUrl> [--source=manual] [--completeness=a,b] [--allow-skeleton-with-figma-mcp]  (default completeness=${defaultCompletenessText})`,
     );
+    console.log(
+      `  ${ex} enrich <figmaUrl> [--allow-skeleton-with-figma-mcp]  # re-run entry hydrate from index + mcp-raw (no index upsert)`,
+    );
+    console.log(
+      `  ${ex} enrich --all [--allow-skeleton-with-figma-mcp]  # same for every figma-mcp item in index.json`,
+    );
     console.log(`  ${ex} init`);
     console.log(`  ${ex} config`);
     console.log(
@@ -493,6 +502,108 @@ function run() {
     return;
   }
 
+  if (cmd === "enrich") {
+    const allowSkeletonWithFigmaMcp = args.includes("--allow-skeleton-with-figma-mcp");
+    const enrichAll = args.includes("--all");
+    const validateDeps = {
+      fs,
+      path,
+      resolveMaybeAbsolutePath,
+      safeReadJson,
+      normalizeSlash,
+      normalizeCompletenessList,
+      completenessToolRequirements: COMPLETENESS_TOOL_REQUIREMENTS,
+    };
+    if (enrichAll) {
+      const index = normalizeIndexShape(readIndex());
+      const failures = [];
+      const successes = [];
+      Object.entries(index.items || {}).forEach(([cacheKey, item]) => {
+        if (!item || item.source !== "figma-mcp") {
+          return;
+        }
+        const completeness = normalizeCompletenessList(item.completeness);
+        const mcpErrors = validateMcpRawEvidence(
+          cacheKey,
+          item,
+          completeness,
+          { allowSkeletonWithFigmaMcp },
+          validateDeps,
+        );
+        if (mcpErrors.length) {
+          failures.push({ cacheKey, errors: mcpErrors });
+          return;
+        }
+        ensureEntryFilesAndHook(cacheKey, item);
+        successes.push(cacheKey);
+      });
+      console.log(
+        JSON.stringify(
+          {
+            ok: failures.length === 0,
+            enriched: successes.length,
+            cacheKeys: successes,
+            failures,
+          },
+          null,
+          2,
+        ),
+      );
+      if (failures.length) {
+        process.exit(2);
+      }
+      return;
+    }
+    const positional = args.filter(
+      (x) =>
+        x !== "--all" &&
+        !x.startsWith("--allow-skeleton-with-figma-mcp") &&
+        !x.startsWith("--"),
+    );
+    const url = positional[0];
+    if (!url) {
+      console.error(
+        "Usage: figma-cache enrich <figmaUrl> [--allow-skeleton-with-figma-mcp]\n       figma-cache enrich --all [--allow-skeleton-with-figma-mcp]",
+      );
+      process.exit(1);
+    }
+    const normalized = normalizeFigmaUrl(url);
+    const index = normalizeIndexShape(readIndex());
+    const item = getItem(index, normalized.cacheKey);
+    if (!item) {
+      console.error(`enrich failed: cacheKey not found in index: ${normalized.cacheKey}`);
+      process.exit(2);
+    }
+    if (item.source === "figma-mcp") {
+      const completeness = normalizeCompletenessList(item.completeness);
+      const mcpErrors = validateMcpRawEvidence(
+        normalized.cacheKey,
+        item,
+        completeness,
+        { allowSkeletonWithFigmaMcp },
+        validateDeps,
+      );
+      if (mcpErrors.length) {
+        console.error("enrich failed: source=figma-mcp but MCP raw evidence is incomplete");
+        mcpErrors.forEach((err) => console.error(`- ${err}`));
+        process.exit(2);
+      }
+    }
+    ensureEntryFilesAndHook(normalized.cacheKey, item);
+    console.log(
+      JSON.stringify(
+        {
+          cacheKey: normalized.cacheKey,
+          enriched: true,
+          paths: item.paths,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
   if (cmd === "validate") {
     const index = readIndex();
     const errors = validateIndex(index, {

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

@@ -1,5 +1,8 @@
 /* eslint-disable no-console */
 
+const { mergeLayoutMetricsFromGeometry, buildEvidenceSummary } = require("./raw-derivatives");
+const { itemCacheKeyFromItem } = require("./related-cache-keys");
+
 function createEntryFilesService(deps) {
   const {
     fs,
@@ -8,6 +11,7 @@ function createEntryFilesService(deps) {
     normalizeCompletenessList,
     completenessAllDimensions,
     runPostEnsureHook,
+    getRelatedCacheKeys,
   } = deps;
 
   function ensureFileWithDefault(relativePath, fallbackContent) {
@@ -37,6 +41,18 @@ function createEntryFilesService(deps) {
     }
   }
 
+  function writeJson(absPath, value) {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  }
+
+  function upsertJsonFile(absPath, buildDefault, mutate) {
+    const current = safeReadJson(absPath);
+    const next = current && typeof current === "object" ? current : buildDefault();
+    const mutated = mutate(next) || next;
+    writeJson(absPath, mutated);
+  }
+
   function isPlaceholderText(input) {
     const text = String(input || "");
     return /(TODO|TBD|待补充|待完善|待确认|占位)/i.test(text);
@@ -83,6 +99,92 @@ function createEntryFilesService(deps) {
     };
   }
 
+  function parseInsetShorthand(input) {
+    const text = String(input || "").trim();
+    if (!text) return null;
+    const normalized = text.replace(/^\[|\]$/g, "");
+    const parts = normalized
+      .split("_")
+      .map((x) => String(x || "").trim())
+      .filter(Boolean);
+    if (!parts.length) return null;
+    const values = parts.map((p) => {
+      const m = p.match(/^(-?\d+(?:\.\d+)?)%$/);
+      return m ? Number(m[1]) : NaN;
+    });
+    if (values.some((n) => !Number.isFinite(n))) return null;
+    if (values.length === 1) {
+      return { top: values[0], right: values[0], bottom: values[0], left: values[0] };
+    }
+    if (values.length === 2) {
+      return { top: values[0], right: values[1], bottom: values[0], left: values[1] };
+    }
+    if (values.length === 3) {
+      return { top: values[0], right: values[1], bottom: values[2], left: values[1] };
+    }
+    return { top: values[0], right: values[1], bottom: values[2], left: values[3] };
+  }
+
+  function percentToPx(percent, boxPx) {
+    return (Number(percent) / 100) * Number(boxPx);
+  }
+
+  function extractIconMetricsFromDesignContext(designContextText) {
+    const text = String(designContextText || "");
+    if (!text) return [];
+
+    // Heuristic: icon outer container has size-[Npx] + data-node-id + data-name.
+    // The immediate inner vector wrapper often uses absolute inset-[..%..] specifying padding.
+    const outerRe =
+      /<div[^>]*className="[^"]*?\bsize-\[(\d+)px\][^"]*?"[^>]*data-node-id="([^"]+)"[^>]*data-name="([^"]+)"[^>]*>/gi;
+    const insetRe = /\babsolute\b[^"]*?\binset-\[([^\]]+)\]/i;
+
+    const metrics = [];
+    let outerMatch = null;
+    while ((outerMatch = outerRe.exec(text))) {
+      const box = Number(outerMatch[1]);
+      const outerNodeId = String(outerMatch[2] || "").trim();
+      const outerName = String(outerMatch[3] || "").trim();
+      if (!Number.isFinite(box) || box <= 0) continue;
+      const searchStart = outerRe.lastIndex;
+      const window = text.slice(searchStart, Math.min(text.length, searchStart + 900));
+      const insetMatch = window.match(insetRe);
+      if (!insetMatch) continue;
+      const insetRaw = `[${String(insetMatch[1] || "").trim()}]`;
+      const parsed = parseInsetShorthand(insetRaw);
+      if (!parsed) continue;
+
+      const topPx = percentToPx(parsed.top, box);
+      const rightPx = percentToPx(parsed.right, box);
+      const bottomPx = percentToPx(parsed.bottom, box);
+      const leftPx = percentToPx(parsed.left, box);
+      const glyphW = box - leftPx - rightPx;
+      const glyphH = box - topPx - bottomPx;
+
+      metrics.push({
+        nodeId: outerNodeId,
+        name: outerName,
+        boxPx: box,
+        insetPercent: { ...parsed },
+        insetPx: {
+          top: Number(topPx.toFixed(4)),
+          right: Number(rightPx.toFixed(4)),
+          bottom: Number(bottomPx.toFixed(4)),
+          left: Number(leftPx.toFixed(4)),
+        },
+        glyphPx: {
+          width: Number(glyphW.toFixed(4)),
+          height: Number(glyphH.toFixed(4)),
+        },
+        source: {
+          kind: "design_context_inset_percent",
+          insetRaw,
+        },
+      });
+    }
+    return metrics;
+  }
+
   function extractLayoutSummary(metadataText, fallbackName) {
     const text = String(metadataText || "");
     const idMatch = text.match(/id="([^"]+)"/);
@@ -100,11 +202,11 @@ function createEntryFilesService(deps) {
 
   function extractTextCandidates(designContextText) {
     const text = String(designContextText || "");
-    const regex = /<p[^>]*>\s*([^<\n][^<]{0,120})\s*<\/p>/g;
+    const regex = /<(p|div|span)[^>]*>\s*([^<\n][^<]{0,120})\s*<\/(p|div|span)>/g;
     const output = [];
     let match = null;
     while ((match = regex.exec(text))) {
-      const value = String(match[1] || "").replace(/\s+/g, " ").trim();
+      const value = String(match[2] || "").replace(/\s+/g, " ").trim();
       if (!value) {
         continue;
       }
@@ -227,16 +329,58 @@ function createEntryFilesService(deps) {
 
     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");
-    }
+    // Always refresh mcp-hydrated entry files to avoid stale evidence summaries
+    // when completeness changes or when earlier runs wrote placeholder content.
+    fs.writeFileSync(specAbs, buildMcpHydratedSpecContent(item, evidence), "utf8");
+    fs.writeFileSync(stateMapAbs, buildMcpHydratedStateMapContent(item), "utf8");
     hydrateRawTodoNotesIfNeeded(item, evidence);
+
+    // Persist machine-friendly icon metrics for 1:1 icon glyph sizing,
+    // optional layoutMetrics from mcp-raw/figma-geometry-metrics.json (Figma Plugin API / bounding boxes),
+    // and evidenceSummary (observability only; not used for validate gates).
+    try {
+      const iconMetrics = extractIconMetricsFromDesignContext(evidence.designContextText);
+      const rawAbs = resolveMaybeAbsolutePath(item.paths.raw);
+      const nodeDir = findNodeDirByItem(item);
+      const geometryAbs = nodeDir
+        ? path.join(nodeDir, "mcp-raw", "figma-geometry-metrics.json")
+        : "";
+      const geometry = geometryAbs ? safeReadJson(geometryAbs) : null;
+      const geometryFilePresent = !!(geometryAbs && fs.existsSync(geometryAbs));
+      upsertJsonFile(
+        rawAbs,
+        () => JSON.parse(buildDefaultRawContent(item)),
+        (next) => {
+          next.iconMetrics = iconMetrics;
+          mergeLayoutMetricsFromGeometry(next, geometry);
+          const iconN = Array.isArray(next.iconMetrics) ? next.iconMetrics.length : 0;
+          const layoutN = Array.isArray(next.layoutMetrics) ? next.layoutMetrics.length : 0;
+          next.evidenceSummary = buildEvidenceSummary({
+            designContextText: evidence.designContextText,
+            metadataText: evidence.metadataText,
+            variableDefs: evidence.variableDefs,
+            nodeId: item.nodeId || "",
+            geometryFilePresent,
+            iconMetricsCount: iconN,
+            layoutMetricsCount: layoutN,
+          });
+          let relatedCacheKeys = [];
+          if (typeof getRelatedCacheKeys === "function") {
+            try {
+              relatedCacheKeys = getRelatedCacheKeys(itemCacheKeyFromItem(item)) || [];
+            } catch {
+              relatedCacheKeys = [];
+            }
+          }
+          if (Array.isArray(relatedCacheKeys) && relatedCacheKeys.length) {
+            next.relatedCacheKeys = relatedCacheKeys;
+          } else {
+            delete next.relatedCacheKeys;
+          }
+          return next;
+        }
+      );
+    } catch {}
   }
 
   function buildCoverageSummary(completeness) {
@@ -254,6 +398,8 @@ function createEntryFilesService(deps) {
         accessibility: covered.includes("accessibility")
           ? ["state-map.md#accessibility"]
           : [],
+        flow: covered.includes("flow") ? ["spec.md#flow"] : [],
+        assets: covered.includes("assets") ? ["mcp-raw/get_design_context#assets"] : [],
       },
     };
   }
@@ -332,24 +478,51 @@ function createEntryFilesService(deps) {
   }
 
   function ensureEntryFiles(item) {
-    ensureFileWithDefault(
-      item.paths.meta,
-      `${JSON.stringify(
-        {
-          fileKey: item.fileKey,
-          nodeId: item.nodeId,
-          scope: item.scope,
-          source: item.source,
-          syncedAt: item.syncedAt,
-          completeness: normalizeCompletenessList(item.completeness),
-        },
-        null,
-        2
-      )}\n`
+    const metaAbs = resolveMaybeAbsolutePath(item.paths.meta);
+    const rawAbs = resolveMaybeAbsolutePath(item.paths.raw);
+    const completeness = normalizeCompletenessList(item.completeness);
+
+    // Always keep meta/raw in sync with latest ensure/upsert, even if files already exist.
+    upsertJsonFile(
+      metaAbs,
+      () => ({
+        fileKey: item.fileKey,
+        nodeId: item.nodeId,
+        scope: item.scope,
+        source: item.source,
+        syncedAt: item.syncedAt,
+        completeness,
+      }),
+      (next) => {
+        next.fileKey = item.fileKey;
+        next.nodeId = item.nodeId;
+        next.scope = item.scope;
+        next.source = item.source;
+        next.syncedAt = item.syncedAt;
+        next.completeness = completeness;
+        return next;
+      }
     );
+
     ensureFileWithDefault(item.paths.spec, buildDefaultSpecContent(item));
     ensureFileWithDefault(item.paths.stateMap, buildDefaultStateMapContent(item));
-    ensureFileWithDefault(item.paths.raw, buildDefaultRawContent(item));
+    if (!fs.existsSync(rawAbs)) {
+      ensureFileWithDefault(item.paths.raw, buildDefaultRawContent(item));
+    }
+    upsertJsonFile(
+      rawAbs,
+      () => JSON.parse(buildDefaultRawContent(item)),
+      (next) => {
+        next.source = item.source;
+        next.fileKey = item.fileKey;
+        next.nodeId = item.nodeId;
+        next.scope = item.scope;
+        next.syncedAt = item.syncedAt;
+        next.completeness = completeness;
+        next.coverageSummary = buildCoverageSummary(completeness);
+        return next;
+      }
+    );
     hydrateMcpEntryFilesIfNeeded(item);
   }
 

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

@@ -9,6 +9,41 @@ function slugifyFlowId(name) {
   return raw || `flow-${Date.now()}`;
 }
 
+function normalizeNodeId(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  return value.includes(":") ? value : value.replace(/-/g, ":");
+}
+
+function normalizeCacheKey(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  const parts = value.split("#");
+  if (parts.length !== 2) return value;
+  return `${parts[0]}#${normalizeNodeId(parts[1])}`;
+}
+
+function resolveCacheKeyOrUrl(input, deps) {
+  const text = String(input || "").trim();
+  if (!text) return { kind: "empty", cacheKey: "" };
+
+  // Shorthand: <fileKey>#<nodeId>
+  if (text.includes("#")) {
+    return { kind: "cacheKey", cacheKey: normalizeCacheKey(text) };
+  }
+
+  // Shorthand: <nodeId> with default fileKey
+  if (/^(?:-?\d+[:-]-?\d+)$/.test(text)) {
+    const fileKey = process.env.FIGMA_DEFAULT_FILEKEY || "";
+    if (fileKey) {
+      return { kind: "cacheKey", cacheKey: `${fileKey}#${normalizeNodeId(text)}` };
+    }
+  }
+
+  // Fallback: treat as URL
+  return { kind: "url", cacheKey: deps.normalizeFigmaUrl(text).cacheKey, url: text };
+}
+
 function ensureFlow(index, flowId, meta, normalizeIndexShape) {
   const normalized = normalizeIndexShape(index);
   normalized.flows = normalized.flows || {};
@@ -91,13 +126,14 @@ function handleFlowCommand(args, deps) {
       console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
       process.exit(1);
     }
-    const url = rest.find((x) => !x.startsWith("--"));
+    const input = rest.find((x) => !x.startsWith("--"));
     const ensureArg = rest.includes("--ensure");
     const sourceArg = rest.find((x) => x.startsWith("--source="));
     const source = sourceArg ? sourceArg.split("=")[1] : "manual";
     const { completeness } = parseCompletenessFromArgs(rest);
     const index = normalizeIndexShape(readIndex());
-    const normalized = normalizeFigmaUrl(url);
+    const resolved = resolveCacheKeyOrUrl(input, { normalizeFigmaUrl });
+    const normalized = { cacheKey: resolved.cacheKey };
     if (!ensureArg && !getItem(index, normalized.cacheKey)) {
       console.error(
         `Missing cache item for ${normalized.cacheKey}. Run figma:cache:ensure first, or pass --ensure.`
@@ -105,7 +141,16 @@ function handleFlowCommand(args, deps) {
       process.exit(2);
     }
     if (ensureArg) {
-      upsertByUrl(url, { source, completeness });
+      if (resolved.kind !== "url" || !resolved.url) {
+        console.error(
+          `flow add-node --ensure requires a Figma URL. Got shorthand "${String(input || "").trim()}".`
+        );
+        console.error(
+          `Tip: set FIGMA_DEFAULT_FILEKEY and run figma:cache:ensure for this node first, then re-run flow add-node without --ensure.`
+        );
+        process.exit(2);
+      }
+      upsertByUrl(resolved.url, { source, completeness });
       const refreshed = normalizeIndexShape(readIndex());
       const item = getItem(refreshed, normalized.cacheKey);
       if (item) {
@@ -140,8 +185,8 @@ function handleFlowCommand(args, deps) {
     }
     const type = typeArg ? typeArg.split("=")[1] : "related";
     const note = noteArg ? noteArg.split("=").slice(1).join("=") : "";
-    const from = normalizeFigmaUrl(urls[0]).cacheKey;
-    const to = normalizeFigmaUrl(urls[1]).cacheKey;
+    const from = resolveCacheKeyOrUrl(urls[0], { normalizeFigmaUrl }).cacheKey;
+    const to = resolveCacheKeyOrUrl(urls[1], { normalizeFigmaUrl }).cacheKey;
     const index = normalizeIndexShape(readIndex());
     if (!getItem(index, from) || !getItem(index, to)) {
       console.error("Missing cache item for from/to. Cache urls first with ensure/upsert.");
@@ -169,7 +214,7 @@ function handleFlowCommand(args, deps) {
       process.exit(1);
     }
     const index = normalizeIndexShape(readIndex());
-    const keys = urls.map((u) => normalizeFigmaUrl(u).cacheKey);
+    const keys = urls.map((u) => resolveCacheKeyOrUrl(u, { normalizeFigmaUrl }).cacheKey);
     keys.forEach((k) => {
       if (!getItem(index, k)) {
         console.error(`Missing cache item for ${k}. Ensure each url is cached first.`);