Docs/sdk update documentation

GFramework.Core.Abstractions/README.md

@@ -36,18 +36,17 @@
 
 ## XML 阅读入口
 
-截至 `2026-04-22`，下面这份目录视图可以帮助你快速定位 `GFramework.Core.Abstractions` 的类型级 XML 文档入口；当前契约目录族的类型声明都已带
-XML 注释。更细的契约约束与交互语义，适合在阅读具体接口和成员时继续结合源码确认。
+下面这份目录视图可以帮助你快速定位 `GFramework.Core.Abstractions` 的代表类型。更细的契约约束与交互语义，适合在阅读具体接口和成员时继续结合源码确认。
 
-| 类型族 | 基线状态 | 代表类型 |
+| 类型族 | 代表类型 | 阅读重点 |
 | --- | --- | --- |
-| `Architectures/` `Lifecycle/` `Registries/` | `20/20` 个类型声明已带 XML 注释 | `IArchitecture`、`IArchitectureContext`、`IServiceModule`、`KeyValueRegistryBase<TKey, TValue>` |
-| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncQueryExecutor`、`ICqrsRuntime` |
-| `Events/` `Property/` `State/` `StateManagement/` | `25/25` 个类型声明已带 XML 注释 | `IEventBus`、`IBindableProperty<T>`、`IStateMachine`、`IStore<TState>` |
-| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `17/17` 个类型声明已带 XML 注释 | `IYieldInstruction`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` |
-| `Resource/` `Pool/` `Logging/` `Localization/` | `27/27` 个类型声明已带 XML 注释 | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`ILocalizationManager` |
-| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage` |
-| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` |
+| `Architectures/` `Lifecycle/` `Registries/` | `IArchitecture`、`IArchitectureContext`、`IServiceModule`、`KeyValueRegistryBase<TKey, TValue>` | 看架构、上下文、模块装配与注册表基类边界 |
+| `Command/` `Query/` `Cqrs/` | `ICommandExecutor`、`IAsyncQueryExecutor`、`ICqrsRuntime` | 看命令、查询与新请求模型的调用入口 |
+| `Events/` `Property/` `State/` `StateManagement/` | `IEventBus`、`IBindableProperty<T>`、`IStateMachine`、`IStore<TState>` | 看事件分发、可绑定状态与 store 契约 |
+| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `IYieldInstruction`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` | 看协程、时间源、暂停栈与并发协调能力 |
+| `Resource/` `Pool/` `Logging/` `Localization/` | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`ILocalizationManager` | 看资源、对象池、日志与本地化服务角色 |
+| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage` | 看配置、环境、数据装载、序列化与存储边界 |
+| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 看组件角色、优先级和值对象约定 |
 
 完整接入说明与阅读顺序见 [Core 抽象层说明](../docs/zh-CN/abstractions/core-abstractions.md)。
 

GFramework.Cqrs.Abstractions/README.md

@@ -1,6 +1,6 @@
 # GFramework.Cqrs.Abstractions
 
-`GFramework.Cqrs.Abstractions` 提供 GFramework CQRS 的最小契约层。它只包含消息接口、处理器接口、运行时 seam 和管道契约，不包含默认 dispatcher、处理器扫描或任何 `GFramework.Core` 运行时实现。适合以下场景：
+`GFramework.Cqrs.Abstractions` 提供 GFramework CQRS 的最小契约层。它只包含消息接口、处理器接口、运行时协作接口和管道契约，不包含默认 dispatcher、处理器扫描或任何 `GFramework.Core` 运行时实现。适合以下场景：
 
 - 你的业务程序集只需要声明 Command、Query、Notification、Stream Request 或处理器接口。
 - 你希望把消息契约放在更稳定的基础层，避免直接依赖默认 runtime 实现。
@@ -43,7 +43,7 @@
   - `Cqrs/IRequestHandler.cs`
   - `Cqrs/INotificationHandler.cs`
   - `Cqrs/IStreamRequestHandler.cs`
