Refactor/cqrs architecture decoupling

.coderabbit.yaml

@@ -16,6 +16,8 @@ reviews:
   auto_review:
     enabled: true
     drafts: false # draft PR 不 review
+    base_branches:
+      - refactor/cqrs-architecture-decoupling
 
 chat:
   auto_reply: true

.github/workflows/auto-tag.yml

@@ -5,6 +5,8 @@ on:
     workflows: ["CI - Build & Test"]
     types:
       - completed
+    branches:
+      - main
   workflow_dispatch:
 concurrency:
   group: auto-tag-main
@@ -13,15 +15,15 @@ concurrency:
 jobs:
   auto-tag:
     if: >
-      github.ref == 'refs/heads/main' &&
       (
-        (
-          github.event_name == 'workflow_run' &&
-          github.event.workflow_run.conclusion == 'success' &&
-          contains(github.event.workflow_run.head_commit.message, '[release ci]')
-        )
-        ||
-        github.event_name == 'workflow_dispatch'
+        github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        contains(github.event.workflow_run.head_commit.message, '[release ci]')
+      )
+      ||
+      (
+        github.event_name == 'workflow_dispatch' &&
+        github.ref == 'refs/heads/main'
       )
 
     runs-on: ubuntu-latest
@@ -61,4 +63,4 @@ jobs:
           fi
 
           git tag -a "$TAG" -m "Auto tag $TAG"
-          git push "https://x-access-token:${PAT}@github.com/${{ github.repository }}.git" "$TAG"
+          git push "https://x-access-token:${PAT}@github.com/${{ github.repository }}.git" "$TAG"

.github/workflows/ci.yml

@@ -1,12 +1,10 @@
 # CI/CD工作流配置：构建和测试.NET项目
-# 该工作流在push到main/master分支或创建pull request时触发
+# 该工作流仅在创建或更新面向任意分支的 pull request 时触发
 name: CI - Build & Test
 
 on:
-  push:
-    branches: [ main, master ]
   pull_request:
-    branches: [ main, master ]
+    branches: [ '**' ]
 
 permissions:
   contents: read
@@ -69,9 +67,9 @@ jobs:
           # 扫描路径，. 表示扫描整个仓库
           path: .
           # 基础提交哈希，用于与当前提交进行比较
-          base: ${{ github.event.before }}
+          base: ${{ github.event.pull_request.base.sha }}
           # 当前提交哈希，作为扫描的目标版本
-          head: ${{ github.sha }}
+          head: ${{ github.event.pull_request.head.sha }}
 
   # 构建和测试 job（并行执行）
   build-and-test:
@@ -168,6 +166,12 @@ jobs:
             --logger "trx;LogFileName=sg-$RANDOM.trx" \
             --results-directory TestResults &
 
+          dotnet test GFramework.Cqrs.Tests \
+            -c Release \
+            --no-build \
+            --logger "trx;LogFileName=cqrs-$RANDOM.trx" \
+            --results-directory TestResults &
+
           dotnet test GFramework.Ecs.Arch.Tests \
             -c Release \
             --no-build \

.github/workflows/codeql.yml

@@ -4,14 +4,11 @@ name: "CodeQL"
 
 # 触发事件配置
 # 在以下情况下触发工作流：
-# 1. 推送到main分支时
-# 2. 针对main分支的拉取请求时  
-# 3. 每天凌晨2点执行一次
+# 1. 针对任意分支的拉取请求时
+# 2. 每天凌晨2点执行一次
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ '**' ]
   schedule:
     - cron: '0 2 * * *'
 

AGENTS.md

@@ -244,6 +244,16 @@ bash scripts/validate-csharp-naming.sh
 - Tracking updates MUST reflect completed work, newly discovered issues, validation results, and the next recommended
   recovery point.
 - Completing code changes without updating the active tracking document is considered incomplete work.
+- For any multi-step refactor, migration, or cross-module task, contributors MUST create or adopt a dedicated recovery
+  document under `local-plan/todos/` before making substantive code changes.
+- Recovery documents MUST record the current phase, the active recovery point identifier, known risks, and the next
+  recommended resume step so another contributor or subagent can continue the work safely.
+- Contributors MUST maintain a matching execution trace under `local-plan/traces/` for complex work. The trace should
+  record the current date, key decisions, validation milestones, and the immediate next step.
+- When a task spans multiple commits or is likely to exceed a single agent context window, update both the recovery
+  document and the trace at each meaningful milestone before pausing or handing work off.
+- If subagents are used on a complex task, the main agent MUST capture the delegated scope and any accepted findings in
+  the active recovery document or trace before continuing implementation.
 
 ### Repository Documentation
 

CLAUDE.md

@@ -73,7 +73,9 @@ Architecture 负责统一生命周期编排，核心阶段包括：
 
 ### CQRS
 
