0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
346 lines
14 KiB
Markdown
346 lines
14 KiB
Markdown
# 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 的架构设计都非常出色，但最大的短板是**端到端可用性未经验证**。
|
||
|
||
**建议的策略是：先收敛、跑通闭环、再扩展。**
|