从“单兵作战“到“团队协作“——解析 JiuwenSwarm 的 Team Agent 多智能体架构

JiuwenSwarm 基于 openJiuwen 框架实现了多 Agent 协作机制：Leader 负责任务调度，Teammate 负责并行执行，技能可继承，任务全程可监控。本文深入解析这套机制的设计思路与核心实现。

一、为什么需要多 Agent

用 AI Agent 处理简单任务，体验通常不错。但当任务的复杂度上来之后，单智能体架构的短板就会暴露得比较明显。

一个典型场景是长链条任务。假设你需要 AI "整理本月所有发票，提取关键信息，汇总成 Excel，再发一封邮件通知"------这涉及数据提取、格式转换、文件操作、邮件发送等多个环节，单 Agent 只能串行处理，中间任何一步出错，后续流程就可能中断。如果用户在执行过程中又追加了新需求，线性执行模式也很难灵活应对。

多领域复合任务同样棘手。一个 Agent 同时要操作浏览器、编写代码、管理文件时，上下文膨胀和注意力分散几乎不可避免。

说到底，单个 Agent 的"注意力"、"专业度"、"并发能力"都有明确的天花板。

JiuwenSwarm 的做法是让 Agent 组队。通过内置的 Swarm Agent 机制，一个 Leader Agent 可以动态创建多个 Teammate Agent，各司其职、协同完成复杂任务。这套机制与 JiuwenSwarm 已有的技能自演进、记忆系统、任务规划等能力是打通的，不是孤立的模块。

运行环境

|----------|------------------------------------------------------------------|
| 项目 | 配置值 |
| 操作系统 | Windows 10 / macOS / Linux |
| Python | 3.11 / 3.12 / 3.13 |
| 模型服务 | 华为云 MaaS / OpenAI 兼容接口 / ModelScope 等 |
| 通信渠道 | Web / 飞书 / 钉钉 / 企业微信 / 小艺 / Telegram / Discord / WhatsApp / 个人微信 |
| Agent 框架 | openJiuwen（内置） |

JiuwenSwarm 与 Swarm Agent

openJiuwen 是一个开源的 Agent 开发框架，JiuwenSwarm 是基于该框架构建的智能助手。框架本身提供了模块化技能系统、多智能体协作、技能自演进、记忆与上下文管理、多渠道接入等能力。

Swarm Agent 在此基础上做了几个关键增强：

• 任务 并行：Leader 调度 + 多 Teammate 并行执行，替代单 Agent 的串行模式
• 技能 继承：按角色选择性继承或全量继承主 Agent 的技能，不必重复配置
• 动态扩容：Leader 可按需创建 Teammate，不需要预先定义所有成员
• 全程可观测：12 种事件类型覆盖成员创建、任务进度、成员间消息等关键节点
• 追加交互：用户可以随时注入新指令，不打断正在执行的任务
• 细粒度权限：按成员、按 Channel 控制工具权限

架构总览

核心组件分工：

|--------------------|----------------------------|---------------------------------------------------------------------------------------|
| 组件 | 职责 | 源码位置 |
| TeamManager | 团队生命周期管理（创建/销毁/会话隔离） | agentserver/team/team_manager.py |
| ConfigLoader | 从 config.yaml 加载团队配置并构建规格 | agentserver/team/config_loader.py |
| TeamAgentSpec | 团队规格定义（角色/技能/生命周期） | openjiuwen agent_teams.schema |
| TeamAgent | 运行时团队实例（Leader + Teammate） | openjiuwen agent_teams.agent |
| TeamMonitorHandler | 实时事件监控（成员/任务/消息） | agentserver/team/monitor_handler.py |
| agent_customizer | 成员初始化定制（能力继承/技能复制/工具注册） | team_manager.py 内嵌 |
| SignalDetector | 技能演进信号检测 | openjiuwen agent_evolving |
| TeamHelpers | 流式协作（多请求并发/事件广播） | agentserver/deep_agent/team_helpers.py |

消息从用户到团队的数据流：

二、核心组件实现

2.1 TeamManager：团队生命周期管理

TeamManager 负责团队的创建、销毁、会话隔离和并发控制。它的核心数据结构很直观：

class TeamManager:
    def __init__(self):
        self._team_agents: dict[str, TeamAgent] = {}       # session_id → TeamAgent
        self._team_monitors: dict[str, TeamMonitorHandler] = {}  # session_id → monitor
        self._stream_tasks: dict[str, asyncio.Task] = {}    # session_id → asyncio.Task
        self._lock = asyncio.Lock()

