Merge pull request #292 from GeWuYou/docs/sdk-update-documentation

docs: clarify meta-package scope, source generator contracts, and add Game config tool documentation
2026-05-10 19:56:45 +08:00 · 2026-04-26 09:41:36 +08:00 · 2026-04-26 09:41:36 +08:00 · 3446896118
commit 3446896118
parent 0c7552e629 65d3634181
21 changed files with 698 additions and 108 deletions
--- a/GFramework.Core.SourceGenerators.Abstractions/README.md
+++ 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)
--- a/GFramework.Godot.SourceGenerators.Abstractions/README.md
+++ 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)
--- a/GFramework.SourceGenerators.Common/README.md
+++ 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)
--- a/GFramework.csproj
+++ b/GFramework.csproj
@ -4,7 +4,7 @@
        <PackageId>GeWuYou.GFramework</PackageId>
        <Authors>gewuyou</Authors>
        <Product>GeWuYou.GFramework</Product>
-        <Description>404 not found</Description>
+        <Description>Meta-package that aggregates GFramework.Core and GFramework.Game for a minimal runtime adoption path.</Description>
        <Copyright>Copyright © 2025</Copyright>
        <RepositoryUrl>https://github.com/GeWuYou/GFramework</RepositoryUrl>
        <PackageProjectUrl>https://github.com/GeWuYou/GFramework</PackageProjectUrl>
--- 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`
--- 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,14 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-036`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-040`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 继续以最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）作为 baseline，当前只收口 PR `#290` latest-head review 仍然成立的 reader-facing 文档问题
-  - 已用 `$gframework-pr-review` 重新抓取 PR `#290`（`docs/sdk-update-documentation`），确认 `coderabbitai[bot]` 与 `greptile-apps[bot]` 仍各有 `1` 条 open thread，测试汇总保持 `2156 passed`
-  - 本轮未提交变更聚焦 3 个点：移除 `API 参考` 侧栏里的跨栏目重复入口、统一 3 个 source generator 侧栏标签与目标页标题、删除 `Core` / `Ecs.Arch` / `Game` README 中残留的 XML 覆盖基线表达
-  - 当前批次仍属于低风险 reader-facing 文档治理，但已经从批量“普查”切换为按 PR review 精确收口
-  - 若本轮收口并提交后仍存在 review 线程，应重新抓取最新 PR 状态，再决定是否继续扩展到其他未触达 README 或 docs 巡检点
+  - 继续以最新 `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` 术语

 ## 当前状态摘要

@ -27,7 +27,15 @@
 - `2026-04-25` 已重新抓取 PR `#290` 并确认：latest reviewed commit 为 `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181`，open thread 聚焦在 `docs/.vitepress/config.mts` 的侧栏重复 / 标签不一致，以及 `GFramework.Core`、`GFramework.Ecs.Arch`、`GFramework.Game` README 的 reader-facing 表格残留治理字段。
 - `2026-04-25` `docs/.vitepress/config.mts` 已保留 `source-generators` 栏目自有子页导航，但不再让 `api-reference` 侧栏重复跳回 `core`、`game`、`godot`、`ecs` 等独立栏目入口。
 - `2026-04-25` `GFramework.Core/README.md`、`GFramework.Ecs.Arch/README.md`、`GFramework.Game/README.md` 当前把 XML 阅读表统一收敛为“代表类型 + 阅读重点”，不再暴露日期、覆盖计数或 `已覆盖` 这类治理式字段。
- `2026-04-25` `docs/zh-CN/tutorials`、`best-practices`、`troubleshooting`、`contributing`、`godot/resource` 的前一轮 reader-facing 与代码块标记治理已保持有效；本轮不再扩批这些同模板切片。
+- `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` `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-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,8 +50,8 @@
 - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
  `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用前一轮“只补 opening fence”规则自动改写。
- PR `#290` 当前 review 线程来自 bot，对 reader-facing 导航和文案一致性的期望比较细；本轮提交后仍需重新抓取 latest-head review，确认是否还有新的 open thread 或旧线程未自动关闭。
+- `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。
+- PR `#292` 当前 review 线程仍主要来自 CodeRabbit，对 reader-facing 文案和文档入口连通性要求较细；本轮提交后仍需重新抓取 latest-head review，确认 open thread 是否已自动关闭。

 ## 归档指针

