docs: add quickstart guide for swarm mode

2026-05-17 20:24:26 +08:00
parent 2657ef23db
commit d0011a8c79
1 changed files with 150 additions and 0 deletions
@@ -0,0 +1,150 @@
+# 蜂群模式快速开始
+
+## 一句话方案
+
+**将蜂群的去中心化任务分发、动态角色分配和自组织协作机制，通过在agent-manager中引入任务广播队列、agent能力注册表和竞价响应机制来实现，让agents像蜂群一样根据自身能力主动认领任务而非被动分配。**
+
+## 实现方式
+
+传统方式：Claude Code在本地启动子agent
+新方案：Claude Code调用agent-manager API，在K8s上动态创建多个specialized agents协作编码
+
+## 快速测试
+
+### 1. 启动服务
+
+```bash
+conda activate data && python app.py
+```
+
+### 2. 创建蜂群
+
+```bash
+curl -X POST http://localhost:8000/api/swarm/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "task_description": "实现简单的TODO API",
+    "agents": [
+      {"role": "architect", "template": "a2a_litellm_agent", "replicas": 1},
+      {"role": "coder", "template": "code_manager_agent", "replicas": 2},
+      {"role": "reviewer", "template": "a2a_litellm_agent", "replicas": 1}
+    ],
+    "orchestration": {"strategy": "sequential"}
+  }'
+```
+
+### 3. 查询状态
+
+```bash
+curl http://localhost:8000/api/swarm/{swarm_id}/status
+```
+
+### 4. 监听结果（SSE）
+
+```bash
+curl -N http://localhost:8000/api/swarm/{swarm_id}/results
+```
+
+### 5. 运行测试脚本
+
+```bash
+python test_swarm_api.py
+```
+
+## 核心组件
+
+### 数据库模型
+- `Swarm`: 蜂群主表
+- `SwarmAgent`: Agent实例
+- `SwarmMessage`: 通信消息
+
+### API端点
+- `POST /api/swarm/create` - 创建蜂群
+- `GET /api/swarm/{id}/status` - 查询状态
+- `GET /api/swarm/{id}/results` - SSE流式结果
+- `POST /api/swarm/{id}/stop` - 停止蜂群
+- `GET /api/swarm/{id}/logs` - 获取日志
+
+### 编排策略
+- **Sequential**: architect → coder → reviewer（顺序执行）
+- **Parallel**: 所有agents并行工作
+- **Hybrid**: 混合模式
+
+## 架构特点
+
+1. **K8s原生**: 每个agent独立namespace和pod
+2. **A2A通信**: 基于HTTP的agent间通信协议
+3. **实时追踪**: SSE流式推送进度和结果
+4. **灵活编排**: 支持多种协作策略
+5. **资源隔离**: 独立的K8s资源和配额管理
+
+## 下一步集成
+
+### Claude Code MCP工具
+
+```json
+{
+  "name": "create_code_swarm",
+  "description": "在K8s上创建Agent蜂群协作编码",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "task": {"type": "string"},
+      "agents": {"type": "array"}
+    }
+  }
+}
+```
+
+### 使用示例
+
+```python
+# Claude Code调用
+result = await mcp.call_tool("create_code_swarm", {
+    "task": "实现用户认证模块",
+    "agents": [
+        {"role": "architect", "model": "gpt-4"},
+        {"role": "coder", "model": "gpt-4", "replicas": 2}
+    ]
+})
+
+# 监听结果
+async for event in mcp.stream_results(result["swarm_id"]):
+    if event["type"] == "code_diff":
+        apply_diff(event["diff"])
+```
+
+## 技术债务和改进
+
+### 当前限制
+1. Agent Pods实际部署需要K8s集群（当前为模拟）
+2. 后台任务使用FastAPI BackgroundTasks（生产建议Celery）
+3. 无认证授权机制
+4. 无自动资源清理TTL
+
+### 建议改进
+1. 实现真实的K8s pod部署和监控
+2. 添加认证和授权机制
+3. 实现自动资源清理和TTL
+4. 添加更多编排策略（如基于依赖的DAG执行）
+5. 实现agent能力注册和任务竞价机制
+
+## 文档
+
+详细文档请参考：
+- [SWARM_README.md](SWARM_README.md) - 完整文档
+- [test_swarm_api.py](test_swarm_api.py) - API测试示例
+
+## Git提交
+
+```bash
+git log --oneline feature/swarm-mode
+# b4b20f0 feat: implement swarm mode for multi-agent collaboration
+# 2657ef2 docs: add swarm mode documentation and test script
+```
+
+---
+
+**实现完成！** 🎉
+
+核心功能已就绪，可以开始集成到Claude Code或进行进一步的测试和优化。