miaoda-game-devkit 0.2.2 → 0.2.4

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

@@ -2,6 +2,8 @@
 import { describe, expect, it } from "vitest";
 
 // src/gameplay-audit.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -35,20 +37,35 @@ function createGameplayContractMetadata(contract) {
   const scenes = normalizeSet(contract.scenes);
   return {
     id: contract.id.trim(),
+    kind: contract.kind,
     scenes,
     requirements: normalizeGameplayRequirements(contract, scenes),
     verified: false
   };
 }
-function validateGameplayAuditOptions(options2) {
+function validateGameplayAuditOptions(options2, projectRoot) {
   const issues = [];
-  const scenes = normalizeSet(options2.scenes);
+  const scenes = [...new Set(options2.scenes.map((scene) => scene.trim()).filter(Boolean))];
+  const mode = options2.mode ?? "interactive";
+  if (mode === "non-interactive") {
+    const justification = options2.nonInteractiveJustification?.trim() ?? "";
+    if (justification.length < 20) {
+      issues.push(
+        "non-interactive \u6A21\u5F0F\u5FC5\u987B\u63D0\u4F9B\u81F3\u5C11 20 \u4E2A\u5B57\u7B26\u7684 nonInteractiveJustification\u3002"
+      );
+    }
+  }
+  if (mode !== "interactive" && mode !== "non-interactive") {
+    issues.push("gameplayAudit.mode \u5FC5\u987B\u662F interactive \u6216 non-interactive\u3002");
+  }
   if (scenes.length === 0) issues.push("gameplayAudit.scenes \u4E0D\u80FD\u4E3A\u7A7A\u3002");
   if (scenes.length !== options2.scenes.length) {
     issues.push("gameplayAudit.scenes \u4E0D\u80FD\u5305\u542B\u7A7A\u503C\u6216\u91CD\u590D Scene key\u3002");
   }
   const contractIds = /* @__PURE__ */ new Set();
   const coveredScenes = /* @__PURE__ */ new Set();
+  const kinds = /* @__PURE__ */ new Map();
+  const invalidKindContracts = [];
   for (const contract of options2.contracts) {
     const id = contract.id.trim();
     if (!id) {
@@ -67,6 +84,27 @@ function validateGameplayAuditOptions(options2) {
       );
     }
     const contractScenes = normalizeSet(contract.scenes);
+    if (!["boot", "playthrough", "transition", "recovery"].includes(contract.kind)) {
+      invalidKindContracts.push(id || "<empty>");
+    } else {
+      const list = kinds.get(contract.kind) ?? [];
+      list.push(contract);
+      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`);
+    }
+    if (contract.kind === "transition" && normalizeList(contract.requireTransition).length === 0) {
+      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`);
+    }
     if (contractScenes.length === 0) {
       issues.push(`contract "${id || "<empty>"}" \u5FC5\u987B\u58F0\u660E\u81F3\u5C11\u4E00\u4E2A Scene\u3002`);
     }
@@ -79,6 +117,11 @@ function validateGameplayAuditOptions(options2) {
       }
     }
   }
+  if (invalidKindContracts.length > 0) {
+    issues.push(
+      `\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`);
@@ -86,11 +129,71 @@ function validateGameplayAuditOptions(options2) {
   }
   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) {
+      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)
+      );
+      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) {
+      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");
+    } else if (restartSignal && (kinds.get("recovery") ?? []).length === 0) {
+      issues.push("\u68C0\u6D4B\u5230\u751F\u4EA7 Scene \u4F7F\u7528 scene.restart()\uFF0C\u4F46\u7F3A\u5C11 kind: recovery contract\u3002");
+    } else if ((options2.flows?.restart || options2.flows?.reset) && (kinds.get("recovery") ?? []).length === 0) {
+      issues.push("\u9879\u76EE\u58F0\u660E\u6216\u5B9E\u73B0\u4E86 restart/reset \u6D41\u7A0B\uFF0C\u4F46\u7F3A\u5C11 kind: recovery contract\u3002");
+    }
+  }
   return issues;
 }
