zclaw_openfang/docs/archive/removed-features/05-swarm-coordination.md

多 Agent 协作 (Swarm Coordination)

分类: 核心功能 优先级: P1 - 重要 成熟度: L4 - 生产 最后更新: 2026-03-16

---

一、功能概述

1.1 基本信息

多 Agent 协作系统支持多个 Agent 以不同模式协同完成任务，包括顺序执行、并行执行和辩论模式。

属性	值
分类	核心功能
优先级	P1
成熟度	L4
依赖	AgentSwarm, chatStore

1.2 相关文件

文件	路径	用途
UI 组件	desktop/src/components/SwarmDashboard.tsx	协作仪表板
核心引擎	desktop/src/lib/agent-swarm.ts	协作逻辑
状态管理	desktop/src/store/chatStore.ts	dispatchSwarmTask
类型定义	desktop/src/types/swarm.ts	Swarm 类型

---

二、设计初衷

2.1 问题背景

用户痛点:

1. 复杂任务单个 Agent 难以完成
2. 需要多个专业 Agent 协作
3. 协作过程不透明

系统缺失能力:

• 缺乏多 Agent 协调机制
• 缺乏任务分解能力
• 缺乏结果聚合机制

为什么需要: 复杂任务（如代码审查、研究分析）需要多个专业 Agent 的协作才能高质量完成。

2.2 设计目标

1. 多种协作模式: Sequential, Parallel, Debate
2. 自动任务分解: 根据 Agent 能力自动分配
3. 结果聚合: 统一输出格式
4. 过程透明: 实时展示协作进度

2.3 协作模式设计

模式	描述	适用场景
Sequential	链式执行，前一个输出作为后一个输入	流水线任务
Parallel	并行执行，各自独立完成任务	独立子任务
Debate	多 Agent 讨论，协调器综合	需要多视角的任务

2.4 设计约束

• 性能约束: 并行执行需要控制并发数
• 成本约束: 多 Agent 调用增加 Token 消耗
• 时间约束: 辩论模式需要多轮交互

---

三、技术设计

3.1 核心接口

interface SwarmTask {
  id: string;
  prompt: string;
  style: 'sequential' | 'parallel' | 'debate';
  specialists: string[];  // Agent ID 列表
  status: 'planning' | 'executing' | 'aggregating' | 'done' | 'failed';
  subtasks: SubTask[];
  result?: string;
}

interface SubTask {
  id: string;
  specialist: string;
  input: string;
  output?: string;
  status: 'pending' | 'running' | 'done' | 'failed';
}

interface AgentSwarm {
  createTask(prompt: string, style: SwarmStyle, specialists: string[]): SwarmTask;
  executeTask(taskId: string, executor: SwarmExecutor): Promise<string>;
  getHistory(): SwarmTask[];
}

3.2 执行流程

创建任务
    │
    ▼
任务分解 (根据 specialists 能力)
    │
    ├──► Sequential: 按顺序创建 subtasks
    ├──► Parallel: 创建独立 subtasks
    └──► Debate: 创建讨论 subtasks + 协调 subtask
    │
    ▼
执行阶段
    │
    ├──► Sequential: 串行执行，传递中间结果
    ├──► Parallel: 并行执行，各自独立
    └──► Debate: 多轮讨论，直到共识或达到上限
    │
    ▼
结果聚合
    │
    ├──► Sequential: 最后一个 Agent 的输出
    ├──► Parallel: 合并所有输出
    └──► Debate: 协调器综合所有观点
    │
    ▼
完成

3.3 执行器抽象

interface SwarmExecutor {
  execute(agentId: string, prompt: string): Promise<string>;
}

// 实现：使用 chatStore 发送消息
const chatExecutor: SwarmExecutor = {
  async execute(agentId, prompt) {
    return await chatStore.sendMessage(prompt, { agentId });
  }
};

3.4 辩论模式逻辑

async function runDebate(task: SwarmTask, executor: SwarmExecutor) {
  const rounds: DebateRound[] = [];
  let consensus = false;

  for (let i = 0; i < MAX_ROUNDS && !consensus; i++) {
    // 1. 每个 Agent 发表观点
    const opinions = await Promise.all(
      task.specialists.map(s => executor.execute(s, generatePrompt(task, rounds)))
    );

    // 2. 检测共识
    consensus = detectConsensus(opinions);

    rounds.push({ round: i + 1, opinions, consensus });
  }

  // 3. 协调器综合
  return await executor.execute(COORDINATOR_ID, summarizeRounds(rounds));
}

---

四、预期作用

4.1 用户价值

价值类型	描述
效率提升	并行处理加速任务完成
质量提升	多视角分析提高决策质量
能力扩展	复杂任务也能处理

4.2 系统价值

价值类型	描述
架构收益	可扩展的协作框架
可维护性	执行器抽象解耦
可扩展性	支持新的协作模式

4.3 成功指标

指标	基线	目标	当前
任务成功率	70%	95%	92%
平均完成时间	-	优化	符合预期
结果质量评分	3.5/5	4.5/5	4.2/5

---

五、实际效果

5.1 已实现功能

• Sequential 模式
• Parallel 模式
• Debate 模式
• 自动任务分解
• 结果聚合
• 历史记录
• UI 仪表板
• 状态实时展示

5.2 测试覆盖

• 单元测试: 43 项 (swarm-skills.test.ts)
• 集成测试: 包含完整流程测试
• 覆盖率: ~90%

5.3 已知问题

问题	严重程度	状态	计划解决
辩论轮数可能过多	中	已限制	-
并发控制不够精细	低	待处理	Q2

5.4 用户反馈

协作模式灵活，适合复杂任务。UI 展示清晰。

---

六、演化路线

6.1 短期计划（1-2 周）

• 添加更多协作模式（投票、竞标）
• 优化并发控制

6.2 中期计划（1-2 月）

• 可视化协作流程图
• 中间结果干预

6.3 长期愿景

• 跨团队协作
• 动态 Agent 调度

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否需要支持人工干预中间结果？
2. 如何处理 Agent 之间的依赖关系？

7.2 创意想法

• 竞标模式：Agent 竞争执行任务
• 拍卖模式：根据 Agent 忙闲程度分配任务
• 学习模式：根据历史表现动态调整分配

7.3 风险与挑战

• 技术风险: 并发控制和错误处理
• 成本风险: 多 Agent 调用增加成本
• 缓解措施: 并发限制、成本估算