figma-cache-toolchain 2.0.4 → 2.0.5

package/README.md

@@ -125,7 +125,6 @@ npm run figma:ui:preflight
 npm run figma:ui:audit -- --min-score=85
 npm run figma:ui:report:aggregate
 npm run figma:ui:accept -- --target=src/components/YourComponent.tsx
-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:gate
 npm run figma:ui:gate:pr
 npm run figma:ui:gate:main
@@ -144,11 +143,8 @@ UI preflight/gate 说明：
 - `figma:ui:gate` 会先跑 preflight + audit（默认阈值 `85`），再串联 `validate`、`cursor:shadow:check` 与 `npm test`
 - `figma:ui:report:aggregate` 会聚合 preflight + audit 报告，输出 `figma-cache/reports/ui-quality-summary.json`
 - `figma:ui:accept` 是一键自动验收：自动跑 preflight + audit + aggregate，并按效果阈值直接返回 pass/fail（退出码）
-- `figma:ui:e2e:cross` 是跨项目联调：自动 `npm pack` 当前包 -> 安装到目标项目 -> 执行自动验收 -> 回收报告路径与摘要
-- 支持 `--auto-ensure-on-miss`：cache miss 时自动尝试 `--source=figma-mcp ensure`
-- 支持 `--batch-file=<json>`：批量节点联调并汇总结果（单条失败即整体失败）
-- 支持 `--fix-loop=<N>`：失败后自动执行自修复重试（补 contract / 刷新缓存后重跑）
 - CI 建议矩阵：`figma:ui:gate:pr`（PR 最低门槛）与 `figma:ui:gate:main`（主干严格门槛）
+- `figma:ui:e2e:cross` 现默认启用“真实组件链路保护”：`--target` 不存在或验收出现 `code-level comparison skipped` 会直接失败，避免“未绑定真实组件但通过”的假阳性；如需兼容历史流程可显式传 `--allow-skipped-code-level-comparison`
 
 UI profile 分层（P3）：
 

package/figma-cache/docs/README.md

@@ -83,7 +83,7 @@ npm run figma:cache:config
 
 ### UI preflight（P0 门禁）
 
