Merge pull request #246 from GeWuYou/refactor/cqrs-dispatcher-cache

Refactor/cqrs dispatcher cache

CLAUDE.md

@@ -18,17 +18,22 @@ Follow them strictly.
 
 ```text
 GFramework (meta package) ─→ Core + Game
+GFramework.Cqrs ─→ Cqrs.Abstractions, Core.Abstractions
 GFramework.Core ─→ Core.Abstractions
 GFramework.Game ─→ Game.Abstractions, Core, Core.Abstractions
 GFramework.Godot ─→ Core, Game, Core.Abstractions, Game.Abstractions
 GFramework.Ecs.Arch ─→ Ecs.Arch.Abstractions, Core, Core.Abstractions
-GFramework.SourceGenerators ─→ SourceGenerators.Common, SourceGenerators.Abstractions
+GFramework.Core.SourceGenerators ─→ Core.SourceGenerators.Abstractions, SourceGenerators.Common
+GFramework.Game.SourceGenerators ─→ SourceGenerators.Common
+GFramework.Godot.SourceGenerators ─→ Godot.SourceGenerators.Abstractions, SourceGenerators.Common
+GFramework.Cqrs.SourceGenerators ─→ SourceGenerators.Common
 ```
 
 - **Abstractions projects** (`netstandard2.1`): 只包含接口和契约定义，不承载运行时实现逻辑。
 - **Core / Game / Ecs.Arch** (`net8.0;net9.0;net10.0`): 平台无关的核心实现层。
 - **Godot**: Godot 引擎集成层，负责与节点、场景和引擎生命周期对接。
-- **SourceGenerators** (`netstandard2.1`): Roslyn 增量源码生成器及其公共基础设施。
+- **SourceGenerators family** (`netstandard2.0`/`netstandard2.1`): 按 Core / Game / Godot / Cqrs 拆分的 Roslyn
+  增量源码生成器，以及共享的 abstractions/common 基础设施。
 
 ## Architecture Pattern
 
@@ -114,10 +119,12 @@ Architecture 负责统一生命周期编排，核心阶段包括：
 仓库以“抽象层 + 实现层 + 集成层 + 生成器层”的方式组织：
 
 - `GFramework.Core.Abstractions` / `GFramework.Game.Abstractions`: 约束接口和公共契约。
+- `GFramework.Cqrs.Abstractions` / `GFramework.Cqrs`: 提供 CQRS 契约、runtime 与 handler 注册基础设施。
 - `GFramework.Core` / `GFramework.Game`: 提供平台无关实现。
 - `GFramework.Godot`: 提供与 Godot 运行时集成的适配实现。
 - `GFramework.Ecs.Arch`: 提供 ECS Architecture 相关扩展。
-- `GFramework.SourceGenerators` 及相关 Abstractions/Common: 提供代码生成能力。
+- `GFramework.Core.SourceGenerators` / `GFramework.Game.SourceGenerators` / `GFramework.Godot.SourceGenerators` /
+  `GFramework.Cqrs.SourceGenerators` 与相关 Abstractions/Common: 提供代码生成能力。
 
 这种结构的核心设计目标是让抽象稳定、实现可替换、引擎集成隔离、生成器能力可独立演进。
 

GFramework.Cqrs.Tests/Cqrs/CqrsDispatcherCacheTests.cs

@@ -7,7 +7,7 @@ using GFramework.Cqrs.Abstractions.Cqrs;
 namespace GFramework.Cqrs.Tests.Cqrs;
 
 /// <summary>
-///     验证 CQRS dispatcher 会缓存热路径中的服务类型与调用委托。
+///     验证 CQRS dispatcher 会缓存热路径中的 dispatch binding。
 /// </summary>
 [TestFixture]
 internal sealed class CqrsDispatcherCacheTests
@@ -46,39 +46,44 @@ internal sealed class CqrsDispatcherCacheTests
     }
 
     /// <summary>
-    ///     验证相同消息类型重复分发时，不会重复扩张服务类型与调用委托缓存。
+    ///     验证相同消息类型重复分发时，不会重复扩张 dispatch binding 缓存。
     /// </summary>
     [Test]
-    public async Task Dispatcher_Should_Cache_Service_Types_After_First_Dispatch()
+    public async Task Dispatcher_Should_Cache_Dispatch_Bindings_After_First_Dispatch()
     {
-        var notificationServiceTypes = GetCacheField("NotificationHandlerServiceTypes");
-        var requestServiceTypes = GetCacheField("RequestServiceTypes");
-        var streamServiceTypes = GetCacheField("StreamHandlerServiceTypes");
-        var requestInvokers = GetGenericCacheField("RequestInvokerCache`1", typeof(int), "Invokers");
-        var requestPipelineInvokers = GetGenericCacheField("RequestPipelineInvokerCache`1", typeof(int), "Invokers");
-        var notificationInvokers = GetCacheField("NotificationInvokers");
-        var streamInvokers = GetCacheField("StreamInvokers");
+        var notificationBindings = GetCacheField("NotificationDispatchBindings");
+        var requestBindings = GetCacheField("RequestDispatchBindings");
+        var streamBindings = GetCacheField("StreamDispatchBindings");
 
-        var notificationBefore = notificationServiceTypes.Count;
-        var requestBefore = requestServiceTypes.Count;
-        var streamBefore = streamServiceTypes.Count;
-        var requestInvokersBefore = requestInvokers.Count;
-        var requestPipelineInvokersBefore = requestPipelineInvokers.Count;
-        var notificationInvokersBefore = notificationInvokers.Count;
-        var streamInvokersBefore = streamInvokers.Count;
+        Assert.Multiple(() =>
+        {
+            Assert.That(
+                GetSingleKeyCacheValue(notificationBindings, typeof(DispatcherCacheNotification)),
+                Is.Null);
+            Assert.That(
+                GetPairCacheValue(requestBindings, typeof(DispatcherCacheRequest), typeof(int)),
+                Is.Null);
+            Assert.That(
+                GetPairCacheValue(requestBindings, typeof(DispatcherPipelineCacheRequest), typeof(int)),
+                Is.Null);
+            Assert.That(
+                GetPairCacheValue(streamBindings, typeof(DispatcherCacheStreamRequest), typeof(int)),
+                Is.Null);
+        });
 
         await _context!.SendRequestAsync(new DispatcherCacheRequest());
         await _context.SendRequestAsync(new DispatcherPipelineCacheRequest());
         await _context.PublishAsync(new DispatcherCacheNotification());
         await DrainAsync(_context.CreateStream(new DispatcherCacheStreamRequest()));
 
-        var notificationAfterFirstDispatch = notificationServiceTypes.Count;
-        var requestAfterFirstDispatch = requestServiceTypes.Count;
-        var streamAfterFirstDispatch = streamServiceTypes.Count;
-        var requestInvokersAfterFirstDispatch = requestInvokers.Count;
-        var requestPipelineInvokersAfterFirstDispatch = requestPipelineInvokers.Count;
-        var notificationInvokersAfterFirstDispatch = notificationInvokers.Count;
-        var streamInvokersAfterFirstDispatch = streamInvokers.Count;
+        var notificationAfterFirstDispatch =
+            GetSingleKeyCacheValue(notificationBindings, typeof(DispatcherCacheNotification));
+        var requestAfterFirstDispatch =
+            GetPairCacheValue(requestBindings, typeof(DispatcherCacheRequest), typeof(int));
+        var pipelineAfterFirstDispatch =
+            GetPairCacheValue(requestBindings, typeof(DispatcherPipelineCacheRequest), typeof(int));
+        var streamAfterFirstDispatch =
+            GetPairCacheValue(streamBindings, typeof(DispatcherCacheStreamRequest), typeof(int));
 
         await _context.SendRequestAsync(new DispatcherCacheRequest());
         await _context.SendRequestAsync(new DispatcherPipelineCacheRequest());
@@ -87,58 +92,63 @@ internal sealed class CqrsDispatcherCacheTests
 
         Assert.Multiple(() =>
         {
-            Assert.That(notificationAfterFirstDispatch, Is.EqualTo(notificationBefore + 1));
-            Assert.That(requestAfterFirstDispatch, Is.EqualTo(requestBefore + 2));
-            Assert.That(streamAfterFirstDispatch, Is.EqualTo(streamBefore + 1));
-            Assert.That(requestInvokersAfterFirstDispatch, Is.EqualTo(requestInvokersBefore + 1));
-            Assert.That(requestPipelineInvokersAfterFirstDispatch, Is.EqualTo(requestPipelineInvokersBefore + 1));
-            Assert.That(notificationInvokersAfterFirstDispatch, Is.EqualTo(notificationInvokersBefore + 1));
-            Assert.That(streamInvokersAfterFirstDispatch, Is.EqualTo(streamInvokersBefore + 1));
+            Assert.That(notificationAfterFirstDispatch, Is.Not.Null);
+            Assert.That(requestAfterFirstDispatch, Is.Not.Null);
+            Assert.That(pipelineAfterFirstDispatch, Is.Not.Null);
+            Assert.That(streamAfterFirstDispatch, Is.Not.Null);
 
-            Assert.That(notificationServiceTypes.Count, Is.EqualTo(notificationAfterFirstDispatch));
-            Assert.That(requestServiceTypes.Count, Is.EqualTo(requestAfterFirstDispatch));
-            Assert.That(streamServiceTypes.Count, Is.EqualTo(streamAfterFirstDispatch));
-            Assert.That(requestInvokers.Count, Is.EqualTo(requestInvokersAfterFirstDispatch));
-            Assert.That(requestPipelineInvokers.Count, Is.EqualTo(requestPipelineInvokersAfterFirstDispatch));
-            Assert.That(notificationInvokers.Count, Is.EqualTo(notificationInvokersAfterFirstDispatch));
-            Assert.That(streamInvokers.Count, Is.EqualTo(streamInvokersAfterFirstDispatch));
+            Assert.That(
+                GetSingleKeyCacheValue(notificationBindings, typeof(DispatcherCacheNotification)),
+                Is.SameAs(notificationAfterFirstDispatch));
+            Assert.That(
+                GetPairCacheValue(requestBindings, typeof(DispatcherCacheRequest), typeof(int)),
+                Is.SameAs(requestAfterFirstDispatch));
+            Assert.That(
+                GetPairCacheValue(requestBindings, typeof(DispatcherPipelineCacheRequest), typeof(int)),
+                Is.SameAs(pipelineAfterFirstDispatch));
+            Assert.That(
+                GetPairCacheValue(streamBindings, typeof(DispatcherCacheStreamRequest), typeof(int)),
+                Is.SameAs(streamAfterFirstDispatch));
         });
     }
 
     /// <summary>
