docs(governance): 收口公开文档治理口径

- 更新 AGENTS.md、DOCUMENTATION_STANDARDS.md 与 gframework-doc-refresh 规则，禁止在公开文档中暴露 inventory、覆盖基线与恢复点 - 修复 Core、Game、Ecs.Arch 与 abstractions 栏目中的 XML 覆盖表述，改为面向使用者的源码阅读入口 - 补充 contributor 页面 frontmatter，并统一 landing page、验证基线等内部术语为读者导向表达 - 更新 documentation-full-coverage-governance tracking 与 trace，记录 -batch-boot 75 基线、验证结果和下一步
2026-05-06 16:16:44 +08:00 · 2026-04-24 08:31:23 +08:00 · 2026-04-24 08:31:23 +08:00 · 66395739dc
commit 66395739dc
parent 2de57f5fde
18 changed files with 208 additions and 97 deletions
--- a/.agents/skills/_shared/DOCUMENTATION_STANDARDS.md
+++ b/.agents/skills/_shared/DOCUMENTATION_STANDARDS.md
@ -40,6 +40,18 @@

 如果 `ai-libs/` 与当前源码或测试冲突，以当前仓库实现为准，并在文档里写明迁移或兼容边界。

+## 公开文档边界
+
+- `README.md` 与 `docs/**` 面向框架使用者，不面向治理执行者。
+- 不要把 inventory、覆盖基线、恢复点、批处理阈值、review 线程、待补审计波次等内部治理信息写进公开页面。
+- XML、README、测试与 `ai-libs/` 证据可以驱动文档决策，但公开页面只能输出读者真正需要的内容：
+  - 模块边界
+  - 最小接入路径
+  - 推荐阅读顺序
+  - 源码 / XML / API 的入口提示
+- 如果确实需要保留治理基线、盘点结果或后续治理计划，把它写到 `ai-plan/**` 或其他 contributor-only 记录里。
+- 当页面需要引用 XML 文档时，写“应优先查看哪些类型、命名空间或契约，以及为什么”，不要写覆盖数量、盘点日期或“已覆盖 / 未覆盖”状态。
+
 ## Markdown 规则

 ### 泛型与 HTML 转义
@ -83,6 +95,12 @@ description: 1-2 句话描述当前页面解决什么问题
 3. 再补 API reference
 4. 最后才补教程

+## 用户页检查点
+
+- 用户读完页面后，应知道怎么采用、该看哪几个入口，而不是知道当前治理批次做到哪一轮。
+- 如果一段内容删掉日期、数量、基线、治理术语后就失去价值，它大概率不该出现在公开文档里。
+- 表格优先表达“何时看什么、解决什么问题”，不要表达“当前盘点覆盖到哪里”。
+
 ## 验证清单

 - [ ] frontmatter 正确
--- a/.agents/skills/gframework-doc-refresh/SKILL.md
+++ b/.agents/skills/gframework-doc-refresh/SKILL.md
@ -173,6 +173,10 @@ Use this exact priority:

 - Prefer correcting the adoption path over expanding page count.
 - Do not copy wording from outdated docs just to keep page volume.
+- Public docs must stay reader-facing. Do not write inventory, coverage baseline, recovery-point, batch-metric, review
+  backlog, or audit-wave wording into `README.md` or `docs/**`.
+- If XML or audit evidence is relevant, translate it into reader guidance such as “which types to inspect first” or
+  “which entry points define the contract”, instead of exposing counts, dates, or governance status.
 - Escape generics outside code blocks.
 - Keep internal links real and current.
 - Mark code blocks with explicit languages.
--- a/AGENTS.md
+++ b/AGENTS.md
@ -312,6 +312,11 @@ bash scripts/validate-csharp-naming.sh

 - Update the relevant `README.md` or `docs/` page when behavior, setup steps, architecture guidance, or user-facing
  examples change.
+- Public documentation under `README.md` and `docs/**` MUST stay reader-facing. Do not publish governance-only content
+  such as inventory tables, coverage baselines, review queues, batch metrics, recovery points, trace summaries, or
+  “this still needs a later audit wave” notes in those user-facing pages.
+- Governance-only material such as XML audit snapshots, documentation remediation baselines, backlog status, and
+  recovery metadata belongs in `ai-plan/**` or other contributor-only artifacts, not in public docs.
 - Treat `ai-libs/` as a read-only third-party source reference area.
 - Code under `ai-libs/**` exists for comparison, tracing, design study, and behavior verification; do not modify it
  unless the user explicitly asks to sync or update that third-party snapshot.
@ -323,6 +328,9 @@ bash scripts/validate-csharp-naming.sh
 - The main documentation site lives under `docs/`, with Chinese content under `docs/zh-CN/`.
 - Keep code samples, package names, and command examples aligned with the current repository state.
 - Prefer documenting behavior and design intent, not only API surface.
+- When a public page references XML docs or API coverage, convert that evidence into reader-facing guidance: explain
+  which types, namespaces, or entry points readers should inspect and why, instead of exposing audit counts or
+  governance terminology.
 - When a feature is added, removed, renamed, or substantially refactored, contributors MUST update or create the
  corresponding user-facing integration documentation in `docs/zh-CN/` in the same change.
 - For integration-oriented features such as the AI-First config system, documentation MUST cover:
