iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: reorganize docs — archive outdated, create brainstorming folder
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details

Browse Source 
- Create docs/brainstorming/ with 5 discussion records (Mar 16 - Apr 7)
- Archive ~30 outdated audit reports (V5-V11) to docs/archive/old-audits/
- Archive superseded analysis docs to docs/archive/old-analysis/
- Archive completed session plans to docs/archive/old-plans/
- Archive old test reports/validations to respective archive folders
- Remove empty directories left after moves
- Keep current docs: TRUTH.md, feature docs, deployment, knowledge-base, superpowers
This commit is contained in:
iven
2026-04-07 09:54:30 +08:00
parent 8e9fc54d92
commit 2e5f63be32
101 changed files with 1829 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
docs/archive/old-analysis/BRAINSTORMING-SESSION-v2.md Normal file
View File

@@ -0,0 +1,387 @@
# ZCLAW 项目头脑风暴会议纪要 v2
> **会议日期：** 2026-03-21
> **基于：** 系统性深度分析报告
> **目标：** 针对分析结果进行深入探讨，提出建设性意见和可行性方案
---
## 参会专家角色
| 角色 | 职责 | 输入领域 |
|------|------|----------|
| 系统架构师 | 整体架构评估 | 代码结构、模块划分 |
| 前端技术专家 | 前端架构优化 | React、性能优化 |
| 后端技术专家 | 后端架构优化 | Rust、智能层 |
| 安全专家 | 安全合规评估 | 数据保护、认证授权 |
| 产品专家 | 功能规划 | 用户价值、优先级 |
---
## 议题一：架构优化方向
### 1.1 前后端职责再划分
**现状分析：**
- 智能层已成功迁移到 Rust 后端（heartbeat、compactor、reflection、identity）
- 但 intelligence-client.ts 仍包含 localStorage 降级逻辑
- 部分业务逻辑仍在前端（agent-swarm、active-learning）
**方案讨论：**
| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| A. 全部迁移到 Rust | 统一、持久化、多端共享 | 工作量大 | ⭐⭐⭐ |
| B. 保持现状，前端做桥接 | 渐进迁移 | 双实现维护成本 | ⭐⭐⭐⭐ |
| C. 只迁移核心模块 | 平衡工作量和收益 | 边界不清 | ⭐⭐⭐ |
**结论：** 采用 **方案 B**，渐进式迁移
- 核心模块（记忆、反思、心跳）已迁移 ✅
- 非核心模块（agent-swarm、active-learning）可评估后决定
### 1.2 gateway-client.ts 拆分
**现状：** 65KB 单文件，包含 WebSocket、REST、认证、心跳、流式处理
**拆分方案：**
```
gateway/
├── index.ts # 统一导出
├── client.ts # 核心类（状态、事件）
├── websocket.ts # WebSocket 连接管理
├── rest.ts # REST API 封装
├── auth.ts # 认证逻辑
├── stream.ts # 流式响应处理
└── types.ts # 类型定义
```
**实施计划：**
- **优先级：** P1
- **工作量：** 2-3 人天
- **风险：** 低（已有模块边界）
**结论：** ✅ 同意拆分
---
## 议题二：技术升级方向
### 2.1 React 19 新特性采用
**现状：** 使用 React 19，但未充分利用新特性
**可采用的新特性：**
| 特性 | 适用场景 | 收益 | 优先级 |
|------|----------|------|--------|
| use() Hook | Store 读取 | 简化代码 | 中 |
| React Compiler | 全局 | 性能优化 | 高 |
| Document Metadata | SEO/Head | 简化元数据管理 | 低 |
| Third-party Hooks | 库集成 | 更好的兼容性 | 中 |
**结论：** 评估 React Compiler，优先在性能敏感组件试用
### 2.2 状态管理评估
**现状：** Zustand 5
**评估：**
- Zustand 5 已支持更多中间件
- 考虑迁移到 @preact/signals 或 Jotai？
**结论：** 保持 Zustand 5，聚焦功能开发
### 2.3 测试框架增强
**现状：** Vitest + Playwright，但 E2E 不稳定 (~80% 通过率)
**改进方案：**
| 改进项 | 方案 | 优先级 |
|--------|------|--------|
| E2E 稳定性 | 增加等待逻辑、使用 `waitForFunction` | P0 |
| 单元测试覆盖率 | 增加边界测试、错误场景测试 | P1 |
| Mock 策略 | 使用 MSW (Mock Service Worker) | P2 |
| 视觉回归测试 | 集成 Playwright 截图对比 | P3 |
**结论：** 优先解决 E2E 稳定性问题 (P0)
---
## 议题三：性能提升方向
### 3.1 渲染性能优化
**问题：** 大量消息时可能 re-render
**方案：**
| 方案 | 实施难度 | 收益 | 推荐度 |
|------|----------|------|--------|
| A. Zustand shallow 比较 | 低 | 中 | ⭐⭐⭐⭐ |
| B. React.memo 优化组件 | 中 | 高 | ⭐⭐⭐⭐⭐ |
| C. 虚拟列表优化 | 中 | 高 | ⭐⭐⭐⭐ |
| D. 减少 Context 使用 | 低 | 中 | ⭐⭐⭐ |
**结论：** 组合实施 A + B + D，重点优化 ChatArea 和 MessageList
### 3.2 网络性能优化
**问题：** 单 WebSocket 连接
**方案：**
| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| A. WebSocket 连接池 | 并发请求 | 实现复杂度高 | ⭐⭐ |
| B. HTTP/2 多路复用 | 标准方案 | 需要后端支持 | ⭐⭐⭐ |
| C. 请求合并 | 减少请求数 | 增加延迟 | ⭐⭐⭐ |
| D. 保持现状 | 简单 | - | ⭐⭐⭐⭐⭐ |
**结论：** 保持现状，当前连接数不是瓶颈
### 3.3 大文件/长文本处理
**现状：** Token 估算和压缩已迁移到 Rust 后端
**可优化点：**
- 流式 token 计数
- 增量压缩
- 智能摘要生成
**结论：** 当前实现已满足需求，持续观察
---
## 议题四：功能扩展方向
### 4.1 移动端支持
**评估：**
| 方案 | 技术选型 | 工作量 | 推荐度 |
|------|----------|--------|--------|
| A. React Native | 跨平台 | 大 | ⭐⭐ |
| B. Tauri Mobile | Tauri 生态 | 中 | ⭐⭐⭐⭐ |
| C. Flutter | 独立生态 | 大 | ⭐⭐ |
| D. 暂不开发 | - | - | ⭐⭐⭐⭐⭐ |
**结论：** 评估 Tauri Mobile，但优先级低于核心功能
### 4.2 国际化 (i18n)
**现状：** 中文优先，但硬编码字符串存在
**方案：**
```typescript
// 使用 react-i18next
i18n.t('chat.placeholder')
i18n.t('hand.trigger', { name })
```
**工作量：** 约 1-2 周
**结论：** 建议在下一版本规划中纳入
### 4.3 更多 Channel 集成
**当前：** 飞书 (Feishu)
**可扩展：**
| Channel | 需求度 | 技术难度 | 优先级 |
|---------|--------|----------|--------|
| 企业微信 | 高 | 高 | 中 |
| 钉钉 | 中 | 高 | 低 |
| Discord | 中 | 中 | 中 |
| Telegram | 低 | 低 | 中 |
**结论：** 优先完善飞书集成，评估 Discord
### 4.4 插件市场
**现状：** 3 个插件 (chinese-models, feishu, ui)
**方案：**
| 阶段 | 内容 | 工作量 |
|------|------|--------|
| Phase 1 | 插件市场 UI + 基础 API | 1 周 |
| Phase 2 | 插件审核机制 | 1 周 |
| Phase 3 | 付费插件支持 | 2 周 |
**结论：** 作为差异化竞争力，纳入中期规划
---
## 议题五：风险规避方向
### 5.1 ZCLAW 兼容性维护
**风险：** ZCLAW 版本升级可能导致兼容性问题
**方案：**
| 方案 | 实施难度 | 保护程度 |
|------|----------|----------|
| A. 版本锁定 | 低 | 弱 |
| B. 兼容层抽象 | 中 | 中 |
| C. 自动化兼容性测试 | 高 | 强 |
| D. 参与 ZCLAW 开发 | 高 | 最强 |
**结论：** 实施 B + C，建立兼容性测试套件
### 5.2 敏感数据保护
**现状：** API Key 使用 OS Keyring，但聊天记录未加密
**改进方案：**
| 敏感数据 | 当前存储 | 建议存储 | 优先级 |
|----------|----------|----------|--------|
| API Key | OS Keyring ✅ | 保持 | - |
| Gateway Token | OS Keyring ✅ | 保持 | - |
| 聊天记录 | SQLite | 加密存储 | P1 |
| Theme | localStorage | 保持 | 低 |
**结论：** 聊天记录加密纳入安全增强计划
### 5.3 灰度发布机制
**现状：** 无灰度发布
**方案：**
| 方案 | 工具 | 工作量 |
|------|------|--------|
| A. Tauri 内置更新 | tauri-plugin-updater | 1 天 |
| B. 手动版本管理 | - | 0 |
| C. 自动化灰度 | 定制开发 | 1 周 |
**结论：** 集成 Tauri 内置更新机制
---
## 议题六：创新解决方案
### 6.1 AI Native 特性增强
**想法：**
| 特性 | 描述 | 创新度 |
|------|------|--------|
| 自适应上下文 | 根据任务类型自动调整上下文长度 | ⭐⭐⭐ |
| 智能缓存 | 预测用户意图，预加载资源 | ⭐⭐⭐ |
| 多模态交互 | 支持图片、语音输入 | ⭐⭐ |
| 主动建议 | 基于上下文主动提供建议 | ⭐⭐⭐⭐ |
**结论：** 优先实现"主动建议"作为差异化功能
### 6.2 本地知识图谱构建
**想法：**
- 将记忆系统升级为知识图谱
- 实体关系挖掘
- 语义推理能力
**技术路径：**
```rust
// 实体提取
struct Entity {
name: String,
type: EntityType,
properties: HashMap<String, Value>,
}
// 关系链接
struct Relation {
from: EntityId,
to: EntityId,
relation_type: String,
confidence: f32,
}
```
**结论：** 长期规划，与 OpenViking 深度集成
### 6.3 跨设备状态同步
**问题：** 当前数据仅本地存储
**方案：**
| 方案 | 复杂度 | 隐私性 | 推荐度 |
|------|--------|--------|--------|
| A. 云端同步 | 高 | 低 | ⭐⭐ |
| B. 端到端加密同步 | 高 | 高 | ⭐⭐⭐⭐ |
| C. 文件导入/导出 | 低 | 最高 | ⭐⭐⭐⭐ |
| D. 保持本地优先 | - | - | ⭐⭐⭐⭐⭐ |
**结论：** 提供端到端加密同步作为 Pro 功能
### 6.4 隐私计算集成
**想法：**
- 本地模型推理（Llama.cpp 集成）
- 联邦学习支持
- 数据不出本机
**结论：** 长期愿景，需要大量研发投入
---
## 行动建议总结
### 短期行动（1-2 周）
| # | 行动 | 优先级 | 负责人 | 工作量 |
|---|------|--------|--------|--------|
| 1 | E2E 测试稳定性修复 | P0 | 测试团队 | 2-3 人天 |
| 2 | gateway-client.ts 拆分 | P1 | 前端团队 | 2-3 人天 |
| 3 | Rust unwrap() 替换 | P1 | 后端团队 | 0.5 人天 |
### 中期行动（1-2 月）
| # | 行动 | 优先级 | 工作量 |
|---|------|--------|--------|
| 4 | 聊天记录加密 | P1 | 1 周 |
| 5 | 插件市场 MVP | P2 | 1 周 |
| 6 | i18n 支持 | P2 | 1-2 周 |
| 7 | 兼容性测试套件 | P1 | 1 周 |
| 8 | 性能优化 (re-render) | P2 | 2-3 人天 |
### 长期愿景（6 月+）
| # | 行动 | 优先级 |
|---|------|--------|
| 9 | 本地知识图谱 | P3 |
| 10 | 端到端加密同步 | P3 |
| 11 | Tauri Mobile 支持 | P3 |
| 12 | 主动建议能力 | P2 |
---
## 会议结论
1. **架构优化优先** - gateway-client.ts 拆分是短期最高优先级
2. **稳定性优先** - E2E 测试修复和兼容性测试是 P0
3. **保持专注** - 不追求功能数量，聚焦核心体验
4. **隐私优先** - 本地优先策略，用户数据不强制上云
5. **渐进改进** - 避免大规模重构，采用渐进式优化
---
## 关键决策记录
| 决策项 | 决策结果 | 理由 |
|--------|----------|------|
| 前后端职责划分 | 渐进迁移 | 平衡工作量和收益 |
| 状态管理 | 保持 Zustand 5 | 聚焦功能开发 |
| 移动端 | 暂不开发 | 优先级低于核心功能 |
| 国际化 | 下一版本纳入 | 1-2 周工作量 |
| 聊天记录 | 加密存储 | 保护用户隐私 |
| 跨设备同步 | Pro 功能 | 端到端加密 |
---
*会议纪要完成*

370
docs/archive/old-analysis/BRAINSTORMING-SESSION.md Normal file
View File

@@ -0,0 +1,370 @@
# ZCLAW 项目头脑风暴会议纪要
> **会议日期：** 2026-03-21
> **参与形式：** AI 辅助分析 + 专家评审
> **目标：** 基于深度分析结果，探讨架构优化、技术升级、性能提升、功能扩展、风险规避及创新解决方案
---
## 一、架构优化方向
### 议题 1.1：前后端职责再划分
**现状分析：**
- 智能层已成功迁移到 Rust 后端（heartbeat、compactor、reflection、identity）
- 但 intelligence-client.ts 仍包含 localStorage 降级逻辑
- 部分业务逻辑仍在前端（如记忆提取、蜂群协作）
**方案讨论：**
| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| A. 全部迁移到 Rust | 统一、持久化、多端共享 | 工作量大 | ⭐⭐⭐ |
| B. 保持现状，前端做桥接 | 渐进迁移 | 双实现维护成本 | ⭐⭐⭐⭐ |
| C. 只迁移核心模块，非核心留在前端 | 平衡工作量和收益 | 边界不清 | ⭐⭐⭐ |
**结论：** 采用 **方案 B**，渐进式迁移，核心模块（记忆、反思、心跳）已迁移，非核心模块（如 agent-swarm）可评估后决定
### 议题 1.2：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 天
---
## 二、技术升级方向
### 议题 2.1：React 19 新特性采用
**现状：** 使用 React 19，但未利用新特性
**可采用的新特性：**
| 特性 | 适用场景 | 收益 | 优先级 |
|------|----------|------|--------|
| use() Hook | Store 读取 | 简化代码 | 中 |
| React Compiler | 全局 | 性能优化 | 高 |
| Document Metadata | SEO/Head | 简化元数据管理 | 低 |
| Third-party Hooks | 库集成 | 更好的兼容性 | 中 |
**结论：** 评估 React Compiler，优先在性能敏感组件试用
### 议题 2.2：状态管理是否升级
**现状：** Zustand 5
**评估：**
- Zustand 5 已支持更多中间件
- 考虑迁移到 @preact/signals 或 Jotai？
- **结论：** 保持 Zustand 5，聚焦功能开发
### 议题 2.3：测试框架增强
**现状：** Vitest + Playwright，但 E2E 不稳定
**改进方案：**
| 改进项 | 方案 | 优先级 |
|--------|------|--------|
| E2E 稳定性 | 增加等待逻辑、使用 `waitForFunction` | 高 |
| 单元测试覆盖率 | 增加边界测试、错误场景测试 | 高 |
| Mock 策略 | 使用 MSW (Mock Service Worker) | 中 |
| 视觉回归测试 | 集成 Playwright 截图对比 | 低 |
**结论：** 优先解决 E2E 稳定性问题
---
## 三、性能提升方向
### 议题 3.1：渲染性能优化
**问题：** 大量消息时可能 re-render
**方案：**
| 方案 | 实施难度 | 收益 | 推荐度 |
|------|----------|------|--------|
| A. Zustand shallow 比较 | 低 | 中 | ⭐⭐⭐⭐ |
| B. React.memo 优化组件 | 中 | 高 | ⭐⭐⭐⭐⭐ |
| C. 虚拟列表优化 | 中 | 高 | ⭐⭐⭐⭐ |
| D. 减少 Context 使用 | 低 | 中 | ⭐⭐⭐ |
**结论：** 组合实施 A + B + D，重点优化 ChatArea 和 MessageList
### 议题 3.2：网络性能优化
**问题：** 单 WebSocket 连接
**方案：**
| 方案 | 优点 | 缺点 | 推荐度 |
|------|------|------|--------|
| A. WebSocket 连接池 | 并发请求 | 实现复杂度高 | ⭐⭐ |
| B. HTTP/2 多路复用 | 标准方案 | 需要后端支持 | ⭐⭐⭐ |
| C. 请求合并 | 减少请求数 | 增加延迟 | ⭐⭐⭐ |
| D. 保持现状 | 简单 | - | ⭐⭐⭐⭐⭐ |
**结论：** 保持现状，当前连接数不是瓶颈
### 议题 3.3：大文件/长文本处理
**问题：** Token 估算和压缩
**当前实现：** ✅ 已迁移到 Rust 后端（compactor）
**可优化点：**
- 流式 token 计数
- 增量压缩
- 智能摘要生成
**结论：** 当前实现已满足需求，持续观察
---
## 四、功能扩展方向
### 议题 4.1：移动端支持
**评估：**
| 方案 | 技术选型 | 工作量 | 推荐度 |
|------|----------|--------|--------|
| A. React Native | 跨平台 | 大 | ⭐⭐ |
| B. Tauri Mobile | Tauri 生态 | 中 | ⭐⭐⭐⭐ |
| C. Flutter | 独立生态 | 大 | ⭐⭐ |
| D. 暂不开发 | - | - | ⭐⭐⭐⭐⭐ |
**结论：** 评估 Tauri Mobile，但优先级低于核心功能
### 议题 4.2：国际化 (i18n)
**现状：** 中文优先，但硬编码字符串存在
**方案：**
```typescript
// 使用 react-i18next
i18n.t('chat.placeholder')
i18n.t('hand.trigger', { name })
```
**工作量：** 约 1-2 周
**结论：** 建议在下一版本规划中纳入
### 议题 4.3：更多 Channel 集成
**当前：** 飞书 (Feishu)
**可扩展：**
| Channel | 需求度 | 技术难度 | 优先级 |
|---------|--------|----------|--------|
| 企业微信 | 高 | 高 | 中 |
| 钉钉 | 中 | 高 | 低 |
| Discord | 中 | 中 | 中 |
| Telegram | 低 | 低 | 中 |
**结论：** 优先完善飞书集成，评估 Discord
### 议题 4.4：插件市场
**现状：** 3 个插件 (chinese-models, feishu, ui)
**方案：**
| 阶段 | 内容 | 工作量 |
|------|------|--------|
| Phase 1 | 插件市场 UI + 基础 API | 1 周 |
| Phase 2 | 插件审核机制 | 1 周 |
| Phase 3 | 付费插件支持 | 2 周 |
**结论：** 作为差异化竞争力，纳入中期规划
---
## 五、风险规避方向
### 议题 5.1：ZCLAW 兼容性维护
**风险：** ZCLAW 版本升级可能导致兼容性问题
**方案：**
| 方案 | 实施难度 | 保护程度 |
|------|----------|----------|
| A. 版本锁定 | 低 | 弱 |
| B. 兼容层抽象 | 中 | 中 |
| C. 自动化兼容性测试 | 高 | 强 |
| D. 参与 ZCLAW 开发 | 高 | 最强 |
**结论：** 实施 B + C，建立兼容性测试套件
### 议题 5.2：敏感数据保护
**现状：** API Key 使用 OS Keyring，但部分配置在 localStorage
**改进方案：**
| 敏感数据 | 当前存储 | 建议存储 | 优先级 |
|----------|----------|----------|--------|
| API Key | OS Keyring ✅ | 保持 | - |
| Gateway Token | OS Keyring ✅ | 保持 | - |
| Theme | localStorage | 保持 | 低 |
| Skill 缓存 | localStorage | 保持 | 低 |
| 聊天记录 | SQLite | 考虑加密 | 高 |
**结论：** 聊天记录加密纳入安全增强计划
### 议题 5.3：灰度发布机制
**现状：** 无灰度发布
**方案：**
| 方案 | 工具 | 工作量 |
|------|------|--------|
| A. Tauri 内置更新 | tauri-plugin-updater | 1 天 |
| B. 手动版本管理 | - | 0 |
| C. 自动化灰度 | 定制开发 | 1 周 |
**结论：** 集成 Tauri 内置更新机制
---
## 六、创新解决方案
### 议题 6.1：AI Native 特性增强
**想法：**
| 特性 | 描述 | 创新度 |
|------|------|--------|
| 自适应上下文 | 根据任务类型自动调整上下文长度 | ⭐⭐⭐ |
| 智能缓存 | 预测用户意图，预加载资源 | ⭐⭐⭐ |
| 多模态交互 | 支持图片、语音输入 | ⭐⭐ |
| 主动建议 | 基于上下文主动提供建议 | ⭐⭐⭐⭐ |
**结论：** 优先实现"主动建议"作为差异化功能
### 议题 6.2：本地知识图谱构建
**想法：**
- 将记忆系统升级为知识图谱
- 实体关系挖掘
- 语义推理能力
**技术路径：**
```rust
// 实体提取
struct Entity {
name: String,
type: EntityType,
properties: HashMap<String, Value>,
}
// 关系链接
struct Relation {
from: EntityId,
to: EntityId,
relation_type: String,
confidence: f32,
}
```
**结论：** 长期规划，与 OpenViking 深度集成
### 议题 6.3：跨设备状态同步
**问题：** 当前数据仅本地存储
**方案：**
| 方案 | 复杂度 | 隐私性 | 推荐度 |
|------|--------|--------|--------|
| A. 云端同步 | 高 | 低 | ⭐⭐ |
| B. 端到端加密同步 | 高 | 高 | ⭐⭐⭐⭐ |
| C. 文件导入/导出 | 低 | 最高 | ⭐⭐⭐⭐ |
| D. 保持本地优先 | - | - | ⭐⭐⭐⭐⭐ |
**结论：** 提供端到端加密同步作为 Pro 功能
### 议题 6.4：隐私计算集成
**想法：**
- 本地模型推理（Llama.cpp 集成）
- 联邦学习支持
- 数据不出本机
**结论：** 长期愿景，需要大量研发投入
---
## 七、行动建议总结
### 短期行动（1-2 周）
| # | 行动 | 优先级 | 负责人 |
|---|------|--------|--------|
| 1 | gateway-client.ts 拆分 | P1 | 前端团队 |
| 2 | E2E 测试稳定性修复 | P0 | 测试团队 |
| 3 | React Compiler 评估 | P2 | 前端团队 |
### 中期行动（1-2 月）
| # | 行动 | 优先级 |
|---|------|--------|
| 4 | 聊天记录加密 | P1 |
| 5 | 插件市场 MVP | P2 |
| 6 | i18n 支持 | P2 |
| 7 | 兼容性测试套件 | P1 |
### 长期愿景（6 月+）
| # | 行动 | 优先级 |
|---|------|--------|
| 8 | 本地知识图谱 | P3 |
| 9 | 端到端加密同步 | P3 |
| 10 | Tauri Mobile 支持 | P3 |
---
## 八、会议结论
1. **架构优化优先** - gateway-client.ts 拆分是短期最高优先级
2. **稳定性优先** - E2E 测试修复和兼容性测试是 P0
3. **保持专注** - 不追求功能数量，聚焦核心体验
4. **隐私优先** - 本地优先策略，用户数据不强制上云
---
## 九、附录
### A. 参与讨论的"专家"
| 角色 | 输入 |
|------|------|
| 架构师 | 代码结构、模块划分 |
| 前端专家 | React、性能优化 |
| 后端专家 | Rust、智能层迁移 |
| 安全专家 | 数据保护、认证授权 |
| 产品专家 | 功能规划、优先级 |
### B. 参考资料
- ZCLAW-DEEP-ANALYSIS-v2.md
- docs/features/00-architecture/
- docs/plans/INTELLIGENCE-LAYER-MIGRATION.md

