@yyyu-star/arcade-kit 0.0.0-stage → 0.10.2

package/src/game.ts

@@ -0,0 +1,200 @@
+/**
+ * 游戏要提供的规则接口，和给游戏自己测"快照多大"的小工具。
+ * 这个文件不依赖 Workers 运行时，游戏的规则测试（普通 Node 里的 vitest）也能直接引用。
+ */
+import { PROTOCOL_VERSION, type RoomInfo, type SeatKind, type WelcomeMsg } from './protocol.js';
+import type { Entropy } from './rng.js';
+
+export type { Entropy } from './rng.js';
+
+/** 开局时房间告诉游戏的（0.3.0）：房主选的选项、每个座位坐的是谁（电脑补满以后；seatCount 以外的座位是 empty）。 */
+export interface RoomSetup<O> {
+  /** options() 校验过的选项；游戏没写 options 时是 undefined */
+  opts: O | undefined;
+  seats: SeatKind[];
+}
+
+/**
+ * 一笔要房间去外面办的事（0.3.0，比如从玩家的钱包扣买入、把筹码结回去），游戏在状态里记着，办完前一直在 effects() 里。
+ * id 在这一局里唯一、不重用：房间可能因为断线、被驱逐把同一笔办两次，办事的一方要按 id 去重（幂等）。
+ * seat 是为谁办：房间把这个座位绑定的 userId 交给 perform（没绑人的电脑座位是 null）。
+ */
+export interface RoomEffect {
+  id: string;
+  seat: number;
+}
+
+/**
+ * 一个游戏的规则，纯函数（浏览器和房间共用，4.3）。S 状态、A 操作、V 某个座位看到的视图。
+ * 房间只通过这些函数碰游戏状态，自己不懂规则。
+ */
+export interface RoomGame<S, A, V, O = unknown, E extends RoomEffect = RoomEffect> {
+  /** 座位数（掼蛋 4） */
+  seats: number;
+  /** 规则版本：开局时记进状态，进行中的牌局按开局时的版本打完（4.3） */
+  rulesVersion: number;
+  /**
+   * 开局（0.2.0 起推荐）：entropy 是房间用 crypto.getRandomValues 现生成的 256 位熵（8 个 u32），只给这一次、房间不存。
+   * 用它当 arcade-kit/rng 的 ChaCha20 密钥发牌；后面每一副也从这把密钥分出的流里取（stream(key, 'deal', 第几副)），
+   * 所以密钥要放进自己的状态——状态只在服务端，view 绝不能带上它。谁拿到密钥谁就知道全桌的牌（9.1）。
+   * 写了 begin，房间就不再调 start
+   */
+  begin?(entropy: Entropy, rulesVersion: number, setup?: RoomSetup<O>): S;
+  /**
+   * @deprecated 0.2.0：32 位种子只有约 43 亿种，玩家拿自己的手牌逐个试，几分钟就能反推出全桌的牌。新游戏写 begin；
+   * 这里只为 0.1.x 的游戏升级 kit 时照常能开局（房间会记一条警告日志），游戏都换成 begin 以后去掉。
+   * 已经开打的房间不会再调开局，按开局时记下的规则版本打完
+   */
+  start(seed: number, rulesVersion: number): S;
+  /** 校验客户端发来的操作的形状，不合格返回 null（不进 apply） */
+  parse(raw: unknown): A | null;
+  /**
+   * 做一步；不合法返回 { error }，状态不变。
+   * error 会原样发给出手的人，所以只能是固定的错误码（小写字母、数字、下划线，最长 32），不能带牌面之类的隐藏信息；
+   * 不合这个格式的一律换成 illegal_move 再发。
+   */
+  apply(state: S, seat: number, action: A): S | { error: string };
+  /** 现在该谁出手；null 表示不在等任何人（比如一局打完）。写了 actors 时房间只看 actors，不再用它 */
+  turn(state: S): number | null;
+  /**
+   * 这一刻可以出手的座位（0.1.1；不写就是 [turn(state)]，和 0.1.0 一样）。多于一个时是"一组"，比如结算页大家点继续：
+   * - 电脑、托管座位由房间立刻用 ai() 代出；真人谁先发都收，不用排队；
+   * - 组里有人出手不重新计时：时限从进入这组时起算，到点对还没出的真人逐个用 timeout() 代出；
+   * - 组里先出手的人改了局面，后出的人照样能出（不判 stale），只有在这组开始之前做的决定才是 stale。
+   * 怎么算"还是同一组"：
+   * - 推荐返回 { seats, group }，group 是这一组的标识（比如 'settle-3'，第几副的结算）：出手前后 group 一样、而且出手的人离开了名单、
+   *   没有新座位加入，才是同一组，否则是新的一手（所以一个人一手的阶段给同一个 group 也没关系，每一手照样重新计时）；
+   * - 只返回座位数组时由房间推断：出手的那个座位离开名单、其他座位原样留着（不多不少）才算同一组。所以组里每个人出手后都要从名单里拿掉。
+   *   这有歧义：[2, 3] 里 2 出完剩 [3]，和"新的一手只有 3 能出"分不清（会被当成同一组），有这种情况的游戏要给 group。
+   * 名单里不合法的座位号、重复的会被忽略。牌局没打完（over 为 false）时名单不能是空的，空了房间按游戏出错处理：记日志、当作打完。
+   */
+  actors?(state: S): number[] | { seats: number[]; group: string };
+  /**
+   * 这一手（或这一组）的时限毫秒（0.1.1；不写、或给的不是正数，就用 RoomLimits.turnMs）。
+   * 按当前局面现算，同一组里要一直给同一个数
+   */
+  turnMs?(state: S): number;
+  /** 这个座位能看到的东西。seat 为 null 是没入座的人，只能给公开信息 */
+  view(state: S, seat: number | null): V;
+  /** 电脑出手（电脑座位、掉线托管），必须合法 */
+  ai(state: S, seat: number): A;
+  /** 超时代出（真人 30 秒没出、掉线时轮到他），只看该座位能看到的；不给就用 ai。被 apply 拒了房间会再用 ai 试一次 */
+  timeout?(state: S, seat: number): A;
+  /** 整场打完了 */
+  over(state: S): boolean;
+  /**
+   * 这一刻是不是一段的结尾，适合收场（0.2.0，可选）：比如掼蛋一副打完、停在结算页。
+   * 当天全站写入到了 stopWrites（meter.ts）时，在打的房间走到这里就停下电脑、把这一步发给大家，然后以 4000 加原因 quota 关房。
+   * 不写的游戏没有"这一段"可等，房间知道要收场时马上关
+   */
+  breakPoint?(state: S): boolean;
+
+  // ---------- 0.3.0：全部可选，不写就和 0.2.0 一样 ----------
+
+  /**
+   * 开局选项：房主发 start 时带的 opts（任意 JSON），在这里校验形状，不合格返回 null（房间回 bad_options、不开局）。
+   * 0.4.0 起也可以开房时就定（acceptCreate 的 options）：开房时校验、存进房间、经 RoomInfo.opts 发给所有人，之后 start 带的不看。
+   * 校验过的选项经 begin 的 setup.opts 交给游戏；游戏要用就放进自己的状态
+   */
+  options?(raw: unknown): O | null;
+  /**
+   * 这一局用几个座位（1 到 seats）：比如德州 2–6 人一桌、座位数按选项定。只用前面这么多个座位，
+   * 开局时只给它们补电脑，后面的座位一直空着、谁也坐不进去；有真人坐在后面的座位上时房间回 seat_closed、不开局。不写就是 seats
+   */
+  seatCount?(opts: O | undefined): number;
+  /**
+   * 开打以后座位换了人（纯函数）：有人坐下或接管电脑的座位（human）、离座交给电脑（ai）。
+   * 和那一步（入座、离座）一起写 1 行。游戏可以借它记"这个座位现在是真人买入的"之类；不需要就不写。
+   * 托管（掉线超过宽限由电脑代打）不算换人，不调它：座位还是那个人的。
+   * 开打后座位绑人，离座的主人回到自己的座位也会以 human 调一次：房间不把 userId 交给规则，游戏按自己的状态判断
+   * （比如这个座位原来就是真人的，就什么都不做）
+   */
+  seated?(state: S, seat: number, kind: 'human' | 'ai'): S;
+  /**
+   * 现在还没办完的对外的事（见 RoomEffect）。房间每一步之后看一眼，把没在办的交给房间子类的 perform 去办，
+   * 办完用 settled 把结果写回状态（1 行）；办失败了按退避重试（用那唯一的闹钟）。结果写回以后这笔就不该再出现在这里
+   */
+  effects?(state: S): E[];
+  /** 一笔对外的事办完了（纯函数）：result 是 perform 的返回值，游戏自己校验。id 已经不在 effects() 里的，房间不会调 */
+  settled?(state: S, id: string, result: unknown): S;
+  /**
+   * 房间要关了（寿命到、没人、额度满、入站用完）：给游戏最后一次机会把要办的事记下来（比如把所有人桌上的筹码结回钱包）。
+   * 写了 effects 才会调。返回的状态里还有 effects 的话，房间先断开所有人、留着存储把它们办完再删；办不完（一直失败）最多等 closingMs
+   */
+  closing?(state: S): S;
+  /**
+   * 不轮流的操作（比如离桌、暂离回来；只是冒个气泡的用 0.6.0 的 emotes，不写存储）：入座的人什么时候都能发，不看轮没轮到他、不判 stale，
+   * 不改这一手的期限和 turnSeq（除非它让该谁出手变了）。照样过 parse、apply，照样占令牌桶和入站额度
+   */
+  free?(action: A): boolean;
+
+  // ---------- 0.3.2 ----------
+
+  /**
+   * 牌局没打完、这一刻谁也不用出手，在等外面的事（0.3.2，可选）：比如德州的牌桌上能打的人不够两个，等有人坐下、补码、从暂离回来，
+   * 或者买入到账。返回 true 时 actors（turn）可以是空的：房间不当作出错，不计时、不驱动电脑、不设这一手的闹钟，一行也不写；
+   * 等到有人发不轮流的操作、座位换人、对外的事办完，牌局变了再看该谁出手。只在没人能出手时才问它；不写就和以前一样，空了按出错处理
+   */
+  waiting?(state: S): boolean;
+
+  // ---------- 0.5.0 ----------
+
+  /**
+   * 这一刻是不是"停一会儿再接着来"（比如一手打完停几秒让大家看清结果，再自动发下一手）：返回要停的毫秒数（正的有限数），不是就返回 null。
+   * 不能等所有人点（有人走开就卡住），也不能指给某个座位计时（电脑、托管的座位会被房间立刻代出，停不住），所以由房间来停。
+   * 只在没人能出手（actors / turn 为空）时才问它，优先于 waiting。停顿从进入这个状态那一刻算（电脑连着出完进来的，从播放完算），
+   * 停顿期间不轮流的操作、座位换人、对外的事办完都不重新计时；按当前局面现算，同一个停顿里要一直给同一个数。
+   * 页面看 RoomInfo.pause.until 画倒计时（这时 RoomInfo.turn 是 null）
+   */
+  pause?(state: S): number | null;
+  /**
+   * 停够了（纯函数）：房间到点用那唯一的闹钟调它做一步（和这一步一起最多写 2 行），比如发下一手；之后电脑照常接着出。
+   * 返回的状态不能还在停（要连着停两段，就在一次 pause 里给总时长）：还在停、或者抛错，房间记日志、不用它的结果，过 60 秒再试。
+   * 写了 pause 就必须写 resume，只写 pause 的当作没有停顿（记一次日志）
+   */
+  resume?(state: S): S;
+
+  // ---------- 0.6.0 ----------
+
+  /**
+   * 快捷短语表有几句（0.6.0，可选）：入座的人可以发 0 到 emotes - 1 的编号，房间只转发给所有人（EmotedMsg），不进状态、不写存储。
+   * 短语的文字、图标由游戏自己在页面里定，房间不知道内容。不写（或不是正整数）就是没有短语，发了回 no_emotes
+   */
+  emotes?: number;
+}
+
+/**
+ * 进房、重连时发的全量快照有多大（字节，取所有座位和"没入座"里最大的那个）。
+ * 重连一律发全量快照（4.5），快照太大会拖慢手机重连、多占出站流量；游戏在自己的测试里挑几个最大的局面断言一个上限。
+ * 座位信息按最坏情况算：全是真人、昵称都是 16 个汉字。
+ */
+export function snapshotBytes<S, A, V, O, E extends RoomEffect>(game: RoomGame<S, A, V, O, E>, state: S): number {
+  const room: RoomInfo = {
+    code: '000000',
+    status: 'playing',
+    seats: Array.from({ length: game.seats }, () => ({ kind: 'human', name: '牌'.repeat(16), away: true, auto: true, reserved: true })),
+    turn: {
+      seat: 0,
+      deadline: 9_999_999_999_999,
+      ...(game.actors ? { seats: Array.from({ length: game.seats }, (_, i) => i) } : {}),
+    },
+    // 停顿和 turn 不会同时有，这里两样都算上，偏大一点（0.5.0）
+    ...(game.pause ? { pause: { until: 9_999_999_999_999 } } : {}),
+  };
+  let max = 0;
+  for (const seat of [null, ...Array.from({ length: game.seats }, (_, i) => i)]) {
+    const msg: WelcomeMsg<V> = {
+      t: 'welcome',
+      v: PROTOCOL_VERSION,
+      minClientVersion: 0,
+      seq: 999_999,
+      you: { seat, bound: seat ?? 0 },
+      room,
+      view: game.view(state, seat),
+      // 有短语的游戏多带一个节奏（0.7.0）
+      ...(game.emotes ? { emote: { ms: 999_999, burst: 99 } } : {}),
+    };
+    max = Math.max(max, new TextEncoder().encode(JSON.stringify(msg)).byteLength);
+  }
+  return max;
+}