-- 运行时 seam
+- 运行时协作接口
   - `Cqrs/ICqrsRuntime.cs`
   - `Cqrs/ICqrsContext.cs`
   - `Cqrs/ICqrsHandlerRegistrar.cs`
@@ -93,7 +93,7 @@ public sealed class GetPlayerProfileHandler
 
 - 只引用本包时，没有 `CommandBase<TInput, TResponse>`、`QueryBase<TInput, TResponse>`、`NotificationBase<TInput>` 等消息基类。
 - 只引用本包时，没有 `AbstractCommandHandler`、`AbstractQueryHandler`、`AbstractNotificationHandler` 等处理器基类。
-- `ICqrsContext` 当前是轻量 marker seam；默认 runtime 在需要向 `IContextAware` 处理器注入上下文时，仍要求传入的上下文同时实现 `IArchitectureContext`。
+- `ICqrsContext` 当前是轻量 marker 接口；默认 runtime 在需要向 `IContextAware` 处理器注入上下文时，仍要求传入的上下文同时实现 `IArchitectureContext`。
 
 ## 文档入口
 

GFramework.Ecs.Arch.Abstractions/README.md

@@ -37,11 +37,11 @@
 
 下表汇总当前契约包的类型级 XML 文档入口，方便把 README、站内抽象页与源码阅读顺序对齐。
 
-| 类型族 | 代表类型 | XML 状态 | 阅读重点 |
-| --- | --- | --- | --- |
-| 模块契约 | `IArchEcsModule` | 已覆盖 | 宿主循环如何统一驱动 ECS 更新 |
-| 系统桥接契约 | `IArchSystemAdapter<T>` | 已覆盖 | 外部模块怎样只依赖更新接口而不绑定默认实现 |
-| 配置对象 | `ArchOptions` | 已覆盖 | 跨程序集共享 ECS 配置边界 |
+| 类型族 | 代表类型 | 阅读重点 |
+| --- | --- | --- |
+| 模块契约 | `IArchEcsModule` | 宿主循环如何统一驱动 ECS 更新 |
+| 系统桥接契约 | `IArchSystemAdapter<T>` | 外部模块怎样只依赖更新接口而不绑定默认实现 |
+| 配置对象 | `ArchOptions` | 跨程序集共享 ECS 配置边界 |
 
 ## 最小接入路径
 

GFramework.Ecs.Arch/README.md

@@ -1,6 +1,6 @@
 # GFramework.Ecs.Arch
 
-`GFramework.Ecs.Arch` 是 `GFramework` 当前 Arch ECS family 的默认运行时实现包。
+`GFramework.Ecs.Arch` 是 `GFramework` 当前 Arch ECS 集成的默认运行时实现包。
 
 它负责把 Arch `World`、GFramework 的服务模块生命周期，以及 `ArchSystemAdapter<T>` 系统桥接到同一条采用路径中。
 如果你需要的只是共享契约，请改为依赖 `GFramework.Ecs.Arch.Abstractions`。

GFramework.Game.Abstractions/README.md

@@ -25,8 +25,7 @@
   - `FileStorage`、`ScopedStorage`、`JsonSerializer`、`SettingsModel<TRepository>`、`SaveRepository<TSaveData>`、`SceneRouterBase`、`UiRouterBase`、`YamlConfigLoader` 等都在实现这里的契约。
 - 引擎适配包或项目代码
   - `IUiFactory`、`ISceneFactory`、`IUiRoot`、`ISceneRoot`、资源注册表等通常由引擎适配层或游戏项目自己实现。
-  - 仓库内 `ai-libs/` 下的只读参考实现通常也是这样组织：页面 / 场景 factory、root、registry 在项目层，
-    运行时基类和契约来自 `GFramework.Game` 与本包。
+  - 常见做法也是这样组织：页面 / 场景 factory、root、registry 在项目层，运行时基类和契约来自 `GFramework.Game` 与本包。
 
 ## 子系统地图
 
