docs(api-reference): 统一文档入口标签写法

- 修复 API 参考页站内入口标签风格不一致的 PR review 问题 - 更新 active tracking 与 trace，记录 PR #287 抓取结果和验证状态 - 补充 docs 构建验证结论，保持当前恢复点与后续动作同步
2026-05-06 16:16:44 +08:00 · 2026-04-25 10:50:38 +08:00 · 2026-04-25 10:50:38 +08:00 · 18bf9f6730
commit 18bf9f6730
parent 8209d7a29f
3 changed files with 37 additions and 23 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,7 +12,7 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-032`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-033`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
  - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理；当前 baseline 已回到 `origin/main`，本批只继续处理新的低风险 reader-facing 缺口
@ -22,11 +22,15 @@
  - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性
  - 将新的 reader-facing 文档约束同步收口到 `AGENTS.md` 与 `.agents/skills/gframework-doc-refresh/`
  - 保持 active tracking / trace 只承载当前恢复入口，把阶段细节留在 `archive/`
+  - 跟进当前 PR `#287` 的 latest-head review，只收口本地复核后仍成立的文档入口标签一致性问题

 ## 当前状态摘要

 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
 - `2026-04-25` 当前本地 `docs/sdk-update-documentation` 与 `origin/main` 的 committed branch diff 仍为 `0 / 75` 个 changed files；本轮待提交批次已触及 `38` 个文件，落地后仍处于 `$gframework-batch-boot 75` 的安全区间。
+- `2026-04-25` 使用 `$gframework-pr-review` 重新抓取当前 PR `#287` 后，确认 latest head commit
+  `8209d7a29f35d969fca6258b9817da9b33a203a3` 仅剩 `1` 条 Greptile open thread；本轮继续收口
+  `docs/zh-CN/api-reference/index.md` 中站内入口列的链接标签风格不一致问题，并顺手把同页仍直接显示路径的站内入口改为语义化标签。
 - `2026-04-24` 使用 `$gframework-pr-review` 抓取当前 PR `#284` 后，确认 latest head commit
  `77540c07f0890cc05b10a849722c87b8bed8f561` 仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；本轮仅继续收口本地复核后仍成立的 reader-facing 文档入口与 active tracking 精简问题。
 - 本轮 PR follow-up 仅收口仍然成立的 review 项：
@ -95,16 +99,20 @@
  - 结果：通过；根 `README.md` reader-friendly 链接标签修正与 `docs/zh-CN` 多页标题本地化落地后站点仍可正常构建，仅保留既有大 chunk warning。
 - `2026-04-25` `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
  - 结果：通过；技能仍能正常解析 `Core` 模块证据面，说明新增的 reader-facing 输出约束未破坏模块扫描主流程。
+- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json`
+  - 结果：通过；PR `#287` 处于 `OPEN`，latest head commit `8209d7a29f35d969fca6258b9817da9b33a203a3` 仅剩
+    `1` 条 Greptile open thread，无 failed checks，测试汇总为 `2156 passed`。
+- `2026-04-25` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；`docs/zh-CN/api-reference/index.md` 的站内入口标签统一为语义化写法后站点仍可正常构建，仅保留既有大 chunk warning。
 - `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
  - 结果：通过；本轮触达页面的 frontmatter、链接与代码块校验均通过，脚本仅继续报告仓库中既有页面的“代码块缺少语言标记”警告。
- `2026-04-25` `bun run build`（工作目录：`docs/`）
-  - 结果：通过；公开文档口吻治理、链接标签收口和规则更新后站点仍可正常构建，仅保留既有大 chunk warning。

 ## 下一步

-1. 当前基线已回到 `origin/main`，本轮待提交批次落地后仍会处于 `$gframework-batch-boot 75` 的安全区间；后续若继续治理，优先保持 `5` 到 `10` 个文件以内的小批次。
-2. 若继续处理 reader-facing 文档问题，优先筛查剩余页面里的维护者视角限制说明、模块 README 中仍可能存在的裸路径标签，以及验证脚本提示的代码块语言标记缺口。
-3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
+1. 提交并推送当前 PR follow-up 后，优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否已清空 open thread。
+2. 当前基线已回到 `origin/main`，本轮待提交批次落地后仍会处于 `$gframework-batch-boot 75` 的安全区间；后续若继续治理，优先保持 `5` 到 `10` 个文件以内的小批次。
+3. 若继续处理 reader-facing 文档问题，优先筛查剩余页面里的维护者视角限制说明、模块 README 中仍可能存在的裸路径标签，以及验证脚本提示的代码块语言标记缺口。
+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` 与相关专题页是否仍保持一致。
--- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
+++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
@ -2,32 +2,38 @@

 ## 2026-04-25

