---
name: agent-swarm
description: Multi-agent orchestration using OpenAI Swarm patterns. Coordinate specialized agents for complex development workflows with handoffs and context sharing.
---

# Agent Swarm - Multi-Agent Orchestration

基于 OpenAI Swarm 设计模式的多智能体协作系统，用于复杂开发任务的智能分解与协调。

## 核心概念

### 1. Agent（智能体）
每个 Agent 是具有特定职责的专家：
- **Instructions**: Agent 的角色定义和行为准则
- **Functions**: Agent 可以调用的工具函数
- **Handoffs**: 何时移交给其他 Agent

### 2. Handoff（任务移交）
Agent 之间的控制权转移机制：
- 当前 Agent 完成自己的职责
- 识别需要其他专长
- 移交给最合适的 Agent

### 3. Context Variables（上下文变量）
跨 Agent 共享的状态：
- 项目目录
- 技术栈信息
- 当前进度
- 发现的问题

---

## 预定义 Agent

### 1. Architect Agent（架构师）
**职责**: 理解需求、技术选型、设计系统架构

**何时使用**:
- 用户描述新功能或系统
- 需要技术方案设计
- 需要架构评审

**工具**:
- Read codebase
- Grep patterns
- 设计文档生成

**Handoff to**:
- Coder Agent（开始编码）
- Reviewer Agent（评审设计）

---

### 2. Coder Agent（编码者）
**职责**: 实现功能、编写代码、修复 bug

**何时使用**:
- 架构师完成设计
- 用户提出 bug 修复
- 需要代码重构

**工具**:
- Edit files
- Write files
- Git operations

**Handoff to**:
- Tester Agent（代码完成后）
- Architect Agent（遇到设计问题）

---

### 3. Tester Agent（测试员）
**职责**: 编写测试、运行测试、验证功能

**何时使用**:
- 代码编写完成
- 需要测试覆盖
- 验证 bug 修复

**工具**:
- Run tests
- Write test cases
- Coverage reports

**Handoff to**:
- Deployer Agent（测试通过）
- Coder Agent（发现问题）

---

### 4. Deployer Agent（部署员）
**职责**: 构建镜像、部署服务、监控上线

**何时使用**:
- 测试全部通过
- 需要发布到环境
- 需要回滚版本

**工具**:
- Docker build
- SSH deployment
- Health checks

**Handoff to**:
- Monitor Agent（部署完成）
- Coder Agent（部署失败）

---

### 5. Reviewer Agent（评审员）
**职责**: 代码审查、文档审查、安全检查

**何时使用**:
- PR 创建后
- 重要功能完成
- 需要质量把关

**工具**:
- Diff analysis
- Security scan
- Best practices check

**Handoff to**:
- Coder Agent（需要修改）
- Deployer Agent（审查通过）

---

## 使用方法

### 基本调用

```bash
/swarm start "在 new-ai-proj 中实现任务批量删除功能"
```

**执行流程**:
1. **Architect** 分析需求 → 设计 API 和前端交互
2. **Coder** 实现后端 API → 实现前端 UI
3. **Tester** 编写单元测试 → 运行测试
4. **Reviewer** 代码审查 → 安全检查
5. **Deployer** 部署到 staging → 验证功能

---

### 指定起始 Agent

```bash
/swarm coder "修复 backend/handlers/task_handler.go 的空指针 bug"
```

直接从 Coder Agent 开始，跳过架构设计阶段。

---

### 传递上下文

```bash
/swarm start "优化数据库查询性能" \
  --context project=/Users/coolbuy-dev/coding/new-ai-proj \
  --context stack=Go,PostgreSQL,Redis \
  --context module=backend/services
```

---

### 查看执行轨迹

```bash
/swarm trace
```

显示 Agent 调用链：
```
Architect → analyzed requirements (3 min)
  ↓ handoff: "Design complete, ready for implementation"
Coder → implemented 5 files (12 min)
  ↓ handoff: "Code complete, needs testing"
Tester → wrote 8 test cases, all passed (5 min)
  ↓ handoff: "Tests passed, ready for review"
Reviewer → approved with 2 suggestions (2 min)
  ↓ handoff: "Approved, ready for deployment"
Deployer → deployed to staging, health check OK (3 min)
```

---

## 配置文件

### swarm.yaml

在项目根目录创建 `swarm.yaml` 自定义 Agent 行为：

```yaml
agents:
  architect:
    instructions: |
      你是系统架构师，专注于 Go + Vue.js 技术栈。
      遵循 RESTful API 设计原则。
      考虑性能、安全性、可维护性。
    max_turns: 5

  coder:
    instructions: |
      你是 Go 后端工程师和 Vue.js 前端工程师。
      编写清晰、简洁、高性能的代码。
      遵循项目现有代码风格。
    tools:
      - Edit
      - Write
      - Bash
    max_turns: 10

  tester:
    instructions: |
      你是测试工程师，编写全面的测试用例。
      确保边界条件、错误处理、并发安全。
    tools:
      - Bash
      - Write
    test_command: "go test ./... -v"
    max_turns: 5

context_variables:
  project_root: /Users/coolbuy-dev/coding/new-ai-proj
  backend_lang: Go 1.21
  frontend_framework: Vue 3
  database: PostgreSQL 15
  deployment_target: staging.ai.pipexerp.com
```