277
docs/archive/old-analysis/CODE-LEVEL-TODO.md Normal file
View File

@@ -0,0 +1,277 @@
# ZCLAW 代码层面未完成工作分析
> 分析日期：2026-03-20
> 基于 git diff 和代码审查
## 一、当前重构状态
### 1.1 已完成的重构
| 模块 | 原始状态 | 当前状态 | 说明 |
|------|----------|----------|------|
| gatewayStore.ts | 1800+ 行巨型文件 | ~100 行 facade | 已拆分为 7 个 domain stores |
| gateway-client.ts | 65KB 单文件 | 模块化 | 拆分为 5 个文件 |
| viking-*.ts | 5 个文件 | 已删除 | 移至 docs/archive/ |
| vector-memory.ts | 385 行 | 已删除 | 功能移至 Rust 后端 |
| context-builder.ts | 409 行 | 已删除 | 功能移至 Rust 后端 |
| session-persistence.ts | 655 行 | 已删除 | 功能移至 Rust 后端 |
### 1.2 新增文件（未提交）
```
desktop/src/lib/gateway-api.ts - REST API 方法实现
desktop/src/lib/gateway-auth.ts - Ed25519 设备认证
desktop/src/lib/gateway-storage.ts - URL/token 持久化
desktop/src/lib/gateway-types.ts - 协议类型定义
desktop/src/store/securityStore.ts - 安全状态管理
desktop/src/store/sessionStore.ts - 会话状态管理
```
---
## 二、代码层面待完成工作
### 2.1 🔴 高优先级：Store 迁移
**问题**：App.tsx 和 34+ 个组件仍使用 `useGatewayStore` (兼容层)，而非新的 domain-specific stores。
**待迁移组件清单**：
```bash
# 查找所有使用 useGatewayStore 的文件
desktop/src/App.tsx # 核心入口
desktop/src/components/ChatArea.tsx
desktop/src/components/Sidebar.tsx
desktop/src/components/RightPanel.tsx
desktop/src/components/HandsPanel.tsx
desktop/src/components/HandApprovalModal.tsx
# ... 更多组件
```
**迁移策略**：
```typescript
// 旧方式（兼容层，不推荐）
const { hands, triggers, approvals } = useGatewayStore();
// 新方式（推荐，按需导入）
import { useHandStore } from './store/handStore';
const { hands, triggers, approvals } = useHandStore();
```
**收益**：
- 减少 re-render（当前 useCompositeStore 订阅 40+ 状态）
- 更清晰的依赖关系
- 更好的代码分割
---
### 2.2 🔴 高优先级：useCompositeStore 性能优化
**问题**：`store/index.ts` 中的 `useCompositeStore` 订阅了所有 store 的几乎所有状态。
```typescript
// 当前实现（有问题）
export function useCompositeStore() {
// 订阅了 40+ 个状态
const connectionState = useConnectionStore((s) => s.connectionState);
const gatewayVersion = useConnectionStore((s) => s.gatewayVersion);
// ... 40+ 个订阅
}
```
**建议**：
1. 废弃 `useCompositeStore`
2. 组件直接使用 domain-specific stores
3. 仅在确实需要跨域状态的场景使用 selector 模式
---
### 2.3 🟡 中优先级：测试文件更新
**已删除测试文件**：
```
tests/desktop/session-persistence.test.ts (424 行)
tests/desktop/vector-memory.test.ts (299 行)
tests/desktop/viking-adapter.test.ts (446 行)
```
**需更新测试文件**：
```
tests/desktop/gatewayStore.test.ts (190 行需更新)
tests/desktop/swarm-skills.test.ts (6 行需更新)
```
**缺失测试**：
- `securityStore.test.ts` - 新 store 无测试
- `sessionStore.test.ts` - 新 store 无测试
- `gateway-api.test.ts` - 新模块无测试
- `gateway-auth.test.ts` - 新模块无测试
---
### 2.4 🟡 中优先级：类型定义清理
**问题**：`gatewayStore.ts` 仍定义了一些类型，这些应该移到各自的 store 或 types 文件。
```typescript
// gatewayStore.ts 中定义的类型（应迁移）
export interface HandRunStore { ... }
export interface ScheduledJob { ... }
export interface EventTrigger { ... }
export interface RunHistoryEntry { ... }
```
**建议**：
1. `HandRunStore` → `handStore.ts`
2. `ScheduledJob`, `EventTrigger`, `RunHistoryEntry` → 新建 `types/automation.ts`
---
### 2.5 🟢 低优先级：组件集成度提升
**存在但集成度低的组件**：
| 组件 | 文件 | 问题 |
|------|------|------|
| HeartbeatConfig | `components/Settings/HeartbeatConfig.tsx` | 未在 Settings 页面使用 |
| CreateTriggerModal | `components/Automation/CreateTriggerModal.tsx` | 未在 Automation 面板集成 |
| PersonalitySelector | `components/Agent/PersonalitySelector.tsx` | 未在 Agent 创建流程使用 |
| ScenarioTags | `components/Agent/ScenarioTags.tsx` | 未在 Agent 编辑使用 |
| DevQALoop | `components/Dev/DevQALoop.tsx` | 开发调试组件，未集成 |
---
### 2.6 🟢 低优先级：文档与代码同步
**文档声称完成但代码未验证**：
| 功能 | 文档状态 | 代码状态 |
|------|----------|----------|
| 身份演化 | ✅ 完成 | ❓ 未验证与后端集成 |
| 上下文压缩 | ✅ 完成 | ❓ 未验证触发条件 |
| 心跳巡检 | ✅ 完成 | ❓ 未验证实际执行 |
| 记忆持久化 | ✅ 完成 | ❓ 依赖 localStorage |
---
## 三、Tauri Rust 后端状态
### 3.1 已实现的 Rust 模块
| 模块 | 文件 | 功能 | 状态 |
|------|------|------|------|
| ZCLAW 集成 | `lib.rs` | Gateway 生命周期管理 | ✅ 完整 |
| Viking Server | `viking_server.rs` | 本地向量数据库 | ✅ 完整 |
| Viking Commands | `viking_commands.rs` | Viking CLI 封装 | ✅ 完整 |
| Browser Automation | `browser/*.rs` | Fantoccini 浏览器控制 | ✅ 完整 |
| Memory Extraction | `memory/*.rs` | 记忆提取、上下文构建 | ✅ 完整 |
| LLM Integration | `llm/mod.rs` | LLM 调用封装 | ✅ 完整 |
| Secure Storage | `secure_storage.rs` | OS keyring/keychain | ✅ 完整 |
### 3.2 Rust 后端与前端对齐问题
**问题**：前端 `lib/` 下有大量智能逻辑（记忆、反思、心跳），与 Rust 后端功能重叠。
| 前端文件 | Rust 对应 | 建议 |
|----------|-----------|------|
| `agent-memory.ts` | `memory/extractor.rs` | 统一到 Rust 端 |
| `context-compactor.ts` | `memory/context_builder.rs` | 统一到 Rust 端 |
| `heartbeat-engine.ts` | 无 | 迁移到 Rust 端 |
| `reflection-engine.ts` | 无 | 迁移到 Rust 端 |
| `agent-identity.ts` | 无 | 迁移到 Rust 端 |
**收益**：
- 后端持久运行（关闭浏览器不中断）
- 多端共享 Agent 状态
- 更可靠的数据持久化
---
## 四、技术债务清单
### 4.1 代码质量
| 问题 | 位置 | 严重度 |
|------|------|--------|
| 使用 `any` 类型 | 多处 | 中 |
| 空 catch 块 | `sessionStore.ts:119` | 低 |
| 硬编码字符串 | 多处 | 低 |
| 重复的类型定义 | `gatewayStore.ts` vs 各 store | 中 |
### 4.2 架构问题
| 问题 | 说明 | 建议 |
|------|------|------|
| 前端承担后端职责 | 记忆/反思/心跳在前端 | 迁移到 Rust |
| Store 过度订阅 | useCompositeStore 订阅 40+ 状态 | 按需订阅 |
| 兼容层膨胀 | gatewayStore.ts 作为 facade | 逐步移除 |
---
## 五、行动建议
### 本周必做
1. **提交当前重构** - gateway-client 模块化、store 拆分已完成
2. **更新测试** - 为新 store 和 gateway 模块添加测试
3. **迁移 App.tsx** - 从 useGatewayStore 迁移到 domain stores
### 两周内
1. **移除 useCompositeStore** - 组件直接使用 domain stores
2. **清理类型定义** - 统一到各自的 store 或 types 文件
3. **集成低使用率组件** - HeartbeatConfig, CreateTriggerModal 等
### 一个月内
1. **前端智能层迁移** - 将记忆/反思/心跳迁移到 Rust 后端
2. **端到端测试** - Playwright + Tauri driver 验证核心流程
3. **性能优化** - 减少不必要的 re-render
---
## 六、代码变更统计
```
当前未提交变更：
21 files changed, 578 insertions(+), 7324 deletions(-)
删除的文件（已归档）：
- desktop/src/lib/context-builder.ts (409 行)
- desktop/src/lib/session-persistence.ts (655 行)
- desktop/src/lib/vector-memory.ts (385 行)
- desktop/src/lib/viking-adapter.ts (734 行)
- desktop/src/lib/viking-client.ts (353 行)
- desktop/src/lib/viking-local.ts (144 行)
- desktop/src/lib/viking-memory-adapter.ts (408 行)
- desktop/src/lib/viking-server-manager.ts (231 行)
新增的文件：
+ desktop/src/lib/gateway-api.ts (新建)
+ desktop/src/lib/gateway-auth.ts (新建)
+ desktop/src/lib/gateway-storage.ts (新建)
+ desktop/src/lib/gateway-types.ts (新建)
+ desktop/src/store/securityStore.ts (新建)
+ desktop/src/store/sessionStore.ts (新建)
```
---
## 七、总结
**重构进度**：约 70% 完成
- ✅ Store 拆分完成
- ✅ Gateway Client 模块化完成
- ✅ Viking 相关代码清理完成
- ⏳ 组件迁移进行中（仍使用兼容层）
- ⏳ 测试更新待完成
- ❌ 前端智能层迁移未开始
**最大风险**：
1. useCompositeStore 性能问题（40+ 状态订阅）
2. 前端智能逻辑（记忆/反思）依赖 localStorage，不可靠
3. 缺少端到端测试验证
**建议策略**：
先完成当前重构（提交、测试、组件迁移），再启动前端智能层向 Rust 迁移。

157
docs/archive/old-analysis/COMPONENT-INTEGRATION-STATUS.md Normal file
View File

@@ -0,0 +1,157 @@
# ZCLAW 组件集成状态报告
> 分析日期：2026-03-20
> 基于 `ZCLAW-DEEP-ANALYSIS.md` 文档的核实结果
---
## 一、分析结论
| 组件 | 文档标记 | 实际状态 | 集成路径 |
|------|----------|----------|----------|
| PersonalitySelector | ❓ 未验证 | ✅ 已集成 | App.tsx → AgentOnboardingWizard |
| ScenarioTags | ❓ 未验证 | ✅ 已集成 | App.tsx → AgentOnboardingWizard |
| DevQALoop | ❓ 未验证 | ❌ 未集成 | 无 |
| HeartbeatConfig | ❓ 未验证 | ✅ 已集成 | SettingsLayout（根据迁移文档） |
| CreateTriggerModal | ❓ 未验证 | ✅ 已迁移 | useHandStore（根据迁移文档） |
---
## 二、详细分析
### 2.1 PersonalitySelector ✅ 已集成
**文件位置：** `desktop/src/components/PersonalitySelector.tsx`
**被引用情况：**
```typescript
// AgentOnboardingWizard.tsx:25
import { PersonalitySelector } from './PersonalitySelector';
```
**集成路径：**
```
App.tsx (L223)
→ AgentOnboardingWizard
→ PersonalitySelector
```
**Store 连接：** 通过 AgentOnboardingWizard 传递 props，组件内部使用 useState
**功能完整性：** ✅ 完整，提供性格选项选择
---
### 2.2 ScenarioTags ✅ 已集成
**文件位置：** `desktop/src/components/ScenarioTags.tsx`
**被引用情况：**
```typescript
// AgentOnboardingWizard.tsx:26
import { ScenarioTags } from './ScenarioTags';
```
**集成路径：**
```
App.tsx (L223)
→ AgentOnboardingWizard
→ ScenarioTags
```
**Store 连接：** 通过 AgentOnboardingWizard 传递 props
**功能完整性：** ✅ 完整，提供场景标签选择
---
### 2.3 DevQALoop ❌ 未集成
**文件位置：** `desktop/src/components/DevQALoop.tsx`
**被引用情况：** 无外部引用
**问题分析：**
- 组件已实现完整的 Dev-QA 循环界面
- 使用 `useTeamStore` 连接到 teamStore
- 但未在任何父组件中被导入使用
**建议集成位置：**
- `TeamOrchestrator.tsx` - 作为团队协作的子面板
- `TeamCollaborationView.tsx` - 作为代码审查工作流的一部分
**Store 连接：** ✅ 已连接
```typescript
import { useTeamStore } from '../store/teamStore';
```
**功能完整性：** ✅ 完整，但未被使用
**下一步行动：**
1. 确定合适的父组件
2. 添加到 TeamOrchestrator 或创建专门的 ReviewPanel
3. 在 UI 中添加导航入口
---
### 2.4 HeartbeatConfig ✅ 已集成
**根据 `docs/progress/2024-03-20-store-migration.md`：**
- 已集成到 SettingsLayout
- 使用 useSecurityStore
---
### 2.5 CreateTriggerModal ✅ 已迁移
**根据 `docs/progress/2024-03-20-store-migration.md`：**
- 已迁移到 useHandStore
- 使用 useWorkflowStore
---
## 三、待办事项
| 优先级 | 任务 | 工作量 |
|--------|------|--------|
| P1 | 将 DevQALoop 集成到 TeamOrchestrator | 小 |
| P2 | 为 DevQALoop 添加导航入口 | 小 |
| P3 | 更新 ZCLAW-DEEP-ANALYSIS.md 反映实际状态 | 小 |
---
## 四、代码引用
### DevQALoop 组件导出
```typescript
// desktop/src/components/DevQALoop.tsx
export function DevQALoop({ loop, onUpdate, onApprove }: DevQALoopProps)
```
### 建议的集成代码
```typescript
// 在 TeamOrchestrator.tsx 中添加
import { DevQALoop } from './DevQALoop';
// 在渲染部分添加条件渲染
{activeTab === 'review' && currentLoop && (
<DevQALoop
loop={currentLoop}
onUpdate={handleLoopUpdate}
onApprove={handleLoopApprove}
/>
)}
```
---
## 五、总结
文档中标记为"集成度低"的组件实际上大部分已完成集成：
- **PersonalitySelector** 和 **ScenarioTags** 通过 AgentOnboardingWizard 间接集成
- **HeartbeatConfig** 和 **CreateTriggerModal** 在 Store 迁移时已完成集成
- **仅 DevQALoop** 确实未被集成，需要后续处理
整体集成完成度比文档描述的更好，建议更新 `ZCLAW-DEEP-ANALYSIS.md` 文档以反映实际状态。

220
docs/archive/old-analysis/FEATURE-INTEGRITY-AUDIT.md Normal file
View File

