docs(zh-cn): 补齐首页与基础教程元数据

- 补充 zh-CN 首页与基础教程章节页的 frontmatter title 与 description - 更新文档治理 topic 的恢复点、批次指标与下一步
2026-05-08 01:24:31 +08:00 · 2026-04-24 13:00:09 +08:00 · 2026-04-24 13:00:09 +08:00 · bf37104c68
commit bf37104c68
parent a8447a68a4
10 changed files with 44 additions and 28 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,12 +12,12 @@

 ## 当前恢复点

- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-026`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-027`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
-  - 收口 PR `#282` 的 latest-head review follow-up，保持 active tracking / trace 只承载当前恢复入口
+  - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 的 metadata 缺口
  - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明
-  - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题
+  - 继续优先处理低风险 metadata 缺口、坏链与 Markdown 结构问题，避免跨模块语义改写
  - 保持 `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/`
@ -25,12 +25,14 @@
 ## 当前状态摘要

 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
+- `2026-04-24` 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 batch baseline 时，当前分支累计 diff 为 `0` 个文件；本批 write set 聚焦 `8` 个文档页面与 `2` 个 `ai-plan` 入口文件，预计提交后分支 diff 为 `10 / 75` 个 changed files。
 - `2026-04-24` 使用 `$gframework-pr-review` 抓取 PR `#282` 后，确认 latest head commit
  `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread；4 条建议均已在本地复核并纳入当前恢复点。
 - 本轮 PR follow-up 仅收口仍然成立的 review 项：
  - 将过长的 active tracking / trace 瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入 `archive/`
  - 将 `docs/zh-CN/core/context.md` 的标题本地化为中文读者友好的写法
  - 统一 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 的 `.md` 链接写法
+- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`，让首页和基础教程章节页拥有完整 frontmatter metadata。
 - `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`、
@ -68,12 +70,15 @@
  - 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。
 - `2026-04-24` `bun run build`（工作目录：`docs/`）
  - 结果：通过；文档标题本地化、站内链接修正与 `ai-plan` 归档瘦身落地后站点仍可正常构建，仅保留既有大 chunk warning。
+- `2026-04-24` `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` frontmatter 是否缺 `title` / `description`）
+  - 结果：通过；当前带 frontmatter 的 `docs/zh-CN` 页面已无 `title` / `description` 缺口。
+- `2026-04-24` `bun run build`（工作目录：`docs/`）
+  - 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。

 ## 下一步

-1. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8`
-   个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
-2. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
+1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
+2. 若继续执行 `$gframework-batch-boot 75`，优先盘点 `docs/zh-CN` 中仍缺完整 frontmatter 的页面，并按模块或教程小批次补齐 metadata。
 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,32 +2,28 @@

 ## 2026-04-24

-### 当前恢复点：RP-026
+### 当前恢复点：RP-027

- 使用 `$gframework-pr-review` 抓取 PR `#282`，确认 latest head commit
-  `982249151ecf8acdff3e62e664034bf95dfacd75` 当前仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread。
- 按“只处理 latest-head unresolved threads 中仍成立的问题”的原则，本轮仅收口 4 条本地可复现的 follow-up：
-  - 将 `tracking.md` 与 `trace.md` 的活动入口瘦身，并把 `RP-023` 到 `RP-025` 的细节迁入新 archive 文件
-  - 将 `docs/zh-CN/core/context.md` 的标题与主标题本地化为 `上下文（Context）`
-  - 将 `docs/zh-CN/troubleshooting.md` 中 `/zh-CN/core/architecture` 与 `/zh-CN/faq` 统一补成显式 `.md` 链接
+- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，确认批次开始时当前分支累计 diff 为 `0` 个文件。
+- 选择“frontmatter metadata 缺口”作为本批次低风险切片，不继续扩大到正文语义改写或跨模块文档重写。
+- 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`。

-### 当前决策（RP-026）
+### 当前决策（RP-027）

- PR review follow-up 继续遵守“先本地验证，再决定是否修复”；对已经过时或无法在当前分支复现的评论不做追随式修改。
- active `ai-plan` 入口只保留当前恢复点、活动事实、风险、最新验证与下一步；批次细节统一迁入 `archive/`。
- `docs/zh-CN` 页面应优先使用中文标题；同一帮助块中的绝对站内链接应保持一致的显式 `.md` 写法。
+- 当 branch diff 明显低于 `75` 文件阈值时，优先消化低风险 metadata / 链接 / Markdown 结构缺口，避免在同一批次混入高语义成本的文案重写。
+- active `ai-plan` 入口继续保持轻量，只记录当前恢复点、batch metric、验证结果与下一批候选项。
+- 当前 WSL 会话继续使用显式 `--git-dir` / `--work-tree` 绑定执行 Git，避免 `git.exe` 失效带来的路径问题。

-### 当前验证（RP-026）
+### 当前验证（RP-027）

- PR review 抓取：
-  - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json`
-  - 结果：通过；PR `#282` 处于 `OPEN`，最新 review 线程与测试状态已成功解析，测试汇总为 `2156 passed`。
- 链接巡检：
-  - `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?<!\\.md)\\)' docs/zh-CN/troubleshooting.md`
-  - 结果：当前无命中；`/zh-CN/core/architecture` 与 `/zh-CN/faq` 已统一补成显式 `.md` 链接。
+- frontmatter 巡检：
+  - `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` frontmatter 是否缺 `title` / `description`）
+  - 结果：通过；当前带 frontmatter 的 `docs/zh-CN` 页面已无 `title` / `description` 缺口。
 - 站点构建：
  - `bun run build`（工作目录：`docs/`）
