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

Docs/sdk update documentation
2026-05-06 16:16:44 +08:00 · 2026-04-24 17:57:23 +08:00 · 2026-04-24 17:57:23 +08:00 · 4c2994ee52
commit 4c2994ee52
parent 63f563cd49 546e6c7b11
58 changed files with 282 additions and 259 deletions
--- a/GFramework.Core.Abstractions/README.md
+++ b/GFramework.Core.Abstractions/README.md
@ -49,7 +49,7 @@ XML 注释。这里记录的是类型族级基线，成员级契约细节仍需
 | `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage` |
 | `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` |

-完整 inventory 与阅读顺序见 `docs/zh-CN/abstractions/core-abstractions.md`。
+完整接入说明与阅读顺序见 [Core 抽象层说明](../docs/zh-CN/abstractions/core-abstractions.md)。

 ## 采用建议

--- a/GFramework.Core/README.md
+++ b/GFramework.Core/README.md
@ -75,7 +75,7 @@ XML 注释。这里先保留阅读基线，成员级 ``<param>`` / ``<returns>``
 | `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`LocalizationManager`、`ConfigurationManager`、`DefaultEnvironment`、`MicrosoftDiContainer` |
 | `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` |

-完整的模块化阅读顺序和 inventory 说明见 `docs/zh-CN/core/index.md`。
+完整的模块化接入说明和阅读顺序见 [Core 栏目](../docs/zh-CN/core/index.md)。

 ## 最小接入路径

--- a/GFramework.Cqrs.Abstractions/README.md
+++ b/GFramework.Cqrs.Abstractions/README.md
@ -97,5 +97,5 @@ public sealed class GetPlayerProfileHandler

 ## 文档入口

- 运行时与整体接入说明：`docs/zh-CN/core/cqrs.md`
- 如果你需要默认实现而不是契约层，请看 `GFramework.Cqrs/README.md`
+- 运行时与整体接入说明：[CQRS 栏目](../docs/zh-CN/core/cqrs.md)
+- 如果你需要默认实现而不是契约层，请看 [GFramework.Cqrs README](../GFramework.Cqrs/README.md)
--- a/GFramework.Cqrs/README.md
+++ b/GFramework.Cqrs/README.md
@ -150,5 +150,5 @@ var playerId = await this.SendAsync(new CreatePlayerCommand(new CreatePlayerInpu

 ## 文档入口

- 总体文档：`docs/zh-CN/core/cqrs.md`
- 契约层说明：`GFramework.Cqrs.Abstractions/README.md`
+- 总体文档：[CQRS 栏目](../docs/zh-CN/core/cqrs.md)
+- 契约层说明：[GFramework.Cqrs.Abstractions README](../GFramework.Cqrs.Abstractions/README.md)
--- a/GFramework.Game.Abstractions/README.md
+++ b/GFramework.Game.Abstractions/README.md
@ -236,14 +236,14 @@ public sealed class ContinueGameCommandHandler

 虽然大部分详细文档写在 `GFramework.Game` 侧，但阅读顺序仍然适用于本包：

- 游戏模块总览：[docs/zh-CN/game/index.md](../docs/zh-CN/game/index.md)
- 内容配置系统：[docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md)
- 数据与存档：[docs/zh-CN/game/data.md](../docs/zh-CN/game/data.md)
- 设置系统：[docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md)
- 存储系统：[docs/zh-CN/game/storage.md](../docs/zh-CN/game/storage.md)
- 序列化系统：[docs/zh-CN/game/serialization.md](../docs/zh-CN/game/serialization.md)
- 场景系统：[docs/zh-CN/game/scene.md](../docs/zh-CN/game/scene.md)
- UI 系统：[docs/zh-CN/game/ui.md](../docs/zh-CN/game/ui.md)
+- 游戏模块总览：[Game 模块总览](../docs/zh-CN/game/index.md)
+- 内容配置系统：[内容配置系统](../docs/zh-CN/game/config-system.md)
+- 数据与存档：[数据与存档系统](../docs/zh-CN/game/data.md)
+- 设置系统：[设置系统](../docs/zh-CN/game/setting.md)
+- 存储系统：[存储系统](../docs/zh-CN/game/storage.md)
+- 序列化系统：[序列化系统](../docs/zh-CN/game/serialization.md)
+- 场景系统：[场景系统](../docs/zh-CN/game/scene.md)
+- UI 系统：[UI 系统](../docs/zh-CN/game/ui.md)

 ## 选择建议

--- a/GFramework.Game/README.md
+++ b/GFramework.Game/README.md
@ -57,8 +57,8 @@

 对应文档：

- [docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md)
- [docs/zh-CN/game/index.md](../docs/zh-CN/game/index.md)
+- [内容配置系统](../docs/zh-CN/game/config-system.md)
+- [Game 模块总览](../docs/zh-CN/game/index.md)

 ### `Data/`

@ -81,8 +81,8 @@

 对应文档：

- [docs/zh-CN/game/data.md](../docs/zh-CN/game/data.md)
- [docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md)
+- [数据与存档系统](../docs/zh-CN/game/data.md)
+- [设置系统](../docs/zh-CN/game/setting.md)

 ### `Setting/`

@ -105,7 +105,7 @@

 对应文档：

- [docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md)
+- [设置系统](../docs/zh-CN/game/setting.md)

 ### `Storage/`

@ -121,7 +121,7 @@

 对应文档：

- [docs/zh-CN/game/storage.md](../docs/zh-CN/game/storage.md)
+- [存储系统](../docs/zh-CN/game/storage.md)
 - [GFramework.Game/Storage/ReadMe.md](./Storage/ReadMe.md)

 ### `Serializer/`
@ -134,7 +134,7 @@

 对应文档：

- [docs/zh-CN/game/serialization.md](../docs/zh-CN/game/serialization.md)
+- [序列化系统](../docs/zh-CN/game/serialization.md)

 ### `Scene/` 与 `UI/`

@ -157,8 +157,8 @@

 对应文档：

- [docs/zh-CN/game/scene.md](../docs/zh-CN/game/scene.md)
- [docs/zh-CN/game/ui.md](../docs/zh-CN/game/ui.md)
+- [场景系统](../docs/zh-CN/game/scene.md)
+- [UI 系统](../docs/zh-CN/game/ui.md)

 ### `Routing/` 与 `State/`

@ -293,7 +293,7 @@ var registry = bootstrap.Registry;

 这一能力几乎总是与 source generators 绑定使用。目录、schema、生成器与热重载约定请直接看：

- [docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md)
+- [内容配置系统](../docs/zh-CN/game/config-system.md)

 ### 4. 接入 Scene / UI 路由

@ -342,14 +342,14 @@ public sealed class MyUiRouter : UiRouterBase

 ## 文档入口

- 游戏模块总览：[docs/zh-CN/game/index.md](../docs/zh-CN/game/index.md)
- 内容配置系统：[docs/zh-CN/game/config-system.md](../docs/zh-CN/game/config-system.md)
- 数据与存档：[docs/zh-CN/game/data.md](../docs/zh-CN/game/data.md)
- 设置系统：[docs/zh-CN/game/setting.md](../docs/zh-CN/game/setting.md)
- 存储系统：[docs/zh-CN/game/storage.md](../docs/zh-CN/game/storage.md)
- 序列化系统：[docs/zh-CN/game/serialization.md](../docs/zh-CN/game/serialization.md)
- 场景系统：[docs/zh-CN/game/scene.md](../docs/zh-CN/game/scene.md)
- UI 系统：[docs/zh-CN/game/ui.md](../docs/zh-CN/game/ui.md)
+- 游戏模块总览：[Game 模块总览](../docs/zh-CN/game/index.md)
+- 内容配置系统：[内容配置系统](../docs/zh-CN/game/config-system.md)
+- 数据与存档：[数据与存档系统](../docs/zh-CN/game/data.md)
+- 设置系统：[设置系统](../docs/zh-CN/game/setting.md)
+- 存储系统：[存储系统](../docs/zh-CN/game/storage.md)
+- 序列化系统：[序列化系统](../docs/zh-CN/game/serialization.md)
+- 场景系统：[场景系统](../docs/zh-CN/game/scene.md)
+- UI 系统：[UI 系统](../docs/zh-CN/game/ui.md)

 ## 什么时候不该直接依赖本包

--- a/GFramework.Godot.SourceGenerators/README.md
+++ b/GFramework.Godot.SourceGenerators/README.md
@ -183,15 +183,15 @@ public partial class MainMenu : Control

 ## 文档入口

- 生成器总览：[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)
+- 生成器总览：[源码生成器总览](../docs/zh-CN/source-generators/index.md)
+- Godot 项目元数据：[Godot 项目生成器](../docs/zh-CN/source-generators/godot-project-generator.md)
+- `GetNode`：[GetNode 生成器](../docs/zh-CN/source-generators/get-node-generator.md)
+- `BindNodeSignal`：[BindNodeSignal 生成器](../docs/zh-CN/source-generators/bind-node-signal-generator.md)
+- `AutoScene`：[AutoScene 生成器](../docs/zh-CN/source-generators/auto-scene-generator.md)
+- `AutoUiPage`：[AutoUiPage 生成器](../docs/zh-CN/source-generators/auto-ui-page-generator.md)
+- `AutoRegisterExportedCollections`：[AutoRegisterExportedCollections 生成器](../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)
+- 集成教程：[Godot 集成教程](../docs/zh-CN/tutorials/godot-integration.md)

 ## 什么时候不该先看这个包

@ -202,4 +202,4 @@ public partial class MainMenu : Control
 - 你只需要 `Game` 契约，不需要 Godot 宿主或生成器：
  - 先看 `GFramework.Game` 或 `GFramework.Game.Abstractions`
 - 你在确认项目接线顺序，而不是单个生成器契约：
-  - 先看 `docs/zh-CN/tutorials/godot-integration.md`
+  - 先看 [Godot 集成教程](../docs/zh-CN/tutorials/godot-integration.md)
--- a/GFramework.Godot/README.md
+++ b/GFramework.Godot/README.md
@ -139,14 +139,14 @@ Godot 上。

 ## 文档入口

- 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)
+- Godot 运行时总览：[Godot 模块总览](../docs/zh-CN/godot/index.md)
+- 架构集成：[Godot 架构集成](../docs/zh-CN/godot/architecture.md)
+- 场景系统：[Godot 场景系统](../docs/zh-CN/godot/scene.md)
+- UI 系统：[Godot UI 系统](../docs/zh-CN/godot/ui.md)
+- 节点扩展：[Godot 节点扩展](../docs/zh-CN/godot/extensions.md)
+- 信号系统：[Godot 信号系统](../docs/zh-CN/godot/signal.md)
+- 日志系统：[Godot 日志系统](../docs/zh-CN/godot/logging.md)
+- 集成教程：[Godot 集成教程](../docs/zh-CN/tutorials/godot-integration.md)
 - 生成器入口：[../GFramework.Godot.SourceGenerators/README.md](../GFramework.Godot.SourceGenerators/README.md)

 ## 什么时候不该把它当成主入口
--- a/README.md
+++ b/README.md
@ -11,8 +11,8 @@

 ## 从哪里开始

- 第一次接触框架：[`docs/zh-CN/getting-started/index.md`](docs/zh-CN/getting-started/index.md)
- 想先跑一个最小例子：[`docs/zh-CN/getting-started/quick-start.md`](docs/zh-CN/getting-started/quick-start.md)
+- 第一次接触框架：[入门指南](docs/zh-CN/getting-started/index.md)
+- 想先跑一个最小例子：[快速开始](docs/zh-CN/getting-started/quick-start.md)
 - 已经知道要用哪个模块：直接进入对应模块目录下的 `README.md`

 ## 模块地图
@ -41,25 +41,25 @@
 | --- | --- | --- |
 | `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) |
