Boss Command Center - API 规范¶

说明：本文档为系统预留接口边界定义。当前 Landing Page 阶段无实际后端依赖，接口为未来功能扩展预留。

1. 接口设计原则¶

RESTful 风格：资源路径清晰，HTTP 语义明确
统一响应格式：所有接口返回统一包装结构
版本控制：URL 路径包含版本号 /api/v1/...
认证预留：Header 携带 Authorization: Bearer <token>

2. 统一响应格式¶

成功响应¶

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

错误响应¶

{
  "code": 10001,
  "message": "参数错误：缺少必填字段 'command'",
  "data": null,
  "requestId": "req_xxx"
}

响应字段说明¶

字段	类型	说明
code	number	0 表示成功，非零为错误码
message	string	提示信息
data	any	业务数据
requestId	string	请求追踪 ID

3. 接口列表¶

3.1 意图识别¶

POST /api/v1/intent/parse

解析自然语言口令，提取意图和参数。

请求体:

{
  "command": "做个客户 PPT，主题是 OpenClaw，8 页",
  "context": {
    "userId": "user_xxx",
    "chatId": "chat_xxx"
  }
}

响应体:

{
  "code": 0,
  "message": "success",
  "data": {
    "intent": "create_ppt",
    "confidence": 0.95,
    "parameters": {
      "type": "ppt",
      "topic": "OpenClaw",
      "pages": 8,
      "format": "html"
    },
    "targetAgent": "marketing"
  }
}

错误码: - 10001: 缺少必填参数 - 10002: 意图识别失败（置信度 < 0.7） - 10003: 不支持的意图类型

3.2 任务创建¶

POST /api/v1/tasks

创建新任务并路由到对应 Agent。

请求体:

{
  "intent": "create_ppt",
  "parameters": { ... },
  "priority": "normal",
  "callback": "https://example.com/webhook"
}

响应体:

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "task_xxx",
    "status": "pending",
    "assignedAgent": "marketing",
    "createdAt": "2026-03-07T10:00:00Z"
  }
}

3.3 任务状态查询¶

GET /api/v1/tasks/{taskId}

查询任务执行状态和进度。

响应体:

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "task_xxx",
    "status": "running",
    "progress": 45,
    "assignedAgent": "marketing",
    "result": null,
    "createdAt": "2026-03-07T10:00:00Z",
    "updatedAt": "2026-03-07T10:05:00Z"
  }
}

状态枚举: - pending: 待处理 - running: 执行中 - completed: 已完成 - failed: 失败 - cancelled: 已取消

3.4 Agent 列表¶

GET /api/v1/agents

获取可用 Agent 列表。

响应体:

href="#__codelineno-7-1">{ "code": 0, "message": "success", "data": { "agents": [ { "id": "pm", "name": "产品经理", "capabilities": ["create_prd", "requirement_analysis"], "status": "available" }, { "id": "design", "name": "设计师", "capabilities": ["create_prototype", "design_review"], "status": "busy" } ] } }

3.5 健康检查¶

GET /api/v1/health

系统健康状态检查。

响应体:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "uptime": 3600,
    "services": {
      "database": "ok",
      "queue": "ok",
      "llm": "ok"
    }
  }
}

4. 数据结构定义¶

4.1 Task 对象¶

interface Task {
  taskId: string;
  intent: string;
  parameters: Record<string, any>;
  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
  progress: number; // 0-100
  assignedAgent: string;
  result?: {
    type: 'document' | 'file' | 'link';
    url: string;
    metadata: Record<string, any>;
  };
  createdAt: string;
  updatedAt: string;
}

4.2 Agent 对象¶

interface Agent {
  id: string;
  name: string;
  description: string;
  capabilities: string[];
  status: 'available' | 'busy' | 'offline';
  version: string;
}

4.3 Intent 类型枚举¶

type IntentType = 
  | 'create_ppt'
  | 'create_prd'
  | 'create_prototype'
  | 'create_page'
  | 'fix_bug'
  | 'code_review'
  | 'competitor_analysis'
  | 'query_progress';

5. 错误码定义¶

错误码	说明	HTTP 状态
0	成功	200
10001	参数错误	400
10002	意图识别失败	422
10003	不支持的意图	400
20001	任务不存在	404
20002	任务执行失败	500
30001	Agent 不可用	503
99999	系统错误	500

6. 预留接口（未来扩展）¶

6.1 WebSocket 实时推送¶

WS /ws/v1/tasks/{taskId}

用于实时推送任务进度更新。

6.2 批量任务创建¶

POST /api/v1/tasks/batch

支持一次提交多个任务。

6.3 任务历史查询¶

GET /api/v1/tasks?userId=xxx&page=1&size=20

分页查询用户任务历史。

API 规范 v1.0 | 2026-03-07