@ -62,6 +70,8 @@

 - `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
  - 结果：通过；PR `#290` 处于 `OPEN`，latest head commit `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181` 有 `2` 条 open thread（CodeRabbit `1`、Greptile `1`），测试汇总为 `2156 passed`，无 failed checks。
+- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
+  - 结果：通过；PR `#292` 处于 `OPEN`，latest head commit `b96565ffa367bade30f44c2d4e8955143fbff85e` 有 `2` 条 CodeRabbit open thread，测试汇总为 `2156 passed`，无 failed tests；另有 `Title check` inconclusive，属于 PR 标题元数据问题，不是仓库文件阻塞。
 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md`
  - 结果：通过；本轮 3 个模块 README 调整后链接目标仍然有效。
 - `2026-04-25` `bun run build`（工作目录：`docs/`）
@ -75,7 +85,25 @@
 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md`
  - 结果：通过；错误输出与完整错误信息块补齐为 `text` 后页面验证通过。
 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md`
-  - 结果：通过，但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告；不属于本轮自动补标规则可安全收口的范围。
+  - 结果：通过；嵌套 fenced 示例已改写为转义围栏文本，`docs/zh-CN/contributing.md` 不再保留代码块语言警告。
+- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
+  - 结果：通过；当前 `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/`）
@ -125,15 +153,18 @@
    `1` 条 Greptile open thread，无 failed checks，测试汇总为 `2156 passed`。
 - `2026-04-25` `bun run build`（工作目录：`docs/`）
  - 结果：通过；`docs/zh-CN/api-reference/index.md` 的站内入口标签统一为语义化写法后站点仍可正常构建，仅保留既有大 chunk warning。
- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
-  - 结果：通过；本轮触达页面的 frontmatter、链接与代码块校验均通过，脚本仅继续报告仓库中既有页面的“代码块缺少语言标记”警告。
+- `2026-04-26` `bun run test`（工作目录：`tools/gframework-config-tool/`）
+  - 结果：通过；`122` 个测试全部通过，说明 README 收口没有影响该工具现有测试面。
+- `2026-04-26` `bun run package:vsix`（工作目录：`tools/gframework-config-tool/`）
+  - 结果：通过；成功生成 `gframework-config-tool-0.0.3.vsix`，满足本轮工具模块的最小 build validation。

 ## 下一步

-1. 完成本轮修改后先跑 `bun run build`（工作目录 `docs/`）与受影响 README 链接校验，再提交当前 PR review 收口批次。
-2. 提交完成后重新抓取 `$gframework-pr-review` 确认 PR `#290` 的 latest-head review 是否已清空 open thread，再决定是否继续巡检其他 reader-facing 文档。
-3. 若后续继续处理公开文档，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得做结构化改写，而不是继续沿用“只补 opening fence”的自动批处理规则。
-4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
+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`、
   `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
-5. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
+6. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
   `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。
--- 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,7 +1,124 @@
 # Documentation Full Coverage Governance Trace

+## 2026-04-26
+
+### 当前恢复点：RP-040
+
+- 本轮继续从 `$gframework-pr-review` 恢复，沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并重新抓取 PR `#292` 的 latest-head review。
+- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#292` 最新 reviewed commit 为 `d3d62cf4541063c46458f88eea0f5acd1b4503f9`，failed checks 为 `0`，测试汇总仍为 `2156 passed`；剩余 `2` 条 CodeRabbit open thread 都落在 `tools/gframework-config-tool/README.md`。
+- 本地逐项复核后确认：缺少 `docs/zh-CN` 链接的评论已经过期，因为 README 当前已有 `Documentation` 章节；仍成立的是补最小接入路径，以及统一 `stable config-schema subset` / `current schema subset` 术语。
+
+### 当前决策（RP-040）
+
+- 接受当前 latest-head review 中仍然成立的两项 README 收口：新增 `Quick Start` 最小接入路径，并统一校验支持范围术语。
+- 不对已经过期的“缺少中文文档入口链接”线程做额外扩展，只在本地结果里保留“已验证为 stale”的结论，等待后续 PR review 刷新反映最新状态。
+- 继续遵守 active topic 的恢复要求，在同一轮里同步更新 tracking / trace，并对直接受影响的工具模块执行最小验证。
+
+### 当前验证（RP-040）
+
+- PR review 抓取：
+  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
+  - 结果：通过；PR `#292` 处于 `OPEN`，latest head review 还有 `2` 条 CodeRabbit open thread，failed checks 为 `0`，测试汇总为 `2156 passed`。
+- 工具 README 收口：
+  - `tools/gframework-config-tool/README.md`
+  - 结果：已新增 `Quick Start` 段落，并把 `Validation Coverage` 术语统一为 `current schema subset`。
+- 工具测试：
+  - `bun run test`（工作目录：`tools/gframework-config-tool/`）
+  - 结果：通过；`122` 个测试全部通过。
+- 工具打包：
+  - `bun run package:vsix`（工作目录：`tools/gframework-config-tool/`）
+  - 结果：通过；成功生成 `gframework-config-tool-0.0.3.vsix`，确认工具模块可完成最小打包验证。
+
 ## 2026-04-25

