diff --git a/GFramework.Godot.SourceGenerators/README.md b/GFramework.Godot.SourceGenerators/README.md
index 2e83adb3..84cd6d95 100644
--- a/GFramework.Godot.SourceGenerators/README.md
+++ b/GFramework.Godot.SourceGenerators/README.md
@@ -1,165 +1,145 @@
 # GFramework.Godot.SourceGenerators
 
-面向 Godot 场景的源码生成扩展模块，减少模板代码。
+`GFramework.Godot.SourceGenerators` 负责把 Godot 项目里的重复样板迁移到编译期。
 
-## 主要功能
+当前包覆盖三类核心场景：
 
-- 与 Godot 场景相关的编译期生成能力
-- 基于 Roslyn 的增量生成器实现
-- `project.godot` 项目元数据生成，产出 AutoLoad 与 Input Action 的强类型访问入口
-- `[GetNode]` 字段注入，减少 `_Ready()` 里的 `GetNode<T>()` 样板代码
-- `[BindNodeSignal]` 方法绑定，减少 `_Ready()` / `_ExitTree()` 中重复的事件订阅样板代码
+- `project.godot` 元数据入口：生成 `AutoLoads` 与 `InputActions`
+- 节点字段与信号接线：`[GetNode]`、`[BindNodeSignal]`
+- Scene / UI 与启动注册样板：`[AutoScene]`、`[AutoUiPage]`、`[AutoRegisterExportedCollections]`
 
-## 使用建议
+它是 Analyzer 包，不是运行时库。
 
-- 仅在 Godot + C# 项目中启用
-- 非 Godot 项目可只使用 GFramework.SourceGenerators
-- 当项目通过 NuGet 包引用本模块时，根目录下的 `project.godot` 会被自动加入 `AdditionalFiles`
-- 当项目通过 `ProjectReference(OutputItemType=Analyzer)` 直接引用生成器时，需要手动把 `project.godot` 加入
-  `AdditionalFiles`
+## 包定位
 
-## project.godot 集成
+当前生成器主要减少这些重复代码：
 
-默认情况下，生成器会读取 Godot 项目根目录下的 `project.godot`，并生成：
+- 从 `project.godot` 手写 AutoLoad / Input Action 字符串
+- 在 `_Ready()` 里重复写 `GetNode<T>()`
+- 在 `_Ready()` / `_ExitTree()` 里重复写 CLR event 订阅与解绑
+- 为 Godot 场景根节点和页面根节点重复声明 `GetScene()` / `GetPage()` 样板
+- 在启动入口里重复遍历导出集合并逐项注册到 registry
+
+它不负责：
+
+- 提供运行时 Scene / UI / 配置实现
+- 自动接管完整生命周期方法
+- 代替 `GFramework.Godot` 的宿主适配逻辑
+
+## 与相邻包的关系
+
+- `GFramework.Godot`
+  - 负责 Godot 运行时适配。
+  - 本包只负责编译期入口和样板生成。
+- `GFramework.Godot.SourceGenerators.Abstractions`
+  - 特性定义所在位置。
+  - 当前 `IsPackable=false`，按内部支撑模块处理，不作为独立消费包推广。
+- `GFramework.SourceGenerators.Common`
+  - 提供公共生成器基础设施与部分类级诊断支持。
+  - 同样按内部支撑模块处理。
+
+## 子系统地图
+
+### `GodotProjectMetadataGenerator`
+
+读取 `project.godot`，生成：
 
 - `GFramework.Godot.Generated.AutoLoads`
 - `GFramework.Godot.Generated.InputActions`
 
-如果你需要覆盖默认项目文件路径，可以在 MSBuild 中设置：
+这是项目级元数据入口，不处理节点字段注入或信号绑定。
 
-- 路径可以调整到项目根目录下的其他位置
-- 文件名必须仍然是 `project.godot`，否则生成器会发出警告并忽略该文件
+### `GetNodeGenerator` 与 `BindNodeSignalGenerator`
 
-```xml
-<PropertyGroup>
-  <GFrameworkGodotProjectFile>Config/project.godot</GFrameworkGodotProjectFile>
-</PropertyGroup>
-```
+- `[GetNode]` 负责生成节点字段注入代码
+- `[BindNodeSignal]` 负责生成 CLR event 绑定 / 解绑辅助方法
 
-如果你在仓库内通过 analyzer 形式直接引用本项目，则需要显式配置：
+这两项能力通常一起使用，但职责不同：
+
+- `[GetNode]` 解决“怎么拿到字段实例”
+- `[BindNodeSignal]` 解决“字段可用后怎么订阅 / 解绑事件”
+
+### `Behavior/`
+
+- `AutoSceneGenerator`
+- `AutoUiPageGenerator`
+
+用于给场景根节点和 UI 页面根节点生成稳定的 `GetScene()` / `GetPage()` 包装入口。
+
+### `Registration/`
+
+- `AutoRegisterExportedCollectionsGenerator`
+
+用于把“遍历导出集合并逐项调用 registry 方法”的启动样板收敛成生成方法。
+
+### `Diagnostics/`
+
+当前诊断围绕这些方向组织：
+
+- `project.godot` 文件与元数据约束
+- `GetNode` / `BindNodeSignal` 的目标成员合法性
+- `AutoScene` / `AutoUiPage` 的宿主类型与参数合法性
+- 导出集合注册的成员形状与方法匹配约束
+
+## 最小接入路径
+
+### 1. 安装生成器包
+
+常规 NuGet 引用方式：
 
 ```xml
 <ItemGroup>
+  <PackageReference Include="GeWuYou.GFramework.Godot.SourceGenerators"
+                    Version="x.y.z"
+                    PrivateAssets="all"
+                    ExcludeAssets="runtime" />
+</ItemGroup>
+```
+
+通常还会同时引用：
+
+```xml
+<PackageReference Include="GeWuYou.GFramework.Godot" Version="x.y.z" />
+```
+
+### 2. 让 `project.godot` 进入 `AdditionalFiles`
+
+通过 NuGet 包使用时，`GeWuYou.GFramework.Godot.SourceGenerators.targets` 会自动尝试把项目根目录下的 `project.godot`
+加入 `AdditionalFiles`。
+
+如果你是仓库内直接通过 `ProjectReference(OutputItemType=Analyzer)` 引用生成器项目，需要手动加入：
+
+```xml
+<ItemGroup>
+  <ProjectReference Include="..\GFramework.Godot.SourceGenerators\GFramework.Godot.SourceGenerators.csproj"
+                    OutputItemType="Analyzer"
+                    ReferenceOutputAssembly="false" />
   <AdditionalFiles Include="project.godot" />
 </ItemGroup>
 ```
 
-## AutoLoad 强类型访问
+### 3. 在节点脚本里显式接生成方法
 
-当某个 AutoLoad 无法仅靠类型名唯一推断到 C# 节点类型时，可以使用 `[AutoLoad]` 显式声明映射：
+当前最重要的生命周期约束是：
+
+- `[GetNode]` 在类型手写 `_Ready()` 时，需要显式调用 `__InjectGetNodes_Generated()`
+- `[BindNodeSignal]` 在手写 `_Ready()` / `_ExitTree()` 时，需要显式调用
+  `__BindNodeSignals_Generated()` 与 `__UnbindNodeSignals_Generated()`
+- `[AutoScene]`、`[AutoUiPage]`、`[AutoRegisterExportedCollections]` 都只生成辅助入口，不会替你织入生命周期
+
+也就是说，本包负责生成辅助方法，但调用时机仍由项目侧决定。
+
+最小接法可以直接写成：
 
 ```csharp
 using GFramework.Godot.SourceGenerators.Abstractions;
 using Godot;
 
-[AutoLoad("GameServices")]
-public partial class GameServices : Node
-{
-}
-```
-
-对应 `project.godot`：
-
-```ini
-[autoload]
-GameServices="*res://autoload/game_services.tscn"
-AudioBus="*res://autoload/audio_bus.gd"
-```
-
-生成器会产出统一入口：
-
-```csharp
-using GFramework.Godot.Generated;
-
-var gameServices = AutoLoads.GameServices;
-
-if (AutoLoads.TryGetAudioBus(out var audioBus))
-{
-}
-```
-
-- 显式 `[AutoLoad]` 映射优先于隐式类型名推断
-- 若同名映射冲突，生成器会给出诊断并退化为 `Godot.Node` 访问
-- 若无法映射到 C# 节点类型，仍会生成可用的 `Godot.Node` 访问器
-
-## Input Action 常量生成
-
-`project.godot` 的 `[input]` 段会自动生成稳定常量，避免手写字符串：
-
-```ini
-[input]
-move_up={
-}
-ui_cancel={
-}
-```
-
-```csharp
-using GFramework.Godot.Generated;
-
-if (Input.IsActionJustPressed(InputActions.MoveUp))
-{
-}
-```
-
-- 动作名会转换为可补全的 C# 标识符，例如 `move_up -> MoveUp`
-- 当多个动作名映射到同一标识符时，会追加稳定后缀并给出警告
-
-## GetNode 用法
-
-```csharp
-using GFramework.Godot.SourceGenerators.Abstractions;
-using Godot;
-
-public partial class TopBar : HBoxContainer
-{
-    [GetNode]
-    private HBoxContainer _leftContainer = null!;
-
-    [GetNode]
-    private HBoxContainer _rightContainer = null!;
-
-    public override void _Ready()
-    {
-        __InjectGetNodes_Generated();
-        OnReadyAfterGetNode();
-    }
-
-    private void OnReadyAfterGetNode()
-    {
-    }
-}
-```
-
-当未显式填写路径时，生成器会默认将字段名推导为唯一名路径：
-
-- `_leftContainer` -> `%LeftContainer`
-- `m_rightContainer` -> `%RightContainer`
-
-## BindNodeSignal 用法
-
-```csharp
-using GFramework.Godot.SourceGenerators.Abstractions;
-using Godot;
-
-public partial class Hud : Control
+public partial class MainMenu : Control
 {
     [GetNode]
     private Button _startButton = null!;
 
-    [GetNode]
-    private SpinBox _startOreSpinBox = null!;
-
-    [BindNodeSignal(nameof(_startButton), nameof(Button.Pressed))]
-    private void OnStartButtonPressed()
-    {
-    }
-
-    [BindNodeSignal(nameof(_startOreSpinBox), nameof(SpinBox.ValueChanged))]
-    private void OnStartOreValueChanged(double value)
-    {
-    }
-
     public override void _Ready()
     {
         __InjectGetNodes_Generated();
@@ -170,12 +150,56 @@ public partial class Hud : Control
     {
         __UnbindNodeSignals_Generated();
     }
+
+    [BindNodeSignal(nameof(_startButton), nameof(Button.Pressed))]
+    private void OnStartPressed()
+    {
+    }
 }
 ```
 
-生成器会产出两个辅助方法：
+### 4. 按场景选特性
 
-- `__BindNodeSignals_Generated()`：负责统一订阅事件
-- `__UnbindNodeSignals_Generated()`：负责统一解绑事件
+- 项目级元数据：
+  - `project.godot` -> `AutoLoads`、`InputActions`
+- 固定节点字段：
+  - `[GetNode]`
+- 固定 CLR event 订阅：
+  - `[BindNodeSignal]`
+- Godot 场景根节点：
+  - `[AutoScene]`
+- Godot UI 页面根节点：
+  - `[AutoUiPage]`
+- 启动入口中的集合批量注册：
+  - `[AutoRegisterExportedCollections]`
 
-当前设计只处理 CLR event 形式的 Godot 事件绑定，不会自动调用 `Connect()` / `Disconnect()`。
+## 当前约束
+
+- `GFrameworkGodotProjectFile` 可以改相对路径，但文件名必须仍然是 `project.godot`
+- `[GetNode]` 与 `[BindNodeSignal]` 都要求宿主类型是顶层 `partial class`
+- `[BindNodeSignal]` 面向 CLR event，不会自动调用 `Connect()` / `Disconnect()`
+- `[AutoScene]` 与 `[AutoUiPage]` 只生成行为包装入口，不会替代 `SceneRouterBase` 或 `UiRouterBase`
+- `[AutoRegisterExportedCollections]` 只适合“集合 -> registry -> 单参数注册方法”这类稳定形状
+
+## 文档入口
+
+- 生成器总览：[docs/zh-CN/source-generators/index.md](../docs/zh-CN/source-generators/index.md)
+- Godot 项目元数据：[docs/zh-CN/source-generators/godot-project-generator.md](../docs/zh-CN/source-generators/godot-project-generator.md)
+- `GetNode`：[docs/zh-CN/source-generators/get-node-generator.md](../docs/zh-CN/source-generators/get-node-generator.md)
+- `BindNodeSignal`：[docs/zh-CN/source-generators/bind-node-signal-generator.md](../docs/zh-CN/source-generators/bind-node-signal-generator.md)
+- `AutoScene`：[docs/zh-CN/source-generators/auto-scene-generator.md](../docs/zh-CN/source-generators/auto-scene-generator.md)
+- `AutoUiPage`：[docs/zh-CN/source-generators/auto-ui-page-generator.md](../docs/zh-CN/source-generators/auto-ui-page-generator.md)
+- `AutoRegisterExportedCollections`：[docs/zh-CN/source-generators/auto-register-exported-collections-generator.md](../docs/zh-CN/source-generators/auto-register-exported-collections-generator.md)
+- Godot 运行时入口：[../GFramework.Godot/README.md](../GFramework.Godot/README.md)
+- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md)
+
+## 什么时候不该先看这个包
+
+以下场景更适合先回到其他入口：
+
+- 你在确认 Godot 运行时 Scene / UI / 存储 / 设置的默认实现：
+  - 先看 `GFramework.Godot`
+- 你只需要 `Game` 契约，不需要 Godot 宿主或生成器：
+  - 先看 `GFramework.Game` 或 `GFramework.Game.Abstractions`
+- 你在确认项目接线顺序，而不是单个生成器契约：
+  - 先看 `docs/zh-CN/tutorials/godot-integration.md`
diff --git a/GFramework.Godot/README.md b/GFramework.Godot/README.md
index e19f4ae6..eaaf856e 100644
--- a/GFramework.Godot/README.md
+++ b/GFramework.Godot/README.md
@@ -1,19 +1,161 @@
 # GFramework.Godot
 
-GFramework 框架的 Godot 引擎集成模块，提供Godot特定的功能和扩展。
+`GFramework.Godot` 是 `GFramework` 在 Godot 宿主侧的运行时适配包。
 
-## 主要功能
+它建立在 `GFramework.Game`、`GFramework.Game.Abstractions` 与 `GFramework.Core.Abstractions` 之上，把框架已有的架构、
+Scene / UI、配置、存储、设置、日志与协程能力接到 `Node`、`SceneTree`、`PackedScene`、`FileAccess` 与 `AudioServer`
+等 Godot 运行时对象上。
 
-- **Extensions** - Godot节点扩展方法，简化常见开发任务
-- **Signal** - 流畅的信号连接API，支持链式调用
-- **Storage** - Godot文件存储系统，支持虚拟路径
-- **Settings** - Godot设置系统，管理音频和图形设置
+如果你需要的是 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 或 `InputActions` 这类编译期能力，请改为同时安装
+`GFramework.Godot.SourceGenerators`。这些能力不属于本包。
 
-## 依赖关系
+## 包定位
 
-- 依赖 GFramework.Core
-- 依赖 GFramework.Core.Abstractions
+当前包解决的是 Godot 运行时接线，而不是重新定义一套 Godot 专属框架：
 
-## 详细文档
+- 架构生命周期与场景树绑定：`AbstractArchitecture`、`ArchitectureAnchor`
+- 节点运行时辅助：`WaitUntilReadyAsync()`、`AddChildXAsync()`、`QueueFreeX()`、`UnRegisterWhenNodeExitTree(...)`
+- Godot 风格的 Scene / UI 工厂与 registry：`GodotSceneFactory`、`GodotUiFactory`
+- Godot 特化的配置、存储与设置实现：`GodotYamlConfigLoader`、`GodotFileStorage`、`GodotAudioSettings`
+- 宿主侧辅助能力：`Signal(...)` fluent API、Godot 时间源、暂停处理、富文本效果
 
-参见 [docs/zh-CN/godot/](../docs/zh-CN/godot/) 目录下的详细文档。
+它不负责：
+
+- 自动生成节点字段注入代码
+- 自动生成 `_Ready()` / `_ExitTree()` 接线
+- 自动扫描所有场景或页面并完成统一注册
+- 提供 `GodotSceneRouter` 或 `GodotUiRouter` 这类额外 router 类型
+
+## 与相邻包的关系
+
+- `GFramework.Game`
+  - 提供 Scene / UI / 配置 / 数据等默认运行时契约与基类。
+  - `GFramework.Godot` 负责把这些能力落到 Godot 宿主。
+- `GFramework.Game.Abstractions`
+  - 提供 `ISceneFactory`、`IUiFactory`、设置与配置相关契约。
+  - 本包的大部分工厂和适配层都实现这些接口。
+- `GFramework.Core.Abstractions`
+  - 提供架构、日志、环境等基础契约。
+  - `AbstractArchitecture` 与日志 provider 都建立在这层之上。
+- `GFramework.Godot.SourceGenerators`
+  - 提供 `project.godot` 元数据、`[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]` 等编译期样板生成。
+  - 推荐与本包配套使用，但职责边界要分开理解。
+
+## 子系统地图
+
+### `Architectures/`
+
+- `AbstractArchitecture`
+- `AbstractGodotModule`
+- `ArchitectureAnchor`
+- `IGodotModule`
+
+用于把架构生命周期绑定到 `SceneTree`，并在需要时把 Godot 模块挂到场景树。
+
+### `Scene/` 与 `UI/`
+
+- `GodotSceneFactory`、`GodotSceneRegistry`
+- `GodotUiFactory`、`GodotUiRegistry`
+- `SceneBehaviorFactory`、`UiPageBehaviorFactory`
+
+这部分负责把 `PackedScene`、`Control`、`CanvasLayer` 等 Godot 对象接入 `GFramework.Game` 的 Scene / UI 契约。
+
+### `Config/`、`Storage/` 与 `Setting/`
+
+- `GodotYamlConfigLoader`
+- `GodotFileStorage`
+- `GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
+
+这部分解决的是 Godot 文件系统、音频总线、图形与本地化设置等宿主差异。
+
+### `Extensions/`、`Coroutine/`、`Logging/`、`Pause/`、`Text/`、`Pool/`
+
+- 节点扩展与 `Signal(...)` fluent API
+- `GodotTimeSource` 与协程时间分段
+- Godot 日志 provider
+- 暂停处理、节点池与富文本效果支持
+
+这些目录都是“宿主适配层”，不是新的 gameplay 抽象层。
+
+## 最小接入路径
+
+### 1. 先区分运行时包和生成器包
+
+如果你只需要 Godot 运行时适配：
+
+```bash
+dotnet add package GeWuYou.GFramework
+dotnet add package GeWuYou.GFramework.Godot
+```
+
+如果你还需要 `project.godot` 强类型入口、节点字段注入和信号绑定，再额外安装：
+
+```bash
+dotnet add package GeWuYou.GFramework.Core.SourceGenerators
+dotnet add package GeWuYou.GFramework.Godot.SourceGenerators
+```
+
+### 2. 保持原有架构注册方式，只把宿主协作接到 Godot
+
+常规模块继续使用 `InstallModule(...)`。
+
+只有模块自身暴露 `Node`、需要挂到 `ArchitectureAnchor`，或要在 `OnAttach(...)` / `OnDetach()` 里处理 Godot 生命周期副作用时，
+再使用 `InstallGodotModule(...)`。
+
+`GFramework.Godot.Tests/Architectures/AbstractArchitectureModuleInstallationTests.cs` 已覆盖一个关键边界：锚点缺失时会先抛
+`InvalidOperationException`，不会继续执行模块安装。
+
+### 3. Scene / UI 继续沿用 `Game` 契约
+
+当前真实边界是：
+
+- 没有 `GodotSceneRouter`
+- 没有 `GodotUiRouter`
+- `GodotSceneFactory` 在 provider 缺失时回退到 `SceneBehaviorFactory`
+- `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
+
+也就是说，项目通常仍然继承 `GFramework.Game.Scene.SceneRouterBase` 与 `GFramework.Game.UI.UiRouterBase`，只是把工厂和行为落到
+Godot 上。
+
+### 4. 按需接入配置、存储和设置
+
+当项目已经使用 `Game` family 的配置、存储、设置契约时，再补 Godot 侧实现：
+
+- 配置：`GodotYamlConfigLoader`
+- 存储：`GodotFileStorage`
+- 设置：`GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
+
+不要把这些宿主实现误写成 `Game` family 的默认行为。
+
+## `ai-libs/` 里的参考接入线索
+
+`ai-libs/CoreGrid` 仍是当前最直接的消费者证据来源：
+
+- 架构侧保持普通模块注册，再按需挂接 Godot 宿主
+- `project.godot` 元数据与节点样板交给 `GFramework.Godot.SourceGenerators`
+- Scene / UI 继续沿用 `Game` family 的 router 语义
+
+当 `ai-libs/` 与源码或测试冲突时，应以当前源码与测试为准。
+
+## 文档入口
+
+- Godot 运行时总览：[docs/zh-CN/godot/index.md](../docs/zh-CN/godot/index.md)
+- 架构集成：[docs/zh-CN/godot/architecture.md](../docs/zh-CN/godot/architecture.md)
+- 场景系统：[docs/zh-CN/godot/scene.md](../docs/zh-CN/godot/scene.md)
+- UI 系统：[docs/zh-CN/godot/ui.md](../docs/zh-CN/godot/ui.md)
+- 节点扩展：[docs/zh-CN/godot/extensions.md](../docs/zh-CN/godot/extensions.md)
+- 信号系统：[docs/zh-CN/godot/signal.md](../docs/zh-CN/godot/signal.md)
+- 日志系统：[docs/zh-CN/godot/logging.md](../docs/zh-CN/godot/logging.md)
+- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md)
+- 生成器入口：[../GFramework.Godot.SourceGenerators/README.md](../GFramework.Godot.SourceGenerators/README.md)
+
+## 什么时候不该把它当成主入口
+
+以下场景更适合先回到其他包：
+
+- 只需要 Scene / UI / 配置契约，不需要 Godot 宿主：
+  - 选 `GFramework.Game.Abstractions`
+- 需要默认运行时实现，但暂时不接 Godot：
+  - 选 `GFramework.Game`
+- 需要的是 `project.godot` 元数据、节点字段注入或编译期样板：
+  - 选 `GFramework.Godot.SourceGenerators`
diff --git a/README.md b/README.md
index af805a2f..85646537 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
 | `GFramework.Core.SourceGenerators` | Core 侧通用源码生成器与分析器 | [README](GFramework.Core.SourceGenerators/README.md) |
 | `GFramework.Game.SourceGenerators` | 游戏内容配置 schema 生成器 | [README](GFramework.Game.SourceGenerators/README.md) |
 | `GFramework.Cqrs.SourceGenerators` | CQRS handler registry 生成器 | [README](GFramework.Cqrs.SourceGenerators/README.md) |
-| `GFramework.Godot.SourceGenerators` | Godot 场景专用源码生成器 | [README](GFramework.Godot.SourceGenerators/README.md) |
+| `GFramework.Godot.SourceGenerators` | Godot 项目元数据、节点注入、信号绑定与 Scene/UI 辅助生成器 | [README](GFramework.Godot.SourceGenerators/README.md) |
 
 ## 内部支撑模块
 
diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md
new file mode 100644
index 00000000..6c306881
--- /dev/null
+++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md
@@ -0,0 +1,77 @@
+# Documentation Full Coverage Governance Status History Through RP-016
+
+以下内容从 active tracking 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到
+`DOCUMENTATION-FULL-COVERAGE-GOV-RP-016` 的阶段性状态、治理结论与恢复背景。默认 `boot` 只需要读取 active
+tracking 中的最新摘要；若需要追溯已完成波次的详细背景，再回到本归档文件。
+
+## 阶段里程碑
+
+### `RP-001` 到 `RP-007`
+
+- 建立长期 active topic `documentation-full-coverage-governance`，并在 `ai-plan/public/README.md` 中将当前分支
+  `docs/sdk-update-documentation` 映射到该 topic。
+- 明确消费属性边界：
+  - `GFramework.Ecs.Arch.Abstractions` 是可打包直接消费模块，需要 README 与文档入口。
+  - `GFramework.Core.SourceGenerators.Abstractions`、
+    `GFramework.Godot.SourceGenerators.Abstractions`、`GFramework.SourceGenerators.Common`
+    都按 `IsPackable=false` 的内部支撑模块处理。
+- 收口 `Core` / `Core.Abstractions` README、landing page 与类型族级 XML inventory。
+- 收口 `Ecs.Arch` / `Ecs.Arch.Abstractions` README、landing page、抽象页与 `UseArch(...)` 早于
+  `Initialize()` 的采用约束。
+- 收口 `Cqrs` family 的 runtime / abstractions / source generator 入口，并为缺失的内部类型补齐 XML 注释。
+- 收口 `Game` family 的 README、landing page、抽象页与类型族级 XML inventory。
+- 将 `Game` family 从“文档存在但入口失真”推进到“runtime / abstractions / source generator 都有当前可审计入口”。
+
+### `RP-008` 到 `RP-013`
+
+- 消化 PR #271 的文档 follow-up，修正 `gframework-pr-review` 脚本与 skill 中的 WSL Git 策略，使其与
+  `AGENTS.md` 保持一致。
+- 将 `Godot` family 的核心恢复摘要迁回 active topic，避免默认恢复路径继续依赖 archive 细节。
+- 重写 `GFramework.Godot/README.md` 与 `GFramework.Godot.SourceGenerators/README.md`，补齐当前包关系、
+  子系统地图、最小接入路径与站内文档入口。
+- 更新根 `README.md`、`docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`，把
+  `GFramework.Godot.SourceGenerators` 的 owner 与能力边界收敛到当前源码口径。
+- 完成 `Godot` docs surface 的 validation-only 巡检，确认 landing、tutorial、API reference 与 README
+  当前保持一致叙述，没有出现新的入口漂移。
+
+### `RP-014` 到 `RP-016`
+
+- 重写 `docs/zh-CN/godot/storage.md`，补齐 frontmatter、`GodotFileStorage` 的路径语义、repository 分工与
+  `GodotYamlConfigLoader` 分流边界。
+- 重写 `docs/zh-CN/godot/setting.md`，改回当前 `ISettingsModel` / `RegisterApplicator(...)` 口径，并补齐
+  `LocalizationMap` fallback 与当前 consumer wiring。
+- 对 `Godot` docs surface 再做一轮 validation-only 巡检，确认 `storage.md`、`setting.md`、landing、README、
+  tutorial 与 API reference 没有新的回漂。
+- 重写 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`，把 `Game` persistence docs
+  surface 收口到当前 repository / storage / serializer / settings 责任边界。
+- 将 `DataRepository`、`UnifiedSettingsDataRepository`、`SaveRepository<TSaveData>` 与 `FileStorage` /
+  `ScopedStorage` / `SettingsModel<TRepository>` 的分工，统一回写到 README、源码与 `PersistenceTests` 已验证的采用路径。
+
+## 已确认的长期事实
+
+- 已归档的 `documentation-governance-and-refresh` 只作为历史证据保留，不再作为默认 `boot` 入口。
+- `Godot` family 当前核心页面集包括：
+  - `docs/zh-CN/godot/index.md`
+  - `docs/zh-CN/godot/architecture.md`
+  - `docs/zh-CN/godot/scene.md`
+  - `docs/zh-CN/godot/ui.md`
+  - `docs/zh-CN/godot/storage.md`
+  - `docs/zh-CN/godot/setting.md`
+  - `docs/zh-CN/godot/signal.md`
+  - `docs/zh-CN/godot/extensions.md`
+  - `docs/zh-CN/godot/logging.md`
+  - `docs/zh-CN/tutorials/godot-integration.md`
+- `Game` persistence docs surface 当前最值得优先复核的页面集包括：
+  - `docs/zh-CN/game/data.md`
+  - `docs/zh-CN/game/storage.md`
+  - `docs/zh-CN/game/serialization.md`
+  - `docs/zh-CN/game/setting.md`
+- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
+  `MSB4276` / `MSB4018`；这是已知环境阻塞，不是本 topic 当前文档回归。
+- 当前 WSL 会话里 `git.exe` 可解析但不可执行，仓库默认 Git 策略应继续优先使用显式
+  `--git-dir` / `--work-tree` 绑定。
+
+## 关联归档
+
+- 早期详细验证历史：`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
+- 时间线归档：`ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md
new file mode 100644
index 00000000..6138130a
--- /dev/null
+++ b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md
@@ -0,0 +1,92 @@
+# Documentation Full Coverage Governance Trace History Through RP-016
+
+以下内容从 active trace 中迁出，用于保留 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到
+`DOCUMENTATION-FULL-COVERAGE-GOV-RP-016` 的阶段时间线、关键决策与主要验证结果。默认 `boot` 只需要读取
+active trace 中的最新恢复点；若需要追溯旧阶段的执行顺序，再回到本归档文件。
+
+## 2026-04-22
+
+### `RP-001`
+
+- 新建 active topic `documentation-full-coverage-governance`。
+- 在 `ai-plan/public/README.md` 中将当前 worktree 绑定到该 topic。
+- 盘点可消费模块与内部支撑模块的边界，作为后续 README / docs 治理基线。
+
+### `RP-002`
+
+- 完成 `Core` / `Core.Abstractions` README、landing page 与类型族级 XML inventory 的第一轮收口。
+- 运行 `docs` 站点构建与局部文档校验，结果通过。
+
+### `RP-003`
+
+- 完成 `Ecs.Arch` / `Ecs.Arch.Abstractions` 文档刷新。
+- 确认 `UseArch(...)` 必须早于 `Initialize()` 的采用顺序，并将该约束写回文档。
+- 运行 `docs` 站点构建，结果通过。
+
+### `RP-004`
+
+- 完成 `Cqrs` family landing、generator topic 与 API 参考入口刷新。
+- 为 `GFramework.Cqrs` 与 `GFramework.Cqrs.SourceGenerators` 缺失的内部类型补齐 XML 注释。
+- `GFramework.Cqrs.SourceGenerators` Release build 通过。
+- `GFramework.Cqrs` Release build 仍受环境级 fallback package folder 问题阻塞，记录为已知非回归风险。
+
+## 2026-04-23
+
+### `RP-005`
+
+- 完成 `Game` family README、landing page、抽象页与类型族级 XML inventory 刷新。
+- 文档校验与 `docs` 站点构建通过。
+
+### `RP-006`
+
+- 更新 `AGENTS.md` 的 WSL Git 回退顺序：
+  - 优先显式 `--git-dir` / `--work-tree` 绑定。
+  - `git.exe` 仅在当前会话可执行时作为 fallback。
+- `docs` 站点构建通过。
+
+### `RP-007`
+
+- 完成 `Game` family validation-only 巡检。
+- 确认 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 当前没有新的采用漂移。
+
+### `RP-008` 到 `RP-013`
+
+- 消化 PR #271 的 review follow-up，修正 `gframework-pr-review` 脚本与 skill 中的 Git 策略。
+- 将 `Godot` family 的核心恢复摘要迁回 active topic。
+- 重写 `GFramework.Godot/README.md` 与 `GFramework.Godot.SourceGenerators/README.md`。
+- 更新根 `README.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/api-reference/index.md` 的
+  `Godot` 入口与 owner 描述。
+- 针对 `Godot` docs surface 执行 validation-only 巡检，确认当前 landing / topic / tutorial / API reference
+  与 README 保持一致。
+
+### `RP-014`
+
+- 重写 `docs/zh-CN/godot/storage.md` 与 `docs/zh-CN/godot/setting.md`。
+- 运行 `scan_module_evidence.py Godot`、相关文档校验与 `docs` 站点构建，结果通过。
+
+### `RP-015`
+
+- 再次执行 `Godot` docs surface validation-only 巡检。
+- 确认 `storage.md`、`setting.md`、landing、README、tutorial 与 API reference 没有新的回漂。
+
+### `RP-016`
+
+- 重写 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`。
+- 运行 `scan_module_evidence.py Game`、相关文档校验与 `docs` 站点构建，结果通过。
+- 当前 `Game` persistence docs surface 已回到与源码、README 和 `PersistenceTests` 一致的责任边界叙述。
+
+## 主要验证汇总
+
+- `cd docs && bun run build`
+  - 多轮执行通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
+- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh ...`
+  - 针对本 topic 涉及的 landing / topic / abstractions 页面多轮执行通过。
+- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`
+  - 通过。
+- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
+  - 通过。
+
+## 归档关联
+
+- 状态归档：`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md`
+- 早期详细验证历史：`ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
diff --git 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
index 157f7b91..578662a2 100644
--- 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
@@ -3,7 +3,7 @@
 ## 目标
 
 建立一个长期 active topic，持续治理 `GFramework` 的 README、`docs/zh-CN`、站点导航、XML 文档和 API
