multiAgentTry/docs/api-reference.md

# 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 通过 ✅