@starlink-awaken/agentmesh 1.0.2 → 1.2.0

package/docs/api.md

@@ -1,566 +1,293 @@
-# Agent Gateway API 文档
+# API Reference
 
-## 概述
+Base URL: `http://127.0.0.1:3000`
 
-Agent Gateway 是一个多 Agent 调度网关，提供 REST API 用于任务提交、Agent 管理和共享空间操作。
+## Health & Status
 
-**基础 URL**: `http://localhost:3000`
+### `GET /health`
+Health check with agent status overview.
 
----
-
-## 认证
-
-当前版本无需认证。生产环境建议添加 API Key 或 JWT 认证。
-
----
-
-## 端点概览
-
-| 方法 | 路径 | 描述 |
-|------|------|------|
-| GET | `/health` | 健康检查 |
-| POST | `/tasks` | 提交任务 |
-| GET | `/tasks` | 获取所有任务 |
-| GET | `/tasks/:taskId` | 获取任务状态 |
-| POST | `/spaces` | 创建共享空间 |
-| GET | `/spaces/:spaceId` | 获取共享空间 |
-| GET | `/agents` | 获取 Agent 列表 |
-| POST | `/agents` | 注册 Agent |
-| GET | `/events` | Server-Sent Events 流 |
-| GET | `/ws-info` | WebSocket 信息 |
-| POST | `/broadcast` | 广播事件 |
-
----
-
-## 端点详情
-
-### 1. 健康检查
-
-检查网关状态和所有 Agent 的在线情况。
-
-**请求**
-```http
-GET /health
-```
-
-**响应**
+**Response:**
 ```json
 {
   "status": "ok",
-  "timestamp": 1708531200000,
+  "timestamp": 1778935574177,
   "agents": [
-    {
-      "id": "claude-code",
-      "name": "Claude Code",
-      "status": "online"
-    }
+    {"id": "claude-code", "name": "Claude Code", "status": "online"}
   ]
 }
 ```
 
----
-
-### 2. 提交任务
+### `GET /model-gateway/health`
+Model gateway health with provider availability and quota summary.
 
-向网关提交任务，自动路由到合适的 Agent 或指定的 Agent。
-
-**请求**
-```http
-POST /tasks
-Content-Type: application/json
-```
-
-**请求体**
+**Response:**
 ```json
 {
-  "source": "api",
-  "target": "gateway",
-  "correlation_id": "uuid-可选",
-  "payload": {
-    "task": "帮我写一个排序算法",
-    "options": {
-      "timeout": 300,
-      "stream": false
-    }
-  }
+  "status": "ok",
+  "timestamp": 1778935574177,
+  "providers_available": [
+    {"name": "deepseek", "summary": "Balance: ¥561.18"}
+  ],
+  "providers_unavailable": [
+    {"name": "codex", "summary": "Credits: 0"}
+  ]
 }
 ```
 
-**完整请求体 (AgentMessage)**
-```json
-{
-  "id": "uuid-可选-会自动生成",
-  "type": "request",
-  "source": "api",
-  "target": "gateway",
-  "correlation_id": "uuid-可选",
-  "timestamp": 1708531200000,
-  "payload": {
-    "task": "任务描述",
-    "context": {
-      "shared_space_id": "空间ID-可选"
-    },
-    "files": ["文件路径-可选"],
-    "options": {
-      "stream": false,
-      "timeout": 300
-    }
-  }
-}
-```
+### `GET /model-gateway/quota`
+Real-time quota data from codexbar. Cached for 60 seconds.
 
-**响应** (202 Accepted)
+**Response:**
 ```json
 {
-  "task_id": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "pending",
-  "message": "Task submitted successfully"
-}
-```
-
-**错误响应** (500)
-```json
-{
-  "error": {
-    "code": "TASK_FAILED",
-    "message": "具体错误信息"
+  "codex": {
+    "provider": "codex",
+    "available": false,
+    "usedPercent": 98,
+    "summary": "Credits: 0, Secondary: 98%"
+  },
+  "deepseek": {
+    "provider": "deepseek",
+    "available": true,
+    "balance": 561.18,
+    "summary": "Balance: ¥561.18"
+  },
+  "ollama": {
+    "provider": "ollama",
+    "available": true,
+    "summary": "Local - always available"
   }
 }
 ```
 