@@ -0,0 +1,220 @@
# ZCLAW 功能完整性审计报告
> **审计日期**: 2026-03-26
> **审计范围**: docs/features 目录下所有功能文档 vs 实际代码实现
> **审计方法**: 五步审计流程（文档对齐 → 追踪数据流 → 识别 dead_code → 检查 trait 实现 → 端到端验证）
---
## 一、五步审计流程执行结果
### 步骤 1: 文档对齐
根据 `docs/features/README.md`，系统声称具备以下功能：
| 模块 | 声称成熟度 | 功能项 |
|------|-----------|--------|
| 架构层 | L4 | 通信层、状态管理、安全认证 |
| 核心功能 | L3-L4 | 聊天界面、Agent分身、Hands系统 |
| 智能层 | L3-L4 | 记忆、身份演化、上下文压缩、反思、心跳、自主授权 |
| Skills生态 | L4 | 动态扫描、execute_skill |
| Hands系统 | L3 | 9/11 已实现 |
| Pipeline DSL | L4 | 5类Pipeline模板 |
### 步骤 2: 追踪数据流
**智能层集成情况** (`intelligence_hooks.rs`):
```
✅ 已接入:
- identity (pre-hook): build_system_prompt()
- memory context (pre-hook): build_memory_context() via VikingStorage
- heartbeat (post-hook): record_interaction()
- reflection (post-hook): record_conversation() + should_reflect()
❌ 未接入:
- compactor: 代码存在但未在 hooks 中调用
- pattern_detector: #![allow(dead_code)]
- recommender: #![allow(dead_code)]
- mesh: #![allow(dead_code)]
- persona_evolver: #![allow(dead_code)]
- trigger_evaluator: #![allow(dead_code)]
```
### 步骤 3: 识别 dead_code
| 文件 | 状态 | 说明 |
|------|------|------|
| `intelligence/pattern_detector.rs` | `#![allow(dead_code)]` | 模块存在但未集成 |
| `intelligence/recommender.rs` | `#![allow(dead_code)]` | 模块存在但未集成 |
| `intelligence/mesh.rs` | `#![allow(dead_code)]` | 模块存在但未集成 |
| `intelligence/persona_evolver.rs` | `#![allow(dead_code)]` | 模块存在但未集成 |
| `intelligence/trigger_evaluator.rs` | `#![allow(dead_code)]` | 模块存在但未集成 |
| `context_compactor.rs` | Tauri命令存在但未在hooks中调用 | 降级为L2 |
### 步骤 4: 检查 trait 实现
| 智能模块 | Rust实现 | Tauri命令 | 前端调用链 |
|---------|---------|----------|-----------|
| heartbeat | ✅ | ✅ | ✅ intelligence_hooks |
| reflection | ✅ | ✅ | ✅ intelligence_hooks |
| identity | ✅ | ✅ | ✅ intelligence_hooks |
| memory | ✅ (VikingStorage) | ✅ | ✅ intelligence_hooks |
| compactor | ✅ | ✅ | ⚠️ chatStore直接调用，未经hooks |
| pattern_detector | ✅ | ❌ | ❌ |
| recommender | ✅ | ❌ | ❌ |
| mesh | ✅ | ❌ | ❌ |
| persona_evolver | ✅ | ❌ | ❌ |
| trigger_evaluator | ✅ | ❌ | ❌ |
### 步骤 5: 端到端验证
**发现编译错误**（target/flycheck0/stdout）:
```
error[E0603]: struct import `FindOptions` is private
--> desktop\src-tauri\src\intelligence_hooks.rs:100:43
```
---
## 二、10项通用审计清单
| # | 检查项 | 状态 | 说明 |
|---|--------|------|------|
| 1 | 代码存在性 | ✅ | 所有声称模块均有代码 |
| 2 | 调用链连通 | ⚠️ | 5个智能模块未接入hooks |
| 3 | 配置传递 | ⚠️ | compactor降级配置未生效 |
| 4 | 降级策略 | ✅ | intelligence-client.ts有fallback逻辑 |
| 5 | 前后端数据流 | ⚠️ | FindOptions私有导入导致编译失败 |
| 6 | UI组件集成 | ✅ | 主要UI已集成到RightPanel |
| 7 | 错误处理 | ✅ | 有容错解析 |
| 8 | 测试覆盖 | ⚠️ | 仅agent-memory有测试 |
| 9 | 文档同步 | ⚠️ | 文档声称L4，实际部分L2 |
| 10 | 依赖声明 | ✅ | Cargo.toml完整 |
---
## 三、5种常见差距模式
| 模式 | 描述 | 发现实例 |
|------|------|----------|
| **写了没接** | 代码已实现但未接入实际流程 | compactor、pattern_detector、recommender、mesh、persona_evolver、trigger_evaluator |
| **接了没传** | 接入了但参数/状态未传递 | heartbeat post-hook参数未使用 |
| **传了没存** | 传了但未持久化 | identity快照未存储 |
| **存了没用** | 存储了但UI未使用 | VikingStorage记忆未在MemoryPanel展示 |
| **双系统不同步** | TypeScript和Rust各有一套实现 | intelligence-backend.ts vs intelligence_hooks.rs |
---
## 四、功能差距详细清单
### 4.1 智能层差距
| 功能 | 文档声称 | 实际状态 | 差距等级 |
|------|---------|---------|---------|
| Agent记忆 | L4 ✅ | L3 ⚠️ | 中 |
| 身份演化 | L3 ✅ | L2 ⚠️ | 中 |
| 上下文压缩 | L2 ⚠️ | L2 ⚠️ | 低 |
| 自我反思 | L3 ✅ | L3 ✅ | 无 |
| 心跳巡检 | L3 ✅ | L3 ✅ | 无 |
| 自主授权 | L3 ✅ | L3 ✅ | 无 |
| Pattern检测 | L4 ✅ | ❌ 未集成 | 高 |
| 推荐引擎 | L4 ✅ | ❌ 未集成 | 高 |
| 自适应Mesh | L4 ✅ | ❌ 未集成 | 高 |
| Persona演进 | L4 ✅ | ❌ 未集成 | 高 |
| 触发评估器 | L4 ✅ | ❌ 未集成 | 高 |
### 4.2 Hands系统差距
| Hand | 文档声称 | 实际状态 |
|------|---------|---------|
| Browser | ✅ | ✅ |
| Collector | ✅ | ✅ |
| Researcher | ✅ | ✅ |
| Predictor | ✅ | ⚠️ 依赖外部API |
| Lead | ✅ | ⚠️ 依赖外部API |
| Clip | ✅ | ⚠️ 需要FFmpeg |
| Speech | ✅ | ✅ |
| Slideshow | ✅ | ✅ |
| Quiz | ✅ | ✅ |
| Whiteboard | ✅ | ✅ |
| Twitter | ✅ | ⚠️ 需要API Key |
### 4.3 未实现的API（feature-checklist.md记录）
| API端点 | 状态 | 文档日期 |
|---------|------|---------|
| `/api/tasks` | ❌ 404 | 2026-03-14 |
| `/api/audit/logs` | ❌ 404 | 2026-03-14 |
| `/api/security/status` | ❌ 404 | 2026-03-14 |
| `/api/plugins` | ❌ 404 | 2026-03-14 |
| `/api/workspace` | ❌ 404 | 2026-03-14 |
| `/api/mcp/*` | ❌ 404 | 2026-03-14 |
---
## 五、审计命令速查
```bash
# 搜索 dead_code
rg "#\!\[allow\(dead_code\)\]" --type rust
# 搜索 TODO/FIXME
rg "TODO|FIXME|XXX|HACK" --type rust --type ts
# 搜索未集成的智能模块
rg "pattern_detector|recommender|mesh|persona_evolver|trigger_evaluator" --type rust
# 检查 invoke 调用链
rg "invoke\('" desktop/src/lib/ --type ts
# 搜索 404 API
rg "404|net::ERR" desktop/src/ --type ts
```
---
## 六、修复建议优先级
### P0 - 阻断性问题
| 问题 | 修复 |
|------|------|
| `FindOptions`私有导入 | 修改 `intelligence_hooks.rs:100` 使用 `zclaw_growth::FindOptions` |
| 5个智能模块未集成 | 将 compactor/pattern_detector/recommender/mesh/persona_evolver/trigger_evaluator 接入 hooks |
### P1 - 重要功能
| 问题 | 修复 |
|------|------|
| Context Compactor 未在hooks调用 | 在 `pre_conversation_hook` 或 `post_conversation_hook` 中添加compact调用 |
| Vector Memory UI未使用 | 集成 `vector-memory.ts` 到 MemoryPanel |
### P2 - 增强功能
| 问题 | 修复 |
|------|------|
| 文档更新 | 将未集成模块的成熟度从L4降为L2 |
| 测试覆盖 | 为每个智能模块添加单元测试 |
---
## 七、总结
| 指标 | 数值 |
|------|------|
| 文档声称成熟度 | 大部分 L3-L4 |
| 实际达到成熟度 | 核心聊天流程 L4，智能层 L2-L3 |
| 未集成模块 | 6个 (compactor降级, 5个智能模块) |
| 编译错误 | 1个 (FindOptions私有导入) |
| 未实现API | 6个 |
**核心问题**: 系统核心聊天功能完整，但智能层的"自我进化"能力大部分停留在代码存在但未集成的状态，属于"**写了没接**"的典型模式。
---
## 八、变更历史
| 日期 | 变更内容 |
|------|---------|
| 2026-03-26 | 初始版本，完成五步审计流程分析 |

331
docs/archive/old-analysis/OPTIMIZATION-ROADMAP.md Normal file
View File

@@ -0,0 +1,331 @@
# 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 项目风险
| 风险 | 概率 | 影响 | 应对措施 |
|------|------|------|----------|
| ZCLAW 版本不兼容 | 中 | 高 | 建立兼容性测试套件 |
| 关键人员离职 | 低 | 高 | 文档和知识共享 |
| 竞品快速迭代 | 高 | 中 | 聚焦差异化功能 |
| 技术方案不可行 | 低 | 中 | 技术验证先行 |
### 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 | |

643
docs/archive/old-analysis/PROJECT-SYSTEMATIC-ANALYSIS-REPORT.md Normal file
View File