-  - 结果：通过；本轮文档与 `ai-plan` 调整后站点仍可正常构建，仅保留既有大 chunk warning。
+  - 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。
+- 当前 stop-condition metric：
+  - 提交前工作树 write set 为 `10` 个文件（`8` 个文档页面 + `2` 个 `ai-plan` 入口）；本批次提交后分支 diff 将提升为 `10 / 75` 个 changed files。

 ### 归档指针

@ -39,5 +35,5 @@

 ### 下一步

-1. 推送当前 follow-up commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
-2. 若继续执行 `$gframework-batch-boot 75`，优先处理 `docs/zh-CN/index.md` 与 `tutorials/basic/01-07.md` 这 `8` 个“已有 frontmatter 但缺 `title` / `description`”的 metadata 缺口。
+1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#282` 的 unresolved review threads 是否已在新 head commit 上消失。
+2. 若继续执行 `$gframework-batch-boot 75`，优先盘点 `docs/zh-CN` 中仍缺完整 frontmatter 的页面，并按模块或教程小批次补齐 metadata。
--- a/docs/zh-CN/index.md
+++ b/docs/zh-CN/index.md
@ -2,6 +2,7 @@
 # https://vitepress.dev/reference/default-theme-home-page
 layout: home
 title: GFramework
+description: 概览 GFramework 的模块能力、入门路径与主要中文文档入口。
 hero:
  name: "GFramework"
  text: 面向游戏开发的模块化 C# 架构体系
@ -35,4 +36,4 @@ features:

  - title: ⚡ Roslyn 源码生成器
    details: 自动生成日志、枚举扩展与规则代码，减少样板代码并提升开发效率。
---
+---
--- a/docs/zh-CN/tutorials/basic/01-environment.md
+++ b/docs/zh-CN/tutorials/basic/01-environment.md
@ -1,4 +1,6 @@
 ---
+title: 第 1 章：环境准备
+description: 说明开始基础教程前需要准备的操作系统、.NET SDK、Godot 与常用开发工具环境。
 prev:
  text: '教程首页'
  link: './index'
--- a/docs/zh-CN/tutorials/basic/02-project-setup.md
+++ b/docs/zh-CN/tutorials/basic/02-project-setup.md
@ -1,4 +1,6 @@
 ---
+title: 第 2 章：项目创建与初始化
+description: 指导创建 Godot C# 项目、引入 GFramework，并搭好基础目录与初始化结构。
 prev:
  text: '环境准备'
  link: './01-environment'
--- a/docs/zh-CN/tutorials/basic/03-counter-basic.md
+++ b/docs/zh-CN/tutorials/basic/03-counter-basic.md
@ -1,4 +1,6 @@
 ---
+title: 第 3 章：基础计数器实现
+description: 通过直接实现计数器场景与交互逻辑，建立后续架构重构的起点示例。
 prev:
  text: '项目创建与初始化'
  link: './02-project-setup'
--- a/docs/zh-CN/tutorials/basic/04-model-refactor.md
+++ b/docs/zh-CN/tutorials/basic/04-model-refactor.md
@ -1,4 +1,6 @@
 ---
+title: 第 4 章：引入 Model 重构
+description: 使用 Model 层与事件系统重构计数器应用，分离状态存储、事件通知与界面更新。
 prev:
  text: '基础计数器实现'
  link: './03-counter-basic'
--- a/docs/zh-CN/tutorials/basic/05-command-system.md
+++ b/docs/zh-CN/tutorials/basic/05-command-system.md
@ -1,4 +1,6 @@
 ---
+title: 第 5 章：命令系统优化
+description: 通过引入 Command 模式拆分 Controller 交互逻辑，建立更清晰的执行职责边界。
 prev:
  text: '引入 Model 重构'
  link: './04-model-refactor'
--- a/docs/zh-CN/tutorials/basic/06-utility-system.md
+++ b/docs/zh-CN/tutorials/basic/06-utility-system.md
@ -1,4 +1,6 @@
 ---
+title: 第 6 章：Utility 与 System
+description: 引入 Utility 与 System 承载业务规则和阈值检查，完成基础分层架构闭环。
 prev:
  text: '命令系统优化'
  link: './05-command-system'
--- a/docs/zh-CN/tutorials/basic/07-summary.md
+++ b/docs/zh-CN/tutorials/basic/07-summary.md
@ -1,4 +1,6 @@
 ---
+title: 第 7 章：总结与最佳实践
+description: 回顾基础教程的架构演进，整理最佳实践、常见问题与后续学习方向。
 prev:
  text: 'Utility 与 System'
  link: './06-utility-system'