package/src/guest.ts

@@ -0,0 +1,122 @@
+/**
+ * 独立模式（0.10.0）：游戏不带平台单独部署（Deploy to Cloudflare、fork）时，没有平台的 /api/me 可问，改认"游客"。
+ *
+ * 什么时候算独立模式（isStandalone）：env 里**没有** ARCADE 绑定，而且 GATE 不是 "login"。
+ * - 有 ARCADE 绑定 = 本站正式环境，行为和 0.9 完全一样，游客 cookie 一律不认（防止有人带一个游客 cookie 绕过登录）；
+ * - 没有 ARCADE 却写了 GATE=login：说明这次部署本该接平台、只是绑定丢了（部署工具出错），按"平台不可用"拒绝（fail-closed），
+ *   不悄悄退成人人可进的游客模式。
+ *
+ * 游客身份：游戏 Worker 自己发一个长期 cookie（HttpOnly、SameSite=Lax、Path=/；https 下是 `__Host-` 前缀加 Secure），
+ * 值是 32 字节 crypto 随机数（base64url）。userId 是值的 SHA-256 取前 128 位（`g:` 开头），不用原值：
+ * userId 会进房间存储、日志，泄露了也拿不到 cookie 本身。昵称默认"游客"加 4 位数字，浏览器可以带一个昵称（cleanNickname 严格清洗）。
+ *
+ * 这个文件不依赖 cloudflare:workers，浏览器也能用（页面可以先用 cleanNickname 检查一遍再提交）。
+ */
+import type { Identity } from './internal.js';
+
+/** 游客 cookie 名字的默认主体；https 下实际名字是 `__Host-kit-guest`。同域的几个游戏共用一个游客身份，想分开就各传 cookie */
+export const GUEST_COOKIE = 'kit-guest';
+
+/** 一年多一点（和平台会话一样长），过期前每次进首页都会被认出来，不续期也够用 */
+const GUEST_MAX_AGE = 34_560_000;
+
+/** 昵称最长几个字（按码点算） */
+export const NICKNAME_MAX = 12;
+
+/**
+ * 默认不许用的昵称词：冒充电脑、系统、管理员，以及"游客"本身（免得冒充别人的默认名"游客1234"）。
+ * 游戏另传自己电脑人物的名字（GuestOptions.reserved），两份合起来查
+ */
+export const RESERVED_NICKNAMES: readonly string[] = ['电脑', '机器人', '人机', '托管', '系统', '管理员', '官方', '客服', '游客', 'ai', 'bot', 'robot', 'cpu', 'admin', 'system'];
+
+export interface GuestOptions {
+  /** cookie 名字的主体（字母、数字、`_`、`-`，最长 32），默认 GUEST_COOKIE；https 下会加 `__Host-` 前缀 */
+  cookie?: string;
+  /** 游戏自己不许用的昵称（电脑人物的名字等），和 RESERVED_NICKNAMES 合起来查 */
+  reserved?: readonly string[];
+}
+
+/** 判断用的 env 字段：ARCADE 绑定在不在、GATE 写的是什么 */
+export interface ModeEnv {
+  ARCADE?: unknown;
+  GATE?: string;
+}
+
+/** 独立模式：没有 ARCADE 绑定、GATE 也不是 "login" */
+export function isStandalone(env: ModeEnv): boolean {
+  return !env.ARCADE && env.GATE !== 'login';
+}
+
+const COOKIE_BASE_RE = /^[A-Za-z0-9_-]{1,32}$/;
+/** 值：我们发的是 32 字节 base64url（43 位）；读的时候只认 22–64 位 base64url，别的一律当没有 */
+const COOKIE_VALUE_RE = /^[A-Za-z0-9_-]{22,64}$/;
+
+/**
+ * 这个请求用的游客 cookie 名字。https 用 `__Host-` 前缀（浏览器保证只能由本站、Path=/、Secure 设置，子域设不进来）；
+ * http 只会是本地开发（wrangler dev 经局域网 IP 打开时浏览器不收 Secure cookie），用不带前缀的名字，两边互不相认
+ */
+export function guestCookieName(request: Request, opts: GuestOptions = {}): string {
+  const base = opts.cookie ?? GUEST_COOKIE;
+  if (!COOKIE_BASE_RE.test(base)) throw new Error(`arcade-kit: bad guest cookie name ${JSON.stringify(base)}`);
+  return isHttps(request) ? `__Host-${base}` : base;
+}
+
+function isHttps(request: Request): boolean {
+  return new URL(request.url).protocol === 'https:';
+}
+
+/** 请求里游客 cookie 的值；没有、格式不对都是 null */
+export function readGuestCookie(request: Request, opts: GuestOptions = {}): string | null {
+  const name = guestCookieName(request, opts);
+  for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+    const i = part.indexOf('=');
+    if (i > 0 && part.slice(0, i).trim() === name) {
+      const v = part.slice(i + 1).trim();
+      return COOKIE_VALUE_RE.test(v) ? v : null;
+    }
+  }
+  return null;
+}
+
+/** 新发一个游客 cookie：返回值和整条 Set-Cookie */
+export function mintGuestCookie(request: Request, opts: GuestOptions = {}): { value: string; setCookie: string } {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  const value = btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  const secure = isHttps(request) ? '; Secure' : '';
+  return { value, setCookie: `${guestCookieName(request, opts)}=${value}; Max-Age=${GUEST_MAX_AGE}; Path=/; HttpOnly; SameSite=Lax${secure}` };
+}
+
+/** cookie 值 → 游客身份：userId = 'g:' + SHA-256 前 128 位（hex），默认昵称"游客"+ 4 位数字；nickname 是清洗过的昵称 */
+export async function guestIdentity(value: string, nickname?: string | null): Promise<Identity> {
+  const hash = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)));
+  const hex = Array.from(hash.subarray(0, 16), (b) => b.toString(16).padStart(2, '0')).join('');
+  const short = String(((hash[16]! << 8) | hash[17]!) % 10_000).padStart(4, '0');
+  return { userId: `g:${hex}`, name: nickname || `游客${short}` };
+}
+
+/** 允许的字：字母（含汉字）、数字，和空格、`_`、`-`、`.`、`·` */
+const NICKNAME_RE = /^[\p{L}\p{N} _\-.·]+$/u;
+
+/**
+ * 清洗浏览器带来的昵称：不合格回 null（调用方用默认的"游客1234"），不报错。
+ * - NFKC 归一（全角、兼容字先折成普通字，免得用全角字母绕过保留词），连续空白并成一个、去掉首尾空白；
+ * - 只许字母（含汉字）、数字和少数几个符号，控制符、零宽字、方向控制符、emoji 一律不行；1 到 NICKNAME_MAX 个字；
+ * - 不能含保留词（RESERVED_NICKNAMES 加游戏传的）：中文等非 ASCII 的词按"包含"查；ASCII 的词按"整个词"查（去掉数字后），
+ *   免得 "Kai" 因为含 "ai" 被拒，但 "AI"、"bot 007" 都会被拒。
+ */
+export function cleanNickname(raw: unknown, reserved: readonly string[] = []): string | null {
+  if (typeof raw !== 'string' || raw.length > 64) return null;
+  const s = raw.normalize('NFKC').replace(/\s+/gu, ' ').trim();
+  const n = [...s].length;
+  if (n < 1 || n > NICKNAME_MAX || !NICKNAME_RE.test(s)) return null;
+  const lower = s.toLowerCase();
+  const compact = lower.replace(/ /g, '');
+  const tokens = lower.split(/[ _\-.·]+/).map((t) => t.replace(/\d+/g, ''));
+  for (const w0 of [...RESERVED_NICKNAMES, ...reserved]) {
+    const w = w0.normalize('NFKC').toLowerCase().replace(/\s+/g, '');
+    if (!w) continue;
+    const ascii = /^[\x00-\x7f]+$/.test(w);
+    if (ascii ? tokens.includes(w) || compact.replace(/\d+/g, '') === w : compact.includes(w)) return null;
+  }
+  return s;
+}

