# Boss 多阶段战斗系统实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 为 Boss 实现固定 3 阶段（P1/P2/P3）战斗模式：混合触发（血量阈值 OR 在场时长）、增量技能轮换（adds/removes）、属性修正，表现层留空钩子。

**Architecture:** 增量驱动式——配置层 `BossPhaseSet`（10000 段 id）声明切换点，`heroInfo.phase_ids` 声明 Boss 允许的方案，`RogueConfig.makeBoss` 随机取一注入 `GeneratedMonster.phase_plan_id`，`Mon.load` 按需挂载 `BossPhaseComp` 标记组件，`BossPhaseSystem`（独立 ECS 系统）检测条件并增量改写 `model.skills`。`SCastSystem`/`HeroAtkSystem` 零改动。

**Tech Stack:** Cocos Creator 3.x + TypeScript 严格模式 + oops-framework ECS + `oops.message` 事件总线

**规格文档:** `docs/superpowers/specs/2026-10-06-boss-phase-system-design.md`

**验证方式:** 项目无单元测试框架，每任务完成后在 Cocos Creator 编辑器中触发编译检查控制台无红色报错；Task 9 做运行时验证。

**已知约束（来自审查，实施时必须遵守）:**
- `ComblockSystem.update` 真实签名为 `update(e: ecs.Entity)`，dt 从 `this.dt` 取，框架自动遍历
- removes/adds 绝不操作普攻首键（`buildSkillCandidates` 硬假设首键=普攻）
- cd 强制兜底 8s（防 `ccd = Math.min(undefined,...) = NaN` 导致大招永不释放）
- 血量阈值每帧实时算 `hp/hp_max*100`，禁止缓存绝对值（hp_max 在 load 后被 MissionMonComp 覆盖）
- `heroSet.ts` 工作区有用户未提交修改，只做精准行内插入，勿动其他行

---

### Task 1: 新建 BossPhaseSet.ts（配置 + 类型 + 校验）

**Files:**
- Create: `assets/script/game/common/config/BossPhaseSet.ts`

- [ ] **Step 1: 创建配置文件**

