From 8a117201d44739728df83c14ec274d4e89e19089 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:01:28 +0800 Subject: [PATCH] =?UTF-8?q?docs(documentation):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E4=B8=93=E9=A2=98=E9=A1=B5README=E5=AF=BC=E8=88=AA=E5=85=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新专题页推荐阅读中的 README 入口为可点击 GitHub 链接 - 修复 source-generators 与 Game/ECS/CQRS 页面中的裸路径导航 - 更新 documentation-full-coverage-governance 跟踪与轨迹以记录第二批治理结果 --- ...ation-full-coverage-governance-tracking.md | 11 +++++-- ...entation-full-coverage-governance-trace.md | 31 +++++++++++-------- .../abstractions/ecs-arch-abstractions.md | 4 +-- docs/zh-CN/core/cqrs.md | 2 +- docs/zh-CN/ecs/arch.md | 2 +- docs/zh-CN/game/scene.md | 4 +-- docs/zh-CN/game/ui.md | 4 +-- ...register-exported-collections-generator.md | 2 +- .../bind-node-signal-generator.md | 2 +- .../context-aware-generator.md | 2 +- .../source-generators/get-node-generator.md | 2 +- .../godot-project-generator.md | 2 +- .../source-generators/priority-generator.md | 2 +- 13 files changed, 40 insertions(+), 30 deletions(-) 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 cdd3dc71..2f4db2ee 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-022` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-023` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本 @@ -53,6 +53,9 @@ `api-reference/index.md`、`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md` 做导航可达性修复，把仓库 README / 根 README 裸路径统一改为指向 GitHub `main` 分支的可点击链接。 - 该批次不改变文档语义，只收口 docs 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。 +- `2026-04-23` 在同一基线下继续收口第二批专题页导航热点，已将 `core/cqrs.md`、`ecs/arch.md`、 + `abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 和 6 个 + `source-generators/*.md` 专题页里的 README 裸路径统一改为 GitHub `main` blob 外链。 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地 文件缺陷。 @@ -86,13 +89,15 @@ - `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` - 结果：确认 landing / API 导航页仍有一批裸路径仓库入口；本轮已先修复 `getting-started`、`core`、`game`、 `source-generators`、`api-reference` 与两个 abstractions 页面。 +- `2026-04-23` `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：定位第二批专题页导航热点，已修复 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、 + `game/scene.md`、`game/ui.md` 以及 6 个 `source-generators/*.md` 页面。 - `2026-04-23` `bun run build`（工作目录：`docs/`） - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 ## 下一步 -1. 对 `docs/zh-CN/**` 继续做下一类低风险导航巡检，优先收口 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、 - `game/ui.md` 与若干 source generator 专题页里剩余的裸路径 README 入口。 +1. 对 `docs/zh-CN/**` 继续做下一类低风险导航 / 渲染巡检，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接是否仍和页面结构一致。 2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖 常见分支阈值场景。 3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.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 4b6011fb..127434ca 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,38 +2,44 @@ ## 2026-04-23 -### 当前恢复点：RP-022 +### 当前恢复点：RP-023 - 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。 -- 本轮目标定义为“在不扩张语义范围的前提下，收口 docs landing / API 导航页中的裸路径仓库入口”。 +- 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。 - 本轮执行的修复： - - 将 `docs/zh-CN/getting-started/index.md` 中 `Cqrs`、`Game`、`Godot` 的仓库模块入口改为可点击链接 - - 将 `docs/zh-CN/core/index.md`、`game/index.md`、`source-generators/index.md` 的“对应模块入口”统一改为可点击链接 - - 将 `docs/zh-CN/api-reference/index.md` 中根 README 与模块 README 映射改为可点击链接 - - 将 `docs/zh-CN/abstractions/core-abstractions.md` 与 `game-abstractions.md` 的回跳入口改为可点击链接 - - 同步更新 active tracking / trace，记录新的治理切片与恢复点 + - 将 `docs/zh-CN/core/cqrs.md` 与 `ecs/arch.md` 的仓库 README 入口改为 GitHub `main` blob 外链 + - 将 `docs/zh-CN/abstractions/ecs-arch-abstractions.md`、`game/scene.md`、`game/ui.md` 的回跳 README 入口改为可点击链接 + - 将 `docs/zh-CN/source-generators/priority-generator.md`、`context-aware-generator.md`、 + `bind-node-signal-generator.md`、`godot-project-generator.md`、`get-node-generator.md`、 + `auto-register-exported-collections-generator.md` 的推荐阅读 README 入口改为可点击链接 + - 同步更新 active tracking / trace，记录第二批导航治理与新的恢复点 -### 当前决策（RP-022） +### 当前决策（RP-023） - 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。 - 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。 - 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。 - 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。 +- 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。 -### 当前验证（RP-022） +### 当前验证（RP-023） - 导航热点巡检： - `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` - 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。 +- 第二批专题页巡检： + - `rg -n '`GFramework\\.[^`]+/README\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'` + - 结果：命中 `core/cqrs.md`、`ecs/arch.md`、`abstractions/ecs-arch-abstractions.md`、`game/scene.md`、 + `game/ui.md` 与 6 个 `source-generators/*.md` 专题页，均已修复。 - 构建校验： - `bun run build`（工作目录：`docs/`） - 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。 -### 归档摘要（RP-021） +### 归档摘要（RP-022） - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。 - 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。 -- `docs/` 站点构建通过。 +- 完成第一批 landing / API 导航页 README 外链治理，并通过 `docs/` 站点构建。 ### 归档指针 @@ -44,5 +50,4 @@ ### 下一步 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。 -2. 若继续执行文档治理批处理，优先排查 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、`game/ui.md` - 与 source generator 专题页中剩余的裸路径 README 入口，而不是扩成跨模块大波次。 +2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。 diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md index c477d310..72c631d4 100644 --- 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` - - `GFramework.Ecs.Arch/README.md` + - [`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) diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index 28653d22..3431e1d9 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -186,4 +186,4 @@ RegisterCqrsPipelineBehavior>(); - 架构入口：[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` +- 模块 README：[`GFramework.Cqrs/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs/README.md) diff --git a/docs/zh-CN/ecs/arch.md b/docs/zh-CN/ecs/arch.md index 47fd2e95..46c1789b 100644 --- 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` +- 仓库模块 README：[`GFramework.Ecs.Arch/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md) - 统一 API / XML 导航：[`../api-reference/index.md`](../api-reference/index.md) diff --git a/docs/zh-CN/game/scene.md b/docs/zh-CN/game/scene.md index ea61c67d..d394adb5 100644 --- 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` -4. `GFramework.Game.Abstractions/README.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) diff --git a/docs/zh-CN/game/ui.md b/docs/zh-CN/game/ui.md index 5a64d405..2dd18cd2 100644 --- 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` -5. `GFramework.Game.Abstractions/README.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) diff --git a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md index fc0ebab9..cb501a3f 100644 --- 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? 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` +4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) diff --git a/docs/zh-CN/source-generators/bind-node-signal-generator.md b/docs/zh-CN/source-generators/bind-node-signal-generator.md index 0e317db7..b64ad0aa 100644 --- 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` +4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) diff --git a/docs/zh-CN/source-generators/context-aware-generator.md b/docs/zh-CN/source-generators/context-aware-generator.md index 3d9aafaf..c4e0a3d2 100644 --- 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` +4. [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md) diff --git a/docs/zh-CN/source-generators/get-node-generator.md b/docs/zh-CN/source-generators/get-node-generator.md index 1f317486..f8843f63 100644 --- 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` +4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) diff --git a/docs/zh-CN/source-generators/godot-project-generator.md b/docs/zh-CN/source-generators/godot-project-generator.md index f4fdfaf9..499013c3 100644 --- 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` +4. [`GFramework.Godot.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Godot.SourceGenerators/README.md) diff --git a/docs/zh-CN/source-generators/priority-generator.md b/docs/zh-CN/source-generators/priority-generator.md index 3059ddb1..62d1215c 100644 --- 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` +4. [`GFramework.Core.SourceGenerators/README.md`](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Core.SourceGenerators/README.md)