# 13 · 资源与对象池模块

> **命名空间** `BaseGames.Core.Pool`、`BaseGames.Core.Assets`  
> **程序集** `BaseGames.Core`  
> **路径** `Assets/Scripts/Core/Pool/`、`Assets/Scripts/Core/Assets/`  
> **依赖** `UnityEngine.AddressableAssets`、`BaseGames.Core.Events`

---

## 目录

1. [Addressables 工作流概述](#1-addressables-工作流概述)
2. [AddressKeys（地址常量）](#2-addresskeys)
3. [GlobalObjectPool](#3-globalobjectpool)
4. [PooledObject 组件](#4-pooledobject-组件)
5. [AssetLoader（运行时资产加载工具）](#5-assetloader)
6. [对象池预热（Warmup）流程](#6-对象池预热流程)
7. [Addressables 资产分组策略](#7-addressables-资产分组策略)
8. [AssetReleaseTracker](#8-assetreleasetracker)
9. [AddressKeyRegistry — 运行时动态注册](#9-addresskeyregistry--运行时动态注册)
10. [AddressKeyValidator — 构建前常量合法性校验](#10-addresskeyvalidator--构建前常量合法性校验)
11. [AddressReferenceGraphWindow — Addressables 依赖图工具](#11-addressreferencegraphwindow--addressables-依赖图工具)
12. [WarmupManifestSO — Addressables 预热策略](#12-warmupmanifestso--addressables-预热策略)

---

## 1. Addressables 工作流概述

**核心原则**：
- **禁止使用 `Resources.Load`**，所有运行时加载通过 Addressables（包括 Prefab、ScriptableObject、Sprite、AudioClip）
- 禁止在代码中直接写地址字符串，统一使用 `AddressKeys` 常量类
- 所有场景异步加载（`Addressables.LoadSceneAsync`）
- 场景切换后及时 `Addressables.Release` 卸载已卸载场景的资产
- 武器 Prefab（`WPN_*`）在角色进入场景时预热，通过 `WeaponManager.EquipAsync` 异步装备

---

## 2. AddressKeys

```csharp
// 路径: Assets/Scripts/Core/Assets/AddressKeys.cs
// 所有 Addressable 地址字符串的静态常量类
// 与 Assets 的 Addressable 分配保持同步（Editor 自动验证工具，见下方）
// 命名规范：所有 const string 以类型前缀命名（Prefab / Scene / Label / Data），驼峰式，无下划线
public static class AddressKeys
{
    // ── Scenes ──────────────────────────────────────────────
    public const string ScenePersistent    = "Scene_Persistent";
    public const string SceneMainMenu      = "Scene_MainMenu";
    public const string SceneCrossroadsA   = "Scene_ForgottenCrossroads_A";
    // ... 所有游戏场景

    // ── Player ──────────────────────────────────────────────
    public const string PrefabPlayer       = "PLY_Player";

    // ── Enemies ─────────────────────────────────────────────
    public const string PrefabEnemyGrunt     = "ENM_GruntWarrior";
    public const string PrefabEnemySkullArch = "ENM_SkullArcher";
    // ... 所有敌人 Prefab

    // ── Projectiles ─────────────────────────────────────────
    public const string PrefabProjArrow      = "PROJ_Arrow";
    public const string PrefabProjFireball   = "PROJ_Fireball";
    public const string PrefabProjSoulBall   = "PROJ_SoulBall";

    // ── VFX ─────────────────────────────────────────────────
    public const string PrefabVFXHitSpark    = "VFX_HitSpark";
    public const string PrefabVFXBloodSplat  = "VFX_BloodSplat";
    public const string PrefabVFXExplosion   = "VFX_Explosion";

    // ── UI ──────────────────────────────────────────────────
    public const string PrefabUIFloatingDmgText  = "UI_FloatingDamageText";

    // ── Collectibles ────────────────────────────────────────
    public const string PrefabCollectibleGeo    = "COL_Geo";
    public const string PrefabCollectibleHPOrb  = "COL_HPOrb";

    // ── Weapons ─────────────────────────────────────────────
    // 命名规范: PrefabWeapon{Id}  对应 Assets/Prefabs/Weapons/WPN_*.prefab
    public const string PrefabWeaponSkyBlade   = "WPN_SkyBlade";
    public const string PrefabWeaponEarthClaw  = "WPN_EarthClaw";
    public const string PrefabWeaponSoulStaff  = "WPN_SoulStaff";
    // ... 其余武器按同一规范追加

    // ── Config ScriptableObjects ─────────────────────────────
    // SO 资产用 Addressables 的场景：SO 数量极多（100+）或 DLC 扩展内容
    // 大多数 SO 通过 Inspector 直接序列化，不走 Addressable
    // 禁止通过 Resources.Load 加载，统一走 Addressables
    public const string DataFootstepCatalog    = "Config/FootstepCatalog";

    // ── Audio ────────────────────────────────────────────────
    // （AudioClip 通过 AudioEventSO 内嵌引用，不需要 Addressable key）

    // ── Labels（用于 Addressables.LoadAssetsAsync 批量加载）───
    public const string LabelEnemy     = "Enemy";
    public const string LabelPoolable  = "Poolable";
    public const string LabelBGM       = "BGM";
    public const string LabelCharms    = "Charms";
}
```

---

## 3. GlobalObjectPool

> **架构改进（2026-05）**：原 SpawnInternal 在池空时同步 `Instantiate`，且每次 Spawn/Despawn 都通过 `GetComponent<PooledObject>()` 查询；`MaxCount` 字段虽已声明但从未强制执行。以下版本修复这三个问题：
> 1. **缓存 PooledObject 引用**：Warmup 和 Instantiate 时就存入辅助字典，Spawn/Despawn 不再 GetComponent
> 2. **MaxCount 强制执行**：Despawn 时若存活总数超过上限，Destroy 而非入队；Spawn 池空时若已达上限，回收最近最少使用（LRU）的活跃对象
> 3. **异步后台补池**：同步 Instantiate 后立即触发后台 UniTask 补足到 `InitialCount`，避免后续 Spawn 仍走同步路径

```csharp
// 路径: Assets/Scripts/Core/Pool/GlobalObjectPool.cs
[DefaultExecutionOrder(-800)]
public class GlobalObjectPool : MonoBehaviour
{
    // 单例（Persistent 场景内）
    public static GlobalObjectPool Instance { get; private set; }

    [System.Serializable]
    public struct PoolConfig
    {
        public string AddressKey;   // AddressKeys 常量
        public int    InitialCount;
        public int    MaxCount;     // 0 = 无上限；> 0 强制限制池中 + 活跃对象总数
    }

    [SerializeField] private PoolConfig[] _warmupConfigs;

    // key = AddressKeys 常量, value = 空闲队列
    private readonly Dictionary<string, Queue<PooledObject>>  _pools      = new();
    // key = addressKey, value = 活跃中的对象列表（按 Spawn 时间先后排序，用于 LRU 回收）
    private readonly Dictionary<string, List<PooledObject>>   _alive      = new();
    private readonly Dictionary<string, GameObject>           _prefabCache = new();
    private readonly Dictionary<string, int>                  _maxCounts   = new();

    private void Awake()
    {
        if (Instance != null) { Destroy(gameObject); return; }
        Instance = this;
    }

    // ── 预热（场景加载完成后调用）────────────────────────────────────
    public async Task WarmupAsync()
    {
        foreach (var cfg in _warmupConfigs)
        {
            _maxCounts[cfg.AddressKey] = cfg.MaxCount;
            await WarmupSingleAsync(cfg.AddressKey, cfg.InitialCount);
        }
    }

    private async Task WarmupSingleAsync(string addressKey, int count)
    {
        var prefab = await Addressables.LoadAssetAsync<GameObject>(addressKey).Task;
        _prefabCache[addressKey] = prefab;

        if (!_pools.ContainsKey(addressKey)) _pools[addressKey] = new Queue<PooledObject>(count);
        if (!_alive.ContainsKey(addressKey)) _alive[addressKey] = new List<PooledObject>();

        for (int i = 0; i < count; i++)
        {
            var go  = Instantiate(prefab);
            var po  = go.GetComponent<PooledObject>();
            po?.Setup(addressKey, this);
            go.SetActive(false);
            _pools[addressKey].Enqueue(po);   // 直接存 PooledObject，Spawn 时无需 GetComponent
        }
    }

    // ── 取出 ─────────────────────────────────────────────────────────
    public T Spawn<T>(string addressKey, Vector3 position, Quaternion rotation) where T : Component
    {
        var po = SpawnInternal(addressKey, position, rotation);
        return po?.GetComponentCached<T>();   // PooledObject 可缓存常用 Component，减少 GetComponent
    }

    public GameObject Spawn(string addressKey, Vector3 position, Quaternion rotation)
        => SpawnInternal(addressKey, position, rotation)?.gameObject;

    private PooledObject SpawnInternal(string addressKey, Vector3 pos, Quaternion rot)
    {
        if (!_pools.TryGetValue(addressKey, out var queue))
        {
            Debug.LogError($"[ObjectPool] {addressKey} not warmed up!");
            return null;
        }

        PooledObject po;

        if (queue.Count > 0)
        {
            po = queue.Dequeue();
        }
        else
        {
            // 池空处理：优先检查 MaxCount 上限
            int maxCount = _maxCounts.GetValueOrDefault(addressKey, 0);
            var aliveList = GetAliveList(addressKey);

            if (maxCount > 0 && aliveList.Count >= maxCount)
            {
                // 已达上限：回收最早 Spawn 的活跃对象（LRU）
                po = aliveList[0];
                aliveList.RemoveAt(0);
                po.ForceReturnToPool();   // PooledObject 调用 OnDespawn + SetActive(false)
                Debug.LogWarning($"[ObjectPool] {addressKey} at MaxCount={maxCount}, recycling oldest.");
            }
            else
            {
                // 未达上限（或无上限）：同步实例化一个，并触发后台补池
                if (!_prefabCache.TryGetValue(addressKey, out var pfx))
                {
                    Debug.LogError($"[ObjectPool] {addressKey} prefab not cached!");
                    return null;
                }
                var go = Instantiate(pfx);
                po = go.GetComponent<PooledObject>();
                po?.Setup(addressKey, this);
                // 异步后台补池（不阻塞当前帧）
                BackgroundRefillAsync(addressKey, 1).Forget();
            }
        }

        var t = po.transform;
        t.SetPositionAndRotation(pos, rot);
        po.gameObject.SetActive(true);
        po.OnSpawn();   // 直接调用，已缓存引用，无 GetComponent

        GetAliveList(addressKey).Add(po);
        return po;
    }

    // ── 归还 ─────────────────────────────────────────────────────────
    public void Despawn(string addressKey, PooledObject po)
    {
        int maxCount = _maxCounts.GetValueOrDefault(addressKey, 0);
        int queueSize = _pools.TryGetValue(addressKey, out var queue) ? queue.Count : 0;
        var aliveList = GetAliveList(addressKey);

        aliveList.Remove(po);
        po.gameObject.SetActive(false);
        po.OnDespawn();   // 直接调用，已缓存引用

        // 超过 MaxCount（池中空闲 + 活跃）时销毁而非入队
        if (maxCount > 0 && queueSize + aliveList.Count >= maxCount)
        {
            Destroy(po.gameObject);
            return;
        }

        if (queue == null) { _pools[addressKey] = queue = new Queue<PooledObject>(); }
        queue.Enqueue(po);
    }

    // ── 后台补池（UniTask，不阻塞主线程）────────────────────────────
    private async UniTaskVoid BackgroundRefillAsync(string addressKey, int count)
    {
        if (!_prefabCache.TryGetValue(addressKey, out var pfx)) yield break;
        // 分帧实例化，避免单帧 GC 峰值
        for (int i = 0; i < count; i++)
        {
            await UniTask.Yield(PlayerLoopTiming.LastUpdate);
            var go = Instantiate(pfx);
            var po = go.GetComponent<PooledObject>();
            po?.Setup(addressKey, this);
            go.SetActive(false);
            if (_pools.TryGetValue(addressKey, out var q)) q.Enqueue(po);
        }
    }

    // ── 清空（场景卸载时）────────────────────────────────────────────
    public void ClearPool(string addressKey)
    {
        if (_pools.TryGetValue(addressKey, out var queue))
        {
            while (queue.Count > 0)
            {
                var po = queue.Dequeue();
                if (po != null) Destroy(po.gameObject);
            }
            _pools.Remove(addressKey);
        }
        _alive.Remove(addressKey);
        if (_prefabCache.TryGetValue(addressKey, out var pfx))
        {
            Addressables.Release(pfx);
            _prefabCache.Remove(addressKey);
        }
    }

    private List<PooledObject> GetAliveList(string addressKey)
    {
        if (!_alive.TryGetValue(addressKey, out var list))
            _alive[addressKey] = list = new List<PooledObject>();
        return list;
    }
}
```

---

## 4. PooledObject 组件

```csharp
// 路径: Assets/Scripts/Core/Pool/PooledObject.cs
// 挂在每个可池化 Prefab 根节点上
public class PooledObject : MonoBehaviour
{
    public string AddressKey { get; private set; }
    private GlobalObjectPool _pool;

    public void Setup(string key, GlobalObjectPool pool)
    {
        AddressKey = key;
        _pool = pool;
    }

    // 子类/组件可覆盖（实现 IPoolable 接口）
    public virtual void OnSpawn()  { }
    public virtual void OnDespawn(){ }

    // 便利方法：自归还
    public void ReturnToPool() => _pool?.Despawn(AddressKey, this);

    // LRU 强制回收（由 GlobalObjectPool 在 MaxCount 限制触发，不应由业务代码调用）
    internal void ForceReturnToPool()
    {
        OnDespawn();
        gameObject.SetActive(false);
    }

    // 延迟归还
    public void ReturnToPoolDelayed(float delay) => StartCoroutine(DelayedReturn(delay));
    private IEnumerator DelayedReturn(float delay)
    {
        yield return new WaitForSeconds(delay);
        ReturnToPool();
    }

    // 缓存常用组件（业务可在 Setup 时调用 CacheComponent，后续通过 GetComponentCached 避免 GetComponent）
    private readonly Dictionary<System.Type, Component> _componentCache = new();
    public T GetComponentCached<T>() where T : Component
    {
        if (!_componentCache.TryGetValue(typeof(T), out var cached))
            _componentCache[typeof(T)] = cached = GetComponent<T>();
        return (T)cached;
    }
}
```

---

## 5. AssetLoader

```csharp
// 路径: Assets/Scripts/Core/Assets/AssetLoader.cs
// 通用异步资产加载工具（非 Prefab 资产：SO、Sprite、AudioClip 等）
public static class AssetLoader
{
    private static readonly Dictionary<string, AsyncOperationHandle> _handles = new();

    public static async Task<T> LoadAsync<T>(string addressKey) where T : UnityEngine.Object
    {
        if (_handles.TryGetValue(addressKey, out var existing) && existing.IsValid())
            return (T)existing.Result;

        var handle = Addressables.LoadAssetAsync<T>(addressKey);
        _handles[addressKey] = handle;
        return await handle.Task;
    }

    // UniTask 版本（推荐用于需要 CancellationToken 的场景）
    public static async UniTask<T> LoadAsync<T>(string addressKey, CancellationToken ct)
        where T : UnityEngine.Object
    {
        if (_handles.TryGetValue(addressKey, out var existing) && existing.IsValid())
            return (T)existing.Result;

        var handle = Addressables.LoadAssetAsync<T>(addressKey);
        _handles[addressKey] = handle;
        return await handle.WithCancellation(ct);   // Cysharp.Threading.Tasks UniTask 扩展
    }

    public static void Release(string addressKey)
    {
        if (_handles.TryGetValue(addressKey, out var handle) && handle.IsValid())
        {
            Addressables.Release(handle);
            _handles.Remove(addressKey);
        }
    }

    public static void ReleaseAll()
    {
        foreach (var h in _handles.Values)
            if (h.IsValid()) Addressables.Release(h);
        _handles.Clear();
    }
}
```

---

## 6. 对象池预热流程

```
[SceneLoader.LoadSceneCoroutine 步骤 4]
    → GlobalObjectPool.Instance.WarmupAsync()
        → 遍历 _warmupConfigs 数组
        → 对每项：Addressables.LoadAssetAsync<GameObject>(key)
        → Instantiate × InitialCount
        → go.SetActive(false) → 入队
    → 完成后：SceneLoader 继续后续步骤（加载进度 60% → 90%）
```

**预热配置约定**（`_warmupConfigs` 数组在 Inspector 配置）：

| AddressKey | InitialCount | MaxCount |
|-----------|:---:|:---:|
| `VFX_HitSpark` | 20 | 40 |
| `VFX_BloodSplat` | 10 | 20 |
| `VFX_Explosion` | 5 | 10 |
| `PROJ_Arrow` | 10 | 30 |
| `PROJ_SoulBall` | 8 | 20 |
| `COL_Geo` | 30 | 60 |
| `COL_HPOrb` | 10 | 20 |
| `UI_FloatingDamageText` | 15 | 30 |
| `ENM_GruntWarrior` | 5 | 10 |

---

## 7. Addressables 资产分组策略

| 分组名 | 内容 | Bundle 模式 | 加载时机 |
|--------|------|------------|---------|
| `Default_LocalGroup` | 核心启动资产（Persistent 场景、InputReaderSO 等）| Pack Together | 游戏启动时常驻 |
| `UI` | 所有 UI Prefab 和 Sprite | Pack Together | 启动时预加载 |
| `Enemies_Poolable` | 所有可池化敌人 Prefab | Pack Together | 进入区域前预加载 |
| `Bosses` | Boss Prefab | Pack Separately | Boss 战开始前加载 |
| `VFX_Poolable` | 所有 VFX 粒子 Prefab | Pack Together | 游戏启动时全量预热 |
| `Projectiles_Poolable` | 弹射物 Prefab | Pack Together | 游戏启动时全量预热 |
| `Scene_{RegionName}` | 区域内场景、敌人、道具 Prefab | Pack Separately | 进入对应区域时加载 |
| `Audio_BGM` | BGM AudioClip | Pack Separately | Streaming，按区域切换 |
| `Audio_SFX` | 所有 SFX AudioClip | Pack Together | 压缩后常驻 |
| `Data_Charms` | CharmSO（数量极多时走 Addressable 路线）| Pack Together | 按需批量加载 |

**Bundle 模式说明**：  
- `Pack Together`：同类小资产批量打包，减少请求数  
- `Pack Separately`：大资产（场景、BGM）各自独立包，按需加载

---

## 8. AssetReleaseTracker

```csharp
// 路径: Assets/Scripts/Core/Assets/AssetReleaseTracker.cs
// 场景卸载时自动释放对应的 Addressable 资产和对象池
public class AssetReleaseTracker : MonoBehaviour
{
    [Header("Event Channels")]
    [SerializeField] private SceneLoadRequestEventChannelSO _onSceneLoadRequest;

    private string _lastLoadedScene;

    private void OnEnable()
        => _onSceneLoadRequest.OnEventRaised += OnSceneLoadRequested;
    private void OnDisable()
        => _onSceneLoadRequest.OnEventRaised -= OnSceneLoadRequested;

    private void OnSceneLoadRequested(SceneLoadRequest req)
    {
        if (!string.IsNullOrEmpty(_lastLoadedScene))
        {
            // 清除旧场景的敌人/VFX 对象池
            GlobalObjectPool.Instance.ClearPool(AddressKeys.PrefabEnemyGrunt);
            // ... 其他场景对象
        }
        _lastLoadedScene = req.SceneName;
    }
}
```

---

## 9. AddressKeyRegistry — 运行时动态注册

> **痛点**：`AddressKeys` 是纯静态常量类，无法在运行时注册新的地址键——DLC 内容或模组扩展时，新 Prefab 的地址字符串只能硬编码或通过外部 JSON 注入，导致对象池无法热扩展。
>
> `AddressKeyRegistry` 在静态常量之上提供一个运行时注册层，同时保持对已有代码的完全向后兼容（`AddressKeys.*` 常量仍是首选）。

```csharp
// 路径: Assets/Scripts/Core/Assets/AddressKeyRegistry.cs
// 命名空间: BaseGames.Core.Assets
// 运行时 Key 注册表（对 AddressKeys 静态常量的补充，不替代）
public class AddressKeyRegistry : MonoBehaviour
{
    public static AddressKeyRegistry Instance { get; private set; }

    // 运行时注册的 key → Addressable 地址映射
    // （静态常量中 key == address，此表支持别名映射）
    private readonly Dictionary<string, string> _registered = new();

    private void Awake()
    {
        if (Instance != null) { Destroy(gameObject); return; }
        Instance = this;
    }

    /// <summary>
    /// 注册一个运行时 key（如 DLC 内容）。
    /// key 不得与 AddressKeys 静态常量冲突（由 RegisterSafe 检查）。
    /// </summary>
    public bool TryRegister(string key, string addressableAddress)
    {
        if (_registered.ContainsKey(key))
        {
            Debug.LogWarning($"[AddressKeyRegistry] Key '{key}' already registered.");
            return false;
        }
        _registered[key] = addressableAddress;
        return true;
    }

    /// <summary>解析 key 到实际的 Addressable 地址。静态常量 key 原样返回。</summary>
    public string Resolve(string key)
        => _registered.TryGetValue(key, out var addr) ? addr : key;

    /// <summary>判断 key 是否已注册（静态常量或运行时注册均算）</summary>
    public bool IsKnown(string key)
        => _registered.ContainsKey(key) || IsStaticKey(key);

    // ── DLC 内容注册示例（由 DLC 包在 SceneLoaded 后调用）────────────
    // AddressKeyRegistry.Instance.TryRegister("DLC1_PrefabBossWraith", "dlc1/ENM_BossWraith");
    // GlobalObjectPool.Instance.AddressKey = Resolve(key) 即可透明接入对象池预热

    // ── Editor Only：验证注册 key 不与静态常量冲突 ────────────────────
    private static bool IsStaticKey(string key)
    {
        // 反射 AddressKeys 常量字段（仅 Editor / 开发版使用，Release Build 可裁剪）
#if UNITY_EDITOR || DEVELOPMENT_BUILD
        return typeof(AddressKeys).GetFields(
                System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static)
            .Any(f => f.IsLiteral && (string)f.GetRawConstantValue() == key);
#else
        return false;
#endif
    }
}
```

**GlobalObjectPool 集成**（透明支持 Registry）：在 `WarmupSingleAsync` 和 `SpawnInternal` 中将原始 `addressKey` 先经过 `AddressKeyRegistry.Instance?.Resolve(addressKey) ?? addressKey` 转换为真实 Addressable 地址，其余逻辑不变。

---

## 10. AddressKeyValidator — 构建前常量合法性校验

> **路径**：`Assets/Editor/Assets/AddressKeyValidator.cs`（Editor-only，不进入 Runtime）  
> **目标**：防止 `AddressKeys` 常量与实际 Addressable Labels 脱节，运行时才发现 Key 失效。

### 触发时机

| 时机 | 触发方式 | 说明 |
|------|---------|------|
| 打包前 | `IPreprocessBuildWithReport` | 正式 Build 自动运行，校验失败则中断出包 |
| 资产导入后 | `AssetPostprocessor.OnPostprocessAllAssets` | 仅当 Addressable 分组 `.asset` 被修改时触发 |
| 菜单手动 | `Tools > Validate AddressKeys` | 开发中随时按需运行 |

```csharp
// 路径: Assets/Editor/Assets/AddressKeyValidator.cs
using UnityEditor;
using UnityEditor.AddressableAssets;
using UnityEditor.Build;
using UnityEditor.Build.Reporting;
using System.Collections.Generic;
using System.Reflection;

public class AddressKeyValidator : IPreprocessBuildWithReport
{
    public int callbackOrder => 0;

    public void OnPreprocessBuild(BuildReport report)
    {
        var errors = Validate();
        if (errors.Count > 0)
            throw new BuildFailedException(
                $"[AddressKeyValidator] {errors.Count} 个 AddressKey 无效，构建中止：\n" +
                string.Join("\n", errors));
    }

    // 菜单入口
    [MenuItem("Tools/Validate AddressKeys")]
    public static void ValidateMenu()
    {
        var errors = Validate();
        if (errors.Count == 0)
            UnityEngine.Debug.Log("[AddressKeyValidator] ✅ 所有 AddressKey 均有效。");
        else
            UnityEngine.Debug.LogError(
                $"[AddressKeyValidator] ❌ 发现 {errors.Count} 个失效 Key：\n" +
                string.Join("\n", errors));
    }

    private static List<string> Validate()
    {
        // ── 1. 收集实际 Addressable 地址 ─────────────────────────────
        var settings = AddressableAssetSettingsDefaultObject.Settings;
        var validAddresses = new HashSet<string>();
        foreach (var group in settings.groups)
        foreach (var entry in group.entries)
            validAddresses.Add(entry.address);

        // ── 2. 反射 AddressKeys 所有 public const string 字段 ────────
        var errors = new List<string>();
        var fields  = typeof(AddressKeys)
            .GetFields(BindingFlags.Public | BindingFlags.Static)
            .Where(f => f.IsLiteral && f.FieldType == typeof(string));

        foreach (var field in fields)
        {
            var key = (string)field.GetRawConstantValue();
            if (!validAddresses.Contains(key))
                errors.Add($"  AddressKeys.{field.Name} = \"{key}\" → 在 Addressable 中未找到");
        }

        return errors;
    }
}

/// <summary>资产导入后检查（仅当 Addressable 分组文件变更时）</summary>
public class AddressKeyImportWatcher : AssetPostprocessor
{
    static void OnPostprocessAllAssets(
        string[] imported, string[] deleted, string[] moved, string[] movedFrom)
    {
        bool affectsAddressables = System.Array.Exists(imported,
            p => p.Contains("AddressableAssetSettings") || p.Contains("AssetGroups"));
        if (affectsAddressables)
            AddressKeyValidator.ValidateMenu();
    }
}
```

**使用流程**：
1. 新增/重命名 Addressable 条目后 → 同步更新 `AddressKeys` 常量
2. 若忘记同步 → 资产导入时控制台自动报 ❌，不会等到运行时崩溃
3. 打包时若有失效 Key → `BuildFailedException` 阻断出包，保护 Release 质量

---

## 11. AddressReferenceGraphWindow — Addressables 依赖图工具

> **P3 优化**：项目中 `AddressKeys` 常量越来越多，部分 Key 在重构后可能已无使用者（孤儿 Key），但不报错也不被 Validator 检测。本工具扫描全代码库，构建 **Key → 使用方** 反向图，高亮孤儿 Key，辅助清理无效资产引用。

### 11.1 功能规格

| 功能 | 说明 |
|------|------|
| **全量扫描** | 扫描所有 `.cs` 文件（排除 `Library/`、`Packages/`），找出 `AddressKeys.XXX` 使用点 |
| **图节点** | 每个 `AddressKeys` 常量字段 = 一个节点；被引用的 MonoBehaviour / SO 名 = 边 |
| **孤儿检测** | 引用计数 = 0 的 Key 标红；只有 1 处引用的 Key 标黄 |
| **快速定位** | 双击节点 → `EditorGUIUtility.PingObject()` 高亮 Project 中对应 .cs 文件 |
| **导出报告** | 点击 "导出 CSV" → 输出 `AddressKeys使用报告.csv` 到项目根目录 |

### 11.2 实现规范

```csharp
// 路径: Assets/Editor/Assets/AddressReferenceGraphWindow.cs
#if UNITY_EDITOR
using UnityEditor;
using UnityEngine;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text.RegularExpressions;

namespace BaseGames.Editor.Assets
{
    public class AddressReferenceGraphWindow : EditorWindow
    {
        [MenuItem("BaseGames/Tools/Asset Reference Graph")]
        public static void Open() => GetWindow<AddressReferenceGraphWindow>("资产引用图");

        // ── 数据模型 ──────────────────────────────────────────────────────
        private struct KeyNode
        {
            public string ConstName;       // e.g. "VFX_HitSpark"
            public string FullKey;         // AddressKeys 中对应的字符串值（如 "VFX/HitSpark"）
            public List<string> UsedBy;    // 使用此 Key 的文件名列表
        }

        private List<KeyNode>   _nodes       = new();
        private Vector2         _scroll;
        private bool            _scanning    = false;
        private string          _filterText  = "";
        private bool            _orphanOnly  = false;

        private static readonly Color ColOrphan  = new(1f, 0.3f, 0.3f, 1f);
        private static readonly Color ColSingle  = new(1f, 0.85f, 0.2f, 1f);
        private static readonly Color ColNormal  = new(0.8f, 1f, 0.8f, 1f);

        // ── GUI ──────────────────────────────────────────────────────────
        private void OnGUI()
        {
            DrawToolbar();
            if (_nodes.Count == 0)
            {
                EditorGUILayout.HelpBox("点击 「扫描」 开始分析 AddressKeys 使用情况。",
                    MessageType.Info);
                return;
            }
            DrawNodeList();
        }

        private void DrawToolbar()
        {
            EditorGUILayout.BeginHorizontal(EditorStyles.toolbar);
            if (GUILayout.Button("扫描", EditorStyles.toolbarButton, GUILayout.Width(48)))
                Scan();
            GUILayout.Label("过滤：", GUILayout.Width(36));
            _filterText = EditorGUILayout.TextField(_filterText, GUILayout.Width(180));
            _orphanOnly = GUILayout.Toggle(_orphanOnly, "仅显示孤儿 Key",
                EditorStyles.toolbarButton, GUILayout.Width(100));
            GUILayout.FlexibleSpace();
            if (_nodes.Count > 0)
            {
                GUILayout.Label($"共 {_nodes.Count} 个 Key  |  " +
                    $"🔴 孤儿 {_nodes.Count(n => n.UsedBy.Count == 0)}  " +
                    $"🟡 单引用 {_nodes.Count(n => n.UsedBy.Count == 1)}",
                    EditorStyles.toolbarLabel);
            }
            if (GUILayout.Button("导出 CSV", EditorStyles.toolbarButton, GUILayout.Width(68)))
                ExportCsv();
            EditorGUILayout.EndHorizontal();
        }

        private void DrawNodeList()
        {
            _scroll = EditorGUILayout.BeginScrollView(_scroll);
            foreach (var node in _nodes)
            {
                if (!string.IsNullOrEmpty(_filterText) &&
                    !node.ConstName.Contains(_filterText, System.StringComparison.OrdinalIgnoreCase))
                    continue;
                if (_orphanOnly && node.UsedBy.Count > 0)
                    continue;

                Color col  = node.UsedBy.Count == 0 ? ColOrphan
                           : node.UsedBy.Count == 1 ? ColSingle
                           :                          ColNormal;

                EditorGUILayout.BeginHorizontal();
                var labelStyle = new GUIStyle(EditorStyles.label)
                    { normal = { textColor = col }, fontStyle = FontStyle.Bold };
                GUILayout.Label($"  {node.ConstName}", labelStyle, GUILayout.Width(260));
                GUILayout.Label($"引用: {node.UsedBy.Count}",
                    EditorStyles.miniLabel, GUILayout.Width(56));

                if (node.UsedBy.Count > 0)
                    GUILayout.Label(string.Join(", ", node.UsedBy.Take(3)) +
                        (node.UsedBy.Count > 3 ? $" +{node.UsedBy.Count - 3}" : ""),
                        EditorStyles.miniLabel);
                EditorGUILayout.EndHorizontal();
            }
            EditorGUILayout.EndScrollView();
        }

        // ── 扫描逻辑 ──────────────────────────────────────────────────────
        private void Scan()
        {
            _nodes.Clear();

            // 1. 反射获取 AddressKeys 所有 const string 字段
            var addressKeysType = System.Type.GetType(
                "BaseGames.Assets.AddressKeys, Assembly-CSharp");
            if (addressKeysType == null)
            {
                Debug.LogError("[AssetRefGraph] 未找到 AddressKeys 类型，请确认命名空间正确。");
                return;
            }

            var fields = addressKeysType.GetFields(
                System.Reflection.BindingFlags.Public |
                System.Reflection.BindingFlags.Static)
                .Where(f => f.IsLiteral && f.FieldType == typeof(string))
                .ToList();

            // 2. 扫描 Assets/Scripts 下所有 .cs 文件
            var csFiles = Directory.GetFiles(
                Path.Combine(Application.dataPath, "Scripts"),
                "*.cs", SearchOption.AllDirectories);

            // 按文件缓存文本（避免重复读）
            var fileTexts = csFiles.ToDictionary(f => f, File.ReadAllText);

            // 3. 构建引用图
            foreach (var field in fields)
            {
                var constName = field.Name;
                var node      = new KeyNode
                {
                    ConstName = constName,
                    FullKey   = (string)field.GetRawConstantValue(),
                    UsedBy    = new List<string>()
                };

                var pattern = new Regex($@"\bAddressKeys\.{Regex.Escape(constName)}\b");
                foreach (var (filePath, text) in fileTexts)
                {
                    if (pattern.IsMatch(text))
                        node.UsedBy.Add(Path.GetFileNameWithoutExtension(filePath));
                }

                _nodes.Add(node);
            }

            // 4. 按引用数升序（孤儿在最前）
            _nodes.Sort((a, b) => a.UsedBy.Count.CompareTo(b.UsedBy.Count));
            Repaint();

            Debug.Log($"[AssetRefGraph] 扫描完成：{_nodes.Count} 个 Key，" +
                      $"{_nodes.Count(n => n.UsedBy.Count == 0)} 个孤儿 Key。");
        }

        // ── CSV 导出 ──────────────────────────────────────────────────────
        private void ExportCsv()
        {
            if (_nodes.Count == 0) { Debug.LogWarning("请先扫描。"); return; }

            var sb = new System.Text.StringBuilder();
            sb.AppendLine("ConstName,FullKey,ReferenceCount,UsedBy");
            foreach (var n in _nodes)
                sb.AppendLine($"{n.ConstName},{n.FullKey},{n.UsedBy.Count}," +
                              $"\"{string.Join("|", n.UsedBy)}\"");

            string path = Path.Combine(
                Path.GetDirectoryName(Application.dataPath)!,
                "AddressKeys使用报告.csv");
            File.WriteAllText(path, sb.ToString(), System.Text.Encoding.UTF8);
            Debug.Log($"[AssetRefGraph] CSV 已导出到：{path}");
            EditorUtility.RevealInFinder(path);
        }
    }
}
#endif
```

**孤儿 Key 处理决策**：

| 引用数 | 显示颜色 | 建议操作 |
|--------|----------|----------|
| 0（孤儿）| 🔴 红色 | 确认后从 `AddressKeys` 和 Addressable Groups 中删除 |
| 1 | 🟡 黄色 | 确认是否仅测试代码引用；若是，评估是否保留 |
| ≥ 2 | 🟢 绿色 | 正常，无需处理 |

---

## 12. WarmupManifestSO — Addressables 预热策略

> **P1 优化**：当前对象池没有集中化预热配置，进入新场景则运行时临时担贿  
> Addressables 异步加载 + 首张 Instantiate 的单帧卡顿。  
> `WarmupManifestSO` 将预热列表外化为每个场景可配置的资产，由 `SceneService`  
> 在加载场景的 Loading 阶段自动分帧预热，消除入场卡顿。
>
> **交叉引用**：`SceneService.LoadSceneAsync()`（规范见 `03_CoreModule.md §13`）内调用：  
> `await ServiceLocator.Get<GlobalObjectPool>().WarmupFromManifestAsync(_warmupManifest, ct);`

### 12.1 数据结构

```csharp
// 路径: Assets/Scripts/Core/Pool/WarmupManifestSO.cs
[CreateAssetMenu(menuName = "Core/Pool/Warmup Manifest")]
public class WarmupManifestSO : ScriptableObject
{
    [System.Serializable]
    public struct WarmupEntry
    {
        [Tooltip("Addressable 地址，对应 AddressKeys 中的常量字符串")]
        public string       AddressKey;     // 如 AddressKeys.ENEMY_CRAWLER

        [Tooltip("初始预热数量（对象池内初始容量）")]
        public int          InitialCount;   // 如 3

        [Tooltip("分类，可用于过滤或分层加载")]
        public WarmupCategory Category;
    }

    public enum WarmupCategory
    {
        Enemy       = 0,
        Projectile  = 1,
        VFX         = 2,
        UI          = 3,
        Other       = 99,
    }

    [Header("预热列表")]
    public WarmupEntry[] Entries;

    [Header("帧预算（每帧最多预热实例数量）")]
    [Range(1, 20)]
    public int InstancesPerFrame = 5;   // 默认每帧预热 5 个，拟地阶段是 30 帧内完成
}
```

### 12.2 场景专用 Manifest 示例

```
Assets/Data/Pool/Warmup/
├── Global_Warmup.asset       ← 全局常住（玩家子弹、核心 VFX，每个场景均需要）
├── Crossroads_Warmup.asset   ← 十字路场景的所有敌人 + Boss
├── ForgottenHollow_Warmup.asset
└── TitleScreen_Warmup.asset   ← UI 元素，革底冲債脚本展示用

# Crossroads_Warmup.asset 内容示例
# Entries:
#   - AddressKey: ENEMY_CRAWLER    InitialCount: 4  Category: Enemy
#   - AddressKey: ENEMY_SHIELDER   InitialCount: 2  Category: Enemy
#   - AddressKey: PROJ_SPIT        InitialCount: 8  Category: Projectile
#   - AddressKey: VFX_HIT_LIGHT    InitialCount: 6  Category: VFX
```

### 12.3 GlobalObjectPool.WarmupFromManifestAsync

```csharp
// GlobalObjectPool.cs — 新增方法
public async UniTask WarmupFromManifestAsync(WarmupManifestSO manifest,
    CancellationToken ct)
{
    if (manifest == null) return;

    int frameCounter = 0;

    foreach (var entry in manifest.Entries)
    {
        for (int i = 0; i < entry.InitialCount; i++)
        {
            ct.ThrowIfCancellationRequested();

            // 预加载并将实例放回池（不激活）
            await PrewarmOneAsync(entry.AddressKey, ct);

            frameCounter++;
            if (frameCounter >= manifest.InstancesPerFrame)
            {
                frameCounter = 0;
                await UniTask.Yield(PlayerLoopTiming.LastUpdate, ct);  // 让出当前帧
            }
        }
    }
}

private async UniTask PrewarmOneAsync(string addressKey, CancellationToken ct)
{
    // 1. 异步加载 Prefab
    var prefab = await Addressables.LoadAssetAsync<GameObject>(addressKey)
                     .ToUniTask(cancellationToken: ct);

    // 2. Instantiate，不激活
    var go = Object.Instantiate(prefab);
    go.SetActive(false);

    // 3. 注册到内部字典（等待请求时直接取出）
    if (!_pools.ContainsKey(addressKey))
        _pools[addressKey] = new Stack<GameObject>();
    _pools[addressKey].Push(go);
}
```

### 12.4 SceneService 集成

```csharp
// SceneService.cs — LoadSceneAsync 内的预热阶段（见 03_CoreModule.md §13）
// SceneService 的场景 manifest 映射通过 Inspector 配置：

[Header("预热 Manifest 映射")]
[SerializeField] private WarmupManifestSO _globalManifest;     // 常驻预热
[SerializeField] private SceneWarmupMapSO _sceneWarmupMap;     // 场景 → Manifest 映射

// LoadSceneAsync 内预热项（在进度条用5%-95%阶段执行）
var pool = ServiceLocator.Get<GlobalObjectPool>();
if (_globalManifest   != null) await pool.WarmupFromManifestAsync(_globalManifest, ct);
if (_sceneWarmupMap   != null)
{
    var sceneManifest = _sceneWarmupMap.Get(sceneAddress);
    if (sceneManifest != null) await pool.WarmupFromManifestAsync(sceneManifest, ct);
}
```

**`SceneWarmupMapSO`**：场景地址 → `WarmupManifestSO` 的字典包装，简单 SO：

```csharp
// Assets/Scripts/Core/Pool/SceneWarmupMapSO.cs
[CreateAssetMenu(menuName = "Core/Pool/Scene Warmup Map")]
public class SceneWarmupMapSO : ScriptableObject
{
    [System.Serializable]
    public struct Entry
    {
        public string          SceneAddress;    // Addressable 场景地址
        public WarmupManifestSO Manifest;
    }
    public Entry[] Entries;

    public WarmupManifestSO Get(string sceneAddress)
    {
        foreach (var e in Entries)
            if (e.SceneAddress == sceneAddress) return e.Manifest;
        return null;
    }
}
```

### 12.5 预热时序与帧预算

```
加载场景时序（全程在 LoadingOverlay 革盖下）：

  [0%]   Addressables.LoadSceneAsync(目标场景)
  [10%]  场景资产加载完成
  [20%]  全局 Manifest 预热开始
  [40%]  场景专用 Manifest 预热开始
  [80%]  预热完成
  [95%]  场景激活（SetActive true）
  [100%] 隐藏 Loading Overlay

帧预算规则 (InstancesPerFrame = 5):
  - 场景有 30 个 Warmup 实例 → 分 6 帧完成 ≈ 0.1s 额外延迟（在 Loading 鵠 屏内）
  - 不占游戏运行时帧时间，玩家没有感知
```

### 12.6 度量指标

| 指标 | 目标 |
|------|------|
| 入场后首次 Spawn 列长 | ≤ 0.5ms | 
| Loading 阶段 GC 分配 | ≤ 1 MB |
| 预热完成率 | 入场前 100% 所需实例就绪 |

### 12.7 WarmupManifestSO 自定义 Inspector — 帧预算预估

> **设计师工具**：配置完 `Entries` 数组后，Inspector 自动显示：
> - 总实例数、预计帧数、各 Category 实例占比饼图
> - 当 `InstancesPerFrame` 过低（预计 > 30 帧）时显示橙色警告

```csharp
// 路径: Assets/Editor/Pool/WarmupManifestSOEditor.cs
#if UNITY_EDITOR
using UnityEditor;
using UnityEngine;
using System.Linq;

[CustomEditor(typeof(WarmupManifestSO))]
public class WarmupManifestSOEditor : Editor
{
    public override void OnInspectorGUI()
    {
        DrawDefaultInspector();

        var manifest = (WarmupManifestSO)target;
        if (manifest.Entries == null || manifest.Entries.Length == 0) return;

        EditorGUILayout.Space(8);
        EditorGUILayout.LabelField("── 帧预算预估 ──", EditorStyles.boldLabel);

        int totalInstances = manifest.Entries.Sum(e => e.InitialCount);
        int ipf            = Mathf.Max(1, manifest.InstancesPerFrame);
        int estimatedFrames = Mathf.CeilToInt((float)totalInstances / ipf);
        float estimatedMs   = estimatedFrames * (1000f / 60f);  // 按 60fps 估算

        EditorGUILayout.LabelField($"总实例数：{totalInstances}");
        EditorGUILayout.LabelField($"每帧预热：{ipf}");

        // 超过 30 帧时显示橙色警告
        var style = new GUIStyle(EditorStyles.label);
        if (estimatedFrames > 30)
        {
            style.normal.textColor = new Color(1f, 0.6f, 0f);  // 橙色
            EditorGUILayout.LabelField(
                $"⚠️  预计帧数：{estimatedFrames} 帧 ≈ {estimatedMs:F0}ms — 建议提高 InstancesPerFrame",
                style);
        }
        else
        {
            EditorGUILayout.LabelField($"预计帧数：{estimatedFrames} 帧 ≈ {estimatedMs:F0}ms ✅");
        }

        // 各 Category 实例分布
        EditorGUILayout.Space(4);
        EditorGUILayout.LabelField("Category 分布：", EditorStyles.miniLabel);
        var groups = manifest.Entries
            .GroupBy(e => e.Category)
            .OrderByDescending(g => g.Sum(e => e.InitialCount));
        foreach (var g in groups)
        {
            int count = g.Sum(e => e.InitialCount);
            float pct = totalInstances > 0 ? (float)count / totalInstances * 100f : 0f;
            EditorGUI.ProgressBar(
                EditorGUILayout.GetControlRect(false, 16),
                pct / 100f,
                $"{g.Key}: {count} ({pct:F0}%)");
        }
    }
}
#endif
```