From 1454c81a5befc78d8706bdb383e6870447ad0ccb Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Mon, 27 Apr 2026 07:42:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(adoption):=20=E6=94=B6=E5=8F=A3=E5=AE=89?= =?UTF-8?q?=E8=A3=85=E5=85=A5=E5=8F=A3=E4=B8=8E=E5=85=AC=E5=BC=80=E6=96=87?= =?UTF-8?q?=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新安装页的选包矩阵、推荐组合与 Godot 基线说明 - 收口公开 README 的 XML 阅读入口表述，移除治理式计数与日期字段 - 调整配置系统与基础教程入口的 reader-facing 文案，并同步更新恢复文档 --- GFramework.Core.Abstractions/README.md | 19 +++---- GFramework.Ecs.Arch.Abstractions/README.md | 10 ++-- GFramework.Game.Abstractions/README.md | 19 +++---- GFramework.Game.SourceGenerators/README.md | 10 ++-- ...ation-full-coverage-governance-tracking.md | 34 ++++++++---- ...entation-full-coverage-governance-trace.md | 32 +++++++++++ docs/zh-CN/game/config-system.md | 4 +- docs/zh-CN/getting-started/installation.md | 55 +++++++++++++------ docs/zh-CN/tutorials/basic/index.md | 6 +- 9 files changed, 125 insertions(+), 64 deletions(-) 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.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.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index 4f02b893..deb184cc 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -133,17 +133,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` | 看公共路由上下文、存储角色、资源注册表与跨层共享枚举 | ## 最小接入路径 diff --git a/GFramework.Game.SourceGenerators/README.md b/GFramework.Game.SourceGenerators/README.md index 8723ad39..193c3f77 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` | 看生成器会抛出的诊断类别与失败边界 | +| 类型族 | 代表类型 | 阅读重点 | +| --- | --- | --- | +| `Config/` | `SchemaConfigGenerator` | 看 schema 到配置类型 / 表包装 / 注册辅助代码的生成入口 | +| `Diagnostics/` | `ConfigSchemaDiagnostics` | 看生成器会抛出的诊断类别与失败边界 | ## 最小接入路径 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..0c51932a 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-041` - 当前阶段：`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 +- 本轮低风险切片聚焦 3 组 reader-facing 收口：安装页选包矩阵补齐、公开 README 的 XML 阅读入口去治理化、`config-system` / 基础教程入口的维护者口吻改写 +- 当前工作树相对 `origin/main` 的 tracked diff 为 `9` files / `191` changed lines；当前 committed branch diff vs `origin/main` 仍为 `0` files，本批次落地后仍明显低于 `50` 文件阈值 +- 当前已知 PR `#292` 远端 review 剩余上下文仍主要集中在 config tool adoption surface；本轮未继续抓取远端 review，而是优先收口本地可验证的 reader-facing 一致性问题 ## 当前状态摘要 @@ -32,6 +31,9 @@ - `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-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` 的共享支撑层说明。 @@ -74,6 +76,16 @@ - 结果：通过；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` `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 +172,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. 提交本轮 `9` 个 tracked files 的 reader-facing 文档批次后，重新抓取 `$gframework-pr-review`，确认 PR `#292` 的 latest-head review 是否已自动关闭或仅剩过期线程。 +2. 若 branch diff vs `origin/main` 在提交后仍明显低于 `50` 文件阈值，继续优先扫描公开文档中的维护者口吻、治理式表格字段与过时安装说明，而不是扩新栏目。 +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..30e6dbf6 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,37 @@ # Documentation Full Coverage Governance Trace +## 2026-04-27 + +### 当前恢复点：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/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/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/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) ## 💡 学习建议