feat: complete Phase 1-3 architecture optimization

Phase 1 - Security: - Add AES-GCM encryption for localStorage fallback - Enforce WSS protocol for non-localhost WebSocket connections - Add URL sanitization to prevent XSS in markdown links Phase 2 - Domain Reorganization: - Create Intelligence Domain with Valtio store and caching - Add unified intelligence-client for Rust backend integration - Migrate from legacy agent-memory, heartbeat, reflection modules Phase 3 - Core Optimization: - Add virtual scrolling for ChatArea with react-window - Implement LRU cache with TTL for intelligence operations - Add message virtualization utilities Additional: - Add OpenFang compatibility test suite - Update E2E test fixtures - Add audit logging infrastructure - Update project documentation and plans Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-21 22:11:50 +08:00
parent 815c56326b
commit ce562e8bfc
36 changed files with 5241 additions and 201 deletions
--- a/docs/analysis/BRAINSTORMING-SESSION-v2.md
+++ b/docs/analysis/BRAINSTORMING-SESSION-v2.md
@@ -0,0 +1,387 @@
+# ZCLAW 项目头脑风暴会议纪要 v2
+
+> **会议日期：** 2026-03-21
+> **基于：** 系统性深度分析报告
+> **目标：** 针对分析结果进行深入探讨，提出建设性意见和可行性方案
+
+---
+
+## 参会专家角色
+
+| 角色 | 职责 | 输入领域 |
+|------|------|----------|
+| 系统架构师 | 整体架构评估 | 代码结构、模块划分 |
+| 前端技术专家 | 前端架构优化 | React、性能优化 |
+| 后端技术专家 | 后端架构优化 | Rust、智能层 |
+| 安全专家 | 安全合规评估 | 数据保护、认证授权 |
+| 产品专家 | 功能规划 | 用户价值、优先级 |
+
+---
+
+## 议题一：架构优化方向
+
+### 1.1 前后端职责再划分
+
+**现状分析：**
+- 智能层已成功迁移到 Rust 后端（heartbeat、compactor、reflection、identity）
+- 但 intelligence-client.ts 仍包含 localStorage 降级逻辑
+- 部分业务逻辑仍在前端（agent-swarm、active-learning）
+
+**方案讨论：**
+
+| 方案 | 优点 | 缺点 | 推荐度 |
+|------|------|------|--------|
+| A. 全部迁移到 Rust | 统一、持久化、多端共享 | 工作量大 | ⭐⭐⭐ |
+| B. 保持现状，前端做桥接 | 渐进迁移 | 双实现维护成本 | ⭐⭐⭐⭐ |
+| C. 只迁移核心模块 | 平衡工作量和收益 | 边界不清 | ⭐⭐⭐ |
+
+**结论：** 采用 **方案 B**，渐进式迁移
+- 核心模块（记忆、反思、心跳）已迁移 ✅
+- 非核心模块（agent-swarm、active-learning）可评估后决定
+
+### 1.2 gateway-client.ts 拆分
+
+**现状：** 65KB 单文件，包含 WebSocket、REST、认证、心跳、流式处理
+
+**拆分方案：**
+```
+gateway/
+├── index.ts              # 统一导出
+├── client.ts             # 核心类（状态、事件）
+├── websocket.ts          # WebSocket 连接管理
+├── rest.ts               # REST API 封装
+├── auth.ts               # 认证逻辑
+├── stream.ts             # 流式响应处理
+└── types.ts              # 类型定义
+```
+
+**实施计划：**
+- **优先级：** P1
+- **工作量：** 2-3 人天
+- **风险：** 低（已有模块边界）
+
+**结论：** ✅ 同意拆分
+
+---
+
+## 议题二：技术升级方向
+
+### 2.1 React 19 新特性采用
+
+**现状：** 使用 React 19，但未充分利用新特性
+
+**可采用的新特性：**
+
+| 特性 | 适用场景 | 收益 | 优先级 |
+|------|----------|------|--------|
+| use() Hook | Store 读取 | 简化代码 | 中 |
+| React Compiler | 全局 | 性能优化 | 高 |
+| Document Metadata | SEO/Head | 简化元数据管理 | 低 |
+| Third-party Hooks | 库集成 | 更好的兼容性 | 中 |
+
+**结论：** 评估 React Compiler，优先在性能敏感组件试用
+
+### 2.2 状态管理评估
+
+**现状：** Zustand 5
+
+**评估：**
+- Zustand 5 已支持更多中间件
+- 考虑迁移到 @preact/signals 或 Jotai？
+
+**结论：** 保持 Zustand 5，聚焦功能开发
+
+### 2.3 测试框架增强
+
+**现状：** Vitest + Playwright，但 E2E 不稳定 (~80% 通过率)
+
+**改进方案：**
+
+| 改进项 | 方案 | 优先级 |
+|--------|------|--------|
+| E2E 稳定性 | 增加等待逻辑、使用 `waitForFunction` | P0 |
+| 单元测试覆盖率 | 增加边界测试、错误场景测试 | P1 |
+| Mock 策略 | 使用 MSW (Mock Service Worker) | P2 |
+| 视觉回归测试 | 集成 Playwright 截图对比 | P3 |
+
+**结论：** 优先解决 E2E 稳定性问题 (P0)
+
+---
+
+## 议题三：性能提升方向
+
+### 3.1 渲染性能优化
+
+**问题：** 大量消息时可能 re-render
+
+**方案：**
+
+| 方案 | 实施难度 | 收益 | 推荐度 |
+|------|----------|------|--------|
+| A. Zustand shallow 比较 | 低 | 中 | ⭐⭐⭐⭐ |
+| B. React.memo 优化组件 | 中 | 高 | ⭐⭐⭐⭐⭐ |
+| C. 虚拟列表优化 | 中 | 高 | ⭐⭐⭐⭐ |
+| D. 减少 Context 使用 | 低 | 中 | ⭐⭐⭐ |
+
+**结论：** 组合实施 A + B + D，重点优化 ChatArea 和 MessageList
+
+### 3.2 网络性能优化
+
+**问题：** 单 WebSocket 连接
+
+**方案：**
+
+| 方案 | 优点 | 缺点 | 推荐度 |
+|------|------|------|--------|
+| A. WebSocket 连接池 | 并发请求 | 实现复杂度高 | ⭐⭐ |
+| B. HTTP/2 多路复用 | 标准方案 | 需要后端支持 | ⭐⭐⭐ |
+| C. 请求合并 | 减少请求数 | 增加延迟 | ⭐⭐⭐ |
+| D. 保持现状 | 简单 | - | ⭐⭐⭐⭐⭐ |
+
+**结论：** 保持现状，当前连接数不是瓶颈
+
+### 3.3 大文件/长文本处理
+
+**现状：** Token 估算和压缩已迁移到 Rust 后端
+
+**可优化点：**
+- 流式 token 计数
+- 增量压缩
+- 智能摘要生成
+
+**结论：** 当前实现已满足需求，持续观察
+
+---
+
+## 议题四：功能扩展方向
+
+### 4.1 移动端支持
+
+**评估：**
+
+| 方案 | 技术选型 | 工作量 | 推荐度 |
+|------|----------|--------|--------|
+| A. React Native | 跨平台 | 大 | ⭐⭐ |
+| B. Tauri Mobile | Tauri 生态 | 中 | ⭐⭐⭐⭐ |
+| C. Flutter | 独立生态 | 大 | ⭐⭐ |
+| D. 暂不开发 | - | - | ⭐⭐⭐⭐⭐ |
+
+**结论：** 评估 Tauri Mobile，但优先级低于核心功能
+
+### 4.2 国际化 (i18n)
+
+**现状：** 中文优先，但硬编码字符串存在
+
+**方案：**
+```typescript
+// 使用 react-i18next
+i18n.t('chat.placeholder')
+i18n.t('hand.trigger', { name })
+```
+
+**工作量：** 约 1-2 周
+
+**结论：** 建议在下一版本规划中纳入
+
+### 4.3 更多 Channel 集成
+
+**当前：** 飞书 (Feishu)
+
+**可扩展：**
+
+| Channel | 需求度 | 技术难度 | 优先级 |
+|---------|--------|----------|--------|
+| 企业微信 | 高 | 高 | 中 |
+| 钉钉 | 中 | 高 | 低 |
+| Discord | 中 | 中 | 中 |
+| Telegram | 低 | 低 | 中 |
+
+**结论：** 优先完善飞书集成，评估 Discord
+
+### 4.4 插件市场
+
+**现状：** 3 个插件 (chinese-models, feishu, ui)
+
+**方案：**
+
+| 阶段 | 内容 | 工作量 |
+|------|------|--------|
+| Phase 1 | 插件市场 UI + 基础 API | 1 周 |
+| Phase 2 | 插件审核机制 | 1 周 |
+| Phase 3 | 付费插件支持 | 2 周 |
+
+**结论：** 作为差异化竞争力，纳入中期规划
+
+---
+
+## 议题五：风险规避方向
+
+### 5.1 OpenFang 兼容性维护
+
+**风险：** OpenFang 版本升级可能导致兼容性问题
+
+**方案：**
+
+| 方案 | 实施难度 | 保护程度 |
+|------|----------|----------|
+| A. 版本锁定 | 低 | 弱 |
+| B. 兼容层抽象 | 中 | 中 |
+| C. 自动化兼容性测试 | 高 | 强 |
+| D. 参与 OpenFang 开发 | 高 | 最强 |
+
+**结论：** 实施 B + C，建立兼容性测试套件
+
+### 5.2 敏感数据保护
+
+**现状：** API Key 使用 OS Keyring，但聊天记录未加密
+
+**改进方案：**
+
+| 敏感数据 | 当前存储 | 建议存储 | 优先级 |
+|----------|----------|----------|--------|
+| API Key | OS Keyring ✅ | 保持 | - |
+| Gateway Token | OS Keyring ✅ | 保持 | - |
+| 聊天记录 | SQLite | 加密存储 | P1 |
+| Theme | localStorage | 保持 | 低 |
+
+**结论：** 聊天记录加密纳入安全增强计划
+
+### 5.3 灰度发布机制
+
+**现状：** 无灰度发布
+
+**方案：**
+
+| 方案 | 工具 | 工作量 |
+|------|------|--------|
+| A. Tauri 内置更新 | tauri-plugin-updater | 1 天 |
+| B. 手动版本管理 | - | 0 |
+| C. 自动化灰度 | 定制开发 | 1 周 |
+
+**结论：** 集成 Tauri 内置更新机制
+
+---
+
+## 议题六：创新解决方案
+
+### 6.1 AI Native 特性增强
+
+**想法：**
+
+| 特性 | 描述 | 创新度 |
+|------|------|--------|
+| 自适应上下文 | 根据任务类型自动调整上下文长度 | ⭐⭐⭐ |
+| 智能缓存 | 预测用户意图，预加载资源 | ⭐⭐⭐ |
+| 多模态交互 | 支持图片、语音输入 | ⭐⭐ |
+| 主动建议 | 基于上下文主动提供建议 | ⭐⭐⭐⭐ |
+
+**结论：** 优先实现"主动建议"作为差异化功能
+
+### 6.2 本地知识图谱构建
+
+**想法：**
+- 将记忆系统升级为知识图谱
+- 实体关系挖掘
+- 语义推理能力
+
+**技术路径：**
+```rust
+// 实体提取
+struct Entity {
+    name: String,
+    type: EntityType,
+    properties: HashMap<String, Value>,
+}
+
+// 关系链接
+struct Relation {
+    from: EntityId,
+    to: EntityId,
+    relation_type: String,
+    confidence: f32,
+}
+```
+
+**结论：** 长期规划，与 OpenViking 深度集成
+
+### 6.3 跨设备状态同步
+
+**问题：** 当前数据仅本地存储
+
+**方案：**
+
+| 方案 | 复杂度 | 隐私性 | 推荐度 |
+|------|--------|--------|--------|
+| A. 云端同步 | 高 | 低 | ⭐⭐ |
+| B. 端到端加密同步 | 高 | 高 | ⭐⭐⭐⭐ |
+| C. 文件导入/导出 | 低 | 最高 | ⭐⭐⭐⭐ |
+| D. 保持本地优先 | - | - | ⭐⭐⭐⭐⭐ |
+
+**结论：** 提供端到端加密同步作为 Pro 功能
+
+### 6.4 隐私计算集成
+
+**想法：**
+- 本地模型推理（Llama.cpp 集成）
+- 联邦学习支持
+- 数据不出本机
+
+**结论：** 长期愿景，需要大量研发投入
+
+---
+
+## 行动建议总结
+
+### 短期行动（1-2 周）
+
+| # | 行动 | 优先级 | 负责人 | 工作量 |
+|---|------|--------|--------|--------|
+| 1 | E2E 测试稳定性修复 | P0 | 测试团队 | 2-3 人天 |
+| 2 | gateway-client.ts 拆分 | P1 | 前端团队 | 2-3 人天 |
+| 3 | Rust unwrap() 替换 | P1 | 后端团队 | 0.5 人天 |
+
+### 中期行动（1-2 月）
+
+| # | 行动 | 优先级 | 工作量 |
+|---|------|--------|--------|
+| 4 | 聊天记录加密 | P1 | 1 周 |
+| 5 | 插件市场 MVP | P2 | 1 周 |
+| 6 | i18n 支持 | P2 | 1-2 周 |
+| 7 | 兼容性测试套件 | P1 | 1 周 |
+| 8 | 性能优化 (re-render) | P2 | 2-3 人天 |
+
+### 长期愿景（6 月+）
+
+| # | 行动 | 优先级 |
+|---|------|--------|
+| 9 | 本地知识图谱 | P3 |
+| 10 | 端到端加密同步 | P3 |
+| 11 | Tauri Mobile 支持 | P3 |
+| 12 | 主动建议能力 | P2 |
+
+---
+
+## 会议结论
+
+1. **架构优化优先** - gateway-client.ts 拆分是短期最高优先级
+2. **稳定性优先** - E2E 测试修复和兼容性测试是 P0
+3. **保持专注** - 不追求功能数量，聚焦核心体验
+4. **隐私优先** - 本地优先策略，用户数据不强制上云
+5. **渐进改进** - 避免大规模重构，采用渐进式优化
+
+---
+
+## 关键决策记录
+
+| 决策项 | 决策结果 | 理由 |
+|--------|----------|------|
+| 前后端职责划分 | 渐进迁移 | 平衡工作量和收益 |
+| 状态管理 | 保持 Zustand 5 | 聚焦功能开发 |
+| 移动端 | 暂不开发 | 优先级低于核心功能 |
+| 国际化 | 下一版本纳入 | 1-2 周工作量 |
+| 聊天记录 | 加密存储 | 保护用户隐私 |
+| 跨设备同步 | Pro 功能 | 端到端加密 |
+
+---
+
+*会议纪要完成*