三个字典分别管理团队实例、监控器和后台流式任务，用 session_id 做键。_lock 保证同一 Channel 下不会出现两个 Team 同时创建的竞态条件。

对外暴露的核心方法是 get_or_create_team()，实现了懒加载复用：已有 Team 就复用，没有就新建。新建时会自动清理同 Channel 下其他会话的残留实例：

async def get_or_create_team(self, session_id, deep_agent, ...) -> TeamAgent:
    async with self._lock:
        team_agent = self._team_agents.get(session_id)
        if team_agent is not None:
            return team_agent
        await self._destroy_other_sessions(session_id)
        return await self.create_team(session_id, deep_agent, ...)

值得一提的是，TeamManager 是按 channel_id 隔离的。每个 Channel（飞书、Web、钉钉等）拥有独立的 TeamManager 实例，通过全局注册表 get_team_manager(channel_id) 获取：

_team_managers: dict[str, TeamManager] = {}

def get_team_manager(channel_id: str | None = None) -> TeamManager:
    resolved_channel_id = str(channel_id or "default").strip() or "default"
    manager = _team_managers.get(resolved_channel_id)
    if manager is None:
        manager = TeamManager()
        _team_managers[resolved_channel_id] = manager
    return manager

这是最近一次重构（commit 1380032）中加入的，解决了多 Channel 同时使用 Team 模式时的冲突问题。

2.2 ConfigLoader：团队配置加载

创建 Team 之前，系统需要知道团队的结构。config_loader.py 从 config.yaml 的 team 段加载配置，构建 TeamAgentSpec 兼容的字典：

几个关键的配置项：

|------------------------|---------------|----------------------|
| 配置项 | 说明 | 默认值 |
| team_name | 团队名称 | team |
| lifecycle | 生命周期模式 | persistent |
| teammate_mode | Teammate 构建模式 | build_mode（按需创建） |
| spawn_mode | 进程模式 | inprocess（进程内） |
| leader.member_name | Leader 名称 | team_leader |
| leader.persona | Leader 人设 | 天才项目管理专家，擅长任务分解和团队协调 |
| agents.<role>.skills | 角色技能列表 | 继承全部全局技能 |

每个 Agent 成员默认继承主 Agent 的模型配置，确保团队内使用一致的 LLM 后端：

def _build_default_model_dict(config_base):
    model_config = config_base.get("models", {}).get("default", {})
    model_client_config = model_config.get("model_client_config", {})
    model_request_config = dict(model_config.get("model_config_obj", {}))
    return {
        "model_client_config": model_client_config,
        "model_request_config": model_request_config,
    }

2.3 技能继承机制

这是 Swarm Agent 设计中比较精巧的部分。新的 Teammate 创建时不是从零开始，而是通过 agent_customizer 自动继承主 Agent 的技能和工具。

继承流程分几步走：

技能继承支持两种模式。如果成员在配置中指定了 skills 列表，只复制指定的技能；否则继承全部：

def copy_member_skills(member_skills_dir, *, skills_configured, selected_skills):
    selected_skill_set = set(selected_skills)
    for skill_dir in global_skills_dir.iterdir():
        if not skill_dir.is_dir() or not (skill_dir / "SKILL.md").is_file():
            continue
        if skills_configured and skill_dir.name not in selected_skill_set:
            continue
        dest = member_skills_dir / skill_dir.name
        if not dest.exists():
            shutil.copytree(skill_dir, dest)

能力卡的继承也是自动的。主 Agent 的工具能力卡中标记为可继承的，会被添加到新成员：

inheritable_cards = filter_inheritable_ability_cards(deep_agent)
existing_ability_ids = {card.id for card in agent.ability_manager.list() or []}
for card in inheritable_cards:
    if card.id not in existing_ability_ids:
        agent.ability_manager.add(card)

实际效果是：给主 Agent 安装了"Excel 处理""网页搜索""邮件发送"三个技能后，新创建的 Teammate 会自动拥有这些能力。

2.4 动态团队构建模式

Swarm Agent 支持两种团队构建模式，可以组合使用。

build_mode（按需构建） 是默认模式。Teammate 不是预先创建的，而是 Leader 分析任务后根据需要动态拉起。比如用户说"帮我分析这份数据并写份报告"，Leader 可能先创建一个数据分析的 Teammate 处理数据，再创建一个写作 Teammate 生成报告。适合任务类型不固定的场景。

predefined_members（预定义成员） 在配置中预先定义好团队成员，团队创建时这些成员就已就位：

