From 103b961e6fa030bdc113b37d2c9b5af83ed44e3f Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 30 Apr 2026 09:50:48 +0800 Subject: [PATCH 1/7] =?UTF-8?q?docs(source-generators):=20=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E7=94=9F=E6=88=90=E5=99=A8=E4=B8=93=E9=A2=98=E8=A6=86?= =?UTF-8?q?=E7=9B=96=E5=B9=B6=E6=9B=B4=E6=96=B0=E8=BF=9B=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 Schema 配置生成器专题页，补充输入契约、生成物与诊断边界 - 更新 source-generators、API 参考与 CQRS 文档，说明共享支撑层阅读路线与 fallback 分层 - 更新 documentation-full-coverage-governance 的 tracking 和 trace，记录批次指标与验证结果 --- ...ation-full-coverage-governance-tracking.md | 28 ++- ...entation-full-coverage-governance-trace.md | 33 +++ docs/.vitepress/config.mts | 1 + docs/zh-CN/api-reference/index.md | 20 +- docs/zh-CN/core/cqrs.md | 5 + .../cqrs-handler-registry-generator.md | 35 +++ docs/zh-CN/source-generators/index.md | 15 +- .../schema-config-generator.md | 200 ++++++++++++++++++ 8 files changed, 330 insertions(+), 7 deletions(-) create mode 100644 docs/zh-CN/source-generators/schema-config-generator.md 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 27deef8a..60f7c878 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,10 +12,14 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-050` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-051` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，收口 `Game` / `Godot` 细页与少量 README 中残留的 reader-facing 措辞与标签问题 + - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，在保持 reader-facing 口吻治理的同时，继续补 `source-generators` / `CQRS` 的公开专题覆盖率 +- `2026-04-30` 本轮恢复时确认当前 `HEAD` 与 `origin/main` 同步，committed diff 为 `0` files / `0` lines；因此本批次不再只做措辞收口，而是允许补新的公开专题页和入口链路 +- `2026-04-30` 本轮接受 2 个 explorer 的只读结论：其一，`GFramework.SourceGenerators.Common` 更适合作为 landing / API 入口内的共享排障层，而不是新的独立 public page；其二，`Cqrs.SourceGenerators` 当前主要缺口不是“没有入口”，而是现有专题页与 `core/cqrs.md` 对生成策略层级、fallback 精度和 `GF_Cqrs_001` 的解释不够 reader-facing +- `2026-04-30` 本批次已新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并同步更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`，把 `Game.SourceGenerators` 的 schema 生成链路和 `Cqrs.SourceGenerators` 的定向 fallback 语义收敛成站内可见入口 +- 当前工作树相对 `origin/main` 已达到 `39` files / `2555` lines；仍低于 `50` 文件 stop condition，但后续若继续扩批，应优先提交本轮覆盖扩展后再开新批次 - `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主 - `2026-04-29` 上一批已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题 - `2026-04-29` 本批次继续接受 2 个 explorer 的只读结论：一个负责 `game/data.md`、`game/storage.md`、`godot/ui.md` 的热点排序，一个负责 README reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写 @@ -26,6 +30,9 @@ ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 +- `2026-04-30` source-generators 栏目当前已补出新的 `Schema 配置生成器` 专题页，并通过 landing、API 入口和侧栏把 `Game.SourceGenerators` 从“只在 `config-system.md` 侧面提到”提升到独立 reader-facing 入口。 +- `2026-04-30` `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 与 `docs/zh-CN/core/cqrs.md` 当前已明确“有 fallback != 退回整程序集盲扫”，并补充 direct registration、实现类型定向反射、精确 service type lookup 与程序集级 fallback 元数据之间的分层关系。 +- `2026-04-30` `docs/zh-CN/api-reference/index.md` 与 `source-generators/index.md` 当前把 `SourceGenerators.Common`、`*.SourceGenerators.Abstractions` 收敛为共享 diagnostics / attribute / 冲突规则的阅读入口，而不是新的安装包或维护者专题页。 - `2026-04-29` 新一轮 batch boot 第 2 批次已进一步收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`：移除 “仓库和测试确认”“真实消费者 wiring”“CoreGrid 当前的做法”“优先看” 这类内部或生硬口吻，并把 CQRS 抽象层 README 的源文件列表改成契约类型族说明。 - `2026-04-29` 新一轮 batch boot 已收口 `docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md` 与 `GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md` 的 reader-facing 文案：移除 `ai-libs`、旧文档对比、命令式跳转和原始路径标签。 - `2026-04-29` 当前分支的 upstream `origin/docs/sdk-update-documentation` 已 gone；后续若继续批处理，应继续以 `origin/main` 作为 branch-size stop condition 的 authoritative baseline，而不是默认恢复旧 PR review 状态。 @@ -70,6 +77,7 @@ - `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。 - 当前分支 upstream 已 gone；在重新建立 remote branch 或新的 PR 之前，不适合再把旧 PR `#299` 的 review 状态当作默认恢复信号。 - 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；本轮仍是低风险措辞收口，但下一轮若继续深入 README 子系统地图或大段采用路径重写，review 面会明显扩大。 +- 当前工作树在 coverage 扩展后已接近 `$gframework-batch-boot 50` 的中后段窗口；如果继续新增 source-generator 或 README 专题，建议先提交本轮改动并重新计算 committed diff，再决定是否继续扩批。 - `GFramework.Cqrs`、`GFramework.Cqrs.SourceGenerators`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 仍有若干源文件列表式“子系统地图”段落；这些已经接近结构级改写，不适合作为本轮剩余低风险批次继续机械推进。 ## 归档指针 @@ -91,6 +99,18 @@ ## 最新验证 +- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` + - 结果：通过；新增 `Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。 +- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` + - 结果：通过；source-generators landing 在补 `Schema 配置生成器` 与共享支撑层阅读路线后校验通过。 +- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` + - 结果：通过；`Cqrs` generator 专题页新增策略层级与 fallback 精度说明后校验通过。 +- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` + - 结果：通过；`CQRS` 运行时页补充 generated registry 与 fallback 协作说明后校验通过。 +- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` + - 结果：通过；API 入口页补充 `Game.SourceGenerators` 与共享 source-generator 支撑层阅读路线后校验通过。 +- `2026-04-30` `bun run build`（工作目录：`docs/`） + - 结果：通过；新增 source-generators 专题页与侧栏入口后站点仍可构建，仅保留既有大 chunk warning。 - `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md` - 结果：通过；`game/data.md` 的 frontmatter、链接与代码块校验通过。 - `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md` @@ -132,7 +152,7 @@ ## 下一步 -1. 提交本轮第 2 批低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。 -2. 若继续下一批，优先挑选仍可“局部改句子”的页面或 README 标签问题；`Cqrs`、`Game.SourceGenerators`、`Ecs.Arch` 这类源文件列表式 README 应视作结构级专题，必要时单独开一轮更明确的写作目标。 +1. 提交本轮 source-generators / CQRS coverage 扩展批次，并在提交后重新计算 committed branch diff vs `origin/main`，确认是否仍适合继续在同一 `$gframework-batch-boot 50` 窗口内推进。 +2. 若继续下一批，优先挑选“已有 package README、但站内专题仍不足”的模块入口，例如 `README` 与现有 docs 之间的采用路径补链；避免把 `SourceGenerators.Common` 之类共享支撑层继续扩写成维护者导向的独立专题。 3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。 4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 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 b7de3b1c..c3b129a9 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,39 @@ ## 2026-04-29 +### 当前恢复点：RP-051 + +- 本轮按 `$gframework-batch-boot 50` 恢复后，先确认 `HEAD` 与 `origin/main` `79f9cb37`（`2026-04-29 22:59:12 +08:00`）同步，committed diff 为 `0` files / `0` lines，因此允许把批次目标从“低风险句子收口”提升为“补新的 docs coverage 入口”。 +- 主线程保留实现与验证，同时接受了 2 个 explorer 的只读结论：一条用于判断 `SourceGenerators.Common` 是否值得升成独立 public page，一条用于判断 `Cqrs.SourceGenerators` 的真实公开缺口。accepted 结论是：共享 source-generator 支撑层更适合补 landing / API 入口，而 `Cqrs.SourceGenerators` 应增强现有专题页对策略层级与 fallback 精度的解释。 +- 一个 worker 曾被短暂分配去草拟独立 `shared-support-modules` 页面，但在 explorer 结论返回后被中断；最终无文件写入，也没有并行实现遗留。 +- 实际落地的 coverage 扩展集中在 6 个文件：新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`。 +- docs 页面与恢复文档更新完成后，工作树相对 `origin/main` 已到 `39` files / `2555` lines；仍低于 `50` 文件 stop condition，但本轮已不再适合继续新开第三类 coverage 切片。 + +### 当前决策（RP-051） + +- `Game.SourceGenerators` 当前公开缺口足够明确，因此直接补一张新的 reader-facing 专题页，专门解释 schema 输入契约、生成物形态、聚合注册入口和 `ConfigSchemaDiagnostics` 边界。 +- `SourceGenerators.Common`、`Core.SourceGenerators.Abstractions`、`Godot.SourceGenerators.Abstractions` 不提升为新的独立 public docs 页面，只在现有 landing / API 入口里补共享 diagnostics、attribute 契约与冲突规则的阅读路线。 +- `Cqrs.SourceGenerators` 不再新增第二张专题页，而是在现有 `cqrs-handler-registry-generator.md` 与 `core/cqrs.md` 内明确“有 fallback != 整程序集盲扫”、direct registration / reflected implementation / precise service type lookup / assembly fallback 的层级关系，以及 `GF_Cqrs_001` 的 reader-facing 判断顺序。 + +### 当前验证（RP-051） + +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` + - 结果：通过；本轮新增专题页与 4 个入口页 / 专题页校验全部通过。 +- 站点构建： + - `bun run build`（工作目录：`docs/`） + - 结果：通过；新增 `Schema 配置生成器` 侧栏入口后站点仍可构建，仅保留既有大 chunk warning。 + +### 下一步（RP-051） + +1. 提交本轮 source-generators / CQRS coverage 扩展批次，并把 committed diff vs `origin/main` 重新写回 active tracking。 +2. 若继续同一主题，优先挑选“已有用户面 package，但站内专题仍需补链”的模块，而不是继续给共享支撑层单开页面。 +3. 在 remote branch / PR 恢复之前，继续把 `origin/main` + branch-size 指标当作唯一 batch stop condition。 + ### 当前恢复点：RP-050 - 本轮继续按 `$gframework-batch-boot 50` 推进，并沿用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为唯一 branch-size baseline。 diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index bba97579..18ec3851 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -248,6 +248,7 @@ export default defineConfig({ text: '源码生成器', items: [ { text: '概览', link: '/zh-CN/source-generators/' }, + { text: 'Schema 配置生成器', link: '/zh-CN/source-generators/schema-config-generator' }, { text: '日志生成器', link: '/zh-CN/source-generators/logging-generator' }, { text: '枚举扩展生成器', link: '/zh-CN/source-generators/enum-generator' }, { text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' }, diff --git a/docs/zh-CN/api-reference/index.md b/docs/zh-CN/api-reference/index.md index 5573089e..278c8f99 100644 --- a/docs/zh-CN/api-reference/index.md +++ b/docs/zh-CN/api-reference/index.md @@ -31,8 +31,8 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 | 模块族 | 先看什么 | 继续深入 | XML 文档关注点 | | --- | --- | --- | --- | | `Core` / `Core.Abstractions` | [Core 模块](../core/index.md) | [Core 抽象层说明](../abstractions/core-abstractions.md)、[快速开始](../getting-started/quick-start.md) | 架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约 | -| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / generated registry / targeted fallback contract | -| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md) | 配置、数据、设置、场景、UI、存储、序列化契约；其中 AI-First 配置工作流的正式支持边界以 Runtime + Generator 共享 schema 子集为准 | +| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md) | [CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)、[协程系统](../core/coroutine.md) | request / notification / handler / pipeline / generated registry / targeted fallback contract，以及生成注册器与定向补扫的协作边界 | +| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | [Game 模块总览](../game/index.md) | [Game 抽象层说明](../abstractions/game-abstractions.md)、[配置系统](../game/config-system.md)、[Schema 配置生成器](../source-generators/schema-config-generator.md) | 配置、数据、设置、场景、UI、存储、序列化契约，以及 schema 到生成代码的公开入口 | | `Godot` / `Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md) | [Godot 项目生成器](../source-generators/godot-project-generator.md)、[GetNode 生成器](../source-generators/get-node-generator.md)、[BindNodeSignal 生成器](../source-generators/bind-node-signal-generator.md) | 节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口 | | `Ecs.Arch` / `Ecs.Arch.Abstractions` | [ECS 模块总览](../ecs/index.md) | [Arch ECS 集成](../ecs/arch.md)、[Ecs.Arch 抽象层说明](../abstractions/ecs-arch-abstractions.md) | ECS 模块契约、系统适配、配置对象和运行时装配边界 | @@ -78,6 +78,22 @@ description: GFramework 的 API 阅读入口，按模块映射 README、专题 - `GFramework.SourceGenerators.Common` - 主要提供共享生成器基类、通用 diagnostics，以及生成方法冲突等跨模块约束。 +如果你要沿着 XML 文档和源码继续读，优先从下面这几类入口开始： + +- 共享 diagnostics + - `CommonDiagnostics` +- 共享生成流程 + - `AttributeClassGeneratorBase` + - `AttributeEnumGeneratorBase` +- 共享冲突规则 + - `GeneratedMethodConflictExtensions` + +这组入口更适合回答三类问题： + +- 为什么多个生成器都会要求宿主类型满足 `partial` +- 为什么不同专题页会出现同一套生成方法名冲突诊断 +- 为什么多个生成器对候选筛选、属性解析和生成阶段采用相近流程 + ## 使用方式 把本页当成“API 阅读导航”而不是“签名快照”： diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index c705bfd3..2a62250d 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -184,6 +184,11 @@ protected override void OnInitialize() 两者的共同点都是“优先消费 generated invoker 元数据，未命中时保留既有反射绑定作为兜底”，而不是要求业务侧切换到另一套 runtime 入口。 +对接入方来说，更关键的 reader-facing 语义是：安装 `Cqrs.SourceGenerators` 后，不要求“所有 handler 都能被生成代码直接引用”才有收益。 +即使仍有 fallback，runtime 也会先消费 generated registry，再只对剩余 handler 做定向补扫；只有旧版 marker 语义或空 fallback 元数据才会退回整程序集扫描。 +`Type` fallback、按名称恢复的 fallback，以及 mixed fallback 只影响补扫精度，不改变 +`RegisterCqrsHandlersFromAssembly(...)` 或 `RegisterCqrsHandlersFromAssemblies(...)` 的接法。 + `Cqrs.SourceGenerators` 的专题入口见[CQRS Handler Registry 生成器](../source-generators/cqrs-handler-registry-generator.md)。 ## Pipeline Behavior diff --git a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md index 94c38765..3b973d5b 100644 --- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md +++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md @@ -124,11 +124,46 @@ RegisterCqrsHandlersFromAssemblies( - 其余场景统一回退到字符串元数据，避免 mixed 场景漏注册 - 只有在 runtime 提供 `CqrsReflectionFallbackAttribute` 合同时，才允许发射依赖 fallback 的结果 +## 生成策略层级 + +把这个生成器理解成“静态注册 or 整程序集扫描”的二选一，会低估它的收益。当前策略实际上分成四层： + +1. 直接静态注册 + - handler 接口和实现类型都能被生成代码安全引用 +2. 实现类型定向反射查找 + - handler 接口还能精确表达，但实现类型只能在运行时按具体类型名恢复 +3. service type 精确运行时查找 + - handler 接口本身也需要运行时构造，但仍能把查找范围收窄到具体 service type +4. 程序集级 fallback 元数据 + - 只有前面几层都无法覆盖的剩余 handler，才交给 `CqrsReflectionFallbackAttribute` + +这意味着安装生成器后，并不要求“所有 handler 都可直接引用”才有收益。很多只能部分静态表达的项目，仍然可以把大部分注册路径前移到编译期，再对少数复杂类型做定向补扫。 + +## 哪些场景通常不会直接退回整程序集扫描 + +下列类型形态经常仍然能保留精细化注册，而不是立刻退回整程序集盲扫： + +| 场景 | 常见结果 | +| --- | --- | +| 私有嵌套 handler，但对外 handler 接口仍可直接引用 | 生成器改为按实现类型定向反射查找 | +| 响应或参数里包含需要运行时恢复的隐藏类型 | 生成器改为精确 service type runtime lookup | +| mixed 场景里同时存在可直接引用和仅能按名称恢复的 fallback handlers | 生成器拆分 `Type` 元数据和字符串元数据，减少后续字符串回查 | +| 响应类型写成 `dynamic` | 生成器会按 `System.Object` 归一化，而不是发射非法的 `typeof(dynamic)` | + +相反，pointer、function-pointer 这类无法安全重建的类型形态，不属于这里承诺的精确生成边界。 + 如果当前编译环境缺少这个 fallback 合同，而某些 handler 又必须依赖它，生成器会报： - `GF_Cqrs_001` 这条诊断的含义不是“某个 handler 写错了”，而是“当前 runtime 合同不足以安全承载这轮生成结果”。 +遇到它时，优先按这个顺序判断： + +1. 当前消费端是否已经引用支持 `CqrsReflectionFallbackAttribute` 的 `GFramework.Cqrs` runtime +2. 当前项目里是否存在只能部分静态表达的 handler 类型 +3. 如果确实不想引入 fallback 合同，是否需要把这类 handler 改成更容易被生成器直接引用的公开形态 + +`CqrsReflectionFallbackAttribute` 出现也不等于“运行时一定回到整程序集扫描”。只有 fallback 元数据为空、或旧版只保留 marker 语义时，runtime 才会退回整程序集补扫；当元数据里已经带了具体 `Type` 或类型名时，runtime 会优先按这些剩余 handler 做定向补扫。 ## 源码与 API 阅读入口 diff --git a/docs/zh-CN/source-generators/index.md b/docs/zh-CN/source-generators/index.md index e4f1981a..55ac039d 100644 --- a/docs/zh-CN/source-generators/index.md +++ b/docs/zh-CN/source-generators/index.md @@ -25,7 +25,7 @@ GFramework 当前发布的生成器包是： | 使用场景 | 安装包 | 继续阅读 | | --- | --- | --- | | 减少日志、上下文注入、模块自动注册等 Core 侧样板代码 | `GeWuYou.GFramework.Core.SourceGenerators` | [Core 模块](../core/index.md)、[日志生成器](./logging-generator.md)、[ContextAware 生成器](./context-aware-generator.md) | -| 把 `schemas/**/*.schema.json` 生成成配置类型和表包装 | `GeWuYou.GFramework.Game.SourceGenerators` | [配置系统](../game/config-system.md)、[VS Code 配置工具](../game/config-tool.md) | +| 把 `schemas/**/*.schema.json` 生成成配置类型和表包装 | `GeWuYou.GFramework.Game.SourceGenerators` | [Schema 配置生成器](./schema-config-generator.md)、[配置系统](../game/config-system.md)、[VS Code 配置工具](../game/config-tool.md) | | 让 CQRS handler registry 在编译期生成，缩小运行时反射扫描范围 | `GeWuYou.GFramework.Cqrs.SourceGenerators` | [CQRS 运行时](../core/cqrs.md)、[CQRS Handler Registry 生成器](./cqrs-handler-registry-generator.md) | | 在 Godot 项目里生成 AutoLoad / Input Action 入口、节点 / 信号样板，或补齐 Scene/UI 包装与导出集合注册辅助 | `GeWuYou.GFramework.Godot.SourceGenerators` | [Godot 模块总览](../godot/index.md)、[Godot 项目生成器](./godot-project-generator.md)、[GetNode 生成器](./get-node-generator.md) | @@ -94,6 +94,15 @@ GFramework 当前发布的生成器包是： - 再根据 attribute 或 diagnostics 回到对应专题页 - 只有在排查生成失败原因时，才继续下钻到这些共享支撑目录 +如果你更关心“多个生成器为什么会给出一致的 `partial` 要求、方法名冲突错误或 trace 诊断”，可以把这三类目录当成共享排障层来理解： + +- `*.SourceGenerators.Abstractions` + - 先看公开 attribute 能写什么，再回到对应专题页确认生成语义 +- `GFramework.SourceGenerators.Common` + - 先看共享 diagnostics，再看公共生成基类和冲突规则 + +这层仍然不是新的安装入口。只有在排查生成失败、对比多个生成器的共同约束，或准备扩展生成器时，才值得继续下钻。 + ## 阅读路线 ### Core 侧通用生成器 @@ -107,6 +116,8 @@ GFramework 当前发布的生成器包是： ### Game / CQRS 相关生成器 +- schema 到配置类型 / 表包装 / 聚合注册的生成路径： + - [Schema 配置生成器](./schema-config-generator.md) - 配置 schema 生成与运行时接法： - [配置系统](../game/config-system.md) - 读者若需要确认共享 schema 子集、关闭对象边界或复杂组合关键字的限制，应以该页为准，而不是只从本页推断支持范围 @@ -138,6 +149,8 @@ GFramework 当前发布的生成器包是： - 安装 `Game` + `Game.SourceGenerators` - 需要 CQRS 生成注册表： - 安装 `Cqrs` + `Cqrs.SourceGenerators` +- 需要排查跨生成器共享的 diagnostics 或 attribute 契约： + - 保持原有 `*.SourceGenerators` 包入口不变，再回到本页的共享支撑模块说明 ## 对应模块入口 diff --git a/docs/zh-CN/source-generators/schema-config-generator.md b/docs/zh-CN/source-generators/schema-config-generator.md new file mode 100644 index 00000000..0d78eb45 --- /dev/null +++ b/docs/zh-CN/source-generators/schema-config-generator.md @@ -0,0 +1,200 @@ +--- +title: Schema 配置生成器 +description: 说明 GFramework.Game.SourceGenerators 如何从 schema 生成配置类型、表包装和聚合注册入口。 +--- + +# Schema 配置生成器 + +`GFramework.Game.SourceGenerators` 会把消费者项目里的 `schemas/**/*.schema.json` 读入编译期管线，并生成： + +- 强类型配置类型 +- 对应的表包装类型 +- 单表绑定辅助代码 +- 聚合注册目录与 `RegisterAllGeneratedConfigTables(...)` 扩展入口 + +如果你当前目标是“先把配置系统接进项目”，先看 [游戏内容配置系统](../game/config-system.md)。这页更适合在你已经决定使用 +`Game.SourceGenerators` 之后，继续确认 schema 输入契约、生成结果和常见诊断边界。 + +## 它解决什么问题 + +相比只写 `YAML` 和运行时加载代码，这个生成器把三件事前移到了编译期： + +- 把 schema 转成 `Config` 类型，让业务代码直接拿到强类型字段和 XML 文档 +- 为运行时表生成包装层，让 `Get`、`TryGet`、按字段查找等入口保持稳定 +- 汇总当前项目中所有 schema 的注册信息，避免 schema 数量增长后继续手写逐表注册 + +这也是 `GFramework.Game` 配置运行时、VS Code 配置工具和 schema 约束能够共享同一份结构定义的基础。 + +## 最小接入路径 + +NuGet 安装保持运行时包与生成器包版本一致，并把生成器声明为编译期依赖： + +```xml + + + + +``` + +默认情况下，包内 `targets` 会自动把 `schemas/**/*.schema.json` 纳入 `AdditionalFiles`。如果你的 schema 目录不是 +`schemas/`，可以在项目文件里覆盖： + +```xml + + GameSchemas + +``` + +## 输入约定 + +### schema 根对象 + +当前生成器要求每个 schema 都满足这些基本约束： + +- 顶层 `type` 必须是 `object` +- 必须声明必填 `id` 字段 +- `id` 目前只支持 `integer` 和 `string` +- schema 文件名与属性名都必须能稳定映射到合法的 C# 标识符 + +最小示例： + +```json +{ + "title": "Monster Config", + "type": "object", + "required": ["id", "name"], + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + } + } +} +``` + +### 路径与索引元数据 + +除了标准 JSON Schema 字段，当前还支持几个会直接影响生成结果的扩展元数据： + +- `x-gframework-config-path` + - 覆盖默认配置目录；值必须是相对路径，且不能包含 `.`、`..` 或绝对路径段 +- `x-gframework-index` + - 为顶层必填、非主键、非引用的标量字段生成 `FindBy...` / `TryFindFirstBy...` 查找入口 +- `x-gframework-ref-table` + - 为字段补充跨表引用语义，并把这部分信息写入生成的绑定元数据 + +如果某个字段不满足 lookup index 的安全条件，生成器会直接报诊断，而不是静默生成一个容易失真的查询入口。 + +### 当前稳定约束子集 + +从源码和快照测试看，当前共享子集已经覆盖： + +- 标量、嵌套对象、对象数组、标量数组 +- `default`、`enum`、`const` +- `minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf` +- `minLength`、`maxLength`、`pattern` +- `format` + - 当前稳定字符串子集是 `date`、`date-time`、`duration`、`email`、`time`、`uri`、`uuid` +- `minItems`、`maxItems`、`uniqueItems`、`contains`、`minContains`、`maxContains` +- `minProperties`、`maxProperties` +- `dependentRequired`、`dependentSchemas`、`allOf` +- 面向对象约束的 `if` / `then` / `else` + +这些约束并不一定都会改变生成类型的形状，但会被保留到生成代码文档和绑定元数据里，方便运行时与工具链共享。 + +## 会生成什么 + +以 `monster.schema.json` 为例，当前生成器会形成四组稳定输出： + +### 1. 配置类型 + +例如 `MonsterConfig`。它承载 schema 字段到 C# 属性的映射，以及对应的 XML 文档。 + +### 2. 表包装类型 + +例如 `MonsterTable`。它包装运行时 `IConfigTable`，并在需要时提供生成的查找入口： + +```csharp +public sealed partial class MonsterTable : IConfigTable +{ + public MonsterConfig Get(int key) { ... } + + public IReadOnlyList FindByName(string value) { ... } + + public bool TryFindFirstByName(string value, out MonsterConfig? result) { ... } +} +``` + +如果字段声明了 `x-gframework-index`，生成器会优先使用延迟构建的只读索引；否则按当前表快照做确定性的线性扫描，以保持和热重载后的运行时数据一致。 + +### 3. 单表绑定辅助 + +例如 `MonsterConfigBindings`。这里会保留单表注册所需的表名、schema 路径、配置路径和引用元数据，方便项目侧继续组合自己的启动逻辑。 + +### 4. 聚合注册目录 + +当一个项目里有多个 schema 时，生成器还会汇总出 `GeneratedConfigCatalog` 与聚合扩展： + +```csharp +loader.RegisterAllGeneratedConfigTables(); +``` + +如果你需要按表传入额外比较器或做更细粒度控制，还可以使用带 `GeneratedConfigRegistrationOptions` 的重载。 + +## 运行时如何消费这些输出 + +最常见的消费路径是把生成器输出交给 `GameConfigBootstrap` 或 `YamlConfigLoader`： + +```csharp +using GFramework.Game.Config; +using GFramework.Game.Config.Generated; + +var bootstrap = new GameConfigBootstrap( + new GameConfigBootstrapOptions + { + RootPath = configRootPath, + ConfigureLoader = static loader => loader.RegisterAllGeneratedConfigTables() + }); +``` + +当你需要继续手动拼装运行时，也可以直接用单表绑定或聚合目录做自己的注册封装。这时建议把“启动生命周期”和“业务读取入口”分开，继续沿用 +[游戏内容配置系统](../game/config-system.md) 里的 `GameConfigHost` / `GameConfigRuntime` 模板。 + +## 常见诊断边界 + +当前 `ConfigSchemaDiagnostics` 暴露的错误主要分成四类： + +- schema 根对象或 JSON 读入失败 + - 例如 `GF_ConfigSchema_001`、`GF_ConfigSchema_002` +- 主键与类型映射不合法 + - 例如 `GF_ConfigSchema_003`、`GF_ConfigSchema_005` +- 生成标识符或路径元数据不安全 + - 例如 `GF_ConfigSchema_006`、`GF_ConfigSchema_007` +- 额外约束元数据不合法 + - 例如 `GF_ConfigSchema_008` 到 `GF_ConfigSchema_014` + +这些边界由 `GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorTests.cs` 和快照测试共同覆盖。遇到生成失败时，优先先看诊断 ID，再回头核对 schema 本身是否超出当前公开子集。 + +## 什么时候优先看这页 + +适合： + +- 你想确认一个 schema 字段会生成哪些 C# 入口 +- 你要排查 `x-gframework-index`、路径元数据或标识符冲突 +- 你在做项目级聚合注册，希望知道 `GeneratedConfigCatalog` 和 `RegisterAllGeneratedConfigTables(...)` 的边界 + +不适合： + +- 你只是第一次接入配置运行时 +- 你更关心 `GameConfigBootstrap`、热重载、Godot 资源路径或 VS Code 配置工具 + +这些采用问题分别回到： + +- [游戏内容配置系统](../game/config-system.md) +- [VS Code 配置工具](../game/config-tool.md) +- [源码生成器总览](./index.md) From 7e77fee0a544bd0b2eb57ceab6b1c449c330618d Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Thu, 30 Apr 2026 09:52:58 +0800 Subject: [PATCH 2/7] =?UTF-8?q?docs(ai-plan):=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A6=86=E7=9B=96=E6=81=A2=E5=A4=8D=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 committed diff 基线，记录本轮提交后的 8 files / 337 lines 状态 - 补充 documentation-full-coverage-governance 的下一步建议，避免后续按过时工作树峰值恢复 --- ...ation-full-coverage-governance-tracking.md | 9 +++--- ...entation-full-coverage-governance-trace.md | 29 +++++++++++++++++++ 2 files changed, 34 insertions(+), 4 deletions(-) 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 60f7c878..f0b0f30e 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,15 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-051` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-052` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，在保持 reader-facing 口吻治理的同时，继续补 `source-generators` / `CQRS` 的公开专题覆盖率 +- `2026-04-30` 本轮 coverage 扩展已提交为 `f88f96c3`（`docs(source-generators): 补充生成器专题覆盖并更新进度`）；当前 committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines，工作树重新变为 clean，仍保留充足阈值余量可供后续批次继续推进 - `2026-04-30` 本轮恢复时确认当前 `HEAD` 与 `origin/main` 同步，committed diff 为 `0` files / `0` lines；因此本批次不再只做措辞收口，而是允许补新的公开专题页和入口链路 - `2026-04-30` 本轮接受 2 个 explorer 的只读结论：其一，`GFramework.SourceGenerators.Common` 更适合作为 landing / API 入口内的共享排障层，而不是新的独立 public page；其二，`Cqrs.SourceGenerators` 当前主要缺口不是“没有入口”，而是现有专题页与 `core/cqrs.md` 对生成策略层级、fallback 精度和 `GF_Cqrs_001` 的解释不够 reader-facing - `2026-04-30` 本批次已新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并同步更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`，把 `Game.SourceGenerators` 的 schema 生成链路和 `Cqrs.SourceGenerators` 的定向 fallback 语义收敛成站内可见入口 -- 当前工作树相对 `origin/main` 已达到 `39` files / `2555` lines；仍低于 `50` 文件 stop condition，但后续若继续扩批，应优先提交本轮覆盖扩展后再开新批次 +- 本轮在提交前一度把工作树推到 `39` files / `2555` lines；提交后 committed diff 已收敛到 `8` files / `337` lines，说明当前 batch 仍适合继续承接下一轮中等规模 coverage 切片 - `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主 - `2026-04-29` 上一批已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题 - `2026-04-29` 本批次继续接受 2 个 explorer 的只读结论：一个负责 `game/data.md`、`game/storage.md`、`godot/ui.md` 的热点排序，一个负责 README reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写 @@ -152,7 +153,7 @@ ## 下一步 -1. 提交本轮 source-generators / CQRS coverage 扩展批次，并在提交后重新计算 committed branch diff vs `origin/main`，确认是否仍适合继续在同一 `$gframework-batch-boot 50` 窗口内推进。 -2. 若继续下一批，优先挑选“已有 package README、但站内专题仍不足”的模块入口，例如 `README` 与现有 docs 之间的采用路径补链；避免把 `SourceGenerators.Common` 之类共享支撑层继续扩写成维护者导向的独立专题。 +1. 若继续下一批，优先挑选“已有 package README、但站内专题仍不足”的模块入口，例如 `README` 与现有 docs 之间的采用路径补链；避免把 `SourceGenerators.Common` 之类共享支撑层继续扩写成维护者导向的独立专题。 +2. 在继续扩批前，先沿用当前 committed diff `8` files / `337` lines 作为新的 batch 起点，避免把提交前的工作树计量误当成现状。 3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。 4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 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 c3b129a9..593d6b45 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 @@ -1,5 +1,34 @@ # Documentation Full Coverage Governance Trace +## 2026-04-30 + +### 当前恢复点：RP-052 + +- 本轮 coverage 扩展已提交为 `f88f96c3`（`docs(source-generators): 补充生成器专题覆盖并更新进度`）。提交后重新计算发现，committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines，工作树 clean，说明提交前的 `39` files / `2555` lines 只是临时工作树峰值，不应继续作为默认恢复指标。 +- 这次提交把 `Game.SourceGenerators` 的 schema 生成链路提升成独立 public docs 专题，并把 `Cqrs.SourceGenerators` 的 fallback 精度、共享 source-generator 支撑层的阅读路线，一并接回 landing / API / CQRS 入口。 +- 由于 stop-condition 余量重新恢复，下一轮仍可以继续沿 `$gframework-batch-boot 50` 推进，但应优先挑“已有模块、已有 README、站内专题仍不足”的 coverage 切片，而不是继续给共享支撑层单开页面。 + +### 当前决策（RP-052） + +- 把 `8` files / `337` lines 视作新的 authoritative branch-size baseline，而不是沿用提交前的工作树峰值。 +- 保留 `RP-051` 的结论：共享 source-generator 支撑层继续通过 landing / API 入口解释，不提升为独立 public docs 页面。 +- 后续若继续扩批，优先考虑 README 与站内 docs 之间仍缺的 reader-facing 采用链路，而不是只做措辞巡检。 + +### 当前验证（RP-052） + +- 继承 `RP-051` 的页面校验与 `bun run build` 成功结果。 +- 提交后状态确认： + - `git status --short --branch` + - `git diff --name-only origin/main...HEAD | wc -l` + - `git diff --numstat origin/main...HEAD` + - 结果：通过；当前分支工作树 clean，相对 `origin/main` 的 committed diff 为 `8` files / `337` lines。 + +### 下一步（RP-052） + +1. 继续同一主题时，把 `8` files / `337` lines 作为新的 batch 起点。 +2. 优先挑选“已有 package README、但站内专题仍不足”的 coverage 切片。 +3. 在 remote branch / PR 恢复之前，继续把 `origin/main` + committed branch diff 当作唯一 stop-condition 度量。 + ## 2026-04-29 ### 当前恢复点：RP-051 From 241c9ffeb3dbd11872b23ecf4a80971feeca475b Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 1 May 2026 13:16:35 +0800 Subject: [PATCH 3/7] =?UTF-8?q?docs(source-generators):=20=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E8=BF=81=E7=A7=BB=E5=85=BC=E5=AE=B9=E8=AF=B4=E6=98=8E?= =?UTF-8?q?=E5=B9=B6=E5=BD=92=E6=A1=A3=E6=81=A2=E5=A4=8D=E5=8E=86=E5=8F=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补充 Schema 配置生成器专题的迁移步骤、兼容边界与回退建议 - 更新 active tracking 与 active trace，只保留当前恢复事实、验证结果与归档指针 - 新增 RP-049 到 RP-052 的状态、验证与时间线归档文件 --- ...tus-history-rp-049-to-rp-052-2026-05-01.md | 31 ++ ...ion-history-rp-049-to-rp-052-2026-05-01.md | 70 +++ ...ace-history-rp-049-to-rp-052-2026-05-01.md | 31 ++ ...ation-full-coverage-governance-tracking.md | 151 ++---- ...entation-full-coverage-governance-trace.md | 483 ++---------------- .../schema-config-generator.md | 21 + 6 files changed, 220 insertions(+), 567 deletions(-) create mode 100644 ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md create mode 100644 ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md create mode 100644 ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md new file mode 100644 index 00000000..7c56f6dd --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md @@ -0,0 +1,31 @@ +# Documentation Full Coverage Governance Status History (RP-049 to RP-052) + +## Scope + +- 该归档承接 active tracking 从 `RP-049` 到 `RP-052` 迁出的阶段状态、批次边界和恢复决策。 +- 逐命令验证明细单独保存在： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` + +## 2026-04-29 / RP-049 + +- 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但上游恢复路径不再依赖旧 PR 线程，而是改用 `origin/main` 作为 batch stop-condition baseline。 +- 本轮工作树在 reader-facing 文案收口后相对 `origin/main` 来到 `13` files / `132` lines`，仍明显低于 `$gframework-batch-boot 50` 的阈值。 +- 主线程接受的变更范围限定在 `docs/zh-CN/godot/*`、`game/*` 和少量 README 标签，不扩展到导航重写或大型结构改稿。 + +## 2026-04-29 / RP-050 + +- 在 `RP-049` 的基础上继续做第 2 批低风险 reader-facing 收口，触达 `game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`。 +- 决策上只接受“改句子即可闭环”的问题，不把 README 子系统地图或结构级重写混入同一轮。 +- 当轮工作树相对 `origin/main` 为 `18` files / `225` lines`，仍保留充足余量。 + +## 2026-04-29 / RP-051 + +- 从与 `origin/main` 零 diff 的状态重新进入后，把批次目标从“低风险句子收口”提升为“补新的 docs coverage 入口”。 +- 这一轮新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并同步更新 `source-generators/index.md`、`api-reference/index.md`、`source-generators/cqrs-handler-registry-generator.md`、`core/cqrs.md` 与 `docs/.vitepress/config.mts`。 +- 接受的核心结论是：`Game.SourceGenerators` 需要新的 reader-facing 专题页，而 `SourceGenerators.Common` 和各 `*.SourceGenerators.Abstractions` 更适合作为现有入口中的共享排障层阅读路线。 + +## 2026-04-30 / RP-052 + +- 该批次提交为 `f88f96c3`（`docs(source-generators): 补充生成器专题覆盖并更新进度`）。 +- 提交后重新计算确认 committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines`，说明提交前的 `39` files / `2555` lines` 只是临时工作树峰值，不应继续作为默认恢复指标。 +- active topic 后续仍可以继续按 `$gframework-batch-boot 50` 推进，但应优先挑“已有 package README、但站内专题仍不足”的覆盖切片。 diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md new file mode 100644 index 00000000..d8fa0afc --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md @@ -0,0 +1,70 @@ +# Documentation Full Coverage Governance Validation History (RP-049 to RP-052) + +## 2026-04-29 / RP-049 + +### 页面校验 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.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/godot/logging.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.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/config-system.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` + - 结果：通过；本轮页面的 frontmatter、链接与代码块校验通过。 + +### README 链接校验 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md tools/gframework-config-tool/README.md` + - 结果：通过；reader-facing 链接标签调整后目标有效。 + +### 站点构建 + +- `bun run build`（工作目录：`docs/`） + - 结果：通过；站点仍可构建，仅保留既有大 chunk warning。 + +## 2026-04-29 / RP-050 + +### 页面校验 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` + - 结果：通过；本轮 3 个页面的 frontmatter、链接与代码块校验通过。 + +### README 链接校验 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md` + - 结果：通过；README reader-facing 标签调整后目标有效。 + +### 站点构建 + +- `bun run build`（工作目录：`docs/`） + - 结果：通过；本轮 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 + +## 2026-04-30 / RP-051 + +### 页面校验 + +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` +- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` + - 结果：通过；新增专题页与相关入口页校验通过。 + +### 站点构建 + +- `bun run build`（工作目录：`docs/`） + - 结果：通过；新增 `Schema 配置生成器` 入口后站点仍可构建，仅保留既有大 chunk warning。 + +## 2026-04-30 / RP-052 + +### 提交后状态确认 + +- `git status --short --branch` +- `git diff --name-only origin/main...HEAD | wc -l` +- `git diff --numstat origin/main...HEAD` + - 结果：通过；提交后工作树 clean，相对 `origin/main` 的 committed diff 为 `8` files / `337` lines。 diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md new file mode 100644 index 00000000..a9df893c --- /dev/null +++ b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md @@ -0,0 +1,31 @@ +# Documentation Full Coverage Governance Trace History (RP-049 to RP-052) + +## Scope + +- 该归档记录 `RP-049` 到 `RP-052` 从 active trace 迁出的阶段时间线，保留每轮恢复点、核心决策与停止条件。 +- 对应的验证明细继续保存在： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` + +## 2026-04-29 / RP-049 + +- 由于旧 PR 恢复路径已经失效，这一轮改用 `origin/main` 作为唯一 batch baseline，并重新确认当前分支仍为 `docs/sdk-update-documentation`。 +- 本轮主要清理 `godot`、`game` 与少量 README 中仍显露内部证据、命令式导流和原始路径标签的 reader-facing 问题。 +- 停止条件保持为 `$gframework-batch-boot 50`，但本轮并未逼近阈值。 + +## 2026-04-29 / RP-050 + +- 主线程继续沿低风险文案批次推进，接受 2 个 explorer 的热点排序，只处理“改句子即可闭环”的页面与 README 标签问题。 +- 实际落地集中在 `game/data.md`、`game/storage.md`、`godot/ui.md` 与 2 个 README。 +- 剩余命中已接近结构级 README 重写，因此被明确排除出这一轮批次。 + +## 2026-04-29 / RP-051 + +- 在确认 `HEAD` 与 `origin/main` 同步后，本轮把目标提升为新的 docs coverage 入口补链，而不是继续做纯措辞巡检。 +- 接受的结论是：`Game.SourceGenerators` 需要独立专题页，而 `SourceGenerators.Common` 与各 `*.SourceGenerators.Abstractions` 只需要在 landing / API 入口内承担共享 diagnostics 与 attribute 契约说明。 +- 与此同时，`Cqrs.SourceGenerators` 的真实缺口被限定为对 fallback 精度、分层策略和 `GF_Cqrs_001` 判断顺序的 reader-facing 解释，而不是继续新增第二张专题页。 + +## 2026-04-30 / RP-052 + +- 这一轮 coverage 扩展提交为 `f88f96c3`，提交后 branch diff 相对 `origin/main` 回落到 `8` files / `337` lines`，重新释放了 stop-condition 余量。 +- active topic 后续仍可继续扩批，但更适合选择“已有 package README、但站内 docs 仍缺 reader-facing 专题”的切片，而不是继续给共享支撑层单开页面。 +- 该状态也为后续用 `$gframework-pr-review` 精确跟进最新 review 线程提供了更清晰的恢复入口。 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 f0b0f30e..f3cd335f 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 @@ -2,84 +2,34 @@ ## 目标 -建立一个长期 active topic，持续治理 `GFramework` 的 README、`docs/zh-CN`、站点导航、XML 文档和 API -参考链路，避免阶段性刷新完成后再次回漂。 +持续治理 `GFramework` 的 README、`docs/zh-CN`、站点导航、XML 文档和 API 参考链路，避免阶段性刷新完成后再次回漂。 - 用源码、测试、`*.csproj` 和必要的 `ai-libs/` 证据校正文档 - 以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路 -- 明确哪些目录是可直接消费模块，哪些只是内部支撑模块 -- 把 XML 文档缺口纳入治理范围，而不是只刷新 Markdown +- 把 XML 文档缺口与 reader-facing 采用路径持续纳入同一主题治理 ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-052` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-053` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，在保持 reader-facing 口吻治理的同时，继续补 `source-generators` / `CQRS` 的公开专题覆盖率 -- `2026-04-30` 本轮 coverage 扩展已提交为 `f88f96c3`（`docs(source-generators): 补充生成器专题覆盖并更新进度`）；当前 committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines，工作树重新变为 clean，仍保留充足阈值余量可供后续批次继续推进 -- `2026-04-30` 本轮恢复时确认当前 `HEAD` 与 `origin/main` 同步，committed diff 为 `0` files / `0` lines；因此本批次不再只做措辞收口，而是允许补新的公开专题页和入口链路 -- `2026-04-30` 本轮接受 2 个 explorer 的只读结论：其一，`GFramework.SourceGenerators.Common` 更适合作为 landing / API 入口内的共享排障层，而不是新的独立 public page；其二，`Cqrs.SourceGenerators` 当前主要缺口不是“没有入口”，而是现有专题页与 `core/cqrs.md` 对生成策略层级、fallback 精度和 `GF_Cqrs_001` 的解释不够 reader-facing -- `2026-04-30` 本批次已新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并同步更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`，把 `Game.SourceGenerators` 的 schema 生成链路和 `Cqrs.SourceGenerators` 的定向 fallback 语义收敛成站内可见入口 -- 本轮在提交前一度把工作树推到 `39` files / `2555` lines；提交后 committed diff 已收敛到 `8` files / `337` lines，说明当前 batch 仍适合继续承接下一轮中等规模 coverage 切片 -- `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主 -- `2026-04-29` 上一批已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题 -- `2026-04-29` 本批次继续接受 2 个 explorer 的只读结论：一个负责 `game/data.md`、`game/storage.md`、`godot/ui.md` 的热点排序，一个负责 README reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写 -- `2026-04-29` 本批次已收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md` 的文案：把内部证据叙述、外部项目指代、命令式导流、源文件路径列表和 `IsPackable=false` 这类实现术语改成 reader-facing 说明 -- 本轮仍保持在新的低风险批次窗口内：当前工作树相对 `origin/main` 为 `18` files / `225` lines，仍明显低于 `50` 文件 stop condition -- 本轮继续沿用已确认的生命周期事实：`Architecture` 只暴露 `OnInitialize()`，`AbstractArchitecture` 通过 `InstallModules()` 暴露模块注册入口，而组件级 `OnInit()` 仍然是当前有效生命周期 + - 处理 PR `#308` latest-head review 中仍成立的 3 条 `CodeRabbit` open threads：继续瘦身 active `ai-plan` 文档，并为 `Schema 配置生成器` 专题补集中式迁移与兼容性说明 +- 当前事实： + - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 为 `097e97bcd66c89c79b4dafc30e24e8b650c7db63` + - 当前 latest-head review 只剩 `CodeRabbit` `3` 条 open threads，分别指向本 tracking、active trace 和 `docs/zh-CN/source-generators/schema-config-generator.md` + - GitHub Test Reporter 汇总为 `2222 passed / 0 failed` + - `Title check` 仍为 `Inconclusive`，属于 PR 元数据问题，不是仓库文件内可直接修复的阻塞项 + - 本地已完成 review 指向文件的收口，但在变更尚未提交推送前，重新抓取的 PR review 仍会继续显示旧的 latest reviewed commit 与同一批 open threads +- 当前风险： + - active tracking / trace 若继续保留阶段性细节与逐项验证，会再次偏离“快速恢复入口”的用途 + - `Schema 配置生成器` 页已经说明边界，但迁移步骤、兼容边界和回退方式仍分散在多个段落中 ## 当前状态摘要 - `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。 -- `2026-04-30` source-generators 栏目当前已补出新的 `Schema 配置生成器` 专题页，并通过 landing、API 入口和侧栏把 `Game.SourceGenerators` 从“只在 `config-system.md` 侧面提到”提升到独立 reader-facing 入口。 -- `2026-04-30` `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` 与 `docs/zh-CN/core/cqrs.md` 当前已明确“有 fallback != 退回整程序集盲扫”，并补充 direct registration、实现类型定向反射、精确 service type lookup 与程序集级 fallback 元数据之间的分层关系。 -- `2026-04-30` `docs/zh-CN/api-reference/index.md` 与 `source-generators/index.md` 当前把 `SourceGenerators.Common`、`*.SourceGenerators.Abstractions` 收敛为共享 diagnostics / attribute / 冲突规则的阅读入口，而不是新的安装包或维护者专题页。 -- `2026-04-29` 新一轮 batch boot 第 2 批次已进一步收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`：移除 “仓库和测试确认”“真实消费者 wiring”“CoreGrid 当前的做法”“优先看” 这类内部或生硬口吻，并把 CQRS 抽象层 README 的源文件列表改成契约类型族说明。 -- `2026-04-29` 新一轮 batch boot 已收口 `docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md` 与 `GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md` 的 reader-facing 文案：移除 `ai-libs`、旧文档对比、命令式跳转和原始路径标签。 -- `2026-04-29` 当前分支的 upstream `origin/docs/sdk-update-documentation` 已 gone；后续若继续批处理，应继续以 `origin/main` 作为 branch-size stop condition 的 authoritative baseline，而不是默认恢复旧 PR review 状态。 -- `2026-04-28` 已重新抓取 PR `#299` 并复核 latest-head review：remote 当前只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，且都指向 active tracking 文档；`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，`Title check` 仍是 PR 元数据问题。 -- `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/contributing.md` 中最后一个嵌套 fenced 示例已改写为转义围栏文本，现有 `validate-code-blocks.sh` 不再报告第 `631` 行警告。 -- `2026-04-25` 全量 `docs/zh-CN` 验证已无剩余代码块语言警告；前一轮触达的 `tutorials`、`best-practices`、`troubleshooting`、`godot/resource` 等栏目结果保持有效。 -- `2026-04-25` `docs/zh-CN/source-generators/index.md` 已按 PR `#292` review 调整“共享支撑模块”段落句式，避免“对读者更重要的判断是”这类拗口表达。 -- `2026-04-25` `tools/gframework-config-tool/README.md` 已新增 `Documentation` 章节，直接链接到 `docs/zh-CN/game/config-tool.md` 与 `config-system.md`，让工具 README 能回到完整中文接入文档。 -- `2026-04-26` `tools/gframework-config-tool/README.md` 已补 `Quick Start`，把安装扩展、配置 `configPath` / `schemasPath`、打开 Explorer、先跑校验、再进入表单 / 批量编辑的最小接入路径串起来，并把 `Validation Coverage` 的 `stable config-schema subset` 统一为 `current schema subset`。 -- `2026-04-27` `docs/zh-CN/getting-started/installation.md` 已补齐当前公开选包矩阵，新增 `Core.Abstractions`、`Game.Abstractions`、`Ecs.Arch`、`Ecs.Arch.Abstractions` 的 reader-facing 安装说明，并把 `Godot` 常见问题里的旧版 `>= 4.5` 提示收敛到当前 `4.6.2` 基线。 -- `2026-04-27` `GFramework.Core.Abstractions/README.md`、`GFramework.Game.Abstractions/README.md`、`GFramework.Game.SourceGenerators/README.md`、`GFramework.Ecs.Arch.Abstractions/README.md` 当前都已把 XML 阅读入口改写为“代表类型 + 阅读重点”，不再暴露覆盖计数、日期或 `已覆盖` 这类治理字段。 -- `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` 新一轮 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` 这类维护与内部语气改写成当前采用说明。 -- `2026-04-27` 已重新抓取 PR `#296` 并逐条复核 latest-head review：`GFramework.Game.SourceGenerators/README.md` 的 XML 阅读表已改成语义标签，`GFramework.Game/README.md` 已删除重复的 `storage.md` 入口，`docs/zh-CN/tutorials/godot-integration.md` 与 `docs/zh-CN/godot/extensions.md` 已收口仍成立的 reader-facing 措辞问题。 -- `2026-04-25` 当前批次已补齐 meta-package / 安装面：`GFramework.csproj` 不再保留占位描述，`README.md`、`docs/zh-CN/index.md`、`docs/zh-CN/getting-started/installation.md` 当前明确说明聚合元包只聚合 `Core` + `Game`，并把安装入口更新到当前 `net8.0/net9.0/net10.0` 与 Godot `4.6.2` 基线。 -- `2026-04-25` `docs/zh-CN/game/config-tool.md` 已新增为 reader-facing 工具页，`docs/zh-CN/game/index.md`、`config-system.md`、`docs/.vitepress/config.mts` 与 `tools/gframework-config-tool/README.md` 当前把 VS Code 配置工具纳入 `Game` 配置工作流入口。 -- `2026-04-25` source-generators 栏目已修正 4 处真实契约问题：`GetNode` 显式路径 / `Lookup` 语义、枚举生成器实际开关、`Context Get` 集合注入边界，以及 `GFramework.SourceGenerators.Common` / `*.SourceGenerators.Abstractions` 的共享支撑层说明。 -- `2026-04-25` `GFramework.SourceGenerators.Common/README.md`、`GFramework.Core.SourceGenerators.Abstractions/README.md`、`GFramework.Godot.SourceGenerators.Abstractions/README.md` 已补齐本地目录说明，根 README 的“内部支撑模块”表可以直接跳到对应目录说明。 -- `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`、 - `GFramework.Godot.SourceGenerators/README.md`、`docs/zh-CN/godot/index.md`、 - `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/tutorials/godot-integration.md` 维持统一 owner / adoption path。 -- `2026-04-23` 到 `2026-04-24` 的批次细节、验证日志与旧恢复建议已迁入： - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md` - -## 当前风险 - -- 当前 `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 策略。 -- `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。 -- 当前分支 upstream 已 gone；在重新建立 remote branch 或新的 PR 之前，不适合再把旧 PR `#299` 的 review 状态当作默认恢复信号。 -- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；本轮仍是低风险措辞收口，但下一轮若继续深入 README 子系统地图或大段采用路径重写，review 面会明显扩大。 -- 当前工作树在 coverage 扩展后已接近 `$gframework-batch-boot 50` 的中后段窗口；如果继续新增 source-generator 或 README 专题，建议先提交本轮改动并重新计算 committed diff，再决定是否继续扩批。 -- `GFramework.Cqrs`、`GFramework.Cqrs.SourceGenerators`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 仍有若干源文件列表式“子系统地图”段落；这些已经接近结构级改写，不适合作为本轮剩余低风险批次继续机械推进。 +- `source-generators` 栏目已经补出 `Schema 配置生成器` 专题页，并把 `Game.SourceGenerators` 接回 landing、API 入口与侧栏。 +- `Cqrs.SourceGenerators` 的 fallback 精度、`GF_Cqrs_001` 诊断边界与共享支撑层阅读路线，当前已经回收进现有专题页与入口页，而不是继续扩成新的维护者导向页面。 +- `RP-049` 到 `RP-052` 的阶段细节、逐命令验证和批次决策已迁入归档；active 文档只保留当前恢复事实、风险、验证结果与下一步。 ## 归档指针 @@ -89,71 +39,46 @@ `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md` - 阶段状态归档（`RP-023` 到 `RP-025`）： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md` +- 阶段状态归档（`RP-049` 到 `RP-052`）： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md` - 时间线归档（`RP-001` 到 `RP-016`）： `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` - 时间线归档（`RP-023` 到 `RP-025`）： `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md` - 时间线归档（`RP-041` 到 `RP-048`）： `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` +- 时间线归档（`RP-049` 到 `RP-052`）： + `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md` - 验证历史归档（`RP-041` 到 `RP-048`）： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` +- 验证历史归档（`RP-049` 到 `RP-052`）： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` ## 最新验证 +- `2026-05-01` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` + - 结果：通过；新增“迁移与兼容性”小节后，页面的 frontmatter、链接与代码块校验仍然通过。 +- `2026-05-01` `bun run build`（工作目录：`docs/`） + - 结果：通过；active `ai-plan` 瘦身与 schema 专题页更新后站点仍可构建，仅保留既有大 chunk warning。 +- `2026-05-01` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` + - 结果：通过；PR `#308` 处于 `OPEN`，latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，测试汇总为 `2222 passed / 0 failed`，`Greptile` / `Gemini Code Assist` 当前无 open thread。 +- `2026-05-01` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review-after-fix.json` + - 结果：通过；remote latest reviewed commit 仍是 `097e97bcd66c89c79b4dafc30e24e8b650c7db63`，因此在本地改动尚未提交推送前，PR 页面仍显示同一批 `3` 条 open threads。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - - 结果：通过；新增 `Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。 + - 结果：通过；`Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` - - 结果：通过；source-generators landing 在补 `Schema 配置生成器` 与共享支撑层阅读路线后校验通过。 + - 结果：通过；source-generators landing 的链接与结构校验通过。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` - - 结果：通过；`Cqrs` generator 专题页新增策略层级与 fallback 精度说明后校验通过。 + - 结果：通过；`Cqrs` generator 专题页在补足 fallback 精度说明后校验通过。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` - - 结果：通过；`CQRS` 运行时页补充 generated registry 与 fallback 协作说明后校验通过。 + - 结果：通过；`CQRS` 运行时页在补足 generated registry 协作说明后校验通过。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` - - 结果：通过；API 入口页补充 `Game.SourceGenerators` 与共享 source-generator 支撑层阅读路线后校验通过。 + - 结果：通过；API 入口页在补充 source-generator 阅读路线后校验通过。 - `2026-04-30` `bun run build`（工作目录：`docs/`） - 结果：通过；新增 source-generators 专题页与侧栏入口后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md` - - 结果：通过；`game/data.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md` - - 结果：通过；`game/storage.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` - - 结果：通过；`godot/ui.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md` - - 结果：通过；本轮 2 个 README 的 reader-facing 标签调整后目标有效。 -- `2026-04-29` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮第 2 批 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` - - 结果：通过；`godot/storage.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` - - 结果：通过；`godot/setting.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md` - - 结果：通过；`godot/signal.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md` - - 结果：通过；`godot/logging.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md` - - 结果：通过；`godot/index.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/scene.md` - - 结果：通过；`game/scene.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md` - - 结果：通过；`game/config-system.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` - - 结果：通过；`core/index.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` - - 结果：通过；`ecs/arch.md` 的 frontmatter、链接与代码块校验通过。 -- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md tools/gframework-config-tool/README.md` - - 结果：通过；本轮 2 个 README 的 reader-facing 链接标签调整后目标有效。 -- `2026-04-29` `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-28` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#299` 处于 `OPEN`，latest head review 有 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 -- `2026-04-28` `bun run build`（工作目录：`docs/`） - - 结果：通过；active tracking 收口与时间线归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-04-27` 到 `2026-04-28` 的详细逐命令验证历史已迁入： - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` ## 下一步 -1. 若继续下一批，优先挑选“已有 package README、但站内专题仍不足”的模块入口，例如 `README` 与现有 docs 之间的采用路径补链；避免把 `SourceGenerators.Common` 之类共享支撑层继续扩写成维护者导向的独立专题。 -2. 在继续扩批前，先沿用当前 committed diff `8` files / `337` lines 作为新的 batch 起点，避免把提交前的工作树计量误当成现状。 -3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。 -4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 +1. 完成本轮 3 个 latest-head review follow-up 后，重新运行最小文档验证，并重新抓取 `$gframework-pr-review`，确认 remote open threads 是否清空。 +2. 若 review 线程清空，再继续按 `$gframework-batch-boot 50` 挑选“已有 package README、但站内专题仍不足”的 coverage 切片，而不是继续扩写共享支撑层。 +3. 若 `Title check` 仍保留，则单独修改 GitHub PR 标题，不把它和仓库文件内容混为同一类修复项。 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 593d6b45..0a60ce9c 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 @@ -1,472 +1,47 @@ # Documentation Full Coverage Governance Trace -## 2026-04-30 +## 2026-05-01 -### 当前恢复点：RP-052 +### 当前恢复点：RP-053 -- 本轮 coverage 扩展已提交为 `f88f96c3`（`docs(source-generators): 补充生成器专题覆盖并更新进度`）。提交后重新计算发现，committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines，工作树 clean，说明提交前的 `39` files / `2555` lines 只是临时工作树峰值，不应继续作为默认恢复指标。 -- 这次提交把 `Game.SourceGenerators` 的 schema 生成链路提升成独立 public docs 专题，并把 `Cqrs.SourceGenerators` 的 fallback 精度、共享 source-generator 支撑层的阅读路线，一并接回 landing / API / CQRS 入口。 -- 由于 stop-condition 余量重新恢复，下一轮仍可以继续沿 `$gframework-batch-boot 50` 推进，但应优先挑“已有模块、已有 README、站内专题仍不足”的 coverage 切片，而不是继续给共享支撑层单开页面。 +- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，且都落在 active tracking、active trace 与 `Schema 配置生成器` 专题页。 +- 本地复核确认这 3 条评论都仍成立：active `ai-plan` 文档累积了过多阶段性细节，而 `schema-config-generator.md` 缺少集中式的迁移与兼容性小节。 +- GitHub Test Reporter 当前汇总为 `2222 passed / 0 failed`；`Title check` 仍然只是 PR 元数据问题，因此不纳入仓库文件修复范围。 -### 当前决策（RP-052） +### 当前决策（RP-053） -- 把 `8` files / `337` lines 视作新的 authoritative branch-size baseline，而不是沿用提交前的工作树峰值。 -- 保留 `RP-051` 的结论：共享 source-generator 支撑层继续通过 landing / API 入口解释，不提升为独立 public docs 页面。 -- 后续若继续扩批，优先考虑 README 与站内 docs 之间仍缺的 reader-facing 采用链路，而不是只做措辞巡检。 +- active tracking 与 active trace 只保留当前恢复点、关键事实、风险、验证结论与下一步；`RP-049` 到 `RP-052` 的阶段细节迁入新的 archive 文件。 +- `Schema 配置生成器` 页新增独立的“迁移与兼容性”小节，集中说明从手写注册迁移的最小步骤、当前兼容边界与回退做法。 +- 本轮只做 latest-head review 精确收口，不扩展到新的 docs coverage 批次。 -### 当前验证（RP-052） - -- 继承 `RP-051` 的页面校验与 `bun run build` 成功结果。 -- 提交后状态确认： - - `git status --short --branch` - - `git diff --name-only origin/main...HEAD | wc -l` - - `git diff --numstat origin/main...HEAD` - - 结果：通过；当前分支工作树 clean，相对 `origin/main` 的 committed diff 为 `8` files / `337` lines。 - -### 下一步（RP-052） - -1. 继续同一主题时，把 `8` files / `337` lines 作为新的 batch 起点。 -2. 优先挑选“已有 package README、但站内专题仍不足”的 coverage 切片。 -3. 在 remote branch / PR 恢复之前，继续把 `origin/main` + committed branch diff 当作唯一 stop-condition 度量。 - -## 2026-04-29 - -### 当前恢复点：RP-051 - -- 本轮按 `$gframework-batch-boot 50` 恢复后，先确认 `HEAD` 与 `origin/main` `79f9cb37`（`2026-04-29 22:59:12 +08:00`）同步，committed diff 为 `0` files / `0` lines，因此允许把批次目标从“低风险句子收口”提升为“补新的 docs coverage 入口”。 -- 主线程保留实现与验证，同时接受了 2 个 explorer 的只读结论：一条用于判断 `SourceGenerators.Common` 是否值得升成独立 public page，一条用于判断 `Cqrs.SourceGenerators` 的真实公开缺口。accepted 结论是：共享 source-generator 支撑层更适合补 landing / API 入口，而 `Cqrs.SourceGenerators` 应增强现有专题页对策略层级与 fallback 精度的解释。 -- 一个 worker 曾被短暂分配去草拟独立 `shared-support-modules` 页面，但在 explorer 结论返回后被中断；最终无文件写入，也没有并行实现遗留。 -- 实际落地的 coverage 扩展集中在 6 个文件：新增 `docs/zh-CN/source-generators/schema-config-generator.md`，并更新 `docs/zh-CN/source-generators/index.md`、`docs/zh-CN/api-reference/index.md`、`docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`、`docs/zh-CN/core/cqrs.md` 与 `docs/.vitepress/config.mts`。 -- docs 页面与恢复文档更新完成后，工作树相对 `origin/main` 已到 `39` files / `2555` lines；仍低于 `50` 文件 stop condition，但本轮已不再适合继续新开第三类 coverage 切片。 - -### 当前决策（RP-051） - -- `Game.SourceGenerators` 当前公开缺口足够明确，因此直接补一张新的 reader-facing 专题页，专门解释 schema 输入契约、生成物形态、聚合注册入口和 `ConfigSchemaDiagnostics` 边界。 -- `SourceGenerators.Common`、`Core.SourceGenerators.Abstractions`、`Godot.SourceGenerators.Abstractions` 不提升为新的独立 public docs 页面，只在现有 landing / API 入口里补共享 diagnostics、attribute 契约与冲突规则的阅读路线。 -- `Cqrs.SourceGenerators` 不再新增第二张专题页，而是在现有 `cqrs-handler-registry-generator.md` 与 `core/cqrs.md` 内明确“有 fallback != 整程序集盲扫”、direct registration / reflected implementation / precise service type lookup / assembly fallback 的层级关系，以及 `GF_Cqrs_001` 的 reader-facing 判断顺序。 - -### 当前验证（RP-051） - -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` - - 结果：通过；本轮新增专题页与 4 个入口页 / 专题页校验全部通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；新增 `Schema 配置生成器` 侧栏入口后站点仍可构建，仅保留既有大 chunk warning。 - -### 下一步（RP-051） - -1. 提交本轮 source-generators / CQRS coverage 扩展批次，并把 committed diff vs `origin/main` 重新写回 active tracking。 -2. 若继续同一主题，优先挑选“已有用户面 package，但站内专题仍需补链”的模块，而不是继续给共享支撑层单开页面。 -3. 在 remote branch / PR 恢复之前，继续把 `origin/main` + branch-size 指标当作唯一 batch stop condition。 - -### 当前恢复点：RP-050 - -- 本轮继续按 `$gframework-batch-boot 50` 推进，并沿用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为唯一 branch-size baseline。 -- 当前 `HEAD` 相对 baseline 的 committed diff 仍是上一批的 `13` files / `133` lines；在本批次工作树修改与 `RP-050` 恢复文档更新后，working tree 相对 `origin/main` 为 `18` files / `225` lines，离 stop condition 仍有充足余量。 -- 本轮接受了 2 个 explorer 的只读排序：一个锁定 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 的低风险措辞问题，一个锁定 README 中仍能局部收口的标签问题。主线程只接受“改句子就能闭环”的项，不扩展到 README 结构重写。 -- 实际落地的收口集中在 5 个文件：`docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`。 - -### 当前决策（RP-050） - -- 文档页只处理内部证据口吻、命令式导流、外部项目指代和生硬 adoption phrasing；不改示例结构和导航层次。 -- README 只处理两类低风险项：把源文件路径列表改成类型级契约说明，把 `IsPackable=false` 这类实现术语改成 reader-facing 安装说明。 -- `GFramework.Cqrs`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 的大段源文件清单继续留到后续单独批次，因为那已经接近结构级重写，不适合和当前轻量文案收口混在一轮。 - -### 当前验证（RP-050） - -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md` - - 结果：通过；本轮 3 个页面的 frontmatter、链接与代码块校验全部通过。 -- README 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md` - - 结果：通过；本轮 2 个 README 的 reader-facing 标签调整后目标有效。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮第 2 批 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - -### 下一步（RP-050） - -1. 提交本轮第 2 批 reader-facing 文案批次，并更新 committed branch diff vs `origin/main` 的精确计量。 -2. 若继续下一批，优先挑选仍可局部收口的页面或 README 标签，不把结构级 README 改写混入同一轮。 -3. 只有在 remote branch / 新 PR 重新建立后，再恢复 `$gframework-pr-review` 作为默认恢复入口。 - -### 当前恢复点：RP-049 - -- 本轮按 `$gframework-batch-boot 50` 恢复，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`；当前 upstream `origin/docs/sdk-update-documentation` 已 gone，因此改用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为新的 branch-size baseline。 -- 恢复时 committed branch diff vs baseline 为 `0` files / `0` lines，因此可以安全开启新一轮低风险 reader-facing 文档批次。 -- 当前工作树在本批次与恢复文档更新后相对 `origin/main` 为 `13` files / `132` lines，离 `$gframework-batch-boot 50` 的主 stop condition 仍有充足余量。 -- 本轮接受了 2 个 explorer 的只读热点排序：一个巡检 `docs/zh-CN/game` 与 `docs/zh-CN/godot` 细页，一个巡检模块 README 的 reader-facing 标签；主线程只接受低风险措辞问题，不扩展到 README 子系统地图或结构重写。 -- 实际落地的收口集中在 11 个文件：`docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md`、`GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md`。 - -### 当前决策（RP-049） - -- 由于 upstream / 旧 PR 恢复路径已经失效，本轮不再以旧的 PR `#299` review 线程作为批处理驱动条件，而是以 `origin/main` + `50` changed files 作为唯一 stop condition。 -- 这批修改只处理 reader-facing 措辞、交叉链接语气和 README 标签，不改导航结构、不补新章节、不重写示例。 -- explorer 给出的 `GFramework.Cqrs` / `GFramework.Cqrs.Abstractions` README 源文件列表问题先不纳入本轮，因为那已经超出“低风险文案收口”边界。 - -### 当前验证（RP-049） - -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.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/godot/logging.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.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/config-system.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/ecs/arch.md` - - 结果：通过；本轮 9 个页面的 frontmatter、链接与代码块校验全部通过。 -- README 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Godot/README.md tools/gframework-config-tool/README.md` - - 结果：通过；本轮 2 个 README 的 reader-facing 链接标签调整后目标有效。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。 - -### 下一步（RP-049） - -1. 提交本轮 reader-facing 文案批次，并更新 branch diff vs `origin/main` 的精确计量。 -2. 若继续下一批，优先复核 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与少量 README 标签问题，不直接展开大段 README 子系统地图重写。 -3. 只有在 remote branch / 新 PR 重新建立后，再恢复 `$gframework-pr-review` 作为默认恢复入口。 - -## 2026-04-28 - -### 当前恢复点：RP-048 - -- 本轮按 `$gframework-pr-review` 抓取当前 PR `#299`，确认 latest head review 当前只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick；两者都指向 active tracking 文档本身，`Greptile` 与 `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，另有 `Title check` inconclusive。 -- 本地复核后确认：此前针对 `docs/zh-CN/abstractions/index.md`、`docs/zh-CN/core/lifecycle.md` 与相关教程 / 排障页的 review follow-up 已不再是当前 remote latest-head review 的剩余阻塞项。 -- 当前仍需收口的只剩两件事：为 `RP-048` 补齐明确的“下一步”段落，以及把 `RP-045` 到 `RP-047` 的逐命令时间线从 active trace 下沉到归档文件。 - -### 当前决策（RP-048） - -- 本轮限定只修改 `ai-plan/public/documentation-full-coverage-governance` 下的 tracking / trace 文档，不再扩展到已经收口的公开文档页面。 -- active trace 只保留当前恢复点、验证结论、下一步与归档指针；`RP-041` 到 `RP-048` 的阶段细节转入专门的 trace archive，逐命令验证继续保留在 validation history archive。 -- 不把 `Title check` 当成仓库文件修复项；本轮完成后只需要在提交推送后重新抓取 PR review，确认 remote 线程状态是否清空。 - -### 当前验证（RP-048） - -- PR review 抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --format json --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#299` 处于 `OPEN`，latest head review 有 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，仅剩 `Title check` inconclusive。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；active tracking 收口与时间线归档瘦身后站点仍可构建，仅保留既有大 chunk warning。 -- 详细时间线归档： - - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` -- 详细验证归档： - - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` - -### 下一步（RP-048） - -1. 提交本轮 active tracking 收口改动，并将提交推送到 PR `#299`。 -2. 推送后重新抓取 `$gframework-pr-review`，确认 latest-head review 是否只剩 `Title check` 或已全部清空。 -3. 若仍有新的文档 review 线程，继续按 latest-head review 精确收口，不恢复关键词驱动的机械扩批。 - -## 2026-04-27 - -### 已归档历史（RP-041 到 RP-047） - -- `RP-045` 到 `RP-047` 的 batch boot 逐阶段时间线、branch diff 计量与 review follow-up 决策，已迁入专门的 trace archive，避免 active trace 继续保留逐命令历史。 -- 对应的页面校验、README 链接校验与站点构建命令，继续保留在 validation history archive 中，供后续追溯。 -- 归档路径： - - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` - - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` - -### 当前恢复点：RP-044 - -- 本轮从 `$gframework-pr-review` 重新进入，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并通过 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` 抓取当前 PR `#296`。 -- 抓取结果显示 latest reviewed commit 为 `5778782df05e22dd24dc95189dd768458afb8537`，共有 `4` 条 open thread：`GFramework.Game.SourceGenerators/README.md` 的表头仍带路径视角、`GFramework.Game/README.md` 有重复 `storage.md` 链接、`docs/zh-CN/tutorials/godot-integration.md` 与 `docs/zh-CN/godot/extensions.md` 还有 reader-facing 措辞收口空间。 -- 本地逐条复核后确认这 `4` 条都仍成立，但都属于低风险文档收口；唯一 failed check `Title check` 只是 PR 标题元数据提示，不属于仓库文件内修复范围。 - -### 当前决策（RP-044） - -- 接受 latest-head review 中仍成立的 `4` 条文档修正，不扩展到 review 未指向的其它页面，避免在当前接近 branch-size stop condition 的阶段继续增大 review 面。 -- 对 README 表格和导航问题，只做 reader-facing 命名与去重；对教程与 Godot 页面，只做措辞收口，不改变现有采用路径与示例结构。 -- 在同一轮里同步更新 active topic tracking / trace，并在提交前运行最小页面校验、README 链接校验与站点构建。 - -### 当前验证（RP-044） +### 当前验证（RP-053） - PR review 抓取： - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#296` 处于 `OPEN`，latest head review 共有 `4` 条 open thread，测试汇总为 `2156 passed`，仅剩 `Title check` inconclusive。 -- README 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md GFramework.Game/README.md` - - 结果：通过；本轮 2 个 README 的 reader-facing 表格与导航去重调整后链接目标有效。 + - 结果：通过；PR `#308` 处于 `OPEN`，latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，测试汇总为 `2222 passed / 0 failed`。 - 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md` - - 结果：通过；两页 frontmatter、链接与代码块校验均通过。 + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` + - 结果：通过；新增“迁移与兼容性”小节后页面校验通过。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 PR `#296` review 收口后的站点仍可构建，仅保留既有大 chunk warning。 - -### 当前恢复点：RP-043 - -- 在提交 `docs(reader-facing): 统一站内入口与公开术语` 后重新计算 branch diff，确认当前工作树继续补一批新文件后已到 `46` changed files，已经接近 `$gframework-batch-boot 50` 的停止线。 -- 因此本轮最后只接受 10 个还没进入 branch diff 的文件：`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` 之类维护 / 内部口吻改成当前采用指导，不扩新结构、不重写示例体系。 - -### 当前决策（RP-043） - -- 当前 stop condition 已接近阈值，因此这批验证通过后立即停止继续扩批，避免 branch diff 超过 `50` files 或让 review 面退化。 -- 提交后本轮默认结束；后续若继续，应从 PR review 或剩余未触达的细页重新开一轮，而不是在同一轮里继续堆文件数。 - -### 当前验证（RP-043） - -- 单页校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/setting.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/serialization.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/architecture.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/logging.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/extensions.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/architecture.md` - - 结果：通过；本轮 10 个新文件的 frontmatter、链接与代码块校验全部通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；接近阈值前的最后一批文案收口后站点仍可构建，仅保留既有大 chunk warning。 - -### 当前恢复点：RP-042 - -- 用户明确要求在当前阈值内循环推进，并允许使用 subagent 降低主线程上下文压力；因此本轮在主线程保留实现与验证，把热点识别委派给 3 个 explorer。 -- 接受的 subagent 结论主要有三类： - - 入口页最划算的改法是统一 reader-facing 骨架，而不是继续保留治理说明或负向 framing。 - - 若站内已有栏目页与专题页，GitHub blob README 不应继续作为公开文档主导航。 - - `GFramework.Game` / `Game.Abstractions` / `Godot` 等 README 仍有 `ai-libs`、`family`、`seam`、`ReadMe.md` 等对外不友好的措辞，适合在同一轮里收口。 -- 基于这些结论，本轮连续落地 3 组低风险切片：入口页 reader-facing 改写、README / Godot 页去内部口吻、剩余 GitHub blob README 外链改回站内入口。 - -### 当前决策（RP-042） - -- 继续保持 critical path 本地执行，不让 subagent 直接改文件；subagent 只负责热点排序与问题归类。 -- stop condition 继续沿用 `origin/main` + `50` changed files；当前工作树相对 baseline 的 tracked diff 已到 `36` files / `500` changed lines，意味着还能再做一小批，但应先提交当前稳定批次。 -- 当前批次不扩展到新栏目、新导航层或大段内容重写，只做 reader-facing 入口、术语和站内导航连通性收口。 - -### 当前验证（RP-042） - -- README 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game/README.md GFramework.Game.Abstractions/README.md GFramework.Godot/README.md GFramework.Cqrs.Abstractions/README.md GFramework.Ecs.Arch/README.md` - - 结果：通过；本轮 5 个 README 的 reader-facing 改写后链接目标有效。 -- 教程 / Godot 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/index.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/godot/scene.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/signal.md` - - 结果：通过；受影响页面的 frontmatter、链接与代码块校验通过。 -- 入口与专题页校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started/quick-start.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.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/ecs/arch.md` - - 结果：通过；入口页和相关推荐入口改写后页面校验通过。 -- 栏目级校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` - - 结果：通过；抽象层与生成器栏目改回站内入口后栏目校验通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮 3 组 reader-facing 文档批次后站点仍可构建，仅保留既有大 chunk warning。 - -### 当前恢复点：RP-041 - -- 通过 `$gframework-batch-boot 50` 重新进入后，先按仓库规则读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` 与 active topic tracking / trace，并继续使用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`。 -- 使用显式 Git 绑定确认最新 baseline 为 `origin/main` `617e0bf`（`2026-04-26 12:17:15 +08:00`），当前 committed branch diff vs baseline 为 `0` files，因此本轮继续选择低风险、reader-facing 文档切片。 -- 本轮收敛出的 3 组切片分别是：`installation.md` 的选包矩阵与旧版 Godot 提示、公开 README 的 XML 阅读入口去治理化，以及 `config-system` / 基础教程入口中的维护者口吻改写。 - -### 当前决策（RP-041） - -- 不扩展到导航结构或新专题页，只在现有入口上修正 reader-facing 采用路径与表述一致性。 -- 对公开 README 中的 XML 阅读入口，统一改成“代表类型 + 阅读重点”，不再暴露覆盖计数、日期或 `已覆盖` 这类治理字段。 -- stop condition 继续沿用 `origin/main` + `50` changed files；本轮工作树相对 baseline 的 tracked diff 为 `9` files / `191` changed lines，仍明显低于阈值。 - -### 当前验证（RP-041） - -- README 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.Abstractions/README.md GFramework.Game.Abstractions/README.md GFramework.Game.SourceGenerators/README.md GFramework.Ecs.Arch.Abstractions/README.md` - - 结果：通过；本轮 4 个 README 的 reader-facing 改写后链接目标有效。 -- 入门栏目校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/getting-started` - - 结果：通过；`installation.md` 更新后 `getting-started` 栏目 frontmatter、链接与代码块校验通过。 -- 配置系统页校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/config-system.md` - - 结果：通过；工具形态建议改写后页面校验通过。 -- 基础教程栏目校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic` - - 结果：通过；入口页阅读路径改写后栏目校验通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮文档批次后站点仍可构建，仅保留既有大 chunk warning。 - -## 2026-04-26 - -### 当前恢复点：RP-040 - -- 本轮继续从 `$gframework-pr-review` 恢复，沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并重新抓取 PR `#292` 的 latest-head review。 -- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#292` 最新 reviewed commit 为 `d3d62cf4541063c46458f88eea0f5acd1b4503f9`，failed checks 为 `0`，测试汇总仍为 `2156 passed`；剩余 `2` 条 CodeRabbit open thread 都落在 `tools/gframework-config-tool/README.md`。 -- 本地逐项复核后确认：缺少 `docs/zh-CN` 链接的评论已经过期，因为 README 当前已有 `Documentation` 章节；仍成立的是补最小接入路径，以及统一 `stable config-schema subset` / `current schema subset` 术语。 - -### 当前决策（RP-040） - -- 接受当前 latest-head review 中仍然成立的两项 README 收口：新增 `Quick Start` 最小接入路径，并统一校验支持范围术语。 -- 不对已经过期的“缺少中文文档入口链接”线程做额外扩展，只在本地结果里保留“已验证为 stale”的结论，等待后续 PR review 刷新反映最新状态。 -- 继续遵守 active topic 的恢复要求，在同一轮里同步更新 tracking / trace，并对直接受影响的工具模块执行最小验证。 - -### 当前验证（RP-040） - -- PR review 抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` - - 结果：通过；PR `#292` 处于 `OPEN`，latest head review 还有 `2` 条 CodeRabbit open thread，failed checks 为 `0`，测试汇总为 `2156 passed`。 -- 工具 README 收口： - - `tools/gframework-config-tool/README.md` - - 结果：已新增 `Quick Start` 段落，并把 `Validation Coverage` 术语统一为 `current schema subset`。 -- 工具测试： - - `bun run test`（工作目录：`tools/gframework-config-tool/`） - - 结果：通过；`122` 个测试全部通过。 -- 工具打包： - - `bun run package:vsix`（工作目录：`tools/gframework-config-tool/`） - - 结果：通过；成功生成 `gframework-config-tool-0.0.3.vsix`，确认工具模块可完成最小打包验证。 - -## 2026-04-25 - -### 当前恢复点：RP-039 - -- 本轮从 `$gframework-pr-review` 重新进入，先按仓库规则读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` 与 active topic tracking / trace，并继续使用显式 `--git-dir` / `--work-tree` 绑定确认当前分支为 `docs/sdk-update-documentation`。 -- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#292` 最新 reviewed commit 为 `b96565ffa367bade30f44c2d4e8955143fbff85e`，latest head review 仅剩 `2` 条 CodeRabbit open thread，无 failed tests；唯一 failed check 为 `Title check` inconclusive，属于 PR 标题文案元数据提示。 -- 本地逐项复核后，两条 review 仍成立且都属于低风险 reader-facing 修正： - - `docs/zh-CN/source-generators/index.md` 的“共享支撑模块”段落中，句式“对读者更重要的判断是”略拗口。 - - `tools/gframework-config-tool/README.md` 缺少通往 `docs/zh-CN/game/config-tool.md` 的中文接入文档入口。 - -### 当前决策（RP-039） - -- 接受这两条 latest-head review，并限定本轮只做文案可读性与 README 入口补链，不扩展到未被当前 review 指向的其它页面。 -- `Title check` 不通过仓库文件修复；保持在本轮结果中显式记录，等待后续通过 GitHub PR 标题更新处理。 -- 继续沿用 active topic 的治理要求，在同一变更里同步更新 tracking / trace，保证后续从 PR review 恢复时能直接看到最新 commit 与剩余风险。 - -### 当前验证（RP-039） - -- PR review 抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` - - 结果：通过；PR `#292` 处于 `OPEN`，latest head review 还有 `2` 条 CodeRabbit open thread，测试汇总为 `2156 passed`，无 failed tests，另有 `Title check` inconclusive。 - -### 当前恢复点：RP-038 - -- 用户明确要求从“低效的单次批次”切到“循环跑到接近阈值”，并允许通过 subagent 避免主线程上下文过长；因此本轮把批处理目标从 PR `#290` 的单点收口扩展为“覆盖整个项目功能的 reader-facing 文档补齐”。 -- 先在主线程确认 critical path 仍是“选定低风险文档切片并控制 branch-size stop condition”，再委派 3 个 explorer 做只读巡检： - - source-generator support modules / 文档失真点 - - CQRS 文档覆盖缺口 - - repo-root / tooling / meta-package surface -- 接受的 explorer 结论： - - `CQRS` 当前不需要扩独立栏目；最小有用修复是补 `docs/zh-CN/core/cqrs.md` 对 `RequestBase`、stream command/query 与协程入口的说明。 - - source-generators 当前最有价值的是修正文档失真，并补清楚 `GFramework.SourceGenerators.Common` 与 `*.SourceGenerators.Abstractions` 的共享支撑层语义。 - - repo-root / tooling 当前最缺的是 meta-package / install surface、VS Code config tool adoption path，以及 repo-visible support module README。 -- 由此收敛出 5 组连续低风险批次： - - meta-package / 安装入口 - - config tool adoption - - source-generators 真实契约修正 - - CQRS `Request` / stream 覆盖补齐 - - generator support module README - -### 当前决策（RP-038） - -- 不把 `CQRS` 从 `Core` 导航中抽成新栏目；本轮优先修正 reader-facing 覆盖缺口，而不是引入新的站点结构。 -- 对 repo-visible support modules，不扩成新的 docs 栏目，而是在各目录本地补 `README.md` 说明“为什么存在、跟谁一起走、什么时候需要读这里”。 -- 对 config tool，不新建顶级 `tooling/` 栏目，而是挂到 `Game` 下，保持它与 `config-system` 的采用路径一致。 -- stop condition 仍按 `origin/main` 与 `50` changed files 追踪；本轮提交前工作树已触达 `18` 个文件，仍明显低于阈值。 - -### 当前验证（RP-038） - -- 文档栏目校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/index.md` - - 结果：通过；触达页 frontmatter、链接与代码块校验通过。 -- README / 链接校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh README.md tools/gframework-config-tool/README.md GFramework.SourceGenerators.Common/README.md GFramework.Core.SourceGenerators.Abstractions/README.md GFramework.Godot.SourceGenerators.Abstractions/README.md` - - 结果：通过；根 README、config tool README 与新增 support README 的链接目标有效。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；站点可构建，仅保留既有大 chunk warning。 -- 元包编译： - - `dotnet build GFramework.csproj -c Release` - - 结果：通过；输出 `357` 条既有 analyzer warnings，无新增错误。 - -### 当前恢复点：RP-037 - -- 通过 `$gframework-batch-boot 50` 重新进入后，先按技能要求读取 `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md`、active topic tracking / trace，并确认当前 worktree 仍映射到 `documentation-full-coverage-governance`。 -- 使用显式 `git --git-dir=/.git/worktrees/GFramework-update-documentation --work-tree=` 绑定确认 baseline 采用 `origin/main` `79934f7`（`2026-04-25 16:15:55 +08:00`）；branch diff vs baseline 当前为 `0` files，工作树仅有本批次改动。 -- 全量运行 `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` 后确认 reader-facing 文档仅剩 `docs/zh-CN/contributing.md:631` 这一条既有代码块语言警告，适合作为单文件低风险批次收口。 -- 将 `docs/zh-CN/contributing.md` 的 Mermaid 示例从“真实嵌套 triple-backtick”改写为“外层 fenced block + 内层转义围栏文本”，避免当前 `validate-code-blocks.sh` 的简单 `^```` 状态机把内层 closing fence 误判成缺语言标记的新 opening fence。 - -### 当前决策（RP-037） - -- 当前批处理目标收敛为“消除 `contributing.md` 中最后一个剩余代码块语言 warning”，不再继续扩展到别的栏目页。 -- 继续沿用 `origin/main` 作为 branch-size stop condition 基线，主指标仍是 `50` changed files；本批次只新增 1 个工作树文件，远未逼近阈值。 -- 对这类“文档中展示 Markdown 代码块”的示例，优先选择仓库现有校验脚本可稳定识别的转义文本写法，而不是依赖嵌套 fenced block 的解析细节。 - -### 当前验证（RP-037） - -- 文档单文件校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/contributing.md` - - 结果：通过；`docs/zh-CN/contributing.md` 不再报告第 `631` 行代码块语言警告。 -- 文档全量校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN` - - 结果：通过；当前 `docs/zh-CN` 的 frontmatter、链接与代码块校验全部通过。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；站点仍可构建，仅保留既有大 chunk warning。 - -### 当前恢复点：RP-036 - -- 本轮从 `$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-036） - -- 对 PR review 的处理改成“只修当前 latest-head review 仍成立的问题”，不再延续前一轮的批量普查节奏。 -- `api-reference` 侧栏不再承载跨栏目目录跳转；跨模块导航继续保留在 `docs/zh-CN/api-reference/index.md` 的正文里，避免侧栏在跳出栏目后发生上下文切换。 -- `source-generators` 侧栏项统一与目标文档的 H1 / frontmatter `title` 对齐，避免同一页面在导航、标题与搜索索引里出现多套命名。 -- 模块 README 的 XML 阅读表只保留读者有用的“代表类型 / 阅读重点”，把覆盖计数、日期和 `已覆盖` 之类治理痕迹全部留在 `ai-plan/**`。 - -### 当前验证（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 GFramework.Core/README.md GFramework.Ecs.Arch/README.md GFramework.Game/README.md` - - 结果：通过；本轮 3 个 README 调整后链接目标仍然有效。 -- 站点构建： - - `bun run build`（工作目录：`docs/`） - - 结果：通过；`docs/.vitepress/config.mts` 的侧栏调整后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；active `ai-plan` 瘦身与 schema 专题页更新后站点仍可构建，仅保留既有大 chunk warning。 +- 复核抓取： + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review-after-fix.json` + - 结果：通过；由于 remote latest reviewed commit 仍未变化，本地未提交推送时 PR 页面仍显示同一批 `3` 条 open threads。 ### 归档指针 -- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md` -- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md` -- `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md` -- `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md` -- `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md` +- `RP-041` 到 `RP-048` 的阶段时间线： + `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-041-to-rp-048-2026-04-28.md` +- `RP-049` 到 `RP-052` 的阶段时间线： + `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md` +- `RP-041` 到 `RP-048` 的验证明细： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-041-to-rp-048-2026-04-28.md` +- `RP-049` 到 `RP-052` 的验证明细： + `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` -### 下一步 +### 下一步（RP-053） -1. 完成 `bun run build` 与 README 链接校验后，提交当前 PR `#290` review 收口批次。 -2. 提交后再次运行 `$gframework-pr-review`，确认 CodeRabbit / Greptile 的 open thread 是否已关闭。 -3. 若仍有 review 残留，再按 latest-head review 精确收口，不恢复到前一轮的广覆盖批处理模式。 +1. 提交本轮 active `ai-plan` 瘦身与 `Schema 配置生成器` 迁移说明补充。 +2. 运行最小文档验证并重新抓取 `$gframework-pr-review`，确认 latest-head review 是否已清空。 +3. 若只剩 `Title check`，则把后续动作限定为 GitHub PR 标题修正，不继续在仓库里做无关变更。 diff --git a/docs/zh-CN/source-generators/schema-config-generator.md b/docs/zh-CN/source-generators/schema-config-generator.md index 0d78eb45..767d2e69 100644 --- a/docs/zh-CN/source-generators/schema-config-generator.md +++ b/docs/zh-CN/source-generators/schema-config-generator.md @@ -165,6 +165,27 @@ var bootstrap = new GameConfigBootstrap( 当你需要继续手动拼装运行时，也可以直接用单表绑定或聚合目录做自己的注册封装。这时建议把“启动生命周期”和“业务读取入口”分开，继续沿用 [游戏内容配置系统](../game/config-system.md) 里的 `GameConfigHost` / `GameConfigRuntime` 模板。 +## 迁移与兼容性 + +如果你当前项目还在手写逐表注册，最小迁移路径可以按下面的顺序推进： + +1. 保持 `GeWuYou.GFramework.Game` 与 `GeWuYou.GFramework.Game.SourceGenerators` 版本一致，并把生成器包声明为 `PrivateAssets="all"` 的编译期依赖。 +2. 把现有 schema 收敛到 `schemas/**/*.schema.json`，或在项目文件中显式设置 `GFrameworkConfigSchemaDirectory`。 +3. 用 `RegisterAllGeneratedConfigTables(...)` 替换启动阶段里手写的逐表注册代码，再按需通过 `GeneratedConfigRegistrationOptions` 补充单表比较器或个别覆盖。 +4. 继续保留原有运行时消费入口，例如 `GameConfigBootstrap`、`YamlConfigLoader`、`GameConfigHost` 或 `GameConfigRuntime`，避免把“生成注册入口切换”与“运行时读取方式重写”混成同一步。 + +当前兼容边界主要有三类： + +- 生成器只覆盖当前公开的 schema 子集；如果现有 schema 使用了尚未支持的结构或元数据，编译期会通过 `ConfigSchemaDiagnostics` 直接暴露，而不会静默退回到手写模型。 +- `x-gframework-index`、路径元数据和标识符映射都要求满足安全约束；旧项目里依赖宽松命名或不安全路径的配置，需要先整理 schema，再切换到聚合注册入口。 +- 迁移到生成链路后，运行时读取模型保持不变，但“表类型定义”和“注册目录”会改为编译期输出，因此自定义扩展更适合挂在单表绑定或 `ConfigureLoader` 阶段，而不是继续复制生成器会维护的样板代码。 + +如果你需要分批迁移，当前更稳妥的回退方式是只回退注册入口，而不是同时回退 schema 结构： + +- 可以先让一部分表继续沿手写注册保留，另一部分切到生成的单表绑定或聚合注册。 +- 如果某张表在迁移后触发诊断，优先根据诊断 ID 收敛 schema，再决定是否临时回到手写注册。 +- 当项目已经接受 schema 目录约定后，尽量不要再把生成链路和旧的命名 / 路径规则长期并存，否则后续维护会同时承担两套约束。 + ## 常见诊断边界 当前 `ConfigSchemaDiagnostics` 暴露的错误主要分成四类： From 4fdb1e7398e4f114757b5c988698af203dce24c8 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 1 May 2026 13:29:52 +0800 Subject: [PATCH 4/7] =?UTF-8?q?docs(ai-plan):=20=E6=94=B6=E5=8F=A3=20PR=20?= =?UTF-8?q?=E5=AE=A1=E6=9F=A5=E9=81=97=E7=95=99=E6=96=87=E6=A1=A3=E9=97=AE?= =?UTF-8?q?=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修复 documentation-full-coverage-governance 归档中的 Markdown 行内代码闭合错误 - 更新 active tracking 与 trace，使其反映 PR #308 review 的本地核验结论 - 补充本轮文档构建验证结果与后续恢复步骤 --- ...tus-history-rp-049-to-rp-052-2026-05-01.md | 6 ++-- ...ace-history-rp-049-to-rp-052-2026-05-01.md | 2 +- ...ation-full-coverage-governance-tracking.md | 23 +++++++------- ...entation-full-coverage-governance-trace.md | 30 ++++++++----------- 4 files changed, 27 insertions(+), 34 deletions(-) diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md index 7c56f6dd..373cda30 100644 --- a/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md +++ b/ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-049-to-rp-052-2026-05-01.md @@ -9,14 +9,14 @@ ## 2026-04-29 / RP-049 - 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但上游恢复路径不再依赖旧 PR 线程，而是改用 `origin/main` 作为 batch stop-condition baseline。 -- 本轮工作树在 reader-facing 文案收口后相对 `origin/main` 来到 `13` files / `132` lines`，仍明显低于 `$gframework-batch-boot 50` 的阈值。 +- 本轮工作树在 reader-facing 文案收口后相对 `origin/main` 来到 `13` files / `132` lines，仍明显低于 `$gframework-batch-boot 50` 的阈值。 - 主线程接受的变更范围限定在 `docs/zh-CN/godot/*`、`game/*` 和少量 README 标签，不扩展到导航重写或大型结构改稿。 ## 2026-04-29 / RP-050 - 在 `RP-049` 的基础上继续做第 2 批低风险 reader-facing 收口，触达 `game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`。 - 决策上只接受“改句子即可闭环”的问题，不把 README 子系统地图或结构级重写混入同一轮。 -- 当轮工作树相对 `origin/main` 为 `18` files / `225` lines`，仍保留充足余量。 +- 当轮工作树相对 `origin/main` 为 `18` files / `225` lines，仍保留充足余量。 ## 2026-04-29 / RP-051 @@ -27,5 +27,5 @@ ## 2026-04-30 / RP-052 - 该批次提交为 `f88f96c3`（`docs(source-generators): 补充生成器专题覆盖并更新进度`）。 -- 提交后重新计算确认 committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines`，说明提交前的 `39` files / `2555` lines` 只是临时工作树峰值，不应继续作为默认恢复指标。 +- 提交后重新计算确认 committed branch diff vs `origin/main` 已回落到 `8` files / `337` lines，说明提交前的 `39` files / `2555` lines 只是临时工作树峰值，不应继续作为默认恢复指标。 - active topic 后续仍可以继续按 `$gframework-batch-boot 50` 推进，但应优先挑“已有 package README、但站内专题仍不足”的覆盖切片。 diff --git a/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md index a9df893c..7cf43a69 100644 --- a/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md +++ b/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md @@ -26,6 +26,6 @@ ## 2026-04-30 / RP-052 -- 这一轮 coverage 扩展提交为 `f88f96c3`，提交后 branch diff 相对 `origin/main` 回落到 `8` files / `337` lines`，重新释放了 stop-condition 余量。 +- 这一轮 coverage 扩展提交为 `f88f96c3`，提交后 branch diff 相对 `origin/main` 回落到 `8` files / `337` lines，重新释放了 stop-condition 余量。 - active topic 后续仍可继续扩批，但更适合选择“已有 package README、但站内 docs 仍缺 reader-facing 专题”的切片，而不是继续给共享支撑层单开页面。 - 该状态也为后续用 `$gframework-pr-review` 精确跟进最新 review 线程提供了更清晰的恢复入口。 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 f3cd335f..efc051d2 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 @@ -10,19 +10,20 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-053` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-054` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 处理 PR `#308` latest-head review 中仍成立的 3 条 `CodeRabbit` open threads：继续瘦身 active `ai-plan` 文档，并为 `Schema 配置生成器` 专题补集中式迁移与兼容性说明 + - 处理 PR `#308` latest-head review 中经本地复核仍成立的 `CodeRabbit` open threads，并清理 active `ai-plan` 对旧结论的漂移 - 当前事实： - - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 为 `097e97bcd66c89c79b4dafc30e24e8b650c7db63` - - 当前 latest-head review 只剩 `CodeRabbit` `3` 条 open threads，分别指向本 tracking、active trace 和 `docs/zh-CN/source-generators/schema-config-generator.md` + - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 为 `241c9ffeb3dbd11872b23ecf4a80971feeca475b` + - 当前 latest-head review 只剩 `CodeRabbit` `3` 条 open threads，但本地复核后只有 `2` 条仍然成立，均指向 `documentation-full-coverage-governance` 的归档 Markdown 反引号问题 + - `docs/zh-CN/source-generators/schema-config-generator.md` 已包含独立的“迁移与兼容性”章节，因此对应 open thread 现阶段应视为 stale，等待提交推送后再由远端重新计算 - GitHub Test Reporter 汇总为 `2222 passed / 0 failed` - `Title check` 仍为 `Inconclusive`，属于 PR 元数据问题，不是仓库文件内可直接修复的阻塞项 - - 本地已完成 review 指向文件的收口，但在变更尚未提交推送前，重新抓取的 PR review 仍会继续显示旧的 latest reviewed commit 与同一批 open threads + - 本地对 review 指向文件的修复在提交推送前，不会改变远端 latest reviewed commit 与 open-thread 统计 - 当前风险： - - active tracking / trace 若继续保留阶段性细节与逐项验证，会再次偏离“快速恢复入口”的用途 - - `Schema 配置生成器` 页已经说明边界，但迁移步骤、兼容边界和回退方式仍分散在多个段落中 + - 如果 active tracking / trace 继续保留已失效的 review 判断，会让后续恢复点重复处理已经本地闭环的问题 + - 在变更推送前，PR 页面仍会继续展示旧的 open-thread 数量，容易把 stale 线程误判为新的本地缺陷 ## 当前状态摘要 @@ -62,8 +63,6 @@ - 结果：通过；active `ai-plan` 瘦身与 schema 专题页更新后站点仍可构建，仅保留既有大 chunk warning。 - `2026-05-01` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#308` 处于 `OPEN`，latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，测试汇总为 `2222 passed / 0 failed`，`Greptile` / `Gemini Code Assist` 当前无 open thread。 -- `2026-05-01` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review-after-fix.json` - - 结果：通过；remote latest reviewed commit 仍是 `097e97bcd66c89c79b4dafc30e24e8b650c7db63`，因此在本地改动尚未提交推送前，PR 页面仍显示同一批 `3` 条 open threads。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - 结果：通过；`Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` @@ -79,6 +78,6 @@ ## 下一步 -1. 完成本轮 3 个 latest-head review follow-up 后，重新运行最小文档验证，并重新抓取 `$gframework-pr-review`，确认 remote open threads 是否清空。 -2. 若 review 线程清空，再继续按 `$gframework-batch-boot 50` 挑选“已有 package README、但站内专题仍不足”的 coverage 切片，而不是继续扩写共享支撑层。 -3. 若 `Title check` 仍保留，则单独修改 GitHub PR 标题，不把它和仓库文件内容混为同一类修复项。 +1. 提交并推送本轮归档修正与 active `ai-plan` 事实校正，然后重新抓取 `$gframework-pr-review`，确认 remote open threads 是否只剩 stale / metadata 项。 +2. 若 review 线程清空或只剩 `Title check`，再按 `$gframework-batch-boot 50` 继续挑选新的 coverage 切片，避免在同一轮混入无关改稿。 +3. 若远端仍保留 schema 页线程，则基于推送后的 latest reviewed commit 再判断是否需要单独在 PR 上回复说明，而不是继续修改已覆盖的本地文档。 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 0a60ce9c..7b89c15c 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,32 +2,26 @@ ## 2026-05-01 -### 当前恢复点：RP-053 +### 当前恢复点：RP-054 -- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，且都落在 active tracking、active trace 与 `Schema 配置生成器` 专题页。 -- 本地复核确认这 3 条评论都仍成立：active `ai-plan` 文档累积了过多阶段性细节，而 `schema-config-generator.md` 缺少集中式的迁移与兼容性小节。 +- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，分别落在两份归档文档与 `Schema 配置生成器` 专题页。 +- 本地复核确认真正仍成立的是 `2` 条归档 Markdown 反引号问题；`schema-config-generator.md` 已包含独立的“迁移与兼容性”小节，因此该线程目前应视为 stale。 - GitHub Test Reporter 当前汇总为 `2222 passed / 0 failed`；`Title check` 仍然只是 PR 元数据问题，因此不纳入仓库文件修复范围。 -### 当前决策（RP-053） +### 当前决策（RP-054） -- active tracking 与 active trace 只保留当前恢复点、关键事实、风险、验证结论与下一步；`RP-049` 到 `RP-052` 的阶段细节迁入新的 archive 文件。 -- `Schema 配置生成器` 页新增独立的“迁移与兼容性”小节，集中说明从手写注册迁移的最小步骤、当前兼容边界与回退做法。 +- 修复两份 `documentation-full-coverage-governance` 归档里的 Markdown 行内代码闭合错误，避免 reader-facing archive 文档继续触发 review。 +- active tracking 与 active trace 改写为与本地核验一致的事实，不再把已经落地的 schema 专题页补充误记为待办。 - 本轮只做 latest-head review 精确收口，不扩展到新的 docs coverage 批次。 -### 当前验证（RP-053） +### 当前验证（RP-054） - PR review 抓取： - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - 结果：通过；PR `#308` 处于 `OPEN`，latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，测试汇总为 `2222 passed / 0 failed`。 -- 页面校验： - - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - - 结果：通过；新增“迁移与兼容性”小节后页面校验通过。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；active `ai-plan` 瘦身与 schema 专题页更新后站点仍可构建，仅保留既有大 chunk warning。 -- 复核抓取： - - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review-after-fix.json` - - 结果：通过；由于 remote latest reviewed commit 仍未变化，本地未提交推送时 PR 页面仍显示同一批 `3` 条 open threads。 + - 结果：通过；本轮归档 Markdown 修正与 active `ai-plan` 更新后站点仍可构建，仅保留既有大 chunk warning。 ### 归档指针 @@ -40,8 +34,8 @@ - `RP-049` 到 `RP-052` 的验证明细： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` -### 下一步（RP-053） +### 下一步（RP-054） -1. 提交本轮 active `ai-plan` 瘦身与 `Schema 配置生成器` 迁移说明补充。 -2. 运行最小文档验证并重新抓取 `$gframework-pr-review`，确认 latest-head review 是否已清空。 -3. 若只剩 `Title check`，则把后续动作限定为 GitHub PR 标题修正，不继续在仓库里做无关变更。 +1. 提交并推送本轮 follow-up 后重新抓取 `$gframework-pr-review`，确认 remote open threads 是否只剩 stale / metadata 项。 +2. 若只剩 `Title check`，则把后续动作限定为 GitHub PR 标题修正，不继续在仓库里做无关变更。 +3. 若远端仍保留 schema 页线程，则基于推送后的 latest reviewed commit 再判断是否需要在 PR 上补充回复说明。 From 896e3efaa9c7496043fdaeee4dceff3d0e46b318 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 1 May 2026 15:37:26 +0800 Subject: [PATCH 5/7] =?UTF-8?q?docs(source-generators):=20=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=20PR=20=E5=AE=A1=E6=9F=A5=E4=B8=AD=E7=9A=84=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=85=A5=E5=8F=A3=E8=A1=A8=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 source-generators 文档中的测试入口表述，使用语义化链接标签替代源码路径 - 校正 documentation-full-coverage-governance active ai-plan 的 PR 审查事实、验证结果与下一步恢复点 --- ...ation-full-coverage-governance-tracking.md | 28 ++++++++-------- ...entation-full-coverage-governance-trace.md | 32 +++++++++++-------- .../cqrs-handler-registry-generator.md | 7 ++-- .../schema-config-generator.md | 6 +++- 4 files changed, 43 insertions(+), 30 deletions(-) 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 efc051d2..220eba28 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 @@ -10,20 +10,20 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-054` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-055` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 处理 PR `#308` latest-head review 中经本地复核仍成立的 `CodeRabbit` open threads，并清理 active `ai-plan` 对旧结论的漂移 + - 处理 PR `#308` 当前 latest-head review 与 outside-diff review 中经本地复核仍成立的 reader-facing 文档表述问题，并清理 active `ai-plan` 对旧结论的漂移 - 当前事实： - - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 为 `241c9ffeb3dbd11872b23ecf4a80971feeca475b` - - 当前 latest-head review 只剩 `CodeRabbit` `3` 条 open threads，但本地复核后只有 `2` 条仍然成立，均指向 `documentation-full-coverage-governance` 的归档 Markdown 反引号问题 - - `docs/zh-CN/source-generators/schema-config-generator.md` 已包含独立的“迁移与兼容性”章节，因此对应 open thread 现阶段应视为 stale，等待提交推送后再由远端重新计算 + - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 已前进到 `4fdb1e7398e4f114757b5c988698af203dce24c8` + - 当前 `CodeRabbit` 仍有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment；本地复核后真正成立的是 `2` 条 reader-facing 文档问题，分别位于 `schema-config-generator.md` 与 `cqrs-handler-registry-generator.md` 的测试入口表述 + - `docs/zh-CN/source-generators/schema-config-generator.md` 已包含独立的“迁移与兼容性”章节，因此对应 major open thread 现阶段应视为 stale，等待提交推送后再由远端重新计算 - GitHub Test Reporter 汇总为 `2222 passed / 0 failed` - `Title check` 仍为 `Inconclusive`，属于 PR 元数据问题，不是仓库文件内可直接修复的阻塞项 - 本地对 review 指向文件的修复在提交推送前，不会改变远端 latest reviewed commit 与 open-thread 统计 - 当前风险： - - 如果 active tracking / trace 继续保留已失效的 review 判断，会让后续恢复点重复处理已经本地闭环的问题 - - 在变更推送前，PR 页面仍会继续展示旧的 open-thread 数量，容易把 stale 线程误判为新的本地缺陷 + - 如果 active tracking / trace 继续保留旧的 commit SHA 和 review 归因，会让后续恢复点重复处理已经本地闭环的问题 + - 在变更推送前，PR 页面仍会继续展示旧的 open-thread / outside-diff 数量，容易把 stale 线程误判为新的本地缺陷 ## 当前状态摘要 @@ -58,11 +58,13 @@ ## 最新验证 - `2026-05-01` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - - 结果：通过；新增“迁移与兼容性”小节后，页面的 frontmatter、链接与代码块校验仍然通过。 + - 结果：通过；在把测试入口改成语义化链接后，页面的 frontmatter、链接与代码块校验仍然通过。 +- `2026-05-01` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` + - 结果：通过；测试源码路径改成语义化链接标签后，页面的 frontmatter、链接与代码块校验通过。 - `2026-05-01` `bun run build`（工作目录：`docs/`） - - 结果：通过；active `ai-plan` 瘦身与 schema 专题页更新后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；两篇 source-generators 页面链接改写与 active `ai-plan` 事实更新后站点仍可构建，仅保留既有大 chunk warning。 - `2026-05-01` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#308` 处于 `OPEN`，latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，测试汇总为 `2222 passed / 0 failed`，`Greptile` / `Gemini Code Assist` 当前无 open thread。 + - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `4fdb1e7398e4f114757b5c988698af203dce24c8`，`CodeRabbit` 当前有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment，测试汇总为 `2222 passed / 0 failed`，`Greptile` / `Gemini Code Assist` 当前无 open thread。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - 结果：通过；`Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。 - `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` @@ -78,6 +80,6 @@ ## 下一步 -1. 提交并推送本轮归档修正与 active `ai-plan` 事实校正，然后重新抓取 `$gframework-pr-review`，确认 remote open threads 是否只剩 stale / metadata 项。 -2. 若 review 线程清空或只剩 `Title check`，再按 `$gframework-batch-boot 50` 继续挑选新的 coverage 切片，避免在同一轮混入无关改稿。 -3. 若远端仍保留 schema 页线程，则基于推送后的 latest reviewed commit 再判断是否需要单独在 PR 上回复说明，而不是继续修改已覆盖的本地文档。 +1. 提交并推送本轮 source-generators 文档 follow-up，然后重新抓取 `$gframework-pr-review`。 +2. 若 remote open threads 只剩 stale 的“迁移与兼容性”线程或 `Title check` 这类 metadata 项，则停止本轮仓库内修复。 +3. 若 review 线程清空或只剩 metadata 项，再按 `$gframework-batch-boot 50` 继续挑选新的 coverage 切片，避免在同一轮混入无关改稿。 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 7b89c15c..0b0dbdd7 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,26 +2,30 @@ ## 2026-05-01 -### 当前恢复点：RP-054 +### 当前恢复点：RP-055 -- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，分别落在两份归档文档与 `Schema 配置生成器` 专题页。 -- 本地复核确认真正仍成立的是 `2` 条归档 Markdown 反引号问题；`schema-config-generator.md` 已包含独立的“迁移与兼容性”小节，因此该线程目前应视为 stale。 +- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest reviewed commit 已前进到 `4fdb1e7398e4f114757b5c988698af203dce24c8`，当前 `CodeRabbit` 仍有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment。 +- 本地复核确认真正仍成立的是 `2` 条 reader-facing 文档表述问题：`cqrs-handler-registry-generator.md` 与 `schema-config-generator.md` 都直接暴露了测试源码路径；`schema-config-generator.md` 的“迁移与兼容性”建议则已经本地满足，应视为 stale。 - GitHub Test Reporter 当前汇总为 `2222 passed / 0 failed`；`Title check` 仍然只是 PR 元数据问题，因此不纳入仓库文件修复范围。 -### 当前决策（RP-054） +### 当前决策（RP-055） -- 修复两份 `documentation-full-coverage-governance` 归档里的 Markdown 行内代码闭合错误，避免 reader-facing archive 文档继续触发 review。 -- active tracking 与 active trace 改写为与本地核验一致的事实，不再把已经落地的 schema 专题页补充误记为待办。 -- 本轮只做 latest-head review 精确收口，不扩展到新的 docs coverage 批次。 +- 把两处测试源码路径改成语义化 GitHub 链接标签，避免把原始文件路径暴露成 reader-facing 导航文本。 +- active tracking 与 active trace 改写为与本次 PR 抓取一致的事实，修正 latest reviewed commit、线程来源和本地结论。 +- 本轮只做 PR review 精确收口，不扩展到新的 docs coverage 批次。 -### 当前验证（RP-054） +### 当前验证（RP-055） - PR review 抓取： - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#308` 处于 `OPEN`，latest-head review 当前只剩 `3` 条 `CodeRabbit` open threads，测试汇总为 `2222 passed / 0 failed`。 + - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `4fdb1e7398e4f114757b5c988698af203dce24c8`，`CodeRabbit` 当前有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment，测试汇总为 `2222 passed / 0 failed`。 +- 页面校验： + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` + - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` + - 结果：通过；两篇 source-generators 页面在改成语义化 GitHub 链接后，frontmatter、链接与代码块校验均通过。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；本轮归档 Markdown 修正与 active `ai-plan` 更新后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；两篇 source-generators 页面链接改写与 active `ai-plan` 事实更新后站点仍可构建，仅保留既有大 chunk warning。 ### 归档指针 @@ -34,8 +38,8 @@ - `RP-049` 到 `RP-052` 的验证明细： `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` -### 下一步（RP-054） +### 下一步（RP-055） -1. 提交并推送本轮 follow-up 后重新抓取 `$gframework-pr-review`，确认 remote open threads 是否只剩 stale / metadata 项。 -2. 若只剩 `Title check`，则把后续动作限定为 GitHub PR 标题修正，不继续在仓库里做无关变更。 -3. 若远端仍保留 schema 页线程，则基于推送后的 latest reviewed commit 再判断是否需要在 PR 上补充回复说明。 +1. 提交并推送本轮 follow-up 后重新抓取 `$gframework-pr-review`，确认 remote open threads 是否只剩 stale 的 schema 线程或 `Title check`。 +2. 若只剩 metadata 项，则把后续动作限定为 GitHub PR 元数据修正，不继续在仓库里做无关变更。 +3. 若 review 线程清空，则回到 `documentation-full-coverage-governance` 的下一个 coverage 切片，而不是继续在同一轮修改无关页面。 diff --git a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md index 3b973d5b..e0cd2853 100644 --- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md +++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md @@ -91,8 +91,11 @@ RegisterCqrsHandlersFromAssemblies( 6. 若存在 `CqrsReflectionFallbackAttribute`，只补扫剩余 handler 7. 同一程序集按稳定键去重，避免重复注册 -这个行为由 `GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs` 和 -`GFramework.SourceGenerators.Tests/Cqrs/CqrsHandlerRegistryGeneratorTests.cs` 共同覆盖。 +这个行为由 +[运行时注册流程测试](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs) +和 +[生成器行为测试](https://github.com/GeWuYou/GFramework/blob/main/GFramework.SourceGenerators.Tests/Cqrs/CqrsHandlerRegistryGeneratorTests.cs) +共同覆盖。 ## 什么时候值得安装 diff --git a/docs/zh-CN/source-generators/schema-config-generator.md b/docs/zh-CN/source-generators/schema-config-generator.md index 767d2e69..c16cf066 100644 --- a/docs/zh-CN/source-generators/schema-config-generator.md +++ b/docs/zh-CN/source-generators/schema-config-generator.md @@ -199,7 +199,11 @@ var bootstrap = new GameConfigBootstrap( - 额外约束元数据不合法 - 例如 `GF_ConfigSchema_008` 到 `GF_ConfigSchema_014` -这些边界由 `GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorTests.cs` 和快照测试共同覆盖。遇到生成失败时，优先先看诊断 ID，再回头核对 schema 本身是否超出当前公开子集。 +这些边界由 +[Schema 生成器行为测试](https://github.com/GeWuYou/GFramework/blob/main/GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorTests.cs) +和 +[生成结果快照测试](https://github.com/GeWuYou/GFramework/blob/main/GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorSnapshotTests.cs) +共同覆盖。遇到生成失败时，优先先看诊断 ID，再回头核对 schema 本身是否超出当前公开子集。 ## 什么时候优先看这页 From 00ecf6fb1083e9039c9dc544a3265c38e1ba9117 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 1 May 2026 17:02:25 +0800 Subject: [PATCH 6/7] =?UTF-8?q?docs(source-generators):=20=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=20PR=20=E5=AE=A1=E6=9F=A5=E6=96=87=E6=A1=A3=E8=B7=9F?= =?UTF-8?q?=E8=BF=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 source-generators 文档中的 fallback 条件说明与自包含运行时示例 - 压缩 documentation-full-coverage-governance active tracking 的验证摘要并同步最新 PR 审查事实 - 补充 active trace 的显式风险记录与本轮验证结论 --- ...ation-full-coverage-governance-tracking.md | 37 ++++++------------- ...entation-full-coverage-governance-trace.md | 22 +++++++---- .../cqrs-handler-registry-generator.md | 2 +- .../schema-config-generator.md | 2 + 4 files changed, 28 insertions(+), 35 deletions(-) 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 220eba28..88bcfa09 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 @@ -13,14 +13,15 @@ - 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-055` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - - 处理 PR `#308` 当前 latest-head review 与 outside-diff review 中经本地复核仍成立的 reader-facing 文档表述问题，并清理 active `ai-plan` 对旧结论的漂移 + - 处理 PR `#308` 当前 latest-head review 与 outside-diff review 中经本地复核仍成立的 reader-facing 文档与 active `ai-plan` 漂移问题 - 当前事实： - - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 已前进到 `4fdb1e7398e4f114757b5c988698af203dce24c8` - - 当前 `CodeRabbit` 仍有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment；本地复核后真正成立的是 `2` 条 reader-facing 文档问题，分别位于 `schema-config-generator.md` 与 `cqrs-handler-registry-generator.md` 的测试入口表述 + - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 已前进到 `896e3efaa9c7496043fdaeee4dceff3d0e46b318` + - 当前 `CodeRabbit` 仍有 `3` 条 latest-head open threads 和 `1` 条 outside-diff comment；`Greptile` / `Gemini Code Assist` 当前无 open thread + - 本地复核后真正仍成立的 `4` 条问题已经全部在当前工作树完成修复：`cqrs-handler-registry-generator.md` 的 fallback 条件说明、`schema-config-generator.md` 的 `configRootPath` 示例、active trace 的显式风险段，以及 active tracking 的验证摘要压缩 - `docs/zh-CN/source-generators/schema-config-generator.md` 已包含独立的“迁移与兼容性”章节，因此对应 major open thread 现阶段应视为 stale，等待提交推送后再由远端重新计算 - - GitHub Test Reporter 汇总为 `2222 passed / 0 failed` + - GitHub Test Reporter 汇总为 `2247 passed / 0 failed` - `Title check` 仍为 `Inconclusive`，属于 PR 元数据问题，不是仓库文件内可直接修复的阻塞项 - - 本地对 review 指向文件的修复在提交推送前，不会改变远端 latest reviewed commit 与 open-thread 统计 + - 本地修复尚未推送前，不会改变远端 latest reviewed commit 与 open-thread 统计 - 当前风险： - 如果 active tracking / trace 继续保留旧的 commit SHA 和 review 归因，会让后续恢复点重复处理已经本地闭环的问题 - 在变更推送前，PR 页面仍会继续展示旧的 open-thread / outside-diff 数量，容易把 stale 线程误判为新的本地缺陷 @@ -57,29 +58,13 @@ ## 最新验证 -- `2026-05-01` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - - 结果：通过；在把测试入口改成语义化链接后，页面的 frontmatter、链接与代码块校验仍然通过。 -- `2026-05-01` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` - - 结果：通过；测试源码路径改成语义化链接标签后，页面的 frontmatter、链接与代码块校验通过。 -- `2026-05-01` `bun run build`（工作目录：`docs/`） - - 结果：通过；两篇 source-generators 页面链接改写与 active `ai-plan` 事实更新后站点仍可构建，仅保留既有大 chunk warning。 -- `2026-05-01` `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `4fdb1e7398e4f114757b5c988698af203dce24c8`，`CodeRabbit` 当前有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment，测试汇总为 `2222 passed / 0 failed`，`Greptile` / `Gemini Code Assist` 当前无 open thread。 -- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - - 结果：通过；`Schema 配置生成器` 专题页的 frontmatter、链接与代码块校验通过。 -- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/index.md` - - 结果：通过；source-generators landing 的链接与结构校验通过。 -- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` - - 结果：通过；`Cqrs` generator 专题页在补足 fallback 精度说明后校验通过。 -- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/cqrs.md` - - 结果：通过；`CQRS` 运行时页在补足 generated registry 协作说明后校验通过。 -- `2026-04-30` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/api-reference/index.md` - - 结果：通过；API 入口页在补充 source-generator 阅读路线后校验通过。 -- `2026-04-30` `bun run build`（工作目录：`docs/`） - - 结果：通过；新增 source-generators 专题页与侧栏入口后站点仍可构建，仅保留既有大 chunk warning。 +- `2026-05-01` 本轮关键验证结论：`$gframework-pr-review` 重新抓取通过，确认 PR `#308` 的 latest reviewed commit 为 `896e3efaa9c7496043fdaeee4dceff3d0e46b318`，`CodeRabbit` 当前仍有 `3` 条 latest-head open threads 与 `1` 条 outside-diff comment；两篇 source-generators 页面校验通过，`docs/` 站点构建通过并仅保留既有大 chunk warning。 +- 逐条命令与详细结果见： + - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` + - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md` ## 下一步 -1. 提交并推送本轮 source-generators 文档 follow-up，然后重新抓取 `$gframework-pr-review`。 +1. 提交并推送本轮 source-generators 文档与 active `ai-plan` follow-up，然后重新抓取 `$gframework-pr-review`。 2. 若 remote open threads 只剩 stale 的“迁移与兼容性”线程或 `Title check` 这类 metadata 项，则停止本轮仓库内修复。 3. 若 review 线程清空或只剩 metadata 项，再按 `$gframework-batch-boot 50` 继续挑选新的 coverage 切片，避免在同一轮混入无关改稿。 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 0b0dbdd7..240f6767 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 @@ -4,28 +4,34 @@ ### 当前恢复点：RP-055 -- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest reviewed commit 已前进到 `4fdb1e7398e4f114757b5c988698af203dce24c8`，当前 `CodeRabbit` 仍有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment。 -- 本地复核确认真正仍成立的是 `2` 条 reader-facing 文档表述问题：`cqrs-handler-registry-generator.md` 与 `schema-config-generator.md` 都直接暴露了测试源码路径；`schema-config-generator.md` 的“迁移与兼容性”建议则已经本地满足，应视为 stale。 -- GitHub Test Reporter 当前汇总为 `2222 passed / 0 failed`；`Title check` 仍然只是 PR 元数据问题，因此不纳入仓库文件修复范围。 +- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest reviewed commit 已前进到 `896e3efaa9c7496043fdaeee4dceff3d0e46b318`，当前 `CodeRabbit` 仍有 `3` 条 latest-head open threads 和 `1` 条 outside-diff comment。 +- 本地复核确认真正仍成立的 `4` 条问题已经全部在当前工作树完成修复：`cqrs-handler-registry-generator.md` 的 fallback 条件说明、`schema-config-generator.md` 的 `configRootPath` 示例、active trace 的显式风险段，以及 active tracking 的“最新验证”压缩；`schema-config-generator.md` 的“迁移与兼容性”建议则已经本地满足，应视为 stale。 +- GitHub Test Reporter 当前汇总为 `2247 passed / 0 failed`；`Title check` 仍然只是 PR 元数据问题，因此不纳入仓库文件修复范围。 ### 当前决策（RP-055） -- 把两处测试源码路径改成语义化 GitHub 链接标签，避免把原始文件路径暴露成 reader-facing 导航文本。 -- active tracking 与 active trace 改写为与本次 PR 抓取一致的事实，修正 latest reviewed commit、线程来源和本地结论。 +- 补齐 `cqrs-handler-registry-generator.md` 的 fallback 条件说明，以及 `schema-config-generator.md` 的自包含运行时示例。 +- active tracking 与 active trace 改写为与本次 PR 抓取一致的事实，修正 latest reviewed commit、线程数量、本地结论与验证摘要。 - 本轮只做 PR review 精确收口，不扩展到新的 docs coverage 批次。 +### 当前风险（RP-055） + +- 在本轮提交推送前，PR 页面仍会继续展示基于旧 diff 的 open threads，因此远端线程数量短时间内不会反映本地已修复状态。 +- `schema-config-generator.md` 的“迁移与兼容性”线程已经由当前文件内容满足，但仍需依赖远端下一次 review 重新计算后才能从 open thread 列表中消失。 +- `Title check` 仍是 PR 元数据层面的 `Inconclusive` 项；即使仓库文件全部修完，也不能仅凭本地改动让该检查转绿。 + ### 当前验证（RP-055） - PR review 抓取： - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `4fdb1e7398e4f114757b5c988698af203dce24c8`，`CodeRabbit` 当前有 `2` 条 latest-head open threads 和 `1` 条 outside-diff comment，测试汇总为 `2222 passed / 0 failed`。 + - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `896e3efaa9c7496043fdaeee4dceff3d0e46b318`，`CodeRabbit` 当前有 `3` 条 latest-head open threads 和 `1` 条 outside-diff comment，测试汇总为 `2247 passed / 0 failed`。 - 页面校验： - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` - - 结果：通过；两篇 source-generators 页面在改成语义化 GitHub 链接后，frontmatter、链接与代码块校验均通过。 + - 结果：通过；fallback 条件说明与自包含示例改动后，两篇页面的 frontmatter、链接与代码块校验仍然通过。 - 站点构建： - `bun run build`（工作目录：`docs/`） - - 结果：通过；两篇 source-generators 页面链接改写与 active `ai-plan` 事实更新后站点仍可构建，仅保留既有大 chunk warning。 + - 结果：通过；source-generators 页面与 active `ai-plan` 更新后站点仍可构建，仅保留既有大 chunk warning。 ### 归档指针 diff --git a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md index e0cd2853..e96815f2 100644 --- a/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md +++ b/docs/zh-CN/source-generators/cqrs-handler-registry-generator.md @@ -88,7 +88,7 @@ RegisterCqrsHandlersFromAssemblies( 3. 若生成注册器同时提供 request invoker provider / descriptor，registrar 会把这些 request invoker 元数据预先登记到 dispatcher 缓存 4. 若生成注册器同时提供 stream invoker provider / descriptor，runtime 也会优先消费对应的 generated stream invoker 元数据；未命中时仍回退到既有反射 stream binding 5. 若生成元数据损坏、registry 不可激活，记录告警并回退到反射路径 -6. 若存在 `CqrsReflectionFallbackAttribute`，只补扫剩余 handler +6. 若存在 `CqrsReflectionFallbackAttribute`，优先按其中携带的 `Type` 或类型名补扫剩余 handler；若元数据为空或只保留 marker 语义，则退回整程序集补扫 7. 同一程序集按稳定键去重，避免重复注册 这个行为由 diff --git a/docs/zh-CN/source-generators/schema-config-generator.md b/docs/zh-CN/source-generators/schema-config-generator.md index c16cf066..9f5936fc 100644 --- a/docs/zh-CN/source-generators/schema-config-generator.md +++ b/docs/zh-CN/source-generators/schema-config-generator.md @@ -154,6 +154,8 @@ loader.RegisterAllGeneratedConfigTables(); using GFramework.Game.Config; using GFramework.Game.Config.Generated; +var configRootPath = Path.Combine(AppContext.BaseDirectory, "schemas"); + var bootstrap = new GameConfigBootstrap( new GameConfigBootstrapOptions { From 6983b7ee84d61511a4eca1d5bf7f771469cffdfb Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Fri, 1 May 2026 19:08:39 +0800 Subject: [PATCH 7/7] =?UTF-8?q?docs(source-generators):=20=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=E6=9C=80=E6=96=B0=20PR=20=E5=AE=A1=E6=9F=A5=E8=B7=9F?= =?UTF-8?q?=E8=BF=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 schema-config-generator 文案并同步 PR review 最新建议 - 修复 documentation-full-coverage-governance active tracking 的 RP-055 验证引用与审查事实 - 更新 active trace 的 latest reviewed commit、线程结论与验证摘要 --- ...tation-full-coverage-governance-tracking.md | 18 +++++++++--------- ...mentation-full-coverage-governance-trace.md | 12 +++++++----- .../schema-config-generator.md | 2 +- 3 files changed, 17 insertions(+), 15 deletions(-) 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 88bcfa09..b2789568 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 @@ -15,16 +15,17 @@ - 当前焦点： - 处理 PR `#308` 当前 latest-head review 与 outside-diff review 中经本地复核仍成立的 reader-facing 文档与 active `ai-plan` 漂移问题 - 当前事实： - - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 已前进到 `896e3efaa9c7496043fdaeee4dceff3d0e46b318` - - 当前 `CodeRabbit` 仍有 `3` 条 latest-head open threads 和 `1` 条 outside-diff comment；`Greptile` / `Gemini Code Assist` 当前无 open thread - - 本地复核后真正仍成立的 `4` 条问题已经全部在当前工作树完成修复：`cqrs-handler-registry-generator.md` 的 fallback 条件说明、`schema-config-generator.md` 的 `configRootPath` 示例、active trace 的显式风险段，以及 active tracking 的验证摘要压缩 - - `docs/zh-CN/source-generators/schema-config-generator.md` 已包含独立的“迁移与兼容性”章节，因此对应 major open thread 现阶段应视为 stale，等待提交推送后再由远端重新计算 + - `2026-05-01` 重新抓取 `$gframework-pr-review` 后确认：PR `#308` 处于 `OPEN`，latest reviewed commit 已前进到 `00ecf6fb1083e9039c9dc544a3265c38e1ba9117` + - 当前 `CodeRabbit` 仍有 `5` 条 latest-head open threads；其中 `2` 条是本轮 latest review 针对 active tracking 与 `schema-config-generator.md` 措辞提出的新 actionable comments，另有 `3` 条为已被当前文件内容满足但尚未由远端重新计算关闭的 stale 线程 + - `Greptile` / `Gemini Code Assist` 当前无 open thread，CodeRabbit latest review 状态为 `CHANGES_REQUESTED` + - 本地复核后，最新 review 中真正仍成立的 `2` 条问题分别是：active tracking 的 RP-055 验证引用仍指向 `RP-049` 到 `RP-052` 归档，以及 `schema-config-generator.md` 的“更稳妥地回退”措辞未同步 + - `docs/zh-CN/source-generators/schema-config-generator.md` 已包含独立的“迁移与兼容性”章节，且运行时示例已补齐 `configRootPath` 定义，因此对应的 major / minor open threads 现阶段应视为 stale，等待提交推送后再由远端重新计算 - GitHub Test Reporter 汇总为 `2247 passed / 0 failed` - `Title check` 仍为 `Inconclusive`，属于 PR 元数据问题，不是仓库文件内可直接修复的阻塞项 - 本地修复尚未推送前，不会改变远端 latest reviewed commit 与 open-thread 统计 - 当前风险： - 如果 active tracking / trace 继续保留旧的 commit SHA 和 review 归因，会让后续恢复点重复处理已经本地闭环的问题 - - 在变更推送前，PR 页面仍会继续展示旧的 open-thread / outside-diff 数量，容易把 stale 线程误判为新的本地缺陷 + - 在变更推送前，PR 页面仍会继续展示 latest reviewed commit `00ecf6fb...` 下的 open-thread 数量，容易把 stale 线程误判为新的本地缺陷 ## 当前状态摘要 @@ -58,10 +59,9 @@ ## 最新验证 -- `2026-05-01` 本轮关键验证结论：`$gframework-pr-review` 重新抓取通过，确认 PR `#308` 的 latest reviewed commit 为 `896e3efaa9c7496043fdaeee4dceff3d0e46b318`，`CodeRabbit` 当前仍有 `3` 条 latest-head open threads 与 `1` 条 outside-diff comment；两篇 source-generators 页面校验通过，`docs/` 站点构建通过并仅保留既有大 chunk warning。 -- 逐条命令与详细结果见： - - `ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-rp-049-to-rp-052-2026-05-01.md` - - `ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-049-to-rp-052-2026-05-01.md` +- `2026-05-01` 本轮关键验证结论：`$gframework-pr-review` 重新抓取通过，确认 PR `#308` 的 latest reviewed commit 为 `00ecf6fb1083e9039c9dc544a3265c38e1ba9117`，`CodeRabbit` 当前仍有 `5` 条 latest-head open threads；其中最新 review 的 `2` 条 actionable comments 已在当前工作树完成修复，其余 `3` 条因当前文件内容已满足而应视为 stale。两篇 source-generators 页面校验通过，`docs/` 站点构建通过并仅保留既有大 chunk warning。 +- 本轮逐条命令与详细结果见 active trace 的 `RP-055` 验证段： + - `ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.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 240f6767..4f4e9daa 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 @@ -4,27 +4,29 @@ ### 当前恢复点：RP-055 -- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest reviewed commit 已前进到 `896e3efaa9c7496043fdaeee4dceff3d0e46b318`，当前 `CodeRabbit` 仍有 `3` 条 latest-head open threads 和 `1` 条 outside-diff comment。 -- 本地复核确认真正仍成立的 `4` 条问题已经全部在当前工作树完成修复：`cqrs-handler-registry-generator.md` 的 fallback 条件说明、`schema-config-generator.md` 的 `configRootPath` 示例、active trace 的显式风险段，以及 active tracking 的“最新验证”压缩；`schema-config-generator.md` 的“迁移与兼容性”建议则已经本地满足，应视为 stale。 +- 通过 `$gframework-pr-review` 重新抓取当前分支 PR `#308`，确认 latest reviewed commit 已前进到 `00ecf6fb1083e9039c9dc544a3265c38e1ba9117`，当前 `CodeRabbit` 仍有 `5` 条 latest-head open threads。 +- 本地复核确认最新 review 中真正仍成立的 `2` 条问题已经在当前工作树完成修复：active tracking 的 RP-055 验证引用改为指向 active trace，以及 `schema-config-generator.md` 的“更稳妥地回退”措辞同步。 +- `schema-config-generator.md` 的“迁移与兼容性”章节与自包含运行时示例已在当前文件内容中满足 earlier open threads，对应 `3` 条历史线程现阶段应视为 stale，等待提交推送后由远端重新计算。 - GitHub Test Reporter 当前汇总为 `2247 passed / 0 failed`；`Title check` 仍然只是 PR 元数据问题，因此不纳入仓库文件修复范围。 ### 当前决策（RP-055） - 补齐 `cqrs-handler-registry-generator.md` 的 fallback 条件说明，以及 `schema-config-generator.md` 的自包含运行时示例。 - active tracking 与 active trace 改写为与本次 PR 抓取一致的事实，修正 latest reviewed commit、线程数量、本地结论与验证摘要。 +- 只修仍然成立的 latest review 问题，不重复处理已被当前内容满足但尚未关闭的 stale 线程。 - 本轮只做 PR review 精确收口，不扩展到新的 docs coverage 批次。 ### 当前风险（RP-055） -- 在本轮提交推送前，PR 页面仍会继续展示基于旧 diff 的 open threads，因此远端线程数量短时间内不会反映本地已修复状态。 -- `schema-config-generator.md` 的“迁移与兼容性”线程已经由当前文件内容满足，但仍需依赖远端下一次 review 重新计算后才能从 open thread 列表中消失。 +- 在本轮提交推送前，PR 页面仍会继续展示 latest reviewed commit `00ecf6fb...` 下的 open threads，因此远端线程数量短时间内不会反映本地已修复状态。 +- `schema-config-generator.md` 的“迁移与兼容性”线程和 `configRootPath` 线程已经由当前文件内容满足，但仍需依赖远端下一次 review 重新计算后才能从 open thread 列表中消失。 - `Title check` 仍是 PR 元数据层面的 `Inconclusive` 项；即使仓库文件全部修完，也不能仅凭本地改动让该检查转绿。 ### 当前验证（RP-055） - PR review 抓取： - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json` - - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `896e3efaa9c7496043fdaeee4dceff3d0e46b318`，`CodeRabbit` 当前有 `3` 条 latest-head open threads 和 `1` 条 outside-diff comment，测试汇总为 `2247 passed / 0 failed`。 + - 结果：通过；PR `#308` 处于 `OPEN`，latest reviewed commit 为 `00ecf6fb1083e9039c9dc544a3265c38e1ba9117`，`CodeRabbit` 当前有 `5` 条 latest-head open threads，其中最新 review 的 `2` 条 actionable comments 已本地修复，其余 `3` 条应视为 stale；测试汇总为 `2247 passed / 0 failed`。 - 页面校验： - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/schema-config-generator.md` - `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md` diff --git a/docs/zh-CN/source-generators/schema-config-generator.md b/docs/zh-CN/source-generators/schema-config-generator.md index 9f5936fc..2a4e6762 100644 --- a/docs/zh-CN/source-generators/schema-config-generator.md +++ b/docs/zh-CN/source-generators/schema-config-generator.md @@ -182,7 +182,7 @@ var bootstrap = new GameConfigBootstrap( - `x-gframework-index`、路径元数据和标识符映射都要求满足安全约束；旧项目里依赖宽松命名或不安全路径的配置，需要先整理 schema，再切换到聚合注册入口。 - 迁移到生成链路后，运行时读取模型保持不变，但“表类型定义”和“注册目录”会改为编译期输出，因此自定义扩展更适合挂在单表绑定或 `ConfigureLoader` 阶段，而不是继续复制生成器会维护的样板代码。 -如果你需要分批迁移，当前更稳妥的回退方式是只回退注册入口，而不是同时回退 schema 结构： +如果你需要分批迁移，当前更稳妥地回退是只回退注册入口，而不是同时回退 schema 结构： - 可以先让一部分表继续沿手写注册保留，另一部分切到生成的单表绑定或聚合注册。 - 如果某张表在迁移后触发诊断，优先根据诊断 ID 收敛 schema，再决定是否临时回到手写注册。