From b96565ffa367bade30f44c2d4e8955143fbff85e Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 25 Apr 2026 17:10:37 +0800 Subject: [PATCH] =?UTF-8?q?docs(documentation):=20=E6=89=A9=E5=B1=95?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=8A=9F=E8=83=BD=E6=96=87=E6=A1=A3=E8=A6=86?= =?UTF-8?q?=E7=9B=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 meta-package 与安装入口，明确聚合范围、当前运行时基线和首页选包路径 - 补充 Game 配置工具文档与导航，把 VS Code config workflow 纳入 reader-facing 采用链路 - 修正文档与实现不一致的 source-generator 与 CQRS 契约说明，补充 support module 边界 - 记录 RP-038 批处理恢复点、委派结论和本轮验证结果 --- .../README.md | 57 ++++++++ .../README.md | 51 +++++++ GFramework.SourceGenerators.Common/README.md | 44 ++++++ GFramework.csproj | 2 +- README.md | 10 +- ...ation-full-coverage-governance-tracking.md | 36 ++++- ...entation-full-coverage-governance-trace.md | 43 ++++++ docs/.vitepress/config.mts | 1 + docs/zh-CN/api-reference/index.md | 10 ++ docs/zh-CN/core/cqrs.md | 36 ++++- docs/zh-CN/game/config-system.md | 4 + docs/zh-CN/game/config-tool.md | 138 ++++++++++++++++++ docs/zh-CN/game/index.md | 8 +- docs/zh-CN/getting-started/installation.md | 17 ++- docs/zh-CN/index.md | 34 +++-- .../context-get-generator.md | 26 ++-- .../zh-CN/source-generators/enum-generator.md | 36 ++--- .../source-generators/get-node-generator.md | 22 ++- docs/zh-CN/source-generators/index.md | 23 +++ tools/gframework-config-tool/README.md | 82 ++++++++--- 20 files changed, 585 insertions(+), 95 deletions(-) create mode 100644 GFramework.Core.SourceGenerators.Abstractions/README.md create mode 100644 GFramework.Godot.SourceGenerators.Abstractions/README.md create mode 100644 GFramework.SourceGenerators.Common/README.md create mode 100644 docs/zh-CN/game/config-tool.md diff --git a/GFramework.Core.SourceGenerators.Abstractions/README.md b/GFramework.Core.SourceGenerators.Abstractions/README.md new file mode 100644 index 00000000..3034cf05 --- /dev/null +++ b/GFramework.Core.SourceGenerators.Abstractions/README.md @@ -0,0 +1,57 @@ +# GFramework.Core.SourceGenerators.Abstractions + +`GFramework.Core.SourceGenerators.Abstractions` 存放 `Core` 侧源码生成器公开使用的 attribute 和最小契约定义。 +它不是单独推广的生成器包，而是 `GFramework.Core.SourceGenerators` 的支撑层。 + +## 目录定位 + +这里当前主要提供： + +- 架构注册相关特性 + - `AutoRegisterModuleAttribute` + - `RegisterModelAttribute` + - `RegisterSystemAttribute` + - `RegisterUtilityAttribute` +- 规则与上下文注入特性 + - `ContextAwareAttribute` + - `GetModelAttribute` + - `GetModelsAttribute` + - `GetSystemAttribute` + - `GetSystemsAttribute` + - `GetUtilityAttribute` + - `GetUtilitiesAttribute` + - `GetServiceAttribute` + - `GetServicesAttribute` + - `GetAllAttribute` +- 其他通用生成器特性 + - `LogAttribute` + - `PriorityAttribute` + - `GenerateEnumExtensionsAttribute` + +这些类型定义“消费端代码可以写什么 attribute”，而实际生成逻辑和 diagnostics 仍在 +`GFramework.Core.SourceGenerators` 中。 + +## 与相邻模块的关系 + +- `GFramework.Core.SourceGenerators` + - 实际读取这里定义的 attribute，并生成代码或 diagnostics。 +- `GFramework.SourceGenerators.Common` + - 为 `Core` 侧生成器提供共享基类和公共约束。 + +当前目录本身 `IsPackable=false`。对 NuGet 使用者来说，更实际的入口仍然是 +`GeWuYou.GFramework.Core.SourceGenerators`；这个 abstractions DLL 会跟随对应 analyzer 包一起交付。 + +## 什么时候需要读这里 + +- 你在确认某个 `Core` 侧 attribute 的可用参数和命名 +- 你在排查“文档写法”和 attribute 实际公开面是否一致 +- 你在扩展 `Core.SourceGenerators`，需要先确认契约层边界 + +如果你的目标只是开始使用生成器，优先回到 `Core.SourceGenerators` README 和 `source-generators` 栏目。 + +## 继续阅读 + +- [Core 源码生成器说明](../GFramework.Core.SourceGenerators/README.md) +- [源码生成器总览](../docs/zh-CN/source-generators/index.md) +- [Context Get 注入生成器](../docs/zh-CN/source-generators/context-get-generator.md) +- [枚举扩展生成器](../docs/zh-CN/source-generators/enum-generator.md) diff --git a/GFramework.Godot.SourceGenerators.Abstractions/README.md b/GFramework.Godot.SourceGenerators.Abstractions/README.md new file mode 100644 index 00000000..2132231c --- /dev/null +++ b/GFramework.Godot.SourceGenerators.Abstractions/README.md @@ -0,0 +1,51 @@ +# GFramework.Godot.SourceGenerators.Abstractions + +`GFramework.Godot.SourceGenerators.Abstractions` 存放 Godot 侧源码生成器公开使用的 attribute 和最小辅助类型。 +它不是单独推广的消费包，而是 `GFramework.Godot.SourceGenerators` 的支撑层。 + +## 目录定位 + +这里当前主要提供： + +- 节点与信号相关特性 + - `GetNodeAttribute` + - `BindNodeSignalAttribute` +- 场景 / UI / 集合注册相关特性 + - `AutoSceneAttribute` + - `AutoUiPageAttribute` + - `AutoRegisterExportedCollectionsAttribute` + - `RegisterExportedCollectionAttribute` +- Godot 项目级辅助类型 + - `AutoLoadAttribute` + - `GodotModuleMarker` + - `NodeLookupMode` + +这些类型负责定义“消费端项目可以声明哪些特性与参数”，而具体的生成逻辑、diagnostics 和生命周期约束仍在 +`GFramework.Godot.SourceGenerators` 中。 + +## 与相邻模块的关系 + +- `GFramework.Godot.SourceGenerators` + - 实际消费这里定义的 attribute，并生成节点注入、信号绑定、Scene / UI 包装与项目元数据辅助代码。 +- `GFramework.SourceGenerators.Common` + - 为 Godot 侧生成器提供共享基础设施和通用约束。 +- `GFramework.Godot` + - 提供运行时宿主与集成层；生成器只负责编译期辅助。 + +当前目录本身 `IsPackable=false`。对 NuGet 使用者来说，更实际的入口仍然是 +`GeWuYou.GFramework.Godot.SourceGenerators`；这个 abstractions DLL 会跟随对应 analyzer 包一起交付。 + +## 什么时候需要读这里 + +- 你在确认 `[GetNode]`、`[BindNodeSignal]`、`[AutoScene]` 等特性的公开参数语义 +- 你在排查生成器文档是否和 attribute 契约一致 +- 你在扩展 Godot 侧生成器，想先看清契约层边界 + +如果你的目标只是把生成器接进项目，优先回到 `Godot.SourceGenerators` README 和专题页。 + +## 继续阅读 + +- [Godot 源码生成器说明](../GFramework.Godot.SourceGenerators/README.md) +- [源码生成器总览](../docs/zh-CN/source-generators/index.md) +- [GetNode 生成器](../docs/zh-CN/source-generators/get-node-generator.md) +- [BindNodeSignal 生成器](../docs/zh-CN/source-generators/bind-node-signal-generator.md) diff --git a/GFramework.SourceGenerators.Common/README.md b/GFramework.SourceGenerators.Common/README.md new file mode 100644 index 00000000..9e964364 --- /dev/null +++ b/GFramework.SourceGenerators.Common/README.md @@ -0,0 +1,44 @@ +# GFramework.SourceGenerators.Common + +`GFramework.SourceGenerators.Common` 是 `GFramework` 多个源码生成器共享的公共支撑目录。它不是独立推广的运行时或 +生成器采用入口，而是跟随各个 `*.SourceGenerators` 模块一起演化的内部基础设施。 + +## 目录定位 + +这个目录当前主要承载三类公共能力： + +- 生成器基类 + - 例如 `AttributeClassGeneratorBase`、`AttributeEnumGeneratorBase`、`MetadataAttributeClassGeneratorBase` +- 共享诊断 + - 例如 `Diagnostics/CommonDiagnostics.cs` +- 共享符号与冲突处理 + - 例如 `Extensions/GeneratedMethodConflictExtensions.cs` + +如果你在 `Core`、`CQRS`、`Game`、`Godot` 侧生成器里看到相似的诊断或生成冲突语义，通常就是这里在统一约束。 + +## 与相邻模块的关系 + +- `GFramework.Core.SourceGenerators` + - 复用这里的生成器基类和部分通用 diagnostics。 +- `GFramework.Cqrs.SourceGenerators` + - 以这里作为编译期公共依赖，并把公共 DLL 一起打进 analyzer 包。 +- `GFramework.Godot.SourceGenerators` + - 同样复用这里的公共实现和共享约束。 + +这个目录当前 `IsPackable=false`，不作为独立安装包推广。对 NuGet 使用者来说，更实际的入口仍然是具体的 +`GeWuYou.GFramework.*.SourceGenerators` 包。 + +## 什么时候需要读这里 + +- 你在排查多个生成器共有的 diagnostics +- 你想确认“为什么不同生成器对命名冲突采用同一套规则” +- 你在扩展或维护生成器，而不是只消费它们 + +如果你的目标只是“选包并开始使用”，优先回到对应生成器模块 README 和文档专题页。 + +## 继续阅读 + +- [源码生成器总览](../docs/zh-CN/source-generators/index.md) +- [Core 源码生成器说明](../GFramework.Core.SourceGenerators/README.md) +- [CQRS 源码生成器说明](../GFramework.Cqrs.SourceGenerators/README.md) +- [Godot 源码生成器说明](../GFramework.Godot.SourceGenerators/README.md) diff --git a/GFramework.csproj b/GFramework.csproj index 00e67766..d4ba523d 100644 --- a/GFramework.csproj +++ b/GFramework.csproj @@ -4,7 +4,7 @@ GeWuYou.GFramework gewuyou GeWuYou.GFramework - 404 not found + Meta-package that aggregates GFramework.Core and GFramework.Game for a minimal runtime adoption path. Copyright © 2025 https://github.com/GeWuYou/GFramework https://github.com/GeWuYou/GFramework diff --git a/README.md b/README.md index 5fc94729..82a0c6bc 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,8 @@ - 第一次接触框架：[入门指南](docs/zh-CN/getting-started/index.md) - 想先跑一个最小例子：[快速开始](docs/zh-CN/getting-started/quick-start.md) +- 想先确认该装哪些包：[安装配置](docs/zh-CN/getting-started/installation.md) +- 想接入 AI-First 配置工作流：[配置系统](docs/zh-CN/game/config-system.md) / [VS Code 配置工具](docs/zh-CN/game/config-tool.md) - 已经知道要用哪个模块：直接进入对应模块的说明页 ## 模块地图 @@ -39,9 +41,9 @@ | 目录 | 定位 | 跟随入口 | | --- | --- | --- | -| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [Core.SourceGenerators 模块说明](GFramework.Core.SourceGenerators/README.md) | -| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [Godot.SourceGenerators 模块说明](GFramework.Godot.SourceGenerators/README.md) | -| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [源码生成器总览](docs/zh-CN/source-generators/index.md) | +| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [目录说明](GFramework.Core.SourceGenerators.Abstractions/README.md) | +| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [目录说明](GFramework.Godot.SourceGenerators.Abstractions/README.md) | +| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [目录说明](GFramework.SourceGenerators.Common/README.md) | ## 文档导航 @@ -64,7 +66,7 @@ ## 包选择 - `GeWuYou.GFramework` - 当前是聚合元包，只聚合 `GFramework.Core` 与 `GFramework.Game` 这两层运行时，适合快速试用。 + 当前是聚合元包，只聚合 `GFramework.Core` 与 `GFramework.Game` 这两层运行时；不会自动带上 `Cqrs`、`Godot` 或任何 Source Generator，适合快速试用或先起一个最小运行时骨架。 - `GeWuYou.GFramework.Core` 推荐的最小起步包。先从核心运行时开始，再按需叠加 `Cqrs`、`Game`、`Godot` 和 Source Generators。 - `GeWuYou.GFramework.*.Abstractions` 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 7f4dfa53..cbff3c31 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-037` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-038` - 当前阶段：`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 - - 当前批次只处理 `docs/zh-CN/contributing.md` 中最后 1 条既有代码块语言警告，避免重新扩张到大范围栏目巡检 - - 工作树当前仅有 1 个未提交文件、`4` added / `4` deleted lines；分支级 branch diff vs `origin/main` 仍为 `0` files，距离阈值有充足空间 - - 公开文档的 reader-facing 治理已基本收口，下一轮应优先确认 PR review 是否还有最新 latest-head 残留，而不是重新启动同模板批量修整 + - 当前批次已从“单点 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 侧当前优先修正文档失真与共享支撑层说明，而不是扩新导航 ## 当前状态摘要 @@ -28,6 +28,10 @@ - `2026-04-25` `GFramework.Core/README.md`、`GFramework.Ecs.Arch/README.md`、`GFramework.Game/README.md` 当前把 XML 阅读表统一收敛为“代表类型 + 阅读重点”，不再暴露日期、覆盖计数或 `已覆盖` 这类治理式字段。 - `2026-04-25` `docs/zh-CN/contributing.md` 中最后一个嵌套 fenced 示例已改写为转义围栏文本，现有 `validate-code-blocks.sh` 不再报告第 `631` 行警告。 - `2026-04-25` 全量 `docs/zh-CN` 验证已无剩余代码块语言警告；前一轮触达的 `tutorials`、`best-practices`、`troubleshooting`、`godot/resource` 等栏目结果保持有效。 +- `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` 的共享支撑层说明。 +- `2026-04-25` `GFramework.SourceGenerators.Common/README.md`、`GFramework.Core.SourceGenerators.Abstractions/README.md`、`GFramework.Godot.SourceGenerators.Abstractions/README.md` 已补齐本地目录说明，根 README 的“内部支撑模块”表可以直接跳到对应目录说明。 - `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。 - `Godot` runtime 与 generator 入口当前以 `GFramework.Godot/README.md`、 @@ -42,6 +46,7 @@ - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 `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 `#290` 当前 review 线程来自 bot，对 reader-facing 导航和文案一致性的期望比较细；本轮提交后仍需重新抓取 latest-head review，确认是否还有新的 open thread 或旧线程未自动关闭。 ## 归档指针 @@ -79,6 +84,20 @@ - 结果：通过；当前 `docs/zh-CN` 全量 frontmatter、链接与代码块校验均通过，不再保留既有代码块语言警告。 - `2026-04-25` `bun run build`（工作目录：`docs/`） - 结果：通过；`contributing.md` 的 Mermaid 示例改写后站点仍可正常构建，仅保留既有大 chunk warning。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` + - 结果：通过；`source-generators` 栏目触达页 frontmatter、链接与代码块校验均通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game` + - 结果：通过；新增 `config-tool.md` 与 `Game` 栏目触达页 frontmatter、链接与代码块校验均通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` + - 结果：通过；`CQRS` 页补充 `Request` / stream 变体与协程入口后链接和代码块校验通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/index.md` + - 结果：通过；首页 hero actions 与 feature 文案更新后 frontmatter、代码块校验通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md tools/gframework-config-tool/README.md GFramework.SourceGenerators.Common/README.md GFramework.Core.SourceGenerators.Abstractions/README.md GFramework.Godot.SourceGenerators.Abstractions/README.md` + - 结果：通过；根 README、config tool README 与新增 3 个 support README 的链接目标有效。 +- `2026-04-25` `dotnet build GFramework.csproj -c Release` + - 结果：通过；元包工程与聚合依赖可编译，输出 `357` 条既有 analyzer warnings，无新增错误。 +- `2026-04-25` `bun run build`（工作目录：`docs/`） + - 结果：通过；meta-package / config tool / source-generators / CQRS 多批次文档更新后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` - 结果：通过；`Godot` 资源页剩余 bare opening fence 已补齐语言标记。 - `2026-04-25` `bun run build`（工作目录：`docs/`） @@ -131,9 +150,10 @@ ## 下一步 -1. 提交当前 `contributing.md` 警告收口批次后，重新抓取 `$gframework-pr-review` 确认 PR `#290` 的 latest-head review 是否已清空 open thread。 -2. 若 review 已清空，则把下一轮文档治理切回“新问题发现”模式，不再围绕已清零的代码块语言警告做重复扫描。 -3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 +1. 提交当前项目级功能覆盖批次后，重新计算 branch diff vs `origin/main`，确认距离 `50` 文件阈值还有多少空间，再决定是否继续追加低风险文档切片。 +2. 提交完成后重新抓取 `$gframework-pr-review`，确认 PR `#290` 的 latest-head review 是否已清空 open thread。 +3. 若后续继续扩批，优先在已识别但尚未扩写的低风险 reader-facing 方向里选择下一组：config tool 更深的 adoption 示例、首页 / 安装页的进一步选包引导，或其它 repo-visible support surface 的本地说明补齐。 +4. 若后续分支继续调整 `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`、 +5. 若后续分支继续调整 `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 ad9fce68..4146f473 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,49 @@ ## 2026-04-25 +### 当前恢复点：RP-038 + +- 用户明确要求从“低效的单次批次”切到“循环跑到接近阈值”，并允许通过 subagent 避免主线程上下文过长；因此本轮把批处理目标从 PR `#290` 的单点收口扩展为“覆盖整个项目功能的 reader-facing 文档补齐”。 +- 先在主线程确认 critical path 仍是“选定低风险文档切片并控制 branch-size stop condition”，再委派 3 个 explorer 做只读巡检： + - source-generator support modules / 文档失真点 + - CQRS 文档覆盖缺口 + - repo-root / tooling / meta-package surface +- 接受的 explorer 结论： + - `CQRS` 当前不需要扩独立栏目；最小有用修复是补 `docs/zh-CN/core/cqrs.md` 对 `RequestBase`、stream command/query 与协程入口的说明。 + - source-generators 当前最有价值的是修正文档失真，并补清楚 `GFramework.SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` 的共享支撑层语义。 + - repo-root / tooling 当前最缺的是 meta-package / install surface、VS Code config tool adoption path，以及 repo-visible support module README。 +- 由此收敛出 5 组连续低风险批次： + - meta-package / 安装入口 + - config tool adoption + - source-generators 真实契约修正 + - CQRS `Request` / stream 覆盖补齐 + - generator support module README + +### 当前决策（RP-038） + +- 不把 `CQRS` 从 `Core` 导航中抽成新栏目；本轮优先修正 reader-facing 覆盖缺口，而不是引入新的站点结构。 +- 对 repo-visible support modules，不扩成新的 docs 栏目，而是在各目录本地补 `README.md` 说明“为什么存在、跟谁一起走、什么时候需要读这里”。 +- 对 config tool，不新建顶级 `tooling/` 栏目，而是挂到 `Game` 下，保持它与 `config-system` 的采用路径一致。 +- stop condition 仍按 `origin/main` 与 `50` changed files 追踪；本轮提交前工作树已触达 `18` 个文件，仍明显低于阈值。 + +### 当前验证（RP-038） + +- 文档栏目校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game` + - `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/index.md` + - 结果：通过；触达页 frontmatter、链接与代码块校验通过。 +- README / 链接校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md tools/gframework-config-tool/README.md GFramework.SourceGenerators.Common/README.md GFramework.Core.SourceGenerators.Abstractions/README.md GFramework.Godot.SourceGenerators.Abstractions/README.md` + - 结果：通过；根 README、config tool README 与新增 support README 的链接目标有效。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；站点可构建，仅保留既有大 chunk warning。 +- 元包编译： + - `dotnet build GFramework.csproj -c Release` + - 结果：通过；输出 `357` 条既有 analyzer warnings，无新增错误。 + ### 当前恢复点：RP-037 - 通过 `$gframework-batch-boot 50` 重新进入后，先按技能要求读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md`、active topic tracking / trace，并确认当前 worktree 仍映射到 `documentation-full-coverage-governance`。 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 9fc7eec6..bba97579 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -211,6 +211,7 @@ export default defineConfig({ items: [ { text: '概览', link: '/zh-CN/game/' }, { text: '内容配置系统', link: '/zh-CN/game/config-system' }, + { text: 'VS Code 配置工具', link: '/zh-CN/game/config-tool' }, { text: '数据管理', link: '/zh-CN/game/data' }, { text: '场景系统', link: '/zh-CN/game/scene' }, { text: 'UI 系统', link: '/zh-CN/game/ui' }, diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index 6a52639b..eaebf2fc 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -70,6 +70,16 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 这些目录当前不是独立消费模块，因此不单独维护站内 API 参考入口。它们的公开说明跟随所属模块 README 和 `source-generators` 栏目维护。 +更准确地说： + +- `*.SourceGenerators.Abstractions` + - 主要定义公开 attribute 和最小契约，供对应生成器与消费端项目共享。 +- `GFramework.SourceGenerators.Common` + - 主要提供共享生成器基类、通用 diagnostics，以及生成方法冲突等跨模块约束。 + +如果你在 `Core`、`CQRS`、`Game`、`Godot` 的生成器页面里遇到相似的 diagnostics 或冲突语义，优先把它理解为共享 +支撑层在复用同一套规则，而不是把这些目录当成新的安装入口。 + ## 使用方式 把本页当成“API 阅读导航”而不是“签名快照”： diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index 05c3b608..cbeea470 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -93,6 +93,9 @@ var playerId = await architecture.Context.SendRequestAsync( - `PublishAsync(...)` - `CreateStream(...)` +如果你在协程驱动的调用链里工作，`GFramework.Core` 还提供了 `CqrsCoroutineExtensions.SendCommandCoroutine(...)` +这类桥接入口，用来把 CQRS 调度接回协程系统。 + ## 统一请求模型 这套 runtime 不只处理 command，也统一处理： @@ -106,6 +109,30 @@ var playerId = await architecture.Context.SendRequestAsync( 新代码通常不需要再分别设计“命令总线”“查询总线”和另一套通知分发语义。 +## Request 与流式变体 + +除了最常见的 `Command` / `Query` / `Notification`，当前公开面还覆盖两类容易被忽略的入口： + +### 普通 Request + +如果你的请求不想再被读者预设成“命令”或“查询”，可以直接使用： + +- `RequestBase` +- `AbstractRequestHandler` + +它们仍然走统一的 `SendRequestAsync(...)` 调度入口，只是把语义保持在更中性的 `Request` 层。 + +### 流式 Command / Query + +如果你需要返回 `IAsyncEnumerable`，除了通用的 `IStreamRequest`，当前也提供更明确的专用契约： + +- `IStreamCommand` +- `IStreamQuery` +- `AbstractStreamCommandHandler` +- `AbstractStreamQueryHandler` + +这几类处理器最终仍然通过 `CreateStream(...)` 进入统一的 CQRS runtime，而不是另一套独立流式总线。 + ## 处理器注册与生成器协作 在标准 `Architecture` 启动路径中，CQRS runtime 会自动接入基础设施。你通常只需要在 `OnInitialize()` 里追加行为或额外程序集： @@ -176,14 +203,15 @@ RegisterCqrsPipelineBehavior>(); | 类型族 | 代表类型 | 建议先确认什么 | | --- | --- | --- | | `GFramework.Cqrs.Abstractions/Cqrs/` | `ICqrsRuntime`、`ICqrsHandlerRegistrar`、`IPipelineBehavior<,>`、`IRequestHandler<,>`、`Unit` | 请求、处理器和 runtime seam 的最小契约 | -| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `CommandBase`、`QueryBase`、`NotificationBase`、`ContextAwareCqrsExtensions` | 业务侧常用基类和上下文发送入口 | -| `GFramework.Cqrs/Cqrs/` | `AbstractCommandHandler<,>`、`AbstractQueryHandler<,>`、`AbstractNotificationHandler<>`、`LoggingBehavior<,>` | 默认处理器基类、上下文注入与行为管道 | +| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `CommandBase`、`QueryBase`、`NotificationBase`、`RequestBase`、`ContextAwareCqrsExtensions` | 业务侧常用基类和上下文发送入口 | +| `GFramework.Cqrs/Cqrs/` | `AbstractCommandHandler<,>`、`AbstractQueryHandler<,>`、`AbstractRequestHandler<,>`、`AbstractStreamCommandHandler<,>`、`AbstractStreamQueryHandler<,>`、`LoggingBehavior<,>` | 默认处理器基类、上下文注入、流式处理与行为管道 | | `GFramework.Cqrs` 根入口与 `Internal/` | `CqrsRuntimeFactory`、`ICqrsHandlerRegistry`、`CqrsHandlerRegistryAttribute`、`CqrsReflectionFallbackAttribute`、`DefaultCqrsRegistrationService` | runtime 创建入口、registry 协议、fallback 语义和程序集去重规则 | | `GFramework.Cqrs.SourceGenerators/Cqrs/` | `CqrsHandlerRegistryGenerator`、`RuntimeTypeReferenceSpec`、`OrderedRegistrationKind` | 生成注册器、精确 type lookup 和 fallback 诊断边界 | ## 继续阅读 -- 架构入口：[architecture](./architecture.md) -- 上下文入口：[context](./context.md) +- 架构入口：[架构与上下文](./architecture.md) +- 上下文入口：[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) diff --git a/docs/zh-CN/game/config-system.md b/docs/zh-CN/game/config-system.md index 081f2f54..9316c7d7 100644 --- a/docs/zh-CN/game/config-system.md +++ b/docs/zh-CN/game/config-system.md @@ -21,6 +21,8 @@ description: 说明 GFramework.Game 配置系统的定位、目录约定、生 - Source Generator 生成配置类型、表包装、单表注册/访问辅助，以及项目级聚合注册目录 - VS Code 插件提供配置浏览、raw 编辑、schema 打开、递归轻量校验和嵌套对象表单入口 +对应工具说明见：[VS Code 配置工具](./config-tool.md) + ## 推荐目录结构 ```text @@ -978,6 +980,8 @@ var hotReload = loader.EnableHotReload( ## VS Code 工具 +完整采用说明见：[VS Code 配置工具](./config-tool.md)。 + 仓库中的 `tools/gframework-config-tool` 当前提供以下能力： - 浏览 `config/` 目录 diff --git a/docs/zh-CN/game/config-tool.md b/docs/zh-CN/game/config-tool.md new file mode 100644 index 00000000..f1a4910f --- /dev/null +++ b/docs/zh-CN/game/config-tool.md @@ -0,0 +1,138 @@ +--- +title: VS Code 配置工具 +description: 说明 GFramework AI-First 配置工作流对应的 VS Code 工具入口、工作区约定、常用命令与使用边界。 +--- + +# VS Code 配置工具 + +`GFramework Config Tool` 是面向 AI-First 配置工作流的 VS Code 扩展。它不是新的运行时模块，而是把 +`config/`、`schemas/`、轻量校验、表单预览和批量编辑收敛到编辑器侧的一条辅助工作流。 + +如果你正在维护 `GFramework.Game` 的 YAML + JSON Schema 配置，这个工具通常比纯手写 YAML 更适合做日常浏览、 +校验和批量修改；如果你要做复杂嵌套结构或超出当前支持子集的 schema 设计，仍然应该回到原始 YAML 和 schema 文件。 + +## 适合什么时候用 + +- 你已经采用 `config/**/*.yaml` + `schemas/**/*.schema.json` +- 你希望在 VS Code 里快速浏览配置域和对应 schema +- 你需要批量修改同一配置域的顶层标量或标量数组字段 +- 你想先走表单预览，再决定是否回到 raw YAML + +不适合： + +- 项目不使用 `GFramework.Game` 的配置工作流 +- 需要完整 JSON Schema 编辑器，而不是当前仓库落地的稳定子集 +- 需要在编辑器里处理更深层对象数组嵌套，且不接受回退到 raw YAML + +## 工作区约定 + +默认目录约定是： + +```text +GameProject/ +├─ config/ +│ ├─ monster/ +│ │ ├─ slime.yaml +│ │ └─ goblin.yaml +│ └─ item/ +│ └─ potion.yaml +└─ schemas/ + ├─ monster.schema.json + └─ item.schema.json +``` + +扩展默认会把： + +- `config/` 视为配置根目录 +- `schemas/` 视为 schema 根目录 + +如果你的项目用了不同目录，可以通过工作区设置覆盖。 + +## 扩展当前提供什么 + +### Explorer 视图 + +扩展会在 VS Code Explorer 中提供一个独立视图，用来浏览配置域和配置文件。 + +### 常用命令 + +当前命令面向这几类操作： + +- 刷新配置树 +- 打开 raw YAML +- 打开对应 schema +- 打开轻量表单预览 +- 对单个配置域做批量编辑 +- 运行全量校验 + +如果你更关心“当前 schema 和 YAML 是否仍一致”，优先使用全量校验；如果你只是定位单个字段或注释，优先使用 +Explorer + 表单预览。 + +## 推荐工作流 + +### 1. 浏览配置与 schema + +先从 Explorer 里进入目标配置文件，再根据需要： + +- 打开 raw YAML +- 跳转到对应 schema +- 进入轻量表单预览 + +### 2. 先校验，再批量改 + +如果你准备改同一配置域下多份文件，推荐顺序是： + +1. 先运行全量校验 +2. 再进入配置域批量编辑 +3. 批量修改完成后回到 raw YAML 或表单确认结果 + +### 3. 嵌套结构优先分层处理 + +当前工具支持： + +- 顶层标量字段 +- 顶层标量数组 +- 嵌套对象字段 +- 对象数组 + +如果你进入更深层对象数组嵌套，当前更稳妥的做法通常是： + +1. 用 Explorer 找到目标文件 +2. 先看表单预览确认字段结构 +3. 再回到 raw YAML 完成最终编辑 + +## 工作区设置 + +当前公开设置只有两个： + +```json +{ + "gframeworkConfig.configPath": "config", + "gframeworkConfig.schemasPath": "schemas" +} +``` + +- `gframeworkConfig.configPath` + - 配置根目录，默认是 `config` +- `gframeworkConfig.schemasPath` + - schema 根目录，默认是 `schemas` + +## 当前边界 + +当前扩展重点覆盖的是仓库已经验证过的最小工作流： + +- 工作区默认只取第一个 workspace folder +- 校验聚焦仓库当前支持的 schema 子集 +- 表单预览支持对象数组，但更深的嵌套对象数组仍可能需要回退到 raw YAML +- 批量编辑当前聚焦顶层标量和顶层标量数组字段 + +因此，最稳妥的理解方式是： + +- 用它加速“浏览、定位、轻量校验、批量维护” +- 不把它当成完整替代 YAML / schema 编辑的唯一入口 + +## 继续阅读 + +- [游戏内容配置系统](./config-system.md) +- [Game 模块](./index.md) +- [安装配置](../getting-started/installation.md) diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 8e9030e3..e5913390 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -31,6 +31,7 @@ description: GFramework.Game family 的运行时入口、采用顺序与源码 - 配置与内容系统 - [配置系统](./config-system.md) + - [VS Code 配置工具](./config-tool.md) - 数据、设置、序列化与存储 - [数据系统](./data.md) - [设置系统](./setting.md) @@ -99,9 +100,10 @@ IStorage storage = new FileStorage("GameData", serializer); 1. [Core 入口](../core/index.md) 2. [配置系统](./config-system.md) -3. [数据系统](./data.md) -4. [设置系统](./setting.md) -5. [场景系统](./scene.md)或[UI 系统](./ui.md) +3. [VS Code 配置工具](./config-tool.md) +4. [数据系统](./data.md) +5. [设置系统](./setting.md) +6. [场景系统](./scene.md)或[UI 系统](./ui.md) ## 源码与 API 阅读入口 diff --git a/docs/zh-CN/getting-started/installation.md b/docs/zh-CN/getting-started/installation.md index d1864548..6f73b3de 100644 --- a/docs/zh-CN/getting-started/installation.md +++ b/docs/zh-CN/getting-started/installation.md @@ -26,6 +26,13 @@ GFramework 采用模块化设计，不同包提供不同的功能： 当前 NuGet 发布按模块拆分 source generator 包，不存在 `GeWuYou.GFramework.SourceGenerators` 聚合包。 +`GeWuYou.GFramework` 当前是聚合元包，只聚合： + +- `GFramework.Core` +- `GFramework.Game` + +它不会自动带上 `Cqrs`、`Godot` 或任何 `*.SourceGenerators` 包。如果你需要这些能力，请按模块单独安装。 + ## 安装方式 ### 1. 使用 .NET CLI（推荐） @@ -66,7 +73,7 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators ```xml - net6.0 + net8.0 @@ -110,14 +117,14 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators ### 运行时要求 -- **.NET 6.0** 或更高版本 -- **Godot 4.5+**（仅 Godot 项目） +- **.NET 8.0、9.0 或 10.0** +- **Godot 4.6.2**（仅 Godot 项目） ### 开发工具 - Visual Studio 2022 或 VS Code -- .NET 6.0 SDK -- Godot 4.5+（可选，仅 Godot 项目需要） +- .NET 8 SDK 或更高版本 +- Godot 4.6.2（可选，仅 Godot 项目需要） ## 项目配置 diff --git a/docs/zh-CN/index.md b/docs/zh-CN/index.md index 78577f56..7ce41a08 100644 --- a/docs/zh-CN/index.md +++ b/docs/zh-CN/index.md @@ -2,11 +2,11 @@ # https://vitepress.dev/reference/default-theme-home-page layout: home title: GFramework -description: 概览 GFramework 的模块能力、入门路径与主要中文文档入口。 +description: 概览 GFramework 的模块能力、安装选包路径，以及 Core、CQRS、Game、Godot 与配置工具入口。 hero: name: "GFramework" text: 面向游戏开发的模块化 C# 架构体系 - tagline: 基于清洁架构与 CQRS 思想构建，支持可扩展设计与多引擎集成 + tagline: 基于清洁架构与 CQRS 思想构建，覆盖运行时、源码生成器、Godot 集成与 AI-First 配置工作流 image: src: /logo.png alt: GFramework Logo @@ -15,25 +15,31 @@ hero: text: 快速开始 link: /zh-CN/getting-started/quick-start - theme: alt - text: 架构概览 - link: /zh-CN/getting-started + text: 安装与选包 + link: /zh-CN/getting-started/installation + - theme: alt + text: CQRS + link: /zh-CN/core/cqrs + - theme: alt + text: 配置工具 + link: /zh-CN/game/config-tool features: - title: 🏗 清洁架构分层 - details: 基于 Model–Controller–System–Utility 五层结构设计，实现职责清晰、可测试、可维护的代码组织方式。 + details: 基于 Model–Controller–System–Utility 五层结构组织运行时能力，适合先从 Core 起步，再逐层叠加 Game、CQRS 和引擎集成。 - - title: 🔧 CQRS 命令查询分离 - details: 通过类型安全的命令与查询系统构建业务流程，支持可扩展操作链与可撤销机制。 + - title: 🔧 CQRS 请求模型 + details: 提供 request、notification、pipeline、handler registry 与 source generator 协作路径，适合把新业务统一收敛到 CQRS runtime。 - - title: 📡 类型安全事件系统 - details: 提供高性能事件总线，实现模块间松耦合通信与可扩展的业务触发机制。 + - title: 🧭 模块化选包路径 + details: 支持按运行时、抽象层、源码生成器和引擎集成拆分安装，而不是先引入一个难以裁剪的大而全包。 - - title: 🎮 引擎集成层 - details: 核心层与引擎层解耦设计，当前提供 Godot 集成实现，支持节点扩展、协程桥接与对象池能力。 + - title: 🎮 Godot 集成 + details: 在保持 Core / Game 运行时边界的前提下，补齐节点扩展、场景与 UI 接线、协程桥接和生成器辅助。 - - title: 🔄 响应式属性系统 - details: 可绑定属性模型驱动 UI 更新与状态变化，构建声明式的数据响应流程。 + - title: 🧩 AI-First 配置工作流 + details: 通过 YAML + JSON Schema + Source Generator + VS Code 工具，把静态内容配置、校验、表单预览和批量编辑串成一条链路。 - title: ⚡ Roslyn 源码生成器 - details: 自动生成日志、枚举扩展与规则代码，减少样板代码并提升开发效率。 + details: 自动生成日志、上下文注入、配置类型、CQRS registry 和 Godot 辅助代码，并复用共享 diagnostics 约束生成行为。 --- diff --git a/docs/zh-CN/source-generators/context-get-generator.md b/docs/zh-CN/source-generators/context-get-generator.md index 71019990..b6c62237 100644 --- a/docs/zh-CN/source-generators/context-get-generator.md +++ b/docs/zh-CN/source-generators/context-get-generator.md @@ -34,13 +34,13 @@ Context Get 注入依赖 `[ContextAware]` 特性提供的上下文访问能力 | 特性 | 应用目标 | 功能描述 | 类型约束 | |------------------|------|------------------|------------------------------------| | `[GetModel]` | 字段 | 注入单个 Model 实例 | 必须实现 IModel | -| `[GetModels]` | 字段 | 注入 Model 集合 | IReadOnlyList\ | +| `[GetModels]` | 字段 | 注入 Model 集合 | 可赋值自 IReadOnlyList\ 的类型 | | `[GetSystem]` | 字段 | 注入单个 System 实例 | 必须实现 ISystem | -| `[GetSystems]` | 字段 | 注入 System 集合 | IReadOnlyList\ | +| `[GetSystems]` | 字段 | 注入 System 集合 | 可赋值自 IReadOnlyList\ 的类型 | | `[GetUtility]` | 字段 | 注入单个 Utility 实例 | 必须实现 IUtility | -| `[GetUtilities]` | 字段 | 注入 Utility 集合 | IReadOnlyList\ | +| `[GetUtilities]` | 字段 | 注入 Utility 集合 | 可赋值自 IReadOnlyList\ 的类型 | | `[GetService]` | 字段 | 注入单个服务实例 | 必须是引用类型 | -| `[GetServices]` | 字段 | 注入服务集合 | IReadOnlyList\ where T : class | +| `[GetServices]` | 字段 | 注入服务集合 | 可赋值自 IReadOnlyList\ 且 `T : class` 的类型 | | `[GetAll]` | 类 | 自动推断并注入所有符合类型的字段 | 智能推断 | ## 基础使用 @@ -248,9 +248,9 @@ public void TestController() | IModel 及其子类型 | 单实例注入 | `this.GetModel()` | | ISystem 及其子类型 | 单实例注入 | `this.GetSystem()` | | IUtility 及其子类型 | 单实例注入 | `this.GetUtility()` | -| IReadOnlyList\ | 集合注入 | `this.GetModels()` | -| IReadOnlyList\ | 集合注入 | `this.GetSystems()` | -| IReadOnlyList\ | 集合注入 | `this.GetUtilities()` | +| 可赋值自 IReadOnlyList\ 的字段类型 | 集合注入 | `this.GetModels()` | +| 可赋值自 IReadOnlyList\ 的字段类型 | 集合注入 | `this.GetSystems()` | +| 可赋值自 IReadOnlyList\ 的字段类型 | 集合注入 | `this.GetUtilities()` | ### 不自动推断的类型 @@ -735,13 +735,19 @@ public partial class Controller **A**: 不会。`[GetAll]` 只注入符合类型约束的字段： - 实现 IModel、ISystem、IUtility 接口的类型 -- 上述类型的 `IReadOnlyList` 集合 +- 上述类型的、可赋值自 `IReadOnlyList` 的集合字段 - 排除 Godot.Node 类型 - 排除 Service 类型 ### Q: 集合注入可以是 List\ 吗？ -**A**: 不可以。集合注入只支持 `IReadOnlyList` 类型，这是为了保证注入集合的不可变性。 +**A**: 不能直接写成普通 `List`。当前要求字段类型至少要能接受 `IReadOnlyList` 赋值，例如： + +- `IReadOnlyList` +- 更宽的只读集合接口或基类，只要生成结果能直接赋给字段 + +生成器的约束重点是“返回值必须能以 `IReadOnlyList` 形式安全赋给字段”，而不是要求你必须逐字写成 +`IReadOnlyList`。 ```csharp [ContextAware] @@ -751,7 +757,7 @@ public partial class Controller [GetModels] private IReadOnlyList _players = null!; - // ❌ 错误：不支持 + // ❌ 错误：不能接受 IReadOnlyList 赋值 [GetModels] private List _players = null!; } diff --git a/docs/zh-CN/source-generators/enum-generator.md b/docs/zh-CN/source-generators/enum-generator.md index 347329fb..752ab5a9 100644 --- a/docs/zh-CN/source-generators/enum-generator.md +++ b/docs/zh-CN/source-generators/enum-generator.md @@ -102,31 +102,6 @@ public enum GameState | GenerateIsMethods | bool | true | 是否为每个枚举值生成 IsX 方法 | | GenerateIsInMethod | bool | true | 是否生成 IsIn 方法 | -#### 未实现的选项 - -以下选项在属性定义中存在，但生成器当前版本**未实现**： - -- `GenerateHasMethod`：未实现 HasX 方法生成 -- `IncludeToString`：未实现 ToString 扩展方法 - -```csharp -// ❌ 以下选项不会生效 -[GenerateEnumExtensions( - GenerateIsMethods = true, - GenerateIsInMethod = true, - GenerateHasMethod = true, // 未实现，参数会被忽略 - IncludeToString = true // 未实现,参数会被忽略 -)] -public enum GameState -{ - Normal, - Paused, - GameOver -} -``` - -**注意**：这些选项计划在后续版本中实现，届时会更新文档说明。 - ### 只生成 IsX 方法 ```csharp @@ -175,7 +150,16 @@ public static bool IsNormal(this GameState value) if (state == GameState.Normal) { } ``` -### 3. 可读性提升 +### 3. 什么时候值得关闭某个开关 + +- 只想保留精确单值判断： + - 保留 `GenerateIsMethods = true` + - 关闭 `GenerateIsInMethod = false` +- 只想保留多值判断入口： + - 保留 `GenerateIsInMethod = true` + - 关闭 `GenerateIsMethods = false` + +### 4. 可读性提升 ```csharp // 使用生成的方法（推荐） diff --git a/docs/zh-CN/source-generators/get-node-generator.md b/docs/zh-CN/source-generators/get-node-generator.md index 50f007f3..c2c68126 100644 --- a/docs/zh-CN/source-generators/get-node-generator.md +++ b/docs/zh-CN/source-generators/get-node-generator.md @@ -83,7 +83,26 @@ private Label _scoreLabel = null!; 对文档来说，最关键的结论是： - `Auto` 在未给路径时默认走唯一名推断 -- 显式路径会结合 `Lookup` 决定最终生成的字符串 +- 一旦显式给了 `Path`，生成结果直接使用这个字符串，`Lookup` 不再改写它 + +可以直接按下面这张表理解当前行为： + +| `Path` | `Lookup` | 生成路径 | +| --- | --- | --- | +| 未设置 | `Auto` | `%FieldName` | +| 未设置 | `UniqueName` | `%FieldName` | +| 未设置 | `RelativePath` | `FieldName` | +| 未设置 | `AbsolutePath` | `/FieldName` | +| 已显式设置 | 任意值 | 原样使用显式路径 | + +例如： + +```csharp +[GetNode("HUD/ScoreLabel", Lookup = NodeLookupMode.AbsolutePath)] +private Label _scoreLabel = null!; +``` + +当前生成结果仍然会直接使用 `"HUD/ScoreLabel"`，不会因为 `Lookup = AbsolutePath` 被改写成 `"/HUD/ScoreLabel"`。 ### `Required` @@ -189,6 +208,7 @@ public override void _Ready() - 只有缺少 `_Ready()` 时才会自动补 override - `OnGetNodeReadyGenerated()` 只存在于自动补 `_Ready()` 的路径 - `Required = false` 会真实切换到 `GetNodeOrNull()` +- `Lookup` 只影响“未显式给路径时”的推断前缀；显式 `Path` 不会被二次改写 ## 推荐阅读 diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 75952ced..1e7cd077 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -20,6 +20,23 @@ 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 侧样板代码： @@ -55,6 +72,12 @@ GFramework 当前发布的生成器包是： 其他生成器包的安装模式相同。 +`GFramework.SourceGenerators.Common` 和两个 `*.SourceGenerators.Abstractions` 目录当前都跟随对应生成器模块维护： + +- 不是额外安装的独立包选择题 +- 主要用于承载 attribute、共享基类和跨生成器共用 diagnostics +- 读者只需要在排查 attribute 语义、冲突规则或生成失败原因时回到这些源码目录确认契约 + ## 这个栏目怎么读 ### Core 侧通用生成器 diff --git a/tools/gframework-config-tool/README.md b/tools/gframework-config-tool/README.md index 780518f4..05889fa4 100644 --- a/tools/gframework-config-tool/README.md +++ b/tools/gframework-config-tool/README.md @@ -2,26 +2,66 @@ VS Code extension for the GFramework AI-First config workflow. -## Current MVP +## Purpose + +This extension is the editor-side companion for the `GFramework.Game` config pipeline: + +- `config/**/*.yaml` +- `schemas/**/*.schema.json` +- source-generated config types and tables + +It is intended to speed up browsing, validation, lightweight form editing, and domain-level maintenance inside VS Code. +It is not a replacement for the runtime or generator packages, and it does not attempt to be a full JSON Schema editor. + +## Recommended Workspace Layout + +By default, the extension expects: + +```text +GameProject/ +├─ config/ +│ ├─ monster/ +│ │ ├─ slime.yaml +│ │ └─ goblin.yaml +│ └─ item/ +│ └─ potion.yaml +└─ schemas/ + ├─ monster.schema.json + └─ item.schema.json +``` + +## What It Adds + +### Explorer View - Browse config files from the workspace `config/` directory -- Open raw YAML files +- Group files by config domain - Open matching schema files from `schemas/` + +### File-Level Actions + +- Open raw YAML +- Open the matching schema +- Open a lightweight form preview + +### Domain-Level Actions + +- Batch edit one config domain across multiple files for top-level scalar and scalar-array fields +- Run validation across the current workspace config surface + +### Form / Validation Support + - Localize extension UI text in English and Simplified Chinese, including the form preview, prompts, and notifications -- Run lightweight schema validation for nested required fields, unknown nested fields, scalar types, scalar arrays, and - arrays of objects -- Open a lightweight form preview for nested object fields, object arrays, top-level scalar fields, and scalar arrays - Render existing YAML comments in the form preview and edit per-field YAML comments directly from the form - Jump from reference fields to the referenced schema, config domain, or direct config file when a reference value is present - Initialize empty config files from schema-derived example YAML -- Batch edit one config domain across multiple files for top-level scalar and scalar-array fields - Surface schema metadata such as `title`, `description`, `default`, `enum`, and `x-gframework-ref-table` in the lightweight editors ## Validation Coverage -The extension currently validates the repository's minimal config-schema subset: +The extension currently validates the repository's stable config-schema subset: - required properties in nested objects - unknown properties in nested objects @@ -30,6 +70,22 @@ The extension currently validates the repository's minimal config-schema subset: - arrays of objects whose items use the same supported subset recursively - scalar `enum` constraints and scalar-array item `enum` constraints +## Workspace Settings + +```json +{ + "gframeworkConfig.configPath": "config", + "gframeworkConfig.schemasPath": "schemas" +} +``` + +## Current Constraints + +- Multi-root workspaces use the first workspace folder +- Validation only covers the repository's current schema subset +- Form preview supports object-array editing, but nested object arrays inside array items still fall back to raw YAML +- Batch editing remains limited to top-level scalar fields and top-level scalar arrays + ## Local Testing ```bash @@ -46,15 +102,3 @@ bun install bun run package:vsix VSCE_PAT=your_marketplace_pat bun run publish:marketplace ``` - -## Current Constraints - -- Multi-root workspaces use the first workspace folder -- Validation only covers a minimal subset of JSON Schema -- Form preview supports object-array editing, but nested object arrays inside array items still fall back to raw YAML -- Batch editing remains limited to top-level scalar fields and top-level scalar arrays - -## Workspace Settings - -- `gframeworkConfig.configPath` -- `gframeworkConfig.schemasPath`