-参考链路，避免历史上的阶段性刷新完成后再次回漂。
+参考链路，避免阶段性刷新完成后再次回漂。
 
 - 用源码、测试、`*.csproj` 和必要的 `ai-libs/` 证据校正文档
 - 以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路
@@ -12,113 +12,65 @@
 
 ## 当前恢复点
 
-- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-008`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-019`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 消化 PR #271 的 latest-head review follow-up，修正仍在本地成立的 docs / skill / ai-plan 问题
-  - 将 active tracking 的重复验证明细迁出默认 boot 路径，只保留最新可恢复摘要
-  - 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic
+  - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
+  - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性
+  - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/`
 
 ## 当前状态摘要
 
-- 已归档的 `documentation-governance-and-refresh` 仅保留为历史证据，不再作为默认 `boot` 入口
-- 本轮已消化的 PR #271 review follow-up：
-  - 为 `.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` 补齐 WSL worktree 下的显式 Linux Git 绑定，避免 `git.exe` 在当前会话触发 `Exec format error`
-  - 同步更新 `.agents/skills/gframework-pr-review/SKILL.md`，改为与 `AGENTS.md` 一致的 Git 策略，并把命令示例统一到 `.agents/...` 路径
-  - 为 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 补充 marker 类型放置与命名约定说明
-  - 从 `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 删除误放的 source-generator 内部模块提醒，并微调 `docs/zh-CN/ecs/index.md` 的边界说明语序
-  - 为 `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 的归档验证补写结果态
-  - 将 RP-001 至 RP-007 的详细验证历史迁入 `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
-- 本轮已确认的消费属性结论：
-  - `GFramework.Ecs.Arch.Abstractions`：可打包直接消费模块，需要 README 和文档入口
-  - `GFramework.Core.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理
-  - `GFramework.Godot.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理
-  - `GFramework.SourceGenerators.Common`：`IsPackable=false`，按内部支撑模块处理
-- 本轮已完成的治理动作：
-  - 新建 `GFramework.Ecs.Arch.Abstractions/README.md`
-  - 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner
-  - 为抽象接口栏目补齐 `Ecs.Arch.Abstractions` 页面与 sidebar 入口
-  - 将 `docs/zh-CN/api-reference/index.md` 重写为模块到 XML / README / 教程的阅读链路入口
-  - 为 `GFramework.Core/README.md` 补齐 `Services`、`Configuration`、`Environment`、`Pool`、`Rule`、`Time` 等当前目录映射
-  - 为 `GFramework.Core.Abstractions/README.md` 补齐契约族地图与 XML 阅读重点
-  - 将 `docs/zh-CN/abstractions/core-abstractions.md` 从过时的接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面
-  - 为 `docs/zh-CN/core/index.md` 补齐 frontmatter、能力域导航和 API / XML 阅读入口
-  - 为 `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` 补齐类型族级 XML 覆盖基线入口
-  - 为 `docs/zh-CN/core/index.md`、`docs/zh-CN/abstractions/core-abstractions.md` 增加“类型族 -> XML 覆盖状态 -> 代表类型”的 inventory
-  - 基于顶层目录轻量盘点确认：`Core` / `Core.Abstractions` 当前公开 / 内部类型声明都已带 XML 注释，成员级审计留待后续波次
-  - 重写 `docs/zh-CN/ecs/index.md`，收敛当前 ECS family 的包边界、采用顺序和 XML inventory
-  - 重写 `docs/zh-CN/ecs/arch.md`，明确 `UseArch(...)` 需早于 `Initialize()` 的真实接入时机
-  - 刷新 `GFramework.Ecs.Arch/README.md`，使运行时 README 与源码 / 测试一致
-  - 为 `GFramework.Ecs.Arch.Abstractions/README.md` 与 `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 补齐类型族级 XML inventory
-  - 重写 `docs/zh-CN/core/cqrs.md`，将其收敛为 `Cqrs` family landing，并补齐运行时 / 契约层 / 生成器的 XML inventory
-  - 新建 `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 注释
-  - 更新 `AGENTS.md` 的 WSL Git 策略，将显式 `--git-dir` / `--work-tree` 绑定提升为高于 `git.exe` 的默认优先级
-  - 记录当前环境偏差：本会话 `git.exe` 可解析但执行会触发 `Exec format error`，而 plain Linux `git` 会命中 worktree 路径翻译错误，需要显式仓库绑定
-  - 完成 `Game` family 巡检，确认 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的核心采用说明、包关系与交叉引用仍与当前源码 / README 一致，没有发现需要立刻修正的回漂
-
-## Inventory（第一版）
-
-| 模块族 | 当前状态 | 当前证据 | 下一动作 |
-| --- | --- | --- | --- |
-| `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 / 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，不建独立采用页 |
-
-## 缺口分级
-
-- `P0`
-  - 错误采用路径、错误包关系、错误 API / 生命周期语义
-  - 站点导航死链、空 landing page、明显错误的模块 owner
-- `P1`
-  - 直接消费模块缺 README 或缺对应 docs 入口
-  - README / docs 示例与源码实现不一致
-  - 教程仍引用已经过时的默认接线方式
-- `P2`
-  - 结构重复、交叉链接不足、API 参考链路过薄
-  - 站内页面存在事实正确但组织方式不利于定位的内容
+- `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
+- `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`
+  作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。
+- `Godot` runtime 与 generator 入口当前以 `GFramework.Godot/README.md`、
+  `GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、
+  `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/tutorials/godot-integration.md` 维持统一 owner / adoption path。
+- `2026-04-23` 基于 PR `#272` 的 review follow-up 已完成：
+  - 为 `docs/zh-CN/game/data.md` 补充 `UnifiedSettingsDataRepository` 的统一文件布局示例
+  - 为 `GFramework.Godot.SourceGenerators/README.md` 补充手写 `_Ready()` / `_ExitTree()` 时显式调用生成方法的最小样例
+  - 将过长的 active tracking / trace 瘦身，并把历史摘要迁回 `archive/`
+- `2026-04-23` 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，确认 latest-head review 当前仍有 1 条
+  Greptile open thread，定位到 `docs/zh-CN/godot/setting.md:75` 的 inline code 误写成
+  `SettingsModel&lt;ISettingsDataRepository&gt;`。
+- 结合当前 PR 已改动的 `docs/zh-CN/godot/storage.md` 做同类巡检后，确认 `SaveRepository&lt;TSaveData&gt;`
+  也会在 VitePress code span 中按字面量渲染；两处现已在本地统一改为真实泛型写法。
+- 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
+  文件缺陷。
 
 ## 当前风险
 
