From 0db50107f7c41d2c84365f373d5c5e7cbf4a08b2 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 24 Apr 2026 18:07:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(documentation):=20=E4=BC=98=E5=8C=96?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=85=A5=E5=8F=A3=E6=A0=87=E9=A2=98=E4=B8=8E?= =?UTF-8?q?=E5=AF=BC=E8=88=AA=E6=A0=87=E7=AD=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新根 README 的内部支撑模块入口标签，避免继续暴露路径式链接名 - 优化 docs/zh-CN 多个 landing 与 core 页面标题，提升中文读者的导航可读性 - 同步 documentation-full-coverage-governance 的 tracking 与 trace，记录最新 baseline 和验证结果 --- README.md | 4 +- ...ation-full-coverage-governance-tracking.md | 18 +++++--- ...entation-full-coverage-governance-trace.md | 44 ++++++++++++------- docs/zh-CN/abstractions/core-abstractions.md | 4 +- .../abstractions/ecs-arch-abstractions.md | 4 +- docs/zh-CN/abstractions/game-abstractions.md | 4 +- docs/zh-CN/core/architecture.md | 4 +- docs/zh-CN/core/command.md | 4 +- docs/zh-CN/core/events.md | 4 +- docs/zh-CN/core/index.md | 4 +- docs/zh-CN/core/logging.md | 4 +- docs/zh-CN/core/property.md | 4 +- docs/zh-CN/core/query.md | 4 +- docs/zh-CN/game/index.md | 4 +- docs/zh-CN/source-generators/index.md | 4 +- 15 files changed, 68 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 01cd897b..0f7c0bab 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,8 @@ | 目录 | 定位 | 跟随入口 | | --- | --- | --- | -| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [GFramework.Core.SourceGenerators/README.md](GFramework.Core.SourceGenerators/README.md) | -| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [GFramework.Godot.SourceGenerators/README.md](GFramework.Godot.SourceGenerators/README.md) | +| `GFramework.Core.SourceGenerators.Abstractions` | `Core.SourceGenerators` 的内部契约层 | [Core.SourceGenerators 模块 README](GFramework.Core.SourceGenerators/README.md) | +| `GFramework.Godot.SourceGenerators.Abstractions` | `Godot.SourceGenerators` 的内部契约层 | [Godot.SourceGenerators 模块 README](GFramework.Godot.SourceGenerators/README.md) | | `GFramework.SourceGenerators.Common` | 生成器家族共享的公共支撑代码 | [源码生成器总览](docs/zh-CN/source-generators/index.md) | ## 文档导航 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 3f6c21da..5241c0c4 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,10 +12,10 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-029` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-031` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理，本批已收口模块 `README.md`、`docs/index.md` 与多组中文落地页之间的读者入口对齐 + - 继续按 `$gframework-batch-boot 75` 的 `origin/main` 分支 diff 阈值做小批量文档治理；当前 baseline 已回到 `origin/main`，本批只继续处理新的低风险 reader-facing 缺口 - 保持 `README.md` 与 `docs/**` 公开页面只承载读者需要的采用信息，不再混入 XML inventory、覆盖基线、恢复点或治理批次说明 - 继续优先处理低风险 metadata 缺口、坏链、README 文档入口对齐、Reader-friendly 链接标签与 Markdown 结构问题，避免跨模块语义改写 - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述 @@ -25,13 +25,17 @@ ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-24` 当前分支累计 diff 已接近 `$gframework-batch-boot 75` 的 stop condition（约 `58 / 75` 个 changed files）；后续 follow-up 应继续保持小 write set，只处理仍然成立的 PR review 项。 +- `2026-04-24` 当前本地 `docs/sdk-update-documentation` 与 `origin/main` 同步到 `4c2994e`，相对 `$gframework-batch-boot 75` 的 baseline 当前为 `0 / 75` 个 changed files；后续批次可以继续，但仍应保持小 write set。 - `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 项： - 将过长的 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` 链接写法 +- 本批次将根 `README.md` 中两个仍直接暴露文件路径的内部支撑模块入口改为 reader-friendly 链接标签，避免目录表格继续把路径本身当成入口名称。 +- 本批次继续将 `Core`、`Game`、`Source Generators` 和三篇 `Abstractions` 落地页的纯英文 `title` / H1 改为中文读者友好的入口标题，减少首页与侧边栏扫描成本。 +- 本批次继续将 `core/architecture.md`、`command.md`、`events.md`、`logging.md`、`property.md`、`query.md` 的纯英文 `title` / H1 本地化为中英对照入口标题，保持 Core 子栏目扫描体验一致。 +- 当前批次完成后，纯英文 `title` 扫描只剩 `docs/zh-CN/core/cqrs.md` 的 `CQRS` 与 `docs/zh-CN/index.md` 的 `GFramework`；它们分别属于通用缩写与品牌名，不再作为本轮优先本地化对象。 - 本批次补齐了 `docs/zh-CN/index.md` 的 `description`，以及 `docs/zh-CN/tutorials/basic/01-07.md` 的 `title` / `description`，让首页和基础教程章节页拥有完整 frontmatter metadata。 - 本批次统一将教程、最佳实践、Core、Godot 页面里缺显式扩展名的站内 Markdown 链接补齐为 `.md` 或 `index.md`，避免目录链接、绝对路径旧写法与 VitePress 构建解析分叉。 - 本批次把模块 README、仓库根 README、`docs/index.md` 及多组中文落地页里直接暴露文件路径的入口调整为读者友好的可点击标签，同时补齐语言落地页 metadata 与 README 指向。 @@ -82,11 +86,15 @@ - 结果：通过；`25` 个页面的站内链接补齐为显式 `.md` / `index.md` 后站点仍可正常构建，仅保留既有大 chunk warning。 - `2026-04-24` `bun run build`（工作目录：`docs/`） - 结果：通过；模块 README、中文落地页 reader-facing 文档入口对齐，以及 `docs/index.md` metadata 调整后站点仍可正常构建，仅保留既有大 chunk warning。 +- `2026-04-24` `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` 中纯英文 `title`） + - 结果：通过；经过三轮标题本地化后，仅剩 `CQRS` 与 `GFramework` 两个品牌/缩写型标题。 +- `2026-04-24` `bun run build`（工作目录：`docs/`） + - 结果：通过；根 `README.md` reader-friendly 链接标签修正与 `docs/zh-CN` 多页标题本地化落地后站点仍可正常构建，仅保留既有大 chunk warning。 ## 下一步 -1. 当前分支已接近 `$gframework-batch-boot 75` 的 stop condition；若继续执行后续批次，应优先选择 `5` 到 `10` 个文件以内的小批次，避免显著降低 reviewability。 -2. 推送当前批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#284` 的 unresolved review threads 是否已在新 head commit 上消失。 +1. 当前基线已回到 `origin/main`，本轮变更仍是小 write set；后续若继续执行 `$gframework-batch-boot 75`，仍优先选择 `5` 到 `10` 个文件以内的小批次。 +2. 若继续处理 reader-facing 文档问题，优先筛查剩余 README / landing page 中是否还有路径式链接标签或不必要的内部治理措辞；纯英文标题方面仅剩品牌名与缩写，不再是当前高优先级切片。 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`、 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 2260f067..05f69de0 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,25 +2,39 @@ ## 2026-04-24 -### 当前恢复点：RP-030 +### 当前恢复点：RP-031 -- 当前 follow-up 聚焦 `$gframework-pr-review` 在 PR `#284` 上仍然成立的 review 项，只处理公开 README 的 reader-facing 文案与 active tracking 精简问题。 -- 以 `origin/main`（`a8447a6`，`2026-04-24T12:53:39+08:00`）为 `$gframework-batch-boot 75` baseline，当前分支 cumulative diff 已接近 stop condition，应继续把 write set 控制在小批次范围内。 -- 本批次计划修改 `3` 个 README 与 `2` 个 `ai-plan` 入口文件，避免再次扩张到跨模块文档面。 +- 当前批次聚焦新的低风险 reader-facing README 缺口，只处理根 `README.md` 的路径式链接标签和对应的 active tracking / trace 基线更新。 +- 以 `origin/main`（`4c2994e`，`2026-04-24 17:57:23 +0800`）为 `$gframework-batch-boot 75` baseline；当前本地 `docs/sdk-update-documentation` 与该基线同步，branch cumulative diff 起始值为 `0 / 75`。 +- 本批次随后扩展到 `6` 个中文 landing / abstraction 页面标题本地化，总 write set 仍保持在 reader-facing 文案层。 -### 当前决策（RP-030） +### 当前决策（RP-031） -- 当 branch diff 已接近 `$gframework-batch-boot 75` 的阈值时，PR follow-up 只继续收口最新 head commit 上仍未消失、且能在本地验证成立的 review 线程。 -- 公开 README 不再使用 `inventory` 这类治理语境，也不把贡献指引缩窄到单一入口页；文案应明确“受影响页面”与“接入说明/阅读顺序”。 -- active tracking 需要保留恢复点与风险信息，但不再保留完整 commit SHA、精确时间戳与拆分式文件计数这类过细基线指标。 +- 当当前分支重新与 `origin/main` 对齐后，`$gframework-batch-boot 75` 可以继续推进，但仍只接受低风险、读者可见、易验证的小批次。 +- 公开 README 的表格入口不应继续把文件路径本身暴露成链接标签；入口名称应直接告诉读者要进入哪个模块 README。 +- active tracking / trace 里的 stop-condition 指标必须反映当前真实基线，不再沿用已经过时的 `58 / 75` 历史值。 -### 当前验证（RP-030） +### 当前验证（RP-031） -- PR review 抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#284` 处于 `OPEN`，latest head commit `77540c07f0890cc05b10a849722c87b8bed8f561` 仍有 `3` 条 CodeRabbit 与 `1` 条 Greptile open thread，测试汇总为 `2156 passed`，仅剩 `Title check` 的 inconclusive PR 元数据提示。 +- 基线确认： + - `git --git-dir=/mnt/f/gewuyou/System/Documents/WorkSpace/GameDev/GFramework/.git/worktrees/GFramework-update-documentation --work-tree=/mnt/f/gewuyou/System/Documents/WorkSpace/GameDev/GFramework-WorkTree/GFramework-update-documentation for-each-ref --format='%(refname:short) %(objectname:short) %(committerdate:iso8601)' refs/heads/main refs/remotes/origin/main refs/heads/docs/sdk-update-documentation HEAD` + - 结果：通过；`docs/sdk-update-documentation` 与 `origin/main` 当前同为 `4c2994e`，本地 `main` 仍停留在 `84b40a2`，因此本轮按 skill 规则选择更新的 `origin/main` 作为 baseline。 - 当前 stop-condition metric： - - 分支 cumulative diff 已接近 `58 / 75`；本轮 follow-up 继续限制在 `3` 个 README 与 `2` 个 `ai-plan` 入口文件内。 + - `git ... diff --name-only origin/main...HEAD | wc -l` + - 结果：通过；当前 branch cumulative diff 为 `0 / 75`。 +- 热点扫描： + - `rg -n '\\[[^]]*(?:README\\.md|docs/[^]]+|GFramework\\.[^]]+/README\\.md|/zh-CN/[^]]+)\\]\\((?:README\\.md|docs/[^)]+|GFramework\\.[^)]+/README\\.md|/zh-CN/[^)]+)\\)' README.md docs GFramework.*/README.md` + - 结果：通过；当前仅在根 `README.md` 的内部支撑模块表格中命中 `2` 处路径式链接标签，适合作为本批次 reader-facing 修正切片。 +- 英文标题扫描： + - `python3 - <<'PY' ...`（扫描 `docs/zh-CN/**/*.md` 中纯英文 `title` / H1） + - 结果：通过；当前 landing / abstraction 页仍有一组纯英文入口标题，其中 `core/index.md`、`game/index.md`、`source-generators/index.md` 与 `abstractions/*.md` 的 `title` / H1 适合作为同批次标题本地化切片。 +- 第二轮标题本地化： + - 同一轮扫描显示 `docs/zh-CN/core/architecture.md`、`command.md`、`events.md`、`logging.md`、`property.md`、`query.md` 仍保留纯英文 `title` / H1；这些页面只需做中英对照标题调整，不涉及正文结构或链接变更，适合作为后续同批次切片。 +- 停批判断： + - 再次扫描后，剩余纯英文 `title` 只剩 `docs/zh-CN/core/cqrs.md` 的 `CQRS` 与 `docs/zh-CN/index.md` 的 `GFramework`；它们属于缩写或品牌名，不再作为当前 reader-facing 本地化批次的优先对象。 +- 构建验证： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；根 `README.md` 链接标签修正与 `docs/zh-CN` 标题本地化后站点仍可构建，仅保留既有大 chunk warning。 ### 归档指针 @@ -32,5 +46,5 @@ ### 下一步 -1. 推送本批次 commit 后，再次执行 `$gframework-pr-review`，确认 PR `#284` 的 unresolved review threads 是否已在新 head commit 上消失。 -2. 若继续执行 `$gframework-batch-boot 75`，优先选择 `5` 到 `10` 个文件以内的小批次，例如剩余零散的 README reader-facing 文案修正。 +1. 提交当前批次，保留根 `README.md` 入口标签修正、`docs/zh-CN` 标题本地化和 `ai-plan` 恢复点同步更新。 +2. 若继续下一轮 `$gframework-batch-boot 75`，优先重新扫描剩余 README / landing page 的路径式链接标签和内部治理措辞，而不是继续本地化品牌名或缩写标题。 diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index ca975213..df109bd6 100644 --- a/docs/zh-CN/abstractions/core-abstractions.md +++ b/docs/zh-CN/abstractions/core-abstractions.md @@ -1,9 +1,9 @@ --- -title: Core Abstractions +title: Core 抽象层 description: GFramework.Core.Abstractions 的契约边界、包关系与源码阅读重点。 --- -# Core Abstractions +# Core 抽象层 `GFramework.Core.Abstractions` 是 `Core` 运行时的契约包。 diff --git a/docs/zh-CN/abstractions/ecs-arch-abstractions.md b/docs/zh-CN/abstractions/ecs-arch-abstractions.md index 72067cc6..06c3d4a6 100644 --- a/docs/zh-CN/abstractions/ecs-arch-abstractions.md +++ b/docs/zh-CN/abstractions/ecs-arch-abstractions.md @@ -1,9 +1,9 @@ --- -title: Ecs.Arch Abstractions +title: Ecs.Arch 抽象层 description: GFramework.Ecs.Arch.Abstractions 的契约边界、包关系和最小接入路径。 --- -# Ecs.Arch Abstractions +# Ecs.Arch 抽象层 `GFramework.Ecs.Arch.Abstractions` 是 Arch ECS 集成层的契约包。 diff --git a/docs/zh-CN/abstractions/game-abstractions.md b/docs/zh-CN/abstractions/game-abstractions.md index 70fdb703..d112e91b 100644 --- a/docs/zh-CN/abstractions/game-abstractions.md +++ b/docs/zh-CN/abstractions/game-abstractions.md @@ -1,9 +1,9 @@ --- -title: Game Abstractions +title: Game 抽象层 description: GFramework.Game.Abstractions 的契约边界、包关系与源码阅读重点。 --- -# Game Abstractions +# Game 抽象层 `GFramework.Game.Abstractions` 是 `Game` 运行时的契约包。 diff --git a/docs/zh-CN/core/architecture.md b/docs/zh-CN/core/architecture.md index 0fcfbcce..3dd72942 100644 --- a/docs/zh-CN/core/architecture.md +++ b/docs/zh-CN/core/architecture.md @@ -1,9 +1,9 @@ --- -title: Architecture +title: 架构（Architecture） description: 说明 GFramework.Core 的 Architecture 入口、生命周期职责与最常用注册 API。 --- -# Architecture +# 架构（Architecture） `Architecture` 是 `GFramework.Core` 的运行时入口。它负责三件事： diff --git a/docs/zh-CN/core/command.md b/docs/zh-CN/core/command.md index 057576cf..59624d4a 100644 --- a/docs/zh-CN/core/command.md +++ b/docs/zh-CN/core/command.md @@ -1,9 +1,9 @@ --- -title: Command +title: 命令（Command） description: 说明 GFramework.Core.Command 旧命令体系的兼容定位、可用基类与当前使用约束。 --- -# Command +# 命令（Command） 本页只说明 `GFramework.Core.Command` 里的旧命令体系。 diff --git a/docs/zh-CN/core/events.md b/docs/zh-CN/core/events.md index 19840c37..0a32559d 100644 --- a/docs/zh-CN/core/events.md +++ b/docs/zh-CN/core/events.md @@ -1,9 +1,9 @@ --- -title: Events +title: 事件（Events） description: 说明 GFramework.Core.Events 的轻量广播模型、安装方式与常用事件入口。 --- -# Events +# 事件（Events） `GFramework.Core.Events` 是架构内的轻量广播层。它适合表达“某件事已经发生”的运行时信号、模块间松耦合通知， 以及为旧模块保留 `EventBus` 语义；如果你需要请求/响应、pipeline behavior 或 handler registry，优先使用 diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index 51020925..d3a570f8 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -1,9 +1,9 @@ --- -title: Core +title: Core 模块 description: GFramework.Core 与 GFramework.Core.Abstractions 的运行时入口、采用顺序和源码阅读导航。 --- -# Core +# Core 模块 `Core` 栏目对应 `GFramework` 的基础运行时层，主要覆盖 `GFramework.Core` 与 `GFramework.Core.Abstractions`，以及与之直接相邻的旧版 `Command` / `Query` 执行器和新版 `CQRS` 迁移入口。 diff --git a/docs/zh-CN/core/logging.md b/docs/zh-CN/core/logging.md index 719301f0..0b46635c 100644 --- a/docs/zh-CN/core/logging.md +++ b/docs/zh-CN/core/logging.md @@ -1,9 +1,9 @@ --- -title: Logging +title: 日志（Logging） description: 说明 GFramework.Core.Logging 的日志接口、组合方式与常见使用入口。 --- -# Logging +# 日志（Logging） `GFramework.Core.Logging` 是 Core runtime 的默认日志实现。只加载抽象层时，`LoggerFactoryResolver` 会退回 silent provider；加载 `GFramework.Core` 或在 `ArchitectureConfiguration` 里显式提供 provider 后，日志才会 diff --git a/docs/zh-CN/core/property.md b/docs/zh-CN/core/property.md index 9d79ba76..58203c32 100644 --- a/docs/zh-CN/core/property.md +++ b/docs/zh-CN/core/property.md @@ -1,9 +1,9 @@ --- -title: Property +title: 属性（Property） description: 说明 GFramework.Core.Property 的可绑定属性模型、订阅方式与常见用法。 --- -# Property +# 属性（Property） `GFramework.Core.Property` 负责字段级响应式值。它最适合“一个字段变化就足以驱动视图或局部业务逻辑”的场景； 如果你的状态已经是聚合状态树、需要 reducer / middleware / history，再切到 diff --git a/docs/zh-CN/core/query.md b/docs/zh-CN/core/query.md index 0ae3a6de..e33380ae 100644 --- a/docs/zh-CN/core/query.md +++ b/docs/zh-CN/core/query.md @@ -1,9 +1,9 @@ --- -title: Query +title: 查询（Query） description: 说明 GFramework.Core.Query 旧查询体系的兼容定位、可用基类与当前使用约束。 --- -# Query +# 查询（Query） 本页说明 `GFramework.Core.Query` 里的旧查询体系。 diff --git a/docs/zh-CN/game/index.md b/docs/zh-CN/game/index.md index d033fad5..b00396d5 100644 --- a/docs/zh-CN/game/index.md +++ b/docs/zh-CN/game/index.md @@ -1,9 +1,9 @@ --- -title: Game +title: Game 模块 description: GFramework.Game family 的运行时入口、采用顺序与源码阅读导航。 --- -# Game +# Game 模块 `Game` 栏目对应 `GFramework.Game` 与 `GFramework.Game.Abstractions` 这层游戏运行时能力。 diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index 8b710612..2f0ba1c3 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -1,9 +1,9 @@ --- -title: Source Generators +title: 源码生成器 description: 按模块梳理 GFramework 当前发布的源码生成器包、运行时归属与推荐选包入口。 --- -# Source Generators +# 源码生成器 `Source Generators` 栏目对应 `GFramework` 当前按模块拆分发布的编译期工具链。