# ZCLAW Admin V2 + Agent 会话端 功能评估报告

> **评估日期**: 2026-03-31
> **评估范围**: Admin V2 (localhost:5173) + Desktop Agent (localhost:1420)
> **后端版本**: zclaw-saas v0.1.0 (Axum + PostgreSQL)

---

## 一、系统定位分析

### 1.1 Admin V2 定位

**核心定位**: AI Agent 管理平台 — 统一管理模型服务商、Token 池、Agent 模板、API 密钥和系统配置。

**用户期望的两个核心功能**:

| 功能 | 定位 | 实现状态 |
|------|------|----------|
| **Token 池代理** | 多个 Tauri 客户端共享模型 API 配额（coding plan 成本优化） | 后端完整，前端 UI 不完整 |
| **行业 Agent 模板** | 预设行业 Agent（含 soul.md），Tauri 端获取后通过对话成长 | 基础框架在，缺行业定制化 |

**实际角色分工**:
- Admin V2 = **管理控制平面**（配置、监控、审计）
- Desktop Agent = **用户交互平面**（对话、任务执行、自主能力）
- SaaS Backend = **中转与数据平面**（认证、Relay、Telemetry）

### 1.2 数据流验证

```
Tauri Agent → SaaS Relay (/api/v1/relay/chat/completions)
           → Key Pool 选择可用 Key
           → 转发到模型提供商 API
           → 流式响应回传
           → 记录 Usage + Telemetry
```

后端实现完整（Key Pool 轮换、429 冷却、RPM/TPM 限制），但 Admin 前端缺少 Key 添加/管理 UI。

---

## 二、环境状态

| 组件 | 状态 | 备注 |
|------|------|------|
| SaaS Backend (8080) | **degraded** | 数据库连接池 96% (48/50) |
| Admin V2 (5173) | 运行正常 | Vite dev server |
| Desktop Agent (1420) | **无法启动** | 多文件编译错误 |
| PostgreSQL | 运行中 | 连接池接近耗尽 |

---

## 三、Admin V2 功能测试结果

### 3.1 测试汇总

| 模块 | 页面 | 结果 | 备注 |
|------|------|------|------|
| A. 认证 | Login.tsx | **PASS** | 登录/登出正常，TOTP 字段隐藏 |
| B. 仪表盘 | Dashboard.tsx | **PASS** | 5 统计卡片 + 10 条日志 |
| C. 账号管理 | Accounts.tsx | **PASS** | 13 条账号，CRUD 正常 |
| D. 服务商 | Providers.tsx | **PARTIAL** | Key Pool 只读，无管理 UI |
| E. 模型管理 | Models.tsx | **PASS** | 12 模型，服务商名正确解析 |
| F. Agent 模板 | AgentTemplates.tsx | **PARTIAL** | 无编辑功能 |
| G. API 密钥 | ApiKeys.tsx | **PASS** | 完整生命周期 |
| H. 用量统计 | Usage.tsx | **PARTIAL** | 按模型统计表显示 "No data" |
| I. 中转任务 | Relay.tsx | **PASS** | 20 条任务，状态筛选正常 |
| J. 系统配置 | Config.tsx | **PASS** | 6 分类标签，内联编辑 |
| K. 提示词管理 | Prompts.tsx | **PASS** | 3 个内置模板，版本管理 |
| L. 操作日志 | Logs.tsx | **PASS** | 275 条日志，分页正常 |

**通过率**: 8/12 完全通过，4/12 部分通过

### 3.2 各模块详细测试记录

#### A. 认证与访问控制

| 测试项 | 结果 | 说明 |
|--------|------|------|
| A1 登录页渲染 | PASS | 左品牌 + 右表单，TOTP 隐藏 |
| A2 正确凭据登录 | PASS | 跳转仪表盘 |
| A3 错误凭据 | PASS | 错误提示显示 |
| A4 Auth Guard | PASS | 未登录重定向到 /login |
| A5 退出登录 | PASS | 清除会话 |
| A6 RBAC 菜单过滤 | PASS | filterMenuByPermission 工作正常 |
| A7 页面刷新保持登录 | **FAIL** | 见问题 #1 |

#### B. 仪表盘

| 测试项 | 结果 |
|--------|------|
| B1 统计卡片 (5) | PASS — 13 账号, 4 服务商, 12 模型, 0 请求, 134,244 Token |
| B2 最近日志 | PASS — 10 条 account.login 记录 |

#### C. 账号管理

| 测试项 | 结果 |
|--------|------|
| C1 账号列表 | PASS — 13 条, 角色/状态/2FA 列正确 |
| C2 编辑账号 | PASS — Modal 预填充 |
| C3 禁用/启用 | PASS — 状态切换即时生效 |