-    ///     验证 request 调用委托会按响应类型分别缓存，避免不同响应类型共用 object 结果桥接。
+    ///     验证 request dispatch binding 会按响应类型分别缓存，避免不同响应类型共用 object 结果桥接。
     /// </summary>
     [Test]
-    public async Task Dispatcher_Should_Cache_Request_Invokers_Per_Response_Type()
+    public async Task Dispatcher_Should_Cache_Request_Dispatch_Bindings_Per_Response_Type()
     {
-        var intRequestInvokers = GetGenericCacheField("RequestInvokerCache`1", typeof(int), "Invokers");
-        var stringRequestInvokers = GetGenericCacheField("RequestInvokerCache`1", typeof(string), "Invokers");
-
-        var intBefore = intRequestInvokers.Count;
-        var stringBefore = stringRequestInvokers.Count;
+        var requestBindings = GetCacheField("RequestDispatchBindings");
 
         await _context!.SendRequestAsync(new DispatcherCacheRequest());
         await _context.SendRequestAsync(new DispatcherStringCacheRequest());
 
-        var intAfterFirstDispatch = intRequestInvokers.Count;
-        var stringAfterFirstDispatch = stringRequestInvokers.Count;
+        var intAfterFirstDispatch =
+            GetPairCacheValue(requestBindings, typeof(DispatcherCacheRequest), typeof(int));
+        var stringAfterFirstDispatch =
+            GetPairCacheValue(requestBindings, typeof(DispatcherStringCacheRequest), typeof(string));
 
         await _context.SendRequestAsync(new DispatcherCacheRequest());
         await _context.SendRequestAsync(new DispatcherStringCacheRequest());
 
         Assert.Multiple(() =>
         {
-            Assert.That(intAfterFirstDispatch, Is.EqualTo(intBefore + 1));
-            Assert.That(stringAfterFirstDispatch, Is.EqualTo(stringBefore + 1));
-            Assert.That(intRequestInvokers.Count, Is.EqualTo(intAfterFirstDispatch));
-            Assert.That(stringRequestInvokers.Count, Is.EqualTo(stringAfterFirstDispatch));
+            Assert.That(intAfterFirstDispatch, Is.Not.Null);
+            Assert.That(stringAfterFirstDispatch, Is.Not.Null);
+            Assert.That(intAfterFirstDispatch, Is.Not.SameAs(stringAfterFirstDispatch));
+            Assert.That(
+                GetPairCacheValue(requestBindings, typeof(DispatcherCacheRequest), typeof(int)),
+                Is.SameAs(intAfterFirstDispatch));
+            Assert.That(
+                GetPairCacheValue(requestBindings, typeof(DispatcherStringCacheRequest), typeof(string)),
+                Is.SameAs(stringAfterFirstDispatch));
         });
     }
 
     /// <summary>
-    ///     通过反射读取 dispatcher 的静态缓存字典。
+    ///     通过反射读取 dispatcher 的静态缓存对象。
     /// </summary>
-    private static IDictionary GetCacheField(string fieldName)
+    private static object GetCacheField(string fieldName)
     {
         var dispatcherType = GetDispatcherType();
         var field = dispatcherType.GetField(
@@ -147,9 +157,9 @@ internal sealed class CqrsDispatcherCacheTests
 
         Assert.That(field, Is.Not.Null, $"Missing dispatcher cache field {fieldName}.");
 
-        return field!.GetValue(null) as IDictionary
+        return field!.GetValue(null)
                ?? throw new InvalidOperationException(
-                   $"Dispatcher cache field {fieldName} does not implement IDictionary.");
+                   $"Dispatcher cache field {fieldName} returned null.");
     }
 
     /// <summary>
@@ -157,41 +167,47 @@ internal sealed class CqrsDispatcherCacheTests
     /// </summary>
     private static void ClearDispatcherCaches()
     {
-        GetCacheField("NotificationHandlerServiceTypes").Clear();
-        GetCacheField("RequestServiceTypes").Clear();
-        GetCacheField("StreamHandlerServiceTypes").Clear();
-        GetCacheField("NotificationInvokers").Clear();
-        GetCacheField("StreamInvokers").Clear();
-        GetGenericCacheField("RequestInvokerCache`1", typeof(int), "Invokers").Clear();
-        GetGenericCacheField("RequestInvokerCache`1", typeof(string), "Invokers").Clear();
-        GetGenericCacheField("RequestPipelineInvokerCache`1", typeof(int), "Invokers").Clear();
-        GetGenericCacheField("RequestPipelineInvokerCache`1", typeof(string), "Invokers").Clear();
+        ClearCache(GetCacheField("NotificationDispatchBindings"));
+        ClearCache(GetCacheField("RequestDispatchBindings"));
+        ClearCache(GetCacheField("StreamDispatchBindings"));
     }
 
     /// <summary>
-    ///     通过反射读取 dispatcher 嵌套泛型缓存类型上的静态缓存字典。
+    ///     读取单键缓存中当前保存的对象。
     /// </summary>
-    private static IDictionary GetGenericCacheField(string nestedTypeName, Type genericTypeArgument, string fieldName)
+    private static object? GetSingleKeyCacheValue(object cache, Type key)
     {
-        var nestedGenericType = GetDispatcherType().GetNestedType(
-            nestedTypeName,
-            BindingFlags.NonPublic);
+        return InvokeInstanceMethod(cache, "GetValueOrDefaultForTesting", key);
+    }
 
-        Assert.That(nestedGenericType, Is.Not.Null, $"Missing dispatcher nested cache type {nestedTypeName}.");
+    /// <summary>
+    ///     读取双键缓存中当前保存的对象。
+    /// </summary>
+    private static object? GetPairCacheValue(object cache, Type primaryType, Type secondaryType)
+    {
+        return InvokeInstanceMethod(cache, "GetValueOrDefaultForTesting", primaryType, secondaryType);
+    }
 
-        var closedNestedType = nestedGenericType!.MakeGenericType(genericTypeArgument);
-        var field = closedNestedType.GetField(
-            fieldName,
-            BindingFlags.NonPublic | BindingFlags.Static);
+    /// <summary>
+    ///     调用缓存实例上的无参清理方法。
+    /// </summary>
+    private static void ClearCache(object cache)
+    {
+        _ = InvokeInstanceMethod(cache, "Clear");
+    }
 
-        Assert.That(
-            field,
-            Is.Not.Null,
-            $"Missing dispatcher nested cache field {nestedTypeName}.{fieldName} for {genericTypeArgument.FullName}.");
+    /// <summary>
+    ///     调用缓存对象上的实例方法。
+    /// </summary>
+    private static object? InvokeInstanceMethod(object target, string methodName, params object[] arguments)
+    {
+        var method = target.GetType().GetMethod(
+            methodName,
+            BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
 
-        return field!.GetValue(null) as IDictionary
-               ?? throw new InvalidOperationException(
-                   $"Dispatcher nested cache field {nestedTypeName}.{fieldName} does not implement IDictionary.");
+        Assert.That(method, Is.Not.Null, $"Missing cache method {target.GetType().FullName}.{methodName}.");
+
+        return method!.Invoke(target, arguments);
     }
 
     /// <summary>

GFramework.Cqrs.Tests/Cqrs/CqrsHandlerRegistrarTests.cs

@@ -292,6 +292,124 @@ internal sealed class CqrsHandlerRegistrarTests
             Times.Never);
         generatedAssembly.Verify(static assembly => assembly.GetTypes(), Times.Never);
     }
