merge: 抽取 WeightedPick 加权随机共享原语(消除四处平行实现)

小怪选招/Boss 选招/战利品掉落统一到 BaseGames.Core.WeightedPick;
删除零调用的 SelectWeightedSkill 死代码,修 LootResolver 权重重复计算;
冷却与 HitBox 时序经评估否决抽取(理由见决策记录)。
EditMode 177/177 通过。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Assets/Tests/EditMode/Core.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: ea96392988606754282c4f14deffc513
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Assets/Tests/EditMode/Core/WeightedPickTests.cs

@@ -0,0 +1,98 @@
+using System.Collections.Generic;
+using NUnit.Framework;
+using BaseGames.Core;
+
+namespace BaseGames.Tests.EditMode.Core
+{
+    /// <summary>
+    /// WeightedPick 加权随机取索引的共享原语测试。
+    /// 该原语被敌人选招 / Boss 选招 / 战利品掉落共用，故对"绝不选中零权重项"等
+    /// 确定性性质做强断言（多次采样），避免任一消费端出现选到不合格项的缺陷。
+    /// </summary>
+    public class WeightedPickTests
+    {
+        static List<float> W(params float[] w) => new List<float>(w);
+
+        [Test]
+        public void Null_ReturnsMinusOne()
+        {
+            Assert.AreEqual(-1, WeightedPick.Index(null));
+        }
+
+        [Test]
+        public void Empty_ReturnsMinusOne()
+        {
+            Assert.AreEqual(-1, WeightedPick.Index(W()));
+        }
+
+        [Test]
+        public void AllZero_ReturnsMinusOne()
+        {
+            Assert.AreEqual(-1, WeightedPick.Index(W(0f, 0f, 0f)));
+        }
+
+        [Test]
+        public void AllNegative_ReturnsMinusOne()
+        {
+            // 负权重按 0 处理（非法输入不应造成负总和/错误索引）
+            Assert.AreEqual(-1, WeightedPick.Index(W(-1f, -5f)));
+        }
+
+        [Test]
+        public void SinglePositive_AlwaysThatIndex()
+        {
+            var w = W(0f, 3f, 0f);
+            for (int i = 0; i < 50; i++)
+                Assert.AreEqual(1, WeightedPick.Index(w));
+        }
+
+        [Test]
+        public void NeverPicksZeroWeight()
+        {
+            // 索引 0/2 权重为 0，无论抽多少次都不该被选中
+            var w = W(0f, 1f, 0f, 2f);
+            for (int i = 0; i < 200; i++)
+            {
+                int idx = WeightedPick.Index(w);
+                Assert.IsTrue(idx == 1 || idx == 3, $"选中了零权重索引 {idx}");
+            }
+        }
+
+        [Test]
+        public void NeverPicksNegativeWeight()
+        {
+            var w = W(-10f, 1f);
+            for (int i = 0; i < 200; i++)
+                Assert.AreEqual(1, WeightedPick.Index(w));
+        }
+
+        [Test]
+        public void AllPositive_EveryIndexReachable()
+        {
+            // 等权重下，足够多次采样应覆盖所有索引（验证不会恒定只返回首个/末个）
+            var w = W(1f, 1f, 1f);
+            var seen = new HashSet<int>();
+            for (int i = 0; i < 500; i++) seen.Add(WeightedPick.Index(w));
+            CollectionAssert.AreEquivalent(new[] { 0, 1, 2 }, seen);
+        }
+
+        [Test]
+        public void HeavyWeight_DominatesDistribution()
+        {
+            // 权重 99:1 时，重权重索引应占绝大多数（宽松阈值，避免随机性造成偶发失败）
+            var w = W(99f, 1f);
+            int heavy = 0;
+            const int N = 1000;
+            for (int i = 0; i < N; i++) if (WeightedPick.Index(w) == 0) heavy++;
+            Assert.Greater(heavy, N * 0.9f, $"重权重仅被选中 {heavy}/{N} 次，分布不符合权重");
+        }
+
+        [Test]
+        public void WorksWithArray()
+        {
+            // IReadOnlyList 契约：数组同样可用（消费端可复用缓存数组，免 GC）
+            float[] w = { 0f, 5f };
+            Assert.AreEqual(1, WeightedPick.Index(w));
+        }
+    }
+}

Assets/Tests/EditMode/Core/WeightedPickTests.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 4a561ea40b19539439c8426cf0ccfe2c
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Assets/_Game/Scripts/Core/Utils.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: a1b254de5372a8242b7447d1acefafd7
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Assets/_Game/Scripts/Core/Utils/WeightedPick.cs

