# 租户用户端 - 完整接口文档

> **版本**: v2.0.0  
> **更新时间**: 2026-01-08  
> **说明**: 本文档基于后端代码完整梳理，包含所有用户端可用接口的详细定义

---

## 目录

1. [接口总览](#接口总览)
2. [认证模块](#认证模块)
3. [仪表板模块](#仪表板模块)
4. [服务网关模块](#服务网关模块)
5. [自定义Agent配额模块](#自定义agent配额模块)
6. [数据与工具模块](#数据与工具模块)
7. [代理工厂模块](#代理工厂模块)
8. [平台Agent模块](#平台agent模块)
9. [自定义Agent模块](#自定义agent模块)
10. [编排中心模块](#编排中心模块)
11. [模型使用模块](#模型使用模块)
12. [计费与资源模块](#计费与资源模块)
13. [Agent计费统计模块](#agent计费统计模块)
14. [监控模块](#监控模块)
15. [通用响应格式](#通用响应格式)
16. [错误码说明](#错误码说明)

---

## 接口总览

### 接口统计

| 模块 | 接口数量 | 说明 |
|------|----------|------|
| 认证模块 | 6 | 登录、登出、刷新Token、修改密码、API密钥管理 |
| 仪表板模块 | 2 | 用户统计、Agent活动 |
| 服务网关模块 | 4 | 网关选择、API创建、API列表、监控数据 |
| 自定义Agent配额模块 | 1 | 配额查询 |
| 数据与工具模块 | 2 | 工具生成、数据模板创建 |
| 代理工厂模块 | 2 | 平台Agent列表、Agent部署 |
| 平台Agent模块 | 6 | 可用Agent、使用Agent、停止Agent、实例列表等 |
| 自定义Agent模块 | 7 | 模板列表、创建、删除、扩缩容、日志、重启、列表 |
| 编排中心模块 | 4 | 工作流创建、列表、运行、删除 |
| 模型使用模块 | 2 | 可用模型、使用统计 |
| 计费与资源模块 | 3 | 余额查询、充值、历史记录 |
| Agent计费统计模块 | 2 | 统计、历史记录 |
| 监控模块 | 5 | 系统指标、服务统计、趋势、告警、仪表盘 |
| **总计** | **46** | |

### 基础信息

- **基础URL**: `https://api.taiji-ai.com` 或 `http://localhost:8002`
- **认证方式**: Bearer Token (JWT)
- **请求头**: `Authorization: Bearer {token}`
- **内容类型**: `application/json`

---

## 认证模块

### 1. 用户登录

**接口**: `POST /api/auth/login`

**代码位置**: [`auth.py:42`](../services/mcp-server/app/routes/auth.py:42)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 用户邮箱 |
| password | string | 是 | 用户密码 |
| role | string | 是 | 角色类型：`user`(租户用户), `channel`(渠道管理员), `billing_admin`, `operations_admin`, `admin`, `super_admin`, `provider` |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "user",
      "channelId": "660e8400-e29b-41d4-a716-446655440001"
    }
  }
}
```

**错误码**: 401(邮箱或密码错误), 403(账户已被禁用/权限不足)

---

### 2. 用户登出

**接口**: `POST /api/auth/logout`

**代码位置**: [`auth.py:173`](../services/mcp-server/app/routes/auth.py:173)

**请求头**: `Authorization: Bearer {token}`

**响应参数**:

```json
{
  "success": true,
  "message": "登出成功"
}
```

---

### 3. 刷新Token

**接口**: `POST /api/auth/refresh`

**代码位置**: [`auth.py:237`](../services/mcp-server/app/routes/auth.py:237)

**请求头**: `Authorization: Bearer {refreshToken}`

**响应参数**:

```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

---

### 4. 修改密码

**接口**: `PUT /api/auth/password`

**代码位置**: [`auth.py:275`](../services/mcp-server/app/routes/auth.py:275)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| old_password | string | 是 | 当前密码 |
| new_password | string | 是 | 新密码 |

**响应参数**:

```json
{
  "success": true,
  "message": "密码修改成功"
}
```

**错误码**: 400(旧密码错误), 404(用户不存在)

---

### 5. 获取API密钥信息

**接口**: `GET /api/auth/keys/info`

**代码位置**: [`auth.py:314`](../services/mcp-server/app/routes/auth.py:314)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "endpoint": "https://api.taiji-ai.com/v1",
    "apiKey": "sk-xxxx...xxxx",
    "createdAt": "2026-01-08T00:00:00Z",
    "lastUsed": "2026-01-08T12:00:00Z"
  }
}
```

---

### 6. 重新生成API密钥

**接口**: `POST /api/auth/keys/regenerate`

**代码位置**: [`auth.py:369`](../services/mcp-server/app/routes/auth.py:369)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "apiKey": "sk-abc123def456ghi789jkl012mno345pqr678stu901vwx",
    "message": "旧密钥已失效"
  }
}
```

---

## 仪表板模块

### 1. 获取用户仪表板统计

**接口**: `GET /api/user/dashboard/stats`

**代码位置**: [`user.py:105`](../services/mcp-server/app/routes/user.py:105)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "activeAgents": 5,
    "totalRequests": 1234,
    "euBalance": 500.50,
    "systemHealth": 98.5
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| activeAgents | integer | 活跃Agent数量（状态为"active"的Agent数） |
| totalRequests | integer | 总请求数（该用户的计费记录总数） |
| euBalance | float | EU余额（用户账户余额） |
| systemHealth | float | 系统健康度百分比（0-100） |

---

### 2. 获取Agent活动数据

**接口**: `GET /api/user/agents/activity`

**代码位置**: [`user.py:156`](../services/mcp-server/app/routes/user.py:156)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| period | string | 否 | 7d | 时间周期：`7d`, `30d`, `90d` |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "data": [
      {
        "date": "2026-01-01",
        "agentName": "my-agent",
        "requests": 100
      }
    ]
  }
}
```

---

## 服务网关模块

### 1. 选择网关类型

**接口**: `POST /api/user/gateway/select`

**代码位置**: [`user.py:198`](../services/mcp-server/app/routes/user.py:198)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| gatewayType | string | 是 | 网关类型：`MCP`, `A2A`, `API` |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "gatewayType": "MCP"
  },
  "message": "已选择 MCP 网关"
}
```

---

### 2. 创建网关API

**接口**: `POST /api/user/gateway/api/create`

**代码位置**: [`user.py:214`](../services/mcp-server/app/routes/user.py:214)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | API名称 |
| method | string | 是 | 上传方式：`json`(JSON内容), `url`(URL地址) |
| content | string | 是 | JSON内容或URL地址 |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-api"
  },
  "message": "API创建成功"
}
```

---

### 3. 获取网关API列表

**接口**: `GET /api/user/gateway/apis`

**代码位置**: [`user.py:242`](../services/mcp-server/app/routes/user.py:242)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "apis": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "my-api",
        "method": "json",
        "createdAt": "2026-01-08T00:00:00Z"
      }
    ]
  }
}
```

---

### 4. 获取网关监控数据

**接口**: `GET /api/user/gateway/monitoring`

**代码位置**: [`user.py:270`](../services/mcp-server/app/routes/user.py:270)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "uptime": 99.9,
    "requestsPerMinute": 10.5,
    "averageLatency": 150.0,
    "errorRate": 0.1
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| uptime | float | 服务可用率（百分比，基于过去1小时的成功率） |
| requestsPerMinute | float | 每分钟请求数（基于过去1小时的平均值） |
| averageLatency | float | 平均延迟（毫秒） |
| errorRate | float | 错误率（百分比） |

---

## 自定义Agent配额模块

### 1. 获取自定义Agent配额

**接口**: `GET /api/user/custom-agent-quota`

**代码位置**: [`user.py:342`](../services/mcp-server/app/routes/user.py:342)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "cpuQuota": 4.0,
    "memoryQuota": 8.0,
    "cpuUsed": 1.5,
    "memoryUsed": 3.0,
    "cpuRemaining": 2.5,
    "memoryRemaining": 5.0,
    "agentCount": 3,
    "hasQuota": true
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| cpuQuota | float | CPU配额上限（核心数） |
| memoryQuota | float | 内存配额上限（GB） |
| cpuUsed | float | 已使用CPU（核心数） |
| memoryUsed | float | 已使用内存（GB） |
| cpuRemaining | float | 剩余CPU（核心数） |
| memoryRemaining | float | 剩余内存（GB） |
| agentCount | integer | 已创建的自定义Agent数量 |
| hasQuota | boolean | 是否有配额 |

---

## 数据与工具模块

### 1. 生成工具（创建自定义Agent）

**接口**: `POST /api/user/tools/generate`

**代码位置**: [`user.py:405`](../services/mcp-server/app/routes/user.py:405)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 工具名称 |
| description | string | 是 | 工具描述 |
| frameworkTemplate | string | 是 | 框架模板：`MCP`, `A2A`, `API` |
| gateway | string | 是 | 服务网关：`MCP`, `A2A`, `API` |
| agentCount | integer | 是 | Agent个数 |
| cpu | float | 是 | CPU核数 |
| memory | float | 是 | 内存大小（GB） |
| maxScale | integer | 是 | 可扩展Agent数量 |
| model | string | 是 | 使用的模型名称 |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-tool",
    "cpu": 1.0,
    "memory": 2.0
  },
  "message": "工具生成成功"
}
```

**错误码**: 400(CPU配额不足/内存配额不足)

---

### 2. 创建数据模板

**接口**: `POST /api/user/data-templates/create`

**代码位置**: [`user.py:493`](../services/mcp-server/app/routes/user.py:493)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 模板名称 |
| type | string | 是 | 模板类型：`json_api`, `cloud_storage`, `database` |
| config | object | 是 | 配置信息 |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-template"
  },
  "message": "数据模板创建成功"
} 
```

---

## 代理工厂模块

### 1. 获取平台Agent列表

**接口**: `GET /api/user/agents/platform`

**代码位置**: [`user.py:523`](../services/mcp-server/app/routes/user.py:523)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "gpt-agent",
        "description": "GPT-4 Agent",
        "category": "通用",
        "cpu": 1.0,
        "memory": 2.0,
        "status": "available"
      }
    ]
  }
}
```

---

### 2. 部署Agent

**接口**: `POST /api/user/agents/deploy`

**代码位置**: [`user.py:554`](../services/mcp-server/app/routes/user.py:554)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | string | 是 | Agent ID（UUID格式） |
| instances | integer | 是 | 实例数量 |
| model | string | 是 | 使用的模型名称 |
| gateway | string | 是 | 服务网关：`MCP`, `A2A`, `API` |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "podName": "gpt-agent-550e8400",
    "namespace": "default",
    "status": "Running",
    "servicePort": 8080,
    "instances": 2,
    "model": "gpt-4",
    "gateway": "MCP"
  },
  "message": "Agent gpt-agent 部署成功"
}
```

**错误码**: 404(Agent不存在)

---

## 平台Agent模块

### 1. 获取可用的平台Agent列表

**接口**: `GET /api/user/platform-agents/available`

**代码位置**: [`user.py:1242`](../services/mcp-server/app/routes/user.py:1242)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "82a5346e-749a-4df3-861f-afff38097b92",
        "templateName": "code-assistant",
        "displayName": "Code Assistant",
        "description": "Platform Agent: code-assistant",
        "podQuota": 5,
        "podUsed": 2,
        "podRemaining": 3,
        "cpuLimit": "500m",
        "memoryLimit": "512Mi",
        "category": "platform",
        "allocatedAt": "2026-01-08T00:00:00Z"
      }
    ]
  }
}
```

---

### 2. 使用平台Agent

**接口**: `POST /api/user/platform-agents/use`

**代码位置**: [`user.py:1282`](../services/mcp-server/app/routes/user.py:1282)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentType | string | 是 | Agent类型（模板名称） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "instanceName": "code-assistant-550e8400-abc123",
    "namespace": "default",
    "status": "Running",
    "servicePort": 8080,
    "accessInfo": {
      "endpoints": {
        "http": "http://code-assistant-550e8400-abc123:8080"
      }
    },
    "quotaRemaining": 2
  },
  "message": "平台 Agent code-assistant 启动成功"
}
```

