MiguDelay 架构 09：TaskOrchestrator 编排

MiguDelay（DDLive）项目架构系列文档：TaskOrchestrator 编排。内容基于 2026-08-04 对指定重构分支的源码扫描结果整理。

发表于 2026/08/05

作者 李正博

3 分钟阅读

系列导航：系列总览 · 上一篇：MiguDelay 架构 08：TaskSession 状态机 · 下一篇：MiguDelay 架构 10：Gateway 与 TaskHandle 兼容边界

扫描基线

项目：MiguDelay（DDLive）

分支：refactor/video-frame-provider

HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908

工作树：clean

扫描日期：2026-08-04

说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 职责

TaskOrchestrator 组织工作区、流探测、收流、录制、首帧、推流、失败清理、重启、停止屏障和 shutdown drain。任务 phase 的最终裁决仍在 TaskSession。

2. 依赖

依赖	用途
`TaskSession`	authoritative state machine
`ITaskGateway`	recv/record/push start/stop
`ITaskStartEffects`	配置、工作区、probe、激活和兼容副作用
`PushRetryController`	推流重试窗口
probe epoch token	取消旧探测链

3. 新任务启动

sequenceDiagram
    participant O as TaskOrchestrator
    participant S as TaskSession
    participant E as TaskStartEffects
    participant P as StreamProbe
    participant G as TaskHandleGateway

    O->>S: start identity
    S-->>O: Starting and generation
    O->>E: prepareStart command and generation
    E-->>O: prepared receive requests
    loop each receive request
        O->>E: probeReceive frozen request
        E->>P: async probe
        P-->>O: probe result
        O->>O: verify epoch and generation
        O->>G: startReceive
    end

4. 主收流成功后的推进

校验 generation。
非主 context 只登记。
主 context 必须有 ReceiveReadySnapshot。
prepareRecording(snapshot) 创建视频录制、音频录制和 push request。
emit mainInputReady。
提交 startRecord。
保存 push request。
arm first-frame。
TaskSession::markRunning()。

Running 表示主输入已激活且录制请求已接纳，不等于所有 worker 都已异步成功。

5. 首帧推流

Output delayed video callback
  -> PreviewFrameRouter
  -> FirstFrameTrigger.consume
  -> TaskOrchestrator.firstOutputFrame
  -> TaskHandleGateway.startPush

只有当前 generation 的首个主 DelayedOutput video 能触发。

6. 新任务替换旧任务

保存 m_pendingCommand。
Session beginRestart(nextIdentity) 先分配新 generation。
停止现有 push、record、receive。
barrier 成功后开始 pending start。
barrier 失败进入 Failed。

7. 停止顺序

sequenceDiagram
    participant C as Caller
    participant O as TaskOrchestrator
    participant S as TaskSession
    participant G as TaskHandleGateway

    C->>O: stop command
    O->>O: cancel probe retry and pending start
    O->>S: beginStop
    O->>G: stopPush
    O->>G: stopRecord
    O->>G: stopReceive backups first
    O->>G: stopReceive main last
    O->>S: armStopBarrier tickets
    G-->>O: async results
    O->>S: completeStop

push 先停，record 次之，receive 最后，主输入最后提交。

8. 资源账本

Orchestrator 保存 receive/record/push 资源、stop ticket 映射、pending push restart、当前/待启动命令、主 contextId 和 first-frame gate。这些是流程临时状态，不替代 Session 真值。

9. failure 与 shutdown

failCurrent() 先进入 Failed，再以同一 stop barrier 清理真实资源。beginShutdown() 对 Idle 立即 ready，对其他 phase 复用或创建 stop barrier；terminal 后 emit shutdownReady。

10. 源码证据

src/code/module/playback/orchestration/taskorchestrator.*
src/code/module/playback/orchestration/itaskstarteffects.h
tests/task_start_orchestrator/*