docs(governance): 建立长期文档治理入口

- 新增 documentation-full-coverage-governance active topic 与首轮 inventory、trace 入口 - 补充 GFramework.Ecs.Arch.Abstractions README、抽象接口页面与导航映射 - 更新 API 参考页与根 README，明确内部支撑模块 owner 和阅读链路
2026-05-06 16:16:44 +08:00 · 2026-04-22 15:07:15 +08:00 · 2026-04-22 15:07:15 +08:00 · cc49b8638f
commit cc49b8638f
parent 45a87c6988
9 changed files with 431 additions and 571 deletions
--- a/GFramework.Ecs.Arch.Abstractions/README.md
+++ b/GFramework.Ecs.Arch.Abstractions/README.md
@ -0,0 +1,93 @@
+# GFramework.Ecs.Arch.Abstractions
+
+`GFramework.Ecs.Arch.Abstractions` 承载 Arch ECS 集成层的最小契约，用来让共享业务层、宿主循环或扩展模块在不依赖
+`GFramework.Ecs.Arch` 默认实现的前提下，仍然可以约定 ECS 模块边界。
+
+如果你需要的是 `UseArch(...)` 扩展、`ArchSystemAdapter<T>` 基类、`World` 注册和默认模块实现，请改为依赖
+`GFramework.Ecs.Arch`。
+
+## 包定位
+
+- 这是 `Ecs.Arch` 的契约层，不是默认实现层。
+- 适合让上层模块只面向 `IArchEcsModule`、`IArchSystemAdapter<T>` 和 `ArchOptions` 编程。
+- 常见场景：
+  - 共享宿主循环只依赖更新契约，不直接引用 Arch runtime 实现
+  - 多程序集之间需要共享 ECS 配置对象或接口边界
+  - 测试替身、编辑器工具或外部适配层希望复用契约，但自行决定底层实现
+
+## 与相邻包的关系
+
+- `GFramework.Core.Abstractions`
+  - 本包直接依赖它，并复用 `IServiceModule`、`ISystem` 等基础契约。
+- `GFramework.Ecs.Arch.Abstractions`
+  - 只定义 Arch ECS 集成相关的最小契约和配置对象。
+- `GFramework.Ecs.Arch`
+  - 本包的默认实现层。
+  - 负责 `UseArch(...)` 扩展、默认模块注册、Arch `World` 装配，以及系统适配器基类。
+
+## 契约地图
+
+| 文件 | 作用 |
+| --- | --- |
+| `IArchEcsModule.cs` | ECS 模块服务契约，负责统一驱动系统更新 |
+| `IArchSystemAdapter.cs` | 让 ECS 系统适配到 GFramework `ISystem` 生命周期的接口 |
+| `ArchOptions.cs` | `WorldCapacity`、`EnableStatistics`、`Priority` 等配置对象 |
+
+## 最小接入路径
+
+### 1. 只想约定宿主循环与 ECS 模块边界
+
+```csharp
+using GFramework.Ecs.Arch.Abstractions;
+
+public sealed class EcsUpdateLoop
+{
+    private readonly IArchEcsModule _ecsModule;
+
+    public EcsUpdateLoop(IArchEcsModule ecsModule)
+    {
+        _ecsModule = ecsModule;
+    }
+
+    public void Tick(float deltaTime)
+    {
+        _ecsModule.Update(deltaTime);
+    }
+}
+```
+
+### 2. 只想共享配置对象
+
+```csharp
+using GFramework.Ecs.Arch.Abstractions;
+
+var options = new ArchOptions
+{
+    WorldCapacity = 2048,
+    EnableStatistics = true,
+    Priority = 40
+};
+```
+
+### 3. 什么时候要升级到 `GFramework.Ecs.Arch`
+
+一旦你需要下面任一项，就不该只停留在本包：
+
+- `UseArch(...)` 或其他 runtime 装配入口
+- `ArchSystemAdapter<T>` 等默认基类
+- Arch `World` 的创建、注册和查询能力
+- 与 `GFramework` 架构生命周期绑定的默认模块实现
+
+## 边界说明
+
+- 本包不提供 Arch `World` 的默认构造与注册逻辑。
+- 本包不提供系统基类、扩展方法或默认服务实现。
+- 它回答的是“外部模块怎样与 Arch ECS 集成层约定边界”，不是“Arch ECS 默认怎么接入到项目里”。
+
+## 对应文档入口
+
+- 抽象接口总览：[`../docs/zh-CN/abstractions/index.md`](../docs/zh-CN/abstractions/index.md)
+- Ecs.Arch 抽象层说明：[`../docs/zh-CN/abstractions/ecs-arch-abstractions.md`](../docs/zh-CN/abstractions/ecs-arch-abstractions.md)
+- ECS 模块入口：[`../docs/zh-CN/ecs/index.md`](../docs/zh-CN/ecs/index.md)
+- Arch ECS 集成：[`../docs/zh-CN/ecs/arch.md`](../docs/zh-CN/ecs/arch.md)
+- 运行时实现入口：[`../GFramework.Ecs.Arch/README.md`](../GFramework.Ecs.Arch/README.md)
--- a/README.md
+++ b/README.md
@ -27,11 +27,22 @@
 | `GFramework.Game.Abstractions` | `Game` 对应的契约层 | [README](GFramework.Game.Abstractions/README.md) |
 | `GFramework.Godot` | Godot 集成层，负责把框架能力接入节点、场景、UI、设置与存储 | [README](GFramework.Godot/README.md) |
 | `GFramework.Ecs.Arch` | Arch ECS 集成 | [README](GFramework.Ecs.Arch/README.md) |