**错误码**: 400(Pod配额已用完), 403(没有使用该Agent的权限)

---

### 3. 停止平台Agent实例

**接口**: `DELETE /api/user/platform-agents/{instance_name}`

**代码位置**: [`user.py:1388`](../services/mcp-server/app/routes/user.py:1388)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| instance_name | string | Agent实例名称 |

**响应参数**:

```json
{
  "success": true,
  "message": "Agent 实例 code-assistant-550e8400-abc123 已停止"
}
```

---

### 4. 获取平台Agent实例列表

**接口**: `GET /api/user/platform-agents/instances`

**代码位置**: [`user.py:1459`](../services/mcp-server/app/routes/user.py:1459)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "instances": [
      {
        "instanceName": "code-assistant-550e8400-abc123",
        "agentType": "code-assistant",
        "status": "Running",
        "startTime": "2026-01-08T00:00:00Z",
        "runningSeconds": 3600
      }
    ]
  }
}
```

---

### 5. 查看平台Agent配额（platform_agent_quota路由）

**接口**: `GET /api/user/platform-agents`

**代码位置**: [`platform_agent_quota.py:919`](../services/mcp-server/app/routes/platform_agent_quota.py:919)

**响应参数**:

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "targetId": "660e8400-e29b-41d4-a716-446655440001",
    "targetType": "tenant",
    "templateName": "code-assistant",
    "podQuota": 5,
    "podUsed": 2,
    "allocatedAt": "2026-01-08T00:00:00Z"
  }
]
```

