miaoda-game-devkit 0.2.3 → 0.2.5

package/README.md

@@ -17,10 +17,14 @@ Scene 命令、restart、业务 checkpoint 和销毁。玩法测试可以调用
 `host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断业务语义，
 authoritative state 仍必须由测试显式断言。
 
-玩法测试应优先使用 `gameplayTest`。它在 Vitest 收集阶段写入静态 contract metadata，
-在执行阶段绑定 HEADLESS host，并在 `onTestFinished` 校验 Ledger。`gameplayAudit` reporter
-会在测试执行前报告未声明或重复的 contract，在测试结束后汇总缺失、失败、证据不足、
-Scene 未访问和 registry 不一致。`registerGameplayContract` 保留为不参加执行前预检的低层接口。
+玩法测试应优先使用 `gameplayTest`。它在 Vitest 收集阶段写入测试声明，
+在执行阶段绑定 HEADLESS host，并在 `onTestFinished` 校验 Ledger。配置加载阶段会先校验
+交互项目的最低基线：至少一个 `kind: "playthrough"` contract 必须要求真实输入、完整帧和
+语义 checkpoint，每个非入口 Scene 必须有生产转场覆盖；检测到 `scene.restart()` 时还必须
+声明 `flows.restart: true` 和 `kind: "recovery"` contract。配置预检失败时测试和 coverage
+都不会运行。配置通过后，`gameplayAudit` reporter 才会检查测试声明，并在结束时汇总
+缺失、失败、证据不足、Scene 未访问和 registry 不一致。`registerGameplayContract` 保留为
+不参加执行前预检的低层接口。
 
 模板直接调用开发工具包提供的命令行程序：
 
@@ -83,7 +87,12 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 断言 authoritative state 后调用 `host.checkpoint("progress")`、
 `host.checkpoint("recovery")` 等稳定检查点，并在清单中通过 `requireCheckpoint` 声明。
 运行结束会输出稳定的 `GAMEPLAY_AUDIT: ALL CONTRACTS PASSED` 或
-`GAMEPLAY_AUDIT: ... FAILED` 标识。
+`GAMEPLAY_AUDIT: ... FAILED` 标识。该标识只表示玩法证据审计；`pnpm test` 的整体结果
+必须以最后的 `TEST_RESULT: PASS` 或 `TEST_RESULT: FAIL` 为准。失败报告会合并重复的问题，
+并给出按类别去重的修复建议，先处理列出的原始测试错误，再重新运行 `pnpm test`。
+
+共享 Vitest 配置使用 `minimal` reporter 和 `text-summary` coverage reporter，保留失败
+定位、Scene 覆盖摘要和最终机器标识，同时避免输出完整测试列表和逐文件噪声。
 
 ## 发布顺序
 

package/dist/lint/gameplay-audit.contract.mjs

@@ -217,7 +217,7 @@ function auditGameplayCollection(options2, file, tests) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
       issues.push(
-        `\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "${contract.id}"\uFF08${normalizedFile}\uFF09\u3002`
+        `\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "${contract.id}" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08${normalizedFile}\uFF09\u3002`
       );
     } else if (matches.length > 1) {
       issues.push(
@@ -248,12 +248,15 @@ function auditGameplayCollection(options2, file, tests) {
 function getGameplayEvidenceIssues(id, requirements, evidence) {
   const issues = [];
   const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
-  if (requirements.requireInput && inputEvents === 0)
+  if (requirements.requireInput && inputEvents === 0) {
     issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
-  if (requirements.requireFrameAdvance && evidence.frames === 0)
+  }
+  if (requirements.requireFrameAdvance && evidence.frames === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
-  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+  }
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  }
   for (const target of normalizeList(requirements.requireTransition)) {
     if (!evidence.transitions.some((transition) => transition.to === target)) {
       issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
@@ -264,21 +267,24 @@ function getGameplayEvidenceIssues(id, requirements, evidence) {
       issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
   }
   for (const scene of normalizeList(requirements.requireRestart)) {
-    if (!evidence.restartedScenes.includes(scene))
+    if (!evidence.restartedScenes.includes(scene)) {
       issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+    }
   }
   for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
-    if (!evidence.checkpoints.includes(checkpoint))
+    if (!evidence.checkpoints.includes(checkpoint)) {
       issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+    }
   }
-  if (requirements.requireDestroy && !evidence.destroyed)
+  if (requirements.requireDestroy && !evidence.destroyed) {
     issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  }
   return issues;
 }
 function auditGameplayRun(options2, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
-  const acceptedEvidence = [];
+  const observedEvidence = [];
   for (const expected of options2.contracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
@@ -294,6 +300,7 @@ function auditGameplayRun(options2, tests) {
     const test = matches[0];
     const metadata = test?.metadata;
     if (!test || !metadata) continue;
+    if (metadata.evidence) observedEvidence.push(metadata.evidence);
     if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
       issues.push(
         `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
@@ -314,7 +321,6 @@ function auditGameplayRun(options2, tests) {
       metadata.evidence
     );
     issues.push(...evidenceIssues);
-    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
@@ -325,14 +331,15 @@ function auditGameplayRun(options2, tests) {
     }
   }
   const registeredScenes = normalizeSet(
-    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+    observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options2.scenes);
   for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene))
+    if (!registeredScenes.includes(scene)) {
       issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
       );
