From 0722ba6dbd891927ca8f7a450bf430fe4688cc60 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Mon, 27 Apr 2026 17:28:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(batch-boot):=20=E6=94=B6=E5=8F=A3=E5=85=AC?= =?UTF-8?q?=E5=BC=80=E5=85=A5=E5=8F=A3=E9=A1=B5=E6=96=87=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 source-generators、game、api-reference 与 abstractions 入口页的 reader-facing 标题和导航口吻 - 优化 godot setting 页的继续阅读标题，移除文件名式与指挥式表述 - 补充 documentation full coverage active topic 的 RP-045 跟踪与验证记录 --- ...ation-full-coverage-governance-tracking.md | 25 ++++++++++++++----- ...entation-full-coverage-governance-trace.md | 25 +++++++++++++++++++ docs/zh-CN/abstractions/index.md | 4 +-- docs/zh-CN/api-reference/index.md | 6 ++--- docs/zh-CN/game/index.md | 2 +- docs/zh-CN/godot/setting.md | 4 +-- docs/zh-CN/source-generators/index.md | 2 +- 7 files changed, 53 insertions(+), 15 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 98d03748..cdbd3255 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,13 +12,13 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-044` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-045` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 继续以最新 `origin/main`（`617e0bf`，`2026-04-26 12:17:15 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files -- 本轮从 `$gframework-pr-review` 重新抓取当前 PR `#296`，确认 latest reviewed commit 为 `5778782df05e22dd24dc95189dd768458afb8537`，剩余 open thread 都落在 reader-facing 文案与 README 导航收口上 -- 当前工作树相对 `origin/main` 的 tracked diff 仍接近 `50` files；因此本轮只接受 latest-head review 中仍成立的 4 条低风险修正，不再扩新栏目或新专题页 -- 已确认 `Title check` 的 inconclusive 仅是 GitHub PR 标题元数据提示，不属于仓库文件内可修复范围；本轮只处理本地仍成立的文档线程 + - 继续以最新 `origin/main`（`7cfdd2c`，`2026-04-27 16:59:57 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files +- 本轮通过 `$gframework-batch-boot 50` 重新进入后确认 `HEAD == origin/main`，当前已提交 branch diff 为 `0` files / `0` lines，因此可以从新的低风险文档批次重新累计阈值 +- 当前已完成第 1 个低风险批次：统一 `source-generators`、`game`、`api-reference`、`godot/setting`、`abstractions` 五个入口页的 reader-facing 标题与导航口吻 +- 当前建议继续第 2 个批次，优先收口仍残留在公开文档里的 `ai-libs/CoreGrid` / `旧文档` 指向式表述，保持同样的低风险文字级修正边界 ## 当前状态摘要 @@ -35,6 +35,7 @@ - `2026-04-27` `GFramework.Core.Abstractions/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` 当前都已把 XML 阅读入口改写为“代表类型 + 阅读重点”，不再暴露覆盖计数、日期或 `已覆盖` 这类治理字段。 - `2026-04-27` `docs/zh-CN/game/config-system.md` 与 `docs/zh-CN/tutorials/basic/index.md` 已把维护者 / 指挥式措辞改成中性的采用建议与阅读入口，避免公开页面继续暴露内部决策口吻。 - `2026-04-27` `docs/zh-CN/getting-started/index.md`、`core/index.md`、`game/index.md`、`api-reference/index.md`、`source-generators/index.md` 已统一收敛为“适用场景 / 起步路线 / 继续阅读”式 reader-facing 入口，不再把 GitHub blob README 或治理说明当作主导航。 +- `2026-04-27` 新一轮 batch boot 第 1 批次已进一步收口 `docs/zh-CN/source-generators/index.md`、`game/index.md`、`api-reference/index.md`、`godot/setting.md`、`abstractions/index.md` 的标题与导航口吻，去掉 `family`、自我指涉标题、原始 `README.md` 文件名提示和“先理解…”式栏目标题。 - `2026-04-27` `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Godot/README.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.Ecs.Arch/README.md` 已收口 `ai-libs`、`family`、`seam`、`ReadMe.md` 等内部化或文件名式表述。 - `2026-04-27` `docs/zh-CN` 当前已清空所有指向 `github.com/GeWuYou/GFramework/blob/main/.../README.md` 的公开外链，相关入口统一回到站内栏目页、专题页或 API 导航。 - `2026-04-27` `docs/zh-CN/tutorials/godot-integration.md`、`game/setting.md`、`game/serialization.md`、`godot/index.md`、`godot/architecture.md`、`godot/storage.md`、`godot/logging.md`、`godot/setting.md`、`godot/extensions.md`、`core/architecture.md` 已把 `旧文档` / `ai-libs` / `.Wait()` / `family` 这类维护与内部语气改写成当前采用说明。 @@ -58,7 +59,7 @@ `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 - `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。 -- PR `#296` 当前 review 线程仍主要来自 CodeRabbit 与 Greptile，对 reader-facing 文案和文档入口连通性要求较细；本轮提交后仍需重新抓取 latest-head review，确认 open thread 是否已自动关闭。 +- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；若继续多批次推进，应优先挑选仍未触及的公开文档文案收口点，避免在同一轮里重新引入大范围导航改造。 ## 归档指针 @@ -75,6 +76,18 @@ ## 最新验证 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` + - 结果：通过；`source-generators` 入口页标题收口后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` + - 结果：通过；`Game` 入口页描述调整后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` + - 结果：通过；API 导航页 reader-facing 标题调整后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` + - 结果：通过；Godot 设置页继续阅读标题收口后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` + - 结果：通过；抽象层入口页去文件名式提示后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 batch boot 第 1 批次的 5 个入口页 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md GFramework.Game/README.md` - 结果：通过；本轮 2 个 README 的 reader-facing 表格与导航去重调整后链接目标有效。 - `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.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 9fc8866b..05295c48 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,6 +2,31 @@ ## 2026-04-27 +### 当前恢复点：RP-045 + +- 本轮通过 `$gframework-batch-boot 50` 重新进入，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并按技能要求把 baseline 固定到最新本地 `origin/main` `7cfdd2c`（`2026-04-27 16:59:57 +08:00`）。 +- 重新计算 branch diff 后确认当前已提交范围相对 `origin/main` 为 `0` files / `0` lines；原因是本分支先前工作已经并入 `origin/main`，因此这一轮 batch boot 需要从零 diff 状态重新累计 stop condition。 +- 结合公开文档搜索结果，本轮先挑一组最稳的 reader-facing 入口页收口：`docs/zh-CN/source-generators/index.md`、`game/index.md`、`api-reference/index.md`、`godot/setting.md`、`abstractions/index.md`。 + +### 当前决策（RP-045） + +- 第 1 批次只处理标题、描述和导航措辞，不改示例代码、不扩栏目结构，确保本轮重新起步时的风险保持最低。 +- 由于 branch-size stop condition 只统计已提交 diff，本轮应在每个稳定批次校验通过后尽快提交，再决定是否继续下一批。 +- 当前下一候选批次是清理公开文档里残留的 `ai-libs/CoreGrid` / `旧文档` 指向式表述，继续保持单页文案级修正边界。 + +### 当前验证（RP-045） + +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` + - 结果：通过；本轮 5 个 reader-facing 入口页的 frontmatter、链接与代码块校验均通过。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 batch boot 第 1 批次的 5 个入口页 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 + ### 当前恢复点：RP-044 - 本轮从 `$gframework-pr-review` 重新进入，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并通过 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` 抓取当前 PR `#296`。 diff --git a/docs/zh-CN/abstractions/index.md b/docs/zh-CN/abstractions/index.md index b6acd585..4fd54fda 100644 --- a/docs/zh-CN/abstractions/index.md +++ b/docs/zh-CN/abstractions/index.md @@ -21,9 +21,9 @@ description: GFramework 各抽象层模块的阅读入口与使用边界。 ## 使用建议 -- 如果你只是想直接使用框架功能，优先从对应运行时模块的 `README.md` 和栏目页开始。 +- 如果你只是想直接使用框架功能，优先从对应运行时模块说明和栏目页开始。 - 只有在明确需要“契约层而非实现层”时，才单独依赖 `*.Abstractions` 包。 -- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块 README 与 `getting-started` 为主。 +- 抽象层页面会解释接口分组与职责；实际安装与接入路径，仍应以运行时模块说明和 `getting-started` 为主。 ## 当前边界 diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index d909c9aa..e6fac1dc 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -5,7 +5,7 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 # API 参考 -这页不是签名索引，而是“先看哪个模块入口、再回哪里读 XML 文档”的导航页。 +本页聚焦“先看哪个模块入口、再回哪里读 XML 文档”的 API 阅读导航。 最常见的阅读顺序是： @@ -15,14 +15,14 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 ## 阅读顺序 -### 想确认“该装哪个包、先看哪类 API” +### 安装与选包入口 先读站内入口页： - 入门入口：[入门指南](../getting-started/index.md) - 安装与选包：[安装配置](../getting-started/installation.md) -### 想确认“这个功能属于哪个模块” +### 模块定位入口 按下面的模块映射进入对应入口： diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index 69e2d66c..a66304a6 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -1,6 +1,6 @@ --- title: Game 模块 -description: GFramework.Game family 的运行时入口、采用顺序与源码阅读导航。 +description: GFramework.Game 运行时模块的入口、采用顺序与源码阅读导航。 --- # Game 模块 diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md index 081fd71a..3211f2fa 100644 --- a/docs/zh-CN/godot/setting.md +++ b/docs/zh-CN/godot/setting.md @@ -133,12 +133,12 @@ await settingsSystem.Apply(); ## 什么时候应该改看别的入口 -### 先理解设置模型和仓库 +### 相关设置模型 如果你想先理解 `ISettingsData`、`IResetApplyAbleSettings`、`SettingsModel`、`SettingsSystem` 与设置迁移，先看 [Game 设置系统](../game/setting.md)。 -### 先理解设置如何被持久化 +### 相关持久化入口 如果你关注的是统一设置文件、备份、数据位置和底层存储实现，应该回到： diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 6397fba5..345cc05f 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -70,7 +70,7 @@ GFramework 当前发布的生成器包是： - 再根据 attribute 或 diagnostics 回到对应专题页 - 只有在排查生成失败原因时，才继续下钻到这些共享支撑目录 -## 这个栏目怎么读 +## 阅读路线 ### Core 侧通用生成器