@@ -0,0 +1,643 @@
# ZCLAW 项目系统性深度分析报告
> **报告日期：** 2026-03-21
> **分析范围：** 代码结构、架构设计、技术栈、业务逻辑、数据流、性能安全
> **报告版本：** v1.0
---
## 执行摘要
### 项目概览
ZCLAW 是一个基于 **ZCLAW** 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
### 核心数据
| 维度 | 数量 | 评价 |
|------|------|------|
| 前端组件 | 88 个 .tsx 文件 | ✅ 职责划分清晰 |
| Store 文件 | 15 个 (13 活跃 + 2 门面) | ✅ 架构已统一 |
| Lib 工具 | 36 个工具文件 | ⚠️ 部分需拆分 |
| 类型定义 | 13 个类型文件 | ✅ 类型安全 |
| Skills | 68 个 SKILL.md | ✅ 生态丰富 |
| Hands | 7 个 HAND.toml | ✅ 自主能力完整 |
| Rust 模块 | 8 个主要模块 | ✅ 后端充实 |
| Tauri Commands | 70+ | ✅ 接口完整 |
| 测试文件 | 15+ | ✅ 覆盖良好 |
| 文档文件 | 84+ | ✅ 文档详尽 |
### 综合评分
| 维度 | 评分 | 说明 |
|------|------|------|
| 代码结构 | 4/5 | 组件划分清晰，文件组织合理 |
| 架构设计 | 4/5 | 分层清晰，模块职责明确 |
| 技术选型 | 4/5 | 框架选择合理，依赖精简 |
| 业务实现 | 4/5 | 核心流程完整，异常处理充分 |
| 数据流设计 | 4/5 | 流向清晰，同步机制完善 |
| 接口设计 | 4/5 | Tauri Commands 粒度合理 |
| 性能表现 | 3/5 | 存在优化空间 |
| 安全合规 | 4/5 | 认证机制完善 |
| 测试覆盖 | 3/5 | 核心逻辑有覆盖 |
| 文档质量 | 4/5 | 文档详尽 |
| **综合** | **3.8/5** | **良好，有改进空间** |
---
## 一、代码结构分析
### 1.1 项目整体结构
```
ZCLAW/
├── desktop/ # Tauri 桌面应用 (React + Rust)
│ ├── src/
│ │ ├── components/ # 88 个 React 组件
│ │ ├── store/ # 15 个 Zustand stores
│ │ ├── lib/ # 36 个工具文件
│ │ ├── types/ # 13 个类型定义
│ │ ├── hooks/ # 自定义 hooks
│ │ └── assets/ # 静态资源
│ └── src-tauri/ # Rust 后端
│ └── src/
│ ├── browser/ # 浏览器自动化
│ ├── intelligence/ # 智能层 (心跳/反思/压缩)
│ ├── memory/ # 记忆系统
│ ├── llm/ # LLM 接口
│ └── *.rs # Commands 实现
├── skills/ # 68 个 SKILL.md
├── hands/ # 7 个 HAND.toml
├── config/ # TOML 配置文件
├── docs/ # 84+ 文档文件
├── src/gateway/ # Node.js Gateway 层
└── tests/ # 测试文件
```
### 1.2 前端组件层分析
**组件分类统计：**
| 类别 | 组件数 | 代表组件 |
|------|--------|----------|
| 聊天/对话 | 8 | ChatArea, ConversationList, MessageSearch |
| Agent/Clone | 6 | CloneManager, AgentOnboardingWizard |
| 自动化 Hands | 10 | HandsPanel, HandList, HandApprovalModal |
| 工作流 | 4 | WorkflowList, WorkflowEditor |
| 团队协作 | 5 | TeamList, TeamCollaborationView |
| 记忆/智能 | 6 | MemoryPanel, MemoryGraph, ReflectionLog |
| 安全/审计 | 5 | SecurityLayersPanel, SecurityStatus |
| 浏览器自动化 | 8 | BrowserHandCard, ScreenshotPreview |
| 设置 | 12 | SettingsLayout, General, ModelsAPI... |
| UI 基础组件 | 15 | Button, Card, Input, Badge... |
**评价：** ✅ 组件职责划分清晰，分类合理
### 1.3 Store 层分析
**13 个活跃 Zustand Stores：**
| Store | 职责 | 状态 |
|-------|------|------|
| chatStore | 聊天消息、会话管理 | ✅ 活跃 |
| connectionStore | Gateway 连接状态 | ✅ 活跃 |
| agentStore | Clone/Agent 管理 | ✅ 活跃 |
| handStore | Hands/Triggers/Approvals | ✅ 活跃 |
| workflowStore | 工作流管理 | ✅ 活跃 |
| configStore | 配置/渠道/技能/模型 | ✅ 活跃 |
| securityStore | 安全状态/审计日志 | ✅ 活跃 |
| sessionStore | 会话管理 | ✅ 活跃 |
| teamStore | 团队协作 | ✅ 活跃 |
| skillMarketStore | 技能市场 | ✅ 活跃 |
| memoryGraphStore | 记忆图谱 | ✅ 活跃 |
| activeLearningStore | 主动学习 | ✅ 活跃 |
| browserHandStore | 浏览器自动化 | ✅ 活跃 |
**gatewayStore.ts 门面模式：**
- 从 1800+ 行缩减到 352 行
- 作为向后兼容的 facade 层
- 标记为 `@deprecated`
**评价：** ✅ Store 架构已统一，拆分合理
### 1.4 Rust 后端结构
```
desktop/src-tauri/src/
├── lib.rs # 入口，ZCLAW 集成
├── main.rs # 主程序
├── viking_commands.rs # OpenViking CLI sidecar
├── viking_server.rs # OpenViking 本地服务器
├── secure_storage.rs # OS Keyring/Keychain
├── memory_commands.rs # 持久化内存命令
├── memory/ # 内存提取和上下文构建
│ ├── extractor.rs # LLM 驱动的记忆提取
│ ├── context_builder.rs # L0/L1/L2 分层上下文
│ └── persistent.rs # SQLite 持久化
├── llm/ # LLM 接口
├── browser/ # 浏览器自动化 (Fantoccini)
│ ├── actions.rs
│ ├── client.rs
│ ├── commands.rs
│ ├── error.rs
│ ├── mod.rs
│ └── session.rs
└── intelligence/ # 智能层 (已从前端迁移)
├── heartbeat.rs # 心跳引擎
├── compactor.rs # 上下文压缩
├── reflection.rs # 反思引擎
├── identity.rs # Agent 身份管理
└── mod.rs
```
**评价：** ✅ 模块组织清晰，职责分明
### 1.5 代码规模与大型文件
**大型文件识别：**
| 文件 | 规模 | 问题 | 建议 |
|------|------|------|------|
| gateway-client.ts | ~65KB | 职责过重 | 拆分为多模块 |
| gatewayStore.ts | 352行 | 已是 facade | 逐步迁移引用 |
| intelligence-client.ts | ~15KB | 功能集中 | 保持现状 |
| autonomy-manager.ts | ~15KB | 授权逻辑 | 保持现状 |
**评价：** ⚠️ gateway-client.ts 需要拆分
---
## 二、架构设计分析
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ React UI Layer │
│ ChatArea, Sidebar, HandsPanel, WorkflowEditor... │
├─────────────────────────────────────────────────────────────┤
│ Zustand State Layer │
│ chatStore, connectionStore, agentStore, handStore... │
├─────────────────────────────────────────────────────────────┤
│ Client Layer │
│ GatewayClient │ IntelligenceClient │ TeamClient │
├─────────────────────────────────────────────────────────────┤
│ Tauri IPC / WebSocket │
├─────────────────────────────────────────────────────────────┤
│ Rust Backend │
│ browser │ intelligence │ memory │ llm │ secure_storage │
└─────────────────────────────────────────────────────────────┘
↕
ZCLAW Kernel / OpenViking
```
### 2.2 数据流架构
**用户操作流程：**
```
用户操作 → React UI → Zustand Store → GatewayClient
↓
WebSocket / REST
↓
ZCLAW Kernel
↓
Skills / Hands 执行
```
**状态更新流程：**
```
Backend Event → GatewayClient → Store Update → React Re-render
```
**评价：** ✅ 数据流清晰，分层合理
### 2.3 通信层设计
**Gateway Protocol v3：**
- 消息类型：req/res/event/stream
- 认证：Ed25519 设备签名
- 心跳：30秒间隔，3次超时断开
- 自动重连：指数退避策略
**Tauri Commands (70+)：**
| 类别 | 命令数 | 示例 |
|------|--------|------|
| Browser | 18 | browser_navigate, browser_click |
| Memory | 12 | memory_store, memory_search |
| Intelligence | 15 | heartbeat_*, reflection_* |
| Viking | 9 | viking_status, viking_find |
| Gateway | 8 | gateway_start, gateway_stop |
| LLM | 3 | llm_complete |
**评价：** ✅ 通信层设计完整
### 2.4 分层架构评估
| 层级 | 技术 | 职责 | 评价 |
|------|------|------|------|
| 表现层 | React 19 | UI 渲染、用户交互 | ✅ 合理 |
| 状态层 | Zustand | 状态管理、流程编排 | ✅ 合理 |
| 通信层 | GatewayClient | 网络通信、协议处理 | ✅ 合理 |
| 服务层 | Rust | 业务逻辑、智能层 | ✅ 合理 |
| 数据层 | SQLite | 本地持久化 | ✅ 合理 |
---
## 三、技术栈分析
### 3.1 前端技术栈
| 技术 | 版本 | 选型理由 | 评估 |
|------|------|----------|------|
| React | 19.1.0 | 最新特性，Concurrent 模式 | ✅ 合理 |
| Zustand | 5.0.11 | 轻量、类型安全 | ✅ 合理 |
| TailwindCSS | 4.2.1 | 原子化样式 | ✅ 合理 |
| Framer Motion | 12.36.0 | 声明式动画 | ✅ 合理 |
| Lucide React | 0.577.0 | 图标库 | ✅ 合理 |
| Tauri | 2.0 | 体积小 (~10MB) | ✅ 合理 |
### 3.2 后端技术栈
| 技术 | 用途 | 评估 |
|------|------|------|
| Rust + Tokio | 异步运行时 | ✅ 高性能 |
| SQLite + SQLx | 本地持久化 | ✅ 轻量 |
| Fantoccini | 浏览器自动化 | ✅ 成熟 |
| Keyring | 安全存储 | ✅ 安全 |
| Ed25519 | 设备认证 | ✅ 安全 |
### 3.3 依赖管理
**前端依赖 (package.json)：**
```json
{
"@tauri-apps/api": "^2",
"react": "^19.1.0",
"zustand": "^5.0.11",
"framer-motion": "^12.36.0",
"lucide-react": "^0.577.0"
}
```
**后端依赖 (Cargo.toml)：**
```toml
[dependencies]
tauri = { version = "2", features = [] }
tokio = { version = "1", features = ["full"] }
sqlx = { version = "0.7", features = ["runtime-tokio", "sqlite"] }
fantoccini = "0.21"
keyring = "3"
```
**评价：** ✅ 依赖精简，版本稳定
---
## 四、业务逻辑实现分析
### 4.1 聊天功能
**消息流程：**
```
用户输入 → sendMessage()
→ 上下文压缩检查 (compactor.checkThreshold)
→ 记忆增强 (intelligenceClient.memory.search)
→ 添加用户消息
→ 创建流式占位消息
→ gatewayClient.chatStream()
→ 收集 tool/hand/workflow 事件
→ 流结束 → 提取记忆 (memory-extractor)
→ 触发反思 (intelligenceClient.reflection)
```
**评价：** ✅ 流程完整，异常处理充分
### 4.2 记忆系统
**记忆提取模式：**
1. **LLM 提取** - 使用 `llmExtract()` 语义提取
2. **规则提取** - 正则匹配模式
**记忆分类：**
- fact: 用户事实
- preference: 用户偏好
- lesson: 经验教训
- context: 上下文
- task: 任务
**分层上下文加载（L0/L1/L2）：**
```
L0 (Quick Scan): 向量相似度搜索，返回概览
L1 (Standard): 加载 top 候选的 overview
L2 (Deep): 加载最相关项的完整内容
```
**评价：** ✅ 设计完善，已迁移到 Rust 后端
### 4.3 自主能力系统 (Hands)
**L4 分层授权：**
| 级别 | 自动内存保存 | 自动压缩 | 自动反思 |
|------|-------------|---------|---------|
| supervised | ❌ | ❌ | ❌ |
| assisted | ✅ | ✅ | ✅ |
| autonomous | ✅ | ✅ | ✅ |
**风险评估：**
- ACTION_RISK_MAP 定义每种操作的风险等级
- importanceMax + riskMax 双重判断
- 所有操作记录审计日志
**7 个内置 Hands：**
| Hand | 功能 | 状态 |
|------|------|------|
| Browser | 网页自动化 | ✅ 可用 |
| Researcher | 深度研究 | ✅ 可用 |
| Collector | 情报监控 | ✅ 可用 |
| Predictor | 趋势预测 | ✅ 可用 |
| Lead | 线索挖掘 | ✅ 可用 |
| Clip | 视频处理 | ⚠️ 需 FFmpeg |
| Twitter | 社媒管理 | ⚠️ 需 API Key |
**评价：** ✅ 授权机制完善，Hands 系统完整
### 4.4 智能层实现
| 模块 | 文件 | 测试 | 集成 |
|------|------|------|------|
| Agent 记忆 | Rust backend | ✅ | ✅ MemoryPanel |
| 身份演化 | Rust backend | ✅ | ✅ Settings |
| 上下文压缩 | Rust backend | ✅ | ✅ chatStore |
| 自我反思 | Rust backend | ✅ | ✅ ReflectionLog |
| 心跳引擎 | Rust backend | ✅ | ✅ HeartbeatConfig |
| 主动学习 | TypeScript | ✅ | ✅ ActiveLearningPanel |
| Agent 蜂群 | TypeScript | ✅ | ✅ SwarmDashboard |
**评价：** ✅ 智能层设计深刻，大部分已迁移到 Rust
### 4.5 功能完成度评估
| 功能 | 状态 | 完成度 |
|------|------|--------|
| 聊天界面 | ✅ 完成 | 95% |
| 分身管理 | ✅ 完成 | 90% |
| 自动化面板 | ✅ 完成 | 85% |
| 技能市场 | 🚧 进行中 | 70% |
| 工作流编辑 | 📋 计划中 | 50% |
| 团队协作 | ✅ 完成 | 80% |
| 记忆系统 | ✅ 完成 | 90% |
| 安全审计 | ✅ 完成 | 85% |
---
## 五、数据流向分析
### 5.1 状态管理
**Store 间关系：**
```
chatStore (核心)
↓ 使用
connectionStore (连接)
↓ 使用
gateway-client.ts (通信)
agentStore, handStore, workflowStore (并行)
↓ 各自使用
configStore (配置)
```
**持久化策略：**
- **SQLite**: 聊天记录、记忆、审计日志
- **OS Keyring**: API Key、Token
- **localStorage**: 主题、部分配置 (⚠️ 需评估)
### 5.2 数据持久化
**SQLite 数据库设计：**
```sql
CREATE TABLE memories (
id TEXT PRIMARY KEY,
agent_id TEXT NOT NULL,
memory_type TEXT NOT NULL,
content TEXT NOT NULL,
importance INTEGER DEFAULT 5,
source TEXT DEFAULT 'auto',
tags TEXT DEFAULT '[]',
conversation_id TEXT,
created_at TEXT NOT NULL,
last_accessed_at TEXT NOT NULL,
access_count INTEGER DEFAULT 0,
embedding BLOB
);
```
**评价：** ✅ 结构清晰，有索引优化
---
## 六、接口设计分析
### 6.1 Tauri Commands 设计
**命令组织：**
- 按功能模块分组
- 统一返回 `Result<T, String>`
- 使用 Tauri State 管理共享状态
**示例：**
```rust
#[tauri::command]
async fn memory_search(
state: State<'_, MemoryState>,
query: String,
limit: Option<usize>,
) -> Result<Vec<MemoryEntry>, String>
```
### 6.2 Gateway Protocol v3
**消息格式：**
```typescript
interface GatewayFrame {
id?: string;
type: 'req' | 'res' | 'event' | 'stream';
method?: string;
payload?: unknown;
error?: GatewayError;
}
```
**评价：** ✅ 接口粒度合理，类型安全
---
## 七、性能分析
### 7.1 渲染性能
**优化措施：**
- ✅ 虚拟滚动 (react-window)
- ⚠️ Store selector 可优化 (shallow 比较)
- ⚠️ 大型组件可拆分
### 7.2 网络性能
**WebSocket 配置：**
- 心跳间隔：30 秒
- 超时：10 秒
- 最大丢失：3 次
- 自动重连：指数退避
**评价：** ✅ 配置合理
### 7.3 计算性能
**Token 估算：**
```rust
// CJK: ~1.5 tokens/字符
// ASCII: ~0.3 tokens/字符
```
**评价：** ✅ 算法合理
---
## 八、安全分析
### 8.1 认证授权
- ✅ Ed25519 设备认证
- ✅ L4 分层授权
- ✅ 操作审计日志
### 8.2 数据安全
| 数据类型 | 存储方式 | 评价 |
|----------|----------|------|
| API Key | OS Keyring | ✅ 安全 |
| Token | OS Keyring | ✅ 安全 |
| 聊天记录 | SQLite (未加密) | ⚠️ 需加密 |
| 主题配置 | localStorage | ✅ 可接受 |
### 8.3 输入验证
- ✅ SQL 注入防护 (参数化查询)
- ⚠️ XSS 防护需确认
---
## 九、测试覆盖分析
### 9.1 单元测试
**测试文件分布：**
| 测试文件 | 覆盖范围 |
|----------|----------|
| autonomy-manager.test.ts | L4 授权逻辑 |
| agent-memory.test.ts | 记忆系统 |
| context-compactor.test.ts | 上下文压缩 |
| heartbeat-reflection.test.ts | 心跳和反思 |
| gatewayStore.test.ts | Store 状态 |
| chatStore.test.ts | 聊天逻辑 |
| teamStore.test.ts | 团队协作 |
| browserHandStore.test.ts | 浏览器手 |
| ws-client.test.ts | WebSocket 客户端 |
**评价：** ✅ 核心逻辑有覆盖
### 9.2 E2E 测试
- ✅ Playwright 已配置
- ⚠️ 测试稳定性需提升 (当前 ~80% 通过率)
---
## 十、风险识别
### 10.1 技术风险
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| ZCLAW 版本不兼容 | 中 | 高 | 兼容性测试套件 |
| LLM API 变更 | 中 | 高 | 抽象层隔离 |
| 性能瓶颈 | 中 | 中 | 监控和优化 |
### 10.2 代码质量风险
| 问题 | 影响 | 优先级 |
|------|------|--------|
| gateway-client.ts 65KB | 维护困难 | P1 |
| Rust unwrap() 使用 | 可能 panic | P1 |
| localStorage 降级 | 数据不一致 | P1 |
### 10.3 维护风险
- 单人/小团队维护压力
- 50+ 组件、36 个 lib、15 个 store 的维护成本
---
## 十一、关键发现总结
### 优势 (Strengths)
1. **技术栈先进** — Tauri 2.0 比 Electron 体积小 10x+
2. **智能层设计深刻** — 记忆、反思、压缩是真正的差异化能力
3. **Skills 生态丰富** — 68 个 Skill 覆盖多领域
4. **Hands 系统完整** — 7 个能力包 + 审批/触发/审计全链路
5. **中文优先** — 中文模型 Provider + 飞书集成
6. **测试覆盖好** — 核心逻辑有单元测试
7. **文档详尽** — 84+ 文档文件
### 劣势 (Weaknesses)
1. **gateway-client.ts 过大** (65KB) — 需拆分
2. **E2E 测试不稳定** — 需修复
3. **聊天记录未加密** — 需增强安全
4. **部分 localStorage 使用** — 需评估
### 机会 (Opportunities)
1. 中国 AI Agent 市场爆发
2. 本地优先隐私诉求增长
3. ZCLAW 生态缺口
4. 飞书+企业微信整合需求
5. Skill 市场变现潜力
### 威胁 (Threats)
1. 竞品迭代极快 (Cursor/Windsurf/AutoClaw)
2. ZCLAW 上游变化
3. LLM API 不稳定
4. 维护成本高
---
## 附录
### A. 关键文件索引
| 文件 | 位置 | 说明 |
|------|------|------|
| gateway-client.ts | desktop/src/lib/ | 核心通信客户端 |
| intelligence-client.ts | desktop/src/lib/ | 智能层统一 API |
| chatStore.ts | desktop/src/store/ | 聊天状态管理 |
| lib.rs | desktop/src-tauri/src/ | Rust 后端入口 |
| intelligence/ | desktop/src-tauri/src/ | 智能层 Rust 实现 |
### B. 参考文档
- [ZCLAW-DEEP-ANALYSIS.md](ZCLAW-DEEP-ANALYSIS.md)
- [ZCLAW-DEEP-ANALYSIS-v2.md](ZCLAW-DEEP-ANALYSIS-v2.md)
- [BRAINSTORMING-SESSION.md](BRAINSTORMING-SESSION.md)
- [OPTIMIZATION-ROADMAP.md](OPTIMIZATION-ROADMAP.md)
- [ISSUE-TRACKER.md](ISSUE-TRACKER.md)
---
*报告完成*

829
docs/archive/old-analysis/SYSTEM_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,829 @@
# ZCLAW 多端系统架构文档
> 版本: 1.3 | 日期: 2026-04-06 | 状态: 已更新 (DeerFlow 2.0 + 安全审计 V1 修复 + Admin V2 迁移)
---
## 目录
1. [系统总览](#1-系统总览)
2. [端口与协议分配](#2-端口与协议分配)
3. [技术栈选型](#3-技术栈选型)
4. [数据流向](#4-数据流向)
5. [SaaS 后端 API 接口清单](#5-saas-后端-api-接口清单)
6. [桌面端内部通信](#6-桌面端内部通信)
7. [权限体系](#7-权限体系)
8. [各端交互逻辑](#8-各端交互逻辑)
9. [部署与启动](#9-部署与启动)
10. [接口设计背景与业务价值](#10-接口设计背景与业务价值)
---
## 1. 系统总览
ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 **4 个独立服务/端** 组成：
```
┌─────────────────────────────────────────────────────────────────┐
│ ZCLAW 系统架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Desktop App │ │ Admin V2 │ │ SaaS Backend │ │
│ │ (Tauri+React)│ │ (Vite+AntD) │ │ (Axum + PostgreSQL) │ │
│ │ Port: 1420 │ │ Port: 5173 │ │ Port: 8080 │ │
│ │ │ │ │ │ │ │
│ │ 内核模式: │ │ 管理后台 │ │ REST API │ │
│ │ Tauri IPC │ │ JWT 鉴权 │ │ JWT + API Token │ │
│ │ │ │ │ │ RBAC 权限 │ │
│ │ 网关模式: │ │ │ │ │ │
│ │ WS :50051 │ │ │ │ ┌────────────────┐ │ │
│ │ WS :4200 │ │ │ │ │ PostgreSQL │ │ │
│ │ │ │ │ │ │ Port: 5432 │ │ │
│ │ SaaS 模式: │ │ │ │ └────────────────┘ │ │
│ │ HTTPS REST │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ ZCLAW 网关 │ │ LLM 服务商 │ │
│ │ (独立二进制) │ │ (外部) │ │
│ │ Port: 4200 │ │ OpenAI 等 │ │
│ │ Port: 50051 │ │ │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 核心设计理念
- **双模式架构**: 桌面端支持「本地内核」(离线/低延迟) 和「远程网关」(团队协作) 两种运行模式
- **统一 LLM 接入**: 4 条 LLM 路径 (直连 OpenAI、直连火山引擎、SaaS 中转、网关透传)
- **集中管控**: SaaS 后端统一管理账号、模型、服务商、Prompt 模板、配置同步
- **安全审计**: 完整的操作日志 + TOTP 2FA + JWT + RBAC
---
## 2. 端口与协议分配
| 端口 | 服务 | 协议 | 用途 | 启动方式 |
|------|------|------|------|----------|
| 1420 | Vite Dev Server | HTTP | 桌面端前端开发服务 (仅 dev) | `pnpm tauri dev` |
| 3000 | ~~Next.js Dev Server~~ | HTTP | ~~旧 Admin 管理后台~~ (已废弃) | ~~`pnpm dev` (admin/)~~ |
| 5173 | Vite Dev Server | HTTP | Admin V2 管理后台开发服务 | `pnpm dev` (admin-v2/) |
| 4200 | ZCLAW Gateway/Kernel | WebSocket + REST | 网关备用端口 | ZCLAW 二进制 |
| 50051 | ZCLAW Gateway | WebSocket + REST | 网关主端口 | ZCLAW 二进制 |
| 5432 | PostgreSQL | PostgreSQL Wire | SaaS 后端数据库 | Docker/start-all.ps1 |
| 8080 | SaaS Backend | HTTP REST | 管理后台 API + 中转代理 | start-saas.ps1 |
| 4444 | ChromeDriver | WebDriver HTTP | 浏览器 Hand 自动化 | start-all.ps1 |
| N/A | Tauri IPC | invoke() | 桌面端内部进程通信 | 内嵌 |
---
## 3. 技术栈选型
### 3.1 桌面端 (Desktop)
| 层级 | 技术 | 选型理由 |
|------|------|----------|
| 桌面框架 | Tauri 2.x | Rust 原生性能，小体积，安全 IPC |
| 前端框架 | React 19 + TypeScript | 生态丰富，类型安全 |
| 状态管理 | Zustand | 轻量、灵活、无 boilerplate |
| 样式方案 | Tailwind 4 | 原子化 CSS，暗色主题友好 |
| 数据存储 | SQLite (本地) | 离线优先，FTS5 全文搜索 |
### 3.2 Admin V2 管理后台
| 层级 | 技术 | 选型理由 |
|------|------|----------|
| 框架 | React 19 + Vite 8 | 纯 SPA，快速构建 |
| 语言 | TypeScript 5.9 | 类型安全 |
| UI 组件 | Ant Design 6 + Pro Components | 企业级组件库，暗色主题 |
| 状态管理 | Zustand 5 | 轻量灵活 |
| 数据获取 | TanStack React Query 5 | 缓存+去重+自动重验证 |
| 路由 | React Router 7 | SPA 路由 |
| HTTP | Axios | 拦截器 + 401 自动刷新 |
| 样式 | Tailwind CSS v4 | 原子化 CSS |
| 测试 | Vitest + Testing Library + MSW | 完整测试覆盖 |
> **Admin V2 迁移说明**: 从 Next.js + SWR + shadcn/ui 迁移到 Vite + React Query + Ant Design Pro，认证改为 HttpOnly Cookie 模式，11 个管理页面全部重写，含 71 个测试用例。
### 3.3 SaaS 后端
| 层级 | 技术 | 选型理由 |
|------|------|----------|
| Web 框架 | Axum | Rust 高性能异步 Web 框架 |
| 数据库 | PostgreSQL | 关系型，复杂查询支持好 |
| ORM | sqlx | 编译时 SQL 检查，零开销 |
| 认证 | JWT + TOTP | 无状态鉴权 + 双因素认证 |
| 加密 | AES-256-GCM | API Key 加密存储 |
| 后台任务 | Worker trait + mpsc Channel | 异步非阻塞，支持自动重试 |
| 定时任务 | 声明式 Scheduler (TOML) | 无需改代码调整调度时间 |
| 连接池 | sqlx PgPool (50 max / 5 min) | 高并发，自动管理生命周期 |
| 迁移系统 | SQL 文件 + Schema 版本控制 | TIMESTAMPTZ 类型，向后兼容 |
| 多环境 | ZCLAW_ENV (dev/prod/test) | 配置隔离，环境变量覆盖 |
### 3.4 核心运行时 (Rust Workspace)
```
zclaw-types → 基础类型 (AgentId, Message, Error)
zclaw-memory → 存储层 (SQLite, FTS5, TF-IDF, Embeddings)
zclaw-runtime → 运行时 (LLM 驱动, 11 层中间件, 工具, Agent 循环)
zclaw-kernel → 核心协调 (注册, 调度, 事件, 9 Hands, 75 Skills)
zclaw-skills → 技能系统 (SKILL.md 解析, 语义路由, DAG 编排)
zclaw-hands → 自主能力 (9 个内置 Hand 实现)
zclaw-protocols → 协议支持 (MCP, A2A)
zclaw-pipeline → 流水线引擎 (v1/v2 DSL, Smart Presentation)
zclaw-growth → 成长系统 (记忆提取/检索/注入, OpenViking 分层)
zclaw-saas → SaaS 后端 (独立服务, 8080 端口, 131 API)
```
---
## 4. 数据流向
### 4.1 Admin V2 管理后台数据流
```
用户操作 → React UI → React Query → request.ts (Axios) → Vite Proxy → SaaS 后端 (:8080)
↑ ↓
└── React Query Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘
```
**关键路径:**
- Admin V2 所有请求通过 `vite.config.ts proxy` 代理到 `localhost:8080`
- API 基路径: `/api/v1/*` (前端) → `http://localhost:8080/api/v1/*` (后端)
- React Query 缓存: 自动去重 + stale-while-revalidate 模式
- SSE 端点 (`/relay/chat/completions`) 超时配置 10 分钟
### 4.2 桌面端数据流 (Tauri 模式)
```
React UI → Zustand Store → invoke() IPC → Rust Tauri Commands → Kernel → LLM/Tools/Skills/Hands
↓
SQLite (~/.zclaw/data.db)
```
### 4.3 桌面端数据流 (网关模式)
```
React UI → gateway-client.ts → WebSocket (:50051) → ZCLAW Gateway → Kernel
→ REST API (/api/*) →
```
### 4.4 桌面端数据流 (SaaS 模式)
```
React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)
llm-service.ts → relay/chat/completions → Provider → LLM API
```
### 4.5 LLM 请求路由 (4 条路径)
```
┌─────────────┐ ┌─ Direct OpenAI ────→ api.openai.com
│ │ ├─ Direct Volcengine ─→ volcengine endpoint
│ llm-service│────┤
│ │ ├─ SaaS Relay ────────→ saas.zclaw.com/relay → Provider
│ │ └─ Gateway ───────────→ invoke('agent_chat') or REST
└─────────────┘
```
---
## 5. SaaS 后端 API 接口清单
### 5.0 通用规范
- **Base URL**: `http://localhost:8080/api/v1`
- **认证方式**: `Authorization: Bearer <JWT_TOKEN>` 或 `Authorization: Bearer zclaw_<API_KEY>`
- **Content-Type**: `application/json`
- **分页响应格式**: `{ items: T[], total: number, page: number, page_size: number }`
- **错误响应格式**: `{ error: string, message: string }`
- **HTTP 状态码**: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Error
### 5.1 公开接口 (无需认证)
| # | 方法 | 路径 | 用途 | 业务价值 |
|---|------|------|------|----------|
| 1 | GET | `/api/health` | 健康检查 | 运维监控探针，检测 DB 连通性 |
| 2 | POST | `/api/v1/auth/register` | 用户注册 | 自助开户，降低运营成本 |
| 3 | POST | `/api/v1/auth/login` | 用户登录 | 身份验证入口，支持 TOTP 2FA |
| 4 | POST | `/api/v1/auth/refresh` | Token 刷新 | 无感续期，单次使用 refresh_token |
**POST /api/v1/auth/login**
请求:
```typescript
{
username: string // 接受用户名或邮箱
password: string // 8-128 字符
totp_code?: string // 6 位数字，启用 TOTP 时必填
}
```
响应:
```typescript
{
token: string // JWT access token
refresh_token: string // 单次使用 refresh token
account: AccountPublic
}
```
### 5.2 认证自服务接口 (需登录)
| # | 方法 | 路径 | 用途 |
|---|------|------|------|
| 5 | GET | `/api/v1/auth/me` | 获取当前用户信息 |
| 6 | PUT | `/api/v1/auth/password` | 修改密码 |
| 7 | POST | `/api/v1/auth/totp/setup` | 生成 TOTP 密钥 |
| 8 | POST | `/api/v1/auth/totp/verify` | 激活 TOTP 2FA |
| 9 | POST | `/api/v1/auth/totp/disable` | 关闭 TOTP 2FA |
### 5.3 账号管理接口 (Admin)
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 10 | GET | `/api/v1/accounts` | 账号列表 (支持搜索/筛选/分页) | `account:admin` |
| 11 | GET | `/api/v1/accounts/:id` | 账号详情 | `account:admin` |
| 12 | PATCH | `/api/v1/accounts/:id` | 更新账号信息 | `account:admin` |
| 13 | PATCH | `/api/v1/accounts/:id/status` | 变更账号状态 | `account:admin` |
| 14 | GET | `/api/v1/logs/operations` | 操作日志列表 | `account:admin` |
| 15 | GET | `/api/v1/stats/dashboard` | 仪表盘统计聚合 | `account:admin` |
| 16 | GET | `/api/v1/devices` | 用户设备列表 | 认证用户 |
| 17 | POST | `/api/v1/devices/register` | 注册/更新设备 | 认证用户 |
| 18 | POST | `/api/v1/devices/heartbeat` | 设备心跳 | 认证用户 |
**GET /api/v1/accounts** 查询参数:
```typescript
{
page?: number // 页码，默认 1
page_size?: number // 每页条数，默认 20
search?: string // 搜索用户名/邮箱/显示名
role?: string // 按角色筛选: super_admin | admin | user
status?: string // 按状态筛选: active | disabled | suspended
}
```
**GET /api/v1/stats/dashboard** 响应:
```typescript
{
total_accounts: number
active_accounts: number
tasks_today: number
active_providers: number
active_models: number
tokens_today_input: number
tokens_today_output: number
}
```
### 5.4 服务商管理接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 19 | GET | `/api/v1/providers` | 服务商列表 | 认证用户 |
| 20 | GET | `/api/v1/providers/:id` | 服务商详情 | 认证用户 |
| 21 | POST | `/api/v1/providers` | 创建服务商 | `provider:manage` |
| 22 | PATCH | `/api/v1/providers/:id` | 更新服务商 | `provider:manage` |
| 23 | DELETE | `/api/v1/providers/:id` | 删除服务商 | `provider:manage` |
| 24 | GET | `/api/v1/providers/:id/models` | 服务商下的模型列表 | 认证用户 |
**Provider 数据结构:**
```typescript
{
id: string
name: string // 唯一标识名，如 "openai"
display_name: string // 显示名，如 "OpenAI"
base_url: string // API 基地址
api_protocol: 'openai' | 'anthropic'
enabled: boolean
rate_limit_rpm?: number // 每分钟请求限制
rate_limit_tpm?: number // 每分钟 Token 限制
created_at: string
updated_at: string
}
```
### 5.5 模型管理接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 25 | GET | `/api/v1/models` | 模型列表 | 认证用户 |
| 26 | GET | `/api/v1/models/:id` | 模型详情 | 认证用户 |
| 27 | POST | `/api/v1/models` | 创建模型 | `model:manage` |
| 28 | PATCH | `/api/v1/models/:id` | 更新模型 | `model:manage` |
| 29 | DELETE | `/api/v1/models/:id` | 删除模型 | `model:manage` |
**Model 数据结构:**
```typescript
{
id: string
provider_id: string
model_id: string // 如 "gpt-4o"
alias: string // 显示别名
context_window: number // 上下文窗口大小
max_output_tokens: number // 最大输出 Token
supports_streaming: boolean
supports_vision: boolean
enabled: boolean
pricing_input: number // $/1M tokens
pricing_output: number // $/1M tokens
}
```
### 5.6 API Key 管理接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 30 | GET | `/api/v1/keys` | 当前用户的 API Key 列表 | 认证用户 |
| 31 | POST | `/api/v1/keys` | 创建 API Key | 认证用户 |
| 32 | POST | `/api/v1/keys/:id/rotate` | 轮换 API Key | 认证用户 |
| 33 | DELETE | `/api/v1/keys/:id` | 撤销 API Key | 认证用户 |
### 5.7 Key Pool 管理接口 (Admin)
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 34 | GET | `/api/v1/providers/:id/keys` | 服务商 Key Pool 列表 | `provider:manage` |
| 35 | POST | `/api/v1/providers/:id/keys` | 添加 Key 到 Pool | `provider:manage` |
| 36 | PUT | `/api/v1/providers/:id/keys/:keyId/toggle` | 启用/禁用 Key | `provider:manage` |
| 37 | DELETE | `/api/v1/providers/:id/keys/:keyId` | 删除 Key | `provider:manage` |
**业务价值**: Key Pool 实现多 API Key 智能轮转，自动绕过 429 限流，提升整体吞吐量。
### 5.8 中转代理接口 (Relay)
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 38 | POST | `/api/v1/relay/chat/completions` | LLM 中转请求 | `relay:use` |
| 39 | GET | `/api/v1/relay/tasks` | 中转任务列表 | 认证用户 |
| 40 | GET | `/api/v1/relay/tasks/:id` | 任务详情 | 认证用户 |
| 41 | POST | `/api/v1/relay/tasks/:id/retry` | 重试失败任务 | `relay:admin` |
| 42 | GET | `/api/v1/relay/models` | 可用模型列表 | 认证用户 |
**POST /api/v1/relay/chat/completions** — 核心中转接口
请求: OpenAI 兼容格式
```typescript
{
model: string
messages: Array<{ role: string, content: string }>
temperature?: number
max_tokens?: number
stream?: boolean // 支持 SSE 流式响应
// ... 其他字段透传给服务商
}
```
响应:
- 非流式: `application/json` — 原始服务商响应
- 流式: `text/event-stream` — SSE 事件流
**业务价值**: 统一入口代理多家 LLM 服务商，自动 Key Pool 轮转、429 处理、用量计费。
### 5.9 用量统计接口
| # | 方法 | 路径 | 用途 |
|---|------|------|------|
| 43 | GET | `/api/v1/usage` | 用量统计 (按天/按模型) |
**查询参数:**
```typescript
{
from?: string // ISO 8601 开始日期
to?: string // ISO 8601 结束日期
provider_id?: string // 按服务商筛选
model_id?: string // 按模型筛选
group_by?: 'day' | 'model'
days?: number // 最近 N 天
}
```
**响应:**
```typescript
{
total_requests: number
total_input_tokens: number
total_output_tokens: number
by_model: Array<{ model_id, count, input_tokens, output_tokens }>
by_day: Array<{ day, count, input_tokens, output_tokens }>
}
```
### 5.10 配置管理接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 44 | GET | `/api/v1/config/items` | 配置项列表 | 认证用户 |
| 45 | GET | `/api/v1/config/items/:id` | 配置项详情 | 认证用户 |
| 46 | POST | `/api/v1/config/items` | 创建配置项 | `config:write` |
| 47 | PATCH | `/api/v1/config/items/:id` | 更新配置项 | `config:write` |
| 48 | DELETE | `/api/v1/config/items/:id` | 删除配置项 | `config:write` |
| 49 | GET | `/api/v1/config/analysis` | 配置分析 | 认证用户 |
| 50 | POST | `/api/v1/config/seed` | 种子配置 | `config:write` |
| 51 | POST | `/api/v1/config/sync` | 双向配置同步 | `config:write` |
| 52 | POST | `/api/v1/config/diff` | 配置差异比较 | 认证用户 |
| 53 | GET | `/api/v1/config/sync-logs` | 同步日志 | 认证用户 |
| 54 | GET | `/api/v1/config/pull` | 批量拉取配置 | 认证用户 |
**业务价值**: 集中管理所有运行参数（服务器、Agent、记忆、LLM、安全策略），支持桌面端双向同步，推送/拉取/合并三种模式。
### 5.11 角色与权限接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 55 | GET | `/api/v1/roles` | 角色列表 | `account:read` |
| 56 | GET | `/api/v1/roles/:id` | 角色详情 | `account:read` |
| 57 | POST | `/api/v1/roles` | 创建角色 | `account:admin` |
| 58 | PUT | `/api/v1/roles/:id` | 更新角色 | `account:admin` |
| 59 | DELETE | `/api/v1/roles/:id` | 删除角色 | `account:admin` |
| 60 | GET | `/api/v1/roles/:id/permissions` | 角色权限列表 | `account:read` |
| 61 | GET | `/api/v1/permission-templates` | 权限模板列表 | `account:read` |
| 62 | GET | `/api/v1/permission-templates/:id` | 权限模板详情 | `account:read` |
| 63 | POST | `/api/v1/permission-templates` | 创建权限模板 | `account:admin` |
| 64 | DELETE | `/api/v1/permission-templates/:id` | 删除权限模板 | `account:admin` |
| 65 | POST | `/api/v1/permission-templates/:id/apply` | 批量应用权限模板 | `account:admin` |
### 5.12 Prompt 模板管理接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 66 | GET | `/api/v1/prompts` | 模板列表 | `prompt:read` |
| 67 | POST | `/api/v1/prompts` | 创建模板 | `prompt:write` |
| 68 | GET | `/api/v1/prompts/:name` | 模板详情 | `prompt:read` |
| 69 | PUT | `/api/v1/prompts/:name` | 更新模板元数据 | `prompt:write` |
| 70 | DELETE | `/api/v1/prompts/:name` | 归档模板 | `prompt:admin` |
| 71 | GET | `/api/v1/prompts/:name/versions` | 版本历史 | `prompt:read` |
| 72 | GET | `/api/v1/prompts/:name/versions/:v` | 特定版本 | `prompt:read` |
| 73 | POST | `/api/v1/prompts/:name/versions` | 发布新版本 | `prompt:write` |
| 74 | POST | `/api/v1/prompts/:name/rollback/:v` | 回滚版本 | `prompt:admin` |
| 75 | POST | `/api/v1/prompts/check` | OTA 更新检查 | 认证用户 |
**POST /api/v1/prompts/check** — OTA 更新检查
请求:
```typescript
{
device_id: string
versions: Record<string, number> // { "reflection": 3, "compaction": 2 }
}
```
响应:
```typescript
{
updates: Array<{
name: string
version: number
system_prompt: string
user_prompt_template?: string
variables: PromptVariable[]
source: string
min_app_version?: string
}>
server_time: string
}
```
**业务价值**: 集中管理 Prompt 模板，桌面端每 30 分钟检查更新，无需发版即可优化提示词。
### 5.13 Agent 模板管理接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 76 | GET | `/api/v1/agent-templates` | Agent 模板列表 | `model:read` |
| 77 | POST | `/api/v1/agent-templates` | 创建 Agent 模板 | `model:manage` |
| 78 | GET | `/api/v1/agent-templates/:id` | 模板详情 | `model:read` |
| 79 | POST | `/api/v1/agent-templates/:id` | 更新模板 | `model:manage` |
| 80 | DELETE | `/api/v1/agent-templates/:id` | 归档模板 | `model:manage` |
**AgentTemplate 数据结构:**
```typescript
{
id: string
name: string
description?: string
category: string
source: 'builtin' | 'custom'
model?: string
system_prompt?: string
tools: string[]
capabilities: string[]
temperature?: number
max_tokens?: number
visibility: 'public' | 'team' | 'private'
status: 'active' | 'archived'
current_version: number
}
```
### 5.14 遥测接口
| # | 方法 | 路径 | 用途 | 权限 |
|---|------|------|------|------|
| 81 | POST | `/api/v1/telemetry/report` | 上报遥测数据 | 认证用户 |
| 82 | GET | `/api/v1/telemetry/stats` | 按模型统计 | 认证用户 |
| 83 | GET | `/api/v1/telemetry/daily` | 按天统计 | 认证用户 |
| 84 | POST | `/api/v1/telemetry/audit` | 上报审计摘要 | 认证用户 |
**POST /api/v1/telemetry/report** 请求:
```typescript
{
device_id: string
app_version: string
entries: Array<{
model_id: string
input_tokens: number
output_tokens: number
latency_ms?: number
success: boolean
error_type?: string
timestamp: string
connection_mode: 'tauri' | 'saas'
}> // 最多 500 条/请求
}
```
**业务价值**: 桌面端批量上报本地 LLM 用量，管理员可在后台查看所有设备的 Token 消耗、延迟、成功率。
---
## 6. 桌面端内部通信
### 6.1 Tauri Commands 清单
桌面端通过 `invoke()` IPC 暴露以下命令组：
| 命令组 | 文件 | 命令数 | 用途 |
|--------|------|--------|------|
| 进程管理 | lib.rs | 10 | zclaw_start/stop/restart, doctor, health_check |
| 内核操作 | kernel_commands.rs | 34 | agent_create/chat_stream, skill_execute, hand_execute, trigger, workflow |
| 工作流 | pipeline_commands.rs | 10 | pipeline_run/progress/cancel, route_intent |
| 浏览器自动化 | browser_commands.rs | 22 | navigate/click/fill/screenshot/evaluate |
| 智能层 | intelligence_commands.rs | 35 | memory/identity/reflection/heartbeat/autonomy |
| 持久记忆 | memory_commands.rs | 14 | memory_store/get/search/export/graph |
| Viking 存储 | viking_commands.rs | 13 | viking_add/find/grep/read |
| CLI 工具 | cli_commands.rs | 13 | doctor/health/export/import |
| 安全存储 | secure_storage.rs | 4 | store/get/delete/list |
| LLM 管理 | llm_commands.rs | 3 | list_providers/test_connection |
> **总计**: 177 个 Tauri Commands (160 已接通前端 + 16 个 @reserved 预留 + 1 个未注册)
### 6.2 WebSocket 事件类型
| 方向 | 事件 | 说明 |
|------|------|------|
| Server→Client | `text_delta` | 流式文本片段 |
| Server→Client | `phase` | 阶段切换 (thinking/tool) |
| Server→Client | `tool_call` / `tool_result` | 工具调用与结果 |
| Server→Client | `hand` | Hand 自主能力触发 |
| Server→Client | `error` | 错误通知 |
| Client→Server | `message` | 发送消息 |
| Client→Server | `auth_challenge` / `auth_response` | Ed25519 握手 |
| 双向 | `ping` / `pong` | 心跳 (30s 间隔) |
---
## 7. 权限体系
### 7.1 角色定义
| 角色 | 权限范围 |
|------|----------|
| `super_admin` | 全部权限 (`admin:full`) |
| `admin` | 账号管理、服务商/模型管理、中转管理、配置读写、Prompt 读写发布 |
| `user` | 模型读取、中转使用、配置读取、Prompt 读取 |
### 7.2 权限清单
| 权限 | 说明 |
|------|------|
| `admin:full` | 超级权限，绕过所有检查 |
| `account:admin` | 账号管理 (列表、状态变更、角色分配) |
| `account:read` | 读取账号、角色、权限模板 |
| `provider:manage` | 创建/更新/删除服务商、管理 Key Pool |
| `model:manage` | 创建/更新/删除模型、Agent 模板 |
| `model:read` | 读取模型、Agent 模板 |
| `relay:use` | 使用中转 (chat completions) |
| `relay:admin` | 查看任意中转任务、重试失败任务 |
| `config:write` | 创建/更新/删除配置项、同步、种子 |
| `prompt:read` | 读取 Prompt 模板和版本 |
| `prompt:write` | 创建/更新 Prompt 模板和版本 |
| `prompt:admin` | 归档 Prompt、回滚版本 |
---
## 8. 各端交互逻辑
### 8.1 Admin 管理后台 ↔ SaaS 后端
```
┌───────────────────────────────────────────────────────────┐
│ Admin V2 浏览器 (localhost:5173) │
│ │
│ ┌──────────┐ React Query ┌──────────────┐ │
│ │ React UI │◄────────────►│ Axios │ │
│ │ 11 页面 │ Cache │ Cookie 认证 │ │
│ └──────────┘ └──────┬───────┘ │
│ │ axios() │
└──────────────────────────────────┼────────────────────────┘
│
Vite Proxy │ /api/* → localhost:8080/api/*
│
┌──────────────────────────────────┼────────────────────────┐
│ SaaS Backend (:8080) │ │
│ ┌──────▼───────┐ │
│ │ Axum Router │ │
│ │ 中间件栈: │ │
│ │ 1. Auth │ │
│ │ 2. RateLimit │ │
│ │ 3. RequestID │ │
│ │ 4. Version │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────────────▼──────────────┐ │
│ │ Handlers (131 个端点) │ │
│ │ auth/account/model/relay/ │ │
│ │ config/prompt/telemetry/ │ │
│ └─────────────┬──────────────┘ │
│ │ │
│ ┌─────────────▼──────────────┐ │
│ │ PostgreSQL (:5432) │ │
│ └─────────────────────────────┘ │
└───────────────────────────────────────────────────────────┘
```
### 8.2 桌面端交互矩阵
| 场景 | 通信方式 | 目标 | 数据 |
|------|----------|------|------|
| 本地对话 | Tauri IPC invoke() | Kernel | 消息、Agent、Skills |
| 流式响应 | Tauri Event listen() | Kernel | stream:chunk 事件 |
| 远程对话 | WebSocket :50051 | ZCLAW Gateway | 消息、事件流 |
| SaaS 登录 | HTTPS REST | SaaS :8080 | JWT 认证 |
| LLM 中转 | HTTPS REST | SaaS :8080/relay | OpenAI 兼容请求 |
| Prompt OTA | HTTPS REST | SaaS :8080/prompts/check | 版本号 → 更新 |
| 配置同步 | HTTPS REST | SaaS :8080/config/sync | 双向键值对 |
| 遥测上报 | HTTPS REST | SaaS :8080/telemetry/report | 批量用量数据 |
---
## 9. 部署与启动
### 9.1 完整启动顺序
```powershell
# start-all.ps1 启动顺序:
1. PostgreSQL → :5432 (Docker 或本地服务)
2. SaaS Backend → :8080 (zclaw-saas.exe)
3. ChromeDriver → :4444 (可选, 用于 Browser Hand)
4. Desktop Dev → :1420 (Tauri dev)
```
### 9.2 SaaS 后端配置
#### 配置加载优先级
```
ZCLAW_SAAS_CONFIG (精确路径) > ZCLAW_ENV (环境选择) > ./saas-config.toml (默认)
```
环境配置文件:
- `ZCLAW_ENV=development` -> `config/saas-development.toml`
- `ZCLAW_ENV=production` -> `config/saas-production.toml`
- `ZCLAW_ENV=test` -> `config/saas-test.toml`
环境变量覆盖:
- `ZCLAW_DATABASE_URL` — 覆盖数据库 URL (避免配置文件存密码)
- `ZCLAW_SAAS_JWT_SECRET` — JWT 签名密钥 (生产环境必须设置)
- `ZCLAW_TOTP_ENCRYPTION_KEY` — TOTP/AES-256-GCM 加密密钥 (hex 64 字符)
- `ZCLAW_SAAS_DEV` — 开发模式 (允许使用不安全的默认密钥)
#### 配置结构
```toml
# saas-config.toml
[server]
host = "0.0.0.0"
port = 8080
cors_origins = []
[database]
url = "postgres://postgres:123123@localhost:5432/zclaw"
[auth]
jwt_expiration_hours = 24
totp_issuer = "ZCLAW SaaS"
refresh_token_hours = 168 # 7 天
[relay]
max_queue_size = 1000
max_concurrent_per_provider = 5 # 预留
batch_window_ms = 50 # 预留
retry_delay_ms = 1000
max_attempts = 3
[rate_limit]
requests_per_minute = 60
burst = 10
# 声明式定时任务 (新增)
[[scheduler.jobs]]
name = "cleanup-refresh-tokens"
interval = "1h"
task = "cleanup_refresh_tokens"
run_on_start = false
[[scheduler.jobs]]
name = "cleanup-rate-limit"
interval = "5m"
task = "cleanup_rate_limit"
run_on_start = false
```
#### 连接池参数
| 参数 | 值 | 说明 |
|------|-----|------|
| max_connections | 50 | 最大并发连接数 |
| min_connections | 5 | 最小空闲连接数 |
| acquire_timeout | 10s | 获取连接超时 |
| idle_timeout | 300s | 空闲连接回收 |
| max_lifetime | 1800s | 连接最大生命周期 |
#### Worker 系统
| Worker | 职责 | 触发方式 |
|--------|------|---------|
| LogOperationWorker | 异步写入操作日志 | Handler 派发 |
| CleanupRefreshTokensWorker | 清理过期 Refresh Token | Scheduler 定时 |
| CleanupRateLimitWorker | 清理过期限流条目 | Scheduler 定时 |
| RecordUsageWorker | 记录 Token 用量 | Relay Handler 派发 |
| UpdateLastUsedWorker | 更新 Key 最后使用时间 | Relay Handler 派发 |
| AggregateUsageWorker | 日/月用量聚合 | Scheduler 定时 |
| GenerateEmbeddingWorker | 知识条目 embedding 生成 | Handler 派发 |
#### SQL 迁移系统
- Schema 版本: **v8**
- 迁移目录: `crates/zclaw-saas/migrations/`
- 时间戳类型: **TIMESTAMPTZ** (新库)，向后兼容 TEXT (旧库)
- 迁移文件按文件名排序执行
---
## 10. 接口设计背景与业务价值
### 10.1 中转代理 (Relay) — 核心收入引擎
**背景**: 多家 LLM 服务商 API 各不相同，用户需统一入口。
**设计价值**:
- OpenAI 兼容接口降低接入成本
- Key Pool 智能轮转绕过限流
- 自动 429 处理 + 冷却恢复
- 按账号精确计费 (input/output tokens)
### 10.2 Prompt OTA — 无感更新
**背景**: Prompt 工程需要频繁迭代，但桌面端发版周期长。
**设计价值**:
- 集中管理 reflection/compaction/extraction 等核心 Prompt
- 桌面端每 30 分钟自动检查更新
- 版本化 + 回滚能力
- min_app_version 兼容性控制
### 10.3 配置同步 — 多设备一致
**背景**: 用户多台设备需保持配置一致。
**设计价值**:
- push/pull/merge 三种同步模式
- 乐观锁 (client_timestamps) 冲突检测
- 只读 diff 不修改数据
- 同步日志可追溯
### 10.4 Key Pool — 高可用保障
**背景**: 单个 API Key 容易触发限流 (429)。
**设计价值**:
- 多 Key 按优先级智能选择
- 429 自动冷却 + 切换
- RPM/TPM 限额独立配置
- 配额重置周期支持
### 10.5 遥测上报 — 数据驱动优化
**背景**: 桌面端本地 LLM 用量无法直接观测。
**设计价值**:
- 批量上报 (500 条/次) 减少请求
- 按模型聚合: Token 消耗、延迟、成功率
- 按天聚合: 请求量、设备活跃度
- 审计摘要: 操作类型 + 结果
---
> **文档统计**: 131 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务 | 7 个 Workers | 声明式 Scheduler | SQL Schema v8