---

### 6. 查看平台Agent配额使用情况

**接口**: `GET /api/user/platform-agents/quota`

**代码位置**: [`platform_agent_quota.py:1071`](../services/mcp-server/app/routes/platform_agent_quota.py:1071)

**响应参数**:

```json
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "quotas": [
    {
      "templateName": "code-assistant",
      "podQuota": 5,
      "podUsed": 2,
      "podAvailable": 3,
      "usagePercent": 40.0
    }
  ],
  "totalQuota": 5,
  "totalUsed": 2
}
```

---

## 自定义Agent模块

### 1. 获取自定义Agent模板列表

**接口**: `GET /api/user/custom-agents/templates`

**代码位置**: [`user.py:1512`](../services/mcp-server/app/routes/user.py:1512)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "python-agent",
        "description": "Python Agent Template",
        "port": 8080
      }
    ]
  }
}
```

---

### 2. 创建自定义Agent

**接口**: `POST /api/user/custom-agents`

**代码位置**: [`user.py:1539`](../services/mcp-server/app/routes/user.py:1539)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| name | string | 是 | - | Agent名称 |
| template | string | 是 | - | 模板名称 |
| description | string | 否 | null | Agent描述 |
| cpuRequest | string | 否 | "100m" | CPU请求量（K8s格式） |
| cpuLimit | string | 否 | null | CPU限制量 |
| memoryRequest | string | 否 | "128Mi" | 内存请求量（K8s格式） |
| memoryLimit | string | 否 | null | 内存限制量 |
| endpoint | string | 否 | null | 用户终结点 |
| apiKey | string | 否 | null | 用户API密钥 |
| envConfig | object | 否 | {} | 环境变量配置 |
| model | string | 否 | null | 使用的模型名称（会自动注入LiteLLM环境变量） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "name": "my-custom-agent",
    "namespace": "default",
    "status": "Running",
    "servicePort": 8080,
    "accessInfo": {
      "endpoints": {
        "http": "http://my-custom-agent:8080"
      }
    },
    "modelInjected": true,
    "quotaRemaining": {
      "cpu": 2.5,
      "memory": 5.0
    }
  },
  "message": "自定义 Agent my-custom-agent 创建成功"
}
```

