iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
820e3a1ffe7bb658da7840d192f64999e8611e26
zclaw_openfang/docs/analysis/OPTIMIZATION-ROADMAP.md
iven e5cdd36118 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
2026-03-21 16:16:16 +08:00

332 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 | |
Reference in New Issue View Git Blame Copy Permalink