miaoda-game-devkit 0.2.1 → 0.2.3

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

@@ -162,6 +162,8 @@ declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene,
 
 /** 一个必须由指定测试文件证明的玩法契约。 */
 interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；boot 不得替代交互游戏的 playthrough。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 在整个游戏项目中唯一且稳定的契约标识。 */
     id: string;
     /** 相对于游戏项目根目录的 Vitest 测试文件。 */
@@ -171,6 +173,15 @@ interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
 }
 /** 游戏项目在一次 Vitest 运行中必须完成的玩法审计清单。 */
 interface GameplayAuditOptions {
+    /** 默认按交互游戏审计；纯演示项目必须显式豁免并说明原因。 */
+    mode?: "interactive" | "non-interactive";
+    /** non-interactive 模式的可审计豁免理由。 */
+    nonInteractiveJustification?: string;
+    /** 应用声明的可恢复流程；restart 会触发 recovery contract 基线。 */
+    flows?: {
+        restart?: boolean;
+        reset?: boolean;
+    };
     /** 生产 Scene registry 中预期出现的全部 Scene key。 */
     scenes: string[];
     /** 必须定义、执行并满足证据要求的玩法契约。 */
@@ -178,6 +189,8 @@ interface GameplayAuditOptions {
 }
 /** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
 interface GameplayContractMetadata {
+    /** 契约用途。 */
+    kind: GameplayAuditContract["kind"];
     /** 契约唯一标识。 */
     id: string;
     /** 契约负责证明的生产 Scene key。 */

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

@@ -162,6 +162,8 @@ declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene,
 
 /** 一个必须由指定测试文件证明的玩法契约。 */
 interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；boot 不得替代交互游戏的 playthrough。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 在整个游戏项目中唯一且稳定的契约标识。 */
     id: string;
     /** 相对于游戏项目根目录的 Vitest 测试文件。 */
@@ -171,6 +173,15 @@ interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
 }
 /** 游戏项目在一次 Vitest 运行中必须完成的玩法审计清单。 */
 interface GameplayAuditOptions {
+    /** 默认按交互游戏审计；纯演示项目必须显式豁免并说明原因。 */
+    mode?: "interactive" | "non-interactive";
+    /** non-interactive 模式的可审计豁免理由。 */
+    nonInteractiveJustification?: string;
+    /** 应用声明的可恢复流程；restart 会触发 recovery contract 基线。 */
+    flows?: {
+        restart?: boolean;
+        reset?: boolean;
+    };
     /** 生产 Scene registry 中预期出现的全部 Scene key。 */
     scenes: string[];
     /** 必须定义、执行并满足证据要求的玩法契约。 */
@@ -178,6 +189,8 @@ interface GameplayAuditOptions {
 }
 /** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
 interface GameplayContractMetadata {
+    /** 契约用途。 */
+    kind: GameplayAuditContract["kind"];
     /** 契约唯一标识。 */
     id: string;
     /** 契约负责证明的生产 Scene key。 */

package/dist/index.d.mts

@@ -1,10 +1,12 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CYqLL8gY.mjs';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CYqLL8gY.mjs';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.mjs';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
 /** 将单个 Vitest 测试绑定到玩法 Ledger 的契约选项。 */
 interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；交互项目不能只使用 boot。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 生产玩法清单中稳定且唯一的 contract 标识。 */
     id: string;
     /** 当前契约负责证明的生产 Scene key。 */

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CYqLL8gY.js';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CYqLL8gY.js';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.js';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-XBGq_jIV.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
 /** 将单个 Vitest 测试绑定到玩法 Ledger 的契约选项。 */
 interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
+    /** 契约用途；交互项目不能只使用 boot。 */
+    kind: "boot" | "playthrough" | "transition" | "recovery";
     /** 生产玩法清单中稳定且唯一的 contract 标识。 */
     id: string;
     /** 当前契约负责证明的生产 Scene key。 */

package/dist/index.js

@@ -1089,6 +1089,8 @@ async function createHeadlessGame(scene, options = {}) {
 var import_vitest = require("vitest");
 
 // src/gameplay-audit.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -1119,6 +1121,7 @@ function createGameplayContractMetadata(contract) {
   const scenes = normalizeSet(contract.scenes);
   return {
     id: contract.id.trim(),
+    kind: contract.kind,
     scenes,
     requirements: normalizeGameplayRequirements(contract, scenes),
     verified: false

package/dist/index.mjs

@@ -1047,6 +1047,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;
@@ -1077,6 +1079,7 @@ function createGameplayContractMetadata(contract) {
   const scenes = normalizeSet(contract.scenes);
   return {
     id: contract.id.trim(),
+    kind: contract.kind,
     scenes,
     requirements: normalizeGameplayRequirements(contract, scenes),
     verified: false

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`
@@ -242,10 +345,12 @@ function auditGameplayRun(options2, tests) {
 
 // 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 +389,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 +521,7 @@ describe("gameplay audit", () => {
         contracts: [
           {
             id: " IndexScene.boot ",
+            kind: "boot",
             testFile: "tests/gameplay.test.ts",
             scenes: ["IndexScene"]
           }
@@ -312,6 +535,7 @@ describe("gameplay audit", () => {
       contracts: [
         {
           id: "IndexScene.boot",
+          kind: "boot",
           testFile,
           scenes: ["IndexScene"]
         }

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

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

@@ -3,11 +3,12 @@ import { resolve as resolve2 } from "path";
 import { describe, expect, it } from "vitest";
 
 // src/vitest-config.ts
-import { createRequire } from "module";
-import { dirname, resolve } from "path";
+import { resolve } from "path";
 import { defineConfig } from "vitest/config";
 
 // 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;
@@ -41,20 +42,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(options) {
+function validateGameplayAuditOptions(options, projectRoot2) {
   const issues = [];
-  const scenes = normalizeSet(options.scenes);
+  const scenes = [...new Set(options.scenes.map((scene) => scene.trim()).filter(Boolean))];
+  const mode = options.mode ?? "interactive";
+  if (mode === "non-interactive") {
+    const justification = options.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 !== options.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 options.contracts) {
     const id = contract.id.trim();
     if (!id) {
@@ -73,6 +89,27 @@ function validateGameplayAuditOptions(options) {
       );
     }
     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`);
     }
@@ -85,6 +122,11 @@ function validateGameplayAuditOptions(options) {
       }
     }
   }
+  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`);
@@ -92,11 +134,71 @@ function validateGameplayAuditOptions(options) {
   }
   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) {
+      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)
+      );
+      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");
+    } 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 ((options.flows?.restart || options.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(projectRoot2) {
+  const sceneRoot = join(projectRoot2, "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`
@@ -331,28 +433,25 @@ GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts
 
 // src/vitest-config.ts
 function defineGameVitestConfig(options) {
-  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit);
+  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
   if (auditIssues.length > 0) {
     throw new Error(
       `\u65E0\u6548\u7684 gameplayAudit \u914D\u7F6E\uFF1A
 - ${auditIssues.join("\n- ")}`
     );
   }
-  const projectRequire = createRequire(
-    resolve(options.projectRoot, "package.json")
-  );
-  const phaserPackageRoot = dirname(
-    projectRequire.resolve("phaser/package.json")
-  );
-  const phaserBrowserBuild = resolve(phaserPackageRoot, "dist/phaser.js");
   return defineConfig({
     resolve: {
       alias: {
         ...options.aliases,
-        "@": resolve(options.projectRoot, "src"),
-        phaser: phaserBrowserBuild
+        "@": resolve(options.projectRoot, "src")
       }
     },
+    // devkit 作为 external ESM 加载时，应用测试也必须 externalize Phaser，
+    // 否则 Vite alias 与 Node 条件导出会创建两个 Phaser 单例，Scene 无法启动。
+    ssr: {
+      external: ["phaser"]
+    },
     test: {
       include: ["tests/**/*.test.ts"],
       testTimeout: options.testTimeout,
@@ -362,7 +461,8 @@ function defineGameVitestConfig(options) {
           // devkit 模块需要在配置和审计阶段使用 Node 内置模块。
           // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
           // 最终触发 "No such built-in module: node:"。
-          external: [/miaoda-game-devkit/]
+          external: [/miaoda-game-devkit/],
+          inline: options.inlineDependencies
         }
       },
       environment: "jsdom",
@@ -403,10 +503,13 @@ function defineGameVitestConfig(options) {
 // src/lint/vitest-config.test.ts
 var projectRoot = resolve2(import.meta.dirname, "../..");
 var gameplayAudit = {
+  mode: "non-interactive",
+  nonInteractiveJustification: "\u56FA\u5B9A\u5939\u5177\u53EA\u9A8C\u8BC1\u5171\u4EAB host \u57FA\u7EBF\uFF0C\u4E0D\u5305\u542B\u73A9\u6CD5\u8F93\u5165\u3002",
   scenes: ["InputScene"],
   contracts: [
     {
       id: "InputScene.boot",
+      kind: "boot",
       testFile: "tests/input.test.ts",
       scenes: ["InputScene"],
       requireFrameAdvance: true
@@ -417,14 +520,16 @@ describe("defineGameVitestConfig", () => {
   it("\u63D0\u4F9B Phaser \u8FD0\u884C\u65F6\u6D4B\u8BD5\u9700\u8981\u7684\u56FA\u5B9A\u57FA\u7EBF", () => {
     const config = defineGameVitestConfig({ projectRoot, gameplayAudit });
     expect(config.resolve?.alias).toMatchObject({
-      "@": resolve2(projectRoot, "src"),
-      phaser: expect.stringContaining("phaser/dist/phaser.js")
+      "@": resolve2(projectRoot, "src")
     });
+    expect(config.resolve?.alias).not.toHaveProperty("phaser");
+    expect(config.ssr).toMatchObject({ external: ["phaser"] });
     expect(config.test).toMatchObject({
       include: ["tests/**/*.test.ts"],
       server: {
         deps: {
-          external: [/miaoda-game-devkit/]
+          external: [/miaoda-game-devkit/],
+          inline: void 0
         }
       },
       environment: "jsdom",
@@ -454,6 +559,7 @@ describe("defineGameVitestConfig", () => {
     const config = defineGameVitestConfig({
       projectRoot,
       gameplayAudit,
+      inlineDependencies: [/phaser4-rex-plugins/],
       additionalSetupFiles: ["tests/custom-setup.ts"],
       testTimeout: 5e3,
       hookTimeout: 2e3
@@ -476,4 +582,16 @@ describe("defineGameVitestConfig", () => {
       })
     ).toThrow(/ResultScene.*没有任何 gameplay contract/s);
   });
+  it("\u62D2\u7EDD\u4EA4\u4E92\u9879\u76EE\u53EA\u6709 boot smoke test", () => {
+    expect(
+      () => defineGameVitestConfig({
+        projectRoot,
+        gameplayAudit: {
+          mode: "interactive",
+          scenes: ["InputScene"],
+          contracts: gameplayAudit.contracts
+        }
+      })
+    ).toThrow(/缺少最低玩法基线/);
+  });
 });

package/dist/vitest-config.d.mts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-CYqLL8gY.mjs';
+import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.mjs';
 import 'phaser';
 
 interface GameVitestConfigOptions {
@@ -7,10 +7,12 @@ interface GameVitestConfigOptions {
     projectRoot: string;
     /** 测试前后都必须审计的生产 Scene 和玩法契约清单。 */
     gameplayAudit: GameplayAuditOptions;
-    /** 项目需要的额外路径别名；`@` 和 `phaser` 由 devkit 统一维护。 */
+    /** 项目需要的额外路径别名；`@` 由 devkit 统一维护。 */
     aliases?: Record<string, string>;
     /** 在 devkit 基础 setup 之后执行的项目级 setup 文件。 */
     additionalSetupFiles?: string[];
+    /** 需要由 Vite 转换的项目依赖，例如包含无扩展名 import 的插件。 */
+    inlineDependencies?: RegExp[];
     /** 单个游戏运行时测试的超时时间。 */
     testTimeout?: number;
     /** 单个游戏测试钩子的超时时间。 */

package/dist/vitest-config.d.ts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-CYqLL8gY.js';
+import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.js';
 import 'phaser';
 
 interface GameVitestConfigOptions {
@@ -7,10 +7,12 @@ interface GameVitestConfigOptions {
     projectRoot: string;
     /** 测试前后都必须审计的生产 Scene 和玩法契约清单。 */
     gameplayAudit: GameplayAuditOptions;
-    /** 项目需要的额外路径别名；`@` 和 `phaser` 由 devkit 统一维护。 */
+    /** 项目需要的额外路径别名；`@` 由 devkit 统一维护。 */
     aliases?: Record<string, string>;
     /** 在 devkit 基础 setup 之后执行的项目级 setup 文件。 */
     additionalSetupFiles?: string[];
+    /** 需要由 Vite 转换的项目依赖，例如包含无扩展名 import 的插件。 */
+    inlineDependencies?: RegExp[];
     /** 单个游戏运行时测试的超时时间。 */
     testTimeout?: number;
     /** 单个游戏测试钩子的超时时间。 */

package/dist/vitest-config.js

@@ -23,11 +23,12 @@ __export(vitest_config_exports, {
   defineGameVitestConfig: () => defineGameVitestConfig
 });
 module.exports = __toCommonJS(vitest_config_exports);
-var import_node_module = require("module");
-var import_node_path2 = require("path");
+var import_node_path3 = require("path");
 var import_config = require("vitest/config");
 
 // src/gameplay-audit.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -61,20 +62,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(options) {
+function validateGameplayAuditOptions(options, projectRoot) {
   const issues = [];
-  const scenes = normalizeSet(options.scenes);
+  const scenes = [...new Set(options.scenes.map((scene) => scene.trim()).filter(Boolean))];
+  const mode = options.mode ?? "interactive";
+  if (mode === "non-interactive") {
+    const justification = options.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 !== options.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 options.contracts) {
     const id = contract.id.trim();
     if (!id) {
@@ -93,6 +109,27 @@ function validateGameplayAuditOptions(options) {
       );
     }
     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`);
     }
@@ -105,6 +142,11 @@ function validateGameplayAuditOptions(options) {
       }
     }
   }
+  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`);
@@ -112,11 +154,71 @@ function validateGameplayAuditOptions(options) {
   }
   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) {
+      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)
+      );
+      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");
+    } 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 ((options.flows?.restart || options.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 = (0, import_node_path.join)(projectRoot, "src", "scenes");
+  const visit = (directory) => {
+    let entries;
+    try {
+      entries = (0, import_node_fs.readdirSync)(directory);
+    } catch {
+      return false;
+    }
+    for (const entry of entries) {
+      const path = (0, import_node_path.join)(directory, entry);
+      let stats;
+      try {
+        stats = (0, import_node_fs.statSync)(path);
+      } catch {
+        continue;
+      }
+      if (stats.isDirectory() && visit(path)) return true;
+      if (!stats.isFile() || !/\.(ts|tsx)$/.test(entry)) continue;
+      try {
+        const source = (0, import_node_fs.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`
@@ -267,7 +369,7 @@ function auditGameplayRun(options, tests) {
 }
 
 // src/gameplay-audit-reporter.ts
-var import_node_path = require("path");
+var import_node_path2 = require("path");
 function normalizePath(path) {
   return path.replaceAll("\\", "/").replace(/^\.\//, "");
 }
@@ -305,7 +407,7 @@ var GameplayAuditReporter = class {
     this.preflightIssues.clear();
     const scheduledFiles = new Set(
       specifications.map(
-        (specification) => normalizePath((0, import_node_path.relative)(this.projectRoot, specification.moduleId))
+        (specification) => normalizePath((0, import_node_path2.relative)(this.projectRoot, specification.moduleId))
       )
     );
     for (const contract of this.options.contracts) {
@@ -351,28 +453,25 @@ GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts
 
 // src/vitest-config.ts
 function defineGameVitestConfig(options) {
-  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit);
+  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
   if (auditIssues.length > 0) {
     throw new Error(
       `\u65E0\u6548\u7684 gameplayAudit \u914D\u7F6E\uFF1A
 - ${auditIssues.join("\n- ")}`
     );
   }
-  const projectRequire = (0, import_node_module.createRequire)(
-    (0, import_node_path2.resolve)(options.projectRoot, "package.json")
-  );
-  const phaserPackageRoot = (0, import_node_path2.dirname)(
-    projectRequire.resolve("phaser/package.json")
-  );
-  const phaserBrowserBuild = (0, import_node_path2.resolve)(phaserPackageRoot, "dist/phaser.js");
   return (0, import_config.defineConfig)({
     resolve: {
       alias: {
         ...options.aliases,
-        "@": (0, import_node_path2.resolve)(options.projectRoot, "src"),
-        phaser: phaserBrowserBuild
+        "@": (0, import_node_path3.resolve)(options.projectRoot, "src")
       }
     },
+    // devkit 作为 external ESM 加载时，应用测试也必须 externalize Phaser，
+    // 否则 Vite alias 与 Node 条件导出会创建两个 Phaser 单例，Scene 无法启动。
+    ssr: {
+      external: ["phaser"]
+    },
     test: {
       include: ["tests/**/*.test.ts"],
       testTimeout: options.testTimeout,
@@ -382,7 +481,8 @@ function defineGameVitestConfig(options) {
           // devkit 模块需要在配置和审计阶段使用 Node 内置模块。
           // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
           // 最终触发 "No such built-in module: node:"。
-          external: [/miaoda-game-devkit/]
+          external: [/miaoda-game-devkit/],
+          inline: options.inlineDependencies
         }
       },
       environment: "jsdom",

package/dist/vitest-config.mjs

@@ -1,9 +1,10 @@
 // src/vitest-config.ts
-import { createRequire } from "module";
-import { dirname, resolve } from "path";
+import { resolve } from "path";
 import { defineConfig } from "vitest/config";
 
 // 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;
@@ -37,20 +38,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(options) {
+function validateGameplayAuditOptions(options, projectRoot) {
   const issues = [];
-  const scenes = normalizeSet(options.scenes);
+  const scenes = [...new Set(options.scenes.map((scene) => scene.trim()).filter(Boolean))];
+  const mode = options.mode ?? "interactive";
+  if (mode === "non-interactive") {
+    const justification = options.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 !== options.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 options.contracts) {
     const id = contract.id.trim();
     if (!id) {
@@ -69,6 +85,27 @@ function validateGameplayAuditOptions(options) {
       );
     }
     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`);
     }
@@ -81,6 +118,11 @@ function validateGameplayAuditOptions(options) {
       }
     }
   }
+  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`);
@@ -88,11 +130,71 @@ function validateGameplayAuditOptions(options) {
   }
   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) {
+      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)
+      );
+      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");
+    } 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 ((options.flows?.restart || options.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`
@@ -327,28 +429,25 @@ GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts
 
 // src/vitest-config.ts
 function defineGameVitestConfig(options) {
-  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit);
+  const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
   if (auditIssues.length > 0) {
     throw new Error(
       `\u65E0\u6548\u7684 gameplayAudit \u914D\u7F6E\uFF1A
 - ${auditIssues.join("\n- ")}`
     );
   }
-  const projectRequire = createRequire(
-    resolve(options.projectRoot, "package.json")
-  );
-  const phaserPackageRoot = dirname(
-    projectRequire.resolve("phaser/package.json")
-  );
-  const phaserBrowserBuild = resolve(phaserPackageRoot, "dist/phaser.js");
   return defineConfig({
     resolve: {
       alias: {
         ...options.aliases,
-        "@": resolve(options.projectRoot, "src"),
-        phaser: phaserBrowserBuild
+        "@": resolve(options.projectRoot, "src")
       }
     },
+    // devkit 作为 external ESM 加载时，应用测试也必须 externalize Phaser，
+    // 否则 Vite alias 与 Node 条件导出会创建两个 Phaser 单例，Scene 无法启动。
+    ssr: {
+      external: ["phaser"]
+    },
     test: {
       include: ["tests/**/*.test.ts"],
       testTimeout: options.testTimeout,
@@ -358,7 +457,8 @@ function defineGameVitestConfig(options) {
           // devkit 模块需要在配置和审计阶段使用 Node 内置模块。
           // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
           // 最终触发 "No such built-in module: node:"。
-          external: [/miaoda-game-devkit/]
+          external: [/miaoda-game-devkit/],
+          inline: options.inlineDependencies
         }
       },
       environment: "jsdom",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -43,6 +43,18 @@
     "!dist/**/*.map",
     "!dist/lint/**/*.test.*"
   ],
+  "scripts": {
+    "build": "tsup",
+    "prepack": "pnpm run build",
+    "release": "pnpm run test && clean-publish",
+    "release:dry-run": "pnpm run test && clean-publish --dry-run",
+    "release:beta": "pnpm run test && npm version prerelease --preid=beta && clean-publish --tag beta",
+    "release:patch": "pnpm run test && npm version patch && clean-publish",
+    "release:minor": "pnpm run test && npm version minor && clean-publish",
+    "release:major": "pnpm run test && npm version major && clean-publish",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build && ./bin/miaoda-game-lint.js --contracts-only"
+  },
   "nx": {
     "tags": [
       "type:package",
@@ -82,8 +94,23 @@
   "peerDependencies": {
     "phaser": ">=4.0.0 <5"
   },
+  "devDependencies": {
+    "@types/eslint": "^9.6.1",
+    "@types/estree": "^1.0.9",
+    "@types/node": "^24.13.3",
+    "clean-publish": "^6.0.5",
+    "phaser": "4.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "clean-publish": {
+    "fields": [
+      "devDependencies",
+      "scripts"
+    ]
   }
 }