----
-
-### 3. 获取所有任务
-
-列出所有任务。
-
-**请求**
-```http
-GET /tasks
-```
-
-**响应**
-```json
-[
-  {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "status": "completed",
-    "assigned_agents": ["claude-code"],
-    "created_at": 1708531200000
-  }
-]
-```
-
----
-
-### 4. 获取任务状态
-
-查询特定任务的详细状态和结果。
-
-**请求**
-```http
-GET /tasks/:taskId
-```
-
-**路径参数**
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| taskId | string | 任务 ID |
+## Model Gateway
 
-**响应**
-```json
-{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "completed",
-  "assigned_agents": ["claude-code"],
-  "result": "任务执行结果",
-  "error": null,
-  "created_at": 1708531200000,
-  "updated_at": 1708531200100
-}
-```
+### `GET /v1/models`
+List available models across all configured providers.
 
-**错误响应** (404)
+**Response:**
 ```json
 {
-  "error": {
-    "code": "TASK_NOT_FOUND",
-    "message": "Task xxx not found"
-  }
+  "object": "list",
+  "data": [
+    {"id": "deepseek-chat", "object": "model", "owned_by": "deepseek"},
+    {"id": "deepseek-v4-pro", "object": "model", "owned_by": "deepseek"},
+    {"id": "gpt-5.1", "object": "model", "owned_by": "openai"},
+    {"id": "o4-mini", "object": "model", "owned_by": "openai"},
+    {"id": "qwen3:14b", "object": "model", "owned_by": "ollama"}
+  ]
 }
 ```
 
----
-
-### 5. 创建共享空间
-
-创建一个用于多 Agent 协作的共享上下文空间。
-
-**请求**
-```http
-POST /spaces
-Content-Type: application/json
-```
+### `POST /v1/chat/completions`
+Standard OpenAI-compatible chat completions. Supports streaming (SSE).
 
-**请求体**
+**Request:**
 ```json
 {
-  "metadata": {
-    "name": "项目A开发",
-    "description": "多人协作项目"
-  }
+  "model": "deepseek-chat",
+  "messages": [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Hello!"}
+  ],
+  "stream": false,
+  "temperature": 0.7,
+  "max_tokens": 1024,
+  "tools": []
 }
 ```
 
-**响应** (201 Created)
+**Response (non-streaming):**
 ```json
 {
-  "space_id": "space-550e8400-e29b-41d4-a716-446655440000"
+  "id": "chatcmpl-xxx",
+  "object": "chat.completion",
+  "model": "deepseek-chat",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "Hello! How can I help you today?"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 20,
+    "completion_tokens": 10,
+    "total_tokens": 30
+  }
 }
 ```
 
----
+**Streaming:** Returns `text/event-stream` with SSE chunks.
 
-### 6. 获取共享空间
+### `POST /v1/responses`
+Codex Desktop Responses API adapter. Converts between Responses API and Chat Completions.
 
-获取共享空间的元数据。
-
-**请求**
-```http
-GET /spaces/:spaceId
-```
-
-**路径参数**
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| spaceId | string | 空间 ID |
-
-**响应**
+**Request:**
 ```json
 {
-  "shared_space_id": "space-550e8400-e29b-41d4-a716-446655440000",
-  "message_count": 5,
-  "artifact_count": 3,
-  "metadata": {
-    "name": "项目A开发"
-  },
-  "created_at": 1708531200000,
-  "updated_at": 1708531200500
+  "model": "deepseek-v4-pro",
+  "input": [
+    {"role": "system", "content": "You are a coding assistant."},
+    {"role": "user", "content": "Write a sorting function"}
+  ],
+  "instructions": "Be concise.",
+  "stream": false,
+  "tools": []
 }
 ```
 
-**错误响应** (404)
+**Response:**
 ```json
 {
-  "error": {
-    "code": "SPACE_NOT_FOUND",
-    "message": "Shared space xxx not found"
+  "id": "resp_xxx",
+  "object": "response",
+  "model": "deepseek-v4-pro",
+  "output": [
+    {
+      "type": "message",
+      "role": "assistant",
+      "content": [
+        {
+          "type": "output_text",
+          "text": "Here is a sorting function...\n\n```python\ndef sort(arr):...\n```"
+        }
+      ]
+    }
+  ],
+  "usage": {
+    "input_tokens": 30,
+    "output_tokens": 150,
+    "total_tokens": 180
   }
 }
 ```
 
