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