```ts
/**
 * @file BossPhaseSet.ts
 * @description Boss 多阶段战斗方案配置（固定 3 阶段：P1 基线 / P2 / P3）
 *
 * 数据流：heroInfo.phase_ids（允许方案）→ RogueConfig.makeBoss 随机取一
 *        → Mon.load 第 8 参 → BossPhaseComp → BossPhaseSystem 检测切换
 *
 * 设计约束：
 *   - 方案 id 使用 10000 段（9100 段已被 TalentSet 9101-9199 / ICardSet 9101~9110 占用）
 *   - 增量驱动：切换 = removes 移除 + adds 注入，P1 = 基线技能（heroInfo.skills + RogueConfig 大招）无需配置
 *   - removes/adds 禁止操作普攻首键（SCastSystem.buildSkillCandidates 硬假设首键=普攻垫底；
 *     JS delete+set 会把键移到末尾，破坏普攻垫底契约）
 *   - 混合触发：同一切换点 hp_pct / time 任一满足即切换；
 *     hp_pct 切换点必须构成前缀（time-only 点之后禁止再配 hp_pct，防乱序连切）
 */

import { SkillSet, SkillOverrides } from "./SkillSet";

/** 阶段切换触发条件（混合触发：任一条件满足即切换） */
export interface PhaseTrigger {
    /** 血量百分比阈值（1~99）：Boss 血量比例 ≤ 该值时触发 */
    hp_pct?: number;
    /** Boss 在场战斗秒数：超过该时长触发 */
    time?: number;
}

/** 切换瞬间一次性属性修正（基于当前值链式乘算，P3 基于 P2 修正后的值） */
export interface PhaseAttrMod {
    /** 攻击 ±% */
    ap_pct?: number;
    /** 防御 ±%（applyDefense 除法递减模型，收益非线性，配值按公式校验） */
    defense_pct?: number;
}

/** 注入技能条目（与 RogueConfig 大招条目同构，cd 缺省由系统兜底 8s） */
export interface PhaseSkillEntry {
    s_uuid: number;
    cd?: number;
    overrides?: SkillOverrides;
}

/** 单个切换点定义（switches[0] = P1→P2，switches[1] = P2→P3） */
export interface PhaseSwitchDef {
    trigger: PhaseTrigger;
    /** 注入的技能（追加进 skills 表，SCastSystem 按 CD 轮转）。禁止操作普攻首键 */
    adds?: PhaseSkillEntry[];
    /** 移除的技能 s_uuid 列表（含 RogueConfig 注入的大招）。禁止操作普攻首键 */
    removes?: number[];
    attr_mod?: PhaseAttrMod;
}

/** 阶段方案：固定 2 个切换点 = 3 阶段，P1 为基线 */
export interface BossPhasePlan {
    name: string;
    switches: [PhaseSwitchDef, PhaseSwitchDef];
}

/**
 * 阶段方案表（id 段 10000）
 * 示例方案 10001 挂在 6101（兽人首领-双刀dps型）的 phase_ids 上；
 * 大招 s_uuid 引用 RogueConfig.BossUltPools 近战池（6100~6104）保证可达
 */
export const BossPhaseSet: Record<number, BossPhasePlan> = {
    10001: {
        name: "狂暴进化",
        switches: [
            { trigger: { hp_pct: 70 }, adds: [{ s_uuid: 6102, overrides: { ap: 180 } }], removes: [6100] },
            { trigger: { hp_pct: 40, time: 60 }, adds: [{ s_uuid: 6103, overrides: { ap: 180 } }], attr_mod: { ap_pct: 20 } },
        ],
    },
};

/**
 * 校验阶段方案表合法性（供 validateRogueConfig 追加调用，建议启动期执行一次）
 * @returns 错误信息数组，空数组表示校验通过
 */
export function validateBossPhaseSet(): string[] {
    const errors: string[] = [];

    for (const key in BossPhaseSet) {
        const plan = BossPhaseSet[key];
        const tag = `BossPhaseSet[${key}](${plan.name})`;

        if (plan.switches.length !== 2) {
            errors.push(`${tag} 切换点必须恰为 2 个（固定 3 阶段），实际 ${plan.switches.length}`);
            continue;
        }

        let seenTimeOnly = false;
        let lastHpPct = 101;
        let lastTime = 0;

        plan.switches.forEach((def, i) => {
            const t = def.trigger;
            const stag = `${tag} switches[${i}]`;

            // 条件完备性与取值范围
            if (t.hp_pct === undefined && t.time === undefined) {
                errors.push(`${stag} trigger 至少需要 hp_pct 或 time 之一`);
                return;
            }
            if (t.hp_pct !== undefined && (t.hp_pct <= 0 || t.hp_pct >= 100)) {
                errors.push(`${stag} hp_pct 必须在 (0,100) 区间，实际 ${t.hp_pct}`);
            }
            if (t.time !== undefined && t.time <= 0) {
                errors.push(`${stag} time 必须 > 0，实际 ${t.time}`);
            }

            // hp_pct 前缀规则：time-only 点之后禁止再配 hp_pct（防"P2 time / P3 hp_pct"乱序连切）
            if (seenTimeOnly && t.hp_pct !== undefined) {
                errors.push(`${stag} hp_pct 切换点必须构成前缀：time-only 切换点之后禁止再配置 hp_pct`);
            }
            if (t.hp_pct === undefined && t.time !== undefined) {
                seenTimeOnly = true;
            }

            // hp_pct 严格递减 / time 严格递增
            if (t.hp_pct !== undefined) {
                if (t.hp_pct >= lastHpPct) {
                    errors.push(`${stag} hp_pct=${t.hp_pct} 未严格小于前一档 ${lastHpPct}`);
                }
                lastHpPct = t.hp_pct;
            }
            if (t.time !== undefined) {
                if (t.time <= lastTime) {
                    errors.push(`${stag} time=${t.time} 未严格大于前一档 ${lastTime}`);
                }
                lastTime = t.time;
            }

            // 技能引用存在性（error 级）
            for (const add of def.adds ?? []) {
                if (!add.s_uuid || !SkillSet[add.s_uuid]) {
                    errors.push(`${stag} adds 技能 ${add.s_uuid} 未在 SkillSet 中定义`);
                }
            }
            for (const s_uuid of def.removes ?? []) {
                if (!SkillSet[s_uuid]) {
                    errors.push(`${stag} removes 技能 ${s_uuid} 未在 SkillSet 中定义`);
                }
            }
        });
    }

    return errors;
}
```

