iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: Add comprehensive project analysis and brainstorming session documents

Browse Source 
- 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
This commit is contained in:
iven
2026-03-21 16:16:16 +08:00
parent 1900abe152
commit e5cdd36118
5 changed files with 2058 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
docs/analysis/BRAINSTORMING-SESSION.md Normal file
View File

@@ -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<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 | 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

363
docs/analysis/ISSUE-TRACKER.md Normal file
View File

@@ -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. ✅ 无引入新问题

331
docs/analysis/OPTIMIZATION-ROADMAP.md Normal file
View File

@@ -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<T, String> |
| 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 | |

541
docs/analysis/ZCLAW-DEEP-ANALYSIS-v2.md Normal file
View File

@@ -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<Mutex<T>> 包装
pub struct BrowserState {
client: Arc<RwLock<BrowserClient>>,
}
// Tauri 命令中使用 State 管理
#[tauri::command]
async fn browser_navigate(
state: State<'_, BrowserState>,
url: String,
) -> Result<String, String>
```
**评价：** ✅ 线程安全，模式合理
#### 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