@@ -0,0 +1,51 @@
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace BaseGames.Core
+{
+    /// <summary>
+    /// 加权随机取索引的共享原语（纯逻辑、无状态、可单测）。
+    ///
+    /// 项目中"按权重随机选一个"的场景（敌人选招 / Boss 选招 / 战利品掉落）此前各写了一份
+    /// 累加-掷点-回退的循环，语义相同却各自维护。统一到本处，消除平行实现。
+    ///
+    /// 调用方职责：把候选的**有效权重**填入一个列表/数组（不合格候选填 0），
+    /// 本原语只负责"按权重挑一个索引"，不关心候选是什么、为何不合格。
+    /// 列表可由调用方缓存复用 → 选取过程零 GC 分配。
+    /// </summary>
+    public static class WeightedPick
+    {
+        /// <summary>
+        /// 按 <paramref name="weights"/> 加权随机返回一个索引。
+        /// 权重 ≤ 0 的项永不被选中（负权重按 0 处理）；无任何正权重时返回 -1。
+        /// </summary>
+        public static int Index(IReadOnlyList<float> weights)
+        {
+            if (weights == null) return -1;
+
+            int count = weights.Count;
+            float total = 0f;
+            for (int i = 0; i < count; i++)
+            {
+                float w = weights[i];
+                if (w > 0f) total += w;
+            }
+            if (total <= 0f) return -1;
+
+            float roll = Random.value * total;
+            float accum = 0f;
+            for (int i = 0; i < count; i++)
+            {
+                float w = weights[i];
+                if (w <= 0f) continue;
+                accum += w;
+                if (roll <= accum) return i;
+            }
+
+            // 浮点累加误差兜底：返回最后一个正权重项（绝不返回零权重项）
+            for (int i = count - 1; i >= 0; i--)
+                if (weights[i] > 0f) return i;
+            return -1;
+        }
+    }
+}

Assets/_Game/Scripts/Core/Utils/WeightedPick.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 9c93d1e517eba4e4a9240dd443c0c992
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Assets/_Game/Scripts/Enemies/Abilities/EnemyAttackSelector.cs

@@ -10,9 +10,14 @@ namespace BaseGames.Enemies.Abilities
     public sealed class EnemyAttackSelector
     {
         private readonly List<IAttackCandidate> _candidates;
+        // 权重缓冲区（与 _candidates 等长，每次选招复用）：避免每次选招 new List 造成 GC
+        private readonly List<float> _weightBuf;
 
         public EnemyAttackSelector(IEnumerable<IAttackCandidate> candidates)
-            => _candidates = new List<IAttackCandidate>(candidates);
+        {
+            _candidates = new List<IAttackCandidate>(candidates);
+            _weightBuf  = new List<float>(_candidates.Count);
+        }
 
         public int Count => _candidates.Count;
 
@@ -47,22 +52,19 @@ namespace BaseGames.Enemies.Abilities
 
         private IAttackCandidate SelectByWeight(bool hasLOS, bool grounded)
         {
-            float total = 0f;
+            // 有效权重：不合格候选填 0（由共享原语保证零权重项绝不被选中）。缓冲区复用 → 选招零 GC。
+            _weightBuf.Clear();
             for (int i = 0; i < _candidates.Count; i++)
             {
                 var c = _candidates[i];
-                if (Eligible(c, hasLOS, grounded)) total += Mathf.Max(0f, c.Weight);
+                _weightBuf.Add(Eligible(c, hasLOS, grounded) ? Mathf.Max(0f, c.Weight) : 0f);
             }
-            if (total <= 0f) return SelectByPriority(hasLOS, grounded); // 权重全 0 → 退化为按 Priority 选(并列取首个)
-            float roll = Random.value * total;
-            for (int i = 0; i < _candidates.Count; i++)
-            {
-                var c = _candidates[i];
-                if (!Eligible(c, hasLOS, grounded)) continue;
-                roll -= Mathf.Max(0f, c.Weight);
-                if (roll <= 0f) return c;
-            }
-            return null; // 理论不达（浮点边界兜底）
+
+            int idx = BaseGames.Core.WeightedPick.Index(_weightBuf);
+            if (idx >= 0) return _candidates[idx];
+
+            // 无正权重（合格候选权重全 0）→ 退化为按 Priority 选(并列取首个)
+            return SelectByPriority(hasLOS, grounded);
         }
     }
 }

