109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
---
|
||
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
|