+### 当前恢复点：RP-039
+
+- 本轮从 `$gframework-pr-review` 重新进入，先按仓库规则读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` 与 active topic tracking / trace，并继续使用显式 `--git-dir` / `--work-tree` 绑定确认当前分支为 `docs/sdk-update-documentation`。
+- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#292` 最新 reviewed commit 为 `b96565ffa367bade30f44c2d4e8955143fbff85e`，latest head review 仅剩 `2` 条 CodeRabbit open thread，无 failed tests；唯一 failed check 为 `Title check` inconclusive，属于 PR 标题文案元数据提示。
+- 本地逐项复核后，两条 review 仍成立且都属于低风险 reader-facing 修正：
+  - `docs/zh-CN/source-generators/index.md` 的“共享支撑模块”段落中，句式“对读者更重要的判断是”略拗口。
+  - `tools/gframework-config-tool/README.md` 缺少通往 `docs/zh-CN/game/config-tool.md` 的中文接入文档入口。
+
+### 当前决策（RP-039）
+
+- 接受这两条 latest-head review，并限定本轮只做文案可读性与 README 入口补链，不扩展到未被当前 review 指向的其它页面。
+- `Title check` 不通过仓库文件修复；保持在本轮结果中显式记录，等待后续通过 GitHub PR 标题更新处理。
+- 继续沿用 active topic 的治理要求，在同一变更里同步更新 tracking / trace，保证后续从 PR review 恢复时能直接看到最新 commit 与剩余风险。
+
+### 当前验证（RP-039）
+
+- PR review 抓取：
+  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
+  - 结果：通过；PR `#292` 处于 `OPEN`，latest head review 还有 `2` 条 CodeRabbit open thread，测试汇总为 `2156 passed`，无 failed tests，另有 `Title check` inconclusive。
+
+### 当前恢复点：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`。
+- 使用显式 `git --git-dir=<repo>/.git/worktrees/GFramework-update-documentation --work-tree=<worktree-root>` 绑定确认 baseline 采用 `origin/main` `79934f7`（`2026-04-25 16:15:55 +08:00`）；branch diff vs baseline 当前为 `0` files，工作树仅有本批次改动。
+- 全量运行 `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` 后确认 reader-facing 文档仅剩 `docs/zh-CN/contributing.md:631` 这一条既有代码块语言警告，适合作为单文件低风险批次收口。
+- 将 `docs/zh-CN/contributing.md` 的 Mermaid 示例从“真实嵌套 triple-backtick”改写为“外层 fenced block + 内层转义围栏文本”，避免当前 `validate-code-blocks.sh` 的简单 `^```` 状态机把内层 closing fence 误判成缺语言标记的新 opening fence。
+
+### 当前决策（RP-037）
+
+- 当前批处理目标收敛为“消除 `contributing.md` 中最后一个剩余代码块语言 warning”，不再继续扩展到别的栏目页。
+- 继续沿用 `origin/main` 作为 branch-size stop condition 基线，主指标仍是 `50` changed files；本批次只新增 1 个工作树文件，远未逼近阈值。
+- 对这类“文档中展示 Markdown 代码块”的示例，优先选择仓库现有校验脚本可稳定识别的转义文本写法，而不是依赖嵌套 fenced block 的解析细节。
+
+### 当前验证（RP-037）
+
+- 文档单文件校验：
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md`
+  - 结果：通过；`docs/zh-CN/contributing.md` 不再报告第 `631` 行代码块语言警告。
+- 文档全量校验：
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
+  - 结果：通过；当前 `docs/zh-CN` 的 frontmatter、链接与代码块校验全部通过。
+- 站点构建：
+  - `bun run build`（工作目录：`docs/`）
+  - 结果：通过；站点仍可构建，仅保留既有大 chunk warning。
+
 ### 当前恢复点：RP-036

 - 本轮从 `$gframework-pr-review` 重新进入，目标不再是扩批，而是核对 PR `#290` latest-head review 仍未关闭的 reader-facing 文档问题。