Assets/_Game/Scripts/Enemies/Boss/BossBase.cs

@@ -39,8 +39,9 @@ namespace BaseGames.Enemies
         public int CurrentPhase => _currentPhase;
         private Coroutine _counterStaggerCoroutine;
 
-        // 缓存加权候选列表，避免 UseBossSkillWeighted() 每次 new List → GC 分配
-        private readonly List<(BossSkillSO skill, float w)> _weightedCandidates = new(8);
+        // 缓存加权候选与其有效权重（两者等长、下标对应），避免 UseBossSkillWeighted() 每次 new List → GC 分配
+        private readonly List<BossSkillSO> _weightedCandidates = new(8);
+        private readonly List<float>       _candidateWeights   = new(8);
 
         // 单元素缓冲数组，供 ApplyCounterResponse 缓存当前技能，避免 new[] 分配
         private readonly BossSkillSO[] _singleSkillBuf = new BossSkillSO[1];
@@ -110,31 +111,22 @@ namespace BaseGames.Enemies
 
             // 筛选：在当前阶段可用 + 冷却就绪 + weight > 0
             _weightedCandidates.Clear();
-            float totalWeight = 0f;
+            _candidateWeights.Clear();
             foreach (var s in skills)
             {
                 if (s == null || s.weight <= 0f) continue;
                 if (!_skillExecutor.CanUseSkill(s.skillId)) continue;
                 if (!IsSkillAvailableInPhase(s)) continue;
 
+                _weightedCandidates.Add(s);
                 // 防重复：上一个技能权重打折
-                float w = s.skillId == LastUsedSkillId ? s.weight * 0.3f : s.weight;
-                _weightedCandidates.Add((s, w));
-                totalWeight += w;
+                _candidateWeights.Add(s.skillId == LastUsedSkillId ? s.weight * 0.3f : s.weight);
             }
 
-            if (_weightedCandidates.Count == 0 || totalWeight <= 0f) return false;
-
-            // 加权随机抽取
-            float roll = UnityEngine.Random.Range(0f, totalWeight);
-            BossSkillSO selected = null;
-            float accum = 0f;
-            foreach (var (skill, w) in _weightedCandidates)
-            {
-                accum += w;
-                if (roll <= accum) { selected = skill; break; }
-            }
-            selected ??= _weightedCandidates[_weightedCandidates.Count - 1].skill;
+            // 加权随机抽取（共享原语：无正权重/无候选时返回 -1）
+            int idx = BaseGames.Core.WeightedPick.Index(_candidateWeights);
+            if (idx < 0) return false;
+            BossSkillSO selected = _weightedCandidates[idx];
 
             if (!CheckResourceCost(selected)) return false;
 

Assets/_Game/Scripts/Enemies/Boss/BossSkillExecutor.cs

@@ -127,37 +127,6 @@ namespace BaseGames.Boss
         /// <summary>Inspector 中注册的全部技能 SO（只读）。</summary>
         public BossSkillSO[] Skills => _skills;
 
-        /// <summary>
-        /// 从候选技能列表中按 weight 加权随机选择一个技能。
-        /// 权重为 0 的技能不参与选择；所有候选权重均为 0 时返回 null。
-        /// </summary>
-        public BossSkillSO SelectWeightedSkill(System.Collections.Generic.IList<BossSkillSO> candidates)
-        {
-            if (candidates == null || candidates.Count == 0) return null;
-
-            float totalWeight = 0f;
-            for (int i = 0; i < candidates.Count; i++)
-            {
-                var s = candidates[i];
-                if (s != null && s.weight > 0f) totalWeight += s.weight;
-            }
-            if (totalWeight <= 0f) return null;
-
-            float roll = UnityEngine.Random.value * totalWeight;
-            float acc  = 0f;
-            for (int i = 0; i < candidates.Count; i++)
-            {
-                var s = candidates[i];
-                if (s == null || s.weight <= 0f) continue;
-                acc += s.weight;
-                if (roll <= acc) return s;
-            }
-            // 浮点精度兜底：返回最后一个有效候选
-            for (int i = candidates.Count - 1; i >= 0; i--)
-                if (candidates[i]?.weight > 0f) return candidates[i];
-            return null;
-        }
-
         /// <summary>
         /// 执行一个 Boss 技能。若当前正在执行或技能冷却未就绪则返回。
         /// </summary>

Assets/_Game/Scripts/Enemies/LootResolver.cs