-### 当前恢复点：RP-032
+### 当前恢复点：RP-033

 - 当前批次聚焦 reader-facing 文档口吻治理，目标是清理公开页面中的反问式标题、维护者视角边界说明、产品评审式表述和裸文件名链接标签。
 - 以 `origin/main`（`9964962`，`2026-04-24 23:05:53 +0800`）为 `$gframework-batch-boot 75` baseline；当前 committed branch diff 仍为 `0 / 75`，本轮待提交 write set 在写回 active tracking / trace 前为 `36` 个文件。
 - 本批次同时把同类约束补进 `AGENTS.md`、`gframework-doc-refresh/SKILL.md` 和 `module-landing` 模板，避免后续刷新再次写回 AI 式公开文案。
+- 使用 `$gframework-pr-review` 重新抓取当前 PR `#287` 后，latest head commit `8209d7a29f35d969fca6258b9817da9b33a203a3` 仅剩
+  `1` 条 Greptile open thread，定位到 `docs/zh-CN/api-reference/index.md` 的站内入口表格链接标签风格不一致。

-### 当前决策（RP-032）
+### 当前决策（RP-033）

 - 公开文档允许说明采用边界、限制和迁移关系，但必须改写成读者采用 guidance，不能继续使用“当前阶段结论”“不建议立即启动”这类维护者记录口吻。
 - 公开文档中的链接标签必须直接说明目的地语义，不再使用 `README.md`、`game/index.md`、`../core/cqrs.md` 这类文件名或路径作为可见导航文字。
 - 文档治理规则不能只靠本轮改文案；必须同步更新 `AGENTS.md` 与 `gframework-doc-refresh` 的输出约束，让后续批次默认遵守同一套 reader-facing 标准。
+- 对 latest-head review 中仍成立的单点问题，优先做最小范围修复，但若同页存在同类 reader-facing 标签缺陷，则允许一并收口，避免 PR 反复产生同类文案评论。

-### 当前验证（RP-032）
+### 当前验证（RP-033）

 - 热点扫描：
  - `rg -n '你真正会用到的公开入口|先理解包关系|这个栏目应该回答什么|什么时候看别的页面|当前阶段的结论|当前不单独启动桌面版的原因|## 边界说明|\\[[^\\]]+\\.md\\]\\([^)]*\\.md\\)|GFramework\\.[A-Za-z.]+ README|对应模块目录下的 \`README\\.md\`' docs/zh-CN README.md GFramework.*/README.md`
  - 结果：通过；当前公开文档已无上述目标模式命中。
+- PR review 抓取：
+  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json`
+  - 结果：通过；PR `#287` 处于 `OPEN`，无 failed checks，tests `2156 passed`，latest head review 仅剩 `1` 条 Greptile open thread。
+- 构建验证：
+  - `bun run build`（工作目录：`docs/`）
+  - 结果：通过；`docs/zh-CN/api-reference/index.md` 的站内入口标签统一为语义化写法后站点仍可构建，仅保留既有大 chunk warning。
 - 技能自检：
  - `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
  - 结果：通过；`Core` 模块扫描链路正常，新增输出约束未破坏 skill 主流程。
 - 规则校验：
  - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN`
  - 结果：通过；本轮触达页面的 frontmatter、链接与代码块校验均通过，脚本仅继续报告仓库中既有页面的“代码块缺少语言标记”警告。
- 构建验证：
-  - `bun run build`（工作目录：`docs/`）
-  - 结果：通过；公开文档口吻治理、规则更新和链接标签收口后站点仍可构建，仅保留既有大 chunk warning。

 ### 归档指针

@ -39,5 +45,5 @@

 ### 下一步

-1. 提交当前批次，保留公开文档 reader-facing 口吻治理、规则补强和 `ai-plan` 恢复点同步更新。
+1. 提交并推送当前 PR follow-up 后，重新抓取 `$gframework-pr-review`，确认 PR `#287` 的 latest-head review 是否清空 open thread。
 2. 若继续下一轮 `$gframework-batch-boot 75`，优先清理验证脚本持续提示的代码块语言标记缺口，或继续扫描剩余公开页中的维护者口吻尾项。
--- a/docs/zh-CN/api-reference/index.md
+++ b/docs/zh-CN/api-reference/index.md
@ -20,7 +20,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

 先读模块 README，再读对应栏目入口页：

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

 ### 想确认“这个功能属于哪个模块”
@ -29,11 +29,11 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题

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

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

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

 优先入口：

- 教程概览：[`../tutorials/index.md`](../tutorials/index.md)
- 最佳实践：[`../best-practices/index.md`](../best-practices/index.md)
- 故障排查：[`../troubleshooting.md`](../troubleshooting.md)
+- 教程概览：[教程总览](../tutorials/index.md)
+- 最佳实践：[最佳实践](../best-practices/index.md)
+- 故障排查：[故障排查](../troubleshooting.md)

 ## 当前边界