--- 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' },
--- 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 阅读导航”而不是“签名快照”：
--- a/docs/zh-CN/contributing.md
+++ b/docs/zh-CN/contributing.md
@ -622,15 +622,15 @@ await architecture.SendCommandAsync(new AttackCommand

 使用 Mermaid 或 ASCII 图表说明复杂概念：

-```markdown
-```mermaid
+````markdown
+\`\`\`mermaid
 graph TD
    A[Controller] --&gt; B[Command]
    B --&gt; C[System]
    C --&gt; D[Model]
-```
+\`\`\`

-```
+````

 ## PR 流程

--- 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<TInput, TResponse>`
+- `AbstractRequestHandler<TRequest, TResponse>`
+
+它们仍然走统一的 `SendRequestAsync(...)` 调度入口，只是把语义保持在更中性的 `Request` 层。
+
+### 流式 Command / Query
+
+如果你需要返回 `IAsyncEnumerable<T>`，除了通用的 `IStreamRequest<TResponse>`，当前也提供更明确的专用契约：
+
+- `IStreamCommand<TResponse>`
+- `IStreamQuery<TResponse>`
+- `AbstractStreamCommandHandler<TCommand, TResponse>`
+- `AbstractStreamQueryHandler<TQuery, TResponse>`
+
+这几类处理器最终仍然通过 `CreateStream(...)` 进入统一的 CQRS runtime，而不是另一套独立流式总线。
+
 ## 处理器注册与生成器协作

 在标准 `Architecture` 启动路径中，CQRS runtime 会自动接入基础设施。你通常只需要在 `OnInitialize()` 里追加行为或额外程序集：
@ -176,14 +203,15 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
 | 类型族 | 代表类型 | 建议先确认什么 |
 | --- | --- | --- |
 | `GFramework.Cqrs.Abstractions/Cqrs/` | `ICqrsRuntime`、`ICqrsHandlerRegistrar`、`IPipelineBehavior<,>`、`IRequestHandler<,>`、`Unit` | 请求、处理器和 runtime seam 的最小契约 |
-| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `CommandBase<TInput, TResponse>`、`QueryBase<TInput, TResponse>`、`NotificationBase<TInput>`、`ContextAwareCqrsExtensions` | 业务侧常用基类和上下文发送入口 |
-| `GFramework.Cqrs/Cqrs/` | `AbstractCommandHandler<,>`、`AbstractQueryHandler<,>`、`AbstractNotificationHandler<>`、`LoggingBehavior<,>` | 默认处理器基类、上下文注入与行为管道 |
+| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `CommandBase<TInput, TResponse>`、`QueryBase<TInput, TResponse>`、`NotificationBase<TInput>`、`RequestBase<TInput, TResponse>`、`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)
--- 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/` 目录
--- a/docs/zh-CN/game/config-tool.md
+++ 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)
--- 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 阅读入口

--- 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
 <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
@ -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 项目需要）

 ## 项目配置

--- 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 约束生成行为。
 ---
--- 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\<IModel\>            |
+| `[GetModels]`    | 字段   | 注入 Model 集合      | 可赋值自 IReadOnlyList\<IModel\> 的类型 |
 | `[GetSystem]`    | 字段   | 注入单个 System 实例   | 必须实现 ISystem                       |
-| `[GetSystems]`   | 字段   | 注入 System 集合     | IReadOnlyList\<ISystem\>           |
+| `[GetSystems]`   | 字段   | 注入 System 集合     | 可赋值自 IReadOnlyList\<ISystem\> 的类型 |
 | `[GetUtility]`   | 字段   | 注入单个 Utility 实例  | 必须实现 IUtility                      |
-| `[GetUtilities]` | 字段   | 注入 Utility 集合    | IReadOnlyList\<IUtility\>          |
+| `[GetUtilities]` | 字段   | 注入 Utility 集合    | 可赋值自 IReadOnlyList\<IUtility\> 的类型 |
 | `[GetService]`   | 字段   | 注入单个服务实例         | 必须是引用类型                            |
-| `[GetServices]`  | 字段   | 注入服务集合           | IReadOnlyList\<T\> where T : class |
+| `[GetServices]`  | 字段   | 注入服务集合           | 可赋值自 IReadOnlyList\<T\> 且 `T : class` 的类型 |
 | `[GetAll]`       | 类    | 自动推断并注入所有符合类型的字段 | 智能推断                               |

 ## 基础使用
@ -248,9 +248,9 @@ public void TestController()
 | IModel 及其子类型              | 单实例注入 | `this.GetModel<T>()`     |
 | ISystem 及其子类型             | 单实例注入 | `this.GetSystem<T>()`    |
 | IUtility 及其子类型            | 单实例注入 | `this.GetUtility<T>()`   |
-| IReadOnlyList\<IModel\>   | 集合注入  | `this.GetModels<T>()`    |
-| IReadOnlyList\<ISystem\>  | 集合注入  | `this.GetSystems<T>()`   |
-| IReadOnlyList\<IUtility\> | 集合注入  | `this.GetUtilities<T>()` |
+| 可赋值自 IReadOnlyList\<IModel\> 的字段类型   | 集合注入  | `this.GetModels<T>()`    |
+| 可赋值自 IReadOnlyList\<ISystem\> 的字段类型  | 集合注入  | `this.GetSystems<T>()`   |
+| 可赋值自 IReadOnlyList\<IUtility\> 的字段类型 | 集合注入  | `this.GetUtilities<T>()` |

 ### 不自动推断的类型

@ -735,13 +735,19 @@ public partial class Controller
 **A**: 不会。`[GetAll]` 只注入符合类型约束的字段：

 - 实现 IModel、ISystem、IUtility 接口的类型
- 上述类型的 `IReadOnlyList<T>` 集合
+- 上述类型的、可赋值自 `IReadOnlyList<T>` 的集合字段
 - 排除 Godot.Node 类型
 - 排除 Service 类型

 ### Q: 集合注入可以是 List\<T\> 吗？

-**A**: 不可以。集合注入只支持 `IReadOnlyList<T>` 类型，这是为了保证注入集合的不可变性。
+**A**: 不能直接写成普通 `List<T>`。当前要求字段类型至少要能接受 `IReadOnlyList<T>` 赋值，例如：
+
+- `IReadOnlyList<T>`
+- 更宽的只读集合接口或基类，只要生成结果能直接赋给字段
+
+生成器的约束重点是“返回值必须能以 `IReadOnlyList<T>` 形式安全赋给字段”，而不是要求你必须逐字写成
+`IReadOnlyList<T>`。

 ```csharp
 [ContextAware]
