mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-06 16:16:44 +08:00
docs(review): 收口PR反馈与技能描述
- 修复 gframework-doc-refresh skill 描述中的 YAML 解析问题 - 补充 Game Scene 与 UI 接入目录和文件约定 - 归档文档治理已闭环 trace 并更新当前恢复点
This commit is contained in:
gewuyou
parent
1239fb4651
commit
ce6bab2301
@ -1,6 +1,6 @@
|
||||
---
|
||||
name: gframework-doc-refresh
|
||||
description: Refresh or reassess GFramework documentation for a source module such as Core, Game, Godot, Cqrs, Ecs.Arch, or their generator/abstraction packages. Use this when the user asks to update module docs, re-evaluate landing pages, fix outdated topic pages, refresh API reference coverage, verify adoption paths against source/tests/README, or compare current docs with ai-libs consumer wiring. Recommended command: /gframework-doc-refresh <module>.
|
||||
description: "Refresh or reassess GFramework documentation for a source module such as Core, Game, Godot, Cqrs, Ecs.Arch, or their generator/abstraction packages. Use this when the user asks to update module docs, re-evaluate landing pages, fix outdated topic pages, refresh API reference coverage, verify adoption paths against source/tests/README, or compare current docs with ai-libs consumer wiring. Recommended command: /gframework-doc-refresh <module>."
|
||||
---
|
||||
|
||||
# Purpose
|
||||
|
||||
@ -0,0 +1,73 @@
|
||||
# Documentation Governance And Refresh Trace Archive RP-001 Through RP-008
|
||||
|
||||
> This archive preserves closed recovery-point history that no longer needs to stay in the default boot trace.
|
||||
> The active trace should point here instead of repeating these completed stages.
|
||||
|
||||
## RP-001 Local-Plan Migration
|
||||
|
||||
- 迁移 `local-plan/` 中的 durable recovery state 到
|
||||
`ai-plan/public/documentation-governance-and-refresh/`
|
||||
- 建立 `todos/`、`traces/`、`archive/todos/` 与 `archive/traces/`
|
||||
- 在 `ai-plan/public/README.md` 中建立
|
||||
`docs/sdk-update-documentation` 到 `documentation-governance-and-refresh` 的映射
|
||||
- 同步记录 `ai-plan-governance` 主题的迁移结论
|
||||
|
||||
## RP-002 Column Landing Pages
|
||||
|
||||
- 复核 `docs/zh-CN/core/index.md`、`game/index.md` 与 `source-generators/index.md`
|
||||
- 对照模块 README 与包拆分关系，重写三个栏目 landing page
|
||||
- 修正 VitePress dead-link 检查中指向 `docs/` 目录外 README 的链接方式
|
||||
- 验证：`cd docs && bun run build`
|
||||
|
||||
## RP-003 Core Topic Pages
|
||||
|
||||
- 核对并重写 `architecture.md`、`context.md`、`lifecycle.md`、`command.md`、`query.md` 与 `cqrs.md`
|
||||
- 移除旧 `Init()`、属性式 `CommandBus` / `QueryBus`、旧 `Input` 赋值式示例和已移除的
|
||||
`RegisterMediatorBehavior` 说明
|
||||
- 将旧 command / query 体系说明收口为兼容路径，并把新功能推荐迁到 `GFramework.Cqrs`
|
||||
- 验证：`cd docs && bun run build`
|
||||
|
||||
## RP-004 PR Review Script Follow-Up
|
||||
|
||||
- 修复 `gframework-pr-review` 把空 `APPROVED` review body 误选为 CodeRabbit review body 的解析路径
|
||||
- 改为在同一提交上优先选择最新非空 CodeRabbit review body
|
||||
- 补齐 `docs/zh-CN/core/index.md` 中 `Godot` 与 `Source Generators` 栏目入口链接
|
||||
- 修正 active trace 重复标题，消除 `MD024/no-duplicate-heading` 噪音
|
||||
- 验证：
|
||||
- `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json`
|
||||
- `cd docs && bun run build`
|
||||
|
||||
## RP-005 Remaining Core High-Risk Topics
|
||||
|
||||
- 核对 `events.md`、`property.md`、`state-management.md`、`coroutine.md` 与 `logging.md`
|
||||
- 重写 `events.md`、`property.md` 与 `logging.md`
|
||||
- 明确 `BindableProperty<T>.Comparer` 按闭合泛型共享，不是实例级配置
|
||||
- 确认 `state-management.md` 与 `coroutine.md` 当前仍可保留
|
||||
- 验证：`cd docs && bun run build`
|
||||
|
||||
## RP-006 Game Scene And UI Topics
|
||||
|
||||
- 核对 `docs/zh-CN/game/scene.md` 与 `docs/zh-CN/game/ui.md`
|
||||
- 重写场景路由文档，明确 `ISceneFactory`、`ISceneRoot`、项目侧 router 与过渡处理器的职责边界
|
||||
- 重写 UI 文档，明确 Page 栈、层级 UI、输入仲裁、World 阻断与暂停语义
|
||||
- 验证：`cd docs && bun run build`
|
||||
|
||||
## RP-007 Core Source Generator Topics
|
||||
|
||||
- 核对 `context-aware-generator.md` 与 `priority-generator.md`
|
||||
- 重写 `[ContextAware]` 文档，说明当前生成成员、provider/实例缓存语义与 `ContextAwareBase` 边界
|
||||
- 重写 `[Priority]` 文档，说明只生成 `IPrioritized`，排序效果取决于调用方是否走 priority-aware API
|
||||
- 验证：`cd docs && bun run build`
|
||||
|
||||
## RP-008 Unified Documentation Refresh Skill
|
||||
|
||||
- 删除旧 `vitepress-*` 公开 skill 定义，建立统一 `.agents/skills/gframework-doc-refresh/`
|
||||
- 新增 `.agents/skills/_shared/module-map.json`，按源码模块而不是文档类型驱动刷新
|
||||
- 重写共享文档标准，固定证据顺序：源码 / XML docs / `*.csproj`、测试、README、当前 docs、`ai-libs/`、归档文档
|
||||
- 新增 `scan_module_evidence.py`，支持模块别名归一化、docs 栏目歧义检测和证据面扫描
|
||||
- 更新 `.agents/skills/README.md`，将统一入口作为推荐工作流
|
||||
- 验证：
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot.SourceGenerators`
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Cqrs`
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py source-generators --json`
|
||||
@ -7,12 +7,12 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-GOVERNANCE-REFRESH-RP-008`
|
||||
- 恢复点编号：`DOCUMENTATION-GOVERNANCE-REFRESH-RP-009`
|
||||
- 当前阶段：`Phase 3`
|
||||
- 当前焦点：
|
||||
- 已建立统一公开 skill：`.agents/skills/gframework-doc-refresh/`
|
||||
- 文档重构入口已从“按 guide/tutorial/api 类型拆 skill”收口为“按源码模块驱动文档刷新”
|
||||
- 旧 `vitepress-*` skill 的模板、规范与校验逻辑已迁入新 skill 或 `_shared/`
|
||||
- PR #268 的当前未解决 review 线程已进入收口：active trace 归档、Game Scene/UI 目录约定补充、skill YAML 修复
|
||||
- 下一轮需要用统一 skill 推进 Godot 相关生成器页面核对
|
||||
|
||||
## 当前状态摘要
|
||||
@ -26,6 +26,8 @@
|
||||
- 旧 `local-plan/` 的详细 todo 与 trace 已迁入主题内 `archive/`
|
||||
- 当前分支 `docs/sdk-update-documentation` 已在 `ai-plan/public/README.md` 建立 topic 映射
|
||||
- active 跟踪文件只保留当前恢复点、活跃事实、风险与下一步，不再重复保存已完成阶段的长篇历史
|
||||
- active trace 已把 RP-001 到 RP-008 的闭环历史归档到
|
||||
`ai-plan/public/documentation-governance-and-refresh/archive/traces/documentation-governance-and-refresh-rp-001-through-rp-008.md`
|
||||
- `core`、`game` 与 `source-generators` 三个栏目入口页现在都以模块 README 与当前包拆分为准
|
||||
- `docs` 站点构建已验证通过，修正了 VitePress 对 `docs/` 目录外相对链接的 dead-link 检查问题
|
||||
- `core` 关键专题页已移除 `Init()`、属性式 `CommandBus` / `QueryBus`、旧 `Input` 赋值式示例和已移除的
|
||||
@ -40,9 +42,9 @@
|
||||
`WithComparer(...)` 当成实例级配置
|
||||
- `docs/zh-CN/core/state-management.md` 与 `coroutine.md` 已按当前 runtime / 测试重新核对，当前内容可继续保留
|
||||
- `docs/zh-CN/game/scene.md` 已改成“真实公开入口、场景栈语义、factory/root 装配、过渡处理器与守卫扩展点”的结构，
|
||||
不再暗示框架自带统一场景注册与完整引擎装配
|
||||
不再暗示框架自带统一场景注册与完整引擎装配；本轮已补充项目侧目录布局、文件命名、最小 wiring 与兼容说明
|
||||
- `docs/zh-CN/game/ui.md` 已改成“Page 栈、layer UI、输入动作仲裁、World 阻断与暂停语义”的结构，明确 `Show(...)`
|
||||
不适用于 `UiLayer.Page`
|
||||
不适用于 `UiLayer.Page`；本轮已补充 router、factory、root、page behavior、params 与 views 的推荐放置约定
|
||||
- 本轮重写后再次执行 `cd docs && bun run build` 通过，当前 `game` 栏目入口与专题页改动没有破坏站点构建
|
||||
- `docs/zh-CN/source-generators/context-aware-generator.md` 已改成“真实生成成员、provider/实例缓存语义、与 `ContextAwareBase` 的边界、测试接法”的结构，
|
||||
不再用旧版简化生成代码替代当前实现
|
||||
@ -50,6 +52,8 @@
|
||||
不再把 `GetAllByPriority<T>()` / `system.Init()` 当作所有场景的默认示例
|
||||
- 本轮重写后再次执行 `cd docs && bun run build` 通过，当前 `source-generators` 栏目改动没有破坏站点构建
|
||||
- `.agents/skills/gframework-doc-refresh/SKILL.md` 已改成标准 YAML frontmatter skill，并明确支持模块输入、证据顺序、输出优先级与验证步骤
|
||||
- `.agents/skills/gframework-doc-refresh/SKILL.md` 的 `description` 已加引号，修复 `Recommended command:` 中冒号导致的
|
||||
invalid YAML skill 加载警告
|
||||
- `.agents/skills/_shared/module-map.json` 已收口为源码模块映射表，覆盖源码目录、测试项目、README、`docs/zh-CN` 栏目与 `ai-libs/` 参考入口
|
||||
- 旧 `vitepress-api-doc`、`vitepress-batch-api`、`vitepress-doc-generator`、`vitepress-guide`、`vitepress-tutorial`、`vitepress-validate`
|
||||
已不再保留为可用公开 skill 定义文件
|
||||
@ -80,13 +84,15 @@
|
||||
|
||||
- 历史跟踪归档：[documentation-governance-and-refresh-history-through-2026-04-18.md](../archive/todos/documentation-governance-and-refresh-history-through-2026-04-18.md)
|
||||
- 历史 trace 归档：[documentation-governance-and-refresh-history-through-2026-04-18.md](../archive/traces/documentation-governance-and-refresh-history-through-2026-04-18.md)
|
||||
- RP-001 到 RP-008 trace 归档：[documentation-governance-and-refresh-rp-001-through-rp-008.md](../archive/traces/documentation-governance-and-refresh-rp-001-through-rp-008.md)
|
||||
|
||||
## 验证说明
|
||||
|
||||
- 旧 `local-plan/` 的详细实施历史与文档站构建结果已迁入主题内归档
|
||||
- active 跟踪文件已按 `ai-plan` 治理规则精简为当前恢复入口
|
||||
- `cd docs && bun run build`
|
||||
- `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json`
|
||||
- `python3 -B .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --branch docs/sdk-update-documentation --format json --json-output /tmp/current-pr-review.json`
|
||||
- `python3 -c "import pathlib, yaml; text = pathlib.Path('.agents/skills/gframework-doc-refresh/SKILL.md').read_text(); yaml.safe_load(text.split('---', 2)[1]); print('yaml-ok')"`
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot.SourceGenerators`
|
||||
- `python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Cqrs`
|
||||
|
||||
@ -1,237 +1,31 @@
|
||||
# Documentation Governance And Refresh 追踪
|
||||
|
||||
## 2026-04-19
|
||||
|
||||
### 阶段：local-plan 迁移收口（RP-001）
|
||||
|
||||
- 复核当前工作树后确认：worktree 根目录仅剩一个 legacy `local-plan/`，其内容属于文档治理与重写主题的
|
||||
durable recovery state，不应继续作为独立根目录入口存在
|
||||
- 按 `ai-plan` 治理规则建立 `ai-plan/public/documentation-governance-and-refresh/` 主题目录，并补齐：
|
||||
- `todos/`
|
||||
- `traces/`
|
||||
- `archive/todos/`
|
||||
- `archive/traces/`
|
||||
- 将原 `local-plan` 中的详细 tracking / trace 迁入主题内历史归档，并为 active 入口只保留当前恢复点、
|
||||
活跃事实、风险与下一步
|
||||
- 在 `ai-plan/public/README.md` 中建立
|
||||
`docs/sdk-update-documentation` -> `documentation-governance-and-refresh` 的 worktree 映射
|
||||
- 同步更新 `ai-plan-governance` 的 tracking / trace，记录本次迁移已验证当前工作树不再依赖 worktree-root
|
||||
`local-plan/`
|
||||
|
||||
### Archive Context
|
||||
|
||||
- 历史跟踪归档：
|
||||
- `ai-plan/public/documentation-governance-and-refresh/archive/todos/documentation-governance-and-refresh-history-through-2026-04-18.md`
|
||||
- 历史 trace 归档：
|
||||
- `ai-plan/public/documentation-governance-and-refresh/archive/traces/documentation-governance-and-refresh-history-through-2026-04-18.md`
|
||||
|
||||
### 下一步（RP-001）
|
||||
|
||||
1. 后续继续该主题时，只从 `ai-plan/public/documentation-governance-and-refresh/` 进入，不再恢复 `local-plan/`
|
||||
2. 若 active 入口再次积累多轮已完成且已验证阶段，继续按同一模式迁入该主题自己的 `archive/`
|
||||
|
||||
## 2026-04-21
|
||||
|
||||
### 阶段：栏目 landing page 收口（RP-002）
|
||||
|
||||
- 依据 `ai-plan/public/README.md` 的 worktree 映射恢复 `documentation-governance-and-refresh` 主题，并确认该分支下一步应优先处理 `docs/zh-CN/core/*`、`game/*` 与 `source-generators/*`
|
||||
- 复核 `docs/zh-CN/core/index.md`、`docs/zh-CN/game/index.md`、`docs/zh-CN/source-generators/index.md` 后确认：这三页仍保留旧版“大而全教程”结构，与当前模块 README、包拆分关系和推荐接入路径明显漂移
|
||||
- 对照 `GFramework.Core/README.md`、`GFramework.Game/README.md`、`GFramework.Core.SourceGenerators/README.md`、
|
||||
`GFramework.Game.SourceGenerators/README.md`、`GFramework.Cqrs.SourceGenerators/README.md` 与
|
||||
`GFramework.Godot.SourceGenerators/README.md`，重写三个栏目 landing page，使其回到“模块定位、包关系、最小接入路径、继续阅读”的可信入口形态
|
||||
- 首次执行 `cd docs && bun run build` 时发现 VitePress 会把跳到 `docs/` 目录外的相对链接判定为 dead link，因此将 landing page 末尾的模块 README 入口改为纯文本路径提示而非站内链接
|
||||
- 第二次执行 `cd docs && bun run build` 通过，说明当前 landing page 重写没有破坏站点构建
|
||||
|
||||
### 当前结论
|
||||
|
||||
- 当前默认导航入口已显著收敛，但专题页仍需逐页按源码与测试继续核对
|
||||
- 后续优先级应从 `core` 专题页开始，再向 `game` 与 `source-generators` 扩展
|
||||
|
||||
### 下一步（RP-002）
|
||||
|
||||
1. 审核 `docs/zh-CN/core/architecture.md`、`context.md`、`lifecycle.md`、`command.md`、`query.md`、`cqrs.md`
|
||||
2. 记录每页的失真点、真实 API 名称与应保留的最小示例
|
||||
3. 完成一轮专题页重写后再次执行 `cd docs && bun run build`
|
||||
|
||||
### 补充：2026-04-21 内容引用迁移
|
||||
|
||||
- 按当前文档治理主题，继续清理活跃规范与面向读者的内容入口中的旧参考仓库命名
|
||||
- `AGENTS.md` 已把“secondary evidence source”从特定项目名收口为 `ai-libs/` 下的已验证只读参考实现
|
||||
- `GFramework.Game/README.md`、`GFramework.Game.Abstractions/README.md` 与
|
||||
`docs/zh-CN/game/index.md` 已同步改为 `ai-libs/` 参考表述，并去掉特定参考项目名称与项目内类型名线索
|
||||
- `documentation-governance-and-refresh` active tracking 已同步把风险缓解中的参考来源更新为
|
||||
`ai-libs/` 下已验证参考实现
|
||||
- 下一次专题页重写时，继续沿用同一表述，不再把特定参考项目名写入新的活跃文档入口
|
||||
|
||||
### 补充：2026-04-21 Core 专题页收口（RP-003）
|
||||
|
||||
- 复核 `docs/zh-CN/core/architecture.md`、`context.md`、`lifecycle.md`、`command.md`、`query.md` 与 `cqrs.md`
|
||||
后确认：这些页面仍大量保留旧 API 叙述，例如 `Init()`、属性式 `CommandBus` / `QueryBus`、旧 `Input`
|
||||
赋值式命令/查询示例，以及已移除的 `RegisterMediatorBehavior`
|
||||
- 对照 `Architecture`、`ArchitectureContext`、`IArchitectureContext`、`ContextAwareBase`、旧
|
||||
`AbstractCommand` / `AbstractQuery` 基类和 `GFramework.Cqrs/README.md` 后，重写上述六个页面
|
||||
- 新版专题页将结构统一为“当前角色、真实公开入口、最小示例、兼容边界、迁移方向”，避免继续复刻旧版大而全教程
|
||||
- `core/context.md` 已明确把 `GameContext` 收束为兼容回退路径，而不是新代码的推荐接法
|
||||
- `core/command.md` 与 `core/query.md` 已明确旧体系仍可用，但新功能应优先走 `GFramework.Cqrs`
|
||||
- `core/cqrs.md` 已与当前 runtime / generator / handler 注册语义对齐，并明确 `RegisterCqrsPipelineBehavior<TBehavior>()`
|
||||
是公开入口
|
||||
- 执行 `cd docs && bun run build` 通过，说明本轮 `core` 专题页重写没有破坏文档站构建
|
||||
|
||||
### 下一步（RP-003）
|
||||
|
||||
### 补充：2026-04-21 PR review 跟进收口（RP-004）
|
||||
|
||||
- 通过 `gframework-pr-review` 复查当前分支 PR 时发现：脚本把同一 head commit 上空 body 的 `APPROVED`
|
||||
review 误当成“最新 review body”，导致 `Nitpick comments` 未被结构化提取
|
||||
- 对照 GitHub API 的 review 列表后，确认真正包含 `Nitpick comments (2)` 的是更早 3 秒提交的
|
||||
`COMMENTED` review；因此调整脚本为“保持最新 review 元数据输出不变，但解析时优先选择同一提交上的最新非空
|
||||
CodeRabbit review body”
|
||||
- 根据重新提取的 Nitpick 内容，补齐 `docs/zh-CN/core/index.md` 里 `Godot` 与 `Source Generators`
|
||||
栏目的可点击链接
|
||||
- 顺手修正 active trace 中重复的 `### 下一步` 标题，消除 `MD024/no-duplicate-heading` 告警，避免后续 PR
|
||||
review 再次把文档治理入口本身标成噪音
|
||||
|
||||
### 验证（RP-004）
|
||||
|
||||
- `python3 .codex/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json`
|
||||
- `cd docs && bun run build`
|
||||
|
||||
### 下一步（RP-004）
|
||||
|
||||
1. 继续处理 `docs/zh-CN/core/events.md`、`property.md`、`state-management.md`、`coroutine.md`、`logging.md`
|
||||
2. 若 active trace 继续累计多个已完成恢复点，按 `archive/traces/` 粒度归档旧阶段细节
|
||||
3. 保持 PR review 跟进时优先验证最新未解决线程、非空 CodeRabbit review body 与 MegaLinter 明确告警
|
||||
|
||||
### 阶段：Core 剩余高风险专题页核对（RP-005）
|
||||
|
||||
- 依据 `documentation-governance-and-refresh` active tracking 的恢复点，继续核对
|
||||
`docs/zh-CN/core/events.md`、`property.md`、`state-management.md`、`coroutine.md`、`logging.md`
|
||||
- 对照 `GFramework.Core/Events/*`、`Property/*`、`Logging/*`、`StateManagement/*`、`Coroutine/*` 以及对应测试后确认：
|
||||
- `events.md`、`property.md` 与 `logging.md` 仍带有旧版“大而全 API 列表”写法，与当前公开入口和推荐边界不匹配
|
||||
- `state-management.md` 与 `coroutine.md` 已和当前 runtime / 测试语义基本对齐，本轮无需为了统一文风做额外重写
|
||||
- 重写 `events.md`，使其回到“上下文入口、`EventBus` / `EnhancedEventBus`、优先级传播、局部事件对象、与 Store / CQRS
|
||||
的边界”的当前结构
|
||||
- 重写 `property.md`，使其回到“字段级响应式值、何时继续使用 `BindableProperty<T>`、何时切到 `Store<TState>`”的当前结构，
|
||||
并补充 `BindableProperty<T>.Comparer` 按闭合泛型共享的兼容注意点
|
||||
- 重写 `logging.md`，使其回到“`LoggerFactoryResolver` 默认行为、`ArchitectureConfiguration` 日志 provider 配置、
|
||||
`IStructuredLogger` / `LogContext`、provider 替换边界”的当前结构
|
||||
- 执行 `cd docs && bun run build` 通过，说明本轮 `core` 专题页收口没有破坏文档站构建
|
||||
|
||||
### 当前结论（RP-005）
|
||||
|
||||
- 本轮计划中的 `core` 剩余高风险页面已完成核对；`state-management` 与 `coroutine` 经复核后可继续保留
|
||||
- `core` 栏目下一步不再需要围绕这五页反复停留，后续重心应转到 `docs/zh-CN/game/*` 与 `docs/zh-CN/source-generators/*`
|
||||
|
||||
### 下一步（RP-005）
|
||||
|
||||
1. 继续核对 `docs/zh-CN/game/*`，优先处理仍引用旧安装方式、旧状态系统或旧 UI / Scene 接法的页面
|
||||
2. 再推进 `docs/zh-CN/source-generators/*`，重点核对生成器 wiring、包关系与最小接入示例
|
||||
3. 若 active trace 继续累计多个已完成恢复点，按 `archive/traces/` 粒度归档旧阶段细节
|
||||
|
||||
### 阶段：Game Scene / UI 专题页收口（RP-006）
|
||||
|
||||
- 依据 `documentation-governance-and-refresh` active tracking 的下一步，优先复核 `docs/zh-CN/game/scene.md` 与
|
||||
`docs/zh-CN/game/ui.md`
|
||||
- 对照 `GFramework.Game.Abstractions/Scene/*`、`GFramework.Game.Abstractions/UI/*`、`GFramework.Game/Scene/SceneRouterBase.cs`、
|
||||
`GFramework.Game/UI/UiRouterBase.cs`、`GFramework.Game/README.md` 与 `ai-libs/CoreGrid` 参考接法后确认：
|
||||
- `scene.md` 仍把场景系统写成框架自带完整注册/装配的一体化方案，没有突出 `ISceneFactory`、`ISceneRoot` 和项目侧
|
||||
router 派生类的责任边界
|
||||
- `ui.md` 仍按旧教程式结构展开，没有清楚区分 `Page` 栈与 `Overlay/Modal/Toast/Topmost` 层级 UI，也缺少当前
|
||||
`UiInteractionProfile`、`TryDispatchUiAction(...)` 与 World 输入阻断语义
|
||||
- 重写 `scene.md`，使其回到“当前公开入口、场景栈语义、最小接入路径、守卫/过渡处理器扩展点、与旧写法的边界”的结构
|
||||
- 重写 `ui.md`，使其回到“页面栈与层级 UI 分流、输入仲裁、暂停/阻断语义、最小接入路径、扩展点”的结构
|
||||
- 新版两页都明确了：factory、root、引擎节点与注册表仍由项目或适配层提供，框架当前提供的是 router 基类与通用编排
|
||||
|
||||
### 验证（RP-006）
|
||||
|
||||
- `cd docs && bun run build`
|
||||
|
||||
### 下一步（RP-006）
|
||||
|
||||
1. 继续核对 `docs/zh-CN/source-generators/*`，优先处理仍引用旧初始化方式、旧聚合包名或过时 generator wiring 的页面
|
||||
2. 重点复核 `priority-generator.md`、`context-aware-generator.md` 与 Godot 相关生成器页面，确认示例仍与当前 runtime /
|
||||
generator 入口一致
|
||||
3. 若 `source-generators` 出现多页连续收口结果，再按恢复点粒度整理 active trace，避免默认入口继续膨胀
|
||||
|
||||
### 阶段：Core Source Generator 关键专题页收口（RP-007）
|
||||
|
||||
- 依据 `documentation-governance-and-refresh` active tracking 的下一步，优先复核
|
||||
`docs/zh-CN/source-generators/context-aware-generator.md` 与 `priority-generator.md`
|
||||
- 对照 `GFramework.Core.SourceGenerators/Rule/ContextAwareGenerator.cs`、`GFramework.Core/Rule/ContextAwareBase.cs`、
|
||||
`GFramework.Core/Extensions/ContextAwareServiceExtensions.cs`、`GFramework.Core.SourceGenerators/Bases/PriorityGenerator.cs`、
|
||||
`GFramework.Core.Abstractions/Architectures/IArchitectureContext.cs` 与相关诊断定义后确认：
|
||||
- `context-aware-generator.md` 仍在展示旧版简化生成代码，没有说明当前实例缓存、类型级共享 provider、同步锁以及
|
||||
`ContextAwareBase` 的不同默认回退路径
|
||||
- `priority-generator.md` 仍把 `[Priority]` 写成“标了就自动改变顺序”的教程式功能说明，并大量使用
|
||||
`GetAllByPriority<T>()`、`system.Init()` 这类不适合作为当前 `IContextAware` 路径默认示例的旧写法
|
||||
- 重写 `context-aware-generator.md`，使其回到“最小用法、当前生成成员、provider 与实例缓存语义、与 `ContextAwareBase`
|
||||
和 Context Get 注入的关系、测试边界”的结构
|
||||
- 重写 `priority-generator.md`，使其回到“只生成 `IPrioritized`、priority-aware API 在不同层上的入口、动态优先级边界、
|
||||
诊断与约束”的结构
|
||||
- 新版两页都明确了：排序效果取决于调用方是否走 priority-aware API；`[ContextAware]` 生成路径与
|
||||
`ContextAwareBase` 不是同一套默认行为
|
||||
|
||||
### 验证（RP-007）
|
||||
|
||||
- `cd docs && bun run build`
|
||||
|
||||
### 下一步（RP-007）
|
||||
|
||||
1. 继续核对 Godot 相关生成器页面，优先处理 `godot-project-generator.md`、`get-node-generator.md` 与
|
||||
`bind-node-signal-generator.md`
|
||||
2. 重点确认 `project.godot`、`AutoLoad` / `InputActions`、`GetNode` / `BindNodeSignal` 示例仍与当前包关系和生成器入口一致
|
||||
3. 若 Godot 页面也出现连续收口结果，再按恢复点粒度整理 active trace，避免默认入口继续膨胀
|
||||
# Documentation Governance And Refresh Trace
|
||||
|
||||
## 2026-04-22
|
||||
|
||||
### 阶段：统一文档编排 skill 收口（RP-008）
|
||||
### 当前恢复点：RP-009
|
||||
|
||||
- 依据当前主题“文档治理 + 持续刷新”的目标，复核 `.agents/skills/` 后确认：现有 `vitepress-api-doc`、
|
||||
`vitepress-batch-api`、`vitepress-doc-generator`、`vitepress-guide`、`vitepress-tutorial` 与
|
||||
`vitepress-validate` 仍保留旧的并列入口模型，其中多数 `SKILL.md` 没有标准 YAML frontmatter，已经不适合作为当前
|
||||
Codex skill 继续公开暴露
|
||||
- 结合当前 `*.csproj`、`docs/zh-CN` 栏目、模块 README 与 `ai-libs/CoreGrid` 参考入口，建立
|
||||
`.agents/skills/_shared/module-map.json`，把文档刷新主输入固定为真实源码模块，而不是 `guide/tutorial/api`
|
||||
之类的文档类型
|
||||
- 重写 `.agents/skills/_shared/DOCUMENTATION_STANDARDS.md`，去掉已经失真的固定页面清单，明确固定证据顺序：
|
||||
1. 源码 / XML docs / `*.csproj`
|
||||
2. 测试与 snapshot
|
||||
3. README
|
||||
4. 当前 `docs/zh-CN`
|
||||
5. `ai-libs/`
|
||||
6. 归档文档
|
||||
- 新增 `.agents/skills/gframework-doc-refresh/`，补齐：
|
||||
- 标准 frontmatter 的 `SKILL.md`
|
||||
- `agents/openai.yaml`
|
||||
- `references/` 下的模块选择、证据顺序与输出策略说明
|
||||
- `templates/` 下的 landing/topic/API/tutorial 骨架
|
||||
- `scripts/scan_module_evidence.py`
|
||||
- 迁移后的文档校验脚本 `validate-*.sh`
|
||||
- `scan_module_evidence.py` 已支持：
|
||||
- 模块名与别名归一化
|
||||
- docs 栏目别名歧义检测
|
||||
- 输出源码、测试、README、docs、`ai-libs/` 的存在性扫描结果
|
||||
- 对 landing/topic/fallback 状态做基础判断，作为后续页面收口入口
|
||||
- `.agents/skills/README.md` 已改成“统一公开入口 + 共享资源”说明，不再把旧 `vitepress-*` skill 当成推荐工作流
|
||||
- 旧 `vitepress-*` skill 文件已删除；目录本身在当前 Windows-backed worktree 上因只读元数据仍可能残留为空目录，但由于
|
||||
`SKILL.md` 已删除，它们不再构成可发现的 skill 入口
|
||||
- 本轮从 PR #268 的最新 review 数据恢复，未发现失败检查；CTRF 报告显示 2139 个测试全部通过
|
||||
- 最新未解决 review 线程要求：
|
||||
- 精简 active trace，避免默认恢复入口继续膨胀
|
||||
- 为 `docs/zh-CN/game/scene.md` 补充项目目录与文件约定
|
||||
- 为 `docs/zh-CN/game/ui.md` 补充项目目录与文件约定
|
||||
- 已闭环 RP-001 到 RP-008 的执行细节已归档到
|
||||
`ai-plan/public/documentation-governance-and-refresh/archive/traces/documentation-governance-and-refresh-rp-001-through-rp-008.md`
|
||||
- 本轮还修复 `.agents/skills/gframework-doc-refresh/SKILL.md` 的 YAML frontmatter，使包含冒号的长描述不再破坏 skill 加载
|
||||
|
||||
### 验证（RP-008）
|
||||
### 当前决策
|
||||
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core`
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Godot.SourceGenerators`
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Cqrs`
|
||||
- `python3 -B .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py source-generators --json`
|
||||
- active trace 只保留当前恢复点、关键事实、验证和下一步；完成阶段继续进入 `archive/traces/`
|
||||
- `scene.md` 与 `ui.md` 的集成说明必须同时覆盖目录布局、文件命名、接口实现关系、最小 wiring 和兼容说明
|
||||
- `gframework-pr-review` 抓取结果以最新未解决 head review thread 为准；旧 summary 或已过期评论只作为参考
|
||||
|
||||
### 当前结论（RP-008）
|
||||
### 验证
|
||||
|
||||
- 当前文档刷新入口已经从“按文档类型拆 skill”转为“按源码模块驱动文档评估与更新”
|
||||
- `ai-libs/` 已正式纳入标准证据链，但仅用于 adoption path 和真实 wiring 参考，不覆盖源码契约
|
||||
- 旧 skill 中仍有价值的模板与校验逻辑已经迁入统一入口或 `_shared/`，后续不需要再维护多套并列说明
|
||||
- `python3 -B .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --branch docs/sdk-update-documentation --format json --json-output /tmp/current-pr-review.json`
|
||||
- `cd docs && bun run build`
|
||||
|
||||
### 下一步（RP-008）
|
||||
### 下一步
|
||||
|
||||
1. 使用 `gframework-doc-refresh` 对 `Godot.SourceGenerators` 做一次真实模块扫描，并据此继续刷新
|
||||
`godot-project-generator.md`、`get-node-generator.md` 与 `bind-node-signal-generator.md`
|
||||
2. 若发现 `module-map.json` 在 Godot 场景下仍缺少别名或 docs 映射，再回补共享映射，而不是在单页文档里硬编码
|
||||
3. 若后续 skill 收口过程继续积累细节，再把迁移细节归档到本 topic 的 `archive/`，保持 active trace 可快速恢复
|
||||
1. 继续使用 `gframework-doc-refresh` 对 `Godot.SourceGenerators` 做真实模块扫描
|
||||
2. 优先刷新 `godot-project-generator.md`、`get-node-generator.md` 与 `bind-node-signal-generator.md`
|
||||
3. 若发现 `module-map.json` 在 Godot 场景下缺少别名或 docs 映射，先回补共享映射，再更新具体页面
|
||||
|
||||
@ -85,6 +85,44 @@ description: 说明 GFramework.Game 场景路由的当前入口、项目侧接
|
||||
|
||||
推荐按下面的顺序接入。
|
||||
|
||||
## 推荐目录与文件约定（项目侧）
|
||||
|
||||
场景系统的目录结构不由框架强制，但建议把“路由编排、实例创建、引擎挂载、业务场景”分开放置，避免后续把
|
||||
`SceneRouterBase` 派生类写成巨型协调器。
|
||||
|
||||
```text
|
||||
Game/Scene/
|
||||
GameSceneRouter.cs
|
||||
GameSceneFactory.cs
|
||||
SceneRoot.cs
|
||||
Scenes/
|
||||
GameplayScene.cs
|
||||
PauseMenuScene.cs
|
||||
Params/
|
||||
GameplayEnterParam.cs
|
||||
Registry/
|
||||
SceneRegistry.cs
|
||||
```
|
||||
|
||||
推荐约定如下：
|
||||
|
||||
- `GameSceneRouter.cs`：项目侧 router，继承 `SceneRouterBase`，只注册 guard、transition handler 和 around handler
|
||||
- `GameSceneFactory.cs`：实现 `ISceneFactory`，负责 `sceneKey -> ISceneBehavior` 的映射与实例创建
|
||||
- `SceneRoot.cs`：实现 `ISceneRoot`，负责把行为对象对应的引擎节点挂到场景容器并移除
|
||||
- `Scenes/*`：放具体业务场景、行为包装器或引擎节点包装类型
|
||||
- `Params/*`：放实现 `ISceneEnterParam` 的进入参数，按业务场景拆分
|
||||
- `Registry/*`：如果项目已有场景表或资源表，建议收口在这里，再由 `GameSceneFactory` 使用
|
||||
|
||||
最小 wiring 通常是：
|
||||
|
||||
```csharp
|
||||
architecture.RegisterUtility<ISceneFactory>(new GameSceneFactory());
|
||||
architecture.RegisterSystem(new GameSceneRouter());
|
||||
```
|
||||
|
||||
然后在 `SceneRoot` 的引擎生命周期就绪点调用 `BindRoot(this)`。如果项目已有不同的资源目录、节点层级或场景注册表，
|
||||
保留原结构即可；只要最终能提供 `ISceneFactory`、`ISceneRoot` 和 `ISceneBehavior`，就不需要为了框架重排所有文件。
|
||||
|
||||
### 1. 准备项目自己的 router
|
||||
|
||||
```csharp
|
||||
|
||||
@ -138,6 +138,44 @@ description: 说明 GFramework.Game UI 路由当前的页面栈、层级 UI、
|
||||
|
||||
## 最小接入路径
|
||||
|
||||
## 推荐目录与文件约定（项目侧）
|
||||
|
||||
UI 系统的接入文件建议按“路由、工厂、根节点、页面行为、入参”拆开。这样可以让 `UiRouterBase` 只承担编排职责，
|
||||
把引擎节点创建和页面业务逻辑留在项目侧。
|
||||
|
||||
```text
|
||||
Game/UI/
|
||||
GameUiRouter.cs
|
||||
GameUiFactory.cs
|
||||
UiRoot.cs
|
||||
Pages/
|
||||
MainMenuPageBehavior.cs
|
||||
SettingsPageBehavior.cs
|
||||
Params/
|
||||
SettingsEnterParam.cs
|
||||
Views/
|
||||
MainMenuView.cs
|
||||
```
|
||||
|
||||
推荐约定如下：
|
||||
|
||||
- `GameUiRouter.cs`：项目侧 router，继承 `UiRouterBase`，只注册 UI transition handler 与 guard
|
||||
- `GameUiFactory.cs`：实现 `IUiFactory`，负责 `uiKey -> IUiPageBehavior` 的映射与实例创建
|
||||
- `UiRoot.cs`：实现 `IUiRoot`，负责按 `UiLayer` 把页面行为挂到真实 UI 容器
|
||||
- `Pages/*PageBehavior.cs`：放实现 `IUiPageBehavior` 的页面行为；使用 Godot 生成器时可由 `AutoUiPage` 相关样板补齐
|
||||
- `Params/*EnterParam.cs`：放实现 `IUiPageEnterParam` 的页面入参
|
||||
- `Views/*`：放项目引擎层视图包装或节点引用，不建议把导航决策写在视图里
|
||||
|
||||
最小 wiring 通常是：
|
||||
|
||||
```csharp
|
||||
architecture.RegisterUtility<IUiFactory>(new GameUiFactory());
|
||||
architecture.RegisterSystem(new GameUiRouter());
|
||||
```
|
||||
|
||||
随后在 `UiRoot` 的引擎生命周期就绪点调用 `_uiRouter.BindRoot(this)`。如果项目已经按功能域组织 UI 文件，也可以保留
|
||||
原目录；关键是让 `*Router` 只做编排、`*Factory` 只做映射与创建、`*Root` 只做容器挂载，页面行为只表达页面自身语义。
|
||||
|
||||
### 1. 提供项目自己的 router
|
||||
|
||||
```csharp
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user