docs(game): 刷新 Game 模块文档基线

- 更新 Game family README、landing 与 abstractions 页面，补齐声明级 XML inventory 入口 - 修复 Game.Abstractions 页面与当前源码不一致的旧接口摘录，改写为真实契约边界与最小接入路径 - 补充 ai-plan 跟踪与 trace，推进恢复点到 RP-005 并记录验证结果
2026-05-07 00:39:00 +08:00 · 2026-04-23 07:30:03 +08:00 · 2026-04-23 07:30:03 +08:00 · 007c33f772
commit 007c33f772
parent a1dbed3c8d
7 changed files with 232 additions and 100 deletions
--- a/GFramework.Game.Abstractions/README.md
+++ b/GFramework.Game.Abstractions/README.md
@ -131,6 +131,20 @@ Scene 与 UI 路由共享这套基础约定。
 - `Enums/`
  - UI/Scene 转场、UI 层级、输入动作、存储类型等公共枚举

+## XML 覆盖基线
+
+下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 /
+内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。
+
+| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
+| --- | --- | --- | --- |
+| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>`、`ConfigLoadException` | 看配置表注册、读取约定和失败诊断模型 |
+| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>`、`DataRepositoryOptions` | 看业务数据、设置持久化、槽位存档和版本迁移契约 |
+| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置数据、应用语义、迁移接口和内置设置对象 |
+| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、路由、工厂 / root 边界与转场事件模型 |
+| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作与 UI 转场契约 |
+| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry<T>`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 |
+
 ## 最小接入路径

 ### 1. 只想在公共业务层声明游戏对象
--- a/GFramework.Game.SourceGenerators/README.md
+++ b/GFramework.Game.SourceGenerators/README.md
@ -44,6 +44,15 @@ GameProject/

 默认情况下，打包产物会通过 `targets` 把 `schemas/**/*.schema.json` 纳入 `AdditionalFiles`。

+## XML 覆盖基线
+
+下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.SourceGenerators` 做的一轮轻量 XML 盘点结果：只统计公开类型声明是否带 XML 注释，用来建立生成器入口；具体诊断消息、生成输出和兼容性语义仍需要回到源码与测试继续核对。
+
+| 类型族 | 基线状态 | 代表类型 | 阅读重点 |
+| --- | --- | --- | --- |
+| `Config/` | `1/1` 个类型声明已带 XML 注释 | `SchemaConfigGenerator` | 看 schema 到配置类型 / 表包装 / 注册辅助代码的生成入口 |
+| `Diagnostics/` | `1/1` 个类型声明已带 XML 注释 | `ConfigSchemaDiagnostics` | 看生成器会抛出的诊断类别与失败边界 |
+
 ## 最小接入路径

 ```xml
--- a/GFramework.Game/README.md
+++ b/GFramework.Game/README.md
@ -169,6 +169,19 @@

 这两部分一般被上层子系统消费，不是多数项目的第一接入点。

+## XML 覆盖基线
+
+下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game` 做的一轮轻量 XML 盘点结果：只统计公开 /
+内部类型声明是否带 XML 注释，用来建立运行时阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。
+
+| 子系统 | 基线状态 | 代表类型 | 阅读重点 |
+| --- | --- | --- | --- |
+| `Config/` | `26/26` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`ConfigRegistry`、`GameConfigBootstrap`、`YamlConfigSchemaValidator` | 看 YAML 加载、schema 校验、模块接入与热重载边界 |
+| `Data/` `Storage/` `Serializer/` | `8/8` 个类型声明已带 XML 注释 | `DataRepository`、`SaveRepository<TSaveData>`、`UnifiedSettingsDataRepository`、`FileStorage`、`JsonSerializer` | 看持久化布局、槽位存档、统一设置文件和底层序列化 / 存储实现 |
+| `Setting/` | `9/9` 个类型声明已带 XML 注释 | `SettingsModel<TRepository>`、`SettingsSystem`、`SettingsAppliedEvent<T>` | 看初始化、应用、保存、重置等设置生命周期编排 |
+| `Scene/` `UI/` `Routing/` | `10/10` 个类型声明已带 XML 注释 | `SceneRouterBase`、`UiRouterBase`、`SceneTransitionPipeline`、`UiTransitionPipeline`、`RouterBase<TRoute, TContext>` | 看路由基类、转换处理器和项目层需要自己提供的 factory / root 边界 |
+| `Extensions/` `Internal/` `State/` | `3/3` 个类型声明已带 XML 注释 | `DataLocationExtensions`、`VersionedMigrationRunner`、`GameStateMachineSystem` | 看辅助扩展、内部迁移执行逻辑和游戏态状态机封装 |
+
 ## 最小接入路径

 下面按最常见的四种接入目标给出最短路径。
--- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md
+++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md
@ -12,12 +12,12 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-004`
- 当前阶段：`Phase 3 - Cqrs Docs Refresh`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-005`
+- 当前阶段：`Phase 4 - Game Docs Refresh`
 - 当前焦点：
-  - 收口 `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` 的 landing / generator topic / API 入口
+  - 收口 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 README / landing / abstractions / XML inventory
  - 延续 `README / landing / API reference / XML inventory` 的同一治理模板
-  - 为下一波 `Game` family 审计保留统一的恢复模板与验证口径
+  - 把 `Game.Abstractions` 从失真的接口摘录页收敛为真实契约边界页面，并为下一轮巡检保留统一口径

 ## 当前状态摘要

@ -47,6 +47,10 @@
  - 新建 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`，为 `Cqrs.SourceGenerators` 补齐站内专题入口
  - 更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md` 与 VitePress sidebar，使 `Cqrs` family 的 generator 入口可导航
  - 为 `GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs` 与 `GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs` 中缺失的内部类型补齐 XML 注释，使本轮轻量 inventory 达到声明级闭环
+  - 为 `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` 补齐 `Game` family 的类型族级 XML inventory
+  - 为 `docs/zh-CN/game/index.md` 补齐 frontmatter，并增加 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 XML 覆盖基线入口
+  - 将 `docs/zh-CN/abstractions/game-abstractions.md` 从失真的旧接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面
+  - 基于顶层目录轻量盘点确认：`GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2`，当前公开 / 内部类型声明都已带 XML 注释

 ## Inventory（第一版）

