miaoda-game-devkit 0.2.5 → 0.2.7

package/README.md

@@ -88,8 +88,9 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 `host.checkpoint("recovery")` 等稳定检查点，并在清单中通过 `requireCheckpoint` 声明。
 运行结束会输出稳定的 `GAMEPLAY_AUDIT: ALL CONTRACTS PASSED` 或
 `GAMEPLAY_AUDIT: ... FAILED` 标识。该标识只表示玩法证据审计；`pnpm test` 的整体结果
-必须以最后的 `TEST_RESULT: PASS` 或 `TEST_RESULT: FAIL` 为准。失败报告会合并重复的问题，
-并给出按类别去重的修复建议，先处理列出的原始测试错误，再重新运行 `pnpm test`。
+必须以最后的 `TEST_RESULT: PASS` 或 `TEST_RESULT: FAIL` 为准。失败报告按根因合并问题并
+给出直接修复步骤；测试文件无法加载或配置要求的测试尚未建立时，不再继续报告 Scene
+注册等派生问题。先处理第一类错误，再重新运行 `pnpm test`。
 
 共享 Vitest 配置使用 `minimal` reporter 和 `text-summary` coverage reporter，保留失败
 定位、Scene 覆盖摘要和最终机器标识，同时避免输出完整测试列表和逐文件噪声。

package/dist/{gameplay-audit-XBGq_jIV.d.mts → gameplay-audit-CusQfLYQ.d.mts}

@@ -18,7 +18,9 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
     stepFramesAsync(count?: number): Promise<void>;
     /** 在限定帧数内推进游戏，直到条件成立。 */
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepUntil(condition: () => boolean, maxFrames?: number | {
+        maxFrames?: number;
+    }): number;
     /** 精确推进指定次数的 Arcade Physics 单步。 */
     stepPhysics(steps?: number): void;
     /** 记录由测试定义的可序列化玩法检查点。 */

package/dist/{gameplay-audit-XBGq_jIV.d.ts → gameplay-audit-CusQfLYQ.d.ts}

@@ -18,7 +18,9 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
     stepFramesAsync(count?: number): Promise<void>;
     /** 在限定帧数内推进游戏，直到条件成立。 */
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepUntil(condition: () => boolean, maxFrames?: number | {
+        maxFrames?: number;
+    }): number;
     /** 精确推进指定次数的 Arcade Physics 单步。 */
     stepPhysics(steps?: number): void;
     /** 记录由测试定义的可序列化玩法检查点。 */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.mjs';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.mjs';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.mjs';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CusQfLYQ.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -23,6 +23,8 @@ interface GameplayTestOptions extends GameplayContractOptions {
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 记录一个由测试先断言、再声明的玩法检查点。 */
+    checkpoint(id: string): void;
     /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.js';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.js';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.js';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CusQfLYQ.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -23,6 +23,8 @@ interface GameplayTestOptions extends GameplayContractOptions {
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 记录一个由测试先断言、再声明的玩法检查点。 */
+    checkpoint(id: string): void;
     /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }

package/dist/index.js

@@ -1021,7 +1021,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1193,6 +1194,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }

package/dist/index.mjs

@@ -979,7 +979,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1151,6 +1152,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }

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

@@ -334,18 +334,21 @@ function auditGameplayRun(options2, tests) {
     observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options2.scenes);