@@ -33,32 +33,24 @@ namespace BaseGames.Enemies
             bool isHard = dm != null &&
                           (int)dm.CurrentLevel >= (int)DifficultyLevel.Hard;
 
-            float totalWeight = 0f;
-            foreach (var entry in table.Entries)
+            // 有效权重只算一遍（难度加成），再交由共享原语加权抽取；无正权重时不掉落。
+            var weights = new float[table.Entries.Length];
+            for (int i = 0; i < table.Entries.Length; i++)
             {
+                var entry = table.Entries[i];
                 float w = entry.BaseWeight;
                 if (isHard && entry.ScaleWithDifficulty) w *= 1.5f;
-                totalWeight += w;
+                weights[i] = w;
             }
 
-            if (totalWeight <= 0f) return;
+            int idx = WeightedPick.Index(weights);
+            if (idx < 0) return;
 
-            float roll = Random.Range(0f, totalWeight);
-            float accum = 0f;
-            foreach (var entry in table.Entries)
-            {
-                float w = entry.BaseWeight;
-                if (isHard && entry.ScaleWithDifficulty) w *= 1.5f;
-                accum += w;
-                if (roll <= accum)
-                {
-                    if (!string.IsNullOrEmpty(entry.ItemId))
-                        CollectibleSpawner.SpawnItem(worldPosition, entry.ItemId);
-                    else if (entry.LingZhuAmount > 0)
-                        CollectibleSpawner.SpawnLingZhu(worldPosition, entry.LingZhuAmount);
-                    return;
-                }
-            }
+            var picked = table.Entries[idx];
+            if (!string.IsNullOrEmpty(picked.ItemId))
+                CollectibleSpawner.SpawnItem(worldPosition, picked.ItemId);
+            else if (picked.LingZhuAmount > 0)
+                CollectibleSpawner.SpawnLingZhu(worldPosition, picked.LingZhuAmount);
         }
 
         private static void ApplyDifficultyLingZhuScale(ref int lingZhu)

Docs_Dev/superpowers/specs/2026-07-27-shared-primitives-decision.md

