diff --git a/GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.Models.cs b/GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.Models.cs
index 0b3ec0c7..541ffcf6 100644
--- a/GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.Models.cs
+++ b/GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.Models.cs
@@ -32,6 +32,13 @@ public sealed partial class CqrsHandlerRegistryGenerator
             HasReflectionTypeLookups;
     }
 
+    /// <summary>
+    ///     标记某条 handler 注册语句在生成阶段采用的表达策略。
+    /// </summary>
+    /// <remarks>
+    ///     该枚举只服务于输出排序与代码分支选择，用来保证生成注册器在“直接注册”
+    ///     “反射实现类型查找”和“精确运行时类型解析”之间保持稳定顺序。
+    /// </remarks>
     private enum OrderedRegistrationKind
     {
         Direct,
@@ -39,6 +46,14 @@ public sealed partial class CqrsHandlerRegistryGenerator
         PreciseReflected
     }
 
+    /// <summary>
+    ///     描述生成注册器中某个运行时类型引用的构造方式。
+    /// </summary>
+    /// <remarks>
+    ///     某些 handler 服务类型可以直接以 <c>typeof(...)</c> 输出，某些则需要在运行时补充
+    ///     反射查找、数组封装或泛型实参重建。该记录把这些差异收敛为统一的递归结构，
+    ///     供源码输出阶段生成稳定的类型解析语句。
+    /// </remarks>
     private sealed record RuntimeTypeReferenceSpec(
         string? TypeDisplayName,
         string? ReflectionTypeMetadataName,
@@ -49,6 +64,9 @@ public sealed partial class CqrsHandlerRegistryGenerator
         RuntimeTypeReferenceSpec? GenericTypeDefinitionReference,
         ImmutableArray<RuntimeTypeReferenceSpec> GenericTypeArguments)
     {
+        /// <summary>
+        ///     创建一个可直接通过 <c>typeof(...)</c> 表达的类型引用。
+        /// </summary>
         public static RuntimeTypeReferenceSpec FromDirectReference(string typeDisplayName)
         {
             return new RuntimeTypeReferenceSpec(
@@ -62,6 +80,9 @@ public sealed partial class CqrsHandlerRegistryGenerator
                 ImmutableArray<RuntimeTypeReferenceSpec>.Empty);
         }
 
+        /// <summary>
+        ///     创建一个需要从当前消费端程序集反射解析的类型引用。
+        /// </summary>
         public static RuntimeTypeReferenceSpec FromReflectionLookup(string reflectionTypeMetadataName)
         {
             return new RuntimeTypeReferenceSpec(
@@ -75,6 +96,9 @@ public sealed partial class CqrsHandlerRegistryGenerator
                 ImmutableArray<RuntimeTypeReferenceSpec>.Empty);
         }
 
+        /// <summary>
+        ///     创建一个需要从被引用程序集反射解析的类型引用。
+        /// </summary>
         public static RuntimeTypeReferenceSpec FromExternalReflectionLookup(
             string reflectionAssemblyName,
             string reflectionTypeMetadataName)
@@ -90,6 +114,9 @@ public sealed partial class CqrsHandlerRegistryGenerator
                 ImmutableArray<RuntimeTypeReferenceSpec>.Empty);
         }
 
+        /// <summary>
+        ///     创建一个数组类型引用。
+        /// </summary>
         public static RuntimeTypeReferenceSpec FromArray(RuntimeTypeReferenceSpec elementTypeReference, int arrayRank)
         {
             return new RuntimeTypeReferenceSpec(
@@ -103,6 +130,9 @@ public sealed partial class CqrsHandlerRegistryGenerator
                 ImmutableArray<RuntimeTypeReferenceSpec>.Empty);
         }
 
+        /// <summary>
+        ///     创建一个封闭泛型类型引用。
+        /// </summary>
         public static RuntimeTypeReferenceSpec FromConstructedGeneric(
             RuntimeTypeReferenceSpec genericTypeDefinitionReference,
             ImmutableArray<RuntimeTypeReferenceSpec> genericTypeArguments)
diff --git a/ai-plan/public/analyzer-warning-reduction/todos/analyzer-warning-reduction-tracking.md b/ai-plan/public/analyzer-warning-reduction/todos/analyzer-warning-reduction-tracking.md
index a6587ab1..bc42ecc2 100644
--- a/ai-plan/public/analyzer-warning-reduction/todos/analyzer-warning-reduction-tracking.md
+++ b/ai-plan/public/analyzer-warning-reduction/todos/analyzer-warning-reduction-tracking.md
@@ -7,8 +7,8 @@
 
 ## 当前恢复点
 
-- 恢复点编号：`ANALYZER-WARNING-REDUCTION-RP-027`
-- 当前阶段：`Phase 27`
+- 恢复点编号：`ANALYZER-WARNING-REDUCTION-RP-028`
+- 当前阶段：`Phase 28`
 - 当前焦点：
   - 已完成 `GFramework.Core` 当前 `MA0016` / `MA0002` / `MA0015` / `MA0077` 低风险收口批次
   - 已复核 `net10.0` 下的 `MA0158` 基线：`GFramework.Core` / `GFramework.Cqrs` 当前共有 `16` 个 object lock
