docs(godot): 刷新 Godot 文档入口

- 更新 GFramework.Godot README，使包定位、相邻包关系与最小接入路径与当前源码和测试一致 - 重写 GFramework.Godot.SourceGenerators README，补齐 project.godot、节点注入、行为包装与批量注册入口 - 补充 API 参考与 ai-plan 恢复点，确保 Godot 相关入口能直接落到专题页
2026-05-06 16:16:44 +08:00 · 2026-04-23 09:54:44 +08:00 · 2026-04-23 09:54:44 +08:00 · 9295480866
commit 9295480866
parent 7d6ff77ff4
5 changed files with 359 additions and 167 deletions
--- a/GFramework.Godot.SourceGenerators/README.md
+++ b/GFramework.Godot.SourceGenerators/README.md
@ -1,181 +1,176 @@
 # GFramework.Godot.SourceGenerators

-面向 Godot 场景的源码生成扩展模块，减少模板代码。
+`GFramework.Godot.SourceGenerators` 负责把 Godot 项目里的重复样板迁移到编译期。

-## 主要功能
+当前包覆盖三类核心场景：

- 与 Godot 场景相关的编译期生成能力
- 基于 Roslyn 的增量生成器实现
- `project.godot` 项目元数据生成，产出 AutoLoad 与 Input Action 的强类型访问入口
- `[GetNode]` 字段注入，减少 `_Ready()` 里的 `GetNode<T>()` 样板代码
- `[BindNodeSignal]` 方法绑定，减少 `_Ready()` / `_ExitTree()` 中重复的事件订阅样板代码
+- `project.godot` 元数据入口：生成 `AutoLoads` 与 `InputActions`
+- 节点字段与信号接线：`[GetNode]`、`[BindNodeSignal]`
+- Scene / UI 与启动注册样板：`[AutoScene]`、`[AutoUiPage]`、`[AutoRegisterExportedCollections]`

-## 使用建议
+它是 Analyzer 包，不是运行时库。

- 仅在 Godot + C# 项目中启用
- 非 Godot 项目可只使用 GFramework.SourceGenerators
- 当项目通过 NuGet 包引用本模块时，根目录下的 `project.godot` 会被自动加入 `AdditionalFiles`
- 当项目通过 `ProjectReference(OutputItemType=Analyzer)` 直接引用生成器时，需要手动把 `project.godot` 加入
-  `AdditionalFiles`
+## 包定位

-## project.godot 集成
+当前生成器主要减少这些重复代码：

-默认情况下，生成器会读取 Godot 项目根目录下的 `project.godot`，并生成：
+- 从 `project.godot` 手写 AutoLoad / Input Action 字符串
+- 在 `_Ready()` 里重复写 `GetNode<T>()`
+- 在 `_Ready()` / `_ExitTree()` 里重复写 CLR event 订阅与解绑
+- 为 Godot 场景根节点和页面根节点重复声明 `GetScene()` / `GetPage()` 样板
+- 在启动入口里重复遍历导出集合并逐项注册到 registry
+
+它不负责：
+
+- 提供运行时 Scene / UI / 配置实现
+- 自动接管完整生命周期方法
+- 代替 `GFramework.Godot` 的宿主适配逻辑
+
+## 与相邻包的关系
+
+- `GFramework.Godot`
+  - 负责 Godot 运行时适配。
+  - 本包只负责编译期入口和样板生成。
+- `GFramework.Godot.SourceGenerators.Abstractions`
+  - 特性定义所在位置。
+  - 当前 `IsPackable=false`，按内部支撑模块处理，不作为独立消费包推广。
+- `GFramework.SourceGenerators.Common`
+  - 提供公共生成器基础设施与部分类级诊断支持。
+  - 同样按内部支撑模块处理。
+
+## 子系统地图
+
+### `GodotProjectMetadataGenerator`
+
+读取 `project.godot`，生成：

 - `GFramework.Godot.Generated.AutoLoads`
 - `GFramework.Godot.Generated.InputActions`

-如果你需要覆盖默认项目文件路径，可以在 MSBuild 中设置：
+这是项目级元数据入口，不处理节点字段注入或信号绑定。