-  for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene)) {
-      issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
-      );
+  if (observedEvidence.length > 0) {
+    for (const scene of expectedScenes) {
+      if (!registeredScenes.includes(scene)) {
+        issues.push(
+          `\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)) {
+        issues.push(
+          `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
+        );
+      }
     }
-  }
-  for (const scene of registeredScenes) {
-    if (!expectedScenes.includes(scene))
-      issues.push(
-        `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
-      );
   }
   return { passed: issues.length === 0, issues: [...new Set(issues)] };
 }
@@ -356,18 +359,31 @@ function formatGameplayIssues(issues) {
   const groups = /* @__PURE__ */ new Map();
   const repairKeys = /* @__PURE__ */ new Set();
   const repairs = [];
+  const missingByFile = /* @__PURE__ */ new Map();
+  const missingIds = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const match = issue.match(
+      /没有找到检查项 "([^"]+)" 的可执行测试（(.+)）。/
+    );
+    if (!match) continue;
+    const [, id, file] = match;
+    missingIds.add(id);
+    const ids = missingByFile.get(file) ?? [];
+    if (!ids.includes(id)) ids.push(id);
+    missingByFile.set(file, ids);
+  }
   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",
+    transition: "\u573A\u666F\u5207\u6362\uFF1A\u542F\u52A8\u6E38\u620F\u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u6E38\u620F\u4E2D\u7684\u5207\u6362\u903B\u8F91\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u68C0\u67E5\u5207\u6362\u7ED3\u679C\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",
+    checkpoint: "\u8FDB\u5EA6\u6807\u8BB0\uFF1A\u5148\u68C0\u67E5\u6E38\u620F\u81EA\u8EAB\u7684\u72B6\u6001\uFF08\u4F8B\u5982\u5206\u6570\u3001\u751F\u547D\u503C\u6216\u5F53\u524D\u5173\u5361\uFF09\uFF0C\u518D\u8C03\u7528 host.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"
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
+    missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -395,9 +411,26 @@ function formatGameplayIssues(issues) {
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
+  for (const [file, ids] of missingByFile) {
+    groups.set(`missing:${file}`, {
+      text: `${file} \u4E2D\u6CA1\u6709\u627E\u5230\u914D\u7F6E\u8981\u6C42\u7684\u73A9\u6CD5\u6D4B\u8BD5\uFF1A${ids.join("\u3001")}\u3002`,
+      ids: [],
+      key: `missing:${file}`
+    });
+  }
+  if (missingByFile.size > 0) {
+    repairKeys.add("missing");
+    repairs.push(repairText.missing);
+  }
   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");
+    if (compact.startsWith("\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 ")) continue;
+    const missingContract = compact.match(/缺少 (?:gameplay )?contract "([^"]+)"/)?.[1];
+    if (missingContract && missingIds.has(missingContract)) continue;
+    if (missingIds.size > 0 && compact.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      continue;
+    }
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
     const id = compact.match(/contract "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
@@ -414,7 +447,7 @@ function formatGameplayIssues(issues) {
   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 `${group.text}\uFF08\u540C\u7C7B\u95EE\u9898\u8FD8\u51FA\u73B0\u5728\uFF1A${group.ids.slice(1).join("\u3001")}\uFF09`;
   });
   return {
     issues: visible.map(
@@ -758,7 +791,7 @@ describe("gameplay audit", () => {
     expect(result.issues).toHaveLength(4);
     expect(result.repairs).toHaveLength(3);
     expect(result.repairs[0]).toContain("\u8F93\u5165");
-    expect(result.repairs[1]).toContain("\u8F6C\u573A");
+    expect(result.repairs[1]).toContain("\u573A\u666F\u5207\u6362");
   });
   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(
@@ -770,4 +803,18 @@ describe("gameplay audit", () => {
     expect(result.repairs).toHaveLength(1);
     expect(result.omitted).toBe(0);
   });
+  it("\u5C06\u7F3A\u5931\u6D4B\u8BD5\u5408\u5E76\u4E3A\u4E00\u4E2A\u53EF\u6267\u884C\u4FEE\u590D\u5E76\u9690\u85CF Scene \u7EA7\u8054\u9519\u8BEF", () => {
+    const result = formatGameplayIssues([
+      '\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "IndexScene.boot" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08tests/production-game.test.ts\uFF09\u3002',
+      '\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 "BattleScene.playthrough" \u7684\u53EF\u6267\u884C\u6D4B\u8BD5\uFF08tests/production-game.test.ts\uFF09\u3002',
+      '\u7F3A\u5C11 gameplay contract "IndexScene.boot"\u3002',
+      '\u7F3A\u5C11 gameplay contract "BattleScene.playthrough"\u3002',
+      '\u751F\u4EA7 Scene "BattleScene" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002'
+    ]);
+    expect(result.issues).toEqual([
+      "tests/production-game.test.ts \u4E2D\u6CA1\u6709\u627E\u5230\u914D\u7F6E\u8981\u6C42\u7684\u73A9\u6CD5\u6D4B\u8BD5\uFF1AIndexScene.boot\u3001BattleScene.playthrough\u3002"
+    ]);
+    expect(result.repairs).toHaveLength(1);
+    expect(result.repairs[0]).toContain("vitest.config.ts");
+  });
 });

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

@@ -983,7 +983,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1155,6 +1156,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }
@@ -1190,7 +1199,8 @@ describe("gameplay contract lifecycle integration", () => {
       id: "InputScene.hit",
       kind: "playthrough",
       requireInput: true,
-      requireFrameAdvance: true
+      requireFrameAdvance: true,
+      requireCheckpoint: "hit-recorded"
     });
     let host;
     try {
@@ -1199,12 +1209,14 @@ describe("gameplay contract lifecycle integration", () => {
       host.stepFrames();
       await host.input.mouse.click(40, 40);
       expect(host.scene.hits).toBe(1);
+      contract.checkpoint("hit-recorded");
       host.destroy();
       await callbacks[0]?.();
       expect(context.task.meta.gameplayContract).toMatchObject({
         id: "InputScene.hit",
         evidence: {
           clicks: 1,
+          checkpoints: ["hit-recorded"],
           frames: 1,
           mouseEvents: 3
         }

package/dist/lint/phaser-headless.contract.mjs

@@ -983,7 +983,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1149,6 +1150,9 @@ describe("Phaser HEADLESS host", () => {
     expect(() => boundedHost.stepUntil(() => false, 1.5)).toThrow(
       "stepUntil maxFrames must be a non-negative safe integer"
     );
+    expect(() => boundedHost.stepUntil(() => false, { maxFrames: 0 })).toThrow(
+      "Condition was not met within 0 complete Phaser frames"
+    );
     expect(() => boundedHost.stepPhysics(-1)).toThrow(
       "stepPhysics steps must be a non-negative safe integer"
     );

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

@@ -339,18 +339,21 @@ function auditGameplayRun(options, tests) {
     observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options.scenes);
-  for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene)) {
-      issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
-      );
+  if (observedEvidence.length > 0) {
+    for (const scene of expectedScenes) {
+      if (!registeredScenes.includes(scene)) {
+        issues.push(
+          `\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)) {
+        issues.push(
+          `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
+        );
+      }
     }
-  }
-  for (const scene of registeredScenes) {
-    if (!expectedScenes.includes(scene))
-      issues.push(
-        `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
-      );
   }
   return { passed: issues.length === 0, issues: [...new Set(issues)] };
 }