---

## 高级功能

### 1. 自定义 Agent

```yaml
agents:
  database-optimizer:
    instructions: |
      你是数据库性能优化专家。
      分析慢查询、优化索引、设计缓存策略。
    functions:
      - explain_analyze
      - create_index
      - cache_design
    handoff_to:
      - coder  # 实现优化方案
```

---

### 2. 条件 Handoff

```yaml
handoff_rules:
  - from: tester
    to: coder
    condition: "test_pass_rate < 90%"
    message: "测试失败率超过 10%，需要修复"

  - from: tester
    to: deployer
    condition: "test_pass_rate == 100%"
    message: "所有测试通过，可以部署"
```

---

### 3. 并行 Agent

对于独立任务，多个 Agent 可以并行工作：

```bash
/swarm parallel \
  "coder: 实现后端 API" \
  "coder: 实现前端 UI" \
  "tester: 编写 API 测试"
```

---

## 与 Remote Coding 集成

在 OpenClaw 中调用本地 Claude Code 执行 Swarm 工作流：

```bash
# OpenClaw 调用 Melbourne Claude Code
ssh melbourne "cd /Users/coolbuy-dev/coding/new-ai-proj && \
  /opt/homebrew/bin/claude --dangerously-skip-permissions \
  -p '/swarm start 实现任务批量删除功能'"
```

---

## 实际案例

### 案例 1: 新功能开发

**任务**: "为 AI-Proj 实现需求批量导出功能"

**执行过程**:
1. **Architect**:
   - 分析需求：导出格式（Excel/PDF）、筛选条件、数据脱敏
   - 设计 API: `POST /api/v1/requirements/export`
   - 设计前端：导出按钮、进度条、下载链接

2. **Coder**:
   - 后端实现 export service
   - 前端实现导出 UI 组件
   - 集成 file download 功能

3. **Tester**:
   - 测试大量数据导出（1000+ 需求）
   - 测试并发导出
   - 测试下载失败重试

4. **Reviewer**:
   - 检查文件大小限制
   - 检查内存泄漏风险
   - 检查数据权限控制

5. **Deployer**:
   - 部署到 staging
   - 验证导出功能
   - 监控资源使用

---

### 案例 2: Bug 修复

**任务**: "修复任务详情页加载缓慢问题"

**执行过程**:
1. **Architect**:
   - 分析性能瓶颈：N+1 查询问题
   - 设计优化方案：使用 JOIN 和预加载

2. **Coder**:
   - 优化数据库查询
   - 添加 Redis 缓存
   - 更新前端数据获取逻辑

3. **Tester**:
   - 性能测试：加载时间从 3s → 300ms
   - 并发测试：100 用户同时访问
   - 缓存一致性测试

4. **Deployer**:
   - 灰度发布到 10% 用户
   - 监控性能指标
   - 全量发布

---

## 最佳实践

1. **明确任务范围**: 复杂任务交给 Swarm，简单任务直接执行
2. **合理设置 max_turns**: 避免 Agent 陷入死循环
3. **记录 Handoff 原因**: 便于追溯和调试
4. **定期审查轨迹**: 优化 Agent 协作流程
5. **利用 Context Variables**: 避免重复传递信息

---

## 故障排查

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| Agent 一直循环 | max_turns 设置过大 | 降低 max_turns，添加明确的 handoff 条件 |
| Handoff 失败 | 目标 Agent 未定义 | 检查 swarm.yaml 配置 |
| 上下文丢失 | Context Variables 未传递 | 在 handoff 时显式传递 context |
| 执行太慢 | 串行执行可并行任务 | 使用 `/swarm parallel` |

---

## 与其他 Skills 集成

- **dev-coding**: Coder Agent 使用 dev-coding 的编码规范
- **dev-test**: Tester Agent 使用 dev-test 的测试策略
- **ops-tools**: Deployer Agent 使用 ops-tools 进行部署
- **ai-proj**: 所有 Agent 使用 ai-proj MCP 进行任务同步

---

## 命令速查

| 命令 | 功能 |
|------|------|
| `/swarm start <task>` | 启动 Swarm 工作流（从 Architect 开始） |
| `/swarm <agent> <task>` | 从指定 Agent 开始 |
| `/swarm parallel <tasks>` | 并行执行多个任务 |
| `/swarm trace` | 查看执行轨迹 |
| `/swarm config` | 显示当前配置 |
| `/swarm agents` | 列出所有可用 Agent |
| `/swarm stop` | 终止当前 Swarm 执行 |

---

## 参考资料

- [OpenAI Swarm 文档](https://github.com/openai/swarm)
- [Multi-Agent Systems 设计模式](https://arxiv.org/abs/2308.00352)
- [Claude Code Skills 文档](https://docs.anthropic.com/claude-code/skills)