3ff08faa56
## Major Features ### Streaming Response System - Implement LlmDriver trait with `stream()` method returning async Stream - Add SSE parsing for Anthropic and OpenAI API streaming - Integrate Tauri event system for frontend streaming (`stream:chunk` events) - Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error ### MCP Protocol Implementation - Add MCP JSON-RPC 2.0 types (mcp_types.rs) - Implement stdio-based MCP transport (mcp_transport.rs) - Support tool discovery, execution, and resource operations ### Browser Hand Implementation - Complete browser automation with Playwright-style actions - Support Navigate, Click, Type, Scrape, Screenshot, Wait actions - Add educational Hands: Whiteboard, Slideshow, Speech, Quiz ### Security Enhancements - Implement command whitelist/blacklist for shell_exec tool - Add SSRF protection with private IP blocking - Create security.toml configuration file ## Test Improvements - Fix test import paths (security-utils, setup) - Fix vi.mock hoisting issues with vi.hoisted() - Update test expectations for validateUrl and sanitizeFilename - Add getUnsupportedLocalGatewayStatus mock ## Documentation Updates - Update architecture documentation - Improve configuration reference - Add quick-start guide updates Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
9.0 KiB
9.0 KiB
ZCLAW 项目上线发布差距分析
上下文
本分析旨在评估 ZCLAW AI Agent 桌面客户端距离正式上线发布给用户使用还欠缺什么。通过对核心 Rust crates、桌面应用 UI/UX、测试覆盖和文档完善程度的深入分析，识别关键差距并制定优先级建议。
一、项目整体完成度评估
| 模块 | 完成度 | 状态 |
|---|---|---|
| 核心类型层 (zclaw-types) | 95% | ✅ 生产就绪 |
| 存储层 (zclaw-memory) | 90% | ✅ 生产就绪 |
| 运行时 (zclaw-runtime) | 75% | ⚠️ 基本可用 |
| 核心协调 (zclaw-kernel) | 85% | ✅ 生产就绪 |
| 技能系统 (zclaw-skills) | 70% | ⚠️ 基本可用 |
| 自主能力 (zclaw-hands) | 80% | ⚠️ 教育场景完整 |
| 协议支持 (zclaw-protocols) | 60% | ⚠️ A2A 可用 |
| 通道适配 (zclaw-channels) | 40% | ❌ 框架阶段 |
| 桌面应用 UI | 75-80% | ⚠️ 主要功能完整 |
| 测试覆盖 | 60% | ⚠️ 需提升 |
| 文档完善 | 70% | ⚠️ 需补充 |
| 发布准备 | 50% | ❌ 不充分 |
整体评估：约 70% 完成度
二、关键差距分析
🔴 阻塞性问题 (必须修复才能发布)
1. 流式响应未实现 (zclaw-runtime)
- 位置:
crates/zclaw-runtime/src/loop_runner.rs:125 - 问题:
// TODO: Implement streaming- 流式响应是占位符 - 影响: 用户无法看到 AI 实时输出，体验极差
- 优先级: P0 - 最高
2. 版本号不一致
- 位置: 多处
package.json: 0.2.0desktop/package.json: 0.1.0tauri.conf.json: 0.2.0Cargo.toml: 0.1.0
- 影响: 发布混乱，用户无法识别版本
- 优先级: P0 - 最高
3. MCP 协议未实现
- 位置:
crates/zclaw-protocols/src/mcp.rs:151,155 - 问题:
// TODO: Implement actual MCP protocol communication - 影响: 无法使用 Claude Code 等 MCP 工具生态
- 优先级: P1 - 高
4. 代码签名缺失
- 影响: Windows 用户安装会遇到 SmartScreen 警告
- 优先级: P1 - 高 (生产必需)
5. CHANGELOG 缺失
- 影响: 用户无法了解版本变更
- 优先级: P1 - 高
🟠 重要问题 (影响用户体验)
6. 无障碍支持不足
- 问题: 大多数组件缺少 ARIA 属性和键盘导航
- 影响: 无法服务残障用户
- 优先级: P2 - 中
7. 测试覆盖率低
- 当前: 60% 阈值
- 目标: 80%+
- Rust 测试: 仅 11 个文件有测试模块
- 优先级: P2 - 中
8. CI/CD 未集成测试
- 问题: Gitea workflow 不运行测试
- 影响: 质量无法自动保障
- 优先级: P2 - 中
9. 通道适配器未实现
- 问题: Telegram/Discord/Slack 适配器仅有框架
- 影响: 无法多平台使用
- 优先级: P3 - 低 (取决于产品定位)
10. 8 个通用 Hands 未实现
- CLAUDE.md 提到: Browser, Collector, Researcher, Predictor, Lead, Trader, Clip, Twitter
- 实际实现: 仅 4 个教育类 Hands (Whiteboard, Slideshow, Speech, Quiz)
- 优先级: P3 - 低 (取决于产品定位)
🟡 次要问题 (可后续迭代)
11. API 文档缺失
- 问题: 无专门的 API 参考文档
- 优先级: P3
12. 仅支持 Windows 构建
- 问题: 无 macOS/Linux 构建
- 影响: 限制用户群
- 优先级: P3
13. 国际化未实现
- 问题: 所有 UI 字符串硬编码为中文
- 影响: 无法国际化
- 优先级: P4 (如果只面向中文用户)
三、功能可用性矩阵
| 功能 | UI | Store | Backend | 可用性 |
|---|---|---|---|---|
| 聊天 (流式) | ✅ | ✅ | ⚠️ 模拟 | 部分可用 |
| 多会话管理 | ✅ | ✅ | ✅ | 完全可用 |
| 分身管理 | ✅ | ✅ | ✅ | 完全可用 |
| 模型切换 | ✅ | ✅ | ✅ | 完全可用 |
| 自定义模型配置 | ✅ | ✅ | ✅ | 完全可用 |
| Hands 触发 | ✅ | ✅ | ⚠️ 部分 | 部分可用 |
| Hand 审批 | ✅ | ✅ | ✅ | 完全可用 |
| 工作流 | ✅ | ✅ | ✅ | 完全可用 |
| 技能市场 | ✅ | ✅ | ⚠️ 部分 | 部分可用 |
| 记忆图谱 | ✅ | ✅ | ⚠️ 部分 | 部分可用 |
| 离线模式 | ✅ | ✅ | N/A | 客户端完整 |
| 审计日志 | ✅ | ✅ | ✅ | 完全可用 |
| 安全层 | ✅ | ✅ | ✅ | 完全可用 |
四、发布前必须完成的工作清单
Phase 1: 阻塞性修复 (1-2 周)
- 实现流式响应 - zclaw-runtime loop_runner.rs
- 统一版本号 - 所有配置文件同步
- 创建 CHANGELOG.md - 记录版本变更
- 获取代码签名证书 - Windows 发布必需
Phase 2: 质量保障 (1 周)
- 增加 Rust 单元测试 - 覆盖核心路径
- CI 集成测试 - 自动运行测试
- 提升覆盖率阈值 - 从 60% 到 80%
Phase 3: 用户体验 (1 周)
- 添加无障碍支持 - ARIA 属性、键盘导航
- 完善错误处理 - 用户友好的错误消息
- 性能优化 - 大消息列表虚拟化已有，需验证
Phase 4: 文档与发布 (1 周)
- 补充 API 文档 - 公共接口参考
- 更新用户手册 - 所有功能说明
- 创建发布脚本 - 自动化发布流程
- 准备发布公告 - 产品介绍
五、可选功能路线图
短期 (v0.3.0)
- MCP 协议实现
- 代码签名
- 无障碍改进
中期 (v0.4.0)
- 通用 Hands (Browser, Collector 等)
- macOS 支持
- 视觉工作流构建器
长期 (v1.0.0)
- 通道适配器 (Telegram, Discord)
- 国际化
- Linux 支持
六、风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|---|---|---|---|
| 流式响应实现复杂度高 | 高 | 高 | 优先处理，可考虑降级方案 |
| 代码签名成本 | 中 | 高 | 预算规划，或使用自签名 |
| 测试覆盖不足导致回归 | 中 | 中 | CI 集成，增量提升 |
| MCP 协议变更 | 低 | 中 | 关注规范更新 |
| 第三方 API 变更 | 低 | 低 | 抽象层隔离 |
七、总结
项目优势
- 架构清晰 - 分层设计，职责明确
- 技术栈现代 - React 19, Tauri 2, Rust workspace
- 安全意识强 - WSS 强制，设备认证，审计日志
- 离线优先 - 消息队列，自动重连
关键差距
- 流式响应 - 最影响用户体验的问题
- 发布准备 - 版本管理、签名、CI/CD
- 测试覆盖 - 低于行业标准
- 生态集成 - MCP、通道适配器
建议发布策略
- 先发布内测版 (v0.2.0-beta) - 收集反馈
- 修复阻塞性问题后发布公测版 (v0.3.0)
- 完善质量后发布正式版 (v1.0.0)
八、头脑风暴决策结果
经过讨论，确定了以下关键决策：
决策 1：流式响应
结论：必须实现真正流式
- 不接受模拟方案
- 需要实现 SSE/WebSocket 真正的流式响应
决策 2：Hands 系统
结论：补充核心通用 Hands
- v0.2.0 必须包含 Browser Hand
- v0.2.0 必须包含 Collector Hand
- 保留现有 4 个教育类 Hands
决策 3：MCP 协议
结论：必须实现
- 完整的 MCP 协议通信
- 接入 Claude Code 等工具生态
决策 4：国际化
结论：搭建多语言基础架构
- 集成 react-i18next
- v0.2.0 仅支持中文
- 为未来国际化预留空间
决策 5：发布策略
结论：内测 → 公测 → 正式
- 内测版 (v0.2.0-beta)：邀请 10-20 位种子用户
- 公测版 (v0.2.0-rc)：开放下载
- 正式版 (v0.2.0)：稳定后发布
决策 6：时间线
结论：灵活
- 不设硬性日期
- 功能完成即发布
九、v0.2.0 发布计划
必须完成 (P0)
| 工作项 | 复杂度 | 说明 |
|---|---|---|
| 真正流式响应 | 高 | SSE/WebSocket 实现 |
| Browser Hand | 高 | 浏览器自动化能力 |
| Collector Hand | 中 | 数据收集聚合能力 |
| MCP 协议实现 | 高 | 完整 MCP 通信 |
应该完成 (P1)
| 工作项 | 复杂度 | 说明 |
|---|---|---|
| i18n 基础架构 | 中 | react-i18next 集成 |
| 版本号统一 | 低 | 所有配置同步 0.2.0 |
| CHANGELOG.md | 低 | 创建变更日志 |
| 代码签名 | 中 | Windows 发布必需 |
可以完成 (P2)
| 工作项 | 复杂度 | 说明 |
|---|---|---|
| 测试覆盖率提升 | 中 | 60% → 75%+ |
| 无障碍支持 | 中 | ARIA 属性 |
推迟到后续版本
| 工作项 | 推迟到 |
|---|---|
| 其他 6 个通用 Hands | v0.3.0 |
| 通道适配器 | v0.4.0 |
| macOS/Linux 构建 | v0.4.0 |
| 多语言翻译 | v0.3.0 |
成功标准
- 用户能正常进行流式对话
- Browser Hand 能完成基础网页自动化
- Collector Hand 能收集指定来源数据
- MCP 能连接至少 1 个外部工具
- Windows 安装无 SmartScreen 警告
- 内测用户无阻塞性问题反馈
十、下一步行动
- 创建规格文档 - 写入
docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md - 规格审查 - 确保设计完整性
- 创建实现计划 - 详细的任务分解和时间估算
- 开始实现 - 按优先级推进