🧩 客户端统一 SDK（game-sdk.js）与 15 款存量改造

1. 形态与运行环境

• 单文件 game-sdk.js，由合集主包提供，各游戏分包直接引用；独立爆款小游戏内置同一文件。
• 三种运行模式（init 时自动探测）：wx（微信小游戏）/ tt（抖音小游戏）/ h5（浏览器开发调试——现有 demo.html 的运行方式）。h5 模式下云端接口 mock 到 localStorage，因此改造后的游戏仍可直接在浏览器里开发调试，保留当前"单文件 HTML 秒开预览"的开发体验。

2. API 表面（全部能力一屏）

// —— 初始化（登录 + 拉配置 + 拉存档，一次完成）——
await GameSDK.init({ gameId: 'g14_mohei' })
GameSDK.user      // { id, nickname, avatar, isNew }
GameSDK.wallet    // { coin, gem, energy }（只读镜像，变更必走接口）

// —— 云存档（双写：本地即时 + 云端节流）——
const save = await GameSDK.save.load()       // 云优先，失败回退本地缓存
GameSDK.save.patch({ level: 3 })             // 内存+本地即时写，不触网
await GameSDK.save.commit()                  // 上云（节流；关键节点可强制）

// —— 经济 ——
await GameSDK.energy.spend()                 // 开局扣体力 → 返回 sessionToken
await GameSDK.energy.refill('ad')            // 渠道: ad | share | pay | item
await GameSDK.wallet.consume('gem', 10, 'consume_revive')

// —— 双/三通道解锁组件（M4 的 UI 落点）——
const r = await GameSDK.unlock.show({
  scene: 'revive',                           // revive|energy|double|hint|signin_fix…
  channels: ['ad', 'share', 'pay']           // 服务端 configs 可远程增减通道
})                                           // → { ok, channel }

// —— 社交与上报 ——
await GameSDK.lb.submit(score)               // 附带 sessionToken，见 03 §5
await GameSDK.share.ask({ scene: 'revive' }) // 回流发奖模型，见 05
GameSDK.track('game_finish', { score })      // 批量缓冲上报 /events

3. 平台适配层（差异收口点）

4. 云存档双写机制（M1/P11 的客户端半边）

4.1 写路径

game 调 save.patch(delta)
  ├─ 内存态合并 → 本地缓存立即写（掉线也不丢）
  └─ 标记 dirty → 节流器（10s）/ onHide / 关键节点(过关·升级) → PUT /saves
        ├─ 200: version=n+1，清 dirty
        ├─ 1409 冲突: 走合并策略(见 4.2)后重提
        └─ 网络失败: 入离线队列，onShow/网络恢复时重放

4.2 冲突与合并策略

• 触发场景：双设备交替玩、离线进度重放。SDK 默认字段级合并：数值字段取 max（等级/最高分/图鉴计数）、数组集合取并集（图鉴/成就）、其他字段取 updatedAt 新者。
• 游戏可覆盖：GameSDK.save.setMerger((local, remote) => merged)——对有方向性进度的游戏（如赛季内进度）自定义。
• 合并后以服务端返回的新 version 为准；绝不静默丢弃任何一侧的图鉴/成就类数据。

4.3 存档 schema 约定

saves.data = {
  v: 1,                    // 档结构版本（游戏自管迁移）
  core: { ... },           // 玩法进度：关卡/最高分/局内统计（游戏自定义）
  meta: {                  // v2 要求叠加的养成层（结构统一，便于后台读取）
    talents:    { t1: 2, t2: 0 },   // 永久天赋等级
    collection: ["s01", "s03"],     // 图鉴/皮肤已获得
    pity:       { gacha1: 7 }       // 保底计数（P2/R10）
  }
}
// 货币不入档：coin/gem/energy 一律走 wallets（见 02 §4 约定）

5. 存量 15 款：迁移映射表

首次登录时若云端 version=0 且本地存在旧 key，SDK 自动执行「旧档 → 新 schema → 上云 → 本地标记已迁移」。逐款映射：

6. 通用改造五步（每款游戏 0.5–1.5 天）

1. 替换存储：删掉自带的 SAVE_KEY/localStorage 读写，改为 save.load() / save.patch() / save.commit()；按 §5 写一次性迁移函数。
2. 接体力闸门：开局前 energy.spend()；返回 2001（体力不足）时弹 unlock.show({scene:'energy'})。
3. 接近失复活：把现有"激励视频演示位"占位按钮替换为 unlock.show({scene:'revive', channels:['ad','share','pay']})——这就是 v2 M4 双通道 + 05 篇分享通道的接入点。
4. 接排行榜与埋点：结算处 lb.submit(score)；关键事件 track()（事件字典见 05 §5）。
5. 叠 meta 养成层（按下表引擎类型）：天赋树 UI + 图鉴页，数据落 meta.talents / meta.collection，用软货币升级（货币走钱包接口）。

按引擎类型的 meta 层叠加清单（对应 v2 第 6 节）