--- 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,11 +12,11 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-023`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-024`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本
-  - 继续按 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险导航 / 渲染热点
+  - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明
+  - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险公开文案与导航热点
  - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
  - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性
  - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/`
@ -60,10 +60,23 @@
  为 `24` 个文件、`264` 行，仍低于 `$gframework-batch-boot 75` 的停止阈值；但剩余命中已主要是正文语义性提及，不再适合作为同类批处理。
 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
  文件缺陷。
+- `2026-04-24` 根据用户反馈完成一轮“公开文档边界”治理，并继续按 `$gframework-batch-boot 75` 向前推进：
+  - 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与
+    `.agents/skills/gframework-doc-refresh/SKILL.md` 中新增硬约束，明确禁止把 inventory、覆盖基线、恢复点、
+    review backlog、治理批次等 contributor-only 内容写进 `README.md` 与 `docs/**`
+  - 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、
+    `abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、
+    `ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 中的 XML 覆盖表述改写为面向读者的“源码阅读入口”
+  - 顺手收口 `api-reference/index.md`、`contributor/development-environment.md` 与
+    `source-generators/*.md` 中的内部口吻用语，例如 `landing page`、`验证基线`、`目标类型基线`
+  - focused validator 已覆盖本轮触达的 `13` 个公开文档页面并全部通过；站点构建 `cd docs && bun run build`
+    已通过，仅保留既有大 chunk warning
+- 当前分支 `HEAD` 仍与 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）对齐；在提交本轮工作前，
+  工作树待提交范围为 `16` 个文件、`224` changed lines，距离 `$gframework-batch-boot 75` 的停止阈值仍很远。

 ## 当前风险

- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理仍以“类型声明级基线”为主，不等于成员级契约全审计。
+- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 `ai-plan/**`，不应再暴露到公开文档。
 - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
  `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
@ -79,6 +92,22 @@

 ## 最新验证

+- `2026-04-24` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
+  - 结果：失败；暴露出仓库既有的 `53` 个历史文档问题（大量缺少 frontmatter、既有坏链与未标语言代码块），不由本轮改动引入，因此本轮改用 focused validator 证明任务级结果。
+- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
+  - 结果：通过；确认 `Core` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。
+- `2026-04-24` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
+  - 结果：通过；确认 `Game` 模块的 README、landing、topic 与 fallback docs 入口仍可解析。
+- `2026-04-24` focused validator（逐个校验本轮触达页面）
+  - 结果：通过；`docs/zh-CN/abstractions/core-abstractions.md`、
+    `abstractions/ecs-arch-abstractions.md`、`abstractions/game-abstractions.md`、
+    `api-reference/index.md`、`contributor/development-environment.md`、`core/cqrs.md`、`core/index.md`、
+    `ecs/arch.md`、`ecs/index.md`、`game/index.md`、
+    `source-generators/bind-node-signal-generator.md`、
+    `source-generators/cqrs-handler-registry-generator.md`、
+    `source-generators/get-node-generator.md` 的 frontmatter / links / code blocks 全部通过。
+- `2026-04-24` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；仅保留既有大 chunk warning。
 - `2026-04-23` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
  - 结果：通过；PR `#272` 处于 `OPEN`，latest head commit 存在 1 条 Greptile open thread，定位到
    `docs/zh-CN/godot/setting.md:75` 的 inline code HTML entity 渲染问题。
@ -99,7 +128,7 @@

 ## 下一步

-1. 若继续执行文档治理批处理，优先改做标题锚点、站内链接和少量非导航型裸路径引用的逐页复核，而不是继续按统一模板机械替换。
+1. 若继续执行 `$gframework-batch-boot 75`，优先改做标题锚点、站内链接和少量内部术语残留的逐页复核，而不是回到大范围模板化替换。
 2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
   常见分支阈值场景。
 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.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,5 +1,55 @@
 # Documentation Full Coverage Governance Trace

+## 2026-04-24
+
+### 当前恢复点：RP-024
+
+- 根据用户反馈，将本轮目标重定义为“清理公开文档中的治理盘点式内容，并把同类约束补进仓库规范与 doc-refresh skill”。
+- 用户随后补充明确使用 `$gframework-batch-boot 75`，因此继续沿用 `origin/main` 作为固定基线，并把 `75` changed
+  files 作为主停止条件。
+- 本轮执行的修复：
+  - 在 `AGENTS.md`、`.agents/skills/_shared/DOCUMENTATION_STANDARDS.md` 与
+    `.agents/skills/gframework-doc-refresh/SKILL.md` 中新增公开文档边界规则，禁止把 inventory、覆盖基线、
+    恢复点、review backlog 和治理批次写入 `README.md` 与 `docs/**`
+  - 将 `docs/zh-CN/core/index.md`、`core/cqrs.md`、`game/index.md`、
+    `abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`、`ecs/index.md`、
+    `ecs/arch.md`、`abstractions/ecs-arch-abstractions.md` 的 XML 覆盖 / inventory 段落改写成读者导向的源码阅读入口
+  - 继续收口 `api-reference/index.md`、`contributor/development-environment.md` 与
+    `source-generators/*.md` 中的内部术语，例如 `landing page`、`验证基线`、`目标类型基线`
+  - 为 `docs/zh-CN/contributor/development-environment.md` 补齐 frontmatter，使其满足当前文档规范
+
+### 当前决策（RP-024）
+
+- 公开文档只承载采用路径、阅读入口、模块边界和可验证示例；治理盘点、覆盖状态和恢复点一律留在 `ai-plan/**`。
+- 当 XML 治理结果需要体现在公开文档里时，只输出“优先看哪些类型 / 命名空间 / 契约以及为什么”，不输出计数、日期或状态表。
+- `$gframework-batch-boot 75` 的基线采用 `origin/main`（`2de57f5`，`2026-04-23T23:03:40+08:00`）。
+- 由于当前 `HEAD` 仍与 `origin/main` 对齐，分支级 diff 暂时仍为 `0`；提交前工作树待提交范围为 `16` 个文件、
+  `224` changed lines，因此本轮仍远低于 `75` 文件阈值。
+
+### 当前验证（RP-024）
+
+- 同类治理内容巡检：
+  - `rg -n 'XML Inventory|XML 覆盖基线|XML 状态|基线状态|盘点|治理优先级|审计入口|覆盖基线|恢复点|验证基线|目标类型基线|目标字段基线|类型审计|契约审计|源码 / API' docs/zh-CN README.md -g '*.md'`
+  - 结果：公开页已无同类命中；剩余 `inventory` 命中仅来自正常代码示例变量名。
+- skill 自检：
+  - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
+  - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game`
+  - 结果：均通过；代表模块的 README / docs 入口映射仍有效。
+- 全量 docs 校验：
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
+  - 结果：失败；暴露 `53` 个仓库既有历史问题（缺少 frontmatter、坏链、未标语言代码块），不属于本轮改动。
+- focused validator：
+  - 逐个校验本轮触达的 `13` 个公开文档页面
+  - 结果：全部通过。
+- 站点构建：
+  - `bun run build`（工作目录：`docs/`）
+  - 结果：通过；仅保留既有大 chunk warning。
+
+### 下一步
+
+1. 继续执行 `$gframework-batch-boot 75` 时，优先排查少量公开页里的内部工程术语残留、标题锚点和站内链接热点。
+2. 若后续需要大范围补 frontmatter / code fence language，应单独开一个新的低风险文档治理批次，而不是混入模块语义刷新。
+
 ## 2026-04-23

 ### 当前恢复点：RP-023
--- a/docs/zh-CN/abstractions/core-abstractions.md
+++ b/docs/zh-CN/abstractions/core-abstractions.md
@ -1,6 +1,6 @@
 ---
 title: Core Abstractions
-description: GFramework.Core.Abstractions 的契约边界、包关系与 XML 阅读重点。
+description: GFramework.Core.Abstractions 的契约边界、包关系与源码阅读重点。
 ---

 # Core Abstractions
@ -70,29 +70,28 @@ public sealed class DiagnosticsFeature

 ## XML 阅读重点

-如果你在做契约审计、采用设计或扩展适配，优先核对这些类型族的 XML 文档：
+如果你在做契约确认、采用设计或扩展适配，优先核对这些类型族的 XML 文档：

 - 架构与模块入口：`IArchitecture`、`IArchitectureContext`、`IServiceModule`
 - 运行时基础设施：`IIocContainer`、`ILogger`、`IResourceManager`、`IConfigurationManager`
 - 状态与并发能力：`IStateMachine`、`IStore`、`IAsyncKeyLockManager`、`ITimeProvider`
 - 迁移与组合边界：`ICommandExecutor`、`IQueryExecutor`、`ICqrsRuntime`

-## XML 覆盖基线
+## 契约族阅读入口

-下面这份 inventory 记录的是 `2026-04-22` 对 `GFramework.Core.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 /
-内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常与生命周期说明仍需要后续波次继续细化。
+如果你要回到源码 XML 文档确认契约，请优先看下面这些族群：

-| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `Architectures/` | `12/12` 个类型声明已带 XML 注释 | `IArchitecture`、`IArchitectureContext`、`IArchitectureServices`、`IServiceModule` | 看架构上下文、服务访问面与模块安装 / 生命周期约束 |
-| `Lifecycle/` `Registries/` | `8/8` 个类型声明已带 XML 注释 | `ILifecycle`、`IAsyncInitializable`、`IRegistry<T, TR>`、`KeyValueRegistryBase<TKey, TValue>` | 看初始化 / 销毁阶段和注册表抽象边界 |
-| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncCommand<TResult>`、`IQueryExecutor`、`ICqrsRuntime` | 看旧命令 / 查询接口与新请求模型之间的兼容和迁移边界 |
-| `Events/` `Property/` | `10/10` 个类型声明已带 XML 注释 | `IEventBus`、`IEventFilter<T>`、`IBindableProperty<T>`、`IReadonlyBindableProperty<T>` | 看事件传播、过滤、解绑对象和属性订阅语义 |
-| `State/` `StateManagement/` | `15/15` 个类型声明已带 XML 注释 | `IStateMachine`、`IAsyncState`、`IStore<TState>`、`IStoreMiddleware<TState>` | 看状态机契约与 Store 的 reducer / middleware / diagnostics 边界 |
-| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `17/17` 个类型声明已带 XML 注释 | `IYieldInstruction`、`ICoroutineStatistics`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` | 看调度模型、时间源、暂停栈和异步锁契约 |
-| `Resource/` `Pool/` `Logging/` `Localization/` | `27/27` 个类型声明已带 XML 注释 | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`IStructuredLogger`、`ILocalizationManager` | 看资源 / 池化 / 日志 / 本地化这些基础设施的宿主责任 |
-| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage`、`IVersioned` | 看配置、环境、序列化和持久化边界，以及谁负责具体实现 |
-| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 看基础角色接口、辅助值对象和架构属性键的复用方式 |
+| 契约族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| `Architectures/` | `IArchitecture`、`IArchitectureContext`、`IArchitectureServices`、`IServiceModule` | 架构上下文、服务访问面与模块安装 / 生命周期约束 |
+| `Lifecycle/` `Registries/` | `ILifecycle`、`IAsyncInitializable`、`IRegistry<T, TR>`、`KeyValueRegistryBase<TKey, TValue>` | 初始化 / 销毁阶段和注册表抽象边界 |
+| `Command/` `Query/` `Cqrs/` | `ICommandExecutor`、`IAsyncCommand<TResult>`、`IQueryExecutor`、`ICqrsRuntime` | 旧命令 / 查询接口与新请求模型之间的兼容和迁移边界 |
+| `Events/` `Property/` | `IEventBus`、`IEventFilter<T>`、`IBindableProperty<T>`、`IReadonlyBindableProperty<T>` | 事件传播、过滤、解绑对象和属性订阅语义 |
+| `State/` `StateManagement/` | `IStateMachine`、`IAsyncState`、`IStore<TState>`、`IStoreMiddleware<TState>` | 状态机契约与 Store 的 reducer / middleware / diagnostics 边界 |
+| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `IYieldInstruction`、`ICoroutineStatistics`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` | 调度模型、时间源、暂停栈和异步锁契约 |
+| `Resource/` `Pool/` `Logging/` `Localization/` | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`IStructuredLogger`、`ILocalizationManager` | 资源 / 池化 / 日志 / 本地化这些基础设施的宿主责任 |
+| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage`、`IVersioned` | 配置、环境、序列化和持久化边界，以及谁负责具体实现 |
+| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 基础角色接口、辅助值对象和架构属性键的复用方式 |

 ## 阅读顺序

--- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md
+++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md
@ -32,13 +32,13 @@ description: GFramework.Ecs.Arch.Abstractions 的契约边界、包关系和最
 | `IArchSystemAdapter<T>` | 让 ECS 系统适配到 `ISystem` 生命周期 |
 | `ArchOptions` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 等配置 |

-## 类型族级 XML Inventory
+## 契约阅读入口

-| 类型族 | 代表类型 | XML 状态 | 阅读重点 |
-| --- | --- | --- | --- |
-| 模块契约 | `IArchEcsModule` | 已覆盖 | 统一更新入口、宿主循环边界 |
-| 系统契约 | `IArchSystemAdapter<T>` | 已覆盖 | 只依赖更新接口而不绑定默认 runtime |
-| 配置对象 | `ArchOptions` | 已覆盖 | 共享配置字段与跨程序集采用边界 |
+| 类型族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| 模块契约 | `IArchEcsModule` | 统一更新入口、宿主循环边界 |
+| 系统契约 | `IArchSystemAdapter<T>` | 只依赖更新接口而不绑定默认 runtime |
+| 配置对象 | `ArchOptions` | 共享配置字段与跨程序集采用边界 |

 ## 最小接入路径

--- a/docs/zh-CN/abstractions/game-abstractions.md
+++ b/docs/zh-CN/abstractions/game-abstractions.md
@ -1,6 +1,6 @@
 ---
 title: Game Abstractions
-description: GFramework.Game.Abstractions 的契约边界、包关系与 XML 阅读重点。
+description: GFramework.Game.Abstractions 的契约边界、包关系与源码阅读重点。
 ---

 # Game Abstractions
@ -37,19 +37,18 @@ description: GFramework.Game.Abstractions 的契约边界、包关系与 XML 阅
 | `Routing/` | `IRoute`、`IRouteContext`、`IRouteGuard<TRoute>`，作为 Scene / UI 共享的路由基础约定 |
 | `Storage/` `Asset/` `Enums/` | 文件存储角色、资源注册表，以及转场 / UI 层级 / 输入动作等跨层枚举 |

-## XML 覆盖基线
+## 契约族阅读入口

-下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 /
-内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要后续 API 波次继续细化。
+如果你要回到源码 XML 文档确认契约，请优先看下面这些族群：

-| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `Config/` | `7/7` 个类型声明已带 XML 注释 | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>`、`ConfigLoadException` | 看配置表注册、只读访问和失败诊断边界 |
-| `Data/` | `14/14` 个类型声明已带 XML 注释 | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>`、`DataRepositoryOptions` | 看业务数据、统一设置文件、槽位存档与迁移契约 |
-| `Setting/` | `12/12` 个类型声明已带 XML 注释 | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 看设置生命周期、应用语义、迁移接口和内置设置对象 |
-| `Scene/` | `14/14` 个类型声明已带 XML 注释 | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 看场景行为、工厂 / root 边界和转场模型 |
-| `UI/` | `19/19` 个类型声明已带 XML 注释 | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 看页面栈、层级 UI、输入动作和 UI 转场契约 |
-| `Routing/` `Storage/` `Asset/` `Enums/` | `13/13` 个类型声明已带 XML 注释 | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry<T>`、`UiLayer`、`SceneTransitionType` | 看公共路由上下文、存储角色、资源注册表与共享枚举 |
+| 契约族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| `Config/` | `IConfigLoader`、`IConfigRegistry`、`IConfigTable<TKey, TValue>`、`ConfigLoadException` | 配置表注册、只读访问和失败诊断边界 |
+| `Data/` | `IDataRepository`、`ISettingsDataRepository`、`ISaveRepository<TSaveData>`、`DataRepositoryOptions` | 业务数据、统一设置文件、槽位存档与迁移契约 |
+| `Setting/` | `ISettingsData`、`ISettingsModel`、`ISettingsSystem`、`LocalizationSettings` | 设置生命周期、应用语义、迁移接口和内置设置对象 |
+| `Scene/` | `IScene`、`ISceneRouter`、`ISceneFactory`、`SceneTransitionEvent` | 场景行为、工厂 / root 边界和转场模型 |
+| `UI/` | `IUiPage`、`IUiRouter`、`IUiFactory`、`UiInteractionProfile`、`UiTransitionHandlerOptions` | 页面栈、层级 UI、输入动作和 UI 转场契约 |
+| `Routing/` `Storage/` `Asset/` `Enums/` | `IRoute`、`IRouteContext`、`IFileStorage`、`IAssetRegistry<T>`、`UiLayer`、`SceneTransitionType` | 公共路由上下文、存储角色、资源注册表与共享枚举 |

 ## 最小接入路径

--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -18,7 +18,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

 ### 想确认“该装哪个包、先看哪类 API”

-先读模块 README，再读对应 landing page：
+先读模块 README，再读对应栏目入口页：

 - 入门入口：[`../getting-started/index.md`](../getting-started/index.md)
 - 根模块地图：仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)
@ -51,7 +51,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

 ### 先看教程和专题页的情况

- 你要的是最小接入路径，而不是逐个类型审计
+- 你要的是最小接入路径，而不是逐个类型展开阅读
 - 你想确认模块组合方式、目录约定和推荐接线顺序
 - 你在做从旧入口迁移到新入口的采用决策

--- a/docs/zh-CN/contributor/development-environment.md
+++ b/docs/zh-CN/contributor/development-environment.md
@ -1,12 +1,17 @@
+---
+title: 开发环境能力清单
+description: 说明 GFramework 当前开发和 AI 协作依赖的环境能力、推荐工具与刷新方式。
+---
+
 # 开发环境能力清单

 这份文档只记录对 `GFramework` 当前开发和 AI 协作真正有用的环境能力，不收录与本项目无关的系统工具。

 如果某个工具没有出现在这里，默认表示它对当前仓库不是必需项，AI 也不应因为“系统里刚好装了”就优先使用它。

-## 当前环境基线
+## 当前验证环境

-当前仓库验证基线是：
+当前仓库主要在下面这组环境中验证：

 - **运行环境**：WSL2
 - **发行版**：Ubuntu 24.04 LTS
@ -114,4 +119,4 @@ LLM 索引文件与文档站一起部署在 GitHub Pages，遵循 `docs/.vitepre
    - 当前仓库构建、测试、文档或验证直接依赖它
    - AI 在当前仓库中会高频使用，且能明显提升效率
    - 新贡献者配置当前仓库开发环境时确实需要知道它
- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。
+- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。
--- a/docs/zh-CN/core/cqrs.md
+++ b/docs/zh-CN/core/cqrs.md
@ -1,6 +1,6 @@
 ---
 title: CQRS
-description: Cqrs 模块族的运行时、契约层、生成器入口，以及 XML / API 阅读链路。
+description: Cqrs 模块族的运行时、契约层、生成器入口，以及源码与 API 阅读链路。
 ---

 # CQRS
@ -169,17 +169,17 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
 - 在维护历史代码：允许继续使用旧 Command / Query
 - 在写新功能或新模块：优先使用 CQRS

-## XML 覆盖基线
+## 源码阅读入口

-下面这份 inventory 记录的是 `2026-04-22` 对 `Cqrs` 家族做的一轮轻量 XML 盘点结果：只统计当前运行时、契约层和生成器入口中的类型声明级 XML 覆盖，用来校对 README、landing page 与 API 入口，不把它表述成成员级契约全审计。
+如果你需要直接回到源码确认 CQRS 契约，建议按下面这几组入口阅读：

-| 类型族 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `GFramework.Cqrs.Abstractions/Cqrs/` | `20/20` 个类型声明已带 XML 注释 | `ICqrsRuntime`、`ICqrsHandlerRegistrar`、`IPipelineBehavior<,>`、`IRequestHandler<,>`、`Unit` | 先看请求、处理器和 runtime seam 的最小契约 |
-| `GFramework.Cqrs/Command` `Query` `Notification` `Request` `Extensions` | `7/7` 个类型声明已带 XML 注释 | `CommandBase<TInput, TResponse>`、`QueryBase<TInput, TResponse>`、`NotificationBase<TInput>`、`ContextAwareCqrsExtensions` | 看业务侧常用基类和上下文发送入口 |
-| `GFramework.Cqrs/Cqrs/` | `12/12` 个类型声明已带 XML 注释 | `AbstractCommandHandler<,>`、`AbstractQueryHandler<,>`、`AbstractNotificationHandler<>`、`LoggingBehavior<,>` | 看默认处理器基类、上下文注入与行为管道 |
-| `GFramework.Cqrs` 根入口与 `Internal/` | `19/19` 个类型声明已带 XML 注释 | `CqrsRuntimeFactory`、`ICqrsHandlerRegistry`、`CqrsHandlerRegistryAttribute`、`CqrsReflectionFallbackAttribute`、`DefaultCqrsRegistrationService` | 看 runtime 创建入口、registry 协议、fallback 语义和程序集去重规则 |
-| `GFramework.Cqrs.SourceGenerators/Cqrs/` | `3/3` 个类型声明已带 XML 注释 | `CqrsHandlerRegistryGenerator`、`RuntimeTypeReferenceSpec`、`OrderedRegistrationKind` | 看生成注册器、精确 type lookup 和 fallback 诊断边界 |
+| 类型族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| `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` 根入口与 `Internal/` | `CqrsRuntimeFactory`、`ICqrsHandlerRegistry`、`CqrsHandlerRegistryAttribute`、`CqrsReflectionFallbackAttribute`、`DefaultCqrsRegistrationService` | runtime 创建入口、registry 协议、fallback 语义和程序集去重规则 |
+| `GFramework.Cqrs.SourceGenerators/Cqrs/` | `CqrsHandlerRegistryGenerator`、`RuntimeTypeReferenceSpec`、`OrderedRegistrationKind` | 生成注册器、精确 type lookup 和 fallback 诊断边界 |

 ## 继续阅读

--- a/docs/zh-CN/core/index.md
+++ b/docs/zh-CN/core/index.md
@ -1,6 +1,6 @@
 ---
 title: Core
-description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口、采用顺序和 XML 阅读导航。
+description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口、采用顺序和源码阅读导航。
 ---

 # Core
@ -82,22 +82,21 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions

 统一入口见 [`../api-reference/index.md`](../api-reference/index.md)。

-## XML 覆盖基线
+## 源码阅读入口

-下面这份 inventory 记录的是 `2026-04-22` 对 `GFramework.Core` 做的一轮轻量 XML 盘点结果：只统计顶层目录中的公开 /
-内部类型声明是否带 XML 注释，用来确认阅读入口和治理优先级；成员级 ``<param>``、``<returns>``、异常语义与线程说明仍需要继续细审。
+如果你准备直接回到源码和 XML 文档确认契约，建议按能力域分批阅读，而不是按文件数量排查：

-| 类型族 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `Architectures/` | `16/16` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ArchitecturePhaseCoordinator` | 看架构启动、模块安装、阶段切换和上下文暴露边界 |
-| `Services/` | `6/6` 个类型声明已带 XML 注释 | `ServiceModuleManager`、`CommandExecutorModule`、`CqrsRuntimeModule` | 看服务模块的注册顺序、销毁语义和默认接线 |
-| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand<TInput>`、`AbstractQuery<TResult>` | 看旧入口兼容面与向 `CQRS` 迁移时还保留了哪些执行契约 |
-| `Events/` `Property/` | `19/19` 个类型声明已带 XML 注释 | `EventBus`、`EnhancedEventBus`、`BindableProperty<T>`、`OrEvent<T>` | 看事件传播、解绑约束和可绑定属性的订阅语义 |
-| `State/` `StateManagement/` | `10/10` 个类型声明已带 XML 注释 | `StateMachine`、`StateMachineSystem`、`Store<TState>`、`StoreBuilder<TState>` | 看状态切换、selector / middleware / dispatch 的单向流边界 |
-| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`WaitForSecondsRealtime`、`PauseStackManager`、`AsyncKeyLockManager` | 看调度阶段、等待指令、时间源和暂停 / 锁的线程语义 |
-| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`ManualReleaseStrategy`、`AbstractObjectPoolSystem<TKey, TObject>` | 看资源句柄释放策略与对象池复用约束 |
-| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`CompositeLogger`、`LocalizationManager`、`ConfigurationManager`、`MicrosoftDiContainer` | 看日志组装、格式化 / filter、配置监听、环境对象与容器适配 |
-| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` | 看默认基类、上下文感知 helper、数值格式化和通用扩展的使用边界 |
+| 类型族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| `Architectures/` | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ArchitecturePhaseCoordinator` | 架构启动、模块安装、阶段切换和上下文暴露边界 |
+| `Services/` | `ServiceModuleManager`、`CommandExecutorModule`、`CqrsRuntimeModule` | 服务模块的注册顺序、销毁语义和默认接线 |
+| `Command/` `Query/` | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand<TInput>`、`AbstractQuery<TResult>` | 旧入口兼容面，以及向 `CQRS` 迁移时保留的执行契约 |
+| `Events/` `Property/` | `EventBus`、`EnhancedEventBus`、`BindableProperty<T>`、`OrEvent<T>` | 事件传播、解绑约束和可绑定属性的订阅语义 |
+| `State/` `StateManagement/` | `StateMachine`、`StateMachineSystem`、`Store<TState>`、`StoreBuilder<TState>` | 状态切换，以及 selector / middleware / dispatch 的单向流边界 |
+| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `CoroutineScheduler`、`CoroutineHandle`、`WaitForSecondsRealtime`、`PauseStackManager`、`AsyncKeyLockManager` | 调度阶段、等待指令、时间源，以及暂停 / 锁的线程语义 |
+| `Resource/` `Pool/` | `ResourceManager`、`AutoReleaseStrategy`、`ManualReleaseStrategy`、`AbstractObjectPoolSystem<TKey, TObject>` | 资源句柄释放策略与对象池复用约束 |
+| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `ConsoleLogger`、`CompositeLogger`、`LocalizationManager`、`ConfigurationManager`、`MicrosoftDiContainer` | 日志组装、格式化 / filter、配置监听、环境对象与容器适配 |
+| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` | 默认基类、上下文感知 helper、数值格式化和通用扩展的使用边界 |

 ## 最小接入路径

--- a/docs/zh-CN/ecs/arch.md
+++ b/docs/zh-CN/ecs/arch.md
@ -1,6 +1,6 @@
 ---
 title: Arch ECS 集成
-description: GFramework.Ecs.Arch 的默认运行时装配路径、系统桥接方式与 XML 阅读入口。
+description: GFramework.Ecs.Arch 的默认运行时装配路径、系统桥接方式与源码阅读入口。
 ---

 # Arch ECS 集成
@ -127,14 +127,14 @@ ecsModule.Update(deltaTime);
 - `Priority` 影响 `ArchEcsModule` 作为服务模块的排序
 - `EnableStatistics` 目前保留在公开配置面上；采用时应以源码 XML 注释和实现行为为准，而不是依赖旧文档推断

-## 类型族级 XML Inventory
+## 源码阅读入口

-| 类型族 | 代表类型 | XML 状态 | 阅读重点 |
-| --- | --- | --- | --- |
-| 装配入口 | `ArchExtensions` | 已覆盖 | `UseArch(...)` 的时机、链式调用返回值 |
-| 服务模块 | `ArchEcsModule` | 已覆盖 | `World` 注册、系统收集、模块销毁顺序 |
-| 系统桥接层 | `ArchSystemAdapter<T>` | 已覆盖 | `OnArchInitialize` / `OnUpdate` / `OnArchDispose` |
-| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 已覆盖 | 组件布局、查询写法、最小集成样例 |
+| 类型族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| 装配入口 | `ArchExtensions` | `UseArch(...)` 的时机、链式调用返回值 |
+| 服务模块 | `ArchEcsModule` | `World` 注册、系统收集、模块销毁顺序 |
+| 系统桥接层 | `ArchSystemAdapter<T>` | `OnArchInitialize` / `OnUpdate` / `OnArchDispose` |
+| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 组件布局、查询写法和最小集成样例 |

 ## 相关入口

--- a/docs/zh-CN/ecs/index.md
+++ b/docs/zh-CN/ecs/index.md
@ -1,6 +1,6 @@
 ---
 title: ECS 系统集成
-description: GFramework 当前 ECS 模块族的包边界、采用顺序与 XML 阅读入口。
+description: GFramework 当前 ECS 模块族的包边界、采用顺序与源码阅读入口。
 ---

 # ECS 系统集成
@ -118,16 +118,16 @@ public sealed class GameLoop
 3. 只想保留共享边界时继续读 [`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md)
 4. 统一查阅 README / docs / XML 入口时回到 [`../api-reference/index.md`](../api-reference/index.md)

-## 类型族级 XML Inventory
+## 源码阅读入口

-下表记录当前 `Ecs.Arch` family 的类型声明级 XML 基线，便于从 README、站内 landing 和源码之间建立一致的审计入口。
+如果你要从栏目入口页回到源码和 XML 文档，建议按下面的入口阅读：

-| 包 | 类型族 | 代表类型 | XML 状态 | 阅读重点 |
-| --- | --- | --- | --- | --- |
-| `GFramework.Ecs.Arch` | 运行时装配与模块生命周期 | `ArchExtensions`、`ArchEcsModule` | 已覆盖 | `UseArch(...)` 的接入时机、`World` 注册、模块优先级 |
-| `GFramework.Ecs.Arch` | 系统桥接层 | `ArchSystemAdapter<T>` | 已覆盖 | GFramework `ISystem` 生命周期如何桥接到 Arch `ISystem<T>` |
-| `GFramework.Ecs.Arch` | 示例组件与系统 | `Position`、`Velocity`、`MovementSystem` | 已覆盖 | 查询写法、组件布局、最小可运行示例 |
-| `GFramework.Ecs.Arch.Abstractions` | 契约与配置对象 | `IArchEcsModule`、`IArchSystemAdapter<T>`、`ArchOptions` | 已覆盖 | 共享宿主循环、测试替身、跨程序集配置边界 |
+| 包 | 类型族 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- | --- |
+| `GFramework.Ecs.Arch` | 运行时装配与模块生命周期 | `ArchExtensions`、`ArchEcsModule` | `UseArch(...)` 的接入时机、`World` 注册、模块优先级 |
+| `GFramework.Ecs.Arch` | 系统桥接层 | `ArchSystemAdapter<T>` | GFramework `ISystem` 生命周期如何桥接到 Arch `ISystem<T>` |
+| `GFramework.Ecs.Arch` | 示例组件与系统 | `Position`、`Velocity`、`MovementSystem` | 查询写法、组件布局和最小可运行示例 |
+| `GFramework.Ecs.Arch.Abstractions` | 契约与配置对象 | `IArchEcsModule`、`IArchSystemAdapter<T>`、`ArchOptions` | 共享宿主循环、测试替身和跨程序集配置边界 |

 ## 边界说明

--- a/docs/zh-CN/game/index.md
+++ b/docs/zh-CN/game/index.md
@ -1,6 +1,6 @@
 ---
 title: Game
-description: GFramework.Game family 的运行时入口、采用顺序与 XML 阅读基线。
+description: GFramework.Game family 的运行时入口、采用顺序与源码阅读导航。
 ---

 # Game
@ -103,15 +103,15 @@ IStorage storage = new FileStorage("GameData", serializer);
 4. [setting](./setting.md)
 5. [scene](./scene.md) 或 [ui](./ui.md)

-## Game Family XML 覆盖基线
+## 源码与 API 阅读入口

-下面这份 inventory 记录的是 `2026-04-23` 对 `Game` family 做的一轮轻量 XML 盘点结果：只统计公开 / 内部类型声明是否带 XML 注释，用来建立 README / landing / API 阅读链路；成员级 `param`、`returns`、`exception` 与生命周期说明仍需要后续波次继续细化。
+如果你已经完成栏目入口页阅读，下一步通常不是看统计表，而是按模块角色回到源码和 XML 文档：

-| 模块 | 基线状态 | 代表类型 | 阅读重点 |
-| --- | --- | --- | --- |
-| `GFramework.Game` | `56/56` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`SettingsModel<TRepository>`、`SceneRouterBase`、`UiRouterBase` | 先看运行时默认实现、配置加载、设置编排和路由基类 |
-| `GFramework.Game.Abstractions` | `80/80` 个类型声明已带 XML 注释 | `IConfigRegistry`、`ISaveRepository<TSaveData>`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 再看契约层边界，决定项目哪些程序集只依赖接口 |
-| `GFramework.Game.SourceGenerators` | `2/2` 个类型声明已带 XML 注释 | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | 最后看 schema 生成入口与诊断模型，确认配置系统的编译期链路 |
+| 模块 | 代表类型 | 建议先确认什么 |
+| --- | --- | --- |
+| `GFramework.Game` | `YamlConfigLoader`、`SettingsModel<TRepository>`、`SceneRouterBase`、`UiRouterBase` | 默认运行时实现、配置加载、设置编排和路由基类 |
+| `GFramework.Game.Abstractions` | `IConfigRegistry`、`ISaveRepository<TSaveData>`、`ISettingsSystem`、`ISceneRouter`、`IUiRouter` | 契约层边界，以及项目中哪些程序集只应依赖接口 |
+| `GFramework.Game.SourceGenerators` | `SchemaConfigGenerator`、`ConfigSchemaDiagnostics` | schema 生成入口与诊断模型，确认配置系统的编译期链路 |

 ## 与真实接法的关系

--- a/docs/zh-CN/source-generators/bind-node-signal-generator.md
+++ b/docs/zh-CN/source-generators/bind-node-signal-generator.md
@ -11,7 +11,7 @@ description: 说明 [BindNodeSignal] 当前生成什么、如何与 GetNode 协

 - 特性来源：`GFramework.Godot.SourceGenerators.Abstractions`
 - 生成器实现：`GFramework.Godot.SourceGenerators`
- 目标字段基线：`nodeFieldName` 指向的字段必须继承 `Godot.Node`
+- 使用前提：`nodeFieldName` 指向的字段必须继承 `Godot.Node`

 ## 最小用法

--- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md
+++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md
@ -116,7 +116,7 @@ RegisterCqrsHandlersFromAssemblies(

 这条诊断的含义不是“某个 handler 写错了”，而是“当前 runtime 合同不足以安全承载这轮生成结果”。

-## XML / API 阅读入口
+## 源码与 API 阅读入口

 如果你要核对生成器对外暴露的契约，优先看这些类型：

--- a/docs/zh-CN/source-generators/get-node-generator.md
+++ b/docs/zh-CN/source-generators/get-node-generator.md
@ -11,7 +11,7 @@ description: 说明 [GetNode] 当前生成什么、路径如何推断，以及 _

 - 特性来源：`GFramework.Godot.SourceGenerators.Abstractions`
 - 生成器实现：`GFramework.Godot.SourceGenerators`
- 目标类型基线：字段类型必须继承 `Godot.Node`
+- 使用前提：字段类型必须继承 `Godot.Node`

 ## 最小用法