+| `GFramework.Ecs.Arch.Abstractions` | Arch ECS 集成对应的契约层，适合共享宿主循环与 ECS 模块边界 | [README](GFramework.Ecs.Arch.Abstractions/README.md) |
 | `GFramework.Core.SourceGenerators` | Core 侧通用源码生成器与分析器 | [README](GFramework.Core.SourceGenerators/README.md) |
 | `GFramework.Game.SourceGenerators` | 游戏内容配置 schema 生成器 | [README](GFramework.Game.SourceGenerators/README.md) |
 | `GFramework.Cqrs.SourceGenerators` | CQRS handler registry 生成器 | [README](GFramework.Cqrs.SourceGenerators/README.md) |
 | `GFramework.Godot.SourceGenerators` | Godot 场景专用源码生成器 | [README](GFramework.Godot.SourceGenerators/README.md) |

+## 内部支撑模块
+
+以下目录目前不是独立采用入口，而是跟随所属模块维护的内部支撑组件：
+
+| 目录 | 定位 | 跟随入口 |
+| --- | --- | --- |
+| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [GFramework.Core.SourceGenerators/README.md](GFramework.Core.SourceGenerators/README.md) |
+| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [GFramework.Godot.SourceGenerators/README.md](GFramework.Godot.SourceGenerators/README.md) |
+| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [docs/zh-CN/source-generators/index.md](docs/zh-CN/source-generators/index.md) |
+
 ## 文档导航

 仓库根 README 与文档站点保持同一套栏目命名：
@ -119,10 +130,13 @@ GFramework.sln
 ├─ GFramework.Game.Abstractions/
 ├─ GFramework.Godot/
 ├─ GFramework.Ecs.Arch/
+├─ GFramework.Ecs.Arch.Abstractions/
 ├─ GFramework.Core.SourceGenerators/
+├─ GFramework.Core.SourceGenerators.Abstractions/
 ├─ GFramework.Game.SourceGenerators/
 ├─ GFramework.Cqrs.SourceGenerators/
 ├─ GFramework.Godot.SourceGenerators/
