From 979db3b5a5def639fa2fd189eb7ac0cb5bd2c018 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Mon, 27 Apr 2026 08:55:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(reader-facing):=20=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E7=AB=99=E5=86=85=E5=85=A5=E5=8F=A3=E4=B8=8E=E5=85=AC=E5=BC=80?= =?UTF-8?q?=E6=9C=AF=E8=AF=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新入口页的 reader-facing 骨架，统一起步路线、阅读顺序与站内导航 - 收口公开 README 与 Godot 页面中的内部口吻、文件名式表述和术语噪音 - 移除 docs/zh-CN 中残留的 GitHub README 外链，并同步刷新文档治理恢复状态 --- GFramework.Cqrs.Abstractions/README.md | 6 +- GFramework.Ecs.Arch/README.md | 2 +- GFramework.Game.Abstractions/README.md | 7 +-- GFramework.Game/README.md | 17 +++--- GFramework.Godot/README.md | 12 ++-- ...ation-full-coverage-governance-tracking.md | 45 ++++++++++++-- ...entation-full-coverage-governance-trace.md | 44 ++++++++++++++ docs/zh-CN/abstractions/core-abstractions.md | 6 +- .../abstractions/ecs-arch-abstractions.md | 6 +- docs/zh-CN/abstractions/game-abstractions.md | 6 +- docs/zh-CN/api-reference/index.md | 41 +++++-------- docs/zh-CN/core/cqrs.md | 2 +- docs/zh-CN/core/index.md | 13 ++-- docs/zh-CN/ecs/arch.md | 2 +- docs/zh-CN/game/index.md | 24 ++++---- docs/zh-CN/game/scene.md | 4 +- docs/zh-CN/game/ui.md | 4 +- docs/zh-CN/getting-started/index.md | 50 +++++++++------- docs/zh-CN/getting-started/quick-start.md | 2 +- docs/zh-CN/godot/scene.md | 19 +++--- docs/zh-CN/godot/signal.md | 2 +- docs/zh-CN/godot/ui.md | 14 ++--- ...register-exported-collections-generator.md | 2 +- .../bind-node-signal-generator.md | 2 +- .../context-aware-generator.md | 2 +- .../source-generators/get-node-generator.md | 2 +- .../godot-project-generator.md | 2 +- docs/zh-CN/source-generators/index.md | 60 ++++++++----------- .../source-generators/priority-generator.md | 2 +- docs/zh-CN/tutorials/index.md | 2 +- 30 files changed, 229 insertions(+), 173 deletions(-) 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/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 deb184cc..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` 与本包。 ## 子系统地图 @@ -209,9 +208,9 @@ public sealed class ContinueGameCommandHandler 也就是说，本包回答的是“项目各层如何约定”，`GFramework.Game` 回答的是“这些约定默认怎么跑起来”。 -## `ai-libs/` 里的参考接入线索 +## 典型分层方式 -`ai-libs/` 下的只读参考实现对本包的使用方式，能比较清楚地说明它的职责边界： +典型项目对本包的使用方式，通常能清楚体现它的职责边界： - 公共脚本广泛引用： - `IUiRouter` diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index f782c4d0..4711e7d6 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,7 @@ 对应文档： - [存储系统](../docs/zh-CN/game/storage.md) -- [Storage 子模块说明](./Storage/ReadMe.md) +- [存储系统专题](../docs/zh-CN/game/storage.md) ### `Serializer/` @@ -149,7 +148,7 @@ - `Scene/Handler/*`、`UI/Handler/*` - 默认转换处理器基类与日志处理器 -`ai-libs/` 下已验证参考实现的常见接法： +常见接法： - 项目自定义 `SceneRouter : SceneRouterBase` - 项目自定义 `UiRouter : UiRouterBase` @@ -266,7 +265,7 @@ await settingsSystem.ApplyAll(); await settingsSystem.SaveAll(); ``` -`ai-libs/` 下的只读参考实现目前也是按这个思路接入，只是底层存储换成了 Godot 适配实现。 +在 Godot 项目中也可以沿用同一思路，只是底层存储通常换成宿主侧适配实现。 ### 3. 接入静态 YAML 配置 @@ -324,9 +323,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 8b700124..bbd58ffd 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,13 +12,13 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-041` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-042` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 继续以最新 `origin/main`（`617e0bf`，`2026-04-26 12:17:15 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files -- 本轮低风险切片聚焦 3 组 reader-facing 收口：安装页选包矩阵补齐、公开 README 的 XML 阅读入口去治理化、`config-system` / 基础教程入口的维护者口吻改写 -- 当前 committed branch diff vs `origin/main` 已为 `9` files / `191` changed lines，仍明显低于 `50` 文件阈值；工作树只剩未纳入本批次的 `tools/gframework-config-tool/gframework-config-tool-0.0.3.vsix` untracked 打包产物 -- 当前已知 PR `#292` 远端 review 剩余上下文仍主要集中在 config tool adoption surface；本轮未继续抓取远端 review，而是优先收口本地可验证的 reader-facing 一致性问题 +- 本轮已扩成 3 个连续低风险切片：入口页 reader-facing 改写、公开 README / Godot 页面去内部口吻，以及剩余 GitHub blob README 外链改回站内导航 +- 当前工作树相对 `origin/main` 的 tracked diff 已到 `36` files / `500` changed lines；仍低于 `50` 文件阈值，但继续扩批前应先提交当前稳定批次，避免 review 面继续发散 +- 已接受 subagent 结论：当前最划算的修正不是扩新栏目，而是统一入口页骨架、清掉公开页面中的治理口吻、以及把站外 README 入口降回站内专题页 ## 当前状态摘要 @@ -34,6 +34,9 @@ - `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-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` 的共享支撑层说明。 @@ -84,6 +87,36 @@ - 结果：通过；`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` `bun run build`（工作目录：`docs/`） - 结果：通过；本轮 README、安装页与公开文案改写后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-25` `bun run build`（工作目录：`docs/`） @@ -172,8 +205,8 @@ ## 下一步 -1. 重新抓取 `$gframework-pr-review`，确认 PR `#292` 的 latest-head review 是否已自动关闭或仅剩过期线程。 -2. 若 branch diff vs `origin/main` 在提交后仍明显低于 `50` 文件阈值，继续优先扫描公开文档中的维护者口吻、治理式表格字段与过时安装说明，而不是扩新栏目。 +1. 提交当前 `36` files / `500` changed lines 的稳定批次后，重新计算 branch diff；若仍低于 `50` 且 reviewability 可接受，再继续选择一组不超过 `10` files 的 reader-facing 收口。 +2. 优先扫描还残留 `ai-libs`、`旧文档`、`README.md` / 路径式标签或内部术语的公开页面，而不是扩新栏目。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 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 30e6dbf6..dedeadae 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 @@ -2,6 +2,50 @@ ## 2026-04-27 +### 当前恢复点：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`。 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/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/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/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/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/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/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/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/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]` 接入边界的开发者 **学习内容**：