team:
  predefined_members:
    - member_name: "data_analyst"
      display_name: "数据分析师"
      persona: "擅长数据分析和报表生成"
    - member_name: "code_writer"
      display_name: "代码编写员"
      persona: "擅长编写和调试代码"

适合工作流程固定、角色分工明确的场景。配置加载时会校验 member_name 必填，缺失的成员会被跳过。

2.5 实时事件监控机制

多智能体系统中，了解"谁在做什么、任务到了哪一步"很重要。JiuwenSwarm 通过 TeamMonitorHandler 实现了实时事件监控。

监控的运作方式：

event_types.py 中定义了 12 种事件类型，分三类：

成员事件（team.member）：

|--------------------------|----------|
| 事件类型 | 说明 |
| MEMBER_SPAWNED | 新成员被创建 |
| MEMBER_STATUS_CHANGED | 成员状态变更 |
| MEMBER_EXECUTION_CHANGED | 成员执行状态变更 |
| MEMBER_RESTARTED | 成员被重启 |
| MEMBER_SHUTDOWN | 成员被关闭 |

任务事件（team.task）：

|----------------|-----------|
| 事件类型 | 说明 |
| TASK_CREATED | 新任务被创建 |
| TASK_CLAIMED | 任务被某个成员认领 |
| TASK_COMPLETED | 任务完成 |
| TASK_CANCELLED | 任务被取消 |
| TASK_UNBLOCKED | 任务解除阻塞 |

消息事件（team.message）：

|-------------------|----------|
| 事件类型 | 说明 |
| MESSAGE_P2P | 成员间点对点消息 |
| MESSAGE_BROADCAST | 广播消息 |

这些事件经过 _convert_event_to_dict() 转换后，通过 _broadcast_event() 分发到所有等待的请求队列，前端可以实时展示团队运行状态。

2.6 流式协作与追加交互机制

Swarm Agent 的交互采用流式模式，团队的进展以事件流的形式实时推送给用户。更重要的是，用户可以在团队执行过程中追加新指令。

流程大致是这样的：

代码层面的判断很直接------检查该 session 是否已有流式任务在跑：

async def process_team_message_stream(request, inputs, deep_agent):
    if is_first_request:
        team_agent = await team_manager.get_or_create_team(...)
        monitor_handler = TeamMonitorHandler(team_agent, session_id)
        await monitor_handler.start()
        stream_task = asyncio.create_task(
            _consume_stream_with_query(channel_id, session_id, team_agent, query)
        )
    else:
        await team_manager.interact(session_id, query)

2.7 与已有能力的融合

Swarm Agent 不是孤立的模块，它和 JiuwenSwarm 的核心能力是打通的：

• 技能自演进 ：Teammate 执行技能出错时，SignalDetector 捕获信号，改进建议写入演进记录，下次调用自动加载
• 记忆系统 ：Team 成员可读取主 Agent 的 MEMORY.md、USER.md 等记忆文件，保持对用户偏好的感知
• 定时任务 ：通过 CronRuntimeBridge，Team 成员也可以注册 Cron Tools，在协作中执行定时操作
• 文件发送 ：Teammate 完成文件处理后，通过 SendFileToolkit 将结果直接发送到用户所在的通信渠道
• 工具权限控制 ：通过 owner_scopes 按 Channel + 用户维度控制工具权限（allow/deny/ask），未配置的操作自动拒绝
• 上下文压缩：长对话中的冗余信息自动压缩，保持 Team 成员的上下文精简
• 浏览器工具 ：Teammate 可操控真实浏览器完成网页任务，按 session_id 复用浏览器会话

三、配置与部署

3.1 团队配置

在 ~/.jiuwenclaw/config/config.yaml 中添加 team 配置段即可启用 Swarm Agent 模式。

最小可用配置：

team:
  team_name: "my_team"
  lifecycle: "persistent"
  teammate_mode: "build_mode"
  spawn_mode: "inprocess"

这样配置后，Leader 和 Teammate 使用默认角色，Teammate 按需动态创建，继承全部技能。

进阶配置示例：

team:
  team_name: "project_team"
  lifecycle: "persistent"
  teammate_mode: "build_mode"
  spawn_mode: "inprocess"

  leader:
    member_name: "project_manager"
    display_name: "项目经理"
    persona: "擅长任务分解和项目管理的专家"

  agents:
    leader:
      skills: ["openJiuwen-DeepSearch", "advanced-daily-report"]  # Leader 的技能
    teammate: {}  # Teammate 继承全部技能

  predefined_members:
    - member_name: "data_analyst"
      display_name: "数据分析师"
      persona: "擅长数据清洗、统计分析和可视化"
    - member_name: "doc_writer"
      display_name: "文档编写员"
      persona: "擅长技术文档、报告和公文撰写"