+| `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [源码生成器总览](docs/zh-CN/source-generators/index.md) |

 ## 文档导航

 仓库根 README 与文档站点保持同一套栏目命名：

- 入门指南：[`docs/zh-CN/getting-started/index.md`](docs/zh-CN/getting-started/index.md)
- Core：[`docs/zh-CN/core/index.md`](docs/zh-CN/core/index.md)
- Game：[`docs/zh-CN/game/index.md`](docs/zh-CN/game/index.md)
- Godot：[`docs/zh-CN/godot/index.md`](docs/zh-CN/godot/index.md)
- 教程：[`docs/zh-CN/tutorials/index.md`](docs/zh-CN/tutorials/index.md)
- 源码生成器：[`docs/zh-CN/source-generators/index.md`](docs/zh-CN/source-generators/index.md)
- ECS：[`docs/zh-CN/ecs/index.md`](docs/zh-CN/ecs/index.md)
- 抽象接口：[`docs/zh-CN/abstractions/index.md`](docs/zh-CN/abstractions/index.md)
- 最佳实践：[`docs/zh-CN/best-practices/index.md`](docs/zh-CN/best-practices/index.md)
- API 参考：[`docs/zh-CN/api-reference/index.md`](docs/zh-CN/api-reference/index.md)
- FAQ：[`docs/zh-CN/faq.md`](docs/zh-CN/faq.md)
- 故障排查：[`docs/zh-CN/troubleshooting.md`](docs/zh-CN/troubleshooting.md)
- 贡献：[`docs/zh-CN/contributing.md`](docs/zh-CN/contributing.md)
+- 入门指南：[入门指南](docs/zh-CN/getting-started/index.md)
+- Core：[Core](docs/zh-CN/core/index.md)
+- Game：[Game](docs/zh-CN/game/index.md)
+- Godot：[Godot](docs/zh-CN/godot/index.md)
+- 教程：[教程](docs/zh-CN/tutorials/index.md)
+- 源码生成器：[源码生成器](docs/zh-CN/source-generators/index.md)
+- ECS：[ECS](docs/zh-CN/ecs/index.md)
+- 抽象接口：[抽象接口](docs/zh-CN/abstractions/index.md)
+- 最佳实践：[最佳实践](docs/zh-CN/best-practices/index.md)
+- API 参考：[API 参考](docs/zh-CN/api-reference/index.md)
+- FAQ：[常见问题](docs/zh-CN/faq.md)
+- 故障排查：[故障排查](docs/zh-CN/troubleshooting.md)
+- 贡献：[贡献指南](docs/zh-CN/contributing.md)

 ## 包选择

@ -146,7 +146,7 @@ GFramework.sln
 提交功能或行为变更时，请把代码、测试和文档一起更新：

 1. 先阅读对应模块目录下的 `README.md`
-2. 如果改动影响采用路径、安装方式、公共 API 或目录结构，同时更新 `docs/zh-CN/`
+2. 如果改动影响采用路径、安装方式、公共 API 或目录结构，同时更新受影响的中文文档页面，必要时同步调整 [中文文档入口](docs/zh-CN/index.md)
 3. 对跨模块或多阶段任务，维护 `ai-plan/public/README.md` 与对应主题目录下的 tracking / trace

 ## 许可证
--- 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-026`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-029`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 收口 PR `#282` 的 latest-head review follow-up，保持 active tracking / trace 只承载当前恢复入口
+  - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口模块 `README.md`、`docs/index.md` 与多组中文落地页之间的读者入口对齐
  - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明
-  - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题
+  - 继续优先处理低风险 metadata 缺口、坏链、README 文档入口对齐、Reader-friendly 链接标签与 Markdown 结构问题，避免跨模块语义改写
  - 保持 `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/`
