gamekit777 0.1.0

package/studio/bin.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+/* GameKit Studio：创作者工作台。
+ *
+ * 两种启动方式，同一个进程形态：
+ *   被 Claude Code 拉起（stdio 不是 TTY）  → MCP 走 stdio，页面照常起在 HTTP 上
+ *   手动 `bunx gamekit777 studio [dir]`    → 只起页面，AI 想接就配 stdio
+ *
+ * stdio 模式下 stdout 是协议通道，所有人话都走 stderr。 */
+import { loadConfig } from './src/config.ts';
+import { Engine } from './src/engine.ts';
+import { startGameServer } from './src/game-vite.ts';
+import { serveStdio } from './src/mcp.ts';
+import { PAGE_PATH, PREVIEW_PATH } from './src/studio-plugin.ts';
+
+const argv = process.argv.slice(2);
+const forceMcp = argv.includes('--mcp');
+const noMcp = argv.includes('--no-mcp');
+const mcpMode = forceMcp || (!noMcp && !process.stdin.isTTY);
+const rest = argv.filter((a) => a !== '--mcp' && a !== '--no-mcp');
+
+const say = (m: string): void => { process.stderr.write(`${m}\n`); };
+if (mcpMode) {
+  // 任何人在任何地方 console.log 都不能污染协议
+  console.log = (...a: unknown[]) => { process.stderr.write(`${a.map(String).join(' ')}\n`); };
+}
+
+let cfg;
+try {
+  cfg = loadConfig(rest);
+} catch (e) {
+  say(`✗ ${e instanceof Error ? e.message : String(e)}`);
+  process.exit(1);
+}
+
+const backendUrl = process.env.GAMEKIT_BASE_URL ?? 'http://127.0.0.1:8787';
+const placeholder = { studio: '', preview: '' };
+const engine = new Engine(cfg.gameDir, placeholder);
+
+const server = await startGameServer({
+  gameDir: cfg.gameDir, studioRoot: cfg.studioRoot, port: cfg.gamePort, backendUrl, engine, quiet: mcpMode,
+});
+const base = (server.resolvedUrls?.local[0] ?? `http://127.0.0.1:${cfg.gamePort}/`).replace(/\/$/, '');
+placeholder.studio = `${base}${PAGE_PATH}`;
+placeholder.preview = `${base}${PREVIEW_PATH}`;
+
+let mcp: Awaited<ReturnType<typeof serveStdio>> | null = null;
+if (mcpMode) mcp = await serveStdio(engine);
+
+const snap = await engine.game.snapshot().catch((e: unknown) => { say(`⚠️ 加载游戏逻辑失败：${e instanceof Error ? e.message : String(e)}`); return null; });
+
+say(`
+GameKit Studio${mcpMode ? '（MCP over stdio）' : ''}
+  游戏    ${cfg.gameDir}${snap ? `  ·  ${snap.spec.title}（${snap.spec.slug}）  ·  ${snap.spec.modes.length} 个 mode` : ''}
+  页面    ${placeholder.studio}
+  预览    ${placeholder.preview}
+  后端    ${backendUrl}  →  /v1
+${mcpMode ? '' : `
+  接 AI：claude mcp add gamekit -- bunx gamekit777 studio
+`}`);
+
+const shutdown = async (): Promise<void> => {
+  await Promise.allSettled([mcp?.close(), server.close(), engine.dispose()]);
+  process.exit(0);
+};
+process.on('SIGINT', () => { void shutdown(); });
+process.on('SIGTERM', () => { void shutdown(); });
+// stdin 关了就是 Claude Code 走了，跟着退出，不留僵尸进程
+if (mcpMode) process.stdin.on('end', () => { void shutdown(); });

