221 lines
8.7 KiB
Markdown
221 lines
8.7 KiB
Markdown
# MCP Server 重构任务清单
|
||
|
||
## 概述
|
||
|
||
根据 [`plans/mcp-server-refactor-requirements.md`](plans/mcp-server-refactor-requirements.md) 需求文档，进行 MCP Server 的重构工作。
|
||
|
||
---
|
||
|
||
## 阶段一：数据模型和迁移
|
||
|
||
### 1.1 创建新的数据模型
|
||
|
||
- [x] **ResourceApplication 模型** - 资源申请审批表 ✅
|
||
- 文件：`services/mcp-server/models.py`
|
||
- 字段：channel_id, resource_type, template_name, requested_pod_quota, provider_id, requested_rpm, requested_tpm, requested_cpu_quota, requested_memory_quota, reason, status, approved_*, reviewed_by, review_reason, reviewed_at
|
||
|
||
- [x] **PlatformAgentQuota 模型** - 平台 Agent 配额表 ✅
|
||
- 文件：`services/mcp-server/models.py`
|
||
- 字段：target_id, target_type, template_name, pod_quota, pod_used, allocated_by, allocated_at
|
||
|
||
- [x] **AgentBillingRecord 模型** - Agent 计费记录表 ✅
|
||
- 文件：`services/mcp-server/models.py`
|
||
- 字段：user_id, channel_id, agent_name, agent_type, template_name, duration_seconds, cpu_seconds, memory_gb_seconds, request_count, cost, currency, period_start, period_end
|
||
|
||
### 1.2 创建数据库迁移脚本
|
||
|
||
- [x] 创建迁移文件：`services/mcp-server/migrations/006_add_agent_resource_management.sql` ✅
|
||
|
||
---
|
||
|
||
## 阶段二：申请审批功能
|
||
|
||
### 2.1 渠道查看可用资源 API
|
||
|
||
- [x] `GET /api/channel/available-platform-agents` - 查看所有可用平台 Agent ✅
|
||
- [x] `GET /api/channel/available-providers` - 查看所有可用模型供应商 ✅ (已有 /api/channel/providers)
|
||
|
||
### 2.2 渠道发起申请 API
|
||
|
||
- [x] `POST /api/channel/applications/platform-agents` - 申请平台 Agent ✅
|
||
- [x] `GET /api/channel/applications/platform-agents` - 查看自己的申请 ✅
|
||
- [x] `POST /api/channel/applications/providers` - 申请模型供应商 ✅ (已有 /api/channel/providers/apply)
|
||
- [x] `GET /api/channel/applications/providers` - 查看自己的申请 ✅ (已有 /api/channel/providers/applications)
|
||
- [x] `POST /api/channel/applications/custom-agent-quota` - 申请自定义 Agent 资源 ✅
|
||
- [x] `GET /api/channel/applications/custom-agent-quota` - 查看自己的申请 ✅
|
||
|
||
### 2.3 管理员审批 API
|
||
|
||
- [x] `GET /api/admin/applications/platform-agents` - 查看平台 Agent 申请列表 ✅
|
||
- [x] `PUT /api/admin/applications/platform-agents/{id}/review` - 审批平台 Agent 申请 ✅
|
||
- [x] `GET /api/admin/applications/providers` - 查看供应商申请列表 ✅ (已有 /api/admin/providers/applications)
|
||
- [x] `PUT /api/admin/applications/providers/{id}/review` - 审批供应商申请 ✅ (已有 /api/admin/providers/applications/{id}/review)
|
||
- [x] `GET /api/admin/applications/custom-agent-quota` - 查看资源申请列表 ✅
|
||
- [x] `PUT /api/admin/applications/custom-agent-quota/{id}/review` - 审批资源申请 ✅
|
||
|
||
---
|
||
|
||
## 阶段三：Agent Manager 客户端重构
|
||
|
||
### 3.1 重构 agent_manager_client.py
|
||
|
||
- [x] 添加 `list_platform_templates()` 方法 ✅
|
||
- [x] 添加 `list_custom_templates()` 方法 ✅
|
||
- [x] 添加 `create_platform_agent()` 方法 ✅
|
||
- [x] 添加 `create_custom_agent()` 方法 ✅
|
||
- [x] 添加 `update_custom_agent_env()` 方法 ✅
|
||
- [x] 添加 `scale_custom_agent()` 方法 ✅
|
||
- [x] 添加 `get_agent_logs()` 方法 ✅
|
||
- [x] 添加 `restart_agent()` 方法 ✅
|
||
- [x] 添加 `get_namespace_resources()` 方法 ✅
|
||
- [x] 添加 `get_user_resources()` 方法 ✅
|
||
- [x] 添加 `get_channel_resources()` 方法 ✅
|
||
|
||
---
|
||
|
||
## 阶段四：平台 Agent 管理功能
|
||
|
||
### 4.1 管理员功能
|
||
|
||
- [x] `GET /api/admin/platform-agents/templates` - 获取平台 Agent 模板列表 ✅
|
||
- [ ] `PUT /api/admin/platform-agents/templates/{name}/config` - 设置平台 Agent 配置
|
||
- [x] `GET /api/admin/platform-agents/allocations` - 查看平台 Agent 分配情况 ✅
|
||
- [x] `GET /api/admin/platform-agents/status` - 查看平台 Agent 运行状态 ✅
|
||
|
||
### 4.2 渠道功能
|
||
|
||
- [x] `GET /api/channel/platform-agents` - 查看渠道的平台 Agent 配额 ✅
|
||
- [x] `POST /api/channel/tenants/{id}/platform-agents` - 分配平台 Agent 给租户 ✅
|
||
- [x] `GET /api/channel/tenants/{id}/platform-agents/usage` - 查看租户使用情况 ✅
|
||
|
||
### 4.3 租户功能
|
||
|
||
- [x] `GET /api/user/platform-agents/available` - 查看可用的平台 Agent ✅
|
||
- [x] `POST /api/user/platform-agents/use` - 使用平台 Agent ✅
|
||
- [x] `DELETE /api/user/platform-agents/{instance_name}` - 停止平台 Agent ✅
|
||
- [x] `GET /api/user/platform-agents/instances` - 查看平台 Agent 实例列表 ✅
|
||
|
||
---
|
||
|
||
## 阶段五：自定义 Agent 管理功能
|
||
|
||
### 5.1 重构现有 API
|
||
|
||
- [x] 重构 `POST /api/user/custom-agents` - 增加配额检查 ✅
|
||
- [x] 重构 `DELETE /api/user/custom-agents/{name}` - 释放配额 ✅
|
||
|
||
### 5.2 新增 API
|
||
|
||
- [x] `GET /api/user/custom-agents/templates` - 查看可用模板 ✅
|
||
- [x] `PUT /api/user/custom-agents/{name}/scale` - 扩缩容 ✅
|
||
- [x] `GET /api/user/custom-agents` - 查看自定义 Agent 列表 ✅
|
||
- [x] `GET /api/user/custom-agents/{name}/logs` - 查看日志 ✅
|
||
- [x] `POST /api/user/custom-agents/{name}/restart` - 重启 Agent ✅
|
||
|
||
---
|
||
|
||
## 阶段六：计费集成
|
||
|
||
- [x] 实现 Agent 计费记录逻辑 ✅
|
||
- `calculate_agent_cost_by_resources()` - 自定义 Agent 资源计费
|
||
- `calculate_platform_agent_cost()` - 平台 Agent 固定计费
|
||
- `create_agent_billing_record()` - 创建计费记录
|
||
- `finalize_agent_billing()` - 结束计费
|
||
- [x] 集成计费到 Agent 使用流程 ✅
|
||
- 平台 Agent 使用时创建计费记录
|
||
- 平台 Agent 停止时结束计费
|
||
- 自定义 Agent 创建时创建计费记录
|
||
- 自定义 Agent 删除时结束计费
|
||
- [x] 实现计费统计 API ✅
|
||
- `GET /api/user/agent-billing/stats` - 用户 Agent 计费统计
|
||
- `GET /api/user/agent-billing/history` - 用户 Agent 计费历史
|
||
- `GET /api/channel/agent-billing/stats` - 渠道 Agent 计费统计
|
||
- `GET /api/channel/agent-billing/history` - 渠道 Agent 计费历史
|
||
- `GET /api/channel/agent-billing/tenant-summary` - 渠道租户计费汇总
|
||
|
||
---
|
||
|
||
## 阶段七：测试
|
||
|
||
- [x] 单元测试 ✅
|
||
- 创建测试文件 `tests/test_agent_management.py`
|
||
- 计费逻辑测试
|
||
- 配额管理测试
|
||
- 资源申请测试
|
||
- Agent Manager 客户端测试
|
||
- 集成测试
|
||
- [x] Docker 集成测试 ✅
|
||
- 超级管理员 API 测试通过
|
||
- 渠道管理员 API 测试通过
|
||
- 资源申请审批流程测试通过
|
||
- Agent 计费统计 API 测试通过
|
||
- [x] API 文档更新 ✅
|
||
- 更新 `Docs/API-超级管理员控制平台完整接口文档.md` 至 v1.2
|
||
- 新增资源申请审批模块文档
|
||
- 新增平台 Agent 管理模块文档
|
||
- 新增 Agent 计费模块文档
|
||
- 更新权限矩阵
|
||
|
||
---
|
||
|
||
## 文件变更清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `services/mcp-server/models.py` | 修改 | 添加新模型 |
|
||
| `services/mcp-server/migrations/006_*.sql` | 新增 | 数据库迁移 |
|
||
| `services/mcp-server/app/routes/channel.py` | 修改 | 添加申请和资源查看 API |
|
||
| `services/mcp-server/app/routes/admin.py` | 修改 | 添加审批 API |
|
||
| `services/mcp-server/app/routes/user.py` | 修改 | 添加平台 Agent 使用 API |
|
||
| `services/mcp-server/app/agent_manager_client.py` | 修改 | 重构客户端 |
|
||
| `services/mcp-server/app/schemas.py` | 修改 | 添加新的请求/响应模型 |
|
||
|
||
---
|
||
|
||
## 当前进度
|
||
|
||
**开始时间**: 2026-01-05
|
||
|
||
**完成时间**: 2026-01-05
|
||
|
||
**状态**: ✅ 全部完成
|
||
|
||
**已完成**:
|
||
- ✅ 阶段一：数据模型和迁移
|
||
- ResourceApplication、PlatformAgentQuota、AgentBillingRecord 模型
|
||
- 数据库迁移脚本 006_add_agent_resource_management.sql
|
||
- ✅ 阶段二：申请审批功能
|
||
- 渠道查看可用资源 API
|
||
- 渠道发起申请 API
|
||
- 管理员审批 API
|
||
- ✅ 阶段三：Agent Manager 客户端重构
|
||
- 平台/自定义 Agent 模板查询
|
||
- 平台/自定义 Agent 创建
|
||
- 环境变量更新、扩缩容
|
||
- 日志查看、重启
|
||
- 资源统计
|
||
- ✅ 阶段四：平台 Agent 管理功能
|
||
- 管理员功能（模板列表、分配情况、运行状态）
|
||
- 渠道功能（配额查看、分配给租户、使用情况）
|
||
- 租户功能（查看可用、使用、停止、实例列表）
|
||
- ✅ 阶段五：自定义 Agent 管理功能
|
||
- 创建自定义 Agent（配额检查）
|
||
- 删除自定义 Agent（释放配额）
|
||
- 查看模板、扩缩容、日志、重启
|
||
- ✅ 阶段六：计费集成
|
||
- Agent 计费记录逻辑（平台/自定义 Agent）
|
||
- 计费集成到 Agent 使用流程
|
||
- 用户/渠道计费统计 API
|
||
- ✅ 阶段七：测试
|
||
- 单元测试（test_agent_management.py）
|
||
- Docker 集成测试（所有 API 测试通过）
|
||
- API 文档更新（v1.2）
|
||
|
||
**总结**:
|
||
MCP Server Agent 管理系统重构已全部完成，包括：
|
||
1. 平台 Agent 和自定义 Agent 的完整管理功能
|
||
2. 资源申请-审批工作流
|
||
3. 配额管理（Pod 配额 / CPU+内存配额）
|
||
4. Agent 计费系统（按时间/资源计费）
|
||
5. 完整的 API 文档
|