From a016e3d4a4e7866be649ffe0e81dfba234bc72da Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Tue, 12 May 2026 13:21:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(cqrs-benchmarks):=20=E5=90=8C=E6=AD=A5=20s?= =?UTF-8?q?tream=20benchmark=20=E6=81=A2=E5=A4=8D=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 StreamingBenchmarks 的 XML 返回值注释并收口 README 中的 stream startup/gap 描述。 - 补充 cqrs-rewrite tracking 与 trace，记录 PR #349 合并后的新基线、startup parity 进展与下一恢复点。 --- .../Messaging/StreamingBenchmarks.cs | 2 + GFramework.Cqrs.Benchmarks/README.md | 4 +- .../todos/cqrs-rewrite-migration-tracking.md | 72 ++++++++----------- .../traces/cqrs-rewrite-migration-trace.md | 41 +++++++++++ 4 files changed, 76 insertions(+), 43 deletions(-) diff --git a/GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs b/GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs index bb3f634a..24ea79bd 100644 --- a/GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs +++ b/GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs @@ -135,6 +135,7 @@ public class StreamingBenchmarks /// /// 直接调用 handler，并按当前观测模式消费响应序列，作为 stream dispatch 额外开销的 baseline。 /// + /// 按当前观测模式完成 stream 消费后的等待句柄。 [Benchmark(Baseline = true)] public ValueTask Stream_Baseline() { @@ -158,6 +159,7 @@ public class StreamingBenchmarks /// /// 通过 MediatR 创建 stream，并按当前观测模式消费，作为外部设计对照。 /// + /// 按当前观测模式完成 stream 消费后的等待句柄。 [Benchmark] public ValueTask Stream_MediatR() { diff --git a/GFramework.Cqrs.Benchmarks/README.md b/GFramework.Cqrs.Benchmarks/README.md index dc1e0d15..4356bde6 100644 --- a/GFramework.Cqrs.Benchmarks/README.md +++ b/GFramework.Cqrs.Benchmarks/README.md @@ -39,7 +39,7 @@ - 同时提供 `FirstItem` 与 `DrainAll` 两种观测口径 - stream startup - `Messaging/StreamStartupBenchmarks.cs` - - `Initialization` 与 `ColdStart` 两组下，`GFramework.Cqrs` reflection、`GFramework.Cqrs` generated、`MediatR` + - `Initialization` 与 `ColdStart` 两组下，覆盖 `GFramework.Cqrs` reflection、`GFramework.Cqrs` generated，以及当前 benchmark 项目已接入的 stream startup 外部 mediator 对照组 - 其中 `ColdStart` 的边界是“新宿主 + 首个元素命中”，不是完整枚举整个 stream - notification steady-state - `Messaging/NotificationBenchmarks.cs` @@ -100,6 +100,6 @@ dotnet run --project GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.cspro ## 当前缺口 -- 当前没有 stream 生命周期与 startup 版的 NuGet `Mediator` source-generated concrete path 对照；`StreamLifetimeBenchmarks` 与 `StreamStartupBenchmarks` 现在都只覆盖 `GFramework.Cqrs` 与 `MediatR` +- 当前没有 stream 生命周期版的 NuGet `Mediator` source-generated concrete path 对照；`StreamLifetimeBenchmarks` 现在只覆盖 `GFramework.Cqrs` 与 `MediatR` - 当前没有 request 生命周期下的 NuGet `Mediator` compile-time lifetime 矩阵；`RequestLifetimeBenchmarks` 只覆盖 `GFramework.Cqrs` 与 `MediatR` - 当前没有 notification fan-out 的生命周期矩阵；`NotificationFanOutBenchmarks` 只覆盖固定 `4 handler` 的已装配宿主 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 9e6dafdc..e7fcb3b0 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,80 +12,70 @@ CQRS 迁移与收敛。 ## 当前恢复点 -- 恢复点编号：`CQRS-REWRITE-RP-136` +- 恢复点编号：`CQRS-REWRITE-RP-137` - 当前阶段：`Phase 8` -- 当前 PR 锚点：`PR #349` +- 当前 PR 锚点：`PR #349（已于 2026-05-12 合并到 origin/main）` - 当前结论： - - 本轮先按 `$gframework-pr-review` 重新确认当前分支最新 GitHub 上下文，确认 `feat/cqrs-optimization` 在 `2026-05-12` 已切到 `PR #349`，不再沿用旧 tracking 中的 `PR #348` 锚点。 - - 随后按 `$gframework-batch-boot 50` 持续协调多波 non-conflicting subagent，基线固定为 - `origin/main @ ef4d3d5d (2026-05-11 17:33:43 +0800)`。 - - 当前 branch 相对基线的累计 diff 约为 `9 files / 1111 lines`；本轮停点由 - `context-budget / reviewability` 决定，而不是 `50 files` 阈值。 - - `PR #349` latest-head review 当前确认仍成立的项只有： - - `StreamPipelineBenchmarks` 三个公开 benchmark 方法补齐 `` XML 契约 - - `StreamingBenchmarks.Stream_Mediator` 补齐 `` XML 契约 - - `CqrsNotificationPublisherTests` 中 fallback publisher 缓存回归测试去掉误导性的“第二次解析返回其它 publisher”分支 - - active tracking / trace 的当前 PR 锚点与下一步入口同步到 `PR #349` - - tests 侧已补齐并提交： + - 本轮恢复时先按 `$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 同步 + - tests 侧此前已补齐并提交： - `CqrsRegistrationServiceTests`：补空输入、空项过滤、稳定键排序与跨调用跳过边界 - `CqrsHandlerRegistrarTests` 与 `CqrsHandlerRegistrarFallbackFailureTests`： 补 abstract registry 与缺少无参构造器 registry 的回退 / 抛错覆盖 - `CqrsNotificationPublisherTests`：补“零 publisher 回退到默认顺序发布器并缓存”回归 - - benchmark 侧已补齐并提交： + - benchmark 侧此前已补齐并提交： - `StreamPipelineBenchmarks` - `StreamingBenchmarks` 的 steady-state `Mediator` 对照 - `GFramework.Cqrs.Benchmarks/README.md` 的 stream coverage / gap 同步 + - `StreamStartupBenchmarks` 的 `Mediator` initialization / cold-start 对照 - 本轮未修改 `GFramework.Cqrs` 运行时代码；notification fallback 与 generated registry 激活守卫均由新回归证明现有实现已满足预期。 ## 当前活跃事实 - 当前分支：`feat/cqrs-optimization` -- 当前 PR：`PR #349` +- 当前 PR：`PR #349（已合并；当前分支暂无新的公开 PR）` - 当前写面： - - `GFramework.Cqrs.Benchmarks/Messaging/StreamPipelineBenchmarks.cs` - `GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs` + - `GFramework.Cqrs.Benchmarks/Messaging/StreamStartupBenchmarks.cs` - `GFramework.Cqrs.Benchmarks/README.md` - - `GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarFallbackFailureTests.cs` - - `GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs` - - `GFramework.Cqrs.Tests/Cqrs/CqrsNotificationPublisherTests.cs` - - `GFramework.Cqrs.Tests/Cqrs/CqrsRegistrationServiceTests.cs` - `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md` - `ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` - 当前基线： - - `origin/main @ ef4d3d5d (2026-05-11 17:33:43 +0800)` - - 本轮 batch 启动前，分支相对基线的累计 diff 为 `0 files / 0 lines` - - 当前自然停点时，累计 diff 约为 `9 files / 1111 lines` + - `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)` + - 当前已提交 branch diff：`1 file / 60 lines` + - 当前工作树尚有 2 个未提交收尾文件：`StreamingBenchmarks.cs`、`GFramework.Cqrs.Benchmarks/README.md` - 本轮提交： - - `ef3cfdc4` `test(cqrs): 补充注册服务边界测试` - - `bcfecd3c` `test(cqrs): 补充 registrar 激活失败分支测试` - - `59cab567` `test(cqrs-benchmarks): 新增 stream pipeline benchmark 覆盖` - - `010b7028` `test(cqrs): 补充通知回退回归覆盖` - - `ae1c3b89` `test(cqrs-benchmarks): 补齐 stream steady-state Mediator 对照` + - `f346110a` `feat(cqrs-benchmarks): 补齐 stream startup 的 Mediator 对照路径` ## 当前风险 -- 分支已累积 5 个窄切片提交；若继续在同一 turn 扩 benchmark + docs，reviewability 会明显下降。 -- 新增 benchmark 目前只做了编译验证，尚未执行 `StreamPipelineBenchmarks` 或更新后的 `StreamingBenchmarks` 实际作业。 -- `ef3cfdc4` 的 commit body 含字面 `\n`；若后续要整理历史，需要在显式允许的前提下单独处理提交格式。 +- `StreamStartupBenchmarks` 的 `Mediator` parity 目前只做了编译验证，尚未单独执行 benchmark 作业确认 startup 矩阵运行结果。 +- `StreamLifetimeBenchmarks` 仍缺 `Mediator` parity；该项涉及 `BenchmarkHostFactory` 与 compile-time lifetime 形状，不再是本轮低风险切片。 +- 当前 worktree 仍有 2 个未提交文档/注释收尾文件；若不在同轮提交，下一次 `boot` 会同时面对已提交 benchmark 扩展与未提交文档漂移。 ## 最近权威验证 - `dotnet build GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release` - 结果：通过，`0 warning / 0 error` -- `dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release --filter "FullyQualifiedName~CqrsNotificationPublisherTests"` - - 结果：通过，`Passed: 9, Failed: 0` -- `dotnet test GFramework.Cqrs.Tests/GFramework.Cqrs.Tests.csproj -c Release --filter "FullyQualifiedName~CqrsRegistrationServiceTests|FullyQualifiedName~CqrsHandlerRegistrarTests|FullyQualifiedName~CqrsHandlerRegistrarFallbackFailureTests|FullyQualifiedName~CqrsNotificationPublisherTests"` - - 结果：通过，`Passed: 36, Failed: 0` -- `python3 scripts/license-header.py --check --paths GFramework.Cqrs.Benchmarks/Messaging/StreamPipelineBenchmarks.cs GFramework.Cqrs.Benchmarks/Messaging/StreamingBenchmarks.cs GFramework.Cqrs.Benchmarks/README.md GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarFallbackFailureTests.cs GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs GFramework.Cqrs.Tests/Cqrs/CqrsNotificationPublisherTests.cs GFramework.Cqrs.Tests/Cqrs/CqrsRegistrationServiceTests.cs ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` - - 结果：通过 -- `git diff --check origin/main...HEAD` +- `python3 scripts/license-header.py --check` - 结果：通过 +- `$gframework-pr-review` + - 结果：`PR #349` 已关闭；latest-head review open thread 经本地核对仅剩 `StreamingBenchmarks.Stream_MediatR()` 的 XML 文档缺口仍成立 ## 下一推荐步骤 -1. 再次运行 `$gframework-pr-review`，复核 `PR #349` latest-head open thread 是否已随着当前修复提交收敛。 -2. 若继续扩 benchmark，优先在 `StreamLifetimeBenchmarks` 或 `StreamStartupBenchmarks` 中补单文件 `Mediator` parity，而不是并行扩多个矩阵。 -3. 若切回文档收尾，把 `GFramework.Cqrs/README.md`、`docs/zh-CN/core/command.md`、`docs/zh-CN/core/query.md` 作为单独一波 docs-only 切片处理。 +1. 先提交 `StreamingBenchmarks.cs`、`GFramework.Cqrs.Benchmarks/README.md` 与本 tracking / trace 收尾，回到干净工作树。 +2. 若继续 benchmark 波次，优先单独执行 `StreamStartupBenchmarks` 的最小 smoke run，验证新加 `Mediator` startup 路径可运行。 +3. 若后续还要扩 stream parity，把 `StreamLifetimeBenchmarks` 视为跨文件设计任务，而不是继续按“单文件低风险切片”处理。 ## 活跃文档 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 3523d2d0..81baa47e 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,47 @@ SPDX-License-Identifier: Apache-2.0 ## 2026-05-12 +### 阶段：stream startup parity 与文档收尾（CQRS-REWRITE-RP-137） + +- 按 `$gframework-batch-boot 50` 恢复后，先重新执行 `$gframework-pr-review`。 +- 当前 GitHub 事实： + - `PR #349` 已关闭并合并到 `origin/main` + - 基线切换为 `origin/main @ 2b2bec65 (2026-05-12 11:49:39 +0800)` + - 当前分支相对新基线的已提交 diff 初始为 `0 files / 0 lines` +- latest-head open thread 本地复核： + - stale + - `StreamPipelineBenchmarks.Stream_Baseline` 的 `` 已存在 + - `CqrsNotificationPublisherTests` 的 fallback 缓存安全网已收口 + - trace 的当前 PR / 下一步已同步到 `PR #349` + - valid + - `StreamingBenchmarks.Stream_MediatR()` 仍缺 `` XML 文档 +- 第 1 波 accepted delegated scope： + - `StreamingBenchmarks.cs` + - worker 补 `Stream_Baseline()` 与 `Stream_MediatR()` 的 `` XML 契约 + - 主线程验收时确认其中 `Stream_Baseline()` 属于额外收口，不是 latest-head 必修项 + - `StreamStartupBenchmarks.cs` + - worker 在单文件 ownership 内补 `GeneratedMediator` 宿主字段、setup/cleanup、`Initialization_Mediator()`、`ColdStart_Mediator()` + - 同文件把 `BenchmarkStreamRequest` / `BenchmarkStreamHandler` 扩成同时支持 `Mediator` stream 合同 + - worker 自主完成并提交：`f346110a feat(cqrs-benchmarks): 补齐 stream startup 的 Mediator 对照路径` + - `GFramework.Cqrs.Benchmarks/README.md` + - worker 只收口 `StreamStartupBenchmarks` coverage 与当前 gap 描述，不假设 `StreamLifetimeBenchmarks` 已补 parity +- 主线程验收结论： + - `StreamLifetimeBenchmarks` 的 `Mediator` parity 被判定为 hard slice，需要 `BenchmarkHostFactory` 与 compile-time lifetime 配套，不再继续作为本 turn 的低风险并行切片 + - 当前自然停点应落在： + - 已提交的 `StreamStartupBenchmarks` parity + - 未提交但已验收的 `StreamingBenchmarks.cs` / `README.md` 收尾 + - `ai-plan` 同步到新基线与新恢复点 +- 本轮权威验证里程碑： + - `dotnet build GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release` + - 结果：通过，`0 warning / 0 error` + - `python3 scripts/license-header.py --check` + - 结果：通过 + - `git diff --check` + - 待当前未提交收尾切片与 `ai-plan` 一并提交前再次运行 +- 当前下一步： + - 提交 `StreamingBenchmarks.cs`、`GFramework.Cqrs.Benchmarks/README.md` 与 `ai-plan/public/cqrs-rewrite/**` 收尾 + - 如需继续 benchmark 波次，优先做 `StreamStartupBenchmarks` 的最小 smoke run，而不是直接展开 `StreamLifetimeBenchmarks` + ### 阶段：PR #349 latest-head review 收口（CQRS-REWRITE-RP-136） - 重新执行 `$gframework-pr-review`，按 GitHub 当前分支状态确认 `feat/cqrs-optimization` 在 `2026-05-12` 对应的是 `PR #349`，不再沿用 active tracking 中的 `PR #348` 锚点。