-- 当前 `Core` / `Core.Abstractions` 只完成了类型族级 XML 基线，不等于成员级契约全审计
-  - 缓解措施：后续只在共享抽象或高风险生命周期接口发生改动时补成员级细审，不在本轮扩张范围
-- `Godot` family 的治理结论主要留在已归档 topic 中，active topic 当前只保留摘要
-  - 缓解措施：下一恢复点优先判断是否要把关键 XML inventory 摘要迁回 active topic，避免后续 boot 仍过度依赖 archive
-- 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂
-  - 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源
-- VitePress 页面不能直接链接到 `docs/` 目录之外的模块 `README.md`
-  - 缓解措施：站内页面用模块路径文本或站内 API 入口表达，仓库级 README 仍保留仓库文件链接
-- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下，本地 build 仍会读取失效的 fallback package folder 配置，导致无法完成该项目的标准编译验证
-  - 缓解措施：本轮先以 `GFramework.Cqrs.SourceGenerators` 编译通过和 docs site build 通过作为有效验证，并在后续环境治理或构建脚本清理时单独处理 `RestoreFallbackFolders` / 资产文件问题
-- 当前 WSL 会话中 `git.exe` 虽然可解析，但不能执行
-  - 缓解措施：把显式 `--git-dir` / `--work-tree` 绑定上升为仓库默认回退策略，并仅把 `git.exe` 保留为可执行时的次级 fallback
+- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理仍以“类型声明级基线”为主，不等于成员级契约全审计。
+- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
+  `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
+- 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
 
-## 验证说明
+## 归档指针
 
-- 详细验证历史已归档到 `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
-- `2026-04-23` `python3 -B -c "from pathlib import Path; compile(Path('.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py').read_text(encoding='utf-8'), '.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py', 'exec')"`
-- 结果：通过
-- `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
-- 结果：通过；成功抓取 PR `#271`，并确认当前 latest-head review threads 为 `4` 条 open
-- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`
-- 结果：通过
-- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md`
-- 结果：通过
-- `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`
-- 结果：通过
-- `2026-04-23` `cd docs && bun run build`
-- 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
+- 详细验证历史（`RP-001` 到 `RP-007`）：
+  `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
+- 阶段状态归档（`RP-001` 到 `RP-016`）：
+  `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md`
+- 时间线归档（`RP-001` 到 `RP-016`）：
+  `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
+
+## 最新验证
+
+- `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
+  - 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到
+    `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。
+- `2026-04-23` `rg -n '`[^`]*&lt;[^`]*`|`[^`]*&gt;[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md`
+  - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。
+- `2026-04-23` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
 
 ## 下一步
 
-1. 完成本轮 PR #271 follow-up 的针对性验证与 docs build，确认 open threads 是否都已被本地收敛
-2. 推送当前分支后重新执行 `$gframework-pr-review`，确认 PR #271 的 latest-head open threads 是否按预期收敛
-3. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，避免长期治理只依赖 archive 恢复
+1. 提交并推送本地对 `docs/zh-CN/godot/setting.md` 与 `docs/zh-CN/godot/storage.md` 的 Markdown 泛型写法修正，
+   然后重新抓取 PR `#272` 确认 Greptile open thread 是否已在新 head commit 上消失。
+2. 如果 PR `#272` 的 `Title check` 仍需要消除，到 GitHub 上把标题改成更具体的文档治理描述。
+3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
+   `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
+4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
+   `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。
diff --git 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
index 220b0133..fb3c5093 100644
--- 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
@@ -1,275 +1,58 @@
 # Documentation Full Coverage Governance Trace
 
-## 2026-04-22
+## 2026-04-23
 
-### 当前恢复点：RP-001
+### 当前恢复点：RP-019
 
-- 按长期治理计划新建 active topic `documentation-full-coverage-governance`
-- 在 `ai-plan/public/README.md` 中将当前分支 `docs/sdk-update-documentation` 映射到该 topic
-- 复核已知缺口模块的 `*.csproj` 后确认：
-  - `GFramework.Ecs.Arch.Abstractions` 是可打包消费模块，需要独立 README
-  - `GFramework.Core.SourceGenerators.Abstractions`、`GFramework.Godot.SourceGenerators.Abstractions`、
-    `GFramework.SourceGenerators.Common` 都是 `IsPackable=false` 的内部支撑模块
-- 基于该结论，本轮没有为内部支撑模块新增独立 README，而是在根 README 与 abstractions / API 入口中明确其 owner
+- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。
+- GitHub latest-head review 当前暴露 1 条新的 Greptile open thread：
+  `docs/zh-CN/godot/setting.md:75` 在 inline code 中写成
+  `SettingsModel&lt;ISettingsDataRepository&gt;`。
+- 本地核对当前文档渲染语义后，确认 CommonMark / VitePress 不会在 code span 内解码 HTML entity，
+  该评论成立。
+- 对当前 PR 已变更的 Godot 文档做同类扫描后，又在 `docs/zh-CN/godot/storage.md:102` 发现
+  `SaveRepository&lt;TSaveData&gt;` 的同型问题。
+- 本轮执行的修复：
+  - 将 `docs/zh-CN/godot/setting.md` 的 `SettingsModel&lt;ISettingsDataRepository&gt;` 改为
+    `SettingsModel<ISettingsDataRepository>`
+  - 将 `docs/zh-CN/godot/storage.md` 的 `SaveRepository&lt;TSaveData&gt;` 改为
+    `SaveRepository<TSaveData>`
+  - 同步更新 active tracking / trace，记录该 PR review follow-up 与新的恢复点
 
-### 当前决策
+### 当前决策（RP-019）
 
-- 新主题的完成条件采用长期治理口径：`P0` 清零、无 README 缺失、无导航死链，并完成连续两轮稳定巡检
-- 本轮先做治理基础设施与 inventory，不把整个长期计划伪装成单轮完成
-- `api-reference` 页面改为“模块 -> README / docs / XML / tutorial”的阅读链路入口，避免继续维护失真的伪签名列表
-- `Ecs.Arch` family 被列为高优先 backlog：抽象层入口已补齐，但 runtime docs 仍需按源码重写
-- `Core` / `Core.Abstractions` 波次先收口 README、landing page 和 abstractions 页的目录映射，再补显式 XML 覆盖 inventory
-- VitePress 站内页面不直接链接仓库根模块 `README.md`；站内仅保留可构建的 docs 链接，模块 README 以文本路径或仓库 README 承接
+- PR review 结果以 GitHub latest-head open threads 为准；即便 active tracking 曾记录“无 open thread”，也必须按新抓取结果回写。
+- 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `<T>` 语法，不能在反引号内部再写
+  `&lt;` / `&gt;`，否则 VitePress 会把 entity 当作字面量展示。
+- 当 latest-head review 命中某个文档表述问题时，应顺手扫描同一批 PR 已改动文档中的同类模式，避免只消掉单条 thread 却把相同渲染缺陷留在相邻页面。
+- 当前本地修复完成后，下一次 GitHub 侧复核需要基于新提交/新 head commit，而不是旧的 PR review 快照。
 
-### 当前恢复点：RP-002
-
-- 完成 `Core` / `Core.Abstractions` 的类型族级 XML inventory：
-  - `GFramework.Core/README.md`
-  - `GFramework.Core.Abstractions/README.md`
-  - `docs/zh-CN/core/index.md`
-  - `docs/zh-CN/abstractions/core-abstractions.md`
-- 通过顶层目录轻量盘点确认：
-  - `GFramework.Core` 当前各目录族的公开 / 内部类型声明都已带 XML 注释
-  - `GFramework.Core.Abstractions` 当前各契约目录族的公开 / 内部类型声明都已带 XML 注释
-- 这轮 inventory 明确限定为“类型声明级基线”，不把结果表述成成员级 XML 合规审计
-
-### 当前决策（RP-002）
-
-- XML inventory 同时落在模块 README 和站内 landing page：
-  - README 提供仓库侧入口，方便从包目录直接恢复上下文
-  - docs landing 提供更细的类型族 / 代表类型 / 阅读重点表格，方便站内导航
-- `Core` 波次在补齐基线后转入巡检，不继续在本轮展开成员级 ``<param>`` / ``<returns>`` 审计
-- 下一恢复点切换到 `Ecs` 波次，优先处理仍明显失真的 runtime docs
-
-### 当前验证
-
-- 文档校验：
-  - `validate-all.sh docs/zh-CN/abstractions/index.md`：通过
-  - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
-  - `validate-all.sh docs/zh-CN/api-reference/index.md`：通过
-  - `validate-all.sh docs/zh-CN/core/index.md`：通过
-  - `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过
-- 构建校验：
-  - `cd docs && bun run build`：通过
-  - `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
-  - `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
-
-### 当前验证（RP-002）
-
-- 文档校验：
-  - `validate-all.sh docs/zh-CN/core/index.md`：通过
-  - `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过
-- 构建校验：
-  - `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
-
-### 当前恢复点：RP-003
-
-- 完成 `Ecs.Arch` 波次的运行时文档刷新：
-  - `docs/zh-CN/ecs/index.md`
-  - `docs/zh-CN/ecs/arch.md`
-  - `GFramework.Ecs.Arch/README.md`
-- 为 `Ecs.Arch.Abstractions` 补齐与运行时页同粒度的 XML inventory：
-  - `GFramework.Ecs.Arch.Abstractions/README.md`
-  - `docs/zh-CN/abstractions/ecs-arch-abstractions.md`
-- 明确记录一个关键采用事实：
-  - `UseArch(...)` 必须早于 `Initialize()` 调用
-  - 该结论以 `ArchExtensions` 的模块注册方式和 `ExplicitRegistrationTests` 为证据
-- 将 `Ecs.Arch` family 从“入口存在但失真”推进到“README / landing / abstractions / XML inventory 已对齐源码与测试”
-
-### 当前决策（RP-003）
-
-- `Ecs` 波次继续采用与 `Core` 相同的治理粒度：
-  - 模块 README 承担仓库入口
-  - `docs/zh-CN/ecs/index.md` 承担模块族 landing
-  - `docs/zh-CN/ecs/arch.md` 承担运行时默认实现专题页
-  - `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 承担契约边界专题页
-- `EnableStatistics` 当前仅保留在公开配置面上；文档不再把它写成已验证的运行时行为
-- 下一恢复点切换到 `Cqrs` 波次，优先解决入口分散和 API / XML 阅读链路不统一的问题
-
-### 当前验证（RP-003）
-
-- 文档校验：
-  - `validate-all.sh docs/zh-CN/ecs/index.md`：通过
-  - `validate-all.sh docs/zh-CN/ecs/arch.md`：通过
-  - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
-- 构建校验：
-  - `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
-
-### 下一步
-
-1. 在 `Cqrs` 波次核对模块 README、`docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` 的真实 owner
-2. 决定 `Cqrs` family 是补 dedicated landing 还是拆分现有入口页
-
-### 当前恢复点：RP-004
-
-- 完成 `Cqrs` 波次的模块族入口刷新：
-  - 重写 `docs/zh-CN/core/cqrs.md`
-  - 新建 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`
-  - 更新 `docs/zh-CN/source-generators/index.md`
-  - 更新 `docs/zh-CN/api-reference/index.md`
-  - 更新 `docs/.vitepress/config.mts`
-- 将 `Cqrs` family 从“README 已存在但 generator 入口分散”推进到“runtime / abstractions / source generator 都有明确站内入口”
-- 为 `GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs` 与
-  `GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs` 中缺失的内部类型补齐 XML 注释
-- 基于轻量扫描确认：
-  - `GFramework.Cqrs.Abstractions/Cqrs/` 当前类型声明级 XML 覆盖为 `20/20`
-  - `GFramework.Cqrs` 根入口与 `Internal/` 已补到 `19/19`
-  - `GFramework.Cqrs.SourceGenerators/Cqrs/` 当前类型声明级 XML 覆盖为 `3/3`
-
-### 当前决策（RP-004）
-
-- `docs/zh-CN/core/cqrs.md` 继续保留在 `Core` 栏目，但其角色调整为 `Cqrs` family landing，而不再只是 runtime 简介页
-- `Cqrs.SourceGenerators` 不单独新建一级导航栏目，而是在 `source-generators` 栏目内补一个专用专题页，保持站点 taxonomy 稳定
-- generator 入口以“专题页 + API reference 链接 + sidebar”三点联动，而不是只在 `source-generators/index.md` 留一个段落链接
-- XML inventory 仍维持“类型声明级基线”口径，不在本轮扩展成成员级 `param/returns/exception` 细审
-
-### 当前验证（RP-004）
-
-- 文档校验：
-  - `validate-all.sh docs/zh-CN/core/cqrs.md`：通过
-  - `validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
-- 轻量 XML inventory：
-  - `GFramework.Cqrs/Internal/`：`14/14`
-  - `GFramework.Cqrs.Abstractions/Cqrs/`：`20/20`
-  - `GFramework.Cqrs.SourceGenerators/Cqrs/`：`3/3`
-- 构建校验：
-  - `dotnet build GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj -c Release -p:RestoreFallbackFolders=`：通过
-  - `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
-  - `dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release`：失败；当前 WSL / dotnet 环境仍引用失效的 Windows fallback package folder，并在多目标 inner build 阶段触发 `MSB4276` / `MSB4018`
-
-### 下一步
-
-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 的依赖
-
-### 当前恢复点：RP-006
-
-- 更新 `AGENTS.md` 的 WSL Git 规则：
-  - 将显式 `git --git-dir=<...> --work-tree=<...>` 绑定提升为高于 `git.exe` 的默认优先级
-  - 明确 plain Linux `git` 命中 worktree 路径翻译错误时，应先切到显式绑定而不是直接改用 `git.exe`
-  - 明确 `git.exe` 只有在当前会话可执行时才作为次级 fallback
-- 记录本次恢复任务的环境偏差：
-  - `git.exe` 在当前 WSL 会话中可解析，但执行会触发 `Exec format error`
-  - plain `git` 会把 worktree 元数据路径翻译错并报“not a git repository”
-  - 显式 `--git-dir` / `--work-tree` 绑定是本次已验证可用的 Git 操作方式
-
-### 当前决策（RP-006）
-
-- 把 Git 回退顺序写进 `AGENTS.md`，而不是只留在一次性的聊天上下文里
-- 不额外扩张 `gframework-boot` skill，因为它本身不内嵌 Git 选择逻辑，继续由 `AGENTS.md` 作为唯一准则
-- 继续把 `git.exe` 保留为 fallback，而不是完全删除，避免在可执行的 WSL 会话里丢掉可用路径
-
-### 当前验证（RP-006）
-
-- 构建校验：
-  - `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 的依赖
-
-### 当前恢复点：RP-007
-
-- 完成 `Game` family 巡检：
-  - 复核 `docs/zh-CN/game/config-system.md`
-  - 复核 `docs/zh-CN/game/scene.md`
-  - 复核 `docs/zh-CN/game/ui.md`
-  - 复核 `docs/zh-CN/source-generators/index.md`
-- 对照 `GFramework.Game`、`GFramework.Game.Abstractions`、`GFramework.Game.SourceGenerators` README 与相关源码 / 测试后，未发现需要立刻修正的采用语义回漂
-- 重点确认的真实语义包括：
-  - `GameConfigBootstrap` / `RegisterAllGeneratedConfigTables(...)` / `GFrameworkConfigSchemaDirectory` 的配置入口仍与文档示例一致
-  - `SceneRouterBase` 仍通过 `SemaphoreSlim` 串行化切换，并拒绝重复 `sceneKey` 入栈
-  - `UiRouterBase` 仍将 `Page` 层与 `Overlay` / `Modal` / `Toast` / `Topmost` 分为两套入口，且 `Show(..., UiLayer.Page)` 会直接拒绝
-
-### 当前决策（RP-007）
-
-- 本轮不为“巡检通过”硬造文档改动，先把结论写回 active topic，保持恢复点准确
-- `Game` family 暂时转入稳定巡检，不在没有源码变化的情况下重复改写 landing page
-- 默认下一步切到 `Godot` family 摘要是否回迁，减少长期治理对 archive topic 的依赖
-
-### 当前验证（RP-007）
-
-- 构建校验：
-  - `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
-
-### 下一步
-
-1. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic
-2. 若不需要迁回，则继续抽查 README / landing page / API reference 之间的 cross-link 是否出现新的漂移
-
-### 当前恢复点：RP-008
-
-- 使用 `$gframework-pr-review` 抓取当前分支 PR `#271` 后，确认 latest head review threads 仍有 `4` 条 open：
-  - `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 的 marker 类型约定说明缺口
-  - `docs/zh-CN/ecs/index.md` 的边界说明语序问题
-  - `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 误放的 source-generator 内部模块提醒
-  - `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md` 的验证历史过长，以及
-    `ai-plan/public/archive/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md` 缺少显式结果态
-- 在当前 WSL 会话里，`gframework-pr-review` 脚本先命中了 `git.exe` 的 `Exec format error`
-- 已将 `.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py` 改为优先使用 Linux `git` 的显式
-  `--git-dir` / `--work-tree` 绑定，并仅在无法建立该绑定时回退到旧的可执行解析逻辑
-- 已同步更新 `.agents/skills/gframework-pr-review/SKILL.md`，使其 Git 策略与命令示例都与当前仓库状态一致
-- 已把 `DOCUMENTATION-FULL-COVERAGE-GOV-RP-001` 到 `RP-007` 的详细验证历史迁入
-  `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
-
-### 当前决策（RP-008）
-
-- 继续把 latest-head unresolved threads 作为主信号，只修仍在本地成立的评论，不为已失效的历史 summary 做无意义回写
-- active tracking 只保留最新验证摘要与恢复点；详细验证历史留在 topic 自己的 archive，而不是继续堆在默认 boot 路径
-- `gframework-pr-review` 的脚本行为、技能文案与 `AGENTS.md` 必须保持同一套 WSL Git 策略，避免再次出现“文档说法正确但工具实现仍跑偏”的情况
-
-### 当前验证（RP-008）
+### 当前验证（RP-019）
 
 - PR review 抓取：
-  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`：通过
-- 脚本语法校验：
-  - `python3 -B -c "from pathlib import Path; compile(Path('.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py').read_text(encoding='utf-8'), '.agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py', 'exec')"`：通过
-- 文档校验：
-  - `validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
-  - `validate-all.sh docs/zh-CN/ecs/index.md`：通过
-  - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
+  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
+  - 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到
+    `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。
+- 同类模式巡检：
+  - `rg -n '`[^`]*&lt;[^`]*`|`[^`]*&gt;[^`]*`' GFramework.Godot.SourceGenerators/README.md GFramework.Godot/README.md README.md docs/zh-CN/api-reference/index.md docs/zh-CN/game/data.md docs/zh-CN/game/serialization.md docs/zh-CN/game/setting.md docs/zh-CN/game/storage.md docs/zh-CN/godot/setting.md docs/zh-CN/godot/storage.md docs/zh-CN/source-generators/index.md`
+  - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。
 - 构建校验：
-  - `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
+  - `bun run build`（工作目录：`docs/`）
+  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
+
+### 归档摘要（RP-018）
+
+- 使用 `$gframework-pr-review` 重新复核当前分支 PR `#272`。
+- latest-head review 命中 `GFramework.Godot.SourceGenerators/README.md:135` 的错误命名空间引用，并已在本地修正。
+- README 校验与 `docs/` 站点构建通过，待新提交推送后回 GitHub 侧确认 open thread 消失。
+
+### 归档指针
+
+- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md`
+- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md`
+- `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md`
 
 ### 下一步
 
-1. 提交本轮 PR review follow-up
-2. 推送当前分支后重新执行 `$gframework-pr-review`，观察 PR #271 的 open threads 是否收敛
+1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。
+2. 如果 PR `#272` 的 `Title check` 仍需要处理，到 GitHub 上把标题改成更具体的文档治理描述。
diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md
index 14ea32b8..94198008 100644
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@@ -32,7 +32,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 | `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
 | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
 | `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
-| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/index.md`](../source-generators/index.md) | 节点扩展、场景 / UI 适配、资源 / 存储 / 日志接入 |
+| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/godot-project-generator.md`](../source-generators/godot-project-generator.md)、[`../source-generators/get-node-generator.md`](../source-generators/get-node-generator.md)、[`../source-generators/bind-node-signal-generator.md`](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
 | `Ecs.Arch` / `Ecs.Arch.Abstractions` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` | [`../ecs/index.md`](../ecs/index.md)、[`../ecs/arch.md`](../ecs/arch.md)、[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
 
 ## 先看 XML，还是先看教程
diff --git a/docs/zh-CN/game/data.md b/docs/zh-CN/game/data.md
index b2e3fb71..2faa03a1 100644
--- a/docs/zh-CN/game/data.md
+++ b/docs/zh-CN/game/data.md
@@ -1,709 +1,204 @@
 ---
 title: 数据与存档系统
-description: 数据与存档系统提供统一的数据持久化基础能力，支持多槽位存档、版本化数据和仓库抽象。
+description: 以当前 GFramework.Game 源码与 PersistenceTests 为准，说明 DataRepository、UnifiedSettingsDataRepository 和 SaveRepository 的职责边界。
 ---
 
 # 数据与存档系统
 
-## 概述
+`GFramework.Game` 的数据持久化不是“只有一个万能仓库”。
 
-数据与存档系统是 GFramework.Game 中用于管理游戏数据持久化的核心组件。它提供了统一的数据加载和保存接口，支持多槽位存档管理、版本化数据模式，以及与存储系统、序列化系统的组合使用。
+当前更准确的理解是三层分工：
 
-通过数据系统，你可以将游戏数据保存到本地存储，支持多个存档槽位，并在需要时于应用层实现版本迁移。
+- `DataRepository`
+  - 面向“一个 location 对应一份持久化对象”的通用数据仓库
+- `UnifiedSettingsDataRepository`
+  - 面向“多个设置 section 聚合到同一个文件”的设置仓库
+- `SaveRepository<TSaveData>`
+  - 面向“按槽位组织的版本化存档”
 
-**主要特性**：
+如果先把这三类入口分开理解，后续采用路径会清晰很多。
 
-- 统一的数据持久化接口
-- 多槽位存档管理
-- 数据版本控制模式
-- 异步加载和保存
-- 批量数据操作
-- 与存储系统集成
+## 什么时候用哪个仓库
 
-## 核心概念
+### `DataRepository`
 
-### 数据接口
+适合：
 
-`IData` 标记数据类型：
+- 单份玩家档案
+- 单份运行时缓存
+- 一条 location 对应一个文件的普通业务数据
 
-```csharp
-public interface IData
-{
-    // 标记接口，用于标识可持久化的数据
-}
+默认语义是：
+
+- `IDataLocation` 决定 key
+- 一条 location 对应一份对象
+- 覆盖保存时可按 `DataRepositoryOptions.AutoBackup` 创建 `<key>.backup`
+- `SaveAllAsync(...)` 视为一次批量提交，只发送批量事件，不重复发送单项保存事件
+
+### `UnifiedSettingsDataRepository`
+
+适合：
+
+- 音频、图形、语言等多个设置 section 统一落到一份文件
+- 启动时一次性加载所有设置，再交给 `SettingsModel<TRepository>` 编排
+
+默认语义是：
+
+- 底层持久化文件只有一份，默认文件名是 `settings.json`
+- 各个设置 section 仍然通过 `IDataLocation` 的 key 区分
+- 保存、删除时会整文件回写，而不是只改单个 section 文件
+- 开启 `AutoBackup` 时，备份粒度也是整个统一文件，不是单个 section
+
+当 `DataRepositoryOptions.BasePath = "settings"`，并保持默认文件名时，最小目录结构通常是：
+
+```text
+settings/
+  settings.json
 ```
 
-### 数据仓库
+如果同时开启 `AutoBackup = true`，则同一路径下还会额外出现：
 
-`IDataRepository` 提供通用的数据操作：
-
-```csharp
-public interface IDataRepository : IUtility
-{
-    Task<T> LoadAsync<T>(IDataLocation location) where T : class, IData, new();
-    Task SaveAsync<T>(IDataLocation location, T data) where T : class, IData;
-    Task<bool> ExistsAsync(IDataLocation location);
-    Task DeleteAsync(IDataLocation location);
-    Task SaveAllAsync(IEnumerable<(IDataLocation, IData)> dataList);
-}
+```text
+settings/
+  settings.json
+  settings.backup
 ```
 
-`IDataRepository` 描述的是“仓库语义”，不是固定的落盘格式。实现可以选择每个数据项独立成文件，也可以把多个 section 聚合到同一个文件里。
+### `SaveRepository<TSaveData>`
 
-当前内建实现里：
+适合：
 
-- `DataRepository` 采用“每个 location 一份持久化对象”的模型
-- `UnifiedSettingsDataRepository` 采用“所有设置聚合到一个统一文件”的模型
+- 多槽位存档
+- 需要版本迁移的 save data
+- 需要列举现有槽位和删除槽位
 
-两者对外遵守同一套约定：
+默认语义是：
 
-- `SaveAllAsync(...)` 视为一次批量提交，只发送 `DataBatchSavedEvent`，不会再为每个条目重复发送 `DataSavedEvent<T>`
-- `DeleteAsync(...)` 只有在目标数据真实存在并被删除时才会发送删除事件
-- 当 `DataRepositoryOptions.AutoBackup = true` 时，覆盖已有数据前会先保留上一份快照
-- 对 `UnifiedSettingsDataRepository` 来说，备份粒度是整个统一文件，而不是单个设置 section
+- 按 `SaveRoot` / `SaveSlotPrefix` / `SaveFileName` 组织目录
+- 槽位不存在时，`LoadAsync(slot)` 返回新的 `TSaveData` 实例，而不是 `null`
+- `ListSlotsAsync()` 只返回真实存在存档文件的槽位，并按升序排列
+- 迁移成功后会把升级后的结果自动回写到槽位文件
 
-### 存档仓库
+## 当前公开入口
 
-`ISaveRepository<T>` 专门用于管理游戏存档：
+### `DataRepository`
+
+`DataRepository` 是最通用的默认实现。当前仓库和测试确认的行为有几条需要特别记住：
+
+- `LoadAsync<T>(location)` 在文件不存在时返回 `new T()`，不是抛异常
+- `DeleteAsync(location)` 只有在目标数据真实存在并被删除时才发送删除事件
+- `SaveAllAsync(...)` 会抑制逐项 `DataSavedEvent<T>`，只保留一次 `DataBatchSavedEvent`
+- `AutoBackup = true` 时，覆盖旧值前会先把旧值写到 `<key>.backup`
+
+最小接法通常是：项目先准备一个 `IDataLocation` 或 `IDataLocationProvider`，再把它交给 `DataRepository` 做
+`location -> key` 的映射；repository 自己不负责推导业务对象应该落在哪个位置。
+
+### `UnifiedSettingsDataRepository`
+
+当前 `SettingsModel<TRepository>` 依赖的默认设置仓库就是它。
+
+它和普通 `DataRepository` 的关键区别不是接口，而是落盘形态：
+
+- `DataRepository`
+  - 每个 location 对应一个独立文件
+- `UnifiedSettingsDataRepository`
+  - 所有 section 聚合到同一个统一文件
+
+还有两个容易遗漏的点：
+
+- `LoadAllAsync()` 依赖 `RegisterDataType(location, type)` 建立 section -> 运行时类型映射
+- 仓库内部会先把统一文件加载进缓存，再在保存 / 删除时基于快照整文件提交
+
+这就是为什么 `SettingsModel<TRepository>` 会在拿到 `GetData<T>()` 或 `RegisterApplicator(...)` 后主动把类型注册回 repository。
+
+### `SaveRepository<TSaveData>`
+
+`SaveRepository<TSaveData>` 用于槽位存档，不直接复用 `IDataLocation`。
+
+最重要的公开配置是 `SaveConfiguration`：
 
 ```csharp
-public interface ISaveRepository<TSaveData> : IUtility
-    where TSaveData : class, IData, new()
+var config = new SaveConfiguration
 {
-    ISaveRepository<TSaveData> RegisterMigration(ISaveMigration<TSaveData> migration);
-    Task<bool> ExistsAsync(int slot);
-    Task<TSaveData> LoadAsync(int slot);
-    Task SaveAsync(int slot, TSaveData data);
-    Task DeleteAsync(int slot);
-    Task<IReadOnlyList<int>> ListSlotsAsync();
-}
+    SaveRoot = "saves",
+    SaveSlotPrefix = "slot_",
+    SaveFileName = "save.json"
+};
 ```
 
-`ISaveMigration<TSaveData>` 定义单步迁移：
+按这个配置，槽位 `1` 的默认文件结构就是：
 
-```csharp
-public interface ISaveMigration<TSaveData>
-    where TSaveData : class, IData
-{
-    int FromVersion { get; }
-    int ToVersion { get; }
-    TSaveData Migrate(TSaveData oldData);
-}
+```text
+saves/
+  slot_1/
+    save.json
 ```
 
-### 版本化数据
+当前实现内部会先把根存储包装成 `ScopedStorage(storage, config.SaveRoot)`，再按槽位继续加前缀，因此项目层一般不需要手工再拼一次 `"saves/slot_1"`。
 