541
docs/archive/old-analysis/ZCLAW-DEEP-ANALYSIS-v2.md Normal file
View File

@@ -0,0 +1,541 @@
# ZCLAW 项目系统性深度分析报告 v2
> **分析日期：** 2026-03-21
> **分析范围：** 代码结构、架构设计、技术栈、业务逻辑、数据流、性能安全
---
## 一、项目概览
### 1.1 项目定位
ZCLAW 是一个基于 ZCLAW 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
### 1.2 技术栈全景
| 层级 | 技术选型 | 成熟度 |
|------|----------|--------|
| 桌面框架 | Tauri 2.0 (Rust + React 19) | ✅ 合理 |
| 前端 | React 19 + TailwindCSS 4 + Zustand 5 + Framer Motion + Lucide | ✅ 现代 |
| 后端通信 | WebSocket (Gateway Protocol v3) + Tauri Commands | ✅ 完整 |
| 状态管理 | Zustand (13 个 Store) + Facade Pattern | ⚠️ 过度拆分但已收敛 |
| 配置格式 | TOML | ✅ 用户友好 |
| 测试 | Vitest + Playwright | ✅ 覆盖较好 |
| 依赖 | 精简 (React 19, Zustand 5, Tauri 2) | ✅ 轻量 |
### 1.3 规模数据
| 维度 | 数量 |
|------|------|
| 前端组件 | 50+ .tsx 文件 |
| Lib 工具 | 40+ 文件 |
| Store 文件 | 13 个 Zustand stores |
| 类型定义 | 13 个类型文件 |
| Skills | 68 个 SKILL.md |
| Hands | 7 个 HAND.toml |
| Rust 模块 | 8 个主要模块 |
| 测试文件 | 15+ 测试文件 |
---
## 二、架构深度分析
### 2.1 整体架构图
```
┌──────────────────────────────────────────────────────────────────┐
│ React UI Layer │
│ ChatArea, Sidebar, HandsPanel, WorkflowEditor, TeamView... │
├──────────────────────────────────────────────────────────────────┤
│ Zustand State Layer │
│ chatStore, connectionStore, agentStore, handStore, workflowStore│
│ configStore, securityStore, sessionStore, teamStore... │
├──────────────────────────────────────────────────────────────────┤
│ Client Layer │
│ GatewayClient │ IntelligenceClient │ TeamClient │ BrowserClient │
├──────────────────────────────────────────────────────────────────┤
│ Tauri IPC / WebSocket │
├──────────────────────────────────────────────────────────────────┤
│ Rust Backend │
│ browser │ intelligence │ memory │ llm │ viking │ secure_storage │
└──────────────────────────────────────────────────────────────────┘
↕
ZCLAW Kernel / OpenViking
```
### 2.2 前端架构分析
#### 2.2.1 组件层 (desktop/src/components/)
**组件分类：**
| 类别 | 组件数 | 代表组件 |
|------|--------|----------|
| 聊天/对话 | 8 | ChatArea, ConversationList, MessageSearch |
| Agent/Clone | 6 | CloneManager, AgentOnboardingWizard, PersonalitySelector |
| 自动化 Hands | 10 | HandsPanel, HandList, HandParamsForm, HandApprovalModal |
| 工作流 | 4 | WorkflowList, WorkflowEditor, WorkflowHistory |
| 团队协作 | 5 | TeamList, TeamCollaborationView, DevQALoop |
| 记忆/智能 | 6 | MemoryPanel, MemoryGraph, ActiveLearningPanel, ReflectionLog |
| 安全/审计 | 5 | SecurityLayersPanel, SecurityStatus, AuditLogsPanel |
| 浏览器自动化 | 8 | BrowserHandCard, ScreenshotPreview, TaskTemplateModal |
| 设置 | 12 | SettingsLayout, General, ModelsAPI, MCPServices... |
| UI 基础组件 | 15 | Button, Card, Input, Badge, Toast, EmptyState... |
**评价：** ✅ 组件职责划分清晰，分类合理
#### 2.2.2 状态管理层 (desktop/src/store/)
**13 个 Zustand Stores：**
| Store | 职责 | 状态 |
|-------|------|------|
| chatStore | 聊天消息、会话管理 | ✅ 活跃 |
| connectionStore | Gateway 连接状态 | ✅ 活跃 |
| agentStore | Clone/Agent 管理 | ✅ 活跃 |
| handStore | Hands/Triggers/Approvals | ✅ 活跃 |
| workflowStore | 工作流管理 | ✅ 活跃 |
| configStore | 配置/渠道/技能/模型 | ✅ 活跃 |
| securityStore | 安全状态/审计日志 | ✅ 活跃 |
| sessionStore | 会话管理 | ✅ 活跃 |
| teamStore | 团队协作 | ✅ 活跃 |
| skillMarketStore | 技能市场 | ✅ 活跃 |
| memoryGraphStore | 记忆图谱 | ✅ 活跃 |
| activeLearningStore | 主动学习 | ✅ 活跃 |
| browserHandStore | 浏览器自动化 | ✅ 活跃 |
**gatewayStore.ts 门面模式：**
- 从 1800+ 行缩减到 352 行
- 作为向后兼容的 facade 层
- 标记为 `@deprecated`，推荐使用领域 Store
**评价：** ✅ Store 架构已统一，拆分合理
#### 2.2.3 通信层 (desktop/src/lib/)
**核心客户端：**
| 客户端 | 规模 | 职责 |
|--------|------|------|
| gateway-client.ts | 65KB | WebSocket/REST 通信、认证、心跳 |
| intelligence-client.ts | ~15KB | 记忆/心跳/反思/身份统一API |
| team-client.ts | ~8KB | Team API REST 客户端 |
| browser-client.ts | ~5KB | 浏览器自动化客户端 |
| autonomy-manager.ts | ~15KB | L4 分层授权系统 |
**GatewayClient 核心功能：**
- ✅ WebSocket 连接管理（自动重连、心跳）
- ✅ REST API 降级（ZCLAW 模式）
- ✅ Ed25519 设备认证
- ✅ 流式响应处理（chatStream）
- ✅ 事件订阅机制
**问题：**
- ⚠️ 文件过大（65KB），职责过重
- ⚠️ 部分方法过长（如 handleZCLAWStreamEvent 100+ 行）
### 2.3 Rust 后端架构分析
#### 2.3.1 模块组织 (desktop/src-tauri/src/)
```
lib.rs (入口)
├── viking_commands.rs # OpenViking CLI sidecar
├── viking_server.rs # OpenViking 本地服务器管理
├── memory/ # 内存提取和上下文构建
│ ├── extractor.rs # LLM 驱动的记忆提取
│ ├── context_builder.rs # L0/L1/L2 分层上下文
│ └── persistent.rs # SQLite 持久化
├── llm/ # LLM 接口（Doubao/OpenAI/Anthropic）
├── browser/ # 浏览器自动化（Fantoccini）
├── secure_storage.rs # OS Keyring/Keychain
├── memory_commands.rs # 持久化内存命令
└── intelligence/ # 智能层（已从前端迁移）
├── heartbeat.rs # 心跳引擎
├── compactor.rs # 上下文压缩
├── reflection.rs # 反思引擎
└── identity.rs # Agent 身份管理
```
#### 2.3.2 状态管理模式
**Tauri State 注入：**
```rust
// 使用 Arc<Mutex<T>> 包装
pub struct BrowserState {
client: Arc<RwLock<BrowserClient>>,
}
// Tauri 命令中使用 State 管理
#[tauri::command]
async fn browser_navigate(
state: State<'_, BrowserState>,
url: String,
) -> Result<String, String>
```
**评价：** ✅ 线程安全，模式合理
#### 2.3.3 SQLite 持久化
**数据库架构：**
```sql
CREATE TABLE memories (
id TEXT PRIMARY KEY,
agent_id TEXT NOT NULL,
memory_type TEXT NOT NULL,
content TEXT NOT NULL,
importance INTEGER DEFAULT 5,
source TEXT DEFAULT 'auto',
tags TEXT DEFAULT '[]',
conversation_id TEXT,
created_at TEXT NOT NULL,
last_accessed_at TEXT NOT NULL,
access_count INTEGER DEFAULT 0,
embedding BLOB
);
-- 索引: agent_id, memory_type, created_at, importance
```
**评价：** ✅ 结构清晰，有索引优化
#### 2.3.4 安全存储
**keyring crate 使用：**
- Windows: Credential Manager
- macOS: Keychain
- Linux: libsecret
**评价：** ✅ 符合安全最佳实践
---
## 三、技术栈分析
### 3.1 框架选型
| 框架 | 选择 | 评价 |
|------|------|------|
| 桌面框架 | Tauri 2.0 | ✅ 体积小（~10MB），性能好 |
| 前端框架 | React 19 | ✅ 最新特性，但未充分利用 |
| 状态管理 | Zustand 5 | ✅ 轻量、类型安全 |
| 样式 | TailwindCSS 4 | ✅ 原子化，开发效率高 |
| 动画 | Framer Motion | ✅ 声明式动画 |
| 桌面封装 | Tauri 2 | ✅ 成熟稳定 |
### 3.2 依赖管理
**package.json 关键依赖：**
```json
{
"dependencies": {
"@tauri-apps/api": "^2",
"react": "^19.1.0",
"zustand": "^5.0.11",
"framer-motion": "^12.36.0",
"lucide-react": "^0.577.0"
}
}
```
**Cargo.toml 关键依赖：**
```toml
[dependencies]
tauri = { version = "2", features = [] }
tokio = { version = "1", features = ["full"] }
sqlx = { version = "0.7", features = ["runtime-tokio", "sqlite"] }
fantoccini = "0.21" # Browser automation
keyring = "3" # Secure storage
```
**评价：** ✅ 依赖精简，版本稳定
---
## 四、业务逻辑分析
### 4.1 聊天功能实现
**消息流程：**
```
用户输入 → sendMessage()
→ 上下文压缩检查 (compactor.checkThreshold)
→ 记忆增强 (intelligenceClient.memory.search)
→ 添加用户消息
→ 创建流式占位消息
→ gatewayClient.chatStream()
→ 收集 tool/hand/workflow 事件
→ 流结束 → 提取记忆 (memory-extractor)
→ 触发反思 (intelligenceClient.reflection)
```
**评价：** ✅ 流程完整，异常处理充分
### 4.2 记忆系统实现
**记忆提取模式：**
1. **LLM 提取** - 使用 `llmExtract()` 语义提取
2. **规则提取** - 正则匹配模式
**记忆分类：**
- fact: 用户事实
- preference: 用户偏好
- lesson: 经验教训
- context: 上下文
- task: 任务
**分层上下文加载（L0/L1/L2）：**
```
L0 (Quick Scan): 向量相似度搜索，返回概览
L1 (Standard): 加载 top 候选的 overview
L2 (Deep): 加载最相关项的完整内容
```
**评价：** ✅ 设计完善，已迁移到 Rust 后端
### 4.3 自主能力系统
**L4 分层授权：**
| 级别 | 自动内存保存 | 自动压缩 | 自动反思 |
|------|-------------|---------|---------|
| supervised | ❌ | ❌ | ❌ |
| assisted | ✅ | ✅ | ✅ |
| autonomous | ✅ | ✅ | ✅ |
**风险评估：**
- ACTION_RISK_MAP 定义每种操作的风险等级
- importanceMax + riskMax 双重判断
- 所有操作记录审计日志
**评价：** ✅ 授权机制完善
---
## 五、数据流与接口分析
### 5.1 整体数据流
```
用户操作 → React UI → Zustand Store → GatewayClient
↓
WebSocket / REST
↓
ZCLAW Kernel
↓
Skills / Hands 执行
```
### 5.2 Gateway Protocol v3
**消息类型：**
- req/res: 请求/响应模式
- event: 事件推送
- stream: 流式响应
**认证：** Ed25519 签名
### 5.3 Tauri Commands
**70+ Commands 分类：**
| 类别 | 命令数 | 示例 |
|------|--------|------|
| Browser | 18 | browser_navigate, browser_click, browser_screenshot |
| Memory | 12 | memory_store, memory_search, memory_stats |
| Intelligence | 15 | heartbeat_*, reflection_*, identity_* |
| Viking | 9 | viking_status, viking_find, viking_read |
| Gateway | 8 | gateway_start, gateway_stop, gateway_status |
| LLM | 3 | llm_complete |
**评价：** ✅ 接口粒度合理，类型安全
---
## 六、性能与安全分析
### 6.1 性能分析
#### 6.1.1 渲染性能
**虚拟滚动：** 已使用 react-window
**潜在问题：**
- ⚠️ 大量消息时可能 re-render
- ⚠️ 某些 Store selector 未优化
#### 6.1.2 网络性能
**WebSocket 心跳：**
- 间隔：30 秒
- 超时：10 秒
- 最大丢失：3 次
**问题：**
- ⚠️ 单 WebSocket 连接，复用机制可优化
#### 6.1.3 计算性能
**Token 估算：**
```rust
// CJK: ~1.5 tokens/字符
// ASCII: ~0.3 tokens/字符
```
**评价：** ✅ 算法合理
### 6.2 安全分析
#### 6.2.1 认证机制
**Ed25519 设备认证：** ✅ 安全
#### 6.2.2 敏感数据
**存储：**
- API Key: OS Keyring ✅
- Token: OS Keyring ✅
- Theme: localStorage ⚠️
**问题：**
- ⚠️ localStorage 仍用于部分前端配置
- ⚠️ 日志可能包含敏感信息
#### 6.2.3 输入验证
**SQL 注入：** ✅ 使用参数化查询
**XSS：** ⚠️ 需要确认输出转义
---
## 七、测试覆盖分析
### 7.1 测试文件分布
| 测试文件 | 覆盖范围 |
|----------|----------|
| autonomy-manager.test.ts | L4 授权逻辑 |
| agent-memory.test.ts | 记忆系统 |
| context-compactor.test.ts | 上下文压缩 |
| heartbeat-reflection.test.ts | 心跳和反思 |
| gatewayStore.test.ts | Store 状态 |
| chatStore.test.ts | 聊天逻辑 |
| teamStore.test.ts | 团队协作 |
| browserHandStore.test.ts | 浏览器手 |
| ws-client.test.ts | WebSocket 客户端 |
**评价：** ✅ 核心逻辑有覆盖，但可增加更多边界测试
### 7.2 E2E 测试
**Playwright 配置：** ✅ 已配置 chromium/chromium-headed
---
## 八、代码质量分析
### 8.1 大型文件
| 文件 | 规模 | 问题 |
|------|------|------|
| gateway-client.ts | 65KB | 职责过重 |
| gatewayStore.ts | 352行 | 已是 facade，仍偏大 |
### 8.2 技术债务
**TODO/FIXME：**
- intelligence/mod.rs: Phase 3 迁移中
- viking_commands.rs: 平台二进制解析
**Rust unsafe：**
- context_builder.rs: 多处 unwrap()
### 8.3 localStorage 使用
**仍在使用 localStorage 的模块：**
- intelligence-client.ts: 降级模式
- skill-discovery.ts: 技能索引缓存
- agent-swarm.ts: 蜂群历史
- gateway-api.ts: 主题等配置
---
## 九、分析维度评分
| # | 维度 | 评分 | 主要发现 |
|---|------|------|----------|
| 1 | 代码结构 | 4/5 | 组件划分清晰，文件组织合理 |
| 2 | 架构设计 | 4/5 | 分层清晰，模块职责明确 |
| 3 | 技术选型 | 4/5 | 框架选择合理，依赖精简 |
| 4 | 业务实现 | 4/5 | 核心流程完整，异常处理充分 |
| 5 | 数据流设计 | 4/5 | 流向清晰，同步机制完善 |
| 6 | 接口设计 | 4/5 | Tauri Commands 粒度合理 |
| 7 | 性能表现 | 3/5 | 存在优化空间（re-render、WebSocket） |
| 8 | 安全合规 | 4/5 | 认证机制完善，部分数据需加强 |
| 9 | 测试覆盖 | 3/5 | 核心逻辑有覆盖，边界测试不足 |
| 10 | 文档质量 | 4/5 | 文档详尽，部分需更新 |
| 11 | 可维护性 | 4/5 | 架构清晰，部分大文件需重构 |
| 12 | 可扩展性 | 4/5 | Plugin 机制、Skills 系统完善 |
**综合评分：3.8 / 5.0**
---
## 十、关键问题清单
### 🔴 P0 - 需立即处理
1. **gateway-client.ts 过大** (65KB)
- 建议：拆分为 gateway-core.ts, gateway-ws.ts, gateway-rest.ts
2. **localStorage 降级风险**
- intelligence-client.ts 在非 Tauri 环境使用 localStorage
- 建议：统一使用 Rust 后端，移除 localStorage 降级
### 🟡 P1 - 应尽快处理
3. **Rust unwrap() 风险**
- context_builder.rs 多处 unsafe unwrap
- 建议：使用 expect() 并添加错误信息
4. **测试覆盖不足**
- E2E 测试不稳定
- 建议：增加边界测试，提高测试稳定性
### 🟢 P2 - 计划处理
5. **Store selector 优化**
- 避免不必要的 re-render
- 建议：使用 Zustand 的 shallow 比较
6. **WebSocket 连接池化**
- 当前单连接，可考虑连接池
- 建议：评估性能瓶颈后优化
---
## 十一、头脑风暴议题
详见 `BRAINSTORMING-SESSION.md`
---
## 十二、附录
### A. 关键文件索引
| 文件 | 位置 | 说明 |
|------|------|------|
| CLAUDE.md | 根目录 | 项目规范文档 |
| gateway-client.ts | desktop/src/lib/ | 核心通信客户端 |
| intelligence-client.ts | desktop/src/lib/ | 智能层统一 API |
| chatStore.ts | desktop/src/store/ | 聊天状态管理 |
| lib.rs | desktop/src-tauri/src/ | Rust 后端入口 |
| intelligence/ | desktop/src-tauri/src/ | 智能层 Rust 实现 |
| memory/ | desktop/src-tauri/src/ | 内存持久化 |
### B. 参考文档
- docs/analysis/ZCLAW-DEEP-ANALYSIS.md (2026-03-20)
- docs/features/00-architecture/
- docs/plans/INTELLIGENCE-LAYER-MIGRATION.md