**错误码**: 400(CPU/内存配额不足), 403(没有自定义Agent配额/没有使用指定模型的权限)

---

### 3. 删除自定义Agent

**接口**: `DELETE /api/user/custom-agents/{name}`

**代码位置**: [`user.py:1715`](../services/mcp-server/app/routes/user.py:1715)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| name | string | Agent名称 |

**响应参数**:

```json
{
  "success": true,
  "message": "自定义 Agent my-custom-agent 已删除",
  "data": {
    "quotaReleased": {
      "cpu": 0.5,
      "memory": 1.0
    }
  }
}
```

**错误码**: 404(未找到Agent或该Agent不属于您)

---

### 4. 扩缩容自定义Agent

**接口**: `PUT /api/user/custom-agents/{name}/scale`

**代码位置**: [`user.py:1800`](../services/mcp-server/app/routes/user.py:1800)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| name | string | Agent名称 |

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| cpuRequest | string | 否 | 新的CPU请求量 |
| cpuLimit | string | 否 | 新的CPU限制量 |
| memoryRequest | string | 否 | 新的内存请求量 |
| memoryLimit | string | 否 | 新的内存限制量 |

**响应参数**:

```json
{
  "success": true,
  "message": "Agent my-custom-agent 扩缩容成功",
  "data": {
    "newCpu": "500m",
    "newMemory": "512Mi",
    "quotaRemaining": {
      "cpu": 2.0,
      "memory": 4.5
    }
  }
}
```

**错误码**: 400(CPU/内存配额不足), 404(未找到Agent)

---

### 5. 获取自定义Agent列表

**接口**: `GET /api/user/custom-agents`

