2e5f63be32
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
- Create docs/brainstorming/ with 5 discussion records (Mar 16 - Apr 7) - Archive ~30 outdated audit reports (V5-V11) to docs/archive/old-audits/ - Archive superseded analysis docs to docs/archive/old-analysis/ - Archive completed session plans to docs/archive/old-plans/ - Archive old test reports/validations to respective archive folders - Remove empty directories left after moves - Keep current docs: TRUTH.md, feature docs, deployment, knowledge-base, superpowers
257 lines
11 KiB
Markdown
257 lines
11 KiB
Markdown
# 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 模板深度定制**（医疗、法律、教育等）
|