taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
b754af8ba184a4ae4c5bb3b5b52963ea6783b3f5
taiji-AI-PAD/Docs/项目文档/租户用户端-完整接口文档.md
T

37 KiB
Raw Blame History

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

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

目录

  1. 接口总览
  2. 认证模块
  3. 仪表板模块
  4. 服务网关模块
  5. 自定义Agent配额模块
  6. 数据与工具模块
  7. 代理工厂模块
  8. 平台Agent模块
  9. 自定义Agent模块
  10. 编排中心模块
  11. 模型使用模块
  12. 计费与资源模块
  13. 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

请求参数:

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

响应参数:

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

请求头: Authorization: Bearer {token}

响应参数:

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

3. 刷新Token

接口: POST /api/auth/refresh

代码位置: auth.py:237

请求头: Authorization: Bearer {refreshToken}

响应参数:

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

4. 修改密码

接口: PUT /api/auth/password

代码位置: auth.py:275

请求参数:

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

响应参数:

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

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

5. 获取API密钥信息

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

代码位置: auth.py:314

响应参数:

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

响应参数:

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

仪表板模块

1. 获取用户仪表板统计

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

代码位置: user.py:105

响应参数:

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

请求参数:

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

响应参数:

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

服务网关模块

1. 选择网关类型

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

代码位置: user.py:198

请求参数:

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

响应参数:

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

2. 创建网关API

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

代码位置: user.py:214

请求参数:

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

响应参数:

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

3. 获取网关API列表

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

代码位置: user.py:242

响应参数:

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

响应参数:

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

响应参数:

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

请求参数:

参数名 类型 必填 说明
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 是 使用的模型名称

响应参数:

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

请求参数:

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

响应参数:

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

代理工厂模块

1. 获取平台Agent列表

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

代码位置: user.py:523

响应参数:

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

请求参数:

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

响应参数:

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

响应参数:

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

请求参数:

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

响应参数:

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

路径参数:

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

响应参数:

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

4. 获取平台Agent实例列表

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

代码位置: user.py:1459

响应参数:

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

响应参数:

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

响应参数:

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

响应参数:

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

2. 创建自定义Agent

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

代码位置: 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环境变量）

响应参数:

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

路径参数:

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

响应参数:

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

路径参数:

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

请求参数:

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

响应参数:

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

响应参数:

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

路径参数:

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

请求参数:

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

响应参数:

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

路径参数:

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

响应参数:

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

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

编排中心模块

1. 创建工作流

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

代码位置: 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开始）

响应参数:

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

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

2. 获取工作流列表

接口: GET /api/user/workflows

代码位置: user.py:713

响应参数:

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

路径参数:

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

响应参数:

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

路径参数:

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

响应参数:

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

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

模型使用模块

1. 获取可用模型列表

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

代码位置: user.py:871

响应参数:

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

请求参数:

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

响应参数:

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

响应参数:

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

请求参数:

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

响应参数:

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

请求参数:

参数名 类型 必填 默认值 说明
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）

响应参数（查询模式）:

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

响应参数（导出模式）:

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

请求参数:

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

响应参数:

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

请求参数:

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

响应参数:

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

响应参数:

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

请求参数:

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

响应参数:

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

3. 获取性能趋势

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

代码位置: monitoring.py:38

请求参数:

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

响应参数:

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

请求参数:

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

响应参数:

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

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

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

通用响应格式

成功响应

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

错误响应

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

或

{
  "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个接口的详细定义
View Git Blame Copy Permalink