**代码位置**: [`user.py:1927`](../services/mcp-server/app/routes/user.py:1927)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "agents": [
      {
        "name": "my-custom-agent",
        "template": "python-agent",
        "status": "Running",
        "cpu": "500m",
        "memory": "512Mi",
        "startTime": "2026-01-08T00:00:00Z",
        "runningSeconds": 3600
      }
    ]
  }
}
```

---

### 6. 获取自定义Agent日志

**接口**: `GET /api/user/custom-agents/{name}/logs`

**代码位置**: [`user.py:1984`](../services/mcp-server/app/routes/user.py:1984)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| name | string | Agent名称 |

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| tail_lines | integer | 否 | 100 | 返回的日志行数（1-1000） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "logs": "2026-01-08 00:00:00 INFO Starting agent...\n2026-01-08 00:00:01 INFO Agent started successfully"
  }
}
```

**错误码**: 404(未找到Agent或该Agent不属于您)

---

### 7. 重启自定义Agent

**接口**: `POST /api/user/custom-agents/{name}/restart`

**代码位置**: [`user.py:2032`](../services/mcp-server/app/routes/user.py:2032)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| name | string | Agent名称 |

**响应参数**:

```json
{
  "success": true,
  "message": "Agent my-custom-agent 正在重启"
}
```

**错误码**: 404(未找到Agent或该Agent不属于您)

---

## 编排中心模块

### 1. 创建工作流

**接口**: `POST /api/user/workflows/create`

**代码位置**: [`user.py:673`](../services/mcp-server/app/routes/user.py:673)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 工作流名称 |
| description | string | 是 | 工作流描述 |
| gateway | string | 是 | 服务网关：`MCP`, `A2A`, `API` |
| nodes | array | 是 | 节点列表（最多3个） |
| nodes[].agentId | string | 是 | Agent ID |
| nodes[].agentType | string | 是 | Agent类型：`platform`, `custom` |
| nodes[].agentName | string | 是 | Agent名称 |
| nodes[].order | integer | 是 | 节点顺序（从1开始） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-workflow"
  },
  "message": "工作流创建成功"
}
```

**错误码**: 400(工作流最多支持3个Agent节点)

---

### 2. 获取工作流列表

**接口**: `GET /api/user/workflows`

**代码位置**: [`user.py:713`](../services/mcp-server/app/routes/user.py:713)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "my-workflow",
        "description": "My workflow description",
        "gateway": "MCP",
        "nodes": [
          {
            "agentId": "660e8400-e29b-41d4-a716-446655440001",
            "agentType": "platform",
            "agentName": "code-assistant",
            "order": 1
          }
        ],
        "status": "active",
        "createdAt": "2026-01-08T00:00:00Z"
      }
    ],
    "count": 1
  }
}
```

---

### 3. 运行工作流

**接口**: `POST /api/user/workflows/{workflow_id}/run`

**代码位置**: [`user.py:747`](../services/mcp-server/app/routes/user.py:747)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| workflow_id | string | 工作流ID（UUID格式） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "executionId": "770e8400-e29b-41d4-a716-446655440002",
    "workflowId": "550e8400-e29b-41d4-a716-446655440000",
    "workflowName": "my-workflow",
    "status": "completed",
    "startedAt": "2026-01-08T00:00:00Z",
    "completedAt": "2026-01-08T00:00:05Z",
    "nodeResults": [
      {
        "nodeId": "660e8400-e29b-41d4-a716-446655440001",
        "agentName": "code-assistant",
        "order": 1,
        "status": "completed",
        "startedAt": "2026-01-08T00:00:00Z",
        "completedAt": "2026-01-08T00:00:05Z",
        "output": {
          "message": "Node 1 executed successfully"
        }
      }
    ],
    "totalNodes": 1,
    "completedNodes": 1
  },
  "message": "工作流 my-workflow 执行完成"
}
```

**错误码**: 400(无效的工作流ID格式), 404(工作流不存在或不属于您)

---

### 4. 删除工作流

**接口**: `DELETE /api/user/workflows/{workflow_id}`

**代码位置**: [`user.py:823`](../services/mcp-server/app/routes/user.py:823)

**路径参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| workflow_id | string | 工作流ID（UUID格式） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "deleted": true,
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "工作流已删除"
}
```

**错误码**: 400(无效的工作流ID格式), 404(工作流不存在或不属于您)

---

## 模型使用模块

### 1. 获取可用模型列表

**接口**: `GET /api/user/models/available`