@ -25,12 +25,16 @@
 ## 当前状态摘要

 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
- `2026-04-24` 使用 `$gframework-pr-review` 抓取 PR `#282` 后，确认 latest head commit
-  `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；4 条建议均已在本地复核并纳入当前恢复点。
+- `2026-04-24` 当前分支累计 diff 已接近 `$gframework-batch-boot 75` 的 stop condition（约 `58 / 75` 个 changed files）；后续 follow-up 应继续保持小 write set，只处理仍然成立的 PR review 项。
+- `2026-04-24` 使用 `$gframework-pr-review` 抓取当前 PR `#284` 后，确认 latest head commit
+  `77540c07f0890cc05b10a849722c87b8bed8f561` 仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；本轮仅继续收口本地复核后仍成立的 reader-facing 文档入口与 active tracking 精简问题。
 - 本轮 PR follow-up 仅收口仍然成立的 review 项：
  - 将过长的 active tracking / trace 瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入 `archive/`
  - 将 `docs/zh-CN/core/context.md` 的标题本地化为中文读者友好的写法
  - 统一 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 的 `.md` 链接写法
+- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`，让首页和基础教程章节页拥有完整 frontmatter metadata。
+- 本批次统一将教程、最佳实践、Core、Godot 页面里缺显式扩展名的站内 Markdown 链接补齐为 `.md` 或 `index.md`，避免目录链接、绝对路径旧写法与 VitePress 构建解析分叉。
+- 本批次把模块 README、仓库根 README、`docs/index.md` 及多组中文落地页里直接暴露文件路径的入口调整为读者友好的可点击标签，同时补齐语言落地页 metadata 与 README 指向。
 - `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`
  作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。
 - `Godot` runtime 与 generator 入口当前以 `GFramework.Godot/README.md`、
@ -62,18 +66,27 @@

 ## 最新验证

- `2026-04-24` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
-  - 结果：通过；PR `#282` 处于 `OPEN`，latest head commit 有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。
+- `2026-04-24` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json`
+  - 结果：通过；PR `#284` 处于 `OPEN`，latest head commit `77540c07f0890cc05b10a849722c87b8bed8f561` 有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。
 - `2026-04-24` `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?<!\\.md)\\)' docs/zh-CN/troubleshooting.md`
  - 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。
 - `2026-04-24` `bun run build`（工作目录：`docs/`）
  - 结果：通过；文档标题本地化、站内链接修正与 `ai-plan` 归档瘦身落地后站点仍可正常构建，仅保留既有大 chunk warning。
+- `2026-04-24` `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` frontmatter 是否缺 `title` / `description`）
+  - 结果：通过；当前带 frontmatter 的 `docs/zh-CN` 页面已无 `title` / `description` 缺口。
+- `2026-04-24` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。
+- `2026-04-24` `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` 中以 `./`、`../`、`/zh-CN/` 开头且未带扩展名的 Markdown 链接）
+  - 结果：通过；当前 `docs/zh-CN` 站内 Markdown 链接已无缺失扩展名的命中。
+- `2026-04-24` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；`25` 个页面的站内链接补齐为显式 `.md` / `index.md` 后站点仍可正常构建，仅保留既有大 chunk warning。
+- `2026-04-24` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；模块 README、中文落地页 reader-facing 文档入口对齐，以及 `docs/index.md` metadata 调整后站点仍可正常构建，仅保留既有大 chunk warning。

 ## 下一步

-1. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8`
-   个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
-2. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
+1. 当前分支已接近 `$gframework-batch-boot 75` 的 stop condition；若继续执行后续批次，应优先选择 `5` 到 `10` 个文件以内的小批次，避免显著降低 reviewability。
+2. 推送当前批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#284` 的 unresolved review threads 是否已在新 head commit 上消失。
 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
   `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
 4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.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
@ -2,32 +2,25 @@

 ## 2026-04-24

-### 当前恢复点：RP-026
+### 当前恢复点：RP-030

- 使用 `$gframework-pr-review` 抓取 PR `#282`，确认 latest head commit
-  `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread。
- 按“只处理 latest-head unresolved threads 中仍成立的问题”的原则，本轮仅收口 4 条本地可复现的 follow-up：
-  - 将 `tracking.md` 与 `trace.md` 的活动入口瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入新 archive 文件
-  - 将 `docs/zh-CN/core/context.md` 的标题与主标题本地化为 `上下文（Context）`
-  - 将 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 统一补成显式 `.md` 链接
+- 当前 follow-up 聚焦 `$gframework-pr-review` 在 PR `#284` 上仍然成立的 review 项，只处理公开 README 的 reader-facing 文案与 active tracking 精简问题。
+- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，当前分支 cumulative diff 已接近 stop condition，应继续把 write set 控制在小批次范围内。
+- 本批次计划修改 `3` 个 README 与 `2` 个 `ai-plan` 入口文件，避免再次扩张到跨模块文档面。

-### 当前决策（RP-026）
+### 当前决策（RP-030）

- PR review follow-up 继续遵守“先本地验证，再决定是否修复”；对已经过时或无法在当前分支复现的评论不做追随式修改。
- active `ai-plan` 入口只保留当前恢复点、活动事实、风险、最新验证与下一步；批次细节统一迁入 `archive/`。
- `docs/zh-CN` 页面应优先使用中文标题；同一帮助块中的绝对站内链接应保持一致的显式 `.md` 写法。
+- 当 branch diff 已接近 `$gframework-batch-boot 75` 的阈值时，PR follow-up 只继续收口最新 head commit 上仍未消失、且能在本地验证成立的 review 线程。
+- 公开 README 不再使用 `inventory` 这类治理语境，也不把贡献指引缩窄到单一入口页；文案应明确“受影响页面”与“接入说明/阅读顺序”。
+- active tracking 需要保留恢复点与风险信息，但不再保留完整 commit SHA、精确时间戳与拆分式文件计数这类过细基线指标。

-### 当前验证（RP-026）
+### 当前验证（RP-030）

 - PR review 抓取：
-  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
-  - 结果：通过；PR `#282` 处于 `OPEN`，最新 review 线程与测试状态已成功解析，测试汇总为 `2156 passed`。
- 链接巡检：
-  - `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?<!\\.md)\\)' docs/zh-CN/troubleshooting.md`
-  - 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。
- 站点构建：
-  - `bun run build`（工作目录：`docs/`）
-  - 结果：通过；本轮文档与 `ai-plan` 调整后站点仍可正常构建，仅保留既有大 chunk warning。
+  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json`
+  - 结果：通过；PR `#284` 处于 `OPEN`，latest head commit `77540c07f0890cc05b10a849722c87b8bed8f561` 仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。
+- 当前 stop-condition metric：
+  - 分支 cumulative diff 已接近 `58 / 75`；本轮 follow-up 继续限制在 `3` 个 README 与 `2` 个 `ai-plan` 入口文件内。

 ### 归档指针

@ -39,5 +32,5 @@

 ### 下一步

-1. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
-2. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
+1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#284` 的 unresolved review threads 是否已在新 head commit 上消失。
+2. 若继续执行 `$gframework-batch-boot 75`，优先选择 `5` 到 `10` 个文件以内的小批次，例如剩余零散的 README reader-facing 文案修正。
--- a/docs/index.md
+++ b/docs/index.md
@ -1,5 +1,7 @@
---
+---
 layout: page
+title: Language Selection
+description: Redirects visitors to the current Chinese documentation entry and keeps the language landing page discoverable.
 ---

 <script setup>
