zclaw_openfang/docs/qa/admin-agent-evaluation-report.md

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 模板深度定制（医疗、法律、教育等）