完整实现 Swarm 多智能体协作系统
- 新增 CLIPluginAdapter 统一接口 (backend/app/core/agent_adapter.py) - 新增 LLM 服务层，支持 Anthropic/OpenAI/DeepSeek/Ollama (backend/app/services/llm_service.py) - 新增 Agent 执行引擎，支持文件锁自动管理 (backend/app/services/agent_executor.py) - 新增 NativeLLMAgent 原生 LLM 适配器 (backend/app/adapters/native_llm_agent.py) - 新增进程管理器 (backend/app/services/process_manager.py) - 新增 Agent 控制 API (backend/app/routers/agents_control.py) - 新增 WebSocket 实时通信 (backend/app/routers/websocket.py) - 更新前端 AgentsPage，支持启动/停止 Agent - 测试通过：Agent 启动、批量操作、栅栏同步 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Code
686
docs/api-reference.md
Normal file
686
docs/api-reference.md
Normal file
@@ -0,0 +1,686 @@
|
||||
# Swarm Command Center - API 接口文档
|
||||
|
||||
后端服务已完整实现并通过测试。本文档描述前端与后端交互的 API 接口。
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **API 基础地址**: `http://localhost:8000/api`
|
||||
- **数据格式**: JSON
|
||||
- **字符编码**: UTF-8
|
||||
|
||||
## 服务状态
|
||||
|
||||
| 服务 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| StorageService | ✅ 已测试 | JSON 文件存储 |
|
||||
| FileLockService | ✅ 已测试 | 文件锁管理 |
|
||||
| HeartbeatService | ✅ 已测试 | Agent 心跳与超时检测 |
|
||||
| AgentRegistry | ✅ 已测试 | Agent 注册与状态管理 |
|
||||
| MeetingScheduler | ✅ 已测试 | 会议栅栏同步 |
|
||||
| MeetingRecorder | ✅ 已测试 | 会议记录与 Markdown |
|
||||
| ResourceManager | ✅ 已测试 | 资源整合管理 |
|
||||
| WorkflowEngine | ✅ 已测试 | YAML 工作流 |
|
||||
| RoleAllocator | ✅ 已测试 | AI 角色分配 |
|
||||
|
||||
---
|
||||
|
||||
## 1. Agent 管理接口
|
||||
|
||||
### 1.1 列出所有 Agent
|
||||
|
||||
```http
|
||||
GET /api/agents
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"agents": [
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"name": "Claude Code",
|
||||
"role": "architect",
|
||||
"model": "claude-opus-4.6",
|
||||
"status": "idle",
|
||||
"created_at": "2026-03-05T10:30:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 注册新 Agent
|
||||
|
||||
```http
|
||||
POST /api/agents/register
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"name": "Claude Code",
|
||||
"role": "architect",
|
||||
"model": "claude-opus-4.6",
|
||||
"description": "负责架构设计"
|
||||
}
|
||||
```
|
||||
|
||||
**角色可选值**: `architect`, `pm`, `developer`, `qa`, `reviewer`, `human`
|
||||
|
||||
### 1.3 获取 Agent 详情
|
||||
|
||||
```http
|
||||
GET /api/agents/:agent_id
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"name": "Claude Code",
|
||||
"role": "architect",
|
||||
"model": "claude-opus-4.6",
|
||||
"status": "working",
|
||||
"created_at": "2026-03-05T10:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.4 获取 Agent 状态
|
||||
|
||||
```http
|
||||
GET /api/agents/:agent_id/state
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"current_task": "修复登录bug",
|
||||
"progress": 75,
|
||||
"working_files": ["src/auth/login.py"],
|
||||
"last_update": "2026-03-05T10:35:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.5 更新 Agent 状态
|
||||
|
||||
```http
|
||||
POST /api/agents/:agent_id/state
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"task": "编写测试用例",
|
||||
"progress": 50,
|
||||
"working_files": ["tests/test_auth.py"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 文件锁接口
|
||||
|
||||
### 2.1 获取所有锁
|
||||
|
||||
```http
|
||||
GET /api/locks
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"locks": [
|
||||
{
|
||||
"file_path": "src/auth/login.py",
|
||||
"agent_id": "claude-001",
|
||||
"agent_name": "CLA",
|
||||
"acquired_at": "2026-03-05T10:30:00",
|
||||
"elapsed_display": "5m 30s"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 获取文件锁
|
||||
|
||||
```http
|
||||
POST /api/locks/acquire
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"file_path": "src/auth/login.py",
|
||||
"agent_id": "claude-001",
|
||||
"agent_name": "CLA"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"file_path": "src/auth/login.py",
|
||||
"agent_id": "claude-001"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 释放文件锁
|
||||
|
||||
```http
|
||||
POST /api/locks/release
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"file_path": "src/auth/login.py",
|
||||
"agent_id": "claude-001"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 检查文件锁定状态
|
||||
|
||||
```http
|
||||
GET /api/locks/check?file_path=src/auth/login.py
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"file_path": "src/auth/login.py",
|
||||
"locked": true,
|
||||
"locked_by": "claude-001"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 心跳接口
|
||||
|
||||
### 3.1 获取所有心跳
|
||||
|
||||
```http
|
||||
GET /api/heartbeats
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"heartbeats": {
|
||||
"claude-001": {
|
||||
"agent_id": "claude-001",
|
||||
"status": "working",
|
||||
"current_task": "修复bug",
|
||||
"progress": 50,
|
||||
"elapsed_display": "2m 15s",
|
||||
"is_timeout": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 更新心跳
|
||||
|
||||
```http
|
||||
POST /api/heartbeats/:agent_id
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "working",
|
||||
"current_task": "实现功能",
|
||||
"progress": 75
|
||||
}
|
||||
```
|
||||
|
||||
**状态可选值**: `working`, `waiting`, `idle`, `error`
|
||||
|
||||
### 3.3 检查超时 Agent
|
||||
|
||||
```http
|
||||
GET /api/heartbeats/timeouts?timeout_seconds=60
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"timeout_seconds": 60,
|
||||
"timeout_agents": ["agent-002", "agent-003"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 会议调度接口
|
||||
|
||||
### 4.1 创建会议
|
||||
|
||||
```http
|
||||
POST /api/meetings/create
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"meeting_id": "design-review-001",
|
||||
"title": "设计评审会议",
|
||||
"expected_attendees": ["claude-001", "kimi-002", "opencode-003"],
|
||||
"min_required": 2
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 获取会议队列
|
||||
|
||||
```http
|
||||
GET /api/meetings/:meeting_id/queue
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"meeting_id": "design-review-001",
|
||||
"title": "设计评审会议",
|
||||
"status": "waiting",
|
||||
"expected_attendees": ["claude-001", "kimi-002", "opencode-003"],
|
||||
"arrived_attendees": ["claude-001", "kimi-002"],
|
||||
"missing_attendees": ["opencode-003"],
|
||||
"progress": "2/3",
|
||||
"is_ready": false
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 等待会议开始（栅栏同步）
|
||||
|
||||
```http
|
||||
POST /api/meetings/:meeting_id/wait
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"timeout": 300
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"result": "started",
|
||||
"meeting_id": "design-review-001",
|
||||
"agent_id": "claude-001"
|
||||
}
|
||||
```
|
||||
|
||||
**result 说明**:
|
||||
- `started`: 会议已开始（最后一个到达者触发）
|
||||
- `timeout`: 等待超时
|
||||
- `error`: 发生错误
|
||||
|
||||
### 4.4 结束会议
|
||||
|
||||
```http
|
||||
POST /api/meetings/:meeting_id/end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 会议记录接口
|
||||
|
||||
### 5.1 创建会议记录
|
||||
|
||||
```http
|
||||
POST /api/meetings/record/create
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"meeting_id": "design-review-001",
|
||||
"title": "设计评审",
|
||||
"attendees": ["claude-001", "kimi-002"],
|
||||
"steps": ["收集想法", "讨论迭代", "生成共识"]
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 添加讨论记录
|
||||
|
||||
```http
|
||||
POST /api/meetings/:meeting_id/discuss
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"agent_name": "Claude",
|
||||
"content": "我建议使用 JWT 认证方案",
|
||||
"step": "讨论迭代"
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 更新会议进度
|
||||
|
||||
```http
|
||||
POST /api/meetings/:meeting_id/progress
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"step": "讨论迭代"
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 获取会议详情
|
||||
|
||||
```http
|
||||
GET /api/meetings/:meeting_id?date=2026-03-05
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"meeting_id": "design-review-001",
|
||||
"title": "设计评审",
|
||||
"date": "2026-03-05",
|
||||
"status": "in_progress",
|
||||
"attendees": ["claude-001", "kimi-002"],
|
||||
"steps": [
|
||||
{"step_id": "step_1", "label": "收集想法", "status": "completed"},
|
||||
{"step_id": "step_2", "label": "讨论迭代", "status": "active"},
|
||||
{"step_id": "step_3", "label": "生成共识", "status": "pending"}
|
||||
],
|
||||
"discussions": [
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"agent_name": "Claude",
|
||||
"content": "我建议使用 JWT",
|
||||
"timestamp": "2026-03-05T10:30:00",
|
||||
"step": "讨论迭代"
|
||||
}
|
||||
],
|
||||
"progress_summary": "1/3",
|
||||
"consensus": ""
|
||||
}
|
||||
```
|
||||
|
||||
### 5.5 完成会议
|
||||
|
||||
```http
|
||||
POST /api/meetings/:meeting_id/finish
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"consensus": "采用 JWT + Redis 方案"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 资源管理接口
|
||||
|
||||
### 6.1 执行任务
|
||||
|
||||
```http
|
||||
POST /api/execute
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"task": "修复 src/auth/login.py 中的 bug",
|
||||
"timeout": 300
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Task executed: 修复 src/auth/login.py 中的 bug",
|
||||
"files_locked": ["src/auth/login.py"],
|
||||
"duration_seconds": 1.25
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 获取所有 Agent 状态
|
||||
|
||||
```http
|
||||
GET /api/status
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"agents": [
|
||||
{
|
||||
"agent_id": "claude-001",
|
||||
"info": {
|
||||
"name": "Claude Code",
|
||||
"role": "architect",
|
||||
"model": "claude-opus-4.6"
|
||||
},
|
||||
"heartbeat": {
|
||||
"status": "working",
|
||||
"current_task": "修复bug",
|
||||
"progress": 50,
|
||||
"elapsed": "3m 20s"
|
||||
},
|
||||
"locks": [
|
||||
{"file": "src/auth/login.py", "elapsed": "2m 10s"}
|
||||
],
|
||||
"state": {
|
||||
"task": "修复bug",
|
||||
"progress": 50,
|
||||
"working_files": ["src/auth/login.py"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 解析任务文件
|
||||
|
||||
```http
|
||||
POST /api/parse-task
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"task": "修复 src/auth/login.py 和 src/utils/helper.js"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"task": "修复 src/auth/login.py 和 src/utils/helper.js",
|
||||
"files": ["src/auth/login.py", "src/utils/helper.js"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 工作流接口
|
||||
|
||||
### 7.1 加载工作流
|
||||
|
||||
```http
|
||||
POST /api/workflows/load
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"path": "example.yaml"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"workflow_id": "example_project",
|
||||
"name": "示例项目工作流",
|
||||
"description": "展示多智能体协作的典型工作流",
|
||||
"status": "pending",
|
||||
"progress": "0/4",
|
||||
"meetings": [
|
||||
{"meeting_id": "requirements-review", "title": "需求评审", "completed": false},
|
||||
{"meeting_id": "design-review", "title": "设计评审", "completed": false}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 获取工作流状态
|
||||
|
||||
```http
|
||||
GET /api/workflows/:workflow_id/status
|
||||
```
|
||||
|
||||
### 7.3 获取下一个会议
|
||||
|
||||
```http
|
||||
GET /api/workflows/:workflow_id/next
|
||||
```
|
||||
|
||||
### 7.4 标记会议完成
|
||||
|
||||
```http
|
||||
POST /api/workflows/:workflow_id/complete
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"meeting_id": "requirements-review"
|
||||
}
|
||||
```
|
||||
|
||||
### 7.5 列出可用工作流文件
|
||||
|
||||
```http
|
||||
GET /api/workflows/files
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"files": ["example.yaml", "project-a.yaml"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 角色分配接口
|
||||
|
||||
### 8.1 获取任务主要角色
|
||||
|
||||
```http
|
||||
POST /api/roles/primary
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"task": "实现登录功能并编写测试用例"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"task": "实现登录功能并编写测试用例",
|
||||
"primary_role": "pm",
|
||||
"role_scores": {
|
||||
"pm": 1.5,
|
||||
"qa": 1.2,
|
||||
"developer": 1.0,
|
||||
"architect": 0.15,
|
||||
"reviewer": 0.13
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 分配角色
|
||||
|
||||
```http
|
||||
POST /api/roles/allocate
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"task": "设计数据库架构并实现 API",
|
||||
"agents": ["claude-001", "kimi-002", "opencode-003"]
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"task": "设计数据库架构并实现 API",
|
||||
"primary_role": "architect",
|
||||
"allocation": {
|
||||
"claude-001": "architect",
|
||||
"kimi-002": "developer",
|
||||
"opencode-003": "pm"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 解释角色分配
|
||||
|
||||
```http
|
||||
POST /api/roles/explain
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"task": "修复bug",
|
||||
"agents": ["claude-001", "kimi-002"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 系统接口
|
||||
|
||||
### 9.1 健康检查
|
||||
|
||||
```http
|
||||
GET /health
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "0.1.0",
|
||||
"services": {
|
||||
"api": "ok",
|
||||
"storage": "ok"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
所有 API 错误返回统一格式:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": true,
|
||||
"code": "RESOURCE_NOT_FOUND",
|
||||
"message": "Agent not found: claude-001"
|
||||
}
|
||||
```
|
||||
|
||||
**常见错误码**:
|
||||
- `400` - Bad Request (请求参数错误)
|
||||
- `404` - Not Found (资源不存在)
|
||||
- `409` - Conflict (资源冲突，如文件已被锁定)
|
||||
- `500` - Internal Server Error (服务器内部错误)
|
||||
|
||||
---
|
||||
|
||||
## 前端集成建议
|
||||
|
||||
### 实时更新
|
||||
- 使用轮询（polling）获取 Agent 状态和会议进度
|
||||
- 建议轮询间隔: 5-10 秒
|
||||
|
||||
### 错误处理
|
||||
- 所有 API 调用应包含错误处理
|
||||
- 网络错误时显示友好提示
|
||||
|
||||
### 状态管理
|
||||
- 建议使用 React Query / SWR 管理服务器状态
|
||||
- 本地状态使用 Zustand / Redux Toolkit
|
||||
|
||||
---
|
||||
|
||||
## 测试验证
|
||||
|
||||
后端所有服务已通过自动化测试:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python test_all_services.py
|
||||
```
|
||||
|
||||
**测试结果**: 9/9 通过 ✅
|
||||
470
docs/backend-steps.md
Normal file
470
docs/backend-steps.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# 后端开发步骤
|
||||
|
||||
每一步完成后都有验证方法，前端逐步替换 mock 数据。
|
||||
|
||||
---
|
||||
|
||||
## 第一步：项目初始化
|
||||
|
||||
**操作**
|
||||
```bash
|
||||
cd backend
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
pip install fastapi uvicorn pydantic typer aiofiles
|
||||
mkdir -p .doc/agents .doc/cache .doc/meetings .doc/resources .doc/workflow
|
||||
```
|
||||
|
||||
**创建文件**
|
||||
- `backend/main.py` - FastAPI 入口
|
||||
- `backend/cli.py` - CLI 入口
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py hello # 输出: Hello Swarm
|
||||
python -m uvicorn main:app --reload
|
||||
curl http://localhost:8000/ # 输出: {"status":"ok"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第二步：基础存储服务
|
||||
|
||||
**操作** - 创建 `backend/services/storage.py`
|
||||
|
||||
```python
|
||||
class StorageService:
|
||||
async def read_json(self, path: str) -> dict
|
||||
async def write_json(self, path: str, data: dict)
|
||||
async def ensure_dir(self, path: str)
|
||||
```
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py storage write .doc/test.json '{"foo":"bar"}'
|
||||
python cli.py storage read .doc/test.json
|
||||
# 输出: {"foo":"bar"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第三步：文件锁服务
|
||||
|
||||
**操作** - 创建 `backend/services/file_lock.py`
|
||||
|
||||
```python
|
||||
class FileLockService:
|
||||
async def acquire_lock(self, file_path: str, agent_id: str) -> bool
|
||||
async def release_lock(self, file_path: str, agent_id: str) -> bool
|
||||
async def get_locks(self) -> List[LockInfo]
|
||||
async def check_locked(self, file_path: str) -> Optional[str]
|
||||
```
|
||||
|
||||
存储到 `.doc/cache/file_locks.json`
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
# CLI 测试
|
||||
python cli.py lock acquire src/auth/login.py claude-001
|
||||
# 输出: Lock acquired
|
||||
|
||||
python cli.py lock status
|
||||
# 输出: src/auth/login.py -> claude-001 (2s ago)
|
||||
|
||||
python cli.py lock release src/auth/login.py claude-001
|
||||
# 输出: Lock released
|
||||
```
|
||||
|
||||
**API 测试**
|
||||
```bash
|
||||
curl http://localhost:8000/api/locks
|
||||
# 输出: {"locks": []}
|
||||
|
||||
curl -X POST http://localhost:8000/api/locks/acquire \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"file_path":"src/auth/login.py","agent_id":"claude-001"}'
|
||||
# 输出: {"acquired":true}
|
||||
```
|
||||
|
||||
**前端对接** - 修改 `ResourceMonitorCard.tsx`
|
||||
```typescript
|
||||
// 替换 lockedFiles mock
|
||||
const response = await fetch('http://localhost:8000/api/locks');
|
||||
const data = await response.json();
|
||||
setLockedFiles(data.locks);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第四步：心跳服务
|
||||
|
||||
**操作** - 创建 `backend/services/heartbeat.py`
|
||||
|
||||
```python
|
||||
class HeartbeatService:
|
||||
async def update_heartbeat(self, agent_id: str, status: dict) -> None
|
||||
async def get_heartbeat(self, agent_id: str) -> Optional[dict]
|
||||
async def get_all_heartbeats(self) -> dict
|
||||
async def check_timeout(self, timeout_seconds: int) -> List[str]
|
||||
```
|
||||
|
||||
存储到 `.doc/cache/heartbeats.json`
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
# 模拟 Agent 发送心跳
|
||||
python cli.py heartbeat ping claude-001 '{"status":"working","task":"fixing bug"}'
|
||||
# 输出: Heartbeat updated
|
||||
|
||||
python cli.py heartbeat list
|
||||
# 输出: claude-001: working (5s ago)
|
||||
|
||||
python cli.py heartbeat check-timeout 30
|
||||
# 输出: No timed out agents
|
||||
```
|
||||
|
||||
**API 测试**
|
||||
```bash
|
||||
curl http://localhost:8000/api/heartbeats
|
||||
# 输出: {"heartbeats": {"claude-001": {...}}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第五步：Agent 注册服务
|
||||
|
||||
**操作** - 创建 `backend/services/agent_registry.py`
|
||||
|
||||
```python
|
||||
class AgentRegistry:
|
||||
async def register_agent(self, agent_info: AgentInfo) -> None
|
||||
async def get_agent(self, agent_id: str) -> Optional[AgentInfo]
|
||||
async def list_agents(self) -> List[AgentInfo]
|
||||
async def update_state(self, agent_id: str, state: dict) -> None
|
||||
async def get_state(self, agent_id: str) -> Optional[dict]
|
||||
```
|
||||
|
||||
存储到 `.doc/agents/{agent_id}/` 目录
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py agent register claude-001 \
|
||||
--name "Claude Code" \
|
||||
--role "architect" \
|
||||
--model "claude-opus-4.6"
|
||||
# 输出: Agent registered
|
||||
|
||||
python cli.py agent list
|
||||
# 输出: claude-001 | Claude Code | architect | claude-opus-4.6
|
||||
|
||||
python cli.py agent state claude-001 set '{"task":"fixing bug","progress":50}'
|
||||
python cli.py agent state claude-001 get
|
||||
# 输出: {"task":"fixing bug","progress":50}
|
||||
```
|
||||
|
||||
**API 测试**
|
||||
```bash
|
||||
curl http://localhost:8000/api/agents
|
||||
# 输出: {"agents": [...]}
|
||||
|
||||
curl http://localhost:8000/api/agents/claude-001/state
|
||||
# 输出: {"task":"fixing bug","progress":50}
|
||||
```
|
||||
|
||||
**前端对接** - 修改 `AgentStatusCard.tsx`
|
||||
```typescript
|
||||
// 替换 agents mock
|
||||
const response = await fetch('http://localhost:8000/api/agents');
|
||||
const data = await response.json();
|
||||
setAgents(data.agents);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第六步：会议调度器（栅栏同步）
|
||||
|
||||
**操作** - 创建 `backend/services/meeting_scheduler.py`
|
||||
|
||||
```python
|
||||
class MeetingScheduler:
|
||||
async def wait_for_meeting(self, agent_id: str, meeting_id: str) -> str
|
||||
async def get_queue(self, meeting_id: str) -> List[str]
|
||||
async def start_meeting(self, meeting_id: str) -> None
|
||||
async def end_meeting(self, meeting_id: str) -> None
|
||||
```
|
||||
|
||||
存储到 `.doc/cache/meeting_queue.json`
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
# 终端1 - Agent 1 等待
|
||||
python cli.py meeting wait design-review claude-001
|
||||
# 阻塞等待...
|
||||
|
||||
# 终端2 - Agent 2 等待
|
||||
python cli.py meeting wait design-review kimi-002
|
||||
# 触发会议，输出: Meeting started!
|
||||
|
||||
python cli.py meeting queue design-review
|
||||
# 输出: [claude-001, kimi-002]
|
||||
```
|
||||
|
||||
**API 测试**
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/meetings/design-review/wait \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"agent_id":"claude-001"}'
|
||||
# 输出: {"status":"waiting"}
|
||||
|
||||
curl http://localhost:8000/api/meetings/design-review/queue
|
||||
# 输出: {"waiting_agents":["claude-001"]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第七步：会议记录服务
|
||||
|
||||
**操作** - 创建 `backend/services/meeting_recorder.py`
|
||||
|
||||
```python
|
||||
class MeetingRecorder:
|
||||
async def create_meeting(self, meeting_info: MeetingInfo) -> str
|
||||
async def add_discussion(self, meeting_id: str, agent_id: str, content: str) -> None
|
||||
async def update_progress(self, meeting_id: str, step: str) -> None
|
||||
async def get_meeting(self, meeting_id: str) -> MeetingInfo
|
||||
async def list_meetings(self, date: str) -> List[MeetingInfo]
|
||||
```
|
||||
|
||||
存储到 `.doc/meetings/{YYYY-MM-DD}/{meeting_id}.md`
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py meeting create design-review \
|
||||
--title "认证方案设计评审" \
|
||||
--attendees claude-001,kimi-002,opencode-003
|
||||
# 输出: Meeting created: design_review_20260304_141000
|
||||
|
||||
python cli.py meeting discuss design_review_20260304_141000 \
|
||||
--agent claude-001 \
|
||||
--content "建议使用 JWT"
|
||||
# 输出: Discussion added
|
||||
|
||||
python cli.py meeting progress design_review_20260304_141000 "收集初步想法"
|
||||
# 输出: Progress updated
|
||||
```
|
||||
|
||||
**API 测试**
|
||||
```bash
|
||||
curl http://localhost:8000/api/meetings/2026-03-04
|
||||
# 输出: {"meetings": [...]}
|
||||
|
||||
curl http://localhost:8000/api/meetings/design_review_20260304_141000
|
||||
# 输出: {...}
|
||||
```
|
||||
|
||||
**前端对接** - 修改 `MeetingProgressCard.tsx` 和 `RecentMeetingsCard.tsx`
|
||||
```typescript
|
||||
// 替换 steps mock
|
||||
const response = await fetch('http://localhost:8000/api/meetings/active');
|
||||
const data = await response.json);
|
||||
setSteps(data.meeting.steps);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第八步：资源管理器（整合锁 + 心跳）
|
||||
|
||||
**操作** - 创建 `backend/services/resource_manager.py`
|
||||
|
||||
```python
|
||||
class ResourceManager:
|
||||
async def execute_task(self, agent_id: str, task_description: str) -> str
|
||||
# 内部逻辑：
|
||||
# 1. 解析任务需要的文件
|
||||
# 2. 获取所有文件锁
|
||||
# 3. 执行任务
|
||||
# 4. finally: 释放所有锁
|
||||
```
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py execute claude-001 "修改 src/auth/login.py 修复登录 bug"
|
||||
# 输出: Task executing...
|
||||
# 输出: Locks acquired: [src/auth/login.py, src/utils/crypto.py]
|
||||
# 输出: Task completed
|
||||
# 输出: Locks released
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第九步：工作流引擎
|
||||
|
||||
**操作** - 创建 `backend/services/workflow_engine.py`
|
||||
|
||||
```python
|
||||
class WorkflowEngine:
|
||||
async def load_workflow(self, workflow_path: str) -> Workflow
|
||||
async def get_next_meeting(self, workflow_id: str) -> Optional[MeetingInfo]
|
||||
async def complete_meeting(self, workflow_id: str, meeting_id: str) -> None
|
||||
```
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py workflow load .doc/workflow/project_workflow.yaml
|
||||
# 输出: Workflow loaded: my_project
|
||||
|
||||
python cli.py workflow next my_project
|
||||
# 输出: Next meeting: design_review (attendees: claude-001,kimi-002)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第十步：角色分配器（AI 路由）
|
||||
|
||||
**操作** - 创建 `backend/services/role_allocator.py`
|
||||
|
||||
```python
|
||||
class RoleAllocator:
|
||||
async def allocate_roles(self, task: str, agents: List[str]) -> Dict[str, str]
|
||||
# 内部调用 LLM 分析任务，返回角色分配
|
||||
```
|
||||
|
||||
**验证**
|
||||
```bash
|
||||
python cli.py role allocate "重构认证模块" claude-001,kimi-002,opencode-003
|
||||
# 输出: claude-001 -> architect
|
||||
# 输出: kimi-002 -> pm
|
||||
# 输出: opencode-003 -> developer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 接口汇总
|
||||
|
||||
| 路径 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/api/agents` | GET | 获取所有 Agent |
|
||||
| `/api/agents/{id}/state` | GET/POST | Agent 状态 |
|
||||
| `/api/locks` | GET | 获取所有锁 |
|
||||
| `/api/locks/acquire` | POST | 获取锁 |
|
||||
| `/api/locks/release` | POST | 释放锁 |
|
||||
| `/api/heartbeats` | GET | 获取心跳列表 |
|
||||
| `/api/heartbeats/{id}` | POST | 更新心跳 |
|
||||
| `/api/meetings/{date}` | GET | 获取会议列表 |
|
||||
| `/api/meetings/{id}` | GET | 获取会议详情 |
|
||||
| `/api/meetings/{id}/wait` | POST | 加入会议等待 |
|
||||
| `/api/workflows/{id}/next` | GET | 获取下一步 |
|
||||
|
||||
---
|
||||
|
||||
## 前端 Mock 替换顺序
|
||||
|
||||
| 步骤 | 组件 | API 端点 |
|
||||
|------|------|----------|
|
||||
| 3 | ResourceMonitorCard | `/api/locks` |
|
||||
| 5 | AgentStatusCard | `/api/agents` |
|
||||
| 7 | MeetingProgressCard | `/api/meetings/{id}` |
|
||||
| 7 | RecentMeetingsCard | `/api/meetings/{date}` |
|
||||
| - | WorkflowCard | `/api/workflows/{id}/next` |
|
||||
|
||||
---
|
||||
|
||||
## 参考开源项目
|
||||
|
||||
### 多智能体协作框架
|
||||
|
||||
| 项目 | 链接 | 参考点 |
|
||||
|------|------|--------|
|
||||
| **AutoGen** | [github.com/microsoft/autogen](https://github.com/microsoft/autogen) | 对话驱动协作、异步消息传递、Agent 交接机制 |
|
||||
| **CrewAI** | [github.com/CrewAIInc/crewAI](https://github.com/CrewAIInc/crewAI) | 角色扮演式 Agent、任务编排、Crew 结构 |
|
||||
| **AgentScope** | [阿里通义实验室](https://github.com/modelscope/agentscope) | Agent 编排、安全沙箱、跨框架互操作 |
|
||||
| **MetaGPT** | [github.com/FoundationAgents/MetaGPT](https://github.com/FoundationAgents/MetaGPT) | AI 软件公司、多角色协作、文档生成 |
|
||||
|
||||
### FastAPI 项目结构
|
||||
|
||||
| 项目 | 链接 | 参考点 |
|
||||
|------|------|--------|
|
||||
| **FastAPI Project Structure** | [github.com/brianobot/fastapi_project_structure](https://github.com/brianobot/fastapi_project_structure) | 分层架构、services/routers/schemas 分离 |
|
||||
| **FastAPI Best Architecture** | [github.com](搜索) | 伪三层架构、插件系统 |
|
||||
| **FastAPI Tips** | [github.com](搜索) | WebSocket 实时通信、性能优化 |
|
||||
|
||||
```
|
||||
推荐目录结构：
|
||||
backend/
|
||||
├── app/
|
||||
│ ├── main.py # FastAPI 入口
|
||||
│ ├── settings.py # 配置管理
|
||||
│ ├── dependencies.py # 依赖注入
|
||||
│ ├── middlewares.py # 中间件
|
||||
│ ├── api_router.py # 路由汇总
|
||||
│ ├── routers/ # API 路由
|
||||
│ │ ├── agents.py
|
||||
│ │ ├── locks.py
|
||||
│ │ └── meetings.py
|
||||
│ ├── services/ # 业务逻辑
|
||||
│ │ ├── storage.py
|
||||
│ │ ├── file_lock.py
|
||||
│ │ ├── heartbeat.py
|
||||
│ │ ├── agent_registry.py
|
||||
│ │ └── meeting_scheduler.py
|
||||
│ ├── schemas/ # Pydantic 模型
|
||||
│ │ ├── agent.py
|
||||
│ │ ├── lock.py
|
||||
│ │ └── meeting.py
|
||||
│ └── models/ # 数据模型（如用数据库）
|
||||
├── cli.py # CLI 入口 (Typer)
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
### 文件锁实现
|
||||
|
||||
| 库 | 链接 | 特点 |
|
||||
|-----|------|------|
|
||||
| **filelock** | [github.com/tox-dev/filelock](https://github.com/tox-dev/filelock) | 跨平台、上下文管理器、超时机制 |
|
||||
| **fasteners** | [github.com/harlowja/fasteners](https://github.com/harlowja/fasteners) | 进程间读写锁 |
|
||||
|
||||
**推荐使用 filelock**：
|
||||
```python
|
||||
from filelock import FileLock, Timeout
|
||||
|
||||
lock = FileLock("/path/to/file.lock", timeout=10)
|
||||
with lock:
|
||||
# 临界区代码
|
||||
pass
|
||||
```
|
||||
|
||||
### WebSocket 实时更新
|
||||
|
||||
FastAPI 原生支持 WebSocket，参考官方文档：[fastapi.tiangolo.com/zh/websockets](https://fastapi.tiangolo.com/zh/advanced/websockets/)
|
||||
|
||||
```python
|
||||
from fastapi import WebSocket
|
||||
|
||||
@app.websocket("/ws")
|
||||
async def websocket_endpoint(websocket: WebSocket):
|
||||
await websocket.accept()
|
||||
async for data in websocket.iter_text():
|
||||
await websocket.send_text(f"Received: {data}")
|
||||
```
|
||||
|
||||
### 技术栈推荐
|
||||
|
||||
```txt
|
||||
# requirements.txt
|
||||
fastapi>=0.110.0
|
||||
uvicorn[standard]>=0.27.0
|
||||
pydantic>=2.0.0
|
||||
typer>=0.9.0
|
||||
aiofiles>=23.0.0
|
||||
filelock>=3.13.0
|
||||
pyyaml>=6.0
|
||||
anthropic>=0.18.0 # Claude API
|
||||
openai>=1.0.0 # OpenAI API
|
||||
```
|
||||
|
||||
### 设计文档参考
|
||||
|
||||
| 文档 | 链接 |
|
||||
|------|------|
|
||||
| AutoGen 编程模型 | [github.com/microsoft/autogen/docs/design](https://github.com/microsoft/autogen/tree/main/docs/design) |
|
||||
| Agent Worker Protocol | [github.com/microsoft/autogen/docs/design](https://github.com/microsoft/autogen/blob/main/docs/design/03%20-%20Agent%20Worker%20Protocol.md) |
|
||||
693
docs/design-spec.md
Normal file
693
docs/design-spec.md
Normal file
@@ -0,0 +1,693 @@
|
||||
# Swarm - 多 Agent 协作系统设计文档
|
||||
|
||||
> 版本：1.0
|
||||
> 日期：2026-03-04
|
||||
> 作者：Swarm Team
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [项目概述](#1-项目概述)
|
||||
2. [系统架构](#2-系统架构)
|
||||
3. [插件化 CLI 工具适配](#3-插件化-cli-工具适配)
|
||||
4. [资源管理与文件锁](#4-资源管理与文件锁)
|
||||
5. [会议与共识机制](#5-会议与共识机制)
|
||||
6. [动态角色分配](#6-动态角色分配)
|
||||
7. [多模型支持](#7-多模型支持)
|
||||
8. [共享存储结构](#8-共享存储结构)
|
||||
9. [技术栈](#9-技术栈)
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
### 1.1 核心目标
|
||||
|
||||
构建一个通用的多 Agent 协作框架，支持：
|
||||
|
||||
- **多工具接入**：Claude Code CLI、Kimi CLI、OpenCode 等命令行 AI 工具
|
||||
- **会议驱动协作**：通过会议流程组织 Agent 间的协作
|
||||
- **资源自动管理**：声明式资源管理，Agent 无需手动处理锁
|
||||
- **协作共识**：Agent 之间通过讨论达成共识，而非简单投票
|
||||
- **动态角色**：AI 根据任务自动分析并分配角色
|
||||
- **多模型支持**：支持多种 LLM，智能路由与故障转移
|
||||
|
||||
### 1.2 设计原则
|
||||
|
||||
| 原则 | 说明 |
|
||||
|-----|------|
|
||||
| 插件化 | CLI 工具通过适配器层接入，实现统一接口 |
|
||||
| 声明式 | Agent 只声明意图，系统自动管理资源 |
|
||||
| 会议驱动 | Workflow 定义会议节点，栅栏同步触发 |
|
||||
| 协作共识 | 多轮讨论、迭代提案、AI 收敛判断 |
|
||||
| AI 分配 | LLM 分析任务自动分配最优角色 |
|
||||
| 可靠性 | 超时 + 心跳 + finally + 看门狗多层保障 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 系统架构
|
||||
|
||||
### 2.1 整体架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 用户界面层 │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Web UI │ │ CLI 工具 │ │ API 接口 │ │ VSCode 插件 │ │
|
||||
│ │ (React/TS) │ │ (Node.js) │ │ (Express) │ │ (TypeScript)│ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 协调层 (Python) │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Workflow Engine │ │ Meeting Scheduler│ │ Resource Manager │ │
|
||||
│ │ (工作流编排) │ │ (栅栏同步) │ │ (文件锁+心跳) │ │
|
||||
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Role Allocator │ │ Consensus Engine │ │ Model Router │ │
|
||||
│ │ (AI角色分配) │ │ (协作共识) │ │ (多模型路由) │ │
|
||||
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Agent 适配层 │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ CLIPluginAdapter Interface │ │
|
||||
│ │ + execute() + join_meeting() + write_state() + read_others() │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ ClaudeCode │ │ KimiCLI │ │ OpenCode │ │ 自定义... │ │
|
||||
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │
|
||||
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 模型层 │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ Anthropic │ │ OpenAI │ │ Google │ │ DeepSeek │ │
|
||||
│ │ API │ │ API │ │ API │ │ API │ │
|
||||
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Ollama (本地模型) │ │
|
||||
│ └────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ 共享存储层 (.doc/) │
|
||||
│ ├── agents/ ├── dialogues/ ├── progress/ │
|
||||
│ ├── resources/ ├── meetings/ ├── cache/ │
|
||||
│ └── workflow/ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件化 CLI 工具适配
|
||||
|
||||
### 3.1 统一接口设计
|
||||
|
||||
```python
|
||||
interface CLIPluginAdapter:
|
||||
"""CLI 工具适配器统一接口"""
|
||||
|
||||
id: str
|
||||
name: str
|
||||
version: str
|
||||
|
||||
# 核心能力
|
||||
def execute(task: Task) -> Result:
|
||||
"""执行任务"""
|
||||
pass
|
||||
|
||||
def join_meeting(meeting_id: str) -> None:
|
||||
"""加入会议等待队列"""
|
||||
pass
|
||||
|
||||
def write_state(state: dict) -> None:
|
||||
"""写入自己的状态文件"""
|
||||
pass
|
||||
|
||||
def read_others(agent_id: str) -> dict:
|
||||
"""读取其他 Agent 的状态"""
|
||||
pass
|
||||
|
||||
def update_heartbeat() -> None:
|
||||
"""更新心跳"""
|
||||
pass
|
||||
```
|
||||
|
||||
### 3.2 预置适配器
|
||||
|
||||
| 适配器 | CLI 工具 | 特点 |
|
||||
|--------|---------|------|
|
||||
| ClaudeCodeAdapter | Claude Code CLI | MCP 支持，代码审查强 |
|
||||
| KimiCLIAdapter | Kimi CLI | ACP 协议，Zsh 集成 |
|
||||
| OpenCodeAdapter | OpenCode | 快速代码生成 |
|
||||
| CustomAdapter | 自定义 | 扩展接口 |
|
||||
|
||||
### 3.3 适配器实现示例
|
||||
|
||||
```python
|
||||
class ClaudeCodeAdapter(CLIPluginAdapter):
|
||||
def __init__(self, config: dict):
|
||||
self.id = "claude-code-001"
|
||||
self.name = "Claude Code"
|
||||
self.config = config
|
||||
self.executor = TaskExecutor(self.id, resource_manager)
|
||||
|
||||
def execute(self, task: Task) -> Result:
|
||||
# 通过 TaskExecutor 自动管理资源
|
||||
return self.executor.execute(task.description)
|
||||
|
||||
def join_meeting(self, meeting_id: str):
|
||||
return meeting_scheduler.wait_for_meeting(self.id, meeting_id)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 资源管理与文件锁
|
||||
|
||||
### 4.1 核心设计
|
||||
|
||||
**声明式资源管理**：Agent 只需要声明"我要修改这个文件"，系统自动获取锁、执行任务、释放锁。
|
||||
|
||||
### 4.2 TaskExecutor 包装层
|
||||
|
||||
```python
|
||||
class TaskExecutor:
|
||||
"""任务执行器 - 自动管理资源生命周期"""
|
||||
|
||||
def execute(self, task_description: str) -> str:
|
||||
# 1. 解析意图，识别需要的文件
|
||||
required_files = self._parse_required_files(task_description)
|
||||
|
||||
# 2. 获取所有需要的锁
|
||||
self._acquire_all_locks(required_files, task_description)
|
||||
|
||||
try:
|
||||
# 3. 执行实际任务
|
||||
result = self._do_execute(task_description)
|
||||
return result
|
||||
finally:
|
||||
# 4. 无论发生什么，都释放锁
|
||||
self._release_all_locks()
|
||||
```
|
||||
|
||||
### 4.3 可靠性保障机制
|
||||
|
||||
| 机制 | 解决问题 | 触发方式 |
|
||||
|-----|---------|---------|
|
||||
| 超时释放 | 锁忘记释放 | 定时器扫描 |
|
||||
| 心跳机制 | Agent 挂了检测 | 定时器 + 心跳超时 |
|
||||
| Lease 上下文管理器 | 代码异常退出 | Python `with` / `finally` |
|
||||
| 生命周期 Hooks | 进程崩溃清理 | `atexit` + 看门狗 |
|
||||
| 看门狗进程 | 整个系统挂了 | 独立进程监控 |
|
||||
| 原子操作 | 并发冲突 | 文件锁 |
|
||||
|
||||
### 4.4 Agent 使用方式
|
||||
|
||||
```python
|
||||
# Agent 代码 - 完全不需要关心锁
|
||||
|
||||
class ClaudeCodeAgent:
|
||||
def fix_login_bug(self):
|
||||
# 只需要描述任务，锁完全透明
|
||||
result = self.executor.execute(
|
||||
"修改 src/main.py 修复登录 bug"
|
||||
)
|
||||
return result
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 会议与共识机制
|
||||
|
||||
### 5.1 栅栏同步
|
||||
|
||||
```python
|
||||
class MeetingScheduler:
|
||||
"""会议调度器 - 实现栅栏同步"""
|
||||
|
||||
def wait_for_meeting(self, agent_id: str, meeting_id: str):
|
||||
"""
|
||||
Agent 调用此方法表示"我准备好了，等会议"
|
||||
最后一个到达的 Agent 触发会议
|
||||
"""
|
||||
queue = self._load_queue()
|
||||
|
||||
# 加入等待队列
|
||||
queue[meeting_id]["waiting_agents"].append(agent_id)
|
||||
|
||||
# 检查是否所有人都准备好了
|
||||
if self._is_everyone_ready(meeting_id):
|
||||
self._start_meeting(meeting_id)
|
||||
return "meeting_started"
|
||||
return "waiting"
|
||||
```
|
||||
|
||||
### 5.2 协作式共识流程
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 协作共识流程 │
|
||||
│ │
|
||||
│ 第一阶段：收集初步想法 │
|
||||
│ Agent A: "建议用 JWT，因为..." │
|
||||
│ Agent B: "我建议用 Session，因为..." │
|
||||
│ Agent C: "两者结合可能更好..." │
|
||||
│ │
|
||||
│ 第二阶段：讨论与迭代（最多5轮） │
|
||||
│ → Agent 互相质疑、补充、融合 │
|
||||
│ → 根据讨论更新提案 │
|
||||
│ → 检查收敛性 │
|
||||
│ │
|
||||
│ 第三阶段：生成共识版本 │
|
||||
│ → 合并相似提案 │
|
||||
│ → 记录讨论过程 │
|
||||
│ → 生成会议文件 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.3 会议文件结构
|
||||
|
||||
```markdown
|
||||
---
|
||||
meeting_id: requirement_review_20260304_103000
|
||||
date: 2026-03-04
|
||||
attendees: [claude-code-001, kimi-cli-002, opencode-003]
|
||||
consensus_type: collaborative
|
||||
iterations: 3
|
||||
---
|
||||
|
||||
# 需求评审会议
|
||||
|
||||
## 参会者
|
||||
- `claude-code-001` (权重: 1.5)
|
||||
- `kimi-cli-002` (权重: 1.0)
|
||||
- `opencode-003` (权重: 1.2)
|
||||
|
||||
## 讨论过程
|
||||
|
||||
### 第一轮：初步想法
|
||||
[各 Agent 的初步提案...]
|
||||
|
||||
### 第二轮：讨论
|
||||
[互相质疑、补充的过程...]
|
||||
|
||||
### 第三轮：迭代
|
||||
[根据讨论更新的提案...]
|
||||
|
||||
## 最终共识
|
||||
[达成的共识内容...]
|
||||
|
||||
## 贡献记录
|
||||
| Agent | 主要贡献 |
|
||||
|-------|---------|
|
||||
| claude-code-001 | ... |
|
||||
| kimi-cli-002 | ... |
|
||||
| opencode-003 | ... |
|
||||
|
||||
## 后续行动
|
||||
1. [ ] ...
|
||||
2. [ ] ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 动态角色分配
|
||||
|
||||
### 6.1 AI 驱动的角色分配
|
||||
|
||||
```python
|
||||
class AIRoleAllocator:
|
||||
"""AI 驱动的角色分配器"""
|
||||
|
||||
def allocate_roles(self, task: Task, available_agents: List[str]) -> dict:
|
||||
"""
|
||||
分析任务，自动分配角色给各 Agent
|
||||
"""
|
||||
# 获取所有 Agent 的能力描述
|
||||
agent_capabilities = self._get_agent_capabilities(available_agents)
|
||||
|
||||
# 构造提示词，让 AI 分析
|
||||
prompt = f"""
|
||||
你是一个团队协调 AI，需要为以下任务分配角色。
|
||||
|
||||
## 任务描述
|
||||
{task.description}
|
||||
|
||||
## 可用的 Agent 及其能力
|
||||
{self._format_capabilities(agent_capabilities)}
|
||||
|
||||
请分析任务需求，为每个 Agent 分配最合适的角色。
|
||||
"""
|
||||
|
||||
# 调用 LLM 分析
|
||||
response = self.llm_client.complete(prompt)
|
||||
allocation = json.loads(response)
|
||||
|
||||
# 应用角色分配
|
||||
for assignment in allocation["role_assignments"]:
|
||||
self._apply_role(
|
||||
assignment["agent_id"],
|
||||
assignment["role"],
|
||||
assignment["reason"]
|
||||
)
|
||||
|
||||
return allocation
|
||||
```
|
||||
|
||||
### 6.2 可用角色
|
||||
|
||||
| 角色 | 名称 | 能力 | 权重 |
|
||||
|-----|------|------|------|
|
||||
| pm | 产品经理 | 需求分析、优先级排序、用户故事 | 1.5 |
|
||||
| architect | 架构师 | 系统设计、技术选型、性能规划 | 1.5 |
|
||||
| developer | 开发者 | 编码、单元测试、代码审查 | 1.0 |
|
||||
| qa | 测试工程师 | 测试用例、自动化测试、bug报告 | 1.2 |
|
||||
| reviewer | 代码审查者 | 代码审查、安全检查、性能分析 | 1.3 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 多模型支持
|
||||
|
||||
### 7.1 智能路由策略
|
||||
|
||||
```python
|
||||
class MultiModelRouter:
|
||||
"""多模型路由器"""
|
||||
|
||||
def route(self, task: Task, context: dict) -> str:
|
||||
"""
|
||||
智能路由：根据任务类型选择最合适的模型
|
||||
"""
|
||||
task_type = self._classify_task(task)
|
||||
|
||||
routing_rules = {
|
||||
"complex_reasoning": ("anthropic", "claude-opus-4.6"),
|
||||
"code_generation": ("anthropic", "claude-sonnet-4.6"),
|
||||
"simple_task": ("anthropic", "claude-haiku-4.6"),
|
||||
"cost_sensitive": ("deepseek", "deepseek-chat"),
|
||||
"local_privacy": ("ollama", "llama3"),
|
||||
"multimodal": ("google", "gemini-2.5-flash")
|
||||
}
|
||||
|
||||
provider, model = routing_rules.get(task_type, default)
|
||||
return self.providers[provider].complete(model, task, context)
|
||||
```
|
||||
|
||||
### 7.2 故障转移
|
||||
|
||||
```python
|
||||
def route_with_failover(self, task: Task, context: dict) -> str:
|
||||
"""带故障转移的路由"""
|
||||
primary_route = self._get_primary_route(task)
|
||||
fallback_routes = self._get_fallback_routes()
|
||||
|
||||
# 尝试主路由
|
||||
try:
|
||||
return self._execute_route(primary_route, task, context)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# 尝试备选路由
|
||||
for route in fallback_routes:
|
||||
try:
|
||||
return self._execute_route(route, task, context)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# 全部失败，使用最简单的本地模型
|
||||
return self._execute_local_fallback(task, context)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 共享存储结构
|
||||
|
||||
```
|
||||
.doc/
|
||||
├── agents/ # Agent 注册与状态
|
||||
│ ├── registry.json # 所有已注册 Agent 列表
|
||||
│ ├── claude-code-001/ # 每个 Agent 的独立目录
|
||||
│ │ ├── config.json # Agent 配置
|
||||
│ │ ├── state.json # 当前状态
|
||||
│ │ ├── history.json # 历史记录
|
||||
│ │ └── capabilities.json # 能力声明
|
||||
│ └── ...
|
||||
│
|
||||
├── dialogues/ # Agent 间对话记录
|
||||
│ └── [agent_a]_[agent_b]_[timestamp].json
|
||||
│
|
||||
├── progress/ # 工程进度
|
||||
│ ├── project_state.json # 项目整体状态
|
||||
│ ├── milestones.json # 里程碑
|
||||
│ └── tasks.json # 任务列表
|
||||
│
|
||||
├── resources/ # 资源分配
|
||||
│ ├── resource_pool.json # 资源池状态
|
||||
│ ├── file_locks.json # 文件锁
|
||||
│ └── allocation_log.json # 分配日志
|
||||
│
|
||||
├── meetings/ # 会议记录与共识
|
||||
│ ├── [YYYY-MM-DD]/
|
||||
│ │ └── [HHMMSS]_[meeting_name].md
|
||||
│ └── meeting_template.md
|
||||
│
|
||||
├── cache/ # 实时缓存
|
||||
│ ├── meeting_queue.json # 会议等待队列
|
||||
│ ├── message_bus.json # 消息总线快照
|
||||
│ ├── lock_state.json # 锁状态缓存
|
||||
│ └── heartbeats.json # Agent 心跳
|
||||
│
|
||||
├── workflow/ # 工作流定义
|
||||
│ ├── project_workflow.yaml # 项目工作流
|
||||
│ ├── meeting_definitions.yaml # 会议定义
|
||||
│ └── consensus_rules.yaml # 共识规则
|
||||
│
|
||||
└── shared/ # 共享资源
|
||||
├── knowledge_base/ # 知识库
|
||||
├── templates/ # 模板文件
|
||||
└── conventions/ # 编码规范
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 技术栈
|
||||
|
||||
### 9.1 后端 (Python)
|
||||
|
||||
| 组件 | 技术选择 |
|
||||
|-----|---------|
|
||||
| 核心框架 | Python 3.12+ |
|
||||
| 异步运行时 | asyncio |
|
||||
| LLM 调用 | anthropic, openai, langchain |
|
||||
| 文件操作 | pathlib, aiofiles |
|
||||
| 进程管理 | subprocess, multiprocessing |
|
||||
| 定时任务 | APScheduler |
|
||||
|
||||
### 9.2 前端 (TypeScript)
|
||||
|
||||
| 组件 | 技术选择 |
|
||||
|-----|---------|
|
||||
| 框架 | React 18 + TypeScript |
|
||||
| UI 库 | shadcn/ui + Tailwind CSS |
|
||||
| 状态管理 | Zustand |
|
||||
| 实时通信 | WebSocket |
|
||||
| HTTP 客户端 | fetch / axios |
|
||||
|
||||
### 9.3 API 层 (Node.js)
|
||||
|
||||
| 组件 | 技术选择 |
|
||||
|-----|---------|
|
||||
| 框架 | Express / Fastify |
|
||||
| 类型检查 | TypeScript |
|
||||
| 实时通信 | Socket.IO |
|
||||
| 进程通信 | child_process |
|
||||
|
||||
---
|
||||
|
||||
## 附录
|
||||
|
||||
### A. 参考项目
|
||||
|
||||
详见 [reference-projects.md](reference-projects.md)
|
||||
|
||||
### B. 更新日志
|
||||
|
||||
| 版本 | 日期 | 变更 |
|
||||
|-----|------|------|
|
||||
| 1.0 | 2026-03-04 | 初始版本 |
|
||||
| 1.1 | 2026-03-04 | 添加人类参与系统设计 |
|
||||
|
||||
### C. 人类参与系统
|
||||
|
||||
#### C.1 设计概述
|
||||
|
||||
人类参与者通过 `humans.json` 文件参与协作，无需 API 或 UI 调用。
|
||||
|
||||
**核心特点**：
|
||||
- 单一共享文件 `humans.json`
|
||||
- 事件驱动通知机制
|
||||
- 按优先级区分处理
|
||||
- 自动合并到会议讨论
|
||||
|
||||
#### C.2 文件结构
|
||||
|
||||
```
|
||||
.doc/
|
||||
├── agents/ # Agent 目录
|
||||
├── humans.json # 人类输入共享文件
|
||||
├── meetings/ # 会议文件
|
||||
├── events/ # 事件通知
|
||||
└── task_queue.json # 任务队列
|
||||
```
|
||||
|
||||
#### C.3 humans.json 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"last_updated": "2026-03-04T14:30:00Z",
|
||||
|
||||
"participants": {
|
||||
"user001": {
|
||||
"name": "张三",
|
||||
"role": "tech_lead",
|
||||
"status": "online",
|
||||
"avatar": "👤"
|
||||
}
|
||||
},
|
||||
|
||||
// 任务需求
|
||||
"task_requests": [
|
||||
{
|
||||
"id": "req_001",
|
||||
"from": "user001",
|
||||
"timestamp": "2026-03-04T14:28:00Z",
|
||||
"priority": "high", // high | medium | low
|
||||
"type": "correction",
|
||||
"title": "登录验证方式调整",
|
||||
"content": "建议改用 Session + Redis",
|
||||
"target_files": ["src/auth/login.py"],
|
||||
"suggested_agent": "claude-code-001",
|
||||
"urgent": true,
|
||||
"status": "pending"
|
||||
}
|
||||
],
|
||||
|
||||
// 会议发言
|
||||
"meeting_comments": [
|
||||
{
|
||||
"id": "comment_001",
|
||||
"from": "user001",
|
||||
"meeting_id": "design_review",
|
||||
"timestamp": "2026-03-04T14:25:00Z",
|
||||
"type": "proposal",
|
||||
"priority": "normal",
|
||||
"content": "建议使用 SQLite，保持简单",
|
||||
"status": "pending"
|
||||
}
|
||||
],
|
||||
|
||||
// 人类状态
|
||||
"human_states": {
|
||||
"user001": {
|
||||
"status": "online",
|
||||
"current_focus": "reviewing",
|
||||
"preferred_contact": "async"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### C.4 事件驱动流程
|
||||
|
||||
```
|
||||
人类写入 humans.json
|
||||
↓
|
||||
文件监听器触发
|
||||
↓
|
||||
写入 events/notification_stream.json
|
||||
↓
|
||||
┌───────┴────────┐
|
||||
│ │
|
||||
↓ ↓
|
||||
会议通知 任务通知
|
||||
│ │
|
||||
↓ ↓
|
||||
Agent 收到 Agent 收到
|
||||
会议通知 任务通知
|
||||
│ │
|
||||
↓ ↓
|
||||
读取会议 读取任务
|
||||
评论部分 requests
|
||||
│ │
|
||||
↓ ↓
|
||||
参与讨论 按优先级
|
||||
处理任务
|
||||
```
|
||||
|
||||
#### C.5 任务优先级处理
|
||||
|
||||
| 优先级 | 处理方式 | 示例 |
|
||||
|-------|---------|------|
|
||||
| **high** + urgent | 立即中断当前任务 | 安全漏洞修复、生产故障 |
|
||||
| **high** | 尽快处理，完成当前任务后 | 功能调整、架构变更 |
|
||||
| **medium** | 加入队列，按序处理 | 功能增强、文档补充 |
|
||||
| **low** | 空闲时处理 | 优化建议、非紧急任务 |
|
||||
|
||||
#### C.6 会议中的人类发言显示
|
||||
|
||||
```markdown
|
||||
## 讨论记录
|
||||
|
||||
### Agent 提案
|
||||
**claude-code-001 (14:20)**:
|
||||
> 建议使用 JWT + Refresh Token...
|
||||
|
||||
### 人类发言（高优先级）
|
||||
**user001 [HUMAN] ⚠️ (14:22)**:
|
||||
> 我反对使用 JWT。我们的数据量不大，SQLite + Session 就够了。
|
||||
>
|
||||
> **优先级：HIGH**
|
||||
|
||||
### Agent 响应
|
||||
**kimi-cli-002 (14:23)**:
|
||||
> 收到用户反馈，重新评估方案...
|
||||
```
|
||||
|
||||
#### C.7 前端输入实现
|
||||
|
||||
前端提供任务输入栏，输入后：
|
||||
|
||||
1. 写入 `humans.json` 的 `task_requests`
|
||||
2. 记录发送时间戳
|
||||
3. 触发文件监听事件
|
||||
4. Agent 读取并处理
|
||||
|
||||
```javascript
|
||||
// 提交任务
|
||||
function submitTask(content, priority = "medium") {
|
||||
const request = {
|
||||
id: `req_${Date.now()}`,
|
||||
from: "user001",
|
||||
timestamp: new Date().toISOString(),
|
||||
priority: priority,
|
||||
type: "user_task",
|
||||
content: content,
|
||||
status: "pending"
|
||||
};
|
||||
|
||||
// 写入 humans.json
|
||||
humans.task_requests.push(request);
|
||||
// 保存文件...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*文档结束*
|
||||
187
docs/frontend-steps.md
Normal file
187
docs/frontend-steps.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 前端开发步骤
|
||||
|
||||
后端已完成并验证通过，现在重新设计前端为多页面应用。
|
||||
|
||||
---
|
||||
|
||||
## 后端 CLI 验证结果
|
||||
|
||||
| 服务 | 状态 | 测试命令 |
|
||||
|------|------|----------|
|
||||
| 项目初始化 | ✅ | `python cli.py hello`, `python cli.py version` |
|
||||
| 存储服务 | ✅ | `python cli.py storage write/read/delete` |
|
||||
| 文件锁 | ✅ | `python cli.py lock acquire/status/release/check` |
|
||||
| 心跳服务 | ✅ | `python cli.py heartbeat ping/list` |
|
||||
| Agent 注册 | ✅ | `python cli.py agent register/list/info/state` |
|
||||
| 会议调度 | ✅ | `python cli.py meeting create/wait/queue` |
|
||||
| 会议记录 | ✅ | `python cli.py meeting record-create/discuss/progress` |
|
||||
| 资源管理 | ✅ | `python cli.py execute`, `python cli.py status` |
|
||||
| 工作流引擎 | ✅ | `python cli.py workflow show` |
|
||||
| 角色分配 | ✅ | `python cli.py role allocate/primary` |
|
||||
|
||||
---
|
||||
|
||||
## 前端架构重新设计
|
||||
|
||||
### 当前问题
|
||||
- 单页面应用，所有组件挤在一起
|
||||
- 没有导航结构
|
||||
- 难以扩展
|
||||
|
||||
### 新架构设计
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── pages/ # 页面组件
|
||||
│ │ ├── DashboardPage.tsx # 仪表盘首页
|
||||
│ │ ├── AgentsPage.tsx # Agent 管理页
|
||||
│ │ ├── MeetingsPage.tsx # 会议管理页
|
||||
│ │ ├── ResourcesPage.tsx # 资源监控页
|
||||
│ │ ├── SettingsPage.tsx # 配置页面
|
||||
│ │ └── WorkflowPage.tsx # 工作流页面
|
||||
│ ├── components/ # 共享组件
|
||||
│ │ ├── layout/
|
||||
│ │ │ ├── AppLayout.tsx # 主布局（导航栏）
|
||||
│ │ │ └── Sidebar.tsx # 侧边栏
|
||||
│ │ ├── ui/ # UI 组件
|
||||
│ │ └── dashboard/ # 仪表盘组件
|
||||
│ ├── lib/ # API 客户端
|
||||
│ │ └── api.ts # 统一 API 调用
|
||||
│ └── App.tsx # 路由入口
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 页面设计规范
|
||||
|
||||
### 1. 仪表盘 (DashboardPage)
|
||||
- 组件网格：Agent 状态卡片、会议进度、资源监控、最近会议
|
||||
- 实时更新（轮询或 WebSocket）
|
||||
- 快捷操作按钮
|
||||
|
||||
### 2. Agent 管理页 (AgentsPage)
|
||||
- Agent 列表（表格或卡片）
|
||||
- 注册新 Agent 表单
|
||||
- Agent 详情面板（可展开）
|
||||
- 状态指示器
|
||||
|
||||
### 3. 会议管理页 (MeetingsPage)
|
||||
- 会议列表（按日期分组）
|
||||
- 创建会议按钮
|
||||
- 会议详情（步骤进度、讨论记录）
|
||||
- 参会者状态
|
||||
|
||||
### 4. 资源监控页 (ResourcesPage)
|
||||
- 文件锁列表
|
||||
- CPU/内存使用情况
|
||||
- Agent 心跳状态
|
||||
- 实时刷新
|
||||
|
||||
### 5. 配置页 (SettingsPage)
|
||||
- 后端 API 地址配置
|
||||
- Agent 配置
|
||||
- 工作流上传
|
||||
- 系统设置
|
||||
|
||||
### 6. 工作流页 (WorkflowPage)
|
||||
- 工作流列表
|
||||
- YAML 编辑器
|
||||
- 工作流执行状态
|
||||
- 进度追踪
|
||||
|
||||
---
|
||||
|
||||
## 开发步骤
|
||||
|
||||
### 第一步：路由和布局
|
||||
- 安装 React Router
|
||||
- 创建 AppLayout 和 Sidebar
|
||||
- 配置路由
|
||||
|
||||
### 第二步：仪表盘页面
|
||||
- 从现有组件迁移到 DashboardPage
|
||||
- 添加导航链接
|
||||
|
||||
### 第三步：API 客户端
|
||||
- 创建 `lib/api.ts`
|
||||
- 实现所有 API 调用函数
|
||||
- 替换 mock 数据
|
||||
|
||||
### 第四步：Agent 管理页
|
||||
- 创建 AgentsPage
|
||||
- 注册表单
|
||||
- Agent 列表和详情
|
||||
|
||||
### 第五步：会议管理页
|
||||
- 创建 MeetingsPage
|
||||
- 会议列表和详情
|
||||
- 创建会议模态框
|
||||
|
||||
### 第六步：资源监控页
|
||||
- 创建 ResourcesPage
|
||||
- 实时数据刷新
|
||||
- 图表展示
|
||||
|
||||
### 第七步：配置页面
|
||||
- 创建 SettingsPage
|
||||
- 表单输入
|
||||
- 配置保存
|
||||
|
||||
### 第八步：工作流页面
|
||||
- 创建 WorkflowPage
|
||||
- YAML 上传和编辑
|
||||
- 执行状态展示
|
||||
|
||||
---
|
||||
|
||||
## 路由结构
|
||||
|
||||
```typescript
|
||||
const routes = [
|
||||
{ path: '/', element: <DashboardPage /> },
|
||||
{ path: '/agents', element: <AgentsPage /> },
|
||||
{ path: '/meetings', element: <MeetingsPage /> },
|
||||
{ path: '/resources', element: <ResourcesPage /> },
|
||||
{ path: '/settings', element: <SettingsPage /> },
|
||||
{ path: '/workflow', element: <WorkflowPage /> },
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 端点对接
|
||||
|
||||
```typescript
|
||||
// API 基础配置
|
||||
const API_BASE = 'http://localhost:8000/api';
|
||||
|
||||
// Agents
|
||||
GET /api/agents
|
||||
POST /api/agents/register
|
||||
GET /api/agents/:id
|
||||
GET /api/agents/:id/state
|
||||
POST /api/agents/:id/state
|
||||
|
||||
// Locks
|
||||
GET /api/locks
|
||||
POST /api/locks/acquire
|
||||
POST /api/locks/release
|
||||
|
||||
# Heartbeats
|
||||
GET /api/heartbeats
|
||||
POST /api/heartbeats/:id
|
||||
|
||||
# Meetings
|
||||
GET /api/meetings/:date
|
||||
GET /api/meetings/:id
|
||||
POST /api/meetings/create
|
||||
POST /api/meetings/:id/discuss
|
||||
POST /api/meetings/:id/progress
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
开始实施前端开发步骤，从路由和布局开始。
|
||||
305
docs/reference-projects.md
Normal file
305
docs/reference-projects.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 多 Agent 协作系统 - 参考项目分析
|
||||
|
||||
> 本文档分析相关开源项目的优点，用于设计整合
|
||||
|
||||
---
|
||||
|
||||
## 一、插件化架构参考
|
||||
|
||||
### 1. OpenClaw ⭐⭐⭐⭐⭐
|
||||
**GitHub**: [MindDock/OpenClaw](https://github.com/MindDock/OpenClaw)
|
||||
|
||||
**核心优点**：
|
||||
- **Channel Plugin 接口**：统一的插件架构，支持消息通道、Agent 工具、CLI 扩展
|
||||
- **Plugin SDK**：完整的插件开发框架，包含扩展点、配置系统、发布流程
|
||||
- **Gateway 控制平面**：WebSocket/HTTP 控制平面，支持 RPC 方法、事件系统
|
||||
- **适配器模式**：每个插件实现标准接口，易于扩展
|
||||
|
||||
```typescript
|
||||
// OpenClaw Channel Plugin 接口
|
||||
interface ChannelPlugin {
|
||||
id: string;
|
||||
meta: ChannelMeta;
|
||||
capabilities: ChannelCapabilities;
|
||||
config: ChannelConfigAdapter;
|
||||
outbound: ChannelOutboundAdapter;
|
||||
inbound?: ChannelInboundAdapter;
|
||||
messaging?: ChannelMessagingAdapter;
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：CLI 工具插件化、多通道适配
|
||||
|
||||
---
|
||||
|
||||
### 2. everything-claude-code ⭐⭐⭐⭐⭐
|
||||
**GitHub**: [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)
|
||||
|
||||
**核心优点**：
|
||||
- **跨工具兼容**：设计为可在 Claude Code、Codex、Cursor、OpenCode 等多种工具运行
|
||||
- **DRY Adapter**：适配器模式实现跨工具通用描述
|
||||
- **插件系统**：完整的 Claude Code 插件，支持 agents、commands、skills、hooks
|
||||
- **多语言规则架构**：按语言分组的规则系统（common + typescript + python + golang）
|
||||
|
||||
```json
|
||||
{
|
||||
"extraKnownMarketplaces": {
|
||||
"everything-claude-code": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "affaan-m/everything-claude-code"
|
||||
}
|
||||
}
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"everything-claude-code@everything-claude-code": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：跨 CLI 工具的 Agent 适配
|
||||
|
||||
---
|
||||
|
||||
### 3. Kimi CLI ⭐⭐⭐⭐
|
||||
**GitHub**: [MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
|
||||
|
||||
**核心优点**：
|
||||
- **Agent Client Protocol (ACP)**：标准的 Agent 客户端协议
|
||||
- **MCP 支持**：完整的 Model Context Protocol 支持
|
||||
- **Zsh 集成**：Shell 集成，支持模式切换（Agent/Shell）
|
||||
|
||||
```bash
|
||||
# MCP 配置示例
|
||||
kimi --mcp-config-file /path/to/mcp.json
|
||||
```
|
||||
|
||||
**适用场景**：CLI 工具的 MCP 集成参考
|
||||
|
||||
---
|
||||
|
||||
## 二、共识机制参考
|
||||
|
||||
### 1. W-5 Multi-Agent Consensus Framework ⭐⭐⭐⭐⭐
|
||||
**GitHub**: [Winner12-AI/w5-football-prediction](https://github.com/Winner12-AI/w5-football-prediction)
|
||||
|
||||
**核心优点**：
|
||||
- **概率再平衡器**：使用 Gemini 3 作为"概率再平衡器"
|
||||
- **动态提示注入**：根据任务动态调整提示词
|
||||
- **多 Agent 辩论**：Agent 之间通过辩论达成共识
|
||||
- **准确率提升**：86.3% 准确率，通过共识机制实现
|
||||
|
||||
```
|
||||
共识流程：
|
||||
1. 各 Agent 独立分析
|
||||
2. 提出初步结论
|
||||
3. Agent 之间辩论
|
||||
4. 概率再平衡
|
||||
5. 达成共识
|
||||
```
|
||||
|
||||
**适用场景**：多 Agent 决策共识
|
||||
|
||||
---
|
||||
|
||||
### 2. Claude-Flow ⭐⭐⭐⭐⭐
|
||||
**项目**: Enterprise multi-agent orchestration for Claude Code
|
||||
|
||||
**核心优点**：
|
||||
- **容错共识**：支持 Byzantine、Weighted、Majority 三种共识机制
|
||||
- **Queen-led Swarms**：层级化协调，防止 Agent 漂移
|
||||
- **SONA 学习**：自优化神经架构，<0.05ms 适应速度
|
||||
- **HNSW Memory**：150x-12,500x 更快的模式检索
|
||||
|
||||
| 共识类型 | 特点 | 适用场景 |
|
||||
|---------|------|---------|
|
||||
| Byzantine | 2/3 多数，抗恶意节点 | 高安全要求 |
|
||||
| Weighted | 按权重投票 | 专家系统 |
|
||||
| Majority | 简单多数 | 快速决策 |
|
||||
| Raft | 领导者选举 | 分布式协调 |
|
||||
| Gossip | 流言传播 | 大规模系统 |
|
||||
|
||||
**适用场景**：企业级 Agent 编排、容错共识
|
||||
|
||||
---
|
||||
|
||||
### 3. Multi-Agent Consensus Seeking via LLMs
|
||||
**论文**: [Multi-Agent Consensus Seeking Via Large Language Models](https://www.aminer.cn/pub/6541a83c939a5f40824d000c/multi-agent-consensus-seeking-via-large-language-models)
|
||||
|
||||
**核心优点**：
|
||||
- **平均策略**：LLM Agent 主要使用平均策略寻求共识
|
||||
- **网络拓扑影响**：分析 Agent 数量、个性、网络拓扑对谈判的影响
|
||||
- **零样本自主规划**：应用于多机器人聚合任务
|
||||
|
||||
**适用场景**：Agent 谈判、共识算法设计
|
||||
|
||||
---
|
||||
|
||||
## 三、协作协议参考
|
||||
|
||||
### 1. Co-TAP: Three-Layer Agent Interaction Protocol ⭐⭐⭐⭐⭐
|
||||
**项目**: Co-TAP 三层 Agent 交互协议
|
||||
|
||||
**核心优点**：
|
||||
- **HAI (Human-Agent Interaction)**：人机交互标准化
|
||||
- **UAP (Unified Agent Protocol)**：异构 Agent 统一通信
|
||||
- **MEK (Memory-Extraction-Knowledge)**：认知链标准化
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ HAI 层：用户-界面-Agent 信息流标准化 │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ UAP 层：异构 Agent 无缝互联 │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ MEK 层：记忆-提取-知识认知链 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**适用场景**：跨平台 Agent 通信
|
||||
|
||||
---
|
||||
|
||||
### 2. Internet of Agents (IoA) ⭐⭐⭐⭐
|
||||
**论文**: Internet of Agents: Fundamentals, Applications, and Challenges
|
||||
|
||||
**核心优点**：
|
||||
- **能力通知与发现**：Agent 动态发现机制
|
||||
- **自适应通信协议**：协议转换机制
|
||||
- **动态任务匹配**：任务自动分配
|
||||
- **共识与冲突解决**：内置冲突解决机制
|
||||
- **激励模型**：经济激励机制
|
||||
|
||||
**适用场景**：大规模 Agent 网络
|
||||
|
||||
---
|
||||
|
||||
### 3. Agent Name Service (ANS) ⭐⭐⭐⭐
|
||||
**项目**: Universal Directory for AI Agent Discovery
|
||||
|
||||
**核心优点**：
|
||||
- **PKI 证书**：可验证的 Agent 身份
|
||||
- **DNS 命名**：DNS 风格的命名约定
|
||||
- **协议适配器层**：支持 A2A、MCP、ACP 等多种协议
|
||||
- **安全解析**：正式化的解析算法
|
||||
|
||||
**适用场景**：Agent 发现与互操作
|
||||
|
||||
---
|
||||
|
||||
## 四、MCP 集成参考
|
||||
|
||||
### 1. MCP 协议完整生态
|
||||
**标准**: Model Context Protocol (Anthropic)
|
||||
|
||||
**核心优点**：
|
||||
- **三种传输模式**：stdio、http、sse
|
||||
- **三大核心原语**：Tools、Resources、Prompts
|
||||
- **动态发现**：运行时工具发现
|
||||
- **16000+ Server**：丰富的生态
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://github-mcp.example.com",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${GITHUB_TOKEN}"
|
||||
}
|
||||
},
|
||||
"filesystem": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Projects"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、整合设计建议
|
||||
|
||||
基于以上分析，建议整合以下优点：
|
||||
|
||||
### 1. 插件化架构（来自 OpenClaw + everything-claude-code）
|
||||
```python
|
||||
interface CLIPluginAdapter {
|
||||
id: string
|
||||
name: string
|
||||
version: string
|
||||
|
||||
# 适配能力
|
||||
def execute(task: Task) -> Result
|
||||
def get_status() -> Status
|
||||
def join_meeting(meeting_id: str) -> None
|
||||
def write_state(state: dict) -> None
|
||||
def read_others(agent_id: str) -> dict
|
||||
}
|
||||
|
||||
# 预置适配器
|
||||
class ClaudeCodeAdapter(CLIPluginAdapter): ...
|
||||
class KimiCodeAdapter(CLIPluginAdapter): ...
|
||||
class OpenCodeAdapter(CLIPluginAdapter): ...
|
||||
```
|
||||
|
||||
### 2. 共识机制（来自 Claude-Flow + W-5）
|
||||
```python
|
||||
class ConsensusMechanism:
|
||||
def propose(self, agent_id: str, proposal: Proposal) -> None
|
||||
def vote(self, agent_id: str, vote: Vote) -> None
|
||||
def resolve(self) -> Decision
|
||||
|
||||
# 共识类型
|
||||
class ByzantineConsensus(ConsensusMechanism): ...
|
||||
class WeightedConsensus(ConsensusMechanism): ...
|
||||
class MajorityConsensus(ConsensusMechanism): ...
|
||||
```
|
||||
|
||||
### 3. 会议驱动（栅栏同步）
|
||||
```python
|
||||
class MeetingBarrier:
|
||||
def wait(self, agent_id: str) -> None
|
||||
def trigger_when_all_ready(self) -> None
|
||||
def start_conensus_process(self) -> Decision
|
||||
```
|
||||
|
||||
### 4. .doc 文件夹结构
|
||||
```
|
||||
.doc/
|
||||
├── agents/ # Agent 注册与状态
|
||||
│ ├── claude-code.json
|
||||
│ ├── kimi-cli.json
|
||||
│ └── opencode.json
|
||||
├── dialogues/ # Agent 间对话记录
|
||||
│ └── agent_a_agent_b_20250304.json
|
||||
├── progress/ # 工程进度
|
||||
│ └── project_state.json
|
||||
├── resources/ # 资源分配与锁
|
||||
│ └── resource_pool.json
|
||||
├── meetings/ # 会议记录与共识
|
||||
│ └── meeting_20250304.md
|
||||
├── cache/ # 实时缓存
|
||||
│ └── meeting_queue.json
|
||||
└── workflow/ # 工作流定义
|
||||
└── project_workflow.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、参考项目链接汇总
|
||||
|
||||
| 项目 | GitHub/链接 | 核心价值 |
|
||||
|-----|------------|---------|
|
||||
| OpenClaw | [MindDock/OpenClaw](https://github.com/MindDock/OpenClaw) | 插件化架构 |
|
||||
| everything-claude-code | [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 跨工具兼容 |
|
||||
| Kimi CLI | [MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) | MCP + ACP |
|
||||
| W-5 Framework | [Winner12-AI/w5-football-prediction](https://github.com/Winner12-AI/w5-football-prediction) | 共识机制 |
|
||||
| Claude-Flow | [ruvnet/claude-flow](https://github.com/ruvnet/claude-flow) | 企业级编排 |
|
||||
| RuVector | [ruvnet/ruvector](https://github.com/ruvnet/ruvector) | 自学习向量库 |
|
||||
| template-repo | [AndrewAltimit/template-repo](https://github.com/AndrewAltimit/template-repo) | 6 Agents + 14 MCP |
|
||||
| MCP Protocol | [modelcontextprotocol](https://modelcontextprotocol.io/) | 统一协议标准 |
|
||||
|
||||
---
|
||||
|
||||
*更新日期：2026-03-04*
|
||||
Reference in New Issue
Block a user