docs(batch-boot): 收口公开文档中的内部参考路径

- 更新 Game、Godot 与 source-generators 多个专题页的 reader-facing 示例口吻

- 移除 ai-libs CoreGrid 路径在公开页面中的直接暴露,保留项目侧常见实现说明

- 补充 documentation full coverage active topic 的 RP-046 跟踪与验证记录
This commit is contained in:
gewuyou 2026-04-27 17:33:36 +08:00 committed by GeWuYou
parent 0722ba6dbd
commit 3c0ac1858a
8 changed files with 52 additions and 10 deletions

View File

@ -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`

View File

@ -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`)。

View File

@ -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

View File

@ -120,7 +120,7 @@ private void OnStartPressed()
- 运行时选出的 signal 名称
- 需要临时追加监听的 dock、panel、overlay
`ai-libs/CoreGrid` 当前就有这类用法
项目侧常见也会这样写
```csharp
_quitConfirmDialog.Signal("Confirmed")

View File

@ -161,7 +161,7 @@ public List<IntConfig>? Values { get; } = new();
## 真实采用路径
`ai-libs/CoreGrid/global/GameEntryPoint.cs` 是当前最直接的消费者参考
一个典型的项目侧入口会这样组织导出集合
- `UiPageConfigs`
- `GameSceneConfigs`

View File

@ -130,7 +130,7 @@ private void OnAnyButtonPressed()
当前生成器会为每个特性都生成一条 `+=` 和一条 `-=`
`ai-libs/CoreGrid` 里的 `GameplayHud``PauseMenu``OptionBrowser` 都在大量使用这种声明式绑定方式。
项目侧的 HUD、菜单和选项面板节点通常都会大量使用这种声明式绑定方式。
## 与 GetNode 的协作边界

View File

@ -179,7 +179,7 @@ public override void _Ready()
先注入节点,再绑定事件;否则 `BindNodeSignal` 对应的字段还没完成解析。
这也是 `ai-libs/CoreGrid` 里项目侧节点类的实际用法。
这也是项目侧节点类的常见接法。
## 什么时候适合用 `[GetNode]`

View File

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