diff --git a/docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md b/docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md new file mode 100644 index 0000000..9963331 --- /dev/null +++ b/docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md @@ -0,0 +1,307 @@ +# ZCLAW v0.2.0 发布设计规格 + +> **版本**: 1.0 +> **日期**: 2026-03-23 +> **状态**: 已批准 +> **作者**: Claude + 用户协作 + +--- + +## 一、概述 + +### 1.1 背景 + +ZCLAW 是一个面向中文用户的 AI Agent 桌面客户端，基于 Tauri 2 + React 19 + Rust workspace 技术栈。当前项目整体完成度约 70%，需要进行关键功能补全和发布准备工作。 + +### 1.2 目标 + +将 ZCLAW 打造成功能完整、可正式发布的 AI Agent 桌面客户端，通过内测 → 公测 → 正式的三阶段发布策略，确保产品质量和用户体验。 + +### 1.3 范围 + +- **包含**: 流式响应、核心 Hands、MCP 协议、i18n 架构、发布准备 +- **不包含**: 其他 6 个通用 Hands、通道适配器、macOS/Linux 构建（推迟到后续版本） + +--- + +## 二、关键决策 + +### 2.1 流式响应 + +**决策**: 必须实现真正流式 + +**理由**: +- 流式响应对用户体验至关重要 +- 当前模拟方案无法接受 +- 需要 SSE/WebSocket 实现 + +**实现要求**: +- 替换 `loop_runner.rs:125` 的 TODO 占位符 +- 实现真正的 SSE 流式传输 +- 前端 `KernelClient` 需要支持流式消费 + +### 2.2 Hands 系统 + +**决策**: 补充核心通用 Hands (Browser + Collector) + +**理由**: +- 教育类 Hands (4个) 已完成 +- Browser 和 Collector 是最常用的通用能力 +- 其他 6 个 Hands 可后续迭代 + +**实现要求**: +- Browser Hand: 网页自动化（导航、点击、输入、截图） +- Collector Hand: 数据收集聚合（网页抓取、API 调用、文件读取） + +### 2.3 MCP 协议 + +**决策**: 必须实现 + +**理由**: +- MCP 是 Claude Code 等工具的生态标准 +- 用户期望能接入外部工具 +- 是差异化竞争力 + +**实现要求**: +- 完成 `mcp.rs:151,155` 的 TODO +- 实现工具调用和资源读取 +- 至少能连接 1 个外部 MCP 服务器 + +### 2.4 国际化 + +**决策**: 搭建多语言基础架构，v0.2.0 仅中文 + +**理由**: +- 当前硬编码无法维护 +- 需要为国际化预留空间 +- 先专注中文用户 + +**实现要求**: +- 集成 react-i18next +- 提取所有 UI 字符串 +- v0.2.0 仅提供中文翻译 + +### 2.5 发布策略 + +**决策**: 内测 → 公测 → 正式 + +**阶段定义**: +1. **内测版 (v0.2.0-beta)**: 邀请 10-20 位种子用户 +2. **公测版 (v0.2.0-rc)**: 开放下载，收集更多反馈 +3. **正式版 (v0.2.0)**: 稳定后发布 + +### 2.6 时间线 + +**决策**: 灵活，功能完成即发布 + +**理由**: +- 不设硬性日期可减少压力 +- 保证质量优先 +- 便于应对意外情况 + +--- + +## 三、工作项清单 + +### 3.1 P0 - 必须完成 + +| ID | 工作项 | 复杂度 | 依赖 | 验收标准 | +|----|--------|--------|------|----------| +| P0-1 | 真正流式响应 | 高 | 无 | 用户能看到逐字输出 | +| P0-2 | Browser Hand | 高 | P0-1 | 能完成基础网页自动化 | +| P0-3 | Collector Hand | 中 | 无 | 能收集指定来源数据 | +| P0-4 | MCP 协议实现 | 高 | 无 | 能连接至少 1 个 MCP 服务器 | + +### 3.2 P1 - 应该完成 + +| ID | 工作项 | 复杂度 | 依赖 | 验收标准 | +|----|--------|--------|------|----------| +| P1-1 | i18n 基础架构 | 中 | 无 | react-i18next 集成，中文可用 | +| P1-2 | 版本号统一 | 低 | 无 | 所有配置文件版本一致 | +| P1-3 | CHANGELOG.md | 低 | 无 | 记录所有变更 | +| P1-4 | 代码签名 | 中 | 无 | Windows 安装无警告 | + +### 3.3 P2 - 可以完成 + +| ID | 工作项 | 复杂度 | 依赖 | 验收标准 | +|----|--------|--------|------|----------| +| P2-1 | 测试覆盖率提升 | 中 | 无 | 从 60% 提升到 75%+ | +| P2-2 | 无障碍支持 | 中 | 无 | 关键组件有 ARIA 属性 | + +--- + +## 四、架构设计 + +### 4.1 流式响应架构 + +``` +┌─────────────────┐ SSE/WS ┌─────────────────┐ +│ React UI │ ◄──────────────►│ Tauri Backend │ +│ ChatArea.tsx │ │ KernelClient │ +└─────────────────┘ └────────┬────────┘ + │ + ▼ + ┌─────────────────┐ + │ zclaw-runtime │ + │ LlmDriver │ + │ (stream mode) │ + └─────────────────┘ +``` + +**关键改动**: +1. `LlmDriver` trait 添加 `send_stream()` 方法 +2. `Kernel` 添加 `send_message_stream()` 实现 +3. 前端使用 Tauri 事件系统接收流式数据 + +### 4.2 Hands 系统架构 + +``` +┌─────────────────────────────────────────────────────┐ +│ zclaw-hands │ +├─────────────────────────────────────────────────────┤ +│ HandRegistry │ +│ ├── WhiteboardHand (已实现) │ +│ ├── SlideshowHand (已实现) │ +│ ├── SpeechHand (已实现) │ +│ ├── QuizHand (已实现) │ +│ ├── BrowserHand (新增) ★ │ +│ └── CollectorHand (新增) ★ │ +└─────────────────────────────────────────────────────┘ +``` + +**Browser Hand 能力**: +- `navigate(url)` - 导航到 URL +- `click(selector)` - 点击元素 +- `input(selector, text)` - 输入文本 +- `screenshot()` - 截图 +- `wait(selector)` - 等待元素 + +**Collector Hand 能力**: +- `fetch_url(url)` - 抓取网页 +- `call_api(url, method, body)` - API 调用 +- `read_file(path)` - 读取文件 +- `aggregate(sources)` - 聚合多个来源 + +### 4.3 MCP 协议架构 + +``` +┌─────────────────────────────────────────────────────┐ +│ zclaw-protocols │ +├─────────────────────────────────────────────────────┤ +│ McpClient (trait) │ +│ └── HttpMcpClient (新增) ★ │ +│ ├── connect() - 建立连接 │ +│ ├── list_tools() - 获取工具列表 │ +│ ├── call_tool() - 调用工具 │ +│ ├── list_resources() - 获取资源列表 │ +│ └── read_resource() - 读取资源 │ +└─────────────────────────────────────────────────────┘ +``` + +### 4.4 i18n 架构 + +``` +desktop/src/ +├── i18n/ +│ ├── index.ts # i18n 配置 +│ └── locales/ +│ └── zh-CN/ +│ ├── common.json +│ ├── chat.json +│ ├── hands.json +│ └── settings.json +└── components/ + └── *.tsx # 使用 useTranslation() +``` + +--- + +## 五、文件改动清单 + +### 5.1 Rust 后端 + +| 文件 | 改动类型 | 说明 | +|------|----------|------| +| `crates/zclaw-runtime/src/loop_runner.rs` | 修改 | 实现流式响应 | +| `crates/zclaw-runtime/src/driver/mod.rs` | 修改 | 添加 stream 方法 | +| `crates/zclaw-kernel/src/kernel.rs` | 修改 | 流式消息处理 | +| `crates/zclaw-hands/src/hands/browser.rs` | 新增 | Browser Hand | +| `crates/zclaw-hands/src/hands/collector.rs` | 新增 | Collector Hand | +| `crates/zclaw-protocols/src/mcp.rs` | 修改 | MCP 协议实现 | + +### 5.2 前端 + +| 文件 | 改动类型 | 说明 | +|------|----------|------| +| `desktop/src/i18n/` | 新增 | i18n 配置和翻译文件 | +| `desktop/src/components/ChatArea.tsx` | 修改 | 使用 i18n | +| `desktop/src/store/chatStore.ts` | 修改 | 流式消息处理 | +| `desktop/package.json` | 修改 | 版本号统一 | + +### 5.3 配置文件 + +| 文件 | 改动类型 | 说明 | +|------|----------|------| +| `package.json` | 修改 | 版本号统一 | +| `Cargo.toml` | 修改 | 版本号统一 | +| `tauri.conf.json` | 修改 | 版本号统一 | +| `CHANGELOG.md` | 新增 | 变更日志 | + +--- + +## 六、成功标准 + +### 6.1 功能验收 + +- [ ] 用户能正常进行流式对话，看到逐字输出 +- [ ] Browser Hand 能完成：导航、点击、输入、截图 +- [ ] Collector Hand 能完成：网页抓取、API 调用、数据聚合 +- [ ] MCP 能连接至少 1 个外部工具（如 filesystem-mcp） +- [ ] i18n 框架可用，中文界面完整 + +### 6.2 质量验收 + +- [ ] 所有 Rust 单元测试通过 +- [ ] 所有 E2E 测试通过 +- [ ] 测试覆盖率 ≥ 75% +- [ ] TypeScript 类型检查无错误 + +### 6.3 发布验收 + +- [ ] 版本号所有位置一致 +- [ ] CHANGELOG.md 记录完整 +- [ ] Windows 安装包无 SmartScreen 警告 +- [ ] 内测用户无阻塞性问题反馈 + +--- + +## 七、风险与缓解 + +| 风险 | 概率 | 影响 | 缓解措施 | +|------|------|------|----------| +| 流式响应实现复杂度超预期 | 高 | 高 | 先实现 SSE，WebSocket 可后续迭代 | +| Browser Hand 依赖问题 | 中 | 中 | 使用 headless-chrome 或 playwright | +| MCP 协议兼容性 | 中 | 中 | 先实现核心功能，边缘场景后续处理 | +| 代码签名成本 | 中 | 高 | 预算规划，或使用自签名（仅内测） | +| i18n 工作量 | 低 | 低 | 使用 i18next-scanner 自动提取 | + +--- + +## 八、附录 + +### A. 参考文档 + +- [Tauri Events](https://tauri.app/v2/guides/features/events/) +- [MCP Specification](https://modelcontextprotocol.io/) +- [react-i18next](https://react.i18next.com/) + +### B. 相关 Issue + +- 流式响应 TODO: `crates/zclaw-runtime/src/loop_runner.rs:125` +- MCP TODO: `crates/zclaw-protocols/src/mcp.rs:151,155` + +### C. 版本历史 + +| 版本 | 日期 | 变更 | +|------|------|------| +| 1.0 | 2026-03-23 | 初始版本，用户批准 |