+├─ GFramework.Godot.SourceGenerators.Abstractions/
 ├─ GFramework.SourceGenerators.Common/
 └─ docs/
 ```
--- a/ai-plan/public/README.md
+++ b/ai-plan/public/README.md
@ -25,6 +25,11 @@ help the current worktree land on the right recovery documents without scanning
  - Purpose: continue the AI-First config runtime, generator, and consumer DX work for `GFramework.Game`.
  - Tracking: `ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md`
  - Trace: `ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md`
+- `documentation-full-coverage-governance`
+  - Purpose: govern full-coverage documentation inventory, module-wave remediation, and the README / docs / XML /
+    API-reference alignment baseline.
+  - Tracking: `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md`
+  - Trace: `ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md`
 - `coroutine-optimization`
  - Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc
    follow-up work.
@ -58,6 +63,9 @@ help the current worktree land on the right recovery documents without scanning
 - Branch: `feat/data-repository-persistence`
  - Worktree hint: `GFramework-data-repository-persistence`
  - Priority 1: `data-repository-persistence`
+- Branch: `docs/sdk-update-documentation`
+  - Worktree hint: `GFramework-update-documentation`
+  - Priority 1: `documentation-full-coverage-governance`
 ## Archived Topics

 - `cqrs-cache-docs-hardening`
--- 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
@ -0,0 +1,89 @@
+# Documentation Full Coverage Governance 跟踪
+
+## 目标
+
+建立一个长期 active topic，持续治理 `GFramework` 的 README、`docs/zh-CN`、站点导航、XML 文档和 API
+参考链路，避免历史上的阶段性刷新完成后再次回漂。
+
+- 用源码、测试、`*.csproj` 和必要的 `ai-libs/` 证据校正文档
+- 以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路
+- 明确哪些目录是可直接消费模块，哪些只是内部支撑模块
+- 把 XML 文档缺口纳入治理范围，而不是只刷新 Markdown
+
+## 当前恢复点
+
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-001`
+- 当前阶段：`Phase 1 - Inventory And Governance Bootstrap`
+- 当前焦点：
+  - 注册新的长期文档治理 topic，并把当前分支映射到该 topic
+  - 落第一版模块化 inventory、缺口分级和治理波次顺序
+  - 立即补齐已确认的 README / 入口缺口：`GFramework.Ecs.Arch.Abstractions`
+  - 把 `api-reference` 页面改成真实的 API 链路入口，而不是失真的伪 API 列表
+
+## 当前状态摘要
+
+- 已归档的 `documentation-governance-and-refresh` 仅保留为历史证据，不再作为默认 `boot` 入口
+- 本轮已确认的消费属性结论：
+  - `GFramework.Ecs.Arch.Abstractions`：可打包直接消费模块，需要 README 和文档入口
+  - `GFramework.Core.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理
+  - `GFramework.Godot.SourceGenerators.Abstractions`：`IsPackable=false`，按内部支撑模块处理
+  - `GFramework.SourceGenerators.Common`：`IsPackable=false`，按内部支撑模块处理
+- 本轮已完成的治理动作：
+  - 新建 `GFramework.Ecs.Arch.Abstractions/README.md`
+  - 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner
+  - 为抽象接口栏目补齐 `Ecs.Arch.Abstractions` 页面与 sidebar 入口
+  - 将 `docs/zh-CN/api-reference/index.md` 重写为模块到 XML / README / 教程的阅读链路入口
+
+## Inventory（第一版）
+
+| 模块族 | 当前状态 | 当前证据 | 下一动作 |
+| --- | --- | --- | --- |
+| `Core` / `Core.Abstractions` | `已验证` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已存在 | 进入首轮波次时补 XML 文档 inventory |
+| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `待重写` | README 已存在；站内入口目前分散在 `docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` | 在 `Cqrs` 波次里补 dedicated landing / API map 审计 |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `已验证` | 根 README、模块 README、`docs/zh-CN/game/**` 和 abstractions 页已存在 | 后续波次补 XML / 教程链路审计 |
+| `Godot` / `Godot.SourceGenerators` | `已验证` | 上一轮归档 topic 已完成核心 landing / topic / tutorial 校验 | 进入巡检周期，重点看回漂 |
+| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `待重写` | runtime README 已存在；`Ecs.Arch.Abstractions` README 与抽象页已在本轮补齐；`docs/zh-CN/ecs/index.md` / `arch.md` 仍偏旧 | 在 `Ecs` 波次重写 runtime docs 并补 XML map |
+| `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 |
+
+## 缺口分级
+
+- `P0`
+  - 错误采用路径、错误包关系、错误 API / 生命周期语义
+  - 站点导航死链、空 landing page、明显错误的模块 owner
+- `P1`
+  - 直接消费模块缺 README 或缺对应 docs 入口
+  - README / docs 示例与源码实现不一致
+  - 教程仍引用已经过时的默认接线方式
+- `P2`
+  - 结构重复、交叉链接不足、API 参考链路过薄
+  - 站内页面存在事实正确但组织方式不利于定位的内容
+
+## 当前风险
+
+- `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md` 仍保留较多早期表述，本轮只先完成 inventory 与入口补齐
+  - 缓解措施：把 `Ecs.Arch` 排进前五波次，并把 runtime docs 重写列为该波次的必做项
+- XML 文档尚未按模块做全量类型审计
+  - 缓解措施：下一恢复点先从 `Core` 模块族建立“类型族 -> XML 覆盖状态”清单
+- 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂
+  - 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源
+
+## 验证说明
+
+- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md`
+- 结果：通过
+- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`
+- 结果：通过
+- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`
+- 结果：通过
+- `cd docs && bun run build`
+- 结果：通过
+- 备注：仅保留 VitePress 大 chunk warning，无构建失败
+- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
+- 结果：通过
+- 备注：`0 Warning(s) / 0 Error(s)`
+
+## 下一步
+
+1. 按波次顺序启动 `Core` / `Core.Abstractions` 的 XML 文档与 API 链路 inventory
+2. 在 `Ecs` 波次重写 `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md`
+3. 为每个模块族补一份“README / landing / tutorials / API reference / XML”对照表，持续清零 `P0` / `P1`
--- 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
@ -0,0 +1,35 @@
+# Documentation Full Coverage Governance Trace
+
+## 2026-04-22
+
+### 当前恢复点：RP-001
+
+- 按长期治理计划新建 active topic `documentation-full-coverage-governance`
+- 在 `ai-plan/public/README.md` 中将当前分支 `docs/sdk-update-documentation` 映射到该 topic
+- 复核已知缺口模块的 `*.csproj` 后确认：
+  - `GFramework.Ecs.Arch.Abstractions` 是可打包消费模块，需要独立 README
+  - `GFramework.Core.SourceGenerators.Abstractions`、`GFramework.Godot.SourceGenerators.Abstractions`、
+    `GFramework.SourceGenerators.Common` 都是 `IsPackable=false` 的内部支撑模块
+- 基于该结论，本轮没有为内部支撑模块新增独立 README，而是在根 README 与 abstractions / API 入口中明确其 owner
+
+### 当前决策
+
+- 新主题的完成条件采用长期治理口径：`P0` 清零、无 README 缺失、无导航死链，并完成连续两轮稳定巡检
+- 本轮先做治理基础设施与 inventory，不把整个长期计划伪装成单轮完成
+- `api-reference` 页面改为“模块 -> README / docs / XML / tutorial”的阅读链路入口，避免继续维护失真的伪签名列表
+- `Ecs.Arch` family 被列为高优先 backlog：抽象层入口已补齐，但 runtime docs 仍需按源码重写
+
+### 当前验证
+
+- 文档校验：
+  - `validate-all.sh docs/zh-CN/abstractions/index.md`：通过
+  - `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
+  - `validate-all.sh docs/zh-CN/api-reference/index.md`：通过
+- 构建校验：
+  - `cd docs && bun run build`：通过
+  - `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
+
+### 下一步
+
+1. 进入 `Core` / `Core.Abstractions` 波次，先建立 XML 文档覆盖 inventory
+2. 在 `Ecs` 波次重写运行时 docs，并把 `Ecs.Arch.Abstractions` 纳入完整模块闭环
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@ -264,7 +264,8 @@ export default defineConfig({
              text: '抽象接口',
              items: [
                { text: 'Core Abstractions', link: '/zh-CN/abstractions/core-abstractions' },
-                { text: 'Game Abstractions', link: '/zh-CN/abstractions/game-abstractions' }
+                { text: 'Game Abstractions', link: '/zh-CN/abstractions/game-abstractions' },
+                { text: 'Ecs.Arch Abstractions', link: '/zh-CN/abstractions/ecs-arch-abstractions' }
              ]
            }
          ],
--- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md
+++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md
@ -0,0 +1,95 @@
+---
+title: Ecs.Arch Abstractions
+description: GFramework.Ecs.Arch.Abstractions 的契约边界、包关系和最小接入路径。
+---
+
+# Ecs.Arch Abstractions
+
+`GFramework.Ecs.Arch.Abstractions` 是 Arch ECS 集成层的契约包。
+
+它建立在 `GFramework.Core.Abstractions` 之上，只定义 ECS 模块更新、系统适配和配置对象，不负责默认的 Arch
+`World` 装配、扩展方法或系统基类。
+
+如果你需要开箱即用的集成实现，请改为依赖 `GFramework.Ecs.Arch`。
+
+## 什么时候单独依赖它
+
+- 你在做共享宿主循环、工具层或 feature 包，只需要 `IArchEcsModule`
+- 你想让不同程序集共享 `ArchOptions` 或系统适配契约，但不直接绑定默认 runtime
+- 你需要为测试或外部适配层提供替身实现
+
+## 包关系
+
+- 契约层：`GFramework.Ecs.Arch.Abstractions`
+- 运行时实现：`GFramework.Ecs.Arch`
+- 底层基础契约：`GFramework.Core.Abstractions`
+
+## 契约地图
+
+| 类型 | 作用 |
+| --- | --- |
+| `IArchEcsModule` | 统一更新 ECS 系统的服务模块契约 |
+| `IArchSystemAdapter<T>` | 让 ECS 系统适配到 `ISystem` 生命周期 |
+| `ArchOptions` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 等配置 |
+
+## 最小接入路径
+
+### 1. 共享模块只依赖更新契约
+
+```csharp
+using GFramework.Ecs.Arch.Abstractions;
+
+public sealed class GameplayHost
+{
+    private readonly IArchEcsModule _ecsModule;
+
+    public GameplayHost(IArchEcsModule ecsModule)
+    {
+        _ecsModule = ecsModule;
+    }
+
+    public void Tick(float deltaTime)
+    {
+        _ecsModule.Update(deltaTime);
+    }
+}
+```
+
+### 2. 共享配置对象
+
+```csharp
+using GFramework.Ecs.Arch.Abstractions;
+
+var options = new ArchOptions
+{
+    WorldCapacity = 2048,
+    EnableStatistics = true,
+    Priority = 40
+};
+```
+
+### 3. 什么时候切到运行时包
+
+下面这些需求都属于 `GFramework.Ecs.Arch` 的职责，而不是本包：
+
+- 通过 `UseArch(...)` 把模块挂进架构
+- 使用默认的 `ArchSystemAdapter<T>` 基类
+- 访问 Arch `World` 与查询 API
+- 使用默认的模块装配和生命周期实现
+
+## 阅读顺序
+
+1. 先读本页，确认你是否真的只需要契约层
+2. 如果需要默认实现，再看 [`../ecs/arch.md`](../ecs/arch.md)
+3. 回到对应模块 README：
+   - `GFramework.Ecs.Arch.Abstractions/README.md`
+   - `GFramework.Ecs.Arch/README.md`
+
+## 边界提醒
+
+- `GFramework.Core.SourceGenerators.Abstractions`
+- `GFramework.Godot.SourceGenerators.Abstractions`
+- `GFramework.SourceGenerators.Common`
+
+这些目录当前都不是独立消费模块，而是源码生成器家族的内部支撑组件。它们不属于抽象接口栏目里的独立采用入口，
+应分别跟随 `Core.SourceGenerators`、`Godot.SourceGenerators` 或其他生成器模块的 README 与专题页维护。
--- a/docs/zh-CN/abstractions/index.md
+++ b/docs/zh-CN/abstractions/index.md
@ -1,3 +1,8 @@
+---
+title: 抽象接口
+description: GFramework 各抽象层模块的阅读入口与使用边界。
+---
+
 # 抽象接口

 `GFramework.*.Abstractions` 用来承载跨模块协作所需的契约，而不是运行时实现。
@ -12,9 +17,19 @@

 - Core 抽象层：[`core-abstractions.md`](./core-abstractions.md)
 - Game 抽象层：[`game-abstractions.md`](./game-abstractions.md)
+- Ecs.Arch 抽象层：[`ecs-arch-abstractions.md`](./ecs-arch-abstractions.md)

 ## 使用建议

 - 如果你只是想直接使用框架功能，优先从对应运行时模块的 `README.md` 和栏目页开始。
 - 只有在明确需要“契约层而非实现层”时，才单独依赖 `*.Abstractions` 包。
- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。
+- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。
+
+## 当前边界
+
+- `GFramework.Core.SourceGenerators.Abstractions`
+- `GFramework.Godot.SourceGenerators.Abstractions`
+- `GFramework.SourceGenerators.Common`
+
+这些目录当前不作为独立抽象接口栏目维护，而是作为源码生成器家族的内部支撑模块，分别跟随所属模块 README 和
+`source-generators` 栏目维护。
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -1,571 +1,81 @@
-# API 参考文档
-
-本文档提供 GFramework 各模块的完整 API 参考。
-
-## 核心命名空间
-
-### GFramework.Core.architecture
-
-核心架构命名空间，包含所有基础组件。
-
-#### 主要类型
-
-| 类型                 | 说明     |
-|--------------------|--------|
-| `Architecture`     | 应用架构基类 |
-| `AbstractModel`    | 数据模型基类 |
-| `AbstractSystem`   | 业务系统基类 |
-| `AbstractCommand`  | 命令基类   |
-| `AbstractQuery<T>` | 查询基类   |
-| `IController`      | 控制器接口  |
-| `IUtility`         | 工具类接口  |
-
-### GFramework.Core.events
-
-事件系统命名空间。
-
-#### 主要类型
-
-| 类型                | 说明       |
-|-------------------|----------|
-| `IEvent`          | 事件接口     |
-| `IEventSystem`    | 事件系统接口   |
-| `TypeEventSystem` | 类型安全事件系统 |
-
-### GFramework.Core.property
-
-属性系统命名空间。
-
-#### 主要类型
-
-| 类型                    | 说明     |
-|-----------------------|--------|
-| `BindableProperty<T>` | 可绑定属性  |
-| `IUnRegister`         | 注销接口   |
-| `IUnRegisterList`     | 注销列表接口 |
-
-### GFramework.Core.ioc
-
-IoC 容器命名空间。
-
-#### 主要类型
-
-| 类型           | 说明   |
-|--------------|------|
-| `IContainer` | 容器接口 |
-| `Container`  | 容器实现 |
-
-### GFramework.Core.pool
-
-对象池命名空间。
-
-#### 主要类型
-
-| 类型               | 说明    |
-|------------------|-------|
-| `IObjectPool<T>` | 对象池接口 |
-| `ObjectPool<T>`  | 对象池实现 |
-
-### GFramework.Core.Localization
-
-本地化系统命名空间。
-
-#### 主要类型
-
-| 类型                       | 说明       |
-|--------------------------|----------|
-| `ILocalizationManager`   | 本地化管理器接口 |
-| `ILocalizationTable`     | 本地化表接口   |
-| `ILocalizationString`    | 本地化字符串接口 |
-| `ILocalizationFormatter` | 格式化器接口   |
-| `LocalizationConfig`     | 本地化配置类   |
-| `LocalizationManager`    | 本地化管理器实现 |
-| `LocalizationTable`      | 本地化表实现   |
-| `LocalizationString`     | 本地化字符串实现 |
-
-## 常用 API
-
-### Architecture
-
-```csharp
-public abstract class Architecture : IBelongToArchitecture
-{
-    // 初始化架构
-    public void Initialize();
-
-    // 销毁架构
-    public void Destroy();
-
-    // 注册模型
-    public void RegisterModel<T>(T model) where T : IModel;
-
-    // 获取模型
-    public T GetModel<T>() where T : IModel;
-
-    // 注册系统
-    public void RegisterSystem<T>(T system) where T : ISystem;
-
-    // 获取系统
-    public T GetSystem<T>() where T : ISystem;
-
-    // 注册工具
-    public void RegisterUtility<T>(T utility) where T : IUtility;
-
-    // 获取工具
-    public T GetUt>() where T : IUtility;
-
-    // 发送命令
-    public void SendCommand<T>(T command) where T : ICommand;
-
-    // 发送查询
-    public TResult SendQuery<TQuery, TResult>(TQuery query)
-        where TQuery : IQuery<TResult>;
-
-    // 发送事件
-    public void SendEvent<T>(T e) where T : IEvent;
-}
-```
-
-### AbstractModel
-
-```csharp
-public abstract class AbstractModel : IBelongToArchitecture
-{
-    // 初始化模型
-    protected abstract void OnInit();
-
-    // 销毁模型
-    protected virtual void OnDestroy();
-
-    // 获取架构
-    public IArchitecture GetArchitecture();
-
-    // 发送事件
-    protected void SendEvent<T>(T e) where T : IEvent;
-
-    // 获取模型
-    protected T GetModel<T>() where T : IModel;
-
-    // 获取系统
-    protected T GetSystem<T>() where T : ISystem;
-
-    // 获取工具
-    protected T GetUtility<T>() where T : IUtility;
-}
-```
-
-### AbstractSystem
-
-```csharp
-public abstract class AbstractSystem : IBelongToArchitecture
-{
-    // 初始化系统
-    protected abstract void OnInit();
-
-    // 销毁系统
-    protected virtual void OnDestroy();
-
-    // 获取架构
-    public IArchitecture GetArchitecture();
-
-    // 发送事件
-    protected void SendEvent<T>(T e) where T : IEvent;
-
-    // 注册事件
-    protected IUnRegister RegisterEvent<T>(Action<T> onEvent)
-        where T : IEvent;
-
-    // 获取模型
-    protected T GetModel<T>() where T : IModel;
-
-    // 获取系统
-    protected T GetSystem<T>() where T : ISystem;
-
-    // 获取工具
-    protected T GetUtility<T>() where T : IUtility;
-}
-```
-
-### AbstractCommand
-
-```csharp
-public abstract class AbstractCommand : IBelongToArchitecture
-{
-    // 执行命令
-    public void Execute();
-
-    // 命令实现
-    protected abstract void OnDo();
-
-    // 获取架构
-    public IArchitecture GetArchitecture();
-
-    // 发送事件
-    protected void SendEvent<T>(T e) where T : IEvent;
-
-    // 获取模型
-    protected T GetModel<T>() where T : IModel;
-
-    // 获取系统
-    protected T GetSystem<T>() where T : ISystem;
-
-    // 获取工具
-    protected T GetUtility<T>() where T : IUtility;
-}
-```
-
-### AbstractQuery`<T>`
-
-```csharp
-public abstract class AbstractQuery<T> : IBelongToArchitecture
-{
-    // 执行查询
-    public T Do();
-
-    // 查询实现
-    protected abstract T OnDo();
-
-    // 获取架构
-    public IArchitecture GetArchitecture();
-
-    // 获取模型
-    protected T GetModel<T>() where T : IModel;
-
-    // 获取系统
-    protected T GetSystem<T>() where T : ISystem;
-
-    // 获取工具
-    protected T GetUtility<T>() where T : IUtility;
-}
-```
-
-### BindableProperty`<T>`
-
-```csharp
-public class BindableProperty<T>
-{
-    // 构造函数
-    public BindableProperty(T initialValue = default);
-
-    // 获取或设置值
-    public T Value { get; set; }
-
-    // 注册监听器
-    public IUnRegister Register(Action<T> onValueChanged);
-
-    // 注册监听器（包含初始值）
-    public IUnRegister RegisterWithInitValue(Action<T> onValueChanged);
-
-    // 获取当前值
-    public T GetValue();
-
-    // 设置值
-    public void SetValue(T newValue);
-}
-```
-
-### ILocalizationManager
-
-```csharp
-public interface ILocalizationManager : ISystem
-{
-    // 获取当前语言代码
-    string CurrentLanguage { get; }
-
-    // 获取当前文化信息
-    CultureInfo CurrentCulture { get; }
-
-    // 获取可用语言列表
-    IReadOnlyList<string> AvailableLanguages { get; }
-
-    // 设置当前语言
-    void SetLanguage(string languageCode);
-
-    // 获取本地化表
-    ILocalizationTable GetTable(string tableName);
-
-    // 获取本地化文本
-    string GetText(string table, string key);
-
-    // 获取本地化字符串（支持变量）
-    ILocalizationString GetString(string table, string key);
-
-    // 尝试获取本地化文本
-    bool TryGetText(string table, string key, out string text);
-
-    // 注册格式化器
-    void RegisterFormatter(string name, ILocalizationFormatter formatter);
-
-    // 订阅语言变化事件
-    void SubscribeToLanguageChange(Action<string> callback);
-
-    // 取消订阅语言变化事件
-    void UnsubscribeFromLanguageChange(Action<string> callback);
-}
-```
-
-### ILocalizationString
-
-```csharp
-public interface ILocalizationString
-{
-    // 获取表名
-    string Table { get; }
-
-    // 获取键名
-    string Key { get; }
-
-    // 添加变量
-    ILocalizationString WithVariable(string name, object value);
-
-    // 批量添加变量
-    ILocalizationString WithVariables(params (string name, object value)[] variables);
-
-    // 格式化并返回文本
-    string Format();
-
-    // 获取原始文本
-    string GetRaw();
-
-    // 检查键是否存在
-    bool Exists();
-}
-```
-
-### LocalizationConfig
-
-```csharp
-public class LocalizationConfig
-{
-    // 默认语言代码
-    public string DefaultLanguage { get; set; } = "eng";
-
-    // 回退语言代码
-    public string FallbackLanguage { get; set; } = "eng";
-
-    // 本地化文件路径
-    public string LocalizationPath { get; set; } = "res://localization";
-
-    // 用户覆盖路径
-    public string OverridePath { get; set; } = "user://localization_override";
-
-    // 是否启用热重载
-    public bool EnableHotReload { get; set; } = true;
-
-    // 是否在加载时验证
-    public bool ValidateOnLoad { get; set; } = true;
-}
-```
-
-## 扩展方法
-
-### 架构扩展
-
-```csharp
-// 发送命令
-public static void SendCommand<T>(this IBelongToArchitecture self, T command)
-    where T : ICommand;
-
-// 发送查询
-public static TResult SendQuery<TQuery, TResult>(
-    this IBelongToArchitecture self, TQuery query)
-    where TQuery : IQuery<TResult>;
-
-// 发送事件
-public static void SendEvent<T>(this IBelongToArchitecture self, T e)
-    where T : IEvent;
-
-// 获取模型
-public static T GetModel<T>(this IBelongToArchitecture self)
-    where T : IModel;
-
-// 获取系统
-public static T GetSystem<T>(this IBelongToArchitecture self)
-    where T : ISystem;
-
-// 获取工具
-public static T GetUtility<T>(this IBelongToArchitecture self)
-    where T : IUtility;
-
-// 注册事件
-public static IUnRegister RegisterEvent<T>(
-    this IBelongToArchitecture self, Action<T> onEvent)
-    where T : IEvent;
-```
-
-### 属性扩展
-
-```csharp
-// 添加到注销列表
-public static IUnRegister AddToUnregisterList(
-    this IUnRegister self, IUnRegisterList list);
-
-// 注销所有
-public static void UnRegisterAll(this IUnRegisterList self);
-```
-
-## 游戏模块 API
-
-### GFramework.Game
-
-游戏业务扩展模块。
-
-#### 主要类型
-
-| 类型            | 说明     |
-|---------------|--------|
-| `GameSetting` | 游戏设置   |
-| `GameState`   | 游戏状态   |
-| `IGameModule` | 游戏模块接口 |
-
-## Godot 集成 API
-
-### GFramework.Godot
-
-Godot 引擎集成模块。
-
-#### 主要类型
-
-| 类型               | 说明         |
-|------------------|------------|
-| `GodotNode`      | Godot 节点扩展 |
-| `GodotCoroutine` | Godot 协程   |
-| `GodotSignal`    | Godot 信号   |
-
-## 源码生成器
-
-### Source Generators 家族
-
-自动代码生成工具按模块拆分为 `GFramework.Core.SourceGenerators`、`GFramework.Game.SourceGenerators`、
-`GFramework.Godot.SourceGenerators` 与 `GFramework.Cqrs.SourceGenerators`。面向业务代码声明的 Attribute
-主要来自 `GFramework.Core.SourceGenerators.Abstractions.*` 与对应模块的 runtime/generator 包。
-
-#### 支持的生成器
-
-| 生成器                                        | 说明          |
-|--------------------------------------------|-------------|
-| `LoggingGenerator`                         | 日志生成器       |
-| `EnumGenerator`                            | 枚举扩展生成器     |
-| `RuleGenerator`                            | 规则生成器       |
-| `AutoRegisterModuleGenerator`              | 架构模块注册生成器   |
-| `AutoUiPageGenerator`                      | UI 页面行为生成器  |
-| `AutoSceneGenerator`                       | 场景行为生成器     |
-| `AutoRegisterExportedCollectionsGenerator` | 导出集合批量注册生成器 |
-
-#### 常用 Attribute
-
-| Attribute                                  | 说明                                        | 文档                                                                                                          |
-|--------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------|
-| `AutoRegisterModuleAttribute`              | 为模块类生成 `Install(IArchitecture)`           | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md)                            |
-| `RegisterModelAttribute`                   | 声明模块内自动注册的 `IModel` 类型                    | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md)                            |
-| `RegisterSystemAttribute`                  | 声明模块内自动注册的 `ISystem` 类型                   | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md)                            |
-| `RegisterUtilityAttribute`                 | 声明模块内自动注册的 `IUtility` 类型                  | [AutoRegisterModule 生成器](../source-generators/auto-register-module-generator.md)                            |
-| `AutoUiPageAttribute`                      | 为 `CanvasItem` 页面节点生成 `GetPage()`         | [AutoUiPage 生成器](../source-generators/auto-ui-page-generator.md)                                            |
-| `AutoSceneAttribute`                       | 为场景根节点生成 `GetScene()`                     | [AutoScene 生成器](../source-generators/auto-scene-generator.md)                                               |
-| `AutoLoadAttribute`                        | 显式声明 `project.godot` AutoLoad 与 C# 节点类型映射 | [Godot 项目元数据生成器](../source-generators/godot-project-generator.md)                                           |
-| `AutoRegisterExportedCollectionsAttribute` | 为宿主类开启导出集合批量注册生成                          | [AutoRegisterExportedCollections 生成器](../source-generators/auto-register-exported-collections-generator.md) |
-| `RegisterExportedCollectionAttribute`      | 指定集合与注册器成员的映射关系                           | [AutoRegisterExportedCollections 生成器](../source-generators/auto-register-exported-collections-generator.md) |
-
-## 常见用法示例
-
-### 创建架构
-
-```csharp
-public class MyArchitecture : Architecture
-{
-    protected override void Init()
-    {
-        RegisterModel(new PlayerModel());
-        RegisterSystem(new PlayerSystem());
-        RegisterUtility(new StorageUtility());
-    }
-}
-
-// 使用
-var arch = new MyArchitecture();
-arch.Initialize();
-```
-
-### 发送命令
-
-```csharp
-public class AttackCommand : AbstractCommand
-{
-    public int Damage { get; set; }
-
-    protected override void OnDo()
-    {
-        var player = this.GetModel<PlayerModel>();
-        this.SendEvent(new AttackEvent { Damage = Damage });
-    }
-}
-
-// 使用
-arch.SendCommand(new AttackCommand { Damage = 10 });
-```
-
-### 发送查询
-
-```csharp
-public class GetPlayerHealthQuery : AbstractQuery<int>
-{
-    protected override int OnDo()
-    {
-        return this.GetModel<PlayerModel>().Health.Value;
-    }
-}
-
-// 使用
-var health = arch.SendQuery(new GetPlayerHealthQuery());
-```
-
-### 监听事件
-
-```csharp
-public class PlayerSystem : AbstractSystem
-{
-    protected override void OnInit()
-    {
-        this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
-    }
-
-    private void OnPlayerDied(PlayerDiedEvent e)
-    {
-        Console.WriteLine("Player died!");
-    }
-}
-```
-
-### 使用本地化
-
-```csharp
-// 初始化本地化管理器
-var config = new LocalizationConfig
-{
-    DefaultLanguage = "eng",
-    LocalizationPath = "res://localization"
-};
-var locManager = new LocalizationManager(config);
-locManager.Initialize();
-
-// 获取简单文本
-string title = locManager.GetText("common", "game.title");
-
-// 使用变量
-var message = locManager.GetString("common", "ui.message.welcome")
-    .WithVariable("playerName", "Alice")
-    .Format();
-
-// 切换语言
-locManager.SetLanguage("zhs");
-
-// 监听语言变化
-locManager.SubscribeToLanguageChange(language =>
-{
-    Console.WriteLine($"Language changed to: {language}");
-});
-```
-
+---
+title: API 参考
+description: GFramework 的 API 阅读入口，按模块映射 README、专题页、XML 文档和教程链路。
 ---

-更多详情请查看各模块的详细文档。
+# API 参考
+
+这里不再维护一份脱离源码演化的“伪 API 列表”。
+
+当前 `GFramework` 的 API 参考链路以四类证据协同为准：
+
+1. 模块 README：说明包关系、最小接入路径和目录边界
+2. `docs/zh-CN` 专题页：说明采用顺序、生命周期和使用建议
+3. 代码中的 XML 文档：说明公开 / 内部类型和关键成员的契约
+4. 教程页：说明这些 API 在真实接入路径中的组合方式
+
+## 阅读顺序
+
+### 想确认“该装哪个包、先看哪类 API”
+
+先读模块 README，再读对应 landing page：
+
+- 入门入口：[`../getting-started/index.md`](../getting-started/index.md)
+- 根模块地图：仓库根 `README.md`
+
+### 想确认“这个功能属于哪个模块”
+
+按下面的模块映射进入对应入口：
+
+| 模块族 | 模块 README | 站内入口 | XML 文档关注点 |
+| --- | --- | --- | --- |
+| `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志契约 |
+| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/index.md`](../source-generators/index.md) | request / notification / handler / pipeline / registry contract |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
+| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/index.md`](../source-generators/index.md) | 节点扩展、场景 / UI 适配、资源 / 存储 / 日志接入 |
+| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` | [`../ecs/index.md`](../ecs/index.md)、[`../ecs/arch.md`](../ecs/arch.md)、[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
+
+## 先看 XML，还是先看教程
+
+### 先看 XML 文档的情况
+
+- 你在确认公开类型的约束、线程 / 生命周期语义、参数和返回值契约
+- 你需要区分“抽象层保证了什么”和“默认实现额外提供了什么”
+- 你在做多模块拆分、测试替身或扩展适配层
+
+优先关注这些类型族：
+
+- 架构 / 模块 / 服务入口
+- 生命周期、注册、路由、工厂、provider 契约
+- Source Generator 的 attribute、diagnostic 和 generated contract
+
+### 先看教程和专题页的情况
+
+- 你要的是最小接入路径，而不是逐个类型审计
+- 你想确认模块组合方式、目录约定和推荐接线顺序
+- 你在做从旧入口迁移到新入口的采用决策
+
+优先入口：
+
+- 教程概览：[`../tutorials/index.md`](../tutorials/index.md)
+- 最佳实践：[`../best-practices/index.md`](../best-practices/index.md)
+- 故障排查：[`../troubleshooting.md`](../troubleshooting.md)
+
+## 当前边界
+
+- `GFramework.Core.SourceGenerators.Abstractions`
+- `GFramework.Godot.SourceGenerators.Abstractions`
+- `GFramework.SourceGenerators.Common`
+
+这些目录当前不是独立消费模块，因此不单独维护站内 API 参考入口。它们的公开说明跟随所属模块 README 和
+`source-generators` 栏目维护。
+
+## 使用方式
+
+把本页当成“API 阅读导航”而不是“签名快照”：
+
+- 先选模块
+- 再进 README 和专题页确认采用路径
+- 最后回到代码里的 XML 文档核对具体契约
+
+当 README、专题页和 XML 文档出现冲突时，以源码和测试所反映的当前实现为准。