@@ -35,6 +35,9 @@
     reference metadata 成员名全局去冲突，但不再依赖现已被 `GF_ConfigSchema_014` 拦截的非法同层 schema key 冲突
   - 已完成当前 PR #269 Greptile follow-up：`ContextAwareGenerator` 现在会把基类链显式成员名也纳入
     `_gFrameworkContextAware*` 字段分配冲突检测，并新增 inherited-field collision 快照回归测试
+  - 已完成当前分支与 `main` 的 `CqrsHandlerRegistryGenerator.cs` 文件级冲突收口：确认 `main` 侧新增的是
+    `OrderedRegistrationKind` / `RuntimeTypeReferenceSpec` 的 XML 文档，现已按当前 partial 拆分结构迁移到
+    `CqrsHandlerRegistryGenerator.Models.cs`，不回退已完成的生成器拆分
   - 已更新 `AGENTS.md`：变更模块必须运行对应 `dotnet build -c Release`，并处理或显式报告模块构建 warning，
     不再默认留给长期 warning 清理分支
   - `CoroutineScheduler` 的 tag/group 字典已显式使用 `StringComparer.Ordinal`，保持既有区分大小写语义
@@ -79,6 +82,8 @@
   并重新通过定向 generator test
 - 已完成当前 PR #269 的 Greptile follow-up：修复 `ContextAwareGenerator` 未覆盖基类成员名冲突的问题，并补齐
   inherited-collision 快照测试
+- 已完成当前分支与 `main` 的 `CqrsHandlerRegistryGenerator.cs` 冲突化解：保留当前 partial 结构，并把
+  `main` 侧新增的模型文档合并到 `CqrsHandlerRegistryGenerator.Models.cs`
 - 已完成 `GFramework.Game.SourceGenerators` 中 `SchemaConfigGenerator` 的第一批 `MA0051` 收口；warnings-only 基线剩余 `9` 条
   `MA0051`
 
diff --git a/ai-plan/public/analyzer-warning-reduction/traces/analyzer-warning-reduction-trace.md b/ai-plan/public/analyzer-warning-reduction/traces/analyzer-warning-reduction-trace.md
index 4706a318..ca74deca 100644
--- a/ai-plan/public/analyzer-warning-reduction/traces/analyzer-warning-reduction-trace.md
+++ b/ai-plan/public/analyzer-warning-reduction/traces/analyzer-warning-reduction-trace.md
@@ -1,5 +1,30 @@
 # Analyzer Warning Reduction 追踪
 
+## 2026-04-23 — RP-028
+
+### 阶段：`CqrsHandlerRegistryGenerator.cs` 文件级冲突化解（RP-028）
+
+- 启动复核：
+  - 用户指出当前分支与 `main` 在 `GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs`
+    存在冲突，需要人工确认并解决
+  - 本地检查后确认工作树没有 `UU` 或冲突标记；进一步对比 `origin/main` 发现冲突根因不是运行逻辑回退，而是
+    `main` 在旧的单文件版本里新增了 `OrderedRegistrationKind` / `RuntimeTypeReferenceSpec` 的 XML 文档，
+    而当前分支已将这些类型拆分到 `CqrsHandlerRegistryGenerator.Models.cs`
+- 决策：
+  - 保留当前分支已经完成的 partial 拆分，不把模型重新塞回 `CqrsHandlerRegistryGenerator.cs`
+  - 以“迁移 `main` 侧文档意图到拆分后的归属文件”为人工合并策略，避免既回退结构拆分又遗漏 `main` 新增文档
+- 实施调整：
+  - 将 `OrderedRegistrationKind` 的枚举说明与 `RuntimeTypeReferenceSpec` / `FromDirectReference` /
+    `FromReflectionLookup` / `FromExternalReflectionLookup` / `FromArray` / `FromConstructedGeneric`
+    的 XML 文档迁移到 `CqrsHandlerRegistryGenerator.Models.cs`
+  - 保持 `CqrsHandlerRegistryGenerator.cs` 主文件只承载主生成管线，不引入重复模型定义
+- 验证结果：
+  - `dotnet build GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj -c Release --no-restore -p:RestoreFallbackFolders="" -clp:"Summary;WarningsOnly" -nologo`
+    - 结果：`0 Warning(s)`，`0 Error(s)`
+- 下一步建议：
+  - 若后续继续处理分支冲突，优先先判断 `main` 改动是否已在当前 partial 文件集里存在等价归属，再决定是否需要真正 merge/rebase
+  - 若回到 PR #269 收口，可继续抓取最新 unresolved threads 与 CI 状态
+
 ## 2026-04-23 — RP-027
 
 ### 阶段：PR #269 Greptile inherited-member collision follow-up（RP-027）