@bgnut/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GomuLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @bgnut/cli
+
+桌游匠 BGNut 开发者工具 —— 从零建游戏、本地双人模拟、一键发布到 [BGNut 平台](https://bgnut.gomulabs.com)。零运行时依赖，Node ≥ 20。
+
+```bash
+npx @bgnut/cli <command>
+# 或全局安装后直接用 bgnut
+npm install -g @bgnut/cli
+```
+
+## 命令
+
+### `bgnut init [dir]`
+
+- **空目录**：生成完整脚手架（`index.html` + `game.js` 示例游戏「抢五」+ `bgnut.json`），示例演示了指令同步三步契约，改造它即可。
+- **已有项目**：只生成 `bgnut.json` 接入清单，并打印三步接入说明，不动你的代码。
+
+`bgnut.json`（房间配置的事实来源）：
+
+```json
+{
+  "name": "my-game",
+  "version": "0.1.0",
+  "gameId": null,
+  "multiplayer": true,
+  "maxPlayers": 2,
+  "config": {}
+}
+```
+
+`gameId` 是你在开发者中心创建桌游后管理页的数字 ID；`multiplayer: false` 表示单机游戏（平台不出联机入口，直接试玩）。
+
+### `bgnut dev [--port=4173]`
+
+本地开发服务器：
+
+- `http://localhost:4173/` —— 单机 mock 模式直接玩；
+- `http://localhost:4173/__harness` —— **双窗位模拟对战**：页内 mock 中继，与线上同一套桥协议（同配置 / 同种子 / 全序指令回显），不用连平台就能验证联机逻辑。
+
+游戏内引用的托管 SDK 地址会被自动重写为本地副本，离线可用。
+
+### `bgnut login [--server=...]`
+
+粘贴你在开发者中心「发布令牌」页创建的 `bgp_` 令牌，校验后写入 `~/.bgnutrc`。
+
+### `bgnut doctor`
+
+发布前本地体检：清单字段、入口 `index.html`、包体等。
+
+### `bgnut publish`
+
+按 `bgnut.json` 的 `gameId` + `version` 打 ZIP 并提交平台审核。审核通过即上架、即可联机。
+
+## 典型流程
+
+```bash
+bgnut init my-game && cd my-game
+bgnut dev            # 本地双窗位调联机
+bgnut login          # 一次性
+bgnut publish        # 提审
+```
+
+游戏运行时 API 见 [`@bgnut/sdk`](https://www.npmjs.com/package/@bgnut/sdk)。
+
+## License
+
+MIT © GomuLabs

package/bin/bgnut.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// bgnut —— 桌游匠开发者 CLI（@bgnut/cli）
+// 命令：init [dir] / login [token] / doctor / dev [--port] / publish
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { basename, extname, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { buildZip } from '../lib/zip.mjs';
+
+const PKG_ROOT = resolve(fileURLToPath(import.meta.url), '../..');
+const RC_PATH = join(homedir(), '.bgnutrc');
+const DEFAULT_SERVER = 'https://bgnut.gomulabs.com';
+const SDK_HOSTED = 'https://bgnut-play.gomulabs.com/sdk/v1.js';
+const MAX_ZIP = 20 * 1024 * 1024;
+const IGNORE = new Set(['node_modules', '.git', 'dist-zip', '.DS_Store']);
+
+const [, , cmd, ...args] = process.argv;
+const log = (s) => console.log(s);
+const fail = (s) => {
+  console.error(`✗ ${s}`);
+  process.exit(1);
+};
+
+const readRc = () => {
+  try {
+    return JSON.parse(readFileSync(RC_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+const readManifest = (dir = '.') => {
+  const p = join(dir, 'bgnut.json');
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    fail('bgnut.json 不是合法 JSON');
+  }
+};
+
+function collectFiles(dir, base = dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    if (IGNORE.has(name)) continue;
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) collectFiles(full, base, out);
+    else out.push({ rel: relative(base, full).replaceAll('\\', '/'), full, size: st.size });
+  }
+  return out;
+}
+
+// ---------- init ----------
+async function cmdInit() {
+  const target = resolve(args[0] ?? '.');
+  mkdirSync(target, { recursive: true });
+  const entries = readdirSync(target).filter((n) => !IGNORE.has(n));
+  const attach = entries.length > 0;
+  const name = basename(target);
+
+  if (!attach) {
+    // 空目录：完整脚手架
+    for (const f of ['index.html', 'game.js', 'README.md']) {
+      writeFileSync(join(target, f), readFileSync(join(PKG_ROOT, 'template', f), 'utf8').replaceAll('%%NAME%%', name));
+    }
+    log(`✓ 脚手架已生成：${target}`);
+  } else {
+    log(`目录非空，进入接入模式（不改动你的代码）`);
+    if (!existsSync(join(target, 'index.html'))) {
+      log(`⚠ 未找到 index.html —— 平台要求包根目录必须有 index.html 入口`);
+    }
+  }
+
+  const mfPath = join(target, 'bgnut.json');
+  if (!existsSync(mfPath)) {
+    writeFileSync(
+      mfPath,
+      JSON.stringify({ name, version: '0.1.0', gameId: null, multiplayer: true, maxPlayers: 2, config: {} }, null, 2),
+    );
+    log(`✓ bgnut.json 已生成（发布前在开发者中心创建桌游，把 gameId 填进来）`);
+  }
+
+  if (attach) {
+    log(`\n接入三步合约（详见 README / 平台文档）：`);
+    log(`  1. index.html 引入 SDK：<script src="${SDK_HOSTED}"></script>`);
+    log(`  2. 等 await BGNut.join() 拿到 ctx 再初始化，用 ctx.random() 取代 Math.random()`);
+    log(`  3. 本地操作改为 ctx.send(指令)，在 ctx.onCommand 里统一应用（含自己的回显）`);
+  }
+  log(`\n下一步：bgnut dev 本地模拟对战；bgnut doctor 体检；bgnut publish 发布提审`);
+}
+
+// ---------- login ----------
+async function cmdLogin() {
+  let token = args.find((a) => !a.startsWith('--'));
+  const server = (args.find((a) => a.startsWith('--server='))?.slice(9) ?? readRc()?.server ?? DEFAULT_SERVER).replace(/\/+$/, '');
+  if (!token) {
+    log(`在开发者中心「发布令牌」页创建令牌（bgp_ 开头），粘贴到这里：`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    token = (await rl.question('令牌: ')).trim();
+    rl.close();
+  }
+  if (!token?.startsWith('bgp_')) fail('令牌应以 bgp_ 开头');
+  const res = await fetch(`${server}/api/v1/creator/games`, { headers: { authorization: `Bearer ${token}` } });
+  if (!res.ok) fail(`令牌校验失败（${res.status}）：${(await res.json().catch(() => ({})))?.message ?? '请确认令牌有效且账号具有创作者身份'}`);
+  writeFileSync(RC_PATH, JSON.stringify({ server, token }, null, 2));
+  log(`✓ 已登录 ${server}，凭据存于 ~/.bgnutrc`);
+}
+
+// ---------- doctor ----------
+function cmdDoctor() {
+  const dir = resolve('.');
+  const mf = readManifest(dir);
+  const problems = [];
+  const warns = [];
+  if (!mf) problems.push('缺少 bgnut.json（运行 bgnut init 生成）');
+  if (!existsSync(join(dir, 'index.html'))) problems.push('缺少 index.html（包根目录入口）');
+  if (mf && mf.version && !/^\d+\.\d+\.\d+$/.test(mf.version)) problems.push('bgnut.json.version 须为 x.y.z');
+  if (mf && mf.multiplayer !== false && existsSync(join(dir, 'index.html'))) {
+    const html = readFileSync(join(dir, 'index.html'), 'utf8');
+    if (!html.includes('/sdk/v1.js') && !html.includes('BGNut')) warns.push('联机包未检测到 SDK 引用（三步合约第 1 步）');
+  }
+  const files = collectFiles(dir);
+  const total = files.reduce((s, f) => s + f.size, 0);
+  if (total > MAX_ZIP) problems.push(`内容 ${(total / 1024 / 1024).toFixed(1)}MB 超过 20MB 上限`);
+  for (const f of files) if (f.rel.includes('..') || f.rel.startsWith('/')) problems.push(`非法路径：${f.rel}`);
+
+  log(`文件 ${files.length} 个，共 ${(total / 1024).toFixed(0)} KB`);
+  warns.forEach((w) => log(`⚠ ${w}`));
+  if (problems.length) {
+    problems.forEach((p) => console.error(`✗ ${p}`));
+    process.exit(1);
+  }
+  log('✓ 体检通过，可以 publish');
+}
+
+// ---------- dev ----------
+function cmdDev() {
+  const dir = resolve('.');
+  const port = Number(args.find((a) => a.startsWith('--port='))?.slice(7) ?? 4173);
+  const sdkSource = readFileSync(join(PKG_ROOT, 'template', 'sdk-v1.js'), 'utf8');
+  const harness = readFileSync(join(PKG_ROOT, 'template', 'harness.html'), 'utf8');
+  const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.svg': 'image/svg+xml', '.webp': 'image/webp', '.wasm': 'application/wasm', '.mp3': 'audio/mpeg', '.wav': 'audio/wav' };
+
+  createServer((req, res) => {
+    const url = new URL(req.url, 'http://x');
+    let p = decodeURIComponent(url.pathname);
+    if (p === '/sdk/v1.js') {
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' });
+      return res.end(sdkSource);
+    }
+    if (p === '/__harness') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      return res.end(harness);
+    }
+    if (p === '/') p = '/index.html';
+    const full = join(dir, p.replaceAll('..', ''));
+    if (!existsSync(full) || statSync(full).isDirectory()) {
+      res.writeHead(404);
+      return res.end('not found');
+    }
+    let body = readFileSync(full);
+    const type = MIME[extname(full).toLowerCase()] ?? 'application/octet-stream';
+    // 托管 SDK 地址重写到本地副本：游戏包保持生产 URL，本地开发离线可用
+    if (type.startsWith('text/html')) body = Buffer.from(body.toString('utf8').replaceAll(SDK_HOSTED, '/sdk/v1.js'));
+    res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' });
+    res.end(body);
+  }).listen(port, () => {
+    log(`✓ 本地开发服务已启动`);
+    log(`  单机模式:   http://localhost:${port}/          （SDK 自动进入 mock）`);
+    log(`  双人模拟:   http://localhost:${port}/__harness  （页内 mock 中继，双窗位对战）`);
+  });
+}
+
+// ---------- publish ----------
+async function cmdPublish() {
+  const rc = readRc();
+  if (!rc?.token) fail('未登录：先运行 bgnut login');
+  const dir = resolve('.');
+  const mf = readManifest(dir);
+  if (!mf) fail('缺少 bgnut.json');
+  if (!mf.gameId) fail('bgnut.json.gameId 为空：在开发者中心创建桌游后把 ID 填入');
+  if (!/^\d+\.\d+\.\d+$/.test(String(mf.version))) fail('bgnut.json.version 须为 x.y.z');
+  if (!existsSync(join(dir, 'index.html'))) fail('缺少 index.html');
+
+  const files = collectFiles(dir).map((f) => ({ name: f.rel, data: readFileSync(f.full) }));
+  const zip = buildZip(files);
+  if (zip.length > MAX_ZIP) fail(`包体 ${(zip.length / 1024 / 1024).toFixed(1)}MB 超过 20MB`);
+  log(`打包 ${files.length} 个文件，${(zip.length / 1024).toFixed(0)} KB，提交 v${mf.version} → ${rc.server}`);
+
+  const form = new FormData();
+  form.set('package', new Blob([zip], { type: 'application/zip' }), 'game.zip');
+  form.set('version', String(mf.version));
+  const res = await fetch(`${rc.server}/api/v1/creator/games/${mf.gameId}/package`, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${rc.token}` },
+    body: form,
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) fail(`提交失败（${res.status}）：${body?.message ?? '未知错误'}`);
+  log(`✓ 已提交审核（状态：${body.status ?? 'in_review'}）。通过后自动发布上线。`);
+}
+
+// ---------- 路由 ----------
+const HELP = `bgnut —— 桌游匠开发者 CLI
+
+  bgnut init [dir]        新建脚手架（空目录）/ 接入存量项目（非空目录）
+  bgnut login [token]     用开发者中心的发布令牌登录（--server=... 可选）
+  bgnut doctor            发布前本地体检
+  bgnut dev [--port=4173] 本地开发：单机 mock + 双人模拟 harness
+  bgnut publish           打包 ZIP 并提交审核
+`;
+
+switch (cmd) {
+  case 'init': await cmdInit(); break;
+  case 'login': await cmdLogin(); break;
+  case 'doctor': cmdDoctor(); break;
+  case 'dev': cmdDev(); break;
+  case 'publish': await cmdPublish(); break;
+  default: log(HELP);
+}

package/lib/zip.mjs

@@ -0,0 +1,60 @@
+// 零依赖 ZIP 写入器（stored 无压缩 + 标准 CRC32），供 bgnut publish 打包。
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+export function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** entries: [{name, data:Buffer}] → 标准 ZIP Buffer */
+export function buildZip(entries) {
+  const localParts = [];
+  const cdParts = [];
+  let offset = 0;
+  for (const { name, data } of entries) {
+    const nameBuf = Buffer.from(name.replaceAll('\\', '/'), 'utf8');
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0x0800, 6); // UTF-8 flag
+    local.writeUInt16LE(0, 8); // stored
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    localParts.push(local, nameBuf, data);
+
+    const cd = Buffer.alloc(46);
+    cd.writeUInt32LE(0x02014b50, 0);
+    cd.writeUInt16LE(20, 4);
+    cd.writeUInt16LE(20, 6);
+    cd.writeUInt16LE(0x0800, 8);
+    cd.writeUInt16LE(0, 10);
+    cd.writeUInt32LE(crc, 16);
+    cd.writeUInt32LE(data.length, 20);
+    cd.writeUInt32LE(data.length, 24);
+    cd.writeUInt16LE(nameBuf.length, 28);
+    cd.writeUInt32LE(offset, 42);
+    cdParts.push(cd, nameBuf);
+
+    offset += 30 + nameBuf.length + data.length;
+  }
+  const cd = Buffer.concat(cdParts);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(cd.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  return Buffer.concat([...localParts, cd, eocd]);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@bgnut/cli",
+  "version": "1.0.0",
+  "description": "桌游匠 BGNut 开发者工具：init 脚手架/接入、login（发布令牌）、doctor 校验、dev 本地双人模拟、publish 发布提审",
+  "type": "module",
+  "bin": {
+    "bgnut": "bin/bgnut.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "bgnut",
+    "boardgame",
+    "cli",
+    "桌游"
+  ],
+  "homepage": "https://bgnut.gomulabs.com",
+  "author": "GomuLabs",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/README.md

@@ -0,0 +1,22 @@
+# %%NAME%%
+
+BGNut 桌游项目。三步合约：
+
+1. `index.html` 引入平台 SDK（`https://bgnut-play.gomulabs.com/sdk/v1.js`）；
+2. `await BGNut.join()` 拿到 `ctx` 后再初始化，随机一律用 `ctx.random()`（同种子所有客户端同序列）；
+3. 玩家操作只 `ctx.send(指令)`，状态只在 `ctx.onCommand` 里修改（含自己的回显）——所有客户端沿同一指令流确定性演进。
+
+## 开发
+
+```bash
+bgnut dev        # 单机 mock: /   双人模拟: /__harness
+bgnut doctor     # 发布前体检
+```
+
+## 发布
+
+1. 在开发者中心创建桌游，把 ID 填入 `bgnut.json` 的 `gameId`；
+2. `bgnut login`（令牌在开发者中心「发布令牌」页生成）；
+3. `bgnut publish` 提交审核，通过后自动上线。
+
+`bgnut.json` 说明：`multiplayer: false` 可发布纯单机包；`maxPlayers` 联机人数（2–8）；`config` 会原样下发给所有客户端。

package/template/game.js

@@ -0,0 +1,46 @@
+// %%NAME%% —— BGNut 三步合约示例：轮流 +1，先到 5 获胜
+// 合约：① 引入 SDK ② await BGNut.join() 后再初始化（随机用 ctx.random）
+//      ③ 操作只 send，状态只在 onCommand 里改（含自己的回显，所有客户端同路径演进）
+(async () => {
+  const ctx = await BGNut.join(); // 无宿主时自动单机 mock
+
+  // —— 状态（每个客户端各自持有，靠同一指令流保持一致）——
+  const score = Array.from({ length: Math.max(ctx.maxPlayers, 1) }, () => 0);
+  let turn = Math.floor(ctx.random() * score.length); // 同种子 → 所有客户端算出同一先手
+  let over = false;
+
+  const $ = (id) => document.getElementById(id);
+  function render() {
+    $('board').textContent = score.join(' : ');
+    $('players').textContent = ctx.members.map((m) => `${m.seat === ctx.seat ? '★' : ''}${m.name}${m.online ? '' : '（掉线）'}`).join('  vs  ');
+    $('hint').textContent = over ? '对局结束' : turn === ctx.seat ? '轮到你了' : `等待${ctx.members[turn]?.name ?? '对方'}`;
+    $('act').disabled = over || turn !== ctx.seat;
+  }
+
+  // —— 指令应用（唯一改状态的地方）——
+  function apply(cmd) {
+    if (over || cmd.data !== 'add') return;
+    score[cmd.seat] += 1;
+    if (score[cmd.seat] >= 5) {
+      over = true;
+      if (cmd.seat === ctx.seat) ctx.finish(cmd.seat); // 由获胜方客户端报告
+    } else {
+      turn = (turn + 1) % score.length;
+    }
+    render();
+  }
+
+  ctx.replay.forEach(apply); // 重连/中途加入：先重放历史
+  ctx.onCommand(apply);
+  ctx.onMembers(render);
+  ctx.onPhase(({ phase, winner }) => {
+    if (phase === 'ended') {
+      over = true;
+      $('hint').textContent = winner === ctx.seat ? '你赢了！' : winner === null ? '对局结束' : `${ctx.members[winner]?.name ?? '对方'}获胜`;
+      render();
+    }
+  });
+
+  $('act').onclick = () => ctx.send('add'); // 不直接改状态，等回显
+  render();
+})();

package/template/harness.html

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <title>BGNut 双人模拟 · bgnut dev</title>
+  <style>
+    body { margin: 0; font-family: system-ui, sans-serif; background: #EEEAE1; height: 100vh; display: flex; flex-direction: column; }
+    header { display: flex; align-items: center; gap: 12px; padding: 10px 16px; background: #25634B; color: #fff; font-size: 14px; }
+    header button { font: inherit; padding: 6px 14px; border: 0; border-radius: 6px; cursor: pointer; }
+    main { flex: 1; display: flex; gap: 2px; min-height: 0; }
+    .pane { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+    .pane .tag { padding: 6px 12px; font-size: 12px; font-weight: 600; color: #626C64; background: #F7F5EF; }
+    iframe { flex: 1; border: 0; width: 100%; }
+  </style>
+</head>
+<body>
+  <header>
+    <strong>BGNut 本地双人模拟</strong>
+    <span>页内 mock 中继：同一份配置 / 同一种子 / 全序指令回显</span>
+    <button onclick="restart()">重开一局</button>
+  </header>
+  <main>
+    <div class="pane"><div class="tag">座位 0 · 玩家1</div><iframe id="f0" src="/"></iframe></div>
+    <div class="pane"><div class="tag">座位 1 · 玩家2</div><iframe id="f1" src="/"></iframe></div>
+  </main>
+
+  <script>
+    // 页内 mock 中继：实现与主站对局页相同的 postMessage 桥协议（ADR-0007）
+    const frames = [document.getElementById('f0'), document.getElementById('f1')];
+    const members = [
+      { seat: 0, name: '玩家1', handle: null, avatarUrl: null, online: true },
+      { seat: 1, name: '玩家2', handle: null, avatarUrl: null, online: true },
+    ];
+    let ready, seed, seq, log, ended;
+
+    function reset() {
+      ready = [false, false];
+      seed = (Date.now() % 2147483647) | 0;
+      seq = 0;
+      log = [];
+      ended = false;
+    }
+    reset();
+
+    function post(i, msg) { frames[i].contentWindow.postMessage(msg, '*'); }
+    function initSeat(i) {
+      post(i, { bgnut: 'init', seat: i, members, config: {}, maxPlayers: 2, seed, replay: log.slice() });
+    }
+
+    window.addEventListener('message', (ev) => {
+      const m = ev.data;
+      if (!m || typeof m !== 'object' || !m.bgnut) return;
+      const i = frames.findIndex((f) => f.contentWindow === ev.source);
+      if (i < 0) return;
+      if (m.bgnut === 'ready') {
+        ready[i] = true;
+        if (ready[0] && ready[1]) { initSeat(0); initSeat(1); }
+      } else if (m.bgnut === 'command' && !ended) {
+        const cmd = { seq: ++seq, seat: i, data: m.data };
+        log.push(cmd);
+        post(0, { bgnut: 'command', ...cmd });
+        post(1, { bgnut: 'command', ...cmd });
+      } else if (m.bgnut === 'finish' && !ended) {
+        ended = true;
+        const winner = typeof m.winner === 'number' ? m.winner : null;
+        post(0, { bgnut: 'phase', phase: 'ended', winner });
+        post(1, { bgnut: 'phase', phase: 'ended', winner });
+      }
+    });
+
+    function restart() {
+      reset();
+      frames.forEach((f) => { f.src = f.src; });
+    }
+  </script>
+</body>
+</html>

package/template/index.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>%%NAME%%</title>
+  <style>
+    body { margin: 0; font-family: system-ui, sans-serif; background: #F7F5EF; color: #202A25;
+           display: flex; flex-direction: column; align-items: center; gap: 16px; padding: 32px 16px; }
+    button { font: inherit; padding: 10px 24px; border: 0; border-radius: 8px; background: #25634B; color: #fff; cursor: pointer; }
+    button:disabled { opacity: .5; cursor: not-allowed; }
+    #players { color: #626C64; font-size: 14px; }
+    #board { font-size: 40px; font-weight: 700; font-variant-numeric: tabular-nums; }
+  </style>
+</head>
+<body>
+  <h1>%%NAME%%</h1>
+  <div id="players">连接中…</div>
+  <div id="board">0 : 0</div>
+  <div id="hint"></div>
+  <button id="act">+1</button>
+
+  <!-- 运行时以平台托管 SDK 为准；bgnut dev 会自动重写为本地副本 -->
+  <script src="https://bgnut-play.gomulabs.com/sdk/v1.js"></script>
+  <script src="./game.js"></script>
+</body>
+</html>

package/template/sdk-v1.js

@@ -0,0 +1,153 @@
+/*!
+ * BGNut SDK v1 —— 桌游匠联机运行时桥（ADR-0007 指令中继模型）
+ * 唯一事实来源：packages/sdk/sdk.js
+ * 托管副本：bgnut-site/public/sdk/v1.js（node scripts/sync-sdk.mjs 同步，禁止直接改副本）
+ *
+ * 游戏三步合约：
+ *   1. 引入本 SDK；
+ *   2. const ctx = await BGNut.join() 后再初始化（用 ctx.random() 取代 Math.random）；
+ *   3. 本地操作一律 ctx.send(指令)，在 ctx.onCommand 里统一应用（含自己的回显）。
+ *
+ * 无宿主（直接打开页面 / 审核初玩）时自动进入单机 mock 模式。
+ */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.BGNut = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  // 确定性 PRNG（mulberry32）——同种子必同序列
+  function mulberry32(seed) {
+    var a = seed >>> 0;
+    return function () {
+      a |= 0;
+      a = (a + 0x6d2b79f5) | 0;
+      var t = Math.imul(a ^ (a >>> 15), 1 | a);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  function makeEmitter() {
+    var handlers = [];
+    return {
+      on: function (fn) {
+        handlers.push(fn);
+        return function () {
+          var i = handlers.indexOf(fn);
+          if (i >= 0) handlers.splice(i, 1);
+        };
+      },
+      emit: function (payload) {
+        for (var i = 0; i < handlers.length; i++) {
+          try {
+            handlers[i](payload);
+          } catch (e) {
+            console.error('[BGNut] 回调异常:', e);
+          }
+        }
+      },
+    };
+  }
+
+  function buildCtx(init, post) {
+    var commandEv = makeEmitter();
+    var membersEv = makeEmitter();
+    var phaseEv = makeEmitter();
+    var ctx = {
+      /** 我的座位号（0 起） */
+      seat: init.seat,
+      /** 成员列表 [{seat,name,handle,avatarUrl,online}] */
+      members: init.members,
+      /** 房间配置（bgnut.json manifest.config，所有客户端一致） */
+      config: init.config || {},
+      maxPlayers: init.maxPlayers,
+      /** 共享随机种子 */
+      seed: init.seed,
+      /** 开局历史指令（重连/中途加载时先按序应用它，再监听 onCommand） */
+      replay: init.replay || [],
+      /** 确定性随机（种子驱动，所有客户端同序列） */
+      random: mulberry32(init.seed),
+      /** 发送指令：服务器定序后广播给所有人（含自己） */
+      send: function (data) {
+        post({ bgnut: 'command', data: data });
+      },
+      /** 报告对局结束（首个报告生效） */
+      finish: function (winner) {
+        post({ bgnut: 'finish', winner: typeof winner === 'number' ? winner : null });
+      },
+      /** 新指令（含自己的回显）：cb({seq, seat, data}) */
+      onCommand: commandEv.on,
+      /** 成员变化（上线/掉线/加入）：cb(members) */
+      onMembers: membersEv.on,
+      /** 阶段变化：cb({phase:'playing'|'ended', winner}) */
+      onPhase: phaseEv.on,
+      _dispatch: { command: commandEv.emit, members: membersEv.emit, phase: phaseEv.emit },
+    };
+    return ctx;
+  }
+
+  // ---------- 桥模式（在主站对局页 iframe 中） ----------
+  function joinViaBridge() {
+    return new Promise(function (resolve) {
+      var ctx = null;
+      window.addEventListener('message', function (ev) {
+        var m = ev.data;
+        if (!m || typeof m !== 'object' || !m.bgnut) return;
+        if (m.bgnut === 'init' && !ctx) {
+          ctx = buildCtx(m, function (out) {
+            window.parent.postMessage(out, '*');
+          });
+          resolve(ctx);
+        } else if (ctx) {
+          if (m.bgnut === 'command') ctx._dispatch.command({ seq: m.seq, seat: m.seat, data: m.data });
+          else if (m.bgnut === 'members') {
+            ctx.members = m.members;
+            ctx._dispatch.members(m.members);
+          } else if (m.bgnut === 'phase') ctx._dispatch.phase({ phase: m.phase, winner: m.winner });
+        }
+      });
+      window.parent.postMessage({ bgnut: 'ready' }, '*');
+    });
+  }
+
+  // ---------- 单机 mock 模式（无宿主：本地直开 / 审核初玩 / bgnut dev 单窗） ----------
+  function joinMock() {
+    var seq = 0;
+    var ctx = buildCtx(
+      {
+        seat: 0,
+        members: [{ seat: 0, name: '本地玩家', handle: null, avatarUrl: null, online: true }],
+        config: {},
+        maxPlayers: 1,
+        seed: (Date.now() % 2147483647) | 0,
+        replay: [],
+      },
+      function (out) {
+        if (out.bgnut === 'command') {
+          seq += 1;
+          var cmd = { seq: seq, seat: 0, data: out.data };
+          setTimeout(function () {
+            ctx._dispatch.command(cmd);
+          }, 0);
+        } else if (out.bgnut === 'finish') {
+          setTimeout(function () {
+            ctx._dispatch.phase({ phase: 'ended', winner: out.winner });
+          }, 0);
+        }
+      },
+    );
+    console.info('[BGNut] 无宿主环境，进入单机 mock 模式');
+    return Promise.resolve(ctx);
+  }
+
+  var joined = null;
+  return {
+    version: '1.0.0',
+    /** 加入对局：返回 ctx。桥模式等待宿主 init；无宿主自动单机 mock。 */
+    join: function () {
+      if (!joined) joined = window.parent !== window ? joinViaBridge() : joinMock();
+      return joined;
+    },
+  };
+});