miaoda-game-devkit 0.2.8 → 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
     );
@@ -328,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`
       );
@@ -531,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", () => {
@@ -551,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",
@@ -570,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",
@@ -601,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", () => {

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,32 +126,25 @@ 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'
+        "\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"
       );
     }
-    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)
-      );
-      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) {
       issues.push("\u68C0\u6D4B\u5230\u751F\u4EA7 Scene \u4F7F\u7528 scene.restart()\uFF1B\u5FC5\u987B\u58F0\u660E flows.restart: true \u5E76\u63D0\u4F9B kind: recovery contract\u3002");
@@ -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
     );
@@ -333,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`
       );
@@ -528,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(
@@ -572,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>;

package/dist/vitest-config.js

@@ -70,6 +70,7 @@ function createGameplayContractMetadata(contract) {
 }
 function validateGameplayAuditOptions(options, projectRoot) {
   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") {
@@ -91,7 +92,7 @@ function validateGameplayAuditOptions(options, projectRoot) {
   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");
@@ -117,7 +118,6 @@ function validateGameplayAuditOptions(options, 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`);
     }
@@ -125,7 +125,6 @@ function validateGameplayAuditOptions(options, 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`);
@@ -147,32 +146,25 @@ function validateGameplayAuditOptions(options, 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 (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'
+        "\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"
       );
     }
-    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)
-      );
-      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 && options.flows?.restart !== true) {
       issues.push("\u68C0\u6D4B\u5230\u751F\u4EA7 Scene \u4F7F\u7528 scene.restart()\uFF1B\u5FC5\u987B\u58F0\u660E flows.restart: true \u5E76\u63D0\u4F9B kind: recovery contract\u3002");
@@ -233,11 +225,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) {
@@ -310,7 +312,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
     );
@@ -353,7 +373,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`
       );
@@ -548,7 +568,7 @@ var GameplayAuditReporter = class {
         (specification) => normalizePath((0, import_node_path2.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(
@@ -592,7 +612,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"