#### D. 服务商管理 + Key Pool

| 测试项 | 结果 |
|--------|------|
| D1 服务商列表 | PASS — 5 个服务商 |
| D2 创建服务商 | PASS |
| D3 编辑服务商 | PASS |
| D4 Key Pool 查看 | PASS — Modal 显示 Key 数据 |
| **D5 Key Pool 管理** | **FAIL** — 无添加/切换/删除按钮 |

#### E-H. 模型/Agent模板/API密钥/用量

| 测试项 | 结果 |
|--------|------|
| E1 模型列表 | PASS — 12 模型，服务商名称正确解析 |
| F1 Agent 模板列表 | PASS — 5 个模板 |
| F3 模板详情 | PASS — 显示工具/能力标签 |
| G1 API 密钥 | PASS — 3 个密钥，权限标签正确 |
| H1 每日统计 | PASS — 112 请求, 308,560 Token |
| **H2 按模型统计** | **FAIL** — 显示 "No data" |

#### I-L. 中转/配置/提示词/日志

| 测试项 | 结果 |
|--------|------|
| I1 中转任务 | PASS — 20 条，状态筛选正常 |
| J1 系统配置 | PASS — 6 分类标签页 |
| K1 提示词管理 | PASS — 3 个内置模板 |
| L1 操作日志 | PASS — 275 条，分页正常 |

---

## 四、Desktop Agent 测试结果

### 4.1 编译阻断

Desktop Agent **无法启动**，存在多个 TypeScript 解析错误：

| 文件 | 错误行 | 错误类型 | 根因 |
|------|--------|----------|------|
| `gateway-storage.ts:160` | 160 | 缺少 `}` 和 `/**` | console.log 清理引入 |
| `llm-service.ts:672` | 672 | 多余 `}` | console.log 清理引入 |
| `gateway-client.ts:425+` | 多处 | 多余 `}` | console.log 清理引入 |

**根因**: 之前的 console.log → logger 替换工作（将 `catch {}` 改为 `catch (e) { log.debug() }`）在多个文件中引入了错误的括号匹配。影响 9 个已修改文件中的至少 3 个。

**修复状态**: `llm-service.ts` 已修复。其余文件需逐一检查。

### 4.2 浏览器模式测试

修复 `llm-service.ts` 后，Desktop Agent 在浏览器模式下成功显示登录界面：
- ZCLAW 品牌 Logo
- SaaS 登录表单（用户名/密码）
- 登录/注册按钮
- "ZCLAW AI Agent Platform" 副标题

但因 `gateway-client.ts` 仍有编译错误，无法完成登录流程。

---

## 五、问题清单（按优先级）

### P0: 阻断性问题

| # | 问题 | 影响 | 文件 | 状态 |
|---|------|------|------|------|
| 1 | ~~Desktop Agent 编译错误~~ | Agent 端完全无法使用 | `gateway-client.ts`, `gateway-storage.ts`, `llm-service.ts` | **已修复** |
| 2 | ~~Key Pool 管理 UI 缺失~~ | Token 池核心定位功能不可用 | `admin-v2/src/pages/Providers.tsx` | **已存在** — 代码已有完整 addKey/toggleKey/deleteKey UI |

> **修复说明 #1**: `catch {}` → `catch (e) { log.debug() }` 清理在 3 个文件中引入括号不匹配。`gateway-storage.ts` 通过 `git checkout` 恢复；`llm-service.ts` 和 `gateway-client.ts` 手动移除多余的 `}`。

> **说明 #2**: 重新审读 Providers.tsx 发现 Key Pool 管理 UI 已完整实现（添加密钥 Modal + 切换/删除操作按钮 + addKey/toggleKey/deleteKey mutations）。初始评估报告有误。

### P1: 高优先级

| # | 问题 | 影响 | 文件 | 状态 |
|---|------|------|------|------|
| 3 | ~~页面刷新丢失登录状态~~ | 用户刷新页面后被迫重新登录 | `admin-v2/src/router/AuthGuard.tsx` | **已修复** — 新增 /auth/me cookie 验证恢复 |
| 4 | **Agent 模板无编辑功能** | 只能创建和归档，无法修改已有模板 | `admin-v2/src/pages/AgentTemplates.tsx` | 待修复 |
| 5 | **SaaS 后端数据库连接池 96%** | 服务状态 "degraded"，接近连接耗尽 | 后端配置/连接管理 | 待修复 |
| 6 | **按模型统计显示 "No data"** | 用量页面按模型统计表为空，即使有 relay 请求记录 | `admin-v2/src/pages/Usage.tsx` 或 telemetry API | 待修复 |