- 路径可以调整到项目根目录下的其他位置
- 文件名必须仍然是 `project.godot`，否则生成器会发出警告并忽略该文件
+### `GetNodeGenerator` 与 `BindNodeSignalGenerator`

-```xml
-<PropertyGroup>
-  <GFrameworkGodotProjectFile>Config/project.godot</GFrameworkGodotProjectFile>
-</PropertyGroup>
-```
+- `[GetNode]` 负责生成节点字段注入代码
+- `[BindNodeSignal]` 负责生成 CLR event 绑定 / 解绑辅助方法

-如果你在仓库内通过 analyzer 形式直接引用本项目，则需要显式配置：
+这两项能力通常一起使用，但职责不同：
+
+- `[GetNode]` 解决“怎么拿到字段实例”
+- `[BindNodeSignal]` 解决“字段可用后怎么订阅 / 解绑事件”
+
+### `Behavior/`
+
+- `AutoSceneGenerator`
+- `AutoUiPageGenerator`
+
+用于给场景根节点和 UI 页面根节点生成稳定的 `GetScene()` / `GetPage()` 包装入口。
+
+### `Registration/`
+
+- `AutoRegisterExportedCollectionsGenerator`
+
+用于把“遍历导出集合并逐项调用 registry 方法”的启动样板收敛成生成方法。
+
+### `Diagnostics/`
+
+当前诊断围绕这些方向组织：
+
+- `project.godot` 文件与元数据约束
+- `GetNode` / `BindNodeSignal` 的目标成员合法性
+- `AutoScene` / `AutoUiPage` 的宿主类型与参数合法性
+- 导出集合注册的成员形状与方法匹配约束
+
+## 最小接入路径
+
+### 1. 安装生成器包
+
+常规 NuGet 引用方式：

 ```xml
 <ItemGroup>
+  <PackageReference Include="GeWuYou.GFramework.Godot.SourceGenerators"
+                    Version="x.y.z"
+                    PrivateAssets="all"
+                    ExcludeAssets="runtime" />
+</ItemGroup>
+```
+
+通常还会同时引用：
+
+```xml
+<PackageReference Include="GeWuYou.GFramework.Godot" Version="x.y.z" />
+```
+
+### 2. 让 `project.godot` 进入 `AdditionalFiles`
+
+通过 NuGet 包使用时，`GeWuYou.GFramework.Godot.SourceGenerators.targets` 会自动尝试把项目根目录下的 `project.godot`
+加入 `AdditionalFiles`。
+
+如果你是仓库内直接通过 `ProjectReference(OutputItemType=Analyzer)` 引用生成器项目，需要手动加入：
+
+```xml
+<ItemGroup>
+  <ProjectReference Include="..\GFramework.Godot.SourceGenerators\GFramework.Godot.SourceGenerators.csproj"
+                    OutputItemType="Analyzer"
+                    ReferenceOutputAssembly="false" />
  <AdditionalFiles Include="project.godot" />
 </ItemGroup>
 ```

-## AutoLoad 强类型访问
+### 3. 在节点脚本里显式接生成方法

-当某个 AutoLoad 无法仅靠类型名唯一推断到 C# 节点类型时，可以使用 `[AutoLoad]` 显式声明映射：
+当前最重要的生命周期约束是：

-```csharp
-using GFramework.Godot.SourceGenerators.Abstractions;
-using Godot;
+- `[GetNode]` 在类型手写 `_Ready()` 时，需要显式调用 `__InjectGetNodes_Generated()`
+- `[BindNodeSignal]` 在手写 `_Ready()` / `_ExitTree()` 时，需要显式调用
+  `__BindNodeSignals_Generated()` 与 `__UnbindNodeSignals_Generated()`
+- `[AutoScene]`、`[AutoUiPage]`、`[AutoRegisterExportedCollections]` 都只生成辅助入口，不会替你织入生命周期

-[AutoLoad("GameServices")]
-public partial class GameServices : Node
-{
-}
-```
+也就是说，本包负责生成辅助方法，但调用时机仍由项目侧决定。

-对应 `project.godot`：
+### 4. 按场景选特性

