gamekit777 0.1.0

package/studio/src/bus.ts

@@ -0,0 +1,98 @@
+/* studio 的状态总线：node 侧 ↔ 页面 ↔ 预览 iframe。
+ *
+ * 下行 SSE 广播，上行普通 POST。预览控制类的 MCP 工具（演一局、读状态）走这条：
+ * node 发一条带 id 的命令，预览壳执行完 POST 回同一个 id 的结果。
+ * 没有预览页连着时命令直接失败——不能让 AI 等一个永远不会来的回复。 */
+import type { ServerResponse } from 'node:http';
+
+export type BusEvent =
+  | { t: 'hello'; clients: number }
+  | { t: 'log'; level: 'info' | 'warn' | 'error'; msg: string; at: number }
+  | { t: 'job'; id: string; kind: string; status: string; msg: string }
+  | { t: 'fingerprint'; hash: string }
+  | { t: 'preview'; state: unknown }
+  | { t: 'cmd'; id: string; cmd: unknown }
+  | { t: 'cases'; changed: true }
+  | { t: 'build'; artifacts: unknown }
+  | { t: 'publish'; request: unknown };
+
+interface Waiter { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }
+
+export class Bus {
+  #clients = new Set<ServerResponse>();
+  #previews = new Set<ServerResponse>();
+  #waiters = new Map<string, Waiter>();
+  #seq = 0;
+  /** 最近的日志，新连上的页面先补这些 */
+  #recent: BusEvent[] = [];
+  /** 预览壳最近一次上报状态的时刻。SSE 的 close 不可靠：bun 的 fetch 中止不关 TCP，
+      浏览器标签页崩掉时 socket 也可能半死不活。预览壳每秒上报一次，没心跳就是没人 */
+  #lastPreviewBeat = 0;
+  static readonly BEAT_TTL_MS = 4_000;
+
+  /** 一个 SSE 连接。`role=preview` 的是预览壳，命令只发给它们 */
+  attach(res: ServerResponse, role: 'page' | 'preview'): void {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write(': connected\n\n');
+    this.#clients.add(res);
+    if (role === 'preview') { this.#previews.add(res); this.heartbeat(); }
+    for (const e of this.#recent) res.write(`data: ${JSON.stringify(e)}\n\n`);
+    this.emit({ t: 'hello', clients: this.#clients.size });
+    res.on('close', () => {
+      this.#clients.delete(res);
+      this.#previews.delete(res);
+      this.emit({ t: 'hello', clients: this.#clients.size });
+    });
+  }
+
+  /** 预览壳上报状态时打一下 */
+  heartbeat(): void { this.#lastPreviewBeat = Date.now(); }
+
+  get previewConnected(): boolean {
+    return this.#previews.size > 0 && Date.now() - this.#lastPreviewBeat < Bus.BEAT_TTL_MS;
+  }
+  get clients(): number { return this.#clients.size; }
+
+  emit(e: BusEvent): void {
+    if (e.t === 'log' || e.t === 'job') {
+      this.#recent.push(e);
+      if (this.#recent.length > 100) this.#recent.shift();
+    }
+    const line = `data: ${JSON.stringify(e)}\n\n`;
+    for (const c of this.#clients) c.write(line);
+  }
+
+  log(level: 'info' | 'warn' | 'error', msg: string): void {
+    this.emit({ t: 'log', level, msg, at: Date.now() });
+  }
+
+  /** 给预览壳发命令并等结果 */
+  command<T>(cmd: unknown, timeoutMs = 30_000): Promise<T> {
+    if (!this.previewConnected) {
+      return Promise.reject(new Error(this.#previews.size > 0
+        ? '预览页的连接还在，但 4 秒没心跳了——标签页可能卡住或已关闭。刷新预览页再试'
+        : '没有预览页连着。在浏览器里打开 studio 的预览页再试'));
+    }
+    const id = `c${++this.#seq}`;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => { this.#waiters.delete(id); reject(new Error(`预览页 ${timeoutMs / 1000}s 内没回复命令 ${id}`)); }, timeoutMs);
+      this.#waiters.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });
+      const line = `data: ${JSON.stringify({ t: 'cmd', id, cmd })}\n\n`;
+      for (const p of this.#previews) p.write(line);
+    });
+  }
+
+  /** 预览壳 POST 回来的结果 */
+  resolve(id: string, ok: boolean, payload: unknown): boolean {
+    const w = this.#waiters.get(id);
+    if (!w) return false;
+    this.#waiters.delete(id);
+    clearTimeout(w.timer);
+    if (ok) w.resolve(payload);
+    else w.reject(new Error(typeof payload === 'string' ? payload : JSON.stringify(payload)));
+    return true;
+  }
+}

package/studio/src/canon.ts

@@ -0,0 +1,18 @@
+/* 规范化哈希：把任意可序列化的结果变成一个稳定的 16 位指纹。
+ *
+ * case 库用它给 restore() 的 outcome 做指纹——round() 自带 proof.outcomeHash，
+ * 但 restore 路径拿不到那一步，填的是空串。键排序、typed array 展开成普通数组，
+ * 于是同一个结果在任何序列化顺序下都得到同一个哈希。 */
+import { sha256, toHex, utf8 } from 'gamekit777/sdk/hash';
+
+export function canonical(v: unknown): string {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'bigint') return `"${v}n"`;
+  if (typeof v !== 'object') return JSON.stringify(v);
+  if (ArrayBuffer.isView(v)) return canonical(Array.from(v as unknown as ArrayLike<number>));
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  const o = v as Record<string, unknown>;
+  return `{${Object.keys(o).sort().filter((k) => o[k] !== undefined).map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`).join(',')}}`;
+}
+
+export const canonHash = (v: unknown): string => toHex(sha256(utf8(canonical(v)))).slice(0, 16);

package/studio/src/cases.ts

@@ -0,0 +1,255 @@
+/* case 库：<gameDir>/studio/cases.jsonl，一行一个局面。
+ *
+ * 一鱼三吃：作者点一下就在预览里重演（调 UI 和文案）；AI 读它写单测或直接跑；
+ * 以及结果漂移的护栏——每条存着结果哈希，任何变化都是 fail。改规则是有意的就 bless，
+ * 那是显式的接受动作；已发布过的 mode 解码逻辑不能改，要改就换 slug。
+ *
+ * studio 不独占这个文件：Claude Code 直接改它是预期用法，所以用 watcher 盯着，
+ * 追加走 appendFile 一行（把和外部编辑的冲突面降到最小），只有 bless 才读全量改写。 */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, watch, writeFileSync, type FSWatcher } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { RngSeed } from 'gamekit777/sdk';
+import { canonHash } from './canon.ts';
+import type { Config, Game } from './game.ts';
+
+export interface CaseRecord {
+  id: string;
+  title: string;
+  tags: string[];
+  game: string;
+  created: string;
+  origin: 'preview' | 'sample' | 'manual' | 'mcp';
+  config: Config;
+  /** 只作记录：bet 不属于局面，只线性缩放 payout */
+  bet: number;
+  /** 直接跑 round() 的定位 */
+  seed?: RngSeed;
+  /**
+   * 表模型定位。桥：sampleSeed(prefix, mode, simId) 确定性派生，只记这两个就能在两条路上都重建。
+   *
+   * 有 table 时，round() 那条路用的是**采样时的配置**（configOf(mode)），不是 config：
+   * 自由字段（抛硬币的 side）会改变某一局的结果，表里那一行是按 mode 冻结的默认值采出来的，
+   * 用玩家的 config 重跑 round() 得到的是另一局。config 只给 restore 用。
+   */
+  table?: { mode: string; simId: number };
+  expect: {
+    payoutCenti: number;
+    /** canonHash(round().outcome) */
+    outcomeHash?: string;
+    /** canonHash(restore().outcome) */
+    restoreHash?: string;
+    /** 可选，验 codec 往返 */
+    frames?: string;
+  };
+  note?: string;
+}
+
+export type CaseStatus = 'pass' | 'fail' | 'skipped' | 'error';
+
+export interface CaseResult {
+  id: string;
+  title: string;
+  model: 'formula' | 'table';
+  status: CaseStatus;
+  detail: string;
+  /** 实际值，作者要「接受新结果」时用 */
+  actual?: { payoutCenti: number; outcomeHash?: string; restoreHash?: string };
+}
+
+const b64 = (b: Uint8Array | null): string | undefined => (b ? btoa(String.fromCharCode(...b)) : undefined);
+
+export class CaseStore {
+  readonly path: string;
+  #cases: CaseRecord[] = [];
+  #watcher: FSWatcher | null = null;
+  #onChange: () => void;
+
+  constructor(gameDir: string, onChange: () => void = () => {}) {
+    this.path = join(gameDir, 'studio', 'cases.jsonl');
+    this.#onChange = onChange;
+    this.reload();
+    this.#watch();
+  }
+
+  #watch(): void {
+    const dir = dirname(this.path);
+    if (!existsSync(dir)) return;
+    try {
+      this.#watcher = watch(dir, (_ev, name) => {
+        if (name === 'cases.jsonl') { this.reload(); this.#onChange(); }
+      });
+    } catch { /* watcher 起不来就退化成每次手动 reload */ }
+  }
+
+  reload(): void {
+    if (!existsSync(this.path)) { this.#cases = []; return; }
+    const lines = readFileSync(this.path, 'utf8').split('\n').filter((l) => l.trim());
+    const out: CaseRecord[] = [];
+    for (const l of lines) {
+      try { out.push(JSON.parse(l) as CaseRecord); }
+      catch { /* 坏行跳过：作者手改时半行没写完是常态，别让整个库跟着炸 */ }
+    }
+    this.#cases = out;
+  }
+
+  list(): CaseRecord[] { return [...this.#cases]; }
+  get(id: string): CaseRecord | undefined { return this.#cases.find((c) => c.id === id); }
+
+  add(c: Omit<CaseRecord, 'id' | 'created'> & { id?: string }): CaseRecord {
+    const rec: CaseRecord = {
+      ...c,
+      id: c.id ?? `c_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}`,
+      created: new Date().toISOString(),
+    };
+    mkdirSync(dirname(this.path), { recursive: true });
+    const fresh = !existsSync(this.path);
+    appendFileSync(this.path, `${JSON.stringify(rec)}\n`);
+    this.#cases.push(rec);
+    if (fresh) this.#watch();
+    return rec;
+  }
+
+  /** 接受新结果。写 tmp 再 rename，外部编辑器不会读到半个文件 */
+  bless(updates: { id: string; expect: CaseRecord['expect'] }[]): number {
+    let n = 0;
+    for (const u of updates) {
+      const c = this.#cases.find((x) => x.id === u.id);
+      if (!c) continue;
+      c.expect = u.expect; n++;
+    }
+    this.#write();
+    return n;
+  }
+
+  remove(id: string): boolean {
+    const before = this.#cases.length;
+    this.#cases = this.#cases.filter((c) => c.id !== id);
+    if (this.#cases.length === before) return false;
+    this.#write();
+    return true;
+  }
+
+  #write(): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, this.#cases.map((c) => JSON.stringify(c)).join('\n') + (this.#cases.length ? '\n' : ''));
+    renameSync(tmp, this.path);
+  }
+
+  close(): void { this.#watcher?.close(); }
+}
+
+/* ── runner ── */
+
+export interface RunCasesOptions {
+  ids?: string[];
+  model?: 'formula' | 'table' | 'both';
+  /** 每局顺带把 Math.random / crypto 换成会抛的假实现 */
+  purity?: boolean;
+}
+
+const DRIFT = '——结果变了。有意改的规则且这个 mode 没发布过：case_bless 接受；已发布过的 mode 解码逻辑不能改，要改就换 slug';
+
+/** 任何结果变化都是 fail：没有「版本号」可以让它变成 stale，接受要走显式的 bless */
+export async function runCases(game: Game, store: CaseStore, o: RunCasesOptions = {}): Promise<{
+  total: number; pass: number; fail: number; skipped: number; error: number; results: CaseResult[];
+}> {
+  const snap = await game.snapshot();
+  const model = o.model ?? 'both';
+  const purity = o.purity ?? true;
+  const cases = store.list().filter((c) => !o.ids || o.ids.includes(c.id));
+  const results: CaseResult[] = [];
+
+  /** 表模型 case 的 round() 用采样时的配置：表里那一行是按 mode 冻结的默认值采出来的 */
+  const formulaConfig = async (c: CaseRecord): Promise<Config> => {
+    if (!c.table) return c.config;
+    const m = snap.spec.modes.find((x) => x.name === c.table!.mode);
+    return m ? (await game.normalize(m.config)).config : c.config;
+  };
+
+  for (const c of cases) {
+    if ((model === 'formula' || model === 'both') && c.seed) {
+      try {
+        const r = await game.round(await formulaConfig(c), c.bet, c.seed, purity);
+        const actual = { payoutCenti: Math.round(r.multiplier * 100), outcomeHash: canonHash(r.outcome) };
+        const same = actual.payoutCenti === c.expect.payoutCenti
+          && (!c.expect.outcomeHash || actual.outcomeHash === c.expect.outcomeHash);
+        results.push({
+          id: c.id, title: c.title, model: 'formula',
+          status: same ? 'pass' : 'fail',
+          detail: same ? `payout ${actual.payoutCenti} centi，outcomeHash ${actual.outcomeHash}`
+            : `期望 payout ${c.expect.payoutCenti} / hash ${c.expect.outcomeHash ?? '-'}，实际 ${actual.payoutCenti} / ${actual.outcomeHash}${DRIFT}`,
+          actual,
+        });
+      } catch (e) {
+        results.push({ id: c.id, title: c.title, model: 'formula', status: 'error', detail: e instanceof Error ? e.message : String(e) });
+      }
+    }
+
+    if ((model === 'table' || model === 'both') && c.table) {
+      const mi = snap.spec.modes.findIndex((m) => m.name === c.table!.mode);
+      if (mi < 0) {
+        results.push({ id: c.id, title: c.title, model: 'table', status: 'skipped', detail: `清单里没有 mode ${c.table.mode}` });
+        continue;
+      }
+      try {
+        const t = await game.tableRoundtrip(mi, c.table.simId, c.config, c.bet);
+        const restoreHash = canonHash(t.restored.outcome);
+        const actual = { payoutCenti: t.payoutCenti, restoreHash };
+        const payoutOk = t.payoutCenti === c.expect.payoutCenti && t.restored.payout === (c.bet / 100) * t.payoutCenti;
+        const hashOk = !c.expect.restoreHash || restoreHash === c.expect.restoreHash;
+        const framesOk = !c.expect.frames || b64(t.frames) === c.expect.frames;
+        const same = payoutOk && hashOk && framesOk;
+        results.push({
+          id: c.id, title: c.title, model: 'table',
+          status: same ? 'pass' : 'fail',
+          detail: same ? `行 ${c.table.simId}：payout ${t.payoutCenti} centi，restoreHash ${restoreHash}`
+            : `期望 payout ${c.expect.payoutCenti} / restoreHash ${c.expect.restoreHash ?? '-'}，实际 ${t.payoutCenti} / ${restoreHash}${!framesOk ? '，book 字节也变了' : ''}${DRIFT}`,
+          actual,
+        });
+      } catch (e) {
+        results.push({ id: c.id, title: c.title, model: 'table', status: 'error', detail: e instanceof Error ? e.message : String(e) });
+      }
+    }
+  }
+
+  const count = (s: CaseStatus): number => results.filter((r) => r.status === s).length;
+  return { total: results.length, pass: count('pass'), fail: count('fail'), skipped: count('skipped'), error: count('error'), results };
+}
+
+/** 从一局结果造一条 case（预览里「存为 case」、MCP 的 case_add 都走这里） */
+export async function captureCase(game: Game, input: {
+  title: string; tags?: string[]; origin: CaseRecord['origin']; config: Config; bet: number;
+  seed?: RngSeed; table?: { mode: string; simId: number }; note?: string;
+}): Promise<Omit<CaseRecord, 'id' | 'created'>> {
+  const snap = await game.snapshot();
+  const expect: CaseRecord['expect'] = { payoutCenti: 0 };
+  let seed = input.seed;
+  let roundConfig = input.config;
+
+  if (input.table) {
+    const mi = snap.spec.modes.findIndex((m) => m.name === input.table!.mode);
+    if (mi < 0) throw new Error(`清单里没有 mode ${input.table.mode}`);
+    const t = await game.tableRoundtrip(mi, input.table.simId, input.config, input.bet);
+    expect.payoutCenti = t.payoutCenti;
+    expect.restoreHash = canonHash(t.restored.outcome);
+    expect.frames = b64(t.frames);
+    seed = seed ?? t.seed;
+    roundConfig = (await game.normalize(snap.spec.modes[mi]!.config)).config;
+  }
+  if (seed) {
+    const r = await game.round(roundConfig, input.bet, seed);
+    const centi = Math.round(r.multiplier * 100);
+    if (input.table && centi !== expect.payoutCenti) {
+      throw new Error(`表里第 ${input.table.simId} 行赔 ${expect.payoutCenti} centi，按采样配置重跑 round() 却是 ${centi}——采样不可复现，这是 round() 不纯或 sims 变了`);
+    }
+    expect.payoutCenti = centi;
+    expect.outcomeHash = canonHash(r.outcome);
+  }
+  if (!seed && !input.table) throw new Error('case 至少要有 seed 或 table 之一');
+
+  return {
+    title: input.title, tags: input.tags ?? [], game: snap.spec.slug,
+    origin: input.origin, config: input.config, bet: input.bet, seed, table: input.table, expect, note: input.note,
+  };
+}

package/studio/src/config.ts

@@ -0,0 +1,39 @@
+/* studio 的启动配置。
+ *
+ * 游戏目录就是 cwd——studio 被 Claude Code 按 stdio 拉起时，cwd 天然就是创作者
+ * 正在编辑的那个目录，不需要再传一遍。手动启动时可以用位置参数覆盖。 */
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface StudioConfig {
+  /** 游戏目录，绝对路径。必须有 package.json 和 vite.config.ts */
+  gameDir: string;
+  /** studio 包自己的根目录。preview/ 在这里，vite 的 fs.allow 要放行它 */
+  studioRoot: string;
+  /** 游戏 vite dev server 的端口 */
+  gamePort: number;
+}
+
+const STUDIO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export function loadConfig(argv: readonly string[]): StudioConfig {
+  const rest = [...argv];
+  let dir: string | undefined;
+  let gamePort = 4301;
+
+  while (rest.length > 0) {
+    const k = rest.shift()!;
+    if (k === '--game-port') gamePort = Number(rest.shift());
+    else if (k.startsWith('-')) throw new Error(`不认识的参数 ${k}`);
+    else dir = k;
+  }
+
+  const gameDir = dir ? (isAbsolute(dir) ? dir : resolve(process.cwd(), dir)) : process.cwd();
+  for (const need of ['package.json', 'vite.config.ts']) {
+    if (!existsSync(join(gameDir, need))) {
+      throw new Error(`${gameDir} 下没有 ${need}——这不像一个游戏目录。在游戏目录里启动，或把目录作为参数传进来`);
+    }
+  }
+  return { gameDir, studioRoot: STUDIO_ROOT, gamePort };
+}

package/studio/src/engine.ts

@@ -0,0 +1,218 @@
+/* 把 node 侧的零件组装成一个 Engine。MCP 工具和 /studio/api 都只跟它说话。
+ *
+ * 状态只有两处：长任务（Jobs）和总线（Bus）。游戏本身的状态在 Game 里按指纹缓存，
+ * 预览的状态在浏览器里，node 侧只留一份最近上报的快照给 AI 读。 */
+import { join } from 'node:path';
+import type { Segment } from 'gamekit777/weights';
+import { Bus } from './bus.ts';
+import { buildMode, groupsSummary, listArtifacts, readArtifactBytes, sampleMode, type Artifact, type BuildModeOptions } from './build.ts';
+import { CaseStore, captureCase, runCases, type CaseRecord, type RunCasesOptions } from './cases.ts';
+import { Game, type Config } from './game.ts';
+import { Jobs, type Job } from './jobs.ts';
+import { probe, type ProbeOptions, type ProbeResult } from './probe.ts';
+import { runSolve, type Targets } from './solver.ts';
+import { runTask, type TaskName, type TaskResult } from './tasks.ts';
+
+export interface PreviewState {
+  connected: boolean;
+  config: Config | null;
+  mode: string | null;
+  bet: number | null;
+  balance: number | null;
+  status: unknown;
+  lastError: string | null;
+  recent: unknown[];
+  consoleErrors: string[];
+  updatedAt: number;
+}
+
+export interface PublishRequest {
+  id: string;
+  modes: string[] | null;
+  note: string | null;
+  from: 'mcp' | 'page';
+  createdAt: number;
+  status: 'awaiting-approval' | 'running' | 'published' | 'rejected' | 'failed';
+  progress: string[];
+  result: unknown;
+  error: string | null;
+}
+
+export class Engine {
+  readonly game: Game;
+  readonly bus = new Bus();
+  readonly jobs: Jobs;
+  readonly cases: CaseStore;
+  readonly urls: { studio: string; preview: string };
+  preview: PreviewState = {
+    connected: false, config: null, mode: null, bet: null, balance: null,
+    status: null, lastError: null, recent: [], consoleErrors: [], updatedAt: 0,
+  };
+  #publish = new Map<string, PublishRequest>();
+  #lastFingerprint: string;
+
+  constructor(gameDir: string, urls: { studio: string; preview: string }) {
+    this.game = new Game(gameDir);
+    this.urls = urls;
+    this.#lastFingerprint = this.game.fingerprint;
+    this.jobs = new Jobs((job, msg) => this.bus.emit({ t: 'job', id: job.id, kind: job.kind, status: job.status, msg }));
+    this.cases = new CaseStore(gameDir, () => this.bus.emit({ t: 'cases', changed: true }));
+  }
+
+  /** 每次外部调用前过一遍：指纹变了就广播，页面和 AI 都该知道缓存作废了 */
+  touch(): void {
+    if (this.game.refresh() || this.game.fingerprint !== this.#lastFingerprint) {
+      this.#lastFingerprint = this.game.fingerprint;
+      this.bus.emit({ t: 'fingerprint', hash: this.game.fingerprint });
+      this.bus.log('info', `规则指纹变了 → ${this.game.fingerprint}，采样缓存与产物按新指纹重算`);
+    }
+  }
+
+  async info(): Promise<{
+    gameDir: string; fingerprint: string; packageName: string;
+    snapshot: Awaited<ReturnType<Game['snapshot']>>;
+    urls: Engine['urls']; previewConnected: boolean; artifacts: Artifact[]; cases: number;
+    caseFile: string;
+  }> {
+    this.touch();
+    return {
+      gameDir: this.game.dir, fingerprint: this.game.fingerprint, packageName: this.game.packageName,
+      snapshot: await this.game.snapshot(), urls: this.urls,
+      previewConnected: this.bus.previewConnected,
+      artifacts: listArtifacts(this.game), cases: this.cases.list().length,
+      caseFile: this.cases.path,
+    };
+  }
+
+  /* ── 探测 / 采样 / 求解 / 建表 ── */
+
+  probe(o: ProbeOptions = {}): Job<ProbeResult> {
+    this.touch();
+    return this.jobs.start('probe', async (say) => {
+      say('探测中：数组合、逐字段采样、数分布…');
+      const r = await probe(this.game, o);
+      say(`结论：${r.verdict}——${r.verdictReason}`);
+      return r;
+    });
+  }
+
+  sample(modes: string[] | null, sims: number | null): Job<{ modes: string[]; sims: number }> {
+    this.touch();
+    return this.jobs.start('sample', async (say) => {
+      const snap = await this.game.snapshot();
+      const n = sims ?? snap.spec.sims;
+      const idx = this.#modeIndices(snap.spec.modes.map((m) => m.name), modes);
+      for (const i of idx) await sampleMode(this.game, i, n, say);
+      return { modes: idx.map((i) => snap.spec.modes[i]!.name), sims: n };
+    });
+  }
+
+  async groups(mode: string | null, sims: number | null): Promise<ReturnType<typeof groupsSummary>> {
+    this.touch();
+    const snap = await this.game.snapshot();
+    const i = mode ? snap.spec.modes.findIndex((m) => m.name === mode) : 0;
+    if (i < 0) throw new Error(`没有 mode ${mode}`);
+    return groupsSummary(this.game, i, sims ?? snap.spec.sims);
+  }
+
+  async solve(mode: string | null, sims: number | null, targets: Targets): Promise<ReturnType<typeof runSolve> & { mode: string; rtpRangePpm: [number, number] }> {
+    const g = await this.groups(mode, sims);
+    const { rtpRangePpm } = await import('./solver.ts');
+    return { ...runSolve(g.groups, targets, g.betCostCenti, g.sims), mode: g.mode, rtpRangePpm: rtpRangePpm(g.groups, g.betCostCenti) };
+  }
+
+  build(modes: string[] | null, o: BuildModeOptions & { segments?: Segment[] } = {}): Job<Artifact[]> {
+    this.touch();
+    return this.jobs.start('build', async (say) => {
+      const snap = await this.game.snapshot();
+      const idx = this.#modeIndices(snap.spec.modes.map((m) => m.name), modes);
+      const out: Artifact[] = [];
+      for (const i of idx) out.push(await buildMode(this.game, i, o, say));
+      this.bus.emit({ t: 'build', artifacts: listArtifacts(this.game) });
+      return out;
+    });
+  }
+
+  artifacts(): Artifact[] { this.touch(); return listArtifacts(this.game); }
+
+  artifactBytes(mode: string): ReturnType<typeof readArtifactBytes> | null {
+    const a = listArtifacts(this.game).find((x) => x.mode === mode);
+    return a ? readArtifactBytes(a) : null;
+  }
+
+  #modeIndices(all: string[], want: string[] | null): number[] {
+    if (!want) return all.map((_, i) => i);
+    return want.map((m) => {
+      const i = all.indexOf(m);
+      if (i < 0) throw new Error(`清单里没有 mode ${m}。有的是：${all.join('、')}`);
+      return i;
+    });
+  }
+
+  /* ── 任务 ── */
+
+  task(name: TaskName): Job<TaskResult> {
+    this.touch();
+    return this.jobs.start(`task:${name}`, async (say) => {
+      say(`bun run ${name}`);
+      const r = await runTask(this.game.dir, name);
+      say(r.ok ? `通过（${(r.durationMs / 1000).toFixed(1)}s）` : `失败，退出码 ${r.exitCode}${r.timedOut ? '（超时）' : ''}`);
+      return r;
+    });
+  }
+
+  /* ── case ── */
+
+  async caseAdd(input: Parameters<typeof captureCase>[1]): Promise<CaseRecord> {
+    this.touch();
+    const rec = this.cases.add(await captureCase(this.game, input));
+    this.bus.emit({ t: 'cases', changed: true });
+    return rec;
+  }
+
+  caseRun(o: RunCasesOptions = {}): ReturnType<typeof runCases> {
+    this.touch();
+    return runCases(this.game, this.cases, o);
+  }
+
+  /* ── 预览 ── */
+
+  reportPreview(state: Partial<PreviewState>): void {
+    this.bus.heartbeat();
+    this.preview = { ...this.preview, ...state, connected: this.bus.previewConnected, updatedAt: Date.now() };
+    this.bus.emit({ t: 'preview', state: this.preview });
+  }
+
+  previewCommand<T>(cmd: unknown, timeoutMs?: number): Promise<T> {
+    return this.bus.command<T>(cmd, timeoutMs);
+  }
+
+  /* ── 发布：node 侧只管排队和记录，上传由页面用浏览器身份做 ── */
+
+  requestPublish(modes: string[] | null, note: string | null, from: PublishRequest['from']): PublishRequest {
+    const req: PublishRequest = {
+      id: `p${Date.now().toString(36)}`, modes, note, from, createdAt: Date.now(),
+      status: 'awaiting-approval', progress: [], result: null, error: null,
+    };
+    this.#publish.set(req.id, req);
+    this.bus.emit({ t: 'publish', request: req });
+    return req;
+  }
+
+  updatePublish(id: string, patch: Partial<PublishRequest>): PublishRequest | null {
+    const req = this.#publish.get(id);
+    if (!req) return null;
+    Object.assign(req, patch);
+    this.bus.emit({ t: 'publish', request: req });
+    return req;
+  }
+
+  publishRequests(): PublishRequest[] { return [...this.#publish.values()].sort((a, b) => b.createdAt - a.createdAt); }
+
+  async dispose(): Promise<void> {
+    this.cases.close();
+    await this.game.dispose();
+  }
+}
+
+export const studioDir = (gameDir: string): string => join(gameDir, '.studio');

package/studio/src/fingerprint.ts

@@ -0,0 +1,39 @@
+/* 规则指纹：游戏逻辑的内容哈希。
+ *
+ * 采样缓存、构建产物全挂在它上面。指纹没变就复用，
+ * 变了就作废——拿旧表演新逻辑是「表里写 0x、客户端演 4.64x」的翻版，而且完全静默。
+ *
+ * 范围故意取得宽：src/ 下所有非 .svelte 的 .ts，外加清单 game.ts。
+ * 纯逻辑面的传递依赖没法静态枚举（coco 的 rules/ 依赖 lib/），漏掉一个就是静默失效，
+ * 多算几个文件的代价只是偶尔一次不必要的重采样。 */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { Sha256 } from 'gamekit777/sdk/hash';
+
+const walk = (dir: string, out: string[] = []): string[] => {
+  for (const n of readdirSync(dir).sort()) {
+    const p = join(dir, n);
+    if (statSync(p).isDirectory()) walk(p, out);
+    else if (/\.ts$/.test(n) && !/\.svelte\.ts$/.test(n) && !/\.test\.ts$/.test(n)) out.push(p);
+  }
+  return out;
+};
+
+export interface Fingerprint {
+  /** 16 位十六进制 */
+  hash: string;
+  files: number;
+}
+
+export function fingerprintOf(gameDir: string): Fingerprint {
+  const files = walk(join(gameDir, 'src'));
+  try { statSync(join(gameDir, 'game.ts')); files.push(join(gameDir, 'game.ts')); } catch { /* 没有就没有 */ }
+
+  const h = new Sha256();
+  for (const f of files) {
+    h.update(new TextEncoder().encode(`${relative(gameDir, f)}\0`));
+    h.update(readFileSync(f));
+    h.update(new TextEncoder().encode('\0'));
+  }
+  return { hash: h.hex().slice(0, 16), files: files.length };
+}