miaoda-game-devkit 0.2.7 → 0.2.9

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,31 +146,24 @@ 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'
-      );
-    }
-    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 = projectRoot ? containsProductionRestart(projectRoot) : false;
     if (restartSignal && options.flows?.restart !== true) {
@@ -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
     );
@@ -333,7 +353,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) {
@@ -349,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`
       );
@@ -390,11 +414,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) {
@@ -425,7 +451,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" };
@@ -450,6 +477,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}` };
   };
@@ -473,7 +508,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) {
@@ -533,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(
@@ -550,7 +585,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
     );
@@ -565,9 +600,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)]);
@@ -575,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"

package/dist/vitest-config.mjs

@@ -46,6 +46,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") {
@@ -67,7 +68,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");
@@ -93,7 +94,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`);
     }
@@ -101,7 +101,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`);
@@ -123,31 +122,24 @@ 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'
-      );
-    }
-    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 = projectRoot ? containsProductionRestart(projectRoot) : false;
     if (restartSignal && options.flows?.restart !== true) {
@@ -209,11 +201,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) {
@@ -286,7 +288,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
     );
@@ -309,7 +329,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) {
@@ -325,7 +349,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`
       );
@@ -366,11 +390,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) {
@@ -401,7 +427,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" };
@@ -426,6 +453,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}` };
   };
@@ -449,7 +484,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) {
@@ -509,7 +544,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(
@@ -526,7 +561,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
     );
@@ -541,9 +576,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)]);
@@ -551,7 +588,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/package.json

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