John Qiu
de25f096e7
- Add install_name, install_type, dir_category fields to all 62 plugin.json files to resolve name-mapping and skill-vs-command routing issues - Add install-skills.sh: idempotent cross-machine skill sync script - Routes skill→~/.claude/skills/<name>/, command→~/.claude/commands/<name>.md - rsync full skills/ directory (preserves multi-file skills like dev-test, req-deploy) - State file ~/.claude/.installed-skills.json tracks installed versions - Conflict detection: warns before overwriting locally modified files - --dry-run, --category, --force, --cleanup, --list flags - Add 9 new plugins migrated from local ~/.claude (agent-swarm, ai-chat, defect-analysis, executing-plans, finishing-branch, frontend-design, req-audit, req-lookback, req-retro) - Add update-plugin-meta.py helper used to bulk-update plugin.json - Fix siyuan SKILL.md: remove hardcoded server credentials, use env vars Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
407 lines
8.9 KiB
Markdown
407 lines
8.9 KiB
Markdown
---
|
||
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)
|