-`IVersionedData` 支持数据版本管理：
-
-```csharp
-public interface IVersionedData : IData
-{
-    int Version { get; }
-    DateTime LastModified { get; }
-}
-```
-
-## 基本用法
-
-### 定义数据类型
+## 存档迁移的真实语义
+
+`SaveRepository<TSaveData>` 只有在 `TSaveData` 实现了 `IVersionedData` 时，才支持 `RegisterMigration(...)`。
+
+当前源码和 `PersistenceTests` 明确约束了下面这些行为：
+
+- 非版本化 save type 注册迁移器会直接失败
+- 同一个 `FromVersion` 不能重复注册迁移器
+- 迁移链缺口会显式抛错，不会静默返回半升级结果
+- 迁移器声明的 `ToVersion` 必须与实际返回对象的版本一致
+- 如果读到比当前运行时代码更高版本的存档，也会明确失败
+- 单次加载会先固定一份迁移表快照，避免并发注册让同一次加载看到变化中的链路
+
+也就是说，`SaveRepository<TSaveData>` 的迁移语义更偏“严格升级管线”，而不是“尽量帮你读出来”。
+
+## 最小接入路径
+
+下面是当前 `Game` 层最常见的一套组合方式：
 
 ```csharp
+using GFramework.Core.Abstractions.Serializer;
+using GFramework.Core.Abstractions.Storage;
 using GFramework.Game.Abstractions.Data;
-
-// 简单数据
-public class PlayerData : IData
-{
-    public string Name { get; set; }
-    public int Level { get; set; }
-    public int Experience { get; set; }
-}
-
-// 版本化数据
-public class SaveData : IVersionedData
-{
-    public int Version { get; set; } = 1;
-    public PlayerData Player { get; set; }
-    public DateTime SaveTime { get; set; }
-}
-```
-
-### 使用存档仓库
-
-```csharp
-using GFramework.Core.Abstractions.Controller;
-using GFramework.Core.SourceGenerators.Abstractions.Rule;
-
-[ContextAware]
-public partial class SaveController : IController
-{
-    public async Task SaveGame(int slot)
-    {
-        var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-        // 创建存档数据
-        var saveData = new SaveData
-        {
-            Player = new PlayerData
-            {
-                Name = "Player1",
-                Level = 10,
-                Experience = 1000
-            },
-            SaveTime = DateTime.Now
-        };
-
-        // 保存到指定槽位
-        await saveRepo.SaveAsync(slot, saveData);
-        Console.WriteLine($"游戏已保存到槽位 {slot}");
-    }
-
-    public async Task LoadGame(int slot)
-    {
-        var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-        // 检查存档是否存在
-        if (!await saveRepo.ExistsAsync(slot))
-        {
-            Console.WriteLine($"槽位 {slot} 不存在存档");
-            return;
-        }
-
-        // 加载存档
-        var saveData = await saveRepo.LoadAsync(slot);
-        Console.WriteLine($"加载存档: {saveData.Player.Name}, 等级 {saveData.Player.Level}");
-    }
-
-    public async Task DeleteSave(int slot)
-    {
-        var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-        // 删除存档
-        await saveRepo.DeleteAsync(slot);
-        Console.WriteLine($"已删除槽位 {slot} 的存档");
-    }
-}
-```
-
-### 注册存档仓库
-
-```csharp
-using GFramework.Game.Data;
-
-public class GameArchitecture : Architecture
-{
-    protected override void Init()
-    {
-        // 获取存储系统
-        var storage = this.GetUtility<IStorage>();
-
-        // 创建存档配置
-        var saveConfig = new SaveConfiguration
-        {
-            SaveRoot = "saves",
-            SaveSlotPrefix = "slot_",
-            SaveFileName = "save.json"
-        };
-
-        // 注册存档仓库
-        var saveRepo = new SaveRepository<SaveData>(storage, saveConfig);
-        RegisterUtility<ISaveRepository<SaveData>>(saveRepo);
-    }
-}
-```
-
-## 高级用法
-
-### 列出所有存档
-
-```csharp
-public async Task ShowSaveList()
-{
-    var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-    // 获取所有存档槽位
-    var slots = await saveRepo.ListSlotsAsync();
-
-    Console.WriteLine($"找到 {slots.Count} 个存档:");
-    foreach (var slot in slots)
-    {
-        var saveData = await saveRepo.LoadAsync(slot);
-        Console.WriteLine($"槽位 {slot}: {saveData.Player.Name}, " +
-                         $"等级 {saveData.Player.Level}, " +
-                         $"保存时间 {saveData.SaveTime}");
-    }
-}
-```
-
-### 自动保存
-
-```csharp
-using GFramework.Core.Abstractions.Controller;
-using GFramework.Core.SourceGenerators.Abstractions.Rule;
-
-[ContextAware]
-public partial class AutoSaveController : IController
-{
-    private CancellationTokenSource? _autoSaveCts;
-
-    public void StartAutoSave(int slot, TimeSpan interval)
-    {
-        _autoSaveCts = new CancellationTokenSource();
-
-        Task.Run(async () =>
-        {
-            while (!_autoSaveCts.Token.IsCancellationRequested)
-            {
-                await Task.Delay(interval, _autoSaveCts.Token);
-
-                try
-                {
-                    await SaveGame(slot);
-                    Console.WriteLine("自动保存完成");
-                }
-                catch (Exception ex)
-                {
-                    Console.WriteLine($"自动保存失败: {ex.Message}");
-                }
-            }
-        }, _autoSaveCts.Token);
-    }
-
-    public void StopAutoSave()
-    {
-        _autoSaveCts?.Cancel();
-        _autoSaveCts?.Dispose();
-        _autoSaveCts = null;
-    }
-
-    private async Task SaveGame(int slot)
-    {
-        var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-        var saveData = CreateSaveData();
-        await saveRepo.SaveAsync(slot, saveData);
-    }
-
-    private SaveData CreateSaveData()
-    {
-        // 从游戏状态创建存档数据
-        return new SaveData();
-    }
-}
-```
-
-### 数据版本迁移
-
-`SaveRepository<TSaveData>` 现在支持注册正式的迁移器，并在 `LoadAsync(slot)` 时自动升级旧版本存档。
-
-迁移规则如下：
-
-- `TSaveData` 需要实现 `IVersionedData`
-- 仓库以 `new TSaveData().Version` 作为当前运行时目标版本
-- 每个迁移器负责一个 `FromVersion -> ToVersion` 跳转
-- 同一个 `FromVersion` 只能注册一个迁移器，且 `ToVersion` 必须严格大于 `FromVersion`
-- 加载时仓库会按链路连续执行迁移，并在成功后自动回写升级后的存档
-- 迁移器返回数据上的 `Version` 必须与声明的 `ToVersion` 一致
-- 如果缺少中间迁移器，或者读到了比当前运行时更高的版本，`LoadAsync` 会抛出异常，避免静默加载错误数据
-
-```csharp
-public sealed class SaveData : IVersionedData
-{
-    // 当前运行时代码支持的最新版本
-    public int Version { get; set; } = 2;
-    public string PlayerName { get; set; }
-    public int Level { get; set; }
-    public int Experience { get; set; }
-    public DateTime LastModified { get; set; }
-}
-
-public sealed class SaveDataMigrationV1ToV2 : ISaveMigration<SaveData>
-{
-    public int FromVersion => 1;
-
-    public int ToVersion => 2;
-
-    public SaveData Migrate(SaveData oldData)
-    {
-        return new SaveData
-        {
-            Version = 2,
-            PlayerName = oldData.PlayerName,
-            Level = oldData.Level,
-            Experience = oldData.Level * 100,
-            LastModified = DateTime.UtcNow
-        };
-    }
-}
-
-public sealed class SaveModule : AbstractModule
-{
-    public override void Install(IArchitecture architecture)
-    {
-        var storage = architecture.GetUtility<IStorage>();
-        var saveConfig = new SaveConfiguration
-        {
-            SaveRoot = "saves",
-            SaveSlotPrefix = "slot_",
-            SaveFileName = "save"
-        };
-
-        var saveRepo = new SaveRepository<SaveData>(storage, saveConfig)
-            .RegisterMigration(new SaveDataMigrationV1ToV2());
-
-        architecture.RegisterUtility<ISaveRepository<SaveData>>(saveRepo);
-    }
-}
-
-public async Task<SaveData> LoadGame(int slot)
-{
-    var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-    // 如果槽位里是 v1，仓库会自动迁移到 v2，并把新版本重新写回存储。
-    return await saveRepo.LoadAsync(slot);
-}
-```
-
-`ISaveMigration<TSaveData>` 接收和返回的是同一个存档类型。也就是说，框架提供的是“当前类型内的版本升级管线”，
-而不是跨 CLR 类型的双模型反序列化系统。如果旧版本缺失了新字段，反序列化会先使用当前类型的默认值，再由迁移器补齐。
-
-### 使用数据仓库
-
-```csharp
-using GFramework.Core.Abstractions.Controller;
-using GFramework.Core.SourceGenerators.Abstractions.Rule;
-
-[ContextAware]
-public partial class SettingsController : IController
-{
-    public async Task SaveSettings()
-    {
-        var dataRepo = this.GetUtility<IDataRepository>();
-
-        var settings = new GameSettings
-        {
-            MasterVolume = 0.8f,
-            MusicVolume = 0.6f,
-            SfxVolume = 0.7f
-        };
-
-        // 定义数据位置
-        var location = new DataLocation("settings", "game_settings.json");
-
-        // 保存设置
-        await dataRepo.SaveAsync(location, settings);
-    }
-
-    public async Task<GameSettings> LoadSettings()
-    {
-        var dataRepo = this.GetUtility<IDataRepository>();
-        var location = new DataLocation("settings", "game_settings.json");
-
-        // 检查是否存在
-        if (!await dataRepo.ExistsAsync(location))
-        {
-            return new GameSettings(); // 返回默认设置
-        }
-
-        // 加载设置
-        return await dataRepo.LoadAsync<GameSettings>(location);
-    }
-}
-```
-
-### 批量保存数据
-
-```csharp
-public async Task SaveAllGameData()
-{
-    var dataRepo = this.GetUtility<IDataRepository>();
-
-    var dataList = new List<(IDataLocation, IData)>
-    {
-        (new DataLocation("player", "profile.json"), playerData),
-        (new DataLocation("inventory", "items.json"), inventoryData),
-        (new DataLocation("quests", "progress.json"), questData)
-    };
-
-    // 批量保存
-    await dataRepo.SaveAllAsync(dataList);
-    Console.WriteLine("所有数据已保存");
-}
-```
-
-`SaveAllAsync(...)` 的事件语义和逐项调用 `SaveAsync(...)` 不同。它代表一次显式的批量提交，因此适合让监听器在收到 `DataBatchSavedEvent` 时统一刷新 UI、缓存或元数据，而不是对每个条目单独响应。
-
-### 聚合设置仓库
-
-如果你希望把设置统一保存到单个文件中，可以使用 `UnifiedSettingsDataRepository`：
-
-```csharp
 using GFramework.Game.Data;
 using GFramework.Game.Serializer;
+using GFramework.Game.Storage;
 
-public sealed class GameArchitecture : Architecture
-{
-    protected override void Init()
+var serializer = new JsonSerializer();
+var storage = new FileStorage("GameData", serializer, ".json");
+
+ISettingsDataRepository settingsRepository = new UnifiedSettingsDataRepository(
+    storage,
+    serializer,
+    new DataRepositoryOptions
     {
-        var storage = this.GetUtility<IStorage>();
-        var serializer = new JsonSerializer();
+        BasePath = "settings",
+        AutoBackup = true
+    });
 
-        var settingsRepo = new UnifiedSettingsDataRepository(
-            storage,
-            serializer,
-            new DataRepositoryOptions
-            {
-                AutoBackup = true,
-                EnableEvents = true
-            },
-            "settings.json");
-
-        settingsRepo.RegisterDataType(new DataLocation("settings", "graphics"), typeof(GraphicsSettings));
-        settingsRepo.RegisterDataType(new DataLocation("settings", "audio"), typeof(AudioSettings));
-
-        RegisterUtility<ISettingsDataRepository>(settingsRepo);
-    }
-}
-```
-
-这个实现依然满足 `IDataRepository` 的通用契约，但有两个实现层面的差异需要明确：
-
-- 它把所有设置 section 缓存在内存中，并在保存或删除时整文件回写
-- 开启自动备份时，备份的是整个 `settings.json` 文件，因此适合做“上一次完整设置快照”的恢复，而不是 section 级别回滚
-
-如果你需要 `LoadAllAsync()`，或者希望在同一个统一文件里混合反序列化多个 section，必须先为每个 section 注册类型：
-
-```csharp
-public async Task PrintSettingsSnapshot()
+var saveConfiguration = new SaveConfiguration
 {
-    var repo = this.GetUtility<ISettingsDataRepository>();
-
-    var all = await repo.LoadAllAsync();
-
-    var graphics = (GraphicsSettings)all["graphics"];
-    var audio = (AudioSettings)all["audio"];
-
-    Console.WriteLine($"Resolution: {graphics.ResolutionWidth}x{graphics.ResolutionHeight}");
-    Console.WriteLine($"MasterVolume: {audio.MasterVolume}");
-}
+    SaveRoot = "saves",
+    SaveSlotPrefix = "slot_",
+    SaveFileName = "save.json"
+};
 ```
 
-最小采用要求：
+分工应保持清晰：
 
-- 项目需要可用的 `IStorage`
-- 项目需要一个可用的序列化器实例，例如 `GFramework.Game.Serializer.JsonSerializer`
-- 在注册仓库时，把所有需要参与 `LoadAllAsync()` 或混合 section 反序列化的 location/type 对显式调用一次 `RegisterDataType(...)`
+- `storage` 只负责底层文件读写
+- `settingsRepository` 负责统一设置文件
+- `SaveRepository<TSaveData>` 负责槽位目录和存档迁移
 
-兼容性说明：
+## 当前边界
 
-- 现在 `UnifiedSettingsDataRepository.LoadAsync<T>()` 发送的是 `DataLoadedEvent<T>`，而不是 `DataLoadedEvent<IData>`
-- 如果你之前监听的是 `DataLoadedEvent<IData>`，需要改成订阅具体类型，例如 `DataLoadedEvent<GraphicsSettings>` 或 `DataLoadedEvent<AudioSettings>`
+- `DataRepositoryOptions` 描述的是仓库公开行为契约，不是某一种固定落盘格式
+- `UnifiedSettingsDataRepository` 不是通用万能仓库，它专门服务“多 section 聚合单文件”的场景
+- `SaveRepository<TSaveData>` 不负责业务层的 autosave 策略、云同步或存档选择 UI
+- `LoadAsync(...)` 返回新实例的行为适合默认启动路径；如果项目需要“缺档即报错”，应在业务层显式调用 `ExistsAsync(...)`
 
-### 存档备份
+## 继续阅读
 
-```csharp
-public async Task BackupSave(int slot)
-{
-    var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-    if (!await saveRepo.ExistsAsync(slot))
-    {
-        Console.WriteLine("存档不存在");
-        return;
-    }
-
-    // 加载原存档
-    var saveData = await saveRepo.LoadAsync(slot);
-
-    // 保存到备份槽位
-    int backupSlot = slot + 100;
-    await saveRepo.SaveAsync(backupSlot, saveData);
-
-    Console.WriteLine($"存档已备份到槽位 {backupSlot}");
-}
-
-public async Task RestoreBackup(int slot)
-{
-    int backupSlot = slot + 100;
-    var saveRepo = this.GetUtility<ISaveRepository<SaveData>>();
-
-    if (!await saveRepo.ExistsAsync(backupSlot))
-    {
-        Console.WriteLine("备份不存在");
-        return;
-    }
-
-    // 加载备份
-    var backupData = await saveRepo.LoadAsync(backupSlot);
-
-    // 恢复到原槽位
-    await saveRepo.SaveAsync(slot, backupData);
-
-    Console.WriteLine($"已从备份恢复到槽位 {slot}");
-}
-```
-
-## 最佳实践
-
-1. **使用版本化数据**：为存档数据实现 `IVersionedData`
-   ```csharp
-   ✓ public class SaveData : IVersionedData { public int Version { get; set; } = 1; }
-   ✗ public class SaveData : IData { } // 无法进行版本管理
-   ```
-
-2. **定期自动保存**：避免玩家数据丢失
-   ```csharp
-   // 每 5 分钟自动保存
-   StartAutoSave(currentSlot, TimeSpan.FromMinutes(5));
-   ```
-
-3. **保存前验证数据**：确保数据完整性
-   ```csharp
-   public async Task SaveGame(int slot)
-   {
-       var saveData = CreateSaveData();
-
-       if (!ValidateSaveData(saveData))
-       {
-           throw new InvalidOperationException("存档数据无效");
-       }
-
-       await saveRepo.SaveAsync(slot, saveData);
-   }
-   ```
-
-4. **处理保存失败**：使用 try-catch 捕获异常
-   ```csharp
-   try
-   {
-       await saveRepo.SaveAsync(slot, saveData);
-   }
-   catch (Exception ex)
-   {
-       Logger.Error($"保存失败: {ex.Message}");
-       ShowErrorMessage("保存失败，请重试");
-   }
-   ```
-
-5. **提供多个存档槽位**：让玩家可以管理多个存档
-   ```csharp
-   // 支持 10 个存档槽位
-   for (int i = 1; i <= 10; i++)
-   {
-       if (await saveRepo.ExistsAsync(i))
-       {
-           ShowSaveSlot(i);
-       }
-   }
-   ```
-
-6. **在关键时刻保存**：场景切换、关卡完成等
-   ```csharp
-   public async Task OnLevelComplete()
-   {
-       // 关卡完成时自动保存
-       await SaveGame(currentSlot);
-   }
-   ```
-
-## 常见问题
-
-### 问题：如何实现多个存档槽位？
-
-**解答**：
-使用 `ISaveRepository<T>` 的槽位参数：
-
-```csharp
-// 保存到不同槽位
-await saveRepo.SaveAsync(1, saveData);  // 槽位 1
-await saveRepo.SaveAsync(2, saveData);  // 槽位 2
-await saveRepo.SaveAsync(3, saveData);  // 槽位 3
-```
-
-### 问题：如何处理数据版本升级？
-
-**解答**：
-实现 `IVersionedData`，并在仓库初始化阶段注册 `ISaveMigration<TSaveData>`。之后 `LoadAsync(slot)` 会自动执行迁移并回写：
-
-```csharp
-var saveRepo = new SaveRepository<SaveData>(storage, saveConfig)
-    .RegisterMigration(new SaveDataMigrationV1ToV2())
-    .RegisterMigration(new SaveDataMigrationV2ToV3());
-
-var data = await saveRepo.LoadAsync(slot);
-```
-
-### 问题：存档数据保存在哪里？
-
-**解答**：
-由存储系统决定，通常在：
-
-- Windows: `%AppData%/GameName/saves/`
-- Linux: `~/.local/share/GameName/saves/`
-- macOS: `~/Library/Application Support/GameName/saves/`
-
-### 问题：如何实现云存档？
-
-**解答**：
-实现自定义的 `IStorage`，将数据保存到云端：
-
-```csharp
-public class CloudStorage : IStorage
-{
-    public async Task WriteAsync(string path, byte[] data)
-    {
-        await UploadToCloud(path, data);
-    }
-
-    public async Task<byte[]> ReadAsync(string path)
-    {
-        return await DownloadFromCloud(path);
-    }
-}
-```
-
-### 问题：如何加密存档数据？
-
-**解答**：
-在保存和加载时进行加密/解密：
-
-```csharp
-public async Task SaveEncrypted(int slot, SaveData data)
-{
-    var json = JsonSerializer.Serialize(data);
-    var encrypted = Encrypt(json);
-    await storage.WriteAsync(path, encrypted);
-}
-
-public async Task<SaveData> LoadEncrypted(int slot)
-{
-    var encrypted = await storage.ReadAsync(path);
-    var json = Decrypt(encrypted);
-    return JsonSerializer.Deserialize<SaveData>(json);
-}
-```
-
-### 问题：存档损坏怎么办？
-
-**解答**：
-实现备份和恢复机制：
-
-```csharp
-public async Task SaveWithBackup(int slot, SaveData data)
-{
-    // 先备份旧存档
-    if (await saveRepo.ExistsAsync(slot))
-    {
-        var oldData = await saveRepo.LoadAsync(slot);
-        await saveRepo.SaveAsync(slot + 100, oldData);
-    }
-
-    // 保存新存档
-    await saveRepo.SaveAsync(slot, data);
-}
-```
-
-## 相关文档
-
-- [设置系统](/zh-CN/game/setting) - 游戏设置管理
-- [场景系统](/zh-CN/game/scene) - 场景切换时保存
-- [存档系统实现教程](/zh-CN/tutorials/save-system) - 完整示例
-- [Godot 集成](/zh-CN/godot/index) - Godot 中的数据管理
+1. [设置系统](./setting.md)
+2. [存储系统](./storage.md)
+3. [序列化系统](./serialization.md)
+4. [Game 入口](./index.md)
diff --git a/docs/zh-CN/game/serialization.md b/docs/zh-CN/game/serialization.md
index fdc24ba1..d07487c5 100644
--- a/docs/zh-CN/game/serialization.md
+++ b/docs/zh-CN/game/serialization.md
@@ -1,811 +1,162 @@
 ---
 title: 序列化系统
-description: 序列化系统提供了统一的对象序列化和反序列化接口，支持 JSON 格式和运行时类型处理。
+description: 以当前 GFramework.Game.JsonSerializer 与 JsonSerializerTests 为准，说明 JSON 序列化器的配置生命周期和使用边界。
 ---
 
 # 序列化系统
 
-## 概述
+`GFramework.Game` 当前在序列化这一层的默认公开入口只有 `JsonSerializer`。
 
-序列化系统是 GFramework.Game 中用于对象序列化和反序列化的核心组件。它提供了统一的序列化接口，支持将对象转换为字符串格式（如
-JSON）进行存储或传输，并能够将字符串数据还原为对象。
+它实现的是：
 
-序列化系统与数据存储、配置管理、存档系统等模块深度集成，为游戏数据的持久化提供了基础支持。
+- `ISerializer`
+- `IRuntimeTypeSerializer`
 
-**主要特性**：
+它不负责：
 
-- 统一的序列化接口
-- JSON 格式支持
-- 运行时类型序列化
-- 泛型和非泛型 API
-- 与存储系统无缝集成
-- 类型安全的反序列化
+- schema 驱动配置生成
+- 存档槽位管理
+- 文件路径或目录布局
 
-## 核心概念
+这些能力分别属于 source generator、repository 和 storage。
 
-### 序列化器接口
+## 当前公开入口
 
-`ISerializer` 定义了基本的序列化操作：
+### `JsonSerializer`
 
-```csharp
-public interface ISerializer : IUtility
-{
-    // 将对象序列化为字符串
-    string Serialize&lt;T&gt;(T value);
-
-    // 将字符串反序列化为对象
-    T Deserialize&lt;T&gt;(string data);
-}
-```
-
-### 运行时类型序列化器
-
-`IRuntimeTypeSerializer` 扩展了基本接口，支持运行时类型处理：
-
-```csharp
-public interface IRuntimeTypeSerializer : ISerializer
-{
-    // 使用运行时类型序列化对象
-    string Serialize(object obj, Type type);
-
-    // 使用运行时类型反序列化对象
-    object Deserialize(string data, Type type);
-}
-```
-
-### JSON 序列化器
-
-`JsonSerializer` 是基于 Newtonsoft.Json 的实现。它会直接复用构造时提供的
-`JsonSerializerSettings` 与 `Converters` 集合，因此推荐在组合根统一完成配置，再把同一个实例注册到架构或仓库中复用：
-
-```csharp
-public sealed class JsonSerializer : IRuntimeTypeSerializer
-{
-    string Serialize&lt;T&gt;(T value);
-    T Deserialize&lt;T&gt;(string data);
-    string Serialize(object obj, Type type);
-    object Deserialize(string data, Type type);
-}
-```
-
-## 基本用法
-
-### 注册序列化器
-
-在架构中注册序列化器：
+`JsonSerializer` 基于 `Newtonsoft.Json`，既支持泛型 API，也支持运行时类型 API：
 
 ```csharp
 using GFramework.Core.Abstractions.Serializer;
 using GFramework.Game.Serializer;
 
-public class GameArchitecture : Architecture
-{
-    protected override void Init()
-    {
-        // 在启动阶段一次性完成配置，后续将该实例视为只读
-        var jsonSerializer = new JsonSerializer();
-        jsonSerializer.Converters.Add(new PlayerDataJsonConverter());
-
-        RegisterUtility<ISerializer>(jsonSerializer);
-        RegisterUtility<IRuntimeTypeSerializer>(jsonSerializer);
-    }
-}
+ISerializer serializer = new JsonSerializer();
+IRuntimeTypeSerializer runtimeSerializer = new JsonSerializer();
 ```
 
-### 序列化对象
+当前测试覆盖的核心行为包括：
 
-使用泛型 API 序列化对象：
+- 普通对象可正常 round-trip
+- 注入的 `JsonSerializerSettings` 会直接生效
+- `Settings` 与 `Converters` 暴露的是同一个活动配置实例
+- 运行时类型序列化 / 反序列化可处理 `object + Type`
+- 非法 JSON 会抛出带目标类型上下文的 `InvalidOperationException`
+- 非法参数（例如空字符串）会保留 `ArgumentException`
+- 运行时类型序列化允许 `null`，输出 `"null"`
+
+## 配置生命周期
+
+这部分是当前实现最容易被旧文档说错的地方。
+
+`JsonSerializer` 不会复制你传入的 `JsonSerializerSettings`。它会直接持有并复用这份实例，以及里面的 `Converters` 集合。
+
+这意味着推荐模式是：
+
+1. 在组合根创建序列化器
+2. 一次性完成 settings / converters 配置
+3. 再把同一个实例注册给存储、repository 或 architecture
+
+推荐写法：
 
 ```csharp
-using GFramework.Core.SourceGenerators.Abstractions.Rule;
+using Newtonsoft.Json;
 
-public class PlayerData
-{
-    public string Name { get; set; }
-    public int Level { get; set; }
-    public int Experience { get; set; }
-}
-
-[ContextAware]
-public partial class SaveController : IController
-{
-    public void SavePlayer()
-    {
-        var serializer = this.GetUtility<ISerializer>();
-
-        var player = new PlayerData
-        {
-            Name = "Player1",
-            Level = 10,
-            Experience = 1000
-        };
-
-        // 序列化为 JSON 字符串
-        string json = serializer.Serialize(player);
-        Console.WriteLine(json);
-        // 输出: {"Name":"Player1","Level":10,"Experience":1000}
-    }
-}
-```
-
-### 反序列化对象
-
-从字符串还原对象：
-
-```csharp
-public void LoadPlayer()
-{
-    var serializer = this.GetUtility<ISerializer>();
-
-    string json = "{\"Name\":\"Player1\",\"Level\":10,\"Experience\":1000}";
-
-    // 反序列化为对象
-    var player = serializer.Deserialize<PlayerData>(json);
-
-    Console.WriteLine($"玩家: {player.Name}, 等级: {player.Level}");
-}
-```
-
-### 运行时类型序列化
-
-处理不确定类型的对象：
-
-```csharp
-public void SerializeRuntimeType()
-{
-    var serializer = this.GetUtility<IRuntimeTypeSerializer>();
-
-    object data = new PlayerData { Name = "Player1", Level = 10 };
-    Type dataType = data.GetType();
-
-    // 使用运行时类型序列化
-    string json = serializer.Serialize(data, dataType);
-
-    // 使用运行时类型反序列化
-    object restored = serializer.Deserialize(json, dataType);
-
-    var player = restored as PlayerData;
-    Console.WriteLine($"玩家: {player?.Name}");
-}
-```
-
-### 配置生命周期约束
-
-`JsonSerializer` 不会复制 `JsonSerializerSettings`。这意味着：
-
-- 传给构造函数的 settings 会被原样保留
-- `serializer.Settings` 与 `serializer.Converters` 返回的都是活动配置对象
-- 一旦序列化器实例已经注册给其他模块或开始被并发调用，就不应继续修改这些配置
-
-推荐模式：
-
-```csharp
 var settings = new JsonSerializerSettings
 {
     Formatting = Formatting.Indented,
     NullValueHandling = NullValueHandling.Ignore
 };
 
-settings.Converters.Add(new Vector2JsonConverter());
+settings.Converters.Add(new CoordinateConverter());
 
 var serializer = new JsonSerializer(settings);
+```
+
+不推荐写法：
+
+```csharp
+var serializer = architecture.GetUtility<IRuntimeTypeSerializer>();
+
+// 序列化器已经被多个组件共享后，再继续改 converter，容易让并发调用看到不稳定配置。
+((JsonSerializer)serializer).Converters.Add(new LateBoundConverter());
+```
+
+## 最小接入路径
+
+### 作为底层 serializer 注册
+
+当前更常见的采用方式不是“业务代码直接到处调 serializer”，而是把它注册给存储和 repository 复用：
+
+```csharp
+using GFramework.Core.Abstractions.Serializer;
+using GFramework.Game.Serializer;
+
+var serializer = new JsonSerializer();
 
 architecture.RegisterUtility<ISerializer>(serializer);
 architecture.RegisterUtility<IRuntimeTypeSerializer>(serializer);
 ```
 
-不推荐模式：
+然后由：
+
+- `FileStorage`
+- `UnifiedSettingsDataRepository`
+- 其他依赖 `ISerializer` / `IRuntimeTypeSerializer` 的组件
+
+统一复用这一份实例。
+
+### 直接处理运行时类型
+
+当业务层拿到的是 `object + Type` 组合，而不是静态泛型类型时，再使用运行时 API：
 
 ```csharp
-var serializer = architecture.GetUtility<IRuntimeTypeSerializer>();
+var serializer = new JsonSerializer();
 
-// 已经共享给运行时后再修改配置，容易让并发调用得到不稳定行为
-((JsonSerializer)serializer).Converters.Add(new LateBoundConverter());
+object data = new PlayerState
+{
+    Name = "Runtime",
+    Level = 11
+};
+
+var json = serializer.Serialize(data, data.GetType());
+var restored = serializer.Deserialize(json, data.GetType());
 ```
 
