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 1/5] =?UTF-8?q?docs(batch-boot):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E5=85=AC=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 侧通用生成器 From 3c0ac1858ad936427888d7e4b2111ebf87c6137a Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Mon, 27 Apr 2026 17:33:36 +0800 Subject: [PATCH 2/5] =?UTF-8?q?docs(batch-boot):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E5=85=AC=E5=BC=80=E6=96=87=E6=A1=A3=E4=B8=AD=E7=9A=84=E5=86=85?= =?UTF-8?q?=E9=83=A8=E5=8F=82=E8=80=83=E8=B7=AF=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Game、Godot 与 source-generators 多个专题页的 reader-facing 示例口吻 - 移除 ai-libs CoreGrid 路径在公开页面中的直接暴露，保留项目侧常见实现说明 - 补充 documentation full coverage active topic 的 RP-046 跟踪与验证记录 --- ...ation-full-coverage-governance-tracking.md | 22 +++++++++++++--- ...entation-full-coverage-governance-trace.md | 26 +++++++++++++++++++ docs/zh-CN/game/ui.md | 2 +- docs/zh-CN/godot/signal.md | 2 +- ...register-exported-collections-generator.md | 2 +- .../bind-node-signal-generator.md | 2 +- .../source-generators/get-node-generator.md | 2 +- .../godot-project-generator.md | 4 +-- 8 files changed, 52 insertions(+), 10 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 cdbd3255..f802b449 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,14 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-045` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-046` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 继续以最新 `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` / `旧文档` 指向式表述，保持同样的低风险文字级修正边界 +- 当前已完成前 2 个低风险批次：先统一 `source-generators`、`game`、`api-reference`、`godot/setting`、`abstractions` 五个入口页的 reader-facing 标题与导航口吻，再清理 `game/ui`、`godot/signal` 与 4 个 source-generators 专题页里的 `ai-libs/CoreGrid` 路径暴露 +- 当前已提交 branch diff 相对 `origin/main` 为 `7` files / `68` lines；第 2 批次提交后预计会把 branch diff 推进到低双位数，仍明显低于 `50` 文件 stop condition +- 当前建议继续第 3 个批次，优先收口仍残留在公开文档里的“旧文档式对比”提示，保持同样的低风险文字级修正边界 ## 当前状态摘要 @@ -36,6 +37,7 @@ - `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` 新一轮 batch boot 第 2 批次已把 `docs/zh-CN/game/ui.md`、`godot/signal.md`、`source-generators/godot-project-generator.md`、`get-node-generator.md`、`bind-node-signal-generator.md`、`auto-register-exported-collections-generator.md` 中直接暴露 `ai-libs/CoreGrid` 的路径型说明改成项目侧常见实现说明。 - `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` 这类维护与内部语气改写成当前采用说明。 @@ -76,6 +78,20 @@ ## 最新验证 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md` + - 结果：通过；Game UI 页去 `ai-libs/` 路径化说明后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md` + - 结果：通过；Godot signal 页改成项目侧示例口吻后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/godot-project-generator.md` + - 结果：通过；Godot project 生成器页去内部参考项目路径后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/get-node-generator.md` + - 结果：通过；GetNode 生成器页改成通用项目侧用法说明后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md` + - 结果：通过；BindNodeSignal 生成器页去具体内部项目名后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md` + - 结果：通过；导出集合自动注册页改成通用入口描述后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 batch boot 第 2 批次的 6 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - `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` 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 05295c48..64620669 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,32 @@ ## 2026-04-27 +### 当前恢复点：RP-046 + +- 第 1 批次提交 `c56260b` 后，重新计算 branch diff 确认当前相对 `origin/main` 为 `7` files / `68` lines，仍远低于 `$gframework-batch-boot 50` 的 stop condition。 +- 基于上一轮搜索结果，本轮继续接收一组同样低风险的公开文案收口：`docs/zh-CN/game/ui.md`、`godot/signal.md` 以及 4 个 source-generators 专题页中直接暴露 `ai-libs/CoreGrid` 路径的段落。 +- 这些页面都只是把内部参考项目路径改写为“项目侧常见实现”或“典型入口组织方式”，不改变示例代码、采用顺序或专题页结构。 + +### 当前决策（RP-046） + +- 第 2 批次继续保持单页文字级修正边界，不把 `ai-libs/**` 当成公开文档里的直接导航或消费者说明。 +- 在站点构建通过后立即提交本批次，以便 branch diff 能继续被 stop condition 精确计量。 +- 当前下一候选批次是清理仍残留在若干公开页面中的“旧文档式对比”提示，继续限定为文案级收口。 + +### 当前验证（RP-046） + +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.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/source-generators/godot-project-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/get-node-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md` + - 结果：通过；本轮 6 个公开页面的 frontmatter、链接与代码块校验均通过。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 batch boot 第 2 批次的 6 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 + ### 当前恢复点：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`）。 diff --git a/docs/zh-CN/game/ui.md b/docs/zh-CN/game/ui.md index c840fa24..fc80ec61 100644 --- a/docs/zh-CN/game/ui.md +++ b/docs/zh-CN/game/ui.md @@ -211,7 +211,7 @@ public sealed class GameUiRouter : UiRouterBase - `AddUiPage(IUiPageBehavior child, UiLayer layer, int orderInLayer = 0)` - `RemoveUiPage(IUiPageBehavior child)` -当前 `ai-libs/` 的参考实现就是在项目自己的 `CanvasLayer` 上为每个 `UiLayer` 建独立容器，再在 `_Ready()` 时执行 +一种常见的项目侧实现方式，是在自己的 `CanvasLayer` 上为每个 `UiLayer` 建独立容器，再在 `_Ready()` 时执行 `_uiRouter.BindRoot(this)`。 ### 4. 装配 router 与 factory diff --git a/docs/zh-CN/godot/signal.md b/docs/zh-CN/godot/signal.md index cfa3a9dc..dee1f53e 100644 --- a/docs/zh-CN/godot/signal.md +++ b/docs/zh-CN/godot/signal.md @@ -120,7 +120,7 @@ private void OnStartPressed() - 运行时选出的 signal 名称 - 需要临时追加监听的 dock、panel、overlay -`ai-libs/CoreGrid` 当前就有这类用法： +项目侧常见也会这样写： ```csharp _quitConfirmDialog.Signal("Confirmed") diff --git a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md index 2f2a0529..4b27d1de 100644 --- a/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md +++ b/docs/zh-CN/source-generators/auto-register-exported-collections-generator.md @@ -161,7 +161,7 @@ public List? Values { get; } = new(); ## 真实采用路径 -`ai-libs/CoreGrid/global/GameEntryPoint.cs` 是当前最直接的消费者参考： +一个典型的项目侧入口会这样组织导出集合： - `UiPageConfigs` - `GameSceneConfigs` diff --git a/docs/zh-CN/source-generators/bind-node-signal-generator.md b/docs/zh-CN/source-generators/bind-node-signal-generator.md index 1e6a4d76..1c3aad01 100644 --- a/docs/zh-CN/source-generators/bind-node-signal-generator.md +++ b/docs/zh-CN/source-generators/bind-node-signal-generator.md @@ -130,7 +130,7 @@ private void OnAnyButtonPressed() 当前生成器会为每个特性都生成一条 `+=` 和一条 `-=`。 -`ai-libs/CoreGrid` 里的 `GameplayHud`、`PauseMenu` 和 `OptionBrowser` 都在大量使用这种声明式绑定方式。 +项目侧的 HUD、菜单和选项面板节点，通常都会大量使用这种声明式绑定方式。 ## 与 GetNode 的协作边界 diff --git a/docs/zh-CN/source-generators/get-node-generator.md b/docs/zh-CN/source-generators/get-node-generator.md index bc5ff66d..b7c0b442 100644 --- a/docs/zh-CN/source-generators/get-node-generator.md +++ b/docs/zh-CN/source-generators/get-node-generator.md @@ -179,7 +179,7 @@ public override void _Ready() 先注入节点，再绑定事件；否则 `BindNodeSignal` 对应的字段还没完成解析。 -这也是 `ai-libs/CoreGrid` 里项目侧节点类的实际用法。 +这也是项目侧节点类的常见接法。 ## 什么时候适合用 `[GetNode]` diff --git a/docs/zh-CN/source-generators/godot-project-generator.md b/docs/zh-CN/source-generators/godot-project-generator.md index 575b6f35..f7ce7670 100644 --- a/docs/zh-CN/source-generators/godot-project-generator.md +++ b/docs/zh-CN/source-generators/godot-project-generator.md @@ -200,8 +200,8 @@ AutoLoad 名称也遵循同样的冲突处理策略。 - 节点字段注入：`[GetNode]` - 节点 CLR event 订阅：`[BindNodeSignal]` -在 `ai-libs/CoreGrid` 中，这三类能力是并行使用的：`project.godot` 负责 AutoLoad / Input Action，具体 UI 或场景节点再通过 -`[GetNode]` 和 `[BindNodeSignal]` 处理。 +在一个同时使用这些生成器的项目里，这三类能力通常并行存在：`project.godot` 负责 AutoLoad / Input Action，具体 UI +或场景节点再通过 `[GetNode]` 和 `[BindNodeSignal]` 处理。 ## 诊断与约束 From 289f12f30906d6b0d9992bbf82e362779bf80269 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Mon, 27 Apr 2026 17:41:17 +0800 Subject: [PATCH 3/5] =?UTF-8?q?docs(batch-boot):=20=E6=94=B6=E5=8F=A3?= =?UTF-8?q?=E6=97=A7=E5=85=A5=E5=8F=A3=E5=AF=B9=E6=AF=94=E6=96=87=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 Core、Game、Godot 与 source-generators 多个页面的 reader-facing 契约说明 - 将旧文档和旧入口对比句式改成直接陈述当前默认入口、约束与推荐做法 - 补充 documentation full coverage active topic 的 RP-047 跟踪与验证记录 --- ...ation-full-coverage-governance-tracking.md | 31 ++++++++++++++++--- ...entation-full-coverage-governance-trace.md | 30 ++++++++++++++++++ docs/zh-CN/core/command.md | 2 +- docs/zh-CN/core/context.md | 4 +-- docs/zh-CN/core/lifecycle.md | 2 +- docs/zh-CN/core/query.md | 2 +- docs/zh-CN/game/scene.md | 2 +- docs/zh-CN/game/ui.md | 2 +- docs/zh-CN/godot/scene.md | 3 +- docs/zh-CN/godot/ui.md | 4 +-- .../context-aware-generator.md | 2 +- .../source-generators/priority-generator.md | 2 +- 12 files changed, 68 insertions(+), 18 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 f802b449..021147c2 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,14 +12,14 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-046` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-047` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 继续以最新 `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，因此可以从新的低风险文档批次重新累计阈值 -- 当前已完成前 2 个低风险批次：先统一 `source-generators`、`game`、`api-reference`、`godot/setting`、`abstractions` 五个入口页的 reader-facing 标题与导航口吻，再清理 `game/ui`、`godot/signal` 与 4 个 source-generators 专题页里的 `ai-libs/CoreGrid` 路径暴露 -- 当前已提交 branch diff 相对 `origin/main` 为 `7` files / `68` lines；第 2 批次提交后预计会把 branch diff 推进到低双位数，仍明显低于 `50` 文件 stop condition -- 当前建议继续第 3 个批次，优先收口仍残留在公开文档里的“旧文档式对比”提示，保持同样的低风险文字级修正边界 +- 当前已完成 4 个低风险批次：入口页 reader-facing 标题统一、内部参考路径去暴露，以及 `Core` / `Game` / `Godot` / `source-generators` 多个页面中“旧文档式对比”提示的直接契约化改写 +- 第 2 个已提交批次结束时，branch diff 相对 `origin/main` 为 `13` files / `124` lines；本轮最后一批提交后仍会明显低于 `50` 文件 stop condition +- 当前建议在本轮停止：剩余命中更多是运行时迁移边界或模块 README 之间的正常交叉引用，不再属于同一类可机械批处理的低风险 reader-facing 收口 ## 当前状态摘要 @@ -38,6 +38,7 @@ - `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` 新一轮 batch boot 第 2 批次已把 `docs/zh-CN/game/ui.md`、`godot/signal.md`、`source-generators/godot-project-generator.md`、`get-node-generator.md`、`bind-node-signal-generator.md`、`auto-register-exported-collections-generator.md` 中直接暴露 `ai-libs/CoreGrid` 的路径型说明改成项目侧常见实现说明。 +- `2026-04-27` 新一轮 batch boot 第 3、4 批次已把 `core/query.md`、`core/command.md`、`core/context.md`、`core/lifecycle.md`、`game/scene.md`、`game/ui.md`、`godot/ui.md`、`godot/scene.md`、`source-generators/priority-generator.md`、`context-aware-generator.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` 这类维护与内部语气改写成当前采用说明。 @@ -61,7 +62,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 清理。 -- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；若继续多批次推进，应优先挑选仍未触及的公开文档文案收口点，避免在同一轮里重新引入大范围导航改造。 +- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步并完成 4 个低风险文案批次；剩余命中更偏向是否保留迁移说明的编辑判断，不再适合继续按同一批处理模式机械推进。 ## 归档指针 @@ -78,6 +79,26 @@ ## 最新验证 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/query.md` + - 结果：通过；Core query 页去旧文档对比表述后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/command.md` + - 结果：通过；Core command 页改成直接陈述当前输入契约后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/context.md` + - 结果：通过；Core context 页去旧总线入口对比表述后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md` + - 结果：通过；Game scene 页改成直接提示当前语义边界后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` + - 结果：通过；Godot UI 页默认语义与入口说明收口后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/priority-generator.md` + - 结果：通过；Priority 生成器页改成直接陈述当前 API 形态后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` + - 结果：通过；Core lifecycle 页旧入口提示收口后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md` + - 结果：通过；Godot scene 页默认入口说明收口后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/context-aware-generator.md` + - 结果：通过；ContextAware 生成器页路径差异说明收口后页面 frontmatter、链接与代码块校验均通过。 +- `2026-04-27` `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 batch boot 第 3、4 批次的 10 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md` - 结果：通过；Game UI 页去 `ai-libs/` 路径化说明后页面 frontmatter、链接与代码块校验均通过。 - `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.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 64620669..142be2b7 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,36 @@ ## 2026-04-27 +### 当前恢复点：RP-047 + +- 第 2 批次提交 `2d2cd0c` 后，重新计算 branch diff 确认当前相对 `origin/main` 为 `13` files / `124` lines，仍然远低于 `$gframework-batch-boot 50` 的 stop condition。 +- 本轮最后继续接受两组同类低风险文案收口：`core/query.md`、`core/command.md`、`core/context.md`、`game/scene.md`、`godot/ui.md`、`source-generators/priority-generator.md`，以及 `core/lifecycle.md`、`game/ui.md`、`godot/scene.md`、`source-generators/context-aware-generator.md`。 +- 这 10 个页面的共同点是：把“旧文档/旧入口对比”句式改成直接陈述当前契约、默认入口或推荐做法，不引入结构改造，也不删掉真实的迁移边界信息。 + +### 当前决策（RP-047） + +- 将第 3、4 批次合并为本轮最后一个提交，避免继续把批次拆得过碎，同时仍保持文件范围可审阅。 +- 本轮在这里停止，不是因为触达了 `50` 文件阈值，而是因为剩余命中已经从机械可收口的 reader-facing 文案问题，转成是否保留迁移信息或 README 交叉引用的编辑判断题。 +- 下一轮若继续，优先从剩余 `旧文档` / `README.md` / `先理解` 命中里做人工复核，而不是继续按关键词机械替换。 + +### 当前验证（RP-047） + +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/query.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/command.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/context.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/ui.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/priority-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/context-aware-generator.md` + - 结果：通过；本轮最后 10 个公开页面的 frontmatter、链接与代码块校验均通过。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 batch boot 第 3、4 批次的 10 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 + ### 当前恢复点：RP-046 - 第 1 批次提交 `c56260b` 后，重新计算 branch diff 确认当前相对 `origin/main` 为 `7` files / `68` lines，仍远低于 `$gframework-batch-boot 50` 的 stop condition。 diff --git a/docs/zh-CN/core/command.md b/docs/zh-CN/core/command.md index 59624d4a..f5667568 100644 --- a/docs/zh-CN/core/command.md +++ b/docs/zh-CN/core/command.md @@ -20,7 +20,7 @@ description: 说明 GFramework.Core.Command 旧命令体系的兼容定位、可 - `AbstractCommand` - 有输入、有返回值 -注意一个和旧文档不同的点：泛型命令现在通过构造函数接收输入，而不是依赖 `Input` 可写属性。 +当前泛型命令通过构造函数接收输入，而不是依赖 `Input` 可写属性。 ## 无输入命令 diff --git a/docs/zh-CN/core/context.md b/docs/zh-CN/core/context.md index a113752f..0aa2f104 100644 --- a/docs/zh-CN/core/context.md +++ b/docs/zh-CN/core/context.md @@ -18,14 +18,14 @@ description: 说明 IArchitectureContext 与 ArchitectureContext 的统一上下 ## 先记住一个事实 -如果你还在找旧文档里的这些属性： +如果你正在寻找这些属性式总线入口： - `CommandBus` - `QueryBus` - `EventBus` - `Container` -那说明你看到的是旧写法。当前推荐入口是方法，不是这些属性式总线。 +当前公开入口是方法，不是这些属性式总线。 ## 组件访问 diff --git a/docs/zh-CN/core/lifecycle.md b/docs/zh-CN/core/lifecycle.md index f0f4f096..8e01afd9 100644 --- a/docs/zh-CN/core/lifecycle.md +++ b/docs/zh-CN/core/lifecycle.md @@ -159,7 +159,7 @@ architecture.PhaseChanged += (_, args) => ## 推荐做法 - 新代码优先使用 `InitializeAsync()` / `DestroyAsync()` -- 把注册逻辑放在 `OnInitialize()`，不要沿用旧文档里的 `Init()` +- 把注册逻辑放在 `OnInitialize()`，不要继续使用 `Init()` 这类旧入口 - 让 `Utility` 承载底层能力，让 `Model` 承载状态，再让 `System` 消费两者 - 跨组件阶段逻辑优先写成 `IArchitectureLifecycleHook` diff --git a/docs/zh-CN/core/query.md b/docs/zh-CN/core/query.md index e33380ae..10e58ac9 100644 --- a/docs/zh-CN/core/query.md +++ b/docs/zh-CN/core/query.md @@ -18,7 +18,7 @@ description: 说明 GFramework.Core.Query 旧查询体系的兼容定位、可 - `AbstractQuery` - 带输入查询 -与旧文档不同，带输入查询现在通过构造函数接收输入，不再依赖 `Input` 属性赋值。 +当前带输入查询通过构造函数接收输入，不再依赖 `Input` 属性赋值。 ## 无输入查询 diff --git a/docs/zh-CN/game/scene.md b/docs/zh-CN/game/scene.md index 45b19606..01a6a387 100644 --- a/docs/zh-CN/game/scene.md +++ b/docs/zh-CN/game/scene.md @@ -76,7 +76,7 @@ description: 说明 GFramework.Game 场景路由的当前入口、项目侧接 - `PopAsync` - 对栈顶执行离开检查，通过后退出并卸载它，再从 `ISceneRoot` 移除，然后恢复新的栈顶。 -当前还有两个容易被旧文档误导的点： +当前还有两个容易混淆的点： - `SceneRouterBase` 默认不允许同一个 `sceneKey` 在栈中重复存在；内部会先做 `Contains(sceneKey)` 检查 - 框架不会替你实现“场景键 -> 具体场景实例”的注册逻辑；这仍然是 `ISceneFactory` 或项目注册表的职责 diff --git a/docs/zh-CN/game/ui.md b/docs/zh-CN/game/ui.md index fc80ec61..038635e5 100644 --- a/docs/zh-CN/game/ui.md +++ b/docs/zh-CN/game/ui.md @@ -113,7 +113,7 @@ description: 说明 GFramework.Game UI 路由当前的页面栈、层级 UI、 - `Page` 层属于栈语义，用 `PushAsync` / `ReplaceAsync` / `PopAsync` - `Overlay`、`Modal`、`Toast`、`Topmost` 属于层级语义，用 `Show` / `Hide` / `Resume` -`Show(..., UiLayer.Page)` 在当前实现里会直接抛异常，因此旧文档里那种“所有 UI 都统一通过 Show 进入”的写法不再准确。 +`Show(..., UiLayer.Page)` 在当前实现里会直接抛异常；`Page` 层应通过 `PushAsync` / `ReplaceAsync` / `PopAsync` 进入。 ### 输入不是页面自己抢，而是 router 先仲裁 diff --git a/docs/zh-CN/godot/scene.md b/docs/zh-CN/godot/scene.md index afb96cd4..050824f3 100644 --- a/docs/zh-CN/godot/scene.md +++ b/docs/zh-CN/godot/scene.md @@ -290,8 +290,7 @@ await sceneRouter.PopAsync(); ### 没有 `GodotSceneRouter` -仓库当前不存在 `GodotSceneRouter` 类型。旧文档里把它写成默认入口是失真的；实际入口仍然是项目侧继承 -`SceneRouterBase` 的 router。 +仓库当前不存在 `GodotSceneRouter` 类型；实际入口仍然是项目侧继承 `SceneRouterBase` 的 router。 ### 没有自动注册所有场景 diff --git a/docs/zh-CN/godot/ui.md b/docs/zh-CN/godot/ui.md index b194a86c..028ca92b 100644 --- a/docs/zh-CN/godot/ui.md +++ b/docs/zh-CN/godot/ui.md @@ -68,7 +68,7 @@ Godot runtime 的页面行为包装基类。它把 `IUiPageBehavior` 的这些 - `UiLayer.Toast` -> `ToastLayerUiPageBehavior` - `UiLayer.Topmost` -> `TopmostLayerUiPageBehavior` -几个容易被旧文档写偏的默认语义如下： +几个容易混淆的默认语义如下： - `Page` - 不可重入，阻断输入 @@ -319,7 +319,7 @@ uiRouter.Hide(handle, UiLayer.Modal); ### 没有 `GodotUiRouter` -仓库当前没有这个类型。旧文档把它写成默认入口是不准确的；真实入口仍然是项目侧的 `UiRouterBase` 派生类。 +仓库当前没有这个类型；真实入口仍然是项目侧的 `UiRouterBase` 派生类。 ### UI 工厂不会自动补 behavior diff --git a/docs/zh-CN/source-generators/context-aware-generator.md b/docs/zh-CN/source-generators/context-aware-generator.md index eb56ab91..5d230d3a 100644 --- a/docs/zh-CN/source-generators/context-aware-generator.md +++ b/docs/zh-CN/source-generators/context-aware-generator.md @@ -102,7 +102,7 @@ public partial class PlayerController : IController - 不维护共享 provider - 默认直接回退到 `GameContext.GetFirstArchitectureContext()` -因此，旧文档里把两条路径混写成“只是写法不同”已经不准确。 +因此，这两条路径不是“只是写法不同”，而是共享 provider 策略和实例缓存边界都不同。 ## 何时使用 `[ContextAware]` diff --git a/docs/zh-CN/source-generators/priority-generator.md b/docs/zh-CN/source-generators/priority-generator.md index 8de267d0..ab63ce17 100644 --- a/docs/zh-CN/source-generators/priority-generator.md +++ b/docs/zh-CN/source-generators/priority-generator.md @@ -68,7 +68,7 @@ var handlers = container.GetAllByPriority(); - `this.GetModelsByPriority()` - `this.GetUtilitiesByPriority()` -这比旧文档里反复出现的 `this.GetAllByPriority()` 更贴近当前公开扩展方法。 +当前公开扩展方法就是按角色拆分的这些 API，而不是泛化的 `this.GetAllByPriority()`。 ## 最小接入示例 From 121479835a572d4e4f614e97bba69538d99103d1 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Tue, 28 Apr 2026 08:52:07 +0800 Subject: [PATCH 4/5] =?UTF-8?q?docs(governance):=20=E6=94=B6=E5=8F=A3=20PR?= =?UTF-8?q?=20=E5=AE=A1=E6=9F=A5=E9=81=97=E7=95=99=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修复抽象层入口页与生命周期文档中的语义化导航和初始化入口说明 - 更新教程与排障文档中过时的架构级 Init() 示例，区分 OnInitialize()、InstallModules() 与 OnInit() - 归档 active tracking 的详细验证历史并补充 RP-048 trace --- ...ion-history-rp-041-to-rp-048-2026-04-28.md | 123 +++++++++ ...ation-full-coverage-governance-tracking.md | 244 +++--------------- ...entation-full-coverage-governance-trace.md | 33 +++ docs/zh-CN/abstractions/index.md | 2 +- docs/zh-CN/core/lifecycle.md | 6 +- docs/zh-CN/troubleshooting.md | 34 +-- .../tutorials/large-project-organization.md | 4 +- docs/zh-CN/tutorials/pause-system.md | 4 +- docs/zh-CN/tutorials/resource-management.md | 2 +- docs/zh-CN/tutorials/save-system.md | 2 +- .../zh-CN/tutorials/state-machine-tutorial.md | 2 +- 11 files changed, 214 insertions(+), 242 deletions(-) create mode 100644 ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md new file mode 100644 index 00000000..e784a06e --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md @@ -0,0 +1,123 @@ +# Documentation Full Coverage Governance Validation History (RP-041 to RP-048) + +## 2026-04-28 / RP-048 + +### PR review 抓取 + +- `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 有 `3` 条 `CodeRabbit` open thread，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 + +### 页面校验 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/state-machine-tutorial.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/resource-management.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/save-system.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/pause-system.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/large-project-organization.md` + - 结果：通过。 +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` + - 结果：通过。 + +### 站点构建 + +- `bun run build`（工作目录：`docs/`） + - 结果：通过；站点仍可构建，仅保留既有大 chunk warning。 + +## 2026-04-27 / RP-045 到 RP-047 + +### 第 1 批次 reader-facing 入口收口 + +- `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` +- `bun run build`（工作目录：`docs/`） + - 结果：通过；第 1 批次 5 个入口页校验与站点构建通过。 + +### 第 2 批次去内部参考路径暴露 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.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/source-generators/godot-project-generator.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/get-node-generator.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md` +- `bun run build`（工作目录：`docs/`） + - 结果：通过；第 2 批次 6 个公开页面校验与站点构建通过。 + +### 第 3、4 批次旧入口/旧文档对比收口 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/query.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/command.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/context.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/ui.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/priority-generator.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/context-aware-generator.md` +- `bun run build`（工作目录：`docs/`） + - 结果：通过；第 3、4 批次 10 个公开页面校验与站点构建通过。 + +### PR review follow-up 与 README / landing 补充验证 + +- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md GFramework.Game/README.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.Abstractions/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch.Abstractions/README.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started` +- `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/tutorials/basic` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.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/abstractions` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` +- `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/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/getting-started/quick-start.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.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/ui.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.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/godot/architecture.md` +- `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/logging.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/extensions.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/architecture.md` +- `bun run build`（工作目录：`docs/`） + - 结果：通过；相关 README、landing page 与 review follow-up 页面校验通过，站点构建通过。 + +## 2026-04-25 到 2026-04-26 / carry-over + +### 代表性验证命令 + +- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` +- `dotnet build GFramework.csproj -c Release` +- `bun run build`（工作目录：`docs/`） +- `bun run test`（工作目录：`tools/gframework-config-tool/`） +- `bun run package:vsix`（工作目录：`tools/gframework-config-tool/`） + - 结果：通过；更早一轮的 README、导航、教程、排障、工具 README 与元包校验结果仍由这些命令覆盖，详细结论可结合 trace 中的 RP-041 到 RP-047 条目与 Git 历史继续追溯。 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 021147c2..f47c4dbd 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,18 +12,20 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-047` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-048` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 继续以最新 `origin/main`（`7cfdd2c`，`2026-04-27 16:59:57 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files + - 按 `$gframework-pr-review` 复核 PR `#299` 的 latest-head review，并收口仍然成立的 3 条文件内问题：抽象层入口语义化链接、架构生命周期入口示例、active tracking 验证历史归档瘦身 - 本轮通过 `$gframework-batch-boot 50` 重新进入后确认 `HEAD == origin/main`，当前已提交 branch diff 为 `0` files / `0` lines，因此可以从新的低风险文档批次重新累计阈值 -- 当前已完成 4 个低风险批次：入口页 reader-facing 标题统一、内部参考路径去暴露，以及 `Core` / `Game` / `Godot` / `source-generators` 多个页面中“旧文档式对比”提示的直接契约化改写 +- 当前已完成 4 个低风险批次，并在本轮额外完成 1 次 review-driven 收口：入口页 reader-facing 标题统一、内部参考路径去暴露，以及 `Core` / `Game` / `Godot` / `source-generators` 多个页面中“旧文档式对比”提示的直接契约化改写 - 第 2 个已提交批次结束时，branch diff 相对 `origin/main` 为 `13` files / `124` lines；本轮最后一批提交后仍会明显低于 `50` 文件 stop condition -- 当前建议在本轮停止：剩余命中更多是运行时迁移边界或模块 README 之间的正常交叉引用，不再属于同一类可机械批处理的低风险 reader-facing 收口 +- 本轮已确认 `Architecture` 只暴露 `OnInitialize()`，`AbstractArchitecture` 通过 `InstallModules()` 暴露模块注册入口，而组件级 `OnInit()` 仍然是当前有效生命周期 +- 当前建议在本轮停止：PR `#299` 剩余 `Title check` 只是 GitHub 侧 PR 标题元数据提示，不是仓库文件内的阻塞问题 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 +- `2026-04-28` 已抓取 PR `#299` 并复核 latest-head review：`CodeRabbit` 的 `3` 条 open thread 在本地都仍成立，现已分别收口为抽象层入口语义化链接、生命周期入口澄清、以及 active tracking 验证历史归档；`Greptile` / `Gemini Code Assist` 当前无 open thread，`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` 等独立栏目入口。 - `2026-04-25` `GFramework.Core/README.md`、`GFramework.Ecs.Arch/README.md`、`GFramework.Game/README.md` 当前把 XML 阅读表统一收敛为“代表类型 + 阅读重点”，不再暴露日期、覆盖计数或 `已覆盖` 这类治理式字段。 @@ -63,6 +65,7 @@ - 当前 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` 当前仅剩 `Title check` inconclusive；这需要直接修改 GitHub 上的 PR 标题，而不是继续改仓库文件。 ## 归档指针 @@ -76,220 +79,31 @@ `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` - 时间线归档（`RP-023` 到 `RP-025`）： `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md` +- 验证历史归档（`RP-041` 到 `RP-048`）： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` ## 最新验证 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/query.md` - - 结果：通过；Core query 页去旧文档对比表述后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/command.md` - - 结果：通过；Core command 页改成直接陈述当前输入契约后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/context.md` - - 结果：通过；Core context 页去旧总线入口对比表述后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md` - - 结果：通过；Game scene 页改成直接提示当前语义边界后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` - - 结果：通过；Godot UI 页默认语义与入口说明收口后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/priority-generator.md` - - 结果：通过；Priority 生成器页改成直接陈述当前 API 形态后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` - - 结果：通过；Core lifecycle 页旧入口提示收口后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md` - - 结果：通过；Godot scene 页默认入口说明收口后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/context-aware-generator.md` - - 结果：通过；ContextAware 生成器页路径差异说明收口后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 batch boot 第 3、4 批次的 10 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md` - - 结果：通过；Game UI 页去 `ai-libs/` 路径化说明后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md` - - 结果：通过；Godot signal 页改成项目侧示例口吻后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/godot-project-generator.md` - - 结果：通过；Godot project 生成器页去内部参考项目路径后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/get-node-generator.md` - - 结果：通过；GetNode 生成器页改成通用项目侧用法说明后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md` - - 结果：通过；BindNodeSignal 生成器页去具体内部项目名后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md` - - 结果：通过；导出集合自动注册页改成通用入口描述后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 batch boot 第 2 批次的 6 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 -- `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` - - 结果：通过；Godot 集成教程的措辞收口后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md` - - 结果：通过；Godot 扩展页去自我指涉表述后页面 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 PR `#296` review 收口后的站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-27` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#296` 处于 `OPEN`，latest head review 共有 `4` 条 open thread，其中 `3` 条文档问题与 `1` 条措辞 nitpick 在本地复核后仍成立；测试汇总为 `2156 passed`，仅剩 `Title check` inconclusive。 -- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` - - 结果：通过；PR `#290` 处于 `OPEN`，latest head commit `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181` 有 `2` 条 open thread（CodeRabbit `1`、Greptile `1`），测试汇总为 `2156 passed`，无 failed checks。 -- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` - - 结果：通过；PR `#292` 处于 `OPEN`，latest head commit `b96565ffa367bade30f44c2d4e8955143fbff85e` 有 `2` 条 CodeRabbit open thread，测试汇总为 `2156 passed`，无 failed tests；另有 `Title check` inconclusive，属于 PR 标题元数据问题，不是仓库文件阻塞。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md` - - 结果：通过；本轮 3 个模块 README 调整后链接目标仍然有效。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.Abstractions/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch.Abstractions/README.md` - - 结果：通过；4 个公开模块 README 的 reader-facing 改写后链接目标仍然有效。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started` - - 结果：通过；`installation.md` 更新后 `getting-started` 栏目的 frontmatter、链接与代码块校验均通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md` - - 结果：通过；`config-system.md` 的工具形态建议改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic` - - 结果：通过；基础教程入口的阅读路径改写后栏目校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md` - - 结果：通过；本轮 5 个模块 README 的 reader-facing 术语与入口改写后链接目标有效。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.md` - - 结果：通过；教程页受众表述改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` - - 结果：通过；Godot UI 页的接法示例与 reader-facing 术语改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md` - - 结果：通过；Godot 场景页的接法示例与 reader-facing 术语改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md` - - 结果：通过；信号页切回站内生成器入口后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions` - - 结果：通过；3 个抽象层页改回站内入口后栏目校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` - - 结果：通过；生成器栏目及受影响专题页改回站内入口后栏目校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` - - 结果：通过；Core 入口页 reader-facing 改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` - - 结果：通过；Game 入口页 reader-facing 改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` - - 结果：通过；API 入口页导航改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started/quick-start.md` - - 结果：通过；快速开始页切回站内安装入口后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` - - 结果：通过；CQRS 页继续阅读入口改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md` - - 结果：通过；Game 场景页相关推荐改回站内入口后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.md` - - 结果：通过；Game UI 页相关推荐改回站内入口后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` - - 结果：通过；ECS Arch 页入口改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md` - - 结果：通过；Godot 集成教程的接线口吻改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md` - - 结果：通过；设置系统页初始化语义改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.md` - - 结果：通过；序列化页生命周期说明改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md` - - 结果：通过；Godot landing page 的采用说明改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/architecture.md` - - 结果：通过；Godot 架构页异步初始化口吻改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` - - 结果：通过；Godot 存储页示例口吻改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md` - - 结果：通过；Godot 日志页 provider 接线说明改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` - - 结果：通过；Godot 设置页 applicator 接线口吻改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md` - - 结果：通过；Godot 扩展页边界说明改写后页面校验通过。 -- `2026-04-27` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/architecture.md` - - 结果：通过；Core 架构页旧初始化入口改写后页面校验通过。 -- `2026-04-27` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 README、安装页与公开文案改写后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-25` `bun run build`（工作目录：`docs/`） - - 结果：通过；移除 `api-reference` 侧栏重复项并统一 `source-generators` 标签后站点仍可正常构建，仅保留既有大 chunk warning。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md` - - 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials` - - 结果：通过；本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices` - - 结果：通过；`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` - - 结果：通过；错误输出与完整错误信息块补齐为 `text` 后页面验证通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` - - 结果：通过；嵌套 fenced 示例已改写为转义围栏文本，`docs/zh-CN/contributing.md` 不再保留代码块语言警告。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` - - 结果：通过；当前 `docs/zh-CN` 全量 frontmatter、链接与代码块校验均通过，不再保留既有代码块语言警告。 -- `2026-04-25` `bun run build`（工作目录：`docs/`） - - 结果：通过；`contributing.md` 的 Mermaid 示例改写后站点仍可正常构建，仅保留既有大 chunk warning。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` - - 结果：通过；`source-generators` 栏目触达页 frontmatter、链接与代码块校验均通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game` - - 结果：通过；新增 `config-tool.md` 与 `Game` 栏目触达页 frontmatter、链接与代码块校验均通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` - - 结果：通过；`CQRS` 页补充 `Request` / stream 变体与协程入口后链接和代码块校验通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/index.md` - - 结果：通过；首页 hero actions 与 feature 文案更新后 frontmatter、代码块校验通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md tools/gframework-config-tool/README.md GFramework.SourceGenerators.Common/README.md GFramework.Core.SourceGenerators.Abstractions/README.md GFramework.Godot.SourceGenerators.Abstractions/README.md` - - 结果：通过；根 README、config tool README 与新增 3 个 support README 的链接目标有效。 -- `2026-04-25` `dotnet build GFramework.csproj -c Release` - - 结果：通过；元包工程与聚合依赖可编译，输出 `357` 条既有 analyzer warnings，无新增错误。 -- `2026-04-25` `bun run build`（工作目录：`docs/`） - - 结果：通过；meta-package / config tool / source-generators / CQRS 多批次文档更新后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md` - - 结果：通过；`Godot` 资源页剩余 bare opening fence 已补齐语言标记。 -- `2026-04-25` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md` - - 结果：通过；README 链接目标有效。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.SourceGenerators/README.md` - - 结果：通过；README 链接目标有效。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.SourceGenerators/README.md` - - 结果：通过；README 链接目标有效。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Ecs.Arch/README.md` - - 结果：通过；README 链接目标有效。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md` - - 结果：通过；README 链接目标有效。 -- `2026-04-25` `rg -n '\\[[^\\]]*(README\\.md|\\.md|\\.md/|/zh-CN/[^\\]]*)\\]\\([^)]*\\)' GFramework.Core/README.md GFramework.Core.SourceGenerators/README.md GFramework.Cqrs.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Game.SourceGenerators/README.md` - - 结果：无命中；本轮 5 个 README 已无可见路径式 / 文件名式 Markdown 链接标签残留。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core` - - 结果：通过；`Core` 栏目本轮触达页面的 frontmatter、链接与代码块校验均通过。 -- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic` - - 结果：通过；基础教程栏目本轮触达页面的 frontmatter、链接与代码块校验均通过。 -- `2026-04-25` `bun run build`（工作目录：`docs/`） - - 结果：通过；README 标签修正与 `Core` / 基础教程代码块语言标记补齐后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-24` `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 元数据提示。 -- `2026-04-24` `rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(? ## 推荐做法 - 新代码优先使用 `InitializeAsync()` / `DestroyAsync()` -- 把注册逻辑放在 `OnInitialize()`，不要继续使用 `Init()` 这类旧入口 +- 把架构级注册逻辑放在 `OnInitialize()`；组件自己的初始化仍然使用 `OnInit()`，不要再尝试重写 `Init()` 这类旧入口 - 让 `Utility` 承载底层能力，让 `Model` 承载状态，再让 `System` 消费两者 - 跨组件阶段逻辑优先写成 `IArchitectureLifecycleHook` diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 74c55162..1db47803 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -150,7 +150,7 @@ if (!arch.IsInitialized) // ✅ 更好：使用单例模式 public class GameArchitecture : Architecture<GameArchitecture> { - protected override void Init() + protected override void OnInitialize() { // 注册组件 } @@ -176,7 +176,7 @@ InvalidOperationException: No service for type 'IPlayerService' has been registe // ❌ 错误：未注册服务 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { // 忘记注册 IPlayerService } @@ -187,7 +187,7 @@ var service = arch.GetService<IPlayerService>(); // 抛出异常 // ✅ 正确：先注册服务 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { // 注册服务 RegisterService<IPlayerService, PlayerService>(); @@ -216,14 +216,14 @@ NullReferenceException: Object reference not set to an instance of an object ```csharp // ❌ 错误：SystemB 依赖 ModelA，但 ModelA 后注册 -protected override void Init() +protected override void OnInitialize() { RegisterSystem(new SystemB()); // SystemB.OnInit() 中访问 ModelA 失败 RegisterModel(new ModelA()); } // ✅ 正确：先注册依赖项 -protected override void Init() +protected override void OnInitialize() { // 1. 先注册 Model RegisterModel(new ModelA()); @@ -306,7 +306,7 @@ var model = arch.GetModel(); // 抛出异常 // ✅ 正确：先注册再获取 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { RegisterModel(new PlayerModel()); // 注册模型 } @@ -523,7 +523,7 @@ arch.RegisterEvent<GameEvent>(OnGameEvent); 3. **检查事件总线是否正确注册**： ```csharp -protected override void Init() +protected override void OnInitialize() { // 确保注册了事件总线 RegisterSystem(new EventBusModule()); @@ -825,7 +825,7 @@ else // ✅ 使用资源管理器 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { RegisterSystem(new ResourceManager()); } @@ -1153,7 +1153,7 @@ public partial class Player : Node // ✅ 使用 Godot 模块 public class GameArchitecture : AbstractArchitecture { - protected override void Init() + protected override void InstallModules() { // 注册 Godot 模块 this.RegisterGodotModule<PlayerModule>(); @@ -1176,7 +1176,7 @@ await uiRouter.PushAsync("MainMenu"); // 失败：页面未注册 // ✅ 正确：先注册 UI 页面 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { var uiRegistry = new GodotUiRegistry(); uiRegistry.Register("MainMenu", "res://ui/main_menu.tscn", UiLayer.Page); @@ -1467,7 +1467,7 @@ _coroutineQueue.Enqueue(MyCoroutine()); // 使用 GFramework 日志系统 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { // 注册日志工厂 RegisterUtility<ILoggerFactory>(new GodotLoggerFactory()); @@ -1554,7 +1554,7 @@ public class EventTracer : AbstractSystem // 在架构中启用事件追踪 #if DEBUG -protected override void Init() +protected override void OnInitialize() { RegisterSystem(new EventTracer()); } @@ -1679,7 +1679,7 @@ System.Collections.Generic.KeyNotFoundException: 未找到类型为 'PlayerModel // 在架构中注册组件 public class GameArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { RegisterModel(new PlayerModel()); RegisterSystem(new PlayerSystem()); @@ -1745,7 +1745,7 @@ var model = this.GetModel<PlayerModel>(); // 返回 null model.Health.Value = 100; // 抛出异常 // ✅ 正确：先注册 -protected override void Init() +protected override void OnInitialize() { RegisterModel(new PlayerModel()); } @@ -1814,20 +1814,20 @@ System.ArgumentException: An item with the same key has already been added. Key: ```csharp // ❌ 错误：重复注册 -protected override void Init() +protected override void OnInitialize() { RegisterModel(new PlayerModel()); RegisterModel(new PlayerModel()); // 重复注册 } // ✅ 正确：只注册一次 -protected override void Init() +protected override void OnInitialize() { RegisterModel(new PlayerModel()); } // ✅ 如果需要多个实例，使用不同的键 -protected override void Init() +protected override void OnInitialize() { RegisterModel(new PlayerModel(), "Player1"); RegisterModel(new PlayerModel(), "Player2"); diff --git a/docs/zh-CN/tutorials/large-project-organization.md b/docs/zh-CN/tutorials/large-project-organization.md index c58f5fa2..38e54a9e 100644 --- a/docs/zh-CN/tutorials/large-project-organization.md +++ b/docs/zh-CN/tutorials/large-project-organization.md @@ -162,7 +162,7 @@ namespace MyGame.Core.Architecture { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; @@ -857,7 +857,7 @@ namespace MyGame.Core.Architecture { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; diff --git a/docs/zh-CN/tutorials/pause-system.md b/docs/zh-CN/tutorials/pause-system.md index 42fd0c6c..ac06287f 100644 --- a/docs/zh-CN/tutorials/pause-system.md +++ b/docs/zh-CN/tutorials/pause-system.md @@ -38,7 +38,7 @@ namespace MyGame { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; @@ -631,7 +631,7 @@ namespace MyGame { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; diff --git a/docs/zh-CN/tutorials/resource-management.md b/docs/zh-CN/tutorials/resource-management.md index 30f99674..dad394d2 100644 --- a/docs/zh-CN/tutorials/resource-management.md +++ b/docs/zh-CN/tutorials/resource-management.md @@ -220,7 +220,7 @@ namespace MyGame { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; diff --git a/docs/zh-CN/tutorials/save-system.md b/docs/zh-CN/tutorials/save-system.md index 604b43a6..b2ecfca5 100644 --- a/docs/zh-CN/tutorials/save-system.md +++ b/docs/zh-CN/tutorials/save-system.md @@ -671,7 +671,7 @@ namespace MyGame { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; diff --git a/docs/zh-CN/tutorials/state-machine-tutorial.md b/docs/zh-CN/tutorials/state-machine-tutorial.md index 9a62f204..993e670d 100644 --- a/docs/zh-CN/tutorials/state-machine-tutorial.md +++ b/docs/zh-CN/tutorials/state-machine-tutorial.md @@ -356,7 +356,7 @@ namespace MyGame { public static IArchitecture Interface { get; private set; } - protected override void Init() + protected override void OnInitialize() { Interface = this; From 9888f8094500fa89690e8cfee033c2e289b2f8cd Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Tue, 28 Apr 2026 11:05:44 +0800 Subject: [PATCH 5/5] =?UTF-8?q?docs(ai-plan):=20=E6=94=B6=E5=8F=A3PR299?= =?UTF-8?q?=E5=89=A9=E4=BD=99=E8=BF=BD=E8=B8=AA=E5=BD=92=E6=A1=A3=E9=97=AE?= =?UTF-8?q?=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 active tracking 与 latest validation，改为记录 PR #299 当前仅剩的 ai-plan review 项。 - 归档 RP-041 到 RP-048 的 trace 时间线，并把 active trace 收敛为恢复点、验证摘要与下一步。 - 补充 PR review 抓取与 docs 站点构建结果，保持本轮收口具备可追溯验证记录。 --- ...ion-history-rp-041-to-rp-048-2026-04-28.md | 12 ++ ...ace-history-rp-041-to-rp-048-2026-04-28.md | 55 ++++++++ ...ation-full-coverage-governance-tracking.md | 26 ++-- ...entation-full-coverage-governance-trace.md | 121 ++++-------------- 4 files changed, 100 insertions(+), 114 deletions(-) create mode 100644 ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md index e784a06e..bf5a670e 100644 --- a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md @@ -1,5 +1,17 @@ # Documentation Full Coverage Governance Validation History (RP-041 to RP-048) +## 2026-04-28 / RP-048 active tracking follow-up + +### PR review 抓取 + +- `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。 + +### 站点构建 + +- `bun run build`（工作目录：`docs/`） + - 结果：通过；active tracking 收口与时间线归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 + ## 2026-04-28 / RP-048 ### PR review 抓取 diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md new file mode 100644 index 00000000..eeb27845 --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md @@ -0,0 +1,55 @@ +# Documentation Full Coverage Governance Trace History (RP-041 to RP-048) + +## Scope + +- 该归档记录 `RP-041` 到 `RP-048` 从 active trace 迁出的阶段性时间线，保留每轮恢复点、主要决策与停止条件。 +- 逐命令验证明细继续保存在： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` + +## 2026-04-28 / RP-048 + +- 通过 `$gframework-pr-review` 重新抓取 PR `#299` 后确认：latest head review 只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，且都指向 active tracking 文档，而非公开文档页面本身。 +- 本地复核确认此前对抽象层入口语义化链接、生命周期入口示例与教程 / 排障页的修正已不再构成当前 remote latest-head review 的剩余阻塞。 +- 因此本轮收敛为 active tracking 收口：补齐 `RP-048` 下一步，并将 `RP-045` 到 `RP-047` 的逐命令历史从 active trace 下沉到 archive。 + +## 2026-04-27 / RP-047 + +- 第 `2` 批次提交 `2d2cd0c` 后，branch diff 相对 `origin/main` 为 `13` files / `124` lines，仍明显低于 `$gframework-batch-boot 50` 的 stop condition。 +- 最后一批集中收口 `core/query.md`、`core/command.md`、`core/context.md`、`game/scene.md`、`godot/ui.md`、`source-generators/priority-generator.md`、`core/lifecycle.md`、`game/ui.md`、`godot/scene.md`、`source-generators/context-aware-generator.md` 中依赖“旧文档 / 旧入口”对比的句式。 +- 在这里停止，不是因为达到阈值，而是因为剩余命中已转成需要人工判断是否保留迁移边界或 README 交叉引用的问题。 + +## 2026-04-27 / RP-046 + +- 第 `1` 批次提交 `c56260b` 后，branch diff 相对 `origin/main` 为 `7` files / `68` lines，仍远低于 stop condition。 +- 本轮继续处理 `docs/zh-CN/game/ui.md`、`godot/signal.md` 以及 `4` 个 source-generators 专题页，把直接暴露 `ai-libs/CoreGrid` 路径的公开说明改写为项目侧常见实现或典型入口组织方式。 +- 决策上继续保持单页文字级边界，不把 `ai-libs/**` 当成公开导航或消费者说明，并在每个稳定批次校验通过后立即提交，以便精确计量 branch diff。 + +## 2026-04-27 / RP-045 + +- 通过 `$gframework-batch-boot 50` 从零 diff 状态重新进入，沿用显式 `--git-dir` / `--work-tree` 绑定，确认当前分支仍为 `docs/sdk-update-documentation`，baseline 固定到最新本地 `origin/main` `7cfdd2c`。 +- 第 `1` 批次先处理 `docs/zh-CN/source-generators/index.md`、`game/index.md`、`api-reference/index.md`、`godot/setting.md`、`abstractions/index.md` 的 reader-facing 标题、描述与导航措辞，不改示例代码，也不扩栏目结构。 +- 当轮下一候选批次被限定为继续清理 `ai-libs/CoreGrid` 与“旧文档”式指向表达，保持风险最低且适合批处理。 + +## 2026-04-27 / RP-044 + +- 本轮从 `$gframework-pr-review` 重新进入，抓取 PR `#296` 后确认 latest reviewed commit 为 `5778782df05e22dd24dc95189dd768458afb8537`，共有 `4` 条 open thread。 +- 接受的仍成立问题集中在 `GFramework.Game.SourceGenerators/README.md` 的表头语义、`GFramework.Game/README.md` 的重复 `storage.md` 链接，以及 `docs/zh-CN/tutorials/godot-integration.md`、`docs/zh-CN/godot/extensions.md` 的 reader-facing 措辞收口。 +- 唯一 failed check `Title check` 被明确排除在仓库文件修复范围之外，本轮只做 review 指向文件的最小修正并同步 tracking / trace。 + +## 2026-04-27 / RP-043 + +- 在提交 `docs(reader-facing): 统一站内入口与公开术语` 后，branch diff 已到 `46` changed files，接近 `$gframework-batch-boot 50` 的停止线。 +- 因此最后只接受 `10` 个还没进入 branch diff 的文件，包括 `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` 等维护 / 内部口吻改成当前采用指导，并在验证通过后立即停止扩批。 + +## 2026-04-27 / RP-042 + +- 用户明确允许在 stop condition 内循环推进，并接受使用 subagent 降低主线程上下文压力；主线程保留实现与验证，把热点识别交给 `3` 个 explorer。 +- 接受的结论主要是：入口页应统一为 reader-facing 骨架；GitHub blob README 不应继续作为公开主导航；多个 README 与 Godot 页面还残留 `ai-libs`、`family`、`seam`、`ReadMe.md` 等对外不友好的表述。 +- 基于这些结论，连续落地了入口页改写、README / Godot 页面去内部口吻、以及 GitHub blob README 外链回归站内入口等 `3` 组低风险切片。 + +## 2026-04-27 / RP-041 + +- 这一轮用于提交后重算 branch diff，并确认在继续补一批新文件后，工作树已经来到 `46` changed files，足够触发“接近 stop condition 时收口”的策略。 +- 因此最后批次刻意限制在 `10` 个尚未进入 branch diff 的文件，并保持全部为 reader-facing 文案修正，不扩大到新结构或示例体系重写。 +- 验证通过后，将后续恢复建议切换为“下一轮从 PR review 或剩余未触达细页重新开一轮”，而不是在同一轮继续堆文件数。 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 f47c4dbd..cd39d105 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 @@ -15,17 +15,17 @@ - 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-048` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按 `$gframework-pr-review` 复核 PR `#299` 的 latest-head review，并收口仍然成立的 3 条文件内问题：抽象层入口语义化链接、架构生命周期入口示例、active tracking 验证历史归档瘦身 + - 按 `$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()` 仍然是当前有效生命周期 -- 当前建议在本轮停止：PR `#299` 剩余 `Title check` 只是 GitHub 侧 PR 标题元数据提示，不是仓库文件内的阻塞问题 +- 当前建议在本轮停止：active tracking 收口完成并推送后，只需重新抓取 PR `#299`，确认剩余项是否只剩 GitHub 侧 `Title check` 元数据提示 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-28` 已抓取 PR `#299` 并复核 latest-head review：`CodeRabbit` 的 `3` 条 open thread 在本地都仍成立，现已分别收口为抽象层入口语义化链接、生命周期入口澄清、以及 active tracking 验证历史归档；`Greptile` / `Gemini Code Assist` 当前无 open thread，`Title check` 仍是 PR 元数据问题。 +- `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` 等独立栏目入口。 - `2026-04-25` `GFramework.Core/README.md`、`GFramework.Ecs.Arch/README.md`、`GFramework.Game/README.md` 当前把 XML 阅读表统一收敛为“代表类型 + 阅读重点”，不再暴露日期、覆盖计数或 `已覆盖` 这类治理式字段。 @@ -65,7 +65,7 @@ - 当前 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` 当前仅剩 `Title check` inconclusive；这需要直接修改 GitHub 上的 PR 标题，而不是继续改仓库文件。 +- PR `#299` 在 remote latest-head review 中仍显示 `1` 条 open thread 与 `1` 条 nitpick，直到本轮 `ai-plan` 改动推送后才会反映关闭状态；`Title check` 仍需要直接修改 GitHub 上的 PR 标题。 ## 归档指针 @@ -79,31 +79,23 @@ `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` - 时间线归档（`RP-023` 到 `RP-025`）： `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md` +- 时间线归档（`RP-041` 到 `RP-048`）： + `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` - 验证历史归档（`RP-041` 到 `RP-048`）： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` ## 最新验证 - `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 有 `3` 条 `CodeRabbit` open thread，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 -- `2026-04-28` 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/state-machine-tutorial.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/resource-management.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/save-system.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/pause-system.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/large-project-organization.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` - - 结果：通过；本轮触达页面的 frontmatter、链接与代码块校验均通过。 + - 结果：通过；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/`） - - 结果：通过；PR `#299` review follow-up 的文档修正与 active tracking 归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；active tracking 收口与时间线归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-27` 到 `2026-04-28` 的详细逐命令验证历史已迁入： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` ## 下一步 1. 推送本轮提交后，优先重新抓取 `$gframework-pr-review`，确认 PR `#299` 仅剩标题元数据提示或已全部清空。 -2. 若后续继续文档治理，优先人工复核尚未触达的 `Game` persistence、Godot runtime 细页与少量残余迁移边界表述，而不是继续按关键词机械扩批。 +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` 与相关专题页是否仍保持一致。 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 be2e20a5..928ac302 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 @@ -4,117 +4,44 @@ ### 当前恢复点：RP-048 -- 本轮按 `$gframework-pr-review` 抓取当前 PR `#299`，并确认 latest head review 仍有 `3` 条 `CodeRabbit` open thread；`Greptile` 与 `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 -- 本地复核源码后确认：`GFramework.Core/Architectures/Architecture.cs` 只暴露架构级 `OnInitialize()`；`GFramework.Godot/Architectures/AbstractArchitecture.cs` 通过 `InstallModules()` 暴露模块注册入口；组件级 `OnInit()` 仍是 `Model` / `System` 的正确生命周期。 -- 仍成立的文件内问题只有三类：`docs/zh-CN/abstractions/index.md` 的原始文件名式导航、`docs/zh-CN/core/lifecycle.md` 与 `tutorials` / `troubleshooting` 里的架构级旧 `Init()` 示例、以及 active tracking 中过长的逐命令验证历史。 +- 本轮按 `$gframework-pr-review` 抓取当前 PR `#299`，确认 latest head review 当前只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick；两者都指向 active tracking 文档本身，`Greptile` 与 `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，另有 `Title check` inconclusive。 +- 本地复核后确认：此前针对 `docs/zh-CN/abstractions/index.md`、`docs/zh-CN/core/lifecycle.md` 与相关教程 / 排障页的 review follow-up 已不再是当前 remote latest-head review 的剩余阻塞项。 +- 当前仍需收口的只剩两件事：为 `RP-048` 补齐明确的“下一步”段落，以及把 `RP-045` 到 `RP-047` 的逐命令时间线从 active trace 下沉到归档文件。 ### 当前决策（RP-048） -- 在同一轮里收口所有仍然适用于仓库文件的 open thread；不把 `Title check` 当成仓库文件修复项。 -- 普通 `Architecture` 示例统一改回 `OnInitialize()`，`AbstractArchitecture` 示例改成 `InstallModules()`，组件级 `OnInit()` 示例保持不变。 -- 将 active tracking 的“最新验证”压缩为摘要，把详细命令历史迁入新的 `archive/todos` 文件，避免默认恢复入口继续膨胀。 +- 本轮限定只修改 `ai-plan/public/documentation-full-coverage-governance` 下的 tracking / trace 文档，不再扩展到已经收口的公开文档页面。 +- active trace 只保留当前恢复点、验证结论、下一步与归档指针；`RP-041` 到 `RP-048` 的阶段细节转入专门的 trace archive，逐命令验证继续保留在 validation history archive。 +- 不把 `Title check` 当成仓库文件修复项；本轮完成后只需要在提交推送后重新抓取 PR review，确认 remote 线程状态是否清空。 ### 当前验证（RP-048） - PR review 抓取： - `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 有 `3` 条 `CodeRabbit` open thread，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/state-machine-tutorial.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/resource-management.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/save-system.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/pause-system.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/large-project-organization.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md` - - 结果：通过；本轮触达页面的 frontmatter、链接与代码块校验均通过。 + - 结果：通过；PR `#299` 处于 `OPEN`，latest head review 有 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；PR `#299` review follow-up 的文档修正与 active tracking 归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；active tracking 收口与时间线归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 +- 详细时间线归档： + - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` +- 详细验证归档： + - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` + +### 下一步（RP-048） + +1. 提交本轮 active tracking 收口改动，并将提交推送到 PR `#299`。 +2. 推送后重新抓取 `$gframework-pr-review`，确认 latest-head review 是否只剩 `Title check` 或已全部清空。 +3. 若仍有新的文档 review 线程，继续按 latest-head review 精确收口，不恢复关键词驱动的机械扩批。 ## 2026-04-27 -### 当前恢复点：RP-047 +### 已归档历史（RP-041 到 RP-047） -- 第 2 批次提交 `2d2cd0c` 后，重新计算 branch diff 确认当前相对 `origin/main` 为 `13` files / `124` lines，仍然远低于 `$gframework-batch-boot 50` 的 stop condition。 -- 本轮最后继续接受两组同类低风险文案收口：`core/query.md`、`core/command.md`、`core/context.md`、`game/scene.md`、`godot/ui.md`、`source-generators/priority-generator.md`，以及 `core/lifecycle.md`、`game/ui.md`、`godot/scene.md`、`source-generators/context-aware-generator.md`。 -- 这 10 个页面的共同点是：把“旧文档/旧入口对比”句式改成直接陈述当前契约、默认入口或推荐做法，不引入结构改造，也不删掉真实的迁移边界信息。 - -### 当前决策（RP-047） - -- 将第 3、4 批次合并为本轮最后一个提交，避免继续把批次拆得过碎，同时仍保持文件范围可审阅。 -- 本轮在这里停止，不是因为触达了 `50` 文件阈值，而是因为剩余命中已经从机械可收口的 reader-facing 文案问题，转成是否保留迁移信息或 README 交叉引用的编辑判断题。 -- 下一轮若继续，优先从剩余 `旧文档` / `README.md` / `先理解` 命中里做人工复核，而不是继续按关键词机械替换。 - -### 当前验证（RP-047） - -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/query.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/command.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/context.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/ui.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/priority-generator.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/lifecycle.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/scene.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/context-aware-generator.md` - - 结果：通过；本轮最后 10 个公开页面的 frontmatter、链接与代码块校验均通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 batch boot 第 3、4 批次的 10 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - -### 当前恢复点：RP-046 - -- 第 1 批次提交 `c56260b` 后，重新计算 branch diff 确认当前相对 `origin/main` 为 `7` files / `68` lines，仍远低于 `$gframework-batch-boot 50` 的 stop condition。 -- 基于上一轮搜索结果，本轮继续接收一组同样低风险的公开文案收口：`docs/zh-CN/game/ui.md`、`godot/signal.md` 以及 4 个 source-generators 专题页中直接暴露 `ai-libs/CoreGrid` 路径的段落。 -- 这些页面都只是把内部参考项目路径改写为“项目侧常见实现”或“典型入口组织方式”，不改变示例代码、采用顺序或专题页结构。 - -### 当前决策（RP-046） - -- 第 2 批次继续保持单页文字级修正边界，不把 `ai-libs/**` 当成公开文档里的直接导航或消费者说明。 -- 在站点构建通过后立即提交本批次，以便 branch diff 能继续被 stop condition 精确计量。 -- 当前下一候选批次是清理仍残留在若干公开页面中的“旧文档式对比”提示，继续限定为文案级收口。 - -### 当前验证（RP-046） - -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/ui.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/source-generators/godot-project-generator.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/get-node-generator.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md` - - 结果：通过；本轮 6 个公开页面的 frontmatter、链接与代码块校验均通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 batch boot 第 2 批次的 6 个公开页面 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - -### 当前恢复点：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-045` 到 `RP-047` 的 batch boot 逐阶段时间线、branch diff 计量与 review follow-up 决策，已迁入专门的 trace archive，避免 active trace 继续保留逐命令历史。 +- 对应的页面校验、README 链接校验与站点构建命令，继续保留在 validation history archive 中，供后续追溯。 +- 归档路径： + - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` + - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` ### 当前恢复点：RP-044