AI Agent 编排测试：调度、重试、状态持久化与多 Agent 一致的框架层验证

编排器的职责：
  ① 生命周期：pending → running → succeeded / failed / cancelled
  ② 调度：任务依赖顺序、并行任务、超时
  ③ 重试：失败重试、退避、最大次数、死信
  ④ 状态持久化：每步快照、断点恢复
  ⑤ 并发隔离：多 Agent 并行不串状态
  ⑥ 可观测：步级日志、指标、结果回溯

状态：PENDING → RUNNING → SUCCEEDED / FAILED / CANCELLED / TIMED_OUT
迁移矩阵（表驱动）：
  - 正常完成：RUNNING → SUCCEEDED
  - Agent 抛错：RUNNING → FAILED（或进入重试）
  - 取消：RUNNING/PENDING → CANCELLED
  - 超时：RUNNING → TIMED_OUT
  - 非法迁移：SUCCEEDED 后再重试 → 拒绝

# 伪代码：生命周期表驱动测试
@pytest.mark.parametrize("from_state,event,expect", [
    ("running", "agent_succeeded", "succeeded"),
    ("running", "agent_failed",    "failed"),
    ("running", "timeout",         "timed_out"),
    ("running", "cancel",          "cancelled"),
    ("pending", "cancel",          "cancelled"),
    ("succeeded", "retry",          "illegal"),     # 终态不可再动
    ("cancelled", "agent_succeeded", "illegal"),
])
def test_lifecycle_transition(from_state, event, expect):
    orc = Orchestrator(start_state=from_state)
    outcome = orc.handle(event)
    assert outcome == expect

防误用测试：
  - 重复启动同一任务 → 拒绝（幂等启动）
  - 对已结束任务再注入事件 → 忽略
  - 并发修改状态 → 加锁/乐观锁拒绝

调度语义测试：
  - 串行依赖：A 完成后才启动 B
  - 并行就绪：无依赖的任务同时启动
  - 条件分支：满足条件才走分支节点
  - 汇合（Join）：多个前置完成后才继续
  - 失败传播：前置失败时下游按配置跳过/告警/也失败

# 伪代码：DAG 调度测试
def test_parallel_after_dependency():
    graph = dag({"A": [], "B": ["A"], "C": ["A"]})   # B、C 依赖 A
    events = run_orchestrator(graph, fake_agents={...})
    # A 启动后 B、C 才可启动
    assert events.order.index("A") < events.order.index("B")
    assert events.order.index("A") < events.order.index("C")
    # B、C 可并行（在 A 完成后都立即运行）
    assert "B" in events.parallel_with("C")

并发控制测试：
  - 最大并行度：并发 Agent 数不超过配置上限
  - 排队：超出并发上限的任务正确排队
  - 优先级：高优先级任务插队
  - 饥饿：低优先级不永久饿死

重试测试场景：
  - 瞬时失败 → 按退避重试 → 成功
  - 达到最大次数 → 标记失败/死信
  - 退避是否指数递增、是否带 jitter（防风暴）
  - 幂等重试：重试不产生重复副作用

# 伪代码：重试与退避测试
def test_retry_then_success():
    agent = FlakyAgent(fail_first=2)          # 前两次失败
    orc = Orchestrator(retry={"max": 5, "backoff": [1, 2, 4]})
    result = orc.run(agent, task)
    assert result.succeeded
    assert agent.invocations == 3              # 失败 2 次 + 成功 1 次
    assert delays == [1, 2]                     # 退避正确递增

def test_max_retry_deadletter():
    agent = AlwaysFailAgent()
    orc = Orchestrator(retry={"max": 3})
    result = orc.run(agent, task)
    assert result.status == "deadletter"        # 超限进死信

幂等验证：
  - 同一步被重复执行 → 副作用只发生一次
  - 用「步 ID + 结果缓存」实现：已成功的步返回缓存结果
  - 副作用工具（发通知/写库）在重试时不被二次调用

fake Agent 记录调用：
  step_done(cache) → 第二次请求该步直接返回缓存，不重新执行

超时测试：
  - 单步超时：Agent 长时间无响应 → 该步超时 → 走失败/重试
  - 整体超时：总执行时长超限 → 强制终止
  - 终止后清理：终止后 Agent 的进程/连接被释放
  - 半途超时恢复：超时后状态机进入「可恢复」而非「僵尸」

持久化设计：
  每步完成后持久化「任务状态 + 中间结果」到存储
  崩溃 → 重启 → 从最后一个快照恢复，续跑而非重跑

测试场景：
  - 步骤中崩溃：恢复后从该步重跑（不重跑已成功的步）
  - 步骤间崩溃：恢复后继续下一步
  - 重复崩溃：多次恢复后仍正确（快照不损坏）
  - 快照一致性：恢复后的状态与崩溃前一致

# 伪代码：断点恢复测试
def test_resume_after_crash():
    orc = Orchestrator(persist=True)
    state = orc.start(task)
    # 在第 3 步制造崩溃
    orc.crash_at(step=3)
    orc2 = Orchestrator.restore(state.checkpoint)   # 恢复
    result = orc2.continue_run()
    assert result.succeeded
    assert orc2.executed_steps == [3, 4, 5]          # 只续跑未完成步
    assert orc2.executed_steps != [1, 2, 3, 4, 5]     # 未重跑已完成步

- 快照版本：旧版本快照被新代码恢复 → 兼容或明确拒绝
- 恢复时上下文完整：Agent 的对话上下文/中间结果不丢
- 并发恢复：同一任务被两实例恢复 → 只有一个继续（锁）

# 伪代码：并行隔离测试
def test_parallel_agents_isolated():
    agent_a = RecordingAgent()
    agent_b = RecordingAgent()
    run_in_parallel([(agent_a, task_x), (agent_b, task_y)])
    # A 只看到 task_x 的上下文，B 只看到 task_y 的
    assert task_y not in agent_a.observed_context
    assert task_x not in agent_b.observed_context

隔离验证点：
  - 上下文隔离：每 Agent 独立会话，不共享
  - 变量/工具状态隔离：并行任务不踩同一份可变状态
  - 全局资源竞争：共享资源（限流器/连接池）不互相饿死
  - 失败隔离：一个 Agent 失败不影响其他并行 Agent

- 汇总顺序：结果按任务 ID 而非完成顺序汇总（确定性）
- 重复结果去重：同一结果不重复计入
- 汇总完整性：所有成功 Agent 的结果都被收集

可观测断言：
  - 步级日志：每步开始/结束/耗时/结果都有结构化日志
  - 指标：成功/失败/重试次数、执行时长分布、并发度
  - 追踪：一次编排的完整执行链可回溯（trace_id）
  - 结果回溯：给定编排 ID 可查询每一步的输入输出

补偿/回滚测试：
  - 编排失败 → 按逆序执行补偿动作（类似 Saga）
  - 补偿幂等：补偿动作可重复执行不重复影响
  - 补偿失败 → 升级人工（半补偿状态可标识）
  - 只读步不补偿：只有副作用步才需要补偿