-## 高级用法
+## 与存储系统的关系
 
-### 与存储系统集成
+`FileStorage` 已经会调用注入的 `ISerializer` 自己完成对象读写，因此当前默认接法里：
 
-序列化器与存储系统配合使用：
+- 你可以直接 `storage.WriteAsync("profile/player", profile)`
+- 不需要先手工 `serializer.Serialize(profile)` 再把字符串写回存储
 
-```csharp
-using GFramework.Core.Abstractions.Storage;
-using GFramework.Game.Storage;
-using GFramework.Core.SourceGenerators.Abstractions.Rule;
+手工显式调用 `Serialize(...)` 更适合这些场景：
 
-[ContextAware]
-public partial class DataManager : IController
-{
-    public async Task SaveData()
-    {
-        var serializer = this.GetUtility<ISerializer>();
-        var storage = this.GetUtility<IStorage>();
+- 需要把 JSON 发到网络或日志
+- 需要和外部文本格式做中转
+- 需要直接调试序列化输出内容
 
-        var gameData = new GameData
-        {
-            Score = 1000,
-            Coins = 500
-        };
+如果目标只是本地持久化，优先让 `IStorage` / repository 复用 serializer。
 
-        // 序列化数据
-        string json = serializer.Serialize(gameData);
+## 与配置系统的关系
 
-        // 写入存储
-        await storage.WriteAsync("game_data", json);
-    }
+不要把 `JsonSerializer` 和 `Game` 的 YAML 配置系统混在一起：
 
-    public async Task<GameData> LoadData()
-    {
-        var serializer = this.GetUtility<ISerializer>();
-        var storage = this.GetUtility<IStorage>();
+- `JsonSerializer`
+  - 负责运行时对象 JSON 序列化
+- `Game.SourceGenerators + YamlConfigLoader`
+  - 负责 schema 驱动的配置表生成与 YAML 读取
 
-        // 从存储读取
-        string json = await storage.ReadAsync<string>("game_data");
+如果你的目标是静态内容配置表，而不是运行时持久化对象，请改看 [`config-system.md`](./config-system.md)。
 
-        // 反序列化数据
-        return serializer.Deserialize<GameData>(json);
-    }
-}
-```
+## 当前边界
 
-### 序列化复杂对象
+- 当前公开默认实现只有 JSON，没有内建 MessagePack、Binary 或 ProtoBuf 实现
+- `JsonSerializer` 负责序列化，不负责对象版本迁移；版本迁移属于 `SettingsModel<TRepository>` 或 `SaveRepository<TSaveData>`
+- 序列化器共享后应视为只读配置对象，避免在运行期继续修改 settings / converters
 
-处理嵌套和集合类型：
+## 继续阅读
 
-```csharp
-public class InventoryData
-{
-    public List<ItemData> Items { get; set; }
-    public Dictionary<string, int> Resources { get; set; }
-}
-
-public class ItemData
-{
-    public string Id { get; set; }
-    public string Name { get; set; }
-    public int Quantity { get; set; }
-}
-
-public void SerializeComplexData()
-{
-    var serializer = this.GetUtility<ISerializer>();
-
-    var inventory = new InventoryData
-    {
-        Items = new List<ItemData>
-        {
-            new ItemData { Id = "sword_01", Name = "铁剑", Quantity = 1 },
-            new ItemData { Id = "potion_hp", Name = "生命药水", Quantity = 5 }
-        },
-        Resources = new Dictionary<string, int>
-        {
-            { "gold", 1000 },
-            { "wood", 500 }
-        }
-    };
-
-    // 序列化复杂对象
-    string json = serializer.Serialize(inventory);
-
-    // 反序列化
-    var restored = serializer.Deserialize<InventoryData>(json);
-
-    Console.WriteLine($"物品数量: {restored.Items.Count}");
-    Console.WriteLine($"金币: {restored.Resources["gold"]}");
-}
-```
-
-### 处理多态类型
-
-序列化继承层次结构：
-
-```csharp
-public abstract class EntityData
-{
-    public string Id { get; set; }
-    public string Type { get; set; }
-}
-
-public class PlayerEntityData : EntityData
-{
-    public int Level { get; set; }
-    public int Experience { get; set; }
-}
-
-public class EnemyEntityData : EntityData
-{
-    public int Health { get; set; }
-    public int Damage { get; set; }
-}
-
-public void SerializePolymorphic()
-{
-    var serializer = this.GetUtility<IRuntimeTypeSerializer>();
-
-    // 创建不同类型的实体
-    EntityData player = new PlayerEntityData
-    {
-        Id = "player_1",
-        Type = "Player",
-        Level = 10,
-        Experience = 1000
-    };
-
-    EntityData enemy = new EnemyEntityData
-    {
-        Id = "enemy_1",
-        Type = "Enemy",
-        Health = 100,
-        Damage = 20
-    };
-
-    // 使用运行时类型序列化
-    string playerJson = serializer.Serialize(player, player.GetType());
-    string enemyJson = serializer.Serialize(enemy, enemy.GetType());
-
-    // 根据类型反序列化
-    var restoredPlayer = serializer.Deserialize(playerJson, typeof(PlayerEntityData));
-    var restoredEnemy = serializer.Deserialize(enemyJson, typeof(EnemyEntityData));
-}
-```
-
-### 自定义序列化逻辑
-
-虽然 GFramework 使用 Newtonsoft.Json，但你可以通过特性控制序列化行为：
-
-```csharp
-using Newtonsoft.Json;
-
-public class CustomData
-{
-    // 忽略此属性
-    [JsonIgnore]
-    public string InternalId { get; set; }
-
-    // 使用不同的属性名
-    [JsonProperty("player_name")]
-    public string Name { get; set; }
-
-    // 仅在值不为 null 时序列化
-    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
-    public string? OptionalField { get; set; }
-
-    // 格式化日期
-    [JsonProperty("created_at")]
-    [JsonConverter(typeof(IsoDateTimeConverter))]
-    public DateTime CreatedAt { get; set; }
-}
-```
-
-### 批量序列化
-
-处理多个对象的序列化：
-
-```csharp
-public async Task SaveMultipleData()
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    var dataList = new Dictionary<string, object>
-    {
-        { "player", new PlayerData { Name = "Player1", Level = 10 } },
-        { "inventory", new InventoryData { Items = new List<ItemData>() } },
-        { "settings", new SettingsData { Volume = 0.8f } }
-    };
-
-    // 批量序列化和保存
-    foreach (var (key, data) in dataList)
-    {
-        string json = serializer.Serialize(data);
-        await storage.WriteAsync(key, json);
-    }
-
-    Console.WriteLine($"已保存 {dataList.Count} 个数据文件");
-}
-```
-
-### 错误处理
-
-处理序列化和反序列化错误：
-
-```csharp
-public void SafeDeserialize()
-{
-    var serializer = this.GetUtility<ISerializer>();
-
-    string json = "{\"Name\":\"Player1\",\"Level\":\"invalid\"}"; // 错误的数据
-
-    try
-    {
-        var player = serializer.Deserialize<PlayerData>(json);
-    }
-    catch (ArgumentException ex)
-    {
-        Console.WriteLine($"反序列化失败: {ex.Message}");
-        // 返回默认值或重新尝试
-    }
-    catch (JsonException ex)
-    {
-        Console.WriteLine($"JSON 格式错误: {ex.Message}");
-    }
-}
-
-public PlayerData DeserializeWithFallback(string json)
-{
-    var serializer = this.GetUtility<ISerializer>();
-
-    try
-    {
-        return serializer.Deserialize<PlayerData>(json);
-    }
-    catch
-    {
-        // 返回默认数据
-        return new PlayerData
-        {
-            Name = "DefaultPlayer",
-            Level = 1,
-            Experience = 0
-        };
-    }
-}
-```
-
-### 版本兼容性
-
-处理数据结构变化：
-
-```csharp
-// 旧版本数据
-public class PlayerDataV1
-{
-    public string Name { get; set; }
-    public int Level { get; set; }
-}
-
-// 新版本数据（添加了新字段）
-public class PlayerDataV2
-{
-    public string Name { get; set; }
-    public int Level { get; set; }
-    public int Experience { get; set; } = 0;  // 新增字段，提供默认值
-    public DateTime LastLogin { get; set; } = DateTime.Now;  // 新增字段
-}
-
-public PlayerDataV2 LoadWithMigration(string json)
-{
-    var serializer = this.GetUtility<ISerializer>();
-
-    try
-    {
-        // 尝试加载新版本
-        return serializer.Deserialize<PlayerDataV2>(json);
-    }
-    catch
-    {
-        // 如果失败，尝试加载旧版本并迁移
-        var oldData = serializer.Deserialize<PlayerDataV1>(json);
-        return new PlayerDataV2
-        {
-            Name = oldData.Name,
-            Level = oldData.Level,
-            Experience = oldData.Level * 100,  // 根据等级计算经验
-            LastLogin = DateTime.Now
-        };
-    }
-}
-```
-
-## 最佳实践
-
-1. **优先依赖接口，在组合根统一实例化**：业务代码依赖 `ISerializer`，具体 `JsonSerializer` 在启动阶段配置一次即可
-   ```csharp
-   ✓ var serializer = this.GetUtility<ISerializer>();
-   ✓ var serializer = new JsonSerializer(settings); // 仅在组合根/启动阶段配置
-   ✗ var serializer = new JsonSerializer(); // 避免在业务逻辑中临时创建
-   ```
-
-2. **为数据类提供默认值**：确保反序列化的健壮性
-   ```csharp
-   public class GameData
-   {
-       public string Name { get; set; } = "Default";
-       public int Score { get; set; } = 0;
-       public List<string> Items { get; set; } = new();
-   }
-   ```
-
-3. **处理反序列化异常**：避免程序崩溃
-   ```csharp
-   try
-   {
-       var data = serializer.Deserialize<GameData>(json);
-   }
-   catch (Exception ex)
-   {
-       Logger.Error($"反序列化失败: {ex.Message}");
-       return GetDefaultData();
-   }
-   ```
-
-4. **避免序列化敏感数据**：使用 `[JsonIgnore]` 标记
-   ```csharp
-   public class UserData
-   {
-       public string Username { get; set; }
-
-       [JsonIgnore]
-       public string Password { get; set; }  // 不序列化密码
-   }
-   ```
-
-5. **使用运行时类型处理多态**：保持类型信息
-   ```csharp
-   var serializer = this.GetUtility<IRuntimeTypeSerializer>();
-   string json = serializer.Serialize(obj, obj.GetType());
-   ```
-
-6. **验证反序列化的数据**：确保数据完整性
-   ```csharp
-   var data = serializer.Deserialize<GameData>(json);
-   if (string.IsNullOrEmpty(data.Name) || data.Score < 0)
-   {
-       throw new InvalidDataException("数据验证失败");
-   }
-   ```
-
-## 性能优化
-
-### 减少序列化开销
-
-```csharp
-// 避免频繁序列化大对象
-public class CachedSerializer
-{
-    private string? _cachedJson;
-    private GameData? _cachedData;
-
-    public string GetJson(GameData data)
-    {
-        if (_cachedData == data && _cachedJson != null)
-        {
-            return _cachedJson;
-        }
-
-        var serializer = GetSerializer();
-        _cachedJson = serializer.Serialize(data);
-        _cachedData = data;
-        return _cachedJson;
-    }
-}
-```
-
-### 异步序列化
-
-```csharp
-public async Task SaveDataAsync()
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    var data = GetLargeData();
-
-    // 在后台线程序列化
-    string json = await Task.Run(() => serializer.Serialize(data));
-
-    // 异步写入存储
-    await storage.WriteAsync("large_data", json);
-}
-```
-
-### 分块序列化
-
-```csharp
-public async Task SaveLargeDataset()
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    var largeDataset = GetLargeDataset();
-
-    // 分块保存
-    const int chunkSize = 100;
-    for (int i = 0; i < largeDataset.Count; i += chunkSize)
-    {
-        var chunk = largeDataset.Skip(i).Take(chunkSize).ToList();
-        string json = serializer.Serialize(chunk);
-        await storage.WriteAsync($"data_chunk_{i / chunkSize}", json);
-    }
-}
-```
-
-## 常见问题
-
-### 问题：如何序列化循环引用的对象？
-
-**解答**：
-Newtonsoft.Json 默认不支持循环引用，需要配置：
-
-```csharp
-// 注意：GFramework 的 JsonSerializer 使用默认设置
-// 如需处理循环引用，避免创建循环引用的数据结构
-// 或使用 [JsonIgnore] 打破循环
-
-public class Node
-{
-    public string Name { get; set; }
-    public List<Node> Children { get; set; }
-
-    [JsonIgnore]  // 忽略父节点引用，避免循环
-    public Node? Parent { get; set; }
-}
-```
-
-### 问题：序列化后的 JSON 太大怎么办？
-
-**解答**：
-使用压缩或分块存储：
-
-```csharp
-public async Task SaveCompressed()
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    var data = GetLargeData();
-    string json = serializer.Serialize(data);
-
-    // 压缩 JSON
-    byte[] compressed = Compress(json);
-
-    // 保存压缩数据
-    await storage.WriteAsync("data_compressed", compressed);
-}
-
-private byte[] Compress(string text)
-{
-    using var output = new MemoryStream();
-    using (var gzip = new GZipStream(output, CompressionMode.Compress))
-    using (var writer = new StreamWriter(gzip))
-    {
-        writer.Write(text);
-    }
-    return output.ToArray();
-}
-```
-
-### 问题：如何处理不同平台的序列化差异？
-
-**解答**：
-使用平台无关的数据类型：
-
-```csharp
-public class CrossPlatformData
-{
-    // 使用 string 而非 DateTime（避免时区问题）
-    public string CreatedAt { get; set; } = DateTime.UtcNow.ToString("O");
-
-    // 使用 double 而非 float（精度一致）
-    public double Score { get; set; }
-
-    // 明确指定编码
-    public string Text { get; set; }
-}
-```
-
-### 问题：反序列化失败时如何恢复？
-
-**解答**：
-实现备份和恢复机制：
-
-```csharp
-public async Task<GameData> LoadWithBackup(string key)
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    try
-    {
-        // 尝试加载主数据
-        string json = await storage.ReadAsync<string>(key);
-        return serializer.Deserialize<GameData>(json);
-    }
-    catch
-    {
-        // 尝试加载备份
-        try
-        {
-            string backupJson = await storage.ReadAsync<string>($"{key}_backup");
-            return serializer.Deserialize<GameData>(backupJson);
-        }
-        catch
-        {
-            // 返回默认数据
-            return new GameData();
-        }
-    }
-}
-```
-
-### 问题：如何加密序列化的数据？
-
-**解答**：
-在序列化后加密：
-
-```csharp
-public async Task SaveEncrypted(string key, GameData data)
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    // 序列化
-    string json = serializer.Serialize(data);
-
-    // 加密
-    byte[] encrypted = EncryptString(json);
-
-    // 保存
-    await storage.WriteAsync(key, encrypted);
-}
-
-public async Task<GameData> LoadEncrypted(string key)
-{
-    var serializer = this.GetUtility<ISerializer>();
-    var storage = this.GetUtility<IStorage>();
-
-    // 读取
-    byte[] encrypted = await storage.ReadAsync<byte[]>(key);
-
-    // 解密
-    string json = DecryptToString(encrypted);
-
-    // 反序列化
-    return serializer.Deserialize<GameData>(json);
-}
-```
-
-### 问题：序列化器是线程安全的吗？
-
-**解答**：
-`JsonSerializer` 的并发读行为只在“配置不再变化”这个前提下才安全。当前实现会暴露活动中的
-`JsonSerializerSettings` 与 `Converters` 集合，因此：
-
-- 可以在启动阶段创建并配置一个共享实例
-- 可以在配置冻结后把该实例注册为 Utility 或注入到仓库
-- 不应在序列化器已经被多个调用方使用时继续修改 settings、contract resolver 或 converters
-
-推荐按下面的方式在启动阶段完成配置，然后只做读操作：
-
-```csharp
-// 启动阶段完成全部配置
-var serializer = new JsonSerializer(new JsonSerializerSettings
-{
-    NullValueHandling = NullValueHandling.Ignore
-});
-serializer.Converters.Add(new GameDataJsonConverter());
-
-architecture.RegisterUtility<ISerializer>(serializer);
-
-// 运行阶段只复用，不再修改配置
-public async Task ParallelSave()
-{
-    var tasks = Enumerable.Range(0, 10).Select(async i =>
-    {
-        var serializer = this.GetUtility<ISerializer>();
-        var data = new GameData { Score = i };
-        string json = serializer.Serialize(data);
-        await SaveToStorage($"data_{i}", json);
-    });
-
-    await Task.WhenAll(tasks);
-}
-```
-
-## 相关文档
-
-- [数据与存档系统](/zh-CN/game/data) - 数据持久化
-- [存储系统](/zh-CN/game/storage) - 文件存储
-- [设置系统](/zh-CN/game/setting) - 设置数据序列化
-- [Utility 系统](/zh-CN/core/utility) - 工具类注册
+1. [存储系统](./storage.md)
+2. [数据与存档系统](./data.md)
+3. [配置系统](./config-system.md)
+4. [Game 入口](./index.md)
diff --git a/docs/zh-CN/game/setting.md b/docs/zh-CN/game/setting.md
index 67f998e8..b5bc724e 100644
--- a/docs/zh-CN/game/setting.md
+++ b/docs/zh-CN/game/setting.md
@@ -1,207 +1,204 @@
+---
+title: 设置系统
+description: 以当前 SettingsModel、SettingsSystem 与相关测试为准，说明设置数据、applicator、迁移和持久化的真实接法。
+---
+
 # 设置系统
 
-设置系统负责管理 `ISettingsData`、持久化加载/保存，以及把设置真正应用到运行时环境。
+`GFramework.Game` 的设置系统负责三件事：
 
-当前实现以 `SettingsModel<TRepository>` 和 `SettingsSystem` 为核心，已经不是旧文档中的
-`Get<T>() / Register(IApplyAbleSettings)` 接口模型。
+- 管理 `ISettingsData` 实例的生命周期
+- 管理设置 applicator，并把设置真正作用到运行时环境
+- 在初始化时加载、迁移、保存和重置设置
 
-## 核心概念
+当前默认 owner 是：
 
-### ISettingsData
+- `SettingsModel<TRepository>`
+- `SettingsSystem`
 
-设置数据对象负责保存设置值、提供默认值，并在加载后把外部数据回填到当前实例。
+而不是旧文档里那种“只靠若干 `Get<T>() / Register(...)` 辅助方法就能自动完成一切”的模型。
+
+## 当前公开入口
+
+### `ISettingsData`
+
+设置数据对象需要同时承担：
+
+- 默认值持有者
+- 版本化 section
+- 从已加载数据回填到当前实例的入口
+
+当前接口组合是：
 
 ```csharp
 public interface ISettingsData : IResettable, IVersionedData, ILoadableFrom<ISettingsData>;
 ```
 
-这意味着一个设置数据类型通常需要实现：
+这意味着一个设置数据类型至少要处理：
 
-- `Reset()`：恢复默认值
-- `Version` / `LastModified`：暴露版本化信息
-- `LoadFrom(ISettingsData)`：把已加载或迁移后的数据复制到当前实例
+- `Reset()`
+- `Version`
+- `LastModified`
+- `LoadFrom(ISettingsData source)`
 
-### IResetApplyAbleSettings
+### `IResetApplyAbleSettings`
 
-应用器负责把设置数据作用到引擎或运行时环境：
+applicator 的职责不是保存数据，而是把设置结果作用到实际运行时对象。
+
+它当前需要暴露：
+
+- `Data`
+- `DataType`
+- `Reset()`
+- `ApplyAsync()`
+
+典型场景包括：
+
+- 把音量设置同步到音频系统
+- 把画质设置同步到窗口或渲染配置
+- 把语言设置同步到本地化服务
+
+### `SettingsModel<TRepository>`
+
+这是当前设置系统的核心编排器。按当前源码，它负责：
+
+- `GetData<T>()`
+  - 返回某个设置类型的唯一实例
+- `RegisterApplicator(...)`
+  - 注册 applicator，并把其 `Data` 一并纳入模型管理
+- `RegisterMigration(...)`
+  - 注册同一设置类型的前进式迁移链
+- `InitializeAsync()`
+  - 从 repository 读取所有设置、执行迁移、回填到当前实例
+- `SaveAllAsync()`
+  - 持久化所有已登记的设置数据
+- `ApplyAllAsync()`
+  - 依次应用所有 applicator
+- `Reset<T>() / ResetAll()`
+  - 重置单个或全部设置
+
+### `SettingsSystem`
+
+`SettingsSystem` 是面向业务代码更直接的一层系统封装：
+
+- `ApplyAll()`
+- `Apply<T>()`
+- `SaveAll()`
+- `Reset<T>()`
+- `ResetAll()`
+
+它自己不持有独立设置状态，而是把工作委托给 `ISettingsModel`，并在应用时补发 settings 相关事件。
+
+## 初始化与迁移的真实语义
+
+`SettingsModel<TRepository>.InitializeAsync()` 的当前行为，比旧文档里“加载一下就好”更严格一些：
+
+- 它会先调用 `ISettingsDataRepository.LoadAllAsync()`
+- 再逐个匹配当前模型里已经登记的设置类型
+- 如果读到了旧版本设置，会以“当前内存实例声明的 `Version`”为目标版本执行迁移
+- 迁移完成后通过 `LoadFrom(...)` 回填到现有实例，而不是直接替换对象引用
+
+当前测试还确认了几个关键边界：
+
+- 同一设置类型的同一个 `FromVersion` 不能重复注册迁移器
+- 注册新迁移器后，类型级迁移缓存会失效并重建，不会继续使用旧快照
+- 如果迁移链缺口导致无法安全升级，模型会保留当前内存中的最新实例，而不是把不完整的旧数据覆盖进来
+- 单个设置 section 初始化失败时，模型会记录错误并继续处理其他 section
+
+这套语义更接近“尽量保证运行时实例总是可用”，而不是“任意旧设置都必须成功导入”。
+
+## 最小接入路径
+
+当前最常见的接法是：
+
+1. 准备一个 `IStorage`
+2. 准备一个 `IRuntimeTypeSerializer`
+3. 注册 `ISettingsDataRepository`
+4. 注册 `IDataLocationProvider`
+5. 创建并注册 `SettingsModel<TRepository>`
+6. 注册 applicator
+7. 注册 `SettingsSystem`
+
+示意代码：
 
 ```csharp
-public interface IResetApplyAbleSettings : IResettable, IApplyAbleSettings
-{
-    ISettingsData Data { get; }
-    Type DataType { get; }
-}
+using GFramework.Core.Abstractions.Storage;
+using GFramework.Game.Abstractions.Data;
+using GFramework.Game.Abstractions.Setting;
+using GFramework.Game.Data;
+using GFramework.Game.Serializer;
+using GFramework.Game.Setting;
+using GFramework.Game.Storage;
+
+var serializer = new JsonSerializer();
+var storage = new FileStorage("GameData", serializer, ".json");
+
+var repository = new UnifiedSettingsDataRepository(
+    storage,
+    serializer,
+    new DataRepositoryOptions
+    {
+        BasePath = "settings",
+        AutoBackup = true
+    });
+
+architecture.RegisterUtility<IStorage>(storage);
+architecture.RegisterUtility<IRuntimeTypeSerializer>(serializer);
+architecture.RegisterUtility<ISettingsDataRepository>(repository);
+// 此处注册项目侧的 IDataLocationProvider 实现，用于把设置类型映射到 section key。
+
+var settingsModel = new SettingsModel<ISettingsDataRepository>(null, null);
+// 在注册到架构前，继续补 applicator 与 migration。
+
+architecture.RegisterModel<ISettingsModel>(settingsModel);
+architecture.RegisterSystem<ISettingsSystem>(new SettingsSystem());
 ```
 
