docs(source-generators): 补充生成器专题覆盖并更新进度

- 新增 Schema 配置生成器专题页，补充输入契约、生成物与诊断边界 - 更新 source-generators、API 参考与 CQRS 文档，说明共享支撑层阅读路线与 fallback 分层 - 更新 documentation-full-coverage-governance 的 tracking 和 trace，记录批次指标与验证结果
2026-05-06 16:16:44 +08:00 · 2026-04-30 09:50:48 +08:00 · 2026-04-30 09:50:48 +08:00 · 103b961e6f
commit 103b961e6f
parent 1c21df1414
8 changed files with 330 additions and 7 deletions
--- 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,10 +12,14 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-050`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-051`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，收口 `Game` / `Godot` 细页与少量 README 中残留的 reader-facing 措辞与标签问题
+  - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，在保持 reader-facing 口吻治理的同时，继续补 `source-generators` / `CQRS` 的公开专题覆盖率
+- `2026-04-30` 本轮恢复时确认当前 `HEAD` 与 `origin/main` 同步，committed diff 为 `0` files / `0` lines；因此本批次不再只做措辞收口，而是允许补新的公开专题页和入口链路
+- `2026-04-30` 本轮接受 2 个 explorer 的只读结论：其一，`GFramework.SourceGenerators.Common` 更适合作为 landing / API 入口内的共享排障层，而不是新的独立 public page；其二，`Cqrs.SourceGenerators` 当前主要缺口不是“没有入口”，而是现有专题页与 `core/cqrs.md` 对生成策略层级、fallback 精度和 `GF_Cqrs_001` 的解释不够 reader-facing
+- `2026-04-30` 本批次已新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并同步更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`，把 `Game.SourceGenerators` 的 schema 生成链路和 `Cqrs.SourceGenerators` 的定向 fallback 语义收敛成站内可见入口
+- 当前工作树相对 `origin/main` 已达到 `39` files / `2555` lines；仍低于 `50` 文件 stop condition，但后续若继续扩批，应优先提交本轮覆盖扩展后再开新批次
 - `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主
 - `2026-04-29` 上一批已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题
 - `2026-04-29` 本批次继续接受 2 个 explorer 的只读结论：一个负责 `game/data.md`、`game/storage.md`、`godot/ui.md` 的热点排序，一个负责 README reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写
@ -26,6 +30,9 @@
 ## 当前状态摘要

 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
+- `2026-04-30` source-generators 栏目当前已补出新的 `Schema 配置生成器` 专题页，并通过 landing、API 入口和侧栏把 `Game.SourceGenerators` 从“只在 `config-system.md` 侧面提到”提升到独立 reader-facing 入口。
+- `2026-04-30` `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 与 `docs/zh-CN/core/cqrs.md` 当前已明确“有 fallback != 退回整程序集盲扫”，并补充 direct registration、实现类型定向反射、精确 service type lookup 与程序集级 fallback 元数据之间的分层关系。
+- `2026-04-30` `docs/zh-CN/api-reference/index.md` 与 `source-generators/index.md` 当前把 `SourceGenerators.Common`、`*.SourceGenerators.Abstractions` 收敛为共享 diagnostics / attribute / 冲突规则的阅读入口，而不是新的安装包或维护者专题页。
 - `2026-04-29` 新一轮 batch boot 第 2 批次已进一步收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`：移除 “仓库和测试确认”“真实消费者 wiring”“CoreGrid 当前的做法”“优先看” 这类内部或生硬口吻，并把 CQRS 抽象层 README 的源文件列表改成契约类型族说明。
 - `2026-04-29` 新一轮 batch boot 已收口 `docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md` 与 `GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md` 的 reader-facing 文案：移除 `ai-libs`、旧文档对比、命令式跳转和原始路径标签。
 - `2026-04-29` 当前分支的 upstream `origin/docs/sdk-update-documentation` 已 gone；后续若继续批处理，应继续以 `origin/main` 作为 branch-size stop condition 的 authoritative baseline，而不是默认恢复旧 PR review 状态。
