API 参考

VAI TEAM 提供完整的 RESTful API，支持所有控制台功能的程序化访问。

认证

JWT 认证

所有 API 请求需要携带 JWT Token：

http

Authorization: Bearer <your-jwt-token>

获取 Token

http

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

响应：

json

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

响应格式

标准响应

所有 API 返回统一格式：

json

{
  "code": 0,
  "data": { ... },
  "message": "success"
}

错误响应

json

{
  "code": 400,
  "data": null,
  "message": "Invalid request parameters"
}

分页响应

json

{
  "code": 0,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "size": 20,
    "pages": 5
  },
  "message": "success"
}

项目管理

创建项目

http

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

{
  "name": "待办事项管理",
  "project_type": "new",
  "description": "个人任务管理应用"
}

获取项目列表

http

GET /api/projects?page=1&size=20

响应：

json

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "proj_123",
        "name": "待办事项管理",
        "project_type": "new",
        "description": "个人任务管理应用",
        "current_stage": 0,
        "created_at": "2026-03-15T10:00:00Z",
        "updated_at": "2026-03-15T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

获取项目详情

http

GET /api/projects/{project_id}

更新项目

http

PUT /api/projects/{project_id}
Content-Type: application/json

{
  "name": "新项目名称",
  "description": "更新后的描述"
}

删除项目

http

DELETE /api/projects/{project_id}

阶段管理

获取阶段列表

http

GET /api/stages?project_id={project_id}

开始阶段

http

POST /api/stages/{stage_id}/start
Content-Type: application/json

{
  "input_data": {
    "requirements": "用户需求描述..."
  }
}

推进阶段

http

POST /api/stages/{stage_id}/advance
Content-Type: application/json

{
  "approved": true,
  "feedback": "审核通过，可以推进"
}

获取阶段文档

http

GET /api/stages/{stage_id}/document

任务管理

获取任务列表

http

GET /api/tasks?project_id={project_id}&status=pending

查询参数：

project_id: 项目 ID
status: 任务状态 (pending/assigned/running/reviewing/done/failed)
role: 角色筛选 (frontend/backend/tester/devops)
page: 页码
size: 页大小

获取任务详情

http

GET /api/tasks/{task_id}

响应：

json

{
  "code": 0,
  "data": {
    "id": "task_456",
    "title": "实现用户登录功能",
    "description": "创建登录页面和认证逻辑",
    "status": "reviewing",
    "role": "frontend",
    "assigned_agent": "agent_001",
    "created_at": "2026-03-15T14:00:00Z",
    "completed_at": "2026-03-15T15:30:00Z",
    "git_commits": [
      {
        "hash": "abc123",
        "message": "feat: 添加登录页面组件",
        "timestamp": "2026-03-15T15:30:00Z"
      }
    ]
  }
}

审核任务

http

POST /api/tasks/{task_id}/review
Content-Type: application/json

{
  "approved": true,
  "feedback": "代码质量良好，功能完整"
}

重新执行任务

http

POST /api/tasks/{task_id}/retry
Content-Type: application/json

{
  "additional_context": "请注意处理边界情况"
}

文档管理

获取文档列表

http

GET /api/documents?project_id={project_id}&type=stage

获取文档内容

http

GET /api/documents/{document_id}

更新文档

http

PUT /api/documents/{document_id}
Content-Type: application/json

{
  "content": "# 更新后的文档内容\n\n..."
}

Agent 管理

获取 Agent 列表

http

GET /api/agents

响应：

json

{
  "code": 0,
  "data": [
    {
      "id": "agent_001",
      "name": "Frontend Agent 01",
      "role": "frontend",
      "status": "online",
      "current_task": null,
      "workspace_path": "/workspace/agent_001",
      "last_heartbeat": "2026-03-15T16:00:00Z",
      "infra_node": "node_001"
    }
  ]
}

获取 Agent 详情

http

GET /api/agents/{agent_id}

重启 Agent

http

POST /api/agents/{agent_id}/restart

获取 Agent 日志

http

GET /api/agents/{agent_id}/logs?lines=100

模型管理

获取模型供应商

http

GET /api/providers

添加模型供应商

http

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

{
  "name": "DeepSeek",
  "base_url": "https://api.deepseek.com",
  "api_key": "sk-your-api-key"
}

测试模型连接

http

POST /api/providers/{provider_id}/test

获取角色模型配置

http

GET /api/models/role-assignments

更新角色模型配置

http

PUT /api/models/role-assignments
Content-Type: application/json

{
  "leader": "gpt-4o",
  "architect": "gpt-4o",
  "frontend": "deepseek-chat",
  "backend": "deepseek-chat"
}

项目备份

创建备份

http

POST /api/projects/{project_id}/backup
Content-Type: application/json