package/src/internal.ts

@@ -0,0 +1,64 @@
+/**
+ * kit 内部用的东西：房间的内部地址、身份头、按房间码取 stub。不在 package.json 的 exports 里，游戏引用不到，
+ * 只能经 worker.ts 的 acceptCreate / acceptJoin 开房进房，没法自己拼内部请求。
+ */
+
+/**
+ * 平台会话 cookie 的名字（docs/platform-backend.md 15.8："平台只读 __Host-sid"）。kit 里只在这里写一次：
+ * 认人时请求里没有它就直接算没登录，不去问平台。
+ */
+export const SESSION_COOKIE = '__Host-sid';
+
+/** 请求的 Cookie 头里有没有非空的平台会话 cookie。 */
+export function hasSessionCookie(cookie: string | null): boolean {
+  if (!cookie) return false;
+  return cookie.split(';').some((part) => {
+    const i = part.indexOf('=');
+    return i > 0 && part.slice(0, i).trim() === SESSION_COOKIE && part.slice(i + 1).trim() !== '';
+  });
+}
+
+/** 游戏 Worker 认出来的人（auth.ts 经平台 /api/me 拿到）。 */
+export interface Identity {
+  userId: string;
+  name: string;
+}
+
+/**
+ * 房间 fetch 只认这个主机名：kit 自己拼的内部地址（acceptJoin）。游戏 Worker 要是把浏览器的原始请求直接转进来，
+ * 地址是站点自己的域名，一律拒绝，浏览器自己带的 x-kit-user 头就不可能被当成身份。
+ */
+export const KIT_HOST = 'arcade-kit.internal';
+
+/** 身份头：JSON 再 URL 编码（昵称是中文，请求头里只放 ASCII）。只有 acceptJoin 拼的内部请求会带它。 */
+export function identityHeader(me: Identity): string {
+  return encodeURIComponent(JSON.stringify({ userId: me.userId, name: me.name }));
+}
+
+export function parseIdentity(raw: string | null): Identity | null {
+  if (!raw) return null;
+  try {
+    const v = JSON.parse(decodeURIComponent(raw)) as Partial<Identity>;
+    return typeof v.userId === 'string' && v.userId && typeof v.name === 'string' ? { userId: v.userId, name: v.name } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 6 位房间码（crypto 随机）。 */
+export function newRoomCode(): string {
+  return String(crypto.getRandomValues(new Uint32Array(1))[0]! % 1_000_000).padStart(6, '0');
+}
+
+/** 房间的 stub：按房间码取，尽量放在亚太（4.1）。 */
+export function roomStub(ns: DurableObjectNamespace, code: string): DurableObjectStub {
+  return ns.get(ns.idFromName(code), { locationHint: 'apac' });
+}
+
+/** 计量的名字：每个游戏 Worker 只有这一个实例（meter.ts）。 */
+export const METER_NAME = 'kit-meter';
+
+/** 计量的 stub：和房间一样放在亚太，开房、报数少绕路。 */
+export function meterStub(ns: DurableObjectNamespace): DurableObjectStub {
+  return ns.get(ns.idFromName(METER_NAME), { locationHint: 'apac' });
+}

package/src/meter.ts

@@ -0,0 +1,255 @@
+/**
+ * 每个游戏 Worker 一个的"计量"（Durable Object，全局只有一个实例，名字固定）：管住免费版每天 10 万行写入（docs/platform-backend.md 4.7）。
+ * 同一个对象里放三样东西，一次 RPC 办完，比"每人一个小 DO + 一个计量"少一次请求、少写建表那几行：
+ * - 当天（UTC）全站的写入行数：房间自己数写了几行，攒够一批（RoomLimits.meterBatch，默认 200）或者结束时报一次；
+ * - 当天全站开了几个房间（最后一道闸）；
+ * - 每个人现在开着的房间、当天开了几个（按人的开房额度）。
+ *
+ * 门槛（QuotaLimits，游戏在 wrangler.jsonc 的 vars.KIT_QUOTA 里改，不用改代码）：
+ * - 写入到 busyWrites（默认 6 万）：不开新房、不进新人，在打的照常；
+ * - 写入到 stopWrites（默认 8.5 万）：在打的房间在这一段结束（RoomGame.breakPoint）时体面收场；
+ * - 开房先过按人额度，再过全站额度。
+ *
+ * 写入：开房（占额度）写 2 行（这个人那一行、当天那一行），报一次写 1 行，结束（还额度加最后一报）写 2 行；计量自己写的也记进当天的数。
+ * 自愈：每个开着的房间记一个"最晚到什么时候"（开房时间 + 房间寿命 + 1 分钟）。房间关的时候来还额度，
+ * 还不上（计量连不上、房间被驱逐时出错）就等到点自动作废，不会把人永远卡在"你已经有一个房间了"。
+ * 当天的数在 UTC 0 点后的第一次调用时清零（和免费版额度重置的时间一样）；房间跨天报上来的写入记在新的一天，偏保守。
+ *
+ * 这里的方法只给 kit 自己调（房间经 RPC），游戏不直接用；kitUsage 给运维和测试看。
+ */
+import { DurableObject } from 'cloudflare:workers';
+import { meterStub } from './internal.js';
+
+export interface QuotaLimits {
+  /** 每人同时开着的房间数（自己开的，打完、关掉、到寿命就还） */
+  roomsPerUser: number;
+  /** 每人每天（UTC）最多开几个房间 */
+  dailyRoomsPerUser: number;
+  /** 全站每天（UTC）最多开几个房间 */
+  dailyRooms: number;
+  /** 当天写入到这么多行：不开新房、不进新人 */
+  busyWrites: number;
+  /** 当天写入到这么多行：在打的房间这一段打完收场 */
+  stopWrites: number;
+}
+
+export const DEFAULT_QUOTA: QuotaLimits = {
+  roomsPerUser: 1,
+  dailyRoomsPerUser: 6,
+  dailyRooms: 300,
+  busyWrites: 60_000,
+  stopWrites: 85_000,
+};
+
+/** KIT_QUOTA 里由房间读的字段（0.7.0）：emoteMs 每多少毫秒补一个短语令牌（0 不限速），emoteBurst 最多攒几个 */
+export const ROOM_QUOTA_FIELDS: readonly string[] = ['emoteMs', 'emoteBurst'];
+
+/** 计量的绑定名和环境变量名固定（和 ROOM、ARCADE 一样）。 */
+export interface MeterEnv {
+  METER?: DurableObjectNamespace;
+  /** 部分覆盖 DEFAULT_QUOTA，比如 { "dailyRooms": 500 }；wrangler.jsonc 的 vars 里写对象，或者写成 JSON 字符串 */
+  KIT_QUOTA?: (Partial<QuotaLimits> & { emoteMs?: number; emoteBurst?: number }) | string;
+}
+
+/** ok 照常；busy 不开新房、不进新人；stop 在打的这一段打完收场。 */
+export type MeterLevel = 'ok' | 'busy' | 'stop';
+
+export type Reserve = { ok: true } | { ok: false; error: 'has_room'; code: string } | { ok: false; error: 'daily_limit' | 'busy' };
+
+export interface Usage {
+  day: string;
+  writes: number;
+  rooms: number;
+  level: MeterLevel;
+  limits: QuotaLimits;
+}
+
+interface UserRow {
+  day: string;
+  /** 当天开了几个 */
+  count: number;
+  /** 开着的房间，until 之后自动作废 */
+  live: { code: string; until: number }[];
+}
+
+/** 房间寿命之外多留一分钟：房间到寿命那一刻的闹钟、关房、还额度都在这之前做完。 */
+const EXPIRY_SLACK_MS = 60_000;
+
+export class RoomMeter extends DurableObject<MeterEnv> {
+  private ready = false;
+  private limitsCache: QuotaLimits | null = null;
+
+  /** 开房前占一个名额（房间调）。房间没建成要调 kitRelease(…, cancel) 退回。 */
+  async kitReserve(userId: string, code: string, until: number): Promise<Reserve> {
+    const now = Date.now();
+    const lim = this.limits();
+    const day = this.day(now);
+    const user = this.user(userId, day.day, now);
+    // 先说"回你的房间"：在打的房间不受全站门槛影响，回去照样能玩
+    if (user.live.length >= lim.roomsPerUser) return { ok: false, error: 'has_room', code: user.live[user.live.length - 1]!.code };
+    if (user.count >= lim.dailyRoomsPerUser) return { ok: false, error: 'daily_limit' };
+    if (levelOf(day.writes, lim) !== 'ok' || day.rooms >= lim.dailyRooms) return { ok: false, error: 'busy' };
+    user.count++;
+    user.live.push({ code, until: until + EXPIRY_SLACK_MS });
+    const w = this.saveUser(userId, user);
+    this.saveDay(day.day, day.writes + w + 1, day.rooms + 1);
+    return { ok: true };
+  }
+
+  /**
+   * 房间结束（打完、关掉）时还名额，顺便报最后一批写入（writes 可以是 0）。cancel：房间没建成，开房次数也退回。
+   * 名额已经不在（还过一次、或者已经到点作废）就只记写入，可以重复调。
+   */
+  async kitRelease(userId: string, code: string, writes: number, cancel = false): Promise<MeterLevel> {
+    const now = Date.now();
+    const day = this.day(now);
+    const user = this.user(userId, day.day, now);
+    const i = user.live.findIndex((r) => r.code === code);
+    let w = 0;
+    if (i >= 0) {
+      user.live.splice(i, 1);
+      if (cancel && user.count > 0) user.count--;
+      w = this.saveUser(userId, user);
+    }
+    const rooms = cancel && i >= 0 ? Math.max(0, day.rooms - 1) : day.rooms;
+    const total = day.writes + clean(writes) + w + 1;
+    this.saveDay(day.day, total, rooms);
+    return levelOf(total, this.limits());
+  }
+
+  /** 报一批写入（房间攒够一批时调），回现在的门槛。 */
+  async kitReport(writes: number): Promise<MeterLevel> {
+    const day = this.day(Date.now());
+    const total = day.writes + clean(writes) + 1;
+    this.saveDay(day.day, total, day.rooms);
+    return levelOf(total, this.limits());
+  }
+
+  /** 只读：现在的门槛（房间放新人进来之前问，不写库）。 */
+  async kitLevel(): Promise<MeterLevel> {
+    return levelOf(this.day(Date.now()).writes, this.limits());
+  }
+
+  /** 只读：当天的数，给运维和测试看。 */
+  async kitUsage(): Promise<Usage> {
+    const day = this.day(Date.now());
+    const limits = this.limits();
+    return { day: day.day, writes: day.writes, rooms: day.rooms, level: levelOf(day.writes, limits), limits };
+  }
+
+  // ---------- 存储 ----------
+
+  private ensure(): void {
+    if (this.ready) return;
+    const sql = this.ctx.storage.sql;
+    // 建表只有第一次真的写（之后 IF NOT EXISTS 什么都不做）；建表那几行记不进当天的数，一个游戏一生只有一次
+    sql.exec('CREATE TABLE IF NOT EXISTS kit_day (k INTEGER PRIMARY KEY, day TEXT NOT NULL, writes INTEGER NOT NULL, rooms INTEGER NOT NULL)');
+    // WITHOUT ROWID：按 userId 存一棵树，改一个人只写 1 行（普通表还要多写一份索引）
+    sql.exec('CREATE TABLE IF NOT EXISTS kit_user (id TEXT PRIMARY KEY, v TEXT NOT NULL) WITHOUT ROWID');
+    this.ready = true;
+  }
+
+  /** 当天那一行；过了 UTC 0 点就是新的一天，从 0 算（不先写，下次保存时一起写）。 */
+  private day(now: number): { day: string; writes: number; rooms: number } {
+    this.ensure();
+    const today = utcDay(now);
+    const row = this.ctx.storage.sql.exec<{ day: string; writes: number; rooms: number }>('SELECT day, writes, rooms FROM kit_day WHERE k = 1').toArray()[0];
+    return row && row.day === today ? row : { day: today, writes: 0, rooms: 0 };
+  }
+
+  private saveDay(day: string, writes: number, rooms: number): void {
+    this.ctx.storage.sql.exec(
+      'INSERT INTO kit_day (k, day, writes, rooms) VALUES (1, ?, ?, ?) ON CONFLICT (k) DO UPDATE SET day = excluded.day, writes = excluded.writes, rooms = excluded.rooms',
+      day,
+      writes,
+      rooms,
+    );
+  }
+
+  /** 这个人那一行：换了一天开房次数清零，到点的房间作废（只在内存里，下次保存时才写）。 */
+  private user(userId: string, today: string, now: number): UserRow {
+    const raw = this.ctx.storage.sql.exec<{ v: string }>('SELECT v FROM kit_user WHERE id = ?', userId).toArray()[0];
+    let row: UserRow = { day: today, count: 0, live: [] };
+    if (raw) {
+      try {
+        row = JSON.parse(raw.v) as UserRow;
+      } catch {
+        console.error('meter user row unreadable', userId);
+      }
+    }
+    return { day: today, count: row.day === today ? row.count : 0, live: row.live.filter((r) => r.until > now) };
+  }
+
+  /** 存这个人那一行，返回写了几行。没有开着的房间、当天也没开过的，删掉这一行，不留着占地方。 */
+  private saveUser(userId: string, row: UserRow): number {
+    const sql = this.ctx.storage.sql;
+    if (row.live.length === 0 && row.count === 0) return sql.exec('DELETE FROM kit_user WHERE id = ?', userId).rowsWritten;
+    return sql.exec('INSERT INTO kit_user (id, v) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET v = excluded.v', userId, JSON.stringify(row)).rowsWritten;
+  }
+
+  /** 门槛按调用时的环境变量算；配错的字段记日志、用默认值（不让一个手误把额度放开或关死）。 */
+  private limits(): QuotaLimits {
+    if (this.limitsCache) return this.limitsCache;
+    this.limitsCache = parseQuota(this.env.KIT_QUOTA);
+    return this.limitsCache;
+  }
+}
+
+/**
+ * 房间以外的 DO（比如游戏自己的钱包）把写了几行记进当天的数，回现在的门槛（0.3.0）。
+ * 计量每收一次报数自己写 1 行，所以只适合写得少的地方（钱包一次操作报一次，就是每次多 1 行）；房间自己会攒一批再报，不用它。
+ * 没绑 METER 时什么都不做、回 ok（和房间一样，只为平滑升级）。连不上时抛错，调用方决定怎么办
+ */
+export async function meterReport(env: MeterEnv, writes: number): Promise<MeterLevel> {
+  if (!env.METER) return 'ok';
+  return (meterStub(env.METER) as DurableObjectStub<RoomMeter>).kitReport(writes);
+}
+
+/** 只读：现在的门槛（0.3.0；写之前问一下，stop 时就别写了）。没绑 METER 回 ok，连不上抛错。 */
+export async function meterLevel(env: MeterEnv): Promise<MeterLevel> {
+  if (!env.METER) return 'ok';
+  return (meterStub(env.METER) as DurableObjectStub<RoomMeter>).kitLevel();
+}
+
+/** 解析 KIT_QUOTA：对象或 JSON 字符串，只认 DEFAULT_QUOTA 里有的字段、非负整数；别的记日志后忽略。 */
+export function parseQuota(raw: unknown): QuotaLimits {
+  let v: unknown = raw;
+  if (typeof raw === 'string') {
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      console.error('KIT_QUOTA is not JSON, using defaults');
+      v = null;
+    }
+  }
+  const out: QuotaLimits = { ...DEFAULT_QUOTA };
+  if (v === undefined || v === null) return out;
+  if (typeof v !== 'object' || Array.isArray(v)) {
+    console.error('KIT_QUOTA is not an object, using defaults');
+    return out;
+  }
+  for (const [k, n] of Object.entries(v)) {
+    // 房间自己读的字段（0.7.0：快捷短语的节奏），计量不管
+    if (ROOM_QUOTA_FIELDS.includes(k)) continue;
+    if (!(k in DEFAULT_QUOTA)) console.error('KIT_QUOTA unknown field', k);
+    else if (typeof n !== 'number' || !Number.isInteger(n) || n < 0) console.error('KIT_QUOTA bad value for', k);
+    else out[k as keyof QuotaLimits] = n;
+  }
+  if (out.stopWrites < out.busyWrites) console.error('KIT_QUOTA stopWrites is below busyWrites');
+  return out;
+}
+
+export function levelOf(writes: number, lim: QuotaLimits): MeterLevel {
+  if (writes >= lim.stopWrites) return 'stop';
+  if (writes >= lim.busyWrites) return 'busy';
+  return 'ok';
+}
+
+function utcDay(now: number): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+/** 房间报上来的行数：只认非负整数（RPC 那头是自己人，这里防的是自己算错） */
+function clean(n: number): number {
+  return Number.isInteger(n) && n > 0 ? n : 0;
+}