@ -54,7 +58,7 @@
 | --- | --- | --- | --- |
 | `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 |
 | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `README / landing / generator topic / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md`、`docs/zh-CN/core/cqrs.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/api-reference/index.md` 已对齐当前源码与测试 | 转入巡检；下一波切到 `Game` family 的 XML / 教程链路审计 |
-| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `已验证` | 根 README、模块 README、`docs/zh-CN/game/**` 和 abstractions 页已存在 | 后续波次补 XML / 教程链路审计 |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/abstractions/game-abstractions.md` 已对齐当前源码与目录基线 | 转入巡检；优先抽查 `config-system`、`scene`、`ui` 与 `source-generators` 交叉链路是否回漂 |
 | `Godot` / `Godot.SourceGenerators` | `已验证` | 上一轮归档 topic 已完成核心 landing / topic / tutorial 校验 | 进入巡检周期，重点看回漂 |
 | `Ecs.Arch` / `Ecs.Arch.Abstractions` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md`、`docs/zh-CN/ecs/**`、`docs/zh-CN/abstractions/ecs-arch-abstractions.md` 已对齐当前源码与测试 | 转入巡检；后续仅在运行时公共 API 变动时补成员级 XML 细审 |
 | `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 |
@ -76,8 +80,8 @@

 - 当前 `Core` / `Core.Abstractions` 只完成了类型族级 XML 基线，不等于成员级契约全审计
  - 缓解措施：后续只在共享抽象或高风险生命周期接口发生改动时补成员级细审，不在本轮扩张范围
- 其他模块族尚未全部建立同粒度的 XML inventory
-  - 缓解措施：按 `Ecs`、`Cqrs`、`Game` 的波次顺序继续推广同一模板
+- `Godot` family 的治理结论主要留在已归档 topic 中，active topic 当前只保留摘要
+  - 缓解措施：后续巡检优先抽查 `Godot` 入口页是否仍与归档结论一致，必要时把关键 XML inventory 摘要迁回 active topic
 - 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂
  - 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源
 - VitePress 页面不能直接链接到 `docs/` 目录之外的模块 `README.md`
@ -138,9 +142,21 @@
 - `cd docs && bun run build`
 - 结果：通过
 - 备注：`2026-04-22` 在 `Cqrs` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败
+- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/game-abstractions.md`
+- 结果：通过
+- 备注：`2026-04-23` 在重写 `Game.Abstractions` 页面后验证通过
+- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md`
+- 结果：通过
+- 备注：`2026-04-23` 在补充 frontmatter 与 XML inventory 后重新验证
+- `python3` 轻量 XML inventory 扫描
+- 结果：通过
+- 备注：`2026-04-23` 确认 `GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2`
+- `cd docs && bun run build`
+- 结果：通过
+- 备注：`2026-04-23` 在 `Game` 波次文档刷新后重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败

 ## 下一步

-1. 切换到 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 波次，按 `Cqrs` 模板核对 README / landing / tutorials / API reference / XML 链路
-2. 评估 `Game` family 当前是否已经具备类型族级 XML inventory，还是仍停留在“README / 页面存在但不可审计”
+1. 进入巡检周期，优先抽查 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的交叉引用是否仍与当前 `Game` family README 对齐
+2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，避免长期治理只依赖 archive 恢复
 3. 在后续环境治理任务中单独处理 `GFramework.Cqrs` 本地 build 的 fallback package folder 阻塞，避免影响后续代码类验证
--- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
+++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
@ -141,3 +141,40 @@

 1. 切换到 `Game` family 波次，按 `Core` / `Ecs` / `Cqrs` 已验证模板继续补 XML inventory 与教程链路
 2. 把 `GFramework.Cqrs` 的本地构建阻塞留给后续环境治理或构建脚本清理，不在本 topic 内扩张为环境修复任务
+
+### 当前恢复点：RP-005
+
+- 完成 `Game` 波次的模块族入口刷新：
+  - 更新 `GFramework.Game/README.md`
+  - 更新 `GFramework.Game.Abstractions/README.md`
+  - 更新 `GFramework.Game.SourceGenerators/README.md`
+  - 更新 `docs/zh-CN/game/index.md`
+  - 重写 `docs/zh-CN/abstractions/game-abstractions.md`
+- 将 `Game` family 从“README / 页面存在但缺少可审计 XML 入口，且 abstractions 页失真”推进到“runtime / abstractions / source generator 都有声明级 XML inventory 与真实采用边界”
+- 基于轻量扫描确认：
+  - `GFramework.Game` 当前类型声明级 XML 覆盖为 `56/56`
+  - `GFramework.Game.Abstractions` 当前类型声明级 XML 覆盖为 `80/80`
+  - `GFramework.Game.SourceGenerators` 当前类型声明级 XML 覆盖为 `2/2`
+
+### 当前决策（RP-005）
+
+- `docs/zh-CN/abstractions/game-abstractions.md` 不再维护虚构接口摘录，而是与源码中的 `Config` / `Data` / `Setting` / `Scene` / `UI` / `Routing` 契约分组保持一致
+- `Game.SourceGenerators` 继续以 `README + docs/zh-CN/game/config-system.md + docs/zh-CN/source-generators/index.md` 组成入口，不额外新增只为凑数量的专题页
+- `docs/zh-CN/game/index.md` 补 frontmatter，并承担 `Game` family 的 XML 基线入口；更细的类型族说明继续留在模块 README 与 abstractions 页
+
+### 当前验证（RP-005）
+
+- 文档校验：
+  - `validate-all.sh docs/zh-CN/abstractions/game-abstractions.md`：通过
+  - `validate-all.sh docs/zh-CN/game/index.md`：通过
+- 轻量 XML inventory：
+  - `GFramework.Game`：`56/56`
+  - `GFramework.Game.Abstractions`：`80/80`
+  - `GFramework.Game.SourceGenerators`：`2/2`
+- 构建校验：
+  - `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
+
+### 下一步
+
+1. 进入 `Game` family 巡检，优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂
+2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，减少对 archive 的依赖
--- a/docs/zh-CN/abstractions/game-abstractions.md
+++ b/docs/zh-CN/abstractions/game-abstractions.md
@ -1,94 +1,122 @@
-# Game Abstractions
-
-> GFramework.Game.Abstractions 游戏模块抽象接口定义
-
-## 概述
-
-GFramework.Game.Abstractions 包含了游戏特定功能的抽象接口，这些接口定义了游戏开发中的通用契约。
-
-## 存档接口
-
-### ISaveSystem
-
-存档系统接口：
-
-```csharp
-public interface ISaveSystem
-{
-    void Save(string slotId, SaveData data);
-    SaveData Load(string slotId);
-    bool HasSave(string slotId);
-    void Delete(string slotId);
-    List<SaveSlotInfo> GetAllSaveSlots();
-}
-```
-
-### ISaveData
-
-存档数据接口：
-
-```csharp
-public interface ISaveData
-{
-    int Version { get; }
-    DateTime Timestamp { get; }
-    void Validate();
-}
-```
-
-## 设置接口
-
-### IGameSettings
-
-游戏设置接口：
-
-```csharp
-public interface IGameSettings
-{
-    AudioSettings Audio { get; }
-    GraphicsSettings Graphics { get; }
-    InputSettings Input { get; }
-    
-    void Save();
-    void Load();
-    void ResetToDefaults();
-}
-```
-
-## 场景管理接口
-
-### ISceneManager
-
-场景管理器接口：
-
-```csharp
-public interface ISceneManager
-{
-    void SwitchScene<TScene>() where TScene : IScene;
-    Task SwitchSceneAsync<TScene>() where TScene : IScene;
-    
-    void PushScene<TScene>() where TScene : IScene;
-    void PopScene();
-    
-    IScene CurrentScene { get; }
-}
-```
-
-### IScene
-
-场景接口：
-
-```csharp
-public interface IScene
-{
-    void OnEnter();
-    void OnExit();
-    void OnUpdate(float delta);
-}
-```
+---
+title: Game Abstractions
+description: GFramework.Game.Abstractions 的契约边界、包关系与 XML 阅读重点。
 ---

-**相关文档**：
+# Game Abstractions

- [Game 概述](../game/index.md)
- [核心抽象](./core-abstractions.md)
+`GFramework.Game.Abstractions` 是 `Game` 运行时的契约包。
+
+它建立在 `GFramework.Core.Abstractions` 之上，负责定义配置、数据、设置、场景、UI、路由、存储和资源注册表相关的接口、
+枚举与事件契约；默认实现、路由基类、YAML 加载器、文件存储和设置 / 存档仓库则在 `GFramework.Game` 中。
+
+如果你要开箱即用地接入游戏运行时能力，应依赖 `GFramework.Game`；如果你在做共享业务层、feature 包、测试替身或引擎适配层，
+才单独消费本包。
+
+## 什么时候单独依赖它
+
+- 你希望公共业务层只依赖 `ISceneRouter`、`IUiRouter`、`ISettingsSystem`、`ISaveRepository<TSaveData>` 这类契约
+- 你要让多个程序集共享 `ISettingsData`、`IData`、`ISceneEnterParam`、`IUiPageEnterParam` 等数据和路由上下文
+- 你需要自己实现 factory、root、存储或配置加载器，但不想把默认运行时一起带进来
+
+## 包关系
+
+- 契约层：`GFramework.Game.Abstractions`
+- 运行时实现：`GFramework.Game`
+- 底层基础契约：`GFramework.Core.Abstractions`
+
+## 契约地图
+
+| 契约族 | 作用 |
+| --- | --- |
+| `Config/` | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>` 和配置失败诊断模型 |
+| `Data/` | `IData`、`IVersionedData`、`IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>` 及数据事件 |
+| `Setting/` | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、设置迁移契约与内置设置数据类型 |
+| `Scene/` | `IScene`、`ISceneRouter`、`ISceneFactory`、`ISceneRoot`、转场处理器与事件 |
+| `UI/` | `IUiPage`、`IUiRouter`、`IUiFactory`、`IUiRoot`、交互配置与 UI 转场选项 |
+| `Routing/` | `IRoute`、`IRouteContext`、`IRouteGuard<TRoute>`，作为 Scene / UI 共享的路由基础约定 |
+| `Storage/` `Asset/` `Enums/` | 文件存储角色、资源注册表，以及转场 / UI 层级 / 输入动作等跨层枚举 |
+
+## XML 覆盖基线
+
+下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 /
+内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要后续 API 波次继续细化。
+
+| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
+| --- | --- | --- | --- |
+| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>`、`ConfigLoadException` | 看配置表注册、只读访问和失败诊断边界 |
+| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>`、`DataRepositoryOptions` | 看业务数据、统一设置文件、槽位存档与迁移契约 |
+| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置生命周期、应用语义、迁移接口和内置设置对象 |
+| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、工厂 / root 边界和转场模型 |
+| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作和 UI 转场契约 |
+| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry<T>`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与共享枚举 |
+
+## 最小接入路径
+
+### 1. 只在公共业务层声明游戏对象
+
+```csharp
+using GFramework.Game.Abstractions.Data;
+using GFramework.Game.Abstractions.Scene;
+using GFramework.Game.Abstractions.UI;
+
+public sealed class GameSaveData : IVersionedData
+{
+    public int Version { get; set; } = 1;
+    public DateTime LastModified { get; set; } = DateTime.UtcNow;
+}
+
+public sealed class GameplayEnterParam : ISceneEnterParam
+{
+    public required string Seed { get; init; }
+}
+
+public sealed class PauseMenuParam : IUiPageEnterParam
+{
+    public bool AllowRestart { get; init; }
+}
+```
+
+### 2. 让 feature 包只依赖抽象
+
+```csharp
+using GFramework.Game.Abstractions.Data;
+using GFramework.Game.Abstractions.Scene;
+
+public sealed class ContinueGameCommandHandler
+{
+    private readonly ISaveRepository<GameSaveData> _saveRepository;
+    private readonly ISceneRouter _sceneRouter;
+
+    public ContinueGameCommandHandler(
+        ISaveRepository<GameSaveData> saveRepository,
+        ISceneRouter sceneRouter)
+    {
+        _saveRepository = saveRepository;
+        _sceneRouter = sceneRouter;
+    }
+}
+```
+
+### 3. 什么时候切到运行时包
+
+下面这些需求都属于 `GFramework.Game` 的职责，而不是本包：
+
+- 使用默认的 `JsonSerializer`、`FileStorage` 或 `ScopedStorage`
+- 使用 `SettingsModel<TRepository>`、`SettingsSystem`、`SaveRepository<TSaveData>` 等默认实现
+- 使用 `YamlConfigLoader`、`GameConfigBootstrap`、`GameConfigModule`
+- 继承 `SceneRouterBase`、`UiRouterBase` 或默认转场处理器基类
+
+## 阅读顺序
+
+1. 先读本页，确认你是否真的只需要契约层
+2. 再看 [`../game/index.md`](../game/index.md) 了解默认运行时怎么组织这些契约
+3. 继续读具体专题页：
+   - [`../game/config-system.md`](../game/config-system.md)
+   - [`../game/data.md`](../game/data.md)
+   - [`../game/setting.md`](../game/setting.md)
+   - [`../game/scene.md`](../game/scene.md)
+   - [`../game/ui.md`](../game/ui.md)
+4. 需要仓库侧入口时，回到：
+   - `GFramework.Game.Abstractions/README.md`
+   - `GFramework.Game/README.md`
--- a/docs/zh-CN/game/index.md
+++ b/docs/zh-CN/game/index.md
@ -1,3 +1,8 @@
+---
+title: Game
+description: GFramework.Game family 的运行时入口、采用顺序与 XML 阅读基线。
+---
+
 # Game

 `Game` 栏目对应 `GFramework.Game` 与 `GFramework.Game.Abstractions` 这层游戏运行时能力。
@ -98,6 +103,16 @@ IStorage storage = new FileStorage("GameData", serializer);
 4. [setting](./setting.md)
 5. [scene](./scene.md) 或 [ui](./ui.md)

+## Game Family XML 覆盖基线
+
+下面这份 inventory 记录的是 `2026-04-23` 对 `Game` family 做的一轮轻量 XML 盘点结果：只统计公开 / 内部类型声明是否带 XML 注释，用来建立 README / landing / API 阅读链路；成员级 `param`、`returns`、`exception` 与生命周期说明仍需要后续波次继续细化。
+
+| 模块 | 基线状态 | 代表类型 | 阅读重点 |
+| --- | --- | --- | --- |
+| `GFramework.Game` | `56/56` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`SettingsModel<TRepository>`、`SceneRouterBase`、`UiRouterBase` | 先看运行时默认实现、配置加载、设置编排和路由基类 |
+| `GFramework.Game.Abstractions` | `80/80` 个类型声明已带 XML 注释 | `IConfigRegistry`、`ISaveRepository<TSaveData>`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 再看契约层边界，决定项目哪些程序集只依赖接口 |
+| `GFramework.Game.SourceGenerators` | `2/2` 个类型声明已带 XML 注释 | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | 最后看 schema 生成入口与诊断模型，确认配置系统的编译期链路 |
+
 ## 与真实接法的关系

 这个栏目以源码、`*.csproj`、模块 `README.md` 与 `ai-libs/` 下已验证的参考接法为准。