+function containsProductionRestart(projectRoot) {
+  const sceneRoot = join(projectRoot, "src", "scenes");
+  const visit = (directory) => {
+    let entries;
+    try {
+      entries = readdirSync(directory);
+    } catch {
+      return false;
+    }
+    for (const entry of entries) {
+      const path = join(directory, entry);
+      let stats;
+      try {
+        stats = statSync(path);
+      } catch {
+        continue;
+      }
+      if (stats.isDirectory() && visit(path)) return true;
+      if (!stats.isFile() || !/\.(ts|tsx)$/.test(entry)) continue;
+      try {
+        const source = readFileSync(path, "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+        if (/\bscene\s*\.\s*restart\s*\(/.test(source)) return true;
+      } catch {
+      }
+    }
+    return false;
+  };
+  return visit(sceneRoot);
+}
 function getDefinitionIssues(expected, actual) {
   const issues = [];
   const expectedMetadata = createGameplayContractMetadata(expected);
+  if (expectedMetadata.kind !== actual.kind) {
+    issues.push(`contract "${expected.id}" \u7684 kind \u4E0E gameplayAudit \u6E05\u5355\u4E0D\u4E00\u81F4\u3002`);
+  }
   if (!sameSet(expectedMetadata.scenes, actual.scenes)) {
     issues.push(
       `contract "${expected.id}" \u58F0\u660E\u7684 Scene \u4E0E gameplayAudit \u6E05\u5355\u4E0D\u4E00\u81F4\u3002`
@@ -145,12 +248,15 @@ function auditGameplayCollection(options2, file, tests) {
 function getGameplayEvidenceIssues(id, requirements, evidence) {
   const issues = [];
   const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
-  if (requirements.requireInput && inputEvents === 0)
+  if (requirements.requireInput && inputEvents === 0) {
     issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
-  if (requirements.requireFrameAdvance && evidence.frames === 0)
+  }
+  if (requirements.requireFrameAdvance && evidence.frames === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
-  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0)
+  }
+  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
     issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  }
   for (const target of normalizeList(requirements.requireTransition)) {
     if (!evidence.transitions.some((transition) => transition.to === target)) {
       issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u5230 ${target} \u7684 Scene \u8F6C\u573A\u3002`);
@@ -161,21 +267,24 @@ function getGameplayEvidenceIssues(id, requirements, evidence) {
       issues.push(`contract "${id}" \u672A\u8BBF\u95EE Scene "${scene}"\u3002`);
   }
   for (const scene of normalizeList(requirements.requireRestart)) {
-    if (!evidence.restartedScenes.includes(scene))
+    if (!evidence.restartedScenes.includes(scene)) {
       issues.push(`contract "${id}" \u672A\u91CD\u542F Scene "${scene}"\u3002`);
+    }
   }
   for (const checkpoint of normalizeList(requirements.requireCheckpoint)) {
-    if (!evidence.checkpoints.includes(checkpoint))
+    if (!evidence.checkpoints.includes(checkpoint)) {
       issues.push(`contract "${id}" \u7F3A\u5C11 checkpoint "${checkpoint}"\u3002`);
+    }
   }
-  if (requirements.requireDestroy && !evidence.destroyed)
+  if (requirements.requireDestroy && !evidence.destroyed) {
     issues.push(`contract "${id}" \u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1\u3002`);
+  }
   return issues;
 }
 function auditGameplayRun(options2, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
-  const acceptedEvidence = [];
+  const observedEvidence = [];
   for (const expected of options2.contracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
@@ -191,6 +300,7 @@ function auditGameplayRun(options2, tests) {
     const test = matches[0];
     const metadata = test?.metadata;
     if (!test || !metadata) continue;
+    if (metadata.evidence) observedEvidence.push(metadata.evidence);
     if (test.file.replaceAll("\\", "/") !== expected.testFile.replaceAll("\\", "/")) {
       issues.push(
         `contract "${expected.id}" \u5FC5\u987B\u4F4D\u4E8E ${expected.testFile}\uFF0C\u5B9E\u9645\u4F4D\u4E8E ${test.file}\u3002`
@@ -211,7 +321,6 @@ function auditGameplayRun(options2, tests) {
       metadata.evidence
     );
     issues.push(...evidenceIssues);
-    if (evidenceIssues.length === 0) acceptedEvidence.push(metadata.evidence);
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
@@ -222,14 +331,15 @@ function auditGameplayRun(options2, tests) {
     }
   }
   const registeredScenes = normalizeSet(
-    acceptedEvidence.flatMap((evidence) => evidence.registeredScenes)
+    observedEvidence.flatMap((evidence) => evidence.registeredScenes)
   );
   const expectedScenes = normalizeSet(options2.scenes);
   for (const scene of expectedScenes) {
-    if (!registeredScenes.includes(scene))
+    if (!registeredScenes.includes(scene)) {
       issues.push(
-        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u4EFB\u4F55\u901A\u8FC7\u5BA1\u8BA1\u7684 host registry \u4E2D\u3002`
+        `\u751F\u4EA7 Scene "${scene}" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002`
       );
+    }
   }
   for (const scene of registeredScenes) {
     if (!expectedScenes.includes(scene))
@@ -240,12 +350,89 @@ function auditGameplayRun(options2, tests) {
   return { passed: issues.length === 0, issues: [...new Set(issues)] };
 }
 
+// src/gameplay-audit-reporter.ts
+import { relative } from "path";
+function formatGameplayIssues(issues) {
+  const groups = /* @__PURE__ */ new Map();
+  const repairKeys = /* @__PURE__ */ new Set();
+  const repairs = [];
+  const repairText = {
+    input: "\u8F93\u5165\uFF1A\u5148\u63A8\u8FDB\u4E00\u5E27\uFF0C\u518D\u901A\u8FC7 host.input.mouse\u3001host.input.keyboard \u6216 host.input.touch \u9A71\u52A8\u771F\u5B9E\u751F\u4EA7\u8F93\u5165\u3002",
+    frames: "\u5E27\u63A8\u8FDB\uFF1A\u5728\u8F93\u5165\u6216\u751F\u4EA7\u547D\u4EE4\u540E\u8C03\u7528 host.stepFrames()\uFF0C\u5F02\u6B65 update \u4F7F\u7528 host.stepFramesAsync()\u3002",
+    physics: "\u7269\u7406\uFF1A\u4EC5\u5728\u751F\u4EA7\u4F7F\u7528 Arcade Physics \u65F6\u8C03\u7528 host.stepPhysics()\uFF1B\u5176\u4ED6\u7269\u7406\u7CFB\u7EDF\u4F7F\u7528\u5B8C\u6574\u5E27\u3002",
+    transition: "\u8F6C\u573A\uFF1Aboot \u524D\u6CE8\u518C\u76EE\u6807 Scene\uFF0C\u8C03\u7528\u751F\u4EA7\u8F6C\u573A\u547D\u4EE4\uFF0C\u518D\u7528 host.stepUntil() \u7B49\u5F85\u76EE\u6807\u6FC0\u6D3B\u5E76\u65AD\u8A00\u6E90/\u76EE\u6807\u72B6\u6001\u3002",
+    visit: "Scene\uFF1A\u786E\u8BA4\u6D4B\u8BD5\u901A\u8FC7\u771F\u5B9E\u5165\u53E3\u6216\u5408\u6CD5\u8F6C\u573A\u8BBF\u95EE\u8BE5 Scene\uFF0C\u5E76\u4F7F\u7528\u771F\u5B9E\u914D\u7F6E\u542F\u52A8\u3002",
+    restart: "\u6062\u590D\uFF1A\u901A\u8FC7\u771F\u5B9E\u8F93\u5165\u6216\u751F\u4EA7 controls \u89E6\u53D1 restart\uFF0C\u7B49\u5F85\u5B8C\u6574\u5E27\u5E76\u65AD\u8A00\u72B6\u6001\u5DF2\u6062\u590D\u3002",
+    checkpoint: "\u68C0\u67E5\u70B9\uFF1A\u5148\u65AD\u8A00 authoritative state\uFF0C\u518D\u8C03\u7528 host.checkpoint()\uFF1B\u4E0D\u8981\u8C03\u7528 contract.checkpoint()\u3002",
+    destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
+    registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4 Scene \u5728\u751F\u4EA7 registry \u4E2D\uFF0C\u5E76\u5728 boot \u524D\u901A\u8FC7 additionalScenes \u6CE8\u518C\u8F6C\u573A\u76EE\u6807\u3002",
+    missing: "\u6D4B\u8BD5\u7F3A\u5931\uFF1A\u5728\u6307\u5B9A\u6587\u4EF6\u4F7F\u7528 gameplayTest \u5B9A\u4E49\u68C0\u67E5\u9879\uFF0C\u5E76\u901A\u8FC7 contract.attachHost(host) \u7ED1\u5B9A host\u3002",
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF1B\u68C0\u67E5\u9879\u53EA\u6C47\u603B\u7ED3\u679C\uFF0C\u4E0D\u662F\u8FD0\u884C\u65F6\u5BF9\u8C61\u3002"
+  };
+  const getCategory = (issue) => {
+    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
+    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
+    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics")) return { category: "physics", key: "physics" };
+    if (issue.includes("\u672A\u8BB0\u5F55\u5230 ") && issue.includes("Scene \u8F6C\u573A")) {
+      const target = issue.match(/未记录到 (.+?) 的 Scene 转场/)?.[1] ?? "unknown";
+      return { category: "transition", key: `transition:${target}` };
+    }
+    if (issue.includes("\u672A\u8BBF\u95EE Scene")) {
+      const scene = issue.match(/未访问 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "visit", key: `visit:${scene}` };
+    }
+    if (issue.includes("\u672A\u91CD\u542F Scene")) {
+      const scene = issue.match(/未重启 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "restart", key: `restart:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 checkpoint")) return { category: "checkpoint", key: `checkpoint:${issue.match(/checkpoint "([^"]+)"/)?.[1] ?? issue}` };
+    if (issue.includes("\u672A\u5B8C\u6210 HEADLESS host \u9500\u6BC1")) return { category: "destroy", key: "destroy" };
+    if (issue.includes("\u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry")) {
+      const scene = issue.match(/生产 Scene "([^"]+)"/)?.[1] ?? "unknown";
+      return { category: "registry", key: `registry:${scene}` };
+    }
+    if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
+    return { category: "other", key: `other:${issue}` };
+  };
+  for (const rawIssue of [...new Set(issues)]) {
+    const compact = rawIssue.replaceAll(/\s+/g, " ").trim();
+    const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u68C0\u67E5\u9879 "$1"').replaceAll("evidence requirements", "\u6240\u9700\u8FD0\u884C\u8BC1\u636E").replaceAll("metadata", "\u6D4B\u8BD5\u58F0\u660E").replaceAll("host registry", "\u5DF2\u6CE8\u518C Scene \u6E05\u5355");
+    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const { category, key } = getCategory(compact);
+    const group = groups.get(key);
+    if (group) {
+      if (id && !group.ids.includes(id)) group.ids.push(id);
+    } else {
+      groups.set(key, { text: readable, ids: id ? [id] : [], key });
+    }
+    if (repairText[category] && !repairKeys.has(category)) {
+      repairKeys.add(category);
+      repairs.push(repairText[category]);
+    }
+  }
+  const grouped = [...groups.values()];
+  const visible = grouped.slice(0, 8).map((group) => {
+    if (group.ids.length <= 1) return group.text;
+    return `${group.text}\uFF08\u53D7\u5F71\u54CD\u68C0\u67E5\u9879\uFF1A${group.ids.join("\u3001")}\uFF09`;
+  });
+  return {
+    issues: visible.map(
+      (issue) => issue.length > 360 ? `${issue.slice(0, 357)}...` : issue
+    ),
+    repairs: repairs.slice(0, 8),
+    omitted: Math.max(0, grouped.length - visible.length)
+  };
+}
+
 // src/lint/gameplay-audit.test.ts
 var options = {
+  mode: "interactive",
   scenes: ["IndexScene", "BattleScene"],
   contracts: [
     {
       id: "gameplay.main-flow",
+      kind: "playthrough",
       testFile: "tests/gameplay.test.ts",
       scenes: ["IndexScene", "BattleScene"],
       requireInput: true,
@@ -284,6 +471,123 @@ function createPassingTest() {
   };
 }
 describe("gameplay audit", () => {
+  it("\u62D2\u7EDD\u4EA4\u4E92\u9879\u76EE\u53EA\u6709 boot contract", () => {
+    const result = validateGameplayAuditOptions({
+      mode: "interactive",
+      scenes: ["IndexScene"],
+      contracts: [
+        {
+          id: "IndexScene.boot",
+          kind: "boot",
+          testFile: "tests/gameplay.test.ts",
+          scenes: ["IndexScene"]
+        }
+      ]
+    });
+    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'
+    );
+  });
+  it("\u5141\u8BB8\u5E26\u7406\u7531\u7684\u975E\u4EA4\u4E92 boot-only \u9879\u76EE", () => {
+    expect(
+      validateGameplayAuditOptions({
+        mode: "non-interactive",
+        nonInteractiveJustification: "\u8FD9\u662F\u53EA\u5C55\u793A\u9759\u6001\u6B22\u8FCE\u753B\u9762\u7684\u6A21\u677F\u5939\u5177\uFF0C\u4E0D\u5305\u542B\u73A9\u5BB6\u8F93\u5165\u3002",
+        scenes: ["IndexScene"],
+        contracts: [
+          {
+            id: "IndexScene.boot",
+            kind: "boot",
+            testFile: "tests/gameplay.test.ts",
+            scenes: ["IndexScene"]
+          }
+        ]
+      })
+    ).toEqual([]);
+  });
+  it("\u5F3A\u5236 recovery contract \u540C\u65F6\u58F0\u660E restart \u548C\u4E24\u4E2A checkpoint", () => {
+    const result = validateGameplayAuditOptions({
+      mode: "non-interactive",
+      nonInteractiveJustification: "\u6D4B\u8BD5 recovery contract \u7684\u914D\u7F6E\u6821\u9A8C\uFF0C\u4E0D\u4EE3\u8868\u771F\u5B9E\u4EA7\u54C1\u8C41\u514D\u3002",
+      scenes: ["BattleScene"],
+      contracts: [{
+        id: "BattleScene.recovery",
+        kind: "recovery",
+        testFile: "tests/gameplay.test.ts",
+        scenes: ["BattleScene"],
+        requireInput: true,
+        requireFrameAdvance: true
+      }]
+    });
+    expect(result).toEqual(expect.arrayContaining([
+      'recovery contract "BattleScene.recovery" \u5FC5\u987B\u58F0\u660E requireRestart\u3002',
+      '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", () => {
+    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"
+      }]
+    });
+    expect(result).toContain('\u975E\u5165\u53E3 Scene "BattleScene" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002');
+  });
+  it("\u4E0D\u63A5\u53D7 boot contract \u4F2A\u88C5\u6210\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"
+        },
+        {
+          id: "BattleScene.boot",
+          kind: "boot",
+          testFile: "tests/gameplay.test.ts",
+          scenes: ["BattleScene"],
+          requireTransition: "BattleScene"
+        }
+      ]
+    });
+    expect(result).toContain(
+      '\u975E\u5165\u53E3 Scene "BattleScene" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002'
+    );
+  });
+  it("\u58F0\u660E restart flow \u540E\u4ECD\u5F3A\u5236 recovery contract", () => {
+    const result = validateGameplayAuditOptions({
+      mode: "interactive",
+      flows: { restart: true },
+      scenes: ["IndexScene"],
+      contracts: [
+        {
+          id: "IndexScene.playthrough",
+          kind: "playthrough",
+          testFile: "tests/gameplay.test.ts",
+          scenes: ["IndexScene"],
+          requireInput: true,
+          requireFrameAdvance: true,
+          requireCheckpoint: "progress"
+        }
+      ]
+    });
+    expect(result).toContain(
+      "\u9879\u76EE\u58F0\u660E\u6216\u5B9E\u73B0\u4E86 restart/reset \u6D41\u7A0B\uFF0C\u4F46\u7F3A\u5C11 kind: recovery contract\u3002"
+    );
+  });
   it("\u62D2\u7EDD\u672A\u88AB contract \u8986\u76D6\u7684\u751F\u4EA7 Scene", () => {
     expect(
       validateGameplayAuditOptions({
@@ -299,6 +603,7 @@ describe("gameplay audit", () => {
         contracts: [
           {
             id: " IndexScene.boot ",
+            kind: "boot",
             testFile: "tests/gameplay.test.ts",
             scenes: ["IndexScene"]
           }
@@ -312,6 +617,7 @@ describe("gameplay audit", () => {
       contracts: [
         {
           id: "IndexScene.boot",
+          kind: "boot",
           testFile,
           scenes: ["IndexScene"]
         }
@@ -378,6 +684,7 @@ describe("gameplay audit", () => {
     evidence.destroyed = false;
     evidence.registeredScenes.push("DebugScene");
     const test = createPassingTest();
+    if (!test.metadata) throw new Error("expected gameplay metadata");
     test.metadata.evidence = evidence;
     const result = auditGameplayRun(options, [test]);
     expect(result.passed).toBe(false);
@@ -389,8 +696,24 @@ describe("gameplay audit", () => {
       ])
     );
   });
+  it("\u4FDD\u7559\u5931\u8D25 host \u5DF2\u6CE8\u518C\u7684 Scene\uFF0C\u907F\u514D checkpoint \u7F3A\u53E3\u7EA7\u8054\u6210\u6CE8\u518C\u9519\u8BEF", () => {
+    const test = createPassingTest();
+    if (!test.metadata?.evidence) throw new Error("expected gameplay evidence");
+    test.metadata.evidence.checkpoints = ["progress"];
+    const result = auditGameplayRun(options, [test]);
+    expect(result.issues).toContain(
+      'contract "gameplay.main-flow" \u7F3A\u5C11 checkpoint "recovery"\u3002'
+    );
+    expect(result.issues).not.toContain(
+      '\u751F\u4EA7 Scene "IndexScene" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002'
+    );
+    expect(result.issues).not.toContain(
+      '\u751F\u4EA7 Scene "BattleScene" \u672A\u51FA\u73B0\u5728\u6D4B\u8BD5\u5B9E\u9645\u8BB0\u5F55\u7684 host registry \u4E2D\u3002'
+    );
+  });
   it("\u62D2\u7EDD\u901A\u8FC7\u5951\u7EA6\u7684 host registry \u4E2D\u51FA\u73B0\u6E05\u5355\u5916 Scene", () => {
     const test = createPassingTest();
+    if (!test.metadata?.evidence) throw new Error("expected gameplay evidence");
     test.metadata.evidence.registeredScenes.push("DebugScene");
     expect(auditGameplayRun(options, [test]).issues).toContain(
       'host registry \u51FA\u73B0\u672A\u5217\u5165 gameplayAudit.scenes \u7684\u751F\u4EA7 Scene "DebugScene"\u3002'
@@ -423,4 +746,28 @@ describe("gameplay audit", () => {
       )
     ).toContain('contract "arcade-physics" \u672A\u63A8\u8FDB Arcade Physics\u3002');
   });
+  it("\u5408\u5E76\u76F8\u540C\u4FEE\u590D\u7C7B\u578B\u4F46\u4FDD\u7559\u4E0D\u540C Scene \u8F6C\u573A\u76EE\u6807", () => {
+    const result = formatGameplayIssues([
+      'contract "Menu.start" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002',
+      'contract "Battle.start" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002',
+      'contract "Menu.to-battle" \u672A\u8BB0\u5F55\u5230 BattleScene \u7684 Scene \u8F6C\u573A\u3002',
+      'contract "Battle.to-result" \u672A\u8BB0\u5F55\u5230 ResultScene \u7684 Scene \u8F6C\u573A\u3002',
+      'contract "Menu.visit-result" \u672A\u8BBF\u95EE Scene "ResultScene"\u3002',
+      'contract "Battle.visit-result" \u672A\u8BBF\u95EE Scene "ResultScene"\u3002'
+    ]);
+    expect(result.issues).toHaveLength(4);
+    expect(result.repairs).toHaveLength(3);
+    expect(result.repairs[0]).toContain("\u8F93\u5165");
+    expect(result.repairs[1]).toContain("\u8F6C\u573A");
+  });
+  it("\u5C06\u591A\u68C0\u67E5\u9879\u7684\u7F3A\u53E3\u9650\u5236\u4E3A\u95EE\u9898\u7EC4\u800C\u4E0D\u662F\u539F\u59CB\u65E5\u5FD7\u884C", () => {
+    const issues = Array.from(
+      { length: 20 },
+      (_, index) => `contract "Scene${index}.boot" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`
+    );
+    const result = formatGameplayIssues(issues);
+    expect(result.issues).toHaveLength(1);
+    expect(result.repairs).toHaveLength(1);
+    expect(result.omitted).toBe(0);
+  });
 });

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

@@ -1051,6 +1051,8 @@ async function createHeadlessGame(scene, options = {}) {
 import { test } from "vitest";
 
 // src/gameplay-audit.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -1081,6 +1083,7 @@ function createGameplayContractMetadata(contract) {
   const scenes = normalizeSet(contract.scenes);
   return {
     id: contract.id.trim(),
+    kind: contract.kind,
     scenes,
     requirements: normalizeGameplayRequirements(contract, scenes),
     verified: false
@@ -1185,6 +1188,7 @@ describe("gameplay contract lifecycle integration", () => {
     const { callbacks, context } = createTestContext();
     const contract = registerGameplayContract(context, {
       id: "InputScene.hit",
+      kind: "playthrough",
       requireInput: true,
       requireFrameAdvance: true
     });
@@ -1213,6 +1217,7 @@ describe("gameplay contract lifecycle integration", () => {
     const { callbacks, context } = createTestContext();
     const contract = registerGameplayContract(context, {
       id: "InputScene.missing-input",
+      kind: "playthrough",
       requireInput: true
     });
     const host = await createHeadlessGame(new InputScene());