docs(documentation): 补充文档站仓库入口链接

- 更新 docs/zh-CN landing page 与 API 导航页中的 README 入口为可点击 GitHub 链接 - 修复 VitePress 对 docs 外相对链接的 dead link 构建失败 - 更新 documentation-full-coverage-governance 跟踪与轨迹以记录本轮批处理结论
2026-05-07 00:39:00 +08:00 · 2026-04-23 20:53:41 +08:00 · 2026-04-23 20:53:41 +08:00 · a4bb041b0d
commit a4bb041b0d
parent 148cfe14b0
9 changed files with 62 additions and 56 deletions
--- 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,11 +12,11 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-021`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-022`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 为 `gframework-batch-boot` 明确数字速记阈值语义，避免把“本轮新增文件数”与“整条分支 diff 阈值”混淆
-  - 保持 `Core` functional docs surface 的 inline code / 泛型示例在 VitePress 下按真实 C# 语法渲染
+  - 保持 landing page / API 导航页中的仓库 README 入口可点击，避免读者在 docs 站点里遇到裸路径文本
+  - 继续按 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险导航 / 渲染热点
  - 保持 `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/`
@ -48,6 +48,11 @@
  - `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止”
  - `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止”
  - `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆
+- `2026-04-23` 以 `origin/main`（`aa879d2`，`2026-04-23T17:51:41+08:00`）为批处理基线，对
+  `docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`source-generators/index.md`、
+  `api-reference/index.md`、`abstractions/core-abstractions.md`、`abstractions/game-abstractions.md`
+  做导航可达性修复，把仓库 README / 根 README 裸路径统一改为指向 GitHub `main` 分支的可点击链接。
+- 该批次不改变文档语义，只收口 docs 站点中的入口可达性；适合继续作为小步快跑的低风险治理模式。
 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
  文件缺陷。

@ -78,15 +83,18 @@
  - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。
 - `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md`
  - 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。
+- `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` `bun run build`（工作目录：`docs/`）
-  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
+  - 结果：通过；仓库 README 外链改为 GitHub `main` blob 后，不再触发 VitePress dead link；仅保留既有大 chunk warning。

 ## 下一步

-1. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
+1. 对 `docs/zh-CN/**` 继续做下一类低风险导航巡检，优先收口 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、
+   `game/ui.md` 与若干 source generator 专题页里剩余的裸路径 README 入口。
+2. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
   常见分支阈值场景。
-2. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内
-   的 HTML entity、站点内链接和标题锚点是否仍与当前页面结构一致。
 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,40 +2,37 @@

 ## 2026-04-23

-### 当前恢复点：RP-021
+### 当前恢复点：RP-022

 - 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。
- 本轮目标定义为“为 `$gframework-batch-boot` 补齐数字速记 stop condition 语义，并消除分支 diff 阈值的歧义”。
+- 本轮目标定义为“在不扩张语义范围的前提下，收口 docs landing / API 导航页中的裸路径仓库入口”。
 - 本轮执行的修复：
-  - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 增加 `Shorthand Stop-Condition Syntax`
-  - 明确 `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止”
-  - 明确 `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止”
-  - 明确 `75 | 2000` 只作为可理解的 OR 输入保留，推荐统一归一化为无 `|` 版本
-  - 为 `.agents/skills/README.md` 同步补充公开入口示例与速记说明
- 本轮执行的修复：
-  - 同步更新 active tracking / trace，记录该 skill 语义收口和新的恢复点
+  - 将 `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，记录新的治理切片与恢复点

-### 当前决策（RP-021）
+### 当前决策（RP-022）

- 对 `$gframework-batch-boot` 的纯数字速记，默认第一位数字绑定“文件数阈值”，第二位数字绑定“行数阈值”。
- 对 `$gframework-batch-boot` 的纯数字速记，默认比较口径固定为“当前分支全部提交相对远程 `origin/main` 的累计 diff”。
- 多个数字阈值的默认逻辑为 OR，而不是 AND；否则不符合“任一 reviewability 阈值接近上限就停”的批处理目标。
- 为避免 shell 语义干扰，文档与后续回复中应优先使用无 `|` 的规范写法，即 `$gframework-batch-boot 75 2000`。
+- 继续使用 `origin/main` 作为 `$gframework-batch-boot 75` 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。
+- 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。
+- 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。
+- 当 docs 页需要跳转到 `docs/` 外部的 README 时，使用 GitHub `main` 分支 blob 外链，而不是跨出 `docs/` 根目录的相对路径。

-### 当前验证（RP-021）
+### 当前验证（RP-022）

- skill 文档巡检：
-  - `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md`
-  - `sed -n '1,220p' .agents/skills/README.md`
-  - 结果：确认原文缺少数字速记与 OR 语义定义，现已补齐。
+- 导航热点巡检：
+  - `rg -n '`GFramework\\.[^`]+/README\\.md`|`docs/zh-CN/[^`]+\\.md`|仓库根 `README\\.md`' docs/zh-CN -g '*.md'`
+  - 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。
 - 构建校验：
  - `bun run build`（工作目录：`docs/`）
-  - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
+  - 结果：通过；将仓库 README 跳转改为 GitHub `main` blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。

-### 归档摘要（RP-020）
+### 归档摘要（RP-021）

- 对 `README.md`、模块 README 与 `docs/zh-CN` 做 HTML entity 泛型热点清理。
- 修复 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 中剩余的 8 处写法。
+- 为 `.agents/skills/gframework-batch-boot/SKILL.md` 与 `.agents/skills/README.md` 补齐数字速记 stop condition 语义。
+- 明确 `$gframework-batch-boot 75` / `75 2000` 默认绑定 `origin/main` 累计 diff 口径。
 - `docs/` 站点构建通过。

 ### 归档指针
@ -47,4 +44,5 @@
 ### 下一步

 1. 提交并推送本地修正后，再次抓取 PR `#272`，确认 Greptile open thread 是否已在新 head commit 上消失。
