f79560a911
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>
188 lines
7.0 KiB
Markdown
188 lines
7.0 KiB
Markdown
# ZCLAW 后续工作分析
|
||
|
||
> **生成日期**: 2026-03-31
|
||
> **基于**: 系统评估报告 + 设计规格差异分析 + TODO扫描 + 测试/部署审计
|
||
|
||
---
|
||
|
||
## 当前状态概览
|
||
|
||
| 维度 | 评分 | 说明 |
|
||
|------|------|------|
|
||
| 功能完成度 | 87% | 核心功能完整，SaaS 定位设计 12/12 项全部实现 |
|
||
| 代码质量 | B+ | 全库仅 1 个 TODO，无 FIXME/HACK，TypeScript 严格模式 |
|
||
| 后端测试 | 34% | Rust 257 个测试 + 12 个集成测试，覆盖可接受 |
|
||
| 前端测试 | ~15% | Desktop 34 个测试文件，Admin V2 零测试 |
|
||
| 部署就绪 | 40% | docker-compose 存在但缺 Dockerfile，无生产部署指南 |
|
||
| 文档完整性 | 50% | 架构/知识库丰富，缺 API 文档和部署指南 |
|
||
|
||
---
|
||
|
||
## 一、P0 — 必须完成 (阻塞上线)
|
||
|
||
### 1.1 SaaS 生产部署基础设施
|
||
|
||
**问题**: `docker-compose.yml` 引用的 Dockerfile 和 `saas-env.example` 不存在，无法容器化部署。
|
||
|
||
| 工作项 | 说明 | 工作量 |
|
||
|--------|------|--------|
|
||
| 创建 `Dockerfile` | 多阶段构建: builder (cargo build --release) + runtime (debian-slim) | 2h |
|
||
| 创建 `saas-env.example` | 所有必需环境变量模板 + 中文注释 | 1h |
|
||
| Nginx/Caddy 反向代理配置 | HTTPS 终止 + WebSocket 代理 + 限流 | 2h |
|
||
| 生产部署指南 | `docs/deployment/saas-production.md` | 2h |
|
||
| 健康检查端点放开 | `/api/health` 当前需认证，生产环境应公开 | 0.5h |
|
||
|
||
### 1.2 Admin V2 基础测试
|
||
|
||
**问题**: Admin V2 的 33 个源文件零测试覆盖，无测试框架。
|
||
|
||
| 工作项 | 说明 | 工作量 |
|
||
|--------|------|--------|
|
||
| 配置 Vitest + React Testing Library | `admin-v2/vitest.config.ts` + 依赖安装 | 1h |
|
||
| request.ts 拦截器测试 | Token 刷新竞态、网络错误包装、401 处理 | 2h |
|
||
| 核心页面冒烟测试 | Accounts/Providers/AgentTemplates 渲染测试 | 3h |
|
||
| authStore 测试 | 登录/登出/Token 刷新状态管理 | 2h |
|
||
|
||
---
|
||
|
||
## 二、P1 — 功能补全 (近期迭代)
|
||
|
||
### 2.1 设计规格遗留项
|
||
|
||
| 工作项 | 当前状态 | 说明 | 工作量 |
|
||
|--------|---------|------|--------|
|
||
| Admin AgentTemplates 表单: `scenarios` 输入 | 缺失 | 创建表单没有 scenarios 多选 Tag 输入 | 1h |
|
||
| Admin AgentTemplates 表单: `quick_commands` 编辑器 | 缺失 | 需 Form.List 动态编辑 `[{label, prompt}]` | 2h |
|
||
| Key Pool 同优先级 LRU 排序 | 缺失 | `select_best_key()` 仅按 priority 排序，同优先级无负载分散 | 2h |
|
||
| `quota_reset_interval` 字段 | 死代码 | provider_keys 表有此字段但无重置逻辑，需决定实现或移除 | 1h |
|
||
|
||
### 2.2 Desktop 遗留 TS 错误修复
|
||
|
||
| 文件 | 问题 | 工作量 |
|
||
|------|------|--------|
|
||
| `desktop/src/lib/llm-service.ts` | 之前重构引入的语法错误 (已修复) | Done |
|
||
| `desktop/src/lib/gateway-api.ts` | 评估显示无错误，需验证是否为旧版本问题 | 0.5h |
|
||
| `desktop/src/lib/kernel-hands.ts` | 同上 | 0.5h |
|
||
|
||
### 2.3 Pipeline `started_at` 时间戳修复
|
||
|
||
| 文件 | 问题 | 工作量 |
|
||
|------|------|--------|
|
||
| `desktop/src-tauri/src/pipeline_commands/discovery.rs:214` | `started_at` 使用 `Utc::now()` 而非实际启动时间 | 1h |
|
||
|
||
### 2.4 Admin V2 表格增强
|
||
|
||
| 工作项 | 说明 | 工作量 |
|
||
|--------|------|--------|
|
||
| 搜索/筛选功能 | Accounts/Models/Providers/ApiKeys/Prompts 表格无搜索 | 4h |
|
||
| 分页状态管理 | 大部分表格不同步本地分页状态 | 2h |
|
||
| Config 页编辑体验 | 内联编辑缺加载指示器和 hover 视觉反馈 | 1h |
|
||
|
||
---
|
||
|
||
## 三、P2 — 质量提升 (中期优化)
|
||
|
||
### 3.1 API 文档
|
||
|
||
| 工作项 | 说明 | 工作量 |
|
||
|--------|------|--------|
|
||
| OpenAPI/Swagger 规范 | 69 个端点需要正式 API 文档，可从 Axum handler 自动生成 | 4h |
|
||
| API Reference 页面 | 可集成到 Admin V2 或独立 docs 站点 | 2h |
|
||
|
||
### 3.2 Desktop 测试提升
|
||
|
||
| 工作项 | 当前 | 目标 | 工作量 |
|
||
|--------|------|------|--------|
|
||
| Store 单元测试 | ~15% | 60% | 8h |
|
||
| 组件测试 | 少量 | 核心组件覆盖 | 6h |
|
||
| E2E 集成到 CI | 12 个 Playwright spec 未在 CI 运行 | 自动执行 | 2h |
|
||
|
||
### 3.3 国际化 (i18n) 准备
|
||
|
||
| 工作项 | 说明 | 工作量 |
|
||
|--------|------|--------|
|
||
| 引入 i18n 框架 | Desktop saasStore/connectionStore 硬编码中文错误消息 | 2h |
|
||
| Admin V2 i18n | 所有页面中文硬编码 | 6h |
|
||
| 提取翻译文件 | zh-CN.json + en-US.json | 4h |
|
||
|
||
### 3.4 监控与可观测性
|
||
|
||
| 工作项 | 说明 | 工作量 |
|
||
|--------|------|--------|
|
||
| 结构化日志增强 | SaaS 后端 tracing 已有，需添加 request_id 关联 | 2h |
|
||
| Prometheus metrics | 请求延迟、Key Pool 使用率、错误率 | 4h |
|
||
| Grafana 仪表盘模板 | 预配置的监控面板 | 3h |
|
||
|
||
---
|
||
|
||
## 四、P3 — 功能扩展 (远期规划)
|
||
|
||
### 4.1 已规划但未启动的功能
|
||
|
||
| 功能 | 设计状态 | 说明 |
|
||
|------|---------|------|
|
||
| 技能市场 UI | CLAUDE.md 标记"进行中" | 技能浏览和安装界面，70 个 SKILL.md 已有 |
|
||
| Pipeline 工作流编辑器 | CLAUDE.md 标记"进行中" | 可视化编辑器，PipelinesPanel 已有基础 |
|
||
| 智能路由 (Semantic Router) | L2/50% 成熟度 | 意图路由不成熟，需更多训练数据 |
|
||
| Predictor Hand | enabled=false | 无 Rust 实现，需完全重写 |
|
||
| Lead Hand | enabled=false | 无 Rust 实现，需完全重写 |
|
||
|
||
### 4.2 设计规格明确排除的未来功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| AccountTier 订阅层级 | 未来商业化 |
|
||
| 实时配置推送 (WebSocket) | 当前登录时拉取，未来推送 |
|
||
| 模板市场/用户上传 | 当前仅 Admin 管理 |
|
||
| Token Pool 计费/用量配额 | 当前无计费逻辑 |
|
||
| Desktop 用户自选路由模式 | 设计决定仅 Admin 控制 |
|
||
|
||
---
|
||
|
||
## 五、工作量估算汇总
|
||
|
||
| 优先级 | 类别 | 工作量 | 建议排期 |
|
||
|--------|------|--------|---------|
|
||
| **P0** | 部署基础设施 | ~7.5h | 第 1 周 |
|
||
| **P0** | Admin V2 基础测试 | ~8h | 第 1-2 周 |
|
||
| **P1** | 设计规格遗留 | ~6.5h | 第 2 周 |
|
||
| **P1** | Desktop TS 错误 | ~1.5h | 第 2 周 |
|
||
| **P1** | 表格增强 | ~7h | 第 3 周 |
|
||
| **P2** | API 文档 | ~6h | 第 3-4 周 |
|
||
| **P2** | 测试提升 | ~16h | 持续 |
|
||
| **P2** | i18n | ~12h | 第 4-5 周 |
|
||
| **P2** | 监控 | ~9h | 第 5 周 |
|
||
| **P3** | 功能扩展 | 大量 | 按需 |
|
||
| **总计 P0+P1** | | **~30.5h** | 3 周 |
|
||
| **总计 P2** | | **~43h** | 5 周 |
|
||
|
||
---
|
||
|
||
## 六、建议执行顺序
|
||
|
||
```
|
||
Week 1: P0 部署基础设施
|
||
├── Dockerfile + saas-env.example
|
||
├── Nginx 反代配置
|
||
├── /api/health 公开
|
||
└── 生产部署指南
|
||
|
||
Week 2: P0 Admin 测试 + P1 遗留修复
|
||
├── Admin V2 Vitest 配置 + request.ts 测试
|
||
├── scenarios/quick_commands 表单
|
||
├── Key Pool LRU 排序
|
||
├── quota_reset_interval 决策
|
||
└── Pipeline started_at 修复
|
||
|
||
Week 3: P1 表格增强 + P2 API 文档
|
||
├── 搜索/筛选功能
|
||
├── 分页状态修复
|
||
├── OpenAPI 规范生成
|
||
└── API Reference 页面
|
||
|
||
Week 4+: P2 质量持续提升
|
||
├── Desktop 测试覆盖提升
|
||
├── i18n 框架引入
|
||
└── 监控/可观测性
|
||
```
|