----
+**Input Mapping:**
+- `input[].role` → `messages[].role`
+- `input[].content` (text/list) → `messages[].content` (string)
+- `input[].type: "message"` → message entry
+- `instructions` → prepended system message
 
-### 7. 获取 Agent 列表
+**Output Mapping:**
+- Chat `choices[0].message.content` → Responses `output[].content[].text`
+- Chat `choices[0].message.tool_calls` → Responses `output[].type: "function_call"`
 
-列出所有已注册的 Agent。
+## Agent Management
 
-**请求**
-```http
-GET /agents
-```
+### `GET /agents`
+List all registered agents.
 
-**响应**
+**Response:**
 ```json
 [
   {
     "id": "claude-code",
     "name": "Claude Code",
     "type": "claude-code",
-    "capabilities": [
-      "code-generation",
-      "code-review",
-      "debugging",
-      "refactoring",
-      "documentation",
-      "file-operations"
-    ],
+    "capabilities": ["code-generation", "code-review"],
     "status": "online",
-    "lastSeen": 1708531200000
+    "lastSeen": 1778935574177
   }
 ]
 ```
 
----
-
-### 8. 注册 Agent
+### `POST /agents`
+Register a new agent.
 
-动态注册一个新的 Agent。
-
-**请求**
-```http
-POST /agents
-Content-Type: application/json
-```
-
-**请求体**
+**Request:**
 ```json
 {
   "id": "my-agent",
   "name": "My Custom Agent",
-  "type": "http",
-  "capabilities": ["code-generation", "text-generation"],
-  "endpoint": "http://localhost:8080"
-}
-```
-
-**响应** (201 Created)
-```json
-{
-  "id": "my-agent",
-  "status": "registered"
+  "type": "process",
+  "capabilities": ["code-generation"],
+  "endpoint": "http://127.0.0.1:8080"
 }
 ```
 
----
-
-### 9. Server-Sent Events (SSE)
+### `POST /tasks`
+Submit a task for agent execution.
 
-订阅实时任务事件和 Agent 状态更新。
-
-**请求**
-```http
-GET /events?taskId=xxx&spaceId=xxx
-```
-
-**查询参数**
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| taskId | string | 可选 - 订阅特定任务的事件 |
-| spaceId | string | 可选 - 订阅特定空间的事件 |
-
-**响应**
-```http
-HTTP/1.1 200 OK
-Content-Type: text/event-stream
-Cache-Control: no-cache
-Connection: keep-alive
-```
-
-**事件格式**
-```json
-data: {"type": "connected", "client_id": "xxx"}
-
-data: {"type": "task_status", "task": {...}}
-
-data: {"type": "welcome", "agents": [...]}
-
-data: {"type": "heartbeat", "timestamp": 1708531200000}
-
-data: {"type": "task.submitted", "task_id": "xxx", "timestamp": 1708531200000}
-
-data: {"type": "task.completed", "task_id": "xxx", "result": "xxx", "timestamp": 1708531200000}
-```
-
----
-
-### 10. 广播事件
-
-向所有连接的客户端广播事件。
-
-**请求**
-```http
-POST /broadcast
-Content-Type: application/json
-```
-
-**请求体**
+**Request:**
 ```json
 {
-  "type": "custom_event",
-  "data": {
-    "message": "Hello all"
+  "type": "request",
+  "source": "api",
+  "target": "gateway",
+  "payload": {
+    "task": "Help me write a sorting algorithm",
+    "options": { "stream": false, "timeout": 300 }
   }
 }
 ```
 
-**响应**
+### `GET /tasks`
+List all tasks.
+
+### `GET /tasks/:taskId`
+Task status and result.
+
+**Response:**
 ```json
 {
-  "delivered": true,
-  "client_count": 5
+  "id": "task-xxx",
+  "status": "completed",
+  "assigned_agents": ["claude-code"],
+  "result": "...",
+  "created_at": 1778935574177,
+  "updated_at": 1778935580000
 }
 ```
 
----
-
-## 数据类型
-
-### AgentMessage
-
-```typescript
-interface AgentMessage {
-  // 基础字段
-  id: string;
-  type: 'request' | 'response' | 'event' | 'stream' | 'stream_end';
-  source: string;
-  target: string;
-  correlation_id: string;
-  timestamp: number;
-
-  // 请求内容
-  payload?: {
-    task?: string;
-    context?: {
-      shared_space_id: string;
-      history?: string[];
-      artifacts?: string[];
-    };
-    files?: string[];
-    options?: {
-      stream?: boolean;
-      timeout?: number;
-    };
-  };
-
-  // 事件驱动
-  event_type?: string;
-  event_data?: Record<string, unknown>;
-
-  // 响应
-  result?: unknown;
-  error?: {
-    code: string;
-    message: string;
-  };
-}
-```
+## Spaces
 
