Lead Agent：任务拆解与子 Agent 分发

┌──────────────────────────────────────────────────────┐
│                     Lead Agent                       │
│                                                      │
│  ① 拆解：目标 → 任务树 / DAG                          │
│  ② 分派：按能力与负载路由到子 Agent                    │
│  ③ 监督：超时、失败、越级上报                          │
│  ④ 汇总：合并结果、裁决冲突、验收                      │
│  ⑤ 负责：对用户交付最终结果                            │
└──────────────────────────────────────────────────────┘

目标：给现有后台增加"订单导出 PDF"功能
│
├── T1 调研（可并行）
│   ├── T1.1 找到现有订单列表与详情接口
│   └── T1.2 确认 PDF 生成库与字体方案
│
├── T2 设计（依赖 T1）
│   └── T2.1 输出接口契约与页面交互说明
│
├── T3 实现（依赖 T2，可并行）
│   ├── T3.1 后端导出接口
│   ├── T3.2 前端导出入口与进度态
│   └── T3.3 模板与排版
│
└── T4 验收（依赖 T3）
    ├── T4.1 单测与集成测试
    └── T4.2 人工验收清单

太小：调度开销 > 执行成本，汇总成本爆炸
太大：Worker 上下文膨胀，失败重试代价高
合适：一个子任务 = 一个明确产物 + 一组相关工具调用

interface TaskHandoff {
  taskId: string;
  goal: string; // 一句话目标
  acceptance: string[]; // 验收标准，可逐条检查
  inputs: {
    files?: string[]; // 相关文件路径，不是全量仓库
    facts?: Record<string, string>; // 已确认的事实
    constraints?: string[]; // 技术栈、规范、禁用项
  };
  outputSchema: JSONSchema; // 产物结构
  deadlineMs: number;
  dependsOn: string[];
}

Lead
 │
 ├─ 能力匹配 ──→ 候选 Agent 列表
 │                   │
 ├─ 负载过滤 ──→ 当前队列最短的
 │                   │
 ├─ 历史成功率 ─→ 同类任务成功率最高的
 │                   │
 └──────────────→ 分派 + 记录 trace

冲突 → 是否可机器判定？
         ├─ 是 → 按规则裁决（依赖/置信度/历史）
         └─ 否 → 评审 Agent 给出理由与建议
                    └─ 仍不确定 → 升级人工

Worker 执行
   │
   ├─ 正常完成 ──────────────→ 返回结果
   ├─ 可自愈错误 ──→ 重试 ──→ 仍失败 ─┐
   ├─ 需要决策 ───────────────────────┤
   └─ 卡死/超时 ──────────────────────┤
                                       ▼
                              Lead 重新规划
                                 ├─ 重派给其他 Worker
                                 ├─ 拆成更小任务
                                 ├─ 降级方案
                                 └─ 升级人工

任务层：成功率、平均完成时间、重派率、越级上报率
Agent 层：单任务步数、工具误调用率、上下文峰值、token 成本
系统层：队列长度、并发数、超时率、人工接管率
质量层：一次验收通过率、返工率、用户满意度

成本 ≈ Σ(子任务数 × 平均上下文 × 轮次 × 单价) + Lead 开销 + 汇总开销

// 极简 Lead Agent：拆解 → 拓扑调度 → 校验 → 汇总
type Task = {
  id: string;
  goal: string;
  deps: string[];
  status: "pending" | "running" | "done" | "failed";
  result?: unknown;
  retries: number;
};

async function runLead(goal: string) {
  const tree = await planner.decompose(goal); // 输出 Task[]

  while (tree.some((t) => t.status === "pending" || t.status === "running")) {
    // 1. 找出依赖已完成的 ready 任务
    const ready = tree.filter(
      (t) =>
        t.status === "pending" &&
        t.deps.every((d) => tree.find((x) => x.id === d)?.status === "done"),
    );

    // 2. 并行执行，控制在并发上限内
    await runWithConcurrency(ready, 3, async (task) => {
      task.status = "running";
      const agent = router.pick(task); // 能力 + 负载 + 历史成功率
      try {
        const output = await agent.run(buildHandoff(task, tree));
        const check = validator.check(task, output);
        if (!check.ok) throw new Error(check.reason);
        task.result = output;
        task.status = "done";
      } catch (err) {
        task.retries += 1;
        if (task.retries >= 3) {
          task.status = "failed";
          await escalator.escalate(task, err); // 重派 / 拆小 / 降级 / 人工
        } else {
          task.status = "pending";
        }
      }
    });
  }

  const failed = tree.filter((t) => t.status === "failed");
  if (failed.length) return synth.partial(tree, failed);

  return synth.merge(tree); // 合并 + 冲突裁决
}

         T1 调研
        /       \
   T1.1 接口   T1.2 PDF 方案
        \       /
         T2 设计（依赖 T1.1 与 T1.2）
              │
      ┌───────┴───────┐
   T3.1 后端       T3.2 前端
      └───────┬───────┘
           T4 验收

一个叶子任务应满足：
1. 产物唯一：能写成一个文件 / 一份报告 / 一个补丁
2. 工具可控：5-15 次工具调用可完成
3. 可验收：验收标准能逐条机器或人工检查
4. 可回滚：失败时不影响已完成的其他节点
5. 依赖显式：前置节点全部写在 dependsOn 里

interface TaskHandoff {
  taskId: string;
  goal: string;
  acceptance: string[];
  inputs: {
    files?: string[];
    facts?: Record<string, string>;
    constraints?: string[];
    artifactRefs?: string[]; // 上游产物在对象存储中的引用
  };
  outputSchema: JSONSchema;
  deadlineMs: number;
  dependsOn: string[];
  owner: string; // 唯一责任人，移交不换 owner
  idempotencyKey: string; // 写操作去重
  budget: { maxTokens: number; maxToolCalls: number };
}

候选 Agent
   │
   ├─ 能力过滤：标签必须覆盖任务所需技能
   ├─ 负载过滤：当前队列长度 / 并发上限
   ├─ 历史成功率：同类任务最近 N 次成功率
   └─ 熔断状态：连续失败超阈值的 Agent 暂时摘除
        │
        ▼
   打分 = w1·能力匹配 + w2·(1-负载) + w3·历史成功率

async function dispatchWithRetry(task: Task, agent: Agent) {
  // 1. 重派前先查状态，不要盲目重试
  const existing = await store.getByKey(task.idempotencyKey);
  if (existing?.status === "done") return existing.result;

  // 2. 写操作带幂等键，下游按 key 去重
  const result = await agent.run(buildHandoff(task), {
    idempotencyKey: task.idempotencyKey,
    deadlineMs: task.deadlineMs,
  });

  // 3. 校验通过的产物才落库
  const check = validator.check(task, result);
  if (!check.ok) throw new Error(check.reason);
  await store.save(task.idempotencyKey, { status: "done", result });
  return result;
}

Worker 执行
   ├─ 正常完成 ───────────────→ 返回结果
   ├─ 可自愈错误 ─→ 重试 ─→ 仍失败 ─┐
   ├─ 需要更高权限 ──────────────────┤
   ├─ 任务前提不成立 ────────────────┤
   ├─ 多方案代价接近，无法自主决策 ──┤
   └─ 连续失败达阈值 ────────────────┤
                                     ▼
                            Lead 重新规划
                               ├─ 重派给其他 Worker
                               ├─ 拆成更小任务
                               ├─ 降级方案
                               └─ 升级人工