- [ ] **Step 2: 编译验证**

在 Cocos Creator 编辑器中保存文件触发编译（或等编辑器自动编译），检查控制台无红色报错。
重点确认：`SkillSet` 与 `SkillOverrides` 均从 `./SkillSet` 导出（RogueConfig.ts L24 已有同款 import 先例）。

- [ ] **Step 3: Commit**

```bash
git add assets/script/game/common/config/BossPhaseSet.ts
git commit -m "feat: add BossPhaseSet config with phase plan schema"
```

---

### Task 2: heroSet.ts 加 phase_ids 字段与示例配置

**Files:**
- Modify: `assets/script/game/common/config/heroSet.ts:432`（接口字段，accuracy 之后）
- Modify: `assets/script/game/common/config/heroSet.ts:1095`（6101 配置行尾）

- [ ] **Step 1: heroInfo 接口新增字段**

在 L432 `accuracy?: number;` 行之后、L433 `skills: Record<number, HSkillInfo>;` 之前插入：

```ts
    phase_ids?: number[]; // Boss 专属：允许的阶段方案 id 列表（引用 BossPhaseSet，生成时随机取一）
```

- [ ] **Step 2: 6101 配置挂载示例方案**

在 L1095（`uuid: 6101, ... speed: 120,` 行）的 `speed: 120,` 之后、行尾前追加：

```ts
 phase_ids: [10001],
```

即该行变为（仅尾部变化，其余内容原样保留）：

```ts
        uuid: 6101, name: "兽人首领-双刀dps型", path: "mb1", fac: FacSet.MON, lv: 6, rarity: 4, type: HType.Melee, grow_type: HGrowType.Warrior, role: HRole.Warrior, monType: MonType.MeleeBoss, hp: HERO_ROLE_BASE[HRole.Warrior].hp, ap: HERO_ROLE_BASE[HRole.Warrior].ap, def: HERO_ROLE_BASE[HRole.Warrior].def, speed: 120, phase_ids: [10001],
```

注意：该文件工作区有用户未提交修改，只做上述两处精准插入，不改动任何其他行。

- [ ] **Step 3: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。

- [ ] **Step 4: Commit**

```bash
git add assets/script/game/common/config/heroSet.ts
git commit -m "feat: add phase_ids field to boss hero config"
```

---

### Task 3: GameEvent.ts 加 BossPhaseChange 枚举

**Files:**
- Modify: `assets/script/game/common/config/GameEvent.ts:118`（RestartMission 之后）

- [ ] **Step 1: 新增枚举项**

在 L118 `RestartMission = "RestartMission",` 之后、枚举闭合 `}` 之前插入：

```ts
    /** Boss 阶段切换（payload: { eid, planId, fromPhase, toPhase }，表现层监听此事件实现演出；eid 定位实体，勿持裸引用） */
    BossPhaseChange = "BossPhaseChange",
```

- [ ] **Step 2: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。

- [ ] **Step 3: Commit**

```bash
git add assets/script/game/common/config/GameEvent.ts
git commit -m "feat: add BossPhaseChange game event"
```

---

### Task 4: 新建 BossPhaseComp.ts（标记组件）

**Files:**
- Create: `assets/script/game/hero/BossPhaseComp.ts`

- [ ] **Step 1: 创建组件文件**