-- `npm run figma:ui:preflight`：读取 `index.json`、adapter contract 与节点关键文件，输出结构化报告到 `figma-cache/reports/ui-preflight-report.json`
+- `npm run figma:ui:preflight`：读取 `index.json`、adapter contract 与节点关键文件，输出结构化报告到 `figma-cache/reports/runtime/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 +97,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/ui-1to1-report.json`
+- 默认报告：`figma-cache/reports/runtime/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 +128,7 @@ npm run figma:cache:config
 - `standard`：audit 默认阈值 85
 - `strict`：preflight warning 计入阻断、audit 默认阈值 92 且要求 `--target`
 - 报告聚合：`npm run figma:ui:report:aggregate`
-  - 输出：`figma-cache/reports/ui-quality-summary.json`
+  - 输出：`figma-cache/reports/runtime/ui-quality-summary.json`
 
 ### 一键自动验收（效果导向）
 
@@ -157,6 +157,7 @@ npm run figma:cache:config
   - `--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 规则（默认）
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "figma-cache-toolchain",
-    "version": "2.0.4",
+    "version": "2.0.5",
     "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
     "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
     "keywords": [

package/scripts/cross-project-e2e.js

@@ -34,6 +34,9 @@ function parseArgs(argv) {
     completeness: "layout,text,tokens,interactions,states,accessibility",
     batchFile: "",
     fixLoop: 0,
+    emitAgentTaskOnFail: false,
+    agentTaskPath: "",
+    allowSkippedCodeLevelComparison: false,
   };
 
   argv.forEach((arg) => {
@@ -103,6 +106,18 @@ function parseArgs(argv) {
     if (arg.startsWith("--fix-loop=")) {
       const n = Number(arg.split("=").slice(1).join("=").trim());
       options.fixLoop = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+      return;
+    }
+    if (arg === "--emit-agent-task-on-fail") {
+      options.emitAgentTaskOnFail = true;
+      return;
+    }
+    if (arg.startsWith("--agent-task-path=")) {
+      options.agentTaskPath = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg === "--allow-skipped-code-level-comparison") {
+      options.allowSkippedCodeLevelComparison = true;
     }
   });
 
@@ -164,6 +179,63 @@ function normalizeSlash(input) {
   return String(input || "").replace(/\\/g, "/");
 }
 
+function writeAgentTask(targetProject, options, payload) {
+  const defaultPath = path.join(targetProject, "agent-task.md");
+  const taskPath = options.agentTaskPath
+    ? resolveMaybeAbsolutePath(options.agentTaskPath)
+    : defaultPath;
+  const lines = [];
+  lines.push("# Agent Task: UI E2E Recovery");
+  lines.push("");
+  lines.push("## Goal");
+  lines.push("Fix target project implementation so ui acceptance passes.");
+  lines.push("");
+  lines.push("## Constraints");
+  lines.push("- Must run ui acceptance after code changes.");
+  lines.push("- Do not bypass by lowering thresholds unless explicitly requested.");
+  lines.push("- Prioritize real component/contract/recipe fixes.");
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`- targetProject: ${normalizeSlash(payload.targetProject || "")}`);
+  lines.push(`- mode: ${payload.mode || "single"}`);
+  lines.push(`- profile: ${payload.profile || "standard"}`);
+  lines.push(`- autoEnsureOnMiss: ${payload.autoEnsureOnMiss ? "true" : "false"}`);
+  lines.push(`- fixLoop: ${Number(payload.fixLoop || 0)}`);
+  lines.push("");
+  lines.push("## Cases");
+  (payload.cases || []).forEach((entry, idx) => {
+    lines.push(`### Case ${idx + 1}`);
+    lines.push(`- cacheKey: ${entry.cacheKey || ""}`);
+    lines.push(`- targetPath: ${normalizeSlash(entry.targetPath || "")}`);
+    lines.push(`- reason: ${entry.reason || "unknown"}`);
+    if (entry.attemptLogs && entry.attemptLogs.length) {
+      lines.push("- attemptLogs:");
+      entry.attemptLogs.forEach((log) => {
+        lines.push(
+          `  - attempt ${log.attempt}: ${log.ok ? "ok" : "fail"}${log.reason ? ` (${log.reason})` : ""}`
+        );
+      });
+    }
+    lines.push("");
+  });
+  lines.push("## Required Command");
+  lines.push("Run this command in toolchain repo after fixes:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(payload.retryCommand || "npm run figma:ui:e2e:cross -- --target-project=<...>");
+  lines.push("```");
+  lines.push("");
+  lines.push("## Completion Criteria");
+  lines.push("- e2e command exits with code 0");
+  lines.push("- summaryStatus is healthy");
+  lines.push("- no unresolved blocking items");
+  lines.push("");
+
+  fs.mkdirSync(path.dirname(taskPath), { recursive: true });
+  fs.writeFileSync(taskPath, `${lines.join("\n")}\n`, "utf8");
+  return taskPath;
+}
+
 function parseCacheKey(cacheKey) {
   const value = String(cacheKey || "").trim();
   const [fileKey, nodeId] = value.split("#");
@@ -260,6 +332,9 @@ function runSingleCase(input, context) {
   if (!targetPath) {
     throw new Error(`batch item ${cacheKey} missing target path`);
   }
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`batch item ${cacheKey} target path does not exist: ${targetPath}`);
+  }
 
   const acceptArgs = [
     `--cacheKey=${cacheKey}`,
@@ -301,6 +376,18 @@ function runSingleCase(input, context) {
       try {
         acceptanceJson = JSON.parse(acceptanceOutput);
       } catch {}
+      if (
+        !options.allowSkippedCodeLevelComparison &&
+        acceptanceJson &&
+        Array.isArray(acceptanceJson.warnings) &&
+        acceptanceJson.warnings.some((entry) =>
+          /code-level comparison skipped/i.test(String(entry || ""))
+        )
+      ) {
+        throw new Error(
+          `acceptance produced skipped code-level comparison for ${cacheKey}; target linkage is invalid`
+        );
+      }
       attemptLogs.push({ attempt, ok: true });
       return {
         ok: true,
@@ -344,6 +431,10 @@ function run() {
       console.error("cross-project-e2e failed: --target is required for real component validation");
       process.exit(FAIL_EXIT_CODE);
     }
+    if (!fs.existsSync(targetPath)) {
+      console.error(`cross-project-e2e failed: --target path does not exist: ${targetPath}`);
+      process.exit(FAIL_EXIT_CODE);
+    }
     const cacheKey = resolveCacheKey(options);
     if (!cacheKey) {
       console.error("cross-project-e2e failed: provide --cacheKey or (--fileKey + --nodeId)");
@@ -352,6 +443,7 @@ function run() {
   }
 
   let tarballPath = "";
+  let taskPayload = null;
   try {
     tarballPath = npmPackAndGetTarball();
     runCommand(`npm i -D "${tarballPath}"`, targetProject);
@@ -404,11 +496,26 @@ function run() {
         caseFailures.push({
           index: indexNo,
           cacheKey: entry && (entry.cacheKey || resolveCacheKey(entry)),
+          targetPath: entry && entry.target,
+          attemptLogs: [],
           reason: error.message,
         });
       }
     });
     if (caseFailures.length) {
+      taskPayload = {
+        targetProject,
+        mode: isBatchMode ? "batch" : "single",
+        profile: options.profile || "standard",
+        autoEnsureOnMiss: options.autoEnsureOnMiss,
+        fixLoop: options.fixLoop,
+        cases: caseFailures,
+        retryCommand: `npm run figma:ui:e2e:cross -- --target-project=${normalizeSlash(
+          targetProject
+        )}${options.batchFile ? ` --batch-file=${normalizeSlash(options.batchFile)}` : ""}${
+          options.autoEnsureOnMiss ? " --auto-ensure-on-miss" : ""
+        }${options.fixLoop ? ` --fix-loop=${options.fixLoop}` : ""}`,
+      };
       throw new Error(`batch cases failed: ${JSON.stringify(caseFailures)}`);
     }
 
@@ -424,9 +531,9 @@ function run() {
       completeness: options.completeness,
       tarballPath,
       reports: {
-        preflight: path.join(reportBase, "ui-preflight-report.json"),
-        audit: path.join(reportBase, "ui-1to1-report.json"),
-        summary: path.join(reportBase, "ui-quality-summary.json"),
+        preflight: path.join(reportBase, "runtime", "ui-preflight-report.json"),
+        audit: path.join(reportBase, "runtime", "ui-1to1-report.json"),
+        summary: path.join(reportBase, "runtime", "ui-quality-summary.json"),
       },
       cases: caseResults,
     };
@@ -438,8 +545,42 @@ function run() {
     }
     console.log(JSON.stringify(output, null, 2));
   } catch (error) {
+    let taskPath = "";
+    if (options.emitAgentTaskOnFail) {
+      try {
+        const payload =
+          taskPayload ||
+          ({
+            targetProject,
+            mode: isBatchMode ? "batch" : "single",
+            profile: options.profile || "standard",
+            autoEnsureOnMiss: options.autoEnsureOnMiss,
+            fixLoop: options.fixLoop,
+            cases: [
+              {
+                cacheKey: resolveCacheKey(options),
+                targetPath: options.target,
+                reason: error.message,
+              },
+            ],
+            retryCommand: `npm run figma:ui:e2e:cross -- --target-project=${normalizeSlash(
+              targetProject
+            )}${options.batchFile ? ` --batch-file=${normalizeSlash(options.batchFile)}` : ""}${
+              options.cacheKey ? ` --cacheKey=${options.cacheKey}` : ""
+            }${options.fileKey ? ` --fileKey=${options.fileKey}` : ""}${
+              options.nodeId ? ` --nodeId=${options.nodeId}` : ""
+            }${options.target ? ` --target=${normalizeSlash(options.target)}` : ""}${
+              options.autoEnsureOnMiss ? " --auto-ensure-on-miss" : ""
+            }${options.fixLoop ? ` --fix-loop=${options.fixLoop}` : ""} --emit-agent-task-on-fail`,
+          });
+        taskPath = writeAgentTask(targetProject, options, payload);
+      } catch {}
+    }
     console.error("cross-project-e2e failed:");
     console.error(`- ${error.message}`);
+    if (taskPath) {
+      console.error(`- agent task emitted: ${normalizeSlash(taskPath)}`);
+    }
     process.exit(FAIL_EXIT_CODE);
   } finally {
     if (tarballPath && !options.keepPackage) {

package/scripts/ui-1to1-audit.js

@@ -11,7 +11,7 @@ const ROOT = process.cwd();
 const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
 const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
 const DEFAULT_CONTRACT_PATH = "figma-cache/adapters/ui-adapter.contract.json";
-const DEFAULT_REPORT_PATH = "figma-cache/reports/ui-1to1-report.json";
+const DEFAULT_REPORT_PATH = "figma-cache/reports/runtime/ui-1to1-report.json";
 const DEFAULT_MIN_SCORE = 85;
 const DEFAULT_RECIPES_DIR = "figma-cache/adapters/recipes";
 const FAIL_EXIT_CODE = 2;

package/scripts/ui-auto-acceptance.js

@@ -105,13 +105,13 @@ function buildReportPaths(options) {
   const cacheDir = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
   return {
     preflight: resolveMaybeAbsolutePath(
-      options.preflightReport || path.join(cacheDir, "reports", "ui-preflight-report.json")
+      options.preflightReport || path.join(cacheDir, "reports", "runtime", "ui-preflight-report.json")
     ),
     audit: resolveMaybeAbsolutePath(
-      options.auditReport || path.join(cacheDir, "reports", "ui-1to1-report.json")
+      options.auditReport || path.join(cacheDir, "reports", "runtime", "ui-1to1-report.json")
     ),
     summary: resolveMaybeAbsolutePath(
-      options.summaryReport || path.join(cacheDir, "reports", "ui-quality-summary.json")
+      options.summaryReport || path.join(cacheDir, "reports", "runtime", "ui-quality-summary.json")
     ),
   };
 }

package/scripts/ui-preflight.js

@@ -10,7 +10,7 @@ const ROOT = process.cwd();
 const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
 const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
 const DEFAULT_CONTRACT_PATH = "figma-cache/adapters/ui-adapter.contract.json";
-const DEFAULT_REPORT_PATH = "figma-cache/reports/ui-preflight-report.json";
+const DEFAULT_REPORT_PATH = "figma-cache/reports/runtime/ui-preflight-report.json";
 const BLOCKING_EXIT_CODE = 2;
 
 function normalizeSlash(input) {

package/scripts/ui-report-aggregate.js

@@ -8,7 +8,7 @@ const { getUiProfileConfig } = require("./ui-profile");
 
 const ROOT = process.cwd();
 const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
-const DEFAULT_OUTPUT_PATH = "figma-cache/reports/ui-quality-summary.json";
+const DEFAULT_OUTPUT_PATH = "figma-cache/reports/runtime/ui-quality-summary.json";
 
 function resolveMaybeAbsolutePath(input) {
   if (!input) {
@@ -62,10 +62,10 @@ function run() {
   const options = parseArgs(process.argv.slice(2));
   const cacheDir = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
   const preflightPath = resolveMaybeAbsolutePath(
-    options.preflightReport || path.join(cacheDir, "reports", "ui-preflight-report.json")
+    options.preflightReport || path.join(cacheDir, "reports", "runtime", "ui-preflight-report.json")
   );
   const auditPath = resolveMaybeAbsolutePath(
-    options.auditReport || path.join(cacheDir, "reports", "ui-1to1-report.json")
+    options.auditReport || path.join(cacheDir, "reports", "runtime", "ui-1to1-report.json")
   );
   const outputPath = resolveMaybeAbsolutePath(options.output);
   const profileConfig = getUiProfileConfig();