@@ -133,17 +132,16 @@ Scene 与 UI 路由共享这套基础约定。
 
 ## XML 阅读入口
 
-下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game.Abstractions` 类型级 XML 文档入口：只统计公开 /
-内部类型声明是否带 XML 注释，用来帮助你建立契约层阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。
+下面这份目录视图用于帮助你建立 `GFramework.Game.Abstractions` 的契约层阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。
 
-| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>`、`ConfigLoadException` | 看配置表注册、读取约定和失败诊断模型 |
-| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>`、`DataRepositoryOptions` | 看业务数据、设置持久化、槽位存档和版本迁移契约 |
-| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置数据、应用语义、迁移接口和内置设置对象 |
-| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、路由、工厂 / root 边界与转场事件模型 |
-| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作与 UI 转场契约 |
-| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry<T>`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 |
+| 契约族 | 代表类型 | 阅读重点 |
+| --- | --- | --- |
+| `Config/` | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>`、`ConfigLoadException` | 看配置表注册、读取约定和失败诊断模型 |
+| `Data/` | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>`、`DataRepositoryOptions` | 看业务数据、设置持久化、槽位存档和版本迁移契约 |
+| `Setting/` | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置数据、应用语义、迁移接口和内置设置对象 |
+| `Scene/` | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、路由、工厂 / root 边界与转场事件模型 |
+| `UI/` | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作与 UI 转场契约 |
+| `Routing/` `Storage/` `Asset/` `Enums/` | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry<T>`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 |
 
 ## 最小接入路径
 
@@ -210,9 +208,9 @@ public sealed class ContinueGameCommandHandler
 
 也就是说，本包回答的是“项目各层如何约定”，`GFramework.Game` 回答的是“这些约定默认怎么跑起来”。
 
-## `ai-libs/` 里的参考接入线索
+## 典型分层方式
 
-`ai-libs/` 下的只读参考实现对本包的使用方式，能比较清楚地说明它的职责边界：
+典型项目对本包的使用方式，通常能清楚体现它的职责边界：
 
 - 公共脚本广泛引用：
   - `IUiRouter`

GFramework.Game.SourceGenerators/README.md

@@ -46,12 +46,12 @@ GameProject/
 
 ## XML 阅读入口
 
-下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game.SourceGenerators` 类型级 XML 文档入口：只统计公开类型声明是否带 XML 注释，用来帮助你定位生成器入口；具体诊断消息、生成输出和兼容性语义仍建议回到源码与测试继续核对。
+下面这份目录视图用于帮助你定位 `GFramework.Game.SourceGenerators` 的生成器入口；具体诊断消息、生成输出和兼容性语义仍建议回到源码与测试继续核对。
 
-| 类型族 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `Config/` | `1/1` 个类型声明已带 XML 注释 | `SchemaConfigGenerator` | 看 schema 到配置类型 / 表包装 / 注册辅助代码的生成入口 |
-| `Diagnostics/` | `1/1` 个类型声明已带 XML 注释 | `ConfigSchemaDiagnostics` | 看生成器会抛出的诊断类别与失败边界 |
+| 阅读主题 | 代表类型 | 阅读重点 |
+| --- | --- | --- |
+| 配置生成入口 | `SchemaConfigGenerator` | 看 schema 到配置类型 / 表包装 / 注册辅助代码的生成入口 |
+| 诊断与失败边界 | `ConfigSchemaDiagnostics` | 看生成器会抛出的诊断类别与失败边界 |
 
 ## 最小接入路径
 

GFramework.Game/README.md

@@ -31,8 +31,7 @@
 - 引擎适配包或项目内适配层
   - 本包提供的是“引擎无关”的核心逻辑和基类。
   - 真正和 Godot、Unity、MonoGame 等引擎对象打交道的工厂、根节点、资源注册表，通常在相邻引擎包或游戏项目内实现。
