多智能体协作（Multi-Agent Supervisor）

今天，我们将正式踏入 AI 智能体开发的深水区，也是目前工业界最前沿的架构模式：Supervisor 多智能体协作（Multi-Agent Supervisor）。

🧠 范式转移：从"流水线"到"敏捷开发团队"

在目前的单体架构中，我们的节点就像是一条硬连接的工厂流水线：

Planner (画图) -> Coder (干活) -> Tester (质检) -> 退回 Coder

这种架构的致命弱点是：缺乏全局视角的灵活调度。

假如用户只是说："帮我查一下 requests 库的最新版本"，在流水线架构下，依然会傻傻地经过 Planner 去做需求拆解。

而在 Supervisor 架构中，我们引入了一个"主管（项目经理）"。

图的拓扑结构变成了星型（Star Topology）：

1. 所有的需求进来，第一站永远是 Supervisor。
2. Supervisor 纵观全局，决定把任务派发给 Planner、Coder 还是直接出结果 FINISH。
3. 任何一个员工（节点）干完活，必须无条件把成果汇报给 Supervisor。
4. Supervisor 再次评估，决定下一步派给谁。

---

🛠️ 重构第一步：定义"派单契约"与全局状态更新

为了让主管能够发号施令，我们需要对系统底层的状态机（State）进行升级，并为主管打造专属的"输出契约"。

请打开你的主程序代码（建议另存为一个新文件，比如 test_multi_agent.py，保留之前的单体版本作为备份），进行以下基础改造：

1. 升级全局状态 (State)

在原本的 SkillsCreatorState 中，我们需要增加一个字段，用来记录"主管的下一步派单去向"。

class SkillsCreatorState(TypedDict):
    """全局微服务上下文"""
    user_requirement: str
    plan: List[str]
    current_code: str
    current_test_code: str
    messages: Annotated[List[BaseMessage], add_messages]
    execution_logs: Annotated[List[str], operator.add]
    iteration_count: int
    error_message: Optional[str]

    # ✨ 【核心新增】：记录当前是谁在干活，以及下一步该谁干
    next_agent: str

2. 打造主管的"派单印章" (Schema)

在定义 PlannerOutputSchema 和 CoderOutputSchema 的附近，新增一个主管专用的 Pydantic 模型：

class SupervisorOutputSchema(BaseModel):
    """主管节点的输出契约：决定下一步路由"""
    reasoning: str = Field(description="作为项目经理，简要说明为什么做出如下派发决定。")
    next_agent: str = Field(
        description="决定下一步由哪个节点执行。可选值：'planner' (需要拆解复杂需求), 'coder' (需要编写代码或修复Bug), 'tester' (代码已就绪，需要执行沙盒测试), 'FINISH' (任务已圆满完成或无法继续，结束流程)"
    )

3. 初始化主管的"大脑"

就像我们之前绑定 Planner 一样，我们要用这个契约生成一个专门扮演主管的大模型实例。在初始化 LLM 的区域加上：

# 主管大脑：绑定派单契约，温度设为 0（需要它极其理智、不产生幻觉）
supervisor_llm = llm.with_structured_output(SupervisorOutputSchema)

---

不过，为了让前端 UI 能够完美展现"项目经理（Supervisor）"运筹帷幄的炫酷过程，我们需要做几处微调（UI 和导入路径）。

请根据以下 3 个步骤修改你的前端 app.py：

🛠️ 必须修改的 3 个地方

1. 更改后端导入路径

因为你的新架构可能保存在了新文件里（比如 test_multi_agent.py），你需要把 load_graph 里的导入改掉。

@st.cache_resource(show_spinner="正在启动引擎，请稍候...")
def load_graph():
    # ✨ 把 test10 换成你刚才保存多智能体架构的 Python 文件名！
    from test_multi_agent import graph 
    return graph

2. 在 UI 标签中加入"项目经理"

在你的 NODE_LABELS 字典中，加上主管的专属图标和文案，让侧边栏的日志更生动：

NODE_LABELS = {
    "supervisor": "👨‍💼 项目经理调度（Supervisor）",  # ✨ 新增主管节点
    "planner": "📐 架构师规划（Planner）",
    "coder": "💻 程序员开发（Coder）",
    "tools": "🔍 检索资料（Tools）",
    "tester": "🧪 测试员验收（Tester）",
}

3. 拦截并打印主管的"派单决定"

在 running 和 resuming 这两个阶段的 graph.stream 循环里，我们把 Supervisor 的派单动作抓取出来并显示在前端日志里。

找到下面这段代码（在 running 和 resuming 里各有一处）：

for node_name, node_output in event.items():
    label = NODE_LABELS.get(node_name, node_name)
    logs.append(f"**✓** {label}")

把它替换为这段更智能的日志渲染逻辑：

for node_name, node_output in event.items():
    label = NODE_LABELS.get(node_name, node_name)
    logs.append(f"**✓** {label}")

    # ✨ 新增：展示项目经理的派单方向
    if node_name == "supervisor" and "next_agent" in node_output:
        next_tgt = node_output["next_agent"]
        if next_tgt == "FINISH":
            logs.append("   - 🏁 项目经理宣布：项目结项！")
        else:
            logs.append(f"   - ➡️ 决定交由【{next_tgt.upper()}】接手")

            # 原有的 Planner 和 Coder 渲染逻辑保持不变
    elif node_name == "planner" and "plan" in node_output:
        for j, s in enumerate(node_output["plan"]):
            logs.append(f"   - 步骤 {j + 1}: {s}")
    elif node_name == "coder" and node_output.get("current_code"):
        logs.append("   - 代码已生成，等待审核")

        # 原有的 Tester 渲染逻辑 (仅在 resuming 阶段有效)
    elif node_name == "tester":
        err = node_output.get("error_message")
        if err is None:
            logs.append("   - ✅ 测试通过，QA 已向项目经理汇报！")
        else:
            logs.append("   - ❌ 发现 Bug，QA 已向项目经理提交报错工单！")

            log_box.markdown("\n".join(logs))

---

🚀 终极点火

就改这三处！你的前端不需要改任何核心框架逻辑，就能直接适配这套极其先进的星型多智能体架构。

保存好前端代码，去终端重新启动：

streamlit run app.py

在网页里再次输入我们那个经典的"王氏开发框架，图像魔法处理"的需求。

你将在前端网页的执行日志面板里，亲眼看到：

1. 👨‍💼 项目经理调度 -> 派给 PLANNER
2. 📐 架构师规划 -> （结合 RAG 给出正确计划）
3. 👨‍💼 项目经理调度 -> 派给 CODER
4. 💻 程序员开发 -> （可能中间还夹杂着 TOOLS 搜索）
5. ⏸️ 弹出代码审查页面，等待你同意进入沙盒！
6. 同意后... 🧪 测试员验收 -> 汇报给经理 -> 结项！