@ -751,7 +757,7 @@ public partial class Controller
    [GetModels]
    private IReadOnlyList<IPlayerModel> _players = null!;

-    // ❌ 错误：不支持
+    // ❌ 错误：不能接受 IReadOnlyList<T> 赋值
    [GetModels]
    private List<IPlayerModel> _players = null!;
 }
--- 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
 // 使用生成的方法（推荐）
--- 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<T>()`
+- `Lookup` 只影响“未显式给路径时”的推断前缀；显式 `Path` 不会被二次改写

 ## 推荐阅读

--- 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 侧通用生成器
--- 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 current schema subset:

 - required properties in nested objects
 - unknown properties in nested objects
@ -30,6 +70,37 @@ 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"
+}
+```
+
+## Quick Start
+
+1. Install the extension in VS Code and open the workspace that contains your `config/` and `schemas/` directories.
+2. Keep the default workspace layout, or set `gframeworkConfig.configPath` and `gframeworkConfig.schemasPath` to your
+   project-specific paths.
+3. Open the `GFramework Config` explorer view and select a config file or domain.
+4. Run validation first to confirm the current YAML files still match the supported schema subset.
+5. Open the lightweight form preview or domain batch editing actions, then fall back to raw YAML for deeper nested edits
+   when needed.
+
+## Documentation
+
+- Chinese adoption guide: [`docs/zh-CN/game/config-tool.md`](../../docs/zh-CN/game/config-tool.md)
+- Related config runtime guide: [`docs/zh-CN/game/config-system.md`](../../docs/zh-CN/game/config-system.md)
+
+## 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 +117,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`