**代码位置**: [`user.py:871`](../services/mcp-server/app/routes/user.py:871)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "models": [
      {
        "modelName": "gpt-4",
        "rpmLimit": 60,
        "tpmLimit": 10000,
        "maxBudget": 100.0,
        "budgetDuration": "monthly",
        "status": "active",
        "allocatedAt": "2026-01-08T00:00:00Z"
      }
    ],
    "count": 1
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| modelName | string | 模型名称 |
| rpmLimit | integer | 每分钟请求数限制 |
| tpmLimit | integer | 每分钟Token数限制 |
| maxBudget | float | 最大预算 |
| budgetDuration | string | 预算周期 |
| status | string | 状态 |
| allocatedAt | string | 分配时间 |

---

### 2. 获取模型使用统计

**接口**: `GET /api/user/models/usage/stats`

**代码位置**: [`user.py:915`](../services/mcp-server/app/routes/user.py:915)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| model_name | string | 否 | 模型名称，不传则返回所有模型 |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "models": [
      {
        "modelName": "gpt-4",
        "requests": 100,
        "totalTokens": 50000,
        "spend": 5.0,
        "rpmLimit": 60,
        "tpmLimit": 10000,
        "maxBudget": 100.0,
        "budgetRemaining": 95.0
      }
    ],
    "totalSpend": 5.0
  }
}
```

---

## 计费与资源模块

### 1. 获取余额信息

**接口**: `GET /api/user/billing/balance`

**代码位置**: [`user.py:1020`](../services/mcp-server/app/routes/user.py:1020)

**响应参数**:

```json
{
  "success": true,
  "data": {
    "balance": 500.50,
    "monthlySpent": 100.25,
    "currency": "CNY"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| balance | float | 当前余额 |
| monthlySpent | float | 本月消费 |
| currency | string | 货币类型 |

---

### 2. 充值余额

**接口**: `POST /api/user/billing/recharge`

**代码位置**: [`user.py:1059`](../services/mcp-server/app/routes/user.py:1059)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| amount | float | 是 | 充值金额 |
| paymentMethod | string | 是 | 支付方式：`alipay`, `wechat`, `card` |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "orderId": "ORD20260108120000abc12345",
    "amount": 100.0,
    "paymentUrl": "https://pay.taiji-ai.com/checkout?order_id=ORD20260108120000abc12345",
    "status": "pending"
  }
}
```

---

### 3. 获取计费历史

**接口**: `GET /api/user/billing/history`

**代码位置**: [`user.py:1150`](../services/mcp-server/app/routes/user.py:1150)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| startTime | string | 是 | - | 开始时间（YYYY-MM-DD 或 ISO 8601格式） |
| endTime | string | 是 | - | 结束时间 |
| customerName | string | 否 | null | 客户名称筛选 |
| minCalls | integer | 否 | null | 最小调用次数 |
| maxCalls | integer | 否 | null | 最大调用次数 |
| export | string | 否 | null | 导出格式：`excel`, `csv`, `pdf` |
| page | integer | 否 | 1 | 页码（从1开始） |
| pageSize | integer | 否 | 20 | 每页数量（1-100） |

**响应参数（查询模式）**:

```json
{
  "success": true,
  "data": {
    "total": 100,
    "records": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "timestamp": "2026-01-08T00:00:00Z",
        "agentName": "my-agent",
        "duration": 60,
        "eu": 6,
        "cost": 0.6
      }
    ]
  }
}
```

**响应参数（导出模式）**:

```json
{
  "success": true,
  "data": {
    "fileUrl": "https://exports.taiji-ai.com/user123/excel/billing_20260108120000.excel",
    "format": "excel",
    "expiresAt": "2026-01-09T12:00:00Z"
  }
}
```

---

## Agent计费统计模块

### 1. 获取Agent计费统计

**接口**: `GET /api/user/agent-billing/stats`

**代码位置**: [`user.py:2081`](../services/mcp-server/app/routes/user.py:2081)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| period | string | 否 | 30d | 时间周期：`7d`, `30d`, `90d` |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "totalCost": 150.0,
    "totalDurationSeconds": 36000,
    "totalRequests": 500,
    "byAgentType": {
      "platform": {
        "cost": 100.0,
        "durationSeconds": 24000,
        "requests": 300
      },
      "custom": {
        "cost": 50.0,
        "durationSeconds": 12000,
        "requests": 200
      }
    },
    "byTemplate": {
      "code-assistant": {
        "cost": 80.0,
        "durationSeconds": 20000,
        "requests": 250
      }
    }
  }
}
```

---

### 2. 获取Agent计费历史

**接口**: `GET /api/user/agent-billing/history`

**代码位置**: [`user.py:2110`](../services/mcp-server/app/routes/user.py:2110)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| startTime | string | 是 | - | 开始时间 |
| endTime | string | 是 | - | 结束时间 |
| agentType | string | 否 | null | Agent类型：`platform`, `custom` |
| page | integer | 否 | 1 | 页码 |
| pageSize | integer | 否 | 20 | 每页数量（1-100） |

