zclaw_openfang/docs/analysis/ISSUE-TRACKER.md

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

影响：

• 应用稳定性降低
• 用户体验受影响

修复建议：

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