🎯 今日核心问题

  1. Supervisor 的「派活」到底该是一段提示词,还是一个状态机?
  2. 专家池怎么定义,才能让 Supervisor 选得准又不臃肿?
  3. 怎么从结构上防止它无限循环、重复派活、自己给自己下命令?

📖 精读提纲

【一】调度器的三段式状态机

新手写的 Supervisor 通常是一个 while 循环加一句「请决定下一步派给谁」,结果 80% 的运行会陷入三种坏循环:反复派同一个专家、派完之后不知道该收工、专家失败就重派直到爆预算。解法是把「决定」这件事夹在确定性代码之间,形成固定三段:

这个结构的价值在于:循环控制在代码里,模型只负责「这一次派谁」。模型再怎么幻觉,也幻觉不出第 9 轮。

【二】专家池:能力卡 + 输入契约 + 自主完赛

Supervisor 要选专家,靠的不是专家的实现,而是专家的能力卡:一句话干什么、需要什么输入、产出什么、什么时候不该用它。三行字,写不出三行字的专家不要放进池子。能力卡里最重要的一行是「不该用它的时候」——负样本描述能显著降低误派率。

专家必须自主完赛:拿到任务描述后自己跑完(内部可以是 W3 的 ReAct 或 Plan-and-Execute),只向 Supervisor 交一份 SubTaskResult。绝不允许专家执行到中途回头问 Supervisor「下一步呢」——那会让 Supervisor 变成排队器,也是上下文爆炸的源头。

【三】共享状态:只存事实,不存对话

SupervisorState 里应该只有三类东西:原始目标、已完成子任务的压缩摘要列表、每个专家的调用次数与结果。不要存任何对话历史。你的目标是把 Supervisor 每一轮的输入 token 稳定在 1500-2500 之间,不随轮数线性增长。做不到这一点,8 轮之后 Supervisor 就会开始忘掉第 1 轮的关键结论——这是多 Agent 系统最常见的质量断崖。

【四】三个必须的护栏

💻 代码示例

以下是可运行的骨架:专家协议、注册表、状态机调度器。注意 Guard 与 finalize 都是确定性代码。

/** 专家协议:能力卡 + 自主完赛 */
public interface SpecialistAgent {
    SpecialistCard card();
    /** 必须在内部跑完整个子任务,不回调 Supervisor */
    SubTaskResult execute(SubTask task);
}

public record SpecialistCard(
        String id,
        String name,
        String capability,      // 一句话能干什么
        String inputSpec,       // 需要什么输入
        String outputSpec,      // 产出格式
        String notFor,          // 什么时候不该用它(负样本)
        int maxCalls) { }
/** 专家池:Spring 自动收集所有 SpecialistAgent 实现 */
@Component
public class SpecialistRegistry {

    private final Map<String, SpecialistAgent> byId = new LinkedHashMap<>();

    public SpecialistRegistry(List<SpecialistAgent> agents) {
        agents.forEach(a -> byId.put(a.card().id(), a));
    }

    public SpecialistAgent get(String id) {
        SpecialistAgent a = byId.get(id);
        if (a == null) throw new IllegalArgumentException("未知专家: " + id);
        return a;
    }

    /** 给 Supervisor 的提示词片段,只暴露能力卡,不暴露实现 */
    public String describeAll() {
        return byId.values().stream()
                .map(a -> {
                    SpecialistCard c = a.card();
                    return "- %s(%s):%s;输入 %s;产出 %s;不要用于 %s"
                            .formatted(c.id(), c.name(), c.capability(),
                                    c.inputSpec(), c.outputSpec(), c.notFor());
                })
                .collect(Collectors.joining("\n"));
    }
}
@Service
@RequiredArgsConstructor
@Slf4j
public class SupervisorOrchestrator {

    private final ChatModel supervisorModel;
    private final SpecialistRegistry registry;
    private final Executor pool;

    private static final int MAX_TURNS = 6;
    private static final int MAX_TOTAL_TOKENS = 120_000;

    public TopologyResult run(String taskId, String objective) {
        SupervisorState st = SupervisorState.fresh(taskId, objective);
        ObjectMapper om = new ObjectMapper();

        while (!st.finished()) {
            // 护栏一:轮数与预算
            if (st.turns() >= MAX_TURNS || st.totalTokens() > MAX_TOTAL_TOKENS) {
                log.warn("预算耗尽 task={} turns={} tokens={}", taskId, st.turns(), st.totalTokens());
                break;
            }

            // Plan:模型只决定本轮派谁
            String raw = supervisorModel.chat(buildPrompt(st));
            Dispatch d = parseOrFinish(raw, st, om);
            if (d == null) break;                       // 模型明确 FINISH

            // Guard:确定性校验,不通过则拒派并把原因回灌
            Optional<String> reject = guard(d, st);
            if (reject.isPresent()) {
                st.rejectWith(reject.get());
                continue;
            }

            // 执行:可并行的 fan-out
            List<SubTask> batch = d.tasks();
            List<CompletableFuture<SubTaskResult>> fs = batch.stream()
                    .map(t -> CompletableFuture.supplyAsync(
                            () -> registry.get(t.agent()).execute(t), pool))
                    .toList();
            CompletableFuture.allOf(fs.toArray(CompletableFuture[]::new)).join();

            // Reduce:只压摘要,不搬上下文
            for (CompletableFuture<SubTaskResult> f : fs) {
                SubTaskResult r = f.join();
                st.record(r, Integer.parseInt(String.valueOf(r.tokensUsed())));
            }
            st.nextTurn();
        }

        // 收尾必产出,正常与降级都走这里
        String answer = finalize(st);
        return new TopologyResult(answer, st.degraded() ? "SUPERVISOR_DEGRADED" : "SUPERVISOR");
    }

    private Optional<String> guard(Dispatch d, SupervisorState st) {
        if (d.tasks().size() > 3) return Optional.of("一次最多派 3 个专家");
        for (SubTask t : d.tasks()) {
            if (st.calls(t.agent()) >= registry.get(t.agent()).card().maxCalls())
                return Optional.of("专家 " + t.agent() + " 已达调用上限");
            if (st.seenSignature(t.signature()))
                return Optional.of("该任务已执行过(幂等命中),请换角度或收尾:" + t.signature());
        }
        return Optional.empty();
    }

    private String finalize(SupervisorState st) {
        return supervisorModel.chat("""
                根据以下已完成子任务结果,直接输出最终答案。
                若信息不足以完全满足目标,先给可用部分,再单列一行「待确认」写缺口。
                不要复述过程。

                目标:""" + st.objective() + """

                结果:
                """ + st.compressedDigest());
    }
}

✏️ 今日动手

搭一个最小可跑的 Supervisor:3 个专家(researcher 联网检索、analyst 做数据计算、writer 出稿),能力卡各写三行(含「不该用它」)。要求:① 故意让 Supervisor 重复派同一个任务,验证 guard 的幂等拦截生效并打印拒绝原因;② 打印每一轮 Supervisor 的输入 token 数,确认它不随轮数线性增长;③ 把 MAX_TURNS 调成 2,验证系统会走降级收尾而不是抛异常。

🔖 明日预告

调度器只解决了「谁做」,没解决「怎么把东西交过去」。明天讲 Agent 间通信:任务信封长什么样、上下文该传原文还是摘要、并行分支的结果怎么合并才不丢关键信息。