iven/zclaw_openfang

Fork 0

Files

iven ef849c62ab cc工作前备份

2026-03-12 00:23:42 +08:00

16 KiB

Raw Blame History

ZCLAW 项目深度分析与头脑风暴

一、项目全景概览

1.1 项目定位

ZCLAW 是一个基于 OpenClaw 框架的定制化中文 AI 助手平台，对标 AutoClaw (智谱) 和 QClaw (腾讯)。

核心价值主张：

OpenClaw Gateway (成熟执行引擎)
      ↕ WebSocket Protocol v3
ZCLAW Tauri App (轻量桌面 UI)
      + 中文模型 Provider (GLM/Qwen/Kimi/MiniMax)
      + 飞书 Channel Plugin
      + 分身(Clone) 管理系统
      + 自定义 Skills

1.2 架构演进历程

阶段	架构方向	状态
v1	自建 AI Agent 框架 (src/core/*)	🗑️ 已归档
v2	基于 OpenClaw + Tauri	✅ 当前方向

架构转向原因：v1 偏离初衷约 75%，重复造轮子而非复用 OpenClaw 生态。

1.3 技术栈一览

层级	技术	版本
执行引擎	OpenClaw Gateway	Node.js daemon
桌面壳	Tauri	2.0
前端框架	React	19.1.0
状态管理	Zustand	5.0.11
样式	TailwindCSS	4.2.1
构建工具	Vite	7.0.4
语言	TypeScript	5.8.3
通信协议	WebSocket	Gateway Protocol v3

二、当前项目状态

2.1 已完成阶段

Phase	内容	完成度
Phase 1	后端 Gateway 层 + 插件 + Skills	✅ 100%
Phase 2	前端 Settings 页面体系 (10页)	✅ 100%
Phase 3	聊天对接 + 分身管理	✅ 100%
Phase 3.5	前端质量提升	✅ 100%
Phase 4	OpenClaw 真实集成测试	⏳ 待开始
Phase 5	Tauri Rust sidecar + 打包发布	📋 规划中

2.2 代码统计

类别	文件数	说明
Gateway 层	3	manager.ts, ws-client.ts, index.ts
插件	6	3 plugins × (index.ts + plugin.json)
Skills	2	2 × SKILL.md
配置	5	1 JSON + 4 MD
前端组件	15+	组件/Store/工具库
v1 遗留代码	37+	src/core/* (已归档)

2.3 编译状态

TypeScript: 0 errors
Vite build: 成功 (1766 modules, 268 KB JS + 26 KB CSS)

三、核心模块深度分析

3.1 OpenClaw Gateway 集成层 (src/gateway/)

manager.ts - 子进程管理器

功能: 管理 OpenClaw Gateway 子进程生命周期
特性:
  - 启动/停止 Gateway daemon
  - 健康检查 (HTTP 探测)
  - 自动重启 (最多 5 次)
  - 连接外部已运行实例

ws-client.ts - WebSocket 客户端

功能: 实现 OpenClaw Gateway Protocol v3
特性:
  - 三步握手 (challenge → connect → hello-ok)
  - 请求/响应模式 (30秒超时)
  - 事件订阅 (agent/chat/presence/health/heartbeat)
  - 自动重连 (指数退避 1.5x, 最大 30s)

3.2 自定义插件系统 (plugins/)

@zclaw/chinese-models - 中文模型 Provider

Provider	模型
智谱 GLM	glm-5, glm-4.7, glm-4-plus, glm-4-flash
通义千问	qwen3.5-plus, qwen-max, qwen-vl-max
Kimi	kimi-k2.5, moonshot-v1-128k
MiniMax	minimax-m2.5, abab6.5s-chat

设计特点: 全部使用 OpenAI 兼容 API 格式，支持自定义 Base URL。

@zclaw/feishu - 飞书 Channel Plugin

功能: 将飞书注册为 OpenClaw 消息渠道
特性:
  - OAuth tenant_access_token 管理 (2h 有效期, 1.5h 刷新)
  - 文本/富文本消息发送
  - 多账户支持

@zclaw/ui - UI 扩展 RPC

方法	功能
zclaw.clones.*	分身 CRUD
zclaw.stats.*	用量/会话统计
zclaw.config.quick	快速配置
zclaw.workspace.info	工作区信息
zclaw.plugins.status	插件状态

3.3 前端架构 (desktop/src/)

三层布局

┌─────────────────────────────────────────────────────────┐
│ Sidebar (w-64) │ ChatArea (flex-1) │ RightPanel (w-72) │
│   左侧边栏      │     中间对话区      │      右侧边栏       │
└─────────────────────────────────────────────────────────┘

状态管理 (Zustand)

chatStore: 消息/对话/Agent/流式状态
gatewayStore: 连接/分身/统计/插件状态

关键组件

组件	职责
ChatArea	消息展示 + 流式输出 + Markdown渲染 + 模型选择
Sidebar	四标签 (对话/分身/频道/任务)
RightPanel	Gateway状态 + 会话统计 + 插件状态
Settings/*	10个设置页面对标 AutoClaw

3.4 v1 遗留代码 (已归档)

以下代码位于 src/core/ 等目录，已从编译范围排除：

模块	状态	替代方案
remote-execution/	🗑️	OpenClaw 工具执行
task-orchestration/	🗑️	OpenClaw Agent Loop
multi-agent/	🗑️	OpenClaw agents.list
memory/	🗑️	OpenClaw Memory Plugin
proactive/	🗑️	OpenClaw Heartbeat Engine
im/	🗑️	OpenClaw Channel 系统
db/	🗑️	OpenClaw 自带 SQLite
config/	🗑️	OpenClaw 配置系统
api/	🗑️	WebSocket + Tauri Commands

四、头脑风暴：机会与挑战

4.1 架构优势 💪

复用成熟生态
- OpenClaw 28万+ Stars，工具执行/Skills/MCP/心跳引擎成熟
- 避免重复造轮子，专注差异化价值
Tauri 轻量化
- ~10MB vs Electron ~150MB
- Rust native 性能优异
- 系统级集成能力
中文优先定位
- 4大中文模型原生支持
- 飞书/微信/QQ 等 IM 渠道
模块化插件设计
- Provider/Channel/RPC 插件独立开发
- 可扩展性强

4.2 潜在风险 ⚠️

OpenClaw 依赖
- 版本兼容性风险
- 文档/社区支持限制
v1 遗留代码清理
- 37+ 文件需要决策 (保留/删除/重构)
- 可能存在可复用的代码片段
Tauri 后端功能有限
- 当前 Rust 代码几乎为空
- 需要实现 sidecar/文件系统/通知等
测试覆盖不足
- 未见测试文件
- 集成测试缺失

4.3 创新机会 💡

A. 分身系统增强

当前: 基础 CRUD
增强方向:
  - 分身间协作 (多 Agent 编排)
  - 分身记忆隔离/共享
  - 分身能力画像 (擅长领域)
  - 分身市场 (社区分享)

B. Skills 生态扩展

当前: 2 个基础 Skills
扩展方向:
  - 社媒运营套件 (微博/小红书/抖音)
  - 学术研究助手 (论文/文献/翻译)
  - 代码审查专家 (PR Review/安全审计)
  - 数据分析专家 (SQL/报表/可视化)

C. IM 渠道深化

当前: 飞书基础支持
深化方向:
  - 微信企业号 (WeCom API)
  - QQ 机器人 (NapCat/Go-CQHTTP)
  - 钉钉/飞书/企业微信三合一
  - 消息路由规则 (关键词/时间/来源)

D. 工作区智能化

当前: 基础目录配置
智能方向:
  - 项目上下文感知 (package.json/README 解析)
  - 代码库索引 (LSP 集成)
  - 文件变更监听 (自动同步理解)
  - 多工作区切换

E. 数据分析增强

当前: 基础用量统计
增强方向:
  - 对话质量分析 (满意度/解决率)
  - Token 成本优化建议
  - 使用模式洞察 (高峰时段/常用功能)
  - 导出报告 (PDF/Excel)

4.4 技术改进建议 🔧

短期 (1-2周)

完成 Phase 4 集成测试
- 安装并验证 OpenClaw
- 测试 Gateway 连接
- 验证插件注册
- 端到端消息收发测试
清理 v1 遗留代码
- 评估每模块的可复用性
- 删除确定无用的代码
- 保留有价值的工具函数
补充基础测试
- Gateway 协议单元测试
- 前端组件测试
- E2E 关键流程测试

中期 (1-2月)

Tauri Rust 后端扩展
- Gateway sidecar 管理
- 系统托盘集成
- 原生通知
- 文件系统访问
微信/QQ Channel Plugin
- 调研 NapCat/Go-CQHTTP
- 实现 Channel Plugin 接口
Skills 扩展
- 社媒运营套件
- 代码审查助手

长期 (3-6月)

多 Agent 协作可视化
- 任务依赖图
- 执行进度追踪
- 结果聚合展示
插件市场
- 插件发现/安装/更新
- 社区贡献机制
移动端伴侣 App
- Flutter/React Native
- 与桌面端数据同步

五、竞品对标分析

维度	AutoClaw (智谱)	QClaw (腾讯)	ZCLAW
基础框架	OpenClaw	OpenClaw	OpenClaw
IM 渠道	飞书	微信+QQ	飞书 (计划微信/QQ)
桌面框架	自研	Electron	Tauri 2.0
模型支持	GLM 系列	腾讯混元	GLM/Qwen/Kimi/MiniMax
安装包大小	未知	~150MB	~10MB (目标)
开源状态	未开源	未开源	MIT 开源

差异化优势：

🦀 Tauri 轻量化
🌐 多中文模型支持
🔓 开源可定制
🧩 插件生态开放

六、下一步行动计划

Phase 4: 真实集成测试 (当前优先级)

[ ] 1. 安装 OpenClaw
      - Windows: iwr -useb https://openclaw.ai/install.ps1 | iex
      - 验证: openclaw --version

[ ] 2. 配置 Gateway
      - 运行 openclaw configure
      - 填入 API Key (智谱/通义/Kimi 任选)

[ ] 3. 启动 Gateway
      - openclaw gateway
      - 验证: curl http://127.0.0.1:18789/health

[ ] 4. 注册 ZCLAW 插件
      - pnpm setup
      - 验证插件加载

[ ] 5. 前端连接测试
      - cd desktop && pnpm tauri dev
      - 验证 WebSocket 连接
      - 测试消息收发

[ ] 6. 飞书 Channel 测试
      - 配置飞书应用凭证
      - 测试消息收发

Phase 5: 打包发布准备

[ ] Tauri Rust sidecar 实现
[ ] 安装包测试 (Windows/macOS/Linux)
[ ] 自动更新机制
[ ] 文档完善
[ ] 发布 v0.1.0

七、总结

ZCLAW 是一个定位清晰的 OpenClaw 定制化项目，通过复用成熟生态 + Tauri 轻量桌面 + 中文优先策略，有望成为开源领域的 AutoClaw/QClaw 替代方案。

核心建议：

🎯 聚焦 Phase 4 集成测试，打通端到端流程
🧹 清理 v1 遗留代码，减少维护负担
✅ 补充测试覆盖，提升代码质量
🚀 迭代发布，快速验证市场反馈

八、执行路线图 (用户选择)

基于用户反馈，将并行推进以下四个方向：

8.1 Phase 4: 真实集成测试 🔌

目标: 打通 OpenClaw Gateway ↔ ZCLAW Tauri 端到端流程

任务清单:

[ ] 安装 OpenClaw CLI
    - Windows: iwr -useb https://openclaw.ai/install.ps1 | iex
    - 验证: openclaw --version

[ ] 配置 Gateway
    - 运行 openclaw configure
    - 配置 API Key (智谱 GLM 作为首选)

[ ] 启动 Gateway daemon
    - openclaw gateway --port 18789
    - 验证: curl http://127.0.0.1:18789/health

[ ] 注册 ZCLAW 插件
    - pnpm setup (执行 scripts/setup.ts)
    - 验证插件加载: openclaw plugins list

[ ] 前端连接测试
    - cd desktop && pnpm tauri dev
    - 验证 WebSocket 连接成功
    - 测试消息发送和流式接收

[ ] 飞书 Channel 测试 (可选)
    - 配置飞书应用凭证
    - 测试飞书消息收发

验收标准:

✅ Gateway 启动成功，健康检查通过
✅ 前端显示"已连接"状态
✅ 发送消息能收到 AI 流式回复
✅ 模型切换功能正常

8.2 清理 v1 遗留代码 🧹

目标: 评估并处理 src/core/ 等 37+ 个归档文件

待处理目录:

目录	文件数	建议操作
src/core/remote-execution/	~4	🗑️ 删除 (OpenClaw 替代)
src/core/task-orchestration/	~3	🗑️ 删除 (OpenClaw 替代)
src/core/multi-agent/	~8	🗑️ 删除 (OpenClaw 替代)
src/core/memory/	~2	🗑️ 删除 (OpenClaw 替代)
src/core/proactive/	~2	🗑️ 删除 (OpenClaw 替代)
src/core/ai/	~6	⚠️ 评估 (可能复用 Provider)
src/im/	~4	🗑️ 删除 (OpenClaw 替代)
src/db/	~3	🗑️ 删除 (OpenClaw 替代)
src/config/	~2	🗑️ 删除 (OpenClaw 替代)
src/api/	~1	🗑️ 删除 (WebSocket 替代)
src/app.ts	1	🗑️ 删除
src/index.ts	1	🔄 重写为简单入口

任务清单:

[ ] 创建 archive/v1-backup 分支保存当前状态
[ ] 评估 src/core/ai/ 的可复用性
    - providers/zhipu.ts 可能对插件开发有参考价值
    - manager.ts 的 fallback 逻辑可借鉴
[ ] 删除确认无用的目录
[ ] 重写 src/index.ts 为最小化入口
[ ] 更新 tsconfig.json 移除对旧代码的引用
[ ] 验证编译: pnpm build (0 errors)

验收标准:

✅ v1 代码已备份到独立分支
✅ 主分支代码精简，无死代码
✅ TypeScript 编译 0 errors
✅ 项目结构清晰，符合 v2 架构

8.3 补充测试覆盖 ✅

目标: 建立基础测试框架，覆盖关键模块

测试分层:

tests/
├── unit/                    # 单元测试
│   ├── gateway/
│   │   ├── manager.test.ts  # 子进程管理
│   │   └── ws-client.test.ts # WebSocket 客户端
│   └── utils/
│       ├── logger.test.ts
│       └── id.test.ts
├── integration/             # 集成测试
│   ├── gateway-protocol.test.ts  # Gateway 协议
│   └── plugin-loading.test.ts    # 插件加载
└── e2e/                     # 端到端测试
    └── chat-flow.test.ts    # 完整对话流程

任务清单:

[ ] 配置测试框架
    - 安装 Vitest + @testing-library/react
    - 配置 vitest.config.ts

[ ] Gateway 层单元测试
    - ws-client.ts: 握手流程、重连逻辑
    - manager.ts: 进程管理、健康检查

[ ] 前端组件测试
    - chatStore: 消息发送、流式处理
    - gatewayStore: 连接状态管理
    - ChatArea: 消息渲染、输入处理

[ ] 集成测试
    - Gateway Protocol v3 完整握手
    - 插件注册和 RPC 调用

[ ] CI 集成
    - GitHub Actions 自动运行测试
    - 覆盖率报告

验收标准:

✅ 测试框架配置完成
✅ 核心模块测试覆盖率 > 60%
✅ CI 流水线运行成功

8.4 扩展 Skills/插件 🧩

目标: 丰富 Skills 生态，增加 IM 渠道支持

Skills 扩展计划:

Skill	触发词	功能
social-media	发微博/小红书/抖音	社媒内容创作和发布
code-review	审查代码/PR Review	代码质量分析和建议
data-analysis	分析数据/生成报表	SQL 查询和可视化
translation	翻译/中译英	多语言翻译

插件扩展计划:

插件	类型	优先级
@zclaw/wechat	Channel	高
@zclaw/qq	Channel	高
@zclaw/terminal	Tool	中
@zclaw/advanced-memory	Memory	中

任务清单:

[ ] Skills 开发
    - 创建 skills/social-media/SKILL.md
    - 创建 skills/code-review/SKILL.md
    - 创建 skills/data-analysis/SKILL.md
    - 创建 skills/translation/SKILL.md

[ ] 微信 Channel Plugin 调研
    - 评估 WeCom API 可行性
    - 评估 NapCat/Go-CQHTTP 桥接方案
    - 输出技术方案文档

[ ] QQ Channel Plugin 调研
    - 评估 NapCatQQ 方案
    - 输出技术方案文档

[ ] 插件开发 (选一个优先)
    - 实现微信或 QQ Channel Plugin

验收标准:

✅ 至少 2 个新 Skills 可用
✅ 微信/QQ 技术方案文档完成
✅ 至少 1 个新 Channel Plugin 可测试

九、执行优先级排序

基于依赖关系和价值，建议执行顺序：

第 1 周: Phase 4 集成测试 + v1 代码清理
    └─ 这两项可以并行，互不依赖

第 2 周: 补充测试覆盖
    └─ 在集成测试通过后补充自动化测试

第 3-4 周: Skills/插件扩展
    └─ 在稳定基础上扩展功能

里程碑:

🏁 Week 1 结束: 端到端流程打通 + 代码库精简
🏁 Week 2 结束: 测试覆盖率 > 60%
🏁 Week 4 结束: 4+ 新 Skills + 1 新 Channel Plugin

分析完成于 2026-03-12 执行计划更新于 2026-03-12

16 KiB Raw Blame History Unescape Escape

ZCLAW 项目深度分析与头脑风暴

一、项目全景概览

1.1 项目定位

1.2 架构演进历程

1.3 技术栈一览

二、当前项目状态

2.1 已完成阶段

2.2 代码统计

2.3 编译状态

三、核心模块深度分析

3.1 OpenClaw Gateway 集成层 (src/gateway/)

manager.ts - 子进程管理器

ws-client.ts - WebSocket 客户端

3.2 自定义插件系统 (plugins/)

@zclaw/chinese-models - 中文模型 Provider

@zclaw/feishu - 飞书 Channel Plugin

@zclaw/ui - UI 扩展 RPC

3.3 前端架构 (desktop/src/)

三层布局

状态管理 (Zustand)

关键组件

3.4 v1 遗留代码 (已归档)

四、头脑风暴：机会与挑战

4.1 架构优势 💪

4.2 潜在风险 ⚠️

4.3 创新机会 💡

A. 分身系统增强

B. Skills 生态扩展

C. IM 渠道深化

D. 工作区智能化

E. 数据分析增强

4.4 技术改进建议 🔧

短期 (1-2周)

中期 (1-2月)

长期 (3-6月)

五、竞品对标分析

六、下一步行动计划

Phase 4: 真实集成测试 (当前优先级)

Phase 5: 打包发布准备

七、总结

八、执行路线图 (用户选择)

8.1 Phase 4: 真实集成测试 🔌

8.2 清理 v1 遗留代码 🧹

8.3 补充测试覆盖 ✅

8.4 扩展 Skills/插件 🧩

九、执行优先级排序

16 KiB

Raw Blame History