From 094e29ed8bba6e9f7cd37b18b4f2a2fcfd2711ae Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 25 Apr 2026 14:56:59 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(docs):=20=E7=BB=9F=E4=B8=80=E4=B8=AD?= =?UTF-8?q?=E6=96=87=E6=96=87=E6=A1=A3=E5=AF=BC=E8=88=AA=E4=B8=8E=E8=AF=AD?= =?UTF-8?q?=E4=B9=89=E5=8C=96=E9=93=BE=E6=8E=A5=E6=96=87=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 docs 站点中 abstractions、source-generators、api-reference 的导航文案，使其与 landing page 入口一致 - 补充遗漏的源码生成器 sidebar 条目，并本地化抽象层与 API 参考的侧边栏标签 - 修复 ECS、Game、Godot 文档中的路径式可见链接标签，改为读者可理解的语义化名称 --- docs/.vitepress/config.mts | 40 ++++++++++++++++++++++++-------- docs/zh-CN/ecs/arch.md | 2 +- docs/zh-CN/game/serialization.md | 2 +- docs/zh-CN/game/setting.md | 2 +- docs/zh-CN/game/storage.md | 4 ++-- docs/zh-CN/godot/setting.md | 4 ++-- docs/zh-CN/godot/storage.md | 4 ++-- 7 files changed, 39 insertions(+), 19 deletions(-) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index b8aeaf5a..4766d4fa 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -117,9 +117,9 @@ export default defineConfig({ items: [ { text: 'ECS', link: '/zh-CN/ecs/' }, { text: '抽象接口', link: '/zh-CN/abstractions/' }, - { text: '源码生成器', link: '/zh-CN/source-generators' }, + { text: '源码生成器', link: '/zh-CN/source-generators/' }, { text: '最佳实践', link: '/zh-CN/best-practices/' }, - { text: 'API 参考', link: '/zh-CN/api-reference' }, + { text: 'API 参考', link: '/zh-CN/api-reference/' }, { text: '常见问题', link: '/zh-CN/faq' }, { text: '故障排查', link: '/zh-CN/troubleshooting' }, { text: '贡献指南', link: '/zh-CN/contributing' }, @@ -248,14 +248,18 @@ export default defineConfig({ items: [ { text: '概览', link: '/zh-CN/source-generators/' }, { text: '日志生成器', link: '/zh-CN/source-generators/logging-generator' }, - { text: '枚举扩展', link: '/zh-CN/source-generators/enum-generator' }, + { text: '枚举生成器', link: '/zh-CN/source-generators/enum-generator' }, { text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' }, { text: 'Priority 生成器', link: '/zh-CN/source-generators/priority-generator' }, - { text: 'Context Get 注入', link: '/zh-CN/source-generators/context-get-generator' }, - { text: 'CQRS Handler Registry', link: '/zh-CN/source-generators/cqrs-handler-registry-generator' }, - { text: 'Godot 项目元数据', link: '/zh-CN/source-generators/godot-project-generator' }, + { text: 'ContextGet 生成器', link: '/zh-CN/source-generators/context-get-generator' }, + { text: '模块自动注册生成器', link: '/zh-CN/source-generators/auto-register-module-generator' }, + { text: 'CQRS Handler Registry 生成器', link: '/zh-CN/source-generators/cqrs-handler-registry-generator' }, + { text: 'Godot 项目生成器', link: '/zh-CN/source-generators/godot-project-generator' }, { text: 'GetNode 生成器 (Godot)', link: '/zh-CN/source-generators/get-node-generator' }, - { text: 'BindNodeSignal 生成器 (Godot)', link: '/zh-CN/source-generators/bind-node-signal-generator' } + { text: 'BindNodeSignal 生成器 (Godot)', link: '/zh-CN/source-generators/bind-node-signal-generator' }, + { text: 'AutoUiPage 生成器', link: '/zh-CN/source-generators/auto-ui-page-generator' }, + { text: 'AutoScene 生成器', link: '/zh-CN/source-generators/auto-scene-generator' }, + { text: 'AutoRegisterExportedCollections 生成器', link: '/zh-CN/source-generators/auto-register-exported-collections-generator' } ] } ], @@ -264,9 +268,25 @@ export default defineConfig({ { text: '抽象接口', items: [ - { text: 'Core Abstractions', link: '/zh-CN/abstractions/core-abstractions' }, - { text: 'Game Abstractions', link: '/zh-CN/abstractions/game-abstractions' }, - { text: 'Ecs.Arch Abstractions', link: '/zh-CN/abstractions/ecs-arch-abstractions' } + { text: '概览', link: '/zh-CN/abstractions/' }, + { text: 'Core 抽象层说明', link: '/zh-CN/abstractions/core-abstractions' }, + { text: 'Game 抽象层说明', link: '/zh-CN/abstractions/game-abstractions' }, + { text: 'Ecs.Arch 抽象层说明', link: '/zh-CN/abstractions/ecs-arch-abstractions' } + ] + } + ], + + '/zh-CN/api-reference/': [ + { + text: 'API 参考', + items: [ + { text: '概览', link: '/zh-CN/api-reference/' }, + { text: 'Core 栏目', link: '/zh-CN/core/' }, + { text: 'Game 模块总览', link: '/zh-CN/game/' }, + { text: 'Godot 模块总览', link: '/zh-CN/godot/' }, + { text: 'ECS 模块总览', link: '/zh-CN/ecs/' }, + { text: '抽象接口', link: '/zh-CN/abstractions/' }, + { text: '源码生成器', link: '/zh-CN/source-generators/' } ] } ], diff --git a/docs/zh-CN/ecs/arch.md b/docs/zh-CN/ecs/arch.md index 5e6cd878..cdc98ae6 100644 --- a/docs/zh-CN/ecs/arch.md +++ b/docs/zh-CN/ecs/arch.md @@ -18,7 +18,7 @@ description: GFramework.Ecs.Arch 的默认运行时装配路径、系统桥接 - 使用仓库自带的 `Position`、`Velocity`、`MovementSystem` 最小示例 如果你只想保留共享边界，而不依赖默认实现，请改看 -[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md)。 +[ECS 抽象层说明](../abstractions/ecs-arch-abstractions.md)。 ## 最小接入路径 diff --git a/docs/zh-CN/game/serialization.md b/docs/zh-CN/game/serialization.md index d07487c5..2ee420d8 100644 --- a/docs/zh-CN/game/serialization.md +++ b/docs/zh-CN/game/serialization.md @@ -146,7 +146,7 @@ var restored = serializer.Deserialize(json, data.GetType()); - `Game.SourceGenerators + YamlConfigLoader` - 负责 schema 驱动的配置表生成与 YAML 读取 -如果你的目标是静态内容配置表，而不是运行时持久化对象，请改看 [`config-system.md`](./config-system.md)。 +如果你的目标是静态内容配置表，而不是运行时持久化对象，请改看 [配置系统](./config-system.md)。 ## 当前边界 diff --git a/docs/zh-CN/game/setting.md b/docs/zh-CN/game/setting.md index b5bc724e..64e106e2 100644 --- a/docs/zh-CN/game/setting.md +++ b/docs/zh-CN/game/setting.md @@ -195,7 +195,7 @@ await settingsModel.SaveAllAsync(); - `SettingsModel` 负责数据生命周期，`SettingsSystem` 负责系统级调用入口；两者不要混成一个巨型服务 - applicator 决定“怎么把数据应用到宿主”，repository 决定“怎么保存数据”，两层职责不要互相侵入 -- 设置迁移和存档迁移是两条不同管线；后者看 [`data.md`](./data.md) 里的 `SaveRepository` +- 设置迁移和存档迁移是两条不同管线；后者看 [数据与存档系统](./data.md) 里的 `SaveRepository` ## 继续阅读 diff --git a/docs/zh-CN/game/storage.md b/docs/zh-CN/game/storage.md index ad2f9856..deed4e65 100644 --- a/docs/zh-CN/game/storage.md +++ b/docs/zh-CN/game/storage.md @@ -161,8 +161,8 @@ var cacheStorage = new ScopedStorage(rootStorage, "runtime-cache"); 也就是说： -- 业务层如果想保存一份独立数据，优先看 [`data.md`](./data.md) -- 业务层如果想保存设置，优先看 [`setting.md`](./setting.md) +- 业务层如果想保存一份独立数据，优先看 [数据与存档系统](./data.md) +- 业务层如果想保存设置，优先看 [设置系统](./setting.md) - 业务层如果只是需要底层存储实现，才直接依赖 `IStorage` ## 当前边界 diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md index 84091c8f..5a79cebf 100644 --- a/docs/zh-CN/godot/setting.md +++ b/docs/zh-CN/godot/setting.md @@ -137,13 +137,13 @@ await settingsSystem.Apply(); ### 先理解设置模型和仓库 如果你想先理解 `ISettingsData`、`IResetApplyAbleSettings`、`SettingsModel`、`SettingsSystem` 与设置迁移，先看 -[`../game/setting.md`](../game/setting.md)。 +[Game 设置系统](../game/setting.md)。 ### 先理解设置如何被持久化 如果你关注的是统一设置文件、备份、数据位置和底层存储实现，应该回到： -- [`../game/storage.md`](../game/storage.md) +- [Game 存储系统](../game/storage.md) - [Godot 存储系统](./storage.md) 本页只补 Godot 宿主如何“应用”设置，不重复维护一份完整设置系统手册。 diff --git a/docs/zh-CN/godot/storage.md b/docs/zh-CN/godot/storage.md index 7ad94a59..be47e4df 100644 --- a/docs/zh-CN/godot/storage.md +++ b/docs/zh-CN/godot/storage.md @@ -108,7 +108,7 @@ architecture.RegisterUtility>(new SaveRepository>(new SaveRepository Date: Sat, 25 Apr 2026 15:12:08 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(documentation):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E6=89=B9=E5=A4=84=E7=90=86=E6=B2=BB=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 优化根 README、模块 README 与抽象层页面的 reader-facing 文案和语义化链接标签 - 补充 tutorials、troubleshooting、best-practices、contributing、godot/resource 的代码块语言标记 - 更新 documentation-full-coverage-governance 的恢复点、验证结果与批处理停止条件 --- GFramework.Core.Abstractions/README.md | 10 ++-- GFramework.Core/README.md | 6 +- GFramework.Ecs.Arch.Abstractions/README.md | 4 +- GFramework.Ecs.Arch/README.md | 4 +- GFramework.Game.Abstractions/README.md | 6 +- GFramework.Game.SourceGenerators/README.md | 4 +- GFramework.Game/README.md | 6 +- README.md | 4 +- ...ation-full-coverage-governance-tracking.md | 52 ++++++++++++------ ...entation-full-coverage-governance-trace.md | 55 +++++++++++-------- docs/zh-CN/abstractions/game-abstractions.md | 6 +- docs/zh-CN/abstractions/index.md | 6 +- .../best-practices/architecture-patterns.md | 2 +- docs/zh-CN/best-practices/index.md | 2 +- docs/zh-CN/contributing.md | 2 +- docs/zh-CN/godot/resource.md | 2 +- docs/zh-CN/troubleshooting.md | 38 ++++++------- docs/zh-CN/tutorials/data-migration.md | 4 +- .../zh-CN/tutorials/functional-programming.md | 2 +- .../zh-CN/tutorials/godot-complete-project.md | 2 +- docs/zh-CN/tutorials/index.md | 6 +- .../tutorials/large-project-organization.md | 4 +- docs/zh-CN/tutorials/pause-system.md | 5 +- docs/zh-CN/tutorials/resource-management.md | 4 +- docs/zh-CN/tutorials/save-system.md | 6 +- .../zh-CN/tutorials/state-machine-tutorial.md | 4 +- docs/zh-CN/tutorials/unit-testing.md | 4 +- 27 files changed, 137 insertions(+), 113 deletions(-) diff --git a/GFramework.Core.Abstractions/README.md b/GFramework.Core.Abstractions/README.md index 58c67061..34382544 100644 --- a/GFramework.Core.Abstractions/README.md +++ b/GFramework.Core.Abstractions/README.md @@ -34,10 +34,10 @@ | `Data/` `Serializer/` `Storage/` `Versioning/` | 数据装载、序列化、存储与版本化契约 | | `Enums/` `Properties/` | 架构阶段枚举，以及架构 / logger 相关属性键 | -## XML 覆盖基线 +## XML 阅读入口 -截至 `2026-04-22`，已按顶层目录对 `GFramework.Core.Abstractions` 的公开 / 内部类型声明做过一轮轻量盘点；当前契约目录族的类型声明都已带 -XML 注释。这里记录的是类型族级基线，成员级契约细节仍需要在后续波次继续审计。 +截至 `2026-04-22`，下面这份目录视图可以帮助你快速定位 `GFramework.Core.Abstractions` 的类型级 XML 文档入口；当前契约目录族的类型声明都已带 +XML 注释。更细的契约约束与交互语义，适合在阅读具体接口和成员时继续结合源码确认。 | 类型族 | 基线状态 | 代表类型 | | --- | --- | --- | @@ -57,9 +57,9 @@ XML 注释。这里记录的是类型族级基线，成员级契约细节仍需 - 若你只需要对接口编程，可以仅引用本包，再在应用层自行提供实现 - 若你在写上层模块，优先把公共契约放在 `*.Abstractions`，实现放在对应 runtime 包 -## 重点 XML 关注点 +## 推荐优先阅读的 XML 类型族 -如果你在做契约审计、模块拆分或测试替身，优先看这些类型族的 XML 文档： +如果你在做模块拆分、测试替身或接口适配，优先看这些类型族的 XML 文档： - 架构与模块入口：`IArchitecture`、`IArchitectureContext`、`IServiceModule` - 运行时基础设施：`IIocContainer`、`ILogger`、`IResourceManager`、`IConfigurationManager` diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index f36d4af9..607fabcb 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -60,10 +60,10 @@ | `Functional/` | `Option`、`Result` 等轻量函数式工具 | | `Extensions/` | 上下文与集合等扩展方法 | -## XML 覆盖基线 +## XML 阅读入口 -截至 `2026-04-22`，已按顶层目录对 `GFramework.Core` 的公开 / 内部类型声明做过一轮轻量盘点；当前主目录族的类型声明都已带 -XML 注释。这里先保留阅读基线，成员级 ```` / ```` / 生命周期语义审计仍属于后续治理项。 +截至 `2026-04-22`，下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口；当前主目录族的类型声明都已带 +XML 注释。更细的参数、返回值和生命周期语义，适合在阅读对应类型与成员时继续结合源码确认。 | 类型族 | 基线状态 | 代表类型 | | --- | --- | --- | diff --git a/GFramework.Ecs.Arch.Abstractions/README.md b/GFramework.Ecs.Arch.Abstractions/README.md index 3b01d248..a92a1fc2 100644 --- a/GFramework.Ecs.Arch.Abstractions/README.md +++ b/GFramework.Ecs.Arch.Abstractions/README.md @@ -33,9 +33,9 @@ | `IArchSystemAdapter.cs` | 让 ECS 系统适配到 GFramework `ISystem` 生命周期的接口 | | `ArchOptions.cs` | `WorldCapacity`、`EnableStatistics`、`Priority` 等配置对象 | -## XML 阅读基线 +## XML 阅读入口 -下表记录当前契约包的类型声明级 XML 基线，方便把 README、站内抽象页与源码阅读顺序对齐。 +下表汇总当前契约包的类型级 XML 文档入口，方便把 README、站内抽象页与源码阅读顺序对齐。 | 类型族 | 代表类型 | XML 状态 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Ecs.Arch/README.md b/GFramework.Ecs.Arch/README.md index c2820ef9..714c2192 100644 --- a/GFramework.Ecs.Arch/README.md +++ b/GFramework.Ecs.Arch/README.md @@ -119,9 +119,9 @@ ecsModule.Update(deltaTime); | `ArchOptions.cs` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 这组运行时配置 | | `Components/*.cs`、`Systems/*.cs` | 提供最小组件与系统示例，帮助对照查询写法和更新模式 | -## XML 阅读基线 +## XML 阅读入口 -下表记录当前模块 README 与源码可对照的类型声明级 XML 基线。 +下表汇总当前模块 README 与源码可对照的类型级 XML 文档入口，方便先抓住 Arch ECS 集成的关键类型。 | 类型族 | 代表类型 | XML 状态 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Game.Abstractions/README.md b/GFramework.Game.Abstractions/README.md index 9439de79..4f02b893 100644 --- a/GFramework.Game.Abstractions/README.md +++ b/GFramework.Game.Abstractions/README.md @@ -131,10 +131,10 @@ Scene 与 UI 路由共享这套基础约定。 - `Enums/` - UI/Scene 转场、UI 层级、输入动作、存储类型等公共枚举 -## XML 覆盖基线 +## XML 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 / -内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。 +下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game.Abstractions` 类型级 XML 文档入口：只统计公开 / +内部类型声明是否带 XML 注释，用来帮助你建立契约层阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。 | 契约族 | 基线状态 | 代表类型 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Game.SourceGenerators/README.md b/GFramework.Game.SourceGenerators/README.md index b752e5c2..8723ad39 100644 --- a/GFramework.Game.SourceGenerators/README.md +++ b/GFramework.Game.SourceGenerators/README.md @@ -44,9 +44,9 @@ GameProject/ 默认情况下，打包产物会通过 `targets` 把 `schemas/**/*.schema.json` 纳入 `AdditionalFiles`。 -## XML 覆盖基线 +## XML 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game.SourceGenerators` 做的一轮轻量 XML 盘点结果：只统计公开类型声明是否带 XML 注释，用来建立生成器入口；具体诊断消息、生成输出和兼容性语义仍需要回到源码与测试继续核对。 +下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game.SourceGenerators` 类型级 XML 文档入口：只统计公开类型声明是否带 XML 注释，用来帮助你定位生成器入口；具体诊断消息、生成输出和兼容性语义仍建议回到源码与测试继续核对。 | 类型族 | 基线状态 | 代表类型 | 阅读重点 | | --- | --- | --- | --- | diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index 586b0b81..597f6760 100644 --- a/GFramework.Game/README.md +++ b/GFramework.Game/README.md @@ -169,10 +169,10 @@ 这两部分一般被上层子系统消费，不是多数项目的第一接入点。 -## XML 覆盖基线 +## XML 阅读入口 -下面这份 inventory 记录的是 `2026-04-23` 对 `GFramework.Game` 做的一轮轻量 XML 盘点结果：只统计公开 / -内部类型声明是否带 XML 注释，用来建立运行时阅读入口；成员级参数、返回值、异常和生命周期说明仍需要在后续 API 波次继续细化。 +下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game` 类型级 XML 文档入口：只统计公开 / +内部类型声明是否带 XML 注释，用来帮助你确定运行时阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。 | 子系统 | 基线状态 | 代表类型 | 阅读重点 | | --- | --- | --- | --- | diff --git a/README.md b/README.md index 294a91b0..5fc94729 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,8 @@ | 目录 | 定位 | 跟随入口 | | --- | --- | --- | -| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [Core.SourceGenerators 模块 README](GFramework.Core.SourceGenerators/README.md) | -| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [Godot.SourceGenerators 模块 README](GFramework.Godot.SourceGenerators/README.md) | +| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [Core.SourceGenerators 模块说明](GFramework.Core.SourceGenerators/README.md) | +| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [Godot.SourceGenerators 模块说明](GFramework.Godot.SourceGenerators/README.md) | | `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [源码生成器总览](docs/zh-CN/source-generators/index.md) | ## 文档导航 diff --git 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 index 10bb88c3..8ba1e64e 100644 --- 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,23 +12,25 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-034` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-035` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按本轮 `$gframework-batch-boot 50` 约束继续使用 `origin/main`（`984fb21`，`2026-04-25 11:11:56 +08:00`）作为唯一 baseline，只推进低风险、可切片的文档治理批次 - - 本轮已收口三类目标：5 个模块 README 的语义化链接标签、7 个 `Core` 热点页的代码块语言标记、7 个基础教程页的代码块语言标记 - - 当前已接收 worker A 的 README 切片结果；其余代码块标记批次由主线程统一复核并补齐 - - 本轮 `19` 个文档文件连同 active tracking / trace 已落地；当前 branch diff 已确认达到 `21 / 50` 个 changed files，仍处于当前批次阈值安全区间 - - 下一轮若继续批处理，优先挑选新的低风险 reader-facing 缺口，并保持单批次预计落地规模不超过剩余 headroom + - 按本轮 `$gframework-batch-boot 50` 约束使用最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）作为唯一 baseline，只推进低风险、可切片的 reader-facing 文档治理批次 + - 已接受 worker 的导航 / 语义化链接批次，提交为 `094e29e`（`docs(docs): 统一中文文档导航与语义化链接文案`） + - 当前未提交批次覆盖 `abstractions` reader-facing 标签、`best-practices` / `troubleshooting` / `tutorials` 代码块语言标记、7 个模块 / 根 README 的 reader-facing XML 阅读入口改写，以及 `contributing` / `godot/resource` 的剩余 bare opening fence + - 当前批次连同 active tracking / trace 一并落地后，累计 branch diff 将达到 `34 / 50` 个 changed files；虽然仍有 `16` 个文件 headroom，但同类低风险、可重复批处理切片已经基本耗尽 + - 若继续下一轮，不应再按当前模式盲目扩批，而应先复核 PR / review 状态，再决定是否进入新的非重复性文档巡检波次 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-25` worker A 已完成并提交 5 个模块 README 的 reader-facing 链接标签修正，提交为 `bd5cdb5`（`docs(readme): 优化链接标签`）；当前批次已接受该切片结果。 -- `2026-04-25` 主线程补齐了 `docs/zh-CN/core/configuration.md`、`extensions.md`、`ioc.md`、`localization.md`、`pause.md`、`pool.md`、`system.md` 的裸 fenced code block opening 语言标记。 -- `2026-04-25` 教程批次当前覆盖 `docs/zh-CN/tutorials/basic/01-environment.md` 到 `07-summary.md`，补齐的内容以目录树、流程图和控制台输出为主，统一显式标注为 `text`。 -- `2026-04-25` 当前实际 branch diff 已更新为 `21 / 50` 个 changed files；其中 `5` 个文件来自已提交的 README 标签切片，`16` 个文件来自本轮代码块标记与 active tracking / trace 更新。 -- `2026-04-25` 本轮目录级验证已覆盖 `docs/zh-CN/core` 与 `docs/zh-CN/tutorials/basic`，README 目标文件链接校验和 `docs/` 站点构建也都已通过。 +- `2026-04-25` worker A 已完成并提交 5 个模块 README 的 reader-facing 链接标签修正，提交为 `bd5cdb5`（`docs(readme): 优化链接标签`）；该切片仍作为本 topic 的已接受历史批次保留。 +- `2026-04-25` 最新 `origin/main` 已推进到 `4ad880c`；当前 `docs/sdk-update-documentation` 相对该 baseline 的已提交 branch diff 为 `7 / 50` 个文件，来自导航与语义化链接批次 `094e29e`。 +- `2026-04-25` 当前未提交工作树额外覆盖 `25` 个文件：`abstractions` 2 页链接标签、`best-practices` 2 页代码块标记、`troubleshooting` 1 页错误输出标记、`tutorials` 10 页目录树 / 路径 / 输出块标记、根 / 模块 README 8 页 reader-facing 改写，以及 `contributing` / `godot/resource` 2 页剩余 bare opening fence 处理。 +- `2026-04-25` `docs/.vitepress/config.mts` 已补齐 `abstractions`、`source-generators`、`api-reference` 的中文 sidebar / nav 入口，且 `docs/zh-CN/ecs/arch.md`、`game/*.md`、`godot/*.md` 的原始路径式可见标签已统一为读者可理解的语义化名称。 +- `2026-04-25` `docs/zh-CN/tutorials` 本轮已额外补齐 10 个非基础教程页的 bare fenced opening 语言标记；目录树、学习路径和控制台输出统一显式标注为 `text`，未改写示例内容。 +- `2026-04-25` 根 README 与 7 个模块 README 当前已把 `XML 覆盖基线` / `XML 阅读基线` / `inventory` / `后续治理项` 一类 maintainer-facing 标题与导语改为 reader-facing 的“XML 阅读入口 / 推荐优先阅读的 XML 类型族”等表达，保留了现有表格、链接与证据链。 +- `2026-04-25` 本轮主线程复核后确认：`docs/zh-CN` 中可由统一规则安全处理的 bare opening fence 只剩 `docs/zh-CN/contributing.md:631` 这一处既有嵌套 fenced 示例警告；它不适合继续按当前“只补 opening fence、不碰 closing fence”的批处理规则自动改写。 - `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`、 @@ -43,8 +45,9 @@ - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 -- README 链接标签与 `Core` / 教程代码块标记这两类低风险批次已经消化完本轮目标文件，但 `docs/zh-CN` 其他目录仍可能保留未显式标语言的历史代码块。 -- PR `#287` 的 latest-head review 是否还有 open thread 尚未在本轮重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。 +- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用本轮“只补 opening fence”规则自动改写。 +- 当前可用的低风险、可重复批处理切片已经基本消耗完毕；如果继续推进，剩余问题更可能落在非重复性 prose 调整、复杂示例结构或远端 review 反馈，不宜按本轮同一批处理模板继续盲扫。 +- PR `#287` 的 latest-head review 本轮未重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。 ## 归档指针 @@ -61,6 +64,20 @@ ## 最新验证 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` + - 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` + - 结果：通过；本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices` + - 结果：通过；`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` + - 结果：通过；错误输出与完整错误信息块补齐为 `text` 后页面验证通过。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` + - 结果：通过，但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告；不属于本轮自动补标规则可安全收口的范围。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` + - 结果：通过；`Godot` 资源页剩余 bare opening fence 已补齐语言标记。 +- `2026-04-25` `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md` - 结果：通过；README 链接目标有效。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.SourceGenerators/README.md` @@ -111,9 +128,10 @@ ## 下一步 -1. 若继续下一轮 `$gframework-batch-boot 50`，优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread；当前相对阈值仍有 `29` 个 changed files 的 headroom。 -2. 后续若继续处理 reader-facing 文档问题，优先筛查剩余页面里的维护者视角限制说明、模块 README 中仍可能存在的裸路径标签，以及 `docs/zh-CN` 其他目录里的代码块语言标记缺口。 -3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 +1. 当前 `$gframework-batch-boot 50` 建议在本轮停止：待当前工作树与 active tracking / trace 一并提交后，累计 branch diff 将为 `34 / 50`，但同类低风险、可重复切片已基本耗尽。 +2. 若继续下一轮，优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。 +3. 若后续继续处理公开文档，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得做结构化改写，而不是继续沿用“只补 opening fence”的自动批处理规则。 +4. 若后续分支继续调整 `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`、 +5. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。 diff --git 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 index e36fc8a8..22cf7154 100644 --- 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,36 +2,42 @@ ## 2026-04-25 -### 当前恢复点：RP-034 +### 当前恢复点：RP-035 -- 本轮按 `$gframework-batch-boot 50` 执行，baseline 固定为 `origin/main`（`984fb21`，`2026-04-25 11:11:56 +08:00`）；开始时 committed branch diff 为 `5 / 50` 个 changed files。 -- 已接受 worker A 的 README 切片结果：5 个模块 README 的 reader-facing 链接标签修正已落在提交 `bd5cdb5`（`docs(readme): 优化链接标签`）。 -- 主线程补齐了 `docs/zh-CN/core` 下 7 个热点页面与 `docs/zh-CN/tutorials/basic` 下 7 个教程页面的裸 fenced code block opening 语言标记，按内容分别落为 `csharp` 或 `text`。 -- 当前批次已提交为 `9dfee75`（`docs(documentation): 补齐文档代码块标记`）；提交后实际 branch diff 为 `21 / 50` 个 changed files，仍有后续小批次空间。 +- 本轮按 `$gframework-batch-boot 50` 执行，baseline 重新对齐到最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）；重新开始时 committed branch diff 为 `0 / 50` 个 changed files。 +- 已接受 worker 批次 `094e29e`（`docs(docs): 统一中文文档导航与语义化链接文案`），该提交补齐了 `abstractions` / `source-generators` / `api-reference` 的中文导航入口，并修复了 `ecs`、`game`、`godot` 目标页面的路径式可见链接标签。 +- 主线程接收并复核了 `abstractions` 2 页 reader-facing 链接标签修正、`best-practices` 2 页和 `troubleshooting` 1 页的代码块语言标记补齐，以及 `tutorials` 10 页目录树 / 路径 / 输出块统一显式标记为 `text`。 +- 主线程还接收了根 README 与 7 个模块 README 的 reader-facing XML 阅读入口改写，并补齐了 `docs/zh-CN/contributing.md`、`docs/zh-CN/godot/resource.md` 的剩余 bare opening fence。 +- 当前未提交工作树连同 active tracking / trace 一并落地后，累计 branch diff 将达到 `34 / 50` 个 changed files；本轮在未触及阈值的情况下停止，因为同类低风险、可重复批处理切片已基本耗尽。 -### 当前决策（RP-034） +### 当前决策（RP-035） -- README 批次只改 reader-facing 可见标签，不改链接目标；复核结果通过后直接接受 worker A 的独立提交，避免主线程重复改写同一组文件。 -- 代码块语言标记批次以 opening fence 为唯一修正点，不重写示例内容；目录树、流程图、控制台输出统一标 `text`，可执行或 API 示例标 `csharp`。 -- 教程 `01` 到 `07` 当前未发现额外裸 opening fence 之外的高风险文案问题，因此本轮不扩展到结构性重写，保持在低语义风险范围内。 +- 继续沿用“导航 / 链接标签”和“bare opening fence 语言标记”两类低语义风险规则，但拒绝把 closing fence 或复杂嵌套 fenced 结构纳入同一自动批处理模板。 +- 对 worker 产出的代码块标记批次一律做主线程复核；发现 closing fence 被误改后已在本轮立即纠正，并把后续批次提示词收紧到“只改 opening fence”。 +- README 治理批次只改 reader-facing 标题、导语和链接可见标签，不删除现有表格、证据链或源码 / 测试导向的阅读线索。 +- 在 `34 / 50` 之前停止本轮，不是因为 headroom 不足，而是因为自动可识别、风险可控的重复切片已经收敛到仅剩 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 警告；该问题更适合后续人工结构化处理。 -### 当前验证（RP-034） +### 当前验证（RP-035） -- README 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh` 逐个验证 5 个目标 README - - 结果：通过；目标链接有效。 -- README 标签复扫： - - `rg -n '\\[[^\\]]*(README\\.md|\\.md|\\.md/|/zh-CN/[^\\]]*)\\]\\([^)]*\\)' GFramework.Core/README.md GFramework.Core.SourceGenerators/README.md GFramework.Cqrs.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Game.SourceGenerators/README.md` - - 结果：无命中；本轮目标 README 已无可见路径式 / 文件名式标签残留。 -- `Core` 校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core` - - 结果：通过；`Core` 栏目 frontmatter、链接与代码块校验通过。 +- README / 链接校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` + - 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。 - 教程校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic` - - 结果：通过；基础教程栏目 frontmatter、链接与代码块校验通过。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` + - 结果：通过；本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。 +- 最佳实践校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices` + - 结果：通过；`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。 +- 单页校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` + - 结果：通过；错误输出与完整错误信息块补齐为 `text` 后页面验证通过。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` + - 结果：通过，但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` + - 结果：通过；剩余 bare opening fence 已补齐语言标记。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；仅保留既有大 chunk warning。 + - 结果：通过；本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建，仅保留既有大 chunk warning。 ### 归档指针 @@ -43,5 +49,6 @@ ### 下一步 -1. 若继续下一轮 `$gframework-batch-boot 50`，优先重新抓取 `$gframework-pr-review`，再选择新的低风险 reader-facing 文档切片。 -2. 当前 branch diff 为 `21 / 50`，后续单批次仍应控制在剩余 `29` 个 changed files 的 headroom 内。 +1. 若继续下一轮，优先重新抓取 `$gframework-pr-review`，确认 PR `#287` 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。 +2. 下一轮若仍要扩批，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得结构化改写，而不是继续沿用本轮的 opening-fence-only 自动修正规则。 +3. 当前轮次建议在 `34 / 50` 停止并提交，后续若要继续，应以新的低风险模式或新的热点清单重新建批。 diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 00e55e6d..73833327 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -109,10 +109,10 @@ public sealed class ContinueGameCommandHandler ## 阅读顺序 1. 先读本页，确认你是否真的只需要契约层 -2. 再看 [`../game/index.md`](../game/index.md) 了解默认运行时怎么组织这些契约 +2. 再看 [Game 模块总览](../game/index.md) 了解默认运行时怎么组织这些契约 3. 继续读具体专题页： - - [`../game/config-system.md`](../game/config-system.md) - - [`../game/data.md`](../game/data.md) + - [配置系统](../game/config-system.md) + - [数据系统](../game/data.md) - [设置系统](../game/setting.md) - [场景系统](../game/scene.md) - [UI 系统](../game/ui.md) diff --git a/docs/zh-CN/abstractions/index.md b/docs/zh-CN/abstractions/index.md index 4e1efc0c..b6acd585 100644 --- a/docs/zh-CN/abstractions/index.md +++ b/docs/zh-CN/abstractions/index.md @@ -15,9 +15,9 @@ description: GFramework 各抽象层模块的阅读入口与使用边界。 ## 阅读顺序 -- Core 抽象层：[`core-abstractions.md`](./core-abstractions.md) -- Game 抽象层：[`game-abstractions.md`](./game-abstractions.md) -- Ecs.Arch 抽象层：[`ecs-arch-abstractions.md`](./ecs-arch-abstractions.md) +- Core 抽象层：[Core 抽象层说明](./core-abstractions.md) +- Game 抽象层：[Game 抽象层说明](./game-abstractions.md) +- Ecs.Arch 抽象层：[Ecs.Arch 抽象层说明](./ecs-arch-abstractions.md) ## 使用建议 diff --git a/docs/zh-CN/best-practices/architecture-patterns.md b/docs/zh-CN/best-practices/architecture-patterns.md index 93d2dd7a..1cb7637a 100644 --- a/docs/zh-CN/best-practices/architecture-patterns.md +++ b/docs/zh-CN/best-practices/architecture-patterns.md @@ -3043,7 +3043,7 @@ public class AchievementSystem : AbstractSystem ### 模式选择决策树 -``` +```text 需要管理游戏状态？ ├─ 是 → 使用状态模式 └─ 否 → 继续 diff --git a/docs/zh-CN/best-practices/index.md b/docs/zh-CN/best-practices/index.md index ab8d236e..f7838a7c 100644 --- a/docs/zh-CN/best-practices/index.md +++ b/docs/zh-CN/best-practices/index.md @@ -121,7 +121,7 @@ public class GetPlayerPositionQuery : AbstractQuery ### 1. 项目结构 -``` +```text GameProject/ ├── Models/ │ ├── PlayerModel.cs diff --git a/docs/zh-CN/contributing.md b/docs/zh-CN/contributing.md index a9708858..e4f7a4e7 100644 --- a/docs/zh-CN/contributing.md +++ b/docs/zh-CN/contributing.md @@ -318,7 +318,7 @@ public TModel RegisterModel<TModel>(TModel model) where TModel : IModel 使用 Conventional Commits 规范： -``` +```text (): diff --git a/docs/zh-CN/godot/resource.md b/docs/zh-CN/godot/resource.md index 7fb78e74..85d82972 100644 --- a/docs/zh-CN/godot/resource.md +++ b/docs/zh-CN/godot/resource.md @@ -542,7 +542,7 @@ public partial class MyResource : Resource, IHasKey **解答**： 推荐按类型和功能组织： -``` +```text res://data/ ├── items/ # 物品资源 │ ├── weapons/ diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 68d1187f..74c55162 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -22,7 +22,7 @@ description: 提供 GFramework 常见安装、架构、事件与运行时问题 **错误信息**： -``` +```text NU1101: Unable to find package GFramework.Core ``` @@ -56,7 +56,7 @@ dotnet add package GFramework.Core --version 1.0.0 **错误信息**： -``` +```text NU1107: Version conflict detected for Microsoft.Extensions.DependencyInjection ``` @@ -93,7 +93,7 @@ NU1107: Version conflict detected for Microsoft.Extensions.DependencyInjection **错误信息**： -``` +```text error NETSDK1045: The current .NET SDK does not support targeting .NET 8.0 ``` @@ -126,7 +126,7 @@ dotnet --version **错误信息**： -``` +```text InvalidOperationException: Architecture is already initialized ``` @@ -166,7 +166,7 @@ var arch = GameArchitecture.Interface; **错误信息**： -``` +```text InvalidOperationException: No service for type 'IPlayerService' has been registered ``` @@ -208,7 +208,7 @@ protected override void ConfigureServices(IServiceCollection services) **错误信息**： -``` +```text NullReferenceException: Object reference not set to an instance of an object ``` @@ -254,7 +254,7 @@ public class SystemB : AbstractSystem **错误信息**： -``` +```text InvalidOperationException: Architecture not fully initialized ``` @@ -799,7 +799,7 @@ private IEnumerator CoroutineWithCleanup() **错误信息**： -``` +```text FileNotFoundException: Could not find file 'res://assets/player.png' ``` @@ -965,7 +965,7 @@ private async void PreloadResources() **错误信息**： -``` +```text NullReferenceException: Object reference not set to an instance of an object ``` @@ -1011,7 +1011,7 @@ await sceneRouter.NavigateToAsync("Game"); **错误信息**： -``` +```text NullReferenceException: Object reference not set to an instance of an object ``` @@ -1108,7 +1108,7 @@ public partial class GameController : Node **错误信息**： -``` +```text InvalidOperationException: Architecture context not found ``` @@ -1635,7 +1635,7 @@ public void DebugPlayerDamage() **完整错误信息**： -``` +```text NU1101: Unable to find package GFramework.Core. No packages exist with this id in source(s): nuget.org ``` @@ -1667,7 +1667,7 @@ dotnet restore **完整错误信息**： -``` +```text System.Collections.Generic.KeyNotFoundException: 未找到类型为 'PlayerModel' 的组件 ``` @@ -1694,7 +1694,7 @@ public class GameArchitecture : Architecture **完整错误信息**： -``` +```text System.InvalidOperationException: Architecture is already initialized ``` @@ -1769,7 +1769,7 @@ AddChild(anchor); **完整错误信息**： -``` +```text System.InvalidCastException: Unable to cast object of type 'Node' to type 'Player' ``` @@ -1804,7 +1804,7 @@ if (GetNode("Player") is Player player) **完整错误信息**： -``` +```text System.ArgumentException: An item with the same key has already been added. Key: PlayerModel ``` @@ -1920,7 +1920,7 @@ public class SystemA : AbstractSystem **完整错误信息**： -``` +```text System.ObjectDisposedException: Cannot access a disposed object. Object name: 'Architecture' ``` @@ -1960,7 +1960,7 @@ public void UseArchitecture() **完整错误信息**： -``` +```text System.IO.FileNotFoundException: Could not find file 'res://assets/player.png' ``` @@ -1997,7 +1997,7 @@ var texture = ResourceLoader.Load<Texture2D>("res://assets/player.png"); **完整错误信息**： -``` +```text System.NotImplementedException: The method or operation is not implemented ``` diff --git a/docs/zh-CN/tutorials/data-migration.md b/docs/zh-CN/tutorials/data-migration.md index 0c04df53..5ad0e689 100644 --- a/docs/zh-CN/tutorials/data-migration.md +++ b/docs/zh-CN/tutorials/data-migration.md @@ -553,7 +553,7 @@ namespace MyGame 所有代码文件已在上述步骤中提供。项目结构如下： -``` +```text MyGame/ ├── Data/ │ ├── PlayerSaveData.cs # 版本 1 数据结构 @@ -570,7 +570,7 @@ MyGame/ 运行程序后，你将看到类似以下的输出： -``` +```text === 数据迁移系统测试 === --- 注册迁移器 --- diff --git a/docs/zh-CN/tutorials/functional-programming.md b/docs/zh-CN/tutorials/functional-programming.md index 121cbd81..538e2797 100644 --- a/docs/zh-CN/tutorials/functional-programming.md +++ b/docs/zh-CN/tutorials/functional-programming.md @@ -775,7 +775,7 @@ class Program 运行程序后，你将看到类似以下的输出： -``` +```text === 函数式编程实践示例 === --- 测试 Option --- diff --git a/docs/zh-CN/tutorials/godot-complete-project.md b/docs/zh-CN/tutorials/godot-complete-project.md index 3545827c..19a0b2c5 100644 --- a/docs/zh-CN/tutorials/godot-complete-project.md +++ b/docs/zh-CN/tutorials/godot-complete-project.md @@ -71,7 +71,7 @@ description: 从零开始使用 GFramework 构建一个完整的 Godot 游戏项 ### 1.3 创建项目结构 -``` +```text MyShooterGame/ ├── Scripts/ │ ├── Architecture/ diff --git a/docs/zh-CN/tutorials/index.md b/docs/zh-CN/tutorials/index.md index 0646beb7..fa4cc05d 100644 --- a/docs/zh-CN/tutorials/index.md +++ b/docs/zh-CN/tutorials/index.md @@ -122,7 +122,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 ### 路径一：快速上手（推荐新手） -``` +```text 基础教程（全章节） → Godot 集成教程（选择性阅读） → 开始你的项目 ``` @@ -133,7 +133,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 ### 路径二：系统学习（推荐完整掌握） -``` +```text 基础教程 → Godot 集成教程 → 小项目实践 → 高级模式教程 ``` @@ -144,7 +144,7 @@ description: 汇总 GFramework 的基础与进阶教程入口，帮助按学习 ### 路径三：架构师之路（推荐团队负责人） -``` +```text 高级模式教程（预览） → 基础教程 → Godot 集成教程 → 高级模式教程（深入） → 架构设计实践 ``` diff --git a/docs/zh-CN/tutorials/large-project-organization.md b/docs/zh-CN/tutorials/large-project-organization.md index d2ff8f7e..c58f5fa2 100644 --- a/docs/zh-CN/tutorials/large-project-organization.md +++ b/docs/zh-CN/tutorials/large-project-organization.md @@ -29,7 +29,7 @@ description: 学习如何使用 GFramework 组织和管理大型游戏项目 ### 1.1 推荐的目录结构 -``` +```text MyLargeGame/ ├── src/ │ ├── MyGame.Core/ # 核心层 @@ -1529,7 +1529,7 @@ namespace MyGame 运行程序后,你将看到类似以下的输出: -``` +```text === 大型游戏项目示例 === === 初始化游戏架构 === diff --git a/docs/zh-CN/tutorials/pause-system.md b/docs/zh-CN/tutorials/pause-system.md index 8022b76e..42fd0c6c 100644 --- a/docs/zh-CN/tutorials/pause-system.md +++ b/docs/zh-CN/tutorials/pause-system.md @@ -822,7 +822,7 @@ namespace MyGame.Controllers ### 项目结构 -``` +```text MyGame/ ├── GameArchitecture.cs ├── Systems/ @@ -911,7 +911,7 @@ class Program 运行程序后，你将看到类似以下的输出： -``` +```text === 暂停系统教程 === 暂停系统和处理器初始化完成 @@ -1130,4 +1130,3 @@ class Program - [Utility 层](/zh-CN/core/utility.md) - Utility 详细说明 - [生命周期管理](/zh-CN/core/lifecycle.md) - 组件生命周期 - [扩展方法](/zh-CN/core/extensions.md) - 便捷的扩展方法 - diff --git a/docs/zh-CN/tutorials/resource-management.md b/docs/zh-CN/tutorials/resource-management.md index 52f59464..30f99674 100644 --- a/docs/zh-CN/tutorials/resource-management.md +++ b/docs/zh-CN/tutorials/resource-management.md @@ -689,7 +689,7 @@ class Program 所有代码文件已在上述步骤中提供。项目结构如下： -``` +```text MyGame/ ├── Resources/ │ ├── Texture.cs @@ -709,7 +709,7 @@ MyGame/ 运行程序后，你将看到类似以下的输出： -``` +```text === 资源管理最佳实践测试 === 资源管理器初始化完成 diff --git a/docs/zh-CN/tutorials/save-system.md b/docs/zh-CN/tutorials/save-system.md index f6782998..604b43a6 100644 --- a/docs/zh-CN/tutorials/save-system.md +++ b/docs/zh-CN/tutorials/save-system.md @@ -810,7 +810,7 @@ class Program 所有代码文件已在上述步骤中提供。项目结构如下： -``` +```text MyGame/ ├── Data/ │ ├── PlayerData.cs @@ -829,7 +829,7 @@ MyGame/ 运行程序后，你将看到类似以下的输出： -``` +```text === 存档系统测试 === 游戏架构初始化完成 @@ -963,4 +963,4 @@ MyGame/ - [数据与存档系统](/zh-CN/game/data.md) - 数据系统详细说明 - [对象池系统](/zh-CN/core/pool.md) - 结合对象池复用资源 - [协程系统](/zh-CN/core/coroutine.md) - 异步加载资源 -- [System 层](/zh-CN/core/system.md) - System 详细说明 \ No newline at end of file +- [System 层](/zh-CN/core/system.md) - System 详细说明 diff --git a/docs/zh-CN/tutorials/state-machine-tutorial.md b/docs/zh-CN/tutorials/state-machine-tutorial.md index 587dd37e..9a62f204 100644 --- a/docs/zh-CN/tutorials/state-machine-tutorial.md +++ b/docs/zh-CN/tutorials/state-machine-tutorial.md @@ -627,7 +627,7 @@ class Program 所有代码文件已在上述步骤中提供。项目结构如下： -``` +```text MyGame/ ├── States/ │ ├── MenuState.cs @@ -645,7 +645,7 @@ MyGame/ 运行程序后，你将看到类似以下的输出： -``` +```text === 状态机系统测试 === 状态机系统初始化完成 diff --git a/docs/zh-CN/tutorials/unit-testing.md b/docs/zh-CN/tutorials/unit-testing.md index 7011d539..90f21cfe 100644 --- a/docs/zh-CN/tutorials/unit-testing.md +++ b/docs/zh-CN/tutorials/unit-testing.md @@ -946,7 +946,7 @@ public class BindablePropertyTests 以下是一个完整的测试项目结构示例： -``` +```text MyGame.Tests/ ├── GlobalUsings.cs ├── MyGame.Tests.csproj @@ -997,7 +997,7 @@ dotnet test --collect:"XPlat Code Coverage" ## 测试输出示例 -``` +```text 正在启动测试执行，请稍候... 总共 1 个测试文件与指定模式匹配。 From 074002254e62be269d7918471ec5b1bc72a1ddae Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sat, 25 Apr 2026 16:08:23 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(pr-review):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=AE=A1=E6=9F=A5=E5=8F=8D=E9=A6=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 source-generators 侧栏标签并移除 API 参考侧栏中的跨栏目重复入口 - 优化 Core、Ecs.Arch、Game README 的 XML 阅读入口表述，删除覆盖基线式字段 - 补充 documentation-full-coverage-governance 跟踪与验证记录，记录 PR #290 审查收口状态 --- GFramework.Core/README.md | 19 ++++--- GFramework.Ecs.Arch/README.md | 12 ++--- GFramework.Game/README.md | 17 +++--- ...ation-full-coverage-governance-tracking.md | 40 +++++++------- ...entation-full-coverage-governance-trace.md | 52 ++++++++----------- docs/.vitepress/config.mts | 21 ++------ 6 files changed, 68 insertions(+), 93 deletions(-) diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index 607fabcb..93481ab3 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -62,18 +62,17 @@ ## XML 阅读入口 -截至 `2026-04-22`，下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口；当前主目录族的类型声明都已带 -XML 注释。更细的参数、返回值和生命周期语义，适合在阅读对应类型与成员时继续结合源码确认。 +下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口。更细的参数、返回值和生命周期语义，适合在阅读对应类型与成员时继续结合源码确认。 -| 类型族 | 基线状态 | 代表类型 | +| 类型族 | 代表类型 | 阅读重点 | | --- | --- | --- | -| `Architectures/` `Services/` | `22/22` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ServiceModuleManager` | -| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand`、`AbstractQuery` | -| `Events/` `Property/` `State/` `StateManagement/` | `29/29` 个类型声明已带 XML 注释 | `EventBus`、`BindableProperty`、`StateMachine`、`Store` | -| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`PauseStackManager`、`AsyncKeyLockManager` | -| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`AbstractObjectPoolSystem` | -| `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` | +| `Architectures/` `Services/` | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ServiceModuleManager` | 先看架构入口、上下文对象与模块生命周期如何协同 | +| `Command/` `Query/` | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand`、`AbstractQuery` | 看命令 / 查询执行入口、同步异步边界与抽象基类约束 | +| `Events/` `Property/` `State/` `StateManagement/` | `EventBus`、`BindableProperty`、`StateMachine`、`Store` | 看事件分发、状态绑定、状态机与 Store 的职责划分 | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `CoroutineScheduler`、`CoroutineHandle`、`PauseStackManager`、`AsyncKeyLockManager` | 看调度、暂停、时间推进与并发控制的生命周期语义 | +| `Resource/` `Pool/` | `ResourceManager`、`AutoReleaseStrategy`、`AbstractObjectPoolSystem` | 看资源释放策略、池化抽象与可复用对象边界 | +| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `ConsoleLogger`、`LocalizationManager`、`ConfigurationManager`、`DefaultEnvironment`、`MicrosoftDiContainer` | 看基础设施入口与默认实现的组合方式 | +| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result` | 看业务模型、系统基类、上下文辅助类型与函数式工具如何配合 | 完整的模块化接入说明和阅读顺序见 [Core 栏目](../docs/zh-CN/core/index.md)。 diff --git a/GFramework.Ecs.Arch/README.md b/GFramework.Ecs.Arch/README.md index 714c2192..75240b8a 100644 --- a/GFramework.Ecs.Arch/README.md +++ b/GFramework.Ecs.Arch/README.md @@ -123,12 +123,12 @@ ecsModule.Update(deltaTime); 下表汇总当前模块 README 与源码可对照的类型级 XML 文档入口，方便先抓住 Arch ECS 集成的关键类型。 -| 类型族 | 代表类型 | XML 状态 | 阅读重点 | -| --- | --- | --- | --- | -| 装配入口 | `ArchExtensions` | 已覆盖 | `UseArch(...)` 的时机与返回值 | -| 运行时模块 | `ArchEcsModule` | 已覆盖 | `World` 注册、系统排序、销毁顺序 | -| 系统桥接层 | `ArchSystemAdapter` | 已覆盖 | `OnArchInitialize`、`OnUpdate`、`OnArchDispose` | -| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 已覆盖 | 组件布局、查询写法、最小示例 | +| 类型族 | 代表类型 | 阅读重点 | +| --- | --- | --- | +| 装配入口 | `ArchExtensions` | `UseArch(...)` 的接入时机、返回值与默认模块拼装方式 | +| 运行时模块 | `ArchEcsModule` | `World` 注册、系统排序、销毁顺序与配置对象的消费方式 | +| 系统桥接层 | `ArchSystemAdapter` | `OnArchInitialize`、`OnUpdate`、`OnArchDispose` 的生命周期桥接 | +| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 组件布局、查询写法与最小更新循环示例 | ## 对应文档入口 diff --git a/GFramework.Game/README.md b/GFramework.Game/README.md index 597f6760..f782c4d0 100644 --- a/GFramework.Game/README.md +++ b/GFramework.Game/README.md @@ -171,16 +171,15 @@ ## XML 阅读入口 -下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game` 类型级 XML 文档入口：只统计公开 / -内部类型声明是否带 XML 注释，用来帮助你确定运行时阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。 +下面这份目录视图汇总了 `GFramework.Game` 的类型级 XML 文档入口，用来帮助你确定运行时阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。 -| 子系统 | 基线状态 | 代表类型 | 阅读重点 | -| --- | --- | --- | --- | -| `Config/` | `26/26` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`ConfigRegistry`、`GameConfigBootstrap`、`YamlConfigSchemaValidator` | 看 YAML 加载、schema 校验、模块接入与热重载边界 | -| `Data/` `Storage/` `Serializer/` | `8/8` 个类型声明已带 XML 注释 | `DataRepository`、`SaveRepository`、`UnifiedSettingsDataRepository`、`FileStorage`、`JsonSerializer` | 看持久化布局、槽位存档、统一设置文件和底层序列化 / 存储实现 | -| `Setting/` | `9/9` 个类型声明已带 XML 注释 | `SettingsModel`、`SettingsSystem`、`SettingsAppliedEvent` | 看初始化、应用、保存、重置等设置生命周期编排 | -| `Scene/` `UI/` `Routing/` | `10/10` 个类型声明已带 XML 注释 | `SceneRouterBase`、`UiRouterBase`、`SceneTransitionPipeline`、`UiTransitionPipeline`、`RouterBase` | 看路由基类、转换处理器和项目层需要自己提供的 factory / root 边界 | -| `Extensions/` `Internal/` `State/` | `3/3` 个类型声明已带 XML 注释 | `DataLocationExtensions`、`VersionedMigrationRunner`、`GameStateMachineSystem` | 看辅助扩展、内部迁移执行逻辑和游戏态状态机封装 | +| 子系统 | 代表类型 | 阅读重点 | +| --- | --- | --- | +| `Config/` | `YamlConfigLoader`、`ConfigRegistry`、`GameConfigBootstrap`、`YamlConfigSchemaValidator` | 看 YAML 加载、schema 校验、模块接入与热重载边界 | +| `Data/` `Storage/` `Serializer/` | `DataRepository`、`SaveRepository`、`UnifiedSettingsDataRepository`、`FileStorage`、`JsonSerializer` | 看持久化布局、槽位存档、统一设置文件和底层序列化 / 存储实现 | +| `Setting/` | `SettingsModel`、`SettingsSystem`、`SettingsAppliedEvent` | 看初始化、应用、保存、重置等设置生命周期编排 | +| `Scene/` `UI/` `Routing/` | `SceneRouterBase`、`UiRouterBase`、`SceneTransitionPipeline`、`UiTransitionPipeline`、`RouterBase` | 看路由基类、转换处理器和项目层需要自己提供的 factory / root 边界 | +| `Extensions/` `Internal/` `State/` | `DataLocationExtensions`、`VersionedMigrationRunner`、`GameStateMachineSystem` | 看辅助扩展、内部迁移执行逻辑和游戏态状态机封装 | ## 最小接入路径 diff --git 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 index 8ba1e64e..0156d68d 100644 --- 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,25 +12,22 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-035` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-036` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按本轮 `$gframework-batch-boot 50` 约束使用最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）作为唯一 baseline，只推进低风险、可切片的 reader-facing 文档治理批次 - - 已接受 worker 的导航 / 语义化链接批次，提交为 `094e29e`（`docs(docs): 统一中文文档导航与语义化链接文案`） - - 当前未提交批次覆盖 `abstractions` reader-facing 标签、`best-practices` / `troubleshooting` / `tutorials` 代码块语言标记、7 个模块 / 根 README 的 reader-facing XML 阅读入口改写，以及 `contributing` / `godot/resource` 的剩余 bare opening fence - - 当前批次连同 active tracking / trace 一并落地后，累计 branch diff 将达到 `34 / 50` 个 changed files；虽然仍有 `16` 个文件 headroom，但同类低风险、可重复批处理切片已经基本耗尽 - - 若继续下一轮，不应再按当前模式盲目扩批，而应先复核 PR / review 状态，再决定是否进入新的非重复性文档巡检波次 + - 继续以最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）作为 baseline，当前只收口 PR `#290` latest-head review 仍然成立的 reader-facing 文档问题 + - 已用 `$gframework-pr-review` 重新抓取 PR `#290`（`docs/sdk-update-documentation`），确认 `coderabbitai[bot]` 与 `greptile-apps[bot]` 仍各有 `1` 条 open thread，测试汇总保持 `2156 passed` + - 本轮未提交变更聚焦 3 个点：移除 `API 参考` 侧栏里的跨栏目重复入口、统一 3 个 source generator 侧栏标签与目标页标题、删除 `Core` / `Ecs.Arch` / `Game` README 中残留的 XML 覆盖基线表达 + - 当前批次仍属于低风险 reader-facing 文档治理，但已经从批量“普查”切换为按 PR review 精确收口 + - 若本轮收口并提交后仍存在 review 线程，应重新抓取最新 PR 状态，再决定是否继续扩展到其他未触达 README 或 docs 巡检点 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-25` worker A 已完成并提交 5 个模块 README 的 reader-facing 链接标签修正，提交为 `bd5cdb5`（`docs(readme): 优化链接标签`）；该切片仍作为本 topic 的已接受历史批次保留。 -- `2026-04-25` 最新 `origin/main` 已推进到 `4ad880c`；当前 `docs/sdk-update-documentation` 相对该 baseline 的已提交 branch diff 为 `7 / 50` 个文件，来自导航与语义化链接批次 `094e29e`。 -- `2026-04-25` 当前未提交工作树额外覆盖 `25` 个文件：`abstractions` 2 页链接标签、`best-practices` 2 页代码块标记、`troubleshooting` 1 页错误输出标记、`tutorials` 10 页目录树 / 路径 / 输出块标记、根 / 模块 README 8 页 reader-facing 改写，以及 `contributing` / `godot/resource` 2 页剩余 bare opening fence 处理。 -- `2026-04-25` `docs/.vitepress/config.mts` 已补齐 `abstractions`、`source-generators`、`api-reference` 的中文 sidebar / nav 入口，且 `docs/zh-CN/ecs/arch.md`、`game/*.md`、`godot/*.md` 的原始路径式可见标签已统一为读者可理解的语义化名称。 -- `2026-04-25` `docs/zh-CN/tutorials` 本轮已额外补齐 10 个非基础教程页的 bare fenced opening 语言标记；目录树、学习路径和控制台输出统一显式标注为 `text`，未改写示例内容。 -- `2026-04-25` 根 README 与 7 个模块 README 当前已把 `XML 覆盖基线` / `XML 阅读基线` / `inventory` / `后续治理项` 一类 maintainer-facing 标题与导语改为 reader-facing 的“XML 阅读入口 / 推荐优先阅读的 XML 类型族”等表达，保留了现有表格、链接与证据链。 -- `2026-04-25` 本轮主线程复核后确认：`docs/zh-CN` 中可由统一规则安全处理的 bare opening fence 只剩 `docs/zh-CN/contributing.md:631` 这一处既有嵌套 fenced 示例警告；它不适合继续按当前“只补 opening fence、不碰 closing fence”的批处理规则自动改写。 +- `2026-04-25` 已重新抓取 PR `#290` 并确认：latest reviewed commit 为 `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181`，open thread 聚焦在 `docs/.vitepress/config.mts` 的侧栏重复 / 标签不一致，以及 `GFramework.Core`、`GFramework.Ecs.Arch`、`GFramework.Game` README 的 reader-facing 表格残留治理字段。 +- `2026-04-25` `docs/.vitepress/config.mts` 已保留 `source-generators` 栏目自有子页导航，但不再让 `api-reference` 侧栏重复跳回 `core`、`game`、`godot`、`ecs` 等独立栏目入口。 +- `2026-04-25` `GFramework.Core/README.md`、`GFramework.Ecs.Arch/README.md`、`GFramework.Game/README.md` 当前把 XML 阅读表统一收敛为“代表类型 + 阅读重点”，不再暴露日期、覆盖计数或 `已覆盖` 这类治理式字段。 +- `2026-04-25` `docs/zh-CN/tutorials`、`best-practices`、`troubleshooting`、`contributing`、`godot/resource` 的前一轮 reader-facing 与代码块标记治理已保持有效；本轮不再扩批这些同模板切片。 - `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`、 @@ -41,13 +38,12 @@ ## 当前风险 -- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 `ai-plan/**`，不应再暴露到公开文档。 +- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 `ai-plan/**`，不应再回流到公开文档。 - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 -- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用本轮“只补 opening fence”规则自动改写。 -- 当前可用的低风险、可重复批处理切片已经基本消耗完毕；如果继续推进，剩余问题更可能落在非重复性 prose 调整、复杂示例结构或远端 review 反馈，不宜按本轮同一批处理模板继续盲扫。 -- PR `#287` 的 latest-head review 本轮未重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。 +- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用前一轮“只补 opening fence”规则自动改写。 +- PR `#290` 当前 review 线程来自 bot，对 reader-facing 导航和文案一致性的期望比较细；本轮提交后仍需重新抓取 latest-head review，确认是否还有新的 open thread 或旧线程未自动关闭。 ## 归档指针 @@ -64,6 +60,12 @@ ## 最新验证 +- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` + - 结果：通过；PR `#290` 处于 `OPEN`，latest head commit `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181` 有 `2` 条 open thread（CodeRabbit `1`、Greptile `1`），测试汇总为 `2156 passed`，无 failed checks。 +- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md` + - 结果：通过；本轮 3 个模块 README 调整后链接目标仍然有效。 +- `2026-04-25` `bun run build`（工作目录：`docs/`） + - 结果：通过；移除 `api-reference` 侧栏重复项并统一 `source-generators` 标签后站点仍可正常构建，仅保留既有大 chunk warning。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` - 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` @@ -128,8 +130,8 @@ ## 下一步 -1. 当前 `$gframework-batch-boot 50` 建议在本轮停止：待当前工作树与 active tracking / trace 一并提交后，累计 branch diff 将为 `34 / 50`，但同类低风险、可重复切片已基本耗尽。 -2. 若继续下一轮，优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。 +1. 完成本轮修改后先跑 `bun run build`（工作目录 `docs/`）与受影响 README 链接校验，再提交当前 PR review 收口批次。 +2. 提交完成后重新抓取 `$gframework-pr-review` 确认 PR `#290` 的 latest-head review 是否已清空 open thread，再决定是否继续巡检其他 reader-facing 文档。 3. 若后续继续处理公开文档，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得做结构化改写，而不是继续沿用“只补 opening fence”的自动批处理规则。 4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 diff --git 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 index 22cf7154..49b5edb6 100644 --- 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,42 +2,32 @@ ## 2026-04-25 -### 当前恢复点：RP-035 +### 当前恢复点：RP-036 -- 本轮按 `$gframework-batch-boot 50` 执行，baseline 重新对齐到最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）；重新开始时 committed branch diff 为 `0 / 50` 个 changed files。 -- 已接受 worker 批次 `094e29e`（`docs(docs): 统一中文文档导航与语义化链接文案`），该提交补齐了 `abstractions` / `source-generators` / `api-reference` 的中文导航入口，并修复了 `ecs`、`game`、`godot` 目标页面的路径式可见链接标签。 -- 主线程接收并复核了 `abstractions` 2 页 reader-facing 链接标签修正、`best-practices` 2 页和 `troubleshooting` 1 页的代码块语言标记补齐，以及 `tutorials` 10 页目录树 / 路径 / 输出块统一显式标记为 `text`。 -- 主线程还接收了根 README 与 7 个模块 README 的 reader-facing XML 阅读入口改写，并补齐了 `docs/zh-CN/contributing.md`、`docs/zh-CN/godot/resource.md` 的剩余 bare opening fence。 -- 当前未提交工作树连同 active tracking / trace 一并落地后，累计 branch diff 将达到 `34 / 50` 个 changed files；本轮在未触及阈值的情况下停止，因为同类低风险、可重复批处理切片已基本耗尽。 +- 本轮从 `$gframework-pr-review` 重新进入，目标不再是扩批，而是核对 PR `#290` latest-head review 仍未关闭的 reader-facing 文档问题。 +- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#290` 最新 reviewed commit 为 `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181`，CodeRabbit 与 Greptile 各有 `1` 条 open thread，失败检查为 `0`，测试汇总仍为 `2156 passed`。 +- 本轮把远端 review 与本地工作树逐项比对后，只接受仍然成立的 5 个 reader-facing 问题：`source-generators` 侧栏 3 个标签与目标标题不一致、`api-reference` 侧栏重复暴露跨栏目入口、`Core` / `Ecs.Arch` / `Game` README 仍保留 XML 覆盖基线字段。 +- 当前未提交批次限定在 `docs/.vitepress/config.mts`、3 个模块 README，以及 active tracking / trace；没有继续扩展到其他未被 review 指向的文档文件。 -### 当前决策（RP-035） +### 当前决策（RP-036） -- 继续沿用“导航 / 链接标签”和“bare opening fence 语言标记”两类低语义风险规则，但拒绝把 closing fence 或复杂嵌套 fenced 结构纳入同一自动批处理模板。 -- 对 worker 产出的代码块标记批次一律做主线程复核；发现 closing fence 被误改后已在本轮立即纠正，并把后续批次提示词收紧到“只改 opening fence”。 -- README 治理批次只改 reader-facing 标题、导语和链接可见标签，不删除现有表格、证据链或源码 / 测试导向的阅读线索。 -- 在 `34 / 50` 之前停止本轮，不是因为 headroom 不足，而是因为自动可识别、风险可控的重复切片已经收敛到仅剩 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 警告；该问题更适合后续人工结构化处理。 +- 对 PR review 的处理改成“只修当前 latest-head review 仍成立的问题”，不再延续前一轮的批量普查节奏。 +- `api-reference` 侧栏不再承载跨栏目目录跳转；跨模块导航继续保留在 `docs/zh-CN/api-reference/index.md` 的正文里，避免侧栏在跳出栏目后发生上下文切换。 +- `source-generators` 侧栏项统一与目标文档的 H1 / frontmatter `title` 对齐，避免同一页面在导航、标题与搜索索引里出现多套命名。 +- 模块 README 的 XML 阅读表只保留读者有用的“代表类型 / 阅读重点”，把覆盖计数、日期和 `已覆盖` 之类治理痕迹全部留在 `ai-plan/**`。 -### 当前验证（RP-035） +### 当前验证（RP-036） + +- PR review 抓取： + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` + - 结果：通过；PR `#290` 处于 `OPEN`，latest head review 还有 `2` 条 open thread，测试汇总为 `2156 passed`。 - README / 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` - - 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。 -- 教程校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` - - 结果：通过；本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。 -- 最佳实践校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices` - - 结果：通过；`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。 -- 单页校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` - - 结果：通过；错误输出与完整错误信息块补齐为 `text` 后页面验证通过。 - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` - - 结果：通过，但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告。 - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` - - 结果：通过；剩余 bare opening fence 已补齐语言标记。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md` + - 结果：通过；本轮 3 个 README 调整后链接目标仍然有效。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；`docs/.vitepress/config.mts` 的侧栏调整后站点仍可构建，仅保留既有大 chunk warning。 ### 归档指针 @@ -49,6 +39,6 @@ ### 下一步 -1. 若继续下一轮，优先重新抓取 `$gframework-pr-review`，确认 PR `#287` 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。 -2. 下一轮若仍要扩批，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得结构化改写，而不是继续沿用本轮的 opening-fence-only 自动修正规则。 -3. 当前轮次建议在 `34 / 50` 停止并提交，后续若要继续，应以新的低风险模式或新的热点清单重新建批。 +1. 完成 `bun run build` 与 README 链接校验后，提交当前 PR `#290` review 收口批次。 +2. 提交后再次运行 `$gframework-pr-review`，确认 CodeRabbit / Greptile 的 open thread 是否已关闭。 +3. 若仍有 review 残留，再按 latest-head review 精确收口，不恢复到前一轮的广覆盖批处理模式。 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 4766d4fa..9fc7eec6 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -248,13 +248,13 @@ export default defineConfig({ items: [ { text: '概览', link: '/zh-CN/source-generators/' }, { text: '日志生成器', link: '/zh-CN/source-generators/logging-generator' }, - { text: '枚举生成器', link: '/zh-CN/source-generators/enum-generator' }, + { text: '枚举扩展生成器', link: '/zh-CN/source-generators/enum-generator' }, { text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' }, { text: 'Priority 生成器', link: '/zh-CN/source-generators/priority-generator' }, - { text: 'ContextGet 生成器', link: '/zh-CN/source-generators/context-get-generator' }, + { text: 'Context Get 注入生成器', link: '/zh-CN/source-generators/context-get-generator' }, { text: '模块自动注册生成器', link: '/zh-CN/source-generators/auto-register-module-generator' }, { text: 'CQRS Handler Registry 生成器', link: '/zh-CN/source-generators/cqrs-handler-registry-generator' }, - { text: 'Godot 项目生成器', link: '/zh-CN/source-generators/godot-project-generator' }, + { text: 'Godot 项目元数据生成器', link: '/zh-CN/source-generators/godot-project-generator' }, { text: 'GetNode 生成器 (Godot)', link: '/zh-CN/source-generators/get-node-generator' }, { text: 'BindNodeSignal 生成器 (Godot)', link: '/zh-CN/source-generators/bind-node-signal-generator' }, { text: 'AutoUiPage 生成器', link: '/zh-CN/source-generators/auto-ui-page-generator' }, @@ -276,21 +276,6 @@ export default defineConfig({ } ], - '/zh-CN/api-reference/': [ - { - text: 'API 参考', - items: [ - { text: '概览', link: '/zh-CN/api-reference/' }, - { text: 'Core 栏目', link: '/zh-CN/core/' }, - { text: 'Game 模块总览', link: '/zh-CN/game/' }, - { text: 'Godot 模块总览', link: '/zh-CN/godot/' }, - { text: 'ECS 模块总览', link: '/zh-CN/ecs/' }, - { text: '抽象接口', link: '/zh-CN/abstractions/' }, - { text: '源码生成器', link: '/zh-CN/source-generators/' } - ] - } - ], - '/zh-CN/tutorials/': [ { text: '教程',