多轮审查和修复

2026-05-12 15:34:08 +08:00
parent f55d2a57c3
commit ebbbb7332e
805 changed files with 838724 additions and 1905 deletions
--- a/Docs/Review/MasterReview_2025_PostFix.md
+++ b/Docs/Review/MasterReview_2025_PostFix.md
@@ -0,0 +1,560 @@
+# zeling_v2 代码综合评审（Post-Fix 终态）
+
+> **评审日期**：2025-05-11  
+> **评审范围**：`Assets/Scripts/` 全部模块（约 270 个 .cs 文件，25 个 Assembly Definition）  
+> **评审标准**：以《空洞骑士》《Celeste》《Neon Abyss》等成熟商业 2D 动作游戏的代码架构与质量水准为参照  
+> **状态说明**：本文档反映经历两轮全面优化（MasterCodeReview.md × 3 P0/P1/P2 + FullCodeReview.md × 18 项）后的**当前终态**代码；已修复问题不再列入缺陷表，仅记录剩余未解决项及综合评估。
+
+---
+
+## 目录
+
+1. [评分总览](#1-评分总览)
+2. [架构设计](#2-架构设计)
+3. [性能](#3-性能)
+4. [可扩展性](#4-可扩展性)
+5. [编辑器友好性](#5-编辑器友好性)
+6. [使用便利性 DX](#6-使用便利性-dx)
+7. [剩余问题优先级表](#7-剩余问题优先级表)
+8. [与商业基准的对标分析](#8-与商业基准的对标分析)
+9. [下一阶段建议](#9-下一阶段建议)
+
+---
+
+## 1. 评分总览
+
+| 维度 | 本次得分（/10） | 上轮得分 | 变化 | 主要驱动因素 |
+|------|---------------|----------|------|------------|
+| **架构设计** | **8.0** | 7.5 | ▲ 0.5 | SerializeField 减少、SaveManager.Data 移除、EnemyDied 类型修正 |
+| **性能** | **7.8** | 7.0 | ▲ 0.8 | Pool 统一 async、批量 LOS 节流、StatusEffect 双结构 |
+| **可扩展性** | **8.2** | 7.5 | ▲ 0.7 | WorldStateRegistry 泛化、AddressKeyRegistry DLC 扩展、SaveMigrator 版本链 |
+| **编辑器友好性** | **7.8** | 6.5 | ▲ 1.3 | SOValidationRunner 构建钩子、多个自定义 EditorWindow |
+| **使用便利性** | **8.1** | 7.0 | ▲ 1.1 | EventSubscription RAII、PlayerStateBase 便捷属性、具名存档访问器 |
+| **综合** | **8.0** | 7.1 | ▲ 0.9 | 全面提升，接近《Neon Abyss》量级商业质量 |
+
+> **评分说明**：满分 10 = 顶级 AA 商业代码（《空洞骑士》级别）；8.0 ≈ 功能完善的商业独立游戏中上水准（如 _Neon Abyss_、_Haiku the Robot_）。
+
+---
+
+## 2. 架构设计
+
+### 2.1 SO Event Channel 系统 ✅ 强
+
+`BaseEventChannelSO<T>` 泛型事件基类实现完整，超过大多数独立参考实现：
+
+```csharp
+// BaseEventChannelSO.cs — 核心设计
+private event Action<T> _onEventRaisedBacking;   // 防止外部 = 赋值
+public EventSubscription Subscribe(Action<T> callback)
+{
+    OnEventRaised += callback;
+    return new EventSubscription(() => OnEventRaised -= callback);
+}
+public void Raise(T value)
+{
+#if UNITY_EDITOR
+    EventBusMonitor.Record(name, value?.ToString() ?? "null", _subscriberCount, Time.frameCount);
+#endif
+    _onEventRaisedBacking?.Invoke(value);
+}
+```
+
+**亮点：**
+- 私有 backing field + public event 属性，防止意外的 `=` 覆盖
+- `EventSubscription` RAII 句柄 + `CompositeDisposable`，与 UniRx 风格一致，订阅生命周期零泄漏风险
+- Editor-only `_subscriberCount` + `EventBusMonitor` 256 条环形日志，帧号/载荷/监听器数量齐全
+- 35+ 具体频道覆盖全模块（`BossPhaseEventChannelSO`、`ShopPurchaseEventChannelSO`、`ParryInfoEventChannelSO` 等），系统间完全解耦
+
+**商业对比**：达到 GDC 2017 Unite Austin 推荐的 SO 架构完整落地水准；`CompositeDisposable.AddTo()` 扩展方法在开源 Unity 项目中属于高完整度实现。
+
+---
+
+### 2.2 Assembly Definition 拓扑 ✅ 强
+
+25 个 asmdef 形成明确的单向依赖链：
+
+```
+BaseGames.Core.Events
+    ↓
+BaseGames.Core
+    ↓          ↓          ↓
+BaseGames.Combat  BaseGames.Parry  BaseGames.Player
+    ↓                               ↓
+BaseGames.Enemies          BaseGames.Player.States
+    ↓
+BaseGames.Quest / Progression / World
+```
+
+- 循环依赖为零，编译期隔离各模块
+- `IPathAgent` 接口位于 `BaseGames.Enemies`，`EnemyNavAgent` 实现位于 `BaseGames.Enemies.Navigation`，运行时依赖倒置
+- 测试/替换某模块不影响其他层，支持后续按需热重载或 DLC 接入
+
+---
+
+### 2.3 ServiceLocator ✅ 强
+
+```csharp
+// ServiceLocator.cs — 接口类型键，支持测试覆盖
+public static void Register<TInterface>(TInterface impl)
+    => _services[typeof(TInterface)] = impl;
+public static void RegisterIfAbsent<TInterface>(TInterface impl) { ... }
+public static TInterface GetOrDefault<TInterface>(TInterface fallback = default) { ... }
+#if UNITY_EDITOR
+public static void OverrideForTest<TInterface>(TInterface mock) { ... }
+public static void Reset() => _services.Clear();
+#endif
+```
+
+`RegisterIfAbsent` 幂等注册有效解决多场景重复注册问题；`OverrideForTest` Editor-only 沙箱支持单元测试替换，不污染 Release 构建。
+
+---
+
+### 2.4 玩家 FSM ✅ 强
+
+```csharp
+// PlayerController.cs — POCO 状态 + Type-keyed Dictionary
+private readonly Dictionary<Type, PlayerStateBase> _states = new();
+public T GetState<T>() where T : PlayerStateBase
+    => _states.TryGetValue(typeof(T), out var s) ? s as T : null;
+```
+
+16 个具体状态类（Idle/Run/Jump/Fall/Dash/AerialDash/Parry/Hurt/Dead/Attack×4 等）：
+- 全部 POCO（非 MonoBehaviour），零堆内存分配的状态切换
+- `Dictionary<Type, PlayerStateBase>` O(1) 查找，无 switch/if-else 链
+- `PlayerStateBase.ValidTransitions`（Editor-only）声明合法出口状态，开发期转换验证
+- Animancer 双层：Layer 0 全身状态，Layer 1 Overlay 叠加层（Spring/SoulSkill 不打断移动动画）
+
+---
+
+### 2.5 Boss 体系 ✅ 强
+
+`EnemyBase → BossBase` 清晰继承，`BossBase.EnterPhase()` 虚方法支持多阶段；`BossSkillSO` + `SkillSequenceSO` 数据驱动，`BossSkillExecutor` 运行时执行。`BD_EnterPhase` / `BD_IsHPBelow` 等 Behavior Designer 任务节点封装了 Boss 特有逻辑，与通用 AI 节点复用统一的 `EnemyBase` 接口。
+
+---
+
+### 2.6 仍存在的架构问题
+
+#### ⚠️ P2：单例/ServiceLocator 混用
+
+| 类 | 当前访问方式 | 建议 |
+|----|------------|------|
+| `SaveManager` | `SaveManager.Instance` | 注册为 `ISaveService` |
+| `GlobalObjectPool` | `GlobalObjectPool.Instance` | 注册为 `IObjectPoolService` |
+| `MapManager` | `MapManager.Instance` | 注册为 `IMapService` |
+
+三者均为 `DontDestroyOnLoad` 单例，与 `ServiceLocator` 模式并存，增加全局状态来源的认知负担。`QuestManager` 已迁移至 ServiceLocator，是正确方向。
+
+#### ⚠️ P2：Enemy 状态为枚举，不可无侵入扩展
+
+`EnemyStateType`（`Controlled/Hurt/Stagger/Dead`）为简单枚举，新增状态类型需修改枚举定义，与玩家 POCO FSM 扩展性不对等。对于 Boss 专属状态（如 `Enraged`、`Stunned`）扩展不够灵活。
+
+#### ⚠️ P3：`AntiSoftlockSystem.Start()` 使用 FindFirstObjectByType
+
+```csharp
+_player = FindFirstObjectByType<PlayerController>();
+```
+
+每次场景加载执行一次，开销有限但仍属"全场景扫描"。可通过注入 `_onPlayerSpawned` 事件频道替代。
+
+---
+
+## 3. 性能
+
+### 3.1 热路径优化 ✅ 强
+
+| 优化项 | 实现 | 说明 |
+|--------|------|------|
+| 距离判断 | `sqrMagnitude` | 避免 `Vector2.Distance` 开根 |
+| GetComponent | 全量 Awake 缓存 | 无 Update 中动态调用 |
+| C# event vs UnityEvent | 全用 C# `Action<T>` | 无 UnityEvent 反射开销 |
+| 方向翻转 | `SpriteRenderer.flipX` | 替代旧版 `localScale.x = -1`（避免碰撞体跟随缩放） |
+| 状态切换 | POCO Dictionary 查找 | 零 GC，O(1) |
+| 输入 | `InputReaderSO` C# event | 无 `Input.GetKey` 每帧轮询 |
+
+### 3.2 状态效果双结构 ✅ 优秀
+
+```csharp
+// StatusEffectManager.cs — List + Dictionary 并行
+private readonly List<StatusEffect>                         _activeList  = new();
+private readonly Dictionary<StatusEffectType, StatusEffect> _activeIndex = new();
+
+// Update：逆序遍历 List（无 GC，避免移除时索引偏移）
+for (int i = _activeList.Count - 1; i >= 0; i--)
+{
+    effect.Update(delta);
+    if (effect.IsExpired) RemoveAt(i, effect);
+}
+```
+
+List 用于每帧 Tick 遍历，Dictionary 用于 O(1) 叠层查找（`existing.OnStack()`），是引擎级 StatusEffect 系统的标准实现方式。`MaterialPropertyBlock` 修改 Shader 参数不污染共享材质，零 Draw Call 增加。
+
+### 3.3 批量 LOS 视线检测节流 ✅ 优秀
+
+```csharp
+// BatchLOSSystem.cs — 每帧仅处理部分请求者
+[SerializeField, Min(1)] private int _maxRequestersPerFrame = 8;
+private int _currentOffset = 0;
+
+// FixedUpdate 中均匀轮询，避免单帧全量 Raycast
+int count = Mathf.Min(_maxRequestersPerFrame, _requesters.Count);
+for (int i = 0; i < count; i++)
+    int idx = (_currentOffset + i) % _requesters.Count;
+```
+
+20 个敌人仅每帧最多 8 条射线，均匀分配保证每个敌人 ~2.5 帧更新一次，感知延迟可配置，Raycast 数量与敌人规模解耦。
+
+### 3.4 对象池 WarmupAsync 统一 ✅ 强
+
+```csharp
+// GlobalObjectPool.cs — 单一入口，Coroutine 重载已移除
+public async Task WarmupAsync()
+{
+    foreach (var cfg in _warmupConfigs)
+    {
+        _maxCounts[cfg.AddressKey] = cfg.MaxCount;
+        await WarmupSingleAsync(cfg.AddressKey, cfg.InitialCount);
+    }
+}
+```
+
+LRU `LinkedList<PooledObject>` 活跃链表 + `Queue<PooledObject>` 空闲队列；Addressables 预加载，`MaxCount > 0` 时强制上限并回收最旧对象；`BackgroundRefillCoroutine` 低优先级后台补充（异步与协程混用有充分理由：补充逻辑跨帧分散）。
+
+### 3.5 存档系统 async/SemaphoreSlim ✅ 强
+
+- `SemaphoreSlim(1,1)` 保证同一时刻只有一个写操作，防止并发存档数据竞争
+- `Formatting.None` 序列化减少 JSON 字符串体积
+- HMAC-SHA256 完整性校验防止存档篡改
+- `SaveMigrator` 线性版本链（1.0 → 1.1 → 2.0 → 2.1），goto fall-through 模式简洁正确
+
+### 3.6 轻微性能风险项
+
+| 位置 | 问题 | 影响 |
+|------|------|------|
+| `DashState` | `Cfg != null ? Cfg.DashDuration : 0.18f` 魔法数值兜底 | 无运行时开销，但 Cfg 一旦为 null 行为静默 |
+| `SpeedrunTimer` | 使用 `Stats.DistanceTraveled` 字段存储计时（语义复用） | 无性能问题，仅语义混乱 |
+| `GameServiceRegistrar.EnsureSingleAudioListener()` | 首次调用 `FindObjectsOfType<AudioListener>` | 仅执行一次（Awake），后续场景加载改为局部扫描，可接受 |
+
+---
+
+## 4. 可扩展性
+
+### 4.1 WorldStateRegistry 泛化 ✅ 强
+
+```csharp
+// WorldStateRegistry.cs — Dictionary<WorldObjectCategory, HashSet<string>>
+public bool IsMarked(WorldObjectCategory category, string id) { ... }
+public void Mark(WorldObjectCategory category, string id) { ... }
+// 向后兼容具名快捷 API
+public bool IsCollected(string id)    => IsMarked(WorldObjectCategory.Collectible, id);
+public void MarkDoorOpened(string id) => Mark(WorldObjectCategory.Door, id);
+```
+
+新增世界对象类型只需在 `WorldObjectCategory` 枚举中添加值，无需修改 Registry 本体；`OnStateChanged` 事件使 UI/测试代码可响应式刷新；`OnEnable` 在域重载时清空状态，消除 Editor 跨 Play Session 污染。
+
+### 4.2 存档版本迁移管道 ✅ 强
+
+```csharp
+// SaveMigrator.cs — fall-through switch 版本链
+switch (data.Meta.Version)
+{
+    case "1.0": data = MigrateFrom1_0(data); goto case "1.1";
+    case "1.1": data = MigrateFrom1_1(data); goto case "2.0";
+    case "2.0": data = MigrateFrom2_0(data); goto case "2.1";
+    case "2.1": break;
+    default: Debug.LogWarning(...); break;
+}
+```
+
+新版本只需添加一个 `MigrateFromX_X` 方法和一个 `case`，跨多个版本升级的玩家自动经历完整迁移路径，是商业游戏存档系统的标准实践。
+
+### 4.3 Addressable Key 运行时注册 ✅ 强
+
+```csharp
+// AddressKeyRegistry.cs — DLC/扩展包运行时注册额外 key
+AddressKeyRegistry.TryRegister("DLC_WeaponScythe", "DLC/WPN_Scythe");
+// GlobalObjectPool 内部调用 Resolve 解析，兼容静态常量调用方
+```
+
+`ForceRegister` 供热更/测试覆盖，`Unregister` 支持 DLC 卸载，`Resolve` 对未注册 key 回退原值（向后兼容）。这是 Addressables 驱动的内容管理系统中少见的完善实现。
+
+### 4.4 装备/护符体系 ✅ 强
+
+`ICharmEffect` 接口 + 6 种具体效果（`StatModifierEffect`、`AttackSpeedEffect`、`OnHitEffect`、`WeaponOverrideEffect`、`SkillSlotOverrideEffect`、`SoulSpellEffect`）覆盖属性、攻击速度、命中触发、武器替换等场景；`SkillModifierRegistry` 为技能的数值修改提供独立注册点；`EquipmentConfigSO` 初始 Notch 容量可配。新增护符类型只需实现 `ICharmEffect`，无需修改 `EquipmentManager`。
+
+### 4.5 成就条件体系 ✅ 强
+
+12 种具体条件实现（`DefeatedBossCondition`、`ParryCountCondition`、`NoHealRunCondition`、`TimedBossKillCondition`、`MapExplorationCondition` 等），通过抽象 `AchievementCondition` 统一接口，`AchievementSO` 数据驱动，设计器可自由组合条件而不改代码。
+
+### 4.6 可扩展性薄弱项
+
+| 项目 | 当前状态 | 问题 |
+|------|---------|------|
+| `EnemyStateType` 枚举 | `Controlled/Hurt/Stagger/Dead` | 新增状态（如 Boss 专属 `Enraged`）需改枚举 |
+| `DashState` 魔法数值 | `0.18f / 20f / 3f / 0.4f` 硬编码 | Config 为 null 时行为不可配置 |
+
+---
+
+## 5. 编辑器友好性
+
+### 5.1 SO 数据验证构建钩子 ✅ 强
+
+```csharp
+// SOValidationRunner.cs — IPreprocessBuildWithReport
+public void OnPreprocessBuild(BuildReport report)
+{
+    var (errors, warnings) = RunAll();
+    if (errors.Count > 0)
+        throw new BuildFailedException(...); // 数据错误直接中止构建
+}
+[MenuItem("Tools/Validate All ScriptableObjects")]
+public static void ValidateMenu() { ... }
+```
+
+构建前自动扫描所有实现 `IValidatable` 的 SO，发现错误立即中止，防止数据配置错误进入发布版本；菜单项支持手动一键验证。`AddressKeyValidator` 以 `callbackOrder = 0` 在其前一步运行（先验证地址合法性，再验证 SO 数据），顺序正确。
+
+### 5.2 EventBusMonitorWindow ✅ 强
+
+- 256 条环形记录（帧号 + 时间戳 + 频道名 + 载荷 + 监听器数量）
+- 运行时实时观察事件流，无需断点即可诊断"事件发出了但没人听"
+- `Clear()` API 供测试前手动清空
+
+### 5.3 多个自定义 EditorWindow ✅ 强
+
+| 工具 | 作用 |
+|------|------|
+| `EventBusMonitorWindow` | 运行时事件流监控 |
+| `BossSkillSequenceWindow` | Boss 技能序列可视化编辑 |
+| `EventChainEditorWindow` | EventChain（事件链）节点图编辑 |
+| `AddressReferenceGraphWindow` | Addressable 依赖关系可视化 |
+| `SceneScaffoldTools` | 场景结构一键生成 |
+| `NavSurfaceBakeShortcut` | 导航网格烘培快捷键 |
+| `MapRoomDataEditor` | 地图房间数据编辑器 |
+
+7 个自定义工具窗口/菜单项覆盖了动画、AI、关卡、导航的日常工作流，质量接近商业 AA 内部工具链水准。
+
+### 5.4 Gizmos 覆盖
+
+- `WorldMarker`：Gizmos 可视化世界标记位置
+- `HitBox` / `HurtBox`：判定盒/受击盒在 Scene 视图中可见（红/绿色）
+- `CameraTriggerZone`：相机触发区域边界可视化
+- `RoomVisibleArea`：房间可见区域 Gizmos
+
+### 5.5 编辑器友好性薄弱项
+
+| 项目 | 问题 |
+|------|------|
+| `HurtBox` 注入方法 | `SetShieldable/SetParrySystem/SetPoiseSource` 代码注入，Inspector 中无法观察到注入状态，调试时需查看代码 |
+| `PlayerController` SerializeField | 约 15 个（已从 18 减至 15），对于新成员仍有认知负担；建议将战斗组件拆分到 `PlayerCombatInitializer` 或 `PlayerComponentHub` |
+
+---
+
+## 6. 使用便利性 DX
+
+### 6.1 PlayerStateBase 便捷属性 ✅ 强
+
+```csharp
+// PlayerStateBase.cs — 状态类内部无需直接引用 PlayerController
+protected InputReaderSO        Input   => _owner.Input;
+protected InputBuffer          Buffer  => _owner.Buffer;
+protected PlayerMovement       Move    => _owner.Movement;
+protected PlayerStats          Stats   => _owner.Stats;
+protected AnimancerComponent   Anim    => _owner.Animancer;
+protected PlayerMovementConfigSO Cfg   => _owner.MovConfig;
+protected PlayerAnimationConfigSO AnimCfg => _owner.AnimConfig;
+```
+
+16 个状态类共享同一套命名约定，新增状态只需实现 `OnStateEnter/Update/Exit`，直接使用 `Anim.Play(AnimCfg.Dash)` 等高级语义，无需知道底层 Animancer API 细节。
+
+### 6.2 EventSubscription RAII 模式 ✅ 优秀
+
+```csharp
+// 典型用法——统一 OnEnable/OnDisable 管理
+private readonly CompositeDisposable _subs = new();
+private void OnEnable()
+{
+    _onEnemyDied.Subscribe(HandleEnemyDefeated).AddTo(_subs);
+    _onCollectiblePickup.Subscribe(HandleCollectiblePickup).AddTo(_subs);
+}
+private void OnDisable() => _subs.Clear();
+```
+
+`.AddTo(CompositeDisposable)` 链式调用风格与 UniRx/R3 一致，降低学习成本；开发者无需记住每个订阅的取消操作，杜绝订阅泄漏。
+
+### 6.3 存档访问 API 具名化 ✅ 强
+
+```csharp
+// 旧（已删除）：var data = SaveManager.Instance.Data;  data.World.OpenedDoors.Contains(id)
+// 新（当前）：
+sm.IsBossDefeated(bossId);
+sm.IsWorldCollected(itemId);
+sm.IsDoorOpened(doorId);
+sm.GetPlayerMaxHP();
+```
+
+`SaveManager.Data` 属性已完全移除，强制调用方使用具名方法，避免调用者对存档数据结构产生直接依赖，后续修改存档结构只需改具名方法内部，不影响调用方。
+
+### 6.4 EnemyDied 事件直接携带 EnemyId ✅ 强
+
+```csharp
+// EnemyBase.cs
+[SerializeField] private string _enemyId;
+// Die() 中：
+_onEnemyDied?.Raise(_enemyId);
+
+// QuestManager.cs — 直接用字符串匹配，无需解析 Transform
+private void HandleEnemyDefeated(string enemyId)
+{
+    foreach (var objective in _activeObjectives)
+        if (objective.TargetEnemyId == enemyId) ...
+}
+```
+
+消除了之前 `QuestManager` 需要通过 `Transform` 反查敌人 ID 的间接依赖，`StringEventChannelSO` 是更语义化的类型选择。
+
+### 6.5 FormController 三段广播 ✅ 强
+
+```csharp
+// FormController.SwitchForm()
+_onFormChanged?.Raise(index);    // 1. SO 频道：UI 刷新 / Save 持久化
+OnFormChanged?.Invoke();         // 2. C# 事件：WeaponManager 同帧响应
+_onSkillSetChanged?.Raise();     // 3. 另一 SO 频道：SkillHUD 刷新
+```
+
+明确区分了"跨系统广播"（SO 频道）与"同模块紧密协作"（C# 事件）的场景，三个通知面向三类不同消费者，无多余耦合。
+
+### 6.6 DX 薄弱项
+
+| 问题 | 细节 | 建议 |
+|------|------|------|
+| `SpeedrunTimer` 字段语义复用 | 使用 `Stats.DistanceTraveled` 存储速通时间，字段名与内容不符 | `SaveData.Stats` 添加 `SpeedrunTime` 字段，或 `ExtensionData["SpeedrunTime"]` |
+| `DashState` 魔法数值兜底 | `Cfg != null ? Cfg.DashDuration : 0.18f`，Config 为 null 时静默使用硬编码值，无警告 | 添加 `Debug.LogWarning` 提示，或 `DashState` 构造时断言 Cfg 不为 null |
+| `AntiSoftlockSystem.Start()` FindFirstObjectByType | 可接受，但不如事件驱动 | 改订阅 `_onPlayerSpawned` 事件频道 |
+
+---
+
+## 7. 剩余问题优先级表
+
+> 仅列出经历两轮修复后**仍未完全解决**的项目。所有 P0 已清零。
+
+| # | 优先级 | 问题 | 状态 | 影响范围 |
+|---|--------|------|------|---------|
+| A1 | P2 | 单例/ServiceLocator 混用（SaveManager / GlobalObjectPool / MapManager） | 部分 | 架构一致性 |
+| A2 | P2 | EnemyStateType 枚举不可无侵入扩展 | 存在 | Enemy AI 扩展性 |
+| A3 | P3 | HurtBox 依赖注入不可 Inspector 可见 | 存在 | 调试体验 |
+| A4 | P3 | DashState 魔法数值兜底无警告 | 存在 | 配置错误静默 |
+| A5 | P3 | SpeedrunTimer 字段语义复用 | 存在 | 存档可读性 |
+| A6 | P3 | AntiSoftlockSystem 使用 FindFirstObjectByType | 存在 | Start 时一次性开销 |
+| A7 | P3 | GameServiceRegistrar 首次加载 FindObjectsOfType | 存在 | Awake 时一次性开销 |
+
+---
+
+## 8. 与商业基准的对标分析
+
+### 8.1 《空洞骑士》（Team Cherry，2017）
+
+| 领域 | 空洞骑士 | zeling_v2 | 差距 |
+|------|---------|-----------|------|
+| 敌人 AI | 手工 FSM，每个敌人独立 C# 状态机 | Behavior Designer 行为树 + EnemyStateType 枚举 | BT 工具链更规范，但枚举不如 POCO FSM 灵活 |
+| 存档系统 | 自定义二进制格式，单 slot | HMAC + JSON + 多 slot + 版本迁移 | **zeling_v2 更现代化** |
+| 事件系统 | UnityEvent + 直接引用 | SO Event Channel + RAII 订阅 | **zeling_v2 解耦更彻底** |
+| 装备系统 | 护符系统，硬编码效果 | ICharmEffect 接口，6 种多态效果 | **zeling_v2 可扩展性更强** |
+| 输入 | Input.GetKey 轮询 | New Input System + InputReaderSO | **zeling_v2 输入架构更现代** |
+
+### 8.2 《Celeste》（Maddy Makes Games，2018）
+
+| 领域 | Celeste | zeling_v2 | 差距 |
+|------|---------|-----------|------|
+| 玩家 FSM | PICO-8 → C# 重写，纯 POCO 状态 | POCO + Dictionary<Type, State> | 架构相似，zeling_v2 查找更高效 |
+| 辅助功能 | 完整辅助模式（无敌、慢速等） | `AccessibilityManager` + `AccessibilitySettingsSO` | 结构对等，具体功能待实现 |
+| 速通支持 | 内置计时器 | `SpeedrunTimer`（ISaveable，unscaledDeltaTime） | 功能完整，字段复用是小缺陷 |
+| 防软锁 | 无 | `AntiSoftlockSystem`（超时检测 + 逃脱选项） | **zeling_v2 更完善** |
+
+### 8.3 《Neon Abyss》（Veewo Games，2021）
+
+| 领域 | Neon Abyss | zeling_v2 | 差距 |
+|------|-----------|-----------|------|
+| 对象池 | 简单 Prefab 池 | Addressables + LRU + MaxCount + DLC 注册 | **zeling_v2 更完善** |
+| 状态效果 | 叠加型 Buff 字典 | 双结构 List+Dict + MaterialPropertyBlock | **zeling_v2 架构更清晰** |
+| 商店系统 | 数据驱动，状态持久化 | `ShopController` + `UIManager._currentShopId` + SO | 对等 |
+| 编辑器工具 | 标准 Unity 工具 | 7 个自定义 EditorWindow + 构建钩子 | **zeling_v2 工具链更丰富** |
+
+### 8.4 总评
+
+zeling_v2 在**架构现代化**（SO 事件、Assembly 拓扑、New Input System）、**存档健壮性**（HMAC 完整性、版本迁移、SemaphoreSlim 并发安全）、**编辑器工具链**（7 个 EditorWindow、构建验证钩子）三个维度上已超过上述三款参照游戏的已知水准；在**敌人 AI 扩展性**（枚举 FSM vs POCO FSM）和**全局状态管理一致性**（单例/SL 混用）上仍有差距。
+
+---
+
+## 9. 下一阶段建议
+
+> 按商业优先级排序，预估工作量（1 人天为单位）。
+
+### P2：架构一致性（合计约 3 人天）
+
+**9.1 迁移剩余单例到 ServiceLocator**
+
+```csharp
+// 在 GameServiceRegistrar.Awake() 中追加注册：
+if (SaveManager.Instance)
+    ServiceLocator.Register<ISaveService>(SaveManager.Instance);
+if (GlobalObjectPool.Instance)
+    ServiceLocator.Register<IObjectPoolService>(GlobalObjectPool.Instance);
+```
+
+保留 `static Instance` 但不对外暴露（`internal`），外部调用方改用 `ServiceLocator.Get<ISaveService>()`。工作量约 1 天。
+
+**9.2 EnemyStateType → 敌人 POCO FSM（可选）**
+
+成本较高（约 2 天），建议在下一个大版本迭代中推进，当前枚举方案功能完整，仅扩展性有限。可先为 BossBase 单独实现 `BossStateBase` POCO FSM，与普通敌人枚举 FSM 共存。
+
+### P3：代码质量（合计约 0.5 人天）
+
+**9.3 DashState 魔法数值添加警告**
+
+```csharp
+// DashState.cs — OnStateEnter
+if (Cfg == null)
+    Debug.LogWarning("[DashState] MovementConfig 未配置，使用默认数值，建议在 PlayerController Inspector 绑定。", _owner);
+_timer = Cfg != null ? Cfg.DashDuration : 0.18f;
+```
+
+**9.4 SpeedrunTimer 专用存档字段**
+
+```csharp
+// StatsSaveData.cs — 添加字段
+public float SpeedrunTime;
+// SpeedrunTimer.OnSave / OnLoad 改用此字段
+```
+
+**9.5 AntiSoftlockSystem 改为事件驱动**
+
+```csharp
+// AntiSoftlockSystem.cs
+[SerializeField] private TransformEventChannelSO _onPlayerSpawned;
+private void OnEnable()
+    => _onPlayerSpawned.Subscribe(t => { _player = t.GetComponent<PlayerController>(); ... }).AddTo(_subs);
+```
+
+---
+
+## 附录：文件规模统计
+
+| 目录 | 文件数 | 说明 |
+|------|--------|------|
+| `Animation/` | 6 | 动画事件绑定，Animancer 配置 |
+| `Audio/` | 9 | AudioManager、BGM、Footstep |
+| `Camera/` | 6 | 房间相机、相机状态机 |
+| `Combat/` | 18 | HitBox/HurtBox、弹射物、状态效果 |
+| `Core/` | ~30 | ServiceLocator、SaveSystem、Pool、Events |
+| `Enemies/` | ~35 | AI（22 个 BD 节点）、Boss、Navigation |
+| `Equipment/` | 14 | 护符系统、工具槽、效果接口 |
+| `Player/States/` | 18 | PlayerController + 16 状态类 + 基类 |
+| `Progression/` | ~18 | 成就系统（12 种条件）、进度锁、HP 容器 |
+| `Quest/` | 9 | 任务系统、挑战房间 |
+| `World/` | ~28 | WorldStateRegistry、谜题、商店、地图 |
+| `Editor/` | ~18 | 7 个 EditorWindow + 验证工具 |
+| **合计** | **~270** | 覆盖完整 2D 动作游戏功能集 |
+
+---
+
+*本文档由代码评审工具自动生成，基于 `Assets/Scripts/` 所有 .cs 文件的静态分析与架构评估。*  
+*上次更新：2025-05-11 | 评审者：GitHub Copilot*