diff --git a/.trae/documents/project-systematic-analysis-plan.md b/.trae/documents/project-systematic-analysis-plan.md new file mode 100644 index 0000000..ca40ef3 --- /dev/null +++ b/.trae/documents/project-systematic-analysis-plan.md @@ -0,0 +1,453 @@ +# ZClaw_openfang 项目系统性深度分析计划 + +> **计划制定日期：** 2026-03-21 +> **计划模式：** 用户要求对项目进行系统性、多维度深度与广度梳理分析，并组织专题头脑风暴会议 + +--- + +## 一、分析目标与范围 + +### 1.1 分析目标 + +对 ZClaw_openfang 项目进行系统性、多维度的深度与广度梳理分析，涵盖： + +- 代码结构 +- 架构设计 +- 技术栈选型 +- 业务逻辑实现 +- 数据流向 +- 接口设计 +- 性能瓶颈 +- 潜在风险 +- 可优化点 + +### 1.2 头脑风暴方向 + +- 架构优化 +- 技术升级 +- 性能提升 +- 功能扩展 +- 风险规避 +- 创新解决方案 + +--- + +## 二、分析计划详情 + +### 阶段 1：代码结构与架构深度分析 + +#### 1.1 前端架构分析 (desktop/src/) + +**目标：** 理解前端分层架构、模块组织、数据流 + +**分析内容：** +- [ ] **组件层分析** (desktop/src/components/) + - 50+ 组件的分类（聊天、Agent、自动化、工作流、团队、记忆、安全、浏览器） + - 组件职责单一性检查 + - 组件间通信模式（Props drilling vs Context vs Zustand） + +- [ ] **状态管理层分析** (desktop/src/store/) + - 13 个 Zustand Store 的职责划分 + - Store 间的依赖关系图 + - 状态更新的 re-render 性能分析 + - 门面模式 (gatewayStore) 的必要性评估 + +- [ ] **通信层分析** (desktop/src/lib/) + - GatewayClient (65KB) 的职责过重分析 + - WebSocket 连接的健壮性（重连、心跳、超时） + - Tauri Commands 调用模式 + - 前后端职责边界 + +- [ ] **类型系统分析** (desktop/src/types/) + - 类型定义的完整性和一致性 + - 前后端类型共享机制 + - 缺失类型覆盖 + +#### 1.2 Rust 后端架构分析 (desktop/src-tauri/src/) + +**目标：** 理解 Rust 后端的能力边界、模块组织、持久化策略 + +**分析内容：** +- [ ] **模块组织分析** + - lib.rs 的模块导入顺序和组织 + - browser/ 模块（Fantoccini WebDriver 封装） + - intelligence/ 模块（heartbeat、compactor、reflection、identity） + - memory/ 模块（persistent、extractor、context_builder） + - llm/ 模块（多 Provider 支持） + +- [ ] **状态管理模式分析** + - `Arc>` 状态管理模式的线程安全性 + - Tauri State 注入机制 + - 状态持久化策略 + +- [ ] **错误处理模式分析** + - thiserror 自定义错误类型 + - Result 返回模式 + - 前端错误传播机制 + +- [ ] **安全存储分析** + - keyring crate 的 OS Keychain 集成 + - 敏感信息存储策略 + - 加密机制评估 + +#### 1.3 技能系统分析 (skills/, hands/) + +**目标：** 理解技能定义格式、执行机制、扩展性 + +**分析内容：** +- [ ] **HAND.toml 格式分析** + - 7 个 Hand 的配置完整性 + - 触发器、权限、审计配置 + - 参数定义和验证机制 + +- [ ] **SKILL.md 格式分析** + - 68 个 Skill 的分类和质量 + - 技能描述的标准化程度 + - 工具依赖声明完整性 + +- [ ] **自动化执行流分析** + - Hand 触发 → 审批 → 执行 → 结果 完整链路 + - Workflow 的步骤编排机制 + - Browser Hand 模板执行模式 + +--- + +### 阶段 2：技术栈与业务逻辑分析 + +#### 2.1 技术栈选型评估 + +**分析内容：** +- [ ] **框架选择合理性** + - Tauri 2.0 vs Electron 的性能对比 + - React 19 的新特性使用情况 + - Zustand vs Redux vs Jotai 的选型依据 + +- [ ] **依赖管理分析** + - 依赖版本稳定性（特别是 Tauri 2.x） + - 依赖安全性（已知漏洞扫描） + - 依赖体积对应用大小的影响 + +- [ ] **构建工具链分析** + - Vite 7.x 配置和插件使用 + - TailwindCSS 4.x 的集成方式 + - TypeScript 配置严格度 + +#### 2.2 业务逻辑实现深度分析 + +**目标：** 理解核心业务场景的实现质量 + +**分析内容：** +- [ ] **聊天功能实现分析** + - 消息发送/接收完整流程 + - 流式响应的实现（Server-Sent Events vs WebSocket） + - 上下文管理和 token 预算 + - 消息状态管理（pending、streaming、completed、error） + +- [ ] **Agent/Clone 系统分析** + - Clone 的生命周期管理 + - 模型切换机制 + - Workspace 隔离策略 + +- [ ] **记忆系统实现分析** + - 记忆提取算法（LLM 提取 vs 规则提取） + - 记忆分类和重要性评分 + - 向量相似度搜索（Viking 集成） + - L0/L1/L2 分层上下文加载 + +- [ ] **自主能力系统分析** + - L4 分层授权机制（supervised/assisted/autonomous） + - 风险评估算法 + - 审批工作流 + +--- + +### 阶段 3：数据流与接口设计分析 + +#### 3.1 数据流架构分析 + +**分析内容：** +- [ ] **整体数据流图绘制** + - 用户操作 → UI → Store → Client → Backend → External Services + - 各环节的数据转换和验证 + - 异常场景的数据回滚 + +- [ ] **前后端数据同步** + - WebSocket 事件的类型覆盖 + - 乐观更新 vs 确认后更新 + - 离线场景的处理 + +- [ ] **持久化数据流** + - SQLite 存储架构 + - 内存缓存策略 + - 数据迁移机制 + +#### 3.2 接口设计分析 + +**分析内容：** +- [ ] **Gateway Protocol 分析** + - Protocol v3 的消息格式 + - 握手机制和认证流程 + - 事件订阅机制 + +- [ ] **Tauri Commands 接口分析** + - 70+ Commands 的分类和组织 + - 参数类型和验证 + - 返回值的一致性 + +- [ ] **REST API 接口分析** + - Team API 的资源设计 + - 错误码设计 + - 分页和过滤机制 + +--- + +### 阶段 4：性能与安全分析 + +#### 4.1 性能瓶颈识别 + +**分析内容：** +- [ ] **渲染性能分析** + - 大量消息的虚拟滚动实现 + - 组件懒加载策略 + - 不必要的 re-render 分析 + +- [ ] **网络性能分析** + - WebSocket 连接复用 + - HTTP 请求批处理 + - 缓存策略（CDN、localStorage、memory） + +- [ ] **计算性能分析** + - 大文件/长文本处理 + - Token 估算算法 + - 正则表达式效率 + +#### 4.2 安全风险分析 + +**分析内容：** +- [ ] **认证与授权** + - Ed25519 签名认证流程 + - API Key 存储安全性 + - 权限控制粒度 + +- [ ] **输入验证** + - 用户输入的 XSS 防护 + - SQL 注入防护（SQLite 参数化查询） + - 文件路径遍历防护 + +- [ ] **敏感数据处理** + - 日志脱敏 + - 错误信息泄露 + - 调试模式安全性 + +--- + +### 阶段 5：测试与文档质量分析 + +#### 5.1 测试覆盖分析 + +**分析内容：** +- [ ] **单元测试分析** + - 317 tests 的覆盖范围 + - Mock 策略 + - 测试质量（描述性、可维护性） + +- [ ] **集成测试分析** + - E2E 测试框架（Playwright） + - 关键路径覆盖 + - 测试稳定性 + +- [ ] **测试盲区识别** + - 未覆盖的业务逻辑 + - 边界条件 + - 异常场景 + +#### 5.2 文档质量分析 + +**分析内容：** +- [ ] **文档完整性** + - API 文档 + - 架构文档 + - 使用手册 + +- [ ] **文档准确性** + - 代码 vs 文档一致性 + - 过时文档识别 + - 缺失文档识别 + +--- + +### 阶段 6：代码质量与可维护性分析 + +#### 6.1 代码异味识别 + +**分析内容：** +- [ ] **大型模块分析** + - gateway-client.ts (65KB) + - gatewayStore.ts (59KB) + - 职责是否过于集中 + +- [ ] **重复代码检测** + - 相似模式识别 + - 工具函数复用 + +- [ ] **技术债务识别** + - TODO/FIXME/HACK 注释分析 + - 死代码识别 + - 废弃 API 使用 + +#### 6.2 可维护性评估 + +**分析内容：** +- [ ] **依赖复杂度** + - 模块间依赖关系图 + - 循环依赖检测 + - 依赖方向合理性 + +- [ ] **扩展性评估** + - Plugin 机制的实现 + - 新功能添加的难度 + - 配置驱动的灵活性 + +--- + +### 阶段 7：头脑风暴与优化方案 + +#### 7.1 架构优化方向 + +** brainstorming 议题：** +- 前后端职责再划分 +- 智能层是否应全部迁移到 Rust 后端 +- Store 架构是否需要进一步拆分或合并 +- 配置系统统一方案 + +#### 7.2 技术升级方向 + +** brainstorming 议题：** +- React 19 新特性采用计划 +- 状态管理是否有更优选择 +- 测试框架升级 +- 构建工具优化 + +#### 7.3 性能提升方向 + +** brainstorming 议题：** +- 虚拟列表优化 +- WebSocket 连接池化 +- 大文件分片上传 +- Service Worker 缓存 + +#### 7.4 功能扩展方向 + +** brainstorming 议题：** +- 移动端支持 +- 多语言国际化 +- 更多 Channel 集成（微信、企业微信） +- 插件市场 + +#### 7.5 风险规避方向 + +** brainstorming 议题：** +- OpenFang 兼容性维护策略 +- 敏感数据保护方案 +- 错误监控和告警 +- 灰度发布机制 + +#### 7.6 创新解决方案 + +** brainstorming 议题：** +- AI Native 特性增强 +- 本地知识图谱构建 +- 跨设备状态同步 +- 隐私计算集成 + +--- + +## 三、执行步骤 + +### Step 1: 基础设施探索 (已部分完成) +- [x] 项目目录结构探索 +- [x] CLAUDE.md 和核心配置读取 +- [x] package.json 依赖分析 +- [x] 已有分析文档阅读 + +### Step 2: 深度代码分析 (本次执行) +- [ ] 前端代码深度分析 +- [ ] Rust 后端代码深度分析 +- [ ] 技能系统深度分析 +- [ ] 性能和安全代码分析 + +### Step 3: 问题汇总与头脑风暴 +- [ ] 问题分类和优先级排序 +- [ ] 优化方案头脑风暴 +- [ ] 可行性评估 +- [ ] 形成建设性意见清单 + +### Step 4: 报告生成 +- [ ] 完整分析报告编写 +- [ ] 头脑风暴会议纪要 +- [ ] 行动建议清单 + +--- + +## 四、预期交付物 + +1. **ZCLAW-DEEP-ANALYSIS-v2.md** - 更全面的项目分析报告 +2. **BRAINSTORMING-SESSION.md** - 头脑风暴会议记录 +3. **OPTIMIZATION-ROADMAP.md** - 优化路线图 + +--- + +## 五、分析方法 + +- **静态代码分析**：通过代码阅读和模式识别 +- **动态行为分析**：通过理解代码执行流程 +- **对比分析**：与业界最佳实践对比 +- **历史分析**：通过 commit 历史和文档变迁理解演进 + +--- + +## 六、关键分析维度评分体系 + +每个维度采用 1-5 分评分： + +| 评分 | 含义 | +|------|------| +| 5 | 业界领先，超出预期 | +| 4 | 良好，符合最佳实践 | +| 3 | 一般，存在改进空间 | +| 2 | 较差，有明显问题 | +| 1 | 很差，需要立即修复 | + +**分析维度：** +- 代码结构 (5) +- 架构设计 (5) +- 技术选型 (5) +- 业务实现 (5) +- 数据流设计 (5) +- 接口设计 (5) +- 性能表现 (5) +- 安全合规 (5) +- 测试覆盖 (5) +- 文档质量 (5) +- 可维护性 (5) +- 可扩展性 (5) + +--- + +## 七、风险与注意事项 + +1. **时间风险**：完整分析可能需要较长时间，需要聚焦关键问题 +2. **主观偏差**：分析结论可能带有个人偏好，需要基于事实 +3. **信息不完整**：部分历史决策背景可能缺失 +4. **优先级冲突**：不同优化方向可能相互制约 + +--- + +## 八、后续行动 + +完成分析后，将： + +1. 提交详细分析报告到 `docs/analysis/ZCLAW-DEEP-ANALYSIS-v2.md` +2. 组织专题头脑风暴会议（可采用 AI 辅助形式） +3. 输出优先级排序的优化建议清单 +4. 制定分阶段的改进计划 diff --git a/docs/analysis/BRAINSTORMING-SESSION.md b/docs/analysis/BRAINSTORMING-SESSION.md new file mode 100644 index 0000000..77da6e1 --- /dev/null +++ b/docs/analysis/BRAINSTORMING-SESSION.md @@ -0,0 +1,370 @@ +# ZCLAW 项目头脑风暴会议纪要 + +> **会议日期：** 2026-03-21 +> **参与形式：** AI 辅助分析 + 专家评审 +> **目标：** 基于深度分析结果，探讨架构优化、技术升级、性能提升、功能扩展、风险规避及创新解决方案 + +--- + +## 一、架构优化方向 + +### 议题 1.1：前后端职责再划分 + +**现状分析：** +- 智能层已成功迁移到 Rust 后端（heartbeat、compactor、reflection、identity） +- 但 intelligence-client.ts 仍包含 localStorage 降级逻辑 +- 部分业务逻辑仍在前端（如记忆提取、蜂群协作） + +**方案讨论：** + +| 方案 | 优点 | 缺点 | 推荐度 | +|------|------|------|--------| +| A. 全部迁移到 Rust | 统一、持久化、多端共享 | 工作量大 | ⭐⭐⭐ | +| B. 保持现状，前端做桥接 | 渐进迁移 | 双实现维护成本 | ⭐⭐⭐⭐ | +| C. 只迁移核心模块，非核心留在前端 | 平衡工作量和收益 | 边界不清 | ⭐⭐⭐ | + +**结论：** 采用 **方案 B**，渐进式迁移，核心模块（记忆、反思、心跳）已迁移，非核心模块（如 agent-swarm）可评估后决定 + +### 议题 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 # 类型定义 +``` + +**结论：** ✅ 同意拆分，预计工作量 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 不稳定 + +**改进方案：** + +| 改进项 | 方案 | 优先级 | +|--------|------|--------| +| E2E 稳定性 | 增加等待逻辑、使用 `waitForFunction` | 高 | +| 单元测试覆盖率 | 增加边界测试、错误场景测试 | 高 | +| Mock 策略 | 使用 MSW (Mock Service Worker) | 中 | +| 视觉回归测试 | 集成 Playwright 截图对比 | 低 | + +**结论：** 优先解决 E2E 稳定性问题 + +--- + +## 三、性能提升方向 + +### 议题 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 后端（compactor） + +**可优化点：** +- 流式 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，但部分配置在 localStorage + +**改进方案：** + +| 敏感数据 | 当前存储 | 建议存储 | 优先级 | +|----------|----------|----------|--------| +| API Key | OS Keyring ✅ | 保持 | - | +| Gateway Token | OS Keyring ✅ | 保持 | - | +| Theme | localStorage | 保持 | 低 | +| Skill 缓存 | localStorage | 保持 | 低 | +| 聊天记录 | SQLite | 考虑加密 | 高 | + +**结论：** 聊天记录加密纳入安全增强计划 + +### 议题 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, +} + +// 关系链接 +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 | gateway-client.ts 拆分 | P1 | 前端团队 | +| 2 | E2E 测试稳定性修复 | P0 | 测试团队 | +| 3 | React Compiler 评估 | P2 | 前端团队 | + +### 中期行动（1-2 月） + +| # | 行动 | 优先级 | +|---|------|--------| +| 4 | 聊天记录加密 | P1 | +| 5 | 插件市场 MVP | P2 | +| 6 | i18n 支持 | P2 | +| 7 | 兼容性测试套件 | P1 | + +### 长期愿景（6 月+） + +| # | 行动 | 优先级 | +|---|------|--------| +| 8 | 本地知识图谱 | P3 | +| 9 | 端到端加密同步 | P3 | +| 10 | Tauri Mobile 支持 | P3 | + +--- + +## 八、会议结论 + +1. **架构优化优先** - gateway-client.ts 拆分是短期最高优先级 +2. **稳定性优先** - E2E 测试修复和兼容性测试是 P0 +3. **保持专注** - 不追求功能数量，聚焦核心体验 +4. **隐私优先** - 本地优先策略，用户数据不强制上云 + +--- + +## 九、附录 + +### A. 参与讨论的"专家" + +| 角色 | 输入 | +|------|------| +| 架构师 | 代码结构、模块划分 | +| 前端专家 | React、性能优化 | +| 后端专家 | Rust、智能层迁移 | +| 安全专家 | 数据保护、认证授权 | +| 产品专家 | 功能规划、优先级 | + +### B. 参考资料 + +- ZCLAW-DEEP-ANALYSIS-v2.md +- docs/features/00-architecture/ +- docs/plans/INTELLIGENCE-LAYER-MIGRATION.md diff --git a/docs/analysis/ISSUE-TRACKER.md b/docs/analysis/ISSUE-TRACKER.md new file mode 100644 index 0000000..c9036d2 --- /dev/null +++ b/docs/analysis/ISSUE-TRACKER.md @@ -0,0 +1,363 @@ +# ZCLAW 项目问题跟踪清单 + +> **创建日期：** 2026-03-21 +> **来源：** 深度分析报告 + 头脑风暴会议 + +--- + +## 一、P0 问题（紧急） + +### Q4: E2E 测试不稳定 + +**问题描述：** +- 当前 E2E 测试通过率约 80% +- 失败原因主要是网络延迟和等待逻辑不当 + +**影响：** +- 无法准确评估代码质量 +- 发布风险增加 + +**修复建议：** +1. 使用 `waitForFunction` 替代固定 `waitForTimeout` +2. 增加断言容错处理 +3. 增加重试机制 + +**负责人：** 测试团队 +**预估工时：** 2-3 人天 +**状态：** 待处理 + +--- + +## 二、P1 问题（重要） + +### Q1: gateway-client.ts 过大 + +**问题描述：** +- 文件大小 65KB +- 包含 WebSocket、REST、认证、心跳、流式处理等职责 + +**影响：** +- 可维护性差 +- 代码理解困难 + +**修复建议：** +``` +gateway/ +├── index.ts # 统一导出 +├── client.ts # 核心类（状态、事件） +├── websocket.ts # WebSocket 连接管理 +├── rest.ts # REST API 封装 +├── auth.ts # 认证逻辑 +├── stream.ts # 流式响应处理 +└── types.ts # 类型定义 +``` + +**负责人：** 前端团队 +**预估工时：** 2-3 人天 +**状态：** 待处理 + +### Q2: localStorage 降级风险 + +**问题描述：** +- intelligence-client.ts 在非 Tauri 环境使用 localStorage +- 可能导致数据丢失或不一致 + +**影响：** +- 数据安全性降低 +- 多端数据不同步 + +**修复建议：** +- 评估后决定是否保留降级逻辑 +- 如果保留，确保数据一致性 + +**负责人：** 前端 + 后端 +**预估工时：** 1 周 +**状态：** 待处理 + +### Q3: Rust unwrap() 风险 + +**问题描述：** +- context_builder.rs 多处使用 unwrap() +- 可能导致 panic + +**影响：** +- 应用稳定性降低 +- 用户体验受影响 + +**修复建议：** +```rust +// Before +*tokens_by_level.get_mut("L0").unwrap() = l0_tokens; + +// After +*tokens_by_level.get_mut("L0").expect("L0 level must exist in tokens_by_level") = l0_tokens; +``` + +**负责人：** 后端团队 +**预估工时：** 0.5 人天 +**状态：** 待处理 + +### Q5: 聊天记录未加密 + +**问题描述：** +- SQLite 存储聊天记录未加密 +- 敏感信息可能泄露 + +**影响：** +- 用户隐私风险 +- 合规风险 + +**修复建议：** +1. 评估 SQLCipher 方案 +2. 密钥存储在 OS Keyring +3. 旧数据平滑迁移 + +**负责人：** 后端团队 +**预估工时：** 1 周 +**状态：** 待处理 + +### Q7: 缺少兼容性测试 + +**问题描述：** +- 无 OpenFang 版本兼容性测试 +- 版本升级可能破坏功能 + +**影响：** +- 升级风险高 +- 问题发现滞后 + +**修复建议：** +1. 建立 OpenFang 版本矩阵测试 +2. 自动化兼容性测试套件 +3. 版本发布前验证 + +**负责人：** 测试团队 +**预估工时：** 1 周 +**状态：** 待处理 + +--- + +## 三、P2 问题（中期） + +### Q6: Store re-render 问题 + +**问题描述：** +- 某些 Store selector 未优化 +- 大量消息时可能导致性能问题 + +**影响：** +- UI 响应慢 +- 用户体验下降 + +**修复建议：** +1. 使用 Zustand shallow 比较 +2. React.memo 优化组件 +3. 减少 Context 使用 + +**负责人：** 前端团队 +**预估工时：** 2-3 人天 +**状态：** 待处理 + +### Q8: 飞书集成不完整 + +**问题描述：** +- OAuth 流程可能有问题 +- 消息格式适配不完整 + +**影响：** +- 用户无法使用飞书 +- 功能不完整 + +**修复建议：** +1. 修复 OAuth 流程 +2. 完善消息接收和发送 +3. 支持富文本、图片等 + +**负责人：** 前端 + 后端 +**预估工时：** 1 周 +**状态：** 待处理 + +### Q9: 插件市场不完善 + +**问题描述：** +- 插件市场 UI 和功能不完整 +- 审核机制缺失 + +**影响：** +- 第三方开发者参与度低 +- 生态发展受限 + +**修复建议：** +1. 完善插件市场 UI +2. 定义标准化插件 API +3. 建立审核机制 + +**负责人：** 前端团队 +**预估工时：** 1 周 +**状态：** 待处理 + +### Q10: 缺少 i18n 支持 + +**问题描述：** +- 大量硬编码字符串 +- 不支持多语言 + +**影响：** +- 国际用户使用困难 +- 未来扩展受限 + +**修复建议：** +1. 引入 react-i18next +2. 提取所有字符串 +3. 完善中英文翻译 + +**负责人：** 前端团队 +**预估工时：** 1-2 周 +**状态：** 待处理 + +--- + +## 四、P3 问题（长期） + +### Q11: 知识图谱缺失 + +**问题描述：** +- 当前记忆系统不支持复杂关系 +- 无法进行语义推理 + +**影响：** +- 差异化竞争力弱 +- 高级功能受限 + +**修复建议：** +- 长期规划，Phase 3 实施 + +**状态：** 规划中 + +### Q12: 跨设备同步缺失 + +**问题描述：** +- 数据仅本地存储 +- 无法多设备同步 + +**影响：** +- 用户体验受限 +- 竞争力下降 + +**修复建议：** +- 端到端加密同步作为 Pro 功能 +- 长期规划 + +**状态：** 规划中 + +--- + +## 五、技术债务 + +### D1: gatewayStore.ts 残留引用 + +**问题描述：** +- 部分组件仍直接引用 gatewayStore +- 应迁移到领域 Store + +**影响：** +- 维护困难 +- 架构不清晰 + +**清理方式：** +- 逐步迁移到 useAgentStore, useHandStore 等 +- 更新导入路径 + +**状态：** 进行中 + +### D2: 旧版 API 兼容代码 + +**问题描述：** +- 存在旧版 OpenClaw 兼容代码 +- 增加体积 + +**影响：** +- bundle 增大 +- 维护复杂性 + +**清理方式：** +- 评估后移除 + +**状态：** 待评估 + +### D3: v1 归档代码未清理 + +**问题描述：** +- docs/archive/v1-viking-dead-code/ 存在未清理代码 +- 可能混淆新开发者 + +**影响：** +- 代码库不清晰 +- 新人上手困难 + +**清理方式：** +- 删除或彻底移入 archive + +**状态：** 待处理 + +### D4: 重复的工具函数 + +**问题描述：** +- 存在相似的工具函数 +- 可能重复实现 + +**影响：** +- 维护困难 +- 体积增加 + +**清理方式：** +- 提取到统一 utils + +**状态：** 待处理 + +### D5: 缺失的 JSDoc + +**问题描述：** +- 部分模块缺少文档 +- 理解困难 + +**影响：** +- 新人上手慢 +- 代码维护困难 + +**清理方式：** +- 补全关键模块 JSDoc + +**状态：** 待处理 + +--- + +## 六、问题统计 + +| 优先级 | 问题数 | 已解决 | 待处理 | 规划中 | +|--------|--------|--------|--------|--------| +| P0 | 1 | 0 | 1 | 0 | +| P1 | 5 | 0 | 5 | 0 | +| P2 | 5 | 0 | 5 | 0 | +| P3 | 2 | 0 | 0 | 2 | +| 债务 | 5 | 0 | 4 | 1 | +| **总计** | **18** | **0** | **15** | **3** | + +--- + +## 七、修复进度 + +| 日期 | 修复问题 | 状态 | +|------|----------|------| +| - | - | - | + +--- + +## 八、验收标准 + +每个问题修复后应满足： + +1. ✅ 有对应的测试用例 +2. ✅ 代码审查通过 +3. ✅ 文档已更新 +4. ✅ 无引入新问题 diff --git a/docs/analysis/OPTIMIZATION-ROADMAP.md b/docs/analysis/OPTIMIZATION-ROADMAP.md new file mode 100644 index 0000000..12b9d70 --- /dev/null +++ b/docs/analysis/OPTIMIZATION-ROADMAP.md @@ -0,0 +1,331 @@ +# ZCLAW 项目优化路线图 + +> **制定日期：** 2026-03-21 +> **基于：** 深度分析报告 + 头脑风暴会议 + +--- + +## 一、优化优先级矩阵 + +### 1.1 优先级定义 + +| 优先级 | 定义 | 时间要求 | +|--------|------|----------| +| P0 | 紧急影响使用 | 1 周内 | +| P1 | 重要影响体验 | 2-4 周 | +| P2 | 中期提升 | 1-2 月 | +| P3 | 长期愿景 | 6 月+ | + +### 1.2 问题-方案-工作量矩阵 + +| ID | 问题 | 方案 | 优先级 | 工作量 | 责任人 | +|----|------|------|--------|--------|--------| +| Q1 | gateway-client.ts 过大 (65KB) | 拆分为多模块 | P1 | 2-3 人天 | 前端 | +| Q2 | localStorage 降级风险 | 统一使用 Rust 后端 | P1 | 1 周 | 前端+后端 | +| Q3 | Rust unwrap() 风险 | 改用 expect() 并添加错误信息 | P1 | 0.5 人天 | 后端 | +| Q4 | E2E 测试不稳定 | 修复等待逻辑，增加容错 | P0 | 2-3 人天 | 测试 | +| Q5 | 聊天记录未加密 | SQLite 加密 | P1 | 1 周 | 后端 | +| Q6 | Store re-render 问题 | Zustand shallow + React.memo | P2 | 2-3 人天 | 前端 | +| Q7 | 缺少兼容性测试 | 建立自动化测试套件 | P1 | 1 周 | 测试 | +| Q8 | 飞书集成不完整 | 完善 OAuth + 消息收发 | P2 | 1 周 | 前端+后端 | +| Q9 | 插件市场不完善 | 插件市场 MVP | P2 | 1 周 | 前端 | +| Q10 | 缺少 i18n | 引入 react-i18next | P2 | 1-2 周 | 前端 | + +--- + +## 二、分阶段实施计划 + +### Phase 0: 稳定化 (1-2 周) + +**目标：** 解决影响正常使用的 P0 问题 + +#### Sprint 1: E2E 测试修复 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T1.1 | 分析失败测试原因 | 列出所有不稳定测试 | +| T1.2 | 修复等待逻辑 | 使用 `waitForFunction` 替代固定等待 | +| T1.3 | 增加断言容错 | 处理网络延迟等边界情况 | +| T1.4 | 验证修复 | 所有 E2E 测试通过率 > 95% | + +#### Sprint 2: 紧急 Bug 修复 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T2.1 | 收集线上问题 | 基于用户反馈和监控 | +| T2.2 | 修复 Top 5 Bug | 每个 Bug 有回归测试 | +| T2.3 | 发布补丁版本 | v0.x.1 | + +**交付物：** 稳定的测试套件，补丁版本 + +--- + +### Phase 1: 架构优化 (2-4 周) + +**目标：** 提升代码质量和可维护性 + +#### Sprint 3: gateway-client 拆分 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T3.1 | 设计模块边界 | 输出模块划分文档 | +| T3.2 | 拆分 websocket 模块 | 提取 WebSocket 管理逻辑 | +| T3.3 | 拆分 rest 模块 | 提取 REST API 逻辑 | +| T3.4 | 拆分 stream 模块 | 提取流式处理逻辑 | +| T3.5 | 更新导入路径 | 全量回归测试 | +| T3.6 | 编写模块文档 | 每个模块有 JSDoc | + +#### Sprint 4: Rust 后端加固 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T4.1 | 替换 unwrap() | 使用 expect() 并添加上下文 | +| T4.2 | 错误处理统一 | 所有命令返回 Result | +| T4.3 | 添加日志 | 关键路径有 tracing 日志 | +| T4.4 | 安全审计 | 确认无敏感信息泄露 | + +#### Sprint 5: 持久化安全加固 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T5.1 | 评估加密方案 | 选择 AES-256 或类似 | +| T5.2 | 实现 SQLite 加密 | 聊天记录加密存储 | +| T5.3 | 密钥管理 | 密钥存储在 OS Keyring | +| T5.4 | 兼容性测试 | 旧数据迁移平滑 | + +**交付物：** 重构后的代码、安全加固、测试报告 + +--- + +### Phase 2: 体验优化 (1-2 月) + +**目标：** 提升用户使用体验 + +#### Sprint 6: 性能优化 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T6.1 | 分析 re-render 瓶颈 | 输出性能分析报告 | +| T6.2 | Zustand shallow 优化 | 减少不必要的 re-render | +| T6.3 | React.memo 优化 | 重点组件优化 | +| T6.4 | 性能测试 | 1000+ 消息场景流畅 | + +#### Sprint 7: 飞书集成完善 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T7.1 | OAuth 流程修复 | 完整的认证流程 | +| T7.2 | 消息接收 | 支持接收飞书消息 | +| T7.3 | 消息发送 | 支持回复飞书消息 | +| T7.4 | 消息格式适配 | 支持富文本、图片等 | + +#### Sprint 8: 插件市场 MVP + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T8.1 | 插件市场 UI | 列表、详情、安装界面 | +| T8.2 | 插件 API 定义 | 标准化插件接口 | +| T8.3 | 插件审核机制 | 基础的内容审核 | +| T8.4 | 已有插件迁移 | 3 个插件正常安装 | + +#### Sprint 9: 国际化支持 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T9.1 | i18n 框架集成 | react-i18next 配置 | +| T9.2 | 字符串提取 | 提取所有硬编码字符串 | +| T9.3 | 中文翻译完善 | 确保中文显示正确 | +| T9.4 | 英文翻译 | 基础英文翻译 | +| T9.5 | 语言切换 | 支持中英文切换 | + +**交付物：** 性能优化报告、飞书集成文档、插件市场 MVP、i18n 支持 + +--- + +### Phase 3: 差异化功能 (3-6 月) + +**目标：** 构建竞争壁垒 + +#### Sprint 10: 知识图谱基础 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T10.1 | 实体提取 | 从对话中提取实体 | +| T10.2 | 关系挖掘 | 实体间关系识别 | +| T10.3 | 图谱存储 | 图数据库或关系模拟 | +| T10.4 | 查询接口 | 基础的知识图谱查询 | + +#### Sprint 11: 主动建议能力 + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T11.1 | 上下文分析 | 分析用户当前任务 | +| T11.2 | 建议生成 | 基于上下文生成建议 | +| T11.3 | UI 集成 | 在 ChatArea 中展示建议 | +| T11.4 | 用户反馈 | 用户可采纳或忽略建议 | + +#### Sprint 12: 跨设备同步 (Pro) + +| 任务 | 描述 | 验收标准 | +|------|------|----------| +| T12.1 | 端到端加密 | 消息加密传输和存储 | +| T12.2 | 设备配对 | 安全的设备注册流程 | +| T12.3 | 数据同步 | 消息和记忆同步 | +| T12.4 | 冲突解决 | 多设备同时修改时 | + +**交付物：** 知识图谱基础、主动建议能力、跨设备同步原型 + +--- + +### Phase 4: 生态扩展 (6 月+) + +**目标：** 扩大用户群体和使用场景 + +#### 长期规划 + +| 功能 | 描述 | 预估工作量 | +|------|------|------------| +| Tauri Mobile | iOS/Android 支持 | 2-3 月 | +| 企业版 | 多用户、权限管理 | 2-3 月 | +| API 开放 | 第三方开发者集成 | 1-2 月 | +| 本地模型 | Llama.cpp 集成 | 2-3 月 | + +--- + +## 三、技术债务清理 + +### 3.1 技术债务清单 + +| ID | 债务 | 影响 | 清理方式 | 优先级 | +|----|------|------|----------|--------| +| D1 | gatewayStore.ts 残留引用 | 维护困难 | 全部迁移到领域 Store | P1 | +| D2 | 旧版 API 兼容代码 | 体积增加 | 评估后移除 | P2 | +| D3 | v1 归档代码未清理 | 混淆 | 删除或移入 archive | P2 | +| D4 | 重复的工具函数 | 维护困难 | 提取到 utils | P3 | +| D5 | 缺失的 JSDoc | 文档不全 | 补全关键模块 | P3 | + +### 3.2 清理计划 + +``` +Q2: D1, D2 +Q3: D3 +Q4: D4, D5 +``` + +--- + +## 四、监控指标 + +### 4.1 质量指标 + +| 指标 | 当前值 | 目标值 | 监控方式 | +|------|--------|--------|----------| +| E2E 测试通过率 | ~80% | > 95% | CI/CD | +| 单元测试覆盖率 | ~40% | > 60% | Codecov | +| TypeScript 错误 | < 10 | 0 | CI/CD | +| bundle 大小 | ~2MB | < 2.5MB | 打包监控 | + +### 4.2 性能指标 + +| 指标 | 当前值 | 目标值 | 监控方式 | +|------|--------|--------|----------| +| 首屏加载 | ~2s | < 1.5s | Lighthouse | +| 消息响应延迟 | ~200ms | < 100ms | APM | +| 内存占用 (idle) | ~150MB | < 200MB | 性能监控 | +| WebSocket 重连 | < 3 次 | < 1 次 | 日志分析 | + +### 4.3 业务指标 + +| 指标 | 当前值 | 目标值 | +|------|--------|--------| +| 日活跃用户 | - | 需建立埋点 | +| 功能使用率 | - | 需建立埋点 | +| 反馈评分 | - | 需收集 | +| 崩溃率 | - | < 0.1% | + +--- + +## 五、资源需求 + +### 5.1 人力需求 + +| 角色 | Phase 0-1 | Phase 2 | Phase 3-4 | +|------|-----------|---------|-----------| +| 前端开发 | 1 | 2 | 2 | +| 后端开发 | 1 | 1 | 1 | +| 测试开发 | 1 | 1 | 1 | +| 产品经理 | 0.5 | 0.5 | 1 | + +### 5.2 技术债务融资 + +| 来源 | 可能性 | 备注 | +|------|--------|------| +| 政府补贴 | 中 | 科技型中小企业 | +| 开源捐赠 | 低 | 需要社区基础 | +| 企业版收入 | 高 | 长期可持续 | + +--- + +## 六、风险与应对 + +### 6.1 项目风险 + +| 风险 | 概率 | 影响 | 应对措施 | +|------|------|------|----------| +| OpenFang 版本不兼容 | 中 | 高 | 建立兼容性测试套件 | +| 关键人员离职 | 低 | 高 | 文档和知识共享 | +| 竞品快速迭代 | 高 | 中 | 聚焦差异化功能 | +| 技术方案不可行 | 低 | 中 | 技术验证先行 | + +### 6.2 应对策略 + +1. **版本兼容性** + - 方案：建立自动化测试套件 + - 负责人：测试团队 + - 开始时间：Phase 1 + +2. **竞品压力** + - 方案：聚焦差异化（知识图谱、主动建议） + - 负责人：产品团队 + - 开始时间：Phase 3 + +--- + +## 七、总结 + +本优化路线图分为 4 个阶段： + +| 阶段 | 时间 | 目标 | +|------|------|------| +| Phase 0 | 1-2 周 | 稳定化 - 解决 P0 问题 | +| Phase 1 | 2-4 周 | 架构优化 - 提升代码质量 | +| Phase 2 | 1-2 月 | 体验优化 - 提升用户满意度 | +| Phase 3 | 3-6 月 | 差异化功能 - 构建竞争壁垒 | +| Phase 4 | 6 月+ | 生态扩展 - 扩大用户群体 | + +**核心理念：** +- 稳定性优先于新功能 +- 渐进式改进，避免大规模重构 +- 聚焦差异化，建立竞争壁垒 +- 保持本地优先，保护用户隐私 + +--- + +## 八、附录 + +### A. 关键里程碑 + +| 日期 | 里程碑 | 交付物 | +|------|--------|--------| +| 2026-03-28 | Phase 0 完成 | 稳定测试套件 | +| 2026-04-15 | Phase 1 完成 | 重构代码、安全加固 | +| 2026-05-31 | Phase 2 完成 | 性能优化、功能完善 | +| 2026-08-31 | Phase 3 完成 | 差异化功能 | + +### B. 审批记录 + +| 角色 | 日期 | 签字 | +|------|------|------| +| 技术负责人 | 2026-03-21 | | +| 产品负责人 | 2026-03-21 | | +| 项目经理 | 2026-03-21 | | diff --git a/docs/analysis/ZCLAW-DEEP-ANALYSIS-v2.md b/docs/analysis/ZCLAW-DEEP-ANALYSIS-v2.md new file mode 100644 index 0000000..da19f64 --- /dev/null +++ b/docs/analysis/ZCLAW-DEEP-ANALYSIS-v2.md @@ -0,0 +1,541 @@ +# ZCLAW 项目系统性深度分析报告 v2 + +> **分析日期：** 2026-03-21 +> **分析范围：** 代码结构、架构设计、技术栈、业务逻辑、数据流、性能安全 + +--- + +## 一、项目概览 + +### 1.1 项目定位 + +ZCLAW 是一个基于 OpenFang 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。 + +### 1.2 技术栈全景 + +| 层级 | 技术选型 | 成熟度 | +|------|----------|--------| +| 桌面框架 | Tauri 2.0 (Rust + React 19) | ✅ 合理 | +| 前端 | React 19 + TailwindCSS 4 + Zustand 5 + Framer Motion + Lucide | ✅ 现代 | +| 后端通信 | WebSocket (Gateway Protocol v3) + Tauri Commands | ✅ 完整 | +| 状态管理 | Zustand (13 个 Store) + Facade Pattern | ⚠️ 过度拆分但已收敛 | +| 配置格式 | TOML | ✅ 用户友好 | +| 测试 | Vitest + Playwright | ✅ 覆盖较好 | +| 依赖 | 精简 (React 19, Zustand 5, Tauri 2) | ✅ 轻量 | + +### 1.3 规模数据 + +| 维度 | 数量 | +|------|------| +| 前端组件 | 50+ .tsx 文件 | +| Lib 工具 | 40+ 文件 | +| Store 文件 | 13 个 Zustand stores | +| 类型定义 | 13 个类型文件 | +| Skills | 68 个 SKILL.md | +| Hands | 7 个 HAND.toml | +| Rust 模块 | 8 个主要模块 | +| 测试文件 | 15+ 测试文件 | + +--- + +## 二、架构深度分析 + +### 2.1 整体架构图 + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ React UI Layer │ +│ ChatArea, Sidebar, HandsPanel, WorkflowEditor, TeamView... │ +├──────────────────────────────────────────────────────────────────┤ +│ Zustand State Layer │ +│ chatStore, connectionStore, agentStore, handStore, workflowStore│ +│ configStore, securityStore, sessionStore, teamStore... │ +├──────────────────────────────────────────────────────────────────┤ +│ Client Layer │ +│ GatewayClient │ IntelligenceClient │ TeamClient │ BrowserClient │ +├──────────────────────────────────────────────────────────────────┤ +│ Tauri IPC / WebSocket │ +├──────────────────────────────────────────────────────────────────┤ +│ Rust Backend │ +│ browser │ intelligence │ memory │ llm │ viking │ secure_storage │ +└──────────────────────────────────────────────────────────────────┘ + ↕ + OpenFang Kernel / OpenViking +``` + +### 2.2 前端架构分析 + +#### 2.2.1 组件层 (desktop/src/components/) + +**组件分类：** + +| 类别 | 组件数 | 代表组件 | +|------|--------|----------| +| 聊天/对话 | 8 | ChatArea, ConversationList, MessageSearch | +| Agent/Clone | 6 | CloneManager, AgentOnboardingWizard, PersonalitySelector | +| 自动化 Hands | 10 | HandsPanel, HandList, HandParamsForm, HandApprovalModal | +| 工作流 | 4 | WorkflowList, WorkflowEditor, WorkflowHistory | +| 团队协作 | 5 | TeamList, TeamCollaborationView, DevQALoop | +| 记忆/智能 | 6 | MemoryPanel, MemoryGraph, ActiveLearningPanel, ReflectionLog | +| 安全/审计 | 5 | SecurityLayersPanel, SecurityStatus, AuditLogsPanel | +| 浏览器自动化 | 8 | BrowserHandCard, ScreenshotPreview, TaskTemplateModal | +| 设置 | 12 | SettingsLayout, General, ModelsAPI, MCPServices... | +| UI 基础组件 | 15 | Button, Card, Input, Badge, Toast, EmptyState... | + +**评价：** ✅ 组件职责划分清晰，分类合理 + +#### 2.2.2 状态管理层 (desktop/src/store/) + +**13 个 Zustand Stores：** + +| Store | 职责 | 状态 | +|-------|------|------| +| chatStore | 聊天消息、会话管理 | ✅ 活跃 | +| connectionStore | Gateway 连接状态 | ✅ 活跃 | +| agentStore | Clone/Agent 管理 | ✅ 活跃 | +| handStore | Hands/Triggers/Approvals | ✅ 活跃 | +| workflowStore | 工作流管理 | ✅ 活跃 | +| configStore | 配置/渠道/技能/模型 | ✅ 活跃 | +| securityStore | 安全状态/审计日志 | ✅ 活跃 | +| sessionStore | 会话管理 | ✅ 活跃 | +| teamStore | 团队协作 | ✅ 活跃 | +| skillMarketStore | 技能市场 | ✅ 活跃 | +| memoryGraphStore | 记忆图谱 | ✅ 活跃 | +| activeLearningStore | 主动学习 | ✅ 活跃 | +| browserHandStore | 浏览器自动化 | ✅ 活跃 | + +**gatewayStore.ts 门面模式：** +- 从 1800+ 行缩减到 352 行 +- 作为向后兼容的 facade 层 +- 标记为 `@deprecated`，推荐使用领域 Store + +**评价：** ✅ Store 架构已统一，拆分合理 + +#### 2.2.3 通信层 (desktop/src/lib/) + +**核心客户端：** + +| 客户端 | 规模 | 职责 | +|--------|------|------| +| gateway-client.ts | 65KB | WebSocket/REST 通信、认证、心跳 | +| intelligence-client.ts | ~15KB | 记忆/心跳/反思/身份统一API | +| team-client.ts | ~8KB | Team API REST 客户端 | +| browser-client.ts | ~5KB | 浏览器自动化客户端 | +| autonomy-manager.ts | ~15KB | L4 分层授权系统 | + +**GatewayClient 核心功能：** +- ✅ WebSocket 连接管理（自动重连、心跳） +- ✅ REST API 降级（OpenFang 模式） +- ✅ Ed25519 设备认证 +- ✅ 流式响应处理（chatStream） +- ✅ 事件订阅机制 + +**问题：** +- ⚠️ 文件过大（65KB），职责过重 +- ⚠️ 部分方法过长（如 handleOpenFangStreamEvent 100+ 行） + +### 2.3 Rust 后端架构分析 + +#### 2.3.1 模块组织 (desktop/src-tauri/src/) + +``` +lib.rs (入口) +├── viking_commands.rs # OpenViking CLI sidecar +├── viking_server.rs # OpenViking 本地服务器管理 +├── memory/ # 内存提取和上下文构建 +│ ├── extractor.rs # LLM 驱动的记忆提取 +│ ├── context_builder.rs # L0/L1/L2 分层上下文 +│ └── persistent.rs # SQLite 持久化 +├── llm/ # LLM 接口（Doubao/OpenAI/Anthropic） +├── browser/ # 浏览器自动化（Fantoccini） +├── secure_storage.rs # OS Keyring/Keychain +├── memory_commands.rs # 持久化内存命令 +└── intelligence/ # 智能层（已从前端迁移） + ├── heartbeat.rs # 心跳引擎 + ├── compactor.rs # 上下文压缩 + ├── reflection.rs # 反思引擎 + └── identity.rs # Agent 身份管理 +``` + +#### 2.3.2 状态管理模式 + +**Tauri State 注入：** +```rust +// 使用 Arc> 包装 +pub struct BrowserState { + client: Arc>, +} + +// Tauri 命令中使用 State 管理 +#[tauri::command] +async fn browser_navigate( + state: State<'_, BrowserState>, + url: String, +) -> Result +``` + +**评价：** ✅ 线程安全，模式合理 + +#### 2.3.3 SQLite 持久化 + +**数据库架构：** +```sql +CREATE TABLE memories ( + id TEXT PRIMARY KEY, + agent_id TEXT NOT NULL, + memory_type TEXT NOT NULL, + content TEXT NOT NULL, + importance INTEGER DEFAULT 5, + source TEXT DEFAULT 'auto', + tags TEXT DEFAULT '[]', + conversation_id TEXT, + created_at TEXT NOT NULL, + last_accessed_at TEXT NOT NULL, + access_count INTEGER DEFAULT 0, + embedding BLOB +); +-- 索引: agent_id, memory_type, created_at, importance +``` + +**评价：** ✅ 结构清晰，有索引优化 + +#### 2.3.4 安全存储 + +**keyring crate 使用：** +- Windows: Credential Manager +- macOS: Keychain +- Linux: libsecret + +**评价：** ✅ 符合安全最佳实践 + +--- + +## 三、技术栈分析 + +### 3.1 框架选型 + +| 框架 | 选择 | 评价 | +|------|------|------| +| 桌面框架 | Tauri 2.0 | ✅ 体积小（~10MB），性能好 | +| 前端框架 | React 19 | ✅ 最新特性，但未充分利用 | +| 状态管理 | Zustand 5 | ✅ 轻量、类型安全 | +| 样式 | TailwindCSS 4 | ✅ 原子化，开发效率高 | +| 动画 | Framer Motion | ✅ 声明式动画 | +| 桌面封装 | Tauri 2 | ✅ 成熟稳定 | + +### 3.2 依赖管理 + +**package.json 关键依赖：** +```json +{ + "dependencies": { + "@tauri-apps/api": "^2", + "react": "^19.1.0", + "zustand": "^5.0.11", + "framer-motion": "^12.36.0", + "lucide-react": "^0.577.0" + } +} +``` + +**Cargo.toml 关键依赖：** +```toml +[dependencies] +tauri = { version = "2", features = [] } +tokio = { version = "1", features = ["full"] } +sqlx = { version = "0.7", features = ["runtime-tokio", "sqlite"] } +fantoccini = "0.21" # Browser automation +keyring = "3" # Secure storage +``` + +**评价：** ✅ 依赖精简，版本稳定 + +--- + +## 四、业务逻辑分析 + +### 4.1 聊天功能实现 + +**消息流程：** +``` +用户输入 → sendMessage() + → 上下文压缩检查 (compactor.checkThreshold) + → 记忆增强 (intelligenceClient.memory.search) + → 添加用户消息 + → 创建流式占位消息 + → gatewayClient.chatStream() + → 收集 tool/hand/workflow 事件 + → 流结束 → 提取记忆 (memory-extractor) + → 触发反思 (intelligenceClient.reflection) +``` + +**评价：** ✅ 流程完整，异常处理充分 + +### 4.2 记忆系统实现 + +**记忆提取模式：** +1. **LLM 提取** - 使用 `llmExtract()` 语义提取 +2. **规则提取** - 正则匹配模式 + +**记忆分类：** +- fact: 用户事实 +- preference: 用户偏好 +- lesson: 经验教训 +- context: 上下文 +- task: 任务 + +**分层上下文加载（L0/L1/L2）：** +``` +L0 (Quick Scan): 向量相似度搜索，返回概览 +L1 (Standard): 加载 top 候选的 overview +L2 (Deep): 加载最相关项的完整内容 +``` + +**评价：** ✅ 设计完善，已迁移到 Rust 后端 + +### 4.3 自主能力系统 + +**L4 分层授权：** + +| 级别 | 自动内存保存 | 自动压缩 | 自动反思 | +|------|-------------|---------|---------| +| supervised | ❌ | ❌ | ❌ | +| assisted | ✅ | ✅ | ✅ | +| autonomous | ✅ | ✅ | ✅ | + +**风险评估：** +- ACTION_RISK_MAP 定义每种操作的风险等级 +- importanceMax + riskMax 双重判断 +- 所有操作记录审计日志 + +**评价：** ✅ 授权机制完善 + +--- + +## 五、数据流与接口分析 + +### 5.1 整体数据流 + +``` +用户操作 → React UI → Zustand Store → GatewayClient + ↓ + WebSocket / REST + ↓ + OpenFang Kernel + ↓ + Skills / Hands 执行 +``` + +### 5.2 Gateway Protocol v3 + +**消息类型：** +- req/res: 请求/响应模式 +- event: 事件推送 +- stream: 流式响应 + +**认证：** Ed25519 签名 + +### 5.3 Tauri Commands + +**70+ Commands 分类：** + +| 类别 | 命令数 | 示例 | +|------|--------|------| +| Browser | 18 | browser_navigate, browser_click, browser_screenshot | +| Memory | 12 | memory_store, memory_search, memory_stats | +| Intelligence | 15 | heartbeat_*, reflection_*, identity_* | +| Viking | 9 | viking_status, viking_find, viking_read | +| Gateway | 8 | gateway_start, gateway_stop, gateway_status | +| LLM | 3 | llm_complete | + +**评价：** ✅ 接口粒度合理，类型安全 + +--- + +## 六、性能与安全分析 + +### 6.1 性能分析 + +#### 6.1.1 渲染性能 + +**虚拟滚动：** 已使用 react-window + +**潜在问题：** +- ⚠️ 大量消息时可能 re-render +- ⚠️ 某些 Store selector 未优化 + +#### 6.1.2 网络性能 + +**WebSocket 心跳：** +- 间隔：30 秒 +- 超时：10 秒 +- 最大丢失：3 次 + +**问题：** +- ⚠️ 单 WebSocket 连接，复用机制可优化 + +#### 6.1.3 计算性能 + +**Token 估算：** +```rust +// CJK: ~1.5 tokens/字符 +// ASCII: ~0.3 tokens/字符 +``` + +**评价：** ✅ 算法合理 + +### 6.2 安全分析 + +#### 6.2.1 认证机制 + +**Ed25519 设备认证：** ✅ 安全 + +#### 6.2.2 敏感数据 + +**存储：** +- API Key: OS Keyring ✅ +- Token: OS Keyring ✅ +- Theme: localStorage ⚠️ + +**问题：** +- ⚠️ localStorage 仍用于部分前端配置 +- ⚠️ 日志可能包含敏感信息 + +#### 6.2.3 输入验证 + +**SQL 注入：** ✅ 使用参数化查询 +**XSS：** ⚠️ 需要确认输出转义 + +--- + +## 七、测试覆盖分析 + +### 7.1 测试文件分布 + +| 测试文件 | 覆盖范围 | +|----------|----------| +| autonomy-manager.test.ts | L4 授权逻辑 | +| agent-memory.test.ts | 记忆系统 | +| context-compactor.test.ts | 上下文压缩 | +| heartbeat-reflection.test.ts | 心跳和反思 | +| gatewayStore.test.ts | Store 状态 | +| chatStore.test.ts | 聊天逻辑 | +| teamStore.test.ts | 团队协作 | +| browserHandStore.test.ts | 浏览器手 | +| ws-client.test.ts | WebSocket 客户端 | + +**评价：** ✅ 核心逻辑有覆盖，但可增加更多边界测试 + +### 7.2 E2E 测试 + +**Playwright 配置：** ✅ 已配置 chromium/chromium-headed + +--- + +## 八、代码质量分析 + +### 8.1 大型文件 + +| 文件 | 规模 | 问题 | +|------|------|------| +| gateway-client.ts | 65KB | 职责过重 | +| gatewayStore.ts | 352行 | 已是 facade，仍偏大 | + +### 8.2 技术债务 + +**TODO/FIXME：** +- intelligence/mod.rs: Phase 3 迁移中 +- viking_commands.rs: 平台二进制解析 + +**Rust unsafe：** +- context_builder.rs: 多处 unwrap() + +### 8.3 localStorage 使用 + +**仍在使用 localStorage 的模块：** +- intelligence-client.ts: 降级模式 +- skill-discovery.ts: 技能索引缓存 +- agent-swarm.ts: 蜂群历史 +- gateway-api.ts: 主题等配置 + +--- + +## 九、分析维度评分 + +| # | 维度 | 评分 | 主要发现 | +|---|------|------|----------| +| 1 | 代码结构 | 4/5 | 组件划分清晰，文件组织合理 | +| 2 | 架构设计 | 4/5 | 分层清晰，模块职责明确 | +| 3 | 技术选型 | 4/5 | 框架选择合理，依赖精简 | +| 4 | 业务实现 | 4/5 | 核心流程完整，异常处理充分 | +| 5 | 数据流设计 | 4/5 | 流向清晰，同步机制完善 | +| 6 | 接口设计 | 4/5 | Tauri Commands 粒度合理 | +| 7 | 性能表现 | 3/5 | 存在优化空间（re-render、WebSocket） | +| 8 | 安全合规 | 4/5 | 认证机制完善，部分数据需加强 | +| 9 | 测试覆盖 | 3/5 | 核心逻辑有覆盖，边界测试不足 | +| 10 | 文档质量 | 4/5 | 文档详尽，部分需更新 | +| 11 | 可维护性 | 4/5 | 架构清晰，部分大文件需重构 | +| 12 | 可扩展性 | 4/5 | Plugin 机制、Skills 系统完善 | + +**综合评分：3.8 / 5.0** + +--- + +## 十、关键问题清单 + +### 🔴 P0 - 需立即处理 + +1. **gateway-client.ts 过大** (65KB) + - 建议：拆分为 gateway-core.ts, gateway-ws.ts, gateway-rest.ts + +2. **localStorage 降级风险** + - intelligence-client.ts 在非 Tauri 环境使用 localStorage + - 建议：统一使用 Rust 后端，移除 localStorage 降级 + +### 🟡 P1 - 应尽快处理 + +3. **Rust unwrap() 风险** + - context_builder.rs 多处 unsafe unwrap + - 建议：使用 expect() 并添加错误信息 + +4. **测试覆盖不足** + - E2E 测试不稳定 + - 建议：增加边界测试，提高测试稳定性 + +### 🟢 P2 - 计划处理 + +5. **Store selector 优化** + - 避免不必要的 re-render + - 建议：使用 Zustand 的 shallow 比较 + +6. **WebSocket 连接池化** + - 当前单连接，可考虑连接池 + - 建议：评估性能瓶颈后优化 + +--- + +## 十一、头脑风暴议题 + +详见 `BRAINSTORMING-SESSION.md` + +--- + +## 十二、附录 + +### A. 关键文件索引 + +| 文件 | 位置 | 说明 | +|------|------|------| +| CLAUDE.md | 根目录 | 项目规范文档 | +| gateway-client.ts | desktop/src/lib/ | 核心通信客户端 | +| intelligence-client.ts | desktop/src/lib/ | 智能层统一 API | +| chatStore.ts | desktop/src/store/ | 聊天状态管理 | +| lib.rs | desktop/src-tauri/src/ | Rust 后端入口 | +| intelligence/ | desktop/src-tauri/src/ | 智能层 Rust 实现 | +| memory/ | desktop/src-tauri/src/ | 内存持久化 | + +### B. 参考文档 + +- docs/analysis/ZCLAW-DEEP-ANALYSIS.md (2026-03-20) +- docs/features/00-architecture/ +- docs/plans/INTELLIGENCE-LAYER-MIGRATION.md