iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
af20487b8dd022d7fc1e8cb958b550cf52d52a6a
zclaw_openfang/docs/analysis-2026-03-31-future-work.md
iven f79560a911 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>
2026-03-31 11:12:47 +08:00

7.0 KiB
Raw Blame History

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 框架引入
  └── 监控/可观测性