iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
36168d6978bae2bc2f3c94de0e970c0ca79cc1a2
zclaw_openfang/plans/vast-enchanting-creek.md
iven 3ff08faa56 release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements 
## 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>
2026-03-24 03:24:24 +08:00

308 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.0
- `desktop/package.json`: 0.1.0
- `tauri.conf.json`: 0.2.0
- `Cargo.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)
1. MCP 协议实现
2. 代码签名
3. 无障碍改进
### 中期 (v0.4.0)
1. 通用 Hands (Browser, Collector 等)
2. macOS 支持
3. 视觉工作流构建器
### 长期 (v1.0.0)
1. 通道适配器 (Telegram, Discord)
2. 国际化
3. Linux 支持
---
## 六、风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 流式响应实现复杂度高 | 高 | 高 | 优先处理，可考虑降级方案 |
| 代码签名成本 | 中 | 高 | 预算规划，或使用自签名 |
| 测试覆盖不足导致回归 | 中 | 中 | CI 集成，增量提升 |
| MCP 协议变更 | 低 | 中 | 关注规范更新 |
| 第三方 API 变更 | 低 | 低 | 抽象层隔离 |
---
## 七、总结
### 项目优势
1. **架构清晰** - 分层设计，职责明确
2. **技术栈现代** - React 19, Tauri 2, Rust workspace
3. **安全意识强** - WSS 强制，设备认证，审计日志
4. **离线优先** - 消息队列，自动重连
### 关键差距
1. **流式响应** - 最影响用户体验的问题
2. **发布准备** - 版本管理、签名、CI/CD
3. **测试覆盖** - 低于行业标准
4. **生态集成** - MCP、通道适配器
### 建议发布策略
1. **先发布内测版 (v0.2.0-beta)** - 收集反馈
2. **修复阻塞性问题后发布公测版 (v0.3.0)**
3. **完善质量后发布正式版 (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 警告
- [ ] 内测用户无阻塞性问题反馈
---
## 十、下一步行动
1. **创建规格文档** - 写入 `docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md`
2. **规格审查** - 确保设计完整性
3. **创建实现计划** - 详细的任务分解和时间估算
4. **开始实现** - 按优先级推进
Reference in New Issue View Git Blame Copy Permalink