```ts
import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";

/**
 * Boss 阶段标记组件：挂载即表示该实体参与多阶段状态机
 * 由 Mon.load 按 phase_plan_id 条件挂载，Monster.destroy 显式 remove（触发 reset + 回组件池）
 * 计时字段 elapsed 随 reset 天然归零，无全局战斗计时状态
 */
@ecs.register('BossPhase')
export class BossPhaseComp extends ecs.Comp {
    /** 生效的阶段方案 id（BossPhaseSet key） */
    plan_id: number = 0;
    /** 当前阶段索引：0=P1 / 1=P2 / 2=P3（P3 后系统不再检测） */
    index: number = 0;
    /** Boss 在场战斗累计时长（秒），time 触发条件基准 */
    elapsed: number = 0;

    reset() {
        this.plan_id = 0;
        this.index = 0;
        this.elapsed = 0;
    }
}
```

- [ ] **Step 2: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。重点确认 `ecs.Comp` 的 `reset()` 为抽象方法必须实现（与 HeroAttrsComp 同款模式）。

- [ ] **Step 3: Commit**

```bash
git add assets/script/game/hero/BossPhaseComp.ts
git commit -m "feat: add BossPhaseComp marker component"
```

---

### Task 5: Mon.ts 接入（load 第 8 参 + 组件挂载/移除）

**Files:**
- Modify: `assets/script/game/hero/Mon.ts:1`（import 区）
- Modify: `assets/script/game/hero/Mon.ts:137`（load 签名）
- Modify: `assets/script/game/hero/Mon.ts:265`（挂载点，updateSkillDistanceCache 之后）
- Modify: `assets/script/game/hero/Mon.ts:126`（destroy 移除）
- Modify: `assets/script/game/hero/Mon.ts:358`（reset 对齐）

- [ ] **Step 1: 新增 import**

在 L12 `import { SkillTriggerHelper } from "./SkillTriggerHelper";` 之后插入：

```ts
import { BossPhaseSet } from "../common/config/BossPhaseSet";
import { BossPhaseComp } from "./BossPhaseComp";
```

- [ ] **Step 2: load 签名追加第 8 参**

L137 改为（仅尾部追加 `phase_plan_id: number = 0`）：

```ts
    load(pos: Vec3 = Vec3.ZERO, scale: number = 1, uuid: number = 1001, is_boss: boolean = false, dropToY: number = pos.y, mon_lv: number = 1, laneIndex: number = 0, phase_plan_id: number = 0) {
```

- [ ] **Step 3: 技能表构建完成后挂载组件**

在 L265 `model.updateSkillDistanceCache();` 之后、L267 `// 注册视图组件并重置对象池复用状态` 注释之前插入：

```ts
        // Boss 阶段初始化：P1 = 基线技能，仅挂标记组件并记录方案（方案缺失则退化为单阶段 Boss）
        if (is_boss && phase_plan_id > 0) {
            const plan = BossPhaseSet[phase_plan_id];
            if (plan) {
                const phase = this.add(BossPhaseComp);
                phase.plan_id = phase_plan_id;
                phase.index = 0;
            } else {
                // 配置兜底：引用了不存在的方案，退化为单阶段并告警（不阻断战斗）
                oops.log.warn(`[BossPhase] 阶段方案 ${phase_plan_id} 未在 BossPhaseSet 中定义，Boss 按单阶段战斗`);
            }
        }
```

- [ ] **Step 4: destroy 显式移除组件（触发 reset + 回组件池）**

在 L126 `this.remove(HeroViewComp);` 之前插入（放 HeroAttrsComp 移除前，便于将来清理逻辑读属性）：

```ts
        // 阶段组件显式移除：触发 reset 清空状态并回组件池（ECS 组件无自动销毁钩子）
        if (this.has(BossPhaseComp)) {
            this.remove(BossPhaseComp);
        }
```

- [ ] **Step 5: reset 与 destroy 对齐（防旁路残留）**

L358-360 改为：

```ts
    /** 重置入口：复用 destroy 的释放流程 */
    reset() {
        if (this.has(BossPhaseComp)) {
            this.remove(BossPhaseComp);
        }
        super.destroy();
    }
```

- [ ] **Step 6: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。此时 BossPhaseSystem 尚未创建，组件挂载后无消费方，属预期中间态。

- [ ] **Step 7: Commit**

```bash
git add assets/script/game/hero/Mon.ts
git commit -m "feat: wire BossPhaseComp into monster load/destroy"
```

---

### Task 6: 新建 BossPhaseSystem.ts（检测与切换系统）