345
docs/archive/old-analysis/ZCLAW-DEEP-ANALYSIS.md Normal file
View File

@@ -0,0 +1,345 @@
# ZCLAW 项目深度梳理分析与头脑风暴
> 分析日期：2026-03-20
## 一、项目全景概览
ZCLAW 是一个基于 ZCLAW (类 ZCLAW) 定制化的中文优先 AI Agent 桌面客户端，采用 Tauri 2.0 (Rust + React 19) 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
### 1.1 技术栈全景
| 层级 | 技术选型 | 成熟度 |
|------|----------|--------|
| 桌面框架 | Tauri 2.0 (Rust + React 19) | ✅ 合理 |
| 前端 | React 19 + TailwindCSS + Zustand + Framer Motion + Lucide | ✅ 现代 |
| 后端通信 | WebSocket (Gateway Protocol v3) + Tauri Commands | ✅ 完整 |
| 状态管理 | Zustand (13 个 Store 文件) + Composite Store | ⚠️ 过度拆分 |
| 配置格式 | TOML (替代 JSON) | ✅ 用户友好 |
| 测试 | Vitest + jsdom (317 tests) | ✅ 覆盖良好 |
| 依赖 | 极精简 (ws + zod) | ✅ 轻量 |
### 1.2 规模数据
| 维度 | 数量 |
|------|------|
| 前端组件 | 50+ .tsx 文件 (88 个 components 目录项) |
| Lib 工具 | 42 个 lib 文件 (~65KB gateway-client 最大) |
| Store 文件 | 13 个 (gatewayStore 59KB 为最大单文件) |
| 类型定义 | 13 个类型文件 |
| Skills | 68 个 SKILL.md 技能定义 |
| Hands | 7 个 HAND.toml 能力包 |
| Plugins | 3 个 (chinese-models, feishu, ui) |
| 测试 | 15 个测试文件, 317 tests |
| 文档 | 84 个 docs 目录项 |
---
## 二、架构深度分析
### 2.1 数据流架构
```
用户操作 → React UI → Zustand Store → GatewayClient (WS) → ZCLAW Kernel
↘ TauriGateway (IPC) → Rust Backend
↘ VikingClient → OpenViking (向量DB)
```
**优点：**
- 清晰的分层设计，UI/Store/Client 职责明确
- 统一的 Gateway Client 抽象层，禁止组件内直接创建 WS
**问题：**
- gatewayStore.ts 59KB，是一个巨型 God Store，虽然已拆分出 connectionStore/agentStore/handStore 等，但旧的 gatewayStore 仍保留且被 App.tsx 直接引用
- Store Coordinator (store/index.ts) 的 useCompositeStore 订阅了所有 store 的几乎全部状态，会导致任何状态变化触发全量 re-render
### 2.2 通信层分析
**Node.js 端 (src/gateway/):**
- manager.ts — 子进程管理，有自动重启、健康检查，设计完整
- ws-client.ts — 完整的 Protocol v3 握手、请求/响应、事件订阅、自动重连
**浏览器端 (desktop/src/lib/gateway-client.ts):**
- 65KB 的单文件，职责过重，包含了连接管理、RPC 调用、事件监听、所有业务方法
### 2.3 智能层分析
这是 ZCLAW 最有价值的差异化层：
| 模块 | 文件 | 测试 | 集成 |
|------|------|------|------|
| Agent 记忆 | agent-memory.ts (14KB) | 42 tests | ✅ MemoryPanel |
| 身份演化 | agent-identity.ts (10KB) | ✅ | ❓ 后端 |
| 上下文压缩 | context-compactor.ts (14KB) | 23 tests | ✅ chatStore |
| 自我反思 | reflection-engine.ts (21KB) | 28 tests | ✅ ReflectionLog |
| 心跳引擎 | heartbeat-engine.ts (10KB) | ✅ | ❓ 未验证 |
| 自主授权 | autonomy-manager.ts (15KB) | ✅ | ✅ AutonomyConfig |
| 主动学习 | active-learning.ts (10KB) | ✅ | ✅ ActiveLearningPanel |
| Agent 蜂群 | agent-swarm.ts (16KB) | 43 tests | ✅ SwarmDashboard |
| 向量记忆 | vector-memory.ts (11KB) | 10 tests | ❌ 未集成到 UI |
### 2.4 前端组件分析
**已集成且工作正常：**
ChatArea, RightPanel (多 tab), Sidebar, Settings (10 页), HandsPanel, HandApprovalModal, SwarmDashboard, TeamCollaborationView, SkillMarket, AgentOnboardingWizard, AutomationPanel
**存在但集成度低：**
HeartbeatConfig, CreateTriggerModal, PersonalitySelector, ScenarioTags, DevQALoop
---
## 三、SWOT 分析
### 💪 优势 (Strengths)
1. **技术栈先进** — Tauri 2.0 比 Electron 体积小 10x+，性能好
2. **智能层设计深刻** — 记忆系统、身份演化、自我反思、上下文压缩是真正的差异化能力
3. **Skills 生态丰富** — 68 个 Skill 覆盖写作、数据分析、社媒运营、前端开发等
4. **Hands 系统完整** — 7 个能力包 + 审批/触发/审计全链路
5. **中文优先** — 中文模型 Provider (GLM/Qwen/Kimi/MiniMax) + 飞书集成
6. **测试覆盖好** — 317 tests, 涵盖核心 lib 和 store
7. **文档极其详尽** — 84 个文档文件，有架构图、偏离分析、审计报告、知识库
### 🔴 劣势 (Weaknesses)
1. **代码膨胀严重**
- gatewayStore.ts 59KB, gateway-client.ts 65KB — 单文件过大
- 42 个 lib 文件，部分职责重叠 (viking-*.ts 有 5 个文件)
- 88 个 components，复杂度管理困难
2. **v1→v2 架构迁移未彻底**
- src/core/ 归档代码仍保留，v1 的 multi-agent/memory/proactive 与 v2 的 desktop/src/lib 存在概念重叠
- 新旧 store 并存 (gatewayStore vs connectionStore/agentStore/...)
3. **前后端耦合不清晰**
- 大量智能逻辑 (记忆、反思、压缩) 在前端 lib 中实现
- 这些应该是后端/Gateway 的职责，放在前端会导致：数据不持久、多端不同步、逻辑重复
4. **真实集成测试缺失**
- PROGRESS.md 中 Phase 4 "真实集成测试"全部未完成
- 没有端到端测试验证 Gateway 连接→消息收发→模型调用
5. **~~Tauri Rust 后端基本空白~~** → ✅ **已实现 85-90%**（更新 2026-03-20）
**已实现的 Tauri Commands：**
- ZCLAW Gateway 管理（start/stop/restart/status/doctor）
- OpenViking 记忆系统（CLI sidecar + 本地服务器）
- 浏览器自动化（Fantoccini WebDriver）
- 安全存储（OS Keyring/Keychain）
- LLM 集成（Doubao/OpenAI/Anthropic）
- 记忆提取和上下文构建
- 进程健康检查（`zclaw_health_check`）
6. **配置系统双重标准**
- config.toml + chinese-providers.toml 是 TOML 格式
- 但 README 提到 zclaw.default.json，plugins 使用 plugin.json
- 配置格式不统一
### 🟡 机会 (Opportunities)
1. **中国 AI Agent 市场爆发** — 智谱/通义/月之暗面/DeepSeek 的中文模型生态成熟
2. **本地优先隐私诉求增长** — 企业和个人对数据隐私要求越来越高
3. **ZCLAW 生态缺口** — 市场上没有优质的中文定制化 ZCLAW 桌面客户端
4. **飞书+企业微信整合** — 企业 IM 集成是刚需，特别是在中国市场
5. **Skill 市场变现** — 74 个 Skills 可以发展成社区市场
### 🔵 威胁 (Threats)
1. **竞品迭代极快** — Cursor/Windsurf/AutoClaw/QClaw 都在快速迭代
2. **ZCLAW 上游变化** — Gateway Protocol 版本升级可能导致兼容性问题
3. **LLM API 不稳定** — 中国模型厂商的 API 变更频繁
4. **单人/小团队维护压力** — 50+ 组件、42 个 lib、13 个 store 的维护成本极高
---
## 四、关键问题深度诊断
### 4.1 🔴 最大风险：前端承担了后端职责
目前 desktop/src/lib/ 下有大量本应属于后端的逻辑：
```
agent-memory.ts → 应在 Gateway/Rust 端
agent-identity.ts → 应在 Gateway/Rust 端
reflection-engine.ts → 应在 Gateway/Rust 端
heartbeat-engine.ts → 应在 Gateway/Rust 端
context-compactor.ts → 应在 Gateway/Rust 端
agent-swarm.ts → 应在 Gateway/Rust 端
vector-memory.ts → 应在 Gateway/Rust 端
```
**后果：**
- 关闭浏览器/桌面端后，心跳、反思、主动学习全部停止
- 数据持久化依赖 localStorage，不可靠
- 无法多端共享 Agent 状态
### 4.2 ✅ Store 架构已统一（已更新 2026-03-20）
**Store 迁移已完成：**
| 领域 Store | 职责 | 状态 |
|------------|------|------|
| connectionStore.ts | Gateway 连接状态 | ✅ 活跃 |
| agentStore.ts | Agent/Clone 管理 | ✅ 活跃 |
| handStore.ts | Hands 和触发器 | ✅ 活跃 |
| workflowStore.ts | 工作流 | ✅ 活跃 |
| configStore.ts | 配置管理 | ✅ 活跃 |
| securityStore.ts | 安全状态 | ✅ 活跃 |
| sessionStore.ts | 会话管理 | ✅ 活跃 |
| chatStore.ts | 聊天消息 | ✅ 活跃 |
| teamStore.ts | 团队协作 | ✅ 活跃 |
| skillMarketStore.ts | 技能市场 | ✅ 活跃 |
| memoryGraphStore.ts | 记忆图谱 | ✅ 活跃 |
| activeLearningStore.ts | 主动学习 | ✅ 活跃 |
| browserHandStore.ts | 浏览器自动化 | ✅ 活跃 |
**gatewayStore.ts 现状：**
- 从 1800+ 行缩减到 352 行
- 作为向后兼容的 facade 层
- 标记为 `@deprecated`，新组件应使用领域 Store
**useCompositeStore 已删除**（是死代码）
### 4.3 ✅ 文档 vs 现实的差距（已更新 2026-03-20）
**经核实，组件集成状态比原文档描述的更好：**
| 组件 | 原文档标记 | 实际状态 | 集成路径 |
|------|------------|----------|----------|
| PersonalitySelector | ❓ 未验证 | ✅ 已集成 | AgentOnboardingWizard |
| ScenarioTags | ❓ 未验证 | ✅ 已集成 | AgentOnboardingWizard |
| HeartbeatConfig | ❓ 未验证 | ✅ 已集成 | SettingsLayout |
| CreateTriggerModal | ❓ 未验证 | ✅ 已集成 | useHandStore |
| DevQALoop | ❓ 未验证 | ✅ 已集成 | TeamOrchestrator (新增) |
**详细分析见：** `docs/analysis/COMPONENT-INTEGRATION-STATUS.md`
---
## 五、头脑风暴：未来方向
### 💡 方向一：架构收敛 — "做减法"（推荐优先级 P0）
**核心思想：** 项目已经膨胀过快，在增加新功能前应先收敛。
| 行动 | 效果 | 工作量 |
|------|------|--------|
| 将智能层 lib 迁移到 Tauri Rust 端或 Gateway 插件 | 后端持久运行，多端共享 | 大 |
| 彻底删除旧 gatewayStore.ts，统一用拆分后的 stores | 消除重复、降低 re-render | 中 |
| 合并 viking-*.ts (5 文件 → 1-2 文件) | 降低复杂度 | 小 |
| 拆分 gateway-client.ts (65KB → 模块化) | 可维护性提升 | 中 |
| 统一配置格式 (TOML 或 JSON，不混用) | 用户体验统一 | 小 |
### 💡 方向二：端到端可用性 — "跑通闭环"（推荐优先级 P0）
**核心思想：** 317 个单元测试通过不代表产品可用，需要真实跑通。
| 行动 | 验证点 |
|------|--------|
| 安装 ZCLAW，验证 Gateway 连接 | 子进程启动 → WS 握手 → 心跳 |
| 配置中文模型 API Key，测试对话 | 流式响应 → 模型切换 → 上下文管理 |
| 测试飞书 Channel 收发消息 | OAuth → 消息接收 → Agent 处理 → 回复 |
| 测试 Hands 触发完整流程 | 意图识别 → 参数收集 → 审批 → 执行 → 结果 |
| 验证记忆持久化 | 重启后记忆保留 → 跨会话记忆命中 |
### 💡 方向三：Tauri Rust 后端落地 — "真正的桌面应用"
**现状：** desktop/src-tauri/ 基本空白，大量能力应由 Rust 端承担。
**设想：**
```rust
// Tauri Commands 愿景
#[tauri::command]
async fn start_gateway(config: GatewayConfig) -> Result<GatewayStatus>
#[tauri::command]
async fn memory_search(query: String) -> Result<Vec<MemoryEntry>>
#[tauri::command]
async fn heartbeat_tick() -> Result<HeartbeatResult>
#[tauri::command]
async fn secure_store_get(key: String) -> Result<String>
```
**好处：**
- Gateway 生命周期由 Rust 管理，稳定性↑
- 记忆/反思/心跳在 Rust 后台持续运行
- 安全存储用系统 Keychain，不再依赖 localStorage
- 离线能力：Rust 端可以在无网络时缓存操作
### 💡 方向四：差异化功能深化 — "不做小 ChatGPT"
ZCLAW 不应与 ChatGPT/Claude Desktop 竞争"对话体验"，而应聚焦：
| 差异化方向 | 竞品不具备 | 实现路径 |
|------------|------------|----------|
| "AI 分身"日常代理 | AutoClaw 有但不开放 | Clone 系统 + 飞书/微信 Channel → 让 AI 分身帮你回消息、整理日程 |
| "本地知识库" Agent | ChatGPT/Claude 是云端 | 向量记忆 + 本地文件索引 → 跨项目知识积累 |
| "自主工作流"引擎 | Cursor 只做代码辅助 | Hands + Scheduler + Workflow → 定时任务自动执行（如每日新闻摘要、竞品监控） |
| "团队蜂群"协作 | 市场上极少 | SwarmDashboard 已有基础 → 多 Agent 分工合作解决复杂问题 |
| "中文场景" Skills | 国际产品不覆盖 | 小红书运营、知乎策略、微信公众号、飞书文档操作 → 已有 Skill 定义 |
### 💡 方向五：开发者体验 (DX) 优化
| 改进 | 现状 | 目标 |
|------|------|------|
| 启动脚本 | 需要 start-all.ps1 + 多步操作 | pnpm dev 一键启动全栈 |
| 热重载 | Vite HMR 可用 | 加上 Gateway 插件热重载 |
| 类型安全 | 部分 any | 全量 strict TypeScript |
| E2E 测试 | 无 | Playwright + Tauri driver |
| CI/CD | 无 | GitHub Actions 自动测试+构建 |
### 💡 方向六：商业化路径探索
基于现有能力的最短变现路径：
```
阶段 1 (Q2): "个人 AI 助手" — 免费开源
→ 建立 GitHub 社区 → 收集种子用户反馈
→ 核心卖点: 本地优先 + 中文模型 + 飞书集成
阶段 2 (Q3): "Pro 版" — 订阅制 ¥49/月
→ 云端记忆同步
→ 高级 Skills (如量化交易分析、SEO 自动优化)
→ 优先技术支持
阶段 3 (Q4): "团队版" — ¥199/人/月
→ 多 Agent 协作编排
→ 企业级审计日志
→ 私有部署选项
```
---
## 六、行动建议总结
### ✅ 已完成 (截至 2026-03-20)
1. **~~Store 架构统一~~** — gatewayStore 已拆分，useCompositeStore 已删除
2. **~~gateway-client 模块化~~** — 已拆分为 api/auth/storage/types 4 模块
3. **~~viking-*.ts 清理~~** — 已归档到 docs/archive/v1-viking-dead-code/
4. **~~E2E 测试框架~~** — Playwright 已配置，74+ 测试用例
5. **~~Skill Market MVP~~** — UI + Store + 发现引擎都已实现
6. **~~DevQALoop 集成~~** — 已添加到 TeamOrchestrator
7. **~~组件集成状态核实~~** — 大部分组件已通过间接路径集成
### 🔥 立即要做 (本周)
1. **跑通真实集成测试** — 使用 INTEGRATION-CHECKLIST.md 逐项验证
2. **配置验证工具** — 运行 `npx ts-node scripts/validate-config.ts`
### 📌 短期 (2 周)
1. **完成真实 Gateway 连接测试** — 连接 ZCLAW Kernel
2. **中文模型 API 测试** — 验证流式响应
3. **飞书集成测试** — OAuth 和消息收发
### 🎯 中期 (1-2 月)
1. **智能层迁移评估** — 评估哪些模块必须迁移到后端
2. **向量记忆 UI 集成** — Viking 已有代码，需要 UI 入口
---
## 核心判断
ZCLAW 的设计远大于实现。智能层的 lib 代码、68 个 Skills、7 个 Hands 的架构设计都非常出色，但最大的短板是**端到端可用性未经验证**。
**建议的策略是：先收敛、跑通闭环、再扩展。**

