# ZCLAW 项目全面架构优化方案 > 头脑风暴日期: 2026-03-21 > 目标: 全面优化 | 时间: 3个月+ | 策略: 激进架构优先 --- ## 一、当前架构分析 ### 1.1 现有问题总结 | 类别 | 问题 | 严重性 | 影响 | |------|------|--------|------| | **安全** | 浏览器 eval() XSS 风险 | 🔴 HIGH | 用户数据泄露 | | **安全** | localStorage 凭据回退 | 🟠 MEDIUM | 密钥暴露 | | **性能** | 流式更新重建整个数组 | 🟠 MEDIUM | 渲染卡顿 | | **性能** | 无界消息数组 | 🟠 MEDIUM | 内存泄漏 | | **架构** | 50+ lib 模块缺乏统一抽象 | 🟡 LOW | 维护困难 | | **测试** | 核心模块无测试覆盖 | 🟠 MEDIUM | 回归风险 | ### 1.2 技术债务分布 ``` desktop/src/ ├── lib/ [50+ 模块] ← 需要模块化重组 ├── store/ [15 stores] ← 需要统一模式 ├── components/ [60+ 组件] ← 需要分层 └── types/ [分散] ← 需要集中管理 ``` --- ## 二、三种优化方案 ### 方案 A: 渐进式模块化重构 (推荐) **核心理念**: 保持现有架构，逐步提取抽象层 ``` Phase 1 (4周): 安全加固 + 测试基础 ├─ 修复 XSS/凭据存储问题 ├─ 添加 chatStore/gateway-client 测试 └─ 建立测试覆盖率门禁 Phase 2 (4周): 性能优化 ├─ 引入 Immer 优化状态更新 ├─ 实现虚拟滚动 (react-window) └─ 消息分页 + 惰性加载 Phase 3 (6周): 架构分层 ├─ 提取 Core Layer (协议无关) ├─ 提取 Adapter Layer (Tauri/Web) └─ 统一错误处理和日志 Phase 4 (4周): Intelligence 增强 ├─ Rust 层功能完善 ├─ TypeScript 适配器优化 └─ 记忆/心跳/反思/身份 全链路 ``` **优点**: - 风险可控，每阶段可独立验证 - 不影响现有功能交付 - 团队可并行工作 **缺点**: - 改动分散，可能产生中间态 - 总体周期较长 --- ### 方案 B: 激进架构重写 **核心理念**: 重新设计核心架构，一次性解决所有问题 ``` Step 1: 定义新架构规范 ├─ 分层架构: UI → Application → Domain → Infrastructure ├─ 依赖注入容器 └─ 统一事件总线 Step 2: 核心层重写 ├─ 新 State Manager (基于 Immer + Middleware) ├─ 新 Client Layer (统一协议抽象) └─ 新 Error System (分类 + 恢复) Step 3: 迁移现有功能 ├─ Store 逐个迁移 ├─ 组件适配新 API └─ 测试同步跟进 Step 4: 清理旧代码 ``` **优点**: - 一次性解决所有架构问题 - 代码质量飞跃式提升 - 未来扩展性最佳 **缺点**: - 高风险，可能引入新 bug - 开发周期不可控 - 需要冻结功能开发 --- ### 方案 C: 领域驱动分层 **核心理念**: 按业务领域重组，每个领域独立优化 ``` Domain 1: Chat (对话系统) ├─ ChatStore 重构 (Immer + 分页) ├─ 流式响应优化 └─ 虚拟滚动 + 记忆增强 Domain 2: Hands (自动化) ├─ HandStore 状态机模式 ├─ 审批流程增强 └─ 执行引擎隔离 Domain 3: Intelligence (智能层) ├─ Rust 后端完善 ├─ 心跳/压缩/反思/身份 └─ 缓存策略优化 Domain 4: Skills (技能系统) ├─ 技能发现/搜索优化 ├─ 执行沙箱隔离 └─ 依赖管理 Cross-Cutting: ├─ 安全层 (统一加解密) ├─ 测试层 (领域测试套件) └─ 监控层 (性能/错误追踪) ``` **优点**: - 领域边界清晰 - 可独立演进 - 易于并行开发 **缺点**: - 跨领域逻辑复杂 - 共享代码可能重复 - 需要重新规划目录结构 --- ## 三、方案对比 | 维度 | 方案 A (渐进) | 方案 B (激进) | 方案 C (领域) | |------|---------------|---------------|---------------| | **风险** | 🟢 低 | 🔴 高 | 🟡 中 | | **速度** | 🟡 中 | 🔴 慢 | 🟢 快 | | **效果** | 🟡 中等提升 | 🟢 飞跃提升 | 🟢 显著提升 | | **并行度** | 🟡 部分并行 | 🔴 串行 | 🟢 完全并行 | | **推荐度** | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | --- ## 四、确认方案: A + C 混合 (用户已确认) > **关键决策**: > - 状态管理: **VZustand** (Proxy 细粒度响应) > - 安全策略: **Web Worker 隔离执行** (最安全) 结合渐进式和领域驱动的优点: ``` ┌─────────────────────────────────────────────────────────────┐ │ Phase 1: 安全 + 测试 (2周) │ │ • 实现 Web Worker 隔离执行引擎 │ │ • 修复凭据存储问题 (加密回退) │ │ • 建立测试框架和覆盖率门禁 │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Phase 2: 领域重组 (4周) │ │ • 按领域重组目录结构 │ │ • 迁移到 VZustand (Proxy 响应式) │ │ • 提取领域接口和抽象 │ │ • 统一错误处理 │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Phase 3: 核心优化 (并行) (6周) │ │ Track A: Chat Track B: Hands Track C: Intelligence │ │ • VZustand 重写 • 状态机模式 • Rust 增强 │ │ • 虚拟滚动 • Web Worker • 缓存策略 │ │ • 流式优化 • 审批流增强 • 性能调优 │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Phase 4: 集成 + 清理 (2周) │ │ • 跨领域集成测试 │ │ • 清理旧代码 │ │ • 文档更新 │ └─────────────────────────────────────────────────────────────┘ ``` **总周期**: 约 14 周 (3.5 个月) --- ## 五、各领域详细优化点 ### 5.1 智能对话系统 (Chat Domain) | 优化项 | 当前问题 | 解决方案 | 预期收益 | |--------|----------|----------|----------| | 状态更新 | 每次重建数组 | **VZustand** (Proxy 细粒度) | 70% 性能提升 | | 长对话 | 无界数组 | 分页 + 惰性加载 | 内存降低 80% | | 虚拟滚动 | 全量渲染 | react-window | 首屏快 3x | | 流式响应 | 回调嵌套 | AsyncGenerator | 代码简洁 | **VZustand 架构**: ```typescript // 基于 Proxy 的细粒度响应 const useChatStore = create( proxy({ messages: [], addMessage: (msg) => { messages.push(msg); } // 直接 mutate }) ); // 组件只订阅使用的字段 function MessageList() { const messages = useChatStore(s => s.messages); // 仅 messages 变化时重渲染 } ``` **关键改动文件**: - `desktop/src/store/chatStore.ts` → 重写为 VZustand - `desktop/src/components/ChatArea/MessageList.tsx` - `desktop/src/lib/gateway-client.ts` ### 5.2 Hands 自动化 (Hands Domain) | 优化项 | 当前问题 | 解决方案 | 预期收益 | |--------|----------|----------|----------| | 状态管理 | 简单状态 | 状态机模式 (XState) | 可预测性提升 | | 审批流程 | 硬编码 | 可配置审批链 | 灵活性提升 | | 执行隔离 | 共享上下文 | **Web Worker 隔离** | 安全性最大化 | | 错误恢复 | 无 | 检查点 + 重试 | 可靠性提升 | **Web Worker 隔离架构**: ``` ┌─────────────────────────────────────────────────────────────┐ │ Main Thread │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ HandStore │←→│ WorkerPool │←→│ UI 更新 │ │ │ └─────────────┘ └──────┬──────┘ └─────────────┘ │ └────────────────────────────┼────────────────────────────────┘ │ postMessage ▼ ┌─────────────────────────────────────────────────────────────┐ │ Web Worker (隔离) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Browser Executor │ │ │ │ • 无 DOM 访问 │ │ │ │ • 受限 API │ │ │ │ • 超时控制 │ │ │ │ • 错误隔离 │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **关键改动文件**: - `desktop/src/store/handStore.ts` → 状态机模式 - `desktop/src/workers/browser-worker.ts` (新建) - `desktop/src/lib/worker-pool.ts` (新建) - `desktop/src-tauri/src/browser/` ### 5.3 Intelligence 层 (Intelligence Domain) | 优化项 | 当前问题 | 解决方案 | 预期收益 | |--------|----------|----------|----------| | Rust 完善 | 部分功能未实现 | 补全所有命令 | 功能完整 | | 缓存策略 | 无缓存 | LRU + TTL | 响应快 2x | | 离线支持 | 依赖网络 | 本地优先 | 可用性提升 | | 记忆搜索 | 简单匹配 | 向量检索 | 准确率提升 | **关键改动文件**: - `desktop/src-tauri/src/intelligence/*.rs` - `desktop/src-tauri/src/memory/*.rs` - `desktop/src/lib/intelligence-client.ts` ### 5.4 技能系统 (Skills Domain) | 优化项 | 当前问题 | 解决方案 | 预期收益 | |--------|----------|----------|----------| | 搜索效率 | 遍历文件 | 索引 + 缓存 | 搜索快 10x | | 执行沙箱 | 无隔离 | iframe/Worker | 安全性提升 | | 依赖管理 | 手动 | 自动解析 | 易用性提升 | **关键改动文件**: - `desktop/src/lib/skill-loader.ts` (新建) - `desktop/src/store/skillStore.ts` - `skills/*/SKILL.md` 规范更新 --- ## 六、安全加固专项 ### 6.1 XSS 防护 - Web Worker 隔离 ```typescript // 当前问题: browser.eval() 直接在主线程执行用户输入 // 解决方案: Web Worker 完全隔离执行 // 主线程: worker-pool.ts class BrowserWorkerPool { private workers: Worker[] = []; async execute(script: string, args: unknown[]): Promise { const worker = this.getAvailableWorker(); return new Promise((resolve, reject) => { const timeout = setTimeout(() => { worker.terminate(); reject(new Error('Execution timeout')); }, 30000); worker.onmessage = (e) => { clearTimeout(timeout); if (e.data.error) reject(new Error(e.data.error)); else resolve(e.data.result); }; worker.postMessage({ type: 'eval', script, args }); }); } } // Worker: browser-worker.ts self.onmessage = async (e) => { const { type, script, args } = e.data; try { // 无 DOM 访问，受限 API const result = await executeScript(script, args); self.postMessage({ result }); } catch (error) { self.postMessage({ error: error.message }); } }; ``` ### 6.2 凭据存储 ```typescript // 当前问题: localStorage 明文回退 // 解决方案: 加密回退 + 密钥派生 const ENCRYPTION_KEY = await deriveKey(userPassword, salt); const encrypted = await encrypt(privateKey, ENCRYPTION_KEY); localStorage.setItem(KEY, encrypted); ``` ### 6.3 WebSocket 安全 ```typescript // 当前问题: 非 localhost 允许 ws:// // 解决方案: 强制 wss:// + 证书验证 if (!url.startsWith('wss://') && !isLocalhost(url)) { throw new SecurityError('Non-localhost must use WSS'); } ``` --- ## 七、测试策略 ### 7.1 测试金字塔 ``` /\ / \ E2E Tests (Playwright) /────\ - 关键用户流程 / \ - 10-15 个核心场景 /────────\ / \ Integration Tests (Vitest) /────────────\ - Store + Client 集成 / \- API 契约测试 /────────────────\ / \ Unit Tests (Vitest) ──────────────────── - 纯函数/工具 - 80%+ 覆盖率目标 ``` ### 7.2 覆盖率目标 | 模块 | 当前 | 目标 | |------|------|------| | `chatStore.ts` | 0% | 90% | | `gateway-client.ts` | 0% | 85% | | `handStore.ts` | 0% | 85% | | `intelligence-client.ts` | 0% | 80% | | 工具函数 | ~40% | 95% | --- ## 八、验证计划 ### 8.1 功能验证 - [ ] 聊天流式响应正常 - [ ] Hands 触发和审批正常 - [ ] Intelligence 层功能完整 - [ ] 技能搜索和执行正常 - [ ] 配置读写正常 ### 8.2 性能验证 - [ ] 首屏加载 < 2s - [ ] 消息渲染 60fps - [ ] 1000+ 消息流畅滚动 - [ ] 内存占用 < 500MB ### 8.3 安全验证 - [ ] XSS 攻击防护有效 - [ ] 凭据存储安全 - [ ] WebSocket 加密传输 --- ## 九、风险与缓解 | 风险 | 概率 | 影响 | 缓解措施 | |------|------|------|----------| | 引入新 bug | 中 | 高 | 每阶段充分测试 | | 进度延期 | 中 | 中 | 预留 buffer | | 架构决策失误 | 低 | 高 | 原型验证 | | 团队不熟悉新架构 | 中 | 中 | 培训 + 文档 | --- ## 十、下一步行动 1. **确认方案**: 用户选择最终方案 2. **创建详细计划**: 使用 writing-plans skill 3. **开始执行**: Phase 1 安全加固