**Files:**
- Create: `assets/script/game/hero/BossPhaseSystem.ts`

- [ ] **Step 1: 创建系统文件**

```ts
/**
 * BossPhaseSystem — Boss 多阶段战斗状态机。
 *
 * 检测混合触发条件（血量阈值 OR 在场时长），命中后执行阶段切换：
 *   removes 移除旧技能 → adds 注入新技能（cd 兜底 + 资源预热）→ attr_mod 属性修正
 *   → 空钩子 onPhaseExit/onPhaseEnter（演出后续迭代）→ 广播 GameEvent.BossPhaseChange
 *
 * Why: 独立系统符合 M/V/S 分层；filter 按 BossPhaseComp 过滤，每局 Boss 唯一，开销可忽略。
 *      计时在组件 elapsed（随 reset 归零），避免系统级计数在 per-entity update 中重复累加。
 */

import { Prefab } from "cc";
import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
import { oops } from "../../../../extensions/oops-plugin-framework/assets/core/Oops";
import { smc } from "../common/SingletonModuleComp";
import { GameEvent } from "../common/config/GameEvent";
import { BossPhaseSet, PhaseSwitchDef } from "../common/config/BossPhaseSet";
import { SkillSet } from "../common/config/SkillSet";
import { mLogger } from "../common/Logger";
import { HeroAttrsComp } from "./HeroAttrsComp";
import { BossPhaseComp } from "./BossPhaseComp";

/** 阶段模块调试日志开关 */
const DEBUG = true;

/** 新注入技能缺省 CD（秒），与 Mon.ts 大招注入兜底一致 */
const DEFAULT_ADD_CD = 8;

@ecs.register('BossPhaseSystem')
export class BossPhaseSystem extends ecs.ComblockSystem implements ecs.ISystemUpdate {

    filter(): ecs.IMatcher {
        return ecs.allOf(BossPhaseComp, HeroAttrsComp);
    }

    update(e: ecs.Entity): void {
        const phase = e.get(BossPhaseComp);
        const model = e.get(HeroAttrsComp);
        if (!phase || !model) return;

        // 战斗状态守卫（与 MoveComp/SCastSystem 同款模式）：暂停/未开战不计时
        if (!smc.mission.play || smc.mission.pause) return;
        // 死亡同帧守卫：防死尸换阶段
        if (model.is_dead) return;
        // P3 后不再检测（固定 3 阶段）
        if (phase.index >= 2) return;

        const plan = BossPhaseSet[phase.plan_id];
        if (!plan) return;

        phase.elapsed += this.dt;
        const def = plan.switches[phase.index];

        // 混合触发：任一条件满足即切换（血量实时计算，禁止缓存绝对值——hp_max 在 load 后被外部覆盖）
        const hpPct = model.hp / model.hp_max * 100;
        const hpHit = def.trigger.hp_pct !== undefined && hpPct <= def.trigger.hp_pct;
        const timeHit = def.trigger.time !== undefined && phase.elapsed >= def.trigger.time;
        if (hpHit || timeHit) {
            this.executePhaseSwitch(e, def);
        }
    }

    /**
     * 执行阶段切换：技能增量改写 + 属性修正 + 钩子与事件广播
     * Why 改 skills 而非施法系统过滤：与 _testSkills/RogueConfig.ults 动态注入同模式，
     *      SCastSystem 零改动；施法闭包捕获 SkillSet 静态配置，进行中施法不受影响
     */
    private executePhaseSwitch(e: ecs.Entity, def: PhaseSwitchDef): void {
        const phase = e.get(BossPhaseComp)!;
        const model = e.get(HeroAttrsComp)!;
        const from = phase.index;

        this.onPhaseExit(e);

        // 1. 移除旧技能（仅大招键；普攻首键受键序契约保护，见 BossPhaseSet 文件头注释）
        if (def.removes) {
            for (const s_uuid of def.removes) {
                delete model.skills[s_uuid];
            }
        }

        // 2. 注入新技能（cd 强制兜底，防 undefined → Math.min 结果 NaN 导致大招永不释放）
        if (def.adds) {
            for (const add of def.adds) {
                if (!add || !add.s_uuid || !SkillSet[add.s_uuid]) continue;
                model.skills[add.s_uuid] = {
                    uuid: add.s_uuid,
                    lv: 1,
                    cd: add.cd ?? DEFAULT_ADD_CD,
                    ccd: 0,
                    overrides: add.overrides,
                };
                // 资源预热：新技能 prefab 首次异步加载会丢一发，切换时预载（路径与 Skill.load 对齐）
                oops.res.load(`game/skill/atk/${SkillSet[add.s_uuid].sp_name}`, Prefab);
            }
        }

        // 3. 属性修正：基于当前值链式乘算（P3 基于 P2 修正后的值，配置按此口径）
        const mod = def.attr_mod;
        if (mod) {
            if (mod.ap_pct) model.ap = Math.round(model.ap * (1 + mod.ap_pct / 100));
            if (mod.defense_pct) model.defense = Math.round(model.defense * (1 + mod.defense_pct / 100));
        }

        phase.index++;

        this.onPhaseEnter(e);

        mLogger.log(DEBUG, "BossPhase", `${model.hero_name} 阶段切换 P${from + 1}→P${phase.index + 1}（方案 ${phase.plan_id}）`);

        // 广播阶段切换（payload 用 eid 定位实体，防监听方持有已回收实体裸引用）
        oops.message.dispatchEvent(GameEvent.BossPhaseChange, {
            eid: e.eid,
            planId: phase.plan_id,
            fromPhase: from,
            toPhase: phase.index,
        });
    }

    /** TODO: 阶段退场表现（震屏/变暗等），后续迭代实现 */
    private onPhaseExit(e: ecs.Entity): void { }

    /** TODO: 阶段入场表现（怒吼/无敌帧/技能横幅等），后续迭代实现 */
    private onPhaseEnter(e: ecs.Entity): void { }
}
```