-常见用途包括：
-
-- 把音量设置同步到音频总线
-- 把图形设置同步到窗口系统
-- 把语言设置同步到本地化管理器
-
-## ISettingsModel
-
-当前 `ISettingsModel` 的主要 API 如下：
+启动阶段通常是：
 
 ```csharp
-public interface ISettingsModel : IModel
-{
-    bool IsInitialized { get; }
-
-    T GetData<T>() where T : class, ISettingsData, new();
-    IEnumerable<ISettingsData> AllData();
-
-    ISettingsModel RegisterApplicator<T>(T applicator)
-        where T : class, IResetApplyAbleSettings;
-    T? GetApplicator<T>() where T : class, IResetApplyAbleSettings;
-    IEnumerable<IResetApplyAbleSettings> AllApplicators();
-
-    ISettingsModel RegisterMigration(ISettingsMigration migration);
-
-    Task InitializeAsync();
-    Task SaveAllAsync();
-    Task ApplyAllAsync();
-    void Reset<T>() where T : class, ISettingsData, new();
-    void ResetAll();
-}
-```
-
-行为说明：
-
-- `GetData<T>()` 返回某个设置数据的唯一实例
-- `RegisterApplicator<T>()` 注册应用器，并把其 `Data` 纳入模型管理
-- `InitializeAsync()` 从 `ISettingsDataRepository` 读取所有已注册设置，并在需要时执行迁移
-- `SaveAllAsync()` 持久化当前所有设置数据
-- `ApplyAllAsync()` 依次调用所有 applicator 的 `ApplyAsync()`
-
-## SettingsSystem
-
-`SettingsSystem` 是对模型的系统级封装，面向业务代码提供更直接的入口：
-
-```csharp
-public interface ISettingsSystem : ISystem
-{
-    Task ApplyAll();
-    Task Apply<T>() where T : class, IResetApplyAbleSettings;
-    Task SaveAll();
-    Task Reset<T>() where T : class, ISettingsData, IResetApplyAbleSettings, new();
-    Task ResetAll();
-}
-```
-
-它不会自己保存数据，而是把保存、重置和应用逻辑委托给 `ISettingsModel`。
-
-## 基本用法
-
-### 定义设置数据
-
-```csharp
-public sealed class GameplaySettings : ISettingsData
-{
-    public float GameSpeed { get; set; } = 1.0f;
-
-    public int Version { get; private set; } = 1;
-    public DateTime LastModified { get; } = DateTime.UtcNow;
-
-    public void Reset()
-    {
-        GameSpeed = 1.0f;
-    }
-
-    public void LoadFrom(ISettingsData source)
-    {
-        if (source is not GameplaySettings settings)
-        {
-            return;
-        }
-
-        GameSpeed = settings.GameSpeed;
-        Version = settings.Version;
-    }
-}
-```
-
-### 定义 applicator
-
-```csharp
-public sealed class GameplaySettingsApplicator : IResetApplyAbleSettings
-{
-    public GameplaySettingsApplicator(GameplaySettings data)
-    {
-        Data = data;
-    }
-
-    public ISettingsData Data { get; }
-    public Type DataType => typeof(GameplaySettings);
-
-    public void Reset()
-    {
-        Data.Reset();
-    }
-
-    public Task ApplyAsync()
-    {
-        var settings = (GameplaySettings)Data;
-        TimeScale.Current = settings.GameSpeed;
-        return Task.CompletedTask;
-    }
-}
-```
-
-### 使用模型和系统
-
-```csharp
-var settingsModel = this.GetModel<ISettingsModel>();
-
-var gameplayData = settingsModel.GetData<GameplaySettings>();
-gameplayData.GameSpeed = 1.25f;
-
-settingsModel.RegisterApplicator(new GameplaySettingsApplicator(gameplayData));
-
 await settingsModel.InitializeAsync();
-await settingsModel.SaveAllAsync();
-
-var settingsSystem = this.GetSystem<ISettingsSystem>();
-await settingsSystem.ApplyAll();
+await settingsModel.ApplyAllAsync();
 ```
 
-## 迁移
-
-设置系统内建了迁移注册入口：
+退出或显式保存时：
 
 ```csharp
-public interface ISettingsMigration
-{
-    Type SettingsType { get; }
-    int FromVersion { get; }
-    int ToVersion { get; }
-    ISettingsData Migrate(ISettingsData oldData);
-}
+await settingsModel.SaveAllAsync();
 ```
 
-当 `InitializeAsync()` 读取到旧版本设置时，会按已注册迁移链逐步升级，再通过 `LoadFrom` 回填到当前实例。
+## `GetData<T>()` 和 `RegisterApplicator(...)` 的分工
 
-迁移规则如下：
+这两个入口经常被混用，但职责不同：
 
-- 同一个设置类型的同一个 `FromVersion` 只能注册一个迁移器
-- `ToVersion` 必须严格大于 `FromVersion`
-- `InitializeAsync()` 会以当前运行时代码里该设置实例的 `Version` 作为目标版本
-- 如果迁移链缺口、迁移结果类型不兼容、迁移结果版本与声明不一致，或者读取到比当前运行时更高的版本，当前设置节不会覆盖内存中的最新实例，并会记录错误日志
-- 与 `SaveRepository<TSaveData>` 不同，设置初始化阶段会跳过失败的设置节并继续处理其他设置节，而不是把异常继续向外抛出
+- `GetData<T>()`
+  - 只保证某个设置数据实例存在，并在 repository / location provider 已就绪时把类型注册回去
+- `RegisterApplicator(...)`
+  - 同时注册 applicator 和 applicator 绑定的 `Data`
 
-## 依赖项
+如果一个设置类型需要真正作用到运行时对象，推荐让它通过 applicator 进入模型；这样 `ApplyAllAsync()`、`ResetAll()` 和
+`SettingsSystem` 才能完整覆盖到它。
 
-要让设置系统完整工作，通常需要准备：
+## 与 repository 的关系
 
-- `ISettingsDataRepository`
-- `IDataLocationProvider`
-- 一个具体的存储实现和序列化器
+设置系统默认不是直接写文件，而是依赖 `ISettingsDataRepository`。
 
-如果使用 `UnifiedSettingsDataRepository`，多个设置节会被合并到单个设置文件中统一保存。
+当前仓库里更推荐的默认实现是 `UnifiedSettingsDataRepository`，原因很直接：
+
+- 多个设置 section 会被聚合到同一份统一文件
+- 启动时能一次性 `LoadAllAsync()`
+- `AutoBackup` 针对整个统一文件生效，更贴近“设置快照”的真实语义
+
+如果你的项目明确需要“一类设置一个独立文件”，才考虑回到通用 `DataRepository` 路径。
 
 ## 当前边界
 
-- 设置迁移是内建能力
-- 设置持久化是内建能力
-- 设置如何应用到具体引擎由 applicator 决定
-- 存档系统也支持内建版本迁移，但入口位于 `ISaveRepository<T>.RegisterMigration(...)`，语义是槽位存档升级而不是设置节初始化
+- `SettingsModel<TRepository>` 负责数据生命周期，`SettingsSystem` 负责系统级调用入口；两者不要混成一个巨型服务
+- applicator 决定“怎么把数据应用到宿主”，repository 决定“怎么保存数据”，两层职责不要互相侵入
+- 设置迁移和存档迁移是两条不同管线；后者看 [`data.md`](./data.md) 里的 `SaveRepository<TSaveData>`
+
+## 继续阅读
+
+1. [数据与存档系统](./data.md)
+2. [存储系统](./storage.md)
+3. [Game 入口](./index.md)
diff --git a/docs/zh-CN/game/storage.md b/docs/zh-CN/game/storage.md
index 3de0170c..ad2f9856 100644
--- a/docs/zh-CN/game/storage.md
+++ b/docs/zh-CN/game/storage.md
@@ -1,735 +1,181 @@
 ---
-title: 存储系统详解
-description: 存储系统提供了灵活的文件存储和作用域隔离功能，支持跨平台数据持久化。
+title: Game 存储系统
+description: 以当前 GFramework.Game 源码与持久化测试为准，说明 FileStorage 与 ScopedStorage 的职责、路径语义和复用方式。
 ---
 
-# 存储系统详解
+# Game 存储系统
 
-## 概述
+`GFramework.Game` 在存储这一层只提供宿主无关的 `IStorage` 默认实现和作用域包装器。
 
-存储系统是 GFramework.Game 中用于管理文件存储的核心组件。它提供了统一的存储接口，支持键值对存储、作用域隔离、目录操作等功能，让你可以轻松实现游戏数据的持久化。
+当前真正对外需要理解的入口只有两个：
 
-存储系统采用装饰器模式设计，通过 `IStorage` 接口定义统一的存储操作，`FileStorage` 提供基于文件系统的实现，`ScopedStorage`
-提供作用域隔离功能。
+- `FileStorage`
+  - 负责 `key -> 文件路径 -> 序列化内容` 的落盘读写
+- `ScopedStorage`
+  - 负责给同一份底层存储加前缀作用域，避免不同子系统直接拼字符串抢同一片键空间
 
-**主要特性**：
+它们不负责：
 
-- 统一的键值对存储接口
-- 基于文件系统的持久化
-- 作用域隔离和命名空间管理
-- 线程安全的并发访问
-- 支持同步和异步操作
-- 目录和文件列举功能
-- 路径安全防护
-- 跨平台支持（包括 Godot）
+- 设置 section 的聚合语义
+- 存档槽位目录约定
+- 业务数据迁移
 
-## 核心概念
+这些都属于上层 repository。
 
-### 存储接口
+## 当前公开入口
 
-`IStorage` 定义了统一的存储操作：
+### `FileStorage`
+
+`FileStorage` 是 `IStorage` 的默认文件系统实现。按当前源码，它的职责比较集中：
+
+- 把业务 key 映射到根目录下的层级文件路径
+- 通过构造函数注入的 `ISerializer` 负责对象序列化和反序列化
+- 对同一目标路径使用 `IAsyncKeyLockManager` 做细粒度串行化
+- 写入时先落 `.tmp` 临时文件，再原子替换目标文件
+- 自动创建父目录
+- 拒绝包含 `..` 的非法 key，并清理路径段中的非法文件名字符
+
+默认文件扩展名是 `.dat`，也可以在构造时改成 `.json` 或其他后缀：
 
 ```csharp
-public interface IStorage : IUtility
-{
-    // 检查键是否存在
-    bool Exists(string key);
-    Task<bool> ExistsAsync(string key);
-
-    // 读取数据
-    T Read&lt;T&gt;(string key);
-    T Read&lt;T&gt;(string key, T defaultValue);
-    Task&lt;T&gt; ReadAsync&lt;T&gt;(string key);
-
-    // 写入数据
-    void Write&lt;T&gt;(string key, T value);
-    Task WriteAsync&lt;T&gt;(string key, T value);
-
-    // 删除数据
-    void Delete(string key);
-    Task DeleteAsync(string key);
-
-    // 目录操作
-    Task<IReadOnlyList<string>> ListDirectoriesAsync(string path = "");
-    Task<IReadOnlyList<string>> ListFilesAsync(string path = "");
-    Task<bool> DirectoryExistsAsync(string path);
-    Task CreateDirectoryAsync(string path);
-}
-```
-
-### 文件存储
-
-`FileStorage` 是基于文件系统的存储实现：
-
-- 将数据序列化后保存为文件
-- 支持自定义文件扩展名（默认 `.dat`）
-- 使用细粒度锁保证线程安全
-- 自动创建目录结构
-- 防止路径遍历攻击
-
-### 作用域存储
-
-`ScopedStorage` 提供命名空间隔离：
-
-- 为所有键添加前缀
-- 支持嵌套作用域
-- 透明包装底层存储
-- 实现逻辑分组
-
-### 存储类型
-
-`StorageKinds` 枚举定义了不同的存储方式：
-
-```csharp
-[Flags]
-public enum StorageKinds
-{
-    None = 0,
-    Local = 1 << 0,      // 本地文件系统
-    Memory = 1 << 1,     // 内存存储
-    Remote = 1 << 2,     // 远程存储
-    Database = 1 << 3    // 数据库存储
-}
-```
-
-## 基本用法
-
-### 创建文件存储
-
-```csharp
-using GFramework.Game.Storage;
+using GFramework.Core.Abstractions.Storage;
 using GFramework.Game.Serializer;
-
-// 创建序列化器
-var serializer = new JsonSerializer();
-
-// 创Windows 示例）
-var storage = new FileStorage(@"C:\MyGame\Data", serializer);
-
-// 或使用自定义扩展名
-var storage = new FileStorage(@"C:\MyGame\Data", serializer, ".json");
-```
-
-### 写入和读取数据
-
-```csharp
-// 写入简单类型
-storage.Write("player_score", 1000);
-storage.Write("player_name", "Alice");
-
-// 写入复杂对象
-var settings = new GameSettings
-{
-    Volume = 0.8f,
-    Difficulty = "Hard",
-    Language = "zh-CN"
-};
-storage.Write("settings", settings);
-
-// 读取数据
-int score = storage.Read<int>("player_score");
-string name = storage.Read<string>("player_name");
-var loadedSettings = storage.Read<GameSettings>("settings");
-
-// 读取数据（带默认值）
-int highScore = storage.Read("high_score", 0);
-```
-
-### 异步操作
-
-```csharp
-// 异步写入
-await storage.WriteAsync("player_level", 10);
-
-// 异步读取
-int level = await storage.ReadAsync<int>("player_level");
-
-// 异步检查存在
-bool exists = await storage.ExistsAsync("player_level");
-
-// 异步删除
-await storage.DeleteAsync("player_level");
-```
-
-### 检查和删除
-
-```csharp
-// 检查键是否存在
-if (storage.Exists("player_score"))
-{
-    Console.WriteLine("存档存在");
-}
-
-// 删除数据
-storage.Delete("player_score");
-
-// 异步检查
-bool exists = await storage.ExistsAsync("player_score");
-```
-
-### 使用层级键
-
-```csharp
-// 使用 / 分隔符创建层级结构
-storage.Write("player/profile/name", "Alice");
-storage.Write("player/profile/level", 10);
-storage.Write("player/inventory/gold", 1000);
-
-// 文件结构：
-// Data/
-//   player/
-//     profile/
-//       name.dat
-//       level.dat
-//     inventory/
-//       gold.dat
-
-// 读取层级数据
-string name = storage.Read<string>("player/profile/name");
-int gold = storage.Read<int>("player/inventory/gold");
-```
-
-## 作用域存储
-
-### 创建作用域存储
-
-```csharp
 using GFramework.Game.Storage;
 
-// 基于文件存储创建作用域存储
-var baseStorage = new FileStorage(@"C:\MyGame\Data", serializer);
-var playerStorage = new ScopedStorage(baseStorage, "player");
-
-// 所有操作都会添加 "player/" 前缀
-playerStorage.Write("name", "Alice");      // 实际存储为 "player/name.dat"
-playerStorage.Write("level", 10);          // 实际存储为 "player/level.dat"
-
-// 读取时也使用相同的前缀
-string name = playerStorage.Read<string>("name");  // 从 "player/name.dat" 读取
+var serializer = new JsonSerializer();
+IStorage storage = new FileStorage("GameData", serializer, ".json");
 ```
 
-### 嵌套作用域
+### `ScopedStorage`
+
+`ScopedStorage` 不额外实现一套落盘逻辑，只是给底层 `IStorage` 包一层前缀。
+
+它适合做的是：
+
+- 把 `settings/`、`profiles/`、`runtime-cache/` 这类键空间隔离开
+- 让多个 repository 或 utility 共用同一份根存储
+- 避免项目层到处手写 `"settings/xxx"`、`"save/slot_1/xxx"` 之类的字符串拼接
+
+当前实现还支持继续嵌套：
 
 ```csharp
-// 创建嵌套作用域
-var settingsStorage = new ScopedStorage(baseStorage, "settings");
-var graphicsStorage = new ScopedStorage(settingsStorage, "graphics");
-
-// 前缀变为 "settings/graphics/"
-graphicsStorage.Write("resolution", "1920x1080");
-// 实际存储为 "settings/graphics/resolution.dat"
-
-// 或使用 Scope 方法
+var rootStorage = new FileStorage("GameData", new JsonSerializer(), ".json");
+var settingsStorage = new ScopedStorage(rootStorage, "settings");
 var audioStorage = settingsStorage.Scope("audio");
-audioStorage.Write("volume", 0.8f);
-// 实际存储为 "settings/audio/volume.dat"
+
+await audioStorage.WriteAsync("master", 0.8f);
 ```
 
-### 多作用域隔离
+最终实际写入的 key 会是 `settings/audio/master`。
 
-```csharp
-// 创建不同作用域的存储
-var playerStorage = new ScopedStorage(baseStorage, "player");
-var gameStorage = new ScopedStorage(baseStorage, "game");
-var settingsStorage = new ScopedStorage(baseStorage, "settings");
+## 路径语义
 
-// 在不同作用域中使用相同的键不会冲突
-playerStorage.Write("level", 5);              // player/level.dat
-gameStorage.Write("level", "forest_area_1");  // game/level.dat
-settingsStorage.Write("level", "high");       // settings/level.dat
+### key 到文件路径的映射
 
-// 读取时各自独立
-int playerLevel = playerStorage.Read<int>("level");           // 5
-string gameLevel = gameStorage.Read<string>("level");         // "forest_area_1"
-string settingsLevel = settingsStorage.Read<string>("level"); // "high"
+`FileStorage` 会把 key 中的 `/` 当成目录分隔符，把最后一段作为文件名，并自动附加扩展名。
+
+例如：
+
+```text
+key: profile/player
+root: GameData
+extension: .json
 ```
 
-## 高级用法
+会落到：
 
-### 目录操作
+```text
+GameData/profile/player.json
+```
+
+这意味着 key 的语义应该保持“逻辑路径”，而不是“完整文件名”。不要在业务层再自己补一遍 `.json`，否则会得到双重后缀。
+
+### 安全边界
+
+当前实现会：
+
+1. 把 `\` 统一成 `/`
+2. 拒绝包含 `..` 的 key
+3. 清理每个路径段中的非法文件名字符
+
+这套规则能挡住明显的路径逃逸和非法文件名问题，但它不代替业务层做目录规划。哪些 key 属于设置、存档还是缓存，仍应由上层模块统一约定。
+
+### 同步与异步 API
+
+`Read`、`Write`、`Exists`、`Delete` 这些同步方法只是对异步 API 的阻塞包装。
+
+在 UI 线程或带同步上下文的宿主中，优先使用：
+
+- `ReadAsync<T>()`
+- `WriteAsync<T>()`
+- `ExistsAsync()`
+- `DeleteAsync()`
+
+只有在无法继续异步传播时，再退回同步封装。
+
+## 最小接入路径
+
+如果你只想先拿到一个可复用的本地持久化底座，最短路径如下：
 
 ```csharp
-// 列举子目录
-var directories = await storage.ListDirectoriesAsync("player");
-foreach (var dir in directories)
+using GFramework.Core.Abstractions.Serializer;
+using GFramework.Core.Abstractions.Storage;
+using GFramework.Game.Serializer;
+using GFramework.Game.Storage;
+
+var serializer = new JsonSerializer();
+IStorage storage = new FileStorage("GameData", serializer, ".json");
+
+await storage.WriteAsync("profiles/player", new Dictionary<string, int>
 {
-    Console.WriteLine($"目录: {dir}");
-}
+    ["level"] = 12
+});
 
-// 列举文件
-var files = await storage.ListFilesAsync("player/inventory");
-foreach (var file in files)
-{
-    Console.WriteLine($"文件: {file}");
-}
-
-// 检查目录是否存在
-bool exists = await storage.DirectoryExistsAsync("player/quests");
-
-// 创建目录
-await storage.CreateDirectoryAsync("player/achievements");
+var loaded = await storage.ReadAsync<Dictionary<string, int>>("profiles/player");
 ```
 
-### 批量操作
+如果项目里同时有设置、存档和运行时缓存，推荐先在组合根把作用域拆开：
 
 ```csharp