package/studio/cli.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+/* `gamekit777` 这个命令的入口：按子命令分派。
+ *
+ *   gamekit777 studio [dir] [--mcp|--no-mcp] [--game-port N]   起工作台（MCP 走 stdio）
+ *   gamekit777 new <id> [标题] [--dest 目录]                     脚手架一个新游戏并装依赖
+ *
+ * 只是薄薄一层分派，逻辑各在 bin.ts 和 src/scaffold.ts。 */
+const [sub, ...rest] = process.argv.slice(2);
+
+const usage = (): never => {
+  process.stderr.write(`用法：
+  gamekit777 studio [dir] [--mcp|--no-mcp] [--game-port N]
+  gamekit777 new <id> [标题] [--dest 目录]
+
+接 Claude Code：在游戏目录里
+  claude mcp add gamekit -- bunx gamekit777 studio
+`);
+  process.exit(1);
+};
+
+switch (sub) {
+  case 'studio': {
+    process.argv = [process.argv[0]!, process.argv[1]!, ...rest];
+    await import('./bin.ts');
+    break;
+  }
+  case 'new': {
+    const { scaffold } = await import('./src/scaffold.ts');
+    const destAt = rest.indexOf('--dest');
+    const dest = destAt >= 0 ? rest.splice(destAt, 2)[1] : undefined;
+    const [id, title] = rest;
+    if (!id) usage();
+    try {
+      const r = await scaffold({ id: id!, title, dest }, process.cwd());
+      process.stdout.write(`✓ ${r.dest}\n\n${r.next.map((n) => `  ${n}`).join('\n')}\n\n  cd ${r.dest} && bunx gamekit777 studio\n`);
+    } catch (e) {
+      process.stderr.write(`✗ ${e instanceof Error ? e.message : String(e)}\n`);
+      process.exit(1);
+    }
+    break;
+  }
+  default: usage();
+}

package/studio/preview/bridge.ts

