4056 lines
125 KiB
Markdown
4056 lines
125 KiB
Markdown
# Multi-Agent Crew 编排与运行监控 — 实施规划
|
||
|
||
> 基于设计文档：`2026-04-14-multi-agent-crew-orchestration-design.md`
|
||
> 日期：2026-04-14
|
||
> 状态：待审核
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [总览](#总览)
|
||
- [Phase 0：准备工作](#phase-0准备工作)
|
||
- [Phase 1：后端数据层（Entity + Migration）](#phase-1后端数据层entity--migration)
|
||
- [Phase 2：后端核心引擎（编排器 + 委派工具）](#phase-2后端核心引擎编排器--委派工具)
|
||
- [Phase 3：后端通信层（WebSocket + 触发 + 定时）](#phase-3后端通信层websocket--触发--定时)
|
||
- [Phase 4：前端编排页](#phase-4前端编排页)
|
||
- [Phase 5：前端监控页](#phase-5前端监控页)
|
||
- [Phase 6：权限集成 + 端到端测试](#phase-6权限集成--端到端测试)
|
||
- [风险应对与降级方案](#风险应对与降级方案)
|
||
- [验收标准](#验收标准)
|
||
|
||
---
|
||
|
||
## 总览
|
||
|
||
### 实施策略
|
||
|
||
采用 **纵向切片、逐层推进** 策略。每个 Phase 完成后都有可验证的产出，允许中途停下来评审。
|
||
|
||
```
|
||
Phase 0 ─ 准备（依赖验证、技术验证、代码骨架）
|
||
│
|
||
Phase 1 ─ 后端数据层（4 个 Entity + agent 扩展字段）
|
||
│
|
||
Phase 2 ─ 后端核心引擎（CrewOrchestrator + CrewDelegate + 3 个工具）
|
||
│
|
||
Phase 3 ─ 后端通信层（CrewGateway + CrewTrigger + CrewScheduler）
|
||
│
|
||
Phase 4 ─ 前端编排页（画布 + 侧栏 + 属性面板）
|
||
│
|
||
Phase 5 ─ 前端监控页（运行列表 + 实时画布 + 时间线 + 日志）
|
||
│
|
||
Phase 6 ─ 权限集成 + 端到端测试
|
||
```
|
||
|
||
### 关键约定
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| **Entity 继承** | 全部继承 `BaseEntity`（自带 id/createTime/updateTime/tenantId） |
|
||
| **Controller 风格** | 使用 `@CoolController` 自动 CRUD，复杂接口手写 |
|
||
| **文件命名** | 下划线法（如 `crew_agent.ts`） |
|
||
| **字段命名** | 驼峰法（如 `masterAgentId`） |
|
||
| **WebSocket** | 独立 `/crew` 命名空间，不侵入现有 `/netaclaw` |
|
||
| **子 Agent 执行** | 直接调用 `runAgent()` 纯函数，零 runtime 改动 |
|
||
| **注释语言** | 中文 |
|
||
|
||
### 文件影响矩阵
|
||
|
||
```
|
||
packages/backend/src/modules/netaclaw/
|
||
├── entity/ ← Phase 1: 新增 4 个文件
|
||
│ ├── crew.ts [新增]
|
||
│ ├── crew_agent.ts [新增]
|
||
│ ├── crew_run.ts [新增]
|
||
│ ├── crew_task.ts [新增]
|
||
│ └── agent.ts [修改: +isCrewMaster 字段]
|
||
├── controller/
|
||
│ └── admin/
|
||
│ ├── crew.ts [新增] Phase 3
|
||
│ ├── crew_run.ts [新增] Phase 3
|
||
│ └── crew_trigger.ts [新增] Phase 3
|
||
├── gateway/
|
||
│ └── crew_server.ts [新增] Phase 3
|
||
├── service/
|
||
│ ├── crew.ts [新增] Phase 2
|
||
│ ├── crew_orchestrator.ts [新增] Phase 2
|
||
│ ├── crew_delegate.ts [新增] Phase 2
|
||
│ └── crew_scheduler.ts [新增] Phase 3
|
||
├── tools/
|
||
│ ├── builtin/
|
||
│ │ ├── delegate_task.ts [新增] Phase 2
|
||
│ │ ├── delegate_parallel.ts [新增] Phase 2
|
||
│ │ └── escalate.ts [新增] Phase 2
|
||
└── config.ts [修改: 注册新 Entity] Phase 1
|
||
|
||
packages/frontend/src/modules/agent/
|
||
├── config.ts [修改: +2 路由] Phase 4
|
||
├── views/
|
||
│ ├── crew-editor.vue [新增] Phase 4
|
||
│ └── crew-monitor.vue [新增] Phase 5
|
||
├── components/crew/
|
||
│ ├── crew-canvas.vue [新增] Phase 4
|
||
│ ├── crew-agent-node.vue [新增] Phase 4
|
||
│ ├── crew-edge-label.vue [新增] Phase 4
|
||
│ ├── crew-sidebar.vue [新增] Phase 4
|
||
│ ├── crew-property-panel.vue [新增] Phase 4
|
||
│ ├── crew-trigger-config.vue [新增] Phase 4
|
||
│ ├── crew-context-menu.vue [新增] Phase 4
|
||
│ ├── crew-run-table.vue [新增] Phase 5
|
||
│ ├── crew-run-detail.vue [新增] Phase 5
|
||
│ ├── crew-timeline.vue [新增] Phase 5
|
||
│ └── crew-log-panel.vue [新增] Phase 5
|
||
├── hooks/
|
||
│ ├── crew-canvas.ts [新增] Phase 4
|
||
│ ├── crew-orchestration.ts [新增] Phase 4
|
||
│ └── crew-monitor.ts [新增] Phase 5
|
||
└── store/
|
||
└── crew.ts [新增] Phase 4
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 0：准备工作
|
||
|
||
> 目标：搭建开发环境，确认依赖可用，创建代码骨架
|
||
> 预估：0.5 天
|
||
|
||
### Step 0.1：确认前端依赖可用
|
||
|
||
项目已安装但未实际使用的关键依赖，需验证版本兼容：
|
||
|
||
```bash
|
||
cd packages/frontend
|
||
# 检查 @vue-flow 系列
|
||
pnpm list @vue-flow/core @vue-flow/minimap @vue-flow/controls @vue-flow/background
|
||
# 检查 elkjs（自动布局）
|
||
pnpm list elkjs
|
||
```
|
||
|
||
**预期结果**：
|
||
- `@vue-flow/core` ≥ 1.42.1 ✓
|
||
- `@vue-flow/minimap`、`@vue-flow/controls`、`@vue-flow/background` 已安装 ✓
|
||
- `elkjs` ≥ 0.9.3 ✓
|
||
|
||
**如果缺失**：
|
||
```bash
|
||
pnpm add @vue-flow/core @vue-flow/minimap @vue-flow/controls @vue-flow/background elkjs
|
||
```
|
||
|
||
### Step 0.2：确认后端依赖
|
||
|
||
```bash
|
||
cd packages/backend
|
||
# cron 包（定时调度用）
|
||
pnpm list cron
|
||
```
|
||
|
||
**如果缺失**：
|
||
```bash
|
||
pnpm add cron
|
||
pnpm add -D @types/cron
|
||
```
|
||
|
||
### Step 0.3：Vue Flow 技术验证（⚠️ 关键风险点）
|
||
|
||
> 这是本项目首次实际使用 Vue Flow。在正式开发前，先用最小 demo 验证核心功能。
|
||
|
||
创建临时验证文件 `packages/frontend/src/modules/agent/views/__test-flow.vue`：
|
||
|
||
```vue
|
||
<template>
|
||
<div style="width: 100%; height: 600px">
|
||
<VueFlow :nodes="nodes" :edges="edges" @node-drag-stop="onNodeDragStop">
|
||
<MiniMap />
|
||
<Controls />
|
||
<Background />
|
||
</VueFlow>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref } from 'vue';
|
||
import { VueFlow } from '@vue-flow/core';
|
||
import { MiniMap } from '@vue-flow/minimap';
|
||
import { Controls } from '@vue-flow/controls';
|
||
import { Background } from '@vue-flow/background';
|
||
|
||
const nodes = ref([
|
||
{ id: '1', position: { x: 100, y: 100 }, data: { label: '主 Agent' } },
|
||
{ id: '2', position: { x: 300, y: 200 }, data: { label: '子 Agent' } },
|
||
]);
|
||
const edges = ref([
|
||
{ id: 'e1-2', source: '1', target: '2' },
|
||
]);
|
||
function onNodeDragStop(event: any) {
|
||
console.log('节点拖拽完成', event);
|
||
}
|
||
</script>
|
||
```
|
||
|
||
**验证清单**：
|
||
- [ ] 画布正常渲染，节点可见
|
||
- [ ] 节点可自由拖拽，连线跟随
|
||
- [ ] MiniMap、Controls、Background 正常显示
|
||
- [ ] 自定义节点（slot 方式）可渲染
|
||
- [ ] 连线可通过 Handle 创建
|
||
|
||
**通过后删除测试文件**，正式进入 Phase 1。
|
||
|
||
### Step 0.4：创建后端模块骨架目录
|
||
|
||
```bash
|
||
cd packages/backend/src/modules/netaclaw
|
||
# 确认以下目录存在
|
||
ls entity/
|
||
ls controller/admin/
|
||
ls service/
|
||
ls gateway/
|
||
ls tools/builtin/
|
||
```
|
||
|
||
### Phase 0 验收
|
||
|
||
- [ ] 前端 Vue Flow 依赖可用且 demo 验证通过
|
||
- [ ] 后端 cron 依赖可用
|
||
- [ ] 目录结构就绪
|
||
|
||
---
|
||
|
||
## Phase 1：后端数据层（Entity + Migration）
|
||
|
||
> 目标：建立 4 个新表 + 扩展 agent 表，TypeORM synchronize 自动建表
|
||
> 预估：1 天
|
||
> 依赖：Phase 0 完成
|
||
|
||
### Step 1.1：创建 `crew.ts` Entity
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/entity/crew.ts`
|
||
|
||
```typescript
|
||
import { BaseEntity } from '../../base/entity/base.js';
|
||
import { Column, Entity, Index } from 'typeorm';
|
||
|
||
/**
|
||
* Agent 集群（Crew）
|
||
*/
|
||
@Entity('netaclaw_crew')
|
||
export class NetaClawCrewEntity extends BaseEntity {
|
||
@Column({ comment: '集群唯一标识', length: 100, unique: true })
|
||
name: string;
|
||
|
||
@Column({ comment: '显示名称', length: 200 })
|
||
label: string;
|
||
|
||
@Column({ comment: '集群描述', type: 'text', nullable: true })
|
||
description: string;
|
||
|
||
@Column({ comment: '图标', length: 500, nullable: true })
|
||
icon: string;
|
||
|
||
@Index()
|
||
@Column({ comment: '主 Agent ID', nullable: true })
|
||
masterAgentId: number;
|
||
|
||
@Column({ type: 'json', comment: '画布布局数据', nullable: true })
|
||
canvasData: Record<string, unknown>;
|
||
|
||
@Column({ type: 'json', comment: '触发配置', nullable: true })
|
||
triggerConfig: {
|
||
manual?: boolean;
|
||
cron?: { enabled: boolean; expression: string; timezone: string };
|
||
webhook?: { enabled: boolean; secret: string };
|
||
api?: { enabled: boolean; apiKey: string };
|
||
};
|
||
|
||
@Column({ type: 'json', comment: '委派提示（从连线生成）', nullable: true })
|
||
delegateHints: {
|
||
hints: string;
|
||
edges: Array<{ from: string; to: string; type: string; note?: string }>;
|
||
};
|
||
|
||
@Index()
|
||
@Column({ comment: '状态: 0=草稿 1=已发布', default: 0 })
|
||
status: number;
|
||
|
||
@Column({ comment: '最大并发子 Agent 数', default: 3 })
|
||
maxConcurrent: number;
|
||
|
||
@Column({ comment: '单个子任务默认超时（秒）', default: 300 })
|
||
taskTimeout: number;
|
||
|
||
@Column({ type: 'json', comment: '全局重试策略', nullable: true })
|
||
retryPolicy: { maxRetries: number; retryDelay: number };
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- `triggerConfig` / `delegateHints` / `retryPolicy` 使用 JSON 列，灵活扩展
|
||
- `masterAgentId` 不使用外键约束（遵循项目规范），通过应用层关联
|
||
- `status` 索引优化发布状态查询
|
||
|
||
### Step 1.2：创建 `crew_agent.ts` Entity
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/entity/crew_agent.ts`
|
||
|
||
```typescript
|
||
import { BaseEntity } from '../../base/entity/base.js';
|
||
import { Column, Entity, Index } from 'typeorm';
|
||
|
||
/**
|
||
* 集群-Agent 关联（成员关系权威来源）
|
||
*/
|
||
@Entity('netaclaw_crew_agent')
|
||
export class NetaClawCrewAgentEntity extends BaseEntity {
|
||
@Index()
|
||
@Column({ comment: '集群 ID' })
|
||
crewId: number;
|
||
|
||
@Index()
|
||
@Column({ comment: 'Agent ID' })
|
||
agentId: number;
|
||
|
||
@Column({ comment: '该 Agent 在集群中的角色描述', type: 'text', nullable: true })
|
||
role: string;
|
||
|
||
@Column({ type: 'json', comment: '画布位置', nullable: true })
|
||
canvasPosition: { x: number; y: number };
|
||
|
||
@Column({ comment: '分组名', length: 100, nullable: true })
|
||
groupName: string;
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- `crewId + agentId` 双索引，支持高频关联查询
|
||
- `canvasPosition` 用 JSON 存画布坐标，前端序列化/反序列化
|
||
- 此表是成员关系的**权威来源**，`canvasData` 仅存渲染信息
|
||
|
||
### Step 1.3：创建 `crew_run.ts` Entity
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/entity/crew_run.ts`
|
||
|
||
```typescript
|
||
import { BaseEntity } from '../../base/entity/base.js';
|
||
import { Column, Entity, Index } from 'typeorm';
|
||
|
||
/**
|
||
* 集群运行记录
|
||
*/
|
||
@Entity('netaclaw_crew_run')
|
||
export class NetaClawCrewRunEntity extends BaseEntity {
|
||
@Index()
|
||
@Column({ comment: '集群 ID' })
|
||
crewId: number;
|
||
|
||
@Column({ comment: '触发方式', length: 20 })
|
||
triggerType: string; // manual / cron / webhook / api
|
||
|
||
@Column({ comment: '触发输入参数', type: 'text', nullable: true })
|
||
triggerInput: string;
|
||
|
||
@Index()
|
||
@Column({ comment: '运行状态', length: 20, default: 'pending' })
|
||
status: string; // pending / running / paused / completed / failed
|
||
|
||
@Column({ comment: '主 Agent 会话 ID', nullable: true })
|
||
masterSessionId: number;
|
||
|
||
@Column({ comment: '开始时间', type: 'datetime', nullable: true })
|
||
startTime: Date;
|
||
|
||
@Column({ comment: '结束时间', type: 'datetime', nullable: true })
|
||
endTime: Date;
|
||
|
||
@Column({ type: 'json', comment: '运行结果摘要', nullable: true })
|
||
result: Record<string, unknown>;
|
||
|
||
@Column({ comment: '错误信息', type: 'text', nullable: true })
|
||
error: string;
|
||
|
||
@Column({ type: 'json', comment: '升级暂停时保存的对话上下文', nullable: true })
|
||
pausedState: unknown;
|
||
|
||
@Column({ type: 'json', comment: '累计 token 消耗', nullable: true })
|
||
tokenUsage: { inputTokens: number; outputTokens: number };
|
||
}
|
||
```
|
||
|
||
### Step 1.4：创建 `crew_task.ts` Entity
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/entity/crew_task.ts`
|
||
|
||
```typescript
|
||
import { BaseEntity } from '../../base/entity/base.js';
|
||
import { Column, Entity, Index } from 'typeorm';
|
||
|
||
/**
|
||
* 子 Agent 任务记录
|
||
*/
|
||
@Entity('netaclaw_crew_task')
|
||
export class NetaClawCrewTaskEntity extends BaseEntity {
|
||
@Index()
|
||
@Column({ comment: '运行记录 ID' })
|
||
runId: number;
|
||
|
||
@Index()
|
||
@Column({ comment: '子 Agent ID' })
|
||
agentId: number;
|
||
|
||
@Column({ comment: '任务描述', type: 'text' })
|
||
taskDescription: string;
|
||
|
||
@Index()
|
||
@Column({ comment: '任务状态', length: 20, default: 'pending' })
|
||
status: string; // pending / running / completed / failed / retrying
|
||
|
||
@Column({ comment: '子 Agent 会话 ID', nullable: true })
|
||
sessionId: number;
|
||
|
||
@Column({ comment: '开始时间', type: 'datetime', nullable: true })
|
||
startTime: Date;
|
||
|
||
@Column({ comment: '结束时间', type: 'datetime', nullable: true })
|
||
endTime: Date;
|
||
|
||
@Column({ type: 'json', comment: '执行结果', nullable: true })
|
||
result: Record<string, unknown>;
|
||
|
||
@Column({ comment: '错误信息', type: 'text', nullable: true })
|
||
error: string;
|
||
|
||
@Column({ comment: '已重试次数', default: 0 })
|
||
retryCount: number;
|
||
|
||
@Column({ comment: '该任务超时（秒），空则使用集群默认', nullable: true })
|
||
timeout: number;
|
||
|
||
@Column({ type: 'json', comment: '该任务 token 消耗', nullable: true })
|
||
tokenUsage: { inputTokens: number; outputTokens: number };
|
||
|
||
@Column({ comment: '父任务 ID（支持嵌套委派）', nullable: true })
|
||
parentTaskId: number;
|
||
}
|
||
```
|
||
|
||
### Step 1.5：扩展 `agent.ts` Entity
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/entity/agent.ts`
|
||
**操作**：在现有 `status` 字段后新增一个字段
|
||
|
||
```typescript
|
||
// 在 status 字段之后添加：
|
||
@Column({ comment: '是否可作为集群主 Agent', default: 0 })
|
||
isCrewMaster: number; // 0=否 1=是（UI 筛选用）
|
||
```
|
||
|
||
> 这是唯一一处修改现有文件的地方，风险极低（仅新增列，不改现有字段）。
|
||
|
||
### Step 1.6：注册 Entity 到模块配置
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/config.ts`
|
||
|
||
在现有 Entity 导入列表中追加：
|
||
|
||
```typescript
|
||
import { NetaClawCrewEntity } from './entity/crew.js';
|
||
import { NetaClawCrewAgentEntity } from './entity/crew_agent.js';
|
||
import { NetaClawCrewRunEntity } from './entity/crew_run.js';
|
||
import { NetaClawCrewTaskEntity } from './entity/crew_task.js';
|
||
|
||
// 在 typeorm.entity 数组中追加：
|
||
NetaClawCrewEntity,
|
||
NetaClawCrewAgentEntity,
|
||
NetaClawCrewRunEntity,
|
||
NetaClawCrewTaskEntity,
|
||
```
|
||
|
||
### Step 1.7：验证建表
|
||
|
||
```bash
|
||
cd packages/backend
|
||
pnpm dev # 启动开发服务器，TypeORM synchronize=true 自动建表
|
||
```
|
||
|
||
**验证清单**：
|
||
- [ ] 服务启动无报错
|
||
- [ ] MySQL 中新增 4 张表：`netaclaw_crew`、`netaclaw_crew_agent`、`netaclaw_crew_run`、`netaclaw_crew_task`
|
||
- [ ] `netaclaw_agent` 表新增 `isCrewMaster` 字段
|
||
- [ ] 所有索引正确创建
|
||
- [ ] JSON 列可正常读写（手动插入测试数据验证）
|
||
|
||
### Step 1.8：提交代码
|
||
|
||
```bash
|
||
git add packages/backend/src/modules/netaclaw/entity/crew*.ts
|
||
git add packages/backend/src/modules/netaclaw/entity/agent.ts
|
||
git add packages/backend/src/modules/netaclaw/config.ts
|
||
git commit -m "feat(crew): 新增 Crew 编排数据模型 - 4 个 Entity + agent 扩展字段"
|
||
```
|
||
|
||
### Phase 1 验收
|
||
|
||
- [ ] 4 个新 Entity 文件创建完成
|
||
- [ ] agent.ts 新增 isCrewMaster 字段
|
||
- [ ] config.ts 注册新 Entity
|
||
- [ ] 自动建表成功，字段/索引/JSON 列均正确
|
||
- [ ] 代码已提交
|
||
|
||
---
|
||
|
||
## Phase 2：后端核心引擎（编排器 + 委派工具）
|
||
|
||
> 目标：实现 CrewOrchestrator 编排调度器 + CrewDelegate 委派执行器 + 3 个委派工具
|
||
> 预估：2.5 天
|
||
> 依赖：Phase 1 完成
|
||
> **本阶段是整个系统的核心，代码量最大，逻辑最复杂**
|
||
|
||
### Step 2.1：定义类型接口
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/service/crew_types.ts`
|
||
|
||
> 先定义所有跨模块共享的类型，避免循环引用。
|
||
|
||
```typescript
|
||
/**
|
||
* Crew 编排系统共享类型定义
|
||
*/
|
||
|
||
/** 委派执行结果 */
|
||
export interface DelegateResult {
|
||
agent: string;
|
||
status: 'completed' | 'failed';
|
||
result: string;
|
||
error?: string;
|
||
duration: string;
|
||
tokenUsage: { inputTokens: number; outputTokens: number };
|
||
}
|
||
|
||
/** 委派回调 */
|
||
export interface CrewCallbacks {
|
||
/** 日志推送 */
|
||
onLog: (runId: number, taskId: number, agentName: string, level: string, message: string) => void;
|
||
/** 任务状态变更推送 */
|
||
onTaskStatus: (runId: number, taskId: number, agentName: string, status: string, result?: any, error?: string) => void;
|
||
/** 运行状态变更推送 */
|
||
onRunStatus: (runId: number, status: string, progress?: string) => void;
|
||
/** 升级推送 */
|
||
onEscalation: (runId: number, taskId: number | undefined, reason: string, error?: string) => void;
|
||
}
|
||
|
||
/** 并行委派任务项 */
|
||
export interface ParallelTaskItem {
|
||
agent_name: string;
|
||
task_description: string;
|
||
context?: string;
|
||
}
|
||
|
||
/** 集群运行上下文（编排器运行期间的内存状态） */
|
||
export interface CrewRunContext {
|
||
runId: number;
|
||
crewId: number;
|
||
masterAgentId: number;
|
||
memberAgents: Array<{
|
||
id: number;
|
||
name: string;
|
||
label: string;
|
||
role: string;
|
||
agent: any; // NetaClawAgentEntity
|
||
}>;
|
||
maxConcurrent: number;
|
||
taskTimeout: number;
|
||
callbacks: CrewCallbacks;
|
||
/** 获取当前主 Agent 对话历史（escalate 持久化用） */
|
||
getConversation?: () => any[];
|
||
}
|
||
```
|
||
|
||
### Step 2.2：实现 CrewDelegate（委派执行器）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/service/crew_delegate.ts`
|
||
|
||
**职责**：执行子 Agent 任务的核心函数，直接调用 `runAgent()`。
|
||
|
||
```typescript
|
||
import { Provide, Inject, Logger } from '@midwayjs/core';
|
||
import { ILogger } from '@midwayjs/logger';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawCrewTaskEntity } from '../entity/crew_task.js';
|
||
import { NetaClawAgentEntity } from '../entity/agent.js';
|
||
import { runAgent, AgentConfig } from '../runtime/agent.js';
|
||
import { AnyAgentTool } from '../tools/common.js';
|
||
import { DelegateResult, CrewCallbacks } from './crew_types.js';
|
||
import { SkillLoaderService } from '../service/skill_loader.js';
|
||
import { buildSkillContext } from '../service/skill_context.js';
|
||
// 导入内置工具
|
||
import { bashTool } from '../tools/builtin/bash.js';
|
||
import { readFileTool, writeFileTool, listDirTool } from '../tools/builtin/file.js';
|
||
|
||
/** 委派相关工具名，子 Agent 不可使用（防止无限嵌套） */
|
||
const CREW_TOOLS = ['delegate_task', 'delegate_parallel', 'escalate'];
|
||
|
||
@Provide()
|
||
export class CrewDelegateService {
|
||
@Logger()
|
||
logger: ILogger;
|
||
|
||
@InjectEntityModel(NetaClawCrewTaskEntity)
|
||
crewTaskRepo: Repository<NetaClawCrewTaskEntity>;
|
||
|
||
@Inject()
|
||
skillLoader: SkillLoaderService;
|
||
|
||
/**
|
||
* 执行单个子 Agent 任务
|
||
*/
|
||
async executeSubAgent(
|
||
agent: NetaClawAgentEntity,
|
||
taskDescription: string,
|
||
context: string | undefined,
|
||
runId: number,
|
||
taskTimeout: number,
|
||
callbacks: CrewCallbacks
|
||
): Promise<DelegateResult> {
|
||
const startTime = Date.now();
|
||
|
||
// 1. 创建 crew_task 记录
|
||
const task = await this.crewTaskRepo.save({
|
||
runId,
|
||
agentId: agent.id,
|
||
taskDescription,
|
||
status: 'running',
|
||
startTime: new Date(),
|
||
} as any);
|
||
|
||
callbacks.onTaskStatus(runId, task.id, agent.name, 'running');
|
||
|
||
try {
|
||
// 2. 加载子 Agent 的 Skill 上下文（继承 Agent 自身配置的 skills）
|
||
let skillSystemPrompt = '';
|
||
if (agent.skills?.length) {
|
||
const skillContext = await buildSkillContext(this.skillLoader, agent.skills);
|
||
skillSystemPrompt = skillContext ? `\n\n${skillContext}` : '';
|
||
}
|
||
|
||
// 3. 构建 Agent 配置
|
||
const agentConfig: AgentConfig = {
|
||
name: agent.name,
|
||
systemPrompt: `${agent.systemPrompt || ''}${skillSystemPrompt}\n\n## 当前任务\n${taskDescription}`,
|
||
model: agent.modelConfig?.modelId || 'anthropic:claude-sonnet-4-20250514',
|
||
apiKey: agent.modelConfig?.apiKey || '',
|
||
baseUrl: agent.modelConfig?.apiUrl,
|
||
skills: agent.skills || [],
|
||
};
|
||
|
||
// 4. 加载子 Agent 工具集（内置工具 + Skill 工具，移除委派工具）
|
||
const builtinTools: AnyAgentTool[] = [bashTool, readFileTool, writeFileTool, listDirTool];
|
||
const skillTools = await this.skillLoader.loadToolsForAgent(agent);
|
||
const tools = [...builtinTools, ...skillTools].filter(t => !CREW_TOOLS.includes(t.name));
|
||
|
||
// 5. 构建用户消息
|
||
const userMessage = context
|
||
? `任务：${taskDescription}\n\n上下文：${context}`
|
||
: taskDescription;
|
||
|
||
// 6. 带超时调用 runAgent()
|
||
const timeout = taskTimeout * 1000;
|
||
const result = await Promise.race([
|
||
runAgent({
|
||
agentConfig,
|
||
tools,
|
||
userMessage,
|
||
history: [], // 空历史 = 独立会话
|
||
onToken: (text) => callbacks.onLog(runId, task.id, agent.name, 'info', text),
|
||
onToolCall: (name) => callbacks.onLog(runId, task.id, agent.name, 'tool', `调用工具: ${name}`),
|
||
}),
|
||
new Promise((_, reject) =>
|
||
setTimeout(() => reject(new Error(`子 Agent "${agent.name}" 执行超时 (${taskTimeout}s)`)), timeout)
|
||
),
|
||
]) as any;
|
||
|
||
// 7. 更新 crew_task 为完成
|
||
const duration = `${((Date.now() - startTime) / 1000).toFixed(1)}s`;
|
||
await this.crewTaskRepo.update(task.id, {
|
||
status: 'completed',
|
||
result: { text: result.finalContent },
|
||
tokenUsage: result.usage,
|
||
endTime: new Date(),
|
||
} as any);
|
||
|
||
const delegateResult: DelegateResult = {
|
||
agent: agent.name,
|
||
status: 'completed',
|
||
result: result.finalContent,
|
||
duration,
|
||
tokenUsage: result.usage,
|
||
};
|
||
|
||
callbacks.onTaskStatus(runId, task.id, agent.name, 'completed', delegateResult);
|
||
return delegateResult;
|
||
|
||
} catch (err: any) {
|
||
// 8. 失败处理
|
||
const duration = `${((Date.now() - startTime) / 1000).toFixed(1)}s`;
|
||
await this.crewTaskRepo.update(task.id, {
|
||
status: 'failed',
|
||
error: err.message,
|
||
endTime: new Date(),
|
||
} as any);
|
||
|
||
const delegateResult: DelegateResult = {
|
||
agent: agent.name,
|
||
status: 'failed',
|
||
result: '',
|
||
error: err.message,
|
||
duration,
|
||
tokenUsage: { inputTokens: 0, outputTokens: 0 },
|
||
};
|
||
|
||
callbacks.onTaskStatus(runId, task.id, agent.name, 'failed', undefined, err.message);
|
||
return delegateResult;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 并行执行多个子 Agent 任务（受 maxConcurrent 限制）
|
||
*/
|
||
async executeParallel(
|
||
tasks: Array<{ agent: NetaClawAgentEntity; taskDescription: string; context?: string }>,
|
||
runId: number,
|
||
maxConcurrent: number,
|
||
taskTimeout: number,
|
||
callbacks: CrewCallbacks
|
||
): Promise<DelegateResult[]> {
|
||
// 简单的并发限制：分批执行
|
||
const results: DelegateResult[] = [];
|
||
for (let i = 0; i < tasks.length; i += maxConcurrent) {
|
||
const batch = tasks.slice(i, i + maxConcurrent);
|
||
const batchResults = await Promise.all(
|
||
batch.map(t => this.executeSubAgent(t.agent, t.taskDescription, t.context, runId, taskTimeout, callbacks))
|
||
);
|
||
results.push(...batchResults);
|
||
}
|
||
return results;
|
||
}
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- `runAgent()` 是纯函数调用，`history: []` 保证独立会话
|
||
- `Promise.race` 实现超时控制
|
||
- **动态加载子 Agent 的 skills/tools**（通过 SkillLoaderService），而非硬编码
|
||
- 移除 delegate/escalate 工具防止子 Agent 嵌套委派
|
||
- 并行执行通过分批 + `Promise.all` 实现，受 `maxConcurrent` 限制
|
||
|
||
### Step 2.3：实现 3 个委派工具
|
||
|
||
#### 2.3.1 `delegate_task.ts`（串行委派）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/tools/builtin/delegate_task.ts`
|
||
|
||
```typescript
|
||
import { Type } from '@sinclair/typebox';
|
||
import type { AnyAgentTool } from '../common.js';
|
||
import type { CrewRunContext, DelegateResult } from '../../service/crew_types.js';
|
||
|
||
/**
|
||
* 创建 delegate_task 工具实例
|
||
* 闭包绑定当前 crew 运行上下文，使主 Agent 可通过工具调用委派子 Agent
|
||
*/
|
||
export function createDelegateTaskTool(ctx: CrewRunContext): AnyAgentTool {
|
||
return {
|
||
name: 'delegate_task',
|
||
label: '委派任务',
|
||
description: '将任务委派给团队中的一个子 Agent 执行，等待执行完成后返回结果。',
|
||
visibility: 'tool',
|
||
parameters: Type.Object({
|
||
agent_name: Type.String({ description: '子 Agent 名称' }),
|
||
task_description: Type.String({ description: '任务描述' }),
|
||
context: Type.Optional(Type.String({ description: '上下文（前序任务结果等）' })),
|
||
}),
|
||
execute: async (_id: string, params: any): Promise<string> => {
|
||
const { agent_name, task_description, context } = params;
|
||
|
||
// 查找目标子 Agent
|
||
const member = ctx.memberAgents.find(m => m.name === agent_name);
|
||
if (!member) {
|
||
return JSON.stringify({
|
||
agent: agent_name,
|
||
status: 'failed',
|
||
error: `未找到名为 "${agent_name}" 的子 Agent。可用成员: ${ctx.memberAgents.map(m => m.name).join(', ')}`,
|
||
});
|
||
}
|
||
|
||
// 调用 CrewDelegate 执行
|
||
// 注意：ctx._delegate 在 CrewOrchestrator 构建时注入
|
||
const result: DelegateResult = await (ctx as any)._delegate.executeSubAgent(
|
||
member.agent,
|
||
task_description,
|
||
context,
|
||
ctx.runId,
|
||
ctx.taskTimeout,
|
||
ctx.callbacks,
|
||
);
|
||
|
||
return JSON.stringify(result);
|
||
},
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 2.3.2 `delegate_parallel.ts`（并行委派）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/tools/builtin/delegate_parallel.ts`
|
||
|
||
```typescript
|
||
import { Type } from '@sinclair/typebox';
|
||
import type { AnyAgentTool } from '../common.js';
|
||
import type { CrewRunContext, DelegateResult } from '../../service/crew_types.js';
|
||
|
||
/**
|
||
* 创建 delegate_parallel 工具实例
|
||
*/
|
||
export function createDelegateParallelTool(ctx: CrewRunContext): AnyAgentTool {
|
||
return {
|
||
name: 'delegate_parallel',
|
||
label: '并行委派',
|
||
description: '将多个任务同时委派给不同的子 Agent 并行执行，全部完成后返回所有结果。',
|
||
visibility: 'tool',
|
||
parameters: Type.Object({
|
||
tasks: Type.Array(
|
||
Type.Object({
|
||
agent_name: Type.String({ description: '子 Agent 名称' }),
|
||
task_description: Type.String({ description: '任务描述' }),
|
||
context: Type.Optional(Type.String({ description: '上下文' })),
|
||
}),
|
||
{ description: '要并行执行的任务列表' }
|
||
),
|
||
}),
|
||
execute: async (_id: string, params: any): Promise<string> => {
|
||
const { tasks } = params;
|
||
|
||
// 解析并验证所有目标 Agent
|
||
const resolvedTasks = [];
|
||
for (const t of tasks) {
|
||
const member = ctx.memberAgents.find(m => m.name === t.agent_name);
|
||
if (!member) {
|
||
return JSON.stringify([{
|
||
agent: t.agent_name,
|
||
status: 'failed',
|
||
error: `未找到名为 "${t.agent_name}" 的子 Agent`,
|
||
}]);
|
||
}
|
||
resolvedTasks.push({
|
||
agent: member.agent,
|
||
taskDescription: t.task_description,
|
||
context: t.context,
|
||
});
|
||
}
|
||
|
||
// 并行执行
|
||
const results: DelegateResult[] = await (ctx as any)._delegate.executeParallel(
|
||
resolvedTasks,
|
||
ctx.runId,
|
||
ctx.maxConcurrent,
|
||
ctx.taskTimeout,
|
||
ctx.callbacks,
|
||
);
|
||
|
||
return JSON.stringify(results);
|
||
},
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 2.3.3 `escalate.ts`（升级人工）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/tools/builtin/escalate.ts`
|
||
|
||
```typescript
|
||
import { Type } from '@sinclair/typebox';
|
||
import type { AnyAgentTool } from '../common.js';
|
||
import type { CrewRunContext } from '../../service/crew_types.js';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawCrewRunEntity } from '../../entity/crew_run.js';
|
||
|
||
/**
|
||
* 内存中保存 escalate 的 resolve 回调（用于暂停/恢复）
|
||
* key: runId, value: resolve 函数
|
||
*/
|
||
export const escalateResolvers = new Map<number, (userMessage: string) => void>();
|
||
|
||
/**
|
||
* 创建 escalate 工具实例
|
||
* 需要传入 crewRunRepo 以持久化 pausedState
|
||
*/
|
||
export function createEscalateTool(
|
||
ctx: CrewRunContext,
|
||
crewRunRepo: Repository<NetaClawCrewRunEntity>
|
||
): AnyAgentTool {
|
||
return {
|
||
name: 'escalate',
|
||
label: '升级人工',
|
||
description: '当你无法处理某个问题时，升级给人工处理。集群将暂停等待人工介入。',
|
||
visibility: 'tool',
|
||
parameters: Type.Object({
|
||
reason: Type.String({ description: '升级原因' }),
|
||
failed_task: Type.Optional(Type.String({ description: '失败的任务描述' })),
|
||
}),
|
||
execute: async (_id: string, params: any): Promise<string> => {
|
||
const { reason, failed_task } = params;
|
||
|
||
// 1. 持久化当前对话上下文到 pausedState（进程重启恢复用）
|
||
const conversation = ctx.getConversation?.() || [];
|
||
await crewRunRepo.update(ctx.runId, {
|
||
status: 'paused',
|
||
pausedState: JSON.stringify(conversation),
|
||
} as any);
|
||
|
||
// 2. 推送升级事件 + 运行状态变更
|
||
ctx.callbacks.onEscalation(ctx.runId, undefined, reason, failed_task);
|
||
ctx.callbacks.onRunStatus(ctx.runId, 'paused');
|
||
|
||
// 3. 返回不 resolve 的 Promise，阻塞 runAttempt 循环
|
||
// 用户在监控页点击"恢复"时，通过 escalateResolvers 回调 resolve
|
||
return new Promise<string>((resolve) => {
|
||
escalateResolvers.set(ctx.runId, (userMessage: string) => {
|
||
resolve(JSON.stringify({
|
||
status: 'resumed',
|
||
userMessage,
|
||
instruction: '用户已提供处理意见，请根据用户意见继续执行。',
|
||
}));
|
||
});
|
||
});
|
||
},
|
||
};
|
||
}
|
||
```
|
||
|
||
**设计要点**：
|
||
- `escalateResolvers` 内存 Map 是暂停/恢复的核心机制
|
||
- `execute()` 返回的 Promise 不立即 resolve → `runAttempt` 阻塞在该 tool_call
|
||
- 恢复时通过 Map 取出 resolve 回调，注入用户意见作为 tool_result
|
||
- 进程重启恢复在 Phase 3 的 CrewScheduler 中处理
|
||
|
||
### Step 2.4：实现 CrewOrchestrator（核心编排器）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/service/crew_orchestrator.ts`
|
||
|
||
**这是整个系统最核心的文件**，负责：
|
||
1. 加载集群配置
|
||
2. 构建主 Agent 增强 system prompt
|
||
3. 注入委派工具
|
||
4. 启动主 Agent ReAct 循环
|
||
5. 管理运行生命周期
|
||
|
||
```typescript
|
||
import { Provide, Inject, Logger } from '@midwayjs/core';
|
||
import { ILogger } from '@midwayjs/logger';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawCrewEntity } from '../entity/crew.js';
|
||
import { NetaClawCrewAgentEntity } from '../entity/crew_agent.js';
|
||
import { NetaClawCrewRunEntity } from '../entity/crew_run.js';
|
||
import { NetaClawCrewTaskEntity } from '../entity/crew_task.js';
|
||
import { NetaClawAgentEntity } from '../entity/agent.js';
|
||
import { runAgent, AgentConfig } from '../runtime/agent.js';
|
||
import { AnyAgentTool } from '../tools/common.js';
|
||
import { CrewDelegateService } from './crew_delegate.js';
|
||
import { CrewRunContext, CrewCallbacks } from './crew_types.js';
|
||
import { createDelegateTaskTool } from '../tools/builtin/delegate_task.js';
|
||
import { createDelegateParallelTool } from '../tools/builtin/delegate_parallel.js';
|
||
import { createEscalateTool } from '../tools/builtin/escalate.js';
|
||
import { bashTool } from '../tools/builtin/bash.js';
|
||
import { readFileTool, writeFileTool, listDirTool } from '../tools/builtin/file.js';
|
||
|
||
@Provide()
|
||
export class CrewOrchestratorService {
|
||
@Logger()
|
||
logger: ILogger;
|
||
|
||
@InjectEntityModel(NetaClawCrewEntity)
|
||
crewRepo: Repository<NetaClawCrewEntity>;
|
||
|
||
@InjectEntityModel(NetaClawCrewAgentEntity)
|
||
crewAgentRepo: Repository<NetaClawCrewAgentEntity>;
|
||
|
||
@InjectEntityModel(NetaClawCrewRunEntity)
|
||
crewRunRepo: Repository<NetaClawCrewRunEntity>;
|
||
|
||
@InjectEntityModel(NetaClawCrewTaskEntity)
|
||
crewTaskRepo: Repository<NetaClawCrewTaskEntity>;
|
||
|
||
@InjectEntityModel(NetaClawAgentEntity)
|
||
agentRepo: Repository<NetaClawAgentEntity>;
|
||
|
||
@Inject()
|
||
crewDelegate: CrewDelegateService;
|
||
|
||
/**
|
||
* 启动一次集群运行
|
||
*/
|
||
async start(
|
||
crewId: number,
|
||
triggerType: string,
|
||
triggerInput: string,
|
||
callbacks: CrewCallbacks
|
||
): Promise<number> {
|
||
// 1. 加载集群配置
|
||
const crew = await this.crewRepo.findOne({ where: { id: crewId } });
|
||
if (!crew) throw new Error(`集群 ${crewId} 不存在`);
|
||
if (crew.status !== 1) throw new Error(`集群 ${crewId} 未发布`);
|
||
|
||
// 2. 加载主 Agent
|
||
const masterAgent = await this.agentRepo.findOne({ where: { id: crew.masterAgentId } });
|
||
if (!masterAgent) throw new Error(`主 Agent ${crew.masterAgentId} 不存在`);
|
||
|
||
// 3. 加载集群成员
|
||
const crewAgents = await this.crewAgentRepo.find({ where: { crewId } });
|
||
const memberAgents = [];
|
||
for (const ca of crewAgents) {
|
||
if (ca.agentId === crew.masterAgentId) continue; // 排除主 Agent 自身
|
||
const agent = await this.agentRepo.findOne({ where: { id: ca.agentId } });
|
||
if (agent) {
|
||
memberAgents.push({
|
||
id: agent.id,
|
||
name: agent.name,
|
||
label: agent.label,
|
||
role: ca.role || agent.description || '',
|
||
agent,
|
||
});
|
||
}
|
||
}
|
||
|
||
// 4. 创建运行记录
|
||
const run = await this.crewRunRepo.save({
|
||
crewId,
|
||
triggerType,
|
||
triggerInput,
|
||
status: 'running',
|
||
startTime: new Date(),
|
||
tokenUsage: { inputTokens: 0, outputTokens: 0 },
|
||
} as any);
|
||
|
||
callbacks.onRunStatus(run.id, 'running', `0/${memberAgents.length}`);
|
||
|
||
// 5. 构建运行上下文
|
||
const ctx: CrewRunContext = {
|
||
runId: run.id,
|
||
crewId,
|
||
masterAgentId: crew.masterAgentId,
|
||
memberAgents,
|
||
maxConcurrent: crew.maxConcurrent || 3,
|
||
taskTimeout: crew.taskTimeout || 300,
|
||
callbacks,
|
||
// getConversation 在 runOrchestration 中注入（需要闭包引用 runAgent 的内部状态）
|
||
};
|
||
// 注入 delegate 服务引用
|
||
(ctx as any)._delegate = this.crewDelegate;
|
||
|
||
// 6. 异步执行编排（不阻塞调用方）
|
||
this.runOrchestration(crew, masterAgent, ctx, triggerInput, callbacks)
|
||
.catch(err => {
|
||
this.logger.error(`集群 ${crewId} 运行 ${run.id} 异常:`, err);
|
||
});
|
||
|
||
return run.id;
|
||
}
|
||
|
||
/**
|
||
* 核心编排执行逻辑
|
||
*/
|
||
private async runOrchestration(
|
||
crew: NetaClawCrewEntity,
|
||
masterAgent: NetaClawAgentEntity,
|
||
ctx: CrewRunContext,
|
||
triggerInput: string,
|
||
callbacks: CrewCallbacks
|
||
): Promise<void> {
|
||
try {
|
||
// 1. 构建增强 system prompt
|
||
const enhancedPrompt = this.buildEnhancedPrompt(masterAgent, ctx, crew);
|
||
|
||
// 2. 构建主 Agent 配置
|
||
const agentConfig: AgentConfig = {
|
||
name: masterAgent.name,
|
||
systemPrompt: enhancedPrompt,
|
||
model: masterAgent.modelConfig?.modelId || 'anthropic:claude-sonnet-4-20250514',
|
||
apiKey: masterAgent.modelConfig?.apiKey || '',
|
||
baseUrl: masterAgent.modelConfig?.apiUrl,
|
||
maxToolRounds: 50, // 主 Agent 可能需要多轮委派
|
||
};
|
||
|
||
// 3. 用闭包捕获对话历史引用（供 escalate 持久化用）
|
||
// runAgent 内部会构建 messages 数组，我们通过 history 参数的引用来追踪
|
||
const conversationTracker: any[] = [];
|
||
ctx.getConversation = () => conversationTracker;
|
||
|
||
// 4. 构建主 Agent 工具集（基础工具 + 委派工具）
|
||
const tools: AnyAgentTool[] = [
|
||
bashTool, readFileTool, writeFileTool, listDirTool,
|
||
createDelegateTaskTool(ctx),
|
||
createDelegateParallelTool(ctx),
|
||
createEscalateTool(ctx, this.crewRunRepo), // 传入 repo 以持久化 pausedState
|
||
];
|
||
|
||
// 5. 执行主 Agent ReAct 循环
|
||
const result = await runAgent({
|
||
agentConfig,
|
||
tools,
|
||
userMessage: triggerInput || '请根据团队成员和调度建议，开始执行任务。',
|
||
history: [],
|
||
onToken: (text) => {
|
||
callbacks.onLog(ctx.runId, 0, masterAgent.name, 'info', text);
|
||
// 追踪对话内容（简化版，完整版需在 runAttempt 层获取）
|
||
conversationTracker.push({ role: 'assistant_token', content: text });
|
||
},
|
||
onToolCall: (name, args) => callbacks.onLog(ctx.runId, 0, masterAgent.name, 'tool', `调用 ${name}`),
|
||
});
|
||
|
||
// 6. 计算累计 Token（主 Agent + 所有子 Agent 任务）
|
||
const tasks = await this.crewTaskRepo.find({ where: { runId: ctx.runId } });
|
||
const totalTokens = tasks.reduce((acc, t) => ({
|
||
inputTokens: acc.inputTokens + (t.tokenUsage?.inputTokens || 0),
|
||
outputTokens: acc.outputTokens + (t.tokenUsage?.outputTokens || 0),
|
||
}), {
|
||
inputTokens: result.usage.inputTokens,
|
||
outputTokens: result.usage.outputTokens,
|
||
});
|
||
|
||
// 7. 更新运行记录为完成
|
||
await this.crewRunRepo.update(ctx.runId, {
|
||
status: 'completed',
|
||
result: { summary: result.finalContent },
|
||
tokenUsage: totalTokens,
|
||
endTime: new Date(),
|
||
} as any);
|
||
|
||
callbacks.onRunStatus(ctx.runId, 'completed');
|
||
|
||
} catch (err: any) {
|
||
// 失败处理
|
||
await this.crewRunRepo.update(ctx.runId, {
|
||
status: 'failed',
|
||
error: err.message,
|
||
endTime: new Date(),
|
||
} as any);
|
||
|
||
callbacks.onRunStatus(ctx.runId, 'failed');
|
||
this.logger.error(`集群运行 ${ctx.runId} 失败:`, err);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 构建主 Agent 增强 system prompt
|
||
*/
|
||
private buildEnhancedPrompt(
|
||
masterAgent: NetaClawAgentEntity,
|
||
ctx: CrewRunContext,
|
||
crew: NetaClawCrewEntity
|
||
): string {
|
||
let prompt = masterAgent.systemPrompt || '';
|
||
|
||
// 追加团队成员信息
|
||
prompt += '\n\n## 团队成员\n';
|
||
prompt += '你是团队的主管 Agent，负责将任务分配给以下子 Agent 执行：\n\n';
|
||
for (const member of ctx.memberAgents) {
|
||
prompt += `- **${member.name}**（${member.label}）: ${member.role}\n`;
|
||
}
|
||
|
||
// 追加调度建议（如有连线提示）
|
||
if (crew.delegateHints?.hints) {
|
||
prompt += `\n## 调度建议\n${crew.delegateHints.hints}\n`;
|
||
}
|
||
|
||
// 追加工具使用说明
|
||
prompt += `\n## 工具说明\n`;
|
||
prompt += `- 使用 \`delegate_task\` 将任务委派给一个子 Agent 串行执行\n`;
|
||
prompt += `- 使用 \`delegate_parallel\` 将多个独立任务同时委派给不同子 Agent 并行执行\n`;
|
||
prompt += `- 当遇到无法解决的问题时，使用 \`escalate\` 升级给人工处理\n`;
|
||
prompt += `- 根据任务之间的依赖关系决定串行还是并行执行\n`;
|
||
prompt += `- 收到子 Agent 的执行结果后，分析结果并决定下一步行动\n`;
|
||
|
||
return prompt;
|
||
}
|
||
|
||
/**
|
||
* 终止运行
|
||
*/
|
||
async stop(runId: number): Promise<void> {
|
||
await this.crewRunRepo.update(runId, {
|
||
status: 'failed',
|
||
error: '用户手动终止',
|
||
endTime: new Date(),
|
||
} as any);
|
||
}
|
||
|
||
/**
|
||
* 暂停运行（由 escalate 工具自动触发，此方法用于手动暂停）
|
||
*/
|
||
async pause(runId: number): Promise<void> {
|
||
await this.crewRunRepo.update(runId, {
|
||
status: 'paused',
|
||
} as any);
|
||
}
|
||
|
||
/**
|
||
* 从 pausedState 恢复运行（进程重启后使用）
|
||
*/
|
||
async resumeFromPausedState(
|
||
runId: number,
|
||
pausedHistory: any[],
|
||
userMessage: string,
|
||
callbacks: CrewCallbacks
|
||
): Promise<void> {
|
||
const run = await this.crewRunRepo.findOne({ where: { id: runId } });
|
||
if (!run) throw new Error(`运行 ${runId} 不存在`);
|
||
|
||
const crew = await this.crewRepo.findOne({ where: { id: run.crewId } });
|
||
if (!crew) throw new Error(`集群 ${run.crewId} 不存在`);
|
||
|
||
const masterAgent = await this.agentRepo.findOne({ where: { id: crew.masterAgentId } });
|
||
if (!masterAgent) throw new Error(`主 Agent 不存在`);
|
||
|
||
// 更新状态为 running
|
||
await this.crewRunRepo.update(runId, { status: 'running' } as any);
|
||
|
||
// 重新构建上下文并继续执行（将用户恢复消息追加到历史中）
|
||
// 简化实现：以用户消息重新触发，历史已持久化
|
||
const crewAgents = await this.crewAgentRepo.find({ where: { crewId: crew.id } });
|
||
const memberAgents = [];
|
||
for (const ca of crewAgents) {
|
||
if (ca.agentId === crew.masterAgentId) continue;
|
||
const agent = await this.agentRepo.findOne({ where: { id: ca.agentId } });
|
||
if (agent) {
|
||
memberAgents.push({ id: agent.id, name: agent.name, label: agent.label, role: ca.role || '', agent });
|
||
}
|
||
}
|
||
|
||
const ctx: CrewRunContext = {
|
||
runId, crewId: crew.id, masterAgentId: crew.masterAgentId,
|
||
memberAgents, maxConcurrent: crew.maxConcurrent || 3,
|
||
taskTimeout: crew.taskTimeout || 300, callbacks,
|
||
};
|
||
(ctx as any)._delegate = this.crewDelegate;
|
||
|
||
// 用恢复消息作为新一轮 triggerInput
|
||
this.runOrchestration(crew, masterAgent, ctx, `用户恢复指令: ${userMessage}`, callbacks)
|
||
.catch(err => this.logger.error(`恢复运行 ${runId} 失败:`, err));
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 2.5：实现 CrewService（集群 CRUD 业务层）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/service/crew.ts`
|
||
|
||
```typescript
|
||
import { Provide, Inject } from '@midwayjs/core';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository, In } from 'typeorm';
|
||
import { NetaClawCrewEntity } from '../entity/crew.js';
|
||
import { NetaClawCrewAgentEntity } from '../entity/crew_agent.js';
|
||
import { NetaClawAgentEntity } from '../entity/agent.js';
|
||
|
||
@Provide()
|
||
export class CrewService {
|
||
@InjectEntityModel(NetaClawCrewEntity)
|
||
crewRepo: Repository<NetaClawCrewEntity>;
|
||
|
||
@InjectEntityModel(NetaClawCrewAgentEntity)
|
||
crewAgentRepo: Repository<NetaClawCrewAgentEntity>;
|
||
|
||
@InjectEntityModel(NetaClawAgentEntity)
|
||
agentRepo: Repository<NetaClawAgentEntity>;
|
||
|
||
/**
|
||
* 保存画布数据 + 同步成员关系
|
||
*/
|
||
async saveCanvas(crewId: number, data: {
|
||
canvasData: any;
|
||
members: Array<{ agentId: number; role?: string; canvasPosition?: any; groupName?: string }>;
|
||
delegateHints?: any;
|
||
}): Promise<void> {
|
||
// 1. 更新画布数据
|
||
await this.crewRepo.update(crewId, {
|
||
canvasData: data.canvasData,
|
||
delegateHints: data.delegateHints,
|
||
} as any);
|
||
|
||
// 2. 同步成员关系（先删后插，简单可靠）
|
||
await this.crewAgentRepo.delete({ crewId });
|
||
if (data.members?.length) {
|
||
const entities = data.members.map(m => ({
|
||
crewId,
|
||
agentId: m.agentId,
|
||
role: m.role || '',
|
||
canvasPosition: m.canvasPosition,
|
||
groupName: m.groupName || '',
|
||
}));
|
||
await this.crewAgentRepo.save(entities as any[]);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 获取集群详情（含成员信息）
|
||
*/
|
||
async getDetail(crewId: number): Promise<any> {
|
||
const crew = await this.crewRepo.findOne({ where: { id: crewId } });
|
||
if (!crew) return null;
|
||
|
||
const crewAgents = await this.crewAgentRepo.find({ where: { crewId } });
|
||
const agentIds = crewAgents.map(ca => ca.agentId);
|
||
const agents = agentIds.length
|
||
? await this.agentRepo.find({ where: { id: In(agentIds) } })
|
||
: [];
|
||
|
||
const members = crewAgents.map(ca => {
|
||
const agent = agents.find(a => a.id === ca.agentId);
|
||
return {
|
||
...ca,
|
||
agentName: agent?.name,
|
||
agentLabel: agent?.label,
|
||
agentIcon: agent?.icon,
|
||
agentDescription: agent?.description,
|
||
};
|
||
});
|
||
|
||
return { ...crew, members };
|
||
}
|
||
|
||
/**
|
||
* 发布集群
|
||
*/
|
||
async publish(crewId: number): Promise<void> {
|
||
const crew = await this.crewRepo.findOne({ where: { id: crewId } });
|
||
if (!crew) throw new Error('集群不存在');
|
||
if (!crew.masterAgentId) throw new Error('请先设置主 Agent');
|
||
|
||
const members = await this.crewAgentRepo.find({ where: { crewId } });
|
||
if (members.length < 2) throw new Error('集群至少需要 2 个成员（含主 Agent）');
|
||
|
||
await this.crewRepo.update(crewId, { status: 1 } as any);
|
||
}
|
||
|
||
/**
|
||
* 取消发布
|
||
*/
|
||
async unpublish(crewId: number): Promise<void> {
|
||
await this.crewRepo.update(crewId, { status: 0 } as any);
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 2.6：验证核心引擎
|
||
|
||
此阶段暂不实现 Controller 和 WebSocket（Phase 3），但可通过单元测试或临时脚本验证：
|
||
|
||
**验证方式**：编写一个临时测试服务，在后端启动后通过 API 手动调用
|
||
|
||
```typescript
|
||
// 临时测试（可在 service 中加一个 test 方法）
|
||
// 1. 创建一个 crew 记录
|
||
// 2. 创建 crew_agent 记录
|
||
// 3. 调用 orchestrator.start()
|
||
// 4. 检查 crew_run 和 crew_task 表是否正确记录
|
||
```
|
||
|
||
**验证清单**：
|
||
- [ ] CrewDelegateService 可正确调用 runAgent() 执行子 Agent
|
||
- [ ] delegate_task 工具可找到目标 Agent 并返回结果
|
||
- [ ] delegate_parallel 工具可并行执行多个子 Agent
|
||
- [ ] escalate 工具可阻塞 ReAct 循环
|
||
- [ ] CrewOrchestrator 可完成完整的编排流程
|
||
- [ ] crew_run / crew_task 记录正确写入数据库
|
||
- [ ] token 消耗正确统计
|
||
|
||
### Step 2.7：提交代码
|
||
|
||
```bash
|
||
git add packages/backend/src/modules/netaclaw/service/crew_types.ts
|
||
git add packages/backend/src/modules/netaclaw/service/crew_delegate.ts
|
||
git add packages/backend/src/modules/netaclaw/service/crew_orchestrator.ts
|
||
git add packages/backend/src/modules/netaclaw/service/crew.ts
|
||
git add packages/backend/src/modules/netaclaw/tools/builtin/delegate_task.ts
|
||
git add packages/backend/src/modules/netaclaw/tools/builtin/delegate_parallel.ts
|
||
git add packages/backend/src/modules/netaclaw/tools/builtin/escalate.ts
|
||
git commit -m "feat(crew): 实现核心编排引擎 - Orchestrator + Delegate + 3个委派工具"
|
||
```
|
||
|
||
### Phase 2 验收
|
||
|
||
- [ ] `crew_types.ts` 共享类型定义完成
|
||
- [ ] `crew_delegate.ts` 子 Agent 执行器完成（含超时控制、并发限制）
|
||
- [ ] `delegate_task.ts` 串行委派工具完成
|
||
- [ ] `delegate_parallel.ts` 并行委派工具完成
|
||
- [ ] `escalate.ts` 升级人工工具完成（含暂停/恢复机制）
|
||
- [ ] `crew_orchestrator.ts` 核心编排器完成（含增强 prompt 构建）
|
||
- [ ] `crew.ts` 集群 CRUD 业务层完成
|
||
- [ ] 核心流程验证通过
|
||
- [ ] 代码已提交
|
||
|
||
---
|
||
|
||
## Phase 3：后端通信层（WebSocket + 触发 + 定时）
|
||
|
||
> 目标：实现 Controller API + CrewGateway WebSocket + 定时调度器
|
||
> 预估：2 天
|
||
> 依赖：Phase 2 完成
|
||
|
||
### Step 3.1：实现 Crew CRUD Controller
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/controller/admin/crew.ts`
|
||
|
||
```typescript
|
||
import { Body, Inject, Post, Provide } from '@midwayjs/core';
|
||
import { CoolController, BaseController } from '@cool-midway/core';
|
||
import { NetaClawCrewEntity } from '../../entity/crew.js';
|
||
import { CrewService } from '../../service/crew.js';
|
||
|
||
/**
|
||
* 集群管理 CRUD
|
||
* 自动生成: add / delete / update / info / list / page
|
||
*/
|
||
@Provide()
|
||
@CoolController({
|
||
api: ['add', 'delete', 'update', 'info', 'list', 'page'],
|
||
entity: NetaClawCrewEntity,
|
||
pageQueryOp: {
|
||
fieldEq: ['status'],
|
||
keyWordLikeFields: ['name', 'label'],
|
||
},
|
||
})
|
||
export class AdminCrewController extends BaseController {
|
||
@Inject()
|
||
crewService: CrewService;
|
||
|
||
/**
|
||
* 保存画布 + 同步成员关系
|
||
*/
|
||
@Post('/saveCanvas')
|
||
async saveCanvas(@Body() body: any) {
|
||
const { crewId, canvasData, members, delegateHints } = body;
|
||
await this.crewService.saveCanvas(crewId, { canvasData, members, delegateHints });
|
||
return this.ok();
|
||
}
|
||
|
||
/**
|
||
* 获取集群详情（含成员 Agent 信息）
|
||
*/
|
||
@Post('/detail')
|
||
async detail(@Body() body: any) {
|
||
const result = await this.crewService.getDetail(body.id);
|
||
return this.ok(result);
|
||
}
|
||
|
||
/**
|
||
* 发布集群
|
||
*/
|
||
@Post('/publish')
|
||
async publish(@Body() body: any) {
|
||
await this.crewService.publish(body.id);
|
||
return this.ok();
|
||
}
|
||
|
||
/**
|
||
* 取消发布
|
||
*/
|
||
@Post('/unpublish')
|
||
async unpublish(@Body() body: any) {
|
||
await this.crewService.unpublish(body.id);
|
||
return this.ok();
|
||
}
|
||
}
|
||
```
|
||
|
||
**自动生成的 API 端点**（Cool Admin 约定，路径基于 `controller/admin/` 目录结构）：
|
||
- `POST /admin/netaclaw/crew/add` — 创建集群
|
||
- `POST /admin/netaclaw/crew/delete` — 删除集群
|
||
- `POST /admin/netaclaw/crew/update` — 更新集群
|
||
- `POST /admin/netaclaw/crew/info` — 获取集群信息
|
||
- `POST /admin/netaclaw/crew/page` — 分页查询
|
||
- `POST /admin/netaclaw/crew/saveCanvas` — 保存画布
|
||
- `POST /admin/netaclaw/crew/detail` — 集群详情（含成员）
|
||
- `POST /admin/netaclaw/crew/publish` — 发布
|
||
- `POST /admin/netaclaw/crew/unpublish` — 取消发布
|
||
|
||
> **注意**：设计文档中写的 `POST /admin/crew/trigger/start` 是简写。实际 Cool Admin 路由映射为 `POST /admin/netaclaw/crewTrigger/start`（基于文件路径 `controller/admin/crew_trigger.ts`，驼峰转换）。前端通过 service 代理调用，无需关心具体路径。
|
||
|
||
**前端 service 代理路径**：`service.netaclaw.crew.saveCanvas()` 等
|
||
|
||
### Step 3.2：实现 Crew Run Controller
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/controller/admin/crew_run.ts`
|
||
|
||
```typescript
|
||
import { Provide } from '@midwayjs/core';
|
||
import { CoolController, BaseController } from '@cool-midway/core';
|
||
import { NetaClawCrewRunEntity } from '../../entity/crew_run.js';
|
||
|
||
/**
|
||
* 集群运行记录查询
|
||
*/
|
||
@Provide()
|
||
@CoolController({
|
||
api: ['info', 'list', 'page'],
|
||
entity: NetaClawCrewRunEntity,
|
||
pageQueryOp: {
|
||
fieldEq: ['crewId', 'status', 'triggerType'],
|
||
where: async (ctx) => {
|
||
// 可根据需求添加筛选逻辑
|
||
return [];
|
||
},
|
||
},
|
||
})
|
||
export class AdminCrewRunController extends BaseController {}
|
||
```
|
||
|
||
### Step 3.3：实现 Crew Trigger Controller
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/controller/admin/crew_trigger.ts`
|
||
|
||
```typescript
|
||
import { Body, Inject, Post, Provide } from '@midwayjs/core';
|
||
import { CoolController, BaseController } from '@cool-midway/core';
|
||
import { CrewOrchestratorService } from '../../service/crew_orchestrator.js';
|
||
import { escalateResolvers } from '../../tools/builtin/escalate.js';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawCrewRunEntity } from '../../entity/crew_run.js';
|
||
|
||
/**
|
||
* 集群触发控制
|
||
*/
|
||
@Provide()
|
||
@CoolController()
|
||
export class AdminCrewTriggerController extends BaseController {
|
||
@Inject()
|
||
orchestrator: CrewOrchestratorService;
|
||
|
||
@InjectEntityModel(NetaClawCrewRunEntity)
|
||
crewRunRepo: Repository<NetaClawCrewRunEntity>;
|
||
|
||
/**
|
||
* 手动触发运行
|
||
*/
|
||
@Post('/start')
|
||
async start(@Body() body: { crewId: number; triggerInput?: string }) {
|
||
const { crewId, triggerInput = '' } = body;
|
||
|
||
// 创建 noop 回调（WebSocket 推送在 Gateway 中处理）
|
||
// 这里提供基础回调，实际的 WebSocket 推送在 Phase 3.4 集成
|
||
const callbacks = this.createNoopCallbacks();
|
||
|
||
const runId = await this.orchestrator.start(crewId, 'manual', triggerInput, callbacks);
|
||
return this.ok({ runId });
|
||
}
|
||
|
||
/**
|
||
* 终止运行
|
||
*/
|
||
@Post('/stop')
|
||
async stop(@Body() body: { runId: number }) {
|
||
await this.orchestrator.stop(body.runId);
|
||
return this.ok();
|
||
}
|
||
|
||
/**
|
||
* 恢复暂停的运行（处理 escalate）
|
||
*/
|
||
@Post('/resume')
|
||
async resume(@Body() body: { runId: number; userMessage: string }) {
|
||
const { runId, userMessage } = body;
|
||
|
||
// 优先从内存 Map 中取出 resolve 回调
|
||
const resolver = escalateResolvers.get(runId);
|
||
if (resolver) {
|
||
// 内存中有 → 直接恢复（进程未重启）
|
||
resolver(userMessage);
|
||
escalateResolvers.delete(runId);
|
||
await this.crewRunRepo.update(runId, { status: 'running' } as any);
|
||
return this.ok();
|
||
}
|
||
|
||
// 内存中没有（进程重启了）→ 从 pausedState 恢复
|
||
const run = await this.crewRunRepo.findOne({ where: { id: runId } });
|
||
if (run?.pausedState) {
|
||
const history = JSON.parse(run.pausedState as string);
|
||
const callbacks = this.createNoopCallbacks();
|
||
await this.orchestrator.resumeFromPausedState(runId, history, userMessage, callbacks);
|
||
return this.ok();
|
||
}
|
||
|
||
return this.fail('运行已过期或无暂停状态，请重新触发');
|
||
}
|
||
|
||
/**
|
||
* 获取运行详情（含子任务列表）
|
||
*/
|
||
@Post('/runDetail')
|
||
async runDetail(@Body() body: { runId: number }) {
|
||
const run = await this.crewRunRepo.findOne({ where: { id: body.runId } });
|
||
// 查询关联的 crew_task
|
||
// ... 补充查询逻辑
|
||
return this.ok(run);
|
||
}
|
||
|
||
private createNoopCallbacks() {
|
||
return {
|
||
onLog: () => {},
|
||
onTaskStatus: () => {},
|
||
onRunStatus: () => {},
|
||
onEscalation: () => {},
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 3.4：实现 CrewGateway（WebSocket 网关）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/gateway/crew_server.ts`
|
||
|
||
> 独立 `/crew` 命名空间，与现有 `/netaclaw` 隔离。
|
||
|
||
```typescript
|
||
import { Inject, Logger, WSController, OnWSConnection, OnWSMessage } from '@midwayjs/core';
|
||
import { ILogger } from '@midwayjs/logger';
|
||
import { Context } from '@midwayjs/socketio';
|
||
import { CrewOrchestratorService } from '../service/crew_orchestrator.js';
|
||
import { escalateResolvers } from '../tools/builtin/escalate.js';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawCrewRunEntity } from '../entity/crew_run.js';
|
||
import { NetaClawCrewTaskEntity } from '../entity/crew_task.js';
|
||
import { CrewCallbacks } from '../service/crew_types.js';
|
||
|
||
/**
|
||
* Crew WebSocket 网关
|
||
* 命名空间: /crew
|
||
*
|
||
* 服务端 → 客户端事件:
|
||
* crew:run:status - 运行状态变更
|
||
* crew:task:status - 子任务状态变更
|
||
* crew:escalation - 升级人工通知
|
||
* crew:log - 实时日志
|
||
*
|
||
* 客户端 → 服务端事件:
|
||
* crew:trigger - 触发运行
|
||
* crew:control - 控制运行（暂停/恢复/终止）
|
||
*/
|
||
@WSController('/crew')
|
||
export class CrewGateway {
|
||
@Inject()
|
||
ctx: Context;
|
||
|
||
@Logger()
|
||
logger: ILogger;
|
||
|
||
@Inject()
|
||
orchestrator: CrewOrchestratorService;
|
||
|
||
@InjectEntityModel(NetaClawCrewRunEntity)
|
||
crewRunRepo: Repository<NetaClawCrewRunEntity>;
|
||
|
||
@OnWSConnection()
|
||
async onConnection() {
|
||
this.logger.info('[Crew WS] 客户端连接:', this.ctx.id);
|
||
}
|
||
|
||
@OnWSMessage('crew:trigger')
|
||
async onTrigger(data: { crewId: number; triggerInput?: string }) {
|
||
const { crewId, triggerInput = '' } = data;
|
||
|
||
// 构建 WebSocket 推送回调
|
||
const callbacks = this.createCallbacks();
|
||
|
||
try {
|
||
const runId = await this.orchestrator.start(crewId, 'manual', triggerInput, callbacks);
|
||
this.ctx.emit('crew:run:status', { runId, status: 'running' });
|
||
} catch (err: any) {
|
||
this.ctx.emit('crew:run:status', { runId: 0, status: 'failed', error: err.message });
|
||
}
|
||
}
|
||
|
||
@OnWSMessage('crew:control')
|
||
async onControl(data: { runId: number; action: string; userMessage?: string }) {
|
||
const { runId, action, userMessage } = data;
|
||
|
||
switch (action) {
|
||
case 'stop':
|
||
await this.orchestrator.stop(runId);
|
||
this.ctx.emit('crew:run:status', { runId, status: 'failed' });
|
||
break;
|
||
|
||
case 'resume':
|
||
const resolver = escalateResolvers.get(runId);
|
||
if (resolver) {
|
||
resolver(userMessage || '继续执行');
|
||
escalateResolvers.delete(runId);
|
||
await this.crewRunRepo.update(runId, { status: 'running' } as any);
|
||
this.ctx.emit('crew:run:status', { runId, status: 'running' });
|
||
}
|
||
break;
|
||
|
||
case 'pause':
|
||
await this.orchestrator.pause(runId);
|
||
this.ctx.emit('crew:run:status', { runId, status: 'paused' });
|
||
break;
|
||
|
||
case 'retry': {
|
||
// 重新触发一次运行（复制原 run 的 crewId 和 triggerInput）
|
||
const run = await this.crewRunRepo.findOne({ where: { id: runId } });
|
||
if (run) {
|
||
const callbacks = this.createCallbacks();
|
||
const newRunId = await this.orchestrator.start(run.crewId, 'manual', run.triggerInput || '', callbacks);
|
||
this.ctx.emit('crew:run:status', { runId: newRunId, status: 'running' });
|
||
}
|
||
break;
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 构建 WebSocket 推送回调
|
||
*/
|
||
private createCallbacks(): CrewCallbacks {
|
||
const ctx = this.ctx;
|
||
return {
|
||
onLog: (runId, taskId, agentName, level, message) => {
|
||
ctx.emit('crew:log', {
|
||
runId, taskId, agentName, level, message,
|
||
timestamp: new Date().toISOString(),
|
||
});
|
||
},
|
||
onTaskStatus: (runId, taskId, agentName, status, result, error) => {
|
||
ctx.emit('crew:task:status', { runId, taskId, agentName, status, result, error });
|
||
},
|
||
onRunStatus: (runId, status, progress) => {
|
||
ctx.emit('crew:run:status', { runId, status, progress });
|
||
},
|
||
onEscalation: (runId, taskId, reason, error) => {
|
||
ctx.emit('crew:escalation', { runId, taskId, reason, error });
|
||
},
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 3.5：实现 CrewScheduler（定时调度器）
|
||
|
||
**文件**：`packages/backend/src/modules/netaclaw/service/crew_scheduler.ts`
|
||
|
||
```typescript
|
||
import { Provide, Inject, Logger, Init } from '@midwayjs/core';
|
||
import { ILogger } from '@midwayjs/logger';
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { CronJob } from 'cron';
|
||
import { NetaClawCrewEntity } from '../entity/crew.js';
|
||
import { NetaClawCrewRunEntity } from '../entity/crew_run.js';
|
||
import { CrewOrchestratorService } from './crew_orchestrator.js';
|
||
import { escalateResolvers } from '../tools/builtin/escalate.js';
|
||
|
||
/**
|
||
* 集群定时调度器
|
||
* - 管理 CronJob 实例的动态创建/销毁
|
||
* - 服务启动时恢复已发布集群的定时任务
|
||
* - 服务启动时恢复 paused 状态的运行
|
||
*/
|
||
@Provide()
|
||
export class CrewSchedulerService {
|
||
@Logger()
|
||
logger: ILogger;
|
||
|
||
@InjectEntityModel(NetaClawCrewEntity)
|
||
crewRepo: Repository<NetaClawCrewEntity>;
|
||
|
||
@InjectEntityModel(NetaClawCrewRunEntity)
|
||
crewRunRepo: Repository<NetaClawCrewRunEntity>;
|
||
|
||
@Inject()
|
||
orchestrator: CrewOrchestratorService;
|
||
|
||
/** 活跃的 CronJob 实例 */
|
||
private activeJobs = new Map<number, CronJob>();
|
||
|
||
/**
|
||
* 服务启动时初始化
|
||
*/
|
||
@Init()
|
||
async init() {
|
||
// 延迟初始化，等待其他服务就绪
|
||
setTimeout(() => {
|
||
this.restoreSchedules().catch(err =>
|
||
this.logger.error('[CrewScheduler] 恢复定时任务失败:', err)
|
||
);
|
||
this.restorePausedRuns().catch(err =>
|
||
this.logger.error('[CrewScheduler] 恢复暂停运行失败:', err)
|
||
);
|
||
}, 5000);
|
||
}
|
||
|
||
/**
|
||
* 注册定时任务
|
||
*/
|
||
registerCron(crew: NetaClawCrewEntity): void {
|
||
if (!crew.triggerConfig?.cron?.enabled) return;
|
||
|
||
// 先取消已有的
|
||
this.unregisterCron(crew.id);
|
||
|
||
try {
|
||
const job = new CronJob(
|
||
crew.triggerConfig.cron.expression,
|
||
() => {
|
||
this.logger.info(`[CrewScheduler] 定时触发集群 ${crew.id}: ${crew.label}`);
|
||
const callbacks = {
|
||
onLog: () => {},
|
||
onTaskStatus: () => {},
|
||
onRunStatus: () => {},
|
||
onEscalation: () => {},
|
||
};
|
||
this.orchestrator.start(crew.id, 'cron', '', callbacks)
|
||
.catch(err => this.logger.error(`[CrewScheduler] 定时运行失败:`, err));
|
||
},
|
||
null,
|
||
true,
|
||
crew.triggerConfig.cron.timezone || 'Asia/Shanghai'
|
||
);
|
||
|
||
this.activeJobs.set(crew.id, job);
|
||
this.logger.info(`[CrewScheduler] 注册定时任务: 集群 ${crew.id}, cron=${crew.triggerConfig.cron.expression}`);
|
||
} catch (err) {
|
||
this.logger.error(`[CrewScheduler] 注册定时任务失败:`, err);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 取消定时任务
|
||
*/
|
||
unregisterCron(crewId: number): void {
|
||
const job = this.activeJobs.get(crewId);
|
||
if (job) {
|
||
job.stop();
|
||
this.activeJobs.delete(crewId);
|
||
this.logger.info(`[CrewScheduler] 取消定时任务: 集群 ${crewId}`);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 恢复所有已发布集群的定时任务
|
||
*/
|
||
private async restoreSchedules(): Promise<void> {
|
||
const publishedCrews = await this.crewRepo.find({ where: { status: 1 } });
|
||
const cronCrews = publishedCrews.filter(c => c.triggerConfig?.cron?.enabled);
|
||
|
||
this.logger.info(`[CrewScheduler] 恢复 ${cronCrews.length} 个定时任务`);
|
||
cronCrews.forEach(crew => this.registerCron(crew));
|
||
}
|
||
|
||
/**
|
||
* 恢复 paused 状态的运行（进程重启后）
|
||
*/
|
||
private async restorePausedRuns(): Promise<void> {
|
||
const pausedRuns = await this.crewRunRepo.find({ where: { status: 'paused' } });
|
||
|
||
if (pausedRuns.length === 0) return;
|
||
this.logger.info(`[CrewScheduler] 发现 ${pausedRuns.length} 个暂停的运行，等待用户恢复`);
|
||
|
||
// 暂停的运行不自动恢复，而是等待用户手动处理
|
||
// 如果 pausedState 存在，可以在用户恢复时使用
|
||
}
|
||
|
||
/**
|
||
* 获取活跃定时任务数
|
||
*/
|
||
getActiveJobCount(): number {
|
||
return this.activeJobs.size;
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 3.6：集成定时调度到发布/取消发布流程
|
||
|
||
**修改文件**：`packages/backend/src/modules/netaclaw/service/crew.ts`
|
||
|
||
在 `publish()` 和 `unpublish()` 方法中注入调度器：
|
||
|
||
```typescript
|
||
// 在 CrewService 中注入
|
||
@Inject()
|
||
scheduler: CrewSchedulerService;
|
||
|
||
// publish() 中追加：
|
||
async publish(crewId: number): Promise<void> {
|
||
// ... 现有校验逻辑 ...
|
||
await this.crewRepo.update(crewId, { status: 1 } as any);
|
||
|
||
// 注册定时任务
|
||
const crew = await this.crewRepo.findOne({ where: { id: crewId } });
|
||
if (crew) this.scheduler.registerCron(crew);
|
||
}
|
||
|
||
// unpublish() 中追加：
|
||
async unpublish(crewId: number): Promise<void> {
|
||
await this.crewRepo.update(crewId, { status: 0 } as any);
|
||
|
||
// 取消定时任务
|
||
this.scheduler.unregisterCron(crewId);
|
||
}
|
||
```
|
||
|
||
### Step 3.7：验证通信层
|
||
|
||
**验证清单**：
|
||
- [ ] **CRUD API**：通过 Postman/curl 测试集群的创建、查询、更新、删除
|
||
- [ ] **画布保存**：`saveCanvas` API 正确保存 canvasData + 同步成员关系
|
||
- [ ] **发布流程**：发布时校验主 Agent 和成员数量
|
||
- [ ] **手动触发**：通过 REST API 和 WebSocket 均可触发运行
|
||
- [ ] **WebSocket 事件**：连接 `/crew` 命名空间，触发运行后能收到 `crew:run:status`、`crew:task:status`、`crew:log` 事件
|
||
- [ ] **终止运行**：`crew:control { action: 'stop' }` 正确终止
|
||
- [ ] **升级恢复**：escalate 后通过 `crew:control { action: 'resume' }` 正确恢复
|
||
- [ ] **定时调度**：发布带 cron 配置的集群后，定时任务注册成功
|
||
- [ ] 前端 service 代理路径可访问：`service.netaclaw.crew.*`
|
||
|
||
### Step 3.8：提交代码
|
||
|
||
```bash
|
||
git add packages/backend/src/modules/netaclaw/controller/admin/crew*.ts
|
||
git add packages/backend/src/modules/netaclaw/gateway/crew_server.ts
|
||
git add packages/backend/src/modules/netaclaw/service/crew_scheduler.ts
|
||
# + crew.ts 的修改
|
||
git commit -m "feat(crew): 实现通信层 - Controller + WebSocket Gateway + 定时调度器"
|
||
```
|
||
|
||
### Phase 3 验收
|
||
|
||
- [ ] 3 个 Controller 创建完成（crew / crew_run / crew_trigger）
|
||
- [ ] CrewGateway WebSocket 网关工作正常
|
||
- [ ] CrewScheduler 定时调度器工作正常
|
||
- [ ] 发布/取消发布联动定时调度
|
||
- [ ] REST API + WebSocket 双通道触发验证通过
|
||
- [ ] 代码已提交
|
||
|
||
---
|
||
|
||
## Phase 4：前端编排页
|
||
|
||
> 目标：实现完整的集群编排画布页面（Vue Flow 画布 + Agent 侧栏 + 属性面板）
|
||
> 预估：3 天（Vue Flow 首次使用，额外预留缓冲）
|
||
> 依赖：Phase 3 完成（后端 API 可用）
|
||
|
||
### Step 4.1：注册路由与菜单
|
||
|
||
#### 4.1.1 修改前端路由配置
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/config.ts`
|
||
|
||
在 views 数组中追加：
|
||
|
||
```typescript
|
||
{
|
||
path: '/agent/crew-editor',
|
||
meta: { label: 'Agent 编排' },
|
||
component: () => import('./views/crew-editor.vue')
|
||
},
|
||
{
|
||
path: '/agent/crew-monitor',
|
||
meta: { label: '运行监控' },
|
||
component: () => import('./views/crew-monitor.vue')
|
||
},
|
||
```
|
||
|
||
#### 4.1.2 插入菜单记录
|
||
|
||
通过数据库插入 `base_sys_menu` 记录（Cool Admin 菜单管理）：
|
||
|
||
```sql
|
||
-- 在 Agent 管理父菜单下新增
|
||
INSERT INTO base_sys_menu (name, router, parentId, orderNum, type, icon, perms)
|
||
VALUES
|
||
('Agent 编排', '/agent/crew-editor', <agent父菜单ID>, 5, 1, 'icon-crew', 'agent:crew:editor'),
|
||
('运行监控', '/agent/crew-monitor', <agent父菜单ID>, 6, 1, 'icon-monitor', 'agent:crew:monitor');
|
||
```
|
||
|
||
> 具体 parentId 需查询当前数据库中 Agent 管理的菜单 ID。
|
||
|
||
### Step 4.2：实现 Pinia Store
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/store/crew.ts`
|
||
|
||
```typescript
|
||
import { defineStore } from 'pinia';
|
||
import { ref, computed } from 'vue';
|
||
import { useCool } from '/@/cool';
|
||
|
||
/**
|
||
* Crew 编排状态管理
|
||
*/
|
||
export const useCrewStore = defineStore('agent-crew', () => {
|
||
const { service } = useCool();
|
||
|
||
// 集群列表
|
||
const crewList = ref<any[]>([]);
|
||
// 当前编辑的集群
|
||
const currentCrew = ref<any>(null);
|
||
// 当前集群的成员列表
|
||
const currentMembers = ref<any[]>([]);
|
||
// 可用 Agent 列表（已发布的 Agent）
|
||
const availableAgents = ref<any[]>([]);
|
||
|
||
// 加载集群列表
|
||
async function loadCrewList() {
|
||
const res = await service.netaclaw.crew.list();
|
||
crewList.value = res || [];
|
||
}
|
||
|
||
// 加载集群详情
|
||
async function loadCrewDetail(crewId: number) {
|
||
const res = await service.netaclaw.crew.detail({ id: crewId });
|
||
currentCrew.value = res;
|
||
currentMembers.value = res?.members || [];
|
||
return res;
|
||
}
|
||
|
||
// 加载可用 Agent
|
||
async function loadAvailableAgents() {
|
||
const res = await service.netaclaw.agent.list({ status: 1 });
|
||
availableAgents.value = res || [];
|
||
}
|
||
|
||
// 保存画布
|
||
async function saveCanvas(crewId: number, canvasData: any, members: any[], delegateHints: any) {
|
||
await service.netaclaw.crew.saveCanvas({
|
||
crewId, canvasData, members, delegateHints,
|
||
});
|
||
}
|
||
|
||
// 创建集群
|
||
async function createCrew(data: any) {
|
||
const res = await service.netaclaw.crew.add(data);
|
||
await loadCrewList();
|
||
return res;
|
||
}
|
||
|
||
// 发布/取消发布
|
||
async function publish(crewId: number) {
|
||
await service.netaclaw.crew.publish({ id: crewId });
|
||
await loadCrewDetail(crewId);
|
||
}
|
||
|
||
async function unpublish(crewId: number) {
|
||
await service.netaclaw.crew.unpublish({ id: crewId });
|
||
await loadCrewDetail(crewId);
|
||
}
|
||
|
||
// 判断某 Agent 是否已在当前集群中
|
||
const isMember = computed(() => {
|
||
const ids = new Set(currentMembers.value.map((m: any) => m.agentId));
|
||
return (agentId: number) => ids.has(agentId);
|
||
});
|
||
|
||
return {
|
||
crewList, currentCrew, currentMembers, availableAgents,
|
||
loadCrewList, loadCrewDetail, loadAvailableAgents,
|
||
saveCanvas, createCrew, publish, unpublish,
|
||
isMember,
|
||
};
|
||
});
|
||
```
|
||
|
||
### Step 4.3：实现画布核心 Hook
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/hooks/crew-canvas.ts`
|
||
|
||
```typescript
|
||
import { ref, watch } from 'vue';
|
||
import { useVueFlow, type Node, type Edge } from '@vue-flow/core';
|
||
|
||
/**
|
||
* 画布操作 Hook
|
||
* 封装 Vue Flow 的节点/连线增删、序列化/反序列化
|
||
*/
|
||
export function useCrewCanvas() {
|
||
const {
|
||
nodes, edges, addNodes, removeNodes,
|
||
addEdges, removeEdges, fitView,
|
||
onConnect, onNodeDragStop,
|
||
} = useVueFlow();
|
||
|
||
// 主 Agent ID
|
||
const masterAgentId = ref<number | null>(null);
|
||
|
||
/**
|
||
* 添加 Agent 节点到画布
|
||
*/
|
||
function addAgentNode(agent: any, position?: { x: number; y: number }) {
|
||
const id = `agent-${agent.id}`;
|
||
|
||
// 避免重复添加
|
||
if (nodes.value.find(n => n.id === id)) return;
|
||
|
||
const node: Node = {
|
||
id,
|
||
type: 'crew-agent', // 自定义节点类型
|
||
position: position || { x: Math.random() * 400 + 100, y: Math.random() * 300 + 100 },
|
||
data: {
|
||
agentId: agent.id,
|
||
name: agent.name,
|
||
label: agent.label,
|
||
icon: agent.icon,
|
||
description: agent.description,
|
||
role: '',
|
||
groupName: '',
|
||
isMaster: agent.id === masterAgentId.value,
|
||
},
|
||
};
|
||
|
||
addNodes([node]);
|
||
}
|
||
|
||
/**
|
||
* 移除 Agent 节点
|
||
*/
|
||
function removeAgentNode(agentId: number) {
|
||
const nodeId = `agent-${agentId}`;
|
||
const node = nodes.value.find(n => n.id === nodeId);
|
||
if (node) removeNodes([node]);
|
||
}
|
||
|
||
/**
|
||
* 设置主 Agent
|
||
*/
|
||
function setMasterAgent(agentId: number) {
|
||
masterAgentId.value = agentId;
|
||
// 更新所有节点的 isMaster 标记
|
||
nodes.value.forEach(n => {
|
||
if (n.data) {
|
||
n.data.isMaster = n.data.agentId === agentId;
|
||
}
|
||
});
|
||
}
|
||
|
||
/**
|
||
* 序列化画布数据（保存用）
|
||
*/
|
||
function serializeCanvas() {
|
||
return {
|
||
nodes: nodes.value.map(n => ({
|
||
id: n.id,
|
||
type: n.type,
|
||
position: n.position,
|
||
data: n.data,
|
||
})),
|
||
edges: edges.value.map(e => ({
|
||
id: e.id,
|
||
source: e.source,
|
||
target: e.target,
|
||
data: e.data,
|
||
})),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* 反序列化画布数据（加载用）
|
||
*/
|
||
function deserializeCanvas(canvasData: any) {
|
||
if (!canvasData?.nodes) return;
|
||
|
||
// 清空当前画布
|
||
removeNodes(nodes.value);
|
||
removeEdges(edges.value);
|
||
|
||
// 恢复节点
|
||
addNodes(canvasData.nodes.map((n: any) => ({
|
||
...n,
|
||
type: n.type || 'crew-agent',
|
||
})));
|
||
|
||
// 恢复连线
|
||
if (canvasData.edges?.length) {
|
||
addEdges(canvasData.edges);
|
||
}
|
||
|
||
// 延迟 fitView
|
||
setTimeout(() => fitView({ padding: 0.2 }), 100);
|
||
}
|
||
|
||
/**
|
||
* 从画布状态提取成员列表（保存到 crew_agent 表）
|
||
*/
|
||
function extractMembers() {
|
||
return nodes.value
|
||
.filter(n => n.data?.agentId)
|
||
.map(n => ({
|
||
agentId: n.data.agentId,
|
||
role: n.data.role || '',
|
||
canvasPosition: n.position,
|
||
groupName: n.data.groupName || '',
|
||
}));
|
||
}
|
||
|
||
return {
|
||
nodes, edges, masterAgentId,
|
||
addAgentNode, removeAgentNode, setMasterAgent,
|
||
serializeCanvas, deserializeCanvas, extractMembers,
|
||
onConnect, onNodeDragStop, fitView,
|
||
};
|
||
}
|
||
```
|
||
|
||
### Step 4.4：实现画布 → delegateHints 转换 Hook
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/hooks/crew-orchestration.ts`
|
||
|
||
```typescript
|
||
import type { Edge, Node } from '@vue-flow/core';
|
||
|
||
/**
|
||
* 从画布连线生成 delegateHints
|
||
* 供主 Agent system prompt 使用
|
||
*/
|
||
export function canvasToHints(
|
||
nodes: Node[],
|
||
edges: Edge[]
|
||
): { hints: string; edges: Array<{ from: string; to: string; type: string; note?: string }> } {
|
||
if (!edges.length) {
|
||
return { hints: '无特定调度建议，请根据任务需求自行安排。', edges: [] };
|
||
}
|
||
|
||
const nodeMap = new Map<string, string>();
|
||
nodes.forEach(n => {
|
||
if (n.data?.label) nodeMap.set(n.id, n.data.label);
|
||
});
|
||
|
||
// 解析连线
|
||
const edgeInfos = edges.map(e => ({
|
||
from: nodeMap.get(e.source) || e.source,
|
||
to: nodeMap.get(e.target) || e.target,
|
||
type: e.data?.edgeType || 'serial',
|
||
note: e.data?.note || '',
|
||
}));
|
||
|
||
// 生成自然语言提示
|
||
const serialEdges = edgeInfos.filter(e => e.type === 'serial');
|
||
const parallelEdges = edgeInfos.filter(e => e.type === 'parallel');
|
||
|
||
let hints = '建议执行顺序：\n';
|
||
|
||
if (serialEdges.length) {
|
||
// 构建串行链
|
||
const chains: string[] = [];
|
||
serialEdges.forEach(e => {
|
||
const note = e.note ? `（${e.note}）` : '';
|
||
chains.push(`${e.from} → ${e.to}${note}`);
|
||
});
|
||
hints += `串行依赖：${chains.join('；')}\n`;
|
||
}
|
||
|
||
if (parallelEdges.length) {
|
||
const parallel = parallelEdges.map(e => `${e.from} 与 ${e.to}`);
|
||
hints += `可并行执行：${parallel.join('；')}\n`;
|
||
}
|
||
|
||
return { hints, edges: edgeInfos };
|
||
}
|
||
```
|
||
|
||
### Step 4.5：实现自定义节点组件
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-agent-node.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div
|
||
class="crew-agent-node"
|
||
:class="{
|
||
'is-master': data.isMaster,
|
||
'is-running': liveStatus === 'running',
|
||
'is-completed': liveStatus === 'completed',
|
||
'is-failed': liveStatus === 'failed',
|
||
}"
|
||
>
|
||
<!-- 主 Agent 星标 -->
|
||
<div v-if="data.isMaster" class="master-badge">★</div>
|
||
|
||
<!-- 分组色带 -->
|
||
<div v-if="data.groupName" class="group-ribbon" :style="{ background: groupColor }">
|
||
{{ data.groupName }}
|
||
</div>
|
||
|
||
<!-- Agent 图标 -->
|
||
<div class="node-icon">
|
||
<el-icon v-if="data.icon" :size="28"><component :is="data.icon" /></el-icon>
|
||
<el-icon v-else :size="28"><UserFilled /></el-icon>
|
||
</div>
|
||
|
||
<!-- Agent 名称 -->
|
||
<div class="node-label">{{ data.label || data.name }}</div>
|
||
|
||
<!-- 角色标签 -->
|
||
<div v-if="data.role" class="node-role">{{ data.role }}</div>
|
||
|
||
<!-- 连线锚点 (四边) -->
|
||
<Handle type="source" :position="Position.Right" />
|
||
<Handle type="source" :position="Position.Bottom" />
|
||
<Handle type="target" :position="Position.Left" />
|
||
<Handle type="target" :position="Position.Top" />
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { computed } from 'vue';
|
||
import { Handle, Position } from '@vue-flow/core';
|
||
import { UserFilled } from '@element-plus/icons-vue';
|
||
|
||
const props = defineProps<{
|
||
data: {
|
||
agentId: number;
|
||
name: string;
|
||
label: string;
|
||
icon?: string;
|
||
description?: string;
|
||
role?: string;
|
||
groupName?: string;
|
||
isMaster?: boolean;
|
||
};
|
||
liveStatus?: string; // 监控页使用
|
||
}>();
|
||
|
||
// 分组颜色（基于名称 hash）
|
||
const groupColor = computed(() => {
|
||
if (!props.data.groupName) return '';
|
||
const hash = [...props.data.groupName].reduce((acc, c) => acc + c.charCodeAt(0), 0);
|
||
const hue = hash % 360;
|
||
return `hsl(${hue}, 60%, 85%)`;
|
||
});
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-agent-node {
|
||
padding: 12px 16px;
|
||
border: 2px solid #e0e0e0;
|
||
border-radius: 12px;
|
||
background: white;
|
||
min-width: 140px;
|
||
text-align: center;
|
||
position: relative;
|
||
transition: all 0.3s;
|
||
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
|
||
}
|
||
|
||
.crew-agent-node:hover {
|
||
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
|
||
}
|
||
|
||
.crew-agent-node.is-master {
|
||
border-color: #e6a23c;
|
||
background: linear-gradient(135deg, #fffbf0, #fff8e6);
|
||
}
|
||
|
||
.crew-agent-node.is-running {
|
||
border-color: #409eff;
|
||
animation: breathe 2s ease-in-out infinite;
|
||
}
|
||
|
||
.crew-agent-node.is-completed {
|
||
border-color: #67c23a;
|
||
}
|
||
|
||
.crew-agent-node.is-failed {
|
||
border-color: #f56c6c;
|
||
}
|
||
|
||
.master-badge {
|
||
position: absolute;
|
||
top: -8px;
|
||
right: -8px;
|
||
width: 24px;
|
||
height: 24px;
|
||
background: #e6a23c;
|
||
color: white;
|
||
border-radius: 50%;
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
font-size: 14px;
|
||
}
|
||
|
||
.group-ribbon {
|
||
position: absolute;
|
||
top: 0;
|
||
left: 0;
|
||
right: 0;
|
||
padding: 2px 8px;
|
||
font-size: 10px;
|
||
border-radius: 10px 10px 0 0;
|
||
text-align: center;
|
||
}
|
||
|
||
.node-icon { margin-bottom: 6px; }
|
||
.node-label { font-weight: 600; font-size: 14px; }
|
||
.node-role { font-size: 11px; color: #909399; margin-top: 4px; }
|
||
|
||
@keyframes breathe {
|
||
0%, 100% { box-shadow: 0 0 0 0 rgba(64, 158, 255, 0.4); }
|
||
50% { box-shadow: 0 0 0 8px rgba(64, 158, 255, 0); }
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Step 4.6：实现自定义连线标签
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-edge-label.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-edge-label" :class="{ 'is-parallel': isParallel }">
|
||
<el-icon :size="14">
|
||
<component :is="isParallel ? 'Refresh' : 'Right'" />
|
||
</el-icon>
|
||
<span v-if="label">{{ label }}</span>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { computed } from 'vue';
|
||
|
||
const props = defineProps<{
|
||
data?: { edgeType?: string; note?: string };
|
||
}>();
|
||
|
||
const isParallel = computed(() => props.data?.edgeType === 'parallel');
|
||
const label = computed(() => props.data?.note || '');
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-edge-label {
|
||
display: flex;
|
||
align-items: center;
|
||
gap: 4px;
|
||
padding: 2px 8px;
|
||
background: white;
|
||
border: 1px solid #ddd;
|
||
border-radius: 10px;
|
||
font-size: 11px;
|
||
white-space: nowrap;
|
||
}
|
||
.crew-edge-label.is-parallel {
|
||
border-color: #409eff;
|
||
color: #409eff;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Step 4.7：实现左侧 Agent 列表
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-sidebar.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-sidebar">
|
||
<el-input v-model="search" placeholder="搜索 Agent..." clearable prefix-icon="Search" />
|
||
|
||
<div class="agent-list">
|
||
<div
|
||
v-for="agent in filteredAgents"
|
||
:key="agent.id"
|
||
class="agent-item"
|
||
:class="{ 'is-member': isMember(agent.id) }"
|
||
draggable="true"
|
||
@dragstart="onDragStart($event, agent)"
|
||
>
|
||
<div class="agent-info">
|
||
<span class="agent-name">{{ agent.label || agent.name }}</span>
|
||
<span class="agent-desc">{{ agent.description }}</span>
|
||
</div>
|
||
<el-icon v-if="isMember(agent.id)" color="#67c23a"><Check /></el-icon>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref, computed } from 'vue';
|
||
import { Check } from '@element-plus/icons-vue';
|
||
|
||
const props = defineProps<{
|
||
agents: any[];
|
||
isMember: (id: number) => boolean;
|
||
}>();
|
||
|
||
const emit = defineEmits<{
|
||
(e: 'drop-agent', agent: any, position: { x: number; y: number }): void;
|
||
}>();
|
||
|
||
const search = ref('');
|
||
|
||
const filteredAgents = computed(() => {
|
||
if (!search.value) return props.agents;
|
||
const q = search.value.toLowerCase();
|
||
return props.agents.filter(a =>
|
||
a.name?.toLowerCase().includes(q) ||
|
||
a.label?.toLowerCase().includes(q) ||
|
||
a.description?.toLowerCase().includes(q)
|
||
);
|
||
});
|
||
|
||
function onDragStart(event: DragEvent, agent: any) {
|
||
event.dataTransfer?.setData('application/crew-agent', JSON.stringify(agent));
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-sidebar {
|
||
width: 240px;
|
||
border-right: 1px solid #eee;
|
||
padding: 12px;
|
||
display: flex;
|
||
flex-direction: column;
|
||
gap: 8px;
|
||
}
|
||
.agent-list { flex: 1; overflow-y: auto; }
|
||
.agent-item {
|
||
padding: 10px 12px;
|
||
border: 1px solid #eee;
|
||
border-radius: 8px;
|
||
margin-bottom: 8px;
|
||
cursor: grab;
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: space-between;
|
||
transition: background 0.2s;
|
||
}
|
||
.agent-item:hover { background: #f5f7fa; }
|
||
.agent-item.is-member { background: #f0f9eb; }
|
||
.agent-info { flex: 1; }
|
||
.agent-name { font-weight: 500; display: block; }
|
||
.agent-desc { font-size: 12px; color: #909399; }
|
||
</style>
|
||
```
|
||
|
||
### Step 4.8：实现属性面板
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-property-panel.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-property-panel">
|
||
<!-- 选中节点时 -->
|
||
<template v-if="selectedNode">
|
||
<h4>Agent 属性</h4>
|
||
<el-form label-position="top" size="small">
|
||
<el-form-item label="名称">
|
||
<span>{{ selectedNode.data.label }}</span>
|
||
</el-form-item>
|
||
<el-form-item label="角色描述">
|
||
<el-input
|
||
v-model="selectedNode.data.role"
|
||
type="textarea"
|
||
:rows="3"
|
||
placeholder="描述该 Agent 在集群中的角色..."
|
||
/>
|
||
</el-form-item>
|
||
<el-form-item label="分组">
|
||
<el-input v-model="selectedNode.data.groupName" placeholder="如：淘宝组" />
|
||
</el-form-item>
|
||
<el-form-item label="重试次数">
|
||
<el-input-number v-model="selectedNode.data.retryCount" :min="0" :max="5" />
|
||
</el-form-item>
|
||
<el-button type="primary" text @click="$emit('set-master', selectedNode.data.agentId)">
|
||
设为主 Agent
|
||
</el-button>
|
||
</el-form>
|
||
</template>
|
||
|
||
<!-- 选中连线时 -->
|
||
<template v-else-if="selectedEdge">
|
||
<h4>连线属性</h4>
|
||
<el-form label-position="top" size="small">
|
||
<el-form-item label="类型">
|
||
<el-radio-group v-model="selectedEdge.data.edgeType">
|
||
<el-radio value="serial">串行依赖</el-radio>
|
||
<el-radio value="parallel">并行建议</el-radio>
|
||
</el-radio-group>
|
||
</el-form-item>
|
||
<el-form-item label="标注">
|
||
<el-input v-model="selectedEdge.data.note" placeholder="如：需要先登录获取cookie" />
|
||
</el-form-item>
|
||
</el-form>
|
||
</template>
|
||
|
||
<!-- 未选中时：全局配置 -->
|
||
<template v-else>
|
||
<h4>集群配置</h4>
|
||
<el-form v-if="crew" label-position="top" size="small">
|
||
<el-form-item label="集群名称">
|
||
<el-input v-model="crew.label" />
|
||
</el-form-item>
|
||
<el-form-item label="描述">
|
||
<el-input v-model="crew.description" type="textarea" :rows="2" />
|
||
</el-form-item>
|
||
<el-form-item label="最大并发数">
|
||
<el-input-number v-model="crew.maxConcurrent" :min="1" :max="10" />
|
||
</el-form-item>
|
||
<el-form-item label="默认超时（秒）">
|
||
<el-input-number v-model="crew.taskTimeout" :min="60" :max="3600" :step="60" />
|
||
</el-form-item>
|
||
<!-- 触发配置子组件 -->
|
||
<crew-trigger-config v-model="crew.triggerConfig" />
|
||
</el-form>
|
||
</template>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import CrewTriggerConfig from './crew-trigger-config.vue';
|
||
|
||
defineProps<{
|
||
selectedNode?: any;
|
||
selectedEdge?: any;
|
||
crew?: any;
|
||
}>();
|
||
|
||
defineEmits<{
|
||
(e: 'set-master', agentId: number): void;
|
||
}>();
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-property-panel {
|
||
border-top: 1px solid #eee;
|
||
padding: 12px 16px;
|
||
max-height: 280px;
|
||
overflow-y: auto;
|
||
}
|
||
h4 { margin: 0 0 12px; font-size: 14px; }
|
||
</style>
|
||
```
|
||
|
||
### Step 4.9：实现触发配置子组件
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-trigger-config.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="trigger-config">
|
||
<el-divider content-position="left">触发方式</el-divider>
|
||
|
||
<el-form-item label="手动触发">
|
||
<el-switch v-model="config.manual" />
|
||
</el-form-item>
|
||
|
||
<el-form-item label="定时触发">
|
||
<el-switch v-model="config.cron.enabled" />
|
||
</el-form-item>
|
||
<template v-if="config.cron?.enabled">
|
||
<el-form-item label="Cron 表达式">
|
||
<el-input v-model="config.cron.expression" placeholder="0 9 * * *" />
|
||
</el-form-item>
|
||
<el-form-item label="时区">
|
||
<el-select v-model="config.cron.timezone">
|
||
<el-option value="Asia/Shanghai" label="Asia/Shanghai" />
|
||
<el-option value="UTC" label="UTC" />
|
||
</el-select>
|
||
</el-form-item>
|
||
</template>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { reactive, watch } from 'vue';
|
||
|
||
const props = defineProps<{ modelValue?: any }>();
|
||
const emit = defineEmits<{ (e: 'update:modelValue', v: any): void }>();
|
||
|
||
const config = reactive({
|
||
manual: true,
|
||
cron: { enabled: false, expression: '0 9 * * *', timezone: 'Asia/Shanghai' },
|
||
...props.modelValue,
|
||
});
|
||
|
||
watch(config, (v) => emit('update:modelValue', { ...v }), { deep: true });
|
||
</script>
|
||
```
|
||
|
||
### Step 4.10：实现编排页主视图
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/views/crew-editor.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-editor">
|
||
<!-- 顶部工具栏 -->
|
||
<div class="toolbar">
|
||
<el-select v-model="selectedCrewId" placeholder="选择集群" @change="onCrewChange">
|
||
<el-option
|
||
v-for="c in crewStore.crewList"
|
||
:key="c.id" :label="c.label" :value="c.id"
|
||
/>
|
||
</el-select>
|
||
<el-button @click="onNewCrew">+ 新建集群</el-button>
|
||
<el-divider direction="vertical" />
|
||
<el-button type="primary" @click="onSave" :loading="saving">保存</el-button>
|
||
<el-button
|
||
v-if="crewStore.currentCrew?.status === 0"
|
||
type="success" @click="onPublish"
|
||
>发布</el-button>
|
||
<el-button
|
||
v-else-if="crewStore.currentCrew?.status === 1"
|
||
type="warning" @click="onUnpublish"
|
||
>取消发布</el-button>
|
||
<el-button @click="onTestRun" :disabled="crewStore.currentCrew?.status !== 1">
|
||
试运行
|
||
</el-button>
|
||
</div>
|
||
|
||
<!-- 主体：左侧栏 + 画布 -->
|
||
<div class="main-area">
|
||
<crew-sidebar
|
||
:agents="crewStore.availableAgents"
|
||
:is-member="crewStore.isMember"
|
||
/>
|
||
|
||
<div class="canvas-container" @drop="onDrop" @dragover.prevent>
|
||
<VueFlow
|
||
:nodes="canvasHook.nodes.value"
|
||
:edges="canvasHook.edges.value"
|
||
@node-click="onNodeClick"
|
||
@edge-click="onEdgeClick"
|
||
@pane-click="onPaneClick"
|
||
@connect="onConnect"
|
||
>
|
||
<template #node-crew-agent="{ data }">
|
||
<crew-agent-node :data="data" />
|
||
</template>
|
||
|
||
<MiniMap />
|
||
<Controls />
|
||
<Background />
|
||
</VueFlow>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 底部属性面板 -->
|
||
<crew-property-panel
|
||
:selected-node="selectedNode"
|
||
:selected-edge="selectedEdge"
|
||
:crew="crewStore.currentCrew"
|
||
@set-master="onSetMaster"
|
||
/>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref, onMounted } from 'vue';
|
||
import { VueFlow } from '@vue-flow/core';
|
||
import { MiniMap } from '@vue-flow/minimap';
|
||
import { Controls } from '@vue-flow/controls';
|
||
import { Background } from '@vue-flow/background';
|
||
import '@vue-flow/core/dist/style.css';
|
||
import '@vue-flow/core/dist/theme-default.css';
|
||
import '@vue-flow/minimap/dist/style.css';
|
||
import '@vue-flow/controls/dist/style.css';
|
||
import { useRouter } from 'vue-router';
|
||
import { ElMessage } from 'element-plus';
|
||
import { useCrewStore } from '../store/crew';
|
||
import { useCrewCanvas } from '../hooks/crew-canvas';
|
||
import { canvasToHints } from '../hooks/crew-orchestration';
|
||
import CrewSidebar from '../components/crew/crew-sidebar.vue';
|
||
import CrewAgentNode from '../components/crew/crew-agent-node.vue';
|
||
import CrewPropertyPanel from '../components/crew/crew-property-panel.vue';
|
||
|
||
const router = useRouter();
|
||
const crewStore = useCrewStore();
|
||
const canvasHook = useCrewCanvas();
|
||
|
||
const selectedCrewId = ref<number | null>(null);
|
||
const selectedNode = ref<any>(null);
|
||
const selectedEdge = ref<any>(null);
|
||
const saving = ref(false);
|
||
|
||
onMounted(async () => {
|
||
await crewStore.loadCrewList();
|
||
await crewStore.loadAvailableAgents();
|
||
});
|
||
|
||
async function onCrewChange(crewId: number) {
|
||
const detail = await crewStore.loadCrewDetail(crewId);
|
||
if (detail?.canvasData) {
|
||
canvasHook.deserializeCanvas(detail.canvasData);
|
||
}
|
||
if (detail?.masterAgentId) {
|
||
canvasHook.setMasterAgent(detail.masterAgentId);
|
||
}
|
||
}
|
||
|
||
function onNodeClick({ node }: any) {
|
||
selectedNode.value = node;
|
||
selectedEdge.value = null;
|
||
}
|
||
|
||
function onEdgeClick({ edge }: any) {
|
||
selectedEdge.value = edge;
|
||
selectedNode.value = null;
|
||
// 确保 edge.data 存在
|
||
if (!edge.data) edge.data = { edgeType: 'serial', note: '' };
|
||
}
|
||
|
||
function onPaneClick() {
|
||
selectedNode.value = null;
|
||
selectedEdge.value = null;
|
||
}
|
||
|
||
function onConnect(params: any) {
|
||
canvasHook.edges.value.push({
|
||
...params,
|
||
id: `e-${params.source}-${params.target}`,
|
||
data: { edgeType: 'serial', note: '' },
|
||
});
|
||
}
|
||
|
||
function onDrop(event: DragEvent) {
|
||
const data = event.dataTransfer?.getData('application/crew-agent');
|
||
if (!data) return;
|
||
const agent = JSON.parse(data);
|
||
const rect = (event.target as HTMLElement).getBoundingClientRect();
|
||
canvasHook.addAgentNode(agent, {
|
||
x: event.clientX - rect.left,
|
||
y: event.clientY - rect.top,
|
||
});
|
||
}
|
||
|
||
function onSetMaster(agentId: number) {
|
||
canvasHook.setMasterAgent(agentId);
|
||
if (crewStore.currentCrew) {
|
||
crewStore.currentCrew.masterAgentId = agentId;
|
||
}
|
||
}
|
||
|
||
async function onSave() {
|
||
if (!selectedCrewId.value) return;
|
||
saving.value = true;
|
||
try {
|
||
const canvasData = canvasHook.serializeCanvas();
|
||
const members = canvasHook.extractMembers();
|
||
const hints = canvasToHints(canvasHook.nodes.value, canvasHook.edges.value);
|
||
await crewStore.saveCanvas(selectedCrewId.value, canvasData, members, hints);
|
||
ElMessage.success('保存成功');
|
||
} finally {
|
||
saving.value = false;
|
||
}
|
||
}
|
||
|
||
async function onPublish() {
|
||
if (!selectedCrewId.value) return;
|
||
await crewStore.publish(selectedCrewId.value);
|
||
ElMessage.success('发布成功');
|
||
}
|
||
|
||
async function onUnpublish() {
|
||
if (!selectedCrewId.value) return;
|
||
await crewStore.unpublish(selectedCrewId.value);
|
||
ElMessage.success('已取消发布');
|
||
}
|
||
|
||
async function onNewCrew() {
|
||
// 弹出创建对话框（简化版直接创建）
|
||
const crew = await crewStore.createCrew({
|
||
name: `crew-${Date.now()}`,
|
||
label: '新建集群',
|
||
status: 0,
|
||
triggerConfig: { manual: true, cron: { enabled: false, expression: '', timezone: '' } },
|
||
});
|
||
selectedCrewId.value = crew.id;
|
||
}
|
||
|
||
function onTestRun() {
|
||
router.push(`/agent/crew-monitor?crewId=${selectedCrewId.value}&autoRun=1`);
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-editor {
|
||
display: flex;
|
||
flex-direction: column;
|
||
height: 100%;
|
||
}
|
||
.toolbar {
|
||
display: flex;
|
||
align-items: center;
|
||
gap: 8px;
|
||
padding: 8px 16px;
|
||
border-bottom: 1px solid #eee;
|
||
}
|
||
.main-area {
|
||
flex: 1;
|
||
display: flex;
|
||
overflow: hidden;
|
||
}
|
||
.canvas-container {
|
||
flex: 1;
|
||
position: relative;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Step 4.11：实现右键菜单组件
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-context-menu.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div
|
||
v-if="visible"
|
||
class="crew-context-menu"
|
||
:style="{ left: position.x + 'px', top: position.y + 'px' }"
|
||
>
|
||
<template v-if="targetType === 'node'">
|
||
<div class="menu-item" @click="$emit('set-master')">设为主 Agent</div>
|
||
<div class="menu-item" @click="$emit('edit-agent')">编辑 Agent</div>
|
||
<div class="menu-item danger" @click="$emit('remove-node')">移出集群</div>
|
||
</template>
|
||
<template v-else-if="targetType === 'edge'">
|
||
<div class="menu-item danger" @click="$emit('remove-edge')">删除连线</div>
|
||
</template>
|
||
<template v-else>
|
||
<div class="menu-item" @click="$emit('auto-layout')">自动布局</div>
|
||
<div class="menu-item" v-if="hasSelection" @click="$emit('group-selection')">设为分组</div>
|
||
</template>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
defineProps<{
|
||
visible: boolean;
|
||
position: { x: number; y: number };
|
||
targetType: 'node' | 'edge' | 'pane';
|
||
hasSelection?: boolean;
|
||
}>();
|
||
|
||
defineEmits<{
|
||
(e: 'set-master'): void;
|
||
(e: 'edit-agent'): void;
|
||
(e: 'remove-node'): void;
|
||
(e: 'remove-edge'): void;
|
||
(e: 'auto-layout'): void;
|
||
(e: 'group-selection'): void;
|
||
}>();
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-context-menu {
|
||
position: fixed;
|
||
background: white;
|
||
border: 1px solid #e0e0e0;
|
||
border-radius: 8px;
|
||
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
|
||
padding: 4px 0;
|
||
min-width: 140px;
|
||
z-index: 1000;
|
||
}
|
||
.menu-item {
|
||
padding: 8px 16px;
|
||
cursor: pointer;
|
||
font-size: 13px;
|
||
}
|
||
.menu-item:hover { background: #f5f7fa; }
|
||
.menu-item.danger { color: #f56c6c; }
|
||
</style>
|
||
```
|
||
|
||
在 `crew-editor.vue` 中集成右键菜单：在 `<VueFlow>` 上监听 `@node-context-menu`、`@edge-context-menu`、`@pane-context-menu` 事件，控制菜单显示/隐藏和位置。
|
||
|
||
### Step 4.12：实现自动布局（elkjs）
|
||
|
||
在 `hooks/crew-canvas.ts` 中新增 `autoLayout` 方法：
|
||
|
||
```typescript
|
||
import ELK from 'elkjs/lib/elk.bundled.js';
|
||
|
||
const elk = new ELK();
|
||
|
||
/**
|
||
* 使用 elkjs 自动布局
|
||
*/
|
||
async function autoLayout() {
|
||
const graph = {
|
||
id: 'root',
|
||
layoutOptions: {
|
||
'elk.algorithm': 'layered',
|
||
'elk.direction': 'RIGHT',
|
||
'elk.spacing.nodeNode': '80',
|
||
'elk.layered.spacing.nodeNodeBetweenLayers': '120',
|
||
},
|
||
children: nodes.value.map(n => ({
|
||
id: n.id,
|
||
width: 160,
|
||
height: 80,
|
||
})),
|
||
edges: edges.value.map(e => ({
|
||
id: e.id,
|
||
sources: [e.source],
|
||
targets: [e.target],
|
||
})),
|
||
};
|
||
|
||
const layout = await elk.layout(graph);
|
||
|
||
// 应用布局结果到节点位置
|
||
layout.children?.forEach(child => {
|
||
const node = nodes.value.find(n => n.id === child.id);
|
||
if (node && child.x !== undefined && child.y !== undefined) {
|
||
node.position = { x: child.x, y: child.y };
|
||
}
|
||
});
|
||
|
||
setTimeout(() => fitView({ padding: 0.2 }), 100);
|
||
}
|
||
```
|
||
|
||
在 `useCrewCanvas` 的返回值中导出 `autoLayout`，右键菜单的"自动布局"调用此方法。
|
||
|
||
### Step 4.13：实现框选分组
|
||
|
||
在 `crew-editor.vue` 中利用 Vue Flow 的 `selectionMode` 和 `@selection-end` 事件实现框选：
|
||
|
||
```typescript
|
||
// 在 crew-editor.vue 的 <VueFlow> 上添加：
|
||
// selection-mode="box"
|
||
// @selection-end="onSelectionEnd"
|
||
|
||
function onSelectionEnd({ nodes: selectedNodes }: any) {
|
||
if (selectedNodes.length < 2) return;
|
||
// 弹出分组名输入框
|
||
ElMessageBox.prompt('请输入分组名', '设为分组', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
}).then(({ value }) => {
|
||
selectedNodes.forEach((n: any) => {
|
||
if (n.data) n.data.groupName = value;
|
||
});
|
||
}).catch(() => {});
|
||
}
|
||
```
|
||
|
||
### Step 4.14：验证编排页
|
||
|
||
**验证清单**：
|
||
- [ ] 路由 `/agent/crew-editor` 正常访问
|
||
- [ ] 左侧 Agent 列表正确加载
|
||
- [ ] 拖拽 Agent 到画布，节点正常渲染
|
||
- [ ] 节点间可拖拽连线
|
||
- [ ] 右键节点：设为主 Agent / 移出集群 / 编辑 Agent
|
||
- [ ] 右键连线：删除连线
|
||
- [ ] 右键空白：自动布局（elkjs）
|
||
- [ ] 框选多节点 → 右键"设为分组"
|
||
- [ ] 主 Agent 显示金色边框 + 星标
|
||
- [ ] 点击节点/连线/空白，底部属性面板正确切换
|
||
- [ ] 属性面板：角色描述、分组名、重试次数均可编辑
|
||
- [ ] 连线类型（串行/并行）可切换
|
||
- [ ] 保存功能正常（canvasData + members + delegateHints 持久化）
|
||
- [ ] 加载已保存的集群，画布正确恢复
|
||
- [ ] 发布/取消发布功能正常
|
||
- [ ] MiniMap / Controls / Background 正常显示
|
||
|
||
### Step 4.15：提交代码
|
||
|
||
```bash
|
||
git add packages/frontend/src/modules/agent/config.ts
|
||
git add packages/frontend/src/modules/agent/store/crew.ts
|
||
git add packages/frontend/src/modules/agent/hooks/crew-canvas.ts
|
||
git add packages/frontend/src/modules/agent/hooks/crew-orchestration.ts
|
||
git add packages/frontend/src/modules/agent/views/crew-editor.vue
|
||
git add packages/frontend/src/modules/agent/components/crew/
|
||
git commit -m "feat(crew): 实现编排页 - Vue Flow 画布 + Agent 侧栏 + 属性面板"
|
||
```
|
||
|
||
### Phase 4 验收
|
||
|
||
- [ ] 前端路由注册完成
|
||
- [ ] Pinia Store 完成
|
||
- [ ] 画布操作 Hook 完成（含 elkjs 自动布局）
|
||
- [ ] delegateHints 转换 Hook 完成
|
||
- [ ] 自定义节点/连线组件完成
|
||
- [ ] 右键菜单组件完成（节点/连线/画布三种模式）
|
||
- [ ] 侧栏/属性面板（含重试次数）/触发配置组件完成
|
||
- [ ] 框选分组功能完成
|
||
- [ ] 编排页主视图完成
|
||
- [ ] 拖拽添加 Agent → 连线 → 配置角色 → 保存 全流程验证通过
|
||
- [ ] 代码已提交
|
||
|
||
---
|
||
|
||
## Phase 5：前端监控页
|
||
|
||
> 目标：实现运行列表 + 运行详情（实时画布 + 任务时间线 + 日志面板）
|
||
> 预估：2.5 天
|
||
> 依赖：Phase 4 完成（画布组件可复用）
|
||
|
||
### Step 5.1：实现 WebSocket 监控 Hook
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/hooks/crew-monitor.ts`
|
||
|
||
```typescript
|
||
import { ref, onUnmounted } from 'vue';
|
||
import { io, Socket } from 'socket.io-client';
|
||
import { useStore } from '../../../store';
|
||
import config from '/@/config';
|
||
|
||
/**
|
||
* Crew 监控 WebSocket Hook
|
||
* 连接 /crew 命名空间，订阅实时事件
|
||
*/
|
||
export function useCrewMonitor() {
|
||
const socket = ref<Socket | null>(null);
|
||
const { user } = useStore();
|
||
|
||
// 实时状态
|
||
const runStatusMap = ref<Map<number, any>>(new Map());
|
||
const taskStatusMap = ref<Map<number, any>>(new Map());
|
||
const logs = ref<any[]>([]);
|
||
const escalations = ref<any[]>([]);
|
||
|
||
/** 连接 WebSocket */
|
||
function connect() {
|
||
const wsUrl = (config as any).host || 'http://127.0.0.1:8001';
|
||
socket.value = io(`${wsUrl}/crew`, {
|
||
auth: { token: user.token, isAdmin: true },
|
||
transports: ['websocket'],
|
||
});
|
||
|
||
socket.value.on('crew:run:status', (data: any) => {
|
||
runStatusMap.value.set(data.runId, data);
|
||
});
|
||
|
||
socket.value.on('crew:task:status', (data: any) => {
|
||
taskStatusMap.value.set(data.taskId, data);
|
||
});
|
||
|
||
socket.value.on('crew:log', (data: any) => {
|
||
logs.value.push(data);
|
||
// 限制日志条数，防止内存溢出
|
||
if (logs.value.length > 5000) logs.value.splice(0, 1000);
|
||
});
|
||
|
||
socket.value.on('crew:escalation', (data: any) => {
|
||
escalations.value.push(data);
|
||
});
|
||
}
|
||
|
||
/** 触发运行 */
|
||
function triggerRun(crewId: number, triggerInput?: string) {
|
||
socket.value?.emit('crew:trigger', { crewId, triggerInput });
|
||
}
|
||
|
||
/** 控制运行 */
|
||
function controlRun(runId: number, action: string, userMessage?: string) {
|
||
socket.value?.emit('crew:control', { runId, action, userMessage });
|
||
}
|
||
|
||
/** 获取某次运行的日志 */
|
||
function getRunLogs(runId: number, agentName?: string) {
|
||
return logs.value.filter(l => {
|
||
if (agentName) return l.agentName === agentName;
|
||
return true; // 返回所有日志
|
||
});
|
||
}
|
||
|
||
/** 获取某次运行的任务状态列表 */
|
||
function getRunTasks(runId: number) {
|
||
return [...taskStatusMap.value.values()].filter(t => t.runId === runId);
|
||
}
|
||
|
||
/** 清理日志 */
|
||
function clearLogs() {
|
||
logs.value = [];
|
||
}
|
||
|
||
/** 断开连接 */
|
||
function disconnect() {
|
||
socket.value?.disconnect();
|
||
socket.value = null;
|
||
}
|
||
|
||
onUnmounted(() => disconnect());
|
||
|
||
return {
|
||
socket, runStatusMap, taskStatusMap, logs, escalations,
|
||
connect, disconnect, triggerRun, controlRun,
|
||
getRunLogs, getRunTasks, clearLogs,
|
||
};
|
||
}
|
||
```
|
||
|
||
### Step 5.2：实现运行记录表格
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-run-table.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-run-table">
|
||
<!-- 筛选栏 -->
|
||
<div class="filter-bar">
|
||
<el-select v-model="filters.crewId" placeholder="集群" clearable>
|
||
<el-option v-for="c in crewList" :key="c.id" :label="c.label" :value="c.id" />
|
||
</el-select>
|
||
<el-select v-model="filters.status" placeholder="状态" clearable>
|
||
<el-option v-for="s in statusOptions" :key="s.value" :label="s.label" :value="s.value" />
|
||
</el-select>
|
||
<el-date-picker
|
||
v-model="filters.timeRange"
|
||
type="daterange"
|
||
range-separator="至"
|
||
start-placeholder="开始日期"
|
||
end-placeholder="结束日期"
|
||
value-format="YYYY-MM-DD"
|
||
/>
|
||
<el-button @click="loadData">刷新</el-button>
|
||
</div>
|
||
|
||
<!-- 表格 -->
|
||
<el-table :data="tableData" @row-click="onRowClick" highlight-current-row>
|
||
<el-table-column prop="crewId" label="集群" width="120">
|
||
<template #default="{ row }">
|
||
{{ getCrewLabel(row.crewId) }}
|
||
</template>
|
||
</el-table-column>
|
||
<el-table-column prop="triggerType" label="触发方式" width="100" />
|
||
<el-table-column prop="status" label="状态" width="100">
|
||
<template #default="{ row }">
|
||
<span class="status-dot" :class="'status-' + row.status" />
|
||
{{ statusLabel(row.status) }}
|
||
</template>
|
||
</el-table-column>
|
||
<el-table-column prop="startTime" label="开始时间" width="180" />
|
||
<el-table-column label="耗时" width="100">
|
||
<template #default="{ row }">
|
||
{{ calcDuration(row.startTime, row.endTime) }}
|
||
</template>
|
||
</el-table-column>
|
||
<el-table-column label="进度" width="80">
|
||
<template #default="{ row }">
|
||
{{ row.progress || '-' }}
|
||
</template>
|
||
</el-table-column>
|
||
<el-table-column label="Token" width="120">
|
||
<template #default="{ row }">
|
||
{{ row.tokenUsage ? `${row.tokenUsage.inputTokens + row.tokenUsage.outputTokens}` : '-' }}
|
||
</template>
|
||
</el-table-column>
|
||
<el-table-column label="操作" width="200">
|
||
<template #default="{ row }">
|
||
<el-button
|
||
v-if="row.status === 'running'"
|
||
size="small" type="warning" text
|
||
@click.stop="$emit('control', row.id, 'stop')"
|
||
>终止</el-button>
|
||
<el-button
|
||
v-if="row.status === 'paused'"
|
||
size="small" type="success" text
|
||
@click.stop="$emit('resume', row.id)"
|
||
>恢复</el-button>
|
||
<el-button
|
||
size="small" text
|
||
@click.stop="$emit('detail', row.id)"
|
||
>详情</el-button>
|
||
</template>
|
||
</el-table-column>
|
||
</el-table>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref, reactive, onMounted } from 'vue';
|
||
import { useCool } from '/@/cool';
|
||
|
||
const props = defineProps<{ crewList: any[] }>();
|
||
const emit = defineEmits<{
|
||
(e: 'detail', runId: number): void;
|
||
(e: 'control', runId: number, action: string): void;
|
||
(e: 'resume', runId: number): void;
|
||
(e: 'row-click', row: any): void;
|
||
}>();
|
||
|
||
const { service } = useCool();
|
||
const tableData = ref<any[]>([]);
|
||
const filters = reactive({ crewId: null as number | null, status: '', timeRange: null as string[] | null });
|
||
|
||
const statusOptions = [
|
||
{ value: 'pending', label: '等待中' },
|
||
{ value: 'running', label: '运行中' },
|
||
{ value: 'paused', label: '已暂停' },
|
||
{ value: 'completed', label: '已完成' },
|
||
{ value: 'failed', label: '已失败' },
|
||
];
|
||
|
||
function statusLabel(s: string) {
|
||
return statusOptions.find(o => o.value === s)?.label || s;
|
||
}
|
||
|
||
function getCrewLabel(crewId: number) {
|
||
return props.crewList.find(c => c.id === crewId)?.label || crewId;
|
||
}
|
||
|
||
function calcDuration(start: string, end: string) {
|
||
if (!start) return '-';
|
||
const s = new Date(start).getTime();
|
||
const e = end ? new Date(end).getTime() : Date.now();
|
||
const sec = Math.round((e - s) / 1000);
|
||
return sec < 60 ? `${sec}s` : `${Math.floor(sec / 60)}m${sec % 60}s`;
|
||
}
|
||
|
||
async function loadData() {
|
||
const params: any = {};
|
||
if (filters.crewId) params.crewId = filters.crewId;
|
||
if (filters.status) params.status = filters.status;
|
||
const res = await service.netaclaw.crewRun.page({ ...params, size: 50, page: 1 });
|
||
tableData.value = res?.list || [];
|
||
}
|
||
|
||
function onRowClick(row: any) {
|
||
emit('row-click', row);
|
||
}
|
||
|
||
/** 外部调用：实时更新某行状态 */
|
||
function updateRowStatus(runId: number, data: any) {
|
||
const row = tableData.value.find(r => r.id === runId);
|
||
if (row) Object.assign(row, data);
|
||
}
|
||
|
||
onMounted(() => loadData());
|
||
|
||
defineExpose({ loadData, updateRowStatus });
|
||
</script>
|
||
|
||
<style scoped>
|
||
.filter-bar { display: flex; gap: 8px; margin-bottom: 12px; }
|
||
.status-dot {
|
||
display: inline-block;
|
||
width: 8px; height: 8px;
|
||
border-radius: 50%;
|
||
margin-right: 4px;
|
||
}
|
||
.status-running { background: #67c23a; }
|
||
.status-completed { background: #409eff; }
|
||
.status-paused { background: #e6a23c; }
|
||
.status-failed { background: #f56c6c; }
|
||
.status-pending { background: #c0c4cc; }
|
||
</style>
|
||
```
|
||
|
||
### Step 5.3：实现任务时间线
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-timeline.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-timeline">
|
||
<h4>任务时间线</h4>
|
||
<el-timeline>
|
||
<el-timeline-item
|
||
v-for="task in sortedTasks"
|
||
:key="task.taskId"
|
||
:type="timelineType(task.status)"
|
||
:timestamp="task.startTime || task.timestamp"
|
||
placement="top"
|
||
>
|
||
<div class="task-item" @click="$emit('select-task', task)">
|
||
<span class="task-agent">{{ task.agentName }}</span>
|
||
<span class="task-status" :class="'status-' + task.status">
|
||
{{ statusIcon(task.status) }} {{ task.status }}
|
||
</span>
|
||
<p class="task-desc">{{ task.taskDescription || task.result?.agent }}</p>
|
||
<span v-if="task.duration" class="task-duration">{{ task.duration }}</span>
|
||
</div>
|
||
</el-timeline-item>
|
||
</el-timeline>
|
||
|
||
<div v-if="!sortedTasks.length" class="empty">暂无任务记录</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { computed } from 'vue';
|
||
|
||
const props = defineProps<{ tasks: any[] }>();
|
||
defineEmits<{ (e: 'select-task', task: any): void }>();
|
||
|
||
const sortedTasks = computed(() =>
|
||
[...props.tasks].sort((a, b) => {
|
||
const ta = a.startTime || a.timestamp || '';
|
||
const tb = b.startTime || b.timestamp || '';
|
||
return ta.localeCompare(tb);
|
||
})
|
||
);
|
||
|
||
function timelineType(status: string) {
|
||
const map: Record<string, string> = {
|
||
running: 'primary', completed: 'success',
|
||
failed: 'danger', pending: 'info', retrying: 'warning',
|
||
};
|
||
return map[status] || 'info';
|
||
}
|
||
|
||
function statusIcon(status: string) {
|
||
const map: Record<string, string> = {
|
||
running: '⏳', completed: '✅', failed: '❌', pending: '⏸', retrying: '🔄',
|
||
};
|
||
return map[status] || '•';
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-timeline { padding: 12px; overflow-y: auto; }
|
||
h4 { margin: 0 0 12px; font-size: 14px; }
|
||
.task-item { cursor: pointer; }
|
||
.task-agent { font-weight: 600; margin-right: 8px; }
|
||
.task-status { font-size: 12px; }
|
||
.task-desc { font-size: 12px; color: #606266; margin: 4px 0 0; }
|
||
.task-duration { font-size: 11px; color: #909399; }
|
||
.empty { text-align: center; color: #c0c4cc; padding: 40px; }
|
||
</style>
|
||
```
|
||
|
||
### Step 5.4：实现日志面板
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-log-panel.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-log-panel">
|
||
<!-- Tab 切换：主 Agent / 各子 Agent -->
|
||
<el-tabs v-model="activeTab">
|
||
<el-tab-pane label="全部日志" name="all" />
|
||
<el-tab-pane
|
||
v-for="agent in agentNames"
|
||
:key="agent" :label="agent" :name="agent"
|
||
/>
|
||
</el-tabs>
|
||
|
||
<!-- 搜索过滤 -->
|
||
<el-input
|
||
v-model="searchText" placeholder="搜索日志..."
|
||
clearable size="small" style="margin-bottom: 8px"
|
||
/>
|
||
|
||
<!-- 日志流 -->
|
||
<div ref="logContainer" class="log-container">
|
||
<div
|
||
v-for="(log, i) in filteredLogs"
|
||
:key="i"
|
||
class="log-line"
|
||
:class="'level-' + log.level"
|
||
>
|
||
<span class="log-time">{{ formatTime(log.timestamp) }}</span>
|
||
<span class="log-agent">[{{ log.agentName }}]</span>
|
||
<span class="log-message">{{ log.message }}</span>
|
||
</div>
|
||
<div v-if="!filteredLogs.length" class="empty">等待日志...</div>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref, computed, watch, nextTick } from 'vue';
|
||
|
||
const props = defineProps<{ logs: any[] }>();
|
||
|
||
const activeTab = ref('all');
|
||
const searchText = ref('');
|
||
const logContainer = ref<HTMLElement>();
|
||
|
||
// 提取所有出现过的 Agent 名称
|
||
const agentNames = computed(() => {
|
||
const names = new Set<string>();
|
||
props.logs.forEach(l => { if (l.agentName) names.add(l.agentName); });
|
||
return [...names];
|
||
});
|
||
|
||
const filteredLogs = computed(() => {
|
||
let result = props.logs;
|
||
if (activeTab.value !== 'all') {
|
||
result = result.filter(l => l.agentName === activeTab.value);
|
||
}
|
||
if (searchText.value) {
|
||
const q = searchText.value.toLowerCase();
|
||
result = result.filter(l => l.message?.toLowerCase().includes(q));
|
||
}
|
||
return result;
|
||
});
|
||
|
||
function formatTime(ts: string) {
|
||
if (!ts) return '';
|
||
return new Date(ts).toLocaleTimeString();
|
||
}
|
||
|
||
// 自动滚动到底部
|
||
watch(() => props.logs.length, async () => {
|
||
await nextTick();
|
||
if (logContainer.value) {
|
||
logContainer.value.scrollTop = logContainer.value.scrollHeight;
|
||
}
|
||
});
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-log-panel { display: flex; flex-direction: column; height: 100%; }
|
||
.log-container {
|
||
flex: 1; overflow-y: auto;
|
||
font-family: 'Consolas', 'Monaco', monospace;
|
||
font-size: 12px; line-height: 1.6;
|
||
background: #1e1e1e; color: #d4d4d4;
|
||
padding: 8px 12px; border-radius: 6px;
|
||
}
|
||
.log-line { white-space: pre-wrap; word-break: break-all; }
|
||
.log-time { color: #6a9955; margin-right: 8px; }
|
||
.log-agent { color: #569cd6; margin-right: 8px; }
|
||
.level-error .log-message { color: #f44747; }
|
||
.level-tool .log-message { color: #dcdcaa; }
|
||
.empty { text-align: center; color: #666; padding: 40px; }
|
||
</style>
|
||
```
|
||
|
||
### Step 5.5：实现运行详情容器
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/components/crew/crew-run-detail.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-run-detail">
|
||
<!-- 三栏布局 -->
|
||
<div class="detail-columns">
|
||
<!-- 左：实时画布 -->
|
||
<div class="col-canvas">
|
||
<VueFlow
|
||
:nodes="canvasNodes"
|
||
:edges="canvasEdges"
|
||
:nodes-draggable="false"
|
||
:nodes-connectable="false"
|
||
:edges-updatable="false"
|
||
fit-view-on-init
|
||
:class-func="edgeClassFunc"
|
||
>
|
||
<template #node-crew-agent="{ data }">
|
||
<crew-agent-node :data="data" :live-status="getNodeStatus(data.agentId)" />
|
||
</template>
|
||
<MiniMap />
|
||
</VueFlow>
|
||
</div>
|
||
|
||
<!-- 中：任务时间线 -->
|
||
<div class="col-timeline">
|
||
<crew-timeline
|
||
:tasks="tasks"
|
||
@select-task="onSelectTask"
|
||
/>
|
||
</div>
|
||
|
||
<!-- 右：日志面板 -->
|
||
<div class="col-logs">
|
||
<crew-log-panel :logs="logs" />
|
||
</div>
|
||
</div>
|
||
|
||
<!-- 升级处理对话框 -->
|
||
<el-dialog v-model="showEscalation" title="需要人工处理" width="500px">
|
||
<p>{{ currentEscalation?.reason }}</p>
|
||
<el-input
|
||
v-model="resumeMessage"
|
||
type="textarea" :rows="4"
|
||
placeholder="请输入处理意见..."
|
||
/>
|
||
<template #footer>
|
||
<el-button @click="showEscalation = false">取消</el-button>
|
||
<el-button type="primary" @click="onResume">恢复执行</el-button>
|
||
</template>
|
||
</el-dialog>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref, computed, watch } from 'vue';
|
||
import { VueFlow } from '@vue-flow/core';
|
||
import { MiniMap } from '@vue-flow/minimap';
|
||
import '@vue-flow/core/dist/style.css';
|
||
import '@vue-flow/core/dist/theme-default.css';
|
||
import '@vue-flow/minimap/dist/style.css';
|
||
import CrewAgentNode from './crew-agent-node.vue';
|
||
import CrewTimeline from './crew-timeline.vue';
|
||
import CrewLogPanel from './crew-log-panel.vue';
|
||
|
||
const props = defineProps<{
|
||
run: any;
|
||
canvasData: any;
|
||
tasks: any[];
|
||
logs: any[];
|
||
escalations: any[];
|
||
}>();
|
||
|
||
const emit = defineEmits<{
|
||
(e: 'resume', runId: number, message: string): void;
|
||
}>();
|
||
|
||
// 画布数据（只读模式）
|
||
const canvasNodes = computed(() => props.canvasData?.nodes || []);
|
||
const canvasEdges = computed(() => props.canvasData?.edges || []);
|
||
|
||
// 节点实时状态映射
|
||
function getNodeStatus(agentId: number): string {
|
||
const task = props.tasks.find(t => t.agentId === agentId);
|
||
return task?.status || 'idle';
|
||
}
|
||
|
||
// 活跃连线动画：当 source 节点正在运行时，连线显示流动虚线
|
||
function edgeClassFunc(edge: any) {
|
||
const sourceNode = canvasNodes.value.find((n: any) => n.id === edge.source);
|
||
if (sourceNode?.data?.agentId) {
|
||
const status = getNodeStatus(sourceNode.data.agentId);
|
||
if (status === 'running') return 'is-active';
|
||
}
|
||
return '';
|
||
}
|
||
|
||
// 升级处理
|
||
const showEscalation = ref(false);
|
||
const currentEscalation = ref<any>(null);
|
||
const resumeMessage = ref('');
|
||
|
||
watch(() => props.escalations.length, () => {
|
||
const latest = props.escalations[props.escalations.length - 1];
|
||
if (latest && latest.runId === props.run?.id) {
|
||
currentEscalation.value = latest;
|
||
showEscalation.value = true;
|
||
}
|
||
});
|
||
|
||
function onResume() {
|
||
if (!props.run?.id) return;
|
||
emit('resume', props.run.id, resumeMessage.value);
|
||
showEscalation.value = false;
|
||
resumeMessage.value = '';
|
||
}
|
||
|
||
function onSelectTask(task: any) {
|
||
// 可以滚动日志到对应位置
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-run-detail { height: 100%; }
|
||
.detail-columns {
|
||
display: flex; height: 100%; gap: 1px;
|
||
background: #eee;
|
||
}
|
||
.col-canvas { flex: 2; background: white; min-height: 300px; }
|
||
.col-timeline { flex: 1; background: white; overflow-y: auto; }
|
||
.col-logs { flex: 1.5; background: white; }
|
||
|
||
/* 活跃连线流动虚线动画 */
|
||
:deep(.vue-flow__edge.is-active path) {
|
||
stroke-dasharray: 8 4;
|
||
animation: flow-dash 0.6s linear infinite;
|
||
}
|
||
@keyframes flow-dash {
|
||
to { stroke-dashoffset: -12; }
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Step 5.6：实现监控页主视图
|
||
|
||
**文件**：`packages/frontend/src/modules/agent/views/crew-monitor.vue`
|
||
|
||
```vue
|
||
<template>
|
||
<div class="crew-monitor">
|
||
<!-- 上半部：运行列表 -->
|
||
<div class="run-list-section">
|
||
<crew-run-table
|
||
ref="runTableRef"
|
||
:crew-list="crewStore.crewList"
|
||
@row-click="onRowClick"
|
||
@control="onControl"
|
||
@resume="onResumeClick"
|
||
@detail="onDetailClick"
|
||
/>
|
||
</div>
|
||
|
||
<!-- 下半部：运行详情 -->
|
||
<div v-if="selectedRun" class="run-detail-section">
|
||
<crew-run-detail
|
||
:run="selectedRun"
|
||
:canvas-data="selectedCanvasData"
|
||
:tasks="monitorHook.getRunTasks(selectedRun.id)"
|
||
:logs="monitorHook.logs.value"
|
||
:escalations="monitorHook.escalations.value"
|
||
@resume="onResume"
|
||
/>
|
||
</div>
|
||
<div v-else class="empty-detail">
|
||
<p>点击运行记录查看详情</p>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref, onMounted } from 'vue';
|
||
import { useRoute } from 'vue-router';
|
||
import { useCrewStore } from '../store/crew';
|
||
import { useCrewMonitor } from '../hooks/crew-monitor';
|
||
import CrewRunTable from '../components/crew/crew-run-table.vue';
|
||
import CrewRunDetail from '../components/crew/crew-run-detail.vue';
|
||
|
||
const route = useRoute();
|
||
const crewStore = useCrewStore();
|
||
const monitorHook = useCrewMonitor();
|
||
|
||
const runTableRef = ref<InstanceType<typeof CrewRunTable>>();
|
||
const selectedRun = ref<any>(null);
|
||
const selectedCanvasData = ref<any>(null);
|
||
|
||
onMounted(async () => {
|
||
await crewStore.loadCrewList();
|
||
monitorHook.connect();
|
||
|
||
// 监听实时状态更新
|
||
monitorHook.runStatusMap.value.forEach((data, runId) => {
|
||
runTableRef.value?.updateRowStatus(runId, data);
|
||
});
|
||
|
||
// 如果从编排页跳转过来，自动触发运行
|
||
const autoRunCrewId = route.query.crewId;
|
||
if (route.query.autoRun === '1' && autoRunCrewId) {
|
||
monitorHook.triggerRun(Number(autoRunCrewId));
|
||
}
|
||
});
|
||
|
||
async function onRowClick(row: any) {
|
||
selectedRun.value = row;
|
||
// 加载该集群的画布数据
|
||
const detail = await crewStore.loadCrewDetail(row.crewId);
|
||
selectedCanvasData.value = detail?.canvasData;
|
||
monitorHook.clearLogs();
|
||
}
|
||
|
||
function onDetailClick(runId: number) {
|
||
// 同 onRowClick，通过 runId 查找行数据
|
||
}
|
||
|
||
function onControl(runId: number, action: string) {
|
||
monitorHook.controlRun(runId, action);
|
||
}
|
||
|
||
function onResumeClick(runId: number) {
|
||
// 打开恢复对话框（由 crew-run-detail 内部处理）
|
||
selectedRun.value = { ...selectedRun.value, id: runId };
|
||
}
|
||
|
||
function onResume(runId: number, message: string) {
|
||
monitorHook.controlRun(runId, 'resume', message);
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.crew-monitor {
|
||
display: flex; flex-direction: column; height: 100%;
|
||
}
|
||
.run-list-section {
|
||
padding: 16px;
|
||
border-bottom: 1px solid #eee;
|
||
max-height: 40%;
|
||
overflow-y: auto;
|
||
}
|
||
.run-detail-section { flex: 1; overflow: hidden; }
|
||
.empty-detail {
|
||
flex: 1; display: flex; align-items: center;
|
||
justify-content: center; color: #c0c4cc;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Step 5.7：验证监控页
|
||
|
||
**验证清单**：
|
||
- [ ] 路由 `/agent/crew-monitor` 正常访问
|
||
- [ ] 运行记录表格正确加载，筛选功能正常
|
||
- [ ] 状态颜色圆点正确显示
|
||
- [ ] WebSocket 连接 `/crew` 命名空间成功
|
||
- [ ] 触发运行后，表格实时更新状态
|
||
- [ ] 点击行展开详情，三栏布局正确渲染
|
||
- [ ] 实时画布：节点状态随任务进度变化（idle→running→completed/failed）
|
||
- [ ] 任务时间线：按时间排序，状态图标正确
|
||
- [ ] 日志面板：实时滚动，Tab 切换过滤，搜索功能正常
|
||
- [ ] 升级处理：escalate 触发后弹出对话框，输入意见后恢复执行
|
||
- [ ] 终止运行功能正常
|
||
|
||
### Step 5.8：提交代码
|
||
|
||
```bash
|
||
git add packages/frontend/src/modules/agent/hooks/crew-monitor.ts
|
||
git add packages/frontend/src/modules/agent/views/crew-monitor.vue
|
||
git add packages/frontend/src/modules/agent/components/crew/crew-run-table.vue
|
||
git add packages/frontend/src/modules/agent/components/crew/crew-run-detail.vue
|
||
git add packages/frontend/src/modules/agent/components/crew/crew-timeline.vue
|
||
git add packages/frontend/src/modules/agent/components/crew/crew-log-panel.vue
|
||
git commit -m "feat(crew): 实现监控页 - 运行列表 + 实时画布 + 时间线 + 日志面板"
|
||
```
|
||
|
||
### Phase 5 验收
|
||
|
||
- [ ] WebSocket 监控 Hook 完成
|
||
- [ ] 运行记录表格完成（含实时更新）
|
||
- [ ] 任务时间线完成
|
||
- [ ] 日志面板完成（Tab 切换 + 搜索 + 自动滚动）
|
||
- [ ] 运行详情三栏布局完成（画布 + 时间线 + 日志）
|
||
- [ ] 升级处理对话框完成
|
||
- [ ] 监控页主视图完成
|
||
- [ ] 端到端实时监控验证通过
|
||
- [ ] 代码已提交
|
||
|
||
---
|
||
|
||
## Phase 6：权限集成 + 端到端测试
|
||
|
||
> 目标：配置菜单权限、数据权限，并完成端到端全流程测试
|
||
> 预估：1 天
|
||
> 依赖：Phase 5 完成
|
||
|
||
### Step 6.1：配置菜单权限
|
||
|
||
通过数据库或 Cool Admin 管理后台插入菜单和权限记录：
|
||
|
||
```sql
|
||
-- 1. 查询 Agent 管理父菜单 ID
|
||
SELECT id FROM base_sys_menu WHERE router = '/agent' OR name = 'Agent 管理';
|
||
|
||
-- 2. 插入 Agent 编排页菜单
|
||
INSERT INTO base_sys_menu (name, router, parentId, orderNum, type, icon, perms, isShow)
|
||
VALUES ('Agent 编排', '/agent/crew-editor', @parentId, 5, 1, 'icon-crew', NULL, 1);
|
||
|
||
-- 3. 插入运行监控页菜单
|
||
INSERT INTO base_sys_menu (name, router, parentId, orderNum, type, icon, perms, isShow)
|
||
VALUES ('运行监控', '/agent/crew-monitor', @parentId, 6, 1, 'icon-monitor', NULL, 1);
|
||
|
||
-- 4. 插入操作权限按钮（挂在编排页菜单下）
|
||
SET @crewMenuId = LAST_INSERT_ID(); -- 需要调整
|
||
INSERT INTO base_sys_menu (name, parentId, type, perms) VALUES
|
||
('创建集群', @crewMenuId, 2, 'agent:crew:create'),
|
||
('编辑集群', @crewMenuId, 2, 'agent:crew:edit'),
|
||
('发布集群', @crewMenuId, 2, 'agent:crew:publish'),
|
||
('触发运行', @crewMenuId, 2, 'agent:crew:trigger'),
|
||
('控制运行', @crewMenuId, 2, 'agent:crew:control'),
|
||
('查看监控', @crewMenuId, 2, 'agent:crew:view');
|
||
```
|
||
|
||
> 实际操作时建议通过 Cool Admin 的菜单管理页面 UI 操作，更安全。
|
||
|
||
### Step 6.2：数据权限（租户隔离）
|
||
|
||
`netaclaw_crew` 继承 `BaseEntity` 已自带 `tenantId` 字段。Cool Admin 的 `@CoolController` 自动在查询时注入租户过滤条件，无需额外代码。
|
||
|
||
**验证点**：
|
||
- [ ] 不同租户创建的集群互不可见
|
||
- [ ] 管理员可查看所有集群
|
||
|
||
### Step 6.3：Controller 权限装饰
|
||
|
||
如需更细粒度的权限控制，在 Controller 方法上添加装饰器：
|
||
|
||
```typescript
|
||
// 示例：crew_trigger.ts 中的 start 方法
|
||
@Post('/start')
|
||
// Cool Admin 权限检查由框架自动处理，基于菜单 perms 配置
|
||
async start(@Body() body: { crewId: number; triggerInput?: string }) {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
> Cool Admin 的权限机制是：前端请求携带 token → 后端中间件解析用户角色 → 校验用户是否有该路由对应的菜单权限。菜单权限在 Step 6.1 已配置。
|
||
|
||
### Step 6.4：端到端全流程测试
|
||
|
||
#### 测试场景 1：基本编排 + 运行
|
||
|
||
```
|
||
前置条件：已有 3 个已发布 Agent（如：登录Agent、数据获取Agent、上架Agent）
|
||
|
||
1. 进入编排页 → 新建集群"淘宝运营"
|
||
2. 从左侧拖入 3 个 Agent
|
||
3. 设置"登录Agent"为主 Agent
|
||
4. 连线：登录Agent → 数据获取Agent → 上架Agent（串行）
|
||
5. 给每个 Agent 配置角色描述
|
||
6. 保存 → 发布
|
||
7. 点击"试运行" → 跳转监控页
|
||
8. 观察：
|
||
- 运行列表新增一行（status=running）
|
||
- 实时画布节点状态变化
|
||
- 时间线记录各任务执行
|
||
- 日志面板实时输出
|
||
9. 运行完成 → status=completed
|
||
10. 检查数据库：crew_run / crew_task 记录正确
|
||
```
|
||
|
||
#### 测试场景 2：并行委派
|
||
|
||
```
|
||
1. 编排：A(主) → B(串行), A → C(并行), A → D(并行)
|
||
2. 触发运行
|
||
3. 验证：B 先执行完，然后 C 和 D 并行执行
|
||
4. 检查 crew_task 表：C 和 D 的 startTime 接近
|
||
```
|
||
|
||
#### 测试场景 3：错误处理 + 升级
|
||
|
||
```
|
||
1. 编排包含一个"必然失败"的 Agent（如 API Key 无效）
|
||
2. 触发运行
|
||
3. 验证：主 Agent 收到错误，尝试处理
|
||
4. 如果主 Agent 判断无法处理 → 调用 escalate
|
||
5. 监控页弹出升级对话框
|
||
6. 输入处理意见 → 点击恢复
|
||
7. 验证主 Agent 继续执行
|
||
```
|
||
|
||
#### 测试场景 4：定时调度
|
||
|
||
```
|
||
1. 编辑集群触发配置：启用 cron，表达式 = "*/2 * * * *"（每2分钟）
|
||
2. 发布集群
|
||
3. 等待 2 分钟，验证自动触发运行
|
||
4. 取消发布 → 验证定时任务停止
|
||
```
|
||
|
||
### Step 6.5：性能与稳定性检查
|
||
|
||
- [ ] **并发安全**：同时触发 3 个集群运行，无死锁或数据混乱
|
||
- [ ] **WebSocket 断线重连**：刷新页面后重新连接 `/crew`，状态恢复
|
||
- [ ] **超时控制**：子 Agent 执行超过 taskTimeout 后正确标记 failed
|
||
- [ ] **内存泄漏**：长时间运行后检查 Node.js 内存使用
|
||
- [ ] **日志量**：大量日志时前端不卡顿（已设置 5000 条上限）
|
||
|
||
### Step 6.6：提交代码
|
||
|
||
```bash
|
||
git add -A
|
||
git commit -m "feat(crew): 完成权限集成 + 端到端测试验证"
|
||
```
|
||
|
||
### Phase 6 验收
|
||
|
||
- [ ] 菜单权限配置完成
|
||
- [ ] 租户数据隔离验证通过
|
||
- [ ] 端到端测试场景 1-4 全部通过
|
||
- [ ] 性能与稳定性检查通过
|
||
- [ ] 代码已提交
|
||
|
||
---
|
||
|
||
## 风险应对与降级方案
|
||
|
||
### 风险 1：Vue Flow 兼容问题
|
||
|
||
| 级别 | 场景 | 应对 |
|
||
|------|------|------|
|
||
| 🟢 低 | 样式冲突 | 调整 CSS 隔离，使用 `scoped` + `deep` 选择器 |
|
||
| 🟡 中 | 自定义节点渲染异常 | 检查 Vue Flow 版本 API 变更，参考官方 examples |
|
||
| 🔴 高 | Vue Flow 与项目 Vue 版本不兼容 | **降级方案**：使用纯 SVG + CSS 实现简化版画布（节点拖拽用 `interact.js`，连线用 SVG `<path>`） |
|
||
|
||
**预防措施**：Phase 0 的技术验证（Step 0.4）可在正式开发前发现此类问题。
|
||
|
||
### 风险 2：主 Agent 编排质量差
|
||
|
||
| 场景 | 应对 |
|
||
|------|------|
|
||
| 主 Agent 不遵循 delegateHints | 强化 system prompt 中的指令措辞，增加 few-shot 示例 |
|
||
| 主 Agent 无限循环委派 | `maxToolRounds = 50` 硬性限制 + 检测连续失败次数 |
|
||
| 主 Agent 忽略错误 | 在 tool_result 中显式标记 `status: "failed"`，提示需要处理 |
|
||
|
||
### 风险 3：长时间运行稳定性
|
||
|
||
| 场景 | 应对 |
|
||
|------|------|
|
||
| 服务重启丢失运行状态 | `pausedState` 持久化对话上下文，启动时恢复 |
|
||
| 子 Agent 执行卡死 | `Promise.race` 超时控制，默认 300s |
|
||
| WebSocket 断线 | 前端 Socket.IO 自动重连 + 重新拉取当前状态 |
|
||
|
||
### 风险 4：并发 Token 消耗过高
|
||
|
||
| 场景 | 应对 |
|
||
|------|------|
|
||
| 并行执行大量子 Agent | `maxConcurrent` 限制（默认 3），分批执行 |
|
||
| Token 成本超预期 | 前端展示累计 token 消耗，集群配置 token 预算告警（后续迭代） |
|
||
|
||
---
|
||
|
||
## 验收标准
|
||
|
||
### 功能验收
|
||
|
||
| # | 功能点 | 验收标准 |
|
||
|---|--------|---------|
|
||
| 1 | 集群 CRUD | 创建/编辑/删除集群，数据持久化正确 |
|
||
| 2 | 画布编排 | 拖拽添加 Agent、自由连线、设置主 Agent、保存/加载画布 |
|
||
| 3 | 角色配置 | 每个 Agent 可配置角色描述和分组 |
|
||
| 4 | 连线提示 | 连线自动生成 delegateHints，注入主 Agent system prompt |
|
||
| 5 | 发布控制 | 发布校验（需主 Agent + ≥2 成员），取消发布 |
|
||
| 6 | 手动触发 | 通过 REST API 和 WebSocket 触发运行 |
|
||
| 7 | 定时调度 | Cron 表达式配置，发布时注册，取消发布时销毁 |
|
||
| 8 | 串行委派 | 主 Agent 通过 delegate_task 串行执行子 Agent |
|
||
| 9 | 并行委派 | 主 Agent 通过 delegate_parallel 并行执行子 Agent |
|
||
| 10 | 错误处理 | 子 Agent 失败时，主 Agent 收到错误信息并自主决策 |
|
||
| 11 | 升级人工 | escalate 暂停运行 → 用户处理 → 恢复执行 |
|
||
| 12 | 运行列表 | 分页查询、状态筛选、实时更新 |
|
||
| 13 | 实时画布 | 节点状态随任务进度实时变化（呼吸动画/颜色） |
|
||
| 14 | 任务时间线 | 按时间排序，并行任务并排显示 |
|
||
| 15 | 日志面板 | 实时流式日志，Agent 维度 Tab 切换，搜索过滤 |
|
||
| 16 | Token 统计 | 每个任务和整次运行的 token 消耗正确记录 |
|
||
| 17 | 权限控制 | 菜单权限 + 租户数据隔离 |
|
||
|
||
### 非功能验收
|
||
|
||
| # | 指标 | 标准 |
|
||
|---|------|------|
|
||
| 1 | 零 runtime 改动 | `runtime/agent.ts` 和 `runtime/attempt.ts` 无修改 |
|
||
| 2 | 现有功能不受影响 | Agent 对话、Skill 管理等原有功能正常 |
|
||
| 3 | 代码规范 | Entity 继承 BaseEntity、Controller 使用 @CoolController、文件下划线命名 |
|
||
| 4 | 并发安全 | 3 个集群同时运行无异常 |
|
||
| 5 | 超时控制 | 子 Agent 超时后正确标记 failed |
|
||
|
||
### 交付物清单
|
||
|
||
| 类别 | 数量 | 文件 |
|
||
|------|------|------|
|
||
| 后端 Entity | 4 新增 + 1 修改 | `crew.ts`, `crew_agent.ts`, `crew_run.ts`, `crew_task.ts`, `agent.ts` |
|
||
| 后端 Service | 5 新增 | `crew_types.ts`, `crew.ts`, `crew_orchestrator.ts`, `crew_delegate.ts`, `crew_scheduler.ts` |
|
||
| 后端 Tool | 3 新增 | `delegate_task.ts`, `delegate_parallel.ts`, `escalate.ts` |
|
||
| 后端 Controller | 3 新增 | `crew.ts`, `crew_run.ts`, `crew_trigger.ts` |
|
||
| 后端 Gateway | 1 新增 | `crew_server.ts` |
|
||
| 前端 View | 2 新增 | `crew-editor.vue`, `crew-monitor.vue` |
|
||
| 前端 Component | 11 新增 | `crew-agent-node.vue`, `crew-edge-label.vue`, `crew-sidebar.vue`, `crew-property-panel.vue`, `crew-trigger-config.vue`, `crew-context-menu.vue`, `crew-run-table.vue`, `crew-run-detail.vue`, `crew-timeline.vue`, `crew-log-panel.vue`, `crew-canvas.vue`（可选抽取） |
|
||
| 前端 Hook | 3 新增 | `crew-canvas.ts`, `crew-orchestration.ts`, `crew-monitor.ts` |
|
||
| 前端 Store | 1 新增 | `crew.ts` |
|
||
| **合计** | **34 个文件** | 31 新增 + 3 修改 |
|
||
|
||
---
|
||
|
||
## 时间线总览
|
||
|
||
```
|
||
Phase 0 准备工作 ██ 0.5 天
|
||
Phase 1 后端数据层 ████ 1 天
|
||
Phase 2 后端核心引擎 ██████████ 2.5 天
|
||
Phase 3 后端通信层 ████████ 2 天
|
||
Phase 4 前端编排页 ████████████ 3 天
|
||
Phase 5 前端监控页 ██████████ 2.5 天
|
||
Phase 6 权限+测试 ████ 1 天
|
||
────────
|
||
总计 12.5 天
|
||
```
|
||
|
||
> **说明**：Phase 4 预留了额外缓冲（Vue Flow 首次使用风险）。如果 Phase 0 验证顺利，Phase 4 可缩短至 2 天。
|
||
|