{
  "name": "v1.0-release",
  "description": "生产发布版本",
  "backup_mode": "metadata_only"
}

备份模式：

metadata_only: 仅备份项目数据，不包含源码
full_source: 完整备份，包含源码（需显式确认）

获取备份列表

http

GET /api/projects/{project_id}/backups

恢复备份

http

POST /api/projects/{project_id}/restore
Content-Type: application/json

{
  "backup_id": "backup_789",
  "restore_mode": "metadata_only"
}

异步任务状态

备份和恢复是异步操作，返回任务 ID：

http

GET /api/projects/{project_id}/backup/tasks/{task_id}

响应：

json

{
  "code": 0,
  "data": {
    "task_id": "gen_task_123",
    "status": "running",
    "progress": 65,
    "message": "正在备份 Agent 工作区...",
    "result": null,
    "created_at": "2026-03-15T16:00:00Z"
  }
}

实时进度流

http

GET /api/projects/{project_id}/backup/tasks/{task_id}/stream
Accept: text/event-stream

返回 Server-Sent Events 格式的实时进度。

Webhook 集成

配置 Webhook

http

POST /api/projects/{project_id}/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "stage.advanced"],
  "secret": "your-webhook-secret"
}

Webhook 事件

支持的事件类型：

事件	说明	数据
`task.created`	任务创建	任务信息
`task.assigned`	任务分配	任务 + Agent 信息
`task.completed`	任务完成	任务 + 执行结果
`task.failed`	任务失败	任务 + 错误信息
`stage.started`	阶段开始	阶段信息
`stage.advanced`	阶段推进	阶段 + 审核结果
`project.completed`	项目完成	项目信息

错误码

错误码	说明
0	成功
400	请求参数错误
401	未认证
403	权限不足
404	资源不存在
409	资源冲突
422	数据验证失败
500	服务器内部错误

速率限制

端点类型	限制
认证相关	10 次/分钟
读取操作	100 次/分钟
写入操作	50 次/分钟
文件上传	10 次/分钟

SDK 和工具

Python SDK

python

from vaiteam import Client

client = Client(
    base_url="http://localhost:8000",
    token="your-jwt-token"
)

# 创建项目
project = client.projects.create(
    name="我的项目",
    description="项目描述"
)

# 获取任务列表
tasks = client.tasks.list(project_id=project.id)

CLI 工具

bash

# 安装 CLI
pip install vaiteam-cli

# 配置认证
vaiteam auth login --url http://localhost:8000

# 创建项目
vaiteam projects create "我的项目" --type new

# 查看任务
vaiteam tasks list --project-id proj_123

在线文档

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

这些页面提供交互式的 API 文档，可以直接在浏览器中测试 API 调用。

API 参考 ​

认证 ​

JWT 认证 ​

获取 Token ​

响应格式 ​

标准响应 ​

错误响应 ​

分页响应 ​

项目管理 ​

创建项目 ​

获取项目列表 ​

获取项目详情 ​

更新项目 ​

删除项目 ​

阶段管理 ​

获取阶段列表 ​

开始阶段 ​

推进阶段 ​

获取阶段文档 ​

任务管理 ​

获取任务列表 ​

获取任务详情 ​

审核任务 ​

重新执行任务 ​

文档管理 ​

获取文档列表 ​

获取文档内容 ​

更新文档 ​

Agent 管理 ​

获取 Agent 列表 ​

获取 Agent 详情 ​

重启 Agent ​

获取 Agent 日志 ​

模型管理 ​

获取模型供应商 ​

添加模型供应商 ​

测试模型连接 ​

获取角色模型配置 ​

更新角色模型配置 ​

项目备份 ​

创建备份 ​

获取备份列表 ​

恢复备份 ​

异步任务状态 ​

实时进度流 ​

Webhook 集成 ​

配置 Webhook ​

Webhook 事件 ​

错误码 ​

速率限制 ​

SDK 和工具 ​

Python SDK ​

CLI 工具 ​

在线文档 ​

API 参考

认证

JWT 认证

获取 Token

响应格式

标准响应

错误响应

分页响应

项目管理

创建项目

获取项目列表

获取项目详情

更新项目

删除项目

阶段管理

获取阶段列表

开始阶段

推进阶段

获取阶段文档

任务管理

获取任务列表

获取任务详情

审核任务

重新执行任务

文档管理

获取文档列表

获取文档内容

更新文档

Agent 管理

获取 Agent 列表

获取 Agent 详情

重启 Agent

获取 Agent 日志

模型管理

获取模型供应商

添加模型供应商

测试模型连接

获取角色模型配置

更新角色模型配置

项目备份

创建备份

获取备份列表

恢复备份

异步任务状态

实时进度流

Webhook 集成

配置 Webhook

Webhook 事件

错误码

速率限制

SDK 和工具

Python SDK

CLI 工具

在线文档