From cdc6d7e028256ead211dd304c29f5d9271c7c061 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 10:02:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(documentation):=20=E6=9B=B4=E6=96=B0Godot?= =?UTF-8?q?=E7=94=9F=E6=88=90=E5=99=A8=E5=85=A5=E5=8F=A3=E6=8F=8F=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修正根 README 中 Godot.SourceGenerators 的模块职责摘要 - 补充 source-generators 总览页的 Godot 选包说明与 frontmatter - 更新 documentation-full-coverage-governance 的恢复点与验证记录 --- README.md | 2 +- ...ation-full-coverage-governance-tracking.md | 14 ++++++-- ...entation-full-coverage-governance-trace.md | 36 +++++++++++++++++++ docs/zh-CN/source-generators/index.md | 7 +++- 4 files changed, 54 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index af805a2f..85646537 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ | `GFramework.Core.SourceGenerators` | Core 侧通用源码生成器与分析器 | [README](GFramework.Core.SourceGenerators/README.md) | | `GFramework.Game.SourceGenerators` | 游戏内容配置 schema 生成器 | [README](GFramework.Game.SourceGenerators/README.md) | | `GFramework.Cqrs.SourceGenerators` | CQRS handler registry 生成器 | [README](GFramework.Cqrs.SourceGenerators/README.md) | -| `GFramework.Godot.SourceGenerators` | Godot 场景专用源码生成器 | [README](GFramework.Godot.SourceGenerators/README.md) | +| `GFramework.Godot.SourceGenerators` | Godot 项目元数据、节点注入、信号绑定与 Scene/UI 辅助生成器 | [README](GFramework.Godot.SourceGenerators/README.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 a095abb6..06d3a471 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,7 +12,7 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-011` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-012` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 继续巡检 `Godot` / `Game` 相关 README、landing page 与 API reference 的 cross-link 是否回漂 @@ -43,6 +43,9 @@ - `GFramework.Godot/README.md` 仍停留在旧版简略描述，缺少当前包关系、子系统地图、最小接入路径与 `docs/zh-CN` 入口 - `GFramework.Godot.SourceGenerators/README.md` 虽有示例，但没有覆盖 `AutoScene`、`AutoUiPage`、`AutoRegisterExportedCollections` 等当前生成器分组，也没有把运行时 / 生成器边界说清 - `docs/zh-CN/api-reference/index.md` 的 `Godot` 行此前只把生成器入口指向泛化的 `source-generators/index.md`，不利于从 API 参考直接落到 `Godot` 专题页 +- `2026-04-23` 的后续入口巡检新增结论： + - 根 `README.md` 的模块地图仍把 `GFramework.Godot.SourceGenerators` 写成“Godot 场景专用源码生成器”，范围过窄，不符合当前 `project.godot` 元数据、节点注入、信号绑定、Scene / UI 包装与导出集合注册的真实职责 + - `docs/zh-CN/source-generators/index.md` 的选包说明此前只提到 `AutoLoad / Input Action` 与节点 / 信号样板，没有把 Scene / UI 包装与导出集合注册辅助纳入同一入口 - 本轮已完成的治理动作： - 新建 `GFramework.Ecs.Arch.Abstractions/README.md` - 在根 `README.md` 中补齐 `GFramework.Ecs.Arch.Abstractions` 入口，并声明内部支撑模块 owner @@ -74,6 +77,8 @@ - 重写 `GFramework.Godot/README.md`，补齐包定位、相邻包关系、子系统地图、最小接入路径与站内文档入口，并明确它不拥有生成器职责 - 重写 `GFramework.Godot.SourceGenerators/README.md`，按 `project.godot` 元数据、节点注入 / 信号绑定、行为包装与批量注册四组能力重建入口 - 更新 `docs/zh-CN/api-reference/index.md` 的 `Godot` 模块映射，使 API 参考能直接落到 `Godot` 专用生成器专题页，而不是仅回到总览页 + - 修正根 `README.md` 中 `GFramework.Godot.SourceGenerators` 的模块描述，使其与当前生成器职责边界一致 + - 扩充 `docs/zh-CN/source-generators/index.md` 的 Godot 选包说明，把 Scene / UI 包装与导出集合注册辅助纳入入口摘要 ## Inventory（第一版） @@ -122,7 +127,7 @@ - 结果：通过；PR `#271` 已关闭，latest reviewed commit 为 `df91d3706ba9db71737e803ef2f40f4841ecbbf1`，当前 `2` 条 open thread 都是已被本地文件满足的陈旧信号，不再构成本轮阻塞 - 最新构建结论： - `2026-04-23` `cd docs && bun run build` - - 结果：通过；在 `Godot` README / API 入口修复后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败 + - 结果：通过；在根 `README.md` 与 `source-generators` 总览页补齐 `Godot.SourceGenerators` 职责描述后再次验证通过，仅保留既有 VitePress 大 chunk warning，无构建失败 - 最新恢复治理结论： - `2026-04-23` 重新读取 `ai-plan/public/archive/documentation-governance-and-refresh/**` - 结果：通过；确认 `Godot` family 适合把最小恢复摘要迁回 active topic，但不需要把整段归档历史重新放回默认 `boot` 路径 @@ -136,9 +141,12 @@ - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot.SourceGenerators/README.md`：通过 - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh GFramework.Godot.SourceGenerators/README.md`：通过 - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md`：通过 + - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md`：通过 + - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh README.md`：通过 + - `2026-04-23` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`：通过 ## 下一步 -1. 继续抽查 `Game` 与 `Godot` 相邻入口，优先看根 `README.md`、`docs/zh-CN/source-generators/index.md` 与教程页之间是否仍有旧 owner 描述 +1. 继续抽查 `Game` / `Godot` 相关教程与 landing page，优先确认 `docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/godot/index.md` 与根 `README.md` 的职责摘要是否继续保持同一口径 2. 当后续分支再修改 `Godot` / `Game` family 的 README、docs 或公共 API 时，回到对应模块追加 targeted 巡检与验证 3. 仅在需要阶段级细节时再读取 `documentation-governance-and-refresh` archive，而不是把 archive 重新当作默认 `boot` 入口 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 e9aa8028..e60fa3d4 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 @@ -395,3 +395,39 @@ 1. 继续抽查根 `README.md`、`docs/zh-CN/source-generators/index.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 是否仍把 `Godot` owner 写回旧边界 2. 当后续分支继续修改 `Game` / `Godot` family 入口时，沿用当前 README -> landing -> API reference 的最小修复顺序 + +### 当前恢复点：RP-012 + +- 继续按 `boot` 恢复后的默认下一步执行 `Game` / `Godot` 入口巡检，并重新读取： + - `README.md` + - `docs/zh-CN/source-generators/index.md` + - `docs/zh-CN/tutorials/godot-integration.md` + - `docs/zh-CN/api-reference/index.md` + - `GFramework.Godot/README.md` + - `GFramework.Godot.SourceGenerators/README.md` +- 巡检结果显示主体内容仍然稳定，但根入口摘要存在一处残留漂移： + - 根 `README.md` 仍把 `GFramework.Godot.SourceGenerators` 写成“Godot 场景专用源码生成器”，与当前包实际覆盖的 `project.godot` 元数据、节点注入、信号绑定、Scene / UI 包装和导出集合注册职责不符 + - `docs/zh-CN/source-generators/index.md` 的选包描述同步缺少 Scene / UI 包装与导出集合注册辅助这组能力 +- 因此本轮执行最小修复集： + - 更新根 `README.md` 的 `GFramework.Godot.SourceGenerators` 模块描述 + - 更新 `docs/zh-CN/source-generators/index.md` 的 Godot 选包摘要 + +### 当前决策（RP-012） + +- 继续维持“只修新发现的入口漂移，不重写稳定页面”的治理节奏；这轮不改 `docs/zh-CN/tutorials/godot-integration.md`，因为教程与 README / 生成器专题页仍使用同一套职责边界 +- 根 `README.md` 作为仓库一级入口，必须与模块 README 保持同一粒度的职责摘要；如果根入口比模块 README 更旧，后续 `boot` 和人工恢复都会被误导 +- `source-generators/index.md` 的选包段落需要覆盖当前真实能力分组，但不重复展开各专题页细节，避免重新长成第二份 README + +### 当前验证（RP-012） + +- 文档校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md`：通过 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-code-blocks.sh README.md`：通过 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md`：通过 +- 构建校验： + - `cd docs && bun run build`：通过；仅保留既有 VitePress 大 chunk warning，无构建失败 + +### 下一步 + +1. 继续抽查 `docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/godot/index.md` 与根 `README.md` 的职责摘要是否继续保持同一口径 +2. 当后续分支继续修改 `Game` / `Godot` family 入口时，沿用当前 README -> landing -> API reference 的最小修复顺序 diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 279762e2..fbde5df3 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -1,3 +1,8 @@ +--- +title: Source Generators +description: 按模块梳理 GFramework 当前发布的源码生成器包、运行时归属与推荐选包入口。 +--- + # Source Generators `Source Generators` 栏目对应 `GFramework` 当前按模块拆分发布的编译期工具链。 @@ -23,7 +28,7 @@ GFramework 当前发布的生成器包是： - 选择 `GeWuYou.GFramework.Game.SourceGenerators` - 想让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围： - 选择 `GeWuYou.GFramework.Cqrs.SourceGenerators` -- 想在 Godot 项目里生成 AutoLoad / Input Action 入口，或减少节点与信号样板代码： +- 想在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助： - 选择 `GeWuYou.GFramework.Godot.SourceGenerators` ## 与运行时的关系