300 lines
11 KiB
Markdown
300 lines
11 KiB
Markdown
# MCP-Server 设计问题审查报告
|
||
|
||
## 概述
|
||
|
||
本报告检查了 MCP-Server 的设计代码，发现了多个设计错误和冲突问题。
|
||
|
||
---
|
||
|
||
## 一、严重问题（会导致运行时错误）
|
||
|
||
### 1.1 PlatformAgentQuota 模型字段缺失 ❌
|
||
|
||
**问题描述**：`user.py` 中使用了 `PlatformAgentQuota` 的多个字段，但这些字段在 `models.py` 中**不存在**。
|
||
|
||
**models.py 中的定义（第 1095-1131 行）**：
|
||
```python
|
||
class PlatformAgentQuota(BaseModel, Base):
|
||
__tablename__ = "platform_agent_quotas"
|
||
|
||
target_id = Column(GUID(), nullable=False)
|
||
target_type = Column(String(20), nullable=False) # channel, tenant
|
||
template_name = Column(String(100), nullable=False)
|
||
pod_quota = Column(Integer, nullable=False, default=0)
|
||
pod_used = Column(Integer, default=0)
|
||
allocated_by = Column(GUID(), ForeignKey("users.id"))
|
||
allocated_at = Column(DateTime, default=datetime.utcnow)
|
||
```
|
||
|
||
**user.py 中使用的缺失字段**：
|
||
|
||
| 缺失字段 | 使用位置 | 用途 |
|
||
|----------|----------|------|
|
||
| `is_active` | user.py:835, 881, 1011 | 过滤活跃配额 |
|
||
| `agent_type` | user.py:844, 880, 1010 | Agent 类型标识 |
|
||
| `cpu_per_pod` | user.py:849, 909, 935 | 每个 Pod 的 CPU 配置 |
|
||
| `memory_per_pod` | user.py:850, 911, 936 | 每个 Pod 的内存配置 |
|
||
|
||
**影响**：
|
||
- 用户调用 `/api/user/platform-agents/available` 会报错
|
||
- 用户调用 `/api/user/platform-agents/use` 会报错
|
||
- 用户停止平台 Agent 时会报错
|
||
|
||
**修复建议**：在 `models.py` 的 `PlatformAgentQuota` 类中添加缺失字段：
|
||
|
||
```python
|
||
class PlatformAgentQuota(BaseModel, Base):
|
||
__tablename__ = "platform_agent_quotas"
|
||
|
||
target_id = Column(GUID(), nullable=False)
|
||
target_type = Column(String(20), nullable=False) # channel, tenant
|
||
template_name = Column(String(100), nullable=False)
|
||
|
||
# 新增字段
|
||
agent_type = Column(String(100)) # Agent 类型名称（与 template_name 可能相同）
|
||
is_active = Column(Boolean, default=True) # 是否活跃
|
||
cpu_per_pod = Column(String(20), default="100m") # 每个 Pod 的 CPU
|
||
memory_per_pod = Column(String(20), default="128Mi") # 每个 Pod 的内存
|
||
|
||
# 原有字段
|
||
pod_quota = Column(Integer, nullable=False, default=0)
|
||
pod_used = Column(Integer, default=0)
|
||
allocated_by = Column(GUID(), ForeignKey("users.id"))
|
||
allocated_at = Column(DateTime, default=datetime.utcnow)
|
||
```
|
||
|
||
---
|
||
|
||
### 1.2 AgentBillingRecord 模型字段缺失 ❌
|
||
|
||
**问题描述**：`user.py` 中使用了 `AgentBillingRecord` 的多个字段，但这些字段在 `models.py` 中**不存在**。
|
||
|
||
**models.py 中的定义（第 1134-1172 行）**：
|
||
```python
|
||
class AgentBillingRecord(BaseModel, Base):
|
||
__tablename__ = "agent_billing_records"
|
||
|
||
user_id = Column(GUID(), ForeignKey("users.id"), nullable=False)
|
||
channel_id = Column(GUID(), ForeignKey("channels.id"))
|
||
agent_name = Column(String(100), nullable=False)
|
||
agent_type = Column(String(20), nullable=False) # platform, custom
|
||
template_name = Column(String(100), nullable=False)
|
||
duration_seconds = Column(Integer, nullable=False)
|
||
cpu_seconds = Column(sa.Float, default=0)
|
||
memory_gb_seconds = Column(sa.Float, default=0)
|
||
request_count = Column(Integer, default=0)
|
||
cost = Column(sa.Numeric(12, 4), nullable=False)
|
||
currency = Column(String(10), default="EU")
|
||
period_start = Column(DateTime, nullable=False)
|
||
period_end = Column(DateTime, nullable=False)
|
||
```
|
||
|
||
**user.py 中使用的缺失字段**：
|
||
|
||
| 缺失字段 | 使用位置 | 用途 |
|
||
|----------|----------|------|
|
||
| `is_platform_agent` | user.py:933, 1054, 1207, 1264, 1469, 1659, 1682 | 区分平台/自定义 Agent |
|
||
| `start_time` | user.py:934, 1071, 1209, 1285, 1488, 1684 | 开始时间 |
|
||
| `end_time` | user.py:992, 1054, 1265, 1469, 1685 | 结束时间 |
|
||
| `cpu_used` | user.py:935, 1211, 1291, 1378, 1421, 1487, 1687 | CPU 使用量 |
|
||
| `memory_used` | user.py:936, 1212, 1291, 1379, 1424, 1488, 1688 | 内存使用量 |
|
||
| `eu_consumed` | user.py:1002, 1287, 1687 | EU 消耗量 |
|
||
|
||
**影响**：
|
||
- 用户使用平台 Agent 时计费记录创建失败
|
||
- 用户创建自定义 Agent 时计费记录创建失败
|
||
- 计费历史查询失败
|
||
|
||
**修复建议**：在 `models.py` 的 `AgentBillingRecord` 类中添加缺失字段：
|
||
|
||
```python
|
||
class AgentBillingRecord(BaseModel, Base):
|
||
__tablename__ = "agent_billing_records"
|
||
|
||
user_id = Column(GUID(), ForeignKey("users.id"), nullable=False)
|
||
channel_id = Column(GUID(), ForeignKey("channels.id"))
|
||
|
||
agent_name = Column(String(100), nullable=False)
|
||
agent_type = Column(String(20), nullable=False) # 模板名称
|
||
template_name = Column(String(100), nullable=False)
|
||
|
||
# 新增字段
|
||
is_platform_agent = Column(Boolean, nullable=False) # 是否为平台 Agent
|
||
start_time = Column(DateTime) # 开始时间
|
||
end_time = Column(DateTime) # 结束时间（None 表示运行中）
|
||
cpu_used = Column(String(20)) # CPU 使用量（如 "100m"）
|
||
memory_used = Column(String(20)) # 内存使用量（如 "128Mi"）
|
||
eu_consumed = Column(sa.Float, default=0) # EU 消耗量
|
||
|
||
# 原有字段
|
||
duration_seconds = Column(Integer) # 改为可空，运行中时为 None
|
||
cpu_seconds = Column(sa.Float, default=0)
|
||
memory_gb_seconds = Column(sa.Float, default=0)
|
||
request_count = Column(Integer, default=0)
|
||
cost = Column(sa.Numeric(12, 4)) # 改为可空
|
||
currency = Column(String(10), default="EU")
|
||
period_start = Column(DateTime) # 改为可空
|
||
period_end = Column(DateTime) # 改为可空
|
||
```
|
||
|
||
---
|
||
|
||
## 二、设计冲突问题
|
||
|
||
### 2.1 平台 Agent 模板硬编码 ⚠️
|
||
|
||
**问题描述**：平台 Agent 模板在 `admin.py` 和 `channel.py` 中**重复硬编码**，而不是从 Agent Manager 获取。
|
||
|
||
**位置**：
|
||
- [`admin.py:2507-2547`](services/mcp-server/app/routes/admin.py:2507) - `PLATFORM_AGENT_TEMPLATES`
|
||
- [`channel.py:1737-1777`](services/mcp-server/app/routes/channel.py:1737) - `PLATFORM_AGENT_TEMPLATES`
|
||
|
||
**问题**：
|
||
1. 两处代码需要保持同步，容易出错
|
||
2. 新增模板需要修改代码并重新部署
|
||
3. 与 Agent Manager 的模板管理功能冲突
|
||
|
||
**修复建议**：
|
||
1. 删除硬编码的 `PLATFORM_AGENT_TEMPLATES`
|
||
2. 调用 `agent_manager_client.list_platform_templates()` 获取模板
|
||
3. 或者在数据库中存储模板配置
|
||
|
||
### 2.2 字段命名不一致 ⚠️
|
||
|
||
**问题描述**：同一概念在不同地方使用不同的字段名。
|
||
|
||
| 概念 | models.py | user.py | 说明 |
|
||
|------|-----------|---------|------|
|
||
| Agent 类型 | `agent_type` | `agent_type` / `template_name` | 有时混用 |
|
||
| 开始时间 | `period_start` | `start_time` | 不一致 |
|
||
| 结束时间 | `period_end` | `end_time` | 不一致 |
|
||
|
||
**修复建议**：统一字段命名，或者在模型中同时保留两个字段作为别名。
|
||
|
||
---
|
||
|
||
## 三、业务逻辑问题
|
||
|
||
### 3.1 平台 Agent 启动时机不符合需求 ⚠️
|
||
|
||
**当前实现**：
|
||
- `user.py` 中的 `/api/user/platform-agents/use` 接口是**用户主动调用**才启动 Pod
|
||
|
||
**需求**：
|
||
- 平台 Agent 应该在**渠道分配给用户时立即启动**，用户可以直接使用
|
||
|
||
**影响位置**：
|
||
- [`channel.py`](services/mcp-server/app/routes/channel.py) 中的租户资源分配接口
|
||
|
||
**修复建议**：
|
||
在渠道分配平台 Agent 配额给租户时，自动调用 Agent Manager 创建 Pod：
|
||
|
||
```python
|
||
# channel.py 中分配平台 Agent 给租户时
|
||
async def allocate_platform_agent_to_tenant(...):
|
||
# 1. 创建配额记录
|
||
tenant_quota = PlatformAgentQuota(...)
|
||
|
||
# 2. 立即调用 Agent Manager 启动 Pod
|
||
client = get_agent_manager_client()
|
||
result = await client.create_platform_agent(
|
||
name=f"{template_name}-{tenant_id[:8]}",
|
||
template=template_name,
|
||
user_id=tenant_id,
|
||
channel_id=channel_id,
|
||
config=AgentConfig(
|
||
cpu_request=cpu_per_pod,
|
||
memory_request=memory_per_pod,
|
||
...
|
||
)
|
||
)
|
||
|
||
# 3. 更新配额使用量
|
||
tenant_quota.pod_used = 1
|
||
tenant_quota.pod_name = result.name
|
||
```
|
||
|
||
### 3.2 自定义 Agent 配额检查逻辑正确 ✅
|
||
|
||
**当前实现**：
|
||
- 渠道分配配额给租户时只记录配额，不启动 Pod
|
||
- 用户创建自定义 Agent 时检查配额并启动 Pod
|
||
|
||
**符合需求**：自定义 Agent 需要用户填写配置后才启动。
|
||
|
||
---
|
||
|
||
## 四、数据库迁移需求
|
||
|
||
根据上述问题，需要创建数据库迁移脚本：
|
||
|
||
### 4.1 迁移脚本 007_fix_platform_agent_quota.sql
|
||
|
||
```sql
|
||
-- 为 platform_agent_quotas 表添加缺失字段
|
||
ALTER TABLE platform_agent_quotas
|
||
ADD COLUMN IF NOT EXISTS agent_type VARCHAR(100),
|
||
ADD COLUMN IF NOT EXISTS is_active BOOLEAN DEFAULT TRUE,
|
||
ADD COLUMN IF NOT EXISTS cpu_per_pod VARCHAR(20) DEFAULT '100m',
|
||
ADD COLUMN IF NOT EXISTS memory_per_pod VARCHAR(20) DEFAULT '128Mi';
|
||
|
||
-- 创建索引
|
||
CREATE INDEX IF NOT EXISTS idx_platform_agent_quota_active
|
||
ON platform_agent_quotas(is_active);
|
||
```
|
||
|
||
### 4.2 迁移脚本 008_fix_agent_billing_record.sql
|
||
|
||
```sql
|
||
-- 为 agent_billing_records 表添加缺失字段
|
||
ALTER TABLE agent_billing_records
|
||
ADD COLUMN IF NOT EXISTS is_platform_agent BOOLEAN,
|
||
ADD COLUMN IF NOT EXISTS start_time TIMESTAMP,
|
||
ADD COLUMN IF NOT EXISTS end_time TIMESTAMP,
|
||
ADD COLUMN IF NOT EXISTS cpu_used VARCHAR(20),
|
||
ADD COLUMN IF NOT EXISTS memory_used VARCHAR(20),
|
||
ADD COLUMN IF NOT EXISTS eu_consumed FLOAT DEFAULT 0;
|
||
|
||
-- 修改原有字段为可空
|
||
ALTER TABLE agent_billing_records
|
||
ALTER COLUMN duration_seconds DROP NOT NULL,
|
||
ALTER COLUMN cost DROP NOT NULL,
|
||
ALTER COLUMN period_start DROP NOT NULL,
|
||
ALTER COLUMN period_end DROP NOT NULL;
|
||
|
||
-- 创建索引
|
||
CREATE INDEX IF NOT EXISTS idx_agent_billing_is_platform
|
||
ON agent_billing_records(is_platform_agent);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_billing_end_time
|
||
ON agent_billing_records(end_time);
|
||
```
|
||
|
||
---
|
||
|
||
## 五、问题汇总
|
||
|
||
| 问题类型 | 问题描述 | 严重程度 | 状态 |
|
||
|----------|----------|----------|------|
|
||
| 模型字段缺失 | PlatformAgentQuota 缺少 is_active, agent_type, cpu_per_pod, memory_per_pod | 严重 | 待修复 |
|
||
| 模型字段缺失 | AgentBillingRecord 缺少 is_platform_agent, start_time, end_time, cpu_used, memory_used, eu_consumed | 严重 | 待修复 |
|
||
| 代码重复 | PLATFORM_AGENT_TEMPLATES 在两处硬编码 | 中等 | 待修复 |
|
||
| 字段命名不一致 | period_start/start_time, period_end/end_time | 低 | 待修复 |
|
||
| 业务逻辑 | 平台 Agent 启动时机不符合需求 | 中等 | 待修复 |
|
||
|
||
---
|
||
|
||
## 六、修复优先级
|
||
|
||
1. **高优先级**：修复 `PlatformAgentQuota` 和 `AgentBillingRecord` 模型字段缺失
|
||
2. **中优先级**：修改平台 Agent 启动时机（渠道分配时启动）
|
||
3. **低优先级**：移除硬编码模板，改为从 Agent Manager 获取
|
||
|
||
---
|
||
|
||
## 七、版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v1.0 | 2026-01-05 | 初始审查报告 |
|