From 092946e91abdfe94b301836cc3be446dd85e0fc4 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Tue, 12 May 2026 14:18:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(cqrs-benchmarks):=20=E5=90=8C=E6=AD=A5star?= =?UTF-8?q?tup=E5=9F=BA=E5=87=86=E6=96=87=E6=A1=A3=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 README 中 stream/request/notification startup benchmark 的覆盖矩阵与适用边界 - 补充 cqrs-rewrite public tracking 与 trace，记录本轮误报剔除、docs-only 收尾与停止判断 --- GFramework.Cqrs.Benchmarks/README.md | 5 +- .../todos/cqrs-rewrite-migration-tracking.md | 67 +++++++++---------- .../traces/cqrs-rewrite-migration-trace.md | 29 ++++++++ 3 files changed, 63 insertions(+), 38 deletions(-) diff --git a/GFramework.Cqrs.Benchmarks/README.md b/GFramework.Cqrs.Benchmarks/README.md index 4356bde6..dd943daa 100644 --- a/GFramework.Cqrs.Benchmarks/README.md +++ b/GFramework.Cqrs.Benchmarks/README.md @@ -24,6 +24,7 @@ - request startup - `Messaging/RequestStartupBenchmarks.cs` - `Initialization` 与 `ColdStart` 两组下，`GFramework.Cqrs`、NuGet `Mediator`、`MediatR` + - 其中 `GFramework.Cqrs` 路径是“单 handler 最小宿主 + 手工注册”的 startup/cold-start 模型，不包含更大范围的程序集扫描或完整注册协调器接线 - stream steady-state - `Messaging/StreamingBenchmarks.cs` - baseline、默认 generated-provider 宿主接线的 `GFramework.Cqrs` runtime、NuGet `Mediator` source-generated concrete path 与 `MediatR` @@ -39,7 +40,7 @@ - 同时提供 `FirstItem` 与 `DrainAll` 两种观测口径 - stream startup - `Messaging/StreamStartupBenchmarks.cs` - - `Initialization` 与 `ColdStart` 两组下，覆盖 `GFramework.Cqrs` reflection、`GFramework.Cqrs` generated，以及当前 benchmark 项目已接入的 stream startup 外部 mediator 对照组 + - `Initialization` 与 `ColdStart` 两组下，覆盖 `MediatR`、`GFramework.Cqrs` reflection、`GFramework.Cqrs` generated、NuGet `Mediator` 四组 initialization/cold-start 对照 - 其中 `ColdStart` 的边界是“新宿主 + 首个元素命中”，不是完整枚举整个 stream - notification steady-state - `Messaging/NotificationBenchmarks.cs` @@ -51,6 +52,7 @@ - notification startup - `Messaging/NotificationStartupBenchmarks.cs` - `Initialization` 与 `ColdStart` 两组下，`GFramework.Cqrs`、NuGet `Mediator`、`MediatR` + - 其中 `GFramework.Cqrs` 路径是“单 handler 最小宿主 + 手工注册”的 startup/cold-start 模型，不包含 fan-out、发布策略变体或更大范围的注册协调逻辑 ## 最小使用方式 @@ -95,6 +97,7 @@ dotnet run --project GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.cspro - `FirstItem` 适合观察“建流到首个元素”的固定成本 - `DrainAll` 适合观察完整枚举整个 stream 的总成本 - `StreamStartupBenchmarks` 的 `ColdStart` 只推进到首个元素，因此它回答的是“新宿主下首次建流命中”的边界，不回答完整枚举总成本 +- `RequestStartupBenchmarks` 与 `NotificationStartupBenchmarks` 的 `GFramework.Cqrs` startup 路径都固定在单 handler、最小宿主、手工注册模型；它们回答的是首次 request / publish 命中的额外成本，不代表程序集扫描或完整注册协调器场景 - 当前 HEAD 没有单独固化的 short-job benchmark 类或 checked-in short-job 结果；如果手动使用 short job / short run 只做 smoke 复核，应把它理解为“确认矩阵与路径能跑通” - 特别是 `StreamInvokerBenchmarks` 的 `DrainAll` 在 short-job smoke 下不应直接写成 reflection、generated 或 `MediatR` 之间的稳定排序结论；若要比较名次或小幅差值，应复跑默认作业或更完整的批次 diff --git a/ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md b/ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md index eb3cd91f..10260065 100644 --- a/ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md +++ b/ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md @@ -12,32 +12,27 @@ CQRS 迁移与收敛。 ## 当前恢复点 -- 恢复点编号：`CQRS-REWRITE-RP-138` +- 恢复点编号：`CQRS-REWRITE-RP-139` - 当前阶段：`Phase 8` - 当前 PR 锚点：`PR #349（已于 2026-05-12 合并到 origin/main）` - 当前结论： - - 本轮恢复时先按 `$gframework-pr-review` 复核 `PR #349` latest-head review，确认该 PR 已关闭且合并到 - `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)`，旧 tracking 中基于 `ef4d3d5d` 的 branch-diff 度量已失效。 - - latest-head 残余 open thread 中，实际仍成立的项只剩： - - `StreamingBenchmarks.Stream_MediatR()` 缺少 `` XML 契约 - - 其余线程经本地核对已判定为 stale： - - `StreamPipelineBenchmarks.Stream_Baseline` 的 `` 已存在 - - `CqrsNotificationPublisherTests` 的 fallback publisher 缓存回归已改成“再次解析立即失败” - - active tracking / trace 已同步到 `PR #349` - - 本轮继续按 `$gframework-batch-boot 50` 协调 subagent，围绕 benchmark 文档与 startup parity 做两波窄切片： - - 已提交 `f346110a`：`StreamStartupBenchmarks` 补 `Mediator` startup parity - - 待收尾提交：`StreamingBenchmarks` 的 XML 文档补齐与 `GFramework.Cqrs.Benchmarks/README.md` 的 stream startup / gap 同步 - - 在当前恢复点继续推进第 2 波 benchmark XML 契约收口，范围严格限定为公开 benchmark 方法缺失的 `` 文档： - - 主线程：`StreamingBenchmarks.cs`、`NotificationBenchmarks.cs` 与 `ai-plan/public/cqrs-rewrite/**` - - worker：`StreamLifetimeBenchmarks.cs`、`StreamInvokerBenchmarks.cs`、`NotificationFanOutBenchmarks.cs` - - 启动第 2 波前，当前分支相对 `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)` 的已提交 branch diff 为 `5 files / 177 lines`，远低于 `$gframework-batch-boot 50` 的文件阈值；本轮是否继续主要由 context-budget / reviewability 决定，而不是 branch-size 预算。 - - 第 3 波继续沿同一模式扩到 request 系 benchmark XML 契约收口，并已由 worker 分别提交： - - `555c7c07`：`RequestBenchmarks.cs`、`RequestPipelineBenchmarks.cs` - - `ab422b05`：`RequestInvokerBenchmarks.cs`、`RequestLifetimeBenchmarks.cs` - - 另有 `RequestStartupBenchmarks.cs` 已完成 `` 收口，待与主线程未提交切片一并收尾 - - 当前已决定在第 3 波后停在自然边界，而不是继续开启第 4 波： - - branch-size 仍远低于 `50 files` - - 但剩余候选已不比当前波次更低风险，继续机械扩批会降低 reviewability，并推高当前上下文负担 + - 本轮按 `$gframework-batch-boot 50` 恢复后，先重新确认基线仍为 + `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)`，当前已提交 branch diff 为 `14 files`，仍远低于 `50 files` + 阈值；是否继续的主停止信号仍是 context-budget / reviewability，而不是 branch-size 预算。 + - 主线程结合本地抽样核对与两个 explorer 子代理的只读盘点后，确认当前不应再继续按“benchmark XML `` 批量缺口”扩批： + - README 一致性盘点成立，`GFramework.Cqrs.Benchmarks/README.md` 的 startup coverage / 解释边界仍可收紧 + - benchmark XML 缺口盘点存在明显误报；代表文件中的 class / benchmark 方法 `` 与 `` 已实际存在 + - 因此本轮不接受新的大范围 XML 收口波次，避免把上下文预算消耗在错误候选上 + - 本轮 accepted delegated scope 收敛为单文件 docs-only worker： + - `GFramework.Cqrs.Benchmarks/README.md` + - 明确 `StreamStartupBenchmarks` 现已覆盖 `MediatR`、`GFramework.Cqrs` reflection、 + `GFramework.Cqrs` generated、NuGet `Mediator` 四组 initialization / cold-start 对照 + - 补充 `RequestStartupBenchmarks` 与 `NotificationStartupBenchmarks` 的 + `GFramework.Cqrs` 路径是“单 handler 最小宿主 + 手工注册”的 startup / cold-start 模型，不外推到程序集扫描、 + 完整注册协调器、fan-out 或发布策略变体 + - 当前决定在该 docs-only 收口后停在自然边界： + - branch-size 仍低于 `50 files` + - 但下一批低风险候选已不再清晰；继续开波次的收益低于评审与上下文成本 - tests 侧此前已补齐并提交： - `CqrsRegistrationServiceTests`：补空输入、空项过滤、稳定键排序与跨调用跳过边界 - `CqrsHandlerRegistrarTests` 与 `CqrsHandlerRegistrarFallbackFailureTests`： @@ -55,31 +50,26 @@ CQRS 迁移与收敛。 - 当前分支：`feat/cqrs-optimization` - 当前 PR：`PR #349（已合并；当前分支暂无新的公开 PR）` - 当前写面： - - `GFramework.Cqrs.Benchmarks/Messaging/NotificationBenchmarks.cs` - - `GFramework.Cqrs.Benchmarks/Messaging/NotificationFanOutBenchmarks.cs` - - `GFramework.Cqrs.Benchmarks/Messaging/RequestStartupBenchmarks.cs` - - `GFramework.Cqrs.Benchmarks/Messaging/StreamInvokerBenchmarks.cs` - - `GFramework.Cqrs.Benchmarks/Messaging/StreamLifetimeBenchmarks.cs` - - `GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs` - - `GFramework.Cqrs.Benchmarks/Messaging/StreamStartupBenchmarks.cs` - `GFramework.Cqrs.Benchmarks/README.md` - `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md` - `ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` - 当前基线： - `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)` - - 当前已提交 branch diff：`9 files / 143 lines` - - 当前分支比 `origin/main` 多 `4` 个提交：`f346110a`、`a016e3d4`、`ab422b05`、`555c7c07` - - 当前未提交面由 notification / stream / request-startup 的 XML 契约补齐与 `ai-plan` 恢复点更新构成 + - 当前已提交 branch diff：`14 files` + - 当前分支比 `origin/main` 多 `5` 个提交：`f346110a`、`a016e3d4`、`ab422b05`、`555c7c07`、`c32a1ec4` + - 当前未提交面由 benchmark README 的 startup 边界同步与 `ai-plan` 恢复点更新构成 - 本轮提交： - `f346110a` `feat(cqrs-benchmarks): 补齐 stream startup 的 Mediator 对照路径` - `ab422b05` `docs(cqrs-benchmarks): 补齐 request benchmark 返回值注释` - `555c7c07` `docs(cqrs-benchmarks): 补齐 request benchmark 返回值文档` + - `c32a1ec4` `docs(cqrs-benchmarks): 补齐stream与notification基准返回值文档` ## 当前风险 - `StreamStartupBenchmarks` 的 `Mediator` parity 目前只做了编译验证，尚未单独执行 benchmark 作业确认 startup 矩阵运行结果。 - `StreamLifetimeBenchmarks` 仍缺 `Mediator` parity；该项涉及 `BenchmarkHostFactory` 与 compile-time lifetime 形状，不再是本轮低风险切片。 -- 本轮已在 request 系 benchmark XML 契约收口后主动停批次；若后续恢复，优先先提交当前未提交面，再决定是否开启 docs/README 或 smoke-run 下一阶段，而不是继续机械扩张 XML 批次。 +- benchmark XML 盘点若再次依赖粗糙脚本或只读 inventory，仍有把已存在文档误记为缺口的风险；后续若再开 XML 波次，必须先用主线程抽样核对代表文件。 +- 本轮已在 README 精度同步后主动停批次；若后续恢复，优先先做 `StreamStartupBenchmarks` smoke run 或更明确的 parity / docs 候选，而不是继续机械扩张 XML 批次。 ## 最近权威验证 @@ -89,13 +79,16 @@ CQRS 迁移与收敛。 - 结果：通过 - `$gframework-pr-review` - 结果：`PR #349` 已关闭；latest-head review open thread 经本地核对仅剩 `StreamingBenchmarks.Stream_MediatR()` 的 XML 文档缺口仍成立 +- `git --git-dir=/mnt/f/gewuyou/System/Documents/WorkSpace/GameDev/GFramework/.git/worktrees/GFramework-cqrs --work-tree=/mnt/f/gewuyou/System/Documents/WorkSpace/GameDev/GFramework-WorkTree/GFramework-cqrs diff -- GFramework.Cqrs.Benchmarks/README.md` + - 结果：通过 + - 备注：确认本轮 worker 仅修改 README 的 startup coverage / 边界文案 ## 下一推荐步骤 -1. 串行运行 `dotnet build GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release`、`python3 scripts/license-header.py --check --paths ...` 与 `git diff --check`，作为当前自然停点的权威收尾验证。 -2. 提交当前未提交的 notification / stream / request-startup XML 契约与 `ai-plan` 更新，回到干净工作树。 +1. 串行运行 `dotnet build GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release`、`python3 scripts/license-header.py --check --paths ...` 与 `git diff --check`，作为本轮 docs-only 收尾的权威验证。 +2. 提交当前 README 与 `ai-plan` 更新，回到干净工作树。 3. 若后续继续 benchmark 波次，优先单独执行 `StreamStartupBenchmarks` 的最小 smoke run，验证新加 `Mediator` startup 路径可运行。 -4. 若后续还要扩 stream parity，把 `StreamLifetimeBenchmarks` 视为跨文件设计任务，而不是继续按“单文件低风险切片”处理。 +4. 若后续再开文档批次，先用主线程核对代表文件，再决定是否存在真实 XML 缺口；不要直接沿用误报 inventory 扩批。 ## 活跃文档 diff --git a/ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md b/ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md index 88f20d7e..30c89650 100644 --- a/ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md +++ b/ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md @@ -7,6 +7,35 @@ SPDX-License-Identifier: Apache-2.0 ## 2026-05-12 +### 阶段：README startup coverage 精度同步并停在自然边界（CQRS-REWRITE-RP-139） + +- 继续按 `$gframework-batch-boot 50` 推进，基线保持为 `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)`。 +- 本轮启动时重新测得当前已提交 branch diff 为 `14 files`，仍远低于 `50 files` 阈值；继续与否的主停止信号仍是 + context-budget / reviewability。 +- 本轮主线程先做只读盘点与抽样核对： + - README 一致性 explorer 结论成立：`GFramework.Cqrs.Benchmarks/README.md` 对 startup coverage / 边界的表述仍可更精确 + - benchmark XML 缺口 explorer 结论未直接接受；主线程抽样检查 `NotificationBenchmarks.cs`、 + `RequestBenchmarks.cs`、`StreamingBenchmarks.cs`、`NotificationStartupBenchmarks.cs` 后确认， + 其 class / benchmark 方法的 `` 与 `` 实际已存在，不能继续按“14 个门面文件普遍缺 XML” + 的假设扩批 +- 因此本轮 accepted delegated scope 缩成单文件 docs-only worker： + - `GFramework.Cqrs.Benchmarks/README.md` + - 把 `StreamStartupBenchmarks` 明确写成 `MediatR`、`GFramework.Cqrs` reflection、 + `GFramework.Cqrs` generated、NuGet `Mediator` 四组 initialization / cold-start 对照 + - 补充 `RequestStartupBenchmarks` 与 `NotificationStartupBenchmarks` 的 `GFramework.Cqrs` startup 路径是 + “单 handler 最小宿主 + 手工注册”模型，不外推到程序集扫描、完整注册协调器、fan-out 或发布策略变体 +- worker 回传验收结论： + - 改动文件未越出 ownership 边界 + - README diff 与代码事实一致，且未引入无法从当前 benchmark 实现验证的表述 +- 当前 stop decision： + - 不继续开启新的 XML 文档波次 + - 原因不是 branch-size 阈值耗尽；当前分支仍只有 `14 files` + - 停止原因是候选清晰度下降：继续追逐 explorer 误报会降低 reviewability，并无谓增加当前上下文负担 +- 当前下一步： + - 主线程更新 `ai-plan/public/cqrs-rewrite/**` + - 串行运行 benchmark 工程 build、license-header 与 `git diff --check` + - 提交 README 与 `ai-plan` 收尾 + ### 阶段：benchmark XML 契约第 2 波收口（CQRS-REWRITE-RP-138） - 延续 `$gframework-batch-boot 50`，基线保持为 `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)`。