187
docs/archive/old-analysis/analysis-2026-03-31-future-work.md Normal file
View File

@@ -0,0 +1,187 @@
# ZCLAW 后续工作分析
> **生成日期**: 2026-03-31
> **基于**: 系统评估报告 + 设计规格差异分析 + TODO扫描 + 测试/部署审计
---
## 当前状态概览
| 维度 | 评分 | 说明 |
|------|------|------|
| 功能完成度 | 87% | 核心功能完整，SaaS 定位设计 12/12 项全部实现 |
| 代码质量 | B+ | 全库仅 1 个 TODO，无 FIXME/HACK，TypeScript 严格模式 |
| 后端测试 | 34% | Rust 257 个测试 + 12 个集成测试，覆盖可接受 |
| 前端测试 | ~15% | Desktop 34 个测试文件，Admin V2 零测试 |
| 部署就绪 | 40% | docker-compose 存在但缺 Dockerfile，无生产部署指南 |
| 文档完整性 | 50% | 架构/知识库丰富，缺 API 文档和部署指南 |
---
## 一、P0 — 必须完成 (阻塞上线)
### 1.1 SaaS 生产部署基础设施
**问题**: `docker-compose.yml` 引用的 Dockerfile 和 `saas-env.example` 不存在，无法容器化部署。
| 工作项 | 说明 | 工作量 |
|--------|------|--------|
| 创建 `Dockerfile` | 多阶段构建: builder (cargo build --release) + runtime (debian-slim) | 2h |
| 创建 `saas-env.example` | 所有必需环境变量模板 + 中文注释 | 1h |
| Nginx/Caddy 反向代理配置 | HTTPS 终止 + WebSocket 代理 + 限流 | 2h |
| 生产部署指南 | `docs/deployment/saas-production.md` | 2h |
| 健康检查端点放开 | `/api/health` 当前需认证，生产环境应公开 | 0.5h |
### 1.2 Admin V2 基础测试
**问题**: Admin V2 的 33 个源文件零测试覆盖，无测试框架。
| 工作项 | 说明 | 工作量 |
|--------|------|--------|
| 配置 Vitest + React Testing Library | `admin-v2/vitest.config.ts` + 依赖安装 | 1h |
| request.ts 拦截器测试 | Token 刷新竞态、网络错误包装、401 处理 | 2h |
| 核心页面冒烟测试 | Accounts/Providers/AgentTemplates 渲染测试 | 3h |
| authStore 测试 | 登录/登出/Token 刷新状态管理 | 2h |
---
## 二、P1 — 功能补全 (近期迭代)
### 2.1 设计规格遗留项
| 工作项 | 当前状态 | 说明 | 工作量 |
|--------|---------|------|--------|
| Admin AgentTemplates 表单: `scenarios` 输入 | 缺失 | 创建表单没有 scenarios 多选 Tag 输入 | 1h |
| Admin AgentTemplates 表单: `quick_commands` 编辑器 | 缺失 | 需 Form.List 动态编辑 `[{label, prompt}]` | 2h |
| Key Pool 同优先级 LRU 排序 | 缺失 | `select_best_key()` 仅按 priority 排序，同优先级无负载分散 | 2h |
| `quota_reset_interval` 字段 | 死代码 | provider_keys 表有此字段但无重置逻辑，需决定实现或移除 | 1h |
### 2.2 Desktop 遗留 TS 错误修复
| 文件 | 问题 | 工作量 |
|------|------|--------|
| `desktop/src/lib/llm-service.ts` | 之前重构引入的语法错误 (已修复) | Done |
| `desktop/src/lib/gateway-api.ts` | 评估显示无错误，需验证是否为旧版本问题 | 0.5h |
| `desktop/src/lib/kernel-hands.ts` | 同上 | 0.5h |
### 2.3 Pipeline `started_at` 时间戳修复
| 文件 | 问题 | 工作量 |
|------|------|--------|
| `desktop/src-tauri/src/pipeline_commands/discovery.rs:214` | `started_at` 使用 `Utc::now()` 而非实际启动时间 | 1h |
### 2.4 Admin V2 表格增强
| 工作项 | 说明 | 工作量 |
|--------|------|--------|
| 搜索/筛选功能 | Accounts/Models/Providers/ApiKeys/Prompts 表格无搜索 | 4h |
| 分页状态管理 | 大部分表格不同步本地分页状态 | 2h |
| Config 页编辑体验 | 内联编辑缺加载指示器和 hover 视觉反馈 | 1h |
---
## 三、P2 — 质量提升 (中期优化)
### 3.1 API 文档
| 工作项 | 说明 | 工作量 |
|--------|------|--------|
| OpenAPI/Swagger 规范 | 69 个端点需要正式 API 文档，可从 Axum handler 自动生成 | 4h |
| API Reference 页面 | 可集成到 Admin V2 或独立 docs 站点 | 2h |
### 3.2 Desktop 测试提升
| 工作项 | 当前 | 目标 | 工作量 |
|--------|------|------|--------|
| Store 单元测试 | ~15% | 60% | 8h |
| 组件测试 | 少量 | 核心组件覆盖 | 6h |
| E2E 集成到 CI | 12 个 Playwright spec 未在 CI 运行 | 自动执行 | 2h |
### 3.3 国际化 (i18n) 准备
| 工作项 | 说明 | 工作量 |
|--------|------|--------|
| 引入 i18n 框架 | Desktop saasStore/connectionStore 硬编码中文错误消息 | 2h |
| Admin V2 i18n | 所有页面中文硬编码 | 6h |
| 提取翻译文件 | zh-CN.json + en-US.json | 4h |
### 3.4 监控与可观测性
| 工作项 | 说明 | 工作量 |
|--------|------|--------|
| 结构化日志增强 | SaaS 后端 tracing 已有，需添加 request_id 关联 | 2h |
| Prometheus metrics | 请求延迟、Key Pool 使用率、错误率 | 4h |
| Grafana 仪表盘模板 | 预配置的监控面板 | 3h |
---
## 四、P3 — 功能扩展 (远期规划)
### 4.1 已规划但未启动的功能
| 功能 | 设计状态 | 说明 |
|------|---------|------|
| 技能市场 UI | CLAUDE.md 标记"进行中" | 技能浏览和安装界面，70 个 SKILL.md 已有 |
| Pipeline 工作流编辑器 | CLAUDE.md 标记"进行中" | 可视化编辑器，PipelinesPanel 已有基础 |
| 智能路由 (Semantic Router) | L2/50% 成熟度 | 意图路由不成熟，需更多训练数据 |
| Predictor Hand | enabled=false | 无 Rust 实现，需完全重写 |
| Lead Hand | enabled=false | 无 Rust 实现，需完全重写 |
### 4.2 设计规格明确排除的未来功能
| 功能 | 说明 |
|------|------|
| AccountTier 订阅层级 | 未来商业化 |
| 实时配置推送 (WebSocket) | 当前登录时拉取，未来推送 |
| 模板市场/用户上传 | 当前仅 Admin 管理 |
| Token Pool 计费/用量配额 | 当前无计费逻辑 |
| Desktop 用户自选路由模式 | 设计决定仅 Admin 控制 |
---
## 五、工作量估算汇总
| 优先级 | 类别 | 工作量 | 建议排期 |
|--------|------|--------|---------|
| **P0** | 部署基础设施 | ~7.5h | 第 1 周 |
| **P0** | Admin V2 基础测试 | ~8h | 第 1-2 周 |
| **P1** | 设计规格遗留 | ~6.5h | 第 2 周 |
| **P1** | Desktop TS 错误 | ~1.5h | 第 2 周 |
| **P1** | 表格增强 | ~7h | 第 3 周 |
| **P2** | API 文档 | ~6h | 第 3-4 周 |
| **P2** | 测试提升 | ~16h | 持续 |
| **P2** | i18n | ~12h | 第 4-5 周 |
| **P2** | 监控 | ~9h | 第 5 周 |
| **P3** | 功能扩展 | 大量 | 按需 |
| **总计 P0+P1** | | **~30.5h** | 3 周 |
| **总计 P2** | | **~43h** | 5 周 |
---
## 六、建议执行顺序
```
Week 1: P0 部署基础设施
├── Dockerfile + saas-env.example
├── Nginx 反代配置
├── /api/health 公开
└── 生产部署指南
Week 2: P0 Admin 测试 + P1 遗留修复
├── Admin V2 Vitest 配置 + request.ts 测试
├── scenarios/quick_commands 表单
├── Key Pool LRU 排序
├── quota_reset_interval 决策
└── Pipeline started_at 修复
Week 3: P1 表格增强 + P2 API 文档
├── 搜索/筛选功能
├── 分页状态修复
├── OpenAPI 规范生成
└── API Reference 页面
Week 4+: P2 质量持续提升
├── Desktop 测试覆盖提升
├── i18n 框架引入
└── 监控/可观测性
```

