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 清理计划
四、监控指标
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 应对策略
-
版本兼容性
- 方案：建立自动化测试套件
- 负责人：测试团队
- 开始时间：Phase 1
-
竞品压力
- 方案：聚焦差异化（知识图谱、主动建议）
- 负责人：产品团队
- 开始时间：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 |
|
e5cdd36118