@@ -0,0 +1,63 @@
+/* 预览壳 ↔ node 侧。下行 SSE 收命令，上行 POST 回结果和状态。
+ *
+ * 同源，所以直接 fetch /studio/api。控制台报错也顺手收一份上报——
+ * AI 读 preview_state 时最想知道的就是「预览里报了什么错」。 */
+const API = '/studio/api';
+
+export interface Cmd { id: string; cmd: Record<string, unknown> & { t: string } }
+
+export type CmdHandler = (cmd: Cmd['cmd']) => Promise<unknown>;
+
+export function connectBridge(o: { onCommand: CmdHandler; onFingerprint?: (hash: string) => void; onBuild?: () => void }): { report: (state: unknown) => void; log: (msg: string) => void; errors: string[] } {
+  const errors: string[] = [];
+  const post = (path: string, body: unknown): Promise<Response> =>
+    fetch(`${API}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+
+  const es = new EventSource(`${API}/events?role=preview`);
+  es.onmessage = (e) => {
+    let msg: { t: string; id?: string; cmd?: Cmd['cmd']; hash?: string };
+    try { msg = JSON.parse(String(e.data)); } catch { return; }
+    if (msg.t === 'cmd' && msg.id && msg.cmd) {
+      const id = msg.id;
+      o.onCommand(msg.cmd).then(
+        (payload) => post('/preview/result', { id, ok: true, payload }),
+        (err: unknown) => post('/preview/result', { id, ok: false, payload: err instanceof Error ? err.message : String(err) }),
+      ).catch(() => {});
+    } else if (msg.t === 'fingerprint' && msg.hash) o.onFingerprint?.(msg.hash);
+    else if (msg.t === 'build') o.onBuild?.();
+  };
+
+  const origError = console.error.bind(console);
+  console.error = (...a: unknown[]) => {
+    const line = a.map((x) => (x instanceof Error ? x.message : typeof x === 'string' ? x : JSON.stringify(x))).join(' ');
+    errors.push(line); if (errors.length > 30) errors.shift();
+    origError(...a);
+  };
+  addEventListener('error', (e) => { errors.push(e.message); if (errors.length > 30) errors.shift(); });
+  addEventListener('unhandledrejection', (e) => { errors.push(String((e as PromiseRejectionEvent).reason)); if (errors.length > 30) errors.shift(); });
+
+  let pending: unknown = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return {
+    errors,
+    // 合并一下：runes 一变就上报会打爆接口
+    report: (state) => { pending = state; if (!timer) timer = setTimeout(() => { timer = null; void post('/preview/state', { ...(pending as object), consoleErrors: errors }); }, 150); },
+    log: (msg) => { void post('/log', { level: 'info', msg }); },
+  };
+}
+
+export const api = {
+  artifacts: async (): Promise<{ mode: string; table: Uint8Array; books: { simId: number; frames: string }[] | null }[]> => {
+    const list = await (await fetch(`${API}/artifacts`)).json() as { mode: string; hasBooks: boolean }[];
+    return Promise.all(list.map(async (a) => ({
+      mode: a.mode,
+      table: new Uint8Array(await (await fetch(`${API}/artifacts/${encodeURIComponent(a.mode)}/table`)).arrayBuffer()),
+      books: a.hasBooks ? await (await fetch(`${API}/artifacts/${encodeURIComponent(a.mode)}/books`)).json() as { simId: number; frames: string }[] : null,
+    })));
+  },
+  addCase: async (body: unknown): Promise<{ id: string }> => {
+    const r = await fetch(`${API}/cases`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+    if (!r.ok) throw new Error((await r.json() as { error: string }).error);
+    return r.json() as Promise<{ id: string }>;
+  },
+};

package/studio/preview/entry.ts

@@ -0,0 +1,89 @@
+/* 预览壳的入口，跑在游戏 vite dev server 的页面里。
+ *
+ * 壳就是 dev-host 的 DevShell——和 `bun run dev` 看到的是同一个参考平台，同一条本地表模型：
+ * 浏览器里就地建表、按权重抽行、restore 还原。studio 多接的只有三样：
+ * 建好的正式产物（有就优先用）、存为 case、以及 node 侧的总线（MCP 的 preview_* 工具从那儿进来）。 */
+import { runDevShell, parseTable, localServer, type LoadedTable, type PlatformOf } from 'gamekit777/dev-host';
+import type { GameModule } from 'gamekit777/sdk';
+import game from 'virtual:studio/game';
+import { api, connectBridge } from './bridge.ts';
+
+type G = GameModule<object, unknown>;
+const g = game as G;
+
+/** node 侧建好的表（.studio/build/<指纹>/），喂给本地服务端；没建的 mode 照样就地建 */
+const external = async (): Promise<ReadonlyMap<string, LoadedTable>> => {
+  const out = new Map<string, LoadedTable>();
+  for (const a of await api.artifacts()) out.set(a.mode, parseTable(a.mode, a.table, a.books));
+  return out;
+};
+
+let p: PlatformOf<object, unknown> | null = null;
+
+runDevShell(g, {
+  // 嵌入模式：页眉和余额由 studio 页面画，这里只剩机台和机台下面的开发面板
+  embedded: true,
+  server: localServer({ spec: g, external }),
+  onPlatform: (plat) => { p = plat; },
+  onSaveCase: async (h, title) => {
+    const body: Record<string, unknown> = { title, origin: 'preview', config: h.config, bet: h.bet };
+    if (h.simId !== null) body.table = { mode: h.mode, simId: h.simId };
+    if (h.seed) body.seed = h.seed;
+    return (await api.addCase(body)).id;
+  },
+});
+
+const plain = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+const snapshot = (): Record<string, unknown> => {
+  if (!p) return { connected: false };
+  return {
+    config: plain(p.config), mode: p.tableMode, bet: p.bet, balance: p.balance, pnl: p.pnl,
+    status: plain(p.game), lastError: p.err, tableModes: plain(p.tableModes),
+    recent: p.history.slice(0, 10).map((h) => ({ n: h.n, mode: h.mode, multiplier: h.multiplier, payout: h.payout, simId: h.simId, ok: h.checks.every((c) => c.ok) })),
+  };
+};
+const waitIdle = (): Promise<void> => new Promise((r) => { const t = setInterval(() => { if (p && !p.game.busy && !p.placing) { clearInterval(t); r(); } }, 50); });
+const must = (): PlatformOf<object, unknown> => { if (!p) throw new Error('预览的平台还没建好'); return p; };
+
+/* ── 总线：MCP 的 preview_* 工具从这里进来 ── */
+const bridge = connectBridge({
+  onBuild: () => { void p?.reloadTables(); },
+  onCommand: async (cmd) => {
+    switch (cmd.t) {
+      case 'state': return snapshot();
+      case 'set': {
+        const plat = must();
+        const applied: string[] = [];
+        const rejected: { key: string; reason: string }[] = [];
+        if (cmd.config !== undefined) { if (plat.requestConfig(cmd.config as never)) applied.push('config'); else rejected.push({ key: 'config', reason: '局中/自动中/注已发出，平台否决' }); }
+        if (cmd.bet !== undefined) { if (plat.setBet(Number(cmd.bet))) applied.push('bet'); else rejected.push({ key: 'bet', reason: '局中/自动中' }); }
+        if (cmd.clientSeed !== undefined) { plat.clientSeed = String(cmd.clientSeed); applied.push('clientSeed'); }
+        if (cmd.skin !== undefined) { plat.setView({ skin: String(cmd.skin) }); applied.push('skin'); }
+        if (cmd.turbo !== undefined) { plat.setView({ turbo: !!cmd.turbo }); applied.push('turbo'); }
+        return { applied, rejected, state: snapshot() };
+      }
+      case 'play': {
+        const plat = must();
+        const n = Math.max(1, Math.min(50, Number(cmd.rounds ?? 1)));
+        if (cmd.bet !== undefined) plat.setBet(Number(cmd.bet));
+        const rounds: unknown[] = [];
+        const errors: string[] = [];
+        for (let i = 0; i < n; i++) {
+          if (plat.game.busy || plat.placing) await waitIdle();
+          const h = await plat.playOne({ seed: cmd.seed as never, simId: cmd.simId as number | undefined, animate: cmd.animate !== false });
+          if (!h) { errors.push(plat.err ?? '未知错误'); if (errors.length >= 3) break; continue; }
+          rounds.push({
+            n: h.n, mode: h.mode, bet: h.bet, payout: h.payout, multiplier: h.multiplier,
+            payoutCenti: Math.round(h.multiplier * 100), checks: h.checks, simId: h.simId, seed: h.seed,
+          });
+        }
+        return { rounds, wallet: { balance: plat.balance }, errors };
+      }
+      default: throw new Error(`预览不认识命令 ${cmd.t}`);
+    }
+  },
+});
+
+// 状态上报：给 AI 的 preview_state 和页面看
+setInterval(() => bridge.report(snapshot()), 1000);
+bridge.report(snapshot());

package/studio/preview/virtual.d.ts

@@ -0,0 +1,6 @@
+/* `virtual:studio/game` 由 src/preview-plugin.ts 在 vite 里解析到游戏入口 */
+declare module 'virtual:studio/game' {
+  import type { GameModule } from 'gamekit777/sdk';
+  const game: GameModule<object, unknown>;
+  export default game;
+}

package/studio/src/api.ts

@@ -0,0 +1,157 @@
+/* /studio/api：页面和预览壳跟 node 侧说话的地方。
+ *
+ * 挂在游戏的 vite dev server 上当中间件——页面、预览、API 三者同源，
+ * 于是页面能直接 import 游戏 logic、预览能直接 fetch 产物、cookie 反代到 /v1 也同源。 */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Engine } from './engine.ts';
+import type { ProbeOptions } from './probe.ts';
+import type { Targets } from './solver.ts';
+import type { TaskName } from './tasks.ts';
+
+type Handler = (req: IncomingMessage, res: ServerResponse, params: Record<string, string>, body: unknown) => Promise<unknown> | unknown;
+
+interface Route { method: string; pattern: RegExp; keys: string[]; handler: Handler }
+
+const compile = (path: string): { pattern: RegExp; keys: string[] } => {
+  const keys: string[] = [];
+  const src = path.replace(/:([a-zA-Z]+)/g, (_, k: string) => { keys.push(k); return '([^/]+)'; });
+  return { pattern: new RegExp(`^${src}$`), keys };
+};
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  if (chunks.length === 0) return null;
+  const text = Buffer.concat(chunks).toString('utf8');
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+const json = (res: ServerResponse, status: number, body: unknown): void => {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Access-Control-Allow-Origin': '*' });
+  res.end(JSON.stringify(body, (_k, v: unknown) => (typeof v === 'bigint' ? v.toString() : v)));
+};
+
+export const API_PREFIX = '/studio/api';
+
+export function createApi(engine: Engine): (req: IncomingMessage, res: ServerResponse, next: () => void) => void {
+  const routes: Route[] = [];
+  const on = (method: string, path: string, handler: Handler): void => { routes.push({ method, ...compile(path), handler }); };
+  const num = (v: unknown): number | null => (v === undefined || v === null || v === '' ? null : Number(v));
+  const list = (v: unknown): string[] | null => (Array.isArray(v) ? v.map(String) : typeof v === 'string' && v ? v.split(',') : null);
+
+  on('GET', '/info', () => engine.info());
+
+  /* 总线 */
+  on('GET', '/events', (req, res) => {
+    const role = new URL(req.url!, 'http://x').searchParams.get('role') === 'preview' ? 'preview' : 'page';
+    engine.bus.attach(res, role);
+    return undefined;   // 已经接管了 res
+  });
+  on('POST', '/preview/state', (_r, _s, _p, body) => { engine.reportPreview(body as never); return { ok: true }; });
+  on('POST', '/preview/result', (_r, _s, _p, body) => {
+    const b = body as { id: string; ok: boolean; payload: unknown };
+    return { matched: engine.bus.resolve(b.id, b.ok, b.payload) };
+  });
+  on('POST', '/preview/command', (_r, _s, _p, body) => engine.previewCommand(body));
+  on('POST', '/log', (_r, _s, _p, body) => {
+    const b = body as { level?: 'info' | 'warn' | 'error'; msg: string };
+    engine.bus.log(b.level ?? 'info', b.msg);
+    return { ok: true };
+  });
+
+  /* 探测 / 采样 / 求解 / 建表 */
+  on('POST', '/probe', (_r, _s, _p, body) => engine.probe((body ?? {}) as ProbeOptions));
+  on('POST', '/sample', (_r, _s, _p, body) => {
+    const b = (body ?? {}) as { modes?: unknown; sims?: unknown };
+    return engine.sample(list(b.modes), num(b.sims));
+  });
+  on('GET', '/groups', (req) => {
+    const q = new URL(req.url!, 'http://x').searchParams;
+    return engine.groups(q.get('mode'), num(q.get('sims')));
+  });
+  on('POST', '/solve', (_r, _s, _p, body) => {
+    const b = body as { mode?: string; sims?: number; targets: Targets };
+    return engine.solve(b.mode ?? null, b.sims ?? null, b.targets);
+  });
+  on('POST', '/build', (_r, _s, _p, body) => {
+    const b = (body ?? {}) as { modes?: unknown; sims?: number; rtpPpm?: number; segments?: never };
+    return engine.build(list(b.modes), { sims: b.sims, declaredRtpPpm: b.rtpPpm, segments: b.segments });
+  });
+  on('GET', '/artifacts', () => engine.artifacts());
+  on('GET', '/artifacts/:mode/table', (_r, res, p) => {
+    const a = engine.artifactBytes(p.mode!);
+    if (!a) { json(res, 404, { error: `没有 mode ${p.mode} 的产物` }); return undefined; }
+    res.writeHead(200, { 'Content-Type': 'application/octet-stream', 'Access-Control-Allow-Origin': '*' });
+    res.end(a.table);
+    return undefined;
+  });
+  on('GET', '/artifacts/:mode/books', (_r, res, p) => {
+    const a = engine.artifactBytes(p.mode!);
+    if (!a) { json(res, 404, { error: `没有 mode ${p.mode} 的产物` }); return undefined; }
+    json(res, 200, a.books ?? []);
+    return undefined;
+  });
+
+  /* 长任务 */
+  on('GET', '/jobs', () => engine.jobs.list());
+  on('GET', '/jobs/:id', (_r, res, p) => {
+    const j = engine.jobs.get(p.id!);
+    if (!j) { json(res, 404, { error: `没有 job ${p.id}` }); return undefined; }
+    return j;
+  });
+
+  /* 任务 */
+  on('POST', '/task', (_r, _s, _p, body) => engine.task((body as { task: TaskName }).task));
+
+  /* case */
+  on('GET', '/cases', () => engine.cases.list());
+  on('POST', '/cases', (_r, _s, _p, body) => engine.caseAdd(body as never));
+  on('POST', '/cases/run', (_r, _s, _p, body) => engine.caseRun((body ?? {}) as never));
+  on('POST', '/cases/bless', (_r, _s, _p, body) => ({ blessed: engine.cases.bless((body as { updates: never[] }).updates) }));
+  on('DELETE', '/cases/:id', (_r, _s, p) => ({ removed: engine.cases.remove(p.id!) }));
+
+  /* 发布 */
+  on('GET', '/publish', () => engine.publishRequests());
+  on('POST', '/publish/request', (_r, _s, _p, body) => {
+    const b = (body ?? {}) as { modes?: unknown; note?: string };
+    return engine.requestPublish(list(b.modes), b.note ?? null, 'page');
+  });
+  on('POST', '/publish/:id', (_r, res, p, body) => {
+    const r = engine.updatePublish(p.id!, body as never);
+    if (!r) { json(res, 404, { error: `没有发布请求 ${p.id}` }); return undefined; }
+    return r;
+  });
+
+  return (req, res, next) => {
+    const url = new URL(req.url ?? '/', 'http://x');
+    if (!url.pathname.startsWith(API_PREFIX)) return next();
+    const path = url.pathname.slice(API_PREFIX.length) || '/';
+    const method = req.method ?? 'GET';
+
+    if (method === 'OPTIONS') {
+      res.writeHead(204, { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET,POST,DELETE,OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type' });
+      res.end();
+      return;
+    }
+
+    for (const r of routes) {
+      if (r.method !== method) continue;
+      const m = r.pattern.exec(path);
+      if (!m) continue;
+      const params: Record<string, string> = {};
+      r.keys.forEach((k, i) => { params[k] = decodeURIComponent(m[i + 1]!); });
+      void (async () => {
+        try {
+          const body = method === 'GET' ? null : await readBody(req);
+          const out = await r.handler(req, res, params, body);
+          if (out !== undefined && !res.headersSent) json(res, 200, out);
+        } catch (e) {
+          if (!res.headersSent) json(res, 500, { error: e instanceof Error ? e.message : String(e) });
+        }
+      })();
+      return;
+    }
+    json(res, 404, { error: `没有 ${method} ${path}` });
+  };
+}

package/studio/src/build.ts

@@ -0,0 +1,166 @@
+/* 表构建：采样（缓存）→ 求解 → 编码 → 自验 → 落盘。
+ *
+ * 采样是慢的那一步，结果按规则指纹缓存在 <gameDir>/.studio/cache/。
+ * 指纹一变缓存作废——拿旧表演新逻辑是「表里写 0x、客户端演 4.64x」的翻版，而且完全静默。
+ *
+ * 产物落在 <gameDir>/.studio/build/<fp>/。预览的表模型和发布上传吃的是**同一份**文件，
+ * 不存在「预览的表和发布的表不是一张」的可能。 */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PAYOUT_SCALE } from 'gamekit777/protocol';
+import type { BuiltTable } from 'gamekit777/publish';
+import { planRows, type RowPlan } from 'gamekit777/publish/table';
+import type { Segment } from 'gamekit777/weights';
+import type { Game } from './game.ts';
+
+export interface Batch { payoutCenti: Int32Array; books: Uint8Array[]; draws: number }
+
+const CACHE_MAGIC = new TextEncoder().encode('GKSC1');
+
+/* ── 采样缓存 ── */
+
+function cachePath(game: Game, mode: string, sims: number): string {
+  return join(game.dir, '.studio', 'cache', game.fingerprint, `${mode}.${sims}.bin`);
+}
+
+function writeBatch(path: string, b: Batch): void {
+  mkdirSync(join(path, '..'), { recursive: true });
+  let total = 0;
+  for (const x of b.books) total += x.length;
+  const sims = b.payoutCenti.length;
+  const head = new DataView(new ArrayBuffer(12));
+  head.setUint32(0, sims, true);
+  head.setUint32(4, total, true);
+  head.setUint32(8, b.draws >>> 0, true);
+  const offsets = new Int32Array(b.books.length + 1);
+  const data = new Uint8Array(total);
+  let at = 0;
+  for (let i = 0; i < b.books.length; i++) { data.set(b.books[i]!, at); at += b.books[i]!.length; offsets[i + 1] = at; }
+  const out = new Uint8Array(CACHE_MAGIC.length + 12 + sims * 4 + offsets.byteLength + total);
+  let p = 0;
+  out.set(CACHE_MAGIC, p); p += CACHE_MAGIC.length;
+  out.set(new Uint8Array(head.buffer), p); p += 12;
+  out.set(new Uint8Array(b.payoutCenti.buffer, b.payoutCenti.byteOffset, sims * 4), p); p += sims * 4;
+  out.set(new Uint8Array(offsets.buffer), p); p += offsets.byteLength;
+  out.set(data, p);
+  writeFileSync(path, out);
+}
+
+function readBatch(path: string): Batch | null {
+  if (!existsSync(path)) return null;
+  const buf = new Uint8Array(readFileSync(path));
+  for (let i = 0; i < CACHE_MAGIC.length; i++) if (buf[i] !== CACHE_MAGIC[i]) return null;
+  const dv = new DataView(buf.buffer, buf.byteOffset + CACHE_MAGIC.length, 12);
+  const sims = dv.getUint32(0, true), total = dv.getUint32(4, true), draws = dv.getUint32(8, true);
+  let p = CACHE_MAGIC.length + 12;
+  const payoutCenti = new Int32Array(buf.buffer.slice(buf.byteOffset + p, buf.byteOffset + p + sims * 4)); p += sims * 4;
+  const hasBooks = total > 0;
+  const offsets = new Int32Array(buf.buffer.slice(buf.byteOffset + p, buf.byteOffset + p + (sims + 1) * 4)); p += (sims + 1) * 4;
+  const data = buf.subarray(p, p + total);
+  const books: Uint8Array[] = hasBooks ? Array.from({ length: sims }, (_, i) => data.subarray(offsets[i]!, offsets[i + 1]!)) : [];
+  return { payoutCenti, books, draws };
+}
+
+/** 按清单采样，命中缓存就直接读 */
+export async function sampleMode(game: Game, modeIndex: number, sims: number, say: (m: string) => void = () => {}): Promise<Batch> {
+  const snap = await game.snapshot();
+  const mode = snap.spec.modes[modeIndex];
+  if (!mode) throw new Error(`没有第 ${modeIndex} 个 mode`);
+  const path = cachePath(game, mode.name, sims);
+  const hit = readBatch(path);
+  if (hit) { say(`[${mode.name}] 采样命中缓存（${sims} 局）`); return hit; }
+  say(`[${mode.name}] 采样 ${sims} 局`);
+  const b = await game.sampleSpec(modeIndex, sims);
+  writeBatch(path, b);
+  return b;
+}
+
+/** 调参 UI 要的摘要：只有 groups，几百 KB 以内，浏览器拿去就能实时 solve */
+export interface GroupsSummary {
+  mode: string; sims: number; betCostCenti: number; declaredRtpPpm: number;
+  groups: { payout: number; prior: number }[];
+  distinctPayouts: number; maxPayoutCenti: number; naturalRtpPpm: number; hitRatePpm: number;
+}
+
+export async function groupsSummary(game: Game, modeIndex: number, sims: number): Promise<GroupsSummary> {
+  const snap = await game.snapshot();
+  const spec = snap.spec;
+  const mode = spec.modes[modeIndex]!;
+  const b = await sampleMode(game, modeIndex, sims);
+  const plan: RowPlan = planRows(b.payoutCenti, true);
+  const betCostCenti = PAYOUT_SCALE;
+  let sum = 0, hit = 0, maxP = 0;
+  for (let i = 0; i < b.payoutCenti.length; i++) { const p = b.payoutCenti[i]!; sum += p; if (p > 0) hit++; if (p > maxP) maxP = p; }
+  return {
+    mode: mode.name, sims, betCostCenti,
+    declaredRtpPpm: Math.round(spec.rtp * 1e6),
+    groups: plan.groups.map((g) => ({ payout: g.payout, prior: g.prior })),
+    distinctPayouts: plan.groups.length, maxPayoutCenti: maxP,
+    naturalRtpPpm: Math.round((sum / sims / betCostCenti) * 1e6),
+    hitRatePpm: Math.round((hit / sims) * 1e6),
+  };
+}
+
+/* ── 产物 ── */
+
+export interface Artifact {
+  mode: string; fingerprint: string; builtAt: number;
+  contentHash: string; rowCount: number; totalWeight: number; betCostCenti: number;
+  declaredRtpPpm: number; computedRtpPpm: number; maxPayoutCenti: number; hitRatePpm: number; distinctPayouts: number;
+  sims: number; hasBooks: boolean;
+  segments: Segment[] | null;
+  stats: BuiltTable['stats'];
+  files: { table: string; books: string | null; meta: string };
+}
+
+const buildDir = (game: Game): string => join(game.dir, '.studio', 'build', game.fingerprint);
+
+export interface BuildModeOptions { sims?: number; declaredRtpPpm?: number; segments?: Segment[] }
+
+export async function buildMode(game: Game, modeIndex: number, o: BuildModeOptions = {}, say: (m: string) => void = () => {}): Promise<Artifact> {
+  const snap = await game.snapshot();
+  const mode = snap.spec.modes[modeIndex];
+  if (!mode) throw new Error(`没有第 ${modeIndex} 个 mode`);
+  const sims = o.sims ?? snap.spec.sims;
+
+  const batch = await sampleMode(game, modeIndex, sims, say);
+  say(`[${mode.name}] 求解 → 量化 → 编码 → 自验`);
+  const t = await game.buildFromBatch(modeIndex, batch, { declaredRtpPpm: o.declaredRtpPpm, segments: o.segments });
+
+  const dir = buildDir(game);
+  mkdirSync(dir, { recursive: true });
+  const stem = join(dir, mode.name);
+  writeFileSync(`${stem}.gklt1`, t.bytes);
+  if (t.books) writeFileSync(`${stem}.books.jsonl`, `${t.books.map((b) => JSON.stringify(b)).join('\n')}\n`);
+  else rmSync(`${stem}.books.jsonl`, { force: true });
+
+  const art: Artifact = {
+    mode: mode.name, fingerprint: game.fingerprint, builtAt: Date.now(),
+    contentHash: t.contentHash, rowCount: t.rowCount, totalWeight: t.totalWeight, betCostCenti: t.betCostCenti,
+    declaredRtpPpm: t.declaredRtpPpm, computedRtpPpm: t.verdict.computedRtpPpm,
+    maxPayoutCenti: t.verdict.maxPayoutCenti, hitRatePpm: t.verdict.hitRatePpm, distinctPayouts: t.verdict.distinctPayouts,
+    sims, hasBooks: t.books !== null, segments: o.segments ?? null,
+    stats: t.stats,
+    files: { table: `${stem}.gklt1`, books: t.books ? `${stem}.books.jsonl` : null, meta: `${stem}.json` },
+  };
+  writeFileSync(`${stem}.json`, `${JSON.stringify(art, null, 2)}\n`);
+  say(`[${mode.name}] ${t.rowCount} 行，RTP ${t.verdict.computedRtpPpm} ppm，sha256 ${t.contentHash.slice(0, 12)}…`);
+  return art;
+}
+
+/** 当前指纹下已建好的表。别的指纹的产物不算——那是旧逻辑的表 */
+export function listArtifacts(game: Game): Artifact[] {
+  const dir = buildDir(game);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith('.json'))
+    .map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')) as Artifact)
+    .sort((a, b) => a.mode.localeCompare(b.mode));
+}
+
+export function readArtifactBytes(art: Artifact): { table: Uint8Array; books: { simId: number; frames: string }[] | null } {
+  const table = new Uint8Array(readFileSync(art.files.table));
+  const books = art.files.books
+    ? readFileSync(art.files.books, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l) as { simId: number; frames: string })
+    : null;
+  return { table, books };
+}