diff --git a/docs/superpowers/specs/2026-09-04-framework-subgame-zero-coupling-migration-design.md b/docs/superpowers/specs/2026-09-04-framework-subgame-zero-coupling-migration-design.md index 6c8ddc2..5a32dc2 100644 --- a/docs/superpowers/specs/2026-09-04-framework-subgame-zero-coupling-migration-design.md +++ b/docs/superpowers/specs/2026-09-04-framework-subgame-zero-coupling-migration-design.md @@ -284,6 +284,46 @@ GameHost 生命周期与 GameSession 一致。dispose 后继续调用必须显 子游戏通过 ViewModel 给公共 UI 提供纯数据;禁止查找公共 Prefab 节点、改写组件或依赖节点层级。 +#### 9.2.1 界面所有权判定 + +每个界面区域在实现前必须归入且只能归入以下一种所有权: + +- 平台公共界面:所有游戏语义相同,由 framework 提供完整 Prefab、Presenter 和默认主题。 +- 平台界面扩展槽:主体语义公共,局部展示因玩法不同,由 framework 定义 Slot 和生命周期,游戏提供 Slot 内容。 +- 游戏专属界面:规则、状态和交互都属于玩法,完整放在 `assets/game`,framework 只负责进入、退出和公共遮罩层。 + +禁止把完整公共 Prefab 复制到每款游戏后长期修改。若大多数游戏都必须替换同一公共区域,说明边界划分错误,应把该区域降为 Slot 或重新归类为游戏专属界面。 + +#### 9.2.2 主题解析规则 + +主题只在 Composition Root 创建应用时解析一次,不在运行时切换。解析顺序固定: + +```text +FrameworkThemeDefaults(完整值集) + -> GameThemeDelta(只声明差异) + -> 生成只读 EffectiveTheme +``` + +- `FrameworkThemeDefaults` 是所有公共 Token 的唯一默认来源,必须提供完整值,不允许下游猜默认值。 +- `GameThemeDelta` 只能覆盖公开 Token;出现未知 Token、错误类型或无效资源键时构建失败。 +- `EffectiveTheme` 创建后只读,同一运行周期不可被游戏或 UI 改写。 +- GameEntry 未声明某个可选覆盖,明确表示使用 FrameworkThemeDefaults;这是主题来源定义的合成语义,不属于下游兜底。 +- theme 文件不得 import framework UI 实现或引用公共 Prefab 节点。 + +`SemanticAssetKey` 同样采用完整默认映射 + 游戏差量映射。SDK 中只出现逻辑键和纯数据描述;Cocos UUID、SpriteFrame、Prefab 等引擎对象由 framework 的资源适配器解析,不泄漏到纯 contracts。 + +#### 9.2.3 Extension Slot 契约 + +每个 Slot 必须定义: + +- 稳定 Slot ID 和用途。 +- 输入 ViewModel 的字段、类型和更新时机。 +- 挂载层级、尺寸约束和可见性所有者。 +- create/attach/update/detach/dispose 生命周期。 +- 资源加载和释放责任。 + +游戏只返回自身 Slot 工厂或逻辑资源地址,不获得 framework 父节点之外的节点引用。framework 在 detach/dispose 后不得继续调用 Slot;游戏 Slot 不得访问兄弟 Slot 或公共 Prefab 内部节点。 + ### 9.3 路径覆盖的定位 现有 `assets/game/override` 构建期合成机制保留,用于已迁移皮肤和必须保持 UUID 的资源替换,但定位为兼容通道: @@ -305,6 +345,16 @@ GameHost 生命周期与 GameSession 一致。dispose 后继续调用必须显 - 子游戏私有内容只在 `games//assets/game`。 - 所有工程使用同一 Cocos Creator 版本。 +`templates/game-seed` 是薄模板,不包含 framework 副本。它只包含: + +- Cocos 工程身份和必要 settings。 +- `assets/app/CompositionRoot.ts` 固定组合入口。 +- 可编译的 `assets/game/GameEntry.ts`、空主题差量和游戏目录骨架。 +- framework junction 的预期挂载位置。 +- SDK conformance、import-boundary 和主题校验测试骨架。 + +`new-game` 从薄模板创建工程、生成新 UUID 并建立 junction。模板创建后,游戏团队只维护 `assets/game`;不得在工程内形成第二份 framework 源码。 + ### 10.2 发布期 沿用现有 `build-game ` 和 materialize 思路: @@ -327,6 +377,20 @@ dist//.zip 发布链路不依赖 junction。构建脚本直接从 framework 真源和所选游戏复制实体文件。 +构建步骤和输入所有权固定为: + +1. 根据显式 game name 解析唯一 `games/`,不存在、重复或名称非法立即失败。 +2. 校验宿主与所选游戏 Cocos 版本一致。 +3. 创建 `build-workspace/`;复制所选游戏工程,但跳过 junction、缓存和历史 build。 +4. 从 `YouleNexus/assets/framework` 复制当前 framework 实体文件。 +5. 校验工作区 assets 顶层只包含薄模板允许项、`framework` 和当前 `game`;禁止出现其它游戏目录或入口。 +6. 解析 GameEntry、ThemeDelta、SemanticAssetMap 和 Slot 声明,生成只读有效配置。 +7. 仅在工作区执行 legacy override 合成,随后执行孤儿、尺寸、meta、Spine 和资源键校验。 +8. 调用 Cocos Creator CLI 构建这个自包含工程。 +9. 对实际构建产物执行内容和依赖审计,通过后才生成 ZIP。 + +构建工具不得先把所有游戏聚合到一个 Cocos 工程再依赖引擎裁剪;“其它游戏从未进入构建工作区”是包隔离的第一保证。 + ### 10.3 ZIP 验收 每个 ZIP 必须: @@ -338,12 +402,39 @@ dist//.zip - 包含 `build-info.json`,至少记录 game、framework commit、Cocos 版本、构建时间、目标平台和资源合成摘要。 - 通过资源引用、入口唯一性、脚本编译、敏感文件和其它游戏残留审计。 +`build-info.json` 还应记录: + +- Game SDK contract digest。 +- EffectiveTheme digest。 +- GameEntry route/game identity 摘要。 +- override 命中数量和无效覆盖数量。 +- ZIP 文件清单 digest。 + +Package Audit 至少执行: + +- 输入审计:工作区没有其它 `games/` 的 GameEntry、主题或资源。 +- 入口审计:只有一个有效 GameEntry 和一个 Composition Root。 +- 依赖审计:所有动态资源地址都能在当前 ZIP 解析,不指向远程 framework 或其它游戏。 +- 身份审计:从 monorepo 游戏清单取得其它游戏 key,扫描产物路径、manifest 和配置,不得命中。 +- 完整性审计:ZIP 解压后可从发布入口启动;`build-info.json` 与实际内容 digest 一致。 + +审计失败时不得生成或覆盖正式 dist ZIP;失败产物只保留在明确的临时诊断目录。 + ## 11. framework 升级模型 ### 11.1 普通升级 framework 的代码、公共 Prefab、公共资源和默认主题都在唯一真源修改。只要 Game SDK、ThemeToken、SemanticAssetKey 和 Slot 契约保持兼容,各子游戏源码无需修改,只需分别与新 framework 重新构建 ZIP。 +不同升级类型的影响规则: + +- framework 代码实现:运行 framework 测试、外部黄金回放和全部游戏 conformance;游戏不复制代码。 +- 公共 Prefab 内部结构:只要 ViewModel/Slot 契约不变,游戏不可见;执行公共界面视觉与交互回归。 +- 公共默认资源:重新生成 EffectiveTheme;对所有游戏执行资源键和 legacy override 影响检查。 +- 新增公开 ThemeToken/AssetKey:必须同时在 FrameworkThemeDefaults 提供权威默认值,旧游戏无需修改。 +- 删除或改变公开 Token/AssetKey/Slot:属于破坏性升级,不能作为普通升级合并。 +- Cocos Creator 版本:按 §11.3 整体升级,不允许单个游戏先行长期分叉。 + 升级门禁: ```text @@ -411,6 +502,8 @@ framework tests - ViewModel/Slot contract 测试。 - 资源覆盖和 SemanticAssetKey 完整性检查。 +- ThemeDelta 合成顺序、未知 Token、错误类型和 EffectiveTheme 只读测试。 +- Slot create/attach/update/detach/dispose 顺序与重复销毁测试。 - 已迁移 Prefab 的关键视觉和交互回归。 - 每游戏 Cocos 构建矩阵。 - ZIP 内容、唯一 GameEntry、无其它游戏残留和自包含运行审计。