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]` 处理。 ## 诊断与约束