-### Task
-
-```typescript
-interface Task {
-  id: string;
-  status: 'pending' | 'assigned' | 'running' | 'completed' | 'failed';
-  message: AgentMessage;
-  assignedAgents: string[];
-  result?: unknown;
-  error?: {
-    code: string;
-    message: string;
-  };
-  createdAt: number;
-  updatedAt: number;
-}
-```
+### `POST /spaces`
+Create a shared context space.
 
-### Agent
-
-```typescript
-interface Agent {
-  id: string;
-  name: string;
-  type: string;
-  capabilities: string[];
-  status: 'online' | 'offline' | 'busy';
-  endpoint?: string;
-  lastSeen: number;
+**Request:**
+```json
+{
+  "metadata": { "name": "Project A", "createdBy": "cli" }
 }
 ```
 
----
-
-## 错误码
-
-| 错误码 | HTTP 状态码 | 描述 |
-|--------|-------------|------|
-| TASK_NOT_FOUND | 404 | 任务不存在 |
-| TASK_FAILED | 500 | 任务执行失败 |
-| SPACE_NOT_FOUND | 404 | 共享空间不存在 |
-| AGENT_NOT_FOUND | 404 | Agent 不存在 |
-| INVALID_REQUEST | 400 | 请求参数无效 |
-
----
-
-## 示例
-
-### cURL
-
-```bash
-# 健康检查
-curl http://localhost:3000/health
-
-# 提交任务
-curl -X POST http://localhost:3000/tasks \
-  -H "Content-Type: application/json" \
-  -d '{"payload": {"task": "帮我写一个排序算法"}}'
-
-# 查询任务状态
-curl http://localhost:3000/tasks/{task_id}
-
-# 获取 Agent 列表
-curl http://localhost:3000/agents
-
-# 创建共享空间
-curl -X POST http://localhost:3000/spaces \
-  -H "Content-Type: application/json" \
-  -d '{"metadata": {"name": "项目A"}}'
-```
-
-### JavaScript
+**Response:** `{ "space_id": "space-xxx" }`
 
-```javascript
-const baseUrl = 'http://localhost:3000';
+### `GET /spaces/:spaceId`
+Shared space details.
 
-// 提交任务
-async function submitTask(task) {
-  const response = await fetch(`${baseUrl}/tasks`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ payload: { task } })
-  });
-  return response.json();
-}
+## Error Format
 
-// 订阅任务事件
-function subscribeTask(taskId) {
-  const eventSource = new EventSource(`${baseUrl}/events?taskId=${taskId}`);
-  eventSource.onmessage = (event) => {
-    const data = JSON.parse(event.data);
-    console.log('Event:', data);
-  };
-  return eventSource;
+```json
+{
+  "error": {
+    "code": "PROVIDER_ERROR",
+    "message": "DeepSeek: insufficient_quota"
+  }
 }
 ```
 
----
-
-## CLI 命令
-
-安装 CLI 后可使用以下命令：
-
-```bash
-# 列出所有 Agent
-agent-gateway agents
-
-# 提交通用任务（自动路由）
-agent-gateway task 帮我写一个排序算法
+### Error Codes
 
-# 提交任务到指定 Agent
-agent-gateway to claude-code 帮我review这段代码
-
-# 创建共享空间
-agent-gateway space create-space
-
-# 列出所有任务
-agent-gateway tasks
-
-# 检查 Gateway 状态
-agent-gateway health
-```
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `TASK_FAILED` | 500 | Task processing failed |
+| `TASK_NOT_FOUND` | 404 | Task ID not found |
+| `SPACE_NOT_FOUND` | 404 | Space ID not found |
+| Provider errors | 502 | Upstream provider error |
+| No provider | 503 | All providers unavailable |
 
----
+## Routing
 
-## 许可
+The model router selects providers based on:
+1. Model name pattern matching
+2. Quota availability (via codexbar)
+3. API key presence
+4. Fallback chain priority
 
-MIT License
+See [Configuration Guide](./configuration.md) for routing rules.