### P2: 中优先级

| # | 问题 | 影响 | 文件 |
|---|------|------|------|
| 7 | **RBAC 无路由级守卫** | 用户可通过 URL 直接访问无权限页面（菜单隐藏但 URL 可达） | `admin-v2/src/router/index.tsx` |
| 8 | **中转任务无操作按钮** | 无法重试失败任务或取消排队任务 | `admin-v2/src/pages/Relay.tsx` |
| 9 | **账号管理无创建账号 UI** | 只能编辑和禁用，无法通过 Admin 创建新账号 | `admin-v2/src/pages/Accounts.tsx` |
| 10 | **仪表盘缺少图表** | 已引入 @ant-design/charts 但未使用，统计仅有数字卡片 | `admin-v2/src/pages/Dashboard.tsx` |
| 11 | **API 密钥名称显示 "-"** | 创建密钥后名称列为空 | `admin-v2/src/pages/ApiKeys.tsx` |

### P3: 低优先级

| # | 问题 | 影响 | 文件 |
|---|------|------|------|
| 12 | **Accounts.tsx import 在底部** | 第 170 行 `import { useState }` 位置不正确，虽然运行时无影响 | `admin-v2/src/pages/Accounts.tsx:170` |
| 13 | **配置重启提示不够明显** | requires_restart=true 的配置项修改后无醒目警告 | `admin-v2/src/pages/Config.tsx` |
| 14 | **表格固定分页大小** | 所有 ProTable 不可调整每页条数 | 多处 |

---

## 六、系统定位与实际实现差距分析

### 6.1 Token 池代理

| 能力 | 后端 | Admin 前端 | 状态 |
|------|------|-----------|------|
| Provider CRUD | 完整 | 完整 | OK |
| Key Pool 添加 | `POST /providers/:id/keys` | **已实现** (Modal + Form) | OK |
| Key Pool 切换 | `PUT /providers/:id/keys/:kid/toggle` | **已实现** (Switch 按钮) | OK |
| Key Pool 删除 | `DELETE /providers/:id/keys/:kid` | **已实现** (Popconfirm) | OK |
| Key Pool 查看 | `GET /providers/:id/keys` | 完整列表 | OK |
| Relay 请求转发 | 完整（含 SSE 流式） | 查看/筛选 | OK |
| Key 轮换策略 | priority + RPM/TPM + 429 cooldown | — | OK |
| 用量统计 | telemetry API | 每日统计 OK，按模型空 | 部分 |

**结论**: 后端 Token 池功能完整，Admin 前端 Key 管理 UI 也已完整实现（添加/切换/删除密钥）。初始评估有误。

### 6.2 行业 Agent 模板

| 能力 | 后端 | Admin 前端 | Desktop | 状态 |
|------|------|-----------|---------|------|
| 模板 CRUD | 完整 | 创建+查看+归档 | — | 部分 |
| 模板编辑 | `PATCH /agent-templates/:id` | **未实现** | — | 缺失 |
| 行业预设 | 5 个通用模板 | 显示正常 | — | 基础 |
| soul.md 人格 | system_prompt 字段 | — | — | 基础 |
| Desktop 获取模板 | `GET /agent-templates` | — | SaaS client 存在 | 待验证 |
| Agent 成长系统 | — | — | identity/memory 系统 | 已有 |

**结论**: Agent 模板基础框架已搭建，但缺少行业深度定制（医疗等特定行业的 soul.md、工具集、能力定义）。模板编辑功能缺失也限制了模板迭代优化。

---

## 七、后续优化建议

### 紧急（已在本次评估中修复）

1. ~~**修复 Desktop Agent 编译错误**~~ — 3 个文件的括号不匹配已修复，`tsc --noEmit` 零错误
2. ~~**补充 Key Pool 管理 UI**~~ — 经复查代码已存在完整 UI（初始评估有误）
3. ~~**添加 AuthGuard session 恢复**~~ — AuthGuard 新增 /auth/me cookie 验证，页面刷新保持登录

### 高优（1-2 周内）

4. **添加 Agent 模板编辑功能**
5. **修复按模型统计 "No data" 问题** — 检查 telemetry API 的 model_stats 查询
6. **调查数据库连接池问题** — 48/50 连接使用中，可能存在连接泄漏

### 中期（1 个月内）

7. **路由级 RBAC 守卫**
8. **中转任务操作（重试/取消）**
9. **账号创建 UI**
10. **仪表盘图表可视化**
11. **行业 Agent 模板深度定制**（医疗、法律、教育等）