# 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. **开始实现** - 按优先级推进