gamekit777 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# gamekit777
+
+可证明公平的博彩小游戏工具箱：游戏 SDK、vite 构建预设、参考平台、权重表求解与打包上传流水线，
+以及一个给 AI 用的创作工作台（MCP server + 页面）。
+
+平台**不执行游戏代码**：打包时用你的 `round()` 采样出一张权重表，运行时按权重抽一行、查表赔付，
+浏览器用 `restore()` 把那一行还原成演出。审计的对象因此从「任意代码」变成「一张可下载的表」。
+
+## 需要
+
+- [bun](https://bun.sh) ≥ 1.2（命令行入口是裸 TS，由 bun 执行；`npx` 不行）
+- 游戏项目自带 `svelte` / `vite` / `@sveltejs/vite-plugin-svelte`（peer 依赖，脚手架会写好）
+
+## 开始
+
+```sh
+bunx gamekit777 new my-game "我的游戏"     # 一个能跑的抛硬币 + bun install
+cd my-game
+bun run dev                                # 参考平台：本地表模型，就地建表、抽行、restore 还原
+```
+
+接 Claude Code：
+
+```sh
+claude mcp add gamekit -- bunx gamekit777 studio   # 在游戏目录里
+claude
+```
+
+studio 同时是 MCP server、创作页面（预览 / 调参 / 建表 / Case / 发布）和到平台后端的反代。
+游戏目录里的 `CLAUDE.md` 是写给 AI 的开发指南：清单字段、`round()` 的硬约束、`modes` / `book` / `restore` 怎么选。
+
+手动起页面：`bunx gamekit777 studio [dir] --no-mcp [--game-port 4301]`。
+
+## 子路径
+
+| import | 内容 |
+|---|---|
+| `gamekit777/sdk` | `defineGame`、契约类型、可证明公平的 RNG、SHA-256 / HMAC、加权抽样原语 |
+| `gamekit777/runtime` | 资源加载、字体预取 |
+| `gamekit777/vite-config` | `defineGameConfig`：一个游戏的 `vite.config.ts` 只要三行 |
+| `gamekit777/dev-host` | 参考平台与本地表模型服务端；`createRemotePlatform` 接真平台 |
+| `gamekit777/protocol` · `client` | 平台 REST 契约（zod）与类型化客户端 |
+| `gamekit777/lut` · `weights` · `publish` | 权重表编解码与校验、凸优化求解器、采样→建表→上传流水线 |
+
+## 一条硬契约
+
+`restore()` 返回的 `payout` 必须恰好等于 `(bet / 100) × payoutCenti`，对不上就抛、不演出。
+本地开发走的就是真平台那条路，违反在第一注就会被拦下。

package/client/http.ts

@@ -0,0 +1,253 @@
+/* 传输层：一次 HTTP 往返 + 重试 + 会话状态。
+ *
+ * 分层的理由是重试策略只在这里有意义——上层的 api.bets.place() 不该知道
+ * 「同一个 Idempotency-Key 重发是安全的」这种事，而这恰恰是整个客户端最容易写错的地方。 */
+import { ApiError, ErrorCode, GameKitError } from '../protocol/index.ts';
+import type { ZodType } from 'zod';
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface RetryPolicy {
+  /** 总尝试次数，含第一次。1 表示不重试 */
+  attempts: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+}
+
+export const DEFAULT_RETRY: RetryPolicy = { attempts: 4, baseDelayMs: 50, maxDelayMs: 2_000 };
+
+export interface RetryEvent {
+  attempt: number;
+  delayMs: number;
+  error: GameKitError;
+  method: string;
+  path: string;
+}
+
+/**
+ * cookie 的落盘位置。
+ *
+ * 不持久化的话每次进程启动都是一个新匿名用户——脚本跑一次就在库里留下
+ * 一个用户、一个钱包、一份同名的游戏（`games` 的唯一约束是 `(owner_id, slug)`，
+ * 换了 owner 同一个 slug 就能再建一份）。跑十次开发库里就有十份。
+ */
+export interface CookieStore {
+  read(): Record<string, string>;
+  write(cookies: Record<string, string>): void;
+}
+
+export interface ClientOptions {
+  baseUrl: string;
+  fetch?: FetchLike;
+  /**
+   * 'browser' 把 cookie 交给浏览器（跨域靠 credentials: 'include'）。
+   * 'manual' 自己存 set-cookie——Node 里没有 cookie jar，不自己存的话
+   * 每个请求都是一个新匿名用户，而且不会报错，只会莫名其妙地余额归位。
+   */
+  cookies?: 'browser' | 'manual';
+  /** 只在 cookies: 'manual' 下有意义。Node 侧的文件实现见 @gamekit/client/node */
+  cookieStore?: CookieStore;
+  retry?: Partial<RetryPolicy>;
+  sleep?: (ms: number) => Promise<void>;
+  random?: () => number;
+  newIdempotencyKey?: () => string;
+  /** 用 zod 校验响应。默认开：协议漂移越早炸越好 */
+  validate?: boolean;
+  headers?: Record<string, string>;
+  onRetry?: (e: RetryEvent) => void;
+}
+
+export interface RequestSpec<T> {
+  method: string;
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  json?: unknown;
+  body?: Uint8Array;
+  headers?: Record<string, string>;
+  /** 带上它就等于声明「这个请求重发是安全的」 */
+  idempotencyKey?: string;
+  schema?: ZodType<T>;
+  binary?: boolean;
+}
+
+const wait = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** 解析失败一律当 INTERNAL：网关返回的 HTML 502 不是本协议的一部分 */
+function toError(status: number, payload: unknown): GameKitError {
+  const parsed = ApiError.safeParse(payload);
+  if (parsed.success) {
+    const e = parsed.data.error;
+    return new GameKitError(e.code, e.message, e.details);
+  }
+  const code: ErrorCode = status === 404 ? 'NOT_FOUND' : status === 401 ? 'UNAUTHENTICATED' : 'INTERNAL';
+  return new GameKitError(code, `HTTP ${status}`, payload);
+}
+
+/**
+ * 客户端本地判定的失败：响应不符合协议、下载的字节哈希对不上。
+ *
+ * 必须和服务端返回的错误分开，因为它复用了 INTERNAL 这类「服务端说可重试」的码，
+ * 而重试一个协议漂移只会把同一个错误再犯三遍。
+ */
+export class ClientError extends GameKitError {
+  override readonly name = 'ClientError';
+}
+
+/** 服务端说了才算。retryable 是响应信封里的字段，不是我们按状态码猜的 */
+const isRetryable = (e: GameKitError): boolean =>
+  !(e instanceof ClientError) && e.toJSON().error.retryable;
+
+export class Http {
+  readonly baseUrl: string;
+  #fetch: FetchLike;
+  #cookies: Map<string, string> | null;
+  #store: CookieStore | undefined;
+  #retry: RetryPolicy;
+  #sleep: (ms: number) => Promise<void>;
+  #random: () => number;
+  #newKey: () => string;
+  #validate: boolean;
+  #headers: Record<string, string>;
+  #onRetry: ((e: RetryEvent) => void) | undefined;
+  #bookmark: string | null = null;
+
+  constructor(opts: ClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+    this.#fetch = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    this.#cookies = opts.cookies === 'manual' ? new Map() : null;
+    this.#store = this.#cookies ? opts.cookieStore : undefined;
+    if (this.#cookies && this.#store) {
+      for (const [k, v] of Object.entries(this.#store.read())) this.#cookies.set(k, v);
+    }
+    this.#retry = { ...DEFAULT_RETRY, ...opts.retry };
+    this.#sleep = opts.sleep ?? wait;
+    this.#random = opts.random ?? Math.random;
+    this.#newKey = opts.newIdempotencyKey ?? (() => crypto.randomUUID());
+    this.#validate = opts.validate ?? true;
+    this.#headers = opts.headers ?? {};
+    this.#onRetry = opts.onRetry;
+  }
+
+  /** D1 Sessions 的因果一致性令牌。读自己刚写的数据全靠它 */
+  get bookmark(): string | null { return this.#bookmark; }
+  set bookmark(v: string | null) { this.#bookmark = v; }
+
+  newIdempotencyKey(): string { return this.#newKey(); }
+
+  /** 只在 cookies: 'manual' 下有内容；浏览器模式恒为空 */
+  get cookieHeader(): string {
+    if (!this.#cookies) return '';
+    return [...this.#cookies].map(([k, v]) => `${k}=${v}`).join('; ');
+  }
+
+  clearCookies(): void {
+    this.#cookies?.clear();
+    this.#store?.write({});
+  }
+
+  async request<T>(spec: RequestSpec<T>): Promise<T> {
+    // 幂等键在循环外生成：重试必须复用同一个 key，否则重试就是第二次下注
+    const key = spec.idempotencyKey;
+    const safeToRetry = spec.method === 'GET' || key !== undefined;
+    const url = this.#url(spec);
+
+    for (let attempt = 1; ; attempt++) {
+      let err: GameKitError;
+      try {
+        return await this.#once(spec, url, key);
+      } catch (e) {
+        err = e instanceof GameKitError
+          ? e
+          // fetch 自己抛 = 连接层面失败，请求多半没到服务端
+          : new GameKitError('INTERNAL', `请求失败：${(e as Error).message}`, { cause: String(e) });
+      }
+
+      if (!safeToRetry || !isRetryable(err) || attempt >= this.#retry.attempts) throw err;
+
+      const delayMs = this.#backoff(attempt);
+      this.#onRetry?.({ attempt, delayMs, error: err, method: spec.method, path: spec.path });
+      await this.#sleep(delayMs);
+    }
+  }
+
+  #backoff(attempt: number): number {
+    const full = Math.min(this.#retry.maxDelayMs, this.#retry.baseDelayMs * 2 ** (attempt - 1));
+    // 半抖动：多个客户端撞上同一次 NONCE_CONFLICT 时不要同步重试
+    return Math.round(full * (0.5 + this.#random() * 0.5));
+  }
+
+  #url(spec: RequestSpec<unknown>): string {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(spec.query ?? {})) {
+      if (v !== undefined) qs.set(k, String(v));
+    }
+    const q = qs.toString();
+    return `${this.baseUrl}${spec.path}${q ? `?${q}` : ''}`;
+  }
+
+  async #once<T>(spec: RequestSpec<T>, url: string, key: string | undefined): Promise<T> {
+    const headers: Record<string, string> = { ...this.#headers, ...spec.headers };
+    let body: BodyInit | undefined;
+
+    if (spec.json !== undefined) {
+      headers['content-type'] = 'application/json';
+      body = JSON.stringify(spec.json);
+    } else if (spec.body) {
+      headers['content-type'] = 'application/octet-stream';
+      // 传 ArrayBuffer 而不是视图：subarray 出来的视图带 byteOffset，
+      // 有些 fetch 实现会连整个底层 buffer 一起发出去
+      body = spec.body.slice().buffer as ArrayBuffer;
+    }
+
+    if (key) headers['idempotency-key'] = key;
+    if (this.#bookmark) headers['x-d1-bookmark'] = this.#bookmark;
+    const cookie = this.cookieHeader;
+    if (cookie) headers.cookie = cookie;
+
+    const res = await this.#fetch(url, {
+      method: spec.method,
+      headers,
+      body,
+      credentials: 'include',
+    });
+
+    this.#absorb(res);
+
+    if (!res.ok) throw toError(res.status, await this.#payload(res));
+
+    if (spec.binary) return new Uint8Array(await res.arrayBuffer()) as T;
+
+    const data = await this.#payload(res);
+    if (!this.#validate || !spec.schema) return data as T;
+    const parsed = spec.schema.safeParse(data);
+    if (!parsed.success) {
+      throw new ClientError('INTERNAL', `${spec.method} ${spec.path} 的响应不符合协议`, parsed.error.issues);
+    }
+    return parsed.data;
+  }
+
+  #absorb(res: Response): void {
+    const bm = res.headers.get('x-d1-bookmark');
+    if (bm) this.#bookmark = bm;
+
+    if (!this.#cookies) return;
+    const raw: string[] = typeof res.headers.getSetCookie === 'function'
+      ? res.headers.getSetCookie()
+      : [res.headers.get('set-cookie')].filter((v): v is string => v !== null);
+    let changed = false;
+    for (const line of raw) {
+      const pair = line.split(';', 1)[0] ?? '';
+      const eq = pair.indexOf('=');
+      if (eq <= 0) continue;
+      this.#cookies.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+      changed = true;
+    }
+    if (changed) this.#store?.write(Object.fromEntries(this.#cookies));
+  }
+
+  async #payload(res: Response): Promise<unknown> {
+    const text = await res.text();
+    if (!text) return null;
+    try { return JSON.parse(text) as unknown; } catch { return text; }
+  }
+}

package/client/index.ts

@@ -0,0 +1,211 @@
+/* @gamekit/client —— 后端 REST 接口的类型化封装。
+ *
+ * 请求与响应的形状全部来自 @gamekit/protocol，这里一个 schema 都不定义。
+ * 客户端重新声明一遍协议的话，两边漂移时没有任何东西会报错。 */
+import {
+  type BetResult as TBetResult, BetResult,
+  type BooksResult as TBooksResult, BooksResult,
+  type ChunkResult as TChunkResult, ChunkResult,
+  type CreateGame, type DeclareTable,
+  type DeclareTableResult as TDeclareTableResult, DeclareTableResult,
+  type Game as TGame, Game,
+  type GameDetail as TGameDetail, GameDetail,
+  type GamePage as TGamePage, GamePage,
+  type GameTable as TGameTable, GameTable,
+  GKLT1_HEADER_BYTES, GKLT1_ROW_BYTES,
+  GameKitError,
+  type ListGamesQuery, type ListRoundsQuery,
+  MAX_BOOKS_PER_CHUNK,
+  type PlaceBet, type PublishGame,
+  type RotateResult as TRotateResult, RotateResult,
+  type RoundDetail as TRoundDetail, RoundDetail,
+  type RoundPage as TRoundPage, RoundPage,
+  type SeedState as TSeedState, SeedState,
+  type SessionView as TSessionView, SessionView,
+  type UpdateGame,
+  type VerifyRoundRequest, type VerifyRoundResult as TVerifyRoundResult, VerifyRoundResult,
+  type VerifySpec as TVerifySpec, VerifySpec,
+  type VerifyTableResult as TVerifyTableResult, VerifyTableResult,
+} from '../protocol/index.ts';
+import { Sha256 } from '../sdk/hash.ts';
+import { z } from 'zod';
+import { ClientError, Http, type ClientOptions } from './http.ts';
+
+export * from './http.ts';
+
+/** 服务端说「重发是安全的」才是安全的，不要按状态码自己猜 */
+export const isRetryableError = (e: unknown): boolean =>
+  e instanceof GameKitError && e.toJSON().error.retryable;
+
+const Health = z.object({ ok: z.boolean() });
+
+export interface BetOptions {
+  /** 不传就自动生成。重试时复用同一个，所以传自己的 key 只在跨进程续传时才有必要 */
+  idempotencyKey?: string;
+}
+
+export interface UploadOptions {
+  /** 每块多少行。10 万行的表一块传完也行，这里的上限是请求体大小而不是行数 */
+  chunkRows?: number;
+  onProgress?: (p: { rowsIngested: number; rowCount: number }) => void;
+}
+
+export interface BookEntry { simId: number; frames: string }
+
+export function createClient(opts: ClientOptions) {
+  const http = new Http(opts);
+
+  const tables = {
+    declare: (gameId: string, body: DeclareTable): Promise<TDeclareTableResult> =>
+      http.request({
+        method: 'POST', path: `/v1/games/${gameId}/tables`, json: body, schema: DeclareTableResult,
+      }),
+
+    chunk: (gameId: string, tableId: string, bytes: Uint8Array): Promise<TChunkResult> =>
+      http.request({
+        method: 'PUT', path: `/v1/games/${gameId}/tables/${tableId}/chunk`,
+        body: bytes, schema: ChunkResult,
+      }),
+
+    /**
+     * 分块传完整张表。
+     *
+     * 切分规则是格式定的，不是随便切的：第一块必须以 64 字节头部开头，
+     * 之后每块都必须是 16 字节行的整数倍。切错了服务端只会回一句
+     * 「块长度必须是 16 的整数倍」，排查起来很费时间。
+     */
+    upload: async (
+      gameId: string, tableId: string, bytes: Uint8Array, o: UploadOptions = {},
+    ): Promise<TChunkResult> => {
+      const rowCount = (bytes.length - GKLT1_HEADER_BYTES) / GKLT1_ROW_BYTES;
+      if (!Number.isInteger(rowCount) || rowCount < 1) {
+        throw new ClientError('TABLE_INVALID_FORMAT', `${bytes.length} 字节不是合法的 GKLT1 长度`);
+      }
+      const step = Math.max(1, o.chunkRows ?? 20_000);
+      let last: TChunkResult = { rowsIngested: 0, done: false, rowCount };
+
+      for (let i = 0; i < rowCount; i += step) {
+        const from = i === 0 ? 0 : GKLT1_HEADER_BYTES + i * GKLT1_ROW_BYTES;
+        const to = Math.min(GKLT1_HEADER_BYTES + (i + step) * GKLT1_ROW_BYTES, bytes.length);
+        last = await tables.chunk(gameId, tableId, bytes.subarray(from, to));
+        o.onProgress?.({ rowsIngested: last.rowsIngested, rowCount });
+      }
+      return last;
+    },
+
+    books: (gameId: string, tableId: string, books: readonly BookEntry[]): Promise<TBooksResult> =>
+      http.request({
+        method: 'PUT', path: `/v1/games/${gameId}/tables/${tableId}/books`,
+        json: { books }, schema: BooksResult,
+      }),
+
+    /** 整表的演出数据，自动切批。要么一行不传，要么一行不少——部分覆盖会被终验拒掉 */
+    uploadBooks: async (
+      gameId: string, tableId: string, books: readonly BookEntry[],
+    ): Promise<TBooksResult> => {
+      let last: TBooksResult = { ingested: 0, rowCount: 0 };
+      for (let i = 0; i < books.length; i += MAX_BOOKS_PER_CHUNK) {
+        last = await tables.books(gameId, tableId, books.slice(i, i + MAX_BOOKS_PER_CHUNK));
+      }
+      return last;
+    },
+
+    verify: (gameId: string, tableId: string): Promise<TVerifyTableResult> =>
+      http.request({
+        method: 'POST', path: `/v1/games/${gameId}/tables/${tableId}/verify`,
+        schema: VerifyTableResult,
+      }),
+
+    get: (gameId: string, tableId: string): Promise<TGameTable> =>
+      http.request({
+        method: 'GET', path: `/v1/games/${gameId}/tables/${tableId}`, schema: GameTable,
+      }),
+
+    /**
+     * 公开下载已验证的表。默认自己算一遍 sha256——这是可证明公平的第一环，
+     * 「服务端说这份字节的哈希是 X」和「我自己算出来是 X」是完全不同的两件事。
+     */
+    download: async (contentHash: string, o: { verify?: boolean } = {}): Promise<Uint8Array> => {
+      const bytes = await http.request<Uint8Array>({
+        method: 'GET', path: `/v1/tables/${contentHash}`, binary: true,
+      });
+      if (o.verify !== false) {
+        const actual = new Sha256().update(bytes).hex();
+        if (actual !== contentHash) {
+          throw new ClientError('TABLE_HASH_MISMATCH',
+            `下载的字节哈希 ${actual} 与请求的 ${contentHash} 不符`, { actual, expected: contentHash });
+        }
+      }
+      return bytes;
+    },
+  };
+
+  return {
+    http,
+
+    health: (): Promise<z.infer<typeof Health>> =>
+      http.request({ method: 'GET', path: '/v1/health', schema: Health }),
+
+    session: {
+      bootstrap: (body: { clientSeed?: string } = {}): Promise<TSessionView> =>
+        http.request({ method: 'POST', path: '/v1/session/bootstrap', json: body, schema: SessionView }),
+      me: (): Promise<TSessionView> =>
+        http.request({ method: 'GET', path: '/v1/me', schema: SessionView }),
+    },
+
+    games: {
+      create: (body: CreateGame): Promise<TGame> =>
+        http.request({ method: 'POST', path: '/v1/games', json: body, schema: Game }),
+      update: (id: string, body: UpdateGame): Promise<TGame> =>
+        http.request({ method: 'PATCH', path: `/v1/games/${id}`, json: body, schema: Game }),
+      publish: (id: string, body: PublishGame): Promise<TGame> =>
+        http.request({ method: 'POST', path: `/v1/games/${id}/publish`, json: body, schema: Game }),
+      list: (query: Partial<ListGamesQuery> = {}): Promise<TGamePage> =>
+        http.request({ method: 'GET', path: '/v1/games', query, schema: GamePage }),
+      /** 详情比列表多一份已生效的 mode 清单——对局页要靠它知道有哪几张表可选 */
+      get: (id: string): Promise<TGameDetail> =>
+        http.request({ method: 'GET', path: `/v1/games/${id}`, schema: GameDetail }),
+    },
+
+    tables,
+
+    bets: {
+      /**
+       * 下注。
+       *
+       * 幂等键在这里生成而不是在传输层的重试循环里——重试必须复用同一个 key，
+       * 否则 NONCE_CONFLICT 的重试就变成了第二次真实下注。
+       */
+      place: (body: PlaceBet, o: BetOptions = {}): Promise<TBetResult> =>
+        http.request({
+          method: 'POST', path: '/v1/bets', json: body, schema: BetResult,
+          idempotencyKey: o.idempotencyKey ?? http.newIdempotencyKey(),
+        }),
+    },
+
+    rounds: {
+      list: (query: Partial<ListRoundsQuery> = {}): Promise<TRoundPage> =>
+        http.request({ method: 'GET', path: '/v1/rounds', query, schema: RoundPage }),
+      get: (id: string): Promise<TRoundDetail> =>
+        http.request({ method: 'GET', path: `/v1/rounds/${id}`, schema: RoundDetail }),
+    },
+
+    seeds: {
+      current: (): Promise<TSeedState> =>
+        http.request({ method: 'GET', path: '/v1/seeds/current', schema: SeedState }),
+      setClientSeed: (clientSeed: string): Promise<TRotateResult> =>
+        http.request({ method: 'POST', path: '/v1/seeds/client', json: { clientSeed }, schema: RotateResult }),
+      rotate: (): Promise<TRotateResult> =>
+        http.request({ method: 'POST', path: '/v1/seeds/rotate', schema: RotateResult }),
+    },
+
+    verify: {
+      spec: (): Promise<TVerifySpec> =>
+        http.request({ method: 'GET', path: '/v1/verify/spec', schema: VerifySpec }),
+      round: (body: VerifyRoundRequest): Promise<TVerifyRoundResult> =>
+        http.request({ method: 'POST', path: '/v1/verify/round', json: body, schema: VerifyRoundResult }),
+    },
+  };
+}
+
+export type GameKitClient = ReturnType<typeof createClient>;

package/client/node.ts

@@ -0,0 +1,61 @@
+/* Node 侧的 cookie 落盘。浏览器不会走到这里——它自己有 cookie jar。
+ *
+ * 为什么要持久化：不存的话每次进程启动都是一个新匿名用户，而 `games` 的唯一约束是
+ * `(owner_id, slug)`，换了 owner 同一个 slug 就能再建一份。端到端脚本跑十次，
+ * 开发库里就躺着十份 `books-full`、十个匿名钱包。 */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { SessionView } from '../protocol/index.ts';
+import type { CookieStore } from './http.ts';
+
+/** 默认落在临时目录：不污染仓库，跨 cwd 一致，重装系统自然失效 */
+export const defaultSessionFile = (): string =>
+  process.env.GAMEKIT_SESSION_FILE ?? join(tmpdir(), 'gamekit-dev-session.json');
+
+export function fileCookieStore(path = defaultSessionFile()): CookieStore {
+  return {
+    read() {
+      try {
+        if (!existsSync(path)) return {};
+        const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+        if (raw === null || typeof raw !== 'object') return {};
+        return Object.fromEntries(
+          Object.entries(raw as Record<string, unknown>)
+            .filter((e): e is [string, string] => typeof e[1] === 'string'),
+        );
+      } catch {
+        // 坏文件当没有：一个开发期的便利设施不值得让脚本跑不起来
+        return {};
+      }
+    },
+    write(cookies) {
+      try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(cookies, null, 2)}\n`);
+      } catch { /* 写不进去就算了，退化成不持久化 */ }
+    },
+  };
+}
+
+/**
+ * 开发脚本的会话引导：复用上次那个匿名用户，钱不够了就换一个。
+ *
+ * 两难是这样的：不复用的话每跑一次就在开发库里留一个用户、一个钱包、一整套同名游戏；
+ * 复用的话余额会被历史下注耗光——赠金只发一次，而 RTP 低于 100%，跑够多次必然归零。
+ *
+ * 所以复用是默认，余额不够时清掉 cookie 换一个新用户。垃圾只在真的需要时才产生。
+ * 真实玩家当然不该有这种行为，所以它住在这里而不是 client 的主入口。
+ */
+export async function bootstrapForScript(
+  api: {
+    session: { bootstrap(body?: { clientSeed?: string }): Promise<SessionView> };
+    http: { clearCookies(): void };
+  },
+  minCents = 20_000,
+): Promise<SessionView> {
+  const me = await api.session.bootstrap();
+  if (me.wallet.balanceCents >= minCents) return me;
+  api.http.clearCookies();
+  return api.session.bootstrap();
+}

package/create-game/scaffold.ts

@@ -0,0 +1,73 @@
+/* 新游戏脚手架的库函数面。
+ *
+ * 模板不是空壳，是一个跑得通的最小游戏（抛硬币）：装完就能 bun run dev、
+ * bun run verify、bun run test、bun run build 全绿。
+ * 从一个能跑的东西开始改，比对着一堆 TODO 填空可靠得多。
+ *
+ * 抽成库函数是因为有三个调用方：CLI、studio 的 scaffold 工具、以及
+ * npm 打包脚本的产物自验——最后一个尤其要紧，它生成的项目就是创作者的真实起点，
+ * 用别的东西代替就验不到「模板能不能脱离仓库跑」。 */
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/* 仓库内是 packages/create-game/{src,template}，压平进 npm 包后是 create-game/{scaffold.ts,template}——
+   两种布局都要找得到 */
+export const TEMPLATE_DIR = [join(HERE, '..', 'template'), join(HERE, 'template')].find(existsSync)
+  ?? join(HERE, '..', 'template');
+
+export const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export interface ScaffoldOptions {
+  id: string;
+  title?: string;
+  /** 目标目录。省略就是仓库内的 games/<id> */
+  dest: string;
+  /**
+   * 覆盖 package.json 里 gamekit777 的版本说明符。
+   * 仓库内是 `workspace:*`，产物自验要指到 dist-npm，创作者机器上是版本号。
+   */
+  gamekitSpec?: string;
+}
+
+export interface ScaffoldResult { dest: string; files: string[] }
+
+const walk = (dir: string): string[] =>
+  readdirSync(dir).flatMap((n) => {
+    const p = join(dir, n);
+    return statSync(p).isDirectory() ? walk(p) : [p];
+  });
+
+/** 驼峰化：coin-flip → CoinFlip，用作类型名前缀 */
+const pascal = (id: string): string =>
+  id.split('-').map((w) => w[0]!.toUpperCase() + w.slice(1)).join('');
+
+export function scaffoldGame(o: ScaffoldOptions): ScaffoldResult {
+  if (!ID_PATTERN.test(o.id)) {
+    throw new Error(`id "${o.id}" 要是小写短横线形式——它同时是包名、输出目录名和 CSS 命名空间`);
+  }
+  if (existsSync(o.dest)) throw new Error(`${o.dest} 已经存在`);
+
+  cpSync(TEMPLATE_DIR, o.dest, { recursive: true });
+
+  const files: string[] = [];
+  for (const file of walk(o.dest)) {
+    if (/\.(png|jpe?g|gif|webp|ico|woff2?)$/i.test(file)) { files.push(file); continue; }
+    let out = readFileSync(file, 'utf8')
+      .replaceAll('__ID__', o.id)
+      .replaceAll('__TITLE__', o.title ?? o.id)
+      .replaceAll('__PASCAL__', pascal(o.id));
+    if (o.gamekitSpec && /package\.json(\.tmpl)?$/.test(file)) {
+      out = out.replace(/("gamekit777"\s*:\s*)"[^"]*"/, `$1${JSON.stringify(o.gamekitSpec)}`);
+    }
+    writeFileSync(file, out);
+    // 模板文件带 .tmpl 后缀，免得脚手架自己的 lint / 构建去处理它们；
+    // .gitignore 叫 _gitignore，因为 npm 打包会把包里的 .gitignore 改名或丢掉
+    let final = file.endsWith('.tmpl') ? file.slice(0, -5) : file;
+    if (final.endsWith('/_gitignore')) final = `${final.slice(0, -'_gitignore'.length)}.gitignore`;
+    if (final !== file) renameSync(file, final);
+    files.push(final);
+  }
+  return { dest: o.dest, files };
+}