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()`。 ## 最小接入示例