-2. 若继续执行文档治理批处理，优先排查下一类低风险渲染 / 链接热点，而不是扩成跨模块大波次。
+2. 若继续执行文档治理批处理，优先排查 `core/cqrs.md`、`ecs/arch.md`、`game/scene.md`、`game/ui.md`
+   与 source generator 专题页中剩余的裸路径 README 入口，而不是扩成跨模块大波次。
--- a/docs/zh-CN/abstractions/core-abstractions.md
+++ b/docs/zh-CN/abstractions/core-abstractions.md
@ -99,6 +99,6 @@ public sealed class DiagnosticsFeature
 1. 先读本页，确认你是否真的只需要契约层
 2. 再看 [`../core/index.md`](../core/index.md) 了解默认运行时怎么组织这些契约
 3. 回到模块 README：
-   - `GFramework.Core.Abstractions/README.md`
-   - `GFramework.Core/README.md`
+   - [`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)
 4. 需要统一导航时，再看 [`../api-reference/index.md`](../api-reference/index.md)
--- a/docs/zh-CN/abstractions/game-abstractions.md
+++ b/docs/zh-CN/abstractions/game-abstractions.md
@ -118,5 +118,5 @@ public sealed class ContinueGameCommandHandler
   - [`../game/scene.md`](../game/scene.md)
   - [`../game/ui.md`](../game/ui.md)
 4. 需要仓库侧入口时，回到：
-   - `GFramework.Game.Abstractions/README.md`
-   - `GFramework.Game/README.md`
+   - [`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)
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -21,7 +21,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题
 先读模块 README，再读对应 landing page：

 - 入门入口：[`../getting-started/index.md`](../getting-started/index.md)
- 根模块地图：仓库根 `README.md`
+- 根模块地图：仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)

 ### 想确认“这个功能属于哪个模块”

@ -29,11 +29,11 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

 | 模块族 | 模块 README | 站内入口 | XML 文档关注点 |
 | --- | --- | --- | --- |
-| `Core` / `Core.Abstractions` | `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` | [`../core/index.md`](../core/index.md)、[`../abstractions/core-abstractions.md`](../abstractions/core-abstractions.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 |
-| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `GFramework.Cqrs/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` | [`../core/cqrs.md`](../core/cqrs.md)、[`../source-generators/cqrs-handler-registry-generator.md`](../source-generators/cqrs-handler-registry-generator.md) | request / notification / handler / pipeline / registry / fallback contract |
-| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md` | [`../game/index.md`](../game/index.md)、[`../abstractions/game-abstractions.md`](../abstractions/game-abstractions.md) | 配置、数据、设置、场景、UI、存储、序列化契约 |
-| `Godot` / `Godot.SourceGenerators` | `GFramework.Godot/README.md`、`GFramework.Godot.SourceGenerators/README.md` | [`../godot/index.md`](../godot/index.md)、[`../source-generators/godot-project-generator.md`](../source-generators/godot-project-generator.md)、[`../source-generators/get-node-generator.md`](../source-generators/get-node-generator.md)、[`../source-generators/bind-node-signal-generator.md`](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 |
-| `Ecs.Arch` / `Ecs.Arch.Abstractions` | `GFramework.Ecs.Arch/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` | [`../ecs/index.md`](../ecs/index.md)、[`../ecs/arch.md`](../ecs/arch.md)、[`../abstractions/ecs-arch-abstractions.md`](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 |
+| `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 模块契约、系统适配、配置对象和运行时装配边界 |

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

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

 ## 对应模块入口

- `GFramework.Core/README.md`
- `GFramework.Core.Abstractions/README.md`
- `docs/zh-CN/api-reference/index.md`
- 仓库根 `README.md`
+- [`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)
+- 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.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`
- `GFramework.Game.Abstractions/README.md`
- 仓库根 `README.md`
+- [`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)
+- 仓库根 [`README.md`](https://github.com/GeWuYou/GFramework/blob/main/README.md)
--- a/docs/zh-CN/getting-started/index.md
+++ b/docs/zh-CN/getting-started/index.md
@ -46,7 +46,7 @@
 对应文档：

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

 ### 想做游戏运行时

@ -65,7 +65,7 @@
 对应文档：

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

 ### 想接入 Godot

@ -76,7 +76,7 @@
 对应文档：

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

 ## Source Generators 什么时候装

--- 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`
- `GFramework.Game.SourceGenerators/README.md`
- `GFramework.Cqrs.SourceGenerators/README.md`
- `GFramework.Godot.SourceGenerators/README.md`
+- [`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)