-```ini
-[autoload]
-GameServices="*res://autoload/game_services.tscn"
-AudioBus="*res://autoload/audio_bus.gd"
-```
+- 项目级元数据：
+  - `project.godot` -> `AutoLoads`、`InputActions`
+- 固定节点字段：
+  - `[GetNode]`
+- 固定 CLR event 订阅：
+  - `[BindNodeSignal]`
+- Godot 场景根节点：
+  - `[AutoScene]`
+- Godot UI 页面根节点：
+  - `[AutoUiPage]`
+- 启动入口中的集合批量注册：
+  - `[AutoRegisterExportedCollections]`

-生成器会产出统一入口：
+## 当前约束

-```csharp
-using GFramework.Godot.Generated;
+- `GFrameworkGodotProjectFile` 可以改相对路径，但文件名必须仍然是 `project.godot`
+- `[GetNode]` 与 `[BindNodeSignal]` 都要求宿主类型是顶层 `partial class`
+- `[BindNodeSignal]` 面向 CLR event，不会自动调用 `Connect()` / `Disconnect()`
+- `[AutoScene]` 与 `[AutoUiPage]` 只生成行为包装入口，不会替代 `SceneRouterBase` 或 `UiRouterBase`
+- `[AutoRegisterExportedCollections]` 只适合“集合 -> registry -> 单参数注册方法”这类稳定形状

-var gameServices = AutoLoads.GameServices;
+## 文档入口

-if (AutoLoads.TryGetAudioBus(out var audioBus))
-{
-}
-```
+- 生成器总览：[docs/zh-CN/source-generators/index.md](../docs/zh-CN/source-generators/index.md)
+- Godot 项目元数据：[docs/zh-CN/source-generators/godot-project-generator.md](../docs/zh-CN/source-generators/godot-project-generator.md)
+- `GetNode`：[docs/zh-CN/source-generators/get-node-generator.md](../docs/zh-CN/source-generators/get-node-generator.md)
+- `BindNodeSignal`：[docs/zh-CN/source-generators/bind-node-signal-generator.md](../docs/zh-CN/source-generators/bind-node-signal-generator.md)
+- `AutoScene`：[docs/zh-CN/source-generators/auto-scene-generator.md](../docs/zh-CN/source-generators/auto-scene-generator.md)
+- `AutoUiPage`：[docs/zh-CN/source-generators/auto-ui-page-generator.md](../docs/zh-CN/source-generators/auto-ui-page-generator.md)
+- `AutoRegisterExportedCollections`：[docs/zh-CN/source-generators/auto-register-exported-collections-generator.md](../docs/zh-CN/source-generators/auto-register-exported-collections-generator.md)
+- Godot 运行时入口：[../GFramework.Godot/README.md](../GFramework.Godot/README.md)
+- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md)

- 显式 `[AutoLoad]` 映射优先于隐式类型名推断
- 若同名映射冲突，生成器会给出诊断并退化为 `Godot.Node` 访问
- 若无法映射到 C# 节点类型，仍会生成可用的 `Godot.Node` 访问器
+## 什么时候不该先看这个包

-## Input Action 常量生成
+以下场景更适合先回到其他入口：