- [ ] **Step 2: 确认系统注册链可达**

`@ecs.register` 装饰器在模块加载时自动注册系统，**唯一要求是模块被 import**。
验证：Task 5 已在 `Mon.ts` import `BossPhaseComp`，但那是组件文件；系统文件需单独确认——
在 `Mon.ts` 的 import 区追加一行（放在 `import { BossPhaseComp } from "./BossPhaseComp";` 之后）：

```ts
import "./BossPhaseSystem";
```

（副作用 import 确保系统模块被加载注册；与框架"装饰器注册即生效"约定一致。）

- [ ] **Step 3: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。
重点确认：`update(e: ecs.Entity)` 签名（框架无 dt 参数）、`this.dt` 可用、`mLogger.log(DEBUG, tag, msg)` 签名与 BuffSystem.ts L39 一致、`e.eid` 属性存在（Mon.ts L120 已有先例）。

- [ ] **Step 4: Commit**

```bash
git add assets/script/game/hero/BossPhaseSystem.ts assets/script/game/hero/Mon.ts
git commit -m "feat: add BossPhaseSystem with phase switch logic"
```

---

### Task 7: RogueConfig.ts 消费阶段方案

**Files:**
- Modify: `assets/script/game/map/RogueConfig.ts:23`（import 区）
- Modify: `assets/script/game/map/RogueConfig.ts:207`（GeneratedMonster 接口）
- Modify: `assets/script/game/map/RogueConfig.ts:390-412`（makeBoss）
- Modify: `assets/script/game/map/RogueConfig.ts:167-189`（validateRogueConfig）
- Modify: `assets/script/game/map/RogueConfig.ts:231-246`（TestModeConfig）
- Modify: `assets/script/game/map/RogueConfig.ts:359-384`（generateTestWave）

- [ ] **Step 1: 新增 import**

在 L24 `import { SkillOverrides, SkillSet } from "../common/config/SkillSet";` 之后插入：

```ts
import { BossPhaseSet, validateBossPhaseSet } from "../common/config/BossPhaseSet";
```

- [ ] **Step 2: GeneratedMonster 接口加字段**

在 L208 `delay?: number;` 之后、L210 `/** 本怪所属批次...` 注释之前插入：