+
+    /// <summary>
+    ///     验证同一程序集对象重复接入多个容器时，会复用已解析的 registry / fallback 元数据，
+    ///     而不是重复读取程序集级 attribute 或重复执行 type-name lookup。
+    /// </summary>
+    [Test]
+    public void RegisterHandlers_Should_Cache_Assembly_Metadata_Across_Containers()
+    {
+        var generatedAssembly = new Mock<Assembly>();
+        generatedAssembly
+            .SetupGet(static assembly => assembly.FullName)
+            .Returns("GFramework.Core.Tests.Cqrs.CachedMetadataAssembly, Version=1.0.0.0");
+        generatedAssembly
+            .Setup(static assembly => assembly.GetCustomAttributes(typeof(CqrsHandlerRegistryAttribute), false))
+            .Returns([new CqrsHandlerRegistryAttribute(typeof(PartialGeneratedNotificationHandlerRegistry))]);
+        generatedAssembly
+            .Setup(static assembly => assembly.GetCustomAttributes(typeof(CqrsReflectionFallbackAttribute), false))
+            .Returns(
+            [
+                new CqrsReflectionFallbackAttribute(
+                    ReflectionFallbackNotificationContainer.ReflectionOnlyHandlerType.FullName!)
+            ]);
+        generatedAssembly
+            .Setup(static assembly => assembly.GetType(
+                ReflectionFallbackNotificationContainer.ReflectionOnlyHandlerType.FullName!,
+                false,
+                false))
+            .Returns(ReflectionFallbackNotificationContainer.ReflectionOnlyHandlerType);
+
+        var firstContainer = new MicrosoftDiContainer();
+        var secondContainer = new MicrosoftDiContainer();
+
+        CqrsTestRuntime.RegisterHandlers(firstContainer, generatedAssembly.Object);
+        CqrsTestRuntime.RegisterHandlers(secondContainer, generatedAssembly.Object);
+        firstContainer.Freeze();
+        secondContainer.Freeze();
+
+        var firstRegistrations = firstContainer.GetAll<INotificationHandler<GeneratedRegistryNotification>>()
+            .Select(static handler => handler.GetType())
+            .ToArray();
+        var secondRegistrations = secondContainer.GetAll<INotificationHandler<GeneratedRegistryNotification>>()
+            .Select(static handler => handler.GetType())
+            .ToArray();
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(
+                firstRegistrations,
+                Is.EqualTo(
+                [
+                    typeof(GeneratedRegistryNotificationHandler),
+                    ReflectionFallbackNotificationContainer.ReflectionOnlyHandlerType
+                ]));
+            Assert.That(
+                secondRegistrations,
+                Is.EqualTo(
+                [
+                    typeof(GeneratedRegistryNotificationHandler),
+                    ReflectionFallbackNotificationContainer.ReflectionOnlyHandlerType
+                ]));
+        });
+
+        generatedAssembly.Verify(
+            static assembly => assembly.GetCustomAttributes(typeof(CqrsHandlerRegistryAttribute), false),
+            Times.Once);
+        generatedAssembly.Verify(
+            static assembly => assembly.GetCustomAttributes(typeof(CqrsReflectionFallbackAttribute), false),
+            Times.Once);
+        generatedAssembly.Verify(
+            static assembly => assembly.GetType(
+                ReflectionFallbackNotificationContainer.ReflectionOnlyHandlerType.FullName!,
+                false,
+                false),
+            Times.Once);
+    }
+
+    /// <summary>
+    ///     验证同一程序集对象在未命中 generated registry 时，会复用首次扫描得到的可加载类型列表，
+    ///     而不是为每个容器重复执行整程序集 <c>GetTypes()</c>。
+    /// </summary>
+    [Test]
+    public void RegisterHandlers_Should_Cache_Loadable_Types_Across_Containers()
+    {
+        var reflectionTypeLoadException = new ReflectionTypeLoadException(
+            [typeof(AlphaDeterministicNotificationHandler), null],
+            [new TypeLoadException("Cached loadable-type probe.")]);
+        var partiallyLoadableAssembly = new Mock<Assembly>();
+        partiallyLoadableAssembly
+            .SetupGet(static assembly => assembly.FullName)
+            .Returns("GFramework.Core.Tests.Cqrs.CachedLoadableTypesAssembly, Version=1.0.0.0");
+        partiallyLoadableAssembly
+            .Setup(static assembly => assembly.GetTypes())
+            .Throws(reflectionTypeLoadException);
+
+        var firstContainer = new MicrosoftDiContainer();
+        var secondContainer = new MicrosoftDiContainer();
+
+        CqrsTestRuntime.RegisterHandlers(firstContainer, partiallyLoadableAssembly.Object);
+        CqrsTestRuntime.RegisterHandlers(secondContainer, partiallyLoadableAssembly.Object);
+        firstContainer.Freeze();
+        secondContainer.Freeze();
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(
+                firstContainer.GetAll<INotificationHandler<DeterministicOrderNotification>>()
+                    .Select(static handler => handler.GetType())
+                    .ToArray(),
+                Is.EqualTo([typeof(AlphaDeterministicNotificationHandler)]));
+            Assert.That(
+                secondContainer.GetAll<INotificationHandler<DeterministicOrderNotification>>()
+                    .Select(static handler => handler.GetType())
+                    .ToArray(),
+                Is.EqualTo([typeof(AlphaDeterministicNotificationHandler)]));
+        });
+
+        partiallyLoadableAssembly.Verify(static assembly => assembly.GetTypes(), Times.Once);
+    }
 }
 
 /// <summary>

GFramework.Cqrs/GlobalUsings.cs

@@ -7,3 +7,4 @@ global using System.Reflection;
 global using Microsoft.Extensions.DependencyInjection;
 global using System.Diagnostics;
 global using System.Collections.Concurrent;
+global using System.Runtime.CompilerServices;

GFramework.Cqrs/Internal/CqrsDispatcher.cs