-`project.godot` 的 `[input]` 段会自动生成稳定常量，避免手写字符串：
-
-```ini
-[input]
-move_up={
-}
-ui_cancel={
-}
-```
-
-```csharp
-using GFramework.Godot.Generated;
-
-if (Input.IsActionJustPressed(InputActions.MoveUp))
-{
-}
-```
-
- 动作名会转换为可补全的 C# 标识符，例如 `move_up -> MoveUp`
- 当多个动作名映射到同一标识符时，会追加稳定后缀并给出警告
-
-## GetNode 用法
-
-```csharp
-using GFramework.Godot.SourceGenerators.Abstractions;
-using Godot;
-
-public partial class TopBar : HBoxContainer
-{
-    [GetNode]
-    private HBoxContainer _leftContainer = null!;
-
-    [GetNode]
-    private HBoxContainer _rightContainer = null!;
-
-    public override void _Ready()
-    {
-        __InjectGetNodes_Generated();
-        OnReadyAfterGetNode();
-    }
-
-    private void OnReadyAfterGetNode()
-    {
-    }
-}
-```
-
-当未显式填写路径时，生成器会默认将字段名推导为唯一名路径：
-
- `_leftContainer` -> `%LeftContainer`
- `m_rightContainer` -> `%RightContainer`
-
-## BindNodeSignal 用法
-
-```csharp
-using GFramework.Godot.SourceGenerators.Abstractions;
-using Godot;
-
-public partial class Hud : Control
-{
-    [GetNode]
-    private Button _startButton = null!;
-
-    [GetNode]
-    private SpinBox _startOreSpinBox = null!;
-
-    [BindNodeSignal(nameof(_startButton), nameof(Button.Pressed))]
-    private void OnStartButtonPressed()
-    {
-    }
-
-    [BindNodeSignal(nameof(_startOreSpinBox), nameof(SpinBox.ValueChanged))]
-    private void OnStartOreValueChanged(double value)
-    {
-    }
-
-    public override void _Ready()
-    {
-        __InjectGetNodes_Generated();
-        __BindNodeSignals_Generated();
-    }
-
-    public override void _ExitTree()
-    {
-        __UnbindNodeSignals_Generated();
-    }
-}
-```
-
-生成器会产出两个辅助方法：
-
- `__BindNodeSignals_Generated()`：负责统一订阅事件
- `__UnbindNodeSignals_Generated()`：负责统一解绑事件
-
-当前设计只处理 CLR event 形式的 Godot 事件绑定，不会自动调用 `Connect()` / `Disconnect()`。
+- 你在确认 Godot 运行时 Scene / UI / 存储 / 设置的默认实现：
+  - 先看 `GFramework.Godot`
+- 你只需要 `Game` 契约，不需要 Godot 宿主或生成器：
+  - 先看 `GFramework.Game` 或 `GFramework.Game.Abstractions`
+- 你在确认项目接线顺序，而不是单个生成器契约：
+  - 先看 `docs/zh-CN/tutorials/godot-integration.md`
--- a/GFramework.Godot/README.md
+++ b/GFramework.Godot/README.md
@ -1,19 +1,161 @@
 # GFramework.Godot

-GFramework 框架的 Godot 引擎集成模块，提供Godot特定的功能和扩展。
+`GFramework.Godot` 是 `GFramework` 在 Godot 宿主侧的运行时适配包。

-## 主要功能
+它建立在 `GFramework.Game`、`GFramework.Game.Abstractions` 与 `GFramework.Core.Abstractions` 之上，把框架已有的架构、
+Scene / UI、配置、存储、设置、日志与协程能力接到 `Node`、`SceneTree`、`PackedScene`、`FileAccess` 与 `AudioServer`
+等 Godot 运行时对象上。

- **Extensions** - Godot节点扩展方法，简化常见开发任务
- **Signal** - 流畅的信号连接API，支持链式调用
- **Storage** - Godot文件存储系统，支持虚拟路径
- **Settings** - Godot设置系统，管理音频和图形设置
+如果你需要的是 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 或 `InputActions` 这类编译期能力，请改为同时安装
+`GFramework.Godot.SourceGenerators`。这些能力不属于本包。

-## 依赖关系
+## 包定位

- 依赖 GFramework.Core
- 依赖 GFramework.Core.Abstractions
+当前包解决的是 Godot 运行时接线，而不是重新定义一套 Godot 专属框架：

-## 详细文档
+- 架构生命周期与场景树绑定：`AbstractArchitecture`、`ArchitectureAnchor`
+- 节点运行时辅助：`WaitUntilReadyAsync()`、`AddChildXAsync()`、`QueueFreeX()`、`UnRegisterWhenNodeExitTree(...)`
+- Godot 风格的 Scene / UI 工厂与 registry：`GodotSceneFactory`、`GodotUiFactory`
+- Godot 特化的配置、存储与设置实现：`GodotYamlConfigLoader`、`GodotFileStorage`、`GodotAudioSettings`
+- 宿主侧辅助能力：`Signal(...)` fluent API、Godot 时间源、暂停处理、富文本效果