-public async Task SaveAllPlayerData(PlayerData player)
-{
-    var playerStorage = new ScopedStorage(baseStorage, $"player_{player.Id}");
+var serializer = new JsonSerializer();
+var rootStorage = new FileStorage("GameData", serializer, ".json");
 
-    // 批量写入
-    var tasks = new List<Task>
-    {
-        playerStorage.WriteAsync("profile", player.Profile),
-        playerStorage.WriteAsync("inventory", player.Inventory),
-        playerStorage.WriteAsync("quests", player.Quests),
-        playerStorage.WriteAsync("achievements", player.Achievements)
-    };
-
-    await Task.WhenAll(tasks);
-    Console.WriteLine("所有玩家数据已保存");
-}
-
-public async Task<PlayerData> LoadAllPlayerData(int playerId)
-{
-    var playerStorage = new ScopedStorage(baseStorage, $"player_{playerId}");
-
-    // 批量读取
-    var tasks = new[]
-    {
-        playerStorage.ReadAsync<Profile>("profile"),
-        playerStorage.ReadAsync<Inventory>("inventory"),
-        playerStorage.ReadAsync<QuestData>("quests"),
-        playerStorage.ReadAsync<Achievements>("achievements")
-    };
-
-    await Task.WhenAll(tasks);
-
-    return new PlayerData
-    {
-        Id = playerId,
-        Profile = tasks[0].Result,
-        Inventory = tasks[1].Result,
-        Quests = tasks[2].Result,
-        Achievements = tasks[3].Result
-    };
-}
+var settingsStorage = new ScopedStorage(rootStorage, "settings");
+var saveStorage = new ScopedStorage(rootStorage, "saves");
+var cacheStorage = new ScopedStorage(rootStorage, "runtime-cache");
 ```
 
-### 存储迁移
+不过在默认仓库接法里，项目通常不需要直接创建 `saveStorage` 这种 scoped instance，因为 `SaveRepository<TSaveData>`
+会再根据 `SaveConfiguration` 自己组织槽位目录。
 
-```csharp
-public async Task MigrateStorage(IStorage oldStorage, IStorage newStorage, string path = "")
-{
-    // 列举所有文件
-    var files = await oldStorage.ListFilesAsync(path);
+## 与上层 repository 的关系
 
-    foreach (var file in files)
-    {
-        var key = string.IsNullOrEmpty(path) ? file : $"{path}/{file}";
+`FileStorage` / `ScopedStorage` 是持久化最底层，不是最终采用入口。当前更常见的实际分工是：
 
-        // 读取旧数据
-        var data = await oldStorage.ReadAsync<object>(key);
+- `DataRepository`
+  - 每个 `IDataLocation` 对应一份独立持久化对象
+- `UnifiedSettingsDataRepository`
+  - 把多个设置 section 聚合到同一个统一文件里保存
+- `SaveRepository<TSaveData>`
+  - 负责存档槽位、文件名和迁移链
 
-        // 写入新存储
-        await newStorage.WriteAsync(key, data);
+也就是说：
 
-        Console.WriteLine($"已迁移: {key}");
-    }
+- 业务层如果想保存一份独立数据，优先看 [`data.md`](./data.md)
+- 业务层如果想保存设置，优先看 [`setting.md`](./setting.md)
+- 业务层如果只是需要底层存储实现，才直接依赖 `IStorage`
 
-    // 递归处理子目录
-    var directories = await oldStorage.ListDirectoriesAsync(path);
-    foreach (var dir in directories)
-    {
-        var subPath = string.IsNullOrEmpty(path) ? dir : $"{path}/{dir}";
-        await MigrateStorage(oldStorage, newStorage, subPath);
-    }
-}
-```
+## 当前边界
 
-### 存储备份
+- `FileStorage` 已经会通过注入的 `ISerializer` 自动序列化对象；默认接法不需要先手工 `Serialize(...)` 再把字符串写回
+- `FileStorage` 负责目录列举与目录创建，但不负责“列出所有存档槽位”的业务语义
+- `ScopedStorage` 只做 key 前缀，不做权限、事务或迁移控制
+- 锁粒度是“当前实例内的目标路径”，不是跨进程文件锁
+- 原子写入只覆盖单文件替换，不等于多文件事务
 
-```csharp
-public class StorageBackupSystem
-{
-    private readonly IStorage _storage;
-    private readonly string _backupPrefix = "backup";
+## 继续阅读
 
-    public async Task CreateBackup(string sourcePath)
-    {
-        var timestamp = DateTime.Now.ToString("yyyyMMdd_HHmmss");
-        var backupPath = $"{_backupPrefix}/{timestamp}";
-
-        await CopyDirectory(sourcePath, backupPath);
-        Console.WriteLine($"备份已创建: {backupPath}");
-    }
-
-    public async Task RestoreBackup(string backupName, string targetPath)
-    {
-        var backupPath = $"{_backupPrefix}/{backupName}";
-
-        if (!await _storage.DirectoryExistsAsync(backupPath))
-        {
-            throw new DirectoryNotFoundException($"备份不存在: {backupName}");
-        }
-
-        await CopyDirectory(backupPath, targetPath);
-        Console.WriteLine($"已从备份恢复: {backupName}");
-    }
-
-    private async Task CopyDirectory(string source, string target)
-    {
-        var files = await _storage.ListFilesAsync(source);
-        foreach (var file in files)
-        {
-            var sourceKey = $"{source}/{file}";
-            var targetKey = $"{target}/{file}";
-            var data = await _storage.ReadAsync<object>(sourceKey);
-            await _storage.WriteAsync(targetKey, data);
-        }
-
-        var directories = await _storage.ListDirectoriesAsync(source);
-        foreach (var dir in directories)
-        {
-            await CopyDirectory($"{source}/{dir}", $"{target}/{dir}");
-        }
-    }
-}
-```
-
-### 缓存层
-
-```csharp
-public class CachedStorage : IStorage
-{
-    private readonly IStorage _innerStorage;
-    private readonly ConcurrentDictionary<string, object> _cache = new();
-
-    public CachedStorage(IStorage innerStorage)
-    {
-        _innerStorage = innerStorage;
-    }
-
-    public T Read&lt;T&gt;(string key)
-    {
-        // 先从缓存读取
-        if (_cache.TryGetValue(key, out var cached))
-        {
-            return (T)cached;
-        }
-
-        // 从存储读取并缓存
-        var value = _innerStorage.Read&lt;T&gt;(key);
-        _cache[key] = value;
-        return value;
-    }
-
-    public void Write&lt;T&gt;(string key, T value)
-    {
-        // 写入存储
-        _innerStorage.Write(key, value);
-
-        // 更新缓存
-        _cache[key] = value;
-    }
-
-    public void Delete(string key)
-    {
-        _innerStorage.Delete(key);
-        _cache.TryRemove(key, out _);
-    }
-
-    public void ClearCache()
-    {
-        _cache.Clear();
-    }
-}
-```
-
-## Godot 集成
-
-### 使用 Godot 文件存储
-
-```csharp
-using GFramework.Godot.Storage;
-
-// 创建 Godot 文件存储
-var storage = new GodotFileStorage(serializer);
-
-// 使用 user:// 路径（用户数据目录）
-storage.Write("user://saves/slot1.dat", saveData);
-var data = storage.Read<SaveData>("user://saves/slot1.dat");
-
-// 使用 res:// 路径（资源目录，只读）
-var config = storage.Read<Config>("res://config/default.json");
-
-// 普通文件路径也支持
-storage.Write("/tmp/temp_data.dat", tempData);
-```
-
-### Godot 路径说明
-
-```csharp
-// user:// - 用户数据目录
-// Windows: %APPDATA%/Godot/app_userdata/[project_name]
-// Linux: ~/.local/share/godot/app_userdata/[project_name]
-// macOS: ~/Library/Application Support/Godot/app_userdata/[project_name]
-storage.Write("user://save.dat", data);
-
-// res:// - 项目资源目录（只读）
-var config = storage.Read<Config>("res://data/config.json");
-
-// 绝对路径
-storage.Write("/home/user/game/data.dat", data);
-```
-
-## 最佳实践
-
-1. **使用作用域隔离不同类型的数据**
-   ```csharp
-   ✓ var playerStorage = new ScopedStorage(baseStorage, "player");
-   ✓ var settingsStorage = new ScopedStorage(baseStorage, "settings");
-   ✗ storage.Write("player_name", name);  // 不使用作用域
-   ```
-
-2. **使用异步操作避免阻塞**
-   ```csharp
-   ✓ await storage.WriteAsync("data", value);
-   ✗ storage.Write("data", value);  // 在 UI 线程中同步操作
-   ```
-
-3. **读取时提供默认值**
-   ```csharp
-   ✓ int score = storage.Read("score", 0);
-   ✗ int score = storage.Read<int>("score");  // 键不存在时抛异常
-   ```
-
-4. **使用层级键组织数据**
-   ```csharp
-   ✓ storage.Write("player/inventory/gold", 1000);
-   ✗ storage.Write("player_inventory_gold", 1000);
-   ```
-
-5. **处理存储异常**
-   ```csharp
-   try
-   {
-       await storage.WriteAsync("data", value);
-   }
-   catch (IOException ex)
-   {
-       Logger.Error($"存储失败: {ex.Message}");
-       ShowErrorMessage("保存失败，请检查磁盘空间");
-   }
-   ```
-
-6. **定期清理过期数据**
-   ```csharp
-   public async Task CleanupOldData(TimeSpan maxAge)
-   {
-       var files = await storage.ListFilesAsync("temp");
-       foreach (var file in files)
-       {
-           var data = await storage.ReadAsync<TimestampedData>($"temp/{file}");
-           if (DateTime.Now - data.Timestamp > maxAge)
-           {
-               await storage.DeleteAsync($"temp/{file}");
-           }
-       }
-   }
-   ```
-
-7. **使用合适的序列化器**
-   ```csharp
-   // JSON - 可读性好，适合配置文件
-   var jsonStorage = new FileStorage(path, new JsonSerializer(), ".json");
-
-   // 二进制 - 性能好，适合大量数据
-   var binaryStorage = new FileStorage(path, new BinarySerializer(), ".dat");
-   ```
-
-## 常见问题
-
-### 问题：如何实现跨平台存储路径？
-
-**解答**：
-使用 `Environment.GetFolderPath` 获取平台特定路径：
-
-```csharp
-public static string GetStoragePath()
-{
-    var appData = Environment.GetFolderPath(
-        Environment.SpecialFolder.ApplicationData);
-    return Path.Combine(appData, "MyGame", "Data");
-}
-
-var storage = new FileStorage(GetStoragePath(), serializer);
-```
-
-### 问题：存储系统是否线程安全？
-
-**解答**：
-是的，`FileStorage` 使用细粒度锁机制保证线程安全：
-
-```csharp
-// 不同键的操作可以并发执行
-Task.Run(() => storage.Write("key1", value1));
-Task.Run(() => storage.Write("key2", value2));
-
-// 相同键的操作会串行化
-Task.Run(() => storage.Write("key", value1));
-Task.Run(() => storage.Write("key", value2));  // 等待第一个完成
-```
-
-### 问题：如何实现存储加密？
-
-**解答**：
-创建加密存储包装器：
-
-```csharp
-public class EncryptedStorage : IStorage
-{
-    private readonly IStorage _innerStorage;
-    private readonly IEncryption _encryption;
-
-    public void Write&lt;T&gt;(string key, T value)
-    {
-        var json = JsonSerializer.Serialize(value);
-        var encrypted = _encryption.Encrypt(json);
-        _innerStorage.Write(key, encrypted);
-    }
-
-    public T Read&lt;T&gt;(string key)
-    {
-        var encrypted = _innerStorage.Read<byte[]>(key);
-        var json = _encryption.Decrypt(encrypted);
-        return JsonSerializer.Deserialize&lt;T&gt;(json);
-    }
-}
-```
-
-### 问题：如何限制存储大小？
-
-**解答**：
-实现配额管理：
-
-```csharp
-public class QuotaStorage : IStorage
-{
-    private readonly IStorage _innerStorage;
-    private readonly long _maxSize;
-    private long _currentSize;
-
-    public void Write&lt;T&gt;(string key, T value)
-    {
-        var data = Serialize(value);
-        var size = data.Length;
-
-        if (_currentSize + size > _maxSize)
-        {
-            throw new InvalidOperationException("存储配额已满");
-        }
-
-        _innerStorage.Write(key, value);
-        _currentSize += size;
-    }
-}
-```
-
-### 问题：如何实现存储压缩？
-
-**解答**：
-使用压缩序列化器：
-
-```csharp
-public class CompressedSerializer : ISerializer
-{
-    private readonly ISerializer _innerSerializer;
-
-    public string Serialize&lt;T&gt;(T value)
-    {
-        var json = _innerSerializer.Serialize(value);
-        var bytes = Encoding.UTF8.GetBytes(json);
-        var compressed = Compress(bytes);
-        return Convert.ToBase64String(compressed);
-    }
-
-    public T Deserialize&lt;T&gt;(string data)
-    {
-        var compressed = Convert.FromBase64String(data);
-        var bytes = Decompress(compressed);
-        var json = Encoding.UTF8.GetString(bytes);
-        return _innerSerializer.Deserialize&lt;T&gt;(json);
-    }
-
-    private byte[] Compress(byte[] data)
-    {
-        using var output = new MemoryStream();
-        using (var gzip = new GZipStream(output, CompressionMode.Compress))
-        {
-            gzip.Write(data, 0, data.Length);
-        }
-        return output.ToArray();
-    }
-
-    private byte[] Decompress(byte[] data)
-    {
-        using var input = new MemoryStream(data);
-        using var gzip = new GZipStream(input, CompressionMode.Decompress);
-        using var output = new MemoryStream();
-        gzip.CopyTo(output);
-        return output.ToArray();
-    }
-}
-```
-
-### 问题：如何监控存储操作？
-
-**解答**：
-实现日志存储包装器：
-
-```csharp
-public class LoggingStorage : IStorage
-{
-    private readonly IStorage _innerStorage;
-    private readonly ILogger _logger;
-
-    public void Write&lt;T&gt;(string key, T value)
-    {
-        var stopwatch = Stopwatch.StartNew();
-        try
-        {
-            _innerStorage.Write(key, value);
-            _logger.Info($"写入成功: {key}, 耗时: {stopwatch.ElapsedMilliseconds}ms");
-        }
-        catch (Exception ex)
-        {
-            _logger.Error($"写入失败: {key}, 错误: {ex.Message}");
-            throw;
-        }
-    }
-
-    public T Read&lt;T&gt;(string key)
-    {
-        var stopwatch = Stopwatch.StartNew();
-        try
-        {
-            var value = _innerStorage.Read&lt;T&gt;(key);
-            _logger.Info($"读取成功: {key}, 耗时: {stopwatch.ElapsedMilliseconds}ms");
-            return value;
-        }
-        catch (Exception ex)
-        {
-            _logger.Error($"读取失败: {key}, 错误: {ex.Message}");
-            throw;
-        }
-    }
-}
-```
-
-## 相关文档
-
-- [数据与存档系统](/zh-CN/game/data) - 数据持久化
-- [序列化系统](/zh-CN/game/serialization) - 数据序列化
-- [Godot 集成](/zh-CN/godot/index) - Godot 中的存储
-- [存档系统教程](/zh-CN/tutorials/save-system) - 完整示例
+1. [数据与存档系统](./data.md)
+2. [设置系统](./setting.md)
+3. [序列化系统](./serialization.md)
+4. [Game 入口](./index.md)
diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md
index 8187f303..84091c8f 100644
--- a/docs/zh-CN/godot/setting.md
+++ b/docs/zh-CN/godot/setting.md
@@ -1,603 +1,156 @@
-# Godot 设置模块 (Godot Settings Module)
+---
+title: Godot 设置系统
+description: 以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准，说明 Godot settings applicator 的职责、注册方式和运行时边界。
+---
 
-## 概述
+# Godot 设置系统
 
-Godot 设置模块是 GFramework.Godot 的核心组件之一，专门为 Godot 引擎提供游戏设置系统的实现。该模块将通用的设置框架与 Godot
-引擎的特定功能相结合，提供了音频设置、图形设置和本地化设置的完整解决方案。
+`GFramework.Godot` 在设置这一层做的事情很克制：它没有重新发明一套设置模型，而是给
+`GFramework.Game` 的 `ISettingsModel` 提供三个 Godot 宿主 applicator：
 
-## 核心类
+- `GodotAudioSettings`
+- `GodotGraphicsSettings`
+- `GodotLocalizationSettings`
 
-### 音频设置系统
+这些类型的职责是“把已经存在的设置数据应用到 Godot 引擎和框架运行时”，不是负责设置 UI、设置持久化或设置迁移。
 
-#### AudioBusMap
+## 当前公开入口
 
-音频总线映射配置类，用于定义音频系统中不同类型音频的总线名称。
+### `GodotAudioSettings`
 
-**属性：**
+`GodotAudioSettings` 从 `ISettingsModel` 读取 `AudioSettings`，再按 `AudioBusMap` 中的总线名把音量写入
+`AudioServer`。
 
-- `Master` - 主音频总线名称（默认："Master"）
-- `Bgm` - 背景音乐音频总线名称（默认："BGM"）
-- `Sfx` - 音效音频总线名称（默认："SFX"）
+当前行为有几个关键点：
 
-#### GodotAudioApplier
+- `Master`、`Bgm`、`Sfx` 三类音量都来自 `AudioSettings`
+- 应用前会把线性音量限制在 `0.0001f ~ 1f`，再转换成分贝
+- 如果找不到对应 bus，当前实现只会 `GD.PushWarning(...)`，不会抛异常中断整个设置流程
 
-音频设置应用器，负责将音频设置应用到 Godot 引擎的音频总线系统。
+`AudioBusMap` 默认值是：
 
-**功能：**
+- `Master`
+- `BGM`
+- `SFX`
 
-- 应用音量设置到指定音频总线
-- 处理音量格式转换（线性值到分贝）
-- 音频总线存在性检查和警告
+如果项目里的 Godot Audio Bus 命名不同，需要在注册 applicator 时替换映射，而不是改写 applicator 本身。
 
-#### GodotAudioSettings
+### `GodotGraphicsSettings`
 
-Godot 音频设置实现类，接收 AudioSettings 配置并实现 IApplyAbleSettings 接口，负责将音频配置应用到 Godot 音频系统。
+`GodotGraphicsSettings` 从 `ISettingsModel` 读取 `GraphicsSettings`，并把结果同步到 `DisplayServer`：
 
-**实现关系：**
+- `Fullscreen = true` 时切到 `ExclusiveFullscreen`
+- 同时把 `Borderless` flag 设为 `true`
+- `Fullscreen = false` 时切回窗口模式，设置窗口尺寸，并按主屏尺寸重新居中
 
-```
-AudioSettings (配置数据)
-    ↓ [组合]
-GodotAudioSettings (Godot 特定实现) → IApplyAbleSettings (可应用设置接口)
-```
+当前实现没有扩展到分辨率档位之外的图形质量、渲染后端或平台特定显示策略。本页不再把这些未实现能力写成既成事实。
 
-**功能：**
+### `GodotLocalizationSettings`
 
-- 接收 AudioSettings 配置对象和 AudioBusMap 总线映射
-- 实现 `ApplyAsync()` 方法，将音量设置应用到指定音频总线
-- 支持自定义音频总线映射
-- 自动处理音量格式转换（线性值到分贝）
+`GodotLocalizationSettings` 负责把 `LocalizationSettings.Language` 同时同步到：
 
-### 图形设置系统
+- Godot `TranslationServer.SetLocale(...)`
+- GFramework `ILocalizationManager.SetLanguage(...)`
 
-#### GodotGraphicsSettings
+这一步依赖 `LocalizationMap` 把“用户可见语言值”拆成两套目标值：
 
-Godot 图形设置实现类，继承自 GraphicsSettings 并实现 IApplyAbleSettings。
+- Godot locale，例如 `zh_CN`
+- 框架语言码，例如 `zhs`
 
-**功能：**
+当前默认映射是：
 
-- 分辨率设置和窗口尺寸调整
-- 全屏模式切换
-- 窗口位置自动居中
-- 多显示器支持
+- `简体中文` -> Godot `zh_CN`，框架 `zhs`
+- `English` -> Godot `en`，框架 `eng`
 
-### 本地化设置系统
+`GFramework.Game.Tests/Setting/GodotLocalizationSettingsTests.cs` 已覆盖三条关键边界：
 
-#### LocalizationMap
+- 英文会同步到 `en` / `eng`
+- 简体中文会同步到 `zh_CN` / `zhs`
+- 未知语言值会稳定回退到英文，而不是让 Godot locale 与框架语言状态分裂
 
-本地化映射配置类，用于把设置系统中保存的用户可见语言值解析为：
+如果当前架构上下文里解析不到 `ILocalizationManager`，Godot locale 仍会被设置，只是不会额外同步框架语言管理器。
 
-- Godot `TranslationServer` 使用的 locale
-- GFramework `ILocalizationManager` 使用的语言码
+## 最小接入路径
 
-默认映射如下：
-
-- `"简体中文"` -> Godot `zh_CN`，框架语言码 `zhs`
-- `"English"` -> Godot `en`，框架语言码 `eng`
-
-未知语言值会稳定回退到英文，避免重启后出现设置值与运行时语言状态不一致。
-
-#### GodotLocalizationSettings
-
-Godot 本地化设置实现类，负责把 `LocalizationSettings` 同时应用到 Godot 引擎与 GFramework 本地化管理器。
-
-**功能：**
-
-- 将语言设置应用到 `TranslationServer.SetLocale(...)`
-- 同步 `ILocalizationManager.SetLanguage(...)`
-- 通过统一映射避免 Godot locale 与框架语言码分裂
-
-## 架构设计
-
-```mermaid
-graph TD
-    A[AudioSettings] --> B[GodotAudioSettings]
-    C[GraphicsSettings] --> D[GodotGraphicsSettings]
-    E[LocalizationSettings] --> F[GodotLocalizationSettings]
-    G[IApplyAbleSettings] --> B
-    G --> D
-    G --> F
-    
-    H[AudioBusMap] --> B
-    I[LocalizationMap] --> F
-    
-    B --> J[AudioServer API]
-    D --> K[DisplayServer API]
-    F --> L[TranslationServer API]
-    F --> M[ILocalizationManager]
-    
-    N[SettingsSystem] --> O[ApplyAsync Method]
-    O --> B
-    O --> D
-    O --> F
-```
-
-## 使用示例
-
-### 音频设置配置
-
-#### 基本音频设置
+当前消费者 `ai-libs/CoreGrid` 的接法，是先注册 `SettingsModel<ISettingsDataRepository>`，再把 Godot applicator
+挂进去：
 
 ```csharp
-// 创建音频配置数据
-var settings = new AudioSettings
-{
-    MasterVolume = 0.8f,  // 80% 主音量
-    BgmVolume = 0.6f,      // 60% 背景音乐音量
-    SfxVolume = 0.9f       // 90% 音效音量
-};
+using GFramework.Game.Abstractions.Data;
+using GFramework.Game.Abstractions.Setting;
+using GFramework.Game.Setting;
+using GFramework.Godot.Setting;
+using GFramework.Godot.Setting.Data;
 
-// 创建 Godot 音频设置应用器
-var audioSettings = new GodotAudioSettings(settings, new AudioBusMap());
+var settingsDataRepository = architecture.Context.GetUtility<ISettingsDataRepository>();
 
-// 应用设置
-await audioSettings.ApplyAsync();
+architecture.RegisterModel(
+    new SettingsModel<ISettingsDataRepository>(
+        new SettingDataLocationProvider(),
+        settingsDataRepository)
+        .Also(it =>
+        {
+            it.RegisterApplicator(new GodotAudioSettings(it, new AudioBusMap()))
+                .RegisterApplicator(new GodotGraphicsSettings(it))
+                .RegisterApplicator(new GodotLocalizationSettings(it, new LocalizationMap()));
+        }));
 ```
 
-#### 自定义音频总线映射
+这条接法说明了当前边界：
+
+- 设置数据和生命周期由 `SettingsModel` 管
+- `GodotAudioSettings` / `GodotGraphicsSettings` / `GodotLocalizationSettings` 只是 applicator
+- 保存、加载和迁移仍然走 `ISettingsDataRepository`、`SettingsModel.InitializeAsync()`、`SaveAllAsync()` 等 `Game`
+  family 入口
+
+## 运行时使用方式
+
+业务代码通常不会直接 new 一次 applicator 然后立即调用，而是通过 `ISettingsSystem` 或 `ISettingsModel` 触发应用：
 
 ```csharp
-// 自定义音频总线映射
-var customBusMap = new AudioBusMap
-{
-    Master = "Master_Bus",
-    Bgm = "Background_Music",
-    Sfx = "Sound_Effects"
-};
+using GFramework.Game.Abstractions.Setting;
+using GFramework.Godot.Setting;
 
-// 创建音频配置
-var settings = new AudioSettings
-{
-    MasterVolume = 0.7f,
-    BgmVolume = 0.5f,
-    SfxVolume = 0.8f
-};
-
-// 使用自定义总线映射应用设置
-var audioSettings = new GodotAudioSettings(settings, customBusMap);
-await audioSettings.ApplyAsync();
-```
-
-#### 通过设置系统使用
-
-```csharp
-// 注册音频设置到设置模型
 var settingsModel = this.GetModel<ISettingsModel>();
-var audioSettingsData = settingsModel.Get<AudioSettings>();
-audioSettingsData.MasterVolume = 0.8f;
-audioSettingsData.BgmVolume = 0.6f;
-audioSettingsData.SfxVolume = 0.9f;
+var audioData = settingsModel.GetData<AudioSettings>();
+audioData.MasterVolume = 0.8f;
+audioData.BgmVolume = 0.6f;
+audioData.SfxVolume = 0.9f;
 
-// 创建 Godot 音频设置应用器
-var godotAudioSettings = new GodotAudioSettings(audioSettingsData, new AudioBusMap());
-await godotAudioSettings.ApplyAsync();
+var settingsSystem = this.GetSystem<ISettingsSystem>();
+await settingsSystem.Apply<GodotAudioSettings>();
 ```
 
-### 图形设置配置
+对图形和语言设置的调用方式相同，区别只是 applicator 类型不同。
 
-#### 基本图形设置
+## 当前边界
 
-```csharp
-// 创建图形设置
-var graphicsSettings = new GodotGraphicsSettings
-{
-    ResolutionWidth = 1920,
-    ResolutionHeight = 1080,
-    Fullscreen = true
-};
+- 这三个类型都不是设置数据对象；它们读取的是 `AudioSettings`、`GraphicsSettings`、`LocalizationSettings`
+- 它们不负责设置持久化；是否保存到文件由 `ISettingsDataRepository` 和存储层决定
+- `ApplyAsync()` 当前都只是同步推进 Godot 引擎调用后返回 `Task.CompletedTask`，不会启动后台工作线程
+- `GodotAudioSettings` 依赖项目里已经存在对应 bus 名称；缺失时只会警告，不会帮你自动创建总线
+- `GodotGraphicsSettings` 当前只覆盖窗口模式、尺寸和居中，不等于一个完整的图形选项系统
+- `GodotLocalizationSettings` 解决的是“用户语言值 -> Godot locale / 框架语言码”双向对齐，不负责翻译资源本身的组织方式
 
