mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-06 16:16:44 +08:00
docs(pr-review): 收口文档审查反馈
- 更新 source-generators 侧栏标签并移除 API 参考侧栏中的跨栏目重复入口 - 优化 Core、Ecs.Arch、Game README 的 XML 阅读入口表述，删除覆盖基线式字段 - 补充 documentation-full-coverage-governance 跟踪与验证记录，记录 PR #290 审查收口状态
This commit is contained in:
gewuyou
parent
54b8e5770a
commit
074002254e
@ -62,18 +62,17 @@
|
||||
|
||||
## XML 阅读入口
|
||||
|
||||
截至 `2026-04-22`，下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口；当前主目录族的类型声明都已带
|
||||
XML 注释。更细的参数、返回值和生命周期语义，适合在阅读对应类型与成员时继续结合源码确认。
|
||||
下面这份目录视图可以帮助你快速定位 `GFramework.Core` 的类型级 XML 文档入口。更细的参数、返回值和生命周期语义，适合在阅读对应类型与成员时继续结合源码确认。
|
||||
|
||||
| 类型族 | 基线状态 | 代表类型 |
|
||||
| 类型族 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- |
|
||||
| `Architectures/` `Services/` | `22/22` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ServiceModuleManager` |
|
||||
| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand<TInput>`、`AbstractQuery<TResult>` |
|
||||
| `Events/` `Property/` `State/` `StateManagement/` | `29/29` 个类型声明已带 XML 注释 | `EventBus`、`BindableProperty<T>`、`StateMachine`、`Store<TState>` |
|
||||
| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`PauseStackManager`、`AsyncKeyLockManager` |
|
||||
| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`AbstractObjectPoolSystem<TKey, TObject>` |
|
||||
| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`LocalizationManager`、`ConfigurationManager`、`DefaultEnvironment`、`MicrosoftDiContainer` |
|
||||
| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` |
|
||||
| `Architectures/` `Services/` | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ServiceModuleManager` | 先看架构入口、上下文对象与模块生命周期如何协同 |
|
||||
| `Command/` `Query/` | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand<TInput>`、`AbstractQuery<TResult>` | 看命令 / 查询执行入口、同步异步边界与抽象基类约束 |
|
||||
| `Events/` `Property/` `State/` `StateManagement/` | `EventBus`、`BindableProperty<T>`、`StateMachine`、`Store<TState>` | 看事件分发、状态绑定、状态机与 Store 的职责划分 |
|
||||
| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `CoroutineScheduler`、`CoroutineHandle`、`PauseStackManager`、`AsyncKeyLockManager` | 看调度、暂停、时间推进与并发控制的生命周期语义 |
|
||||
| `Resource/` `Pool/` | `ResourceManager`、`AutoReleaseStrategy`、`AbstractObjectPoolSystem<TKey, TObject>` | 看资源释放策略、池化抽象与可复用对象边界 |
|
||||
| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `ConsoleLogger`、`LocalizationManager`、`ConfigurationManager`、`DefaultEnvironment`、`MicrosoftDiContainer` | 看基础设施入口与默认实现的组合方式 |
|
||||
| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` | 看业务模型、系统基类、上下文辅助类型与函数式工具如何配合 |
|
||||
|
||||
完整的模块化接入说明和阅读顺序见 [Core 栏目](../docs/zh-CN/core/index.md)。
|
||||
|
||||
|
||||
@ -123,12 +123,12 @@ ecsModule.Update(deltaTime);
|
||||
|
||||
下表汇总当前模块 README 与源码可对照的类型级 XML 文档入口，方便先抓住 Arch ECS 集成的关键类型。
|
||||
|
||||
| 类型族 | 代表类型 | XML 状态 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
| 装配入口 | `ArchExtensions` | 已覆盖 | `UseArch(...)` 的时机与返回值 |
|
||||
| 运行时模块 | `ArchEcsModule` | 已覆盖 | `World` 注册、系统排序、销毁顺序 |
|
||||
| 系统桥接层 | `ArchSystemAdapter<T>` | 已覆盖 | `OnArchInitialize`、`OnUpdate`、`OnArchDispose` |
|
||||
| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 已覆盖 | 组件布局、查询写法、最小示例 |
|
||||
| 类型族 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- |
|
||||
| 装配入口 | `ArchExtensions` | `UseArch(...)` 的接入时机、返回值与默认模块拼装方式 |
|
||||
| 运行时模块 | `ArchEcsModule` | `World` 注册、系统排序、销毁顺序与配置对象的消费方式 |
|
||||
| 系统桥接层 | `ArchSystemAdapter<T>` | `OnArchInitialize`、`OnUpdate`、`OnArchDispose` 的生命周期桥接 |
|
||||
| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 组件布局、查询写法与最小更新循环示例 |
|
||||
|
||||
## 对应文档入口
|
||||
|
||||
|
||||
@ -171,16 +171,15 @@
|
||||
|
||||
## XML 阅读入口
|
||||
|
||||
下面这份目录视图汇总了 `2026-04-23` 可直接对照的 `GFramework.Game` 类型级 XML 文档入口：只统计公开 /
|
||||
内部类型声明是否带 XML 注释，用来帮助你确定运行时阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。
|
||||
下面这份目录视图汇总了 `GFramework.Game` 的类型级 XML 文档入口，用来帮助你确定运行时阅读顺序；更细的参数、返回值、异常和生命周期说明，建议继续回到具体类型与成员确认。
|
||||
|
||||
| 子系统 | 基线状态 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Config/` | `26/26` 个类型声明已带 XML 注释 | `YamlConfigLoader`、`ConfigRegistry`、`GameConfigBootstrap`、`YamlConfigSchemaValidator` | 看 YAML 加载、schema 校验、模块接入与热重载边界 |
|
||||
| `Data/` `Storage/` `Serializer/` | `8/8` 个类型声明已带 XML 注释 | `DataRepository`、`SaveRepository<TSaveData>`、`UnifiedSettingsDataRepository`、`FileStorage`、`JsonSerializer` | 看持久化布局、槽位存档、统一设置文件和底层序列化 / 存储实现 |
|
||||
| `Setting/` | `9/9` 个类型声明已带 XML 注释 | `SettingsModel<TRepository>`、`SettingsSystem`、`SettingsAppliedEvent<T>` | 看初始化、应用、保存、重置等设置生命周期编排 |
|
||||
| `Scene/` `UI/` `Routing/` | `10/10` 个类型声明已带 XML 注释 | `SceneRouterBase`、`UiRouterBase`、`SceneTransitionPipeline`、`UiTransitionPipeline`、`RouterBase<TRoute, TContext>` | 看路由基类、转换处理器和项目层需要自己提供的 factory / root 边界 |
|
||||
| `Extensions/` `Internal/` `State/` | `3/3` 个类型声明已带 XML 注释 | `DataLocationExtensions`、`VersionedMigrationRunner`、`GameStateMachineSystem` | 看辅助扩展、内部迁移执行逻辑和游戏态状态机封装 |
|
||||
| 子系统 | 代表类型 | 阅读重点 |
|
||||
| --- | --- | --- |
|
||||
| `Config/` | `YamlConfigLoader`、`ConfigRegistry`、`GameConfigBootstrap`、`YamlConfigSchemaValidator` | 看 YAML 加载、schema 校验、模块接入与热重载边界 |
|
||||
| `Data/` `Storage/` `Serializer/` | `DataRepository`、`SaveRepository<TSaveData>`、`UnifiedSettingsDataRepository`、`FileStorage`、`JsonSerializer` | 看持久化布局、槽位存档、统一设置文件和底层序列化 / 存储实现 |
|
||||
| `Setting/` | `SettingsModel<TRepository>`、`SettingsSystem`、`SettingsAppliedEvent<T>` | 看初始化、应用、保存、重置等设置生命周期编排 |
|
||||
| `Scene/` `UI/` `Routing/` | `SceneRouterBase`、`UiRouterBase`、`SceneTransitionPipeline`、`UiTransitionPipeline`、`RouterBase<TRoute, TContext>` | 看路由基类、转换处理器和项目层需要自己提供的 factory / root 边界 |
|
||||
| `Extensions/` `Internal/` `State/` | `DataLocationExtensions`、`VersionedMigrationRunner`、`GameStateMachineSystem` | 看辅助扩展、内部迁移执行逻辑和游戏态状态机封装 |
|
||||
|
||||
## 最小接入路径
|
||||
|
||||
|
||||
@ -12,25 +12,22 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-035`
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-036`
|
||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||
- 当前焦点：
|
||||
- 按本轮 `$gframework-batch-boot 50` 约束使用最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）作为唯一 baseline，只推进低风险、可切片的 reader-facing 文档治理批次
|
||||
- 已接受 worker 的导航 / 语义化链接批次，提交为 `094e29e`（`docs(docs): 统一中文文档导航与语义化链接文案`）
|
||||
- 当前未提交批次覆盖 `abstractions` reader-facing 标签、`best-practices` / `troubleshooting` / `tutorials` 代码块语言标记、7 个模块 / 根 README 的 reader-facing XML 阅读入口改写，以及 `contributing` / `godot/resource` 的剩余 bare opening fence
|
||||
- 当前批次连同 active tracking / trace 一并落地后，累计 branch diff 将达到 `34 / 50` 个 changed files；虽然仍有 `16` 个文件 headroom，但同类低风险、可重复批处理切片已经基本耗尽
|
||||
- 若继续下一轮，不应再按当前模式盲目扩批，而应先复核 PR / review 状态，再决定是否进入新的非重复性文档巡检波次
|
||||
- 继续以最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）作为 baseline，当前只收口 PR `#290` latest-head review 仍然成立的 reader-facing 文档问题
|
||||
- 已用 `$gframework-pr-review` 重新抓取 PR `#290`（`docs/sdk-update-documentation`），确认 `coderabbitai[bot]` 与 `greptile-apps[bot]` 仍各有 `1` 条 open thread，测试汇总保持 `2156 passed`
|
||||
- 本轮未提交变更聚焦 3 个点：移除 `API 参考` 侧栏里的跨栏目重复入口、统一 3 个 source generator 侧栏标签与目标页标题、删除 `Core` / `Ecs.Arch` / `Game` README 中残留的 XML 覆盖基线表达
|
||||
- 当前批次仍属于低风险 reader-facing 文档治理，但已经从批量“普查”切换为按 PR review 精确收口
|
||||
- 若本轮收口并提交后仍存在 review 线程，应重新抓取最新 PR 状态，再决定是否继续扩展到其他未触达 README 或 docs 巡检点
|
||||
|
||||
## 当前状态摘要
|
||||
|
||||
- `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
|
||||
- `2026-04-25` worker A 已完成并提交 5 个模块 README 的 reader-facing 链接标签修正，提交为 `bd5cdb5`（`docs(readme): 优化链接标签`）；该切片仍作为本 topic 的已接受历史批次保留。
|
||||
- `2026-04-25` 最新 `origin/main` 已推进到 `4ad880c`；当前 `docs/sdk-update-documentation` 相对该 baseline 的已提交 branch diff 为 `7 / 50` 个文件，来自导航与语义化链接批次 `094e29e`。
|
||||
- `2026-04-25` 当前未提交工作树额外覆盖 `25` 个文件：`abstractions` 2 页链接标签、`best-practices` 2 页代码块标记、`troubleshooting` 1 页错误输出标记、`tutorials` 10 页目录树 / 路径 / 输出块标记、根 / 模块 README 8 页 reader-facing 改写，以及 `contributing` / `godot/resource` 2 页剩余 bare opening fence 处理。
|
||||
- `2026-04-25` `docs/.vitepress/config.mts` 已补齐 `abstractions`、`source-generators`、`api-reference` 的中文 sidebar / nav 入口，且 `docs/zh-CN/ecs/arch.md`、`game/*.md`、`godot/*.md` 的原始路径式可见标签已统一为读者可理解的语义化名称。
|
||||
- `2026-04-25` `docs/zh-CN/tutorials` 本轮已额外补齐 10 个非基础教程页的 bare fenced opening 语言标记；目录树、学习路径和控制台输出统一显式标注为 `text`，未改写示例内容。
|
||||
- `2026-04-25` 根 README 与 7 个模块 README 当前已把 `XML 覆盖基线` / `XML 阅读基线` / `inventory` / `后续治理项` 一类 maintainer-facing 标题与导语改为 reader-facing 的“XML 阅读入口 / 推荐优先阅读的 XML 类型族”等表达，保留了现有表格、链接与证据链。
|
||||
- `2026-04-25` 本轮主线程复核后确认：`docs/zh-CN` 中可由统一规则安全处理的 bare opening fence 只剩 `docs/zh-CN/contributing.md:631` 这一处既有嵌套 fenced 示例警告；它不适合继续按当前“只补 opening fence、不碰 closing fence”的批处理规则自动改写。
|
||||
- `2026-04-25` 已重新抓取 PR `#290` 并确认：latest reviewed commit 为 `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181`，open thread 聚焦在 `docs/.vitepress/config.mts` 的侧栏重复 / 标签不一致，以及 `GFramework.Core`、`GFramework.Ecs.Arch`、`GFramework.Game` README 的 reader-facing 表格残留治理字段。
|
||||
- `2026-04-25` `docs/.vitepress/config.mts` 已保留 `source-generators` 栏目自有子页导航，但不再让 `api-reference` 侧栏重复跳回 `core`、`game`、`godot`、`ecs` 等独立栏目入口。
|
||||
- `2026-04-25` `GFramework.Core/README.md`、`GFramework.Ecs.Arch/README.md`、`GFramework.Game/README.md` 当前把 XML 阅读表统一收敛为“代表类型 + 阅读重点”，不再暴露日期、覆盖计数或 `已覆盖` 这类治理式字段。
|
||||
- `2026-04-25` `docs/zh-CN/tutorials`、`best-practices`、`troubleshooting`、`contributing`、`godot/resource` 的前一轮 reader-facing 与代码块标记治理已保持有效；本轮不再扩批这些同模板切片。
|
||||
- `Game` persistence docs surface 当前以 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md`
|
||||
作为最小巡检集合；若后续 README、runtime public API 或 `PersistenceTests` 变动，应优先复核这一组页面。
|
||||
- `Godot` runtime 与 generator 入口当前以 `GFramework.Godot/README.md`、
|
||||
@ -41,13 +38,12 @@
|
||||
|
||||
## 当前风险
|
||||
|
||||
- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 `ai-plan/**`，不应再暴露到公开文档。
|
||||
- 当前 `Core` / `Core.Abstractions`、`Ecs.Arch`、`Cqrs`、`Game` 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 `ai-plan/**`，不应再回流到公开文档。
|
||||
- `GFramework.Cqrs` 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发
|
||||
`MSB4276` / `MSB4018`；这是已知环境阻塞，不属于本轮文档回归。
|
||||
- 当前 WSL 会话里 `git.exe` 可解析但不能执行，应继续使用显式 `--git-dir` / `--work-tree` 绑定作为默认 Git 策略。
|
||||
- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用本轮“只补 opening fence”规则自动改写。
|
||||
- 当前可用的低风险、可重复批处理切片已经基本消耗完毕；如果继续推进，剩余问题更可能落在非重复性 prose 调整、复杂示例结构或远端 review 反馈，不宜按本轮同一批处理模板继续盲扫。
|
||||
- PR `#287` 的 latest-head review 本轮未重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。
|
||||
- `docs/zh-CN/contributing.md:631` 仍有 1 条既有代码块语言警告；该位置属于嵌套 fenced 示例结构，不适合继续沿用前一轮“只补 opening fence”规则自动改写。
|
||||
- PR `#290` 当前 review 线程来自 bot，对 reader-facing 导航和文案一致性的期望比较细；本轮提交后仍需重新抓取 latest-head review，确认是否还有新的 open thread 或旧线程未自动关闭。
|
||||
|
||||
## 归档指针
|
||||
|
||||
@ -64,6 +60,12 @@
|
||||
|
||||
## 最新验证
|
||||
|
||||
- `2026-04-25` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
|
||||
- 结果：通过；PR `#290` 处于 `OPEN`，latest head commit `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181` 有 `2` 条 open thread（CodeRabbit `1`、Greptile `1`），测试汇总为 `2156 passed`，无 failed checks。
|
||||
- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md`
|
||||
- 结果：通过；本轮 3 个模块 README 调整后链接目标仍然有效。
|
||||
- `2026-04-25` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；移除 `api-reference` 侧栏重复项并统一 `source-generators` 标签后站点仍可正常构建，仅保留既有大 chunk warning。
|
||||
- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md`
|
||||
- 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。
|
||||
- `2026-04-25` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials`
|
||||
@ -128,8 +130,8 @@
|
||||
|
||||
## 下一步
|
||||
|
||||
1. 当前 `$gframework-batch-boot 50` 建议在本轮停止：待当前工作树与 active tracking / trace 一并提交后，累计 branch diff 将为 `34 / 50`，但同类低风险、可重复切片已基本耗尽。
|
||||
2. 若继续下一轮，优先重新抓取 `$gframework-pr-review` 确认 PR `#287` 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。
|
||||
1. 完成本轮修改后先跑 `bun run build`（工作目录 `docs/`）与受影响 README 链接校验，再提交当前 PR review 收口批次。
|
||||
2. 提交完成后重新抓取 `$gframework-pr-review` 确认 PR `#290` 的 latest-head review 是否已清空 open thread，再决定是否继续巡检其他 reader-facing 文档。
|
||||
3. 若后续继续处理公开文档，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得做结构化改写，而不是继续沿用“只补 opening fence”的自动批处理规则。
|
||||
4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
|
||||
`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
|
||||
|
||||
@ -2,42 +2,32 @@
|
||||
|
||||
## 2026-04-25
|
||||
|
||||
### 当前恢复点：RP-035
|
||||
### 当前恢复点：RP-036
|
||||
|
||||
- 本轮按 `$gframework-batch-boot 50` 执行，baseline 重新对齐到最新 `origin/main`（`4ad880c`，`2026-04-25 14:35:38 +08:00`）；重新开始时 committed branch diff 为 `0 / 50` 个 changed files。
|
||||
- 已接受 worker 批次 `094e29e`（`docs(docs): 统一中文文档导航与语义化链接文案`），该提交补齐了 `abstractions` / `source-generators` / `api-reference` 的中文导航入口，并修复了 `ecs`、`game`、`godot` 目标页面的路径式可见链接标签。
|
||||
- 主线程接收并复核了 `abstractions` 2 页 reader-facing 链接标签修正、`best-practices` 2 页和 `troubleshooting` 1 页的代码块语言标记补齐，以及 `tutorials` 10 页目录树 / 路径 / 输出块统一显式标记为 `text`。
|
||||
- 主线程还接收了根 README 与 7 个模块 README 的 reader-facing XML 阅读入口改写，并补齐了 `docs/zh-CN/contributing.md`、`docs/zh-CN/godot/resource.md` 的剩余 bare opening fence。
|
||||
- 当前未提交工作树连同 active tracking / trace 一并落地后，累计 branch diff 将达到 `34 / 50` 个 changed files；本轮在未触及阈值的情况下停止，因为同类低风险、可重复批处理切片已基本耗尽。
|
||||
- 本轮从 `$gframework-pr-review` 重新进入，目标不再是扩批，而是核对 PR `#290` latest-head review 仍未关闭的 reader-facing 文档问题。
|
||||
- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#290` 最新 reviewed commit 为 `54b8e5770af9ab3c8a86a396ffa4794fe4bb5181`，CodeRabbit 与 Greptile 各有 `1` 条 open thread，失败检查为 `0`，测试汇总仍为 `2156 passed`。
|
||||
- 本轮把远端 review 与本地工作树逐项比对后，只接受仍然成立的 5 个 reader-facing 问题：`source-generators` 侧栏 3 个标签与目标标题不一致、`api-reference` 侧栏重复暴露跨栏目入口、`Core` / `Ecs.Arch` / `Game` README 仍保留 XML 覆盖基线字段。
|
||||
- 当前未提交批次限定在 `docs/.vitepress/config.mts`、3 个模块 README，以及 active tracking / trace；没有继续扩展到其他未被 review 指向的文档文件。
|
||||
|
||||
### 当前决策（RP-035）
|
||||
### 当前决策（RP-036）
|
||||
|
||||
- 继续沿用“导航 / 链接标签”和“bare opening fence 语言标记”两类低语义风险规则，但拒绝把 closing fence 或复杂嵌套 fenced 结构纳入同一自动批处理模板。
|
||||
- 对 worker 产出的代码块标记批次一律做主线程复核；发现 closing fence 被误改后已在本轮立即纠正，并把后续批次提示词收紧到“只改 opening fence”。
|
||||
- README 治理批次只改 reader-facing 标题、导语和链接可见标签，不删除现有表格、证据链或源码 / 测试导向的阅读线索。
|
||||
- 在 `34 / 50` 之前停止本轮，不是因为 headroom 不足，而是因为自动可识别、风险可控的重复切片已经收敛到仅剩 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 警告；该问题更适合后续人工结构化处理。
|
||||
- 对 PR review 的处理改成“只修当前 latest-head review 仍成立的问题”，不再延续前一轮的批量普查节奏。
|
||||
- `api-reference` 侧栏不再承载跨栏目目录跳转；跨模块导航继续保留在 `docs/zh-CN/api-reference/index.md` 的正文里，避免侧栏在跳出栏目后发生上下文切换。
|
||||
- `source-generators` 侧栏项统一与目标文档的 H1 / frontmatter `title` 对齐，避免同一页面在导航、标题与搜索索引里出现多套命名。
|
||||
- 模块 README 的 XML 阅读表只保留读者有用的“代表类型 / 阅读重点”，把覆盖计数、日期和 `已覆盖` 之类治理痕迹全部留在 `ai-plan/**`。
|
||||
|
||||
### 当前验证（RP-035）
|
||||
### 当前验证（RP-036）
|
||||
|
||||
- PR review 抓取：
|
||||
- `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json`
|
||||
- 结果：通过；PR `#290` 处于 `OPEN`，latest head review 还有 `2` 条 open thread，测试汇总为 `2156 passed`。
|
||||
|
||||
- README / 链接校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md GFramework.Core/README.md GFramework.Core.Abstractions/README.md GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Ecs.Arch.Abstractions/README.md`
|
||||
- 结果：通过；根 README 与本轮触达的模块 README 链接目标有效。
|
||||
- 教程校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials`
|
||||
- 结果：通过；本轮新增触达的 10 个教程页与其余教程页 frontmatter、链接、代码块校验均通过。
|
||||
- 最佳实践校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/best-practices`
|
||||
- 结果：通过；`index.md` 与 `architecture-patterns.md` 的代码块标记补齐后栏目验证通过。
|
||||
- 单页校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/troubleshooting.md`
|
||||
- 结果：通过；错误输出与完整错误信息块补齐为 `text` 后页面验证通过。
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md`
|
||||
- 结果：通过，但保留 `docs/zh-CN/contributing.md:631` 的既有嵌套 fenced 示例警告。
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/resource.md`
|
||||
- 结果：通过；剩余 bare opening fence 已补齐语言标记。
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md`
|
||||
- 结果：通过；本轮 3 个 README 调整后链接目标仍然有效。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；本轮导航补齐、README reader-facing 改写与教程 / 排障 / 资源页代码块语言标记更新后站点仍可构建，仅保留既有大 chunk warning。
|
||||
- 结果：通过；`docs/.vitepress/config.mts` 的侧栏调整后站点仍可构建，仅保留既有大 chunk warning。
|
||||
|
||||
### 归档指针
|
||||
|
||||
@ -49,6 +39,6 @@
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 若继续下一轮，优先重新抓取 `$gframework-pr-review`，确认 PR `#287` 的 latest-head review 是否还有 open thread，再决定是否进入新的非重复性 reader-facing 文档巡检。
|
||||
2. 下一轮若仍要扩批，优先人工评估 `docs/zh-CN/contributing.md:631` 的嵌套 fenced 示例是否值得结构化改写，而不是继续沿用本轮的 opening-fence-only 自动修正规则。
|
||||
3. 当前轮次建议在 `34 / 50` 停止并提交，后续若要继续，应以新的低风险模式或新的热点清单重新建批。
|
||||
1. 完成 `bun run build` 与 README 链接校验后，提交当前 PR `#290` review 收口批次。
|
||||
2. 提交后再次运行 `$gframework-pr-review`，确认 CodeRabbit / Greptile 的 open thread 是否已关闭。
|
||||
3. 若仍有 review 残留，再按 latest-head review 精确收口，不恢复到前一轮的广覆盖批处理模式。
|
||||
|
||||
@ -248,13 +248,13 @@ export default defineConfig({
|
||||
items: [
|
||||
{ text: '概览', link: '/zh-CN/source-generators/' },
|
||||
{ text: '日志生成器', link: '/zh-CN/source-generators/logging-generator' },
|
||||
{ text: '枚举生成器', link: '/zh-CN/source-generators/enum-generator' },
|
||||
{ text: '枚举扩展生成器', link: '/zh-CN/source-generators/enum-generator' },
|
||||
{ text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' },
|
||||
{ text: 'Priority 生成器', link: '/zh-CN/source-generators/priority-generator' },
|
||||
{ text: 'ContextGet 生成器', link: '/zh-CN/source-generators/context-get-generator' },
|
||||
{ text: 'Context Get 注入生成器', link: '/zh-CN/source-generators/context-get-generator' },
|
||||
{ text: '模块自动注册生成器', link: '/zh-CN/source-generators/auto-register-module-generator' },
|
||||
{ text: 'CQRS Handler Registry 生成器', link: '/zh-CN/source-generators/cqrs-handler-registry-generator' },
|
||||
{ text: 'Godot 项目生成器', link: '/zh-CN/source-generators/godot-project-generator' },
|
||||
{ text: 'Godot 项目元数据生成器', link: '/zh-CN/source-generators/godot-project-generator' },
|
||||
{ text: 'GetNode 生成器 (Godot)', link: '/zh-CN/source-generators/get-node-generator' },
|
||||
{ text: 'BindNodeSignal 生成器 (Godot)', link: '/zh-CN/source-generators/bind-node-signal-generator' },
|
||||
{ text: 'AutoUiPage 生成器', link: '/zh-CN/source-generators/auto-ui-page-generator' },
|
||||
@ -276,21 +276,6 @@ export default defineConfig({
|
||||
}
|
||||
],
|
||||
|
||||
'/zh-CN/api-reference/': [
|
||||
{
|
||||
text: 'API 参考',
|
||||
items: [
|
||||
{ text: '概览', link: '/zh-CN/api-reference/' },
|
||||
{ text: 'Core 栏目', link: '/zh-CN/core/' },
|
||||
{ text: 'Game 模块总览', link: '/zh-CN/game/' },
|
||||
{ text: 'Godot 模块总览', link: '/zh-CN/godot/' },
|
||||
{ text: 'ECS 模块总览', link: '/zh-CN/ecs/' },
|
||||
{ text: '抽象接口', link: '/zh-CN/abstractions/' },
|
||||
{ text: '源码生成器', link: '/zh-CN/source-generators/' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
'/zh-CN/tutorials/': [
|
||||
{
|
||||
text: '教程',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user