-参见 [docs/zh-CN/godot/](../docs/zh-CN/godot/) 目录下的详细文档。
+它不负责：
+
+- 自动生成节点字段注入代码
+- 自动生成 `_Ready()` / `_ExitTree()` 接线
+- 自动扫描所有场景或页面并完成统一注册
+- 提供 `GodotSceneRouter` 或 `GodotUiRouter` 这类额外 router 类型
+
+## 与相邻包的关系
+
+- `GFramework.Game`
+  - 提供 Scene / UI / 配置 / 数据等默认运行时契约与基类。
+  - `GFramework.Godot` 负责把这些能力落到 Godot 宿主。
+- `GFramework.Game.Abstractions`
+  - 提供 `ISceneFactory`、`IUiFactory`、设置与配置相关契约。
+  - 本包的大部分工厂和适配层都实现这些接口。
+- `GFramework.Core.Abstractions`
+  - 提供架构、日志、环境等基础契约。
+  - `AbstractArchitecture` 与日志 provider 都建立在这层之上。
+- `GFramework.Godot.SourceGenerators`
+  - 提供 `project.godot` 元数据、`[GetNode]`、`[BindNodeSignal]`、`[AutoScene]`、`[AutoUiPage]` 等编译期样板生成。
+  - 推荐与本包配套使用，但职责边界要分开理解。
+
+## 子系统地图
+
+### `Architectures/`
+
+- `AbstractArchitecture`
+- `AbstractGodotModule`
+- `ArchitectureAnchor`
+- `IGodotModule`
+
+用于把架构生命周期绑定到 `SceneTree`，并在需要时把 Godot 模块挂到场景树。
+
+### `Scene/` 与 `UI/`
+
+- `GodotSceneFactory`、`GodotSceneRegistry`
+- `GodotUiFactory`、`GodotUiRegistry`
+- `SceneBehaviorFactory`、`UiPageBehaviorFactory`
+
+这部分负责把 `PackedScene`、`Control`、`CanvasLayer` 等 Godot 对象接入 `GFramework.Game` 的 Scene / UI 契约。
+
+### `Config/`、`Storage/` 与 `Setting/`
+
+- `GodotYamlConfigLoader`
+- `GodotFileStorage`
+- `GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
+
+这部分解决的是 Godot 文件系统、音频总线、图形与本地化设置等宿主差异。
+
+### `Extensions/`、`Coroutine/`、`Logging/`、`Pause/`、`Text/`、`Pool/`
+
+- 节点扩展与 `Signal(...)` fluent API
+- `GodotTimeSource` 与协程时间分段
+- Godot 日志 provider
+- 暂停处理、节点池与富文本效果支持
+
+这些目录都是“宿主适配层”，不是新的 gameplay 抽象层。
+
+## 最小接入路径
+
+### 1. 先区分运行时包和生成器包
+
+如果你只需要 Godot 运行时适配：
+
+```bash
+dotnet add package GeWuYou.GFramework
+dotnet add package GeWuYou.GFramework.Godot
+```
+
+如果你还需要 `project.godot` 强类型入口、节点字段注入和信号绑定，再额外安装：
+
+```bash
+dotnet add package GeWuYou.GFramework.Core.SourceGenerators
+dotnet add package GeWuYou.GFramework.Godot.SourceGenerators
+```
+
+### 2. 保持原有架构注册方式，只把宿主协作接到 Godot
+
+常规模块继续使用 `InstallModule(...)`。
+
+只有模块自身暴露 `Node`、需要挂到 `ArchitectureAnchor`，或要在 `OnAttach(...)` / `OnDetach()` 里处理 Godot 生命周期副作用时，
+再使用 `InstallGodotModule(...)`。
+
+`GFramework.Godot.Tests/Architectures/AbstractArchitectureModuleInstallationTests.cs` 已覆盖一个关键边界：锚点缺失时会先抛
+`InvalidOperationException`，不会继续执行模块安装。
+
+### 3. Scene / UI 继续沿用 `Game` 契约
+
+当前真实边界是：
+
+- 没有 `GodotSceneRouter`
+- 没有 `GodotUiRouter`
+- `GodotSceneFactory` 在 provider 缺失时回退到 `SceneBehaviorFactory`
+- `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
+
+也就是说，项目通常仍然继承 `GFramework.Game.Scene.SceneRouterBase` 与 `GFramework.Game.UI.UiRouterBase`，只是把工厂和行为落到
+Godot 上。
+
+### 4. 按需接入配置、存储和设置
+
+当项目已经使用 `Game` family 的配置、存储、设置契约时，再补 Godot 侧实现：
+
+- 配置：`GodotYamlConfigLoader`
+- 存储：`GodotFileStorage`
+- 设置：`GodotAudioSettings`、`GodotGraphicsSettings`、`GodotLocalizationSettings`
+
+不要把这些宿主实现误写成 `Game` family 的默认行为。
+
+## `ai-libs/` 里的参考接入线索
+
+`ai-libs/CoreGrid` 仍是当前最直接的消费者证据来源：
+
+- 架构侧保持普通模块注册，再按需挂接 Godot 宿主
+- `project.godot` 元数据与节点样板交给 `GFramework.Godot.SourceGenerators`
+- Scene / UI 继续沿用 `Game` family 的 router 语义
+
+当 `ai-libs/` 与源码或测试冲突时，应以当前源码与测试为准。
+
+## 文档入口
+
+- Godot 运行时总览：[docs/zh-CN/godot/index.md](../docs/zh-CN/godot/index.md)
+- 架构集成：[docs/zh-CN/godot/architecture.md](../docs/zh-CN/godot/architecture.md)
+- 场景系统：[docs/zh-CN/godot/scene.md](../docs/zh-CN/godot/scene.md)
+- UI 系统：[docs/zh-CN/godot/ui.md](../docs/zh-CN/godot/ui.md)
+- 节点扩展：[docs/zh-CN/godot/extensions.md](../docs/zh-CN/godot/extensions.md)
+- 信号系统：[docs/zh-CN/godot/signal.md](../docs/zh-CN/godot/signal.md)
+- 日志系统：[docs/zh-CN/godot/logging.md](../docs/zh-CN/godot/logging.md)
+- 集成教程：[docs/zh-CN/tutorials/godot-integration.md](../docs/zh-CN/tutorials/godot-integration.md)
+- 生成器入口：[../GFramework.Godot.SourceGenerators/README.md](../GFramework.Godot.SourceGenerators/README.md)
+
+## 什么时候不该把它当成主入口
+
+以下场景更适合先回到其他包：
+
+- 只需要 Scene / UI / 配置契约，不需要 Godot 宿主：
+  - 选 `GFramework.Game.Abstractions`
+- 需要默认运行时实现，但暂时不接 Godot：
+  - 选 `GFramework.Game`
+- 需要的是 `project.godot` 元数据、节点字段注入或编译期样板：
+  - 选 `GFramework.Godot.SourceGenerators`
--- 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,12 +12,12 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-010`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-011`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 将 `Godot` family 的关键恢复摘要回填到 active topic，避免后续 `boot` 默认依赖 archive 才能恢复核心上下文
-  - 保留 `documentation-governance-and-refresh` archive 的细节历史，但在 active topic 中记录足够的页面范围、owner 与运行时边界
-  - 继续抽查 README / landing page / API reference 之间的 cross-link 是否出现新的漂移
+  - 继续巡检 `Godot` / `Game` 相关 README、landing page 与 API reference 的 cross-link 是否回漂
+  - 保持 `Godot` family 的模块 README、生成器 README 与站内专题页使用同一套 owner / adoption path 叙述
+  - 仅在发现新的入口漂移时补最小修复，不重复改写已经稳定的 landing page

 ## 当前状态摘要