-命令与查询分离，支持同步与异步执行。Mediator 模式通过源码生成器集成，以减少模板代码并保持调用路径清晰。
+命令与查询分离，支持同步与异步执行。当前版本内建自有 CQRS runtime、行为管道和 handler 自动注册；公开 API 里仍保留少量历史
+`Mediator` 命名以兼容旧调用点，但这些别名已进入正式弃用周期：新代码应使用 `Cqrs` 命名入口，旧别名会继续兼容一段时间并计划在未来
+major 版本中移除。
 
 ### EventBus
 
@@ -103,6 +105,8 @@ Architecture 负责统一生命周期编排，核心阶段包括：
 - `PriorityGenerator` (`[Priority]`): 生成优先级比较相关实现。
 - `EnumExtensionsGenerator` (`[GenerateEnumExtensions]`): 生成枚举扩展能力。
 - `ContextAwareGenerator` (`[ContextAware]`): 自动实现 `IContextAware` 相关样板逻辑。
+- `CqrsHandlerRegistryGenerator`: 为消费端程序集生成 CQRS handler 注册器，运行时优先使用生成产物，无法覆盖时回退到反射扫描；非默认程序集可通过
+  `RegisterCqrsHandlersFromAssembly(...)` / `RegisterCqrsHandlersFromAssemblies(...)` 显式接入同一路径。
 
 这些生成器的目标是减少重复代码，同时保持框架层 API 的一致性与可维护性。
 

GFramework.Core.Abstractions/Architectures/IArchitecture.cs

@@ -1,8 +1,9 @@
+using System.ComponentModel;
+using System.Reflection;
 using GFramework.Core.Abstractions.Lifecycle;
 using GFramework.Core.Abstractions.Model;
 using GFramework.Core.Abstractions.Systems;
 using GFramework.Core.Abstractions.Utility;
-using Microsoft.Extensions.DependencyInjection;
 
 namespace GFramework.Core.Abstractions.Architectures;
 
@@ -73,15 +74,46 @@ public interface IArchitecture : IAsyncInitializable, IAsyncDestroyable, IInitia
     void RegisterUtility<T>(Action<T>? onCreated = null) where T : class, IUtility;
 
     /// <summary>
-    ///     注册中介行为管道
-    ///     用于配置Mediator框架的行为拦截和处理逻辑。
+    ///     注册 CQRS 请求管道行为。
     ///     既支持实现 <c>IPipelineBehavior&lt;,&gt;</c> 的开放泛型行为类型，
     ///     也支持绑定到单一请求/响应对的封闭行为类型。
     /// </summary>
     /// <typeparam name="TBehavior">行为类型，必须是引用类型</typeparam>
+    void RegisterCqrsPipelineBehavior<TBehavior>()
+        where TBehavior : class;
+
+    /// <summary>
+    ///     注册 CQRS 请求管道行为。
+    ///     该成员保留旧名称以兼容历史调用点，内部行为与 <see cref="RegisterCqrsPipelineBehavior{TBehavior}" /> 一致。
+    ///     新代码不应继续依赖该别名；兼容层计划在未来的 major 版本中移除。
+    ///     既支持实现 <c>IPipelineBehavior&lt;,&gt;</c> 的开放泛型行为类型，
+    ///     也支持绑定到单一请求/响应对的封闭行为类型。
+    /// </summary>
+    /// <typeparam name="TBehavior">行为类型，必须是引用类型</typeparam>
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    [Obsolete(
+        "Use RegisterCqrsPipelineBehavior<TBehavior>() instead. This compatibility alias will be removed in a future major version.")]
     void RegisterMediatorBehavior<TBehavior>()
         where TBehavior : class;
 
+    /// <summary>
+    ///     从指定程序集显式注册 CQRS 处理器。
+    ///     当处理器位于默认架构程序集之外的模块或扩展程序集中时，可在初始化阶段调用该入口接入对应程序集。
+    /// </summary>
+    /// <param name="assembly">包含 CQRS 处理器或生成注册器的程序集。</param>
+    /// <exception cref="ArgumentNullException"><paramref name="assembly" /> 为 <see langword="null" />。</exception>
+    /// <exception cref="InvalidOperationException">当前架构的底层容器已冻结，无法继续注册处理器。</exception>
+    void RegisterCqrsHandlersFromAssembly(Assembly assembly);
+
+    /// <summary>
+    ///     从多个程序集显式注册 CQRS 处理器。
+    ///     该入口会对程序集集合去重，适用于统一接入多个扩展包或模块程序集。
+    /// </summary>
+    /// <param name="assemblies">要接入的程序集集合。</param>
+    /// <exception cref="ArgumentNullException"><paramref name="assemblies" /> 为 <see langword="null" />。</exception>
+    /// <exception cref="InvalidOperationException">当前架构的底层容器已冻结，无法继续注册处理器。</exception>
+    void RegisterCqrsHandlersFromAssemblies(IEnumerable<Assembly> assemblies);
+
     /// <summary>
     ///     安装架构模块
     /// </summary>
@@ -101,4 +133,4 @@ void RegisterMediatorBehavior<TBehavior>()
     /// </summary>
     /// <returns>表示异步等待操作的任务</returns>
     Task WaitUntilReadyAsync();
-}
+}