@@ -378,18 +381,31 @@ function formatGameplayIssues(issues) {
   const groups = /* @__PURE__ */ new Map();
   const repairKeys = /* @__PURE__ */ new Set();
   const repairs = [];
+  const missingByFile = /* @__PURE__ */ new Map();
+  const missingIds = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const match = issue.match(
+      /没有找到检查项 "([^"]+)" 的可执行测试（(.+)）。/
+    );
+    if (!match) continue;
+    const [, id, file] = match;
+    missingIds.add(id);
+    const ids = missingByFile.get(file) ?? [];
+    if (!ids.includes(id)) ids.push(id);
+    missingByFile.set(file, ids);
+  }
   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",
+    transition: "\u573A\u666F\u5207\u6362\uFF1A\u542F\u52A8\u6E38\u620F\u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u6E38\u620F\u4E2D\u7684\u5207\u6362\u903B\u8F91\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u68C0\u67E5\u5207\u6362\u7ED3\u679C\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",
+    checkpoint: "\u8FDB\u5EA6\u6807\u8BB0\uFF1A\u5148\u68C0\u67E5\u6E38\u620F\u81EA\u8EAB\u7684\u72B6\u6001\uFF08\u4F8B\u5982\u5206\u6570\u3001\u751F\u547D\u503C\u6216\u5F53\u524D\u5173\u5361\uFF09\uFF0C\u518D\u8C03\u7528 host.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"
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
+    missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -417,9 +433,26 @@ function formatGameplayIssues(issues) {
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
+  for (const [file, ids] of missingByFile) {
+    groups.set(`missing:${file}`, {
+      text: `${file} \u4E2D\u6CA1\u6709\u627E\u5230\u914D\u7F6E\u8981\u6C42\u7684\u73A9\u6CD5\u6D4B\u8BD5\uFF1A${ids.join("\u3001")}\u3002`,
+      ids: [],
+      key: `missing:${file}`
+    });
+  }
+  if (missingByFile.size > 0) {
+    repairKeys.add("missing");
+    repairs.push(repairText.missing);
+  }
   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");
+    if (compact.startsWith("\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 ")) continue;
+    const missingContract = compact.match(/缺少 (?:gameplay )?contract "([^"]+)"/)?.[1];
+    if (missingContract && missingIds.has(missingContract)) continue;
+    if (missingIds.size > 0 && compact.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      continue;
+    }
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
     const id = compact.match(/contract "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
@@ -436,7 +469,7 @@ function formatGameplayIssues(issues) {
   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 `${group.text}\uFF08\u540C\u7C7B\u95EE\u9898\u8FD8\u51FA\u73B0\u5728\uFF1A${group.ids.slice(1).join("\u3001")}\uFF09`;
   });
   return {
     issues: visible.map(
@@ -450,9 +483,7 @@ function printIssues(stage, issues) {
   if (issues.length === 0) return;
   console.error(`
 GAMEPLAY_AUDIT: ${stage} FAILED`);
-  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"
-  );
+  console.error("\u73A9\u6CD5\u6D4B\u8BD5\u672A\u901A\u8FC7\u3002\u8BF7\u5148\u5904\u7406\u7B2C\u4E00\u7C7B\u95EE\u9898\uFF0C\u91CD\u65B0\u8FD0\u884C\u540E\u518D\u5904\u7406\u540E\u7EED\u95EE\u9898\u3002");
   const formatted = formatGameplayIssues(issues);
   for (const issue of formatted.issues) console.error(`- ${issue}`);
   if (formatted.repairs.length > 0) {
@@ -519,9 +550,6 @@ var GameplayAuditReporter = class {
       ...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 {

package/dist/vitest-config.d.mts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.mjs';
+import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.mjs';
 import 'phaser';
 
 interface GameVitestConfigOptions {

package/dist/vitest-config.d.ts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.js';
+import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.js';
 import 'phaser';
 
 interface GameVitestConfigOptions {

package/dist/vitest-config.js

@@ -359,18 +359,21 @@ function auditGameplayRun(options, tests) {
     observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options.scenes);
-  for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene)) {
-      issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
-      );
+  if (observedEvidence.length > 0) {
+    for (const scene of expectedScenes) {
+      if (!registeredScenes.includes(scene)) {
+        issues.push(
+          `\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)) {
+        issues.push(
+          `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
+        );
+      }
     }
-  }
-  for (const scene of registeredScenes) {
-    if (!expectedScenes.includes(scene))
-      issues.push(
-        `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
-      );
   }
   return { passed: issues.length === 0, issues: [...new Set(issues)] };
 }
@@ -398,18 +401,31 @@ function formatGameplayIssues(issues) {
   const groups = /* @__PURE__ */ new Map();
   const repairKeys = /* @__PURE__ */ new Set();
   const repairs = [];
+  const missingByFile = /* @__PURE__ */ new Map();
+  const missingIds = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const match = issue.match(
+      /没有找到检查项 "([^"]+)" 的可执行测试（(.+)）。/
+    );
+    if (!match) continue;
+    const [, id, file] = match;
+    missingIds.add(id);
+    const ids = missingByFile.get(file) ?? [];
+    if (!ids.includes(id)) ids.push(id);
+    missingByFile.set(file, ids);
+  }
   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",
+    transition: "\u573A\u666F\u5207\u6362\uFF1A\u542F\u52A8\u6E38\u620F\u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u6E38\u620F\u4E2D\u7684\u5207\u6362\u903B\u8F91\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u68C0\u67E5\u5207\u6362\u7ED3\u679C\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",
+    checkpoint: "\u8FDB\u5EA6\u6807\u8BB0\uFF1A\u5148\u68C0\u67E5\u6E38\u620F\u81EA\u8EAB\u7684\u72B6\u6001\uFF08\u4F8B\u5982\u5206\u6570\u3001\u751F\u547D\u503C\u6216\u5F53\u524D\u5173\u5361\uFF09\uFF0C\u518D\u8C03\u7528 host.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"
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
+    missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -437,9 +453,26 @@ function formatGameplayIssues(issues) {
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
+  for (const [file, ids] of missingByFile) {
+    groups.set(`missing:${file}`, {
+      text: `${file} \u4E2D\u6CA1\u6709\u627E\u5230\u914D\u7F6E\u8981\u6C42\u7684\u73A9\u6CD5\u6D4B\u8BD5\uFF1A${ids.join("\u3001")}\u3002`,
+      ids: [],
+      key: `missing:${file}`
+    });
+  }
+  if (missingByFile.size > 0) {
+    repairKeys.add("missing");
+    repairs.push(repairText.missing);
+  }
   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");
+    if (compact.startsWith("\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 ")) continue;
+    const missingContract = compact.match(/缺少 (?:gameplay )?contract "([^"]+)"/)?.[1];
+    if (missingContract && missingIds.has(missingContract)) continue;
+    if (missingIds.size > 0 && compact.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      continue;
+    }
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
     const id = compact.match(/contract "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
@@ -456,7 +489,7 @@ function formatGameplayIssues(issues) {
   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 `${group.text}\uFF08\u540C\u7C7B\u95EE\u9898\u8FD8\u51FA\u73B0\u5728\uFF1A${group.ids.slice(1).join("\u3001")}\uFF09`;
   });
   return {
     issues: visible.map(
@@ -470,9 +503,7 @@ function printIssues(stage, issues) {
   if (issues.length === 0) return;
   console.error(`
 GAMEPLAY_AUDIT: ${stage} FAILED`);
-  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"
-  );
+  console.error("\u73A9\u6CD5\u6D4B\u8BD5\u672A\u901A\u8FC7\u3002\u8BF7\u5148\u5904\u7406\u7B2C\u4E00\u7C7B\u95EE\u9898\uFF0C\u91CD\u65B0\u8FD0\u884C\u540E\u518D\u5904\u7406\u540E\u7EED\u95EE\u9898\u3002");
   const formatted = formatGameplayIssues(issues);
   for (const issue of formatted.issues) console.error(`- ${issue}`);
   if (formatted.repairs.length > 0) {
@@ -539,9 +570,6 @@ var GameplayAuditReporter = class {
       ...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 {

package/dist/vitest-config.mjs

@@ -335,18 +335,21 @@ function auditGameplayRun(options, tests) {
     observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options.scenes);
-  for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene)) {
-      issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
-      );
+  if (observedEvidence.length > 0) {
+    for (const scene of expectedScenes) {
+      if (!registeredScenes.includes(scene)) {
+        issues.push(
+          `\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)) {
+        issues.push(
+          `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
+        );
+      }
     }
-  }
-  for (const scene of registeredScenes) {
-    if (!expectedScenes.includes(scene))
-      issues.push(
-        `host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "${scene}"\u3002`
-      );
   }
   return { passed: issues.length === 0, issues: [...new Set(issues)] };
 }
@@ -374,18 +377,31 @@ function formatGameplayIssues(issues) {
   const groups = /* @__PURE__ */ new Map();
   const repairKeys = /* @__PURE__ */ new Set();
   const repairs = [];
+  const missingByFile = /* @__PURE__ */ new Map();
+  const missingIds = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    const match = issue.match(
+      /没有找到检查项 "([^"]+)" 的可执行测试（(.+)）。/
+    );
+    if (!match) continue;
+    const [, id, file] = match;
+    missingIds.add(id);
+    const ids = missingByFile.get(file) ?? [];
+    if (!ids.includes(id)) ids.push(id);
+    missingByFile.set(file, ids);
+  }
   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",
+    transition: "\u573A\u666F\u5207\u6362\uFF1A\u542F\u52A8\u6E38\u620F\u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u6E38\u620F\u4E2D\u7684\u5207\u6362\u903B\u8F91\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u68C0\u67E5\u5207\u6362\u7ED3\u679C\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",
+    checkpoint: "\u8FDB\u5EA6\u6807\u8BB0\uFF1A\u5148\u68C0\u67E5\u6E38\u620F\u81EA\u8EAB\u7684\u72B6\u6001\uFF08\u4F8B\u5982\u5206\u6570\u3001\u751F\u547D\u503C\u6216\u5F53\u524D\u5173\u5361\uFF09\uFF0C\u518D\u8C03\u7528 host.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"
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
+    missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -413,9 +429,26 @@ function formatGameplayIssues(issues) {
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
+  for (const [file, ids] of missingByFile) {
+    groups.set(`missing:${file}`, {
+      text: `${file} \u4E2D\u6CA1\u6709\u627E\u5230\u914D\u7F6E\u8981\u6C42\u7684\u73A9\u6CD5\u6D4B\u8BD5\uFF1A${ids.join("\u3001")}\u3002`,
+      ids: [],
+      key: `missing:${file}`
+    });
+  }
+  if (missingByFile.size > 0) {
+    repairKeys.add("missing");
+    repairs.push(repairText.missing);
+  }
   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");
+    if (compact.startsWith("\u6CA1\u6709\u627E\u5230\u68C0\u67E5\u9879 ")) continue;
+    const missingContract = compact.match(/缺少 (?:gameplay )?contract "([^"]+)"/)?.[1];
+    if (missingContract && missingIds.has(missingContract)) continue;
+    if (missingIds.size > 0 && compact.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      continue;
+    }
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
     const id = compact.match(/contract "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
@@ -432,7 +465,7 @@ function formatGameplayIssues(issues) {
   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 `${group.text}\uFF08\u540C\u7C7B\u95EE\u9898\u8FD8\u51FA\u73B0\u5728\uFF1A${group.ids.slice(1).join("\u3001")}\uFF09`;
   });
   return {
     issues: visible.map(
@@ -446,9 +479,7 @@ function printIssues(stage, issues) {
   if (issues.length === 0) return;
   console.error(`
 GAMEPLAY_AUDIT: ${stage} FAILED`);
-  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"
-  );
+  console.error("\u73A9\u6CD5\u6D4B\u8BD5\u672A\u901A\u8FC7\u3002\u8BF7\u5148\u5904\u7406\u7B2C\u4E00\u7C7B\u95EE\u9898\uFF0C\u91CD\u65B0\u8FD0\u884C\u540E\u518D\u5904\u7406\u540E\u7EED\u95EE\u9898\u3002");
   const formatted = formatGameplayIssues(issues);
   for (const issue of formatted.issues) console.error(`- ${issue}`);
   if (formatted.repairs.length > 0) {
@@ -515,9 +546,6 @@ var GameplayAuditReporter = class {
       ...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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",