ai-proj-helper/skills-dev/agent-swarm-plugin/skills/SKILL.md

name, description

name	description
agent-swarm	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（审查通过）

---

使用方法

基本调用

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

执行流程:

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

---

指定起始 Agent

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

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

---

传递上下文

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

---

查看执行轨迹

/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 行为：

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

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

---

2. 条件 Handoff

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 可以并行工作：

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

---

与 Remote Coding 集成

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

# 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 文档
• Multi-Agent Systems 设计模式
• Claude Code Skills 文档