@@ -0,0 +1,92 @@
+# 小怪 / Boss 共享底座：抽取决策记录
+
+> 日期：2026-07-27　　状态：已实施（Layer A），B/C 明确否决
+> 背景：小怪走 `EnemyAiBrain + PerceptionStateMachine + EnemyAbilityBase`，Boss 走
+> `BossBase + BossSkillExecutor + BossSkillSO`。两套决策/技能层并行演进，出现机制原语的平行实现。
+
+## 1. 结论摘要
+
+| 层 | 内容 | 决策 | 依据 |
+|---|---|---|---|
+| **A** | 加权随机取索引 | ✅ **已抽取** `BaseGames.Core.WeightedPick` | **4 份**平行实现，且已出现分歧 |
+| **B** | 冷却记账 | ❌ **否决** | 全项目冷却是**异构**的，符合该形态的只有 1 个消费者 |
+| **C** | HitBox 时序窗口 | ❌ **否决** | 仅 2 个**形态不同**的消费者，且两处均无测试覆盖 |
+
+核心原则：**只抽"两边同构且会漂移"的原语；不为"看起来像"的浅层重复付重构风险**。
+
+## 2. Layer A：已实施
+
+### 抽取前的 4 份平行实现
+1. `EnemyAttackSelector.SelectByWeight`（小怪选招）
+2. `BossBase.UseBossSkillWeighted`（Boss 选招，带上一招 0.3× 防重复惩罚）
+3. `BossSkillExecutor.SelectWeightedSkill`（**零调用者的死代码**，与 2 近似重复）
+4. `LootResolver.Resolve`（战利品掉落；**权重被算了两遍**——累加一遍、抽取时再算一遍，
+   两处公式若改动不同步即产生分布偏差）
+
+### 抽取结果
+```csharp
+namespace BaseGames.Core
+{
+    /// 调用方把候选的"有效权重"填入列表（不合格候选填 0），本原语只负责按权重挑索引。
+    public static class WeightedPick { public static int Index(IReadOnlyList<float> weights); }
+}
+```
+- 语义：权重 ≤ 0 的项**永不被选中**（负权重按 0 处理）；无正权重返回 `-1`；含浮点累加误差兜底。
+- 放 `BaseGames.Core`（非 Combat）——因为消费者含**战利品掉落**，并非战斗专属。
+- 零 GC：调用方复用权重缓冲区（`EnemyAttackSelector._weightBuf`、`BossBase._candidateWeights`）。
+- 覆盖：10 条 EditMode 单测（含"绝不选中零/负权重项"200 次采样断言、权重分布断言）。
+- 顺带清理：删除死代码 `SelectWeightedSkill`；消除 `LootResolver` 权重重复计算。
+
+### 为何不做 `ISelectable` 接口 + `WeightedSelector<T>`（初版草案）
+深入代码后否决：
+- `BossSkillSO` **没有** `priority` 字段（Boss 只用加权随机）→ 强加接口会产生无意义成员；
+- `LootTableSO.Entries` 的权重是**动态计算**的（难度加成），无法用静态接口属性表达；
+- 候选类型/合格判定两边完全不同，抽到接口层只会造出"上帝抽象"。
+→ 改为**更低层、更通用的 `Index(weights)`**，合格性与权重加成留在各自领域内。
+
+## 3. Layer B（冷却）：否决理由
+
+全项目冷却实现是**异构**的，不存在可统一的单一形态：
+
+| 系统 | 形态 |
+|---|---|
+| `ParrySystem` / `DashState` / `ToolSlotManager` / `SkillManager` | 每帧递减的**倒计时器** |
+| `BossSkillExecutor` | `Dictionary<string,float>` **截止时刻** |
+| `EnemyAbilityBase` | 单个 float **截止时刻**（每组件一个，判定仅 1 行） |
+
+符合"多 key 截止时刻字典"形态的**只有 `BossSkillExecutor` 一处**。为单一消费者建抽象＝纯仪式；
+强行统一则要重写玩家闪避/弹反/道具/技能 4 个无关系统，风险与收益完全不成比例。
+
+## 4. Layer C（HitBox 时序窗口）：否决理由
+
+两个消费者**形态本质不同**：
+- `MeleeAttackAbility.PlayAttackStep`：**归一化**（`hitBoxEnterT/ExitT` × duration）、**单** HitBox、逐帧 `Time.deltaTime` 推进、需跑满整段时长。
+- `BossSkillExecutor.ExecutePatternCoroutine`：**绝对秒数**（windup/active/recovery）、**多** HitBox 齐开齐关、`WaitForSeconds` 推进。
+- 玩家侧 `WeaponHitBoxInstance`（外部动画事件驱动开关）/ `SkillHitBoxInstance`（池化实例生命周期）是**另一种语义**，不是同一回事。
+
+叠加关键风险：**两处都无自动化测试覆盖**。重构等于在无测试保护下改动战斗手感时序，
+一个细微的时序回归难以发现。重复本身很浅（开/等/关约 5 行），不构成维护危害。
+→ 判定：**收益 < 风险，不做**。若将来出现第 3 个同形态消费者，可重新评估。
+
+## 5. 后续路线：Boss 决策层走 BrainGraph（延后，按需触发）
+
+**可行性高**：`BossBase` 已暴露决策所需 API（`UseBossSkillWeighted` / `IsBossSkillExecuting` /
+`IsHPBelow` / `CurrentPhase` / `BeginPhaseTransition` / `IsPhaseTransitioning`），
+只需一个 `IBossControl` facet 挂进 `IAiContext`（同 `ICombatant` 模式，保证 lambda 不捕获具体实例），
+`BossSkillExecutor` 的富执行层**原样保留**。
+
+**当前不必要**。触发条件（任一出现再做）：
+- 出现第 2/3 个 Boss，或需要"精英怪 / mini-boss"中间形态（要混用小怪状态 + Boss 技能）；
+- 要清理 BD（Behavior Designer）迁移债——现存 `StopBehaviorTree`、`BD_*` 注释残留；
+- 希望 Boss 也吃上小怪那套工具链（状态 Inspector、`TransitionRecord`、EditMode 测试）。
+
+**执行建议**：不要拿已能跑的 ChaoFeng 开刀验证；**等下一个新 Boss 时用 BrainGraph 从零搭**
+（决策走图 + `IBossControl`，执行仍用 `BossSkillExecutor`），验证顺畅后再回迁 ChaoFeng。
+
+**终态**：决策层统一 BrainGraph + 机制原语统一底座 + 执行层按复杂度分层
+（小怪 `EnemyAbilityBase` / Boss `BossSkillExecutor`）——既消重复，又保留 Boss 编排自由。
+
+## 6. 注记
+
+- `UseBossSkillWeighted` 目前**无调用者**（原 BD 任务已移除），是等待决策层接入的 Boss API，故保留。
+- 验证：编译 0 错误 0 警告；EditMode **177/177 通过**（原 167 + 新增 10）。