数据存储配置（可选，不配置时默认使用 ~/.jiuwenclaw/agent/team.db）：

team:
  storage:
    type: "sqlite"
    params:
      connection_string: "team.db"  # 相对于 agent_teams_home

3.2 模型配置

Swarm Agent 的模型配置继承自主 Agent，在 config.yaml 的 models 段配置：

models:
  default:
    model_client_config:
      model_name: "qwen-plus"
      client_provider: "openai"
    model_config_obj:
      model: "qwen-plus"
      temperature: 0.7

3.3 Channel 配置

Swarm Agent 可以在任何已配置的 Channel 上使用，无需额外配置。以飞书为例：

channels:
  feishu:
    app_id: "cli_xxxxx"
    app_secret: "xxxxx"
    enabled: true

在数字分身模式下，工具权限的配置示例：

permissions:
  owner_scopes:
    feishu:
      "ou_xxxx":
        defaults:
          "*": "allow"
        tools:
          bash:
            "*": "deny"
            patterns:
              "git status *": "allow"
              "git log *": "allow"
          write:
            "*": "deny"
  deny_guidance_message: "该工具未被授权在数字分身模式下使用。"

3.4 启动服务

pip install jiuwenclaw
jiuwenclaw-init    # 首次初始化
jiuwenclaw-start   # 启动服务

服务启动后，AgentServer 会自动注册 TeamManager，当检测到 team 配置时启用 Swarm Agent 模式。

四、实操演示：多方向并行调研

用一个实际场景走一遍完整流程：用户要求对 AI Agent 的多个方向同时展开深度调研。

4.1 场景说明

用户在 Web 前端发送：

"帮我全面调研一下 AI Agent 的最新进展，我需要了解三个方向：1）主流 Agent 框架的设计对比（LangGraph vs CrewAI vs AutoGen）；2）Agent 通信协议的现状（MCP、A2A、ACP）；3）Agent 在企业场景中的落地案例。每个方向生成一份独立的 Markdown 报告，保存到工作目录。"

这个场景适合 Swarm Agent 的原因很简单：三个方向互相独立，信息源不同，可以并行处理。单 Agent 串行处理大约需要 45 分钟（每个方向约 15 分钟），而且随着信息累积，上下文膨胀会影响后面的调研质量。Swarm Agent 的做法是拆出 3 个 Teammate 各负责一个方向，同时启动 DeepSearch，理论上 15 分钟即可全部完成。

用到的都是 JiuwenSwarm 内置能力：openJiuwen-DeepSearch 技能负责深度搜索，内置文件工具负责保存报告，TeamMonitorHandler 负责实时监控。

4.2 步骤一：启动服务

pip install jiuwenclaw
jiuwenclaw-init    # 首次初始化
jiuwenclaw-start   # 启动服务（all 模式，包含 app 后端 + Web 前端）

服务启动后，浏览器打开 http://localhost:5173 进入 Web 前端界面。

4.3 步骤二：切换到集群模式

在聊天输入框底部的工具栏中，找到左侧的模式切换按钮组（三个并排的按钮），从左到右依次为：

|----------|------------|-----------------|
| 按钮 | 模式 | 说明 |
| 📋（规划模式） | agent.plan | 主动记忆 + 任务规划 |
| ⚙️（智能执行） | agent.fast | 基础 Agent，适合日常对话 |
| 👥（集群模式） | team | 多 Agent 团队协作 |

点击最右侧的"集群模式"按钮（图标为多人头像），将模式切换为 Swarm Agent 模式。

• 如果当前会话没有历史消息，会立即切换。
• 如果已有历史消息，会弹出确认弹窗，提示"切换模式将创建新会话"，点击确认即可。

切换成功后，输入框底部的模式按钮高亮状态会移到"集群模式"上。

4.4 步骤三：发送调研任务

在聊天输入框中输入调研任务：

帮我全面调研一下 AI Agent 的最新进展，我需要了解三个方向：
1）主流 Agent 框架的设计对比（LangGraph vs CrewAI vs AutoGen）
2）Agent 通信协议的现状（MCP、A2A、ACP）
3）Agent 在企业场景中的落地案例
每个方向生成一份独立的 Markdown 报告，保存到工作目录。

按 Enter 或点击输入框右侧的发送按钮（向上箭头图标）发送消息。

4.5 步骤四：观察团队运行