@ -39,6 +39,10 @@
  - `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是当前需要保留的核心页面集
  - `GFramework.Godot.SourceGenerators` 继续作为 `[GetNode]`、`[BindNodeSignal]`、`AutoLoads` 与 `InputActions` 的 owner；`GFramework.Godot.SourceGenerators.Abstractions` 仍按内部支撑模块处理
  - `Godot` Scene / UI 采用边界已经稳定：当前没有 `GodotSceneRouter` 或 `GodotUiRouter`；`GodotSceneFactory` 在 provider 缺失时会回退到 `SceneBehaviorFactory`，而 `GodotUiFactory` 仍要求 `IUiPageBehaviorProvider`
+- `2026-04-23` 的交叉链接巡检新增结论：
+  - `GFramework.Godot/README.md` 仍停留在旧版简略描述，缺少当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
+  - `GFramework.Godot.SourceGenerators/README.md` 虽有示例，但没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 等当前生成器分组，也没有把运行时 / 生成器边界说清
+  - `docs/zh-CN/api-reference/index.md` 的 `Godot` 行此前只把生成器入口指向泛化的 `source-generators/index.md`，不利于从 API 参考直接落到 `Godot` 专题页
 - 本轮已完成的治理动作：
  - 新建 `GFramework.Ecs.Arch.Abstractions/README.md`
  - 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner
@ -67,6 +71,9 @@
  - 记录当前环境偏差：本会话 `git.exe` 可解析但执行会触发 `Exec format error`，而 plain Linux `git` 会命中 worktree 路径翻译错误，需要显式仓库绑定
  - 完成 `Game` family 巡检，确认 `docs/zh-CN/game/config-system.md`、`scene.md`、`ui.md` 与 `docs/zh-CN/source-generators/index.md` 的核心采用说明、包关系与交叉引用仍与当前源码 / README 一致，没有发现需要立刻修正的回漂
  - 将 `Godot` family 的最小恢复摘要迁回 active topic，保留核心页面集、生成器 owner、Scene / UI 真实边界与归档指针，避免长期治理默认恢复路径继续依赖 archive 明细
+  - 重写 `GFramework.Godot/README.md`，补齐包定位、相邻包关系、子系统地图、最小接入路径与站内文档入口，并明确它不拥有生成器职责
+  - 重写 `GFramework.Godot.SourceGenerators/README.md`，按 `project.godot` 元数据、节点注入 / 信号绑定、行为包装与批量注册四组能力重建入口
+  - 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 模块映射，使 API 参考能直接落到 `Godot` 专用生成器专题页，而不是仅回到总览页

 ## Inventory（第一版）

@ -75,7 +82,7 @@
 | `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 |
 | `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `README / landing / generator topic / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md`、`docs/zh-CN/core/cqrs.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/api-reference/index.md` 已对齐当前源码与测试 | 转入巡检；下一波切到 `Game` family 的 XML / 教程链路审计 |
 | `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/abstractions/game-abstractions.md` 已对齐当前源码与目录基线 | 转入巡检；优先抽查 `config-system`、`scene`、`ui` 与 `source-generators` 交叉链路是否回漂 |
-| `Godot` / `Godot.SourceGenerators` | `核心 landing / topic / tutorial 已校验，active topic 已回填最小恢复摘要` | `docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md`、`docs/zh-CN/tutorials/godot-integration.md`，以及归档 topic 中的 `Godot` 治理历史 | 进入巡检周期，优先抽查 cross-link 与源码回漂；详细历史继续留在 archive |
+| `Godot` / `Godot.SourceGenerators` | `README / 生成器 README / landing / topic / tutorial / API reference 入口已重新对齐，成员级 XML 审计不在本轮范围` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、`architecture.md`、`scene.md`、`ui.md`、`signal.md`、`extensions.md`、`logging.md`、`docs/zh-CN/tutorials/godot-integration.md` | 进入巡检周期，优先观察后续分支是否再次把 README / API 入口写回过时边界 |
 | `Ecs.Arch` / `Ecs.Arch.Abstractions` | `README / landing / abstractions / 类型族级 XML inventory 已收口，成员级审计待补齐` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md`、`docs/zh-CN/ecs/**`、`docs/zh-CN/abstractions/ecs-arch-abstractions.md` 已对齐当前源码与测试 | 转入巡检；后续仅在运行时公共 API 变动时补成员级 XML 细审 |
 | `SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` | `已判定为内部支撑` | `*.csproj` 明确 `IsPackable=false` | 由所属模块 README 与生成器栏目说明 owner，不建独立采用页 |

