docs: Add comprehensive project analysis and brainstorming session documents

- ZCLAW-DEEP-ANALYSIS-v2.md: Complete analysis covering 12 dimensions
- BRAINSTORMING-SESSION.md: Brainstorming notes on architecture, tech, performance
- OPTIMIZATION-ROADMAP.md: 4-phase implementation plan
- ISSUE-TRACKER.md: 18 issues tracked with priorities
- project-systematic-analysis-plan.md: Analysis plan document

.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<Mutex<T>>` 状态管理模式的线程安全性
+  - Tauri State 注入机制
+  - 状态持久化策略
+
+- [ ] **错误处理模式分析**
+  - thiserror 自定义错误类型
+  - Result<T, String> 返回模式
+  - 前端错误传播机制
+
+- [ ] **安全存储分析**
+  - 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. 制定分阶段的改进计划