385
docs/archive/old-analysis/saas-backend-optimization.md Normal file
View File

@@ -0,0 +1,385 @@
# ZCLAW SaaS 后端优化计划
> 生成时间: 2026-03-28
> 分析范围: crates/zclaw-saas
## 一、架构概览
```
┌─────────────────────────────────────────────────────────────────┐
│ ZCLAW SaaS Backend │
│ (Rust + Axum + PostgreSQL) │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ auth │ │ account │ │model_cfg │ │ relay │ │
│ │ 认证 │ │ 账号管理 │ │ 模型配置 │ │ 中转服务 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └─────────────┴─────────────┴─────────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ middleware │ │
│ │ - auth │ │
│ │ - rate_limit│ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ PostgreSQL │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 二、API 接口清单 (共 42 个端点)
### 2.1 认证模块 `/api/v1/auth` (5 个)
| 方法 | 路径 | 权限 | 功能 |
|------|------|------|------|
| POST | `/auth/register` | 公开 | 用户注册 |
| POST | `/auth/login` | 公开 | 用户登录 |
| POST | `/auth/refresh` | 认证 | 刷新 Token |
| GET | `/auth/me` | 认证 | 获取当前用户 |
| PUT | `/auth/password` | 认证 | 修改密码 |
### 2.2 账号管理 `/api/v1` (12 个)
| 方法 | 路径 | 权限 | 功能 |
|------|------|------|------|
| GET | `/accounts` | admin | 列出账号 |
| GET | `/accounts/:id` | 自己/admin | 账号详情 |
| PUT | `/accounts/:id` | 自己/admin | 更新账号 |
| PATCH | `/accounts/:id/status` | admin | 更新状态 |
| GET | `/tokens` | 认证 | 列出 Token |
| POST | `/tokens` | 认证 | 创建 Token |
| DELETE | `/tokens/:id` | 认证 | 撤销 Token |
| GET | `/logs/operations` | admin | 操作日志 |
| GET | `/stats/dashboard` | admin | 仪表盘 |
| POST | `/devices/register` | 认证 | 注册设备 |
| POST | `/devices/heartbeat` | 认证 | 设备心跳 |
| GET | `/devices` | 认证 | 设备列表 |
### 2.3 模型配置 `/api/v1` (15 个)
| 方法 | 路径 | 权限 | 功能 |
|------|------|------|------|
| GET | `/providers` | 认证 | 服务商列表 |
| GET | `/providers/:id` | 认证 | 服务商详情 |
| POST | `/providers` | provider:manage | 创建服务商 |
| PUT | `/providers/:id` | provider:manage | 更新服务商 |
| DELETE | `/providers/:id` | provider:manage | 删除服务商 |
| GET | `/models` | 认证 | 模型列表 |
| GET | `/models/:id` | 认证 | 模型详情 |
| POST | `/models` | model:manage | 创建模型 |
| PUT | `/models/:id` | model:manage | 更新模型 |
| DELETE | `/models/:id` | model:manage | 删除模型 |
| GET | `/keys` | 认证 | API Key 列表 |
| POST | `/keys` | 认证 | 创建 Key |
| POST | `/keys/:id/rotate` | 认证 | 轮换 Key |
| DELETE | `/keys/:id` | 认证 | 撤销 Key |
| GET | `/usage` | 认证 | 用量统计 |
### 2.4 中转服务 `/api/v1/relay` (5 个)
| 方法 | 路径 | 权限 | 功能 |
|------|------|------|------|
| POST | `/relay/chat/completions` | relay:use | 聊天补全 |
| GET | `/relay/tasks` | 认证 | 任务列表 |
| GET | `/relay/tasks/:id` | 认证 | 任务详情 |
| GET | `/relay/models` | 认证 | 可用模型 |
| POST | `/relay/tasks/:id/retry` | relay:admin | 重试任务 |
### 2.5 配置迁移 `/api/v1/config` (10 个)
| 方法 | 路径 | 权限 | 功能 |
|------|------|------|------|
| GET | `/config/items` | 认证 | 配置列表 |
| GET | `/config/items/:id` | 认证 | 配置详情 |
| POST | `/config/items` | config:write | 创建配置 |
| PUT | `/config/items/:id` | config:write | 更新配置 |
| DELETE | `/config/items/:id` | config:write | 删除配置 |
| GET | `/config/analysis` | 认证 | 配置分析 |
| POST | `/config/seed` | config:write | 种子配置 |
| POST | `/config/sync` | 认证 | 同步配置 |
| POST | `/config/diff` | 认证 | 配置差异 |
| GET | `/config/sync-logs` | 认证 | 同步日志 |
---
## 三、问题清单
### 🔴 高优先级 (影响功能/性能)
#### P1-001: 登录接口 N+1 查询
**位置:** `auth/handlers.rs:login()`
**现状:**
```rust
// 查询 1: 获取用户信息
let row = sqlx::query_as("SELECT id, username, ... FROM accounts WHERE username = $1")...
// 查询 2: 获取密码哈希
let (password_hash,) = sqlx::query_as("SELECT password_hash FROM accounts WHERE id = $1")...
// 查询 3: 获取权限
let permissions = get_role_permissions(&state.db, &role).await?;
```
**影响:** 每次登录触发 3 次数据库查询
**修复方案:**
```sql
SELECT a.id, a.username, a.email, a.display_name, a.role, a.status,
a.totp_enabled, a.created_at, a.password_hash,
r.permissions
FROM accounts a
LEFT JOIN roles r ON a.role = r.id
WHERE a.username = $1 OR a.email = $1
```
**工作量:** 小 (1-2 小时)
---
#### P1-002: 流式响应 Token 统计缺失
**位置:** `relay/handlers.rs:chat_completions()`
**现状:**
```rust
Ok(service::RelayResponse::Sse(body)) => {
model_service::record_usage(..., 0, 0, ...); // 流式记录 0 tokens
}
```
**影响:** 流式请求的 token 使用量无法统计，影响计费和监控
**修复方案:**
1. 解析 SSE 流中的 `usage` 字段
2. 在流结束后更新统计
**工作量:** 中 (4-6 小时)
---
#### P1-003: 健康检查端点缺失
**位置:** `main.rs`
**现状:** 无 `/health` 或 `/ready` 端点
**影响:**
- K8s/Docker 无法进行健康检查
- 负载均衡器无法判断服务状态
**修复方案:**
```rust
.route("/health", get(|| async {
Json(json!({"status": "ok"}))
}))
.route("/ready", get(|State(state): State<AppState>| async move {
// 检查数据库连接
let db_ok = sqlx::query("SELECT 1").fetch_one(&state.db).await.is_ok();
Json(json!({"ready": db_ok, "db": if db_ok { "connected" } else { "disconnected" }}))
}))
```
**工作量:** 小 (1 小时)
---
### 🟡 中优先级 (影响可维护性)
#### P2-001: 权限系统无缓存
**位置:** `auth/handlers.rs:get_role_permissions()`
**现状:** 每次请求都查询数据库获取权限
**影响:**
- 数据库压力增加
- 响应延迟增加
**修复方案:**
1. 方案 A: 在 JWT 中嵌入权限 (无需查询，但权限变更需重新登录)
2. 方案 B: 添加内存缓存 (LRU Cache，权限变更即时生效)
**推荐:** 方案 B，使用 `moka` 或 `dashmap` 缓存
**工作量:** 中 (4-8 小时)
---
#### P2-002: 错误响应格式不统一
**位置:** 所有 handlers
**现状:**
```json
// 格式 1
{"error": "AUTH_ERROR", "message": "认证失败"}
// 格式 2
{"ok": true}
// 格式 3
{"ok": true, "message": "密码修改成功"}
```
**影响:** 前端需要处理多种格式，增加复杂度
**修复方案:** 统一为 RFC 7807 Problem Details 格式:
```json
{
"type": "https://zclaw.ai/errors/auth-error",
"title": "认证失败",
"status": 401,
"detail": "用户名或密码错误",
"code": "AUTH_ERROR"
}
```
**工作量:** 中 (4-6 小时)
---
#### P2-003: 分页响应缺少元数据
**位置:** `account/handlers.rs:list_accounts()`
**现状:**
```rust
pub struct PaginatedResponse<T> {
pub items: Vec<T>,
// 缺少 total, page, total_pages
}
```
**影响:** 前端无法显示总页数和分页导航
**修复方案:**
```rust
pub struct PaginatedResponse<T> {
pub items: Vec<T>,
pub total: i64,
pub page: i64,
pub page_size: i64,
pub total_pages: i64,
}
```
**工作量:** 小 (2-3 小时)
---
### 🟢 低优先级 (技术债务)
#### P3-001: 数据库 Schema 使用 TEXT 类型
**位置:** `db.rs`
**现状:**
```sql
created_at TEXT NOT NULL, -- 应该用 TIMESTAMPTZ
role TEXT NOT NULL DEFAULT 'user' -- 应该用外键
```
**影响:**
- 无法使用 PostgreSQL 时间函数
- 角色无外键约束，可能导致数据不一致
**修复方案:** 编写迁移脚本，逐步更新 Schema
**工作量:** 大 (需要数据迁移)
---
#### P3-002: 缺少请求追踪
**现状:** 操作日志只记录业务操作，不记录 API 请求详情
**影响:**
- 无法追踪请求链路
- 问题排查困难
**修复方案:** 添加请求追踪中间件:
- 生成 `request_id`
- 记录请求耗时
- 关联日志与请求
**工作量:** 中 (4-6 小时)
---
#### P3-003: API 版本控制策略缺失
**现状:** 只有 `v1`，无版本升级策略
**影响:** 未来 API 变更可能导致兼容性问题
**修复方案:**
1. 在响应头添加 `X-API-Version`
2. 支持 `Accept: application/vnd.zclaw.v1+json`
3. 添加版本废弃机制
**工作量:** 小 (2-3 小时)
---
## 四、优化实施计划
### Phase 1: 高优先级修复 (1-2 天)
| 任务 | 工作量 | 负责人 | 状态 |
|------|--------|--------|------|
| P1-001 登录 N+1 查询优化 | 2h | - | 待开始 |
| P1-003 健康检查端点 | 1h | - | 待开始 |
| P1-002 流式 Token 统计 | 6h | - | 待开始 |
### Phase 2: 中优先级优化 (2-3 天)
| 任务 | 工作量 | 负责人 | 状态 |
|------|--------|--------|------|
| P2-001 权限缓存 | 8h | - | 待开始 |
| P2-002 错误格式统一 | 6h | - | 待开始 |
| P2-003 分页元数据 | 3h | - | 待开始 |
### Phase 3: 技术债务清理 (按需)
| 任务 | 工作量 | 负责人 | 状态 |
|------|--------|--------|------|
| P3-001 Schema 迁移 | 2-3 天 | - | 待评估 |
| P3-002 请求追踪 | 6h | - | 待开始 |
| P3-003 API 版本控制 | 3h | - | 待开始 |
---
## 五、NOT in Scope
以下内容在本次优化范围之外:
1. **前端 Admin UI 优化** - 仅关注后端 API
2. **数据库分库分表** - 当前数据量不需要
3. **微服务拆分** - 架构已足够清晰
4. **GraphQL 支持** - REST API 已满足需求
5. **WebSocket 支持** - 当前无实时推送需求
---
## 六、风险评估
| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|----------|
| Schema 迁移数据丢失 | 低 | 高 | 先备份，分批迁移 |
| 权限缓存不一致 | 中 | 中 | 设置 TTL，主动失效 |
| 流式解析兼容性 | 中 | 低 | 多模型测试 |
---
## 七、验收标准
- [ ] 所有 API 端点有健康检查
- [ ] 登录接口响应时间 < 100ms (P99)
- [ ] 流式请求 Token 统计准确率 > 95%
- [ ] 错误响应格式统一
- [ ] 分页接口包含完整元数据