-  - 仓库内 `ai-libs/` 下的只读参考实现通常也是这样接入：配置文件 IO 由 `GFramework.Godot.Config` 适配，
-    UI / Scene factory 与 root 由项目自己提供。
+  - 典型项目里，配置文件 IO 会交给宿主适配层处理，UI / Scene 的 factory 与 root 则继续由项目自己提供。
 
 ## 子系统地图
 
@@ -73,7 +72,7 @@
 - `SaveConfiguration`
   - 槽位目录、文件名、前缀等约定
 
-`ai-libs/` 下已验证参考实现的常见接法：
+常见接法：
 
 - 设置持久化使用 `UnifiedSettingsDataRepository`
 - 存档使用 `SaveRepository<GameSaveData>`
@@ -96,7 +95,7 @@
 - `Setting/Events/*`
   - 设置初始化、应用、保存、重置相关事件
 
-`ai-libs/` 下已验证参考实现的常见接法：
+常见接法：
 
 - 在模型模块中创建 `SettingsModel<ISettingsDataRepository>`
 - 注册多个 applicator
@@ -122,7 +121,6 @@
 对应文档：
 
 - [存储系统](../docs/zh-CN/game/storage.md)
-- [Storage 子模块说明](./Storage/ReadMe.md)
 
 ### `Serializer/`
 
@@ -149,7 +147,7 @@
 - `Scene/Handler/*`、`UI/Handler/*`
   - 默认转换处理器基类与日志处理器
 
-`ai-libs/` 下已验证参考实现的常见接法：
+常见接法：
 
 - 项目自定义 `SceneRouter : SceneRouterBase`
 - 项目自定义 `UiRouter : UiRouterBase`
@@ -266,7 +264,7 @@ await settingsSystem.ApplyAll();
 await settingsSystem.SaveAll();
 ```
 
-`ai-libs/` 下的只读参考实现目前也是按这个思路接入，只是底层存储换成了 Godot 适配实现。
+在 Godot 项目中也可以沿用同一思路，只是底层存储通常换成宿主侧适配实现。
 
 ### 3. 接入静态 YAML 配置
 
@@ -324,9 +322,9 @@ public sealed class MyUiRouter : UiRouterBase
 
 这类 router 适合作为你的项目层或引擎适配层代码，而不是直接修改本包。
 
-## `ai-libs/` 里的参考接入线索
+## 典型项目分层方式
 
-当前仓库内的只读参考实现，对本包的使用大致分成三层：
+典型项目对本包的使用大致分成三层：
 
 - 配置
   - 项目级配置宿主类型使用生成表元数据与 YAML loader 完成配置注册

GFramework.Godot/README.md

@@ -119,23 +119,19 @@ Godot 上。
 
 ### 4. 按需接入配置、存储和设置
 
-当项目已经使用 `Game` family 的配置、存储、设置契约时，再补 Godot 侧实现：
+当项目已经使用 `Game` 模块的配置、存储、设置契约时，再补 Godot 侧实现：
 
 - 配置：`GodotYamlConfigLoader`
 - 存储：`GodotFileStorage`
 - 设置：`GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
 
-不要把这些宿主实现误写成 `Game` family 的默认行为。
+不要把这些宿主实现误写成 `Game` 模块的默认行为。
 
-## `ai-libs/` 里的参考接入线索
-
-`ai-libs/CoreGrid` 仍是当前最直接的消费者证据来源：
+## 典型接入方式
 
 - 架构侧保持普通模块注册，再按需挂接 Godot 宿主
 - `project.godot` 元数据与节点样板交给 `GFramework.Godot.SourceGenerators`
-- Scene / UI 继续沿用 `Game` family 的 router 语义
-
-当 `ai-libs/` 与源码或测试冲突时，应以当前源码与测试为准。
+- Scene / UI 继续沿用 `Game` 模块的路由语义
 
 ## 文档入口