@ -39,4 +41,4 @@ onMounted(() => {
  <p style="margin-top: 40px; color: #666;">
    Auto-redirecting... / 自动跳转中...
  </p>
-</div>
+</div>
--- a/docs/zh-CN/abstractions/core-abstractions.md
+++ b/docs/zh-CN/abstractions/core-abstractions.md
@ -98,6 +98,6 @@ public sealed class DiagnosticsFeature
 1. 先读本页，确认你是否真的只需要契约层
 2. 再看 [`../core/index.md`](../core/index.md) 了解默认运行时怎么组织这些契约
 3. 回到模块 README：
-   - [`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
-   - [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
+   - [`GFramework.Core.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
+   - [`GFramework.Core README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
 4. 需要统一导航时，再看 [`../api-reference/index.md`](../api-reference/index.md)
--- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md
+++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md
@ -90,5 +90,5 @@ var options = new ArchOptions
 1. 先读本页，确认你是否真的只需要契约层
 2. 如果需要默认实现，再看 [`../ecs/arch.md`](../ecs/arch.md)
 3. 回到对应模块 README：
-   - [`GFramework.Ecs.Arch.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md)
-   - [`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
+   - [`GFramework.Ecs.Arch.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md)
+   - [`GFramework.Ecs.Arch README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
--- a/docs/zh-CN/abstractions/game-abstractions.md
+++ b/docs/zh-CN/abstractions/game-abstractions.md
@ -117,5 +117,5 @@ public sealed class ContinueGameCommandHandler
   - [`../game/scene.md`](../game/scene.md)
   - [`../game/ui.md`](../game/ui.md)
 4. 需要仓库侧入口时，回到：
-   - [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
-   - [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+   - [`GFramework.Game.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
+   - [`GFramework.Game README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -29,11 +29,11 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

 | 模块族 | 模块 README | 站内入口 | XML 文档关注点 |
 | --- | --- | --- | --- |
-| `Core` / `Core.Abstractions` | [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)、[`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/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`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)、[`GFramework.Cqrs.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.Abstractions/README.md)、[`GFramework.Cqrs.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/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`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)、[`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)、[`GFramework.Game.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/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`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)、[`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/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`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)、[`GFramework.Ecs.Arch.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/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 模块契约、系统适配、配置对象和运行时装配边界 |
+| `Core` / `Core.Abstractions` | [`GFramework.Core README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)、[`GFramework.Core.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md) | [`Core 栏目`](../core/index.md)、[`Core 抽象层说明`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
+| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [`GFramework.Cqrs README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)、[`GFramework.Cqrs.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.Abstractions/README.md)、[`GFramework.Cqrs.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md) | [`CQRS 栏目`](../core/cqrs.md)、[`CQRS Handler Registry 生成器`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
+| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [`GFramework.Game README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)、[`GFramework.Game.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)、[`GFramework.Game.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md) | [`Game 模块总览`](../game/index.md)、[`Game 抽象层说明`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
+| `Godot` / `Godot.SourceGenerators` | [`GFramework.Godot README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)、[`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) | [`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` | [`GFramework.Ecs.Arch README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)、[`GFramework.Ecs.Arch.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch.Abstractions/README.md) | [`ECS 模块总览`](../ecs/index.md)、[`Arch ECS 集成`](../ecs/arch.md)、[`Ecs.Arch 抽象层说明`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |

 ## 先看 XML，还是先看教程

--- a/docs/zh-CN/best-practices/architecture-patterns.md
+++ b/docs/zh-CN/best-practices/architecture-patterns.md
@ -3432,12 +3432,12 @@ public void GetPlayerStatsQuery_ShouldReturnCorrectStats()

 ### 相关资源

- [架构核心文档](/zh-CN/core/architecture)
- [命令模式文档](/zh-CN/core/command)
- [查询模式文档](/zh-CN/core/query)
- [事件系统文档](/zh-CN/core/events)
- [状态机文档](/zh-CN/core/state-machine)
- [IoC 容器文档](/zh-CN/core/ioc)
+- [架构核心文档](/zh-CN/core/architecture.md)
+- [命令模式文档](/zh-CN/core/command.md)
+- [查询模式文档](/zh-CN/core/query.md)
+- [事件系统文档](/zh-CN/core/events.md)
+- [状态机文档](/zh-CN/core/state-machine.md)
+- [IoC 容器文档](/zh-CN/core/ioc.md)

 记住，好的架构不是一蹴而就的，需要持续的学习、实践和改进。

--- a/docs/zh-CN/best-practices/mobile-optimization.md
+++ b/docs/zh-CN/best-practices/mobile-optimization.md
@ -970,10 +970,10 @@ public class DeviceProfiler

 ## 相关文档

- [资源管理系统](/zh-CN/core/resource) - 资源管理详细说明
- [对象池系统](/zh-CN/core/pool) - 对象池优化
- [协程系统](/zh-CN/core/coroutine) - 异步操作优化
- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns) - 架构设计
+- [资源管理系统](/zh-CN/core/resource.md) - 资源管理详细说明
+- [对象池系统](/zh-CN/core/pool.md) - 对象池优化
+- [协程系统](/zh-CN/core/coroutine.md) - 异步操作优化
+- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns.md) - 架构设计

 ---

--- a/docs/zh-CN/core/cqrs.md
+++ b/docs/zh-CN/core/cqrs.md
@ -186,4 +186,4 @@ RegisterCqrsPipelineBehavior<LoggingBehavior<,>>();
 - 架构入口：[architecture](./architecture.md)
 - 上下文入口：[context](./context.md)
 - 生成器专题：[../source-generators/cqrs-handler-registry-generator.md](../source-generators/cqrs-handler-registry-generator.md)
- 模块 README：[`GFramework.Cqrs/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
+- 模块 README：[`GFramework.Cqrs README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
--- a/docs/zh-CN/core/index.md
+++ b/docs/zh-CN/core/index.md
@ -71,7 +71,7 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions

 如果你已经知道模块归属，但想确认公开类型的契约边界，建议按下面顺序阅读：

-1. 先看模块 README [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)，确认包关系和目录边界
+1. 先看模块 README [`GFramework.Core`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)，确认包关系和目录边界
 2. 再看本栏目对应专题页，确认采用顺序、生命周期与推荐接线方式
 3. 最后回到源码中的 XML 文档，重点核对这些类型族：
   - `Architecture` / `IArchitectureContext`
@ -148,7 +148,7 @@ public sealed class CounterArchitecture : Architecture

 ## 对应模块入口

- [`GFramework.Core/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
- [`GFramework.Core.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
- [`docs/zh-CN/api-reference/index.md`](../api-reference/index.md)
+- [`GFramework.Core README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core/README.md)
+- [`GFramework.Core.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.Abstractions/README.md)
+- [API 参考入口](../api-reference/index.md)
 - 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)
--- a/docs/zh-CN/core/resource.md
+++ b/docs/zh-CN/core/resource.md
@ -501,7 +501,7 @@ Parallel.For(0, 10, i =>

 ## 相关文档

- [对象池系统](/zh-CN/core/pool) - 结合对象池复用资源
- [协程系统](/zh-CN/core/coroutine) - 异步加载资源
- [Godot 扩展](/zh-CN/godot/extensions) - Godot 引擎的资源管理
- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 详细教程
+- [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源
+- [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源
+- [Godot 扩展](/zh-CN/godot/extensions.md) - Godot 引擎的资源管理
+- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 详细教程
--- a/docs/zh-CN/core/state-machine.md
+++ b/docs/zh-CN/core/state-machine.md
@ -576,7 +576,7 @@ await stateMachine.GoBackAsync();

 ## 相关文档

- [生命周期管理](/zh-CN/core/lifecycle) - 状态的初始化和销毁
- [事件系统](/zh-CN/core/events) - 状态变更通知
- [协程系统](/zh-CN/core/coroutine) - 异步状态操作
- [状态机实现教程](/zh-CN/tutorials/state-machine-tutorial) - 完整示例
+- [生命周期管理](/zh-CN/core/lifecycle.md) - 状态的初始化和销毁
+- [事件系统](/zh-CN/core/events.md) - 状态变更通知
+- [协程系统](/zh-CN/core/coroutine.md) - 异步状态操作
+- [状态机实现教程](/zh-CN/tutorials/state-machine-tutorial.md) - 完整示例
--- a/docs/zh-CN/ecs/arch.md
+++ b/docs/zh-CN/ecs/arch.md
@ -140,5 +140,5 @@ ecsModule.Update(deltaTime);

 - ECS 模块总览：[`index.md`](./index.md)
 - 抽象契约页：[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md)
- 仓库模块 README：[`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
+- 仓库模块 README：[`GFramework.Ecs.Arch README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
 - 统一 API / XML 导航：[`../api-reference/index.md`](../api-reference/index.md)
--- a/docs/zh-CN/game/index.md
+++ b/docs/zh-CN/game/index.md
@ -127,6 +127,6 @@ IStorage storage = new FileStorage("GameData", serializer);

 ## 对应模块入口

- [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
- [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
+- [`GFramework.Game README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+- [`GFramework.Game.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
 - 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)
--- a/docs/zh-CN/game/scene.md
+++ b/docs/zh-CN/game/scene.md
@ -258,5 +258,5 @@ await sceneRouter.PopAsync();

 1. [game/index.md](./index.md)
 2. [ui.md](./ui.md)
-3. [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
-4. [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
+3. [`GFramework.Game README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+4. [`GFramework.Game.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
--- a/docs/zh-CN/game/ui.md
+++ b/docs/zh-CN/game/ui.md
@ -329,5 +329,5 @@ uiRouter.Hide(modalHandle, UiLayer.Modal);
 1. [game/index.md](./index.md)
 2. [scene.md](./scene.md)
 3. [../source-generators/auto-ui-page-generator.md](../source-generators/auto-ui-page-generator.md)
-4. [`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
-5. [`GFramework.Game.Abstractions/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
+4. [`GFramework.Game README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+5. [`GFramework.Game.Abstractions README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.Abstractions/README.md)
--- a/docs/zh-CN/getting-started/index.md
+++ b/docs/zh-CN/getting-started/index.md
@ -51,7 +51,7 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
 对应文档：

 - [`../core/cqrs.md`](../core/cqrs.md)
- 仓库内模块入口：[`GFramework.Cqrs/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)
+- 仓库内模块入口：[`GFramework.Cqrs README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md)

 ### 想做游戏运行时

@ -70,7 +70,7 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
 对应文档：

 - [`../game/index.md`](../game/index.md)
- 仓库内模块入口：[`GFramework.Game/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)
+- 仓库内模块入口：[`GFramework.Game README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game/README.md)

 ### 想接入 Godot

@ -81,7 +81,7 @@ description: 概览 GFramework 的模块组成、最小接入路径与继续阅
 对应文档：

 - [`../godot/index.md`](../godot/index.md)
- 仓库内模块入口：[`GFramework.Godot/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)
+- 仓库内模块入口：[`GFramework.Godot README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot/README.md)

 ## Source Generators 什么时候装

--- a/docs/zh-CN/godot/pause.md
+++ b/docs/zh-CN/godot/pause.md
@ -730,7 +730,7 @@ foreach (var reason in reasons)

 ## 相关文档

- [Godot 架构集成](/zh-CN/godot/architecture) - Godot 架构基础
- [Godot 场景系统](/zh-CN/godot/scene) - Godot 场景集成
- [Godot UI 系统](/zh-CN/godot/ui) - Godot UI 集成
- [Godot 扩展](/zh-CN/godot/extensions) - Godot 扩展方法
+- [Godot 架构集成](/zh-CN/godot/architecture.md) - Godot 架构基础
+- [Godot 场景系统](/zh-CN/godot/scene.md) - Godot 场景集成
+- [Godot UI 系统](/zh-CN/godot/ui.md) - Godot UI 集成
+- [Godot 扩展](/zh-CN/godot/extensions.md) - Godot 扩展方法
--- a/docs/zh-CN/godot/pool.md
+++ b/docs/zh-CN/godot/pool.md
@ -678,7 +678,7 @@ GD.Print($"使用池: {stopwatch.ElapsedMilliseconds}ms");

 ## 相关文档

- [对象池系统](/zh-CN/core/pool) - 核心对象池实现
- [Godot 架构集成](/zh-CN/godot/architecture) - Godot 架构基础
- [Godot 场景系统](/zh-CN/godot/scene) - Godot 场景管理
- [性能优化](/zh-CN/core/pool) - 性能优化最佳实践
+- [对象池系统](/zh-CN/core/pool.md) - 核心对象池实现
+- [Godot 架构集成](/zh-CN/godot/architecture.md) - Godot 架构基础
+- [Godot 场景系统](/zh-CN/godot/scene.md) - Godot 场景管理
+- [性能优化](/zh-CN/core/pool.md) - 性能优化最佳实践
--- a/docs/zh-CN/godot/resource.md
+++ b/docs/zh-CN/godot/resource.md
@ -631,7 +631,7 @@ public class LazyResourceRepository<TKey, TResource>

 ## 相关文档

- [数据与存档系统](/zh-CN/game/data) - 数据持久化
- [Godot 架构集成](/zh-CN/godot/architecture) - Godot 架构基础
- [Godot 场景系统](/zh-CN/godot/scene) - 场景资源管理
- [资源管理系统](/zh-CN/core/resource) - 核心资源管理
+- [数据与存档系统](/zh-CN/game/data.md) - 数据持久化
+- [Godot 架构集成](/zh-CN/godot/architecture.md) - Godot 架构基础
+- [Godot 场景系统](/zh-CN/godot/scene.md) - 场景资源管理
+- [资源管理系统](/zh-CN/core/resource.md) - 核心资源管理
--- a/docs/zh-CN/godot/signal.md
+++ b/docs/zh-CN/godot/signal.md
@ -104,7 +104,7 @@ slider.Signal(Range.SignalName.ValueChanged)

 ### 4. 静态场景绑定优先交给 `[BindNodeSignal]`

-从 `GFramework.Godot.SourceGenerators/README.md` 和 `ai-libs/CoreGrid` 的当前接法看，静态场景按钮、滑条、菜单项这类固定
+从 [`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) 和 `ai-libs/CoreGrid` 的当前接法看，静态场景按钮、滑条、菜单项这类固定
 节点，更常见的路径仍然是 `[BindNodeSignal]`：

 ```csharp
--- a/docs/zh-CN/index.md
+++ b/docs/zh-CN/index.md
@ -2,6 +2,7 @@
 # https://vitepress.dev/reference/default-theme-home-page
 layout: home
 title: GFramework
+description: 概览 GFramework 的模块能力、入门路径与主要中文文档入口。
 hero:
  name: "GFramework"
  text: 面向游戏开发的模块化 C# 架构体系
@ -35,4 +36,4 @@ features:

  - title: ⚡ Roslyn 源码生成器
    details: 自动生成日志、枚举扩展与规则代码，减少样板代码并提升开发效率。
---
+---
--- a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md
+++ b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md
@ -220,4 +220,4 @@ public List<IntConfig>? Values { get; } = new();
 1. [/zh-CN/source-generators/index](./index.md)
 2. [/zh-CN/game/config-system](../game/config-system.md)
 3. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
-4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
+4. [`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/bind-node-signal-generator.md
+++ b/docs/zh-CN/source-generators/bind-node-signal-generator.md
@ -189,4 +189,4 @@ private void OnAnyButtonPressed()
 1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md)
 2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
 3. [/zh-CN/godot/ui](../godot/ui.md)
-4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
+4. [`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/context-aware-generator.md
+++ b/docs/zh-CN/source-generators/context-aware-generator.md
@ -195,4 +195,4 @@ finally
 1. [context-get-generator.md](./context-get-generator.md)
 2. [logging-generator.md](./logging-generator.md)
 3. [../core/index.md](../core/index.md)
-4. [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
+4. [`GFramework.Core.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/get-node-generator.md
+++ b/docs/zh-CN/source-generators/get-node-generator.md
@ -195,4 +195,4 @@ public override void _Ready()
 1. [/zh-CN/source-generators/bind-node-signal-generator](./bind-node-signal-generator.md)
 2. [/zh-CN/source-generators/godot-project-generator](./godot-project-generator.md)
 3. [/zh-CN/godot/ui](../godot/ui.md)
-4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
+4. [`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/godot-project-generator.md
+++ b/docs/zh-CN/source-generators/godot-project-generator.md
@ -217,4 +217,4 @@ AutoLoad 名称也遵循同样的冲突处理策略。
 1. [/zh-CN/source-generators/get-node-generator](./get-node-generator.md)
 2. [/zh-CN/source-generators/bind-node-signal-generator](./bind-node-signal-generator.md)
 3. [/zh-CN/tutorials/godot-integration](../tutorials/godot-integration.md)
-4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
+4. [`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/index.md
+++ b/docs/zh-CN/source-generators/index.md
@ -101,7 +101,7 @@ GFramework 当前发布的生成器包是：

 ## 对应模块入口

- [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
- [`GFramework.Game.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md)
- [`GFramework.Cqrs.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md)
- [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
+- [`GFramework.Core.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
+- [`GFramework.Game.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Game.SourceGenerators/README.md)
+- [`GFramework.Cqrs.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.SourceGenerators/README.md)
+- [`GFramework.Godot.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md)
--- a/docs/zh-CN/source-generators/priority-generator.md
+++ b/docs/zh-CN/source-generators/priority-generator.md
@ -213,4 +213,4 @@ public sealed class DynamicPrioritySystem : IPrioritized
 1. [context-aware-generator.md](./context-aware-generator.md)
 2. [context-get-generator.md](./context-get-generator.md)
 3. [../core/index.md](../core/index.md)
-4. [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
+4. [`GFramework.Core.SourceGenerators README`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)
--- a/docs/zh-CN/tutorials/basic/01-environment.md
+++ b/docs/zh-CN/tutorials/basic/01-environment.md
@ -1,4 +1,6 @@
 ---
+title: 第 1 章：环境准备
+description: 说明开始基础教程前需要准备的操作系统、.NET SDK、Godot 与常用开发工具环境。
 prev:
  text: '教程首页'
  link: './index'
--- a/docs/zh-CN/tutorials/basic/02-project-setup.md
+++ b/docs/zh-CN/tutorials/basic/02-project-setup.md
@ -1,4 +1,6 @@
 ---
+title: 第 2 章：项目创建与初始化
+description: 指导创建 Godot C# 项目、引入 GFramework，并搭好基础目录与初始化结构。
 prev:
  text: '环境准备'
  link: './01-environment'
--- a/docs/zh-CN/tutorials/basic/03-counter-basic.md
+++ b/docs/zh-CN/tutorials/basic/03-counter-basic.md
@ -1,4 +1,6 @@
 ---
+title: 第 3 章：基础计数器实现
+description: 通过直接实现计数器场景与交互逻辑，建立后续架构重构的起点示例。
 prev:
  text: '项目创建与初始化'
  link: './02-project-setup'
--- a/docs/zh-CN/tutorials/basic/04-model-refactor.md
+++ b/docs/zh-CN/tutorials/basic/04-model-refactor.md
@ -1,4 +1,6 @@
 ---
+title: 第 4 章：引入 Model 重构
+description: 使用 Model 层与事件系统重构计数器应用，分离状态存储、事件通知与界面更新。
 prev:
  text: '基础计数器实现'
  link: './03-counter-basic'
--- a/docs/zh-CN/tutorials/basic/05-command-system.md
+++ b/docs/zh-CN/tutorials/basic/05-command-system.md
@ -1,4 +1,6 @@
 ---
+title: 第 5 章：命令系统优化
+description: 通过引入 Command 模式拆分 Controller 交互逻辑，建立更清晰的执行职责边界。
 prev:
  text: '引入 Model 重构'
  link: './04-model-refactor'
--- a/docs/zh-CN/tutorials/basic/06-utility-system.md
+++ b/docs/zh-CN/tutorials/basic/06-utility-system.md
@ -1,4 +1,6 @@
 ---
+title: 第 6 章：Utility 与 System
+description: 引入 Utility 与 System 承载业务规则和阈值检查，完成基础分层架构闭环。
 prev:
  text: '命令系统优化'
  link: './05-command-system'
--- a/docs/zh-CN/tutorials/basic/07-summary.md
+++ b/docs/zh-CN/tutorials/basic/07-summary.md
@ -1,4 +1,6 @@
 ---
+title: 第 7 章：总结与最佳实践
+description: 回顾基础教程的架构演进，整理最佳实践、常见问题与后续学习方向。
 prev:
  text: 'Utility 与 System'
  link: './06-utility-system'
@ -644,10 +646,10 @@ public override void _Process(double delta)
 ### 推荐资源

 - **GFramework 文档**：
-    - [Core 核心框架](../../core/)
-    - [Game 游戏模块](../../game/)
-    - [Godot 集成](../../godot/)
-    - [源码生成器](../../source-generators/)
+    - [Core 核心框架](../../core/index.md)
+    - [Game 游戏模块](../../game/index.md)
+    - [Godot 集成](../../godot/index.md)
+    - [源码生成器](../../source-generators/index.md)

 - **设计模式**：
    - 命令模式（Command Pattern）
--- a/docs/zh-CN/tutorials/basic/index.md
+++ b/docs/zh-CN/tutorials/basic/index.md
@ -173,10 +173,10 @@ description: 从零开始串联环境准备、项目搭建与核心概念的基

 ## 🔗 相关资源

- [GFramework 文档首页](../../)
- [Core 核心框架](../../core/)
- [Godot 集成](../../godot/)
- [源码生成器](../../source-generators/)
+- [GFramework 文档首页](../../index.md)
+- [Core 核心框架](../../core/index.md)
+- [Godot 集成](../../godot/index.md)
+- [源码生成器](../../source-generators/index.md)

 ## ❓ 遇到问题？

--- a/docs/zh-CN/tutorials/coroutine-tutorial.md
+++ b/docs/zh-CN/tutorials/coroutine-tutorial.md
@ -188,5 +188,5 @@ BlinkCoroutine()

 ## 下一步

- Core 侧更完整的 API 说明见 [Core 协程系统](/zh-CN/core/coroutine)
- Godot 集成细节见 [Godot 协程系统](/zh-CN/godot/coroutine)
+- Core 侧更完整的 API 说明见 [Core 协程系统](/zh-CN/core/coroutine.md)
+- Godot 集成细节见 [Godot 协程系统](/zh-CN/godot/coroutine.md)
--- a/docs/zh-CN/tutorials/data-migration.md
+++ b/docs/zh-CN/tutorials/data-migration.md
@ -20,9 +20,9 @@ description: 学习如何实现数据版本迁移系统，处理不同版本间

 - 已安装 GFramework.Game NuGet 包
 - 了解 C# 基础语法和接口实现
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[数据与存档系统](/zh-CN/game/data)
- 建议先完成[实现存档系统](/zh-CN/tutorials/save-system)教程
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[数据与存档系统](/zh-CN/game/data.md)
+- 建议先完成[实现存档系统](/zh-CN/tutorials/save-system.md)教程

 ## 为什么需要数据迁移

@ -647,9 +647,9 @@ MyGame/

 恭喜！你已经实现了一个完整的数据版本迁移系统。接下来可以学习：

- [实现存档系统](/zh-CN/tutorials/save-system) - 结合存档系统使用迁移
- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project) - 在实际项目中应用
- [数据与存档系统](/zh-CN/game/data) - 深入了解数据系统
+- [实现存档系统](/zh-CN/tutorials/save-system.md) - 结合存档系统使用迁移
+- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project.md) - 在实际项目中应用
+- [数据与存档系统](/zh-CN/game/data.md) - 深入了解数据系统

 ## 最佳实践

@ -780,6 +780,6 @@ public async Task<List<ISettingsSection>> MigrateBatchAsync(

 ## 相关文档

- [数据与存档系统](/zh-CN/game/data) - 数据系统详细说明
- [实现存档系统](/zh-CN/tutorials/save-system) - 存档系统教程
- [架构系统](/zh-CN/core/architecture) - 架构设计原则
+- [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明
+- [实现存档系统](/zh-CN/tutorials/save-system.md) - 存档系统教程
+- [架构系统](/zh-CN/core/architecture.md) - 架构设计原则
--- a/docs/zh-CN/tutorials/functional-programming.md
+++ b/docs/zh-CN/tutorials/functional-programming.md
@ -20,7 +20,7 @@ description: 学习如何在实际项目中使用 Option、Result 和管道操

 - 已安装 GFramework.Core NuGet 包
 - 了解 C# 基础语法和泛型
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
 - 了解 Lambda 表达式和 LINQ

 ## 步骤 1：使用 Option 处理可空值
@ -811,12 +811,12 @@ class Program

 恭喜！你已经掌握了函数式编程的核心技术。接下来可以学习：

- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 结合函数式编程和协程
- [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - 在状态机中应用函数式模式
- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 使用 Result 处理资源加载
+- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 结合函数式编程和协程
+- [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) - 在状态机中应用函数式模式
+- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 使用 Result 处理资源加载

 ## 相关文档

- [扩展方法](/zh-CN/core/extensions) - 更多函数式扩展方法
- [架构组件](/zh-CN/core/architecture) - 在架构中使用函数式编程
- [最佳实践](/zh-CN/best-practices/architecture-patterns) - 函数式编程最佳实践
+- [扩展方法](/zh-CN/core/extensions.md) - 更多函数式扩展方法
+- [架构组件](/zh-CN/core/architecture.md) - 在架构中使用函数式编程
+- [最佳实践](/zh-CN/best-practices/architecture-patterns.md) - 函数式编程最佳实践
--- a/docs/zh-CN/tutorials/godot-complete-project.md
+++ b/docs/zh-CN/tutorials/godot-complete-project.md
@ -22,9 +22,9 @@ description: 从零开始使用 GFramework 构建一个完整的 Godot 游戏项
 - 已安装 .NET SDK 8.0+
 - 了解 C# 和 Godot 基础
 - 阅读过前面的教程：
-    - [使用协程系统](/zh-CN/tutorials/coroutine-tutorial)
-    - [实现状态机](/zh-CN/tutorials/state-machine-tutorial)
-    - [实现存档系统](/zh-CN/tutorials/save-system)
+    - [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md)
+    - [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md)
+    - [实现存档系统](/zh-CN/tutorials/save-system.md)

 ## 项目概述

@ -805,7 +805,7 @@ public partial class GameScene : Node2D, IController

 ## 相关文档

- [Godot 架构集成](/zh-CN/godot/architecture) - 架构详细说明
- [Godot 场景系统](/zh-CN/godot/scene) - 场景管理
- [Godot UI 系统](/zh-CN/godot/ui) - UI 管理
- [Godot 扩展](/zh-CN/godot/extensions) - 扩展功能
+- [Godot 架构集成](/zh-CN/godot/architecture.md) - 架构详细说明
+- [Godot 场景系统](/zh-CN/godot/scene.md) - 场景管理
+- [Godot UI 系统](/zh-CN/godot/ui.md) - UI 管理
+- [Godot 扩展](/zh-CN/godot/extensions.md) - 扩展功能
--- a/docs/zh-CN/tutorials/index.md
+++ b/docs/zh-CN/tutorials/index.md
@ -9,7 +9,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习

 ## 📚 可用教程

-### [基础教程](./basic/)
+### [基础教程](./basic/index.md)

 > 从零开始学习 GFramework，通过构建一个完整的计数器应用，逐步掌握框架的核心概念。

@ -169,7 +169,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习

 ### 善用资源

- **查阅文档**：结合 [Core 核心框架](../core/) 和 [Godot 集成](../godot/) 文档
+- **查阅文档**：结合 [Core 核心框架](../core/index.md) 和 [Godot 集成](../godot/index.md) 文档
 - **查看示例**：参考框架附带的示例项目
 - **社区交流**：遇到问题时查看 GitHub Issues 或参与讨论

@ -193,11 +193,11 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习

 ## 🔗 相关资源

- [入门指南](../getting-started/) - 快速了解框架和安装配置
- [Core 核心框架](../core/) - 深入学习核心概念
- [Game 模块](../game/) - 游戏特定功能文档
- [Godot 集成](../godot/) - Godot 特定功能参考
- [源码生成器](../source-generators/) - 自动化代码生成工具
+- [入门指南](../getting-started/index.md) - 快速了解框架和安装配置
+- [Core 核心框架](../core/index.md) - 深入学习核心概念
+- [Game 模块](../game/index.md) - 游戏特定功能文档
+- [Godot 集成](../godot/index.md) - Godot 特定功能参考
+- [源码生成器](../source-generators/index.md) - 自动化代码生成工具

 ---

@ -236,7 +236,7 @@ A: 根据学习深度不同：

 <div style="text-align: center; margin: 2rem 0;">

-[开始基础教程 →](./basic/)
+[开始基础教程 →](./basic/index.md)

 </div>

--- a/docs/zh-CN/tutorials/large-project-organization.md
+++ b/docs/zh-CN/tutorials/large-project-organization.md
@ -20,8 +20,8 @@ description: 学习如何使用 GFramework 组织和管理大型游戏项目

 - 已安装 GFramework.Core 和 GFramework.Game NuGet 包
 - 了解 C# 基础语法和面向对象编程
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[架构组件](/zh-CN/core/architecture)和[模块系统](/zh-CN/core/architecture#模块系统)
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[架构组件](/zh-CN/core/architecture.md)和[模块系统](/zh-CN/core/architecture.md#模块系统)

 ## 步骤 1: 项目结构设计

@ -1628,14 +1628,14 @@ namespace MyGame

 恭喜!你已经掌握了大型项目的组织方法。接下来可以学习:

- [Godot 完整项目](/zh-CN/tutorials/godot-complete-project) - 在 Godot 中应用这些原则
- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 管理大型项目的资源
- [实现存档系统](/zh-CN/tutorials/save-system) - 保存复杂的游戏状态
- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns) - 高级架构模式
+- [Godot 完整项目](/zh-CN/tutorials/godot-complete-project.md) - 在 Godot 中应用这些原则
+- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 管理大型项目的资源
+- [实现存档系统](/zh-CN/tutorials/save-system.md) - 保存复杂的游戏状态
+- [架构模式最佳实践](/zh-CN/best-practices/architecture-patterns.md) - 高级架构模式

 ## 相关文档

- [架构组件](/zh-CN/core/architecture) - 架构系统详解
- [模块系统](/zh-CN/core/architecture#模块系统) - 模块化设计
- [依赖注入](/zh-CN/core/ioc) - IoC 容器使用
- [最佳实践](/zh-CN/best-practices/) - 开发最佳实践
+- [架构组件](/zh-CN/core/architecture.md) - 架构系统详解
+- [模块系统](/zh-CN/core/architecture.md#模块系统) - 模块化设计
+- [依赖注入](/zh-CN/core/ioc.md) - IoC 容器使用
+- [最佳实践](/zh-CN/best-practices/index.md) - 开发最佳实践
--- a/docs/zh-CN/tutorials/pause-system.md
+++ b/docs/zh-CN/tutorials/pause-system.md
@ -20,8 +20,8 @@ description: 学习如何使用暂停系统实现多层暂停管理和游戏流

 - 已安装 GFramework.Core NuGet 包
 - 了解 C# 基础语法和接口实现
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[架构组件](/zh-CN/core/architecture)基础
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[架构组件](/zh-CN/core/architecture.md)基础

 ## 步骤 1：注册暂停管理器

@ -1120,14 +1120,14 @@ class Program

 恭喜！你已经掌握了暂停系统的使用。接下来可以学习：

- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 在暂停状态下控制协程
- [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - 结合状态机管理游戏流程
- [事件系统](/zh-CN/core/events) - 使用事件响应暂停状态变化
+- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 在暂停状态下控制协程
+- [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) - 结合状态机管理游戏流程
+- [事件系统](/zh-CN/core/events.md) - 使用事件响应暂停状态变化

 ## 相关文档

- [架构组件](/zh-CN/core/architecture) - 架构基础
- [Utility 层](/zh-CN/core/utility) - Utility 详细说明
- [生命周期管理](/zh-CN/core/lifecycle) - 组件生命周期
- [扩展方法](/zh-CN/core/extensions) - 便捷的扩展方法
+- [架构组件](/zh-CN/core/architecture.md) - 架构基础
+- [Utility 层](/zh-CN/core/utility.md) - Utility 详细说明
+- [生命周期管理](/zh-CN/core/lifecycle.md) - 组件生命周期
+- [扩展方法](/zh-CN/core/extensions.md) - 便捷的扩展方法

--- a/docs/zh-CN/tutorials/resource-management.md
+++ b/docs/zh-CN/tutorials/resource-management.md
@ -20,8 +20,8 @@ description: 学习如何高效管理游戏资源，避免内存泄漏和性能

 - 已安装 GFramework.Core NuGet 包
 - 了解 C# 基础语法和 async/await
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[协程系统](/zh-CN/core/coroutine)
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[协程系统](/zh-CN/core/coroutine.md)

 ## 步骤 1：创建资源类型和加载器

@ -802,13 +802,13 @@ MyGame/

 恭喜！你已经掌握了资源管理的最佳实践。接下来可以学习：

- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 在协程中加载资源
- [实现状态机](/zh-CN/tutorials/state-machine-tutorial) - 在状态切换时管理资源
- [实现存档系统](/zh-CN/tutorials/save-system) - 保存和加载游戏数据
+- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 在协程中加载资源
+- [实现状态机](/zh-CN/tutorials/state-machine-tutorial.md) - 在状态切换时管理资源
+- [实现存档系统](/zh-CN/tutorials/save-system.md) - 保存和加载游戏数据

 ## 相关文档

- [资源管理系统](/zh-CN/core/resource) - 资源系统详细说明
- [对象池系统](/zh-CN/core/pool) - 结合对象池复用资源
- [协程系统](/zh-CN/core/coroutine) - 异步加载资源
- [System 层](/zh-CN/core/system) - System 详细说明
+- [资源管理系统](/zh-CN/core/resource.md) - 资源系统详细说明
+- [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源
+- [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源
+- [System 层](/zh-CN/core/system.md) - System 详细说明
--- a/docs/zh-CN/tutorials/save-system.md
+++ b/docs/zh-CN/tutorials/save-system.md
@ -20,8 +20,8 @@ description: 学习如何实现完整的游戏存档系统，支持多槽位和

 - 已安装 GFramework.Game NuGet 包
 - 了解 C# 基础语法和 async/await
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[数据与存档系统](/zh-CN/game/data)
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[数据与存档系统](/zh-CN/game/data.md)

 ## 步骤 1：定义存档数据结构

@ -954,13 +954,13 @@ MyGame/

 恭喜！你已经实现了一个完整的存档系统。接下来可以学习：

- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project) - 在 Godot 中使用存档系统
- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 异步加载存档
- [数据与存档系统](/zh-CN/game/data) - 数据系统详细说明
+- [Godot 完整项目搭建](/zh-CN/tutorials/godot-complete-project.md) - 在 Godot 中使用存档系统
+- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 异步加载存档
+- [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明

 ## 相关文档

- [数据与存档系统](/zh-CN/game/data) - 数据系统详细说明
- [对象池系统](/zh-CN/core/pool) - 结合对象池复用资源
- [协程系统](/zh-CN/core/coroutine) - 异步加载资源
- [System 层](/zh-CN/core/system) - System 详细说明
+- [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明
+- [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源
+- [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源
+- [System 层](/zh-CN/core/system.md) - System 详细说明
--- a/docs/zh-CN/tutorials/state-machine-tutorial.md
+++ b/docs/zh-CN/tutorials/state-machine-tutorial.md
@ -20,8 +20,8 @@ description: 学习如何使用状态机系统管理游戏状态和场景切换

 - 已安装 GFramework.Core NuGet 包
 - 了解 C# 基础语法和 async/await
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[生命周期管理](/zh-CN/core/lifecycle)
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[生命周期管理](/zh-CN/core/lifecycle.md)

 ## 步骤 1：定义游戏状态

@ -734,13 +734,13 @@ MyGame/

 恭喜！你已经掌握了状态机系统的使用。接下来可以学习：

- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial) - 在状态中使用协程
- [资源管理最佳实践](/zh-CN/tutorials/resource-management) - 在加载状态中管理资源
- [实现存档系统](/zh-CN/tutorials/save-system) - 保存和恢复游戏状态
+- [使用协程系统](/zh-CN/tutorials/coroutine-tutorial.md) - 在状态中使用协程
+- [资源管理最佳实践](/zh-CN/tutorials/resource-management.md) - 在加载状态中管理资源
+- [实现存档系统](/zh-CN/tutorials/save-system.md) - 保存和恢复游戏状态

 ## 相关文档

- [状态机系统](/zh-CN/core/state-machine) - 状态机详细说明
- [生命周期管理](/zh-CN/core/lifecycle) - 组件生命周期
- [System 层](/zh-CN/core/system) - System 详细说明
- [架构组件](/zh-CN/core/architecture) - 架构基础
+- [状态机系统](/zh-CN/core/state-machine.md) - 状态机详细说明
+- [生命周期管理](/zh-CN/core/lifecycle.md) - 组件生命周期
+- [System 层](/zh-CN/core/system.md) - System 详细说明
+- [架构组件](/zh-CN/core/architecture.md) - 架构基础
--- a/docs/zh-CN/tutorials/unit-testing.md
+++ b/docs/zh-CN/tutorials/unit-testing.md
@ -22,8 +22,8 @@ description: 学习如何为 GFramework 项目编写单元测试
 - 已安装 .NET SDK 8.0 或更高版本
 - 了解 C# 基础语法
 - 熟悉 xUnit 或 NUnit 测试框架
- 阅读过[快速开始](/zh-CN/getting-started/quick-start)
- 了解[架构系统](/zh-CN/core/architecture)
+- 阅读过[快速开始](/zh-CN/getting-started/quick-start.md)
+- 了解[架构系统](/zh-CN/core/architecture.md)

 ## 步骤 1：创建测试项目

@ -1143,5 +1143,5 @@ public void CalculateBonus_Should_Return_Double(int input, int expected)

 - [NUnit 官方文档](https://docs.nunit.org/)
 - [Moq 快速入门](https://github.com/moq/moq4/wiki/Quickstart)
- [架构设计模式](/zh-CN/best-practices/architecture-patterns)
- [性能优化最佳实践](/zh-CN/best-practices/performance)
+- [架构设计模式](/zh-CN/best-practices/architecture-patterns.md)
+- [性能优化最佳实践](/zh-CN/best-practices/performance.md)