@@ -15,24 +15,19 @@ internal sealed class CqrsDispatcher(
     IIocContainer container,
     ILogger logger) : ICqrsRuntime
 {
-    // 进程级缓存：缓存通知调用委托，复用并发安全字典以支撑多线程发布路径。
-    private static readonly ConcurrentDictionary<Type, NotificationInvoker> NotificationInvokers = new();
+    // 卸载安全的进程级缓存：通知类型只以弱键语义保留。
+    // 若插件/热重载程序集中的通知类型被卸载，对应分发绑定会自然失效，下次命中时再重新计算。
+    private static readonly WeakKeyCache<Type, NotificationDispatchBinding>
+        NotificationDispatchBindings = new();
 
-    // 进程级缓存：缓存通知处理器服务类型，避免每次发布都重复 MakeGenericType。
-    private static readonly ConcurrentDictionary<Type, Type> NotificationHandlerServiceTypes = new();
+    // 卸载安全的进程级缓存：请求/响应类型对采用弱键缓存，避免流式消息类型被静态字典永久保留。
+    private static readonly WeakTypePairCache<StreamDispatchBinding>
+        StreamDispatchBindings = new();
 
-    // 进程级缓存：缓存流式请求调用委托，避免每次创建流时重复解析反射签名。
-    private static readonly ConcurrentDictionary<(Type RequestType, Type ResponseType), StreamInvoker> StreamInvokers =
-        new();
-
-    // 进程级缓存：缓存请求处理器与 pipeline 行为的服务类型，减少热路径中的泛型类型构造。
-    private static readonly ConcurrentDictionary<(Type RequestType, Type ResponseType), RequestServiceTypeSet>
-        RequestServiceTypes = new();
-
-    // 进程级缓存：缓存流式请求处理器服务类型，避免每次建流时重复 MakeGenericType。
-    private static readonly ConcurrentDictionary<(Type RequestType, Type ResponseType), Type>
-        StreamHandlerServiceTypes =
-            new();
+    // 卸载安全的进程级缓存：请求/响应类型对命中后复用强类型 dispatch binding；
+    // 若任一类型被回收，后续首次发送时会按当前加载状态重新生成。
+    private static readonly WeakTypePairCache<RequestDispatchBindingBox>
+        RequestDispatchBindings = new();
 
     // 静态方法定义缓存：这些反射查找与消息类型无关，只需解析一次即可复用。
     private static readonly MethodInfo RequestHandlerInvokerMethodDefinition = typeof(CqrsDispatcher)
@@ -64,10 +59,10 @@ internal sealed class CqrsDispatcher(
         ArgumentNullException.ThrowIfNull(notification);
 
         var notificationType = notification.GetType();
-        var handlerType = NotificationHandlerServiceTypes.GetOrAdd(
+        var dispatchBinding = NotificationDispatchBindings.GetOrAdd(
             notificationType,
-            static type => typeof(INotificationHandler<>).MakeGenericType(type));
-        var handlers = container.GetAll(handlerType);
+            CreateNotificationDispatchBinding);
+        var handlers = container.GetAll(dispatchBinding.HandlerType);
 
         if (handlers.Count == 0)
         {
@@ -75,14 +70,10 @@ internal sealed class CqrsDispatcher(
             return;
         }
 
-        var invoker = NotificationInvokers.GetOrAdd(
-            notificationType,
-            CreateNotificationInvoker);
-
         foreach (var handler in handlers)
         {
             PrepareHandler(handler, context);
-            await invoker(handler, notification, cancellationToken);
+            await dispatchBinding.Invoker(handler, notification, cancellationToken);
         }
     }
 
@@ -103,36 +94,21 @@ internal sealed class CqrsDispatcher(
         ArgumentNullException.ThrowIfNull(request);
 
         var requestType = request.GetType();
-        var serviceTypes = RequestServiceTypes.GetOrAdd(
-            (requestType, typeof(TResponse)),
-            static key => new RequestServiceTypeSet(
-                typeof(IRequestHandler<,>).MakeGenericType(key.RequestType, key.ResponseType),
-                typeof(IPipelineBehavior<,>).MakeGenericType(key.RequestType, key.ResponseType)));
-        var handlerType = serviceTypes.HandlerType;
-        var handler = container.Get(handlerType)
+        var dispatchBinding = GetRequestDispatchBinding<TResponse>(requestType);
+        var handler = container.Get(dispatchBinding.HandlerType)
                       ?? throw new InvalidOperationException(
                           $"No CQRS request handler registered for {requestType.FullName}.");
 
         PrepareHandler(handler, context);
-        var behaviors = container.GetAll(serviceTypes.BehaviorType);
+        var behaviors = container.GetAll(dispatchBinding.BehaviorType);
 
         foreach (var behavior in behaviors)
             PrepareHandler(behavior, context);
 
         if (behaviors.Count == 0)
-        {
-            var invoker = RequestInvokerCache<TResponse>.Invokers.GetOrAdd(
-                requestType,
-                CreateRequestInvoker<TResponse>);
+            return await dispatchBinding.RequestInvoker(handler, request, cancellationToken);
 
-            return await invoker(handler, request, cancellationToken);
-        }
-
-        var pipelineInvoker = RequestPipelineInvokerCache<TResponse>.Invokers.GetOrAdd(
-            requestType,
-            CreateRequestPipelineInvoker<TResponse>);
-
-        return await pipelineInvoker(handler, behaviors, request, cancellationToken);
+        return await dispatchBinding.PipelineInvoker(handler, behaviors, request, cancellationToken);
     }
 
     /// <summary>
@@ -152,20 +128,17 @@ internal sealed class CqrsDispatcher(
         ArgumentNullException.ThrowIfNull(request);
 
         var requestType = request.GetType();
-        var handlerType = StreamHandlerServiceTypes.GetOrAdd(
-            (requestType, typeof(TResponse)),
-            static key => typeof(IStreamRequestHandler<,>).MakeGenericType(key.RequestType, key.ResponseType));
-        var handler = container.Get(handlerType)
+        var dispatchBinding = StreamDispatchBindings.GetOrAdd(
+            requestType,
+            typeof(TResponse),
+            CreateStreamDispatchBinding);
+        var handler = container.Get(dispatchBinding.HandlerType)
                       ?? throw new InvalidOperationException(
                           $"No CQRS stream handler registered for {requestType.FullName}.");
 
         PrepareHandler(handler, context);
 
-        var invoker = StreamInvokers.GetOrAdd(
-            (requestType, typeof(TResponse)),
-            static key => CreateStreamInvoker(key.RequestType, key.ResponseType));
-
-        return (IAsyncEnumerable<TResponse>)invoker(handler, request, cancellationToken);
+        return (IAsyncEnumerable<TResponse>)dispatchBinding.Invoker(handler, request, cancellationToken);
     }
 
     /// <summary>
@@ -185,6 +158,64 @@ internal sealed class CqrsDispatcher(
         }
     }
 
+    /// <summary>
+    ///     为指定请求类型构造完整分发绑定，把服务类型与强类型调用委托一次性收敛到同一缓存项。
+    /// </summary>
+    private static RequestDispatchBinding<TResponse> CreateRequestDispatchBinding<TResponse>(Type requestType)
+    {
+        return new RequestDispatchBinding<TResponse>(
+            typeof(IRequestHandler<,>).MakeGenericType(requestType, typeof(TResponse)),
+            typeof(IPipelineBehavior<,>).MakeGenericType(requestType, typeof(TResponse)),
+            CreateRequestInvoker<TResponse>(requestType),
+            CreateRequestPipelineInvoker<TResponse>(requestType));
+    }
+
+    /// <summary>
+    ///     获取指定请求/响应类型对的 dispatch binding；若缓存未命中则按当前加载状态创建。
+    /// </summary>
+    private static RequestDispatchBinding<TResponse> GetRequestDispatchBinding<TResponse>(Type requestType)
+    {
+        var bindingBox = RequestDispatchBindings.GetOrAdd(
+            requestType,
+            typeof(TResponse),
+            CreateRequestDispatchBindingBox<TResponse>);
+        return bindingBox.Get<TResponse>();
+    }
+
+    /// <summary>
+    ///     为弱键请求缓存创建强类型 binding 盒子，避免 value-type 响应走 object 结果桥接。
+    /// </summary>
+    private static RequestDispatchBindingBox CreateRequestDispatchBindingBox<TResponse>(
+        Type requestType,
+        Type responseType)
+    {
+        if (responseType != typeof(TResponse))
+            throw new InvalidOperationException(
+                $"Request dispatch binding cache expected response type {typeof(TResponse).FullName}, but received {responseType.FullName}.");
+
+        return RequestDispatchBindingBox.Create(CreateRequestDispatchBinding<TResponse>(requestType));
+    }
+
+    /// <summary>
+    ///     为指定通知类型构造完整分发绑定，把服务类型与调用委托聚合到同一缓存项。
+    /// </summary>
+    private static NotificationDispatchBinding CreateNotificationDispatchBinding(Type notificationType)
+    {
+        return new NotificationDispatchBinding(
+            typeof(INotificationHandler<>).MakeGenericType(notificationType),
+            CreateNotificationInvoker(notificationType));
+    }
+
+    /// <summary>
+    ///     为指定流式请求类型构造完整分发绑定，把服务类型与调用委托聚合到同一缓存项。
+    /// </summary>
+    private static StreamDispatchBinding CreateStreamDispatchBinding(Type requestType, Type responseType)
+    {
+        return new StreamDispatchBinding(
+            typeof(IStreamRequestHandler<,>).MakeGenericType(requestType, responseType),
+            CreateStreamInvoker(requestType, responseType));
+    }
+
     /// <summary>
     ///     生成请求处理器调用委托，避免每次发送都重复反射。
     /// </summary>
@@ -312,22 +343,113 @@ internal sealed class CqrsDispatcher(
     private delegate object StreamInvoker(object handler, object request, CancellationToken cancellationToken);
 
     /// <summary>
-    ///     按响应类型分层缓存 request 处理器调用委托，避免 value-type 响应在 object 桥接中产生装箱。
+    ///     将不同响应类型的 request dispatch binding 包装到统一弱缓存值中，
+    ///     同时保留强类型委托，避免值类型响应退化为 object 桥接。
     /// </summary>
-    /// <typeparam name="TResponse">请求响应类型。</typeparam>
-    private static class RequestInvokerCache<TResponse>
+    private abstract class RequestDispatchBindingBox
     {
-        internal static readonly ConcurrentDictionary<Type, RequestInvoker<TResponse>> Invokers = new();
+        /// <summary>
+        ///     创建一个新的强类型 dispatch binding 盒子。
+        /// </summary>
+        public static RequestDispatchBindingBox Create<TResponse>(RequestDispatchBinding<TResponse> binding)
+        {
+            ArgumentNullException.ThrowIfNull(binding);
+            return new RequestDispatchBindingBox<TResponse>(binding);
+        }
+
+        /// <summary>
+        ///     读取指定响应类型的 request dispatch binding。
+        /// </summary>
+        public abstract RequestDispatchBinding<TResponse> Get<TResponse>();
     }
 
     /// <summary>
-    ///     按响应类型分层缓存带 pipeline 的 request 调用委托，避免 pipeline 热路径上的额外装箱。
+    ///     保存特定响应类型的 request dispatch binding。
     /// </summary>
     /// <typeparam name="TResponse">请求响应类型。</typeparam>
-    private static class RequestPipelineInvokerCache<TResponse>
+    private sealed class RequestDispatchBindingBox<TResponse>(RequestDispatchBinding<TResponse> binding)
+        : RequestDispatchBindingBox
     {
-        internal static readonly ConcurrentDictionary<Type, RequestPipelineInvoker<TResponse>> Invokers = new();
+        private readonly RequestDispatchBinding<TResponse> _binding = binding;
+
+        /// <summary>
+        ///     以原始强类型返回当前 binding；若请求的响应类型不匹配则抛出异常。
+        /// </summary>
+        public override RequestDispatchBinding<TRequestedResponse> Get<TRequestedResponse>()
+        {
+            if (typeof(TRequestedResponse) != typeof(TResponse))
+            {
+                throw new InvalidOperationException(
+                    $"Cached request dispatch binding for {typeof(TResponse).FullName} cannot be used as {typeof(TRequestedResponse).FullName}.");
+            }
+
+            return (RequestDispatchBinding<TRequestedResponse>)(object)_binding;
+        }
     }
 
-    private readonly record struct RequestServiceTypeSet(Type HandlerType, Type BehaviorType);
+    /// <summary>
+    ///     保存通知分发路径所需的服务类型与强类型调用委托。
+    ///     该绑定把“容器解析哪个服务类型”与“如何调用处理器”聚合到同一缓存项中。
+    /// </summary>
+    private sealed class NotificationDispatchBinding(Type handlerType, NotificationInvoker invoker)
+    {
+        /// <summary>
+        ///     获取通知处理器在容器中的服务类型。
+        /// </summary>
+        public Type HandlerType { get; } = handlerType;
+
+        /// <summary>
+        ///     获取执行通知处理器的强类型调用委托。
+        /// </summary>
+        public NotificationInvoker Invoker { get; } = invoker;
+    }
+
+    /// <summary>
+    ///     保存流式请求分发路径所需的服务类型与调用委托。
+    ///     该绑定让建流热路径只需一次缓存命中即可获得解析与调用所需元数据。
+    /// </summary>
+    private sealed class StreamDispatchBinding(Type handlerType, StreamInvoker invoker)
+    {
+        /// <summary>
+        ///     获取流式请求处理器在容器中的服务类型。
+        /// </summary>
+        public Type HandlerType { get; } = handlerType;
+
+        /// <summary>
+        ///     获取执行流式请求处理器的调用委托。
+        /// </summary>
+        public StreamInvoker Invoker { get; } = invoker;
+    }
+
+    /// <summary>
+    ///     保存普通请求分发路径所需的 handler 服务类型、pipeline 服务类型与强类型调用委托。
+    ///     该绑定同时覆盖“直接请求处理”和“带 pipeline 的请求处理”两条路径。
+    /// </summary>
+    /// <typeparam name="TResponse">请求响应类型。</typeparam>
+    private sealed class RequestDispatchBinding<TResponse>(
+        Type handlerType,
+        Type behaviorType,
+        RequestInvoker<TResponse> requestInvoker,
+        RequestPipelineInvoker<TResponse> pipelineInvoker)
+    {
+        /// <summary>
+        ///     获取请求处理器在容器中的服务类型。
+        /// </summary>
+        public Type HandlerType { get; } = handlerType;
+
+        /// <summary>
+        ///     获取 pipeline 行为在容器中的服务类型。
+        /// </summary>
+        public Type BehaviorType { get; } = behaviorType;
+
+        /// <summary>
+        ///     获取直接调用请求处理器的强类型委托。
+        /// </summary>
+        public RequestInvoker<TResponse> RequestInvoker { get; } = requestInvoker;
+
+        /// <summary>
+        ///     获取执行 pipeline 行为链的强类型委托。
+        /// </summary>
+        public RequestPipelineInvoker<TResponse> PipelineInvoker { get; } = pipelineInvoker;
+    }
 }

GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs

@@ -11,6 +11,20 @@ namespace GFramework.Cqrs.Internal;
 /// </summary>
 internal static class CqrsHandlerRegistrar
 {
+    // 卸载安全的进程级缓存：程序集元数据只按弱键复用。
+    // 若程序集来自 collectible AssemblyLoadContext，被回收后会重新分析，而不会被静态缓存永久钉住。
+    private static readonly WeakKeyCache<Assembly, AssemblyRegistrationMetadata> AssemblyMetadataCache =
+        new();
+
+    // 卸载安全的进程级缓存：registry 类型的构造分析可跨容器复用，但不应阻止类型卸载。
+    private static readonly WeakKeyCache<Type, RegistryActivationMetadata> RegistryActivationMetadataCache =
+        new();
+
+    // 卸载安全的进程级缓存：可加载类型列表只在程序集存活期间保留；
+    // 若程序集卸载，后续重新加载后的首次注册会重新执行 GetTypes()/恢复逻辑。
+    private static readonly WeakKeyCache<Assembly, IReadOnlyList<Type>> LoadableTypesCache =
+        new();
+
     /// <summary>
     ///     扫描指定程序集并注册所有 CQRS 请求/通知/流式处理器。
     /// </summary>
@@ -60,14 +74,10 @@ internal static class CqrsHandlerRegistrar
 
         try
         {
-            var registryTypes = assembly
-                .GetCustomAttributes(typeof(CqrsHandlerRegistryAttribute), inherit: false)
-                .OfType<CqrsHandlerRegistryAttribute>()
-                .Select(static attribute => attribute.RegistryType)
-                .Where(static type => type is not null)
-                .Distinct()
-                .OrderBy(GetTypeSortKey, StringComparer.Ordinal)
-                .ToList();
+            var assemblyMetadata = AssemblyMetadataCache.GetOrAdd(
+                assembly,
+                key => AnalyzeAssemblyRegistrationMetadata(key, logger));
+            var registryTypes = assemblyMetadata.RegistryTypes;
 
             if (registryTypes.Count == 0)
                 return GeneratedRegistrationResult.NoGeneratedRegistry();
@@ -75,27 +85,32 @@ internal static class CqrsHandlerRegistrar
             var registries = new List<ICqrsHandlerRegistry>(registryTypes.Count);
             foreach (var registryType in registryTypes)
             {
-                if (!typeof(ICqrsHandlerRegistry).IsAssignableFrom(registryType))
+                var activationMetadata = RegistryActivationMetadataCache.GetOrAdd(
+                    registryType,
+                    AnalyzeRegistryActivation);
+
+                if (!activationMetadata.ImplementsRegistryContract)
                 {
                     logger.Warn(
                         $"Ignoring generated CQRS handler registry {registryType.FullName} in assembly {assemblyName} because it does not implement {typeof(ICqrsHandlerRegistry).FullName}.");
                     return GeneratedRegistrationResult.NoGeneratedRegistry();
                 }
 
-                if (registryType.IsAbstract)
+                if (activationMetadata.IsAbstract)
                 {
                     logger.Warn(
                         $"Ignoring generated CQRS handler registry {registryType.FullName} in assembly {assemblyName} because it is abstract.");
                     return GeneratedRegistrationResult.NoGeneratedRegistry();
                 }
 
-                if (Activator.CreateInstance(registryType, nonPublic: true) is not ICqrsHandlerRegistry registry)
+                if (activationMetadata.Factory is null)
                 {
                     logger.Warn(
-                        $"Ignoring generated CQRS handler registry {registryType.FullName} in assembly {assemblyName} because it could not be instantiated.");
+                        $"Ignoring generated CQRS handler registry {registryType.FullName} in assembly {assemblyName} because it does not expose an accessible parameterless constructor.");
                     return GeneratedRegistrationResult.NoGeneratedRegistry();
                 }
 
+                var registry = activationMetadata.Factory();
                 registries.Add(registry);
             }
 
@@ -106,7 +121,7 @@ internal static class CqrsHandlerRegistrar
                 registry.Register(services, logger);
             }
 
-            var reflectionFallbackMetadata = GetReflectionFallbackMetadata(assembly, logger);
+            var reflectionFallbackMetadata = assemblyMetadata.ReflectionFallbackMetadata;
             if (reflectionFallbackMetadata is not null)
             {
                 if (reflectionFallbackMetadata.HasExplicitTypes)
@@ -259,13 +274,69 @@ internal static class CqrsHandlerRegistrar
     ///     安全获取程序集中的可加载类型，并在部分类型加载失败时保留其余处理器注册能力。
     /// </summary>
     private static IReadOnlyList<Type> GetLoadableTypes(Assembly assembly, ILogger logger)
+    {
+        return LoadableTypesCache.GetOrAdd(
+            assembly,
+            key => LoadAndSortTypes(key, logger));
+    }
+
+    /// <summary>
+    ///     分析并缓存指定程序集上的 generated-registry 与 fallback 元数据。
+    /// </summary>
+    private static AssemblyRegistrationMetadata AnalyzeAssemblyRegistrationMetadata(
+        Assembly assembly,
+        ILogger logger)
+    {
+        var registryTypes = assembly
+            .GetCustomAttributes(typeof(CqrsHandlerRegistryAttribute), inherit: false)
+            .OfType<CqrsHandlerRegistryAttribute>()
+            .Select(static attribute => attribute.RegistryType)
+            .Where(static type => type is not null)
+            .Distinct()
+            .OrderBy(GetTypeSortKey, StringComparer.Ordinal)
+            .ToArray();
+
+        var reflectionFallbackMetadata = GetReflectionFallbackMetadata(assembly, logger);
+        return new AssemblyRegistrationMetadata(registryTypes, reflectionFallbackMetadata);
+    }
+
+    /// <summary>
+    ///     分析并缓存 registry 类型的可激活性，避免每次注册都重复检查接口实现与构造函数。
+    /// </summary>
+    private static RegistryActivationMetadata AnalyzeRegistryActivation(Type registryType)
+    {
+        var implementsRegistryContract = typeof(ICqrsHandlerRegistry).IsAssignableFrom(registryType);
+        if (!implementsRegistryContract)
+            return new RegistryActivationMetadata(false, registryType.IsAbstract, null);
+
+        if (registryType.IsAbstract)
+            return new RegistryActivationMetadata(true, true, null);
+
+        var constructor = registryType.GetConstructor(
+            BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic,
+            binder: null,
+            Type.EmptyTypes,
+            modifiers: null);
+
+        return constructor is null
+            ? new RegistryActivationMetadata(true, false, null)
+            : new RegistryActivationMetadata(
+                true,
+                false,
+                () => (ICqrsHandlerRegistry)constructor.Invoke(null));
+    }
+
+    /// <summary>
+    ///     首次命中未生成 registry 的程序集时加载并排序全部可扫描类型，后续复用缓存结果。
+    /// </summary>
+    private static IReadOnlyList<Type> LoadAndSortTypes(Assembly assembly, ILogger logger)
     {
         try
         {
             return assembly.GetTypes()
                 .Where(static type => type is not null)
                 .OrderBy(GetTypeSortKey, StringComparer.Ordinal)
-                .ToList();
+                .ToArray();
         }
         catch (ReflectionTypeLoadException exception)
         {
@@ -390,4 +461,26 @@ internal static class CqrsHandlerRegistrar
 
         public bool HasExplicitTypes => Types.Count > 0;
     }
+
+    private sealed class AssemblyRegistrationMetadata(
+        IReadOnlyList<Type> registryTypes,
+        ReflectionFallbackMetadata? reflectionFallbackMetadata)
+    {
+        public IReadOnlyList<Type> RegistryTypes { get; } =
+            registryTypes ?? throw new ArgumentNullException(nameof(registryTypes));
+
+        public ReflectionFallbackMetadata? ReflectionFallbackMetadata { get; } = reflectionFallbackMetadata;
+    }
+
+    private sealed class RegistryActivationMetadata(
+        bool implementsRegistryContract,
+        bool isAbstract,
+        Func<ICqrsHandlerRegistry>? factory)
+    {
+        public bool ImplementsRegistryContract { get; } = implementsRegistryContract;
+
+        public bool IsAbstract { get; } = isAbstract;
+
+        public Func<ICqrsHandlerRegistry>? Factory { get; } = factory;
+    }
 }

GFramework.Cqrs/Internal/WeakKeyCache.cs

@@ -0,0 +1,214 @@
+namespace GFramework.Cqrs.Internal;
+
+/// <summary>
+///     提供基于弱键语义的线程安全缓存。
+///     该缓存用于跨容器复用与 <see cref="Assembly" /> 或 <see cref="Type" /> 绑定的派生元数据，
+///     同时避免静态强引用阻止 collectible 程序集或热重载类型被卸载。
+/// </summary>
+/// <typeparam name="TKey">缓存键类型。</typeparam>
+/// <typeparam name="TValue">缓存值类型。</typeparam>
+/// <remarks>
+///     该缓存只保证“命中时复用”，不保证“永久保留”。
+///     当键对象被 GC 回收后，条目会自然失效，后续访问会重新计算对应值。
+///     这是 CQRS 运行时在卸载安全与热路径性能之间的显式权衡。
+/// </remarks>
+internal sealed class WeakKeyCache<TKey, TValue>
+    where TKey : class
+    where TValue : class
+{
+    private readonly object _gate = new();
+    private ConditionalWeakTable<TKey, TValue> _entries = new();
+
+    /// <summary>
+    ///     获取指定键对应的缓存值；若当前未命中，则在锁保护下创建并写入。
+    /// </summary>
+    /// <param name="key">缓存键。</param>
+    /// <param name="valueFactory">创建缓存值的工厂方法。</param>
+    /// <returns>已存在或新创建的缓存值。</returns>
+    /// <exception cref="ArgumentNullException">
+    ///     <paramref name="key" /> 或 <paramref name="valueFactory" /> 为 <see langword="null" />。
+    ///     或 <paramref name="valueFactory" /> 返回 <see langword="null" />。
+    /// </exception>
+    public TValue GetOrAdd(TKey key, Func<TKey, TValue> valueFactory)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        ArgumentNullException.ThrowIfNull(valueFactory);
+
+        var entries = Volatile.Read(ref _entries);
+        if (entries.TryGetValue(key, out var cachedValue))
+            return cachedValue;
+
+        lock (_gate)
+        {
+            entries = _entries;
+            if (entries.TryGetValue(key, out cachedValue))
+                return cachedValue;
+
+            var createdValue = valueFactory(key);
+            ArgumentNullException.ThrowIfNull(createdValue);
+            entries.Add(key, createdValue);
+            return createdValue;
+        }
+    }
+
+    /// <summary>
+    ///     获取指定键对应的缓存值；若当前未命中，则在锁保护下使用附加状态创建并写入。
+    /// </summary>
+    /// <typeparam name="TState">创建缓存值时需要携带的附加状态类型。</typeparam>
+    /// <param name="key">缓存键。</param>
+    /// <param name="state">创建缓存值时复用的附加状态。</param>
+    /// <param name="valueFactory">基于键与附加状态创建缓存值的工厂方法。</param>
+    /// <returns>已存在或新创建的缓存值。</returns>
+    /// <exception cref="ArgumentNullException">
+    ///     <paramref name="key" /> 或 <paramref name="valueFactory" /> 为 <see langword="null" />。
+    ///     或 <paramref name="valueFactory" /> 返回 <see langword="null" />。
+    /// </exception>
+    public TValue GetOrAdd<TState>(TKey key, TState state, Func<TKey, TState, TValue> valueFactory)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        ArgumentNullException.ThrowIfNull(valueFactory);
+
+        var entries = Volatile.Read(ref _entries);
+        if (entries.TryGetValue(key, out var cachedValue))
+            return cachedValue;
+
+        lock (_gate)
+        {
+            entries = _entries;
+            if (entries.TryGetValue(key, out cachedValue))
+                return cachedValue;
+
+            var createdValue = valueFactory(key, state);
+            ArgumentNullException.ThrowIfNull(createdValue);
+            entries.Add(key, createdValue);
+            return createdValue;
+        }
+    }
+
+    /// <summary>
+    ///     尝试读取当前缓存中的值，而不触发新的创建逻辑。
+    /// </summary>
+    /// <param name="key">缓存键。</param>
+    /// <param name="value">命中时返回的缓存值。</param>
+    /// <returns>若命中当前缓存则为 <see langword="true" />；否则为 <see langword="false" />。</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="key" /> 为 <see langword="null" />。</exception>
+    public bool TryGetValue(TKey key, out TValue? value)
+    {
+        ArgumentNullException.ThrowIfNull(key);
+        return Volatile.Read(ref _entries).TryGetValue(key, out value);
+    }
+
+    /// <summary>
+    ///     清空当前缓存实例。
+    /// </summary>
+    /// <remarks>
+    ///     该方法主要服务于测试，便于在同一进程内隔离不同用例的静态缓存状态。
+    /// </remarks>
+    public void Clear()
+    {
+        lock (_gate)
+        {
+            _entries = new ConditionalWeakTable<TKey, TValue>();
+        }
+    }
+
+    /// <summary>
+    ///     返回指定键当前命中的缓存对象；若未命中则返回 <see langword="null" />。
+    /// </summary>
+    /// <param name="key">缓存键。</param>
+    /// <returns>当前缓存对象，或 <see langword="null" />。</returns>
+    /// <remarks>
+    ///     该入口仅用于测试通过反射观察缓存状态，不应用于运行时代码路径。
+    /// </remarks>
+    public TValue? GetValueOrDefaultForTesting(TKey key)
+    {
+        return TryGetValue(key, out var value) ? value : null;
+    }
+}
+
+/// <summary>
+///     提供以两段 <see cref="Type" /> 为键的弱引用缓存。
+///     适用于请求/响应或流请求/响应这类组合类型元数据的复用场景。
+/// </summary>
+/// <typeparam name="TValue">缓存值类型。</typeparam>
+/// <remarks>
+///     第一层和第二层键都使用弱键缓存，因此只要任一类型不再被外部引用，
+///     对应条目都允许被 GC 清理，并在后续首次访问时重新建立。
+/// </remarks>
+internal sealed class WeakTypePairCache<TValue>
+    where TValue : class
+{
+    private readonly WeakKeyCache<Type, WeakKeyCache<Type, TValue>> _entries = new();
+
+    /// <summary>
+    ///     获取指定类型对对应的缓存值；若未命中则创建并写入。
+    /// </summary>
+    /// <param name="primaryType">第一段类型键。</param>
+    /// <param name="secondaryType">第二段类型键。</param>
+    /// <param name="valueFactory">创建缓存值的工厂方法。</param>
+    /// <returns>已存在或新创建的缓存值。</returns>
+    /// <exception cref="ArgumentNullException">
+    ///     <paramref name="primaryType" />、<paramref name="secondaryType" /> 或
+    ///     <paramref name="valueFactory" /> 为 <see langword="null" />。
+    /// </exception>
+    public TValue GetOrAdd(Type primaryType, Type secondaryType, Func<Type, Type, TValue> valueFactory)
+    {
+        ArgumentNullException.ThrowIfNull(primaryType);
+        ArgumentNullException.ThrowIfNull(secondaryType);
+        ArgumentNullException.ThrowIfNull(valueFactory);
+
+        var secondaryEntries = _entries.GetOrAdd(primaryType, static _ => new WeakKeyCache<Type, TValue>());
+        return secondaryEntries.GetOrAdd(
+            secondaryType,
+            (PrimaryType: primaryType, Factory: valueFactory),
+            static (cachedSecondaryType, state) => state.Factory(state.PrimaryType, cachedSecondaryType));
+    }
+
+    /// <summary>
+    ///     尝试读取指定类型对的缓存值，而不触发新的创建逻辑。
+    /// </summary>
+    /// <param name="primaryType">第一段类型键。</param>
+    /// <param name="secondaryType">第二段类型键。</param>
+    /// <param name="value">命中时返回的缓存值。</param>
+    /// <returns>若命中当前缓存则为 <see langword="true" />；否则为 <see langword="false" />。</returns>
+    /// <exception cref="ArgumentNullException">
+    ///     <paramref name="primaryType" /> 或 <paramref name="secondaryType" /> 为 <see langword="null" />。
+    /// </exception>
+    public bool TryGetValue(Type primaryType, Type secondaryType, out TValue? value)
+    {
+        ArgumentNullException.ThrowIfNull(primaryType);
+        ArgumentNullException.ThrowIfNull(secondaryType);
+
+        if (_entries.TryGetValue(primaryType, out var secondaryEntries) &&
+            secondaryEntries is not null)
+            return secondaryEntries.TryGetValue(secondaryType, out value);
+
+        value = null;
+        return false;
+    }
+
+    /// <summary>
+    ///     清空当前缓存实例。
+    /// </summary>
+    /// <remarks>
+    ///     该方法主要服务于测试，避免同一进程里的静态缓存污染后续断言。
+    /// </remarks>
+    public void Clear()
+    {
+        _entries.Clear();
+    }
+
+    /// <summary>
+    ///     返回指定类型对当前命中的缓存对象；若未命中则返回 <see langword="null" />。
+    /// </summary>
+    /// <param name="primaryType">第一段类型键。</param>
+    /// <param name="secondaryType">第二段类型键。</param>
+    /// <returns>当前缓存对象，或 <see langword="null" />。</returns>
+    /// <remarks>
+    ///     该入口仅用于测试通过反射观察缓存状态，不应用于运行时代码路径。
+    /// </remarks>
+    public TValue? GetValueOrDefaultForTesting(Type primaryType, Type secondaryType)
+    {
+        return TryGetValue(primaryType, secondaryType, out var value) ? value : null;
+    }
+}