```ts
    /** Boss 阶段方案 id（引用 BossPhaseSet，由 makeBoss 从 heroInfo.phase_ids 随机取一；未配置为 undefined） */
    phase_plan_id?: number;
```

- [ ] **Step 3: makeBoss 读取消费**

L399-411 的 return 对象，在 `skills: { ults: this.pickBossUlts(range, stage) },` 之后追加一行属性：

```ts
            phase_plan_id: this.pickPhasePlan(baseInfo),
```

并在 `pickBossUuid` 方法（L428-434）之后新增私有方法：

```ts
    /** 从 Boss 允许的阶段方案中随机取一（未配置返回 undefined，Boss 退化为单阶段） */
    private pickPhasePlan(baseInfo?: { phase_ids?: number[] }): number | undefined {
        const ids = baseInfo?.phase_ids;
        if (!ids || ids.length === 0) return undefined;
        return ids[Math.floor(Math.random() * ids.length)];
    }
```

- [ ] **Step 4: validateRogueConfig 追加校验**

在 L186 `return errors;` 之前插入：

```ts
    // 校验 Boss 阶段方案表合法性（恰 2 切换点 / trigger 条件 / hp_pct 前缀与递减 / 技能引用）
    for (const err of validateBossPhaseSet()) {
        errors.push(err);
    }

    // 校验 heroInfo.phase_ids 引用的方案存在
    for (const key in HeroInfo) {
        const info = HeroInfo[key];
        if (!info.phase_ids) continue;
        for (const pid of info.phase_ids) {
            if (!BossPhaseSet[pid]) {
                errors.push(`HeroInfo[${key}] phase_ids 引用的方案 ${pid} 未在 BossPhaseSet 中定义`);
            }
        }
    }
```

- [ ] **Step 5: TestModeConfig 加调试开关**

在 L244 `fstart: undefined as TriggerGrouped | undefined,` 之后追加：

```ts
    /** 测试模式：Boss 阶段方案 id（0 = 不启用阶段；需配合 isBoss: true 才会挂载组件） */
    phasePlanId: 0 as number,
    /** 测试模式：是否以 Boss 身份刷出（影响层级/金币/阶段组件挂载） */
    isBoss: false,
```

- [ ] **Step 6: generateTestWave 接通调试开关**

L364-381 的 monsters.push 对象改为（isBoss 与 phase_plan_id 两处变化，其余原样）：

```ts
            monsters.push({
                uuid: TestModeConfig.monUuid,
                type: TestModeConfig.monType,
                hp: TestModeConfig.baseHp,
                ap: TestModeConfig.baseAp,
                isBoss: TestModeConfig.isBoss,
                lv: 1,
                spawnIndex: i,
                batch: 0,
                phase_plan_id: TestModeConfig.phasePlanId || undefined,
                skills: {
                    skill: TestModeConfig.skill,
                    ults: TestModeConfig.ults,
                    atking: TestModeConfig.atking,
                    atked: TestModeConfig.atked,
                    dead: TestModeConfig.dead,
                    fstart: TestModeConfig.fstart,
                },
            });
```

- [ ] **Step 7: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。

- [ ] **Step 8: Commit**

```bash
git add assets/script/game/map/RogueConfig.ts
git commit -m "feat: consume phase plans in boss generation"
```

---

### Task 8: MissionMonComp.ts 接线 + _testSkills 残留修复

**Files:**
- Modify: `assets/script/game/map/MissionMonComp.ts:219-222`（_testSkills 赋值）
- Modify: `assets/script/game/map/MissionMonComp.ts:224`（load 调用）

- [ ] **Step 1: 修复 _testSkills 池化残留（现存 bug）**

L219-222 原代码：

```ts
        // 技能套装注入：通过 _testSkills 通道传递给 Mon.load()
        if (monData.skills) {
            (mon as any)._testSkills = monData.skills;
        }
```

改为（无条件赋值，Boss 死亡回池复用为小怪时不再继承上一个 Boss 的大招）：

```ts
        // 技能套装注入：通过 _testSkills 通道传递给 Mon.load()
        // Why 无条件赋值：实体池复用同一 JS 对象，条件赋值会让复用为小怪的实体残留上一个 Boss 的技能
        (mon as any)._testSkills = monData.skills ?? undefined;
```

