a207cb8d65
- .agents/skills 25 件全量 frontmatter 规范化与评审修入(含 prompt-governance 大修);.claude/skills 7 件薄壳按双层方案①落位 - 新增 skill:agentic-seat-context-design(agentic 席位与 context 工程设计基线,2026-07-05 探索蒸馏) - 设计波三件落档:复杂游戏北极星件(W-NSTAR 终审稿待拍)/黄金模板规格件(W-TPL 定稿待批)/生成侧过程蒸馏回路(W-GENLOG 骨架) - protocol/在飞板/作战清单/数据飞轮 SoT/契约 prompts 索引同步;breakout 九门证据刷新 - .gitignore 补 /localagents.md 真实忽略行(该文件自声明绝不提交,此前声明未被机器执行) - 刻意不入库:nacos-data/ 与 _tier2-gen、c2v-*、amgen-* 生成产物(可重生成,忽略行格式待拍) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
162 lines
12 KiB
Markdown
162 lines
12 KiB
Markdown
---
|
||
name: runtime-and-multichannel
|
||
description: "当开发/调试 runtime 编译与包版本化交付、WanxiangGameSDK 注入与降级、iframe 沙箱三容器预加载、或微信/抖音/快手多渠道导出时使用:渲染层 LittleJS 增强发行版、SDK 两层、沙箱安全边界与微信格式导出枢纽。"
|
||
---
|
||
|
||
# 运行时、Game SDK 与多渠道导出手册（runtime-and-multichannel）
|
||
|
||
> 蒸馏来源：`docs/architecture/架构/README.md`（§3.4 Game SDK / §4.2 运行时三容器 / §6.6 运行时与导出选型）、`docs/architecture/架构/13模块.md`（runtime 模块 T-RT-* 技术功能）、`docs/architecture/架构/README.md`（§2 模块地图 / §10.4 LayaAir CLI）。
|
||
> 适用：开发/调试 runtime 模块、WanxiangGameSDK、多渠道（微信/抖音/快手）小游戏导出。
|
||
> 配套：SDK 降级铁律与沙箱安全红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)；工程规范见 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md)；架构全景见 [`../knowledge/product-and-architecture.md`](../knowledge/product-and-architecture.md)；上游生成见 [`./agentic-amodel-generation.md`](./agentic-amodel-generation.md)；契约见 [`./contract-first-development.md`](./contract-first-development.md)。
|
||
> **⚠️ 状态升级（2026-06-12 终裁，取代 2026-06-11 待 spike 表述）**：本手册「自研 Canvas Runtime(<15KB)」相关段落=**1.x 历史口径，渲染层已改判**。现行裁决：
|
||
> - **Tier1 渲染层 = LittleJS 增强发行版 + Runner v2**（2026-06-12 创始人终裁，spike 85/82；Phaser 竞标落选）；「自研轻量 Canvas Runtime / <15KB 体积门」废除（15KB 系 srcdoc 内联架构衍生约束，前提已失效），改三层约束框架（SLO@千元机+4G P75 / B1 gz≤350KB·raw≤1.5MB / 工程增强层）。
|
||
> - **模板 = LittleJS 能力插件/二次开发件**（玩法模板层废除）；粒子/物理/后处理三插件=引擎能力包装层（裁决①2026-06-12），collision/手感=引擎缺件维持自研。
|
||
> - **沙箱 / SDK Core 注入 / 三容器预加载 / 多渠道导出枢纽**章节不受影响，仍现行有效。
|
||
> 单一事实源：[`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §1.1 + `git show 6d2f8789^:docs/agent-specs/_archive/2026-06-11-T1引擎终裁包.md`（已随 _archive 清理删除、git 定位）。下文凡「自研 Canvas<15KB / OpenGame 生成」字样均按本横幅改读。
|
||
> **⚠️ 纠偏（2026-07-05）**：① 编译输入口径改真——runtime 编译输入 = 上游 **src/ 多文件源工程**，产出 **engineBundle（iife、全局 `__GameBundle` 承重）**；`gameConfig` 降为模板玩法参数占位（`contracts/game-package.schema.json` 可核）。② runtime service 真目录 = `service/build/` `service/pkg/` `service/session/`（旧稿 `service/compiler/`、`service/package/` 已不存在）。③ §6 多渠道代码件系（`service/conversion/`、`WechatAdapter`/`DouyinAdapter`/`KuaishouAdapter.java`）**规划中·未实现**——全仓无此源文件，微信格式枢纽策略叙述仍有效。
|
||
|
||
---
|
||
|
||
## 目标
|
||
|
||
把上游 **src/ 多文件源工程**编译为**可运行 Web 包**（engineBundle iife 承重、gameConfig 降为模板玩法参数占位）并版本化交付，注入 WanxiangGameSDK，在 iframe 沙箱中安全运行（三容器预加载），并支持向微信/抖音/快手等小游戏渠道**静态导出**。**产出后游戏流可即点即玩、可分发到外部渠道。**
|
||
|
||
## 前置
|
||
|
||
- OSS（本地 MinIO）+ CDN 可用。Cocos（仅留 3D / 渠道导出、人在环、非分档轴）官方一键导出微信包；LittleJS 线（~~自研 Canvas~~）渠道 adapter 走 W-CH-α 对比竞标（LittleJS+自研 adapter vs Cocos 导出，HJ-CH-001）（见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §1.1）。
|
||
- SDK Core 体积达标（< 8KB 压缩）；上游 aigc 产出的 GamePackage 符合 `game-package.schema.json` 契约。
|
||
|
||
---
|
||
|
||
## 1. runtime 模块职责
|
||
|
||
| 职责 | 说明 |
|
||
|---|---|
|
||
| src/ 源工程 → 可运行 Web 包编译 | `service/build/`：src/ 源工程 + assets → engineBundle（iife 承重）web bundle |
|
||
| Manifest 生成 | runtimeVersion / configUrl / assetList / hash / preloadPolicy / bundleSize |
|
||
| 包存储版本化 | `service/pkg/`：checksum(sha256) + CDN，路径 `/games/{gameId}/versions/{versionId}/` |
|
||
| 预览交付端点 | `controller/app/runtime/`：按版本返回 manifest + 资源 URL（真路径 `GET /app-api/runtime/package/{versionId}?scene=preview`；预览为 `scene` 参数、无独立 `/preview` 路径） |
|
||
| 多渠道转换 | `service/conversion/`（**规划中·未实现**）：以导出微信小游戏格式包为枢纽 → 抖音(自有接口)/快手(微信格式兼容转换)；渠道 adapter 走 W-CH-α 竞标（Cocos 仅留 3D / 渠道导出、人在环，见 §6 与顶部横幅） |
|
||
|
||
渲染层：~~**自研轻量 Canvas Runtime（< 15KB）**~~ → **LittleJS 增强发行版 + Runner v2**（2026-06-12 终裁，见顶部横幅；15KB 红线废除），iframe sandbox + SDK Core 注入，平台完全控制沙箱（沙箱/SDK 注入语义不变；技术决策版 §6.6 的"自研薄壳"结论已被引擎选型取代）。
|
||
|
||
> 本手册聚焦 **Tier1（极轻量 2D，游戏流）**。分层运行时见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §1.1（**正交两轴**：AI 参与深度 Tier0/1/2 与引擎按表现复杂度选 LittleJS/Phaser 是两根正交轴、引擎不是分档轴；Cocos 仅留 3D / 渠道导出轴、编辑器 + 人在环，进不了自治生成轨）。
|
||
|
||
---
|
||
|
||
## 2. 三容器预加载策略
|
||
|
||
参考抖音短视频预加载，只保留前/当/后三个容器（技术决策版 §4.2，详见 Doc B runtime 模块）：
|
||
|
||
```
|
||
[Container N-1] [Container N] [Container N+1]
|
||
(销毁中) (当前播放) (预加载完成)
|
||
```
|
||
|
||
- 当前游戏播放时，**预加载下一款** manifest + 关键资源。
|
||
- 加载**超时则自动跳过**下一款 + 记录 `game_load_failed` + 错误上报降权（详见 Doc B runtime 模块）。
|
||
- 上滑切换：销毁 N-1，N+1 转为当前，再预加载新的 N+1。
|
||
|
||
---
|
||
|
||
## 3. 安全边界
|
||
|
||
| 项 | 配置 | 出处 |
|
||
|---|---|---|
|
||
| iframe sandbox | `sandbox="allow-scripts allow-same-origin"` | 技术决策版 §4.2 |
|
||
| CSP | `script-src 'self'; connect-src 'none'`（游戏内**无网络请求**） | 技术决策版 §4.2 |
|
||
| postMessage 校验 | 来源（origin 白名单）+ schema 双校验，防伪造 | 技术决策版 §4.2，Doc B runtime 模块 |
|
||
| 资源大小 | 总资源 ≤ 10MB，首屏 ≤ 2MB，超限编译失败 | 技术决策版 §4.2，Doc B runtime 模块 |
|
||
|
||
> 游戏 iframe **禁止网络**，所以广告/支付/社交都在宿主侧 iframe 外渲染（见第 4 节）。沙箱逃逸是极高危风险，检测到异常立即销毁 iframe（技术决策版 §8 风险 3）。详细红线见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。
|
||
|
||
---
|
||
|
||
## 4. WanxiangGameSDK
|
||
|
||
SDK 是**平台能力注入游戏的唯一通道**——没有 SDK，平台就是静态文件托管（技术决策版 §3.4）。分两层：
|
||
|
||
```
|
||
Core（内联 < 8KB，游戏启动时加载，异步不阻塞）
|
||
├── Lifecycle ready/started/paused/resumed/completed/error + onPause/onResume
|
||
├── EventBus SDK ↔ 宿主 postMessage 通信
|
||
├── Telemetry 事件批量上报（10 条 / 5s flush，sendBeacon 兜底）
|
||
└── ErrorTrack onerror + unhandledrejection 捕获、去重、不中断游戏
|
||
|
||
Plugin（按需懒加载，首次调用对应 API 时加载，不影响首屏）
|
||
├── Ad 激励视频 / 插屏 / Banner（宿主侧渲染）
|
||
├── Pay 内购 / 打赏触发（宿主侧弹支付 UI）
|
||
├── Social 排行榜 / 好友 / 邀请 / 分享（宿主代理请求）
|
||
└── Storage 云存档 / 进度（失败回退 localStorage）
|
||
```
|
||
|
||
SDK ↔ 宿主 postMessage 协议（消息 `type`）：`init` / `lifecycle` / `telemetry` / `ad` / `pay` / `social` / `storage`。
|
||
|
||
关键决策（技术决策版 §3.4）：
|
||
- **广告与支付在宿主侧（iframe 外）渲染**——因为它们要网络权限，而游戏沙箱无网络。
|
||
- 事件 SDK 内缓冲 10 条 / 5s flush，减少 postMessage 频率、不影响帧率。
|
||
- **降级铁律**：Plugin 层全部 `try-catch` 包裹，异常不向上抛，游戏主循环（requestAnimationFrame）永不被 SDK 阻塞。完整降级表见 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md)。
|
||
|
||
---
|
||
|
||
## 5. SDK 与 runtime 的关系
|
||
|
||
```
|
||
runtime 编译 GamePackage 时：
|
||
1. 把 SDK Core 代码内联进游戏 entry.js 头部
|
||
2. 源工程声明所需 Plugin（ad / pay / social / storage）；gameConfig 降为模板玩法参数占位
|
||
3. manifest.json 记录 SDK 版本号
|
||
4. 宿主据 manifest 决定加载哪些 Plugin chunk
|
||
```
|
||
|
||
游戏代码**不直接引用**广告联盟/支付 SDK——只通过 `sdk.ad.showRewarded()` 等抽象 API 触发，具体实现对游戏透明、由宿主在 iframe 外管理（技术决策版 §3.4）。
|
||
|
||
---
|
||
|
||
## 6. 多渠道导出（构建期静态转换）
|
||
|
||
**构建期静态转换**（非运行时动态适配），导出可异步离线进行、不影响实时预览（技术决策版 §6.6）。
|
||
|
||
**导出枢纽 = 微信小游戏格式包**：
|
||
|
||
| 渠道 | 导出路径 |
|
||
|---|---|
|
||
| 微信 | 引擎/壳导出微信小游戏包（官方格式） |
|
||
| 抖音 | 抖音自有导出接口 |
|
||
| 快手 | **无专用导出接口** → 快手开发者工具"微信格式兼容转换"（基础 API 与微信一致，开放 API 需快手专属代码） |
|
||
|
||
> **快手导出渠道清单不含 LayaAir CLI 路线**：LayaAir 官方平台清单无快手，快手统一走"微信格式包兼容转换"。"统一工具链"实质 = 统一产出微信格式包，再分发抖音/快手。详见 [`../knowledge/tech-decisions.md`](../knowledge/tech-decisions.md) §1.1。
|
||
|
||
**导出工具**：**Cocos（仅留 3D / 渠道导出、人在环）官方一键**导出微信包，LittleJS 线（~~自研 Canvas~~）渠道 adapter 走 W-CH-α 竞标（见顶部横幅）。Java（runtime `service/conversion/`，**规划中·未实现**）设计上统一以 `ProcessBuilder` 调用对应工具 → 异步等待进程 → 产物上传 OSS。
|
||
|
||
渠道适配器（**规划中·未实现**；开发团队版 §2.1 设计，下列 Java 文件全仓尚不存在）各自处理**尺寸 / 资质 / 文案 / 违禁词**：
|
||
- `WechatAdapter.java`（规划中） — 微信小游戏适配规则
|
||
- `DouyinAdapter.java`（规划中） — 抖音小游戏适配规则
|
||
- `KuaishouAdapter.java`（规划中） — 快手适配（微信格式 → 快手兼容转换）
|
||
|
||
> 外部进程调用要按 [`../rules/security-and-reliability.md`](../rules/security-and-reliability.md) 处理超时/失败/重试/产物校验。
|
||
|
||
---
|
||
|
||
## 7. 资源优化
|
||
|
||
| 手段 | 说明 | 出处 |
|
||
|---|---|---|
|
||
| hash 命名长期缓存 | hash 文件名启用 CDN 永久缓存 | Doc B runtime 模块 |
|
||
| WebP/AVIF 转换 | 素材压缩 + 尺寸裁剪降首屏 | Doc B runtime 模块 |
|
||
| CDN 发布刷新 | 发布时刷新需更新的 HTML/Manifest CDN 缓存 | Doc B runtime 模块 |
|
||
| 低端设备降级 | 限制粒子/音频预加载，帧率锁 **30fps** | Doc B runtime 模块 |
|
||
|
||
---
|
||
|
||
## 8. 常见坑
|
||
|
||
| 坑 | 排查 / 应对 |
|
||
|---|---|
|
||
| postMessage 收不到 | 查 iframe **origin 白名单**是否放行 + Console 报错（开发团队版 §9）；确认 schema 校验未误拦 |
|
||
| DevTool import 导出包看着对 | 渠道包**仍需真机验证**（开发者工具 import 不等于真机通过） |
|
||
| 小游戏导出拖慢预览 | 导出可**异步离线**进行，与实时预览解耦，不影响游戏流加载（技术决策版 §6.6） |
|
||
| 首屏超 2MB / 总包超 10MB | 编译门禁直接阻断 + 给优化建议；走 WebP/AVIF + 音频懒加载 |
|
||
| 三容器内存涨 | 严格只保留前/当/后三容器，及时销毁 N-1（技术决策版 §4.2） |
|
||
| 加载卡死无兜底 | 加载超时 5s 自动跳过 + 错误记录 + 降权（技术决策版 §7.2） |
|