GFramework.Game.Tests/Config/ArchitectureConfigIntegrationTests.cs

@@ -325,8 +325,8 @@ public class ArchitectureConfigIntegrationTests
     }
 
     /// <summary>
-     ///     创建一个使用配置模块的模块实例。
-     /// </summary>
+    ///     创建一个使用配置模块的模块实例。
+    /// </summary>
     /// <param name="configRoot">测试配置根目录。</param>
     /// <returns>已配置的模块实例。</returns>
     private static GameConfigModule CreateModule(string configRoot)
@@ -529,7 +529,9 @@ public class ArchitectureConfigIntegrationTests
         /// </summary>
         protected override void OnInit()
         {
+#pragma warning disable GF_ContextRegistration_003
             var registry = this.GetUtility<IConfigRegistry>();
+#pragma warning restore GF_ContextRegistration_003
             var monsterTable = registry.GetMonsterTable();
 
             ObservedMonsterName = monsterTable.Get(1).Name;

README.md

@@ -25,15 +25,17 @@ GFramework 采用清晰分层与模块化设计，强调：
 
 ## 功能模块
 
-| 模块 | 说明 | 文档 |
-| --- | --- | --- |
-| `GFramework.Core` | 平台无关的核心架构能力（架构、命令、查询、事件、属性、IOC、日志等） | [查看](GFramework.Core/README.md) |
-| `GFramework.Core.Abstractions` | Core 对应的抽象接口定义 | [查看](GFramework.Core.Abstractions/README.md) |
-| `GFramework.Game` | 游戏业务侧扩展（状态、配置、存储、UI 等） | [查看](GFramework.Game/README.md) |
-| `GFramework.Game.Abstractions` | Game 模块抽象接口定义 | [查看](GFramework.Game.Abstractions/README.md) |
-| `GFramework.Godot` | Godot 集成层（节点扩展、场景/设置/存储适配等） | [查看](GFramework.Godot/README.md) |
-| `GFramework.SourceGenerators` | 通用源码生成器（日志、枚举扩展、规则等） | [查看](GFramework.SourceGenerators/README.md) |
-| `GFramework.Godot.SourceGenerators` | Godot 场景下的源码生成器扩展 | [查看](GFramework.Godot.SourceGenerators/README.md) |
+| 模块                                                                      | 说明                                      | 文档                                                |
+|-------------------------------------------------------------------------|-----------------------------------------|---------------------------------------------------|
+| `GFramework.Core`                                                       | 平台无关的核心架构能力（架构、命令、查询、事件、属性、IOC、日志等）     | [查看](GFramework.Core/README.md)                   |
+| `GFramework.Core.Abstractions`                                          | Core 对应的抽象接口定义                          | [查看](GFramework.Core.Abstractions/README.md)      |
+| `GFramework.Game`                                                       | 游戏业务侧扩展（状态、配置、存储、UI 等）                  | [查看](GFramework.Game/README.md)                   |
+| `GFramework.Game.Abstractions`                                          | Game 模块抽象接口定义                           | [查看](GFramework.Game.Abstractions/README.md)      |
+| `GFramework.Godot`                                                      | Godot 集成层（节点扩展、场景/设置/存储适配等）             | [查看](GFramework.Godot/README.md)                  |
+| `GFramework.Cqrs` / `GFramework.Cqrs.Abstractions`                      | CQRS runtime、契约与 handler 注册基础设施         | [查看](docs/zh-CN/core/cqrs.md)                     |
+| `GFramework.Core.SourceGenerators`                                      | Core 侧源码生成器（日志、枚举扩展、规则、模块注册等）           | [查看](GFramework.Core.SourceGenerators/README.md)  |
+| `GFramework.Game.SourceGenerators` / `GFramework.Cqrs.SourceGenerators` | 游戏配置 schema 与 CQRS handler registry 生成器 | [查看](docs/zh-CN/source-generators/index.md)       |
+| `GFramework.Godot.SourceGenerators`                                     | Godot 场景下的源码生成器扩展                       | [查看](GFramework.Godot.SourceGenerators/README.md) |
 
 ## 文档导航
 
@@ -50,7 +52,7 @@ GFramework 采用清晰分层与模块化设计，强调：
 - **`GeWuYou.GFramework`**：聚合元包（Meta Package），用于一键引入常用能力集合，适合快速试用或原型阶段。
 - **`GeWuYou.GFramework.Core`**：核心起步包，适合希望按模块精细控制依赖的项目（推荐生产项目从此起步）。
 
-如果你已明确技术栈，建议优先按模块安装（Core / Game / Godot / SourceGenerators），避免不必要依赖。
+如果你已明确技术栈，建议优先按模块安装（Core / Cqrs / Game / Godot / Source Generators），避免不必要依赖。
 
 ## 快速安装
 
@@ -61,6 +63,10 @@ GFramework 采用清晰分层与模块化设计，强调：
 dotnet add package GeWuYou.GFramework.Core
 dotnet add package GeWuYou.GFramework.Core.Abstractions
 
+# CQRS
+dotnet add package GeWuYou.GFramework.Cqrs
+dotnet add package GeWuYou.GFramework.Cqrs.Abstractions
+
 # 游戏扩展
 dotnet add package GeWuYou.GFramework.Game
 dotnet add package GeWuYou.GFramework.Game.Abstractions
@@ -105,13 +111,19 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
 
 ```text
 GFramework.sln
+├─ GFramework.Cqrs/
+├─ GFramework.Cqrs.Abstractions/
 ├─ GFramework.Core/
 ├─ GFramework.Core.Abstractions/
+├─ GFramework.Core.SourceGenerators/
+├─ GFramework.Core.SourceGenerators.Abstractions/
 ├─ GFramework.Game/
 ├─ GFramework.Game.Abstractions/
+├─ GFramework.Game.SourceGenerators/
 ├─ GFramework.Godot/
-├─ GFramework.SourceGenerators/
 ├─ GFramework.Godot.SourceGenerators/
+├─ GFramework.Cqrs.SourceGenerators/
+├─ GFramework.SourceGenerators.Common/
 ├─ docs/
 └─ docfx/
 ```

docs/zh-CN/core/cqrs.md

@@ -21,6 +21,18 @@ CQRS（Command Query Responsibility Segregation，命令查询职责分离）是
 - 与架构系统深度集成
 - 支持流式处理
 
+## 接入包
+
+按模块安装 CQRS runtime；如果希望在编译期生成 handler 注册表，再额外安装对应的 source generator：
+
+```bash
+dotnet add package GeWuYou.GFramework.Cqrs
+dotnet add package GeWuYou.GFramework.Cqrs.Abstractions
+
+# 可选：编译期生成 handler registry，减少冷启动反射扫描
+dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
+```
+
 ## 核心概念
 
 ### Command（命令）
@@ -28,8 +40,8 @@ CQRS（Command Query Responsibility Segregation，命令查询职责分离）是
 命令表示修改系统状态的操作，如创建、更新、删除：
 
 ```csharp
-using GFramework.Core.CQRS.Command;
-using GFramework.Core.Abstractions.CQRS.Command;
+using GFramework.Cqrs.Command;
+using GFramework.Cqrs.Abstractions.Cqrs.Command;
 
 // 定义命令输入
 public class CreatePlayerInput : ICommandInput
@@ -50,8 +62,8 @@ public class CreatePlayerCommand : CommandBase<CreatePlayerInput, int>
 查询表示读取系统状态的操作，不修改数据：
 
 ```csharp
-using GFramework.Core.CQRS.Query;
-using GFramework.Core.Abstractions.CQRS.Query;
+using GFramework.Cqrs.Query;
+using GFramework.Cqrs.Abstractions.Cqrs.Query;
 
 // 定义查询输入
 public class GetPlayerInput : IQueryInput
@@ -71,7 +83,8 @@ public class GetPlayerQuery : QueryBase<GetPlayerInput, PlayerData>
 处理器负责执行命令或查询的具体逻辑：
 
 ```csharp
-using GFramework.Core.CQRS.Command;
+using GFramework.Cqrs.Command;
+using GFramework.Cqrs.Cqrs.Command;
 
 // 命令处理器
 public class CreatePlayerCommandHandler : AbstractCommandHandler<CreatePlayerCommand, int>
@@ -91,6 +104,9 @@ public class CreatePlayerCommandHandler : AbstractCommandHandler<CreatePlayerCom
 }
 ```
 
+> 说明：消息基类位于 `GFramework.Cqrs.Command` / `Query` / `Notification` 命名空间，而处理器基类位于
+> `GFramework.Cqrs.Cqrs.*` 命名空间。编写最小示例时需要同时引用对应的消息与 handler 命名空间。
+
 ### Dispatcher（请求分发器）
 
 架构上下文会负责将命令、查询和通知路由到对应的处理器：
@@ -247,8 +263,8 @@ public class GameArchitecture : Architecture
 handler。
 
 `RegisterCqrsPipelineBehavior<TBehavior>()` 是唯一保留的公开入口；旧的 `Mediator` 兼容别名与扩展已移除，不再继续维护。
-如果你正在从旧版本迁移，显式替换关系就是
-`RegisterMediatorBehavior<TBehavior>() -> RegisterCqrsPipelineBehavior<TBehavior>()`。
+如果你正在从旧版本迁移，只需要直接改用 `RegisterCqrsPipelineBehavior<TBehavior>()`；
+旧 `RegisterMediatorBehavior<TBehavior>()` 已移除，不再保留兼容入口。
 当前接口支持两种形式：
 
 - 开放泛型行为，例如 `LoggingBehavior<,>`，用于匹配所有请求
@@ -261,8 +277,8 @@ handler。
 Request 是更通用的消息类型，可以用于任何场景：
 
 ```csharp
-using GFramework.Core.CQRS.Request;
-using GFramework.Core.Abstractions.CQRS.Request;
+using GFramework.Cqrs.Request;
+using GFramework.Cqrs.Abstractions.Cqrs.Request;
 
 // 定义请求输入
 public class ValidatePlayerInput : IRequestInput
@@ -299,8 +315,8 @@ public class ValidatePlayerRequestHandler : AbstractRequestHandler<ValidatePlaye
 Notification 用于一对多的消息广播：
 
 ```csharp
-using GFramework.Core.CQRS.Notification;
-using GFramework.Core.Abstractions.CQRS.Notification;
+using GFramework.Cqrs.Notification;
+using GFramework.Cqrs.Abstractions.Cqrs.Notification;
 
 // 定义通知输入
 public class PlayerLevelUpInput : INotificationInput

docs/zh-CN/getting-started/installation.md

@@ -6,16 +6,18 @@ GFramework 提供多种安装方式，您可以根据项目需求选择合适的
 
 GFramework 采用模块化设计，不同包提供不同的功能：
 
-| 包名                                          | 说明          | 适用场景                           |
-|---------------------------------------------|-------------|--------------------------------|
-| `GeWuYou.GFramework`                        | 聚合元包        | 快速试用、原型开发                      |
-| `GeWuYou.GFramework.Core`                   | 核心框架        | 生产项目推荐                         |
-| `GeWuYou.GFramework.Game`                   | 游戏模块        | 需要游戏特定功能                       |
-| `GeWuYou.GFramework.Godot`                  | Godot集成     | Godot项目必需                      |
-| `GeWuYou.GFramework.Core.SourceGenerators`  | Core 源码生成器  | `[Log]`、`[ContextAware]`、架构注入等 |
-| `GeWuYou.GFramework.Game.SourceGenerators`  | Game 源码生成器  | 配置 schema / 配表生成               |
-| `GeWuYou.GFramework.Godot.SourceGenerators` | Godot 源码生成器 | Godot 节点、UI、项目元数据生成            |
-| `GeWuYou.GFramework.Cqrs.SourceGenerators`  | CQRS 源码生成器  | 处理器注册表生成                       |
+| 包名                                          | 说明           | 适用场景                           |
+|---------------------------------------------|--------------|--------------------------------|
+| `GeWuYou.GFramework`                        | 聚合元包         | 快速试用、原型开发                      |
+| `GeWuYou.GFramework.Core`                   | 核心框架         | 生产项目推荐                         |
+| `GeWuYou.GFramework.Cqrs`                   | CQRS runtime | 命令/查询/通知分发与处理器注册               |
+| `GeWuYou.GFramework.Cqrs.Abstractions`      | CQRS 抽象契约    | CQRS 契约、handler 接口与共享抽象        |
+| `GeWuYou.GFramework.Game`                   | 游戏模块         | 需要游戏特定功能                       |
+| `GeWuYou.GFramework.Godot`                  | Godot集成      | Godot项目必需                      |
+| `GeWuYou.GFramework.Core.SourceGenerators`  | Core 源码生成器   | `[Log]`、`[ContextAware]`、架构注入等 |
+| `GeWuYou.GFramework.Game.SourceGenerators`  | Game 源码生成器   | 配置 schema / 配表生成               |
+| `GeWuYou.GFramework.Godot.SourceGenerators` | Godot 源码生成器  | Godot 节点、UI、项目元数据生成            |
+| `GeWuYou.GFramework.Cqrs.SourceGenerators`  | CQRS 源码生成器   | 处理器注册表生成                       |
 
 当前 NuGet 发布按模块拆分 source generator 包，不存在 `GeWuYou.GFramework.SourceGenerators` 聚合包。
 
@@ -28,6 +30,10 @@ GFramework 采用模块化设计，不同包提供不同的功能：
 dotnet add package GeWuYou.GFramework.Core
 dotnet add package GeWuYou.GFramework.Core.Abstractions
 
+# CQRS runtime
+dotnet add package GeWuYou.GFramework.Cqrs
+dotnet add package GeWuYou.GFramework.Cqrs.Abstractions
+
 # 游戏扩展
 dotnet add package GeWuYou.GFramework.Game
 dotnet add package GeWuYou.GFramework.Game.Abstractions
@@ -62,6 +68,10 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
     <!-- 核心框架 -->
     <PackageReference Include="GeWuYou.GFramework.Core" Version="1.0.0" />
     <PackageReference Include="GeWuYou.GFramework.Core.Abstractions" Version="1.0.0" />
+
+    <!-- CQRS runtime -->
+    <PackageReference Include="GeWuYou.GFramework.Cqrs" Version="1.0.0" />
+    <PackageReference Include="GeWuYou.GFramework.Cqrs.Abstractions" Version="1.0.0" />
     
     <!-- 游戏模块 -->
     <PackageReference Include="GeWuYou.GFramework.Game" Version="1.0.0" />
@@ -154,12 +164,14 @@ dotnet add package GeWuYou.GFramework.Cqrs.SourceGenerators
 创建一个简单的测试来验证安装是否成功：
 
 ```csharp
-using GFramework.Core.Architecture;
+using GFramework.Core.Architectures;
+using GFramework.Core.Model;
+using GFramework.Core.Property;
 
 // 定义简单的架构
 public class TestArchitecture : Architecture
 {
-    protected override void Init()
+    protected override void OnInitialize()
     {
         // 注册一个简单的模型
         RegisterModel(new TestModel());
@@ -169,6 +181,10 @@ public class TestArchitecture : Architecture
 public class TestModel : AbstractModel
 {
     public BindableProperty<string> Message { get; } = new("Hello GFramework!");
+
+    protected override void OnInit()
+    {
+    }
 }
 
 // 测试代码

docs/zh-CN/source-generators/index.md

@@ -1,8 +1,8 @@
-# GFramework.SourceGenerators
+# Source Generators
 
 > 编译时代码生成 - 零运行时开销的代码增强工具
 
-GFramework.SourceGenerators 是 GFramework 框架的源代码生成器包，通过编译时分析自动生成样板代码，显著提升开发效率并减少运行时开销。
+GFramework 当前按模块提供一组 Source Generators，通过编译时分析自动生成样板代码，显著提升开发效率并减少运行时开销。
 
 ## 📋 目录
 
@@ -11,6 +11,7 @@ GFramework.SourceGenerators 是 GFramework 框架的源代码生成器包，通
 - [安装配置](#安装配置)
 - [Log 属性生成器](#log-属性生成器)
 - [Config Schema 生成器](#config-schema-生成器)
+- [CQRS Handler Registry 生成器](#cqrs-handler-registry-生成器)
 - [ContextAware 属性生成器](#contextaware-属性生成器)
 - [GenerateEnumExtensions 属性生成器](#generateenumextensions-属性生成器)
 - [Priority 属性生成器](#priority-属性生成器)
@@ -30,7 +31,7 @@ GFramework.SourceGenerators 是 GFramework 框架的源代码生成器包，通
 
 ## 概述
 
-GFramework 的 source generators 利用 Roslyn 源代码生成器技术，在编译时分析你的代码并自动生成常用的样板代码，让开发者专注于业务逻辑而不是重复的模板代码。
+GFramework 的 Source Generators 利用 Roslyn 源代码生成器技术，在编译时分析你的代码并自动生成常用的样板代码，让开发者专注于业务逻辑而不是重复的模板代码。
 
 当前 NuGet 发布按模块拆分为：
 
@@ -54,6 +55,7 @@ GFramework 的 source generators 利用 Roslyn 源代码生成器技术，在编
 
 - **[Log] 属性**：自动生成 ILogger 字段和日志方法
 - **Config Schema 生成器**：根据 `*.schema.json` 生成配置类型和表包装
+- **CQRS Handler Registry 生成器**：为 CQRS handlers 生成程序集级注册表并缩小运行时反射范围
 - **[ContextAware] 属性**：自动实现 IContextAware 接口
 - **[GenerateEnumExtensions] 属性**：自动生成枚举扩展方法
 - **[Priority] 属性**：自动实现 IPrioritized 接口，为类添加优先级标记
@@ -161,6 +163,70 @@ Config Schema 生成器会扫描 `*.schema.json` 文件，并生成：
 </Project>
 ```
 
+## CQRS Handler Registry 生成器
+
+`GeWuYou.GFramework.Cqrs.SourceGenerators` 会在编译期分析当前业务程序集中的 CQRS handlers，并生成：
+
+- `ICqrsHandlerRegistry` 实现，用于在启动时直接注册可安全引用的 handlers
+- 程序集级 `CqrsHandlerRegistryAttribute` 元数据，供运行时优先走生成注册路径
+- 必要时的 `CqrsReflectionFallbackAttribute`，让运行时只补扫生成代码无法合法引用的 handlers
+
+### 接入包
+
+如果你的项目已经使用 GFramework 架构层，请在现有 Core 依赖基础上补齐 CQRS runtime 与 generator：
+
+```xml
+<ItemGroup>
+    <PackageReference Include="GeWuYou.GFramework.Cqrs" Version="1.0.0" />
+    <PackageReference Include="GeWuYou.GFramework.Cqrs.Abstractions" Version="1.0.0" />
+    <PackageReference Include="GeWuYou.GFramework.Cqrs.SourceGenerators"
+                      Version="1.0.0"
+                      PrivateAssets="all"
+                      ExcludeAssets="runtime" />
+</ItemGroup>
+```
+
+如果当前项目还没有接入架构运行时，请同时保持 `GeWuYou.GFramework.Core` /
+`GeWuYou.GFramework.Core.Abstractions` 与 CQRS 包版本一致。
+
+### 最小示例
+
+下面的最小示例展示了“安装 runtime + source generator 后，正常注册程序集”的接入方式。运行时会优先使用生成的
+handler registry；如果某个 handler 无法被生成代码直接引用，则自动补走定向反射回退。
+
+```csharp
+using GFramework.Core.Architectures;
+using GFramework.Cqrs.Abstractions.Cqrs.Command;
+using GFramework.Cqrs.Cqrs.Command;
+
+public sealed record CreatePlayerCommand(string Name) : ICommand<int>;
+
+public sealed class CreatePlayerCommandHandler : AbstractCommandHandler<CreatePlayerCommand, int>
+{
+    public override ValueTask<int> Handle(CreatePlayerCommand command, CancellationToken cancellationToken)
+    {
+        return ValueTask.FromResult(command.Name.Length);
+    }
+}
+
+public sealed class GameArchitecture : Architecture
+{
+    protected override void OnInitialize()
+    {
+        RegisterCqrsHandlersFromAssembly(typeof(GameArchitecture).Assembly);
+    }
+}
+```
+
+### 兼容性与迁移说明
+
+- 不安装 `GeWuYou.GFramework.Cqrs.SourceGenerators` 也可以正常运行；此时 CQRS runtime 会继续使用反射扫描注册
+  handlers。
+- 安装生成器后，不需要额外改写 `RegisterCqrsHandlersFromAssembly(...)` /
+  `RegisterCqrsHandlersFromAssemblies(...)` 调用点；运行时会自动优先使用生成注册表。
+- CQRS 消息基类位于 `GFramework.Cqrs.Command` / `Query` / `Notification`，而处理器基类位于
+  `GFramework.Cqrs.Cqrs.*` 命名空间。文档示例需要分别引用两组命名空间。
+
 ## Log 属性生成器
 
 [Log] 属性自动为标记的类生成日志记录功能，包括 ILogger 字段和便捷的日志方法。
@@ -693,7 +759,7 @@ public partial class GameEntryPoint : Node
 
 ## 诊断信息
 
-GFramework.SourceGenerators 提供详细的编译时诊断信息，帮助开发者快速定位和解决问题。
+这一组 Source Generators 提供详细的编译时诊断信息，帮助开发者快速定位和解决问题。
 
 ### GF_Logging_001 - 日志字段名冲突