- [ ] **Step 2: load 调用追加第 8 实参**

L224 改为：

```ts
        mon.load(spawnPos, scale, monData.uuid, monData.isBoss, landingY, monData.lv, posIndex, monData.phase_plan_id ?? 0);
```

- [ ] **Step 3: 编译验证**

Cocos Creator 编辑器编译，控制台无红色报错。

- [ ] **Step 4: Commit**

```bash
git add assets/script/game/map/MissionMonComp.ts
git commit -m "fix: pass phase plan id and clear stale test skills on reuse"
```

---

### Task 9: 运行时验证（编辑器内）

**Files:**
- 无代码改动（临时改 TestModeConfig 验证后还原）

- [ ] **Step 1: 配置测试模式**

`RogueConfig.ts` TestModeConfig 临时改为：

```ts
export const TestModeConfig = {
    enable: true,
    baseHp: 1000,
    baseAp: 5,
    monType: MonType.MeleeBoss,
    monUuid: 6101,
    spawnCount: 1,
    phasePlanId: 10001,
    isBoss: true,
    // 其余字段保持原样（skill/ults/atking/atked/dead/fstart 均为 undefined）
```

（baseAp 调低避免过快击杀 Boss；baseHp 适中便于打到 70%/40% 阈值。）

- [ ] **Step 2: 运行验证阶段切换**

Cocos Creator 编辑器运行游戏进入战斗，验证：

1. 控制台出现 `[BossPhase] 兽人首领-双刀dps型 阶段切换 P1→P2（方案 10001）`（血量打到 70% 以下时）
2. 继续输出 `P2→P3`（血量 40% 以下或 60 秒后）
3. P3 后无论血量多低不再出现切换日志
4. 切换后 Boss 普攻（6004）仍正常施放（普攻首键未被破坏）
5. 拖过 60 秒验证 time 条件独立生效（用高生存阵容）
6. P2 起 Boss 施放新注入大招 6102（裂气斩）、P3 起 6103（闪电斩），P2 后 6100（寒冰斩，若 RogueConfig 注入过）消失

- [ ] **Step 3: 验证池化复用修复**

击败 Boss 后继续推进关卡刷出普通小怪，验证小怪不再施放 Boss 大招（控制台无异常大招横幅/弹道）。

- [ ] **Step 4: 验证乱序配置拦截（规格 §7.4）**

临时在 BossPhaseSet.ts 中加一个乱序方案：

```ts
    99999: {
        name: "乱序测试",
        switches: [
            { trigger: { time: 30 } },
            { trigger: { hp_pct: 80 } },
        ],
    },
```

在浏览器/编辑器控制台执行 `validateBossPhaseSet()`，确认返回包含
`hp_pct 切换点必须构成前缀` 的错误信息；验证后删除该临时方案。

- [ ] **Step 5: 验证单阶段回归**

TestModeConfig 改回 `phasePlanId: 0` 或换未配置 phase_ids 的 Boss（如 monUuid: 6102），验证行为与现状一致（无阶段切换日志）。

- [ ] **Step 6: 还原测试模式并提交**

TestModeConfig 还原为 `enable: false` 及原始默认值（phasePlanId: 0, isBoss: false 保留新增字段），提交：

```bash
git add assets/script/game/map/RogueConfig.ts
git commit -m "test: verify boss phase switching and pool reuse fix"
```

若验证中修复了任何问题，将修复与验证一并提交并在 commit body 说明。

---

## 完成标准

- [ ] 6101 Boss 在 70%/40% 血量阈值或 60s 时间阈值处依次切换 P1→P2→P3
- [ ] 切换时技能增量生效（removes 消失、adds 按 CD 轮转、attr_mod 攻防修正生效）
- [ ] 普攻全程不受影响（首键契约）
- [ ] 未配置 phase_ids 的 Boss 行为与现状完全一致
- [ ] 对象池复用无状态残留（Boss→小怪不继承技能）
- [ ] 全部任务提交完成，Cocos Creator 编译无报错