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

GET /api/agents

响应示例:

{
  "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

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 详情

GET /api/agents/:agent_id

响应示例:

{
  "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 状态

GET /api/agents/:agent_id/state

响应示例:

{
  "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 状态

POST /api/agents/:agent_id/state
Content-Type: application/json

{
  "task": "编写测试用例",
  "progress": 50,
  "working_files": ["tests/test_auth.py"]
}

---

2. 文件锁接口

2.1 获取所有锁

GET /api/locks

响应示例:

{
  "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 获取文件锁

POST /api/locks/acquire
Content-Type: application/json

{
  "file_path": "src/auth/login.py",
  "agent_id": "claude-001",
  "agent_name": "CLA"
}

响应示例:

{
  "success": true,
  "file_path": "src/auth/login.py",
  "agent_id": "claude-001"
}

2.3 释放文件锁

POST /api/locks/release
Content-Type: application/json

{
  "file_path": "src/auth/login.py",
  "agent_id": "claude-001"
}

2.4 检查文件锁定状态

GET /api/locks/check?file_path=src/auth/login.py

响应示例:

{
  "file_path": "src/auth/login.py",
  "locked": true,
  "locked_by": "claude-001"
}

---

3. 心跳接口

3.1 获取所有心跳

GET /api/heartbeats

响应示例:

{
  "heartbeats": {
    "claude-001": {
      "agent_id": "claude-001",
      "status": "working",
      "current_task": "修复bug",
      "progress": 50,
      "elapsed_display": "2m 15s",
      "is_timeout": false
    }
  }
}

3.2 更新心跳

POST /api/heartbeats/:agent_id
Content-Type: application/json

{
  "status": "working",
  "current_task": "实现功能",
  "progress": 75
}

状态可选值: working, waiting, idle, error

3.3 检查超时 Agent

GET /api/heartbeats/timeouts?timeout_seconds=60

响应示例:

{
  "timeout_seconds": 60,
  "timeout_agents": ["agent-002", "agent-003"]
}

---

4. 会议调度接口

4.1 创建会议

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 获取会议队列

GET /api/meetings/:meeting_id/queue

响应示例:

{
  "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 等待会议开始（栅栏同步）

POST /api/meetings/:meeting_id/wait
Content-Type: application/json

{
  "agent_id": "claude-001",
  "timeout": 300
}

响应示例:

{
  "result": "started",
  "meeting_id": "design-review-001",
  "agent_id": "claude-001"
}

result 说明:

• started: 会议已开始（最后一个到达者触发）
• timeout: 等待超时
• error: 发生错误

4.4 结束会议

POST /api/meetings/:meeting_id/end

---

5. 会议记录接口

5.1 创建会议记录

POST /api/meetings/record/create
Content-Type: application/json

{
  "meeting_id": "design-review-001",
  "title": "设计评审",
  "attendees": ["claude-001", "kimi-002"],
  "steps": ["收集想法", "讨论迭代", "生成共识"]
}

5.2 添加讨论记录

POST /api/meetings/:meeting_id/discuss
Content-Type: application/json

{
  "agent_id": "claude-001",
  "agent_name": "Claude",
  "content": "我建议使用 JWT 认证方案",
  "step": "讨论迭代"
}

5.3 更新会议进度

POST /api/meetings/:meeting_id/progress
Content-Type: application/json

{
  "step": "讨论迭代"
}

5.4 获取会议详情

GET /api/meetings/:meeting_id?date=2026-03-05

响应示例:

{
  "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 完成会议

POST /api/meetings/:meeting_id/finish
Content-Type: application/json

{
  "consensus": "采用 JWT + Redis 方案"
}

---

6. 资源管理接口

6.1 执行任务

POST /api/execute
Content-Type: application/json

{
  "agent_id": "claude-001",
  "task": "修复 src/auth/login.py 中的 bug",
  "timeout": 300
}

响应示例:

{
  "success": true,
  "message": "Task executed: 修复 src/auth/login.py 中的 bug",
  "files_locked": ["src/auth/login.py"],
  "duration_seconds": 1.25
}

6.2 获取所有 Agent 状态

GET /api/status

响应示例:

{
  "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 解析任务文件

POST /api/parse-task
Content-Type: application/json

{
  "task": "修复 src/auth/login.py 和 src/utils/helper.js"
}

响应示例:

{
  "task": "修复 src/auth/login.py 和 src/utils/helper.js",
  "files": ["src/auth/login.py", "src/utils/helper.js"]
}

---

7. 工作流接口

7.1 加载工作流

POST /api/workflows/load
Content-Type: application/json

{
  "path": "example.yaml"
}

响应示例:

{
  "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 获取工作流状态

GET /api/workflows/:workflow_id/status

7.3 获取下一个会议

GET /api/workflows/:workflow_id/next

7.4 标记会议完成

POST /api/workflows/:workflow_id/complete
Content-Type: application/json

{
  "meeting_id": "requirements-review"
}

7.5 列出可用工作流文件

GET /api/workflows/files

响应示例:

{
  "files": ["example.yaml", "project-a.yaml"]
}

---

8. 角色分配接口

8.1 获取任务主要角色

POST /api/roles/primary
Content-Type: application/json

{
  "task": "实现登录功能并编写测试用例"
}

响应示例:

{
  "task": "实现登录功能并编写测试用例",
  "primary_role": "pm",
  "role_scores": {
    "pm": 1.5,
    "qa": 1.2,
    "developer": 1.0,
    "architect": 0.15,
    "reviewer": 0.13
  }
}

8.2 分配角色

POST /api/roles/allocate
Content-Type: application/json

{
  "task": "设计数据库架构并实现 API",
  "agents": ["claude-001", "kimi-002", "opencode-003"]
}

响应示例:

{
  "task": "设计数据库架构并实现 API",
  "primary_role": "architect",
  "allocation": {
    "claude-001": "architect",
    "kimi-002": "developer",
    "opencode-003": "pm"
  }
}

8.3 解释角色分配

POST /api/roles/explain
Content-Type: application/json

{
  "task": "修复bug",
  "agents": ["claude-001", "kimi-002"]
}

---

9. 系统接口

9.1 健康检查

GET /health

响应示例:

{
  "status": "healthy",
  "version": "0.1.0",
  "services": {
    "api": "ok",
    "storage": "ok"
  }
}

---

错误处理

所有 API 错误返回统一格式:

{
  "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

---

测试验证

后端所有服务已通过自动化测试:

cd backend
python test_all_services.py

测试结果: 9/9 通过 ✅