From 74f853bffef8b4127f9fc88d095dd939ca32d5c3 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 30 Apr 2026 11:59:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(game):=20=E5=90=8C=E6=AD=A5=E7=94=9F?= =?UTF-8?q?=E6=88=90=E5=99=A8=E4=B8=8E=E6=8A=BD=E8=B1=A1=E5=B1=82=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 source-generators 入口，说明 Game.SourceGenerators 面向与 Runtime 对齐的共享 schema 子集 - 补充 abstractions 文档与 README，明确配置契约实现边界仍需回到 GFramework.Game 与 config-system 文档 - 强调 oneOf、anyOf 与非 false 的 additionalProperties 不属于当前 reader-facing 采用路径 --- GFramework.Game.Abstractions/README.md | 28 ++++++++++++++++++++ docs/zh-CN/abstractions/game-abstractions.md | 22 +++++++++++++++ docs/zh-CN/source-generators/index.md | 25 +++++++++++++++++ 3 files changed, 75 insertions(+) diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index 62d5d1ea..40693bc5 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -27,6 +27,29 @@ - `IUiFactory`、`ISceneFactory`、`IUiRoot`、`ISceneRoot`、资源注册表等通常由引擎适配层或游戏项目自己实现。 - 常见做法也是这样组织：页面 / 场景 factory、root、registry 在项目层，运行时基类和契约来自 `GFramework.Game` 与本包。 +## Config Workflow Boundary + +If you only depend on `GFramework.Game.Abstractions`, keep the configuration boundary explicit. + +`Config/` in this package defines read-side contracts such as `IConfigLoader`, `IConfigRegistry`, `IConfigTable`, and +diagnostic models. It does not define the full adoption boundary of the AI-First configuration workflow by itself. + +The actual implementation and support boundary still lives in `GFramework.Game` and its companion documentation: + +- `YamlConfigLoader`, `GameConfigBootstrap`, and `GameConfigModule` are runtime features from `GFramework.Game` +- `GFramework.Game.SourceGenerators` targets the shared schema subset that stays aligned with the runtime contract +- schema designs outside that shared subset should be evaluated against `GFramework.Game` and + `docs/zh-CN/game/config-system.md`, not inferred from abstractions alone + +Typical examples that are outside the current adoption path include: + +- combinators such as `oneOf` and `anyOf` +- non-`false` forms of `additionalProperties` +- other schema designs that rely on open object shapes, union-like branching, or shape-merging behavior + +If your project needs those boundaries clarified, move from this package-level contract view to the runtime-facing +configuration documentation instead of assuming `Game.Abstractions` implies broader schema support. + ## 子系统地图 ### `Config/` @@ -205,6 +228,8 @@ public sealed class ContinueGameCommandHandler - 槽位存档仓库实现 - YAML 配置加载器 - Scene / UI 路由基类 +- AI-First configuration boundary details, including the supported shared schema subset and the unsupported combinator / + open-shape cases 也就是说，本包回答的是“项目各层如何约定”，`GFramework.Game` 回答的是“这些约定默认怎么跑起来”。 @@ -251,3 +276,6 @@ public sealed class ContinueGameCommandHandler - 你需要默认实现、基础设施拼装、运行时启动入口 - 两者一起用 - 最常见。公共层依赖 abstractions，应用层或引擎层依赖 runtime + +For configuration-specific adoption decisions, treat `GFramework.Game` and +[`docs/zh-CN/game/config-system.md`](../docs/zh-CN/game/config-system.md) as the authoritative next step. diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 232f6db7..21d41673 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -25,6 +25,25 @@ description: GFramework.Game.Abstractions 的契约边界、包关系与源码 - 运行时实现：`GFramework.Game` - 底层基础契约：`GFramework.Core.Abstractions` +## 配置契约的采用边界 + +如果你只依赖 `GFramework.Game.Abstractions`，需要额外记住一件事：这里的 `Config/` 只定义“如何注册与访问配置表”的读取契约，不定义 +AI-First 配置工作流的完整实现边界。 + +与配置相关的实际采用路径仍然要回到 `GFramework.Game`： + +- `YamlConfigLoader`、`GameConfigBootstrap`、`GameConfigModule` 等实现都在 `GFramework.Game` +- `GFramework.Game.SourceGenerators` 生成的配置类型，服务的是与 Runtime 对齐的共享 schema 子集 +- 共享子集之外的复杂 schema 设计，不会因为你只依赖 abstractions 就自动获得额外支持 + +这意味着，如果你的 schema 依赖下面这些能力，就不能只停留在 abstractions 视角理解配置契约： + +- `oneOf`、`anyOf` 这类复杂组合关键字 +- 非 `false` 的 `additionalProperties` +- 其他会引入开放对象形状、联合分支或属性合并漂移的 schema 设计 + +这些边界由 `GFramework.Game` 与 [配置系统](../game/config-system.md) 负责说明和落地；`GFramework.Game.Abstractions` 本身不重新定义它们。 + ## 契约地图 | 契约族 | 作用 | @@ -105,6 +124,7 @@ public sealed class ContinueGameCommandHandler - 使用 `SettingsModel`、`SettingsSystem`、`SaveRepository` 等默认实现 - 使用 `YamlConfigLoader`、`GameConfigBootstrap`、`GameConfigModule` - 继承 `SceneRouterBase`、`UiRouterBase` 或默认转场处理器基类 +- 需要确认 AI-First 配置工作流当前支持的共享 schema 子集，以及 `oneOf` / `anyOf`、非 `false` `additionalProperties` 等不在采用路径内的边界 ## 阅读顺序 @@ -119,3 +139,5 @@ public sealed class ContinueGameCommandHandler 4. 需要统一入口时，回到： - [Game 模块总览](../game/index.md) - [入门指南](../getting-started/index.md) + +如果你的关注点是配置契约，请把 [配置系统](../game/config-system.md) 当作下一跳，而不是停留在 abstractions 页面对支持边界做推断。 diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 345cc05f..d65147be 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -42,6 +42,30 @@ GFramework 当前发布的生成器包是： | `GFramework.Cqrs.SourceGenerators` | `GFramework.Cqrs` | | `GFramework.Godot.SourceGenerators` | `GFramework.Godot` | +对 `GFramework.Game.SourceGenerators` 而言，这个“服务 `GFramework.Game`”的关系还包含一个采用前提： + +- 它面向的是与 `GFramework.Game` Runtime 对齐的共享 schema 子集 +- 它的目标是把当前运行时已经明确支持的配置契约生成成类型与表包装，而不是承诺任意 JSON Schema 都能直接生成 +- 读者在评估配置工作流时，应始终把 [配置系统](../game/config-system.md) 视为实际采用边界的说明页 + +## Game 配置生成器的采用边界 + +如果你选择的是 `GFramework.Game.SourceGenerators`，请先按“共享子集”来理解它，而不是按“JSON Schema 全量实现”来理解它。 + +当前 reader-facing 的采用路径是： + +- Runtime、Source Generator 与 Tooling 共同对齐一组共享关键字与对象形状约束 +- 生成器只为这组已经收口的契约生成 C# 配置类型、表包装和相关注册入口 +- 一旦 schema 超出这组共享边界，就应该回到 schema 本体与运行时专题页重新判断，而不是假设生成器会替你兜底 + +当前不属于默认采用路径的典型情况包括： + +- `oneOf`、`anyOf` 这类会改变生成类型形状的组合关键字 +- 非 `false` 的 `additionalProperties` +- 其他需要开放对象形状、联合分支或更自由属性合并的 schema 设计 + +这些场景当前不应被理解为“文档还没写到的隐藏支持”，而应被理解为：它们不在 `GFramework.Game` 现阶段共享配置契约内。 + 安装时通常保持生成器包与对应运行时包版本一致，并将生成器声明为： ```xml @@ -85,6 +109,7 @@ GFramework 当前发布的生成器包是： - 配置 schema 生成与运行时接法： - [配置系统](../game/config-system.md) + - 读者若需要确认共享 schema 子集、关闭对象边界或复杂组合关键字的限制，应以该页为准，而不是只从本页推断支持范围 - CQRS handler registry 生成器： - [CQRS Handler Registry 生成器](./cqrs-handler-registry-generator.md) - CQRS 模块族采用入口：