gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-10 19:56:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #296 from GeWuYou/docs/sdk-update-documentation

Browse Source 
Docs/sdk update documentation
This commit is contained in:
gewuyou 2026-04-27 13:22:54 +08:00 committed by GitHub
commit 99ccc28697
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
46 changed files with 458 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
GFramework.Core.Abstractions/README.md
View File

@ -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)。

6
GFramework.Cqrs.Abstractions/README.md
View File

@ -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`。
## 文档入口

10
GFramework.Ecs.Arch.Abstractions/README.md
View File

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

2
GFramework.Ecs.Arch/README.md
View File

@ -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`。

26
GFramework.Game.Abstractions/README.md
View File

@ -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`

10
GFramework.Game.SourceGenerators/README.md
View File

@ -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` | 看生成器会抛出的诊断类别与失败边界 |
## 最小接入路径

16
GFramework.Game/README.md
View File

@ -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 完成配置注册

12
GFramework.Godot/README.md
View File

@ -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` 模块的路由语义
## 文档入口

101
ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md
View File

@ -12,14 +12,13 @@
## 当前恢复点
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-040`
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-044`
- 当前阶段：`Phase 5 - Governance Maintenance`
- 当前焦点：
- 继续以最新 `origin/main`（`79934f7`，`2026-04-25 16:15:55 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files
- 当前批次已从“单点 review 收口”切到“覆盖整个项目功能的 reader-facing 文档补齐”，重点处理 4 组低风险切片：meta-package / 安装入口、config tool adoption、source-generators 真实契约修正、内部支撑模块 README
- 当前未提交工作树已触达 `18` 个文件，其中 `14` 个更新、`4` 个新增；当前 committed branch diff vs `origin/main` 仍为 `3` files，提交本批次后仍明显低于 `50` 文件阈值
- 已接受 subagent 结论：`Cqrs` 当前不是栏目缺失，而是 `docs/zh-CN/core/cqrs.md` 需要补 `Request` / stream 变体与协程入口；source-generators 侧当前优先修正文档失真与共享支撑层说明，而不是扩新导航
- `2026-04-26` 重新抓取 PR `#292` 后确认 latest reviewed commit 已推进到 `d3d62cf4541063c46458f88eea0f5acd1b4503f9`；当前 open thread 仍集中在 `tools/gframework-config-tool/README.md`，其中“缺少中文文档入口链接”已在本地工作树验证为过期评论，仍需收口的是补最小接入路径以及统一 `current schema subset` 术语
- 继续以最新 `origin/main`（`617e0bf`，`2026-04-26 12:17:15 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files
- 本轮从 `$gframework-pr-review` 重新抓取当前 PR `#296`，确认 latest reviewed commit 为 `5778782df05e22dd24dc95189dd768458afb8537`，剩余 open thread 都落在 reader-facing 文案与 README 导航收口上
- 当前工作树相对 `origin/main` 的 tracked diff 仍接近 `50` files；因此本轮只接受 latest-head review 中仍成立的 4 条低风险修正，不再扩新栏目或新专题页
- 已确认 `Title check` 的 inconclusive 仅是 GitHub PR 标题元数据提示，不属于仓库文件内可修复范围；本轮只处理本地仍成立的文档线程
## 当前状态摘要
@ -32,6 +31,14 @@
- `2026-04-25` `docs/zh-CN/source-generators/index.md` 已按 PR `#292` review 调整“共享支撑模块”段落句式，避免“对读者更重要的判断是”这类拗口表达。
- `2026-04-25` `tools/gframework-config-tool/README.md` 已新增 `Documentation` 章节，直接链接到 `docs/zh-CN/game/config-tool.md` 与 `config-system.md`，让工具 README 能回到完整中文接入文档。
- `2026-04-26` `tools/gframework-config-tool/README.md` 已补 `Quick Start`，把安装扩展、配置 `configPath` / `schemasPath`、打开 Explorer、先跑校验、再进入表单 / 批量编辑的最小接入路径串起来，并把 `Validation Coverage` 的 `stable config-schema subset` 统一为 `current schema subset`。
- `2026-04-27` `docs/zh-CN/getting-started/installation.md` 已补齐当前公开选包矩阵，新增 `Core.Abstractions`、`Game.Abstractions`、`Ecs.Arch`、`Ecs.Arch.Abstractions` 的 reader-facing 安装说明，并把 `Godot` 常见问题里的旧版 `>= 4.5` 提示收敛到当前 `4.6.2` 基线。
- `2026-04-27` `GFramework.Core.Abstractions/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` 当前都已把 XML 阅读入口改写为“代表类型 + 阅读重点”，不再暴露覆盖计数、日期或 `已覆盖` 这类治理字段。
- `2026-04-27` `docs/zh-CN/game/config-system.md` 与 `docs/zh-CN/tutorials/basic/index.md` 已把维护者 / 指挥式措辞改成中性的采用建议与阅读入口，避免公开页面继续暴露内部决策口吻。
- `2026-04-27` `docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`api-reference/index.md`、`source-generators/index.md` 已统一收敛为“适用场景 / 起步路线 / 继续阅读”式 reader-facing 入口，不再把 GitHub blob README 或治理说明当作主导航。
- `2026-04-27` `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Godot/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Ecs.Arch/README.md` 已收口 `ai-libs`、`family`、`seam`、`ReadMe.md` 等内部化或文件名式表述。
- `2026-04-27` `docs/zh-CN` 当前已清空所有指向 `github.com/GeWuYou/GFramework/blob/main/.../README.md` 的公开外链，相关入口统一回到站内栏目页、专题页或 API 导航。
- `2026-04-27` `docs/zh-CN/tutorials/godot-integration.md`、`game/setting.md`、`game/serialization.md`、`godot/index.md`、`godot/architecture.md`、`godot/storage.md`、`godot/logging.md`、`godot/setting.md`、`godot/extensions.md`、`core/architecture.md` 已把 `旧文档` / `ai-libs` / `.Wait()` / `family` 这类维护与内部语气改写成当前采用说明。
- `2026-04-27` 已重新抓取 PR `#296` 并逐条复核 latest-head review：`GFramework.Game.SourceGenerators/README.md` 的 XML 阅读表已改成语义标签，`GFramework.Game/README.md` 已删除重复的 `storage.md` 入口，`docs/zh-CN/tutorials/godot-integration.md` 与 `docs/zh-CN/godot/extensions.md` 已收口仍成立的 reader-facing 措辞问题。
- `2026-04-25` 当前批次已补齐 meta-package / 安装面：`GFramework.csproj` 不再保留占位描述，`README.md`、`docs/zh-CN/index.md`、`docs/zh-CN/getting-started/installation.md` 当前明确说明聚合元包只聚合 `Core` + `Game`，并把安装入口更新到当前 `net8.0/net9.0/net10.0` 与 Godot `4.6.2` 基线。
- `2026-04-25` `docs/zh-CN/game/config-tool.md` 已新增为 reader-facing 工具页，`docs/zh-CN/game/index.md`、`config-system.md`、`docs/.vitepress/config.mts` 与 `tools/gframework-config-tool/README.md` 当前把 VS Code 配置工具纳入 `Game` 配置工作流入口。
- `2026-04-25` source-generators 栏目已修正 4 处真实契约问题：`GetNode` 显式路径 / `Lookup` 语义、枚举生成器实际开关、`Context Get` 集合注入边界，以及 `GFramework.SourceGenerators.Common` / `*.SourceGenerators.Abstractions` 的共享支撑层说明。
@ -51,7 +58,7 @@
`MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
- 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
- `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。
- PR `#292` 当前 review 线程仍主要来自 CodeRabbit，对 reader-facing 文案和文档入口连通性要求较细；本轮提交后仍需重新抓取 latest-head review，确认 open thread 是否已自动关闭。
- PR `#296` 当前 review 线程仍主要来自 CodeRabbit 与 Greptile，对 reader-facing 文案和文档入口连通性要求较细；本轮提交后仍需重新抓取 latest-head review，确认 open thread 是否已自动关闭。
## 归档指针
@ -68,12 +75,82 @@
## 最新验证
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md GFramework.Game/README.md`
- 结果：通过；本轮 2 个 README 的 reader-facing 表格与导航去重调整后链接目标有效。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`
- 结果：通过；Godot 集成教程的措辞收口后页面 frontmatter、链接与代码块校验均通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md`
- 结果：通过；Godot 扩展页去自我指涉表述后页面 frontmatter、链接与代码块校验均通过。
- `2026-04-27` `bun run build`（工作目录：`docs/`）
- 结果：通过；本轮 PR `#296` review 收口后的站点仍可构建，仅保留既有大 chunk warning。
- `2026-04-27` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json`
- 结果：通过；PR `#296` 处于 `OPEN`，latest head review 共有 `4` 条 open thread，其中 `3` 条文档问题与 `1` 条措辞 nitpick 在本地复核后仍成立；测试汇总为 `2156 passed`，仅剩 `Title check` inconclusive。
- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
- 结果：通过；PR `#290` 处于 `OPEN`，latest head commit `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181` 有 `2` 条 open thread（CodeRabbit `1`、Greptile `1`），测试汇总为 `2156 passed`，无 failed checks。
- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
- 结果：通过；PR `#292` 处于 `OPEN`，latest head commit `b96565ffa367bade30f44c2d4e8955143fbff85e` 有 `2` 条 CodeRabbit open thread，测试汇总为 `2156 passed`，无 failed tests；另有 `Title check` inconclusive，属于 PR 标题元数据问题，不是仓库文件阻塞。
- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md`
- 结果：通过；本轮 3 个模块 README 调整后链接目标仍然有效。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.Abstractions/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch.Abstractions/README.md`
- 结果：通过；4 个公开模块 README 的 reader-facing 改写后链接目标仍然有效。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started`
- 结果：通过；`installation.md` 更新后 `getting-started` 栏目的 frontmatter、链接与代码块校验均通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md`
- 结果：通过；`config-system.md` 的工具形态建议改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic`
- 结果：通过；基础教程入口的阅读路径改写后栏目校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md`
- 结果：通过；本轮 5 个模块 README 的 reader-facing 术语与入口改写后链接目标有效。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.md`
- 结果：通过；教程页受众表述改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md`
- 结果：通过；Godot UI 页的接法示例与 reader-facing 术语改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md`
- 结果：通过；Godot 场景页的接法示例与 reader-facing 术语改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md`
- 结果：通过；信号页切回站内生成器入口后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions`
- 结果：通过；3 个抽象层页改回站内入口后栏目校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators`
- 结果：通过；生成器栏目及受影响专题页改回站内入口后栏目校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md`
- 结果：通过；Core 入口页 reader-facing 改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md`
- 结果：通过；Game 入口页 reader-facing 改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
- 结果：通过；API 入口页导航改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started/quick-start.md`
- 结果：通过；快速开始页切回站内安装入口后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md`
- 结果：通过；CQRS 页继续阅读入口改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md`
- 结果：通过；Game 场景页相关推荐改回站内入口后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md`
- 结果：通过；Game UI 页相关推荐改回站内入口后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md`
- 结果：通过；ECS Arch 页入口改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`
- 结果：通过；Godot 集成教程的接线口吻改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md`
- 结果：通过；设置系统页初始化语义改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.md`
- 结果：通过；序列化页生命周期说明改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md`
- 结果：通过；Godot landing page 的采用说明改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/architecture.md`
- 结果：通过；Godot 架构页异步初始化口吻改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`
- 结果：通过；Godot 存储页示例口吻改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md`
- 结果：通过；Godot 日志页 provider 接线说明改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`
- 结果：通过；Godot 设置页 applicator 接线口吻改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md`
- 结果：通过；Godot 扩展页边界说明改写后页面校验通过。
- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/architecture.md`
- 结果：通过；Core 架构页旧初始化入口改写后页面校验通过。
- `2026-04-27` `bun run build`（工作目录：`docs/`）
- 结果：通过；本轮 README、安装页与公开文案改写后站点仍可构建，仅保留既有大 chunk warning。
- `2026-04-25` `bun run build`（工作目录：`docs/`）
- 结果：通过；移除 `api-reference` 侧栏重复项并统一 `source-generators` 标签后站点仍可正常构建，仅保留既有大 chunk warning。
- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md`
@ -160,11 +237,9 @@
## 下一步
1. 运行 `bun run test`（工作目录：`tools/gframework-config-tool/`），完成本轮 README 收口改动的最小模块验证。
2. 验证通过后重新抓取 `$gframework-pr-review`，确认 PR `#292` 的 latest-head review 是否只剩过期线程或已自动清空。
3. 若本轮提交后 branch diff vs `origin/main` 仍明显低于 `50` 文件阈值，再决定是否继续追加低风险 reader-facing 文档切片。
4. 若后续继续扩批，优先在已识别但尚未扩写的低风险 reader-facing 方向里选择下一组：config tool 更深的 adoption 示例、首页 / 安装页的进一步选包引导，或其它 repo-visible support surface 的本地说明补齐。
5. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
1. 提交当前接近阈值的稳定批次后，优先重新抓取 `$gframework-pr-review` 或在新一轮里按 `46 / 50` 的 branch diff 重新评估是否还适合继续扩批。
2. 若后续还要继续文档治理，优先复核尚未触达的 `Game` persistence、Godot runtime 细页与少量残余 `ai-libs` 口吻，而不是继续扩大同一轮 review 面。
3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
6. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
`docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。

133
ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
View File

@ -1,5 +1,138 @@
# Documentation Full Coverage Governance Trace
## 2026-04-27
### 当前恢复点：RP-044
- 本轮从 `$gframework-pr-review` 重新进入，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并通过 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` 抓取当前 PR `#296`。
- 抓取结果显示 latest reviewed commit 为 `5778782df05e22dd24dc95189dd768458afb8537`，共有 `4` 条 open thread：`GFramework.Game.SourceGenerators/README.md` 的表头仍带路径视角、`GFramework.Game/README.md` 有重复 `storage.md` 链接、`docs/zh-CN/tutorials/godot-integration.md` 与 `docs/zh-CN/godot/extensions.md` 还有 reader-facing 措辞收口空间。
- 本地逐条复核后确认这 `4` 条都仍成立，但都属于低风险文档收口；唯一 failed check `Title check` 只是 PR 标题元数据提示，不属于仓库文件内修复范围。
### 当前决策（RP-044）
- 接受 latest-head review 中仍成立的 `4` 条文档修正，不扩展到 review 未指向的其它页面，避免在当前接近 branch-size stop condition 的阶段继续增大 review 面。
- 对 README 表格和导航问题，只做 reader-facing 命名与去重；对教程与 Godot 页面，只做措辞收口，不改变现有采用路径与示例结构。
- 在同一轮里同步更新 active topic tracking / trace，并在提交前运行最小页面校验、README 链接校验与站点构建。
### 当前验证（RP-044）
- PR review 抓取：
- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json`
- 结果：通过；PR `#296` 处于 `OPEN`，latest head review 共有 `4` 条 open thread，测试汇总为 `2156 passed`，仅剩 `Title check` inconclusive。
- README 链接校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md GFramework.Game/README.md`
- 结果：通过；本轮 2 个 README 的 reader-facing 表格与导航去重调整后链接目标有效。
- 页面校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md`
- 结果：通过；两页 frontmatter、链接与代码块校验均通过。
- 站点构建：
- `bun run build`（工作目录：`docs/`）
- 结果：通过；本轮 PR `#296` review 收口后的站点仍可构建，仅保留既有大 chunk warning。
### 当前恢复点：RP-043
- 在提交 `docs(reader-facing): 统一站内入口与公开术语` 后重新计算 branch diff，确认当前工作树继续补一批新文件后已到 `46` changed files，已经接近 `$gframework-batch-boot 50` 的停止线。
- 因此本轮最后只接受 10 个还没进入 branch diff 的文件：`tutorials/godot-integration.md`、`game/setting.md`、`game/serialization.md`、`godot/index.md`、`godot/architecture.md`、`godot/storage.md`、`godot/logging.md`、`godot/setting.md`、`godot/extensions.md`、`core/architecture.md`。
- 这批文件统一收口的是同一类问题：把 `旧文档`、`ai-libs`、`.Wait()`、`family` 之类维护 / 内部口吻改成当前采用指导，不扩新结构、不重写示例体系。
### 当前决策（RP-043）
- 当前 stop condition 已接近阈值，因此这批验证通过后立即停止继续扩批，避免 branch diff 超过 `50` files 或让 review 面退化。
- 提交后本轮默认结束；后续若继续，应从 PR review 或剩余未触达的细页重新开一轮，而不是在同一轮里继续堆文件数。
### 当前验证（RP-043）
- 单页校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/architecture.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/architecture.md`
- 结果：通过；本轮 10 个新文件的 frontmatter、链接与代码块校验全部通过。
- 站点构建：
- `bun run build`（工作目录：`docs/`）
- 结果：通过；接近阈值前的最后一批文案收口后站点仍可构建，仅保留既有大 chunk warning。
### 当前恢复点：RP-042
- 用户明确要求在当前阈值内循环推进，并允许使用 subagent 降低主线程上下文压力；因此本轮在主线程保留实现与验证，把热点识别委派给 3 个 explorer。
- 接受的 subagent 结论主要有三类：
- 入口页最划算的改法是统一 reader-facing 骨架，而不是继续保留治理说明或负向 framing。
- 若站内已有栏目页与专题页，GitHub blob README 不应继续作为公开文档主导航。
- `GFramework.Game` / `Game.Abstractions` / `Godot` 等 README 仍有 `ai-libs`、`family`、`seam`、`ReadMe.md` 等对外不友好的措辞，适合在同一轮里收口。
- 基于这些结论，本轮连续落地 3 组低风险切片：入口页 reader-facing 改写、README / Godot 页去内部口吻、剩余 GitHub blob README 外链改回站内入口。
### 当前决策（RP-042）
- 继续保持 critical path 本地执行，不让 subagent 直接改文件；subagent 只负责热点排序与问题归类。
- stop condition 继续沿用 `origin/main` + `50` changed files；当前工作树相对 baseline 的 tracked diff 已到 `36` files / `500` changed lines，意味着还能再做一小批，但应先提交当前稳定批次。
- 当前批次不扩展到新栏目、新导航层或大段内容重写，只做 reader-facing 入口、术语和站内导航连通性收口。
### 当前验证（RP-042）
- README 链接校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md`
- 结果：通过；本轮 5 个 README 的 reader-facing 改写后链接目标有效。
- 教程 / Godot 页面校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md`
- 结果：通过；受影响页面的 frontmatter、链接与代码块校验通过。
- 入口与专题页校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started/quick-start.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md`
- 结果：通过；入口页和相关推荐入口改写后页面校验通过。
- 栏目级校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions`
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators`
- 结果：通过；抽象层与生成器栏目改回站内入口后栏目校验通过。
- 站点构建：
- `bun run build`（工作目录：`docs/`）
- 结果：通过；本轮 3 组 reader-facing 文档批次后站点仍可构建，仅保留既有大 chunk warning。
### 当前恢复点：RP-041
- 通过 `$gframework-batch-boot 50` 重新进入后，先按仓库规则读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` 与 active topic tracking / trace，并继续使用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`。
- 使用显式 Git 绑定确认最新 baseline 为 `origin/main` `617e0bf`（`2026-04-26 12:17:15 +08:00`），当前 committed branch diff vs baseline 为 `0` files，因此本轮继续选择低风险、reader-facing 文档切片。
- 本轮收敛出的 3 组切片分别是：`installation.md` 的选包矩阵与旧版 Godot 提示、公开 README 的 XML 阅读入口去治理化，以及 `config-system` / 基础教程入口中的维护者口吻改写。
### 当前决策（RP-041）
- 不扩展到导航结构或新专题页，只在现有入口上修正 reader-facing 采用路径与表述一致性。
- 对公开 README 中的 XML 阅读入口，统一改成“代表类型 + 阅读重点”，不再暴露覆盖计数、日期或 `已覆盖` 这类治理字段。
- stop condition 继续沿用 `origin/main` + `50` changed files；本轮工作树相对 baseline 的 tracked diff 为 `9` files / `191` changed lines，仍明显低于阈值。
### 当前验证（RP-041）
- README 链接校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.Abstractions/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch.Abstractions/README.md`
- 结果：通过；本轮 4 个 README 的 reader-facing 改写后链接目标有效。
- 入门栏目校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started`
- 结果：通过；`installation.md` 更新后 `getting-started` 栏目 frontmatter、链接与代码块校验通过。
- 配置系统页校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md`
- 结果：通过；工具形态建议改写后页面校验通过。
- 基础教程栏目校验：
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic`
- 结果：通过；入口页阅读路径改写后栏目校验通过。
- 站点构建：
- `bun run build`（工作目录：`docs/`）
- 结果：通过；本轮文档批次后站点仍可构建，仅保留既有大 chunk warning。
## 2026-04-26
### 当前恢复点：RP-040

6
docs/zh-CN/abstractions/core-abstractions.md
View File

@ -97,7 +97,7 @@ public sealed class DiagnosticsFeature
1. 先读本页，确认你是否真的只需要契约层
2. 再看 [Core 模块总览](../core/index.md) 了解默认运行时怎么组织这些契约
3. 回到模块 README：
- [Core 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
- [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
3. 再按需要回到：
- [入门指南](../getting-started/index.md)
- [Core 模块总览](../core/index.md)
4. 需要统一导航时，再看 [API 参考](../api-reference/index.md)

6
docs/zh-CN/abstractions/ecs-arch-abstractions.md
View File

@ -89,6 +89,6 @@ var options = new ArchOptions
1. 先读本页，确认你是否真的只需要契约层
2. 如果需要默认实现，再看 [Arch ECS 集成](../ecs/arch.md)
3. 回到对应模块 README：
- [ECS 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md)
- [Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
3. 需要统一入口时，再看：
- [ECS 模块总览](../ecs/index.md)
- [入门指南](../getting-started/index.md)

6
docs/zh-CN/abstractions/game-abstractions.md
View File

@ -116,6 +116,6 @@ public sealed class ContinueGameCommandHandler
- [设置系统](../game/setting.md)
- [场景系统](../game/scene.md)
- [UI 系统](../game/ui.md)
4. 需要仓库侧入口时，回到：
- [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
- [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
4. 需要统一入口时，回到：
- [Game 模块总览](../game/index.md)
- [入门指南](../getting-started/index.md)

41
docs/zh-CN/api-reference/index.md
View File

@ -5,35 +5,34 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
# API 参考
这里不再维护一份脱离源码演化的“伪 API 列表”。
这页不是签名索引，而是“先看哪个模块入口、再回哪里读 XML 文档”的导航页。
当前 `GFramework` 的 API 参考链路以四类证据协同为准：
最常见的阅读顺序是：
1. 模块 README：说明包关系、最小接入路径和目录边界
2. `docs/zh-CN` 专题页：说明采用顺序、生命周期和使用建议
3. 代码中的 XML 文档：说明公开 / 内部类型和关键成员的契约
4. 教程页：说明这些 API 在真实接入路径中的组合方式
1. 先按模块找到对应栏目入口
2. 再进专题页确认安装、生命周期和推荐接线方式
3. 最后回到源码中的 XML 文档核对具体契约
## 阅读顺序
### 想确认“该装哪个包、先看哪类 API”
先读模块 README，再读对应栏目入口页：
先读站内入口页：
- 入门入口：[入门指南](../getting-started/index.md)
- 根模块地图：[仓库总览](https://github.com/GeWuYou/GFramework/blob/main/README.md)
- 安装与选包：[安装配置](../getting-started/installation.md)
### 想确认“这个功能属于哪个模块”
按下面的模块映射进入对应入口：
| 模块族 | 模块 README | 站内入口 | XML 文档关注点 |
| 模块族 | 先看什么 | 继续深入 | XML 文档关注点 |
| --- | --- | --- | --- |
| `Core` / `Core.Abstractions` | [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)、[Core 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md) | [Core 栏目](../core/index.md)、[Core 抽象层说明](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)、[CQRS 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.Abstractions/README.md)、[CQRS 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md) | [CQRS 栏目](../core/cqrs.md)、[CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)、[Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)、[Game 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md) | [Game 模块总览](../game/index.md)、[Game 抽象层说明](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
| `Godot` / `Godot.SourceGenerators` | [Godot 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)、[Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) | [Godot 模块总览](../godot/index.md)、[Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | [Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)、[ECS 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md) | [ECS 模块总览](../ecs/index.md)、[Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
| `Core` / `Core.Abstractions` | [Core 模块](../core/index.md) | [Core 抽象层说明](../abstractions/core-abstractions.md)、[快速开始](../getting-started/quick-start.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / registry / fallback contract |
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
| `Godot` / `Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md) | [Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
| `Ecs.Arch` / `Ecs.Arch.Abstractions` | [ECS 模块总览](../ecs/index.md) | [Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
## 先看 XML，还是先看教程
@ -61,31 +60,23 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
- 最佳实践：[最佳实践](../best-practices/index.md)
- 故障排查：[故障排查](../troubleshooting.md)
## 当前边界
## 共享支撑层怎么看
- `GFramework.Core.SourceGenerators.Abstractions`
- `GFramework.Godot.SourceGenerators.Abstractions`
- `GFramework.SourceGenerators.Common`
这些目录当前不是独立消费模块，因此不单独维护站内 API 参考入口。它们的公开说明跟随所属模块 README 和
`source-generators` 栏目维护。
更准确地说：
这些目录当前不作为独立采用入口；阅读它们时，优先回到所属模块页和 `source-generators` 栏目，再根据需要下钻到具体源码目录。
- `*.SourceGenerators.Abstractions`
- 主要定义公开 attribute 和最小契约，供对应生成器与消费端项目共享。
- `GFramework.SourceGenerators.Common`
- 主要提供共享生成器基类、通用 diagnostics，以及生成方法冲突等跨模块约束。
如果你在 `Core`、`CQRS`、`Game`、`Godot` 的生成器页面里遇到相似的 diagnostics 或冲突语义，优先把它理解为共享
支撑层在复用同一套规则，而不是把这些目录当成新的安装入口。
## 使用方式
把本页当成“API 阅读导航”而不是“签名快照”：
- 先选模块
- 再进 README 和专题页确认采用路径
- 再进专题页确认采用路径
- 最后回到代码里的 XML 文档核对具体契约
当 README、专题页和 XML 文档出现冲突时，以源码和测试所反映的当前实现为准。

4
docs/zh-CN/core/architecture.md
View File

@ -61,7 +61,7 @@ await architecture.WaitUntilReadyAsync();
## 初始化时机
当前版本不再使用旧文档里的 `Init()` 入口。注册逻辑必须写在：
当前 `Architecture` 的注册逻辑必须写在：
```csharp
protected override void OnInitialize()
@ -77,7 +77,7 @@ protected override void OnInitialize()
4. 按阶段初始化 `Utility -> Model -> System`
5. 进入 `Ready`
如果你还看到旧示例里写 `protected override void Init()`，那就是过时内容。
如果项目里仍保留 `protected override void Init()` 风格的旧代码，应迁移到 `OnInitialize()`。
## 组件注册顺序

2
docs/zh-CN/core/cqrs.md
View File

@ -214,4 +214,4 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
- 上下文入口：[Context 上下文](./context.md)
- 生成器专题：[CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)
- 协程接法：[协程系统](./coroutine.md)
- 模块说明：[CQRS 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
- 选包与入口：[入门指南](../getting-started/index.md)

13
docs/zh-CN/core/index.md
View File

@ -8,7 +8,7 @@ description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口
`Core` 栏目对应 `GFramework` 的基础运行时层，主要覆盖 `GFramework.Core` 与 `GFramework.Core.Abstractions`，以及与之直接相邻的旧版
`Command` / `Query` 执行器和新版 `CQRS` 迁移入口。
如果你第一次接入框架，建议先把这里当作“运行时底座说明”，再按需进入 `Game`、`Godot` 或 Source Generators 栏目。
如果你第一次接入框架，可以先把这里当作“运行时底座说明”：先确认 `Core` 解决什么问题、最小安装组合是什么，再决定什么时候转向 `CQRS`、`Game`、`Godot` 或源码生成器。
## 模块与包关系
@ -32,7 +32,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions
## 栏目覆盖范围
`Core` 栏目不是旧版“完整框架教程”的镜像，而是当前实现的入口导航。这里的页面按能力域组织：
这里的页面按能力域组织，适合按“我要接什么能力”而不是“我要读完所有目录”的方式进入：
- 架构与生命周期
- [架构](./architecture.md)
@ -71,7 +71,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions
如果你已经知道模块归属，但想确认公开类型的契约边界，建议按下面顺序阅读：
1. 先看[Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)，确认包关系和目录边界
1. 先读本页与 [Core 抽象层说明](../abstractions/core-abstractions.md)，确认运行时和契约层边界
2. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式
3. 最后回到源码中的 XML 文档，重点核对这些类型族：
- `Architecture` / `IArchitectureContext`
@ -148,7 +148,8 @@ public sealed class CounterArchitecture : Architecture
## 对应模块入口
- [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
- [Core 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
- [入门指南](../getting-started/index.md)
- [Core 抽象层说明](../abstractions/core-abstractions.md)
- [CQRS 运行时](./cqrs.md)
- [源码生成器总览](../source-generators/index.md)
- [API 参考入口](../api-reference/index.md)
- [仓库总览](https://github.com/GeWuYou/GFramework/blob/main/README.md)

2
docs/zh-CN/ecs/arch.md
View File

@ -140,5 +140,5 @@ ecsModule.Update(deltaTime);
- ECS 模块总览：[ECS 模块总览](./index.md)
- 抽象契约页：[ECS 抽象层说明](../abstractions/ecs-arch-abstractions.md)
- 仓库模块说明：[Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
- 选包与接入顺序：[入门指南](../getting-started/index.md)
- 统一 API / XML 导航：[API 参考](../api-reference/index.md)

4
docs/zh-CN/game/config-system.md
View File

@ -1021,11 +1021,11 @@ var hotReload = loader.EnableHotReload(
## 工具形态建议
当前优先采用 `VS Code Extension` 形态即可覆盖仓库中已落地的主要工作流，包括 schema 校验、轻量表单、批量编辑和 raw YAML 回退。
对当前仓库已经落地的工作流而言，`VS Code Extension` 形态已经可以覆盖 schema 校验、轻量表单、批量编辑和 raw YAML 回退这条采用路径。
如果你的团队出现以下需求，再评估独立 `Config Studio` 会更合适：
- 主要使用者变成非开发人员，且 VS Code 的安装与使用成本持续阻碍日常维护
- 配置维护主要由非开发角色承担，希望进一步降低 VS Code 的安装和使用门槛
- 需要更重的表格视图、跨表可视化关系编辑、复杂审批流或离线发布流程
- 插件形态已经明显受限于 VS Code Webview / Extension API，而不是 schema 与工作流本身
- 已经沉淀出稳定的 schema 元数据约定，足以支撑单独工具的长期维护

24
docs/zh-CN/game/index.md
View File

@ -25,7 +25,7 @@ description: GFramework.Game family 的运行时入口、采用顺序与源码
## 栏目覆盖范围
`Game` 栏目聚焦“游戏项目该怎么接这些运行时能力”，不再保留与当前实现脱节的泛化模块示例。
`Game` 栏目聚焦“游戏项目该怎么把这些运行时能力接起来”，适合先按目标判断你要接入的是配置、设置与存档、Scene / UI 路由，还是文件存储与序列化。
当前栏目主要入口：
@ -115,20 +115,16 @@ IStorage storage = new FileStorage("GameData", serializer);
| `GFramework.Game.Abstractions` | `IConfigRegistry`、`ISaveRepository<TSaveData>`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 契约层边界，以及项目中哪些程序集只应依赖接口 |
| `GFramework.Game.SourceGenerators` | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | schema 生成入口与诊断模型，确认配置系统的编译期链路 |
## 与真实接法的关系
## 运行时与生成器如何配合
本栏目内容以源码、`*.csproj`、模块说明页与 `ai-libs/` 下已验证的参考接法为准。
例如当前文档应优先和以下已验证事实保持一致：
- 配置系统采用 `YAML + JSON Schema + Source Generator`
- 设置持久化通常通过 `UnifiedSettingsDataRepository`
- 场景与 UI 路由依赖项目自己的 factory / root，而不是框架替你绑定引擎对象
如果某个旧页面与这些事实冲突，应以源码和模块说明页为准，并在同一轮里修正文档。
- 运行时入口主要来自 `GFramework.Game`
- 只依赖接口或拆分业务层时，补充 `GFramework.Game.Abstractions`
- 需要静态内容配置类型和表包装生成时，再追加 `GFramework.Game.SourceGenerators`
- 需要编辑器侧内容维护工作流时，再看 [VS Code 配置工具](./config-tool.md)
## 对应模块入口
- [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
- [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
- [仓库总览](https://github.com/GeWuYou/GFramework/blob/main/README.md)
- [入门指南](../getting-started/index.md)
- [Game 抽象层说明](../abstractions/game-abstractions.md)
- [源码生成器总览](../source-generators/index.md)
- [API 参考入口](../api-reference/index.md)

4
docs/zh-CN/game/scene.md
View File

@ -258,5 +258,5 @@ await sceneRouter.PopAsync();
1. [Game 模块总览](./index.md)
2. [UI 系统](./ui.md)
3. [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
4. [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
3. [Game 抽象层说明](../abstractions/game-abstractions.md)
4. [API 参考](../api-reference/index.md)

2
docs/zh-CN/game/serialization.md
View File

@ -46,7 +46,7 @@ IRuntimeTypeSerializer runtimeSerializer = new JsonSerializer();
## 配置生命周期
这部分是当前实现最容易被旧文档说错的地方。
这里最需要先确认的是序列化器的配置生命周期。
`JsonSerializer` 不会复制你传入的 `JsonSerializerSettings`。它会直接持有并复用这份实例，以及里面的 `Converters` 集合。

4
docs/zh-CN/game/setting.md
View File

@ -16,7 +16,7 @@ description: 以当前 SettingsModel、SettingsSystem 与相关测试为准，
- `SettingsModel<TRepository>`
- `SettingsSystem`
而不是旧文档里那种“只靠若干 `Get<T>() / Register(...)` 辅助方法就能自动完成一切”的模型。
而不是只靠若干 `Get<T>() / Register(...)` 辅助方法就能自动完成一切的模型。
## 当前公开入口
@ -91,7 +91,7 @@ applicator 的职责不是保存数据，而是把设置结果作用到实际运
## 初始化与迁移的真实语义
`SettingsModel<TRepository>.InitializeAsync()` 的当前行为，比旧文档里“加载一下就好”更严格一些：
`SettingsModel<TRepository>.InitializeAsync()` 会按更完整的初始化与迁移顺序工作：
- 它会先调用 `ISettingsDataRepository.LoadAllAsync()`
- 再逐个匹配当前模型里已经登记的设置类型

4
docs/zh-CN/game/ui.md
View File

@ -329,5 +329,5 @@ uiRouter.Hide(modalHandle, UiLayer.Modal);
1. [Game 模块总览](./index.md)
2. [场景系统](./scene.md)
3. [AutoUiPage 生成器](../source-generators/auto-ui-page-generator.md)
4. [Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
5. [Game 抽象层说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
4. [Game 抽象层说明](../abstractions/game-abstractions.md)
5. [API 参考](../api-reference/index.md)

50
docs/zh-CN/getting-started/index.md
View File

@ -5,17 +5,19 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
# 入门指南
这一部分只回答三个问题：
如果你第一次接触 `GFramework`，或者还在判断“应该先装哪些包、先看哪一组文档”，先从这里开始最省时间。
1. `GFramework` 由哪些模块组成
2. 第一次接入应该从哪个包开始
3. 最小可运行路径是什么
这组页面的目标只有一个：帮你用最短路径找到适合当前项目的运行时入口、安装组合和下一步阅读顺序。
如果你还没决定具体用法，先阅读本栏目；如果你已经明确要用某个模块，直接进入对应模块的说明页会更快。
## 适合谁先读本栏
## 推荐起步路径
- 第一次接入 `GFramework`，还没决定该从 `Core`、`Game`、`Godot` 还是 `CQRS` 开始
- 想先确认最小安装组合，再决定是否追加源码生成器
- 想先跑通一个可运行骨架，再深入某个专题页
### 只想先把架构跑起来
## 按目标选择起步路线
### 基础运行时起步
从 `Core` 开始：
@ -33,8 +35,9 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
- [Core 模块总览](../core/index.md)
- [快速开始](./quick-start.md)
- [安装配置](./installation.md)
### 想用新版 CQRS
### 新版 CQRS 请求流
在 `Core` 基础上补：
@ -51,9 +54,9 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
对应文档：
- [CQRS 运行时](../core/cqrs.md)
- 模块说明：[CQRS 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
- [安装配置](./installation.md)
### 想做游戏运行时
### 游戏运行时与内容配置
在 `Core` 基础上按需补：
@ -70,9 +73,10 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
对应文档：
- [Game 模块总览](../game/index.md)
- 模块说明：[Game 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
- [配置系统](../game/config-system.md)
- [安装配置](./installation.md)
### 想接入 Godot
### Godot 项目接入
继续叠加：
@ -81,9 +85,10 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
对应文档：
- [Godot 模块总览](../godot/index.md)
- 模块说明：[Godot 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)
- [Godot 集成教程](../tutorials/godot-integration.md)
- [安装配置](./installation.md)
## Source Generators 什么时候装
## 什么时候追加源码生成器
只在需要编译期生成代码时再装：
@ -99,14 +104,15 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
- 为 CQRS handlers 生成注册表
- 生成 Godot 节点、场景和 UI 包装代码
继续阅读：
- [源码生成器总览](../source-generators/index.md)
- [配置系统](../game/config-system.md)
- [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)
## 建议阅读顺序
1. [快速开始](./quick-start.md)
2. 你准备使用的模块说明页
3. 对应栏目页，例如 `core`、`game`、`godot`
4. 需要更完整示例时，再进入 `tutorials/`
## 注意
- 旧文档里有一些早期示例已经和当前 API 漂移。本栏目以后只保留经过代码或测试核对的最小路径。
- 若根 README、模块 README 与某篇专题页冲突，以模块 README 和当前代码为准。
2. [安装配置](./installation.md)
3. 按你的目标进入 [基础运行时](../core/index.md)、[游戏运行时](../game/index.md)、[Godot 集成](../godot/index.md) 或 [源码生成器](../source-generators/index.md)
4. 需要完整示例时，再进入 [教程总览](../tutorials/index.md)

55
docs/zh-CN/getting-started/installation.md
View File

@ -5,24 +5,28 @@ description: 说明 GFramework 各运行时与 source generator 包的安装选
# 安装配置
GFramework 提供多种安装方式，您可以根据项目需求选择合适的包进行安装。
GFramework 采用按模块拆分的安装路径。先确认你要接入的是哪一层运行时、抽象层或源码生成器，再决定安装组合，会比直接把所有包一次性带进来更稳妥。
## 包选择说明
GFramework 采用模块化设计，不同包提供不同的功能：
| 包名 | 说明 | 适用场景 |
|---------------------------------------------|--------------|--------------------------------|
| `GeWuYou.GFramework` | 聚合元包 | 快速试用、原型开发 |
| `GeWuYou.GFramework.Core` | 核心框架 | 生产项目推荐 |
| `GeWuYou.GFramework.Cqrs` | CQRS runtime | 命令/查询/通知分发与处理器注册 |
| `GeWuYou.GFramework.Cqrs.Abstractions` | CQRS 抽象契约 | CQRS 契约、handler 接口与共享抽象 |
| `GeWuYou.GFramework.Game` | 游戏模块 | 需要游戏特定功能 |
| `GeWuYou.GFramework.Godot` | Godot集成 | Godot项目必需 |
| `GeWuYou.GFramework.Core.SourceGenerators` | Core 源码生成器 | `[Log]`、`[ContextAware]`、架构注入等 |
| `GeWuYou.GFramework.Game.SourceGenerators` | Game 源码生成器 | 配置 schema / 配表生成 |
| `GeWuYou.GFramework.Godot.SourceGenerators` | Godot 源码生成器 | Godot 节点、UI、项目元数据生成 |
| `GeWuYou.GFramework.Cqrs.SourceGenerators` | CQRS 源码生成器 | 处理器注册表生成 |
| 包名 | 说明 | 适用场景 |
| --- | --- | --- |
| `GeWuYou.GFramework` | 聚合元包 | 快速试用、原型开发，或先起一个最小运行时骨架 |
| `GeWuYou.GFramework.Core` | Core 运行时 | 生产项目推荐的最小运行时起点 |
| `GeWuYou.GFramework.Core.Abstractions` | Core 抽象契约 | 面向接口开发、测试替身、插件化拆分 |
| `GeWuYou.GFramework.Cqrs` | CQRS runtime | 命令 / 查询 / 通知分发与处理器注册 |
| `GeWuYou.GFramework.Cqrs.Abstractions` | CQRS 抽象契约 | 共享 request、handler 与 pipeline 契约 |
| `GeWuYou.GFramework.Game` | Game 运行时 | 配置、存储、设置、Scene、UI 等游戏层能力 |
| `GeWuYou.GFramework.Game.Abstractions` | Game 抽象契约 | 共享 `IConfigRegistry`、`ISceneRouter`、`IUiRouter` 等接口 |
| `GeWuYou.GFramework.Godot` | Godot 集成 | Godot 项目的运行时接线、节点扩展与宿主适配 |
| `GeWuYou.GFramework.Ecs.Arch` | Arch ECS 运行时 | 需要 `UseArch(...)`、默认 `World` 注册与系统桥接 |
| `GeWuYou.GFramework.Ecs.Arch.Abstractions` | Arch ECS 抽象契约 | 只共享 ECS 模块接口、配置对象与宿主循环边界 |
| `GeWuYou.GFramework.Core.SourceGenerators` | Core 源码生成器 | `[Log]`、`[ContextAware]`、架构注入等 |
| `GeWuYou.GFramework.Game.SourceGenerators` | Game 源码生成器 | 配置 schema、配置类型、表包装与注册辅助生成 |
| `GeWuYou.GFramework.Godot.SourceGenerators` | Godot 源码生成器 | Godot 节点、UI、项目元数据生成 |
| `GeWuYou.GFramework.Cqrs.SourceGenerators` | CQRS 源码生成器 | 处理器注册表生成 |
当前 NuGet 发布按模块拆分 source generator 包，不存在 `GeWuYou.GFramework.SourceGenerators` 聚合包。
@ -33,6 +37,16 @@ GFramework 采用模块化设计，不同包提供不同的功能：
它不会自动带上 `Cqrs`、`Godot` 或任何 `*.SourceGenerators` 包。如果你需要这些能力，请按模块单独安装。
## 推荐组合
- 最小运行时：`GeWuYou.GFramework.Core` + `GeWuYou.GFramework.Core.Abstractions`
- 新版 CQRS：在 Core 基础上追加 `GeWuYou.GFramework.Cqrs` + `GeWuYou.GFramework.Cqrs.Abstractions`
- Game 配置工作流：在 Core 基础上追加 `GeWuYou.GFramework.Game` + `GeWuYou.GFramework.Game.Abstractions` + `GeWuYou.GFramework.Game.SourceGenerators`
- Godot 项目：在所需运行时基础上追加 `GeWuYou.GFramework.Godot`，需要生成器辅助时再加 `GeWuYou.GFramework.Godot.SourceGenerators`
- Arch ECS：直接安装 `GeWuYou.GFramework.Ecs.Arch`；如果只想共享宿主循环或接口边界，可改为 `GeWuYou.GFramework.Ecs.Arch.Abstractions`
如果你准备采用 AI-First 配置工作流，可以继续阅读 [游戏内容配置系统](../game/config-system.md) 与 [VS Code 配置工具](../game/config-tool.md)。
## 安装方式
### 1. 使用 .NET CLI（推荐）
@ -50,6 +64,10 @@ dotnet add package GeWuYou.GFramework.Cqrs.Abstractions
dotnet add package GeWuYou.GFramework.Game
dotnet add package GeWuYou.GFramework.Game.Abstractions
# Arch ECS
dotnet add package GeWuYou.GFramework.Ecs.Arch
dotnet add package GeWuYou.GFramework.Ecs.Arch.Abstractions
# Godot 集成（仅 Godot 项目需要）
dotnet add package GeWuYou.GFramework.Godot
@ -88,6 +106,10 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
<!-- 游戏模块 -->
<PackageReference Include="GeWuYou.GFramework.Game" Version="1.0.0" />
<PackageReference Include="GeWuYou.GFramework.Game.Abstractions" Version="1.0.0" />
<!-- Arch ECS -->
<PackageReference Include="GeWuYou.GFramework.Ecs.Arch" Version="1.0.0" />
<PackageReference Include="GeWuYou.GFramework.Ecs.Arch.Abstractions" Version="1.0.0" />
<!-- Godot 集成 -->
<PackageReference Include="GeWuYou.GFramework.Godot" Version="1.0.0" />
@ -143,10 +165,9 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
如果你想排除局部导入，可以继续在项目文件中添加排除项：
```xml
<ItemGroup>
<GFrameworkExcludedUsing Include="GFramework.Core.Environment"/>
<GFrameworkExcludedUsing Include="GFramework.Godot.Extensions"/>
<GFrameworkExcludedUsing Include="GFramework.Core.Environment" />
<GFrameworkExcludedUsing Include="GFramework.Godot.Extensions" />
</ItemGroup>
```
@ -223,7 +244,7 @@ dotnet build
确保：
- Godot 版本 >= 4.5
- 项目环境与当前文档保持在 Godot 4.6.2 基线
- 已正确安装 Godot C# 模板
- 项目引用了正确的 Godot 包

2
docs/zh-CN/getting-started/quick-start.md
View File

@ -107,4 +107,4 @@ Console.WriteLine(count); // 1
- 新功能的请求 / 通知处理：看 [CQRS 运行时](../core/cqrs.md)
- 游戏层能力与接入顺序：看 [Game 模块总览](../game/index.md)
- 包目录与最小安装组合：看 [Core 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
- 包目录与最小安装组合：看 [安装配置](./installation.md)

9
docs/zh-CN/godot/architecture.md
View File

@ -1,6 +1,6 @@
---
title: Godot 架构集成
description: 说明 AbstractArchitecture、ArchitectureAnchor 和 Godot 模块挂接的当前生命周期语义，避免继续沿用旧版 `.Wait()` 接法。
description: 说明 AbstractArchitecture、ArchitectureAnchor 和 Godot 模块挂接的当前生命周期语义，以及推荐的初始化路径。
---
# Godot 架构集成
@ -33,7 +33,7 @@ Godot 场景树销毁”，而不是改变注册方式。
### 常规模块仍然用 `InstallModule(...)`
当前消费者 `ai-libs/CoreGrid` 的默认做法，是保持普通模块注册方式：
当前更稳的默认做法，是保持普通模块注册方式：
```csharp
using GFramework.Core.Abstractions.Architectures;
@ -95,8 +95,7 @@ public sealed class HudModule : AbstractGodotModule
```
这类模块的关键点不是“注册更多框架能力”，而是“让模块节点跟着架构锚点进出场景树”。
真正调用 `InstallGodotModule(...)` 时，也应该把它放在能够接受异步挂接流程的初始化路径里，而不是继续沿用旧文档里的
`.Wait()` 叙述。
真正调用 `InstallGodotModule(...)` 时，也应该把它放在能够接受异步挂接流程的初始化路径里。
## 当前生命周期
@ -148,7 +147,7 @@ public sealed class HudModule : AbstractGodotModule
- 当锚点尚未初始化时，`InstallGodotModule(...)` 会直接抛 `InvalidOperationException("Anchor not initialized")`
- 失败发生在 `module.Install(...)` 之前，因此不会留下半安装副作用
这也是为什么文档不应该再把 `InstallGodotModule(...).Wait()` 写成一种随处可用的默认初始化方式。
这也是为什么 `InstallGodotModule(...)` 更适合放在异步初始化路径里，而不是同步阻塞地等待挂接结果。
### `AbstractGodotModule` 只是便捷基类，不代表自动阶段广播

4
docs/zh-CN/godot/extensions.md
View File

@ -12,7 +12,7 @@ description: 以当前 GFramework.Godot.Extensions 源码为准，说明路径
- `SignalFluentExtensions`
- `UnRegisterExtension`
这页的重点应该是识别这些扩展各自解决什么问题，以及哪些旧文档里的“大而全能力”现在并不存在。
按源码看，这些扩展各自解决的问题并不相同，也需要区分哪些能力属于单一运行时辅助，而不是统一入口。
## 当前公开入口
@ -166,7 +166,7 @@ public override void _Ready()
## 当前边界
- 当前 `NodeExtensions` 没有 `GetNodeX()`、`CreateSignalBuilder()` 之类旧文档里提过的 API
- 当前 `NodeExtensions` 不提供 `GetNodeX()`、`CreateSignalBuilder()` 这类额外包装 API
- 它不是 router、scene factory、UI factory 或生成器的替代层
- `GetOrCreateNode<T>()` 只会创建一个直接子节点，不会递归补整条路径
- `SafeCallDeferred(...)` 只有在 `IsValidNode()` 为 `true` 时才会调用；节点未入树时不会执行

4
docs/zh-CN/godot/index.md
View File

@ -60,7 +60,7 @@ dotnet add package GeWuYou.GFramework.Godot.SourceGenerators
### 2. 让架构继续负责注册，让 Godot 节点负责场景接线
`ai-libs/CoreGrid` 当前的真实做法，是让架构继承 `AbstractArchitecture`，但模块注册依然使用普通的
当前更稳的接法，是让架构继承 `AbstractArchitecture`，但模块注册依然使用普通的
`InstallModule(...)`：
```csharp
@ -150,7 +150,7 @@ public partial class SettingsPanel : Control
- `AbstractArchitecture` 会在 `SceneTree.Root` 下创建 `ArchitectureAnchor`，并在锚点退出场景树时触发架构销毁观察流程
- `InstallGodotModule(...)` 会先检查锚点是否存在；测试覆盖了“锚点缺失时直接抛 `InvalidOperationException`，且不会执行
`module.Install(...)`”这一路径
- `Signal(...)` 是当前 fluent API 入口，不是旧文档里的 `CreateSignalBuilder(...)`
- `Signal(...)` 是当前的 fluent API 入口
- `NodeExtensions` 目前保留的是 `FindChildX<T>()`、`GetParentX<T>()`、`GetOrCreateNode<T>()`、`QueueFreeX()`、
`FreeX()`、`WaitUntilReadyAsync()` 这一类运行时辅助；不要再把它描述成一个“默认覆盖所有 Godot 节点操作”的大而全层
- Scene / UI 工厂依赖显式 registry 与 `PackedScene` 资源，不存在“运行时自动扫描所有场景并完成统一注册”的当前契约

4
docs/zh-CN/godot/logging.md
View File

@ -67,8 +67,8 @@ public sealed class GodotLoggerFactoryProvider : ILoggerFactoryProvider
### 1. 在 `ArchitectureConfiguration` 中挂上 Godot provider
当前仓库里更稳的接法，不是到处直接改全局 `LoggerFactoryResolver.Provider`，而是在架构配置里显式提供
`LoggerProperties.LoggerFactoryProvider`。`ai-libs/CoreGrid/global/GameEntryPoint.cs` 现在就是这样接的。
当前更稳的接法，不是到处直接改全局 `LoggerFactoryResolver.Provider`，而是在架构配置里显式提供
`LoggerProperties.LoggerFactoryProvider`。
```csharp
using GFramework.Core.Abstractions.Environment;

19
docs/zh-CN/godot/scene.md
View File

@ -1,11 +1,11 @@
---
title: Godot 场景系统
description: 以当前 GFramework.Godot 源码、Game 场景契约与 CoreGrid 接线为准，说明 PackedScene 场景工厂、行为包装和最小接入路径。
description: 说明 GFramework.Godot 当前如何把 Game 场景契约接到 PackedScene、行为包装和最小接入路径上。
---
# Godot 场景系统
`GFramework.Godot` 在场景这一层负责的是 Godot runtime 适配，而不是再提供一个 Godot 专属 router。
`GFramework.Godot` 在场景这一层负责的是 Godot runtime 适配，而不是再提供一套 Godot 专用路由器类型。
当前真正参与场景接线的核心类型是：
@ -14,7 +14,7 @@ description: 以当前 GFramework.Godot 源码、Game 场景契约与 CoreGrid
- `SceneBehaviorFactory`
- `SceneBehaviorBase<T>` 及其 `Node2D` / `Node3D` / `Control` / `Generic` 实现
- 项目侧实现的 `ISceneRoot`
- 项目侧继承 `SceneRouterBase` 的 router
- 项目侧继承 `SceneRouterBase` 的路由器
也就是说，Godot 集成页的重点不是“再造一套场景导航 API”，而是把 `PackedScene`、`Node` 和 `GFramework.Game` 的
`ISceneRouter` / `ISceneBehavior` 契约接起来。
@ -39,7 +39,7 @@ Godot 侧的场景资源表，底层是 `IAssetRegistry<PackedScene>`。它只
3. 如果节点实现了 `ISceneBehaviorProvider`，优先返回 `provider.GetScene()`
4. 否则回退到 `SceneBehaviorFactory.Create(node, sceneKey)`
这和旧文档里“必须有 Godot 专属 router / 专属 scene provider 才能工作”的说法不同。当前源码允许两条路径：
当前源码允许两条路径：
- 显式 provider：项目自己决定行为对象
- 自动包装：按节点类型回退到默认 behavior
@ -67,24 +67,23 @@ process 开关和 `QueueFreeX()` 释放。
- `Control` -> `ControlSceneBehavior`
- 其他 `Node` -> `GenericSceneBehavior`
这意味着 Godot runtime 确实能“自动给节点补一个 behavior”，但它不会替你补项目侧 router、root 或 registry。
这意味着 Godot runtime 确实能“自动给节点补一个 behavior”，但它不会替你补项目侧路由器、root 或 registry。
## 最小接入路径
推荐按下面顺序接入。
### 1. 继续在项目层保留自己的 router
### 1. 继续在项目层保留自己的路由器
`GFramework.Godot` 当前没有 `GodotSceneRouter` 类型。消费者项目的实际做法，是在项目层继承
`GFramework.Game.Scene.SceneRouterBase`。
`ai-libs/CoreGrid` 的 router 就是这样：
最小形态通常就是：
```csharp
using global::CoreGrid.global;
using LoggingTransitionHandler = GFramework.Game.Scene.Handler.LoggingTransitionHandler;
namespace CoreGrid.scripts.core.scene;
namespace GameProject.Scene;
public partial class SceneRouter : SceneRouterBase
{
@ -102,7 +101,7 @@ public partial class SceneRouter : SceneRouterBase
}
```
这里可以看到，Godot 适配点在 factory / registry / root / transition handler 上，而 router 仍然是项目类。
这里可以看到，Godot 适配点在 factory / registry / root / transition handler 上，而路由器仍然是项目类。
### 2. 注册 `IGodotSceneRegistry` 与 `ISceneFactory`

5
docs/zh-CN/godot/setting.md
View File

@ -72,8 +72,7 @@ description: 以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准
## 最小接入路径
当前消费者 `ai-libs/CoreGrid` 的接法，是先注册 `SettingsModel<ISettingsDataRepository>`，再把 Godot applicator
挂进去：
当前更常见的接法，是先注册 `SettingsModel<ISettingsDataRepository>`，再把 Godot applicator 挂进去：
```csharp
using GFramework.Game.Abstractions.Data;
@ -101,7 +100,7 @@ architecture.RegisterModel(
- 设置数据和生命周期由 `SettingsModel` 管
- `GodotAudioSettings` / `GodotGraphicsSettings` / `GodotLocalizationSettings` 只是 applicator
- 保存、加载和迁移仍然走 `ISettingsDataRepository`、`SettingsModel.InitializeAsync()`、`SaveAllAsync()` 等 `Game`
family 入口
模块入口
## 运行时使用方式

2
docs/zh-CN/godot/signal.md
View File

@ -104,7 +104,7 @@ slider.Signal(Range.SignalName.ValueChanged)
### 4. 静态场景绑定优先交给 `[BindNodeSignal]`
从 [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) 和 `ai-libs/CoreGrid` 的当前接法看，静态场景按钮、滑条、菜单项这类固定
从 [源码生成器总览](../source-generators/index.md) 和当前 Godot 接线方式看，静态场景按钮、滑条、菜单项这类固定
节点，更常见的路径仍然是 `[BindNodeSignal]`：
```csharp

2
docs/zh-CN/godot/storage.md
View File

@ -60,7 +60,7 @@ description: 以当前 GFramework.Godot 源码与 CoreGrid 接线为准，说明
## 最小接入路径
当前消费者 `ai-libs/CoreGrid` 的接法是先注册同一个序列化器和存储实例，再让设置仓库、存档仓库等上层组件复用它：
当前更常见的接法，是先注册同一个序列化器和存储实例，再让设置仓库、存档仓库等上层组件复用它：
```csharp
using GFramework.Core.Abstractions.Serializer;

14
docs/zh-CN/godot/ui.md
View File

@ -1,12 +1,12 @@
---
title: Godot UI 系统
description: 以当前 GFramework.Godot 源码、Game UI 契约与 CoreGrid 接线为准，说明 PackedScene UI 工厂、页面行为和层级接入路径。
description: 说明 GFramework.Godot 当前如何把 Game UI 契约接到 PackedScene、页面行为和层级 UI 接入路径上。
---
# Godot UI 系统
`GFramework.Godot.UI` 当前负责的是把 `GFramework.Game` 的 UI 路由契约接到 `Control` / `CanvasLayer` /
`PackedScene` 上，而不是定义一个 Godot 专属 router。
`PackedScene` 上，而不是再提供一套 Godot 专用路由器类型。
当前真正参与这条链路的核心类型是：
@ -16,7 +16,7 @@ description: 以当前 GFramework.Godot 源码、Game UI 契约与 CoreGrid 接
- `UiPageBehaviorFactory`
- `Page` / `Overlay` / `Modal` / `Toast` / `Topmost` 五类 layer behavior
- 项目侧实现的 `IUiRoot`
- 项目侧继承 `UiRouterBase` 的 router
- 项目侧继承 `UiRouterBase` 的路由器
## 当前公开入口
@ -83,16 +83,16 @@ Godot runtime 的页面行为包装基类。它把 `IUiPageBehavior` 的这些
## 最小接入路径
### 1. 继续在项目层保留自己的 router
### 1. 继续在项目层保留自己的路由器
仓库当前不存在 `GodotUiRouter` 类型。实际做法仍然是项目侧继承 `GFramework.Game.UI.UiRouterBase`。
`ai-libs/CoreGrid` 的 `UiRouter` 目前就是：
最小形态通常就是：
```csharp
using LoggingTransitionHandler = GFramework.Game.UI.Handler.LoggingTransitionHandler;
namespace CoreGrid.scripts.core.ui;
namespace GameProject.UI;
[Log]
public partial class UiRouter : UiRouterBase
@ -105,7 +105,7 @@ public partial class UiRouter : UiRouterBase
}
```
Godot runtime 自身并不接管这层 router 的定义。
Godot runtime 自身并不接管这层路由器定义。
### 2. 注册 `IGodotUiRegistry` 与 `IUiFactory`

2
docs/zh-CN/source-generators/auto-register-exported-collections-generator.md
View File

@ -220,4 +220,4 @@ public List<IntConfig>? Values { get; } = new();
1. [源码生成器总览](./index.md)
2. [配置系统](../game/config-system.md)
3. [Godot 项目生成器](./godot-project-generator.md)
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
4. [Godot 模块总览](../godot/index.md)

2
docs/zh-CN/source-generators/bind-node-signal-generator.md
View File

@ -189,4 +189,4 @@ private void OnAnyButtonPressed()
1. [GetNode 生成器](./get-node-generator.md)
2. [Godot 项目生成器](./godot-project-generator.md)
3. [Godot UI 系统](../godot/ui.md)
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
4. [Godot 模块总览](../godot/index.md)

2
docs/zh-CN/source-generators/context-aware-generator.md
View File

@ -195,4 +195,4 @@ finally
1. [ContextGet 生成器](./context-get-generator.md)
2. [日志生成器](./logging-generator.md)
3. [Core 模块总览](../core/index.md)
4. [Core 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
4. [源码生成器总览](./index.md)

2
docs/zh-CN/source-generators/get-node-generator.md
View File

@ -215,4 +215,4 @@ public override void _Ready()
1. [BindNodeSignal 生成器](./bind-node-signal-generator.md)
2. [Godot 项目生成器](./godot-project-generator.md)
3. [Godot UI 系统](../godot/ui.md)
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
4. [Godot 模块总览](../godot/index.md)

2
docs/zh-CN/source-generators/godot-project-generator.md
View File

@ -217,4 +217,4 @@ AutoLoad 名称也遵循同样的冲突处理策略。
1. [GetNode 生成器](./get-node-generator.md)
2. [BindNodeSignal 生成器](./bind-node-signal-generator.md)
3. [Godot 集成教程](../tutorials/godot-integration.md)
4. [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
4. [Godot 模块总览](../godot/index.md)

60
docs/zh-CN/source-generators/index.md
View File

@ -7,7 +7,7 @@ description: 按模块梳理 GFramework 当前发布的源码生成器包、运
`Source Generators` 栏目对应 `GFramework` 当前按模块拆分发布的编译期工具链。
这里的重点不是“存在一个统一的大生成器包”，而是帮助你确认应该安装哪个生成器包、它服务哪个运行时模块，以及继续去看哪一类专题页。
如果你当前最关心的是“我该装哪个生成器包、它服务哪个运行时、接下来该去哪看示例或专题页”，先看这一页。
## 当前包拆分
@ -20,33 +20,14 @@ GFramework 当前发布的生成器包是：
不存在 `GeWuYou.GFramework.SourceGenerators` 或 `*.SourceGenerators.Attributes` 这类聚合包。
## 共享支撑模块
除了上面的可直接安装包，仓库里还有三类跟随这些生成器共同演化的支撑目录：
- `GFramework.SourceGenerators.Common`
- 承载跨生成器共享的基类、通用 diagnostics 和生成冲突规则。
- `GFramework.Core.SourceGenerators.Abstractions`
- 承载 `Core` 侧生成器特性定义，例如 `[Log]`、`[ContextAware]`、`[GetModel]`、`[GenerateEnumExtensions]`。
- `GFramework.Godot.SourceGenerators.Abstractions`
- 承载 Godot 侧生成器特性定义，例如 `[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]`。
这些目录当前不是新的安装入口。对读者更重要的是先判断：
- 应该安装哪个 `*.SourceGenerators` 包
- 当前看到的 attribute 和 diagnostics 属于哪条生成链
- 继续阅读时应该回到哪个运行时或专题页
## 先按场景选包
- 想减少日志、上下文注入、模块自动注册等 Core 侧样板代码：
- 选择 `GeWuYou.GFramework.Core.SourceGenerators`
- 想把 `schemas/**/*.schema.json` 生成成配置类型和表包装：
- 选择 `GeWuYou.GFramework.Game.SourceGenerators`
- 想让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围：
- 选择 `GeWuYou.GFramework.Cqrs.SourceGenerators`
- 想在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助：
- 选择 `GeWuYou.GFramework.Godot.SourceGenerators`
| 使用场景 | 安装包 | 继续阅读 |
| --- | --- | --- |
| 减少日志、上下文注入、模块自动注册等 Core 侧样板代码 | `GeWuYou.GFramework.Core.SourceGenerators` | [Core 模块](../core/index.md)、[日志生成器](./logging-generator.md)、[ContextAware 生成器](./context-aware-generator.md) |
| 把 `schemas/**/*.schema.json` 生成成配置类型和表包装 | `GeWuYou.GFramework.Game.SourceGenerators` | [配置系统](../game/config-system.md)、[VS Code 配置工具](../game/config-tool.md) |
| 让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围 | `GeWuYou.GFramework.Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md)、[CQRS Handler Registry 生成器](./cqrs-handler-registry-generator.md) |
| 在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助 | `GeWuYou.GFramework.Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md)、[Godot 项目生成器](./godot-project-generator.md)、[GetNode 生成器](./get-node-generator.md) |
## 与运行时的关系
@ -72,11 +53,22 @@ GFramework 当前发布的生成器包是：
其他生成器包的安装模式相同。
`GFramework.SourceGenerators.Common` 和两个 `*.SourceGenerators.Abstractions` 目录当前都跟随对应生成器模块维护：
## 共享支撑模块
- 不是额外安装的独立包选择题
- 主要用于承载 attribute、共享基类和跨生成器共用 diagnostics
- 读者只需要在排查 attribute 语义、冲突规则或生成失败原因时回到这些源码目录确认契约
除了上面的可直接安装包，仓库里还有三类跟随这些生成器共同演化的支撑目录：
- `GFramework.SourceGenerators.Common`
- 承载跨生成器共享的基类、通用 diagnostics 和生成冲突规则。
- `GFramework.Core.SourceGenerators.Abstractions`
- 承载 `Core` 侧生成器特性定义，例如 `[Log]`、`[ContextAware]`、`[GetModel]`、`[GenerateEnumExtensions]`。
- `GFramework.Godot.SourceGenerators.Abstractions`
- 承载 Godot 侧生成器特性定义，例如 `[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]`。
这些目录当前都不是新的安装入口。更实用的理解方式是：
- 先判断你要装哪个 `*.SourceGenerators` 包
- 再根据 attribute 或 diagnostics 回到对应专题页
- 只有在排查生成失败原因时，才继续下钻到这些共享支撑目录
## 这个栏目怎么读
@ -124,7 +116,7 @@ GFramework 当前发布的生成器包是：
## 对应模块入口
- [Core 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
- [Game 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md)
- [CQRS 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md)
- [Godot 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
- [Core 模块](../core/index.md)
- [Game 模块总览](../game/index.md)
- [CQRS 运行时](../core/cqrs.md)
- [Godot 模块总览](../godot/index.md)

2
docs/zh-CN/source-generators/priority-generator.md
View File

@ -213,4 +213,4 @@ public sealed class DynamicPrioritySystem : IPrioritized
1. [ContextAware 生成器](./context-aware-generator.md)
2. [ContextGet 生成器](./context-get-generator.md)
3. [Core 模块总览](../core/index.md)
4. [Core 源码生成器说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
4. [源码生成器总览](./index.md)

6
docs/zh-CN/tutorials/basic/index.md
View File

@ -160,9 +160,9 @@ description: 从零开始串联环境准备、项目搭建与核心概念的基
如果你已经熟悉基础概念，可以：
1. **只想看最终效果**：直接跳到 [第 6 章](./06-utility-system.md) 查看完整架构
2. **已有 Godot 项目**：从 [第 2 章](./02-project-setup.md) 开始集成 GFramework
3. **想快速上手**：按顺序完成 [第 2-4 章](./02-project-setup.md)，掌握核心用法
1. **查看完整架构示例**：直接跳到 [第 6 章](./06-utility-system.md)
2. **从现有 Godot 项目接入**：从 [第 2 章](./02-project-setup.md) 开始
3. **按最小路径上手**：按顺序完成 [第 2-4 章](./02-project-setup.md)
## 💡 学习建议

6
docs/zh-CN/tutorials/godot-integration.md
View File

@ -65,7 +65,7 @@ dotnet add package GeWuYou.GFramework.Godot.SourceGenerators
## 第二步：把架构和 Godot 节点分开看
当前真实消费者 `ai-libs/CoreGrid` 的默认接入方式，是：
当前更稳妥的默认接入方式，是：
- 架构层继续用常规 `InstallModule(new SomeModule())`
- Godot 节点脚本通过运行时扩展和源码生成器接入场景
@ -195,7 +195,7 @@ public override void _Ready()
}
```
这也是 `ai-libs/CoreGrid` 里项目侧节点类的真实顺序。
这也是项目侧节点类更稳妥的顺序。
## 第五步：只在运行时处理真正需要运行时决定的东西
@ -226,7 +226,7 @@ public partial class SettingsPanel : Control, IController
}
```
手动信号接线时，当前 API 叫 `Signal(...)`，不是旧文档里的 `CreateSignalBuilder(...)`：
手动信号接线时，当前入口是 `Signal(...)`：
```csharp
using GFramework.Godot.Extensions.Signal;

2
docs/zh-CN/tutorials/index.md
View File

@ -39,7 +39,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习
- 已完成基础教程的开发者
- 正在把现有 Godot C# 项目接入 GFramework 的开发者
- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 边界的维护者
- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 接入边界的开发者
**学习内容**：