**响应参数**:

```json
{
  "success": true,
  "data": {
    "total": 50,
    "records": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "agentName": "my-agent",
        "agentType": "platform",
        "templateName": "code-assistant",
        "startTime": "2026-01-08T00:00:00Z",
        "endTime": "2026-01-08T01:00:00Z",
        "durationSeconds": 3600,
        "euConsumed": 360,
        "cpuUsed": "500m",
        "memoryUsed": "512Mi",
        "cost": 3.6
      }
    ]
  }
}
```

---

## 监控模块

### 1. 获取系统指标

**接口**: `GET /api/v1/monitoring/metrics`

**代码位置**: [`monitoring.py:18`](../services/mcp-server/app/routes/monitoring.py:18)

**响应参数**:

```json
{
  "cpu_percent": 45.5,
  "memory_percent": 60.2,
  "disk_percent": 70.0,
  "network_io": {
    "bytes_sent": 1000000,
    "bytes_recv": 2000000
  }
}
```

---

### 2. 获取服务统计

**接口**: `GET /api/v1/monitoring/stats`

**代码位置**: [`monitoring.py:28`](../services/mcp-server/app/routes/monitoring.py:28)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| service | string | 否 | all | 服务名称或"all" |

**响应参数**:

```json
{
  "service": "all",
  "stats": {
    "total_requests": 10000,
    "success_rate": 99.5,
    "average_latency_ms": 150
  }
}
```

---

### 3. 获取性能趋势

**接口**: `GET /api/v1/monitoring/trends`

**代码位置**: [`monitoring.py:38`](../services/mcp-server/app/routes/monitoring.py:38)

**请求参数**:

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| metric | string | 否 | executions | 指标类型：`executions`, `eu_consumption` |
| period | string | 否 | 24h | 时间周期：`24h`, `7d`, `30d` |
| interval | string | 否 | 1h | 时间间隔：`1h`, `6h`, `1d` |

**响应参数**:

```json
{
  "metric": "executions",
  "period": "24h",
  "interval": "1h",
  "data": [
    {
      "timestamp": "2026-01-08T00:00:00Z",
      "value": 100
    },
    {
      "timestamp": "2026-01-08T01:00:00Z",
      "value": 120
    }
  ]
}
```

---

### 4. 获取系统告警

**接口**: `GET /api/v1/monitoring/alerts`

**代码位置**: [`monitoring.py:50`](../services/mcp-server/app/routes/monitoring.py:50)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| severity | string | 否 | 严重程度过滤：`critical`, `warning`, `info` |

**响应参数**:

```json
{
  "timestamp": "2026-01-08T12:00:00Z",
  "alerts": [
    {
      "id": "alert-001",
      "severity": "warning",
      "message": "CPU usage above 80%",
      "timestamp": "2026-01-08T11:55:00Z"
    }
  ],
  "count": 1
}
```

---

### 5. 获取监控仪表盘

**接口**: `GET /api/v1/monitoring/dashboard`

**代码位置**: [`monitoring.py:65`](../services/mcp-server/app/routes/monitoring.py:65)

**响应参数（已登录用户）**:

```json
{
  "timestamp": "2026-01-08T12:00:00Z",
  "health": {
    "score": 98,
    "services": {
      "mcp_server": {"status": "healthy", "latency_ms": 50},
      "data_ingestion": {"status": "healthy", "latency_ms": 30},
      "api_gateway": {"status": "healthy", "latency_ms": 20}
    }
  },
  "euConsumption24h": {
    "total": 1000,
    "hourly": [40, 45, 50, 42]
  },
  "modelUsage": {
    "gpt-4": {"requests": 500, "tokens": 250000},
    "claude-3": {"requests": 300, "tokens": 150000}
  },
  "weeklyApiCalls": {
    "2026-01-01": {"success": 1000, "failed": 10},
    "2026-01-02": {"success": 1200, "failed": 15}
  },
  "alerts": {
    "items": [],
    "count": 0,
    "critical_count": 0,
    "warning_count": 0
  }
}
```

---

## 通用响应格式

### 成功响应

```json
{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}
```

### 错误响应

```json
{
  "detail": "错误描述"
}
```

或

```json
{
  "detail": {
    "error": "error_code",
    "message": "错误描述",
    "detail": "详细信息"
  }
}
```

---

## 错误码说明