@ -115,7 +122,7 @@
  - 结果：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号，不再构成本轮阻塞
 - 最新构建结论：
  - `2026-04-23` `cd docs && bun run build`
-  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败
+  - 结果：通过；在 `Godot` README / API 入口修复后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败
 - 最新恢复治理结论：
  - `2026-04-23` 重新读取 `ai-plan/public/archive/documentation-governance-and-refresh/**`
  - 结果：通过；确认 `Godot` family 适合把最小恢复摘要迁回 active topic，但不需要把整段归档历史重新放回默认 `boot` 路径
@ -124,9 +131,14 @@
  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/index.md`：通过
  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
+  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md`：通过
+  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot/README.md`：通过
+  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过
+  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`：通过
+  - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`：通过

 ## 下一步

-1. 继续抽查 README / landing page / API reference 的 cross-link 是否出现新的漂移，优先覆盖 `Godot` 与 `Game` 相关入口
-2. 当后续分支再修改 README / docs / 公共 API 时，回到对应 module family 追加 targeted 巡检与验证
+1. 继续抽查 `Game` 与 `Godot` 相邻入口，优先看根 `README.md`、`docs/zh-CN/source-generators/index.md` 与教程页之间是否仍有旧 owner 描述
+2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证
 3. 仅在需要阶段级细节时再读取 `documentation-governance-and-refresh` archive，而不是把 archive 重新当作默认 `boot` 入口
--- 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
@ -352,3 +352,46 @@

 1. 抽查 `Godot` 与 `Game` 相关 README / landing page / API reference 的 cross-link 是否出现新的漂移
 2. 当后续分支修改相关 README / docs / 公共 API 时，回到对应 module family 追加 targeted 巡检与验证
+
+### 当前恢复点：RP-011
+
+- 继续按 `boot` 恢复后的默认下一步执行 `Godot` / `Game` cross-link 巡检，并额外补读：
+  - `GFramework.Godot/README.md`
+  - `GFramework.Godot.SourceGenerators/README.md`
+  - `docs/zh-CN/api-reference/index.md`
+  - `docs/zh-CN/godot/index.md`
+  - `docs/zh-CN/source-generators/index.md`
+- 结合 `GFramework.Godot.csproj`、`GFramework.Godot.SourceGenerators.csproj`、相关测试与 `scan_module_evidence.py` 输出，确认新的漂移点集中在入口 README：
+  - `GFramework.Godot/README.md` 仍是旧版简略说明，没有记录当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口
+  - `GFramework.Godot.SourceGenerators/README.md` 没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 这些当前已发布的生成器分组
+  - `docs/zh-CN/api-reference/index.md` 的 `Godot` 映射仍只把生成器入口落到泛化总览页，恢复效率偏低
+- 因此本轮执行最小修复集：
+  - 重写 `GFramework.Godot/README.md`
+  - 重写 `GFramework.Godot.SourceGenerators/README.md`
+  - 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 行
+
+### 当前决策（RP-011）
+
+- 这轮不改 `docs/zh-CN/godot/**` landing / topic 页面，因为站内页面本身没有发现新的事实漂移，问题集中在仓库 README 与 API 入口的回退
+- `GFramework.Godot` README 必须和 `Game` / `Godot` 真实边界一致，明确它不是生成器 owner，也不引入虚构的 router 类型
+- `GFramework.Godot.SourceGenerators` README 采用“元数据 / 节点注入与信号绑定 / 行为包装 / 批量注册”四段式入口，避免读者只看到旧的三项能力
+- API 参考页对 `Godot` 生成器入口直接给出专题页链接，而不是仅要求读者再从总览页二次分流
+
+### 当前验证（RP-011）
+
+- 模块扫描：
+  - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot`：通过
+  - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot.SourceGenerators`：通过
+- 文档校验：
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md`：通过
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot/README.md`：通过
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过
+  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.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，无构建失败
+
+### 下一步
+
+1. 继续抽查根 `README.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是否仍把 `Godot` owner 写回旧边界
+2. 当后续分支继续修改 `Game` / `Godot` family 入口时，沿用当前 README -> landing -> API reference 的最小修复顺序
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -32,7 +32,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 | `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/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback 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 适配、资源 / 存储 / 日志接入 |
+| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/godot-project-generator.md`](../source-generators/godot-project-generator.md)、[`../source-generators/get-node-generator.md`](../source-generators/get-node-generator.md)、[`../source-generators/bind-node-signal-generator.md`](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
 | `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，还是先看教程