miaoda-game-devkit 0.2.7 → 0.2.9

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

@@ -45,6 +45,7 @@ function createGameplayContractMetadata(contract) {
 }
 function validateGameplayAuditOptions(options2, projectRoot) {
   const issues = [];
+  const contracts = options2.contracts;
   const scenes = [...new Set(options2.scenes.map((scene) => scene.trim()).filter(Boolean))];
   const mode = options2.mode ?? "interactive";
   if (mode === "non-interactive") {
@@ -66,7 +67,7 @@ function validateGameplayAuditOptions(options2, projectRoot) {
   const coveredScenes = /* @__PURE__ */ new Set();
   const kinds = /* @__PURE__ */ new Map();
   const invalidKindContracts = [];
-  for (const contract of options2.contracts) {
+  for (const contract of contracts ?? []) {
     const id = contract.id.trim();
     if (!id) {
       issues.push("gameplayAudit.contracts \u4E2D\u5B58\u5728\u7A7A contract id\u3002");
@@ -92,7 +93,6 @@ function validateGameplayAuditOptions(options2, projectRoot) {
       kinds.set(contract.kind, list);
     }
     if (contract.kind === "playthrough") {
-      if (!contract.requireInput) issues.push(`playthrough contract "${id}" \u5FC5\u987B requireInput: true\u3002`);
       if (!contract.requireFrameAdvance) issues.push(`playthrough contract "${id}" \u5FC5\u987B requireFrameAdvance: true\u3002`);
       if (normalizeList(contract.requireCheckpoint).length === 0) issues.push(`playthrough contract "${id}" \u5FC5\u987B\u58F0\u660E requireCheckpoint\u3002`);
     }
@@ -100,7 +100,6 @@ function validateGameplayAuditOptions(options2, projectRoot) {
       issues.push(`transition contract "${id}" \u5FC5\u987B\u58F0\u660E requireTransition\u3002`);
     }
     if (contract.kind === "recovery") {
-      if (!contract.requireInput) issues.push(`recovery contract "${id}" \u5FC5\u987B requireInput: true\u3002`);
       if (!contract.requireFrameAdvance) issues.push(`recovery contract "${id}" \u5FC5\u987B requireFrameAdvance: true\u3002`);
       if (normalizeList(contract.requireRestart).length === 0) issues.push(`recovery contract "${id}" \u5FC5\u987B\u58F0\u660E requireRestart\u3002`);
       if (normalizeList(contract.requireCheckpoint).length < 2) issues.push(`recovery contract "${id}" \u81F3\u5C11\u9700\u8981\u4E24\u4E2A checkpoint\uFF08\u91CD\u7F6E\u524D\u540E\uFF09\u3002`);
@@ -122,31 +121,24 @@ function validateGameplayAuditOptions(options2, projectRoot) {
       `\u4EE5\u4E0B contract \u7F3A\u5C11\u6709\u6548 kind\uFF1A${invalidKindContracts.map((id) => `"${id}"`).join("\u3001")}\u3002\u8BF7\u4E3A\u6BCF\u4E2A contract \u8BBE\u7F6E kind: "boot"\u3001"playthrough"\u3001"transition" \u6216 "recovery"\u3002`
     );
   }
-  for (const scene of scenes) {
-    if (!coveredScenes.has(scene)) {
-      issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+  if (contracts) {
+    for (const scene of scenes) {
+      if (!coveredScenes.has(scene)) {
+        issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+      }
     }
+    if (contracts.length === 0)
+      issues.push("gameplayAudit.contracts \u5B58\u5728\u65F6\u4E0D\u80FD\u4E3A\u7A7A\uFF1B\u4E0D\u4F7F\u7528\u663E\u5F0F\u6E05\u5355\u8BF7\u7701\u7565\u8BE5\u5B57\u6BB5\u3002");
   }
-  if (options2.contracts.length === 0)
-    issues.push("gameplayAudit.contracts \u4E0D\u80FD\u4E3A\u7A7A\u3002");
-  if (mode === "interactive") {
-    const hasPlaythrough = (kinds.get("playthrough") ?? []).length > 0;
-    const hasInput = options2.contracts.some((contract) => contract.requireInput);
-    const hasCheckpoint = options2.contracts.some((contract) => normalizeList(contract.requireCheckpoint).length > 0);
-    if (!hasPlaythrough || !hasInput || !hasCheckpoint) {
+  if (mode === "interactive" && contracts) {
+    const hasPlaythrough = (kinds.get("playthrough") ?? []).some(
+      (contract) => Boolean(contract.requireFrameAdvance) && normalizeList(contract.requireCheckpoint).length > 0
+    );
+    const hasInput = contracts.some((contract) => contract.requireInput);
+    if (!hasPlaythrough || !hasInput) {
       issues.push(
-        '\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A kind: "playthrough" contract \u5FC5\u987B\u540C\u65F6\u58F0\u660E requireInput: true\u3001requireFrameAdvance: true \u548C requireCheckpoint: ["progress"]\u3002'
-      );
-    }
-    const entryScene = scenes[0];
-    for (const scene of scenes.slice(1)) {
-      const transitioned = options2.contracts.some(
-        (contract) => (contract.kind === "transition" || contract.kind === "playthrough") && normalizeList(contract.requireTransition).includes(scene)
+        "\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A playthrough contract \u5FC5\u987B\u58F0\u660E requireFrameAdvance \u548C checkpoint\uFF0C\u4E14\u81F3\u5C11\u4E00\u4E2A contract \u5FC5\u987B\u58F0\u660E requireInput: true\u3002"
       );
-      if (!transitioned) issues.push(`\u975E\u5165\u53E3 Scene "${scene}" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002`);
-    }
-    if (entryScene && scenes.length > 1 && (kinds.get("transition") ?? []).length === 0 && (kinds.get("playthrough") ?? []).length === 0 && invalidKindContracts.length === 0) {
-      issues.push(`\u4EA4\u4E92\u9879\u76EE\u5165\u53E3 Scene "${entryScene}" \u7F3A\u5C11 transition/playthrough flow\u3002`);
     }
     const restartSignal = projectRoot ? containsProductionRestart(projectRoot) : false;
     if (restartSignal && options2.flows?.restart !== true) {
@@ -208,11 +200,21 @@ function getDefinitionIssues(expected, actual) {
 }
 function auditGameplayCollection(options2, file, tests) {
   const normalizedFile = file.replaceAll("\\", "/");
-  const expected = options2.contracts.filter(
+  const expected = (options2.contracts ?? []).filter(
     (contract) => contract.testFile.replaceAll("\\", "/") === normalizedFile
   );
   const actual = tests.filter((test) => test.metadata);
   const issues = [];
+  if (!options2.contracts) {
+    const actualIds = /* @__PURE__ */ new Set();
+    for (const test of actual) {
+      const id = test.metadata?.id;
+      if (!id) continue;
+      if (actualIds.has(id)) issues.push(`contract "${id}" \u5728 ${normalizedFile} \u4E2D\u91CD\u590D\u5B9A\u4E49\u3002`);
+      actualIds.add(id);
+    }
+    return { passed: issues.length === 0, issues };
+  }
   for (const contract of expected) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
@@ -285,7 +287,25 @@ function auditGameplayRun(options2, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
   const observedEvidence = [];
-  for (const expected of options2.contracts) {
+  const discoveredContracts = actualContracts.flatMap((test) => {
+    const metadata = test.metadata;
+    if (!metadata) return [];
+    return [{
+      id: metadata.id,
+      kind: metadata.kind,
+      testFile: test.file,
+      scenes: metadata.scenes,
+      ...metadata.requirements
+    }];
+  });
+  const expectedContracts = options2.contracts ?? discoveredContracts;
+  if (!options2.contracts) {
+    const discoveredIssues = validateGameplayAuditOptions(
+      { ...options2, contracts: discoveredContracts }
+    );
+    issues.push(...discoveredIssues);
+  }
+  for (const expected of expectedContracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
     );
@@ -308,7 +328,11 @@ function auditGameplayRun(options2, tests) {
     }
     issues.push(...getDefinitionIssues(expected, metadata));
     if (test.state !== "passed") {
-      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      if (test.error) {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u6D4B\u8BD5\u5931\u8D25\uFF1A${test.error}`);
+      } else {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      }
       continue;
     }
     if (!metadata.verified || !metadata.evidence) {
@@ -324,7 +348,7 @@ function auditGameplayRun(options2, tests) {
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
-    if (id && !options2.contracts.some((contract) => contract.id === id)) {
+    if (id && options2.contracts && !options2.contracts.some((contract) => contract.id === id)) {
       issues.push(
         `\u53D1\u73B0\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\uFF08${test.file}\uFF09\u3002`
       );
@@ -383,7 +407,8 @@ function formatGameplayIssues(issues) {
     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\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"
+    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",
+    unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -408,6 +433,14 @@ function formatGameplayIssues(issues) {
       return { category: "registry", key: `registry:${scene}` };
     }
     if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u6D4B\u8BD5\u5931\u8D25\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u5931\u8D25\uFF1A")[1] ?? issue;
+      return { category: "test", key: `test:${message}` };
+    }
+    if (issue.includes("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")[1] ?? issue;
+      return { category: "unhandled", key: `test:${message}` };
+    }
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
@@ -431,7 +464,7 @@ function formatGameplayIssues(issues) {
       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 id = compact.match(/(?:contract|玩法测试) "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
     if (group) {
@@ -518,7 +551,7 @@ describe("gameplay audit", () => {
       ]
     });
     expect(result).toContain(
-      '\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A kind: "playthrough" contract \u5FC5\u987B\u540C\u65F6\u58F0\u660E requireInput: true\u3001requireFrameAdvance: true \u548C requireCheckpoint: ["progress"]\u3002'
+      "\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A playthrough contract \u5FC5\u987B\u58F0\u660E requireFrameAdvance \u548C checkpoint\uFF0C\u4E14\u81F3\u5C11\u4E00\u4E2A contract \u5FC5\u987B\u58F0\u660E requireInput: true\u3002"
     );
   });
   it("\u5141\u8BB8\u5E26\u7406\u7531\u7684\u975E\u4EA4\u4E92 boot-only \u9879\u76EE", () => {
@@ -538,6 +571,44 @@ describe("gameplay audit", () => {
       })
     ).toEqual([]);
   });
+  it("\u5141\u8BB8 Telemetry \u957F\u6D41\u7A0B\u4E0E\u72EC\u7ACB\u771F\u5B9E\u8F93\u5165 contract \u5206\u5DE5", () => {
+    expect(
+      validateGameplayAuditOptions({
+        mode: "interactive",
+        scenes: ["IndexScene"],
+        contracts: [
+          {
+            id: "IndexScene.telemetry-playthrough",
+            kind: "playthrough",
+            testFile: "tests/gameplay.test.ts",
+            scenes: ["IndexScene"],
+            requireFrameAdvance: true,
+            requireCheckpoint: "progress"
+          },
+          {
+            id: "IndexScene.input-smoke",
+            kind: "playthrough",
+            testFile: "tests/gameplay.test.ts",
+            scenes: ["IndexScene"],
+            requireInput: true,
+            requireFrameAdvance: true,
+            requireCheckpoint: "input-wired"
+          }
+        ]
+      })
+    ).toEqual([]);
+  });
+  it("\u5141\u8BB8\u7701\u7565\u91CD\u590D inventory \u5E76\u4ECE gameplayTest metadata \u5BA1\u8BA1", () => {
+    const inventoryFree = {
+      mode: "interactive",
+      scenes: ["IndexScene", "BattleScene"]
+    };
+    expect(validateGameplayAuditOptions(inventoryFree)).toEqual([]);
+    expect(auditGameplayRun(inventoryFree, [createPassingTest()])).toEqual({
+      passed: true,
+      issues: []
+    });
+  });
   it("\u5F3A\u5236 recovery contract \u540C\u65F6\u58F0\u660E restart \u548C\u4E24\u4E2A checkpoint", () => {
     const result = validateGameplayAuditOptions({
       mode: "non-interactive",
@@ -557,26 +628,34 @@ describe("gameplay audit", () => {
       'recovery contract "BattleScene.recovery" \u81F3\u5C11\u9700\u8981\u4E24\u4E2A checkpoint\uFF08\u91CD\u7F6E\u524D\u540E\uFF09\u3002'
     ]));
   });
-  it("\u4EA4\u4E92\u9879\u76EE\u8981\u6C42\u6BCF\u4E2A\u975E\u5165\u53E3 Scene \u6709\u751F\u4EA7\u8F6C\u573A\u8BC1\u636E\u58F0\u660E", () => {
+  it("\u5141\u8BB8\u72EC\u7ACB\u8986\u76D6 Scene\uFF0C\u800C\u4E0D\u5F3A\u5236\u5236\u9020\u751F\u4EA7\u8F6C\u573A", () => {
     const result = validateGameplayAuditOptions({
       mode: "interactive",
       scenes: ["MenuScene", "BattleScene"],
-      contracts: [{
-        id: "MenuScene.playthrough",
-        kind: "playthrough",
-        testFile: "tests/gameplay.test.ts",
-        scenes: ["MenuScene"],
-        requireInput: true,
-        requireFrameAdvance: true,
-        requireCheckpoint: "progress"
-      }]
+      contracts: [
+        {
+          id: "MenuScene.playthrough",
+          kind: "playthrough",
+          testFile: "tests/gameplay.test.ts",
+          scenes: ["MenuScene"],
+          requireInput: true,
+          requireFrameAdvance: true,
+          requireCheckpoint: "progress"
+        },
+        {
+          id: "BattleScene.boot",
+          kind: "boot",
+          testFile: "tests/gameplay.test.ts",
+          scenes: ["BattleScene"]
+        }
+      ]
     });
-    expect(result).toContain('\u975E\u5165\u53E3 Scene "BattleScene" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002');
+    expect(result).toEqual([]);
   });
-  it("\u4E0D\u63A5\u53D7 boot contract \u4F2A\u88C5\u6210\u751F\u4EA7\u8F6C\u573A", () => {
+  it("\u4ECD\u8981\u6C42 transition contract \u58F0\u660E\u76EE\u6807", () => {
     const result = validateGameplayAuditOptions({
       mode: "interactive",
-      scenes: ["MenuScene", "BattleScene"],
+      scenes: ["MenuScene"],
       contracts: [
         {
           id: "MenuScene.playthrough",
@@ -588,16 +667,15 @@ describe("gameplay audit", () => {
           requireCheckpoint: "progress"
         },
         {
-          id: "BattleScene.boot",
-          kind: "boot",
+          id: "MenuScene.transition",
+          kind: "transition",
           testFile: "tests/gameplay.test.ts",
-          scenes: ["BattleScene"],
-          requireTransition: "BattleScene"
+          scenes: ["MenuScene"]
         }
       ]
     });
     expect(result).toContain(
-      '\u975E\u5165\u53E3 Scene "BattleScene" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002'
+      'transition contract "MenuScene.transition" \u5FC5\u987B\u58F0\u660E requireTransition\u3002'
     );
   });
   it("\u58F0\u660E restart flow \u540E\u4ECD\u5F3A\u5236 recovery contract", () => {
@@ -817,4 +895,15 @@ describe("gameplay audit", () => {
     expect(result.repairs).toHaveLength(1);
     expect(result.repairs[0]).toContain("vitest.config.ts");
   });
+  it("\u4FDD\u7559\u5E76\u5408\u5E76 Vitest \u8FD0\u884C\u65F6\u5F02\u5E38\u6D88\u606F", () => {
+    const result = formatGameplayIssues([
+      '\u73A9\u6CD5\u6D4B\u8BD5 "Map.transition" \u6D4B\u8BD5\u5931\u8D25\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events',
+      '\u73A9\u6CD5\u6D4B\u8BD5 "Editor.transition" \u6D4B\u8BD5\u5931\u8D25\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events',
+      "\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events"
+    ]);
+    expect(result.issues).toEqual([
+      '\u73A9\u6CD5\u6D4B\u8BD5 "Map.transition" \u6D4B\u8BD5\u5931\u8D25\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events\uFF08\u540C\u7C7B\u95EE\u9898\u8FD8\u51FA\u73B0\u5728\uFF1AEditor.transition\uFF09'
+    ]);
+    expect(result.repairs[0]).toContain("\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF");
+  });
 });

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

@@ -1,5 +1,5 @@
 // src/lint/gameplay-contract.test.ts
-import * as Phaser4 from "phaser";
+import * as Phaser5 from "phaser";
 import { describe, expect, it } from "vitest";
 
 // src/phaser-headless-host.ts
@@ -1168,8 +1168,11 @@ function registerGameplayContract(context, options) {
   };
 }
 
+// src/game-telemetry.ts
+import * as Phaser4 from "phaser";
+
 // src/lint/gameplay-contract.test.ts
-var InputScene = class extends Phaser4.Scene {
+var InputScene = class extends Phaser5.Scene {
   hits = 0;
   constructor() {
     super("InputScene");

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

@@ -50,6 +50,7 @@ function createGameplayContractMetadata(contract) {
 }
 function validateGameplayAuditOptions(options, projectRoot2) {
   const issues = [];
+  const contracts = options.contracts;
   const scenes = [...new Set(options.scenes.map((scene) => scene.trim()).filter(Boolean))];
   const mode = options.mode ?? "interactive";
   if (mode === "non-interactive") {
@@ -71,7 +72,7 @@ function validateGameplayAuditOptions(options, projectRoot2) {
   const coveredScenes = /* @__PURE__ */ new Set();
   const kinds = /* @__PURE__ */ new Map();
   const invalidKindContracts = [];
-  for (const contract of options.contracts) {
+  for (const contract of contracts ?? []) {
     const id = contract.id.trim();
     if (!id) {
       issues.push("gameplayAudit.contracts \u4E2D\u5B58\u5728\u7A7A contract id\u3002");
@@ -97,7 +98,6 @@ function validateGameplayAuditOptions(options, projectRoot2) {
       kinds.set(contract.kind, list);
     }
     if (contract.kind === "playthrough") {
-      if (!contract.requireInput) issues.push(`playthrough contract "${id}" \u5FC5\u987B requireInput: true\u3002`);
       if (!contract.requireFrameAdvance) issues.push(`playthrough contract "${id}" \u5FC5\u987B requireFrameAdvance: true\u3002`);
       if (normalizeList(contract.requireCheckpoint).length === 0) issues.push(`playthrough contract "${id}" \u5FC5\u987B\u58F0\u660E requireCheckpoint\u3002`);
     }
@@ -105,7 +105,6 @@ function validateGameplayAuditOptions(options, projectRoot2) {
       issues.push(`transition contract "${id}" \u5FC5\u987B\u58F0\u660E requireTransition\u3002`);
     }
     if (contract.kind === "recovery") {
-      if (!contract.requireInput) issues.push(`recovery contract "${id}" \u5FC5\u987B requireInput: true\u3002`);
       if (!contract.requireFrameAdvance) issues.push(`recovery contract "${id}" \u5FC5\u987B requireFrameAdvance: true\u3002`);
       if (normalizeList(contract.requireRestart).length === 0) issues.push(`recovery contract "${id}" \u5FC5\u987B\u58F0\u660E requireRestart\u3002`);
       if (normalizeList(contract.requireCheckpoint).length < 2) issues.push(`recovery contract "${id}" \u81F3\u5C11\u9700\u8981\u4E24\u4E2A checkpoint\uFF08\u91CD\u7F6E\u524D\u540E\uFF09\u3002`);
@@ -127,31 +126,24 @@ function validateGameplayAuditOptions(options, projectRoot2) {
       `\u4EE5\u4E0B contract \u7F3A\u5C11\u6709\u6548 kind\uFF1A${invalidKindContracts.map((id) => `"${id}"`).join("\u3001")}\u3002\u8BF7\u4E3A\u6BCF\u4E2A contract \u8BBE\u7F6E kind: "boot"\u3001"playthrough"\u3001"transition" \u6216 "recovery"\u3002`
     );
   }
-  for (const scene of scenes) {
-    if (!coveredScenes.has(scene)) {
-      issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+  if (contracts) {
+    for (const scene of scenes) {
+      if (!coveredScenes.has(scene)) {
+        issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+      }
     }
+    if (contracts.length === 0)
+      issues.push("gameplayAudit.contracts \u5B58\u5728\u65F6\u4E0D\u80FD\u4E3A\u7A7A\uFF1B\u4E0D\u4F7F\u7528\u663E\u5F0F\u6E05\u5355\u8BF7\u7701\u7565\u8BE5\u5B57\u6BB5\u3002");
   }
-  if (options.contracts.length === 0)
-    issues.push("gameplayAudit.contracts \u4E0D\u80FD\u4E3A\u7A7A\u3002");
-  if (mode === "interactive") {
-    const hasPlaythrough = (kinds.get("playthrough") ?? []).length > 0;
-    const hasInput = options.contracts.some((contract) => contract.requireInput);
-    const hasCheckpoint = options.contracts.some((contract) => normalizeList(contract.requireCheckpoint).length > 0);
-    if (!hasPlaythrough || !hasInput || !hasCheckpoint) {
+  if (mode === "interactive" && contracts) {
+    const hasPlaythrough = (kinds.get("playthrough") ?? []).some(
+      (contract) => Boolean(contract.requireFrameAdvance) && normalizeList(contract.requireCheckpoint).length > 0
+    );
+    const hasInput = contracts.some((contract) => contract.requireInput);
+    if (!hasPlaythrough || !hasInput) {
       issues.push(
-        '\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A kind: "playthrough" contract \u5FC5\u987B\u540C\u65F6\u58F0\u660E requireInput: true\u3001requireFrameAdvance: true \u548C requireCheckpoint: ["progress"]\u3002'
-      );
-    }
-    const entryScene = scenes[0];
-    for (const scene of scenes.slice(1)) {
-      const transitioned = options.contracts.some(
-        (contract) => (contract.kind === "transition" || contract.kind === "playthrough") && normalizeList(contract.requireTransition).includes(scene)
+        "\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A playthrough contract \u5FC5\u987B\u58F0\u660E requireFrameAdvance \u548C checkpoint\uFF0C\u4E14\u81F3\u5C11\u4E00\u4E2A contract \u5FC5\u987B\u58F0\u660E requireInput: true\u3002"
       );
-      if (!transitioned) issues.push(`\u975E\u5165\u53E3 Scene "${scene}" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002`);
-    }
-    if (entryScene && scenes.length > 1 && (kinds.get("transition") ?? []).length === 0 && (kinds.get("playthrough") ?? []).length === 0 && invalidKindContracts.length === 0) {
-      issues.push(`\u4EA4\u4E92\u9879\u76EE\u5165\u53E3 Scene "${entryScene}" \u7F3A\u5C11 transition/playthrough flow\u3002`);
     }
     const restartSignal = projectRoot2 ? containsProductionRestart(projectRoot2) : false;
     if (restartSignal && options.flows?.restart !== true) {
@@ -213,11 +205,21 @@ function getDefinitionIssues(expected, actual) {
 }
 function auditGameplayCollection(options, file, tests) {
   const normalizedFile = file.replaceAll("\\", "/");
-  const expected = options.contracts.filter(
+  const expected = (options.contracts ?? []).filter(
     (contract) => contract.testFile.replaceAll("\\", "/") === normalizedFile
   );
   const actual = tests.filter((test) => test.metadata);
   const issues = [];
+  if (!options.contracts) {
+    const actualIds = /* @__PURE__ */ new Set();
+    for (const test of actual) {
+      const id = test.metadata?.id;
+      if (!id) continue;
+      if (actualIds.has(id)) issues.push(`contract "${id}" \u5728 ${normalizedFile} \u4E2D\u91CD\u590D\u5B9A\u4E49\u3002`);
+      actualIds.add(id);
+    }
+    return { passed: issues.length === 0, issues };
+  }
   for (const contract of expected) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
@@ -290,7 +292,25 @@ function auditGameplayRun(options, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
   const observedEvidence = [];
-  for (const expected of options.contracts) {
+  const discoveredContracts = actualContracts.flatMap((test) => {
+    const metadata = test.metadata;
+    if (!metadata) return [];
+    return [{
+      id: metadata.id,
+      kind: metadata.kind,
+      testFile: test.file,
+      scenes: metadata.scenes,
+      ...metadata.requirements
+    }];
+  });
+  const expectedContracts = options.contracts ?? discoveredContracts;
+  if (!options.contracts) {
+    const discoveredIssues = validateGameplayAuditOptions(
+      { ...options, contracts: discoveredContracts }
+    );
+    issues.push(...discoveredIssues);
+  }
+  for (const expected of expectedContracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
     );
@@ -313,7 +333,11 @@ function auditGameplayRun(options, tests) {
     }
     issues.push(...getDefinitionIssues(expected, metadata));
     if (test.state !== "passed") {
-      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      if (test.error) {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u6D4B\u8BD5\u5931\u8D25\uFF1A${test.error}`);
+      } else {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      }
       continue;
     }
     if (!metadata.verified || !metadata.evidence) {
@@ -329,7 +353,7 @@ function auditGameplayRun(options, tests) {
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
-    if (id && !options.contracts.some((contract) => contract.id === id)) {
+    if (id && options.contracts && !options.contracts.some((contract) => contract.id === id)) {
       issues.push(
         `\u53D1\u73B0\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\uFF08${test.file}\uFF09\u3002`
       );
@@ -370,11 +394,13 @@ function isGameplayContractMetadata(value) {
 }
 function toAuditTest(test) {
   const metadata = test.meta().gameplayContract;
+  const firstError = test.result().errors?.[0];
   return {
     file: normalizePath(test.module.relativeModuleId),
     name: test.fullName,
     state: test.result().state,
-    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
+    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0,
+    error: firstError?.message?.replaceAll(/\s+/g, " ").trim().slice(0, 360) || void 0
   };
 }
 function formatGameplayIssues(issues) {
@@ -405,7 +431,8 @@ function formatGameplayIssues(issues) {
     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\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"
+    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",
+    unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -430,6 +457,14 @@ function formatGameplayIssues(issues) {
       return { category: "registry", key: `registry:${scene}` };
     }
     if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u6D4B\u8BD5\u5931\u8D25\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u5931\u8D25\uFF1A")[1] ?? issue;
+      return { category: "test", key: `test:${message}` };
+    }
+    if (issue.includes("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")[1] ?? issue;
+      return { category: "unhandled", key: `test:${message}` };
+    }
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
@@ -453,7 +488,7 @@ function formatGameplayIssues(issues) {
       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 id = compact.match(/(?:contract|玩法测试) "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
     if (group) {
@@ -513,7 +548,7 @@ var GameplayAuditReporter = class {
         (specification) => normalizePath(relative(this.projectRoot, specification.moduleId))
       )
     );
-    for (const contract of this.options.contracts) {
+    for (const contract of this.options.contracts ?? []) {
       const testFile = normalizePath(contract.testFile);
       if (!scheduledFiles.has(testFile)) {
         this.reportPreflightIssue(
@@ -530,7 +565,7 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+  onTestRunEnd(testModules, unhandledErrors = [], reason = "passed") {
     const collectionFailed = reason === "failed" && testModules.some(
       (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
     );
@@ -545,9 +580,11 @@ var GameplayAuditReporter = class {
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
+    const runtimeIssues = unhandledErrors.map((error) => error.message?.replaceAll(/\s+/g, " ").trim()).filter(Boolean).map((message) => `\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A${message}`);
     const combinedIssues = [
       ...this.preflightIssues,
-      ...result.issues
+      ...result.issues,
+      ...runtimeIssues
     ];
     if (combinedIssues.length > 0) {
       printIssues("FINAL", [...new Set(combinedIssues)]);
@@ -555,7 +592,7 @@ var GameplayAuditReporter = class {
     } else {
       console.log(
         `
-GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts, ${this.options.scenes.length} scenes)`
+GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${tests.filter((test) => test.metadata).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"

package/dist/vitest-config.d.mts

@@ -1,11 +1,11 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.mjs';
+import { c as GameplayAuditOptions } from './gameplay-audit-CCJo4Qhk.mjs';
 import 'phaser';
 
 interface GameVitestConfigOptions {
     /** 模板项目的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
-    /** 测试前后都必须审计的生产 Scene 和玩法契约清单。 */
+    /** 测试前后都必须审计的生产 Scene；contracts 可省略以避免重复声明测试 metadata。 */
     gameplayAudit: GameplayAuditOptions;
     /** 项目需要的额外路径别名；`@` 由 devkit 统一维护。 */
     aliases?: Record<string, string>;

package/dist/vitest-config.d.ts

@@ -1,11 +1,11 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.js';
+import { c as GameplayAuditOptions } from './gameplay-audit-CCJo4Qhk.js';
 import 'phaser';
 
 interface GameVitestConfigOptions {
     /** 模板项目的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
-    /** 测试前后都必须审计的生产 Scene 和玩法契约清单。 */
+    /** 测试前后都必须审计的生产 Scene；contracts 可省略以避免重复声明测试 metadata。 */
     gameplayAudit: GameplayAuditOptions;
     /** 项目需要的额外路径别名；`@` 由 devkit 统一维护。 */
     aliases?: Record<string, string>;