@ -70,6 +77,7 @@
 - `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。
 - 当前分支 upstream 已 gone；在重新建立 remote branch 或新的 PR 之前，不适合再把旧 PR `#299` 的 review 状态当作默认恢复信号。
 - 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；本轮仍是低风险措辞收口，但下一轮若继续深入 README 子系统地图或大段采用路径重写，review 面会明显扩大。
+- 当前工作树在 coverage 扩展后已接近 `$gframework-batch-boot 50` 的中后段窗口；如果继续新增 source-generator 或 README 专题，建议先提交本轮改动并重新计算 committed diff，再决定是否继续扩批。
 - `GFramework.Cqrs`、`GFramework.Cqrs.SourceGenerators`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 仍有若干源文件列表式“子系统地图”段落；这些已经接近结构级改写，不适合作为本轮剩余低风险批次继续机械推进。

 ## 归档指针
@ -91,6 +99,18 @@

 ## 最新验证

+- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md`
+  - 结果：通过；新增 `Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。
+- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`
+  - 结果：通过；source-generators landing 在补 `Schema 配置生成器` 与共享支撑层阅读路线后校验通过。
+- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`
+  - 结果：通过；`Cqrs` generator 专题页新增策略层级与 fallback 精度说明后校验通过。
+- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md`
+  - 结果：通过；`CQRS` 运行时页补充 generated registry 与 fallback 协作说明后校验通过。
+- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
+  - 结果：通过；API 入口页补充 `Game.SourceGenerators` 与共享 source-generator 支撑层阅读路线后校验通过。
+- `2026-04-30` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；新增 source-generators 专题页与侧栏入口后站点仍可构建，仅保留既有大 chunk warning。
 - `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`
  - 结果：通过；`game/data.md` 的 frontmatter、链接与代码块校验通过。
 - `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md`
@ -132,7 +152,7 @@

 ## 下一步

-1. 提交本轮第 2 批低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。
-2. 若继续下一批，优先挑选仍可“局部改句子”的页面或 README 标签问题；`Cqrs`、`Game.SourceGenerators`、`Ecs.Arch` 这类源文件列表式 README 应视作结构级专题，必要时单独开一轮更明确的写作目标。
+1. 提交本轮 source-generators / CQRS coverage 扩展批次，并在提交后重新计算 committed branch diff vs `origin/main`，确认是否仍适合继续在同一 `$gframework-batch-boot 50` 窗口内推进。
+2. 若继续下一批，优先挑选“已有 package README、但站内专题仍不足”的模块入口，例如 `README` 与现有 docs 之间的采用路径补链；避免把 `SourceGenerators.Common` 之类共享支撑层继续扩写成维护者导向的独立专题。
 3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。
 4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
--- 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,39 @@

 ## 2026-04-29

+### 当前恢复点：RP-051
+
+- 本轮按 `$gframework-batch-boot 50` 恢复后，先确认 `HEAD` 与 `origin/main` `79f9cb37`（`2026-04-29 22:59:12 +08:00`）同步，committed diff 为 `0` files / `0` lines，因此允许把批次目标从“低风险句子收口”提升为“补新的 docs coverage 入口”。
+- 主线程保留实现与验证，同时接受了 2 个 explorer 的只读结论：一条用于判断 `SourceGenerators.Common` 是否值得升成独立 public page，一条用于判断 `Cqrs.SourceGenerators` 的真实公开缺口。accepted 结论是：共享 source-generator 支撑层更适合补 landing / API 入口，而 `Cqrs.SourceGenerators` 应增强现有专题页对策略层级与 fallback 精度的解释。
+- 一个 worker 曾被短暂分配去草拟独立 `shared-support-modules` 页面，但在 explorer 结论返回后被中断；最终无文件写入，也没有并行实现遗留。
+- 实际落地的 coverage 扩展集中在 6 个文件：新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`。
+- docs 页面与恢复文档更新完成后，工作树相对 `origin/main` 已到 `39` files / `2555` lines；仍低于 `50` 文件 stop condition，但本轮已不再适合继续新开第三类 coverage 切片。
+
+### 当前决策（RP-051）
+
+- `Game.SourceGenerators` 当前公开缺口足够明确，因此直接补一张新的 reader-facing 专题页，专门解释 schema 输入契约、生成物形态、聚合注册入口和 `ConfigSchemaDiagnostics` 边界。
+- `SourceGenerators.Common`、`Core.SourceGenerators.Abstractions`、`Godot.SourceGenerators.Abstractions` 不提升为新的独立 public docs 页面，只在现有 landing / API 入口里补共享 diagnostics、attribute 契约与冲突规则的阅读路线。
+- `Cqrs.SourceGenerators` 不再新增第二张专题页，而是在现有 `cqrs-handler-registry-generator.md` 与 `core/cqrs.md` 内明确“有 fallback != 整程序集盲扫”、direct registration / reflected implementation / precise service type lookup / assembly fallback 的层级关系，以及 `GF_Cqrs_001` 的 reader-facing 判断顺序。
+
+### 当前验证（RP-051）
+
+- 页面校验：
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md`
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md`
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
+  - 结果：通过；本轮新增专题页与 4 个入口页 / 专题页校验全部通过。
+- 站点构建：
+  - `bun run build`（工作目录：`docs/`）
+  - 结果：通过；新增 `Schema 配置生成器` 侧栏入口后站点仍可构建，仅保留既有大 chunk warning。
+
+### 下一步（RP-051）
+
+1. 提交本轮 source-generators / CQRS coverage 扩展批次，并把 committed diff vs `origin/main` 重新写回 active tracking。
+2. 若继续同一主题，优先挑选“已有用户面 package，但站内专题仍需补链”的模块，而不是继续给共享支撑层单开页面。
+3. 在 remote branch / PR 恢复之前，继续把 `origin/main` + branch-size 指标当作唯一 batch stop condition。
+
 ### 当前恢复点：RP-050

 - 本轮继续按 `$gframework-batch-boot 50` 推进，并沿用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为唯一 branch-size baseline。
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@ -248,6 +248,7 @@ export default defineConfig({
              text: '源码生成器',
              items: [
                { text: '概览', link: '/zh-CN/source-generators/' },
+                { text: 'Schema 配置生成器', link: '/zh-CN/source-generators/schema-config-generator' },
                { text: '日志生成器', link: '/zh-CN/source-generators/logging-generator' },
                { text: '枚举扩展生成器', link: '/zh-CN/source-generators/enum-generator' },
                { text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' },
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -31,8 +31,8 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 | 模块族 | 先看什么 | 继续深入 | XML 文档关注点 |
 | --- | --- | --- | --- |
 | `Core` / `Core.Abstractions` | [Core 模块](../core/index.md) | [Core 抽象层说明](../abstractions/core-abstractions.md)、[快速开始](../getting-started/quick-start.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
-| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / generated registry / targeted fallback contract |
-| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md) | 配置、数据、设置、场景、UI、存储、序列化契约；其中 AI-First 配置工作流的正式支持边界以 Runtime + Generator 共享 schema 子集为准 |
+| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / generated registry / targeted fallback contract，以及生成注册器与定向补扫的协作边界 |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md)、[Schema 配置生成器](../source-generators/schema-config-generator.md) | 配置、数据、设置、场景、UI、存储、序列化契约，以及 schema 到生成代码的公开入口 |
 | `Godot` / `Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md) | [Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
 | `Ecs.Arch` / `Ecs.Arch.Abstractions` | [ECS 模块总览](../ecs/index.md) | [Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |

@ -78,6 +78,22 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 - `GFramework.SourceGenerators.Common`
  - 主要提供共享生成器基类、通用 diagnostics，以及生成方法冲突等跨模块约束。

+如果你要沿着 XML 文档和源码继续读，优先从下面这几类入口开始：
+
+- 共享 diagnostics
+  - `CommonDiagnostics`
+- 共享生成流程
+  - `AttributeClassGeneratorBase`
+  - `AttributeEnumGeneratorBase`
+- 共享冲突规则
+  - `GeneratedMethodConflictExtensions`
+
+这组入口更适合回答三类问题：
+
+- 为什么多个生成器都会要求宿主类型满足 `partial`
+- 为什么不同专题页会出现同一套生成方法名冲突诊断
+- 为什么多个生成器对候选筛选、属性解析和生成阶段采用相近流程
+
 ## 使用方式

 把本页当成“API 阅读导航”而不是“签名快照”：
--- a/docs/zh-CN/core/cqrs.md
+++ b/docs/zh-CN/core/cqrs.md
@ -184,6 +184,11 @@ protected override void OnInitialize()

 两者的共同点都是“优先消费 generated invoker 元数据，未命中时保留既有反射绑定作为兜底”，而不是要求业务侧切换到另一套 runtime 入口。

+对接入方来说，更关键的 reader-facing 语义是：安装 `Cqrs.SourceGenerators` 后，不要求“所有 handler 都能被生成代码直接引用”才有收益。
+即使仍有 fallback，runtime 也会先消费 generated registry，再只对剩余 handler 做定向补扫；只有旧版 marker 语义或空 fallback 元数据才会退回整程序集扫描。
+`Type` fallback、按名称恢复的 fallback，以及 mixed fallback 只影响补扫精度，不改变
+`RegisterCqrsHandlersFromAssembly(...)` 或 `RegisterCqrsHandlersFromAssemblies(...)` 的接法。
+
 `Cqrs.SourceGenerators` 的专题入口见[CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)。

 ## Pipeline Behavior
--- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md
+++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md
@ -124,11 +124,46 @@ RegisterCqrsHandlersFromAssemblies(
 - 其余场景统一回退到字符串元数据，避免 mixed 场景漏注册
 - 只有在 runtime 提供 `CqrsReflectionFallbackAttribute` 合同时，才允许发射依赖 fallback 的结果

+## 生成策略层级
+
+把这个生成器理解成“静态注册 or 整程序集扫描”的二选一，会低估它的收益。当前策略实际上分成四层：
+
+1. 直接静态注册
+   - handler 接口和实现类型都能被生成代码安全引用
+2. 实现类型定向反射查找
+   - handler 接口还能精确表达，但实现类型只能在运行时按具体类型名恢复
+3. service type 精确运行时查找
+   - handler 接口本身也需要运行时构造，但仍能把查找范围收窄到具体 service type
+4. 程序集级 fallback 元数据
+   - 只有前面几层都无法覆盖的剩余 handler，才交给 `CqrsReflectionFallbackAttribute`
+
+这意味着安装生成器后，并不要求“所有 handler 都可直接引用”才有收益。很多只能部分静态表达的项目，仍然可以把大部分注册路径前移到编译期，再对少数复杂类型做定向补扫。
+
+## 哪些场景通常不会直接退回整程序集扫描
+
+下列类型形态经常仍然能保留精细化注册，而不是立刻退回整程序集盲扫：
+
+| 场景 | 常见结果 |
+| --- | --- |
+| 私有嵌套 handler，但对外 handler 接口仍可直接引用 | 生成器改为按实现类型定向反射查找 |
+| 响应或参数里包含需要运行时恢复的隐藏类型 | 生成器改为精确 service type runtime lookup |
+| mixed 场景里同时存在可直接引用和仅能按名称恢复的 fallback handlers | 生成器拆分 `Type` 元数据和字符串元数据，减少后续字符串回查 |
+| 响应类型写成 `dynamic` | 生成器会按 `System.Object` 归一化，而不是发射非法的 `typeof(dynamic)` |
+
+相反，pointer、function-pointer 这类无法安全重建的类型形态，不属于这里承诺的精确生成边界。
+
 如果当前编译环境缺少这个 fallback 合同，而某些 handler 又必须依赖它，生成器会报：

 - `GF_Cqrs_001`

 这条诊断的含义不是“某个 handler 写错了”，而是“当前 runtime 合同不足以安全承载这轮生成结果”。
+遇到它时，优先按这个顺序判断：
+
+1. 当前消费端是否已经引用支持 `CqrsReflectionFallbackAttribute` 的 `GFramework.Cqrs` runtime
+2. 当前项目里是否存在只能部分静态表达的 handler 类型
+3. 如果确实不想引入 fallback 合同，是否需要把这类 handler 改成更容易被生成器直接引用的公开形态
+
+`CqrsReflectionFallbackAttribute` 出现也不等于“运行时一定回到整程序集扫描”。只有 fallback 元数据为空、或旧版只保留 marker 语义时，runtime 才会退回整程序集补扫；当元数据里已经带了具体 `Type` 或类型名时，runtime 会优先按这些剩余 handler 做定向补扫。

 ## 源码与 API 阅读入口

--- a/docs/zh-CN/source-generators/index.md
+++ b/docs/zh-CN/source-generators/index.md
@ -25,7 +25,7 @@ GFramework 当前发布的生成器包是：
 | 使用场景 | 安装包 | 继续阅读 |
 | --- | --- | --- |
 | 减少日志、上下文注入、模块自动注册等 Core 侧样板代码 | `GeWuYou.GFramework.Core.SourceGenerators` | [Core 模块](../core/index.md)、[日志生成器](./logging-generator.md)、[ContextAware 生成器](./context-aware-generator.md) |
-| 把 `schemas/**/*.schema.json` 生成成配置类型和表包装 | `GeWuYou.GFramework.Game.SourceGenerators` | [配置系统](../game/config-system.md)、[VS Code 配置工具](../game/config-tool.md) |
+| 把 `schemas/**/*.schema.json` 生成成配置类型和表包装 | `GeWuYou.GFramework.Game.SourceGenerators` | [Schema 配置生成器](./schema-config-generator.md)、[配置系统](../game/config-system.md)、[VS Code 配置工具](../game/config-tool.md) |
 | 让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围 | `GeWuYou.GFramework.Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md)、[CQRS Handler Registry 生成器](./cqrs-handler-registry-generator.md) |
 | 在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助 | `GeWuYou.GFramework.Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md)、[Godot 项目生成器](./godot-project-generator.md)、[GetNode 生成器](./get-node-generator.md) |

@ -94,6 +94,15 @@ GFramework 当前发布的生成器包是：
 - 再根据 attribute 或 diagnostics 回到对应专题页
 - 只有在排查生成失败原因时，才继续下钻到这些共享支撑目录

+如果你更关心“多个生成器为什么会给出一致的 `partial` 要求、方法名冲突错误或 trace 诊断”，可以把这三类目录当成共享排障层来理解：
+
+- `*.SourceGenerators.Abstractions`
+  - 先看公开 attribute 能写什么，再回到对应专题页确认生成语义
+- `GFramework.SourceGenerators.Common`
+  - 先看共享 diagnostics，再看公共生成基类和冲突规则
+
+这层仍然不是新的安装入口。只有在排查生成失败、对比多个生成器的共同约束，或准备扩展生成器时，才值得继续下钻。
+
 ## 阅读路线

 ### Core 侧通用生成器
@ -107,6 +116,8 @@ GFramework 当前发布的生成器包是：

 ### Game / CQRS 相关生成器

+- schema 到配置类型 / 表包装 / 聚合注册的生成路径：
+  - [Schema 配置生成器](./schema-config-generator.md)
 - 配置 schema 生成与运行时接法：
  - [配置系统](../game/config-system.md)
  - 读者若需要确认共享 schema 子集、关闭对象边界或复杂组合关键字的限制，应以该页为准，而不是只从本页推断支持范围
@ -138,6 +149,8 @@ GFramework 当前发布的生成器包是：
  - 安装 `Game` + `Game.SourceGenerators`
 - 需要 CQRS 生成注册表：
  - 安装 `Cqrs` + `Cqrs.SourceGenerators`
+- 需要排查跨生成器共享的 diagnostics 或 attribute 契约：
+  - 保持原有 `*.SourceGenerators` 包入口不变，再回到本页的共享支撑模块说明

 ## 对应模块入口

--- a/docs/zh-CN/source-generators/schema-config-generator.md
+++ b/docs/zh-CN/source-generators/schema-config-generator.md
@ -0,0 +1,200 @@
+---
+title: Schema 配置生成器
+description: 说明 GFramework.Game.SourceGenerators 如何从 schema 生成配置类型、表包装和聚合注册入口。
+---
+
+# Schema 配置生成器
+
+`GFramework.Game.SourceGenerators` 会把消费者项目里的 `schemas/**/*.schema.json` 读入编译期管线，并生成：
+
+- 强类型配置类型
+- 对应的表包装类型
+- 单表绑定辅助代码
+- 聚合注册目录与 `RegisterAllGeneratedConfigTables(...)` 扩展入口
+
+如果你当前目标是“先把配置系统接进项目”，先看 [游戏内容配置系统](../game/config-system.md)。这页更适合在你已经决定使用
+`Game.SourceGenerators` 之后，继续确认 schema 输入契约、生成结果和常见诊断边界。
+
+## 它解决什么问题
+
+相比只写 `YAML` 和运行时加载代码，这个生成器把三件事前移到了编译期：
+
+- 把 schema 转成 `Config` 类型，让业务代码直接拿到强类型字段和 XML 文档
+- 为运行时表生成包装层，让 `Get`、`TryGet`、按字段查找等入口保持稳定
+- 汇总当前项目中所有 schema 的注册信息，避免 schema 数量增长后继续手写逐表注册
+
+这也是 `GFramework.Game` 配置运行时、VS Code 配置工具和 schema 约束能够共享同一份结构定义的基础。
+
+## 最小接入路径
+
+NuGet 安装保持运行时包与生成器包版本一致，并把生成器声明为编译期依赖：
+
+```xml
+<ItemGroup>
+  <PackageReference Include="GeWuYou.GFramework.Game" Version="x.y.z" />
+  <PackageReference Include="GeWuYou.GFramework.Game.SourceGenerators"
+                    Version="x.y.z"
+                    PrivateAssets="all"
+                    ExcludeAssets="runtime" />
+</ItemGroup>
+```
+
+默认情况下，包内 `targets` 会自动把 `schemas/**/*.schema.json` 纳入 `AdditionalFiles`。如果你的 schema 目录不是
+`schemas/`，可以在项目文件里覆盖：
+
+```xml
+<PropertyGroup>
+  <GFrameworkConfigSchemaDirectory>GameSchemas</GFrameworkConfigSchemaDirectory>
+</PropertyGroup>
+```
+
+## 输入约定
+
+### schema 根对象
+
+当前生成器要求每个 schema 都满足这些基本约束：
+
+- 顶层 `type` 必须是 `object`
+- 必须声明必填 `id` 字段
+- `id` 目前只支持 `integer` 和 `string`
+- schema 文件名与属性名都必须能稳定映射到合法的 C# 标识符
+
+最小示例：
+
+```json
+{
+  "title": "Monster Config",
+  "type": "object",
+  "required": ["id", "name"],
+  "properties": {
+    "id": {
+      "type": "integer"
+    },
+    "name": {
+      "type": "string"
+    }
+  }
+}
+```
+
+### 路径与索引元数据
+
+除了标准 JSON Schema 字段，当前还支持几个会直接影响生成结果的扩展元数据：
+
+- `x-gframework-config-path`
+  - 覆盖默认配置目录；值必须是相对路径，且不能包含 `.`、`..` 或绝对路径段
+- `x-gframework-index`
+  - 为顶层必填、非主键、非引用的标量字段生成 `FindBy...` / `TryFindFirstBy...` 查找入口
+- `x-gframework-ref-table`
+  - 为字段补充跨表引用语义，并把这部分信息写入生成的绑定元数据
+
+如果某个字段不满足 lookup index 的安全条件，生成器会直接报诊断，而不是静默生成一个容易失真的查询入口。
+
+### 当前稳定约束子集
+
+从源码和快照测试看，当前共享子集已经覆盖：
+
+- 标量、嵌套对象、对象数组、标量数组
+- `default`、`enum`、`const`
+- `minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf`
+- `minLength`、`maxLength`、`pattern`
+- `format`
+  - 当前稳定字符串子集是 `date`、`date-time`、`duration`、`email`、`time`、`uri`、`uuid`
+- `minItems`、`maxItems`、`uniqueItems`、`contains`、`minContains`、`maxContains`
+- `minProperties`、`maxProperties`
+- `dependentRequired`、`dependentSchemas`、`allOf`
+- 面向对象约束的 `if` / `then` / `else`
+
+这些约束并不一定都会改变生成类型的形状，但会被保留到生成代码文档和绑定元数据里，方便运行时与工具链共享。
+
+## 会生成什么
+
+以 `monster.schema.json` 为例，当前生成器会形成四组稳定输出：
+
+### 1. 配置类型
+
+例如 `MonsterConfig`。它承载 schema 字段到 C# 属性的映射，以及对应的 XML 文档。
+
+### 2. 表包装类型
+
+例如 `MonsterTable`。它包装运行时 `IConfigTable<TKey, TValue>`，并在需要时提供生成的查找入口：
+
+```csharp
+public sealed partial class MonsterTable : IConfigTable<int, MonsterConfig>
+{
+    public MonsterConfig Get(int key) { ... }
+
+    public IReadOnlyList<MonsterConfig> FindByName(string value) { ... }
+
+    public bool TryFindFirstByName(string value, out MonsterConfig? result) { ... }
+}
+```
+
+如果字段声明了 `x-gframework-index`，生成器会优先使用延迟构建的只读索引；否则按当前表快照做确定性的线性扫描，以保持和热重载后的运行时数据一致。
+
+### 3. 单表绑定辅助
+
+例如 `MonsterConfigBindings`。这里会保留单表注册所需的表名、schema 路径、配置路径和引用元数据，方便项目侧继续组合自己的启动逻辑。
+
+### 4. 聚合注册目录
+
+当一个项目里有多个 schema 时，生成器还会汇总出 `GeneratedConfigCatalog` 与聚合扩展：
+
+```csharp
+loader.RegisterAllGeneratedConfigTables();
+```
+
+如果你需要按表传入额外比较器或做更细粒度控制，还可以使用带 `GeneratedConfigRegistrationOptions` 的重载。
+
+## 运行时如何消费这些输出
+
+最常见的消费路径是把生成器输出交给 `GameConfigBootstrap` 或 `YamlConfigLoader`：
+
+```csharp
+using GFramework.Game.Config;
+using GFramework.Game.Config.Generated;
+
+var bootstrap = new GameConfigBootstrap(
+    new GameConfigBootstrapOptions
+    {
+        RootPath = configRootPath,
+        ConfigureLoader = static loader => loader.RegisterAllGeneratedConfigTables()
+    });
+```
+
+当你需要继续手动拼装运行时，也可以直接用单表绑定或聚合目录做自己的注册封装。这时建议把“启动生命周期”和“业务读取入口”分开，继续沿用
+[游戏内容配置系统](../game/config-system.md) 里的 `GameConfigHost` / `GameConfigRuntime` 模板。
+
+## 常见诊断边界
+
+当前 `ConfigSchemaDiagnostics` 暴露的错误主要分成四类：
+
+- schema 根对象或 JSON 读入失败
+  - 例如 `GF_ConfigSchema_001`、`GF_ConfigSchema_002`
+- 主键与类型映射不合法
+  - 例如 `GF_ConfigSchema_003`、`GF_ConfigSchema_005`
+- 生成标识符或路径元数据不安全
+  - 例如 `GF_ConfigSchema_006`、`GF_ConfigSchema_007`
+- 额外约束元数据不合法
+  - 例如 `GF_ConfigSchema_008` 到 `GF_ConfigSchema_014`
+
+这些边界由 `GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorTests.cs` 和快照测试共同覆盖。遇到生成失败时，优先先看诊断 ID，再回头核对 schema 本身是否超出当前公开子集。
+
+## 什么时候优先看这页
+
+适合：
+
+- 你想确认一个 schema 字段会生成哪些 C# 入口
+- 你要排查 `x-gframework-index`、路径元数据或标识符冲突
+- 你在做项目级聚合注册，希望知道 `GeneratedConfigCatalog` 和 `RegisterAllGeneratedConfigTables(...)` 的边界
+
+不适合：
+
+- 你只是第一次接入配置运行时
+- 你更关心 `GameConfigBootstrap`、热重载、Godot 资源路径或 VS Code 配置工具
+
+这些采用问题分别回到：
+
+- [游戏内容配置系统](../game/config-system.md)
+- [VS Code 配置工具](../game/config-tool.md)
+- [源码生成器总览](./index.md)