消息发送后，系统进入 Swarm Agent 模式。在聊天区域右侧会显示团队面板，包含两个区域：

团队成员面板（TeamArea）：

• 显示团队中所有成员的列表
• 每个成员前有一个状态圆点，颜色含义：

• • 🟢 绿色：就绪（ready）
  • 🟡 黄色：忙碌（busy）
  • 🔵 蓝色：重启中（restarting）
  • 🟠 橙色：关闭请求中（shutdown_requested）
  • ⚪ 灰色：已关闭（shut_down）
  • 🔴 红色：错误（error）

• 如果成员正在执行任务，会显示**"执行中: xxx"**的任务描述
• 每个成员右侧显示状态更新时间

初始状态：可以看到 Leader（team_leader）被创建。随后 Leader 分析任务，动态创建 3 个 Teammate（如 framework_researcher、protocol_researcher、enterprise_researcher），成员列表会实时更新。

任务事件面板（TeamTaskEvents）：

• 显示团队任务的实时事件日志
• 每条事件包含：任务 ID、事件类型（如 created、claimed、completed）、时间戳
• 随着调研推进，可以看到任务被创建 → 被成员认领 → 执行中 → 完成的完整生命周期

4.6 步骤五：追加新方向

调研进行到第 5 分钟左右，可以在输入框中直接追加减指令：

再帮我加一个方向，Agent 的安全与对齐问题也调研一下。

在集群模式下，直接在输入框输入并发送即可。消息会通过追加交互路径注入正在运行的 TeamAgent，Leader 收到后动态创建新的 Teammate 处理，不影响其他正在执行的成员。

此时观察团队成员面板，可以看到第 4 个成员被创建并开始执行。

可以看到team-leader会实时监控成员的运行状态，给出及时的提醒，并且会实时给我们汇报进度

4.7 步骤六：查看结果

调研完成后：

1. 聊天区域：Leader 会汇总所有调研结果，展示最终输出

1. 团队成员面板：所有成员状态变为 🟢 就绪，随后变为 ⚪ 已关闭
2. 工作目录：报告文件已保存

工作目录中最终生成的文件：

workspace/session/sess_research/
├── Agent框架对比分析.md          # LangGraph vs CrewAI vs AutoGen
├── Agent通信协议技术对比.md       # MCP / A2A / ACP
├── Agent企业落地案例.md           # 企业应用实践
├── Agent安全与对齐.md            # 追加的安全方向
└── todo.md                      # 任务进度记录

查看工作目录中的文件。

4.8 效果对比

与单 Agent 相比，核心差异在于：

|-------|-----------------|--------------------------|
| 维度 | 单 Agent | Swarm Agent |
| 处理方式 | 串行处理 4 个方向 | 并行处理，3+1 个 Teammate 同时工作 |
| 耗时 | 约 60 分钟 | 约 20 分钟 |
| 上下文质量 | 信息累积导致膨胀，后期质量下降 | 每个 Teammate 上下文独立，质量稳定 |
| 追加需求 | 需排队等待当前任务完成 | 立即创建新 Teammate 处理 |

五、写在最后

Swarm Agent 当前还有一些值得探索的方向。

部署层面，现在 spawn_mode: inprocess 意味着 Teammate 和 Leader 跑在同一进程里。如果未来能扩展到独立进程或远程节点，让 Teammate 在专用 GPU 服务器上执行，算力上限会提高不少。互联互通层面，JiuwenSwarm 已经实现了 A2A ingress channel（jiuwenclaw/channel/a2a_channel.py），可以通过 A2A 协议与其他 Agent 系统对接。使用体验层面，一个可视化的团队编排界面------拖拽配置角色和技能------会进一步降低上手门槛。

回顾这套设计，JiuwenSwarm 的 Swarm Agent 没有从零发明一套复杂的多 Agent 框架，而是在 openJiuwen 的基础上，把技能、记忆、演进等已有能力自然地扩展到多 Agent 场景。几个设计决策值得一提：渐进式能力继承让 Teammate 上岗成本很低，不需要逐个配置；动态 + 静态两种构建模式覆盖了不同场景；12 种事件的全链路监控让系统变得可观测；流式协作与追加交互打破了"提交后只能等待"的模式，用户可以随时介入。

总的来说，这是一套实用导向的多智能体协作方案------重心放在如何让现有能力在多 Agent 场景下顺畅运转，而不是追求架构上的花哨。

---

参考资料：

• https://atomgit.com/openJiuwen?utm_source=csdn
• https://www.openjiuwen.com?utm_source=csdn