mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-08 17:44:29 +08:00
docs(batch-boot): 收口旧入口对比文案
- 更新 Core、Game、Godot 与 source-generators 多个页面的 reader-facing 契约说明 - 将旧文档和旧入口对比句式改成直接陈述当前默认入口、约束与推荐做法 - 补充 documentation full coverage active topic 的 RP-047 跟踪与验证记录
This commit is contained in:
gewuyou
GeWuYou
parent
3c0ac1858a
commit
289f12f309
@ -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`
|
||||
|
||||
@ -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。
|
||||
|
||||
@ -20,7 +20,7 @@ description: 说明 GFramework.Core.Command 旧命令体系的兼容定位、可
|
||||
- `AbstractCommand<TInput, TResult>`
|
||||
- 有输入、有返回值
|
||||
|
||||
注意一个和旧文档不同的点：泛型命令现在通过构造函数接收输入，而不是依赖 `Input` 可写属性。
|
||||
当前泛型命令通过构造函数接收输入，而不是依赖 `Input` 可写属性。
|
||||
|
||||
## 无输入命令
|
||||
|
||||
|
||||
@ -18,14 +18,14 @@ description: 说明 IArchitectureContext 与 ArchitectureContext 的统一上下
|
||||
|
||||
## 先记住一个事实
|
||||
|
||||
如果你还在找旧文档里的这些属性：
|
||||
如果你正在寻找这些属性式总线入口：
|
||||
|
||||
- `CommandBus`
|
||||
- `QueryBus`
|
||||
- `EventBus`
|
||||
- `Container`
|
||||
|
||||
那说明你看到的是旧写法。当前推荐入口是方法，不是这些属性式总线。
|
||||
当前公开入口是方法，不是这些属性式总线。
|
||||
|
||||
## 组件访问
|
||||
|
||||
|
||||
@ -159,7 +159,7 @@ architecture.PhaseChanged += (_, args) =>
|
||||
## 推荐做法
|
||||
|
||||
- 新代码优先使用 `InitializeAsync()` / `DestroyAsync()`
|
||||
- 把注册逻辑放在 `OnInitialize()`，不要沿用旧文档里的 `Init()`
|
||||
- 把注册逻辑放在 `OnInitialize()`，不要继续使用 `Init()` 这类旧入口
|
||||
- 让 `Utility` 承载底层能力，让 `Model` 承载状态，再让 `System` 消费两者
|
||||
- 跨组件阶段逻辑优先写成 `IArchitectureLifecycleHook`
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ description: 说明 GFramework.Core.Query 旧查询体系的兼容定位、可
|
||||
- `AbstractQuery<TInput, TResult>`
|
||||
- 带输入查询
|
||||
|
||||
与旧文档不同，带输入查询现在通过构造函数接收输入，不再依赖 `Input` 属性赋值。
|
||||
当前带输入查询通过构造函数接收输入，不再依赖 `Input` 属性赋值。
|
||||
|
||||
## 无输入查询
|
||||
|
||||
|
||||
@ -76,7 +76,7 @@ description: 说明 GFramework.Game 场景路由的当前入口、项目侧接
|
||||
- `PopAsync`
|
||||
- 对栈顶执行离开检查，通过后退出并卸载它，再从 `ISceneRoot` 移除，然后恢复新的栈顶。
|
||||
|
||||
当前还有两个容易被旧文档误导的点：
|
||||
当前还有两个容易混淆的点：
|
||||
|
||||
- `SceneRouterBase` 默认不允许同一个 `sceneKey` 在栈中重复存在；内部会先做 `Contains(sceneKey)` 检查
|
||||
- 框架不会替你实现“场景键 -> 具体场景实例”的注册逻辑；这仍然是 `ISceneFactory` 或项目注册表的职责
|
||||
|
||||
@ -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 先仲裁
|
||||
|
||||
|
||||
@ -290,8 +290,7 @@ await sceneRouter.PopAsync();
|
||||
|
||||
### 没有 `GodotSceneRouter`
|
||||
|
||||
仓库当前不存在 `GodotSceneRouter` 类型。旧文档里把它写成默认入口是失真的；实际入口仍然是项目侧继承
|
||||
`SceneRouterBase` 的 router。
|
||||
仓库当前不存在 `GodotSceneRouter` 类型；实际入口仍然是项目侧继承 `SceneRouterBase` 的 router。
|
||||
|
||||
### 没有自动注册所有场景
|
||||
|
||||
|
||||
@ -68,7 +68,7 @@ Godot runtime 的页面行为包装基类。它把 `IUiPageBehavior` 的这些
|
||||
- `UiLayer.Toast` -> `ToastLayerUiPageBehavior<T>`
|
||||
- `UiLayer.Topmost` -> `TopmostLayerUiPageBehavior<T>`
|
||||
|
||||
几个容易被旧文档写偏的默认语义如下：
|
||||
几个容易混淆的默认语义如下：
|
||||
|
||||
- `Page`
|
||||
- 不可重入，阻断输入
|
||||
@ -319,7 +319,7 @@ uiRouter.Hide(handle, UiLayer.Modal);
|
||||
|
||||
### 没有 `GodotUiRouter`
|
||||
|
||||
仓库当前没有这个类型。旧文档把它写成默认入口是不准确的；真实入口仍然是项目侧的 `UiRouterBase` 派生类。
|
||||
仓库当前没有这个类型；真实入口仍然是项目侧的 `UiRouterBase` 派生类。
|
||||
|
||||
### UI 工厂不会自动补 behavior
|
||||
|
||||
|
||||
@ -102,7 +102,7 @@ public partial class PlayerController : IController
|
||||
- 不维护共享 provider
|
||||
- 默认直接回退到 `GameContext.GetFirstArchitectureContext()`
|
||||
|
||||
因此，旧文档里把两条路径混写成“只是写法不同”已经不准确。
|
||||
因此，这两条路径不是“只是写法不同”，而是共享 provider 策略和实例缓存边界都不同。
|
||||
|
||||
## 何时使用 `[ContextAware]`
|
||||
|
||||
|
||||
@ -68,7 +68,7 @@ var handlers = container.GetAllByPriority<IMyHandler>();
|
||||
- `this.GetModelsByPriority<TModel>()`
|
||||
- `this.GetUtilitiesByPriority<TUtility>()`
|
||||
|
||||
这比旧文档里反复出现的 `this.GetAllByPriority<T>()` 更贴近当前公开扩展方法。
|
||||
当前公开扩展方法就是按角色拆分的这些 API，而不是泛化的 `this.GetAllByPriority<T>()`。
|
||||
|
||||
## 最小接入示例
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user