From e18512f0439cda886849a15afb71a21609b7316b Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Wed, 29 Apr 2026 13:23:26 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(documentation-governance):=20=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=20Game=20=E4=B8=8E=20Godot=20=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=8E=AA=E8=BE=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Game / Godot 细页的交叉链接与边界描述，移除内部路径、旧文档对比和命令式跳转 - 更新 GFramework.Godot 与配置工具 README 的公开标签，避免暴露测试路径和原始文档路径 - 补充 documentation-full-coverage-governance 的 RP-049 恢复点、验证结果与 origin/main stop-condition 计量 --- GFramework.Godot/README.md | 3 +- ...ation-full-coverage-governance-tracking.md | 50 ++++++++++++++----- ...entation-full-coverage-governance-trace.md | 42 ++++++++++++++++ docs/zh-CN/core/index.md | 4 +- docs/zh-CN/ecs/arch.md | 2 +- docs/zh-CN/game/config-system.md | 2 +- docs/zh-CN/game/scene.md | 2 +- docs/zh-CN/godot/index.md | 2 +- docs/zh-CN/godot/logging.md | 4 +- docs/zh-CN/godot/setting.md | 8 +-- docs/zh-CN/godot/signal.md | 4 +- docs/zh-CN/godot/storage.md | 6 +-- tools/gframework-config-tool/README.md | 4 +- 13 files changed, 99 insertions(+), 34 deletions(-) diff --git a/GFramework.Godot/README.md b/GFramework.Godot/README.md index 3f85835b..3e42f487 100644 --- a/GFramework.Godot/README.md +++ b/GFramework.Godot/README.md @@ -102,8 +102,7 @@ dotnet add package GeWuYou.GFramework.Godot.SourceGenerators 只有模块自身暴露 `Node`、需要挂到 `ArchitectureAnchor`，或要在 `OnAttach(...)` / `OnDetach()` 里处理 Godot 生命周期副作用时， 再使用 `InstallGodotModule(...)`。 -`GFramework.Godot.Tests/Architectures/AbstractArchitectureModuleInstallationTests.cs` 已覆盖一个关键边界：锚点缺失时会先抛 -`InvalidOperationException`，不会继续执行模块安装。 +这一点已有测试覆盖：锚点缺失时会先抛 `InvalidOperationException`，不会继续执行模块安装。 ### 3. Scene / UI 继续沿用 `Game` 契约 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 cd39d105..f7471461 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,19 +12,21 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-048` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-049` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按 `$gframework-pr-review` 复核 PR `#299` 的 latest-head review，并收口当前仍成立的 active tracking 问题：补齐 `RP-048` 下一步，以及把 `RP-045` 到 `RP-047` 的逐命令历史迁入归档 -- 本轮通过 `$gframework-batch-boot 50` 重新进入后确认 `HEAD == origin/main`，当前已提交 branch diff 为 `0` files / `0` lines，因此可以从新的低风险文档批次重新累计阈值 -- 当前已完成 4 个低风险批次，并在本轮额外完成 1 次 review-driven 收口：入口页 reader-facing 标题统一、内部参考路径去暴露，以及 `Core` / `Game` / `Godot` / `source-generators` 多个页面中“旧文档式对比”提示的直接契约化改写 -- 第 2 个已提交批次结束时，branch diff 相对 `origin/main` 为 `13` files / `124` lines；本轮最后一批提交后仍会明显低于 `50` 文件 stop condition -- 本轮已确认 `Architecture` 只暴露 `OnInitialize()`，`AbstractArchitecture` 通过 `InstallModules()` 暴露模块注册入口，而组件级 `OnInit()` 仍然是当前有效生命周期 -- 当前建议在本轮停止：active tracking 收口完成并推送后，只需重新抓取 PR `#299`，确认剩余项是否只剩 GitHub 侧 `Title check` 元数据提示 + - 按 `$gframework-batch-boot 50` 恢复 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，继续收口 `Game` / `Godot` 细页与工具 README 中残留的 reader-facing 措辞问题 +- `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主 +- 本轮在更新 tracking / trace 之前已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题 +- 本轮接受了 2 个 explorer 的只读结论：一个负责 `docs/zh-CN/game` 与 `docs/zh-CN/godot` 的热点排序，一个负责模块 README 的 reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写 +- 本轮仍保持在新的低风险批次窗口内：进入时 committed branch diff 相对 `origin/main` 为 `0` files / `0` lines，当前工作树相对 `origin/main` 为 `13` files / `132` lines，仍明显低于 `50` 文件 stop condition +- 本轮继续沿用已确认的生命周期事实：`Architecture` 只暴露 `OnInitialize()`，`AbstractArchitecture` 通过 `InstallModules()` 暴露模块注册入口，而组件级 `OnInit()` 仍然是当前有效生命周期 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 +- `2026-04-29` 新一轮 batch boot 已收口 `docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md` 与 `GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md` 的 reader-facing 文案：移除 `ai-libs`、旧文档对比、命令式跳转和原始路径标签。 +- `2026-04-29` 当前分支的 upstream `origin/docs/sdk-update-documentation` 已 gone；后续若继续批处理，应继续以 `origin/main` 作为 branch-size stop condition 的 authoritative baseline，而不是默认恢复旧 PR review 状态。 - `2026-04-28` 已重新抓取 PR `#299` 并复核 latest-head review：remote 当前只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，且都指向 active tracking 文档；`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，`Title check` 仍是 PR 元数据问题。 - `2026-04-25` 已重新抓取 PR `#290` 并确认：latest reviewed commit 为 `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181`，open thread 聚焦在 `docs/.vitepress/config.mts` 的侧栏重复 / 标签不一致，以及 `GFramework.Core`、`GFramework.Ecs.Arch`、`GFramework.Game` README 的 reader-facing 表格残留治理字段。 - `2026-04-25` `docs/.vitepress/config.mts` 已保留 `source-generators` 栏目自有子页导航，但不再让 `api-reference` 侧栏重复跳回 `core`、`game`、`godot`、`ecs` 等独立栏目入口。 @@ -64,8 +66,8 @@ `MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。 - 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。 - `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。 -- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步并完成 4 个低风险文案批次；剩余命中更偏向是否保留迁移说明的编辑判断，不再适合继续按同一批处理模式机械推进。 -- PR `#299` 在 remote latest-head review 中仍显示 `1` 条 open thread 与 `1` 条 nitpick，直到本轮 `ai-plan` 改动推送后才会反映关闭状态；`Title check` 仍需要直接修改 GitHub 上的 PR 标题。 +- 当前分支 upstream 已 gone；在重新建立 remote branch 或新的 PR 之前，不适合再把旧 PR `#299` 的 review 状态当作默认恢复信号。 +- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；本轮仍是低风险措辞收口，但下一轮若继续深入 README 子系统地图或大段采用路径重写，review 面会明显扩大。 ## 归档指针 @@ -86,6 +88,28 @@ ## 最新验证 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` + - 结果：通过；`godot/storage.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` + - 结果：通过；`godot/setting.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md` + - 结果：通过；`godot/signal.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md` + - 结果：通过；`godot/logging.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md` + - 结果：通过；`godot/index.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md` + - 结果：通过；`game/scene.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md` + - 结果：通过；`game/config-system.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` + - 结果：通过；`core/index.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` + - 结果：通过；`ecs/arch.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md tools/gframework-config-tool/README.md` + - 结果：通过；本轮 2 个 README 的 reader-facing 链接标签调整后目标有效。 +- `2026-04-29` `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-28` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#299` 处于 `OPEN`，latest head review 有 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 - `2026-04-28` `bun run build`（工作目录：`docs/`） @@ -95,7 +119,7 @@ ## 下一步 -1. 推送本轮提交后，优先重新抓取 `$gframework-pr-review`，确认 PR `#299` 仅剩标题元数据提示或已全部清空。 -2. 若 remote review 清空后仍继续文档治理，优先人工复核尚未触达的 `Game` persistence、Godot runtime 细页与少量残余迁移边界表述，而不是继续按关键词机械扩批。 -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`、`docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。 +1. 提交本轮低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。 +2. 若继续下一批，优先人工复核 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 以及少量仍暴露原始路径标签的模块 README，而不是进入大段结构改写。 +3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。 +4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 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 928ac302..51bbf8fe 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 @@ -1,5 +1,47 @@ # Documentation Full Coverage Governance Trace +## 2026-04-29 + +### 当前恢复点：RP-049 + +- 本轮按 `$gframework-batch-boot 50` 恢复，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`；当前 upstream `origin/docs/sdk-update-documentation` 已 gone，因此改用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为新的 branch-size baseline。 +- 恢复时 committed branch diff vs baseline 为 `0` files / `0` lines，因此可以安全开启新一轮低风险 reader-facing 文档批次。 +- 当前工作树在本批次与恢复文档更新后相对 `origin/main` 为 `13` files / `132` lines，离 `$gframework-batch-boot 50` 的主 stop condition 仍有充足余量。 +- 本轮接受了 2 个 explorer 的只读热点排序：一个巡检 `docs/zh-CN/game` 与 `docs/zh-CN/godot` 细页，一个巡检模块 README 的 reader-facing 标签；主线程只接受低风险措辞问题，不扩展到 README 子系统地图或结构重写。 +- 实际落地的收口集中在 11 个文件：`docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md`、`GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md`。 + +### 当前决策（RP-049） + +- 由于 upstream / 旧 PR 恢复路径已经失效，本轮不再以旧的 PR `#299` review 线程作为批处理驱动条件，而是以 `origin/main` + `50` changed files 作为唯一 stop condition。 +- 这批修改只处理 reader-facing 措辞、交叉链接语气和 README 标签，不改导航结构、不补新章节、不重写示例。 +- explorer 给出的 `GFramework.Cqrs` / `GFramework.Cqrs.Abstractions` README 源文件列表问题先不纳入本轮，因为那已经超出“低风险文案收口”边界。 + +### 当前验证（RP-049） + +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.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/godot/signal.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` + - 结果：通过；本轮 9 个页面的 frontmatter、链接与代码块校验全部通过。 +- README 链接校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md tools/gframework-config-tool/README.md` + - 结果：通过；本轮 2 个 README 的 reader-facing 链接标签调整后目标有效。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 + +### 下一步（RP-049） + +1. 提交本轮 reader-facing 文案批次，并更新 branch diff vs `origin/main` 的精确计量。 +2. 若继续下一批，优先复核 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与少量 README 标签问题，不直接展开大段 README 子系统地图重写。 +3. 只有在 remote branch / 新 PR 重新建立后，再恢复 `$gframework-pr-review` 作为默认恢复入口。 + ## 2026-04-28 ### 当前恢复点：RP-048 diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index 38d8b123..6a5a7094 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -132,9 +132,9 @@ public sealed class CounterArchitecture : Architecture - 要写新的请求/通知处理流： - 优先阅读[CQRS 运行时](./cqrs.md) - 要接入游戏内容配置、设置、数据仓库、Scene 或 UI： - - 转到[Game 模块](../game/index.md) + - 继续阅读[Game 模块](../game/index.md) - 要接入 Godot 节点、场景和项目元数据生成： - - 转到[Godot 模块](../godot/index.md)与[源码生成器](../source-generators/index.md)栏目 + - 继续阅读[Godot 模块](../godot/index.md)与[源码生成器](../source-generators/index.md) ## 阅读顺序 diff --git a/docs/zh-CN/ecs/arch.md b/docs/zh-CN/ecs/arch.md index 0eff9707..1b222318 100644 --- a/docs/zh-CN/ecs/arch.md +++ b/docs/zh-CN/ecs/arch.md @@ -125,7 +125,7 @@ ecsModule.Update(deltaTime); - `WorldCapacity` 用于 `World.Create(...)` 的容量参数 - `Priority` 影响 `ArchEcsModule` 作为服务模块的排序 -- `EnableStatistics` 目前保留在公开配置面上；采用时应以源码 XML 注释和实现行为为准，而不是依赖旧文档推断 +- `EnableStatistics` 目前保留在公开配置面上；采用时应以源码 XML 注释和实现行为为准 ## 源码阅读入口 diff --git a/docs/zh-CN/game/config-system.md b/docs/zh-CN/game/config-system.md index 9c38f65a..1f1ca949 100644 --- a/docs/zh-CN/game/config-system.md +++ b/docs/zh-CN/game/config-system.md @@ -436,7 +436,7 @@ var slime = runtime.GetMonster(1); ### 生成查询辅助 -从当前阶段开始，生成的 `*Table` 包装会为“顶层、非主键、非引用的标量字段”额外产出轻量查询辅助。 +对于顶层、非主键、非引用的标量字段，生成的 `*Table` 包装会额外产出轻量查询辅助。 如果某个字段属于高频精确匹配条件，可以在 schema 中显式声明： diff --git a/docs/zh-CN/game/scene.md b/docs/zh-CN/game/scene.md index 01a6a387..438b58d3 100644 --- a/docs/zh-CN/game/scene.md +++ b/docs/zh-CN/game/scene.md @@ -159,7 +159,7 @@ public sealed class GameSceneRouter : SceneRouterBase - `AddScene(ISceneBehavior scene)` - `RemoveScene(ISceneBehavior scene)` -也就是说，root 是“挂载/移除容器”，不是路由器本身。当前 `ai-libs/` 参考实现也是在项目自己的 Godot 节点里实现 +也就是说，root 是“挂载/移除容器”，不是路由器本身。项目通常会在自己的 Godot 节点里实现 `ISceneRoot`，并在 `_Ready()` 时调用 `BindRoot(this)`。 ### 4. 把 router 和 factory 装进架构 diff --git a/docs/zh-CN/godot/index.md b/docs/zh-CN/godot/index.md index 49f6f73b..e3b6d1f0 100644 --- a/docs/zh-CN/godot/index.md +++ b/docs/zh-CN/godot/index.md @@ -140,7 +140,7 @@ public partial class SettingsPanel : Control - 音频、图形与本地化设置接线：[Godot 设置系统](./setting.md) - `Signal(...)` fluent API 与动态连接边界：[Godot 信号系统](./signal.md) -如果你要核对项目级接线，而不是运行时 API，本页之后优先看： +如果你要核对项目级接线，而不是运行时 API，可继续阅读： - [Godot 集成教程](../tutorials/godot-integration.md) - [Godot 项目元数据生成器](../source-generators/godot-project-generator.md) diff --git a/docs/zh-CN/godot/logging.md b/docs/zh-CN/godot/logging.md index 400a4ea6..039f9472 100644 --- a/docs/zh-CN/godot/logging.md +++ b/docs/zh-CN/godot/logging.md @@ -159,8 +159,8 @@ RegisterHandler(new LoggingTransitionHandler()); System.IO.IOException: ... ``` -如果你需要 JSON formatter、rolling file、namespace 级过滤、structured sink 组合，这已经超出 -`GFramework.Godot.Logging` 当前职责，应该回到 [Core 日志系统](../core/logging.md) 设计 provider 组合。 +如果你需要 JSON formatter、rolling file、namespace 级过滤或 structured sink 组合，可继续阅读 +[Core 日志系统](../core/logging.md) 里的 provider 组合方式。 ## 什么时候用手写 logger，什么时候用 `[Log]` diff --git a/docs/zh-CN/godot/setting.md b/docs/zh-CN/godot/setting.md index 3211f2fa..2639d01d 100644 --- a/docs/zh-CN/godot/setting.md +++ b/docs/zh-CN/godot/setting.md @@ -133,14 +133,14 @@ await settingsSystem.Apply(); ## 什么时候应该改看别的入口 -### 相关设置模型 +### 宿主无关设置契约 -如果你想先理解 `ISettingsData`、`IResetApplyAbleSettings`、`SettingsModel`、`SettingsSystem` 与设置迁移，先看 +`ISettingsData`、`IResetApplyAbleSettings`、`SettingsModel`、`SettingsSystem` 与设置迁移的宿主无关说明，可继续阅读 [Game 设置系统](../game/setting.md)。 -### 相关持久化入口 +### 相关持久化文档 -如果你关注的是统一设置文件、备份、数据位置和底层存储实现，应该回到： +如果你关注统一设置文件、备份、数据位置和底层存储实现，可继续阅读： - [Game 存储系统](../game/storage.md) - [Godot 存储系统](./storage.md) diff --git a/docs/zh-CN/godot/signal.md b/docs/zh-CN/godot/signal.md index dee1f53e..0bdbc9f3 100644 --- a/docs/zh-CN/godot/signal.md +++ b/docs/zh-CN/godot/signal.md @@ -139,11 +139,11 @@ _quitConfirmDialog.Signal("Confirmed") - 你已经在用 `[GetNode]` - 希望把 `_Ready()` 里的重复绑定样板交给生成器 -这两条路径是互补关系，不是前后代际关系。当前源码没有“先用 `CreateSignalBuilder(...)`，再升级到生成器”这种迁移链。 +这两条路径是互补关系，不要求按“先 fluent API、后生成器”的顺序迁移。 ## 当前边界 -- 当前入口是 `Signal(...)`，不是旧文档里的 `CreateSignalBuilder(...)` +- 动态连接的公开入口是 `Signal(...)` - 这里不会自动生成 `_Ready()` / `_ExitTree()`，这类能力属于 `GFramework.Godot.SourceGenerators` - `SignalBuilder` 不提供取消订阅 token，也不会替你包装 `Disconnect(...)` - `End()` 只返回原始对象，不会提交额外配置，也不是必须调用的终止步骤 diff --git a/docs/zh-CN/godot/storage.md b/docs/zh-CN/godot/storage.md index 6e662b81..0a1797ab 100644 --- a/docs/zh-CN/godot/storage.md +++ b/docs/zh-CN/godot/storage.md @@ -107,8 +107,8 @@ architecture.RegisterUtility>(new SaveRepository>(new SaveRepository Date: Wed, 29 Apr 2026 13:36:07 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(documentation-governance):=20=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=E6=95=B0=E6=8D=AE=E4=B8=8E=20UI=20=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=8E=AA=E8=BE=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Game 数据与存储页面、Godot UI 页面中的 reader-facing 说明，移除内部证据口吻、外部项目指代和生硬导流 - 更新 CQRS 抽象层与 SourceGenerators.Common README 的标签表述，避免暴露源文件路径列表和实现级打包术语 - 补充 documentation-full-coverage-governance 的 RP-050 恢复点、验证结果与 origin/main stop-condition 计量 --- GFramework.Cqrs.Abstractions/README.md | 24 ++++---------- GFramework.SourceGenerators.Common/README.md | 2 +- ...ation-full-coverage-governance-tracking.md | 27 +++++++++++---- ...entation-full-coverage-governance-trace.md | 33 +++++++++++++++++++ docs/zh-CN/game/data.md | 4 +-- docs/zh-CN/game/storage.md | 6 ++-- docs/zh-CN/godot/ui.md | 10 +++--- 7 files changed, 70 insertions(+), 36 deletions(-) diff --git a/GFramework.Cqrs.Abstractions/README.md b/GFramework.Cqrs.Abstractions/README.md index 4a7c6bdd..908e895b 100644 --- a/GFramework.Cqrs.Abstractions/README.md +++ b/GFramework.Cqrs.Abstractions/README.md @@ -30,27 +30,15 @@ 本包当前可以分为几类契约： - 消息契约 - - `Cqrs/IRequest.cs` - - `Cqrs/INotification.cs` - - `Cqrs/IStreamRequest.cs` - - `Cqrs/Command/ICommand.cs` - - `Cqrs/Query/IQuery.cs` - - `Cqrs/Request/IRequestInput.cs` - - `Cqrs/Command/ICommandInput.cs` - - `Cqrs/Query/IQueryInput.cs` - - `Cqrs/Notification/INotificationInput.cs` + - `IRequest`、`INotification`、`IStreamRequest` + - `ICommand`、`IQuery` + - `IRequestInput`、`ICommandInput`、`IQueryInput`、`INotificationInput` - 处理器契约 - - `Cqrs/IRequestHandler.cs` - - `Cqrs/INotificationHandler.cs` - - `Cqrs/IStreamRequestHandler.cs` + - `IRequestHandler<,>`、`INotificationHandler<>`、`IStreamRequestHandler<,>` - 运行时协作接口 - - `Cqrs/ICqrsRuntime.cs` - - `Cqrs/ICqrsContext.cs` - - `Cqrs/ICqrsHandlerRegistrar.cs` + - `ICqrsRuntime`、`ICqrsContext`、`ICqrsHandlerRegistrar` - 管道与辅助类型 - - `Cqrs/IPipelineBehavior.cs` - - `Cqrs/MessageHandlerDelegate.cs` - - `Cqrs/Unit.cs` + - `IPipelineBehavior<,>`、`MessageHandlerDelegate<,>`、`Unit` ## 最小接入路径 diff --git a/GFramework.SourceGenerators.Common/README.md b/GFramework.SourceGenerators.Common/README.md index 9e964364..c6783e44 100644 --- a/GFramework.SourceGenerators.Common/README.md +++ b/GFramework.SourceGenerators.Common/README.md @@ -25,7 +25,7 @@ - `GFramework.Godot.SourceGenerators` - 同样复用这里的公共实现和共享约束。 -这个目录当前 `IsPackable=false`，不作为独立安装包推广。对 NuGet 使用者来说，更实际的入口仍然是具体的 +这个目录不会单独作为消费包提供。对 NuGet 使用者来说，更实际的入口仍然是具体的 `GeWuYou.GFramework.*.SourceGenerators` 包。 ## 什么时候需要读这里 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 f7471461..27deef8a 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,19 +12,21 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-049` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-050` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按 `$gframework-batch-boot 50` 恢复 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，继续收口 `Game` / `Godot` 细页与工具 README 中残留的 reader-facing 措辞问题 + - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，收口 `Game` / `Godot` 细页与少量 README 中残留的 reader-facing 措辞与标签问题 - `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主 -- 本轮在更新 tracking / trace 之前已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题 -- 本轮接受了 2 个 explorer 的只读结论：一个负责 `docs/zh-CN/game` 与 `docs/zh-CN/godot` 的热点排序，一个负责模块 README 的 reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写 -- 本轮仍保持在新的低风险批次窗口内：进入时 committed branch diff 相对 `origin/main` 为 `0` files / `0` lines，当前工作树相对 `origin/main` 为 `13` files / `132` lines，仍明显低于 `50` 文件 stop condition +- `2026-04-29` 上一批已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题 +- `2026-04-29` 本批次继续接受 2 个 explorer 的只读结论：一个负责 `game/data.md`、`game/storage.md`、`godot/ui.md` 的热点排序，一个负责 README reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写 +- `2026-04-29` 本批次已收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md` 的文案：把内部证据叙述、外部项目指代、命令式导流、源文件路径列表和 `IsPackable=false` 这类实现术语改成 reader-facing 说明 +- 本轮仍保持在新的低风险批次窗口内：当前工作树相对 `origin/main` 为 `18` files / `225` lines，仍明显低于 `50` 文件 stop condition - 本轮继续沿用已确认的生命周期事实：`Architecture` 只暴露 `OnInitialize()`，`AbstractArchitecture` 通过 `InstallModules()` 暴露模块注册入口，而组件级 `OnInit()` 仍然是当前有效生命周期 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 +- `2026-04-29` 新一轮 batch boot 第 2 批次已进一步收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`：移除 “仓库和测试确认”“真实消费者 wiring”“CoreGrid 当前的做法”“优先看” 这类内部或生硬口吻，并把 CQRS 抽象层 README 的源文件列表改成契约类型族说明。 - `2026-04-29` 新一轮 batch boot 已收口 `docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md` 与 `GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md` 的 reader-facing 文案：移除 `ai-libs`、旧文档对比、命令式跳转和原始路径标签。 - `2026-04-29` 当前分支的 upstream `origin/docs/sdk-update-documentation` 已 gone；后续若继续批处理，应继续以 `origin/main` 作为 branch-size stop condition 的 authoritative baseline，而不是默认恢复旧 PR review 状态。 - `2026-04-28` 已重新抓取 PR `#299` 并复核 latest-head review：remote 当前只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，且都指向 active tracking 文档；`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，`Title check` 仍是 PR 元数据问题。 @@ -68,6 +70,7 @@ - `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。 - 当前分支 upstream 已 gone；在重新建立 remote branch 或新的 PR 之前，不适合再把旧 PR `#299` 的 review 状态当作默认恢复信号。 - 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；本轮仍是低风险措辞收口，但下一轮若继续深入 README 子系统地图或大段采用路径重写，review 面会明显扩大。 +- `GFramework.Cqrs`、`GFramework.Cqrs.SourceGenerators`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 仍有若干源文件列表式“子系统地图”段落；这些已经接近结构级改写，不适合作为本轮剩余低风险批次继续机械推进。 ## 归档指针 @@ -88,6 +91,16 @@ ## 最新验证 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md` + - 结果：通过；`game/data.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md` + - 结果：通过；`game/storage.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` + - 结果：通过；`godot/ui.md` 的 frontmatter、链接与代码块校验通过。 +- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md` + - 结果：通过；本轮 2 个 README 的 reader-facing 标签调整后目标有效。 +- `2026-04-29` `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮第 2 批 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` - 结果：通过；`godot/storage.md` 的 frontmatter、链接与代码块校验通过。 - `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` @@ -119,7 +132,7 @@ ## 下一步 -1. 提交本轮低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。 -2. 若继续下一批，优先人工复核 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 以及少量仍暴露原始路径标签的模块 README，而不是进入大段结构改写。 +1. 提交本轮第 2 批低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。 +2. 若继续下一批，优先挑选仍可“局部改句子”的页面或 README 标签问题；`Cqrs`、`Game.SourceGenerators`、`Ecs.Arch` 这类源文件列表式 README 应视作结构级专题，必要时单独开一轮更明确的写作目标。 3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。 4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 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 51bbf8fe..b7de3b1c 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,39 @@ ## 2026-04-29 +### 当前恢复点：RP-050 + +- 本轮继续按 `$gframework-batch-boot 50` 推进，并沿用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为唯一 branch-size baseline。 +- 当前 `HEAD` 相对 baseline 的 committed diff 仍是上一批的 `13` files / `133` lines；在本批次工作树修改与 `RP-050` 恢复文档更新后，working tree 相对 `origin/main` 为 `18` files / `225` lines，离 stop condition 仍有充足余量。 +- 本轮接受了 2 个 explorer 的只读排序：一个锁定 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 的低风险措辞问题，一个锁定 README 中仍能局部收口的标签问题。主线程只接受“改句子就能闭环”的项，不扩展到 README 结构重写。 +- 实际落地的收口集中在 5 个文件：`docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`。 + +### 当前决策（RP-050） + +- 文档页只处理内部证据口吻、命令式导流、外部项目指代和生硬 adoption phrasing；不改示例结构和导航层次。 +- README 只处理两类低风险项：把源文件路径列表改成类型级契约说明，把 `IsPackable=false` 这类实现术语改成 reader-facing 安装说明。 +- `GFramework.Cqrs`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 的大段源文件清单继续留到后续单独批次，因为那已经接近结构级重写，不适合和当前轻量文案收口混在一轮。 + +### 当前验证（RP-050） + +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` + - 结果：通过；本轮 3 个页面的 frontmatter、链接与代码块校验全部通过。 +- README 链接校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md` + - 结果：通过；本轮 2 个 README 的 reader-facing 标签调整后目标有效。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮第 2 批 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 + +### 下一步（RP-050） + +1. 提交本轮第 2 批 reader-facing 文案批次，并更新 committed branch diff vs `origin/main` 的精确计量。 +2. 若继续下一批，优先挑选仍可局部收口的页面或 README 标签，不把结构级 README 改写混入同一轮。 +3. 只有在 remote branch / 新 PR 重新建立后，再恢复 `$gframework-pr-review` 作为默认恢复入口。 + ### 当前恢复点：RP-049 - 本轮按 `$gframework-batch-boot 50` 恢复，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`；当前 upstream `origin/docs/sdk-update-documentation` 已 gone，因此改用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为新的 branch-size baseline。 diff --git a/docs/zh-CN/game/data.md b/docs/zh-CN/game/data.md index 2faa03a1..a184e1a9 100644 --- a/docs/zh-CN/game/data.md +++ b/docs/zh-CN/game/data.md @@ -16,7 +16,7 @@ description: 以当前 GFramework.Game 源码与 PersistenceTests 为准，说 - `SaveRepository` - 面向“按槽位组织的版本化存档” -如果先把这三类入口分开理解，后续采用路径会清晰很多。 +如果先把这三类入口分开理解，后续接入时会清晰很多。 ## 什么时候用哪个仓库 @@ -83,7 +83,7 @@ settings/ ### `DataRepository` -`DataRepository` 是最通用的默认实现。当前仓库和测试确认的行为有几条需要特别记住： +`DataRepository` 是最通用的默认实现。有几条默认行为需要特别注意： - `LoadAsync(location)` 在文件不存在时返回 `new T()`，不是抛异常 - `DeleteAsync(location)` 只有在目标数据真实存在并被删除时才发送删除事件 diff --git a/docs/zh-CN/game/storage.md b/docs/zh-CN/game/storage.md index deed4e65..9d2997b6 100644 --- a/docs/zh-CN/game/storage.md +++ b/docs/zh-CN/game/storage.md @@ -150,7 +150,7 @@ var cacheStorage = new ScopedStorage(rootStorage, "runtime-cache"); ## 与上层 repository 的关系 -`FileStorage` / `ScopedStorage` 是持久化最底层，不是最终采用入口。当前更常见的实际分工是： +`FileStorage` / `ScopedStorage` 是持久化最底层，不是业务层最常直接接入的入口。当前更常见的实际分工是： - `DataRepository` - 每个 `IDataLocation` 对应一份独立持久化对象 @@ -161,8 +161,8 @@ var cacheStorage = new ScopedStorage(rootStorage, "runtime-cache"); 也就是说： -- 业务层如果想保存一份独立数据，优先看 [数据与存档系统](./data.md) -- 业务层如果想保存设置，优先看 [设置系统](./setting.md) +- 业务层如果想保存一份独立数据，可继续阅读 [数据与存档系统](./data.md) +- 业务层如果想保存设置，可继续阅读 [设置系统](./setting.md) - 业务层如果只是需要底层存储实现，才直接依赖 `IStorage` ## 当前边界 diff --git a/docs/zh-CN/godot/ui.md b/docs/zh-CN/godot/ui.md index 028ca92b..f77725c9 100644 --- a/docs/zh-CN/godot/ui.md +++ b/docs/zh-CN/godot/ui.md @@ -38,8 +38,8 @@ Godot 侧 UI 资源表，底层是 `IAssetRegistry`。它只负责 3. 节点必须实现 `IUiPageBehaviorProvider` 4. 返回 `provider.GetPage()` -如果实例化得到的节点没有实现 `IUiPageBehaviorProvider`，当前实现会直接抛 `InvalidCastException`。这也是 UI 页面文档必须强调 -`GetPage()` / `[AutoUiPage]` 的原因。 +如果实例化得到的节点没有实现 `IUiPageBehaviorProvider`，当前实现会直接抛 `InvalidCastException`。因此页面节点必须显式提供 +`GetPage()`，或者通过 `[AutoUiPage]` 生成对应样板。 ### `CanvasItemUiPageBehaviorBase` @@ -135,7 +135,7 @@ architecture.RegisterSystem(new UiRouter()); `UiRouterBase` 只负责页面栈、layer UI、输入仲裁和暂停语义；真正把页面挂到 Godot 容器的是项目自己的 `IUiRoot`。 -CoreGrid 当前的 `UiRoot` 做法和源码契约一致： +项目侧常见的 `UiRoot` 接法如下： - 继承 `CanvasLayer` - 为每个 `UiLayer` 创建一个 `Control` 容器 @@ -221,7 +221,7 @@ public partial class PauseMenu : Control, IUiPage, IUiPageBehaviorProvider #### 方式 B：用 `[AutoUiPage]` 让生成器补样板 -当前更贴近真实消费者 wiring 的方式，是让生成器产出 `UiKeyStr` 和 `GetPage()`： +更常见的接法，是让生成器产出 `UiKeyStr` 和 `GetPage()`： ```csharp using GFramework.Game.Abstractions.UI; @@ -297,7 +297,7 @@ uiRouter.Hide(handle, UiLayer.Modal); 如果页面只实现 `IUiPage`，它只有基础生命周期。 -如果还需要更强的输入仲裁或暂停语义，可以像 CoreGrid 的 `PauseMenu` 一样继续实现： +如果还需要更强的输入仲裁或暂停语义，可以继续实现： - `IUiInteractionProfileProvider` - `IUiActionHandler`