案例二 · 传送的 cmd

把一次传送拆成一条阶段链，每个阶段只负责自己的成败。 传送比场景加载更「动态」：随时可能被新请求抢占、被打断、要能中途让位。 于是它在命令框架上做了两层包装——阶段命令基类的四个出口解决「单阶段怎么收口」， 轮次令牌解决「迟到异步怎么判断自己还算不算数」。 本案例看的就是这套「阶段化 + 轮次隔离」怎么和 CommandExecutor 拼在一起。

1. 传送为什么适合用命令组织

一次传送天然是有阶段、有前置条件、可被打断的长流程：校验 → 吟唱 → 上升遮挡 → 发包 → 流送 → 落地 → 收尾。 每一步都可能「成功继续」「主动让位」「失败还原」「致命终止」——这正是命令框架擅长的模型。 传送的做法是把每个阶段包成一条阶段命令，串到同一个 executor 上，再由流程在外部持有 executor 的句柄以便随时取消。

2. 两套实现

3. TeleportCommandBase：约定四个出口

阶段命令统一继承 TeleportCommandBase<T>。它只做一件事：把「阶段名 + 日志前缀」和「四个收口出口」固定下来。

export abstract class TeleportCommandBase<T extends CommandContextBase> extends CommandBase<T> {
    protected abstract get StageName(): string;
    protected get StageLogPrefix(): string { return `传送-阶段[${this.StageName}]`; }

    protected Complete(): void  { if (Executing) this.Succeed(); }                       // 阶段完成，进下一阶段
    protected Skip(reason): void { if (Executing) this.Bail(`${StageLogPrefix} 主动跳过：${reason}`); }  // 主动退出（预期内）
    protected Abort(reason): void { if (Executing) this.Fail(`${StageLogPrefix} 失败：${reason}`); }   // 失败，触发还原
    protected FatalError(reason): void { if (Executing) this.Fatal(...); }               // 致命错误
}

四个出口都先判 GetState() === Executing 才结算，作用是防止迟到回执重复收口——阶段被取消后，晚到的技能完成回调再进来也不会二次结算。

4. 经典阶段命令一览

5. 上下文与轮次令牌

阶段命令之间要共享状态，靠的是 TeleportCmdContext（泛型 T 的具体化）：

export class TeleportCmdContext extends CommandContextBase {
    public TeleportType = ETeleportType.SeamlessLevel;
    public Param = 0;                                   // 传送参数，如传送点实体配置 Id
    public IsLocalPlayer = true;                          // 是否本地主控玩家
    public Flow: ITeleportStageFlow | undefined = undefined;   // 受限的流程访问面
    public Round: TeleportRoundToken | undefined = undefined; // 本轮身份令牌
}

其中两个类型是本案例的核心：

• ITeleportStageFlow：命令能调用的流程能力清单（RegisterStageCancel / PlayUpSkill / OpenEntryCoverForStage / BeginStreaming / AwaitDownLanding / IsRoundValid / FinishTeleportFlow …）。 命令只依赖接口，不依赖 TeleportTransitionFlow 具体实现——这是它能在两套流程里复用的原因。
• TeleportRoundToken：一轮传送的身份令牌，{ Cancelled = false }。命令在异步等待前抓一份 capturedRound = context.Round，回执到达后用 flow.IsRoundValid(capturedRound) 判断自己还算不算当前轮；不成立就 Skip 让位。这就是「迟到异步的归属判据」。

TeleportCmdContext.OnDispose() 会把 Flow 与 Round 置空——整条链执行完、上下文释放时，不留悬挂引用。

6. 简化分段：现场编排一个 CommandExecutor

普通表现层不走六阶段那条长链，而是按 Down / Load / Seamless 三段临时组装短链。 分段类型定义在 TeleportSimplifiedCmd 里：

export type TTeleportSimplifiedStage = 'Down' | 'Load' | 'Seamless';

export class TeleportSimplifiedAssembler {
    public static BuildCommands(stage: TTeleportSimplifiedStage) {
        switch (stage) {
            case 'Load':   return [new TeleportSimplifiedCoverCmd(), new TeleportSimplifiedStreamingCmd()];
            case 'Down':   return [new TeleportSimplifiedExitCmd()];
            default:         return [new TeleportSeamlessStartCmd()];
        }
    }
}

这段短链的基类 TeleportSimplifiedCmd 把「四出口」进一步简化成「执行 → 判成败」： 子类只管实现 ExecuteStage()（返回 boolean 或 Promise<boolean>），基类负责收口—— 轮次已取消 → Skip；阶段未完成 → Skip（阶段中断）；完成 → Complete；抛异常 → Abort。

真正创建并驱动 executor 的地方是 TeleportTransitionFlow.RunSimplifiedStage()：

private async RunSimplifiedStage(context: TeleportSimplifiedCmdContext, stage: TTeleportSimplifiedStage): Promise<boolean> {
    if (!context.IsCurrent()) return false;
    const executor = new CommandExecutor<TeleportSimplifiedCmdContext>();
    executor.Init(
        context,
        `传送-普通阶段-${stage}`,
        false,
        TeleportTransitionFlow.EnterSeqBackstopTimeoutMs,   // 40s 兜底超时
        false,
        true,
    );
    for (const command of TeleportSimplifiedAssembler.BuildCommands(stage)) {
        executor.AddInitCommand(command);
    }
    this.SimplifiedExecutor = executor;
    let completed = false;
    try {
        await executor.Execute((result) => {                 // 终态回调：先结算，再决定整轮走向
            if (this.SimplifiedExecutor === executor) this.SimplifiedExecutor = undefined;
            if (!context.IsCurrent()) return;
            completed = result === ECommandExecutorResult.Success;
            if (completed) { if (stage === 'Seamless') this.OnEnd(); return; }
            this.FinishEnterSeqWait(false);
            this.InvalidateFlow();                          // 中断：作废本轮流送与 executor
        });
    } catch (error) { /* 记录 + FinishEnterSeqWait(false) + InvalidateFlow() */ }
    finally {
        executor.RemoveExpireTime();                       // 正常结束就撤掉兜底超时
        if (this.SimplifiedExecutor === executor) this.SimplifiedExecutor = undefined;
    }
    return completed;
}

源码注释点破了这段的关键顺序：「执行器终态先结算，再同步通知无缝上层结束，避免 OnEnd 把自身取消成 Bail。」 ——所以回调里第一件事是把 SimplifiedExecutor 引用清掉，防止后续 OnEnd 触发 InvalidateFlow 时又把自己取消掉。

取消整轮的收口在 InvalidateFlow()：

private InvalidateFlow(): void {
    this.FlowGeneration.Cancelled = true;                 // 旧令牌作废
    this.FlowGeneration = new TeleportRoundToken();       // 换新令牌，旧令牌永不复用
    const executor = this.SimplifiedExecutor;
    const context = this.SimplifiedContext;
    this.SimplifiedExecutor = undefined;
    this.SimplifiedContext = undefined;
    context?.FinishStreamingWait(false);             // 兑现挂起的流送等待
    executor?.CommandBail();                            // 立刻终止分段 executor
}

7. 这个案例的五个关键点