-// 应用设置
-await graphicsSettings.ApplyAsync();
-```
+## 什么时候应该改看别的入口
 
-#### 窗口模式切换
+### 先理解设置模型和仓库
 
-```csharp
-public class DisplayManager : Node
-{
-    private GodotGraphicsSettings _graphicsSettings;
-    
-    public override void _Ready()
-    {
-        _graphicsSettings = new GodotGraphicsSettings();
-    }
-    
-    public async Task ToggleFullscreen()
-    {
-        _graphicsSettings.Fullscreen = !_graphicsSettings.Fullscreen;
-        await _graphicsSettings.ApplyAsync();
-    }
-    
-    public async Task SetResolution(int width, int height)
-    {
-        _graphicsSettings.ResolutionWidth = width;
-        _graphicsSettings.ResolutionHeight = height;
-        _graphicsSettings.Fullscreen = false; // 窗口化时自动关闭全屏
-        await _graphicsSettings.ApplyAsync();
-    }
-}
-```
+如果你想先理解 `ISettingsData`、`IResetApplyAbleSettings`、`SettingsModel`、`SettingsSystem` 与设置迁移，先看
+[`../game/setting.md`](../game/setting.md)。
 
-#### 预设分辨率配置
+### 先理解设置如何被持久化
 
-```csharp
-public class ResolutionPresets
-{
-    public static readonly (int width, int height)[] CommonResolutions = 
-    {
-        (1920, 1080), // Full HD
-        (2560, 1440), // QHD
-        (3840, 2160), // 4K
-        (1280, 720),  // HD
-        (1366, 768),  // 常见笔记本分辨率
-    };
-    
-    public static async Task ApplyResolution(GodotGraphicsSettings settings, int width, int height)
-    {
-        settings.ResolutionWidth = width;
-        settings.ResolutionHeight = height;
-        settings.Fullscreen = false;
-        await settings.ApplyAsync();
-    }
-}
-```
+如果你关注的是统一设置文件、备份、数据位置和底层存储实现，应该回到：
 
-## API 详细说明
+- [`../game/storage.md`](../game/storage.md)
+- [Godot 存储系统](./storage.md)
 
-### AudioBusMap
+本页只补 Godot 宿主如何“应用”设置，不重复维护一份完整设置系统手册。
 
-```csharp
-public sealed class AudioBusMap
-{
-    public string Master { get; init; } = "Master";
-    public string Bgm { get; init; } = "BGM";
-    public string Sfx { get; init; } = "SFX";
-}
-```
+## 继续阅读
 
-**特点：**
-
-- 使用 `init` 属性，创建后不可修改
-- 提供合理的默认值
-- 支持对象初始化语法
-
-### GodotAudioSettings
-
-```csharp
-public class GodotAudioSettings(AudioSettings settings, AudioBusMap busMap) : IApplyAbleSettings
-{
-    public Task ApplyAsync();
-}
-```
-
-**构造函数参数：**
-
-- `settings` - AudioSettings 配置对象，包含音量设置
-- `busMap` - AudioBusMap 对象，定义音频总线映射
-
-**Apply 方法实现：**
-
-```csharp
-public Task ApplyAsync()
-{
-    SetBus(busMap.Master, settings.MasterVolume);
-    SetBus(busMap.Bgm, settings.BgmVolume);
-    SetBus(busMap.Sfx, settings.SfxVolume);
-    return Task.CompletedTask;
-}
-```
-
-### GodotGraphicsSettings
-
-```csharp
-public class GodotGraphicsSettings : GraphicsSettings, IApplyAbleSettings
-{
-    public Task ApplyAsync();
-}
-```
-
-**Apply 方法功能：**
-
-- 设置窗口边框标志
-- 切换窗口模式（窗口化/全屏）
-- 调整窗口尺寸
-- 自动居中窗口
-
-## 技术实现细节
-
-### 音频音量转换
-
-Godot 音频系统使用分贝（dB）作为音量单位，而我们通常使用线性值（0-1）：
-
-```csharp
-// 线性值到分贝转换
-float linearVolume = 0.5f;  // 50% 音量
-float dbVolume = Mathf.LinearToDb(linearVolume); // 转换为分贝
-
-// 应用到音频总线
-AudioServer.SetBusVolumeDb(busIndex, dbVolume);
-```
-
-### 音量限制和保护
-
-为避免完全静音（-inf dB），应用了最小音量限制：
-
-```csharp
-float clampedVolume = Mathf.Clamp(linear, 0.0001f, 1f);
-float dbVolume = Mathf.LinearToDb(clampedVolume);
-```
-
-### 窗口管理
-
-#### 全屏模式
-
-```csharp
-// 设置全屏
-DisplayServer.WindowSetMode(DisplayServer.WindowMode.ExclusiveFullscreen);
-DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, true);
-```
-
-#### 窗口化模式
-
-```csharp
-// 设置窗口化
-DisplayServer.WindowSetMode(DisplayServer.WindowMode.Windowed);
-DisplayServer.WindowSetSize(newSize);
-
-// 居中窗口
-var screen = DisplayServer.GetPrimaryScreen();
-var screenSize = DisplayServer.ScreenGetSize(screen);
-var position = (screenSize - newSize) / 2;
-DisplayServer.WindowSetPosition(position);
-```
-
-## 最佳实践
-
-### 1. 音频设置管理
-
-#### 音量变化平滑过渡
-
-```csharp
-public class AudioManager : Node
-{
-    private Tween _volumeTween;
-    
-    public async Task SmoothVolumeTransition(float targetMasterVolume, float duration = 1.0f)
-    {
-        var currentVolume = AudioServer.GetBusVolumeDb(AudioServer.GetBusIndex("Master"));
-        var currentLinear = Mathf.DbToLinear(currentVolume);
-        
-        _volumeTween?.Kill();
-        _volumeTween = CreateTween();
-        
-        _volumeTween.TweenMethod(
-            new Callable(this, nameof(SetMasterVolume)),
-            currentLinear,
-            targetMasterVolume,
-            duration
-        );
-    }
-    
-    private async void SetMasterVolume(float linearVolume)
-    {
-        var settings = new AudioSettings { MasterVolume = linearVolume };
-        var audioSettings = new GodotAudioSettings(settings, new AudioBusMap());
-        await audioSettings.ApplyAsync();
-    }
-}
-
-// 使用自定义总线映射的平滑过渡
-public class CustomAudioManager : Node
-{
-    private Tween _volumeTween;
-    private AudioBusMap _customBusMap;
-    
-    public override void _Ready()
-    {
-        _customBusMap = new AudioBusMap
-        {
-            Master = "Master_Bus",
-            Bgm = "Background_Music",
-            Sfx = "Sound_Effects"
-        };
-    }
-    
-    public async Task SmoothVolumeTransition(float targetMasterVolume, float duration = 1.0f)
-    {
-        var settings = new AudioSettings { MasterVolume = targetMasterVolume };
-        var currentVolume = AudioServer.GetBusVolumeDb(AudioServer.GetBusIndex(_customBusMap.Master));
-        var currentLinear = Mathf.DbToLinear(currentVolume);
-        
-        _volumeTween?.Kill();
-        _volumeTween = CreateTween();
-        
-        _volumeTween.TweenMethod(
-            new Callable(this, nameof(SetMasterVolume)),
-            currentLinear,
-            targetMasterVolume,
-            duration
-        );
-    }
-    
-    private async void SetMasterVolume(float linearVolume)
-    {
-        var audioSettingsData = new AudioSettings { MasterVolume = linearVolume };
-        var audioSettings = new GodotAudioSettings(audioSettingsData, _customBusMap);
-        await audioSettings.ApplyAsync();
-    }
-}
-```
-
-#### 音频设置验证
-
-```csharp
-public static class AudioSettingsValidator
-{
-    public static bool ValidateBusNames(AudioBusMap busMap)
-    {
-        var masterIndex = AudioServer.GetBusIndex(busMap.Master);
-        var bgmIndex = AudioServer.GetBusIndex(busMap.Bgm);
-        var sfxIndex = AudioServer.GetBusIndex(busMap.Sfx);
-        
-        return masterIndex >= 0 && bgmIndex >= 0 && sfxIndex >= 0;
-    }
-    
-    public static void LogMissingBuses(AudioBusMap busMap)
-    {
-        if (AudioServer.GetBusIndex(busMap.Master) < 0)
-            GD.PrintErr($"Master bus not found: {busMap.Master}");
-        
-        if (AudioServer.GetBusIndex(busMap.Bgm) < 0)
-            GD.PrintErr($"BGM bus not found: {busMap.Bgm}");
-        
-        if (AudioServer.GetBusIndex(busMap.Sfx) < 0)
-            GD.PrintErr($"SFX bus not found: {busMap.Sfx}");
-    }
-}
-```
-
-### 2. 图形设置管理
-
-#### 分辨率变更安全检查
-
-```csharp
-public static class DisplayValidator
-{
-    public static bool IsResolutionSupported(int width, int height)
-    {
-        var screen = DisplayServer.GetPrimaryScreen();
-        var screenSize = DisplayServer.ScreenGetSize(screen);
-        
-        return width <= screenSize.x && height <= screenSize.y;
-    }
-    
-    public static (int width, int height) GetMaxSafeResolution()
-    {
-        var screen = DisplayServer.GetPrimaryScreen();
-        var screenSize = DisplayServer.ScreenGetSize(screen);
-        
-        return ((int)screenSize.x, (int)screenSize.y);
-    }
-}
-```
-
-#### 图形设置持久化
-
-```csharp
-public class GraphicsSettingsManager : Node
-{
-    private const string SettingsKey = "graphics_settings";
-    private GodotGraphicsSettings _settings;
-    
-    public override void _Ready()
-    {
-        LoadSettings();
-    }
-    
-    private void LoadSettings()
-    {
-        var storage = new GodotFileStorage(new JsonSerializer());
-        
-        try
-        {
-            _settings = storage.Read<GodotGraphicsSettings>(SettingsKey);
-        }
-        catch (FileNotFoundException)
-        {
-            _settings = new GodotGraphicsSettings
-            {
-                ResolutionWidth = 1920,
-                ResolutionHeight = 1080,
-                Fullscreen = false
-            };
-            SaveSettings();
-        }
-    }
-    
-    public void SaveSettings()
-    {
-        var storage = new GodotFileStorage(new JsonSerializer());
-        storage.Write(SettingsKey, _settings);
-    }
-    
-    public async Task ApplyAndSave()
-    {
-        await _settings.ApplyAsync();
-        SaveSettings();
-    }
-}
-```
-
-## 性能考虑
-
-### 1. 音频设置应用
-
-- 音频总线查找是 O(1) 操作
-- 音量转换计算开销很小
-- 建议批量应用多个音量设置
-
-### 2. 图形设置应用
-
-- 窗口操作需要系统调用，相对较慢
-- 分辨率变更可能触发窗口重建
-- 避免频繁切换显示模式
-
-### 3. 设置持久化
-
-- 使用异步文件 I/O
-- 考虑设置变更防抖机制
-- 压缩设置文件以减少 I/O 开销
-
-## 故障排除
-
-### 常见问题
-
-#### 1. 音频总线未找到
-
-```
-错误：Audio bus not found: CustomBGM
-解决：确保在 Godot 项目中创建了对应的音频总线
-```
-
-#### 2. 分辨率设置无效
-
-```
-错误：分辨率无法设置到指定值
-解决：检查分辨率是否超出显示器支持范围
-```
-
-#### 3. 全屏模式问题
-
-```
-错误：全屏切换失败
-解决：检查是否在调试器中运行，某些全屏模式在调试时可能不可用
-```
-
-### 调试技巧
-
-#### 音频调试
-
-```csharp
-// 打印所有音频总线信息
-for (int i = 0; i < AudioServer.GetBusCount(); i++)
-{
-    var name = AudioServer.GetBusName(i);
-    var volume = AudioServer.GetBusVolumeDb(i);
-    GD.Print($"Bus {i}: {name} ({volume} dB)");
-}
-```
-
-#### 图形调试
-
-```csharp
-// 打印当前显示信息
-var screen = DisplayServer.GetPrimaryScreen();
-var screenSize = DisplayServer.ScreenGetSize(screen);
-var windowSize = DisplayServer.WindowGetSize();
-var windowPos = DisplayServer.WindowGetPosition();
-var windowMode = DisplayServer.WindowGetMode();
-
-GD.Print($"Screen: {screenSize}");
-GD.Print($"Window: {windowSize} at {windowPos}");
-GD.Print($"Mode: {windowMode}");
-```
+1. [Godot 运行时集成](./index.md)
+2. [Game 设置系统](../game/setting.md)
+3. [Godot 存储系统](./storage.md)
+4. [Godot 集成教程](../tutorials/godot-integration.md)
diff --git a/docs/zh-CN/godot/storage.md b/docs/zh-CN/godot/storage.md
index 03b7da1a..7ad94a59 100644
--- a/docs/zh-CN/godot/storage.md
+++ b/docs/zh-CN/godot/storage.md
@@ -1,275 +1,138 @@
-# 存储模块 (Storage Module)
+---
+title: Godot 存储系统
+description: 以当前 GFramework.Godot 源码与 CoreGrid 接线为准，说明 GodotFileStorage 的职责、路径边界和最小接入方式。
+---
 
-## 概述
+# Godot 存储系统
 
-存储模块是 GFramework.Godot 的核心存储实现，专门为 Godot 引擎设计的文件存储系统。该模块支持 Godot 的虚拟路径系统（如
-`res://` 和 `user://`），并提供了按键级别的细粒度锁机制来保证线程安全。
+`GFramework.Godot` 在存储这一层提供的核心入口只有 `GodotFileStorage`。
 
-## 核心类
+它实现 `GFramework.Game` 侧统一的 `IStorage` 契约，负责把序列化后的读写、目录列举和路径处理接到 Godot 的
+`res://`、`user://` 和普通文件系统路径上，而不是另外提供一套独立的“Godot 专属存档框架”。
 
-### GodotFileStorage
+## 当前公开入口
 
-Godot 特化的文件存储实现，实现了 `IStorage` 接口。
+### `GodotFileStorage`
 
-**主要特性：**
+`GodotFileStorage` 的当前职责比较集中：
 
-- ✅ Godot 虚拟路径支持（`res://`, `user://`）
-- ✅ 线程安全（按键级别的细粒度锁）
-- ✅ 同步/异步读写操作
-- ✅ 自动创建目录结构
-- ❌ 删除操作（Delete 方法未实现）
+- 对外暴露 `IStorage` 约定的 `Read`、`Write`、`Exists`、`Delete`、目录列举与目录创建能力
+- 识别并保留 Godot 虚拟路径：`res://`、`user://`
+- 对普通文件系统路径做段级清理，并拒绝包含 `..` 的非法 key
+- 使用 `IAsyncKeyLockManager` 对“绝对路径 / Godot 路径”做按 key 细粒度串行化
 
-## 功能特性
+构造函数默认会在未注入锁管理器时创建内部 `AsyncKeyLockManager`。这意味着：
 
-### 路径处理
+- 同一个 `GodotFileStorage` 实例内，不同文件可以并发访问
+- 同一个目标路径的读写 / 删除会被串行化
+- 锁作用域只限当前进程内的当前实例，不是跨进程文件锁
 
-该存储系统支持三种路径类型：
+## 路径语义
 
-#### 1. Godot 资源路径 (`res://`)
+### `res://`
 
-- **用途**：存储游戏资源文件
-- **特点**：只读，包含在游戏构建中
-- **示例**：`res://config/game_settings.json`
+`res://` 更适合作为只读资源或配置源目录。
 
-#### 2. Godot 用户数据路径 (`user://`)
+当前实现不会阻止你把它传给 `ReadAsync`、`ExistsAsync` 之类的方法，但在导出后的 Godot 项目里，`res://`
+通常不应被当作用户可写存储根目录。存档、设置和运行时缓存应优先落到 `user://`。
 
-- **用途**：存储用户数据、存档、配置等
-- **特点**：可读写，游戏可访问的用户目录
-- **示例**：`user://saves/save_001.dat`
+### `user://`
 
-#### 3. 普通文件系统路径
+`user://` 是当前推荐的可写路径：
 
-- **用途**：存储临时文件或调试数据
-- **特点**：完整的文件系统访问
-- **示例**：`C:/Games/MyGame/logs/debug.log`
+- 用户设置
+- 存档
+- 运行时缓存
+- 导出后仍需要读写的 JSON / YAML / 二进制数据
 
-### 路径验证与清理
+如果调用 `ListDirectoriesAsync()` 或 `ListFilesAsync()` 时传入空字符串，当前实现会默认从 `user://` 根开始列举。
 
-```mermaid
-graph TD
-    A[输入路径] --> B{包含 ".." ?}
-    B -->|是| C[抛出异常]
-    B -->|否| D{是 Godot 路径?}
-    D -->|是| E[直接使用]
-    D -->|否| F[清理路径段]
-    F --> G[替换无效字符]
-    G --> H[创建目录结构]
-    H --> I[返回绝对路径]
-    C --> J[结束]
-    E --> J
-    I --> J
-```
+### 普通文件系统路径
 
-### 线程安全机制
+当 key 不是 Godot 路径时，`GodotFileStorage` 会：
 
-每个文件路径都有独立的锁对象，确保：
+1. 把 `\` 统一成 `/`
+2. 拒绝包含 `..` 的 key
+3. 按路径段清理非法文件名字符
+4. 在写入或建目录前自动补父目录
 
-1. **细粒度锁** - 不同文件可以并发访问
-2. **避免死锁** - 锁的获取顺序一致
-3. **高性能** - 减少锁竞争
+这条路径更适合测试、桌面工具链或显式指定外部目录的宿主环境，不建议在项目业务层自己重新拼装一套路径清理逻辑。
 
-## API 接口
+## 最小接入路径
 
-### IStorage 接口
+当前消费者 `ai-libs/CoreGrid` 的接法是先注册同一个序列化器和存储实例，再让设置仓库、存档仓库等上层组件复用它：
 
 ```csharp
-public interface IStorage
-{
-    // 读取操作
-    T Read<T>(string key);
-    T Read<T>(string key, T defaultValue);
-    Task<T> ReadAsync<T>(string key);
-    
-    // 写入操作
-    void Write<T>(string key, T value);
-    Task WriteAsync<T>(string key, T value);
-    
-    // 检查存在性
-    bool Exists(string key);
-    Task<bool> ExistsAsync(string key);
-    
-    // 删除操作（未实现）
-    void Delete(string key);
-}
+using GFramework.Core.Abstractions.Serializer;
+using GFramework.Core.Abstractions.Storage;
+using GFramework.Game.Abstractions.Data;
+using GFramework.Game.Storage;
+using GFramework.Godot.Storage;
+using Godot;
+
+var jsonSerializer = new JsonSerializer();
+architecture.RegisterUtility<ISerializer>(jsonSerializer);
+
+var storage = new GodotFileStorage(jsonSerializer);
+architecture.RegisterUtility<IStorage>(storage);
+
+architecture.RegisterUtility(new UnifiedSettingsDataRepository(
+    storage,
+    jsonSerializer,
+    new DataRepositoryOptions
+    {
+        BasePath = ProjectSettings.GetSetting("application/config/save/setting_path").AsString(),
+        AutoBackup = true
+    }));
+
+architecture.RegisterUtility<ISaveRepository<GameSaveData>>(new SaveRepository<GameSaveData>(
+    storage,
+    new SaveConfiguration
+    {
+        SaveRoot = ProjectSettings.GetSetting("application/config/save/save_path").AsString(),
+        SaveSlotPrefix = ProjectSettings.GetSetting("application/config/save/save_slot_prefix").AsString(),
+        SaveFileName = ProjectSettings.GetSetting("application/config/save/save_file_name").AsString()
+    }));
 ```
 
-## 使用示例
+这里的分工是：
 
-### 基本使用
+- `GodotFileStorage` 负责底层 key -> 文件读写
+- `UnifiedSettingsDataRepository` 负责设置节聚合与持久化
+- `SaveRepository<TSaveData>` 负责存档结构和保存槽位语义
 
-```csharp
-// 创建存储实例（需要序列化器）
-var serializer = new JsonSerializer(); // 或其他序列化器
-var storage = new GodotFileStorage(serializer);
+不要把 `GodotFileStorage` 本身写成“设置系统”或“存档系统”的 owner。
 
-// 写入用户数据
-var userData = new UserData
-{
-    PlayerName = "Alice",
-    Level = 5,
-    Score = 1000
-};
-storage.Write("user://player.dat", userData);
+## 什么时候应该改看别的入口
 
-// 读取用户数据
-var loadedData = storage.Read<UserData>("user://player.dat");
-Console.WriteLine($"Player: {loadedData.PlayerName}, Level: {loadedData.Level}");
-```
+### 配置 YAML / schema 文本加载
 
-### 异步操作
+如果你的目标是读取 `res://` 下的 YAML 配置，并在导出态同步到运行时缓存，请优先看
+[`../game/config-system.md`](../game/config-system.md) 里的 `GodotYamlConfigLoader` 接法。
 
-```csharp
-// 异步写入游戏配置
-var config = new GameConfig
-{
-    Resolution = "1920x1080",
-    Fullscreen = true,
-    Volume = 0.8f
-};
-await storage.WriteAsync("user://config.json", config);
+这类场景的重点不是通用键值存储，而是：
 
-// 异步读取配置
-var loadedConfig = await storage.ReadAsync<GameConfig>("user://config.json");
-```
+- `res://` 与 `user://` 缓存切换
+- 生成器表元数据
+- 热重载可用性边界
 
-### 不同路径类型使用
+### 通用存储契约
 
-```csharp
-// 读取游戏资源（只读）
-var levelData = storage.Read<LevelData>("res://levels/level_001.json");
+如果你想先理解 `IStorage`、`ScopedStorage`、`FileStorage` 和统一数据仓库的宿主无关语义，应先看
+[`../game/storage.md`](../game/storage.md)。
 
-// 存储用户存档
-var saveData = new SaveData { /* ... */ };
-storage.Write("user://saves/slot_001.dat", saveData);
+本页只补 Godot 宿主差异，不重复维护一份跨宿主 API 手册。
 
-// 存储调试信息（普通路径）
-var debugLog = new DebugLog { /* ... */ };
-storage.Write("logs/debug_" + DateTime.UtcNow.Ticks + ".json", debugLog);
-```
+## 当前边界
 
-### 存在性检查
+- 同步 `Read` / `Write` / `Delete` / `Exists` 只是对异步方法的阻塞包装；在带同步上下文的宿主里，优先使用异步 API
+- `GodotFileStorage` 不负责文件扩展名约定、作用域前缀或保存槽位策略，这些属于上层 repository / scoped storage
+- 路径安全只覆盖当前 key 的格式校验与路径段清理，不代替业务层的目录规划
+- 当前实现支持目录列举与目录创建，但没有额外的“监视目录变化”或“自动迁移目录结构”能力
 
-```csharp
-// 检查文件是否存在
-if (storage.Exists("user://settings.json"))
-{
-    var settings = storage.Read<AppSettings>("user://settings.json");
-    // 使用设置...
-}
-else
-{
-    // 使用默认设置
-    var defaultSettings = new AppSettings();
-    storage.Write("user://settings.json", defaultSettings);
-}
-```
+## 继续阅读
 
-### 带默认值的读取
-
-```csharp
-// 尝试读取，如果文件不存在则返回默认值
-var settings = storage.Read("user://user_prefs.json", new UserPrefs
-{
-    Language = "en",
-    Volume = 1.0f,
-    Difficulty = 1
-});
-```
-
-## 路径扩展
-
-该模块使用了路径扩展方法：
-
-```csharp
-public static class GodotPathExtensions
-{
-    public static bool IsUserPath(this string path);
-    public static bool IsResPath(this string path);
-    public static bool IsGodotPath(this string path);
-}
-```
-
-**使用示例：**
-
-```csharp
-string path1 = "user://save.dat";
-string path2 = "res://config.json";
-string path3 = "C:/temp/file.txt";
-
-Console.WriteLine(path1.IsGodotPath()); // true
-Console.WriteLine(path1.IsUserPath());  // true
-Console.WriteLine(path2.IsResPath());    // true
-Console.WriteLine(path3.IsGodotPath()); // false
-```
-
-## 性能考虑
-
-### 1. 锁机制
-
-- 每个文件路径独立锁，减少锁竞争
-- 读写操作串行化，避免数据损坏
-
-### 2. 文件访问
-
-- Godot 虚拟路径使用 `FileAccess` API
-- 普通路径使用标准 .NET 文件 I/O
-- 自动创建目录结构
-
-### 3. 内存使用
-
-- 锁对象使用 `ConcurrentDictionary` 管理
-- 锁对象按需创建，避免内存泄漏
-
-## 错误处理
-
-### 常见异常
-
-1. **ArgumentException** - 路径参数无效
-    - 空路径
-    - 包含 ".." 的路径
-    - 无效的存储键
-
-2. **FileNotFoundException** - 文件不存在
-    - 读取不存在的文件时抛出
-
-3. **IOException** - 文件操作失败
-    - 写入权限不足
-    - 磁盘空间不足
-
-### 错误处理示例
-
-```csharp
-try
-{
-    var data = storage.Read<UserData>("user://save.dat");
-}
-catch (FileNotFoundException)
-{
-    Console.WriteLine("存档文件不存在，创建新的存档");
-    var newSave = new UserData();
-    storage.Write("user://save.dat", newSave);
-}
-catch (Exception ex)
-{
-    Console.WriteLine($"读取存档失败: {ex.Message}");
-}
-```
-
-## 最佳实践
-
-1. **路径选择**
-    - 游戏资源使用 `res://`
-    - 用户数据使用 `user://`
-    - 调试/临时文件使用普通路径
-
-2. **异常处理**
-    - 总是处理 `FileNotFoundException`
-    - 使用带默认值的 `Read` 重载方法
-
-3. **性能优化**
-    - 批量读写时使用异步方法
-    - 避免频繁的小文件操作
-
-4. **序列化器选择**
-    - JSON：人类可读，调试友好
-    - 二进制：性能更好，文件更小
\ No newline at end of file
+1. [Godot 运行时集成](./index.md)
+2. [Game 存储系统](../game/storage.md)
+3. [Game 配置系统](../game/config-system.md)
+4. [Godot 集成教程](../tutorials/godot-integration.md)
diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md
index 279762e2..fbde5df3 100644
--- a/docs/zh-CN/source-generators/index.md
+++ b/docs/zh-CN/source-generators/index.md
@@ -1,3 +1,8 @@
+---
+title: Source Generators
+description: 按模块梳理 GFramework 当前发布的源码生成器包、运行时归属与推荐选包入口。
+---
+
 # Source Generators
 
 `Source Generators` 栏目对应 `GFramework` 当前按模块拆分发布的编译期工具链。
@@ -23,7 +28,7 @@ GFramework 当前发布的生成器包是：
   - 选择 `GeWuYou.GFramework.Game.SourceGenerators`
 - 想让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围：
   - 选择 `GeWuYou.GFramework.Cqrs.SourceGenerators`
-- 想在 Godot 项目里生成 AutoLoad / Input Action 入口，或减少节点与信号样板代码：
+- 想在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助：
   - 选择 `GeWuYou.GFramework.Godot.SourceGenerators`
 
 ## 与运行时的关系