0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
364 lines
6.6 KiB
Markdown
364 lines
6.6 KiB
Markdown
# 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: 缺少兼容性测试
|
||
|
||
**问题描述：**
|
||
- 无 ZCLAW 版本兼容性测试
|
||
- 版本升级可能破坏功能
|
||
|
||
**影响：**
|
||
- 升级风险高
|
||
- 问题发现滞后
|
||
|
||
**修复建议：**
|
||
1. 建立 ZCLAW 版本矩阵测试
|
||
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 兼容代码
|
||
|
||
**问题描述：**
|
||
- 存在旧版 ZCLAW 兼容代码
|
||
- 增加体积
|
||
|
||
**影响：**
|
||
- 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. ✅ 无引入新问题
|