| HTTP状态码 | 说明 |
|------------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未认证或认证失败 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 500 | 服务器内部错误 |

### 常见业务错误

| 错误码 | 说明 |
|--------|------|
| quota_exceeded | 配额超出限制 |
| agent_not_found | Agent不存在 |
| workflow_not_found | 工作流不存在 |
| invalid_id_format | 无效的ID格式 |
| deployment_failed | 部署失败 |
| agent_start_failed | Agent启动失败 |
| agent_stop_failed | Agent停止失败 |
| create_agent_failed | 创建Agent失败 |
| delete_agent_failed | 删除Agent失败 |
| scale_agent_failed | 扩缩容失败 |
| get_logs_failed | 获取日志失败 |
| restart_failed | 重启失败 |
| fetch_templates_failed | 获取模板失败 |
| pod_creation_failed | Pod创建失败 |

---

## 接口路径快速索引

### 认证模块 `/api/auth`
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 用户登录 |
| POST | `/api/auth/logout` | 用户登出 |
| POST | `/api/auth/refresh` | 刷新Token |
| PUT | `/api/auth/password` | 修改密码 |
| GET | `/api/auth/keys/info` | 获取API密钥信息 |
| POST | `/api/auth/keys/regenerate` | 重新生成API密钥 |

### 用户模块 `/api/user`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/user/dashboard/stats` | 仪表板统计 |
| GET | `/api/user/agents/activity` | Agent活动数据 |
| POST | `/api/user/gateway/select` | 选择网关类型 |
| POST | `/api/user/gateway/api/create` | 创建网关API |
| GET | `/api/user/gateway/apis` | 网关API列表 |
| GET | `/api/user/gateway/monitoring` | 网关监控数据 |
| GET | `/api/user/custom-agent-quota` | 自定义Agent配额 |
| POST | `/api/user/tools/generate` | 生成工具 |
| POST | `/api/user/data-templates/create` | 创建数据模板 |
| GET | `/api/user/agents/platform` | 平台Agent列表 |
| POST | `/api/user/agents/deploy` | 部署Agent |
| GET | `/api/user/platform-agents/available` | 可用平台Agent |
| POST | `/api/user/platform-agents/use` | 使用平台Agent |
| DELETE | `/api/user/platform-agents/{instance_name}` | 停止平台Agent |
| GET | `/api/user/platform-agents/instances` | 平台Agent实例列表 |
| GET | `/api/user/platform-agents` | 平台Agent配额 |
| GET | `/api/user/platform-agents/quota` | 配额使用情况 |
| GET | `/api/user/custom-agents/templates` | 自定义Agent模板 |
| POST | `/api/user/custom-agents` | 创建自定义Agent |
| DELETE | `/api/user/custom-agents/{name}` | 删除自定义Agent |
| PUT | `/api/user/custom-agents/{name}/scale` | 扩缩容自定义Agent |
| GET | `/api/user/custom-agents` | 自定义Agent列表 |
| GET | `/api/user/custom-agents/{name}/logs` | 自定义Agent日志 |
| POST | `/api/user/custom-agents/{name}/restart` | 重启自定义Agent |
| POST | `/api/user/workflows/create` | 创建工作流 |
| GET | `/api/user/workflows` | 工作流列表 |
| POST | `/api/user/workflows/{id}/run` | 运行工作流 |
| DELETE | `/api/user/workflows/{id}` | 删除工作流 |
| GET | `/api/user/models/available` | 可用模型列表 |
| GET | `/api/user/models/usage/stats` | 模型使用统计 |
| GET | `/api/user/billing/balance` | 余额信息 |
| POST | `/api/user/billing/recharge` | 充值余额 |
| GET | `/api/user/billing/history` | 计费历史 |
| GET | `/api/user/agent-billing/stats` | Agent计费统计 |
| GET | `/api/user/agent-billing/history` | Agent计费历史 |

### 监控模块 `/api/v1/monitoring`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/monitoring/metrics` | 系统指标 |
| GET | `/api/v1/monitoring/stats` | 服务统计 |
| GET | `/api/v1/monitoring/trends` | 性能趋势 |
| GET | `/api/v1/monitoring/alerts` | 系统告警 |
| GET | `/api/v1/monitoring/dashboard` | 监控仪表盘 |

---

## 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| v1.0.0 | 2026-01-08 | 初始版本 |
| v1.1.0 | 2026-01-08 | 添加请求参数和响应参数详细说明 |
| v2.0.0 | 2026-01-08 | 完整梳理所有用户端接口，包含46个接口的详细定义 |