refactor(desktop): split kernel_commands/pipeline_commands into modules, add SaaS client libs and gateway modules

Split monolithic kernel_commands.rs (2185 lines) and pipeline_commands.rs (1391 lines)
into focused sub-modules under kernel_commands/ and pipeline_commands/ directories.
Add gateway module (commands, config, io, runtime), health_check, and 15 new
TypeScript client libraries for SaaS relay, auth, admin, telemetry, and kernel
sub-systems (a2a, agent, chat, hands, skills, triggers).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

@@ -0,0 +1,256 @@
+# 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 模板深度定制**（医疗、法律、教育等）