---
title: Multi-Agent Crew 编排系统
created: 2026-04-14
updated: 2026-04-14
type: entity
tags: [agent, architecture, websocket, runtime]
sources: [packages/backend/src/modules/netaclaw/service/crew_orchestrator.ts, packages/backend/src/modules/netaclaw/entity/crew.ts, packages/frontend/src/modules/agent/views/crew-editor.vue]
---

# Multi-Agent Crew 编排系统

多智能体协作框架，支持主 Agent 通过委派、并行执行、升级等机制协调多个子 Agent 完成复杂任务。分为后端编排引擎和前端可视化画布编辑器两部分。

## 核心概念

- **Crew（集群）**：一组 Agent 的编排单元，包含一个主 Agent 和多个成员 Agent
- **主 Agent**：负责任务分解和委派决策，拥有 delegate_task / delegate_parallel / escalate 三个编排工具
- **子 Agent**：接收委派任务并独立执行，拥有内置工具和 Skill 工具（不含委派工具）
- **升级（Escalate）**：主 Agent 遇到无法自主解决的问题时暂停执行，请求人工介入

## 数据模型（4个表）

| 表名 | Entity | 用途 |
|------|--------|------|
| `netaclaw_crew` | `entity/crew.ts` | 集群定义（画布、触发配置、委派提示） |
| `netaclaw_crew_agent` | `entity/crew_agent.ts` | 集群-Agent 关联（角色、画布位置、分组） |
| `netaclaw_crew_run` | `entity/crew_run.ts` | 运行记录（状态、token、暂停状态） |
| `netaclaw_crew_task` | `entity/crew_task.ts` | 子任务记录（支持嵌套 parentTaskId） |

### 关键字段

**netaclaw_crew**: `name`(唯一) | `label` | `masterAgentId` | `canvasData`(JSON) | `triggerConfig`(JSON) | `delegateHints`(文本) | `status`(0草稿/1发布) | `maxConcurrent`(默认3) | `taskTimeout`(默认300秒) | `retryPolicy`(JSON)

**netaclaw_crew_run**: `crewId` | `triggerType`(manual/cron/webhook/api) | `status`(pending/running/paused/completed/failed/stopped) | `masterSessionId` | `pausedState`(JSON,升级暂停时的对话) | `tokenUsage`(JSON)

## 后端关键文件

| 文件 | 职责 |
|------|------|
| `service/crew_orchestrator.ts` | 核心编排器：启动、运行、暂停、恢复 |
| `service/crew_delegate.ts` | 委派执行器：串行和并行子 Agent 执行 |
| `service/crew_scheduler.ts` | Cron 定时调度（Singleton，启动时恢复） |
| `service/crew.ts` | 集群 CRUD、画布保存、成员同步、发布校验 |
| `service/crew_types.ts` | 类型定义（DelegateResult, CrewCallbacks, CrewRunContext） |
| `gateway/crew_server.ts` | WebSocket `/crew` 命名空间 |
| `controller/admin/crew.ts` | 集群 API（CRUD + saveCanvas/publish） |
| `controller/admin/crew_trigger.ts` | 触发 API（start/stop/resume） |
| `controller/admin/crew_run.ts` | 运行记录查询 API |

## 编排执行流程

```
触发运行（手动/定时/Webhook/API）
  → CrewOrchestratorService.start()
    ├─ 加载集群、主Agent、成员Agent
    ├─ 创建 crew_run 记录
    └─ 异步执行（立即返回 runId）
  → runOrchestration()
    ├─ 构建增强系统提示词（原始 + 团队成员 + 委派提示 + 工具说明）
    ├─ 构建工具集（内置 + 委派 + Skill）
    └─ 执行主Agent的 ReAct 循环
      ├─ delegate_task → executeSubAgent()（串行）
      ├─ delegate_parallel → executeParallel()（按 maxConcurrent 分批）
      └─ escalate → 暂停，等待人工介入
  → 运行完成，更新状态和 token 统计
```

## 升级恢复机制

```
主Agent 调用 escalate → 持久化 pausedState → 推送 escalation 事件
  → 前端显示升级提示 → 用户输入处理意见
  → POST /crew_trigger/resume → resolver(userMessage)
  → Promise resolve → 主Agent 继续 ReAct 循环
```

关键实现：`escalateResolvers` Map 存储 resolve 回调，escalate 工具返回不 resolve 的 Promise。

## 前端画布编辑器

| 文件 | 职责 |
|------|------|
| `views/crew-editor.vue` | 编辑器主页面（VueFlow 画布 + 侧栏 + 属性面板） |
| `views/crew-monitor.vue` | 运行监控页面（运行列表 + 详情 + 日志） |
| `hooks/crew-canvas.ts` | 画布操作（节点增删、主Agent设置、序列化） |
| `hooks/crew-monitor.ts` | WebSocket 监控（连接 `/crew` 命名空间） |
| `hooks/crew-orchestration.ts` | 连线转委派提示词（串行/并行建议） |
| `store/crew.ts` | Pinia Store（集群列表、详情、成员） |
| `components/crew/*.vue` | 10个子组件（节点、侧栏、属性面板、日志等） |

## WebSocket 协议（`/crew` 命名空间）

| 事件 | 方向 | 说明 |
|------|------|------|
| `crew:trigger` | 客户端→服务端 | 触发集群运行 |
| `crew:control` | 客户端→服务端 | 控制运行（stop/resume/pause/retry） |
| `crew:run:status` | 服务端→客户端 | 运行状态变化 |
| `crew:task:status` | 服务端→客户端 | 任务状态变化 |
| `crew:log` | 服务端→客户端 | 日志消息 |
| `crew:escalation` | 服务端→客户端 | 升级事件 |

## 相关页面

- [[netaclaw-module]] — 所属模块
- [[agent-runtime]] — 子 Agent 执行复用 runAgent()
- [[tool-system]] — delegate_task / delegate_parallel / escalate 工具
- [[websocket-gateway]] — `/crew` 命名空间
- [[skill-system]] — 主/子 Agent 均可加载 Skill