+    }
   }
   for (const scene of registeredScenes) {
     if (!expectedScenes.includes(scene))
@@ -343,6 +350,81 @@ function auditGameplayRun(options2, tests) {
   return { passed: issues.length === 0, issues: [...new Set(issues)] };
 }
 
+// src/gameplay-audit-reporter.ts
+import { relative } from "path";
+function formatGameplayIssues(issues) {
+  const groups = /* @__PURE__ */ new Map();
+  const repairKeys = /* @__PURE__ */ new Set();
+  const repairs = [];
+  const repairText = {
+    input: "\u8F93\u5165\uFF1A\u5148\u63A8\u8FDB\u4E00\u5E27\uFF0C\u518D\u901A\u8FC7 host.input.mouse\u3001host.input.keyboard \u6216 host.input.touch \u9A71\u52A8\u771F\u5B9E\u751F\u4EA7\u8F93\u5165\u3002",
+    frames: "\u5E27\u63A8\u8FDB\uFF1A\u5728\u8F93\u5165\u6216\u751F\u4EA7\u547D\u4EE4\u540E\u8C03\u7528 host.stepFrames()\uFF0C\u5F02\u6B65 update \u4F7F\u7528 host.stepFramesAsync()\u3002",
+    physics: "\u7269\u7406\uFF1A\u4EC5\u5728\u751F\u4EA7\u4F7F\u7528 Arcade Physics \u65F6\u8C03\u7528 host.stepPhysics()\uFF1B\u5176\u4ED6\u7269\u7406\u7CFB\u7EDF\u4F7F\u7528\u5B8C\u6574\u5E27\u3002",
+    transition: "\u8F6C\u573A\uFF1Aboot \u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u751F\u4EA7\u8F6C\u573A\u547D\u4EE4\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u65AD\u8A00\u6E90/\u76EE\u6807\u72B6\u6001\u3002",
+    visit: "Scene\uFF1A\u786E\u8BA4\u6D4B\u8BD5\u901A\u8FC7\u771F\u5B9E\u5165\u53E3\u6216\u5408\u6CD5\u8F6C\u573A\u8BBF\u95EE\u8BE5 Scene\uFF0C\u5E76\u4F7F\u7528\u771F\u5B9E\u914D\u7F6E\u542F\u52A8\u3002",
+    restart: "\u6062\u590D\uFF1A\u901A\u8FC7\u771F\u5B9E\u8F93\u5165\u6216\u751F\u4EA7 controls \u89E6\u53D1 restart\uFF0C\u7B49\u5F85\u5B8C\u6574\u5E27\u5E76\u65AD\u8A00\u72B6\u6001\u5DF2\u6062\u590D\u3002",
+    checkpoint: "\u68C0\u67E5\u70B9\uFF1A\u5148\u65AD\u8A00 authoritative state\uFF0C\u518D\u8C03\u7528 host.checkpoint()\uFF1B\u4E0D\u8981\u8C03\u7528 contract.checkpoint()\u3002",
+    destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4 Scene \u5728\u751F\u4EA7 registry \u4E2D\uFF0C\u5E76\u5728 boot \u524D\u901A\u8FC7 additionalScenes \u6CE8\u518C\u8F6C\u573A\u76EE\u6807\u3002",
+    missing: "\u6D4B\u8BD5\u7F3A\u5931\uFF1A\u5728\u6307\u5B9A\u6587\u4EF6\u4F7F\u7528 gameplayTest \u5B9A\u4E49\u68C0\u67E5\u9879\uFF0C\u5E76\u901A\u8FC7 contract.attachHost(host) \u7ED1\u5B9A host\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF1B\u68C0\u67E5\u9879\u53EA\u6C47\u603B\u7ED3\u679C\uFF0C\u4E0D\u662F\u8FD0\u884C\u65F6\u5BF9\u8C61\u3002"
+  };
+  const getCategory = (issue) => {
+    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
+    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
+    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics")) return { category: "physics", key: "physics" };
+    if (issue.includes("\u672A\u8BB0\u5F55\u5230 ") && issue.includes("Scene \u8F6C\u573A")) {
+      const target = issue.match(/未记录到 (.+?) 的 Scene 转场/)?.[1] ?? "unknown";
+      return { category: "transition", key: `transition:${target}` };
+    }
+    if (issue.includes("\u672A\u8BBF\u95EE Scene")) {
+      const scene = issue.match(/未访问 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "visit", key: `visit:${scene}` };
+    }
+    if (issue.includes("\u672A\u91CD\u542F Scene")) {
+      const scene = issue.match(/未重启 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "restart", key: `restart:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 checkpoint")) return { category: "checkpoint", key: `checkpoint:${issue.match(/checkpoint "([^"]+)"/)?.[1] ?? issue}` };
+    if (issue.includes("\u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1")) return { category: "destroy", key: "destroy" };
+    if (issue.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      const scene = issue.match(/生产 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "registry", key: `registry:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
+    return { category: "other", key: `other:${issue}` };
+  };
+  for (const rawIssue of [...new Set(issues)]) {
+    const compact = rawIssue.replaceAll(/\s+/g, " ").trim();
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u68C0\u67E5\u9879 "$1"').replaceAll("evidence requirements", "\u6240\u9700\u8FD0\u884C\u8BC1\u636E").replaceAll("metadata", "\u6D4B\u8BD5\u58F0\u660E").replaceAll("host registry", "\u5DF2\u6CE8\u518C Scene \u6E05\u5355");
+    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const { category, key } = getCategory(compact);
+    const group = groups.get(key);
+    if (group) {
+      if (id && !group.ids.includes(id)) group.ids.push(id);
+    } else {
+      groups.set(key, { text: readable, ids: id ? [id] : [], key });
+    }
+    if (repairText[category] && !repairKeys.has(category)) {
+      repairKeys.add(category);
+      repairs.push(repairText[category]);
+    }
+  }
+  const grouped = [...groups.values()];
+  const visible = grouped.slice(0, 8).map((group) => {
+    if (group.ids.length <= 1) return group.text;
+    return `${group.text}\uFF08\u53D7\u5F71\u54CD\u68C0\u67E5\u9879\uFF1A${group.ids.join("\u3001")}\uFF09`;
+  });
+  return {
+    issues: visible.map(
+      (issue) => issue.length > 360 ? `${issue.slice(0, 357)}...` : issue
+    ),
+    repairs: repairs.slice(0, 8),
+    omitted: Math.max(0, grouped.length - visible.length)
+  };
+}
+
 // src/lint/gameplay-audit.test.ts
 var options = {
   mode: "interactive",
@@ -568,7 +650,7 @@ describe("gameplay audit", () => {
     expect(result).toEqual({
       passed: false,
       issues: [
-        '\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "gameplay.main-flow"\uFF08tests/gameplay.test.ts\uFF09\u3002'
+        '\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "gameplay.main-flow" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08tests/gameplay.test.ts\uFF09\u3002'
       ]
     });
   });
@@ -602,6 +684,7 @@ describe("gameplay audit", () => {
     evidence.destroyed = false;
     evidence.registeredScenes.push("DebugScene");
     const test = createPassingTest();
+    if (!test.metadata) throw new Error("expected gameplay metadata");
     test.metadata.evidence = evidence;
     const result = auditGameplayRun(options, [test]);
     expect(result.passed).toBe(false);
@@ -613,8 +696,24 @@ describe("gameplay audit", () => {
       ])
     );
   });
+  it("\u4FDD\u7559\u5931\u8D25 host \u5DF2\u6CE8\u518C\u7684 Scene\uFF0C\u907F\u514D checkpoint \u7F3A\u53E3\u7EA7\u8054\u6210\u6CE8\u518C\u9519\u8BEF", () => {
+    const test = createPassingTest();
+    if (!test.metadata?.evidence) throw new Error("expected gameplay evidence");
+    test.metadata.evidence.checkpoints = ["progress"];
+    const result = auditGameplayRun(options, [test]);
+    expect(result.issues).toContain(
+      'contract "gameplay.main-flow" \u7F3A\u5C11 checkpoint "recovery"\u3002'
+    );
+    expect(result.issues).not.toContain(
+      '\u751F\u4EA7 Scene "IndexScene" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002'
+    );
+    expect(result.issues).not.toContain(
+      '\u751F\u4EA7 Scene "BattleScene" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002'
+    );
+  });
   it("\u62D2\u7EDD\u901A\u8FC7\u5951\u7EA6\u7684 host registry \u4E2D\u51FA\u73B0\u6E05\u5355\u5916 Scene", () => {
     const test = createPassingTest();
+    if (!test.metadata?.evidence) throw new Error("expected gameplay evidence");
     test.metadata.evidence.registeredScenes.push("DebugScene");
     expect(auditGameplayRun(options, [test]).issues).toContain(
       'host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "DebugScene"\u3002'
@@ -647,4 +746,28 @@ describe("gameplay audit", () => {
       )
     ).toContain('contract "arcade-physics" \u672A\u63A8\u8FDB Arcade Physics\u3002');
   });
+  it("\u5408\u5E76\u76F8\u540C\u4FEE\u590D\u7C7B\u578B\u4F46\u4FDD\u7559\u4E0D\u540C Scene \u8F6C\u573A\u76EE\u6807", () => {
+    const result = formatGameplayIssues([
+      'contract "Menu.start" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002',
+      'contract "Battle.start" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002',
+      'contract "Menu.to-battle" \u672A\u8BB0\u5F55\u5230 BattleScene \u7684 Scene \u8F6C\u573A\u3002',
+      'contract "Battle.to-result" \u672A\u8BB0\u5F55\u5230 ResultScene \u7684 Scene \u8F6C\u573A\u3002',
+      'contract "Menu.visit-result" \u672A\u8BBF\u95EE Scene "ResultScene"\u3002',
+      'contract "Battle.visit-result" \u672A\u8BBF\u95EE Scene "ResultScene"\u3002'
+    ]);
+    expect(result.issues).toHaveLength(4);
+    expect(result.repairs).toHaveLength(3);
+    expect(result.repairs[0]).toContain("\u8F93\u5165");
+    expect(result.repairs[1]).toContain("\u8F6C\u573A");
+  });
+  it("\u5C06\u591A\u68C0\u67E5\u9879\u7684\u7F3A\u53E3\u9650\u5236\u4E3A\u95EE\u9898\u7EC4\u800C\u4E0D\u662F\u539F\u59CB\u65E5\u5FD7\u884C", () => {
+    const issues = Array.from(
+      { length: 20 },
+      (_, index) => `contract "Scene${index}.boot" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`
+    );
+    const result = formatGameplayIssues(issues);
+    expect(result.issues).toHaveLength(1);
+    expect(result.repairs).toHaveLength(1);
+    expect(result.omitted).toBe(0);
+  });
 });

package/dist/lint/gameplay-contract.contract.mjs

@@ -1188,6 +1188,7 @@ describe("gameplay contract lifecycle integration", () => {
     const { callbacks, context } = createTestContext();
     const contract = registerGameplayContract(context, {
       id: "InputScene.hit",
+      kind: "playthrough",
       requireInput: true,
       requireFrameAdvance: true
     });
@@ -1216,6 +1217,7 @@ describe("gameplay contract lifecycle integration", () => {
     const { callbacks, context } = createTestContext();
     const contract = registerGameplayContract(context, {
       id: "InputScene.missing-input",
+      kind: "playthrough",
       requireInput: true
     });
     const host = await createHeadlessGame(new InputScene());

package/dist/lint/vitest-config.contract.mjs

@@ -222,7 +222,7 @@ function auditGameplayCollection(options, file, tests) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
       issues.push(
-        `\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "${contract.id}"\uFF08${normalizedFile}\uFF09\u3002`
+        `\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "${contract.id}" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08${normalizedFile}\uFF09\u3002`
       );
     } else if (matches.length > 1) {
       issues.push(
@@ -253,12 +253,15 @@ function auditGameplayCollection(options, file, tests) {
 function getGameplayEvidenceIssues(id, requirements, evidence) {
   const issues = [];
   const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
-  if (requirements.requireInput && inputEvents === 0)
+  if (requirements.requireInput && inputEvents === 0) {
     issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
-  if (requirements.requireFrameAdvance && evidence.frames === 0)
+  }
+  if (requirements.requireFrameAdvance && evidence.frames === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
-  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+  }
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  }
   for (const target of normalizeList(requirements.requireTransition)) {
     if (!evidence.transitions.some((transition) => transition.to === target)) {
       issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
@@ -269,21 +272,24 @@ function getGameplayEvidenceIssues(id, requirements, evidence) {
       issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
   }
   for (const scene of normalizeList(requirements.requireRestart)) {
-    if (!evidence.restartedScenes.includes(scene))
+    if (!evidence.restartedScenes.includes(scene)) {
       issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+    }
   }
   for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
-    if (!evidence.checkpoints.includes(checkpoint))
+    if (!evidence.checkpoints.includes(checkpoint)) {
       issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+    }
   }
-  if (requirements.requireDestroy && !evidence.destroyed)
+  if (requirements.requireDestroy && !evidence.destroyed) {
     issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  }
   return issues;
 }
 function auditGameplayRun(options, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
-  const acceptedEvidence = [];
+  const observedEvidence = [];
   for (const expected of options.contracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
@@ -299,6 +305,7 @@ function auditGameplayRun(options, tests) {
     const test = matches[0];
     const metadata = test?.metadata;
     if (!test || !metadata) continue;
+    if (metadata.evidence) observedEvidence.push(metadata.evidence);
     if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
       issues.push(
         `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
@@ -319,7 +326,6 @@ function auditGameplayRun(options, tests) {
       metadata.evidence
     );
     issues.push(...evidenceIssues);
-    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
@@ -330,14 +336,15 @@ function auditGameplayRun(options, tests) {
     }
   }
   const registeredScenes = normalizeSet(
-    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+    observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options.scenes);
   for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene))
+    if (!registeredScenes.includes(scene)) {
       issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
       );
+    }
   }
   for (const scene of registeredScenes) {
     if (!expectedScenes.includes(scene))
@@ -367,11 +374,96 @@ function toAuditTest(test) {
     metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
   };
 }
+function formatGameplayIssues(issues) {
+  const groups = /* @__PURE__ */ new Map();
+  const repairKeys = /* @__PURE__ */ new Set();
+  const repairs = [];
+  const repairText = {
+    input: "\u8F93\u5165\uFF1A\u5148\u63A8\u8FDB\u4E00\u5E27\uFF0C\u518D\u901A\u8FC7 host.input.mouse\u3001host.input.keyboard \u6216 host.input.touch \u9A71\u52A8\u771F\u5B9E\u751F\u4EA7\u8F93\u5165\u3002",
+    frames: "\u5E27\u63A8\u8FDB\uFF1A\u5728\u8F93\u5165\u6216\u751F\u4EA7\u547D\u4EE4\u540E\u8C03\u7528 host.stepFrames()\uFF0C\u5F02\u6B65 update \u4F7F\u7528 host.stepFramesAsync()\u3002",
+    physics: "\u7269\u7406\uFF1A\u4EC5\u5728\u751F\u4EA7\u4F7F\u7528 Arcade Physics \u65F6\u8C03\u7528 host.stepPhysics()\uFF1B\u5176\u4ED6\u7269\u7406\u7CFB\u7EDF\u4F7F\u7528\u5B8C\u6574\u5E27\u3002",
+    transition: "\u8F6C\u573A\uFF1Aboot \u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u751F\u4EA7\u8F6C\u573A\u547D\u4EE4\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u65AD\u8A00\u6E90/\u76EE\u6807\u72B6\u6001\u3002",
+    visit: "Scene\uFF1A\u786E\u8BA4\u6D4B\u8BD5\u901A\u8FC7\u771F\u5B9E\u5165\u53E3\u6216\u5408\u6CD5\u8F6C\u573A\u8BBF\u95EE\u8BE5 Scene\uFF0C\u5E76\u4F7F\u7528\u771F\u5B9E\u914D\u7F6E\u542F\u52A8\u3002",
+    restart: "\u6062\u590D\uFF1A\u901A\u8FC7\u771F\u5B9E\u8F93\u5165\u6216\u751F\u4EA7 controls \u89E6\u53D1 restart\uFF0C\u7B49\u5F85\u5B8C\u6574\u5E27\u5E76\u65AD\u8A00\u72B6\u6001\u5DF2\u6062\u590D\u3002",
+    checkpoint: "\u68C0\u67E5\u70B9\uFF1A\u5148\u65AD\u8A00 authoritative state\uFF0C\u518D\u8C03\u7528 host.checkpoint()\uFF1B\u4E0D\u8981\u8C03\u7528 contract.checkpoint()\u3002",
+    destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4 Scene \u5728\u751F\u4EA7 registry \u4E2D\uFF0C\u5E76\u5728 boot \u524D\u901A\u8FC7 additionalScenes \u6CE8\u518C\u8F6C\u573A\u76EE\u6807\u3002",
+    missing: "\u6D4B\u8BD5\u7F3A\u5931\uFF1A\u5728\u6307\u5B9A\u6587\u4EF6\u4F7F\u7528 gameplayTest \u5B9A\u4E49\u68C0\u67E5\u9879\uFF0C\u5E76\u901A\u8FC7 contract.attachHost(host) \u7ED1\u5B9A host\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF1B\u68C0\u67E5\u9879\u53EA\u6C47\u603B\u7ED3\u679C\uFF0C\u4E0D\u662F\u8FD0\u884C\u65F6\u5BF9\u8C61\u3002"
+  };
+  const getCategory = (issue) => {
+    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
+    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
+    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics")) return { category: "physics", key: "physics" };
+    if (issue.includes("\u672A\u8BB0\u5F55\u5230 ") && issue.includes("Scene \u8F6C\u573A")) {
+      const target = issue.match(/未记录到 (.+?) 的 Scene 转场/)?.[1] ?? "unknown";
+      return { category: "transition", key: `transition:${target}` };
+    }
+    if (issue.includes("\u672A\u8BBF\u95EE Scene")) {
+      const scene = issue.match(/未访问 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "visit", key: `visit:${scene}` };
+    }
+    if (issue.includes("\u672A\u91CD\u542F Scene")) {
+      const scene = issue.match(/未重启 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "restart", key: `restart:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 checkpoint")) return { category: "checkpoint", key: `checkpoint:${issue.match(/checkpoint "([^"]+)"/)?.[1] ?? issue}` };
+    if (issue.includes("\u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1")) return { category: "destroy", key: "destroy" };
+    if (issue.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      const scene = issue.match(/生产 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "registry", key: `registry:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
+    return { category: "other", key: `other:${issue}` };
+  };
+  for (const rawIssue of [...new Set(issues)]) {
+    const compact = rawIssue.replaceAll(/\s+/g, " ").trim();
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u68C0\u67E5\u9879 "$1"').replaceAll("evidence requirements", "\u6240\u9700\u8FD0\u884C\u8BC1\u636E").replaceAll("metadata", "\u6D4B\u8BD5\u58F0\u660E").replaceAll("host registry", "\u5DF2\u6CE8\u518C Scene \u6E05\u5355");
+    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const { category, key } = getCategory(compact);
+    const group = groups.get(key);
+    if (group) {
+      if (id && !group.ids.includes(id)) group.ids.push(id);
+    } else {
+      groups.set(key, { text: readable, ids: id ? [id] : [], key });
+    }
+    if (repairText[category] && !repairKeys.has(category)) {
+      repairKeys.add(category);
+      repairs.push(repairText[category]);
+    }
+  }
+  const grouped = [...groups.values()];
+  const visible = grouped.slice(0, 8).map((group) => {
+    if (group.ids.length <= 1) return group.text;
+    return `${group.text}\uFF08\u53D7\u5F71\u54CD\u68C0\u67E5\u9879\uFF1A${group.ids.join("\u3001")}\uFF09`;
+  });
+  return {
+    issues: visible.map(
+      (issue) => issue.length > 360 ? `${issue.slice(0, 357)}...` : issue
+    ),
+    repairs: repairs.slice(0, 8),
+    omitted: Math.max(0, grouped.length - visible.length)
+  };
+}
 function printIssues(stage, issues) {
   if (issues.length === 0) return;
   console.error(`
 GAMEPLAY_AUDIT: ${stage} FAILED`);
-  for (const issue of issues) console.error(`- ${issue}`);
+  console.error(
+    "\u73A9\u6CD5\u68C0\u67E5\u5931\u8D25\uFF1A\u4EE5\u4E0B\u6BCF\u4E2A\u68C0\u67E5\u9879\u5BF9\u5E94\u4E00\u4E2A\u9700\u8981\u6D4B\u8BD5\u8BC1\u660E\u7684\u6E38\u620F\u884C\u4E3A\u3002"
+  );
+  const formatted = formatGameplayIssues(issues);
+  for (const issue of formatted.issues) console.error(`- ${issue}`);
+  if (formatted.repairs.length > 0) {
+    console.error("\u4FEE\u590D\u5EFA\u8BAE\uFF08\u540C\u7C7B\u95EE\u9898\u53EA\u5217\u4E00\u6B21\uFF09\uFF1A");
+    for (const repair of formatted.repairs) console.error(`- ${repair}`);
+  }
+  if (formatted.omitted > 0) {
+    console.error(
+      `- \u5176\u4F59 ${formatted.omitted} \u7C7B\u95EE\u9898\u5DF2\u7701\u7565\uFF1B\u5148\u4FEE\u590D\u4EE5\u4E0A\u95EE\u9898\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002`
+    );
+  }
 }
 var GameplayAuditReporter = class {
   projectRoot;
@@ -407,26 +499,45 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules) {
+  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+    const collectionFailed = reason === "failed" && testModules.some(
+      (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
+    );
+    if (collectionFailed) {
+      console.error(
+        "\nGAMEPLAY_AUDIT: NOT RUN\n\u73A9\u6CD5\u6D4B\u8BD5\u6587\u4EF6\u65E0\u6CD5\u52A0\u8F7D\uFF0C\u56E0\u6B64\u65E0\u6CD5\u68C0\u67E5\u6E38\u620F\u884C\u4E3A\u3002\u8BF7\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u663E\u793A\u7684\u8BED\u6CD5\u6216\u5BFC\u5165\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\u3002"
+      );
+      process.exitCode = 1;
+      return;
+    }
     const tests = testModules.flatMap(
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
-    if (!result.passed) {
-      printIssues("FINAL", result.issues);
+    const combinedIssues = [
+      ...this.preflightIssues,
+      ...result.issues
+    ];
+    if (combinedIssues.length > 0) {
+      if (this.preflightIssues.size > 0) {
+        console.error("\nGAMEPLAY_AUDIT: PREFLIGHT FAILED (included in final summary)");
+      }
+      printIssues("FINAL", [...new Set(combinedIssues)]);
       process.exitCode = 1;
     } else {
       console.log(
         `
 GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts, ${this.options.scenes.length} scenes)`
       );
+      console.log(
+        "GAMEPLAY_AUDIT_NOTE: \u73A9\u6CD5\u68C0\u67E5\u5DF2\u901A\u8FC7\uFF1B\u4ECD\u9700\u4EE5\u6700\u540E\u7684 TEST_RESULT \u5224\u65AD\u6574\u4F53\u6210\u529F\u3002"
+      );
     }
   }
   /** 立即输出一个此前未报告过的预检缺口，并让本次测试命令失败。 */
   reportPreflightIssue(issue) {
     if (this.preflightIssues.has(issue)) return;
     this.preflightIssues.add(issue);
-    printIssues("PREFLIGHT", [issue]);
     process.exitCode = 1;
   }
 };
@@ -476,7 +587,9 @@ function defineGameVitestConfig(options) {
         ...options.additionalSetupFiles ?? []
       ],
       reporters: [
-        "default",
+        // Vitest's minimal reporter is optimized for AI output: passing tests
+        // stay quiet while failed tests retain their useful error message.
+        "minimal",
         new GameplayAuditReporter(options.projectRoot, options.gameplayAudit)
       ],
       restoreMocks: true,
@@ -488,7 +601,9 @@ function defineGameVitestConfig(options) {
           "src/scenes/**/*.d.ts",
           "src/scenes/**/*.{spec,test}.{ts,tsx}"
         ],
-        reporter: ["text"],
+        // Per-file threshold errors still identify omitted Scene files; the
+        // summary avoids printing a large coverage table on every successful run.
+        reporter: ["text-summary"],
         thresholds: {
           perFile: true,
           lines: 1,
@@ -535,7 +650,7 @@ describe("defineGameVitestConfig", () => {
       environment: "jsdom",
       environmentOptions: { jsdom: { url: "http://localhost/" } },
       setupFiles: ["miaoda-game-devkit/vitest-setup"],
-      reporters: ["default", expect.any(Object)],
+      reporters: ["minimal", expect.any(Object)],
       restoreMocks: true,
       clearMocks: true,
       coverage: {
@@ -545,7 +660,7 @@ describe("defineGameVitestConfig", () => {
           "src/scenes/**/*.d.ts",
           "src/scenes/**/*.{spec,test}.{ts,tsx}"
         ],
-        reporter: ["text"],
+        reporter: ["text-summary"],
         thresholds: {
           perFile: true,
           lines: 1,

package/dist/vitest-config.js

@@ -242,7 +242,7 @@ function auditGameplayCollection(options, file, tests) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
       issues.push(
-        `\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "${contract.id}"\uFF08${normalizedFile}\uFF09\u3002`
+        `\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "${contract.id}" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08${normalizedFile}\uFF09\u3002`
       );
     } else if (matches.length > 1) {
       issues.push(
@@ -273,12 +273,15 @@ function auditGameplayCollection(options, file, tests) {
 function getGameplayEvidenceIssues(id, requirements, evidence) {
   const issues = [];
   const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
-  if (requirements.requireInput && inputEvents === 0)
+  if (requirements.requireInput && inputEvents === 0) {
     issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
-  if (requirements.requireFrameAdvance && evidence.frames === 0)
+  }
+  if (requirements.requireFrameAdvance && evidence.frames === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
-  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+  }
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  }
   for (const target of normalizeList(requirements.requireTransition)) {
     if (!evidence.transitions.some((transition) => transition.to === target)) {
       issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
@@ -289,21 +292,24 @@ function getGameplayEvidenceIssues(id, requirements, evidence) {
       issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
   }
   for (const scene of normalizeList(requirements.requireRestart)) {
-    if (!evidence.restartedScenes.includes(scene))
+    if (!evidence.restartedScenes.includes(scene)) {
       issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+    }
   }
   for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
-    if (!evidence.checkpoints.includes(checkpoint))
+    if (!evidence.checkpoints.includes(checkpoint)) {
       issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+    }
   }
-  if (requirements.requireDestroy && !evidence.destroyed)
+  if (requirements.requireDestroy && !evidence.destroyed) {
     issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  }
   return issues;
 }
 function auditGameplayRun(options, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
-  const acceptedEvidence = [];
+  const observedEvidence = [];
   for (const expected of options.contracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
@@ -319,6 +325,7 @@ function auditGameplayRun(options, tests) {
     const test = matches[0];
     const metadata = test?.metadata;
     if (!test || !metadata) continue;
+    if (metadata.evidence) observedEvidence.push(metadata.evidence);
     if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
       issues.push(
         `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
@@ -339,7 +346,6 @@ function auditGameplayRun(options, tests) {
       metadata.evidence
     );
     issues.push(...evidenceIssues);
-    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
@@ -350,14 +356,15 @@ function auditGameplayRun(options, tests) {
     }
   }
   const registeredScenes = normalizeSet(
-    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+    observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options.scenes);
   for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene))
+    if (!registeredScenes.includes(scene)) {
       issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
       );
+    }
   }
   for (const scene of registeredScenes) {
     if (!expectedScenes.includes(scene))
@@ -387,11 +394,96 @@ function toAuditTest(test) {
     metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
   };
 }
+function formatGameplayIssues(issues) {
+  const groups = /* @__PURE__ */ new Map();
+  const repairKeys = /* @__PURE__ */ new Set();
+  const repairs = [];
+  const repairText = {
+    input: "\u8F93\u5165\uFF1A\u5148\u63A8\u8FDB\u4E00\u5E27\uFF0C\u518D\u901A\u8FC7 host.input.mouse\u3001host.input.keyboard \u6216 host.input.touch \u9A71\u52A8\u771F\u5B9E\u751F\u4EA7\u8F93\u5165\u3002",
+    frames: "\u5E27\u63A8\u8FDB\uFF1A\u5728\u8F93\u5165\u6216\u751F\u4EA7\u547D\u4EE4\u540E\u8C03\u7528 host.stepFrames()\uFF0C\u5F02\u6B65 update \u4F7F\u7528 host.stepFramesAsync()\u3002",
+    physics: "\u7269\u7406\uFF1A\u4EC5\u5728\u751F\u4EA7\u4F7F\u7528 Arcade Physics \u65F6\u8C03\u7528 host.stepPhysics()\uFF1B\u5176\u4ED6\u7269\u7406\u7CFB\u7EDF\u4F7F\u7528\u5B8C\u6574\u5E27\u3002",
+    transition: "\u8F6C\u573A\uFF1Aboot \u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u751F\u4EA7\u8F6C\u573A\u547D\u4EE4\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u65AD\u8A00\u6E90/\u76EE\u6807\u72B6\u6001\u3002",
+    visit: "Scene\uFF1A\u786E\u8BA4\u6D4B\u8BD5\u901A\u8FC7\u771F\u5B9E\u5165\u53E3\u6216\u5408\u6CD5\u8F6C\u573A\u8BBF\u95EE\u8BE5 Scene\uFF0C\u5E76\u4F7F\u7528\u771F\u5B9E\u914D\u7F6E\u542F\u52A8\u3002",
+    restart: "\u6062\u590D\uFF1A\u901A\u8FC7\u771F\u5B9E\u8F93\u5165\u6216\u751F\u4EA7 controls \u89E6\u53D1 restart\uFF0C\u7B49\u5F85\u5B8C\u6574\u5E27\u5E76\u65AD\u8A00\u72B6\u6001\u5DF2\u6062\u590D\u3002",
+    checkpoint: "\u68C0\u67E5\u70B9\uFF1A\u5148\u65AD\u8A00 authoritative state\uFF0C\u518D\u8C03\u7528 host.checkpoint()\uFF1B\u4E0D\u8981\u8C03\u7528 contract.checkpoint()\u3002",
+    destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4 Scene \u5728\u751F\u4EA7 registry \u4E2D\uFF0C\u5E76\u5728 boot \u524D\u901A\u8FC7 additionalScenes \u6CE8\u518C\u8F6C\u573A\u76EE\u6807\u3002",
+    missing: "\u6D4B\u8BD5\u7F3A\u5931\uFF1A\u5728\u6307\u5B9A\u6587\u4EF6\u4F7F\u7528 gameplayTest \u5B9A\u4E49\u68C0\u67E5\u9879\uFF0C\u5E76\u901A\u8FC7 contract.attachHost(host) \u7ED1\u5B9A host\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF1B\u68C0\u67E5\u9879\u53EA\u6C47\u603B\u7ED3\u679C\uFF0C\u4E0D\u662F\u8FD0\u884C\u65F6\u5BF9\u8C61\u3002"
+  };
+  const getCategory = (issue) => {
+    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
+    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
+    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics")) return { category: "physics", key: "physics" };
+    if (issue.includes("\u672A\u8BB0\u5F55\u5230 ") && issue.includes("Scene \u8F6C\u573A")) {
+      const target = issue.match(/未记录到 (.+?) 的 Scene 转场/)?.[1] ?? "unknown";
+      return { category: "transition", key: `transition:${target}` };
+    }
+    if (issue.includes("\u672A\u8BBF\u95EE Scene")) {
+      const scene = issue.match(/未访问 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "visit", key: `visit:${scene}` };
+    }
+    if (issue.includes("\u672A\u91CD\u542F Scene")) {
+      const scene = issue.match(/未重启 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "restart", key: `restart:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 checkpoint")) return { category: "checkpoint", key: `checkpoint:${issue.match(/checkpoint "([^"]+)"/)?.[1] ?? issue}` };
+    if (issue.includes("\u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1")) return { category: "destroy", key: "destroy" };
+    if (issue.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      const scene = issue.match(/生产 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "registry", key: `registry:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
+    return { category: "other", key: `other:${issue}` };
+  };
+  for (const rawIssue of [...new Set(issues)]) {
+    const compact = rawIssue.replaceAll(/\s+/g, " ").trim();
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u68C0\u67E5\u9879 "$1"').replaceAll("evidence requirements", "\u6240\u9700\u8FD0\u884C\u8BC1\u636E").replaceAll("metadata", "\u6D4B\u8BD5\u58F0\u660E").replaceAll("host registry", "\u5DF2\u6CE8\u518C Scene \u6E05\u5355");
+    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const { category, key } = getCategory(compact);
+    const group = groups.get(key);
+    if (group) {
+      if (id && !group.ids.includes(id)) group.ids.push(id);
+    } else {
+      groups.set(key, { text: readable, ids: id ? [id] : [], key });
+    }
+    if (repairText[category] && !repairKeys.has(category)) {
+      repairKeys.add(category);
+      repairs.push(repairText[category]);
+    }
+  }
+  const grouped = [...groups.values()];
+  const visible = grouped.slice(0, 8).map((group) => {
+    if (group.ids.length <= 1) return group.text;
+    return `${group.text}\uFF08\u53D7\u5F71\u54CD\u68C0\u67E5\u9879\uFF1A${group.ids.join("\u3001")}\uFF09`;
+  });
+  return {
+    issues: visible.map(
+      (issue) => issue.length > 360 ? `${issue.slice(0, 357)}...` : issue
+    ),
+    repairs: repairs.slice(0, 8),
+    omitted: Math.max(0, grouped.length - visible.length)
+  };
+}
 function printIssues(stage, issues) {
   if (issues.length === 0) return;
   console.error(`
 GAMEPLAY_AUDIT: ${stage} FAILED`);
-  for (const issue of issues) console.error(`- ${issue}`);
+  console.error(
+    "\u73A9\u6CD5\u68C0\u67E5\u5931\u8D25\uFF1A\u4EE5\u4E0B\u6BCF\u4E2A\u68C0\u67E5\u9879\u5BF9\u5E94\u4E00\u4E2A\u9700\u8981\u6D4B\u8BD5\u8BC1\u660E\u7684\u6E38\u620F\u884C\u4E3A\u3002"
+  );
+  const formatted = formatGameplayIssues(issues);
+  for (const issue of formatted.issues) console.error(`- ${issue}`);
+  if (formatted.repairs.length > 0) {
+    console.error("\u4FEE\u590D\u5EFA\u8BAE\uFF08\u540C\u7C7B\u95EE\u9898\u53EA\u5217\u4E00\u6B21\uFF09\uFF1A");
+    for (const repair of formatted.repairs) console.error(`- ${repair}`);
+  }
+  if (formatted.omitted > 0) {
+    console.error(
+      `- \u5176\u4F59 ${formatted.omitted} \u7C7B\u95EE\u9898\u5DF2\u7701\u7565\uFF1B\u5148\u4FEE\u590D\u4EE5\u4E0A\u95EE\u9898\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002`
+    );
+  }
 }
 var GameplayAuditReporter = class {
   projectRoot;
@@ -427,26 +519,45 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules) {
+  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+    const collectionFailed = reason === "failed" && testModules.some(
+      (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
+    );
+    if (collectionFailed) {
+      console.error(
+        "\nGAMEPLAY_AUDIT: NOT RUN\n\u73A9\u6CD5\u6D4B\u8BD5\u6587\u4EF6\u65E0\u6CD5\u52A0\u8F7D\uFF0C\u56E0\u6B64\u65E0\u6CD5\u68C0\u67E5\u6E38\u620F\u884C\u4E3A\u3002\u8BF7\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u663E\u793A\u7684\u8BED\u6CD5\u6216\u5BFC\u5165\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\u3002"
+      );
+      process.exitCode = 1;
+      return;
+    }
     const tests = testModules.flatMap(
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
-    if (!result.passed) {
-      printIssues("FINAL", result.issues);
+    const combinedIssues = [
+      ...this.preflightIssues,
+      ...result.issues
+    ];
+    if (combinedIssues.length > 0) {
+      if (this.preflightIssues.size > 0) {
+        console.error("\nGAMEPLAY_AUDIT: PREFLIGHT FAILED (included in final summary)");
+      }
+      printIssues("FINAL", [...new Set(combinedIssues)]);
       process.exitCode = 1;
     } else {
       console.log(
         `
 GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts, ${this.options.scenes.length} scenes)`
       );
+      console.log(
+        "GAMEPLAY_AUDIT_NOTE: \u73A9\u6CD5\u68C0\u67E5\u5DF2\u901A\u8FC7\uFF1B\u4ECD\u9700\u4EE5\u6700\u540E\u7684 TEST_RESULT \u5224\u65AD\u6574\u4F53\u6210\u529F\u3002"
+      );
     }
   }
   /** 立即输出一个此前未报告过的预检缺口，并让本次测试命令失败。 */
   reportPreflightIssue(issue) {
     if (this.preflightIssues.has(issue)) return;
     this.preflightIssues.add(issue);
-    printIssues("PREFLIGHT", [issue]);
     process.exitCode = 1;
   }
 };
@@ -496,7 +607,9 @@ function defineGameVitestConfig(options) {
         ...options.additionalSetupFiles ?? []
       ],
       reporters: [
-        "default",
+        // Vitest's minimal reporter is optimized for AI output: passing tests
+        // stay quiet while failed tests retain their useful error message.
+        "minimal",
         new GameplayAuditReporter(options.projectRoot, options.gameplayAudit)
       ],
       restoreMocks: true,
@@ -508,7 +621,9 @@ function defineGameVitestConfig(options) {
           "src/scenes/**/*.d.ts",
           "src/scenes/**/*.{spec,test}.{ts,tsx}"
         ],
-        reporter: ["text"],
+        // Per-file threshold errors still identify omitted Scene files; the
+        // summary avoids printing a large coverage table on every successful run.
+        reporter: ["text-summary"],
         thresholds: {
           perFile: true,
           lines: 1,

package/dist/vitest-config.mjs

@@ -218,7 +218,7 @@ function auditGameplayCollection(options, file, tests) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
       issues.push(
-        `\u6D4B\u8BD5\u6267\u884C\u524D\u672A\u6536\u96C6\u5230 contract "${contract.id}"\uFF08${normalizedFile}\uFF09\u3002`
+        `\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "${contract.id}" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08${normalizedFile}\uFF09\u3002`
       );
     } else if (matches.length > 1) {
       issues.push(
@@ -249,12 +249,15 @@ function auditGameplayCollection(options, file, tests) {
 function getGameplayEvidenceIssues(id, requirements, evidence) {
   const issues = [];
   const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
-  if (requirements.requireInput && inputEvents === 0)
+  if (requirements.requireInput && inputEvents === 0) {
     issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
-  if (requirements.requireFrameAdvance && evidence.frames === 0)
+  }
+  if (requirements.requireFrameAdvance && evidence.frames === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
-  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+  }
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  }
   for (const target of normalizeList(requirements.requireTransition)) {
     if (!evidence.transitions.some((transition) => transition.to === target)) {
       issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
@@ -265,21 +268,24 @@ function getGameplayEvidenceIssues(id, requirements, evidence) {
       issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
   }
   for (const scene of normalizeList(requirements.requireRestart)) {
-    if (!evidence.restartedScenes.includes(scene))
+    if (!evidence.restartedScenes.includes(scene)) {
       issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+    }
   }
   for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
-    if (!evidence.checkpoints.includes(checkpoint))
+    if (!evidence.checkpoints.includes(checkpoint)) {
       issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+    }
   }
-  if (requirements.requireDestroy && !evidence.destroyed)
+  if (requirements.requireDestroy && !evidence.destroyed) {
     issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  }
   return issues;
 }
 function auditGameplayRun(options, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
-  const acceptedEvidence = [];
+  const observedEvidence = [];
   for (const expected of options.contracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
@@ -295,6 +301,7 @@ function auditGameplayRun(options, tests) {
     const test = matches[0];
     const metadata = test?.metadata;
     if (!test || !metadata) continue;
+    if (metadata.evidence) observedEvidence.push(metadata.evidence);
     if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
       issues.push(
         `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
@@ -315,7 +322,6 @@ function auditGameplayRun(options, tests) {
       metadata.evidence
     );
     issues.push(...evidenceIssues);
-    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
@@ -326,14 +332,15 @@ function auditGameplayRun(options, tests) {
     }
   }
   const registeredScenes = normalizeSet(
-    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+    observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options.scenes);
   for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene))
+    if (!registeredScenes.includes(scene)) {
       issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
       );
+    }
   }
   for (const scene of registeredScenes) {
     if (!expectedScenes.includes(scene))
@@ -363,11 +370,96 @@ function toAuditTest(test) {
     metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
   };
 }
+function formatGameplayIssues(issues) {
+  const groups = /* @__PURE__ */ new Map();
+  const repairKeys = /* @__PURE__ */ new Set();
+  const repairs = [];
+  const repairText = {
+    input: "\u8F93\u5165\uFF1A\u5148\u63A8\u8FDB\u4E00\u5E27\uFF0C\u518D\u901A\u8FC7 host.input.mouse\u3001host.input.keyboard \u6216 host.input.touch \u9A71\u52A8\u771F\u5B9E\u751F\u4EA7\u8F93\u5165\u3002",
+    frames: "\u5E27\u63A8\u8FDB\uFF1A\u5728\u8F93\u5165\u6216\u751F\u4EA7\u547D\u4EE4\u540E\u8C03\u7528 host.stepFrames()\uFF0C\u5F02\u6B65 update \u4F7F\u7528 host.stepFramesAsync()\u3002",
+    physics: "\u7269\u7406\uFF1A\u4EC5\u5728\u751F\u4EA7\u4F7F\u7528 Arcade Physics \u65F6\u8C03\u7528 host.stepPhysics()\uFF1B\u5176\u4ED6\u7269\u7406\u7CFB\u7EDF\u4F7F\u7528\u5B8C\u6574\u5E27\u3002",
+    transition: "\u8F6C\u573A\uFF1Aboot \u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u751F\u4EA7\u8F6C\u573A\u547D\u4EE4\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u65AD\u8A00\u6E90/\u76EE\u6807\u72B6\u6001\u3002",
+    visit: "Scene\uFF1A\u786E\u8BA4\u6D4B\u8BD5\u901A\u8FC7\u771F\u5B9E\u5165\u53E3\u6216\u5408\u6CD5\u8F6C\u573A\u8BBF\u95EE\u8BE5 Scene\uFF0C\u5E76\u4F7F\u7528\u771F\u5B9E\u914D\u7F6E\u542F\u52A8\u3002",
+    restart: "\u6062\u590D\uFF1A\u901A\u8FC7\u771F\u5B9E\u8F93\u5165\u6216\u751F\u4EA7 controls \u89E6\u53D1 restart\uFF0C\u7B49\u5F85\u5B8C\u6574\u5E27\u5E76\u65AD\u8A00\u72B6\u6001\u5DF2\u6062\u590D\u3002",
+    checkpoint: "\u68C0\u67E5\u70B9\uFF1A\u5148\u65AD\u8A00 authoritative state\uFF0C\u518D\u8C03\u7528 host.checkpoint()\uFF1B\u4E0D\u8981\u8C03\u7528 contract.checkpoint()\u3002",
+    destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4 Scene \u5728\u751F\u4EA7 registry \u4E2D\uFF0C\u5E76\u5728 boot \u524D\u901A\u8FC7 additionalScenes \u6CE8\u518C\u8F6C\u573A\u76EE\u6807\u3002",
+    missing: "\u6D4B\u8BD5\u7F3A\u5931\uFF1A\u5728\u6307\u5B9A\u6587\u4EF6\u4F7F\u7528 gameplayTest \u5B9A\u4E49\u68C0\u67E5\u9879\uFF0C\u5E76\u901A\u8FC7 contract.attachHost(host) \u7ED1\u5B9A host\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF1B\u68C0\u67E5\u9879\u53EA\u6C47\u603B\u7ED3\u679C\uFF0C\u4E0D\u662F\u8FD0\u884C\u65F6\u5BF9\u8C61\u3002"
+  };
+  const getCategory = (issue) => {
+    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
+    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
+    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics")) return { category: "physics", key: "physics" };
+    if (issue.includes("\u672A\u8BB0\u5F55\u5230 ") && issue.includes("Scene \u8F6C\u573A")) {
+      const target = issue.match(/未记录到 (.+?) 的 Scene 转场/)?.[1] ?? "unknown";
+      return { category: "transition", key: `transition:${target}` };
+    }
+    if (issue.includes("\u672A\u8BBF\u95EE Scene")) {
+      const scene = issue.match(/未访问 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "visit", key: `visit:${scene}` };
+    }
+    if (issue.includes("\u672A\u91CD\u542F Scene")) {
+      const scene = issue.match(/未重启 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "restart", key: `restart:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 checkpoint")) return { category: "checkpoint", key: `checkpoint:${issue.match(/checkpoint "([^"]+)"/)?.[1] ?? issue}` };
+    if (issue.includes("\u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1")) return { category: "destroy", key: "destroy" };
+    if (issue.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      const scene = issue.match(/生产 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "registry", key: `registry:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
+    return { category: "other", key: `other:${issue}` };
+  };
+  for (const rawIssue of [...new Set(issues)]) {
+    const compact = rawIssue.replaceAll(/\s+/g, " ").trim();
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u68C0\u67E5\u9879 "$1"').replaceAll("evidence requirements", "\u6240\u9700\u8FD0\u884C\u8BC1\u636E").replaceAll("metadata", "\u6D4B\u8BD5\u58F0\u660E").replaceAll("host registry", "\u5DF2\u6CE8\u518C Scene \u6E05\u5355");
+    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const { category, key } = getCategory(compact);
+    const group = groups.get(key);
+    if (group) {
+      if (id && !group.ids.includes(id)) group.ids.push(id);
+    } else {
+      groups.set(key, { text: readable, ids: id ? [id] : [], key });
+    }
+    if (repairText[category] && !repairKeys.has(category)) {
+      repairKeys.add(category);
+      repairs.push(repairText[category]);
+    }
+  }
+  const grouped = [...groups.values()];
+  const visible = grouped.slice(0, 8).map((group) => {
+    if (group.ids.length <= 1) return group.text;
+    return `${group.text}\uFF08\u53D7\u5F71\u54CD\u68C0\u67E5\u9879\uFF1A${group.ids.join("\u3001")}\uFF09`;
+  });
+  return {
+    issues: visible.map(
+      (issue) => issue.length > 360 ? `${issue.slice(0, 357)}...` : issue
+    ),
+    repairs: repairs.slice(0, 8),
+    omitted: Math.max(0, grouped.length - visible.length)
+  };
+}
 function printIssues(stage, issues) {
   if (issues.length === 0) return;
   console.error(`
 GAMEPLAY_AUDIT: ${stage} FAILED`);
-  for (const issue of issues) console.error(`- ${issue}`);
+  console.error(
+    "\u73A9\u6CD5\u68C0\u67E5\u5931\u8D25\uFF1A\u4EE5\u4E0B\u6BCF\u4E2A\u68C0\u67E5\u9879\u5BF9\u5E94\u4E00\u4E2A\u9700\u8981\u6D4B\u8BD5\u8BC1\u660E\u7684\u6E38\u620F\u884C\u4E3A\u3002"
+  );
+  const formatted = formatGameplayIssues(issues);
+  for (const issue of formatted.issues) console.error(`- ${issue}`);
+  if (formatted.repairs.length > 0) {
+    console.error("\u4FEE\u590D\u5EFA\u8BAE\uFF08\u540C\u7C7B\u95EE\u9898\u53EA\u5217\u4E00\u6B21\uFF09\uFF1A");
+    for (const repair of formatted.repairs) console.error(`- ${repair}`);
+  }
+  if (formatted.omitted > 0) {
+    console.error(
+      `- \u5176\u4F59 ${formatted.omitted} \u7C7B\u95EE\u9898\u5DF2\u7701\u7565\uFF1B\u5148\u4FEE\u590D\u4EE5\u4E0A\u95EE\u9898\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002`
+    );
+  }
 }
 var GameplayAuditReporter = class {
   projectRoot;
@@ -403,26 +495,45 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules) {
+  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+    const collectionFailed = reason === "failed" && testModules.some(
+      (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
+    );
+    if (collectionFailed) {
+      console.error(
+        "\nGAMEPLAY_AUDIT: NOT RUN\n\u73A9\u6CD5\u6D4B\u8BD5\u6587\u4EF6\u65E0\u6CD5\u52A0\u8F7D\uFF0C\u56E0\u6B64\u65E0\u6CD5\u68C0\u67E5\u6E38\u620F\u884C\u4E3A\u3002\u8BF7\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u663E\u793A\u7684\u8BED\u6CD5\u6216\u5BFC\u5165\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\u3002"
+      );
+      process.exitCode = 1;
+      return;
+    }
     const tests = testModules.flatMap(
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
-    if (!result.passed) {
-      printIssues("FINAL", result.issues);
+    const combinedIssues = [
+      ...this.preflightIssues,
+      ...result.issues
+    ];
+    if (combinedIssues.length > 0) {
+      if (this.preflightIssues.size > 0) {
+        console.error("\nGAMEPLAY_AUDIT: PREFLIGHT FAILED (included in final summary)");
+      }
+      printIssues("FINAL", [...new Set(combinedIssues)]);
       process.exitCode = 1;
     } else {
       console.log(
         `
 GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts, ${this.options.scenes.length} scenes)`
       );
+      console.log(
+        "GAMEPLAY_AUDIT_NOTE: \u73A9\u6CD5\u68C0\u67E5\u5DF2\u901A\u8FC7\uFF1B\u4ECD\u9700\u4EE5\u6700\u540E\u7684 TEST_RESULT \u5224\u65AD\u6574\u4F53\u6210\u529F\u3002"
+      );
     }
   }
   /** 立即输出一个此前未报告过的预检缺口，并让本次测试命令失败。 */
   reportPreflightIssue(issue) {
     if (this.preflightIssues.has(issue)) return;
     this.preflightIssues.add(issue);
-    printIssues("PREFLIGHT", [issue]);
     process.exitCode = 1;
   }
 };
@@ -472,7 +583,9 @@ function defineGameVitestConfig(options) {
         ...options.additionalSetupFiles ?? []
       ],
       reporters: [
-        "default",
+        // Vitest's minimal reporter is optimized for AI output: passing tests
+        // stay quiet while failed tests retain their useful error message.
+        "minimal",
         new GameplayAuditReporter(options.projectRoot, options.gameplayAudit)
       ],
       restoreMocks: true,
@@ -484,7 +597,9 @@ function defineGameVitestConfig(options) {
           "src/scenes/**/*.d.ts",
           "src/scenes/**/*.{spec,test}.{ts,tsx}"
         ],
-        reporter: ["text"],
+        // Per-file threshold errors still identify omitted Scene files; the
+        // summary avoids printing a large coverage table on every successful run.
+        reporter: ["text-summary"],
         thresholds: {
           perFile: true,
           lines: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -43,18 +43,6 @@
     "!dist/**/*.map",
     "!dist/lint/**/*.test.*"
   ],
-  "scripts": {
-    "build": "tsup",
-    "prepack": "pnpm run build",
-    "release": "pnpm run test && clean-publish",
-    "release:dry-run": "pnpm run test && clean-publish --dry-run",
-    "release:beta": "pnpm run test && npm version prerelease --preid=beta && clean-publish --tag beta",
-    "release:patch": "pnpm run test && npm version patch && clean-publish",
-    "release:minor": "pnpm run test && npm version minor && clean-publish",
-    "release:major": "pnpm run test && npm version major && clean-publish",
-    "typecheck": "tsc --noEmit",
-    "test": "pnpm run build && ./bin/miaoda-game-lint.js --contracts-only"
-  },
   "nx": {
     "tags": [
       "type:package",
@@ -94,23 +82,8 @@
   "peerDependencies": {
     "phaser": ">=4.0.0 <5"
   },
-  "devDependencies": {
-    "@types/eslint": "^9.6.1",
-    "@types/estree": "^1.0.9",
-    "@types/node": "^24.13.3",
-    "clean-publish": "^6.0.5",
-    "phaser": "4.0.0",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
-  },
-  "clean-publish": {
-    "fields": [
-      "devDependencies",
-      "scripts"
-    ]
   }
 }