diff --git a/GFramework.Core.Abstractions/README.md b/GFramework.Core.Abstractions/README.md index 34382544..cbb44371 100644 --- a/GFramework.Core.Abstractions/README.md +++ b/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` | -| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncQueryExecutor`、`ICqrsRuntime` | -| `Events/` `Property/` `State/` `StateManagement/` | `25/25` 个类型声明已带 XML 注释 | `IEventBus`、`IBindableProperty`、`IStateMachine`、`IStore` | -| `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`、`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` | 看架构、上下文、模块装配与注册表基类边界 | +| `Command/` `Query/` `Cqrs/` | `ICommandExecutor`、`IAsyncQueryExecutor`、`ICqrsRuntime` | 看命令、查询与新请求模型的调用入口 | +| `Events/` `Property/` `State/` `StateManagement/` | `IEventBus`、`IBindableProperty`、`IStateMachine`、`IStore` | 看事件分发、可绑定状态与 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`、`ISerializer`、`IStorage` | 看配置、环境、数据装载、序列化与存储边界 | +| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 看组件角色、优先级和值对象约定 | 完整接入说明与阅读顺序见 [Core 抽象层说明](../docs/zh-CN/abstractions/core-abstractions.md)。 diff --git a/GFramework.Cqrs.Abstractions/README.md b/GFramework.Cqrs.Abstractions/README.md index 94ed14a8..4a7c6bdd 100644 --- a/GFramework.Cqrs.Abstractions/README.md +++ b/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`、`QueryBase`、`NotificationBase` 等消息基类。 - 只引用本包时，没有 `AbstractCommandHandler`、`AbstractQueryHandler`、`AbstractNotificationHandler` 等处理器基类。 -- `ICqrsContext` 当前是轻量 marker seam；默认 runtime 在需要向 `IContextAware` 处理器注入上下文时，仍要求传入的上下文同时实现 `IArchitectureContext`。 +- `ICqrsContext` 当前是轻量 marker 接口；默认 runtime 在需要向 `IContextAware` 处理器注入上下文时，仍要求传入的上下文同时实现 `IArchitectureContext`。 ## 文档入口 diff --git a/GFramework.Ecs.Arch.Abstractions/README.md b/GFramework.Ecs.Arch.Abstractions/README.md index a92a1fc2..2471bdc8 100644 --- a/GFramework.Ecs.Arch.Abstractions/README.md +++ b/GFramework.Ecs.Arch.Abstractions/README.md @@ -37,11 +37,11 @@ 下表汇总当前契约包的类型级 XML 文档入口，方便把 README、站内抽象页与源码阅读顺序对齐。 -| 类型族 | 代表类型 | XML 状态 | 阅读重点 | -| --- | --- | --- | --- | -| 模块契约 | `IArchEcsModule` | 已覆盖 | 宿主循环如何统一驱动 ECS 更新 | -| 系统桥接契约 | `IArchSystemAdapter` | 已覆盖 | 外部模块怎样只依赖更新接口而不绑定默认实现 | -| 配置对象 | `ArchOptions` | 已覆盖 | 跨程序集共享 ECS 配置边界 | +| 类型族 | 代表类型 | 阅读重点 | +| --- | --- | --- | +| 模块契约 | `IArchEcsModule` | 宿主循环如何统一驱动 ECS 更新 | +| 系统桥接契约 | `IArchSystemAdapter` | 外部模块怎样只依赖更新接口而不绑定默认实现 | +| 配置对象 | `ArchOptions` | 跨程序集共享 ECS 配置边界 | ## 最小接入路径 diff --git a/GFramework.Ecs.Arch/README.md b/GFramework.Ecs.Arch/README.md index 75240b8a..6f855c89 100644 --- a/GFramework.Ecs.Arch/README.md +++ b/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` 系统桥接到同一条采用路径中。 如果你需要的只是共享契约，请改为依赖 `GFramework.Ecs.Arch.Abstractions`。 diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index 4f02b893..62d5d1ea 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -25,8 +25,7 @@ - `FileStorage`、`ScopedStorage`、`JsonSerializer`、`SettingsModel`、`SaveRepository`、`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`、`ConfigLoadException` | 看配置表注册、读取约定和失败诊断模型 | -| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository`、`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`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 | +| 契约族 | 代表类型 | 阅读重点 | +| --- | --- | --- | +| `Config/` | `IConfigLoader`、`IConfigRegistry`、`IConfigTable`、`ConfigLoadException` | 看配置表注册、读取约定和失败诊断模型 | +| `Data/` | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository`、`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`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 | ## 最小接入路径 @@ -210,9 +208,9 @@ public sealed class ContinueGameCommandHandler 也就是说，本包回答的是“项目各层如何约定”，`GFramework.Game` 回答的是“这些约定默认怎么跑起来”。 -## `ai-libs/` 里的参考接入线索 +## 典型分层方式 -`ai-libs/` 下的只读参考实现对本包的使用方式，能比较清楚地说明它的职责边界： +典型项目对本包的使用方式，通常能清楚体现它的职责边界： - 公共脚本广泛引用： - `IUiRouter` diff --git a/GFramework.Game.SourceGenerators/README.md b/GFramework.Game.SourceGenerators/README.md index 8723ad39..63478af8 100644 --- a/GFramework.Game.SourceGenerators/README.md +++ b/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` | 看生成器会抛出的诊断类别与失败边界 | ## 最小接入路径 diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index f782c4d0..33aaa752 100644 --- a/GFramework.Game/README.md +++ b/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` @@ -96,7 +95,7 @@ - `Setting/Events/*` - 设置初始化、应用、保存、重置相关事件 -`ai-libs/` 下已验证参考实现的常见接法： +常见接法： - 在模型模块中创建 `SettingsModel` - 注册多个 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 完成配置注册 diff --git a/GFramework.Godot/README.md b/GFramework.Godot/README.md index 5c7dee03..3f85835b 100644 --- a/GFramework.Godot/README.md +++ b/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` 模块的路由语义 ## 文档入口 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 51914f03..98d03748 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 @@ -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` 与相关专题页是否仍保持一致。 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 4a0b4abc..9fc8866b 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,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 diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index 3d3ec390..db399a46 100644 --- a/docs/zh-CN/abstractions/core-abstractions.md +++ b/docs/zh-CN/abstractions/core-abstractions.md @@ -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) diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md index 2c23b8d4..41692ec7 100644 --- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md +++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md @@ -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) diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 73833327..232f6db7 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -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) diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index eaebf2fc..d909c9aa 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -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 文档出现冲突时，以源码和测试所反映的当前实现为准。 diff --git a/docs/zh-CN/core/architecture.md b/docs/zh-CN/core/architecture.md index 51db2547..2562f534 100644 --- a/docs/zh-CN/core/architecture.md +++ b/docs/zh-CN/core/architecture.md @@ -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()`。 ## 组件注册顺序 diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index cbeea470..7bde2c3a 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -214,4 +214,4 @@ RegisterCqrsPipelineBehavior>(); - 上下文入口：[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) diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index 51413279..38d8b123 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -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) diff --git a/docs/zh-CN/ecs/arch.md b/docs/zh-CN/ecs/arch.md index cdc98ae6..0eff9707 100644 --- a/docs/zh-CN/ecs/arch.md +++ b/docs/zh-CN/ecs/arch.md @@ -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) diff --git a/docs/zh-CN/game/config-system.md b/docs/zh-CN/game/config-system.md index 9316c7d7..9c38f65a 100644 --- a/docs/zh-CN/game/config-system.md +++ b/docs/zh-CN/game/config-system.md @@ -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 元数据约定，足以支撑单独工具的长期维护 diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index e5913390..69e2d66c 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -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`、`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) diff --git a/docs/zh-CN/game/scene.md b/docs/zh-CN/game/scene.md index 8a203175..45b19606 100644 --- a/docs/zh-CN/game/scene.md +++ b/docs/zh-CN/game/scene.md @@ -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) diff --git a/docs/zh-CN/game/serialization.md b/docs/zh-CN/game/serialization.md index 2ee420d8..1d05fcb8 100644 --- a/docs/zh-CN/game/serialization.md +++ b/docs/zh-CN/game/serialization.md @@ -46,7 +46,7 @@ IRuntimeTypeSerializer runtimeSerializer = new JsonSerializer(); ## 配置生命周期 -这部分是当前实现最容易被旧文档说错的地方。 +这里最需要先确认的是序列化器的配置生命周期。 `JsonSerializer` 不会复制你传入的 `JsonSerializerSettings`。它会直接持有并复用这份实例，以及里面的 `Converters` 集合。 diff --git a/docs/zh-CN/game/setting.md b/docs/zh-CN/game/setting.md index 64e106e2..67fab33e 100644 --- a/docs/zh-CN/game/setting.md +++ b/docs/zh-CN/game/setting.md @@ -16,7 +16,7 @@ description: 以当前 SettingsModel、SettingsSystem 与相关测试为准， - `SettingsModel` - `SettingsSystem` -而不是旧文档里那种“只靠若干 `Get() / Register(...)` 辅助方法就能自动完成一切”的模型。 +而不是只靠若干 `Get() / Register(...)` 辅助方法就能自动完成一切的模型。 ## 当前公开入口 @@ -91,7 +91,7 @@ applicator 的职责不是保存数据，而是把设置结果作用到实际运 ## 初始化与迁移的真实语义 -`SettingsModel.InitializeAsync()` 的当前行为，比旧文档里“加载一下就好”更严格一些： +`SettingsModel.InitializeAsync()` 会按更完整的初始化与迁移顺序工作： - 它会先调用 `ISettingsDataRepository.LoadAllAsync()` - 再逐个匹配当前模型里已经登记的设置类型 diff --git a/docs/zh-CN/game/ui.md b/docs/zh-CN/game/ui.md index a1d24e56..c840fa24 100644 --- a/docs/zh-CN/game/ui.md +++ b/docs/zh-CN/game/ui.md @@ -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) diff --git a/docs/zh-CN/getting-started/index.md b/docs/zh-CN/getting-started/index.md index f981c746..addf0b4e 100644 --- a/docs/zh-CN/getting-started/index.md +++ b/docs/zh-CN/getting-started/index.md @@ -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) diff --git a/docs/zh-CN/getting-started/installation.md b/docs/zh-CN/getting-started/installation.md index 6f73b3de..7d33eb7f 100644 --- a/docs/zh-CN/getting-started/installation.md +++ b/docs/zh-CN/getting-started/installation.md @@ -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 + + + + @@ -143,10 +165,9 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators 如果你想排除局部导入，可以继续在项目文件中添加排除项： ```xml - - - + + ``` @@ -223,7 +244,7 @@ dotnet build 确保： -- Godot 版本 >= 4.5 +- 项目环境与当前文档保持在 Godot 4.6.2 基线 - 已正确安装 Godot C# 模板 - 项目引用了正确的 Godot 包 diff --git a/docs/zh-CN/getting-started/quick-start.md b/docs/zh-CN/getting-started/quick-start.md index 7041b78c..364d7844 100644 --- a/docs/zh-CN/getting-started/quick-start.md +++ b/docs/zh-CN/getting-started/quick-start.md @@ -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) diff --git a/docs/zh-CN/godot/architecture.md b/docs/zh-CN/godot/architecture.md index 3261a6b3..4e4fa286 100644 --- a/docs/zh-CN/godot/architecture.md +++ b/docs/zh-CN/godot/architecture.md @@ -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` 只是便捷基类，不代表自动阶段广播 diff --git a/docs/zh-CN/godot/extensions.md b/docs/zh-CN/godot/extensions.md index 8f006692..ba37b150 100644 --- a/docs/zh-CN/godot/extensions.md +++ b/docs/zh-CN/godot/extensions.md @@ -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()` 只会创建一个直接子节点，不会递归补整条路径 - `SafeCallDeferred(...)` 只有在 `IsValidNode()` 为 `true` 时才会调用；节点未入树时不会执行 diff --git a/docs/zh-CN/godot/index.md b/docs/zh-CN/godot/index.md index e1f19bb8..49f6f73b 100644 --- a/docs/zh-CN/godot/index.md +++ b/docs/zh-CN/godot/index.md @@ -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()`、`GetParentX()`、`GetOrCreateNode()`、`QueueFreeX()`、 `FreeX()`、`WaitUntilReadyAsync()` 这一类运行时辅助；不要再把它描述成一个“默认覆盖所有 Godot 节点操作”的大而全层 - Scene / UI 工厂依赖显式 registry 与 `PackedScene` 资源，不存在“运行时自动扫描所有场景并完成统一注册”的当前契约 diff --git a/docs/zh-CN/godot/logging.md b/docs/zh-CN/godot/logging.md index 55b9efeb..400a4ea6 100644 --- a/docs/zh-CN/godot/logging.md +++ b/docs/zh-CN/godot/logging.md @@ -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; diff --git a/docs/zh-CN/godot/scene.md b/docs/zh-CN/godot/scene.md index 85fad2eb..afb96cd4 100644 --- a/docs/zh-CN/godot/scene.md +++ b/docs/zh-CN/godot/scene.md @@ -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` 及其 `Node2D` / `Node3D` / `Control` / `Generic` 实现 - 项目侧实现的 `ISceneRoot` -- 项目侧继承 `SceneRouterBase` 的 router +- 项目侧继承 `SceneRouterBase` 的路由器 也就是说，Godot 集成页的重点不是“再造一套场景导航 API”，而是把 `PackedScene`、`Node` 和 `GFramework.Game` 的 `ISceneRouter` / `ISceneBehavior` 契约接起来。 @@ -39,7 +39,7 @@ Godot 侧的场景资源表，底层是 `IAssetRegistry`。它只 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` diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md index 5a79cebf..081fd71a 100644 --- a/docs/zh-CN/godot/setting.md +++ b/docs/zh-CN/godot/setting.md @@ -72,8 +72,7 @@ description: 以当前 GFramework.Godot 源码、测试与 CoreGrid 接线为准 ## 最小接入路径 -当前消费者 `ai-libs/CoreGrid` 的接法，是先注册 `SettingsModel`，再把 Godot applicator -挂进去： +当前更常见的接法，是先注册 `SettingsModel`，再把 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 入口 + 模块入口 ## 运行时使用方式 diff --git a/docs/zh-CN/godot/signal.md b/docs/zh-CN/godot/signal.md index 3561f883..cfa3a9dc 100644 --- a/docs/zh-CN/godot/signal.md +++ b/docs/zh-CN/godot/signal.md @@ -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 diff --git a/docs/zh-CN/godot/storage.md b/docs/zh-CN/godot/storage.md index be47e4df..6e662b81 100644 --- a/docs/zh-CN/godot/storage.md +++ b/docs/zh-CN/godot/storage.md @@ -60,7 +60,7 @@ description: 以当前 GFramework.Godot 源码与 CoreGrid 接线为准，说明 ## 最小接入路径 -当前消费者 `ai-libs/CoreGrid` 的接法是先注册同一个序列化器和存储实例，再让设置仓库、存档仓库等上层组件复用它： +当前更常见的接法，是先注册同一个序列化器和存储实例，再让设置仓库、存档仓库等上层组件复用它： ```csharp using GFramework.Core.Abstractions.Serializer; diff --git a/docs/zh-CN/godot/ui.md b/docs/zh-CN/godot/ui.md index b1becf96..b194a86c 100644 --- a/docs/zh-CN/godot/ui.md +++ b/docs/zh-CN/godot/ui.md @@ -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` diff --git a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md index 1b72415e..2f2a0529 100644 --- a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md +++ b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md @@ -220,4 +220,4 @@ public List? 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) diff --git a/docs/zh-CN/source-generators/bind-node-signal-generator.md b/docs/zh-CN/source-generators/bind-node-signal-generator.md index 56a077fc..1e6a4d76 100644 --- a/docs/zh-CN/source-generators/bind-node-signal-generator.md +++ b/docs/zh-CN/source-generators/bind-node-signal-generator.md @@ -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) diff --git a/docs/zh-CN/source-generators/context-aware-generator.md b/docs/zh-CN/source-generators/context-aware-generator.md index 340a9ea3..eb56ab91 100644 --- a/docs/zh-CN/source-generators/context-aware-generator.md +++ b/docs/zh-CN/source-generators/context-aware-generator.md @@ -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) diff --git a/docs/zh-CN/source-generators/get-node-generator.md b/docs/zh-CN/source-generators/get-node-generator.md index c2c68126..bc5ff66d 100644 --- a/docs/zh-CN/source-generators/get-node-generator.md +++ b/docs/zh-CN/source-generators/get-node-generator.md @@ -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) diff --git a/docs/zh-CN/source-generators/godot-project-generator.md b/docs/zh-CN/source-generators/godot-project-generator.md index 09634d8e..575b6f35 100644 --- a/docs/zh-CN/source-generators/godot-project-generator.md +++ b/docs/zh-CN/source-generators/godot-project-generator.md @@ -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) diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 846042fd..6397fba5 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -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) diff --git a/docs/zh-CN/source-generators/priority-generator.md b/docs/zh-CN/source-generators/priority-generator.md index 9317937f..8de267d0 100644 --- a/docs/zh-CN/source-generators/priority-generator.md +++ b/docs/zh-CN/source-generators/priority-generator.md @@ -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) diff --git a/docs/zh-CN/tutorials/basic/index.md b/docs/zh-CN/tutorials/basic/index.md index 7e2cc085..0e7c6d47 100644 --- a/docs/zh-CN/tutorials/basic/index.md +++ b/docs/zh-CN/tutorials/basic/index.md @@ -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) ## 💡 学习建议 diff --git a/docs/zh-CN/tutorials/godot-integration.md b/docs/zh-CN/tutorials/godot-integration.md index 595a5a31..64548938 100644 --- a/docs/zh-CN/tutorials/godot-integration.md +++ b/docs/zh-CN/tutorials/godot-integration.md @@ -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; diff --git a/docs/zh-CN/tutorials/index.md b/docs/zh-CN/tutorials/index.md index fa4cc05d..be5ab2c1 100644 --- a/docs/zh-CN/tutorials/index.md +++ b/docs/zh-CN/tutorials/index.md @@ -39,7 +39,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 - 已完成基础教程的开发者 - 正在把现有 Godot C# 项目接入 GFramework 的开发者 -- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 边界的维护者 +- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 接入边界的开发者 **学习内容**：