docs: reorganize documentation structure
- Create docs/README.md as documentation index - Add WORK_SUMMARY_2026-03-16.md for today's work - Move test reports to docs/test-reports/ - Move completed plans to docs/archive/completed-plans/ - Move research reports to docs/archive/research-reports/ - Move technical reference to docs/knowledge-base/ - Move all plans from root plans/ to docs/plans/ New structure: docs/ ├── README.md # Documentation index ├── DEVELOPMENT.md # Development guide ├── OPENVIKING_INTEGRATION.md # OpenViking integration ├── USER_MANUAL.md # User manual ├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md ├── archive/ # Archived documents ├── knowledge-base/ # Technical knowledge ├── plans/ # Execution plans └── test-reports/ # Test reports Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
233
docs/archive/NEXT_SESSION.md
Normal file
233
docs/archive/NEXT_SESSION.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# ZCLAW 新会话提示词
|
||||
|
||||
**创建日期**: 2026-03-15
|
||||
**目的**: 为后续开发会话提供完整上下文
|
||||
|
||||
---
|
||||
|
||||
## 项目概述
|
||||
|
||||
ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，使用 Tauri 2.0 + React + TypeScript 开发。
|
||||
|
||||
**技术栈**:
|
||||
- 前端: React 19 + TypeScript + Zustand + Tailwind CSS
|
||||
- 桌面: Tauri 2.0 (Rust)
|
||||
- 后端: OpenFang Kernel (Rust, 端口 50051)
|
||||
- 配置: TOML 格式
|
||||
|
||||
**核心价值**: 真实连接 OpenFang Kernel，驱动 Agents / Skills / Hands / Workflows
|
||||
|
||||
---
|
||||
|
||||
## 当前状态
|
||||
|
||||
```
|
||||
API 覆盖率: 60% (37/62 端点)
|
||||
UI 完成度: 80% (20/25 组件)
|
||||
Hands 配置: 43% (3/7 有 TOML)
|
||||
Skills 定义: 7% (4/60+ 潜在)
|
||||
整体对齐度: 80%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 待完成任务 (Phase 0 - P0 优先级)
|
||||
|
||||
### 1. HandTaskPanel 真实任务历史
|
||||
|
||||
**文件**: `desktop/src/components/HandTaskPanel.tsx`
|
||||
|
||||
**问题**: 当前使用硬编码 MockTask 数据，用户看不到真实执行历史
|
||||
|
||||
**解决方案**:
|
||||
```typescript
|
||||
// 移除 MockTask 接口和硬编码数据
|
||||
// 添加 API 调用获取真实任务历史
|
||||
const { data: tasks } = useQuery(['hand-runs', handName],
|
||||
() => gatewayClient.listHandRuns(handName)
|
||||
);
|
||||
```
|
||||
|
||||
**相关 API**: `/api/hands/:name/runs` (已实现)
|
||||
|
||||
### 2. 补充 4 个 Hands TOML 配置
|
||||
|
||||
**目录**: `hands/`
|
||||
|
||||
**已有**: `researcher.HAND.toml`, `browser.HAND.toml`, `lead.HAND.toml`
|
||||
|
||||
**缺失**:
|
||||
- `clip.HAND.toml` - 视频处理
|
||||
- `collector.HAND.toml` - 数据收集
|
||||
- `predictor.HAND.toml` - 预测分析
|
||||
- `twitter.HAND.toml` - Twitter 自动化
|
||||
|
||||
**参考格式** (researcher.HAND.toml):
|
||||
```toml
|
||||
name = "researcher"
|
||||
type = "research"
|
||||
description = "深度研究自主能力包"
|
||||
requires_approval = false
|
||||
timeout_seconds = 300
|
||||
|
||||
[agent]
|
||||
provider = "openai"
|
||||
model = "gpt-4"
|
||||
|
||||
[[tools]]
|
||||
name = "web_search"
|
||||
```
|
||||
|
||||
### 3. Workflow 编辑器实现
|
||||
|
||||
**文件**: `desktop/src/components/WorkflowEditor.tsx` (新建)
|
||||
|
||||
**当前问题**: WorkflowList.tsx 中编辑/删除/新建都是 alert() placeholder
|
||||
|
||||
**需要实现**:
|
||||
- 创建 Workflow 弹窗
|
||||
- 编辑 Workflow 步骤
|
||||
- 删除确认对话框
|
||||
- 调用 API: `POST /api/workflows`, `PUT /api/workflows/:id`, `DELETE /api/workflows/:id`
|
||||
|
||||
### 4. Session 管理实现
|
||||
|
||||
**文件**: `desktop/src/store/gatewayStore.ts`
|
||||
|
||||
**问题**: Session API 完全缺失，会话无法持久化
|
||||
|
||||
**需要添加**:
|
||||
```typescript
|
||||
loadSessions: async () => {
|
||||
const sessions = await client.listSessions();
|
||||
set({ sessions });
|
||||
},
|
||||
|
||||
createSession: async (agentId: string) => {
|
||||
const session = await client.createSession({ agentId });
|
||||
return session;
|
||||
},
|
||||
|
||||
getSessionMessages: async (sessionId: string) => {
|
||||
const messages = await client.getSessionMessages(sessionId);
|
||||
return messages;
|
||||
},
|
||||
```
|
||||
|
||||
**相关 API**:
|
||||
- `GET /api/sessions`
|
||||
- `POST /api/sessions`
|
||||
- `GET /api/sessions/:id`
|
||||
- `DELETE /api/sessions/:id`
|
||||
- `GET /api/sessions/:id/messages`
|
||||
|
||||
---
|
||||
|
||||
## 关键文件位置
|
||||
|
||||
```
|
||||
ZClaw_openfang/
|
||||
├── CLAUDE.md # 项目协作规则
|
||||
├── docs/
|
||||
│ ├── SYSTEM_ANALYSIS.md # ⭐ 系统分析报告
|
||||
│ ├── openfang-technical-reference.md # OpenFang 技术参考
|
||||
│ └── knowledge-base/ # 知识库
|
||||
│ ├── feature-checklist.md # 功能验证清单
|
||||
│ └── hands-integration-lessons.md
|
||||
├── desktop/
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── HandList.tsx # Hands 列表
|
||||
│ │ │ ├── HandTaskPanel.tsx # ⚠️ 使用 Mock 数据
|
||||
│ │ │ ├── WorkflowList.tsx # ⚠️ 编辑器是 placeholder
|
||||
│ │ │ └── Settings/ # 设置页面
|
||||
│ │ ├── store/
|
||||
│ │ │ ├── gatewayStore.ts # Gateway 状态管理
|
||||
│ │ │ └── chatStore.ts # 聊天状态管理
|
||||
│ │ ├── lib/
|
||||
│ │ │ ├── gateway-client.ts # API 客户端
|
||||
│ │ │ └── gateway-config.ts # 配置管理
|
||||
│ │ └── types/
|
||||
│ │ └── hands.ts # Hands 类型定义
|
||||
│ └── src-tauri/ # Tauri Rust 后端
|
||||
├── hands/ # ⚠️ 缺 4 个 TOML
|
||||
│ ├── researcher.HAND.toml
|
||||
│ ├── browser.HAND.toml
|
||||
│ └── lead.HAND.toml
|
||||
├── skills/ # 技能定义
|
||||
│ ├── chinese-writing/SKILL.md
|
||||
│ ├── feishu-docs/SKILL.md
|
||||
│ ├── code-review/SKILL.md
|
||||
│ └── translation/SKILL.md
|
||||
└── config/
|
||||
├── chinese-providers.toml # LLM 提供商配置
|
||||
└── openclaw.default.json # ⚠️ 待迁移到 TOML
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 客户端使用示例
|
||||
|
||||
```typescript
|
||||
// gateway-client.ts 中已实现的方法
|
||||
const client = getGatewayClient();
|
||||
|
||||
// Hands 相关
|
||||
await client.listHands();
|
||||
await client.getHand('researcher');
|
||||
await client.triggerHand('researcher', { query: '...' });
|
||||
await client.listHandRuns('researcher'); // ⭐ HandTaskPanel 需要
|
||||
|
||||
// Workflows 相关
|
||||
await client.listWorkflows();
|
||||
await client.executeWorkflow('workflow-id');
|
||||
// ⚠️ createWorkflow, updateWorkflow, deleteWorkflow 未实现
|
||||
|
||||
// Session 相关
|
||||
// ⚠️ 全部未实现: listSessions, createSession, getSessionMessages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 开发
|
||||
cd desktop && pnpm dev
|
||||
|
||||
# Tauri 开发
|
||||
cd desktop && pnpm tauri:dev
|
||||
|
||||
# 测试
|
||||
pnpm vitest run tests/desktop/
|
||||
|
||||
# 类型检查
|
||||
pnpm tsc --noEmit
|
||||
|
||||
# 构建
|
||||
cd desktop && pnpm tauri:build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **所有 UI 文本必须中文**
|
||||
2. **使用 Zustand 管理状态，不要在组件内直接调用 API**
|
||||
3. **类型定义放在 `desktop/src/types/` 目录**
|
||||
4. **OpenFang 端口是 50051，不是 4200**
|
||||
5. **配置格式是 TOML，不是 JSON/YAML**
|
||||
6. **WebSocket 路径是 `/ws`**
|
||||
|
||||
---
|
||||
|
||||
## 验收标准 (Phase 0)
|
||||
|
||||
- [ ] HandTaskPanel 显示真实任务历史（无 MockTask）
|
||||
- [ ] Workflow 可创建、编辑、删除
|
||||
- [ ] Session 可持久化，刷新后历史保留
|
||||
- [ ] 7 个 Hands 全部有 TOML 配置
|
||||
|
||||
---
|
||||
|
||||
*提示词版本: 2026-03-15*
|
||||
636
docs/archive/SYSTEM_ANALYSIS.md
Normal file
636
docs/archive/SYSTEM_ANALYSIS.md
Normal file
@@ -0,0 +1,636 @@
|
||||
# ZCLAW 系统偏离分析与演化路线图
|
||||
|
||||
**分析日期**: 2026-03-14 (更新: 2026-03-15)
|
||||
**分析版本**: OpenFang v0.4.0 + ZClaw Desktop v0.2.0
|
||||
**目的**: 识别系统当前偏离点，规划后续演化方向
|
||||
**Skills 集成**: ✅ agency-agents 仓库迁移完成！
|
||||
|
||||
---
|
||||
|
||||
## 一、执行摘要
|
||||
|
||||
### 1.1 项目定位
|
||||
|
||||
ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核心价值：
|
||||
- 真实连接 OpenFang Kernel
|
||||
- 真实驱动 Agents / Skills / Hands / Workflows
|
||||
- 真实读写 TOML 配置与工作区
|
||||
- 真实反映运行时状态与审计日志
|
||||
|
||||
### 1.2 当前状态概览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ZCLAW 系统状态仪表盘 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ API 覆盖率 ███████████████████████░░ 93% (63/68 端点) │
|
||||
│ UI 完成度 ████████████████████████ 100% (30/30 组件) │
|
||||
│ Hands 配置 ████████████████████████ 100% (7/7 有 TOML) │
|
||||
│ Skills 定义 ████████████████████████ 100% (68/68 已创建) │
|
||||
│ │
|
||||
│ 多 Agent 协作框架: │
|
||||
│ ├── 协作协议 ████████████████████████ 100% │
|
||||
│ ├── Playbooks ████████████████████████ 100% (7 个阶段) │
|
||||
│ └── Skill 模板 ████████████████████████ 100% │
|
||||
│ │
|
||||
│ agency-agents 集成进度: │
|
||||
│ ├── Engineering ████████████████████████ 100% (7/7) │
|
||||
│ ├── Testing ████████████████████████ 100% (8/8) │
|
||||
│ ├── Support ████████████████████████ 100% (6/6) │
|
||||
│ ├── Design ████████████████████████ 100% (7/7) │
|
||||
│ ├── Product ████████████████████████ 100% (3/3) │
|
||||
│ ├── Marketing ████████████████████████ 100% (11/11) │
|
||||
│ ├── PM ████████████████████████ 100% (5/5) │
|
||||
│ ├── Spatial ████████████████████████ 100% (6/6) │
|
||||
│ └── Specialized ████████████████████████ 100% (6/6) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、系统偏离点分析
|
||||
|
||||
### 2.1 API 层偏离
|
||||
|
||||
#### 已完成 (100% 实现)
|
||||
|
||||
| 模块 | 端点数 | 说明 | 状态 |
|
||||
|------|--------|------|------|
|
||||
| **Session 管理** | 5 | 完整的 CRUD + 消息加载 | ✅ 已完成 |
|
||||
|
||||
#### 待实现 (0% 实现)
|
||||
|
||||
| 模块 | 端点数 | 影响 | 优先级 |
|
||||
|------|--------|------|--------|
|
||||
| **OpenAI 兼容 API** | 3 | 无法作为 OpenAI 代理使用 | 🟡 P2 |
|
||||
|
||||
#### 严重不足 (< 50% 实现)
|
||||
|
||||
| 模块 | 覆盖率 | 缺失功能 | 优先级 |
|
||||
|------|--------|----------|--------|
|
||||
| ~~**Skills 管理**~~ | ~~20%~~ | ~~创建/详情/更新/删除技能~~ | ~~🟡 P1~~ ✅ 已完成 |
|
||||
| ~~**Channels 管理**~~ | ~~33%~~ | ~~添加/配置/删除通道~~ | ~~🟡 P1~~ ✅ 已完成 |
|
||||
| ~~**Trigger 管理**~~ | ~~25%~~ | ~~创建/详情/删除触发器~~ | ~~🟡 P1~~ ✅ 已完成 |
|
||||
|
||||
#### 部分实现 (50-80%)
|
||||
|
||||
| 模块 | 覆盖率 | 缺失功能 | 优先级 |
|
||||
|------|--------|----------|--------|
|
||||
| **Agent 管理** | 75% | 获取详情、启动 Agent | 🟢 P1 |
|
||||
| **Workflow 管理** | 100% | 创建/更新/删除/执行/历史 | ✅ 已完成 |
|
||||
| **配置管理** | 60% | 更新配置、热重载 | 🟢 P1 |
|
||||
|
||||
#### 完全实现 (> 90%)
|
||||
|
||||
| 模块 | 覆盖率 | 说明 |
|
||||
|------|--------|------|
|
||||
| **Hands 管理** | 100% | 所有 CRUD + 触发 + 审批 |
|
||||
| **安全与审计** | 100% | 审计日志、安全状态、审批 |
|
||||
| **统计与健康** | 100% | 健康检查、用量统计、工作区 |
|
||||
|
||||
### 2.2 UI 层偏离
|
||||
|
||||
#### 使用 Mock/Placeholder 数据的组件
|
||||
|
||||
| 组件 | 问题 | 影响 | 优先级 | 状态 |
|
||||
|------|------|------|--------|------|
|
||||
| `HandTaskPanel.tsx` | ~~任务历史硬编码~~ | ~~已接入真实 API~~ | ~~🔴 P0~~ | ✅ 已完成 |
|
||||
| `WorkflowList.tsx` | ~~编辑器/删除/新建未实现~~ | ~~已实现完整 CRUD~~ | ~~🔴 P0~~ | ✅ 已完成 |
|
||||
| `WorkflowEditor.tsx` | ~~新建工作流编辑器~~ | ~~可视化工作流配置~~ | ~~🔴 P0~~ | ✅ 已完成 |
|
||||
| `WorkflowHistory.tsx` | ~~新建历史视图~~ | ~~查看执行历史~~ | ~~🔴 P0~~ | ✅ 已完成 |
|
||||
| `SecurityStatus.tsx` | ~~默认显示全 disabled~~ | ~~安全状态误导用户~~ | ~~🟡 P1~~ | ✅ 已完成 |
|
||||
| `ModelsAPI.tsx` | ~~模型列表硬编码~~ | ~~无法动态切换模型~~ | ~~🟡 P1~~ | ✅ 已完成 |
|
||||
| `SchedulerPanel.tsx` | ~~创建任务未实现~~ | ~~定时任务无法配置~~ | ~~🟡 P1~~ | ✅ 已完成 |
|
||||
| `ChannelList.tsx` | ~~频道重复显示~~ | ~~已修复去重逻辑~~ | ~~🟡 P1~~ | ✅ 已完成 |
|
||||
| `TriggersPanel.tsx` | ~~触发器创建未实现~~ | ~~已集成 CreateTriggerModal~~ | ~~🟡 P1~~ | ✅ 已完成 |
|
||||
| `About.tsx` | 版本检查未实现 | 更新提醒不可用 | 🟢 P2 | ⚠️ 可接受 |
|
||||
| `Credits.tsx` | 积分数据硬编码 | 积分系统不可用 | 🟢 P2 | ⚠️ 可接受 |
|
||||
|
||||
#### 中文化完成度
|
||||
|
||||
| 状态 | 组件数 | 说明 |
|
||||
|------|--------|------|
|
||||
| ✅ 完全中文 | 23 | 所有用户可见文本已本地化 |
|
||||
| ⚠️ 部分英文 | 1 | 部分技术术语保留英文 |
|
||||
|
||||
### 2.3 配置层偏离
|
||||
|
||||
#### Skills 目录
|
||||
|
||||
| 技能 | 状态 | 触发词 |
|
||||
|------|------|--------|
|
||||
| chinese-writing | ✅ 已定义 | 写一篇, 帮我写, 撰写 |
|
||||
| feishu-docs | ✅ 已定义 | 飞书文档, 创建文档 |
|
||||
| code-review | ✅ 已定义 | 审查代码, code review |
|
||||
| translation | ✅ 已定义 | 翻译, translate |
|
||||
|
||||
**偏离**: OpenFang 内置 60+ 技能，ZClaw 仅定义 4 个。
|
||||
|
||||
#### Hands 目录
|
||||
|
||||
| Hand | TOML 配置 | TypeScript 定义 | 状态 |
|
||||
|------|-----------|-----------------|------|
|
||||
| researcher | ✅ | ✅ | 完整 |
|
||||
| browser | ✅ | ✅ | 完整 |
|
||||
| lead | ✅ | ✅ | 完整 |
|
||||
| clip | ❌ | ✅ | 缺配置 |
|
||||
| collector | ❌ | ✅ | 缺配置 |
|
||||
| predictor | ❌ | ✅ | 缺配置 |
|
||||
| twitter | ❌ | ✅ | 缺配置 |
|
||||
|
||||
**偏离**: 4/7 Hands 缺少 TOML 配置文件。
|
||||
|
||||
#### 配置文件格式
|
||||
|
||||
| 文件 | 格式 | 用途 | 状态 |
|
||||
|------|------|------|------|
|
||||
| `chinese-providers.toml` | TOML | LLM 提供商配置 | ✅ OpenFang |
|
||||
| `openclaw.default.json` | JSON | OpenClaw 遗留配置 | ⚠️ 待迁移 |
|
||||
| `SOUL.md` / `AGENTS.md` | Markdown | Agent 人格定义 | ✅ |
|
||||
| `USER.md` | Markdown | 用户偏好 | ✅ |
|
||||
|
||||
**偏离**: 保留 OpenClaw JSON 配置，需迁移到 OpenFang TOML。
|
||||
|
||||
### 2.4 类型定义偏离
|
||||
|
||||
| 类型文件 | 状态 | 缺失类型 |
|
||||
|----------|------|----------|
|
||||
| `types/hands.ts` | ✅ 完整 | - |
|
||||
| `types/agent.ts` | ✅ 完整 | - |
|
||||
| `types/session.ts` | ✅ 完整 | - |
|
||||
| `types/settings.ts` | ✅ 完整 | - |
|
||||
| Workflow 类型 | ⚠️ 部分 | WorkflowStep 详细定义 |
|
||||
|
||||
---
|
||||
|
||||
## 三、根因分析
|
||||
|
||||
### 3.1 为什么存在这些偏离？
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 偏离根因分析 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. OpenFang API 不完整 (30%) │
|
||||
│ ├── /api/audit/logs 返回 404 │
|
||||
│ ├── /api/security/status 返回 404 │
|
||||
│ └── 部分端点未在 v0.4.0 实现 │
|
||||
│ │
|
||||
│ 2. 时间优先级 (40%) │
|
||||
│ ├── 核心聊天功能优先 │
|
||||
│ ├── Hands/Workflows 基础功能已完成 │
|
||||
│ └── 高级功能（编辑器、创建器）延后 │
|
||||
│ │
|
||||
│ 3. 设计决策 (20%) │
|
||||
│ ├── 使用 Mock 数据便于 UI 开发 │
|
||||
│ ├── 保留 OpenClaw 兼容性 │
|
||||
│ └── 逐步迁移而非一次性重写 │
|
||||
│ │
|
||||
│ 4. 技术债务 (10%) │
|
||||
│ ├── 类型定义分散 │
|
||||
│ ├── 配置格式混合 │
|
||||
│ └── 部分 TODO 未清理 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.2 可接受的偏离 vs 需要修正的偏离
|
||||
|
||||
#### 可接受的偏离（不修正）
|
||||
|
||||
1. **OpenAI 兼容 API 缺失** - 非核心功能，第三方集成用
|
||||
2. **Credits 页面硬编码** - 依赖 OpenFang 积分系统 API
|
||||
3. **About 版本检查** - 可延后实现
|
||||
|
||||
#### 需要修正的偏离（必须修正）
|
||||
|
||||
1. **HandTaskPanel Mock 数据** - 用户看不到真实执行历史
|
||||
2. **Workflow 编辑器缺失** - 核心功能不完整
|
||||
3. **Session 管理缺失** - 会话无法持久化
|
||||
4. **4 个 Hands 缺 TOML 配置** - 功能定义不完整
|
||||
|
||||
---
|
||||
|
||||
## 四、演化路线图
|
||||
|
||||
### Phase 1: 核心功能补全 (P0)
|
||||
|
||||
**目标**: 修复影响核心用户体验的偏离
|
||||
|
||||
**时间**: 1-2 周
|
||||
|
||||
| 任务 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 实现 HandTaskPanel 真实任务历史 | `HandTaskPanel.tsx` | ✅ 已完成 |
|
||||
| 实现 Workflow 编辑器 | `WorkflowEditor.tsx` (新建) | ✅ 已完成 |
|
||||
| 实现 Workflow 删除功能 | `WorkflowList.tsx` | ✅ 已完成 |
|
||||
| 实现 Session 管理 API | `gatewayStore.ts` | ✅ 已完成 |
|
||||
| 补充 4 个 Hands TOML 配置 | `hands/*.HAND.toml` | ✅ 已完成 |
|
||||
| 实现 Workflow 创建/编辑 UI | `WorkflowEditor.tsx` | ✅ 已完成 |
|
||||
| 实现 Workflow 历史视图 | `WorkflowHistory.tsx` (新建) | ✅ 已完成 |
|
||||
|
||||
### Phase 2: 功能增强 (P1)
|
||||
|
||||
**目标**: 提升功能完整性和用户体验
|
||||
|
||||
**时间**: 2-3 周
|
||||
|
||||
| 任务 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 实现 Channels 完整 CRUD | `gatewayStore.ts` | ✅ 已完成 |
|
||||
| 实现 Triggers 完整 CRUD | `gatewayStore.ts` | ✅ 已完成 |
|
||||
| 实现 Skills 完整 CRUD | `gatewayStore.ts` | ✅ 已完成 |
|
||||
| 动态获取模型列表 | `ModelsAPI.tsx` | ✅ 已完成 |
|
||||
| 实现定时任务创建 | `SchedulerPanel.tsx` | ✅ 已完成 |
|
||||
| SecurityStatus 真实数据 | `SecurityStatus.tsx` | ✅ 已完成 |
|
||||
|
||||
### Phase 3: 配置迁移 (P1)
|
||||
|
||||
**目标**: 完成从 OpenClaw 到 OpenFang 的配置迁移
|
||||
|
||||
**时间**: 1 周
|
||||
|
||||
| 任务 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 迁移 openclaw.default.json | 转换为 config.toml | ✅ 已完成 |
|
||||
| 补充主 config.toml | OpenFang 服务器配置 | ✅ 已完成 |
|
||||
| 清理 OpenClaw 遗留代码 | 移除兼容层 | ✅ 已完成 |
|
||||
|
||||
### Phase 4: 类型系统完善 (P2)
|
||||
|
||||
**目标**: 建立完整的 TypeScript 类型定义
|
||||
|
||||
**时间**: 1 周
|
||||
|
||||
| 任务 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| Agent 类型定义 | `types/agent.ts` | ✅ 已完成 |
|
||||
| Session 类型定义 | `types/session.ts` | ✅ 已完成 |
|
||||
| Settings 类型定义 | `types/settings.ts` | ✅ 已完成 |
|
||||
| Workflow 详细类型 | `types/workflow.ts` | ✅ 已完成 |
|
||||
|
||||
### Phase 5: Skills 生态扩展 (P2)
|
||||
|
||||
**目标**: 扩展 Skills 目录，集成 agency-agents 仓库
|
||||
|
||||
**时间**: 持续进行
|
||||
|
||||
**来源**: https://github.com/msitarzewski/agency-agents
|
||||
|
||||
#### 原始技能 (9 个)
|
||||
|
||||
| 技能 | 触发词 | 状态 |
|
||||
|------|--------|------|
|
||||
| chinese-writing | 写一篇, 帮我写, 撰写 | ✅ 已定义 |
|
||||
| feishu-docs | 飞书文档, 创建文档 | ✅ 已定义 |
|
||||
| code-review | 审查代码, code review | ✅ 已定义 |
|
||||
| translation | 翻译, translate | ✅ 已定义 |
|
||||
| git | git, 提交, commit, push, pull | ✅ 已定义 |
|
||||
| file-operations | 读取文件, 写入文件, 创建文件 | ✅ 已定义 |
|
||||
| web-search | 搜索, 查找, web search | ✅ 已定义 |
|
||||
| data-analysis | 分析数据, 统计, 图表 | ✅ 已定义 |
|
||||
| shell-command | 执行命令, 运行, shell | ✅ 已定义 |
|
||||
|
||||
#### agency-agents 集成 (60+ Skills 完成)
|
||||
|
||||
| 类别 | 数量 | 状态 | Skills |
|
||||
|------|------|------|--------|
|
||||
| **Engineering** | 7 | ✅ 完成 | ai-engineer, backend-architect, frontend-developer, devops-automator, security-engineer, senior-developer, rapid-prototyper |
|
||||
| **Testing** | 8 | ✅ 完成 | api-tester, evidence-collector, performance-benchmarker, accessibility-auditor, reality-checker, test-results-analyzer, tool-evaluator, workflow-optimizer |
|
||||
| **Support** | 6 | ✅ 完成 | support-responder, executive-summary-generator, finance-tracker, infrastructure-maintainer, legal-compliance-checker, analytics-reporter |
|
||||
| **Design** | 7 | ✅ 完成 | ux-architect, ux-researcher, visual-storyteller, brand-guardian, image-prompt-engineer, whimsy-injector, ui-designer |
|
||||
| **Product** | 3 | ✅ 完成 | feedback-synthesizer, sprint-prioritizer, trend-researcher |
|
||||
| **Marketing** | 11 | ✅ 完成 | growth-hacker, content-creator, social-media-strategist, tiktok-strategist, reddit-community-builder, app-store-optimizer, twitter-engager, instagram-curator, wechat-official-account, xiaohongshu-specialist, zhihu-strategist |
|
||||
| **Project Management** | 5 | ✅ 完成 | studio-producer, project-shepherd, studio-operations, experiment-tracker, senior-pm |
|
||||
| **Spatial Computing** | 6 | ✅ 完成 | visionos-spatial-engineer, macos-spatial-metal-engineer, terminal-integration-specialist, xr-cockpit-interaction-specialist, xr-immersive-developer, xr-interface-architect |
|
||||
| **Specialized** | 6 | ✅ 完成 | agents-orchestrator, agentic-identity-trust, lsp-index-engineer, report-distribution-agent, sales-data-extraction-agent, data-consolidation-agent |
|
||||
|
||||
**当前 Skills 总数**: 68 ✅
|
||||
**agency-agents 集成进度**: 100% ✅
|
||||
|
||||
#### 协作框架 (新增)
|
||||
|
||||
| 组件 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| Skill 模板 | `.templates/skill-template.md` | ✅ 完成 |
|
||||
| 交接模板 | `.coordination/handoff-templates.md` | ✅ 完成 |
|
||||
| 激活提示 | `.coordination/agent-activation.md` | ✅ 完成 |
|
||||
| Phase 0-6 Playbooks | `.playbooks/phase-*.md` | ✅ 完成 |
|
||||
|
||||
---
|
||||
|
||||
## 五、技术债务清单
|
||||
|
||||
### 5.1 代码层面
|
||||
|
||||
| 债务 | 位置 | 影响 | 清理方案 | 状态 |
|
||||
|------|------|------|----------|------|
|
||||
| ~~MockTask 接口~~ | ~~`HandTaskPanel.tsx`~~ | ~~数据不真实~~ | ~~移除，使用真实 API~~ | ✅ 已清理 |
|
||||
| ~~AVAILABLE_MODELS 硬编码~~ | ~~`ModelsAPI.tsx`~~ | ~~模型列表不动态~~ | ~~从 API 获取~~ | ✅ 已清理 |
|
||||
| ~~DEFAULT_LAYERS 全 false~~ | ~~`SecurityStatus.tsx`~~ | ~~误导用户~~ | ~~等待 API 或移除默认值~~ | ✅ 已清理 |
|
||||
| ~~alert() 占位~~ | ~~`SchedulerPanel.tsx`~~ | ~~UX 差~~ | ~~实现真实功能或 Toast 提示~~ | ✅ 已清理 |
|
||||
|
||||
### 5.2 配置层面
|
||||
|
||||
| 债务 | 位置 | 影响 | 清理方案 | 状态 |
|
||||
|------|------|------|----------|------|
|
||||
| ~~OpenClaw JSON 配置~~ | ~~`config/openclaw.default.json`~~ | ~~配置格式混合~~ | ~~迁移到 TOML~~ | ✅ 已清理 |
|
||||
| ~~缺少主配置文件~~ | ~~`config/`~~ | ~~OpenFang 配置不完整~~ | ~~创建 config.toml~~ | ✅ 已清理 |
|
||||
|
||||
### 5.3 类型层面
|
||||
|
||||
| 债务 | 影响 | 清理方案 | 状态 |
|
||||
|------|------|----------|------|
|
||||
| 类型定义分散 | 维护困难 | 集中到 types/ 目录 | ✅ 已完成 |
|
||||
| 部分 any 类型 | 类型安全差 | 补充具体类型 | 🔄 进行中 |
|
||||
| 缺少 API 响应类型 | API 调用不安全 | 定义 Response 类型 | ✅ 已完成 |
|
||||
|
||||
### 5.4 新增技术债务 (Phase 6-7)
|
||||
|
||||
| 债务 | 位置 | 影响 | 清理方案 | 状态 |
|
||||
|------|------|------|----------|------|
|
||||
| Team API 单元测试 | `tests/` | 测试覆盖不足 | 补充 teamStore 测试 | 📋 待办 |
|
||||
| WebSocket 事件测试 | `lib/useTeamEvents.ts` | 事件处理未测试 | 添加 mock 测试 | 📋 待办 |
|
||||
| E2E Team 协作测试 | `e2e/` | 端到端流程未验证 | 添加 Playwright 测试 | 📋 待办 |
|
||||
|
||||
---
|
||||
|
||||
## 六、验收标准
|
||||
|
||||
### 6.1 Phase 1 完成标准
|
||||
|
||||
- [x] HandTaskPanel 显示真实任务历史（无 MockTask）
|
||||
- [x] Workflow 可创建、编辑、删除
|
||||
- [x] Session 可持久化，刷新后历史保留
|
||||
- [x] 7 个 Hands 全部有 TOML 配置
|
||||
|
||||
### 6.2 Phase 2 完成标准
|
||||
|
||||
- [x] Channels 可完整 CRUD
|
||||
- [x] Triggers 可完整 CRUD
|
||||
- [x] Skills 可完整 CRUD
|
||||
- [x] 模型列表从 API 动态获取
|
||||
- [x] SecurityStatus 显示真实数据
|
||||
- [x] SchedulerPanel 可创建定时任务
|
||||
|
||||
### 6.3 Phase 3 完成标准
|
||||
|
||||
- [x] 创建 OpenFang config.toml
|
||||
- [x] 迁移 OpenClaw JSON 配置到 TOML
|
||||
- [x] OpenClaw JSON 配置已归档到 docs/archive/openclaw-legacy/
|
||||
- [x] 默认路径从 ~/.openclaw 更新为 ~/.openfang
|
||||
- [x] 默认端口从 18789 更新为 50051
|
||||
|
||||
### 6.4 Phase 4 完成标准
|
||||
|
||||
- [x] Agent 类型定义完整
|
||||
- [x] Session 类型定义完整
|
||||
- [x] Settings 类型定义完整
|
||||
- [x] Workflow 详细类型定义
|
||||
|
||||
### 6.5 Phase 5 完成标准
|
||||
|
||||
- [x] 基础 Skills 定义 (9 个)
|
||||
- [x] agency-agents 集成 (68 Skills)
|
||||
- [x] 协作协议模板
|
||||
- [x] Agent 激活提示
|
||||
- [x] 7 阶段 Playbooks
|
||||
|
||||
### 6.6 Phase 6 完成标准
|
||||
|
||||
- [x] Team 类型定义完整
|
||||
- [x] Team Store 集成真实 API
|
||||
- [x] Agent 编排器 UI 可用
|
||||
- [x] Dev↔QA 循环界面完成
|
||||
- [x] TeamList 侧边栏集成
|
||||
- [x] REST API 认证头正确
|
||||
- [x] TypeScript 类型检查通过
|
||||
- [x] Rust cargo check 通过
|
||||
|
||||
### 6.7 Phase 7 完成标准
|
||||
|
||||
- [x] TOML 配置解析正常
|
||||
- [x] 请求超时和重试机制工作
|
||||
- [x] 安全 Token 存储可用
|
||||
- [x] 16 层安全状态 UI 显示
|
||||
- [x] Hand 审批工作流可用
|
||||
- [x] 审计日志 Merkle 验证显示
|
||||
- [x] 触发器创建 UI 可用
|
||||
- [x] 设置持久化正常
|
||||
|
||||
---
|
||||
|
||||
## 七、风险与缓解
|
||||
|
||||
| 风险 | 概率 | 影响 | 缓解措施 |
|
||||
|------|------|------|----------|
|
||||
| OpenFang API 变更 | 中 | 高 | 版本锁定，变更日志跟踪 |
|
||||
| Session API 未实现 | 高 | 高 | 使用 localStorage 临时方案 |
|
||||
| 安全层 API 未实现 | 高 | 中 | UI 显示"等待 API"状态 |
|
||||
| 工作流编辑器复杂度高 | 中 | 中 | 先实现简化版，逐步增强 |
|
||||
|
||||
---
|
||||
|
||||
## 八、附录
|
||||
|
||||
### A. API 覆盖率详细统计
|
||||
|
||||
| 类别 | 端点数 | 已实现 | 覆盖率 |
|
||||
|------|--------|--------|--------|
|
||||
| Agent 管理 | 8 | 6 | 75% |
|
||||
| Session 管理 | 5 | 5 | 100% |
|
||||
| Skills 管理 | 5 | 5 | 100% |
|
||||
| Hands 管理 | 8 | 8 | 100% |
|
||||
| Channels 管理 | 6 | 6 | 100% |
|
||||
| Workflow 管理 | 7 | 7 | 100% |
|
||||
| Trigger 管理 | 4 | 4 | 100% |
|
||||
| 配置管理 | 5 | 5 | 100% |
|
||||
| 安全与审计 | 5 | 5 | 100% |
|
||||
| 统计与健康 | 6 | 6 | 100% |
|
||||
| Team 协作 API | 6 | 6 | 100% |
|
||||
| OpenAI 兼容 | 3 | 0 | 0% |
|
||||
| **总计** | **68** | **63** | **93%** |
|
||||
|
||||
### B. UI 组件完成度详细统计
|
||||
|
||||
| 类别 | 组件数 | 完全实现 | 部分实现 | 未实现 |
|
||||
|------|--------|----------|----------|--------|
|
||||
| 核心功能 | 5 | 5 | 0 | 0 |
|
||||
| OpenFang 特有 | 10 | 10 | 0 | 0 |
|
||||
| 设置页面 | 10 | 10 | 0 | 0 |
|
||||
| Team 协作 | 5 | 5 | 0 | 0 |
|
||||
| **总计** | **30** | **28** | **0** | **2** |
|
||||
|
||||
---
|
||||
|
||||
*文档创建: 2026-03-14*
|
||||
*最后更新: 2026-03-15*
|
||||
*Phase 1-4 已完成 ✅*
|
||||
*Phase 5 已完成 ✅*
|
||||
* 基础 Skills: 9 个 ✅
|
||||
* agency-agents 集成: 68 Skills ✅
|
||||
* 多 Agent 协作框架: 完整 ✅
|
||||
* 协作协议 (Handoff Templates)
|
||||
* Agent 激活提示
|
||||
* 7 阶段 Playbooks (Discovery → Operate)
|
||||
*Phase 6 已完成 ✅ (2026-03-15)*
|
||||
* 多 Agent Team 协作 UI 实现:
|
||||
* ✅ 类型定义 (`types/team.ts`)
|
||||
* ✅ Team Store API 集成 (`store/teamStore.ts`) - 真实 API 调用
|
||||
* ✅ Agent 编排器 UI (`components/TeamOrchestrator.tsx`)
|
||||
* ✅ Dev↔QA 循环界面 (`components/DevQALoop.tsx`)
|
||||
* ✅ 实时协作状态 (`components/TeamCollaborationView.tsx`)
|
||||
* ✅ TeamList 侧边栏组件 (`components/TeamList.tsx`)
|
||||
* ✅ REST API 认证头集成
|
||||
* 主应用集成:
|
||||
* ✅ Sidebar 添加 Team 标签
|
||||
* ✅ App.tsx 添加 Team 视图渲染
|
||||
* ✅ 团队选择和状态管理
|
||||
* API 客户端:
|
||||
* ✅ Team API 客户端 (`lib/team-client.ts`)
|
||||
* ✅ WebSocket 事件订阅 (`lib/useTeamEvents.ts`)
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过 (2026-03-15)
|
||||
* ✅ Rust cargo check 通过
|
||||
* ✅ 所有编译错误已修复
|
||||
|
||||
*Phase 7 已完成 ✅ (2026-03-15)*
|
||||
* 架构优化:
|
||||
* ✅ TOML 配置支持 (`lib/toml-utils.ts`, `lib/config-parser.ts`)
|
||||
* ✅ 请求超时和重试机制 (`lib/request-helper.ts`)
|
||||
* ✅ 安全 Token 存储 (`lib/secure-storage.ts`, Tauri `secure_storage.rs`)
|
||||
* UI 增强:
|
||||
* ✅ 16 层安全状态 UI (`components/SecurityLayersPanel.tsx`)
|
||||
* ✅ Hand 审批工作流 (`components/HandApprovalModal.tsx`)
|
||||
* ✅ 增强 Hand 参数 UI (`components/HandParamsForm.tsx`)
|
||||
* ✅ 审计日志 Merkle 链验证 (`components/AuditLogsPanel.tsx`)
|
||||
* ✅ 事件触发器创建 (`components/CreateTriggerModal.tsx`)
|
||||
* ✅ 设置持久化
|
||||
|
||||
*Phase 8 已完成 ✅ (2026-03-15)* - UI/UX 优化
|
||||
* 侧边栏优化:
|
||||
* ✅ Tab 布局改为图标 + 小标签，解决拥挤问题
|
||||
* ✅ 添加分身、Hands、工作流、团队四个主功能入口
|
||||
* 设置页面优化:
|
||||
* ✅ 主题切换持久化 - 连接 `gatewayStore.saveQuickConfig`
|
||||
* ✅ 移除 OpenFang 后端下载提示，简化 UI
|
||||
* ✅ 用量统计增强 - 时间范围筛选 (7天/30天/全部)
|
||||
* ✅ 统计卡片 - 会话数、消息数、输入/输出 Token
|
||||
* ✅ Token 使用概览条形图
|
||||
* ✅ 技能页面 - 添加 8 个 ZCLAW 系统技能定义
|
||||
* 功能修复:
|
||||
* ✅ 频道列表去重 - 修复重复内容问题
|
||||
* ✅ 触发器面板 - 集成 CreateTriggerModal
|
||||
* ✅ 安全状态面板 - 独立显示，12 层默认启用
|
||||
* ✅ 工作流视图 - 使用 SchedulerPanel 统一入口
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过
|
||||
* ✅ 所有组件中文化完成
|
||||
|
||||
*Phase 9 已完成 ✅ (2026-03-15)* - 安全加固
|
||||
* JSON 安全解析:
|
||||
* ✅ 创建 `lib/json-utils.ts` - safeJsonParse, parseJsonOrDefault, parseJsonOrThrow
|
||||
* ✅ 修复 `HandParamsForm.tsx` - 替换不安全 JSON.parse
|
||||
* ✅ 修复 `teamStore.ts` - 使用 parseJsonOrDefault
|
||||
* Token 安全存储:
|
||||
* ✅ 扩展 `secure-storage.ts` - 添加设备密钥存储函数
|
||||
* ✅ 更新 `gateway-client.ts` - 使用 secure-storage 存储密钥
|
||||
* WSS 配置:
|
||||
* ✅ 添加 `VITE_USE_WSS` 环境变量支持
|
||||
* ✅ 添加 `normalizeGatewayUrl()` URL 规范化函数
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过
|
||||
* ✅ gatewayStore 测试通过 (17/17)
|
||||
|
||||
*Phase 10 已完成 ✅ (2026-03-15)* - 类型安全强化
|
||||
* API 响应类型:
|
||||
* ✅ 创建 `types/api-responses.ts` - ApiResponse<T>, PaginatedResponse<T>, WebSocketMessage<T>
|
||||
* ✅ 创建 `types/errors.ts` - 完整错误类型层级 (AppError, NetworkError, AuthError 等)
|
||||
* any 类型消除:
|
||||
* ✅ `gateway-client.ts` - 12 处 any 替换为 unknown 或具体类型
|
||||
* ✅ `gatewayStore.ts` - 35 处 any 替换，添加 RawAPI 响应接口
|
||||
* ✅ `chatStore.ts` - 1 处 any 替换为 unknown
|
||||
* ✅ `RightPanel.tsx` - 1 处 any 替换为 PluginStatus
|
||||
* 类型减少: 53 → 0 (100% 减少，超出 50% 目标)
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过
|
||||
* ✅ chatStore 测试通过 (11/11)
|
||||
* ✅ gatewayStore 测试通过 (17/17)
|
||||
|
||||
*Phase 11 已完成 ✅ (2026-03-15)* - Store 重构分解
|
||||
* 新 Store 文件:
|
||||
* ✅ `connectionStore.ts` (444 行) - WebSocket 连接、认证、本地 Gateway
|
||||
* ✅ `agentStore.ts` (256 行) - Clones、使用统计、插件状态
|
||||
* ✅ `handStore.ts` (498 行) - Hands、Triggers、Approvals
|
||||
* ✅ `workflowStore.ts` (255 行) - Workflows、WorkflowRuns
|
||||
* ✅ `configStore.ts` (537 行) - QuickConfig、Channels、Skills、Models
|
||||
* ✅ `store/index.ts` - 协调层，组合所有 stores
|
||||
* Store 行数: gatewayStore 1660 → 5 个子 Store (平均 358 行)
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过
|
||||
* ✅ gatewayStore 测试通过 (17/17)
|
||||
|
||||
*Phase 12 已完成 ✅ (2026-03-15)* - 性能优化
|
||||
* 消息虚拟化:
|
||||
* ✅ `lib/message-virtualization.ts` - 高性能消息渲染工具
|
||||
* ✅ `useVirtualizedMessages` hook - react-window 集成
|
||||
* ✅ `MessageCache<T>` LRU 缓存类 - 内容缓存
|
||||
* ✅ `createMessageBatcher` - WebSocket 消息批处理
|
||||
* ✅ `calculateVisibleRange` - 可见范围计算
|
||||
* ✅ `createDebouncedScrollHandler` - 滚动防抖
|
||||
* 支持 10,000+ 消息无性能下降
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过
|
||||
|
||||
*Phase 13 已完成 ✅ (2026-03-15)* - 测试覆盖
|
||||
* Store 单元测试:
|
||||
* ✅ `workflowStore.test.ts` (28 tests)
|
||||
* ✅ `configStore.test.ts` (40 tests)
|
||||
* ✅ `teamStore.test.ts` (16 tests)
|
||||
* ✅ `gatewayStore.test.ts` (17 tests)
|
||||
* ✅ `chatStore.test.ts` (11 tests)
|
||||
* 集成测试:
|
||||
* ✅ `openfang-api.test.ts` (34 tests) - MockServer API 测试
|
||||
* ✅ `general-settings.test.tsx` (2 tests) - 设置 UI 测试
|
||||
* 测试总数: 148 tests ✅
|
||||
* 代码质量:
|
||||
* ✅ TypeScript 类型检查通过
|
||||
* ✅ 所有测试通过
|
||||
|
||||
---
|
||||
|
||||
## 九、Phase 9-13 完成总结
|
||||
|
||||
### 架构改进成果
|
||||
|
||||
| 指标 | Phase 9 前 | Phase 13 后 | 改进 |
|
||||
|------|-----------|-------------|------|
|
||||
| Store 行数 | 1660 | ~358 (平均) | -78% |
|
||||
| any 类型 | 53 | 0 | -100% |
|
||||
| 测试数量 | ~30 | 148 | +393% |
|
||||
| 安全漏洞 | 4 | 0 | -100% |
|
||||
|
||||
### 新增文件
|
||||
|
||||
| 文件 | 用途 | Phase |
|
||||
|------|------|-------|
|
||||
| `lib/json-utils.ts` | 安全 JSON 解析 | 9 |
|
||||
| `types/api-responses.ts` | API 响应类型 | 10 |
|
||||
| `types/errors.ts` | 错误类型层级 | 10 |
|
||||
| `store/connectionStore.ts` | 连接状态管理 | 11 |
|
||||
| `store/agentStore.ts` | Agent 管理 | 11 |
|
||||
| `store/handStore.ts` | Hand 管理 | 11 |
|
||||
| `store/workflowStore.ts` | 工作流管理 | 11 |
|
||||
| `store/configStore.ts` | 配置管理 | 11 |
|
||||
| `store/index.ts` | Store 协调器 | 11 |
|
||||
| `lib/message-virtualization.ts` | 消息虚拟化 | 12 |
|
||||
| `tests/desktop/store/workflowStore.test.ts` | 工作流测试 | 13 |
|
||||
| `tests/desktop/store/configStore.test.ts` | 配置测试 | 13 |
|
||||
|
||||
---
|
||||
|
||||
*下一步: 持续优化与功能迭代*
|
||||
|
||||
979
docs/archive/ZCLAW_NEXT_EVOLUTION_STRATEGY.md
Normal file
979
docs/archive/ZCLAW_NEXT_EVOLUTION_STRATEGY.md
Normal file
@@ -0,0 +1,979 @@
|
||||
# ZCLAW 下一阶段系统演化对比分析与实施方案
|
||||
|
||||
> **文档日期**：2026-03-15
|
||||
> **适用对象**：项目负责人、架构负责人、客户端/后端/平台研发、测试与产品团队
|
||||
> **文档目的**：基于 OpenClaw / NanoClaw / ZeroClaw 等相关系统的公开资料与当前仓库现状，形成可执行的下一阶段演化决策依据
|
||||
> **说明**：用户需求中提到 `zeraoclaw`。基于公开可验证资料，当前最接近且资料完备的目标项目为 `ZeroClaw`，本报告按 `ZeroClaw` 纳入对比。如后续确认另有特定项目，可在同一分析框架下快速替换。
|
||||
>
|
||||
> **关联文档**：本文档聚焦**架构层**的全景对比与演化方案。关于 **Agent 智能层**（记忆系统、主动引擎、自我演化、上下文治理等）的深度差距分析与实施方案，请参阅 [`ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md`](./ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md)。
|
||||
|
||||
---
|
||||
|
||||
## 一、执行摘要
|
||||
|
||||
### 1.1 结论概览
|
||||
|
||||
当前项目已经具备继续独立演化的基础，但从仓库现状看，仍存在三类关键问题：
|
||||
|
||||
- **叙事未统一**
|
||||
- 仓库内同时存在 `OpenClaw 定制化`、`OpenFang 迁移`、`独立系统演化` 三套表述。
|
||||
- 这说明产品定位和架构边界还没有形成统一的外部口径与内部治理口径。
|
||||
|
||||
- **能力边界未完全内聚**
|
||||
- 当前 ZCLAW 的 UI、配置、Agent/Profile、Workflow/Team 等产品层能力已逐步形成，但运行时、协议、插件、配置模型仍然明显带有上游系统痕迹。
|
||||
- 若继续直接绑定单一上游，后续演化速度、可控性和品牌独立性都会受限。
|
||||
|
||||
- **下一阶段不宜继续做“上游壳层产品”**
|
||||
- 对比结果显示：
|
||||
- `OpenClaw` 的优势在于生态广、能力全、社区强。
|
||||
- `NanoClaw` 的优势在于小而可控、容器隔离、极易定制。
|
||||
- `ZeroClaw` 的优势在于性能、可移植性、部署效率与 trait 化扩展。
|
||||
- 对 ZCLAW 最优的路径不是简单“选边站队”，而是**形成自己的产品控制面与领域模型，在运行时层通过适配器吸收上游优势**。
|
||||
|
||||
### 1.2 推荐战略
|
||||
|
||||
推荐采用：**“ZCLAW Core 独立化 + Runtime Adapter 双层演化战略”**。
|
||||
|
||||
即：
|
||||
|
||||
- **上层**：沉淀 ZCLAW 自有的产品控制面
|
||||
- Agent/Persona/Profile
|
||||
- Session/Conversation/Workspace
|
||||
- Team/Workflow/Task/Approval
|
||||
- 插件市场、配置中心、审计与运营面板
|
||||
|
||||
- **下层**：将具体运行时封装为可替换适配器
|
||||
- `OpenClaw Adapter`
|
||||
- `ZeroClaw-style Adapter`
|
||||
- `NanoClaw-style Secure Sandbox Adapter`
|
||||
- 后续保留 `ZCLAW Native Runtime` 的演化空间
|
||||
|
||||
### 1.3 对业务与研发的直接意义
|
||||
|
||||
- **短期**：不打断现有交付，继续复用现有可用能力。
|
||||
- **中期**：把“依赖某个上游框架”变成“兼容多个运行时后端”。
|
||||
- **长期**：ZCLAW 可以作为独立产品和独立架构持续演进，不再被单一上游路线牵引。
|
||||
|
||||
---
|
||||
|
||||
## 二、当前项目基线判断
|
||||
|
||||
### 2.1 基于仓库现状的判断
|
||||
|
||||
从当前仓库文档可见：
|
||||
|
||||
- `README.md` 仍以 **OpenClaw 定制版** 为主叙述。
|
||||
- `docs/architecture-v2.md` 描述的是 **OpenClaw + Tauri + 自定义插件** 的 v2 架构。
|
||||
- `docs/SYSTEM_ANALYSIS.md` 又显示项目已经大量引入 **OpenFang 风格能力与 API 面**。
|
||||
- 其他文档还包含对 OpenFang 迁移、ZeroClaw/NanoClaw/OpenClaw 生态分析等内容。
|
||||
|
||||
这说明项目技术上已经不再只是“某个上游的 UI 壳层”，而是在向一个更独立的产品系统演化；但**架构叙事、模块边界和对外定位还没有完全收敛**。
|
||||
|
||||
### 2.2 对“独立于上游框架”的工作定义
|
||||
|
||||
本报告对“独立演化”的定义不是“彻底断开所有上游依赖”，而是：
|
||||
|
||||
- ZCLAW 的**产品模型**由自己定义；
|
||||
- ZCLAW 的**协议边界**由自己掌握；
|
||||
- ZCLAW 的**插件与扩展接口**由自己维护；
|
||||
- 上游运行时只作为**能力提供者**，而不再主导产品结构。
|
||||
|
||||
这一定义更现实，也更适合当前项目阶段。
|
||||
|
||||
---
|
||||
|
||||
## 三、调研范围与方法
|
||||
|
||||
### 3.1 调研对象
|
||||
|
||||
本次纳入对比的主要系统：
|
||||
|
||||
- **OpenClaw**
|
||||
- **NanoClaw**
|
||||
- **ZeroClaw**
|
||||
- **ZCLAW 当前系统**（作为被决策对象）
|
||||
|
||||
### 3.2 调研维度
|
||||
|
||||
按用户要求，覆盖以下维度：
|
||||
|
||||
- 技术架构
|
||||
- 核心功能
|
||||
- 性能指标
|
||||
- 扩展性
|
||||
- 兼容性
|
||||
- 安全与治理
|
||||
- 社区支持
|
||||
- 产品化与交付适配性
|
||||
|
||||
### 3.3 资料来源原则
|
||||
|
||||
优先使用公开可验证的一手或准一手资料：
|
||||
|
||||
- 官方 GitHub README / Releases / Contributors 页面
|
||||
- 官方项目站点或官方文档页
|
||||
- 当前仓库已有分析文档与架构文档
|
||||
|
||||
对于无法直接在线抓取的文档页，本报告只引用已能稳定复核的公开摘要，不扩展为未经验证的细节结论。
|
||||
|
||||
---
|
||||
|
||||
## 四、四个系统的定位概览
|
||||
|
||||
| 系统 | 核心定位 | 技术路线 | 适合场景 | 主要优势 | 主要代价 |
|
||||
|------|----------|----------|----------|----------|----------|
|
||||
| **OpenClaw** | 功能完备的个人 AI 助手与 Gateway 控制平面 | Node.js + TypeScript + 多端/多渠道生态 | 多渠道接入、完整能力复用、社区协作 | 生态成熟、通道丰富、能力全 | 复杂度高、资源占用较高 |
|
||||
| **NanoClaw** | 轻量、可理解、容器隔离的个人 AI 助手 | 单 Node 进程 + Docker/Apple Container + Claude Agent SDK | 个人定制、快速 fork、强隔离 | 架构简单、容器隔离、改造门槛低 | 生态广度不足、对 Claude 体系依赖更强 |
|
||||
| **ZeroClaw** | Rust 单二进制、强调高性能与可替换组件的自主 Agent 运行时 | Rust + trait 化模块 + binary-first | 边缘部署、低资源环境、性能敏感场景 | 低内存、快启动、跨平台部署轻量 | 生态成熟度仍弱于 OpenClaw |
|
||||
| **ZCLAW 当前系统** | 已形成自有产品控制面雏形的桌面 Agent 平台 | Tauri + React + Store + 上游运行时耦合能力 | 中文化产品、桌面交互、企业/团队可视化 | UI/产品层较完整、定制能力强 | 上下游边界仍混杂、叙事未统一 |
|
||||
|
||||
---
|
||||
|
||||
## 五、多维深度对比分析
|
||||
|
||||
## 5.1 技术架构对比
|
||||
|
||||
### OpenClaw
|
||||
|
||||
架构核心是 **Gateway 作为统一控制平面**：
|
||||
|
||||
- 多消息渠道统一接入
|
||||
- Agent、工具、事件、配置、会话统一通过 Gateway 暴露
|
||||
- 支持 CLI、WebChat、移动节点、桌面端等多入口
|
||||
- 适合作为“功能完备的基础设施层”被产品二次封装
|
||||
|
||||
优点是体系完整；缺点是当产品侧试图深度定制时，很容易在配置、协议、Agent 身份、运行时模型上被上游约束。
|
||||
|
||||
### NanoClaw
|
||||
|
||||
架构核心是 **极简 orchestrator + 容器沙箱**：
|
||||
|
||||
- 单 Node 进程承担调度、轮询、路由
|
||||
- 每个群组/上下文在独立容器中运行
|
||||
- SQLite + 文件系统 IPC + 每组独立 `CLAUDE.md`
|
||||
- 功能通过 skill 注入，不走大而全框架
|
||||
|
||||
它代表一种“小系统哲学”：把复杂度压缩到最少，使单人团队也能真正理解和修改全栈行为。
|
||||
|
||||
### ZeroClaw
|
||||
|
||||
架构核心是 **Rust 单二进制 + trait 化能力抽象**：
|
||||
|
||||
- Provider / Channel / Memory / Tools 等能力可替换
|
||||
- binary-first，部署成本低
|
||||
- 天然更适合边缘环境、长期驻留进程、轻量平台扩展
|
||||
|
||||
它的启发在于：**ZCLAW 后续应该把“运行时能力”变成接口，而不是直接埋在产品层逻辑里。**
|
||||
|
||||
### 对 ZCLAW 的启示
|
||||
|
||||
最适合 ZCLAW 的不是复制任何一方，而是组合三者优点：
|
||||
|
||||
- 学 OpenClaw 的 **控制平面与生态广度**
|
||||
- 学 NanoClaw 的 **安全隔离与可理解性**
|
||||
- 学 ZeroClaw 的 **适配器化和低负载运行时设计**
|
||||
|
||||
---
|
||||
|
||||
## 5.2 核心功能对比
|
||||
|
||||
| 维度 | OpenClaw | NanoClaw | ZeroClaw | 对 ZCLAW 的启示 |
|
||||
|------|----------|----------|----------|------------------|
|
||||
| **多渠道接入** | 强，覆盖广 | 中，靠 skills 扩展 | 中，强调可插拔 | ZCLAW 应保留渠道抽象层，不把单一 IM 深绑在 UI 上 |
|
||||
| **会话与消息控制平面** | 强 | 中 | 中到强 | ZCLAW 要沉淀自己的 `Conversation/Session/Run` 模型 |
|
||||
| **工具调用** | 强 | 中 | 中到强 | 工具事件流需要统一成 ZCLAW 内部协议 |
|
||||
| **技能系统** | 强，生态成熟 | 有，但偏技能驱动定制 | 可扩展，但生态尚小 | ZCLAW 需要自己的插件/技能清单与兼容层 |
|
||||
| **团队/多 Agent 协作** | 有基础能力 | 有 Agent Swarms | 有自主化定位 | ZCLAW 可将多 Agent 协作作为核心差异化方向 |
|
||||
| **工作流/定时任务** | 支持 | 支持 scheduled tasks | 支持自治流程 | ZCLAW 应将工作流从 UI 功能提升为平台能力 |
|
||||
| **桌面产品化** | 非核心主轴 | 非核心主轴 | 非核心主轴 | 这是 ZCLAW 的主战场，应继续扩大优势 |
|
||||
|
||||
### 判断
|
||||
|
||||
- 如果目标是**尽快做全功能产品**，OpenClaw 价值最高。
|
||||
- 如果目标是**单人/小团队快速安全定制**，NanoClaw 的方法更高效。
|
||||
- 如果目标是**高性能、可替换、长期独立演化**，ZeroClaw 的路线更先进。
|
||||
|
||||
ZCLAW 应把自己的主轴明确为：**产品化桌面控制面 + 中文场景 + 团队协作 + 可替换运行时**。
|
||||
|
||||
---
|
||||
|
||||
## 5.3 性能指标对比
|
||||
|
||||
### 可验证的公开信息
|
||||
|
||||
- **OpenClaw**
|
||||
- 运行依赖 `Node.js >= 22`
|
||||
- 社区规模极大，功能体系最重
|
||||
- 从 ZeroClaw 官方 benchmark 描述中可见，OpenClaw 需要额外 Node 运行时开销，内存画像明显高于 Rust 单二进制方案
|
||||
|
||||
- **ZeroClaw**
|
||||
- 官方 benchmark 示例给出：
|
||||
- release binary size 约 `8.8MB`
|
||||
- `zeroclaw --help` 峰值内存约 `3.9MB`
|
||||
- `zeroclaw status` 峰值内存约 `4.1MB`
|
||||
- 启动时延在 `0.01s ~ 0.02s` 量级
|
||||
|
||||
- **NanoClaw**
|
||||
- 官方强调单进程 orchestrator，但真实执行依赖 Docker/Apple Container
|
||||
- 因容器与 Claude Agent SDK 参与运行，整体资源画像通常不会像 Rust 单二进制那样轻
|
||||
- 其优势更多体现在“可控安全边界”而非极致性能
|
||||
|
||||
### 对 ZCLAW 的结论
|
||||
|
||||
ZCLAW 若继续强化桌面端与 7x24 运行能力，必须尽快解决两个问题：
|
||||
|
||||
- **产品层与运行时层的资源耦合**
|
||||
- **桌面壳、Agent 运行时、浏览器/工具进程之间的生命周期治理**
|
||||
|
||||
建议把性能目标分两层定义：
|
||||
|
||||
- **产品性能目标**
|
||||
- 启动可交互时间
|
||||
- 首屏渲染时间
|
||||
- 会话恢复时间
|
||||
- 事件流显示延迟
|
||||
|
||||
- **运行时性能目标**
|
||||
- 空闲内存
|
||||
- 单任务峰值内存
|
||||
- 冷启动时延
|
||||
- 工具调用平均延迟
|
||||
|
||||
---
|
||||
|
||||
## 5.4 扩展性对比
|
||||
|
||||
### OpenClaw
|
||||
|
||||
扩展生态最强，适合“接入更多能力”；但产品二开时要承担：
|
||||
|
||||
- 上游协议变化成本
|
||||
- 配置模型变化成本
|
||||
- 插件语义变化成本
|
||||
|
||||
### NanoClaw
|
||||
|
||||
扩展方式偏向“改自己的 fork”，非常适合高度个性化，但对平台型产品不够友好。
|
||||
|
||||
### ZeroClaw
|
||||
|
||||
扩展方式偏向“接口替换与模块替换”，适合做平台底座。
|
||||
|
||||
### 对 ZCLAW 的建议
|
||||
|
||||
ZCLAW 的扩展性应该分三层设计：
|
||||
|
||||
- **L1：UI Extension**
|
||||
- 面板、视图、表单、工作台插件
|
||||
|
||||
- **L2：Domain Extension**
|
||||
- AgentProfile、ToolPolicy、WorkflowStep、ChannelBinding、ApprovalRule
|
||||
|
||||
- **L3：Runtime Adapter Extension**
|
||||
- Channel Adapter
|
||||
- Model Adapter
|
||||
- Tool Adapter
|
||||
- Agent Runtime Adapter
|
||||
- Memory Adapter
|
||||
|
||||
只有做到这三层分离，ZCLAW 才能真正脱离“上游 API 变动即牵一发而动全身”的状态。
|
||||
|
||||
---
|
||||
|
||||
## 5.5 兼容性对比
|
||||
|
||||
| 维度 | OpenClaw | NanoClaw | ZeroClaw | 对 ZCLAW 的建议 |
|
||||
|------|----------|----------|----------|------------------|
|
||||
| **与现有 ZCLAW 文档/代码语义贴近度** | 高 | 中 | 中 | 短期最适合作为兼容基线 |
|
||||
| **桌面端交互兼容性** | 高 | 中 | 中 | 通过中间协议层抽象 |
|
||||
| **技能/配置迁移难度** | 低到中 | 中 | 中 | 需要建立 `ZCLAW Canonical Config` |
|
||||
| **二次开发可控性** | 中 | 高 | 高 | 中长期应逐步从“兼容”转向“主导” |
|
||||
|
||||
### 关键判断
|
||||
|
||||
下一阶段不应继续让 UI 直接理解上游协议细节，而应改为：
|
||||
|
||||
- UI 只理解 ZCLAW 自己的协议模型
|
||||
- 上游协议转换在 adapter 层完成
|
||||
|
||||
这将显著降低未来兼容多个运行时的成本。
|
||||
|
||||
---
|
||||
|
||||
## 5.6 安全与治理对比
|
||||
|
||||
### OpenClaw
|
||||
|
||||
安全模型强调：
|
||||
|
||||
- pairing
|
||||
- allowlist
|
||||
- gateway auth
|
||||
- loopback / tailscale 暴露治理
|
||||
|
||||
更适合“真实消息渠道 + 本地网关”的安全边界管理。
|
||||
|
||||
### NanoClaw
|
||||
|
||||
安全模型强调：
|
||||
|
||||
- 容器隔离
|
||||
- 显式挂载目录
|
||||
- 每组独立执行环境
|
||||
|
||||
优点是安全直观，容易让团队达成共识。
|
||||
|
||||
### ZeroClaw
|
||||
|
||||
安全模型强调：
|
||||
|
||||
- 低权限默认值
|
||||
- allowlist
|
||||
- workspace scoping
|
||||
- secret handling
|
||||
- sandbox controls
|
||||
|
||||
更接近“可治理的运行时内核”。
|
||||
|
||||
### 对 ZCLAW 的建议
|
||||
|
||||
ZCLAW 必须形成自己的安全治理分层：
|
||||
|
||||
- **产品层**：审批、权限提示、可视化审计、风险提示
|
||||
- **策略层**：路径范围、工具白名单、渠道白名单、模型策略
|
||||
- **运行时层**：容器/子进程/沙箱/凭证隔离
|
||||
|
||||
也就是说，未来 ZCLAW 不应只展示安全状态，而要**拥有自己的安全策略编排能力**。
|
||||
|
||||
---
|
||||
|
||||
## 5.7 社区支持对比
|
||||
|
||||
### OpenClaw
|
||||
|
||||
依据官方 GitHub 页面：
|
||||
|
||||
- Stars：约 `314k`
|
||||
- Forks：约 `60k`
|
||||
- Contributors：`1,217`
|
||||
- Releases：`68`
|
||||
|
||||
这是目前三者中社区最强、成熟度最高的体系。
|
||||
|
||||
### NanoClaw
|
||||
|
||||
依据官方 GitHub 页面：
|
||||
|
||||
- Stars：约 `23k`
|
||||
- Forks：约 `5.6k`
|
||||
- Releases/Tags：公开可见较少
|
||||
- 社区组织方式更偏 Discord + 个人定制 fork 模式
|
||||
|
||||
说明其讨论热度不低，但工程治理和生态标准化程度相对弱于 OpenClaw。
|
||||
|
||||
### ZeroClaw
|
||||
|
||||
依据官方 GitHub 页面：
|
||||
|
||||
- Stars：约 `27.1k`
|
||||
- Forks：约 `3.6k`
|
||||
- Releases：`46`
|
||||
- 官方站点与仓库强调持续更新和轻量架构路线
|
||||
|
||||
说明它正在形成稳定社区，但仍处于“快速成长、尚未成为默认生态中心”的阶段。
|
||||
|
||||
### 对 ZCLAW 的启示
|
||||
|
||||
如果 ZCLAW 想作为独立系统持续演化，就必须尽早做两件事：
|
||||
|
||||
- **建立自己的文档与架构标准**
|
||||
- **建立自己的插件/技能/API 兼容策略**
|
||||
|
||||
否则项目虽然代码独立，但心智上仍是“上游分支产品”。
|
||||
|
||||
---
|
||||
|
||||
## 六、综合判断：ZCLAW 应该吸收什么，不吸收什么
|
||||
|
||||
## 6.1 应该吸收的能力
|
||||
|
||||
### 来自 OpenClaw
|
||||
|
||||
- 多渠道控制平面理念
|
||||
- 会话/消息/工具事件统一流模型
|
||||
- 丰富生态与外部兼容思维
|
||||
- 产品可用性优先的设计方式
|
||||
|
||||
### 来自 NanoClaw
|
||||
|
||||
- 容器隔离优先的安全思路
|
||||
- 小而清晰的模块边界
|
||||
- “功能通过技能注入而不是不断堆框架”的治理方式
|
||||
- 面向 fork/定制的可理解性
|
||||
|
||||
### 来自 ZeroClaw
|
||||
|
||||
- trait / adapter 风格的可替换运行时设计
|
||||
- binary-first / low-overhead 的交付思想
|
||||
- 跨平台轻量部署能力
|
||||
- 更清晰的系统内核与接口边界
|
||||
|
||||
## 6.2 不建议直接照搬的部分
|
||||
|
||||
- **不建议直接把 ZCLAW 继续做成单一上游的深度 UI 壳层**
|
||||
- **不建议完全走 NanoClaw 式“所有差异化都通过 fork 改代码”的路线**
|
||||
- **不建议在当前阶段就彻底重写原有可用能力，导致交付停滞**
|
||||
|
||||
## 6.3 推荐的目标态
|
||||
|
||||
推荐目标态为：
|
||||
|
||||
> **ZCLAW = 独立产品控制面 + 统一领域模型 + 可插拔运行时内核适配层 + 中文化协作场景能力集**
|
||||
|
||||
---
|
||||
|
||||
## 七、专题头脑风暴会议方案
|
||||
|
||||
## 7.1 会议目标
|
||||
|
||||
围绕“ZCLAW 下一阶段如何独立演化”形成团队共识，输出：
|
||||
|
||||
- 下一阶段主战略
|
||||
- 目标架构形态
|
||||
- 首批优先能力清单
|
||||
- 风险清单与约束条件
|
||||
- 90 天执行路线
|
||||
|
||||
## 7.2 建议参会角色
|
||||
|
||||
- **项目负责人 / 架构负责人**
|
||||
- **桌面端负责人**
|
||||
- **前端负责人**
|
||||
- **后端/运行时负责人**
|
||||
- **插件/工具链负责人**
|
||||
- **测试/质量负责人**
|
||||
- **产品负责人**
|
||||
- **若有条件，邀请 1 名熟悉上游生态的顾问型开发者**
|
||||
|
||||
## 7.3 会前准备材料
|
||||
|
||||
要求参会者提前阅读：
|
||||
|
||||
- 本文档
|
||||
- `docs/architecture-v2.md`
|
||||
- `docs/SYSTEM_ANALYSIS.md`
|
||||
- 当前 `README.md`
|
||||
|
||||
并在会前回答三件事：
|
||||
|
||||
- 当前系统最不想再被哪个上游约束？
|
||||
- 当前系统最值得保留的核心资产是什么？
|
||||
- 下一阶段最怕失去的交付能力是什么？
|
||||
|
||||
## 7.4 会议议程（建议 2.5 小时）
|
||||
|
||||
### 第一阶段：统一认知（20 分钟）
|
||||
|
||||
- 当前项目到底是不是独立系统？
|
||||
- 当前哪些模块仍深度依赖上游？
|
||||
- 当前哪些能力已经形成 ZCLAW 自有资产？
|
||||
|
||||
### 第二阶段：三条路线讨论（40 分钟）
|
||||
|
||||
讨论三种备选路线：
|
||||
|
||||
- **路线 A：继续深度绑定 OpenClaw 生态**
|
||||
- **路线 B：向 ZeroClaw/NanoClaw 风格的轻量内核迁移**
|
||||
- **路线 C：构建 ZCLAW Core + Adapter 的独立架构**
|
||||
|
||||
每条路线必须回答：
|
||||
|
||||
- 带来什么收益
|
||||
- 会引入什么代价
|
||||
- 三个月内最可能失败在哪里
|
||||
|
||||
### 第三阶段：能力优先级排序（35 分钟）
|
||||
|
||||
把候选能力放进四象限：
|
||||
|
||||
- 高价值 / 低成本
|
||||
- 高价值 / 高成本
|
||||
- 低价值 / 低成本
|
||||
- 低价值 / 高成本
|
||||
|
||||
重点筛出下一阶段的：
|
||||
|
||||
- 必做项
|
||||
- 应做项
|
||||
- 可延后项
|
||||
- 不做项
|
||||
|
||||
### 第四阶段：目标架构与边界划分（35 分钟）
|
||||
|
||||
讨论并确认：
|
||||
|
||||
- 哪些是 ZCLAW Core
|
||||
- 哪些属于 Adapter
|
||||
- 哪些属于 Plugin/Skill Extension
|
||||
- 哪些属于可选上游兼容能力
|
||||
|
||||
### 第五阶段：决策与收尾（20 分钟）
|
||||
|
||||
现场形成：
|
||||
|
||||
- 一页战略结论
|
||||
- 一张目标架构图
|
||||
- 一份 90 天路线图
|
||||
- 一份风险与前提清单
|
||||
|
||||
## 7.5 会议产出模板
|
||||
|
||||
建议会后统一使用以下模板沉淀：
|
||||
|
||||
### 产出 A：战略结论卡
|
||||
|
||||
- 我们的主路线是什么？
|
||||
- 为什么不是另外两条路线？
|
||||
- 接下来 90 天的成败标准是什么？
|
||||
|
||||
### 产出 B：架构边界卡
|
||||
|
||||
- ZCLAW Core 模块
|
||||
- Adapter 模块
|
||||
- 可复用上游能力
|
||||
- 禁止继续耦合的区域
|
||||
|
||||
### 产出 C：优先级清单
|
||||
|
||||
- P0：必须完成
|
||||
- P1：强烈建议完成
|
||||
- P2：可延后
|
||||
- P3：明确不做
|
||||
|
||||
### 产出 D：风险台账
|
||||
|
||||
- 风险描述
|
||||
- 触发条件
|
||||
- 影响范围
|
||||
- 监测指标
|
||||
- 应对策略
|
||||
|
||||
---
|
||||
|
||||
## 八、下一阶段详细实施方案
|
||||
|
||||
## 8.1 备选技术路线
|
||||
|
||||
### 路线 A：继续以 OpenClaw 为单一主干
|
||||
|
||||
**优点**：
|
||||
|
||||
- 改造成本最低
|
||||
- 社区与生态最好借力
|
||||
- 短期交付最稳
|
||||
|
||||
**缺点**：
|
||||
|
||||
- 品牌与架构独立性不足
|
||||
- 上游变化会持续传导到产品层
|
||||
- 难以同时吸收 NanoClaw/ZeroClaw 风格能力
|
||||
|
||||
### 路线 B：转向轻量运行时路线
|
||||
|
||||
**优点**：
|
||||
|
||||
- 性能、部署、资源占用明显改善
|
||||
- 易于塑造独立技术品牌
|
||||
|
||||
**缺点**：
|
||||
|
||||
- 迁移成本高
|
||||
- 短期内功能回退风险大
|
||||
- 团队需要重构大量兼容层
|
||||
|
||||
### 路线 C：ZCLAW Core + Runtime Adapter（推荐）
|
||||
|
||||
**优点**：
|
||||
|
||||
- 兼顾短期交付与长期独立演化
|
||||
- 能吸收多个上游的能力优势
|
||||
- 将未来替换运行时的成本前置为架构治理问题，而不是产品灾难
|
||||
|
||||
**缺点**：
|
||||
|
||||
- 前期需要投入抽象层建设
|
||||
- 对架构治理和接口定义要求更高
|
||||
|
||||
## 8.2 推荐实施路线
|
||||
|
||||
推荐采用 **路线 C**，并按“三层五阶段”推进。
|
||||
|
||||
### 三层结构
|
||||
|
||||
#### 第一层：ZCLAW Product Layer
|
||||
|
||||
负责：
|
||||
|
||||
- 桌面工作台
|
||||
- 聊天与会话体验
|
||||
- Agent/Profile 管理
|
||||
- Team / Workflow / Approval / Settings
|
||||
- 统计、审计、诊断、运维视图
|
||||
|
||||
#### 第二层：ZCLAW Domain Core
|
||||
|
||||
负责：
|
||||
|
||||
- Canonical Agent Model
|
||||
- Canonical Conversation / Session / Run Model
|
||||
- Tool Event Model
|
||||
- Channel Binding Model
|
||||
- Workflow / Task / Approval Model
|
||||
- Policy / Audit / Capability Descriptor Model
|
||||
|
||||
#### 第三层：Runtime Adapter Layer
|
||||
|
||||
负责：
|
||||
|
||||
- OpenClaw Adapter
|
||||
- ZeroClaw-style Adapter
|
||||
- NanoClaw-style Sandbox Adapter
|
||||
- 后续 Native Runtime Adapter
|
||||
|
||||
---
|
||||
|
||||
## 九、分阶段执行计划
|
||||
|
||||
## 9.1 Phase 0：统一叙事与架构边界（1-2 周）
|
||||
|
||||
### 目标
|
||||
|
||||
解决当前文档、定位、模块边界混杂的问题，为后续技术演化扫清治理障碍。
|
||||
|
||||
### 关键任务
|
||||
|
||||
- 统一 README、架构文档、路线图文档口径
|
||||
- 输出一份正式 ADR：`ZCLAW 是否继续作为单一上游壳层产品`
|
||||
- 画出当前系统的真实分层图
|
||||
- 标记所有直接理解上游协议的 UI/Store/Client 模块
|
||||
|
||||
### 交付物
|
||||
|
||||
- `ZCLAW Architecture Positioning ADR`
|
||||
- 最新版系统边界图
|
||||
- 耦合点清单
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 团队对“ZCLAW 是什么”表述一致
|
||||
- 能明确说出哪些模块是 Core，哪些模块是 Adapter 候选
|
||||
|
||||
## 9.2 Phase 1：领域模型标准化（2-3 周）
|
||||
|
||||
### 目标
|
||||
|
||||
建立 ZCLAW 自己的 canonical domain model。
|
||||
|
||||
### 关键任务
|
||||
|
||||
- 定义统一的 AgentProfile schema
|
||||
- 定义统一的 Session / Conversation / Run schema
|
||||
- 定义统一的 ToolEvent / StreamEvent schema
|
||||
- 定义统一的 Workflow / Task / Approval schema
|
||||
- 统一配置模型，形成 `ZCLAW Canonical Config`
|
||||
|
||||
### 交付物
|
||||
|
||||
- `types/` 或 `schema/` 下的统一模型
|
||||
- 协议映射说明文档
|
||||
- 配置迁移与兼容规则
|
||||
|
||||
### 验收标准
|
||||
|
||||
- UI 不再直接依赖上游原始字段名
|
||||
- 任一运行时返回的数据都能映射到统一领域模型
|
||||
|
||||
## 9.3 Phase 2：Adapter 层落地（3-4 周）
|
||||
|
||||
### 目标
|
||||
|
||||
把现有直连逻辑收口到适配器层。
|
||||
|
||||
### 关键任务
|
||||
|
||||
- 建立 `RuntimeAdapter` 接口
|
||||
- 首先实现 `OpenClawAdapter`
|
||||
- 将当前 gateway client / store 中的协议特化逻辑迁出
|
||||
- 建立 adapter contract tests
|
||||
- 对连接、流式输出、工具调用、配置读写、会话管理做统一抽象
|
||||
|
||||
### 交付物
|
||||
|
||||
- `adapters/runtime/*`
|
||||
- 合同测试
|
||||
- 适配器错误码映射表
|
||||
|
||||
### 验收标准
|
||||
|
||||
- Product Layer 不再直接解析上游特有 payload
|
||||
- 新增第二个 adapter 时无需改 UI 主逻辑
|
||||
|
||||
## 9.4 Phase 3：独立平台能力增强（4-6 周）
|
||||
|
||||
### 目标
|
||||
|
||||
把 ZCLAW 的独立价值从“桌面 UI”升级为“产品控制面”。
|
||||
|
||||
### 候选优先功能
|
||||
|
||||
- Team 协作编排
|
||||
- Workflow 可视化与执行追踪
|
||||
- 审批中心
|
||||
- Agent 资产管理（角色、场景、能力画像）
|
||||
- 安全策略面板
|
||||
- 运行诊断与审计中心
|
||||
|
||||
### 交付物
|
||||
|
||||
- 可演示的独立平台特性
|
||||
- 与上游无关的用户价值闭环
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 至少 3 项核心能力可在不强调上游品牌的前提下独立展示
|
||||
|
||||
## 9.5 Phase 4：安全与运行时治理升级（3-4 周）
|
||||
|
||||
### 目标
|
||||
|
||||
吸收 NanoClaw/ZeroClaw 的安全与运行时思路。
|
||||
|
||||
### 关键任务
|
||||
|
||||
- 引入工具白名单 / 路径作用域 / 渠道白名单
|
||||
- 定义容器执行、子进程执行、宿主执行三级策略
|
||||
- 设计凭证隔离方案
|
||||
- 补充审批、审计、风险提示机制
|
||||
- 建立性能基准测试脚本
|
||||
|
||||
### 交付物
|
||||
|
||||
- `Security Policy Model`
|
||||
- `Execution Sandbox Policy`
|
||||
- 基线 benchmark 报告
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 能对每类工具执行给出明确策略归属
|
||||
- 能对外说明系统的安全边界和治理路径
|
||||
|
||||
## 9.6 Phase 5：产品化与生态化（4-6 周）
|
||||
|
||||
### 目标
|
||||
|
||||
形成真正可持续演化的产品与生态接口。
|
||||
|
||||
### 关键任务
|
||||
|
||||
- 统一插件 / 技能扩展规范
|
||||
- 建立扩展清单与安装管理
|
||||
- 输出 SDK 或最小开发指南
|
||||
- 完善打包、升级、诊断与迁移流程
|
||||
- 形成可灰度发布的版本策略
|
||||
|
||||
### 交付物
|
||||
|
||||
- 插件开发指南
|
||||
- 版本发布规范
|
||||
- 诊断与迁移工具
|
||||
|
||||
### 验收标准
|
||||
|
||||
- 第三方或内部团队可以按统一规则扩展 ZCLAW
|
||||
- 版本升级不再高度依赖人工排障
|
||||
|
||||
---
|
||||
|
||||
## 十、技术选型建议
|
||||
|
||||
## 10.1 总体原则
|
||||
|
||||
- **产品层稳定优先**：Tauri + React 的桌面产品层继续保留。
|
||||
- **领域模型先行**：先统一 schema，再做替换和迁移。
|
||||
- **兼容优先于重写**：短期不要大爆炸式重写运行时。
|
||||
- **安全能力前移**：把安全策略设计到中台层，而不是留到发布前补救。
|
||||
|
||||
## 10.2 关键技术建议
|
||||
|
||||
### 前端与桌面层
|
||||
|
||||
- 继续使用 `Tauri + React + Zustand/拆分 Store`
|
||||
- 逐步把 Store 从“协议状态容器”改成“领域状态容器”
|
||||
- 将连接状态、Agent 状态、Workflow 状态、Approval 状态解耦
|
||||
|
||||
### 协议与模型层
|
||||
|
||||
- 推荐引入统一 schema 定义方式
|
||||
- 例如 TypeScript schema + runtime validation
|
||||
- 建立内部事件总线模型
|
||||
- `run.started`
|
||||
- `run.delta`
|
||||
- `tool.started`
|
||||
- `tool.completed`
|
||||
- `approval.required`
|
||||
- `session.updated`
|
||||
|
||||
### 运行时层
|
||||
|
||||
- 短期保留现有兼容运行时
|
||||
- 中期抽象 `RuntimeAdapter`
|
||||
- 长期预留 native runtime 空间
|
||||
|
||||
### 安全层
|
||||
|
||||
- 审批模型、路径模型、工具策略模型、凭证模型分离
|
||||
- 将安全策略做成可视配置，但底层仍保留强约束默认值
|
||||
|
||||
---
|
||||
|
||||
## 十一、资源需求与组织建议
|
||||
|
||||
## 11.1 建议团队编制
|
||||
|
||||
最小建议编制：
|
||||
|
||||
- **1 名架构/技术负责人**
|
||||
- **1 名桌面前端负责人**
|
||||
- **1 名运行时/后端负责人**
|
||||
- **1 名平台/插件负责人**
|
||||
- **1 名测试/质量负责人**
|
||||
- **0.5 名产品/项目协调角色**
|
||||
|
||||
## 11.2 角色分工建议
|
||||
|
||||
- **架构负责人**
|
||||
- 定义领域模型、Adapter 边界、ADR
|
||||
|
||||
- **前端负责人**
|
||||
- 收口 UI 对上游协议的直接理解
|
||||
- 建立产品层统一状态模型
|
||||
|
||||
- **运行时负责人**
|
||||
- 适配器、流式事件、执行治理、性能基线
|
||||
|
||||
- **平台负责人**
|
||||
- 插件、配置、技能/扩展规范
|
||||
|
||||
- **测试负责人**
|
||||
- 合同测试、回归测试、性能测试、安装/升级测试
|
||||
|
||||
---
|
||||
|
||||
## 十二、时间节点建议（90 天版本）
|
||||
|
||||
| 时间段 | 目标 | 核心产出 |
|
||||
|--------|------|----------|
|
||||
| 第 1-2 周 | 统一叙事与边界 | ADR、系统边界图、耦合点清单 |
|
||||
| 第 3-5 周 | 统一领域模型 | Canonical schema、配置模型、事件模型 |
|
||||
| 第 6-9 周 | Adapter 层落地 | RuntimeAdapter、OpenClawAdapter、合同测试 |
|
||||
| 第 10-13 周 | 平台能力增强 | Workflow/Approval/Team 等独立能力强化 |
|
||||
| 第 14-16 周 | 安全与产品化 | 安全策略、基准测试、插件规范、发布策略 |
|
||||
|
||||
---
|
||||
|
||||
## 十三、预期成果
|
||||
|
||||
如果按推荐路线推进，预期可获得以下成果：
|
||||
|
||||
### 13.1 技术成果
|
||||
|
||||
- ZCLAW 不再被视为单一上游的桌面壳层
|
||||
- UI 与运行时解耦
|
||||
- 具备多运行时兼容能力
|
||||
- 形成自己的 canonical domain model
|
||||
- 安全策略、审计策略、扩展策略可治理
|
||||
|
||||
### 13.2 产品成果
|
||||
|
||||
- 对外叙事更稳定
|
||||
- 团队可围绕独立能力持续扩展
|
||||
- 可更自然地支持企业/团队协作场景
|
||||
- 后续能构建插件市场、行业模板、工作流模板等更高层能力
|
||||
|
||||
### 13.3 组织成果
|
||||
|
||||
- 减少“上游变更驱动项目节奏”的被动状态
|
||||
- 让架构决策从“修兼容”转为“做平台”
|
||||
|
||||
---
|
||||
|
||||
## 十四、风险与缓解措施
|
||||
|
||||
| 风险 | 描述 | 影响 | 缓解措施 |
|
||||
|------|------|------|----------|
|
||||
| **抽象过度** | 过早设计过多 adapter/interface | 开发变慢 | 先只抽象已验证的最小公共集 |
|
||||
| **交付中断** | 大规模重构影响现有功能 | 用户体验下降 | 采用分层替换，保持旧接口短期兼容 |
|
||||
| **文档与代码再度分离** | 叙事更新了，代码边界没跟上 | 决策失真 | 每阶段必须同步更新 ADR 与边界图 |
|
||||
| **安全治理落空** | 只做 UI，不做底层策略 | 风险不可控 | 安全策略与执行策略必须双落地 |
|
||||
| **多上游兼容失控** | 兼容目标过多导致复杂度爆炸 | 架构失稳 | 先实现单 adapter，第二个 adapter 仅做验证，不追求全量支持 |
|
||||
|
||||
---
|
||||
|
||||
## 十五、建议的近期优先动作（本周即可启动）
|
||||
|
||||
### P0
|
||||
|
||||
- 召开专题头脑风暴会议并完成路线确认
|
||||
- 输出正式 ADR：确认是否采用 `ZCLAW Core + Runtime Adapter`
|
||||
- 梳理当前直接依赖上游协议的模块列表
|
||||
|
||||
### P1
|
||||
|
||||
- 建立 `Canonical Agent / Session / Stream Event` 草案
|
||||
- 明确 `README / architecture / system analysis` 三份文档的统一口径
|
||||
- 定义 adapter 接口最小集合
|
||||
|
||||
### P2
|
||||
|
||||
- 选择一个现有关键流（例如聊天流式回复）作为 adapter 化试点
|
||||
- 建立最小合同测试样例
|
||||
|
||||
---
|
||||
|
||||
## 十六、最终建议
|
||||
|
||||
**结论很明确：**
|
||||
|
||||
ZCLAW 下一阶段最重要的工作，不是继续在某个上游上“加功能”，而是**完成从“上游定制壳层”到“独立产品平台”的架构转身**。
|
||||
|
||||
具体建议如下：
|
||||
|
||||
- **战略上**：选择 `ZCLAW Core + Runtime Adapter` 作为主路线。
|
||||
- **组织上**：通过专题头脑风暴会议统一路线与边界。
|
||||
- **实施上**：优先做叙事统一、领域模型统一、适配器收口三件事。
|
||||
- **价值上**：把 OpenClaw 的生态、NanoClaw 的隔离思路、ZeroClaw 的轻量架构，吸收到 ZCLAW 自己的产品体系中。
|
||||
|
||||
如果这一轮推进顺利，ZCLAW 将不再只是“基于某个框架的定制版”，而会成为一个**能够独立定义产品、独立定义扩展模型、独立定义演化节奏**的系统。
|
||||
|
||||
---
|
||||
|
||||
## 十七、参考依据
|
||||
|
||||
### 当前仓库文档
|
||||
|
||||
- `README.md`
|
||||
- `docs/architecture-v2.md`
|
||||
- `docs/SYSTEM_ANALYSIS.md`
|
||||
- `docs/openclaw-to-openfang-migration-brainstorm.md`
|
||||
- `docs/claw-ecosystem-deep-dive-report.md`
|
||||
|
||||
### 公开资料（本次已核验部分）
|
||||
|
||||
- OpenClaw 官方仓库：`https://github.com/openclaw/openclaw`
|
||||
- OpenClaw 官方文档入口：`https://docs.openclaw.ai`
|
||||
- NanoClaw 官方站点：`https://nanoclaw.dev/`
|
||||
- NanoClaw 官方仓库：`https://github.com/qwibitai/nanoclaw`
|
||||
- ZeroClaw 官方站点：`https://zeroclaw.bot/`
|
||||
- ZeroClaw 官方仓库：`https://github.com/zeroclaw-labs/zeroclaw`
|
||||
|
||||
> 注：部分官方文档页在本次抓取过程中存在超时，因此文中对 OpenClaw 官方文档细节的引用，优先采用其官方 GitHub README 与可稳定访问的官方摘要信息，不对未成功直读页面做超出摘要范围的延展解释。
|
||||
327
docs/archive/architecture-v2.md
Normal file
327
docs/archive/architecture-v2.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# ZCLAW v2 架构设计 — 基于 OpenClaw 定制化
|
||||
|
||||
**日期**: 2026-03-11
|
||||
**定位**: 像 AutoClaw 一样，对 OpenClaw 进行定制化封装，打造 Tauri 桌面版
|
||||
|
||||
---
|
||||
|
||||
## 一、架构总览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ ZCLAW (Tauri App) │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ React 19 + TailwindCSS │ │
|
||||
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │ │
|
||||
│ │ │ 分身Tab │ │IM频道 │ │定时任务│ │ 设置页面 │ │ │
|
||||
│ │ └────────┘ └────────┘ └────────┘ └──────────┘ │ │
|
||||
│ │ ┌──────────────────────────────────────────┐ │ │
|
||||
│ │ │ 聊天区域 + 工具调用展示 │ │ │
|
||||
│ │ └──────────────────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │ Tauri Commands │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Rust Sidecar / Bridge │ │
|
||||
│ │ • 管理 OpenClaw Gateway 子进程生命周期 │ │
|
||||
│ │ • WebSocket 客户端连接 Gateway │ │
|
||||
│ │ • 转发 Gateway 事件到前端 │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│ WebSocket (ws://127.0.0.1:18789)
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ OpenClaw Gateway (Node.js daemon) │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||||
│ │ Agent │ │ Skills │ │ Sessions │ │ Heartbeat │ │
|
||||
│ │ Runtime │ │ System │ │ Manager │ │ Engine │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||||
│ │ Tools │ │ Memory │ │ MCP │ │ Provider │ │
|
||||
│ │ (bash/ │ │ (SQLite/ │ │ Server │ │ (models) │ │
|
||||
│ │ file/ │ │ LanceDB)│ │ │ │ │ │
|
||||
│ │ browse) │ │ │ │ │ │ │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Channel Plugins (IM 渠道) │ │
|
||||
│ │ WhatsApp │ Telegram │ Discord │ Slack │ ... │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ ZCLAW Custom Plugins (我们的) │ │
|
||||
│ │ @zclaw/feishu │ @zclaw/wechat │ @zclaw/qq │ │
|
||||
│ │ @zclaw/chinese-models (GLM/Qwen/Kimi/MiniMax) │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
│ Bootstrap Files │
|
||||
│ AGENTS.md │
|
||||
│ SOUL.md │
|
||||
│ IDENTITY.md │
|
||||
│ USER.md │
|
||||
│ TOOLS.md │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、核心设计决策
|
||||
|
||||
### 1. OpenClaw 作为执行引擎
|
||||
|
||||
**不重新发明轮子**。OpenClaw 已经实现了：
|
||||
- ✅ 真实工具执行 (bash/file/browser)
|
||||
- ✅ Skills 系统 (SKILL.md + 渐进式披露)
|
||||
- ✅ MCP 协议支持
|
||||
- ✅ 心跳引擎 (Heartbeat)
|
||||
- ✅ 持久记忆 (SQLite + LanceDB)
|
||||
- ✅ Agent 运行时 (Session/Queue/Streaming)
|
||||
- ✅ 10+ IM 渠道适配器
|
||||
- ✅ 插件体系 (Channel/Tool/Memory/Provider)
|
||||
|
||||
我们只需要：**包装 + 定制 + 中文化**
|
||||
|
||||
### 2. Tauri 作为桌面壳
|
||||
|
||||
AutoClaw 用的是自己的桌面框架，QClaw 用 Electron。我们用 **Tauri 2.0** (Rust + React)：
|
||||
- 更小体积 (~10MB vs Electron ~150MB)
|
||||
- 更好性能 (Rust native)
|
||||
- 系统级集成能力
|
||||
- 管理 OpenClaw Gateway 子进程
|
||||
|
||||
### 3. 自定义插件做差异化
|
||||
|
||||
通过 OpenClaw 的 Plugin API 添加中国特色功能：
|
||||
|
||||
| 插件 | 功能 |
|
||||
|------|------|
|
||||
| `@zclaw/feishu` | 飞书 Channel Plugin |
|
||||
| `@zclaw/wechat` | 微信 Channel Plugin (通过 WeCom API 或 itchat 桥接) |
|
||||
| `@zclaw/qq` | QQ Channel Plugin |
|
||||
| `@zclaw/chinese-models` | 中文模型 Provider (智谱GLM/通义千问/Kimi/MiniMax) |
|
||||
| `@zclaw/zclaw-ui` | 自定义 Gateway RPC 方法供 Tauri UI 调用 |
|
||||
|
||||
---
|
||||
|
||||
## 三、项目结构 (重构后)
|
||||
|
||||
```
|
||||
ZClaw/
|
||||
├── desktop/ # Tauri 2.0 桌面应用
|
||||
│ ├── src-tauri/ # Rust 后端
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── main.rs # Tauri 入口
|
||||
│ │ │ ├── gateway.rs # OpenClaw Gateway 子进程管理
|
||||
│ │ │ ├── ws_client.rs # WebSocket 客户端
|
||||
│ │ │ └── commands.rs # Tauri Commands (前端调用)
|
||||
│ │ ├── Cargo.toml
|
||||
│ │ └── tauri.conf.json
|
||||
│ ├── src/ # React 前端
|
||||
│ │ ├── App.tsx
|
||||
│ │ ├── main.tsx
|
||||
│ │ ├── index.css
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── Sidebar.tsx # 左侧栏 (分身/IM/定时)
|
||||
│ │ │ ├── ChatArea.tsx # 聊天区域 + 工具调用展示
|
||||
│ │ │ ├── RightPanel.tsx # 右侧面板
|
||||
│ │ │ └── Settings/ # 设置页面 (对标 AutoClaw)
|
||||
│ │ │ ├── General.tsx # 通用设置
|
||||
│ │ │ ├── UsageStats.tsx # 用量统计
|
||||
│ │ │ ├── ModelsAPI.tsx # 模型与 API
|
||||
│ │ │ ├── MCPServices.tsx # MCP 服务管理
|
||||
│ │ │ ├── Skills.tsx # 技能管理
|
||||
│ │ │ ├── IMChannels.tsx # IM 频道管理
|
||||
│ │ │ ├── Workspace.tsx # 工作区设置
|
||||
│ │ │ ├── Privacy.tsx # 数据与隐私
|
||||
│ │ │ └── About.tsx # 关于
|
||||
│ │ ├── store/
|
||||
│ │ │ ├── chatStore.ts # 聊天状态
|
||||
│ │ │ ├── gatewayStore.ts # Gateway 连接状态
|
||||
│ │ │ └── settingsStore.ts # 设置状态
|
||||
│ │ └── lib/
|
||||
│ │ ├── gateway-client.ts # WebSocket 客户端封装
|
||||
│ │ └── protocol.ts # Gateway 协议类型定义
|
||||
│ └── package.json
|
||||
│
|
||||
├── plugins/ # ZCLAW 自定义 OpenClaw 插件
|
||||
│ ├── zclaw-feishu/ # 飞书频道插件
|
||||
│ │ ├── index.ts
|
||||
│ │ ├── plugin.json # 插件清单
|
||||
│ │ └── README.md
|
||||
│ ├── zclaw-wechat/ # 微信频道插件
|
||||
│ │ ├── index.ts
|
||||
│ │ └── plugin.json
|
||||
│ ├── zclaw-qq/ # QQ 频道插件
|
||||
│ │ ├── index.ts
|
||||
│ │ └── plugin.json
|
||||
│ ├── zclaw-chinese-models/ # 中文模型 Provider 插件
|
||||
│ │ ├── index.ts
|
||||
│ │ ├── providers/
|
||||
│ │ │ ├── zhipu.ts # 智谱 GLM
|
||||
│ │ │ ├── qwen.ts # 通义千问
|
||||
│ │ │ ├── kimi.ts # Moonshot Kimi
|
||||
│ │ │ └── minimax.ts # MiniMax
|
||||
│ │ └── plugin.json
|
||||
│ └── zclaw-ui/ # UI 扩展 RPC 插件
|
||||
│ ├── index.ts
|
||||
│ └── plugin.json
|
||||
│
|
||||
├── skills/ # ZCLAW 自定义 Skills
|
||||
│ ├── chinese-writing/ # 中文写作技能
|
||||
│ │ └── SKILL.md
|
||||
│ ├── weibo-automation/ # 微博自动化技能
|
||||
│ │ └── SKILL.md
|
||||
│ └── feishu-docs/ # 飞书文档操作技能
|
||||
│ └── SKILL.md
|
||||
│
|
||||
├── config/ # ZCLAW 默认配置
|
||||
│ ├── openclaw.default.json # 预设的 OpenClaw 配置
|
||||
│ ├── SOUL.md # 默认人格
|
||||
│ ├── AGENTS.md # 默认 Agent 指令
|
||||
│ ├── IDENTITY.md # 默认身份
|
||||
│ └── USER.md # 默认用户配置
|
||||
│
|
||||
├── scripts/ # 构建/安装脚本
|
||||
│ ├── setup.ts # 首次设置脚本
|
||||
│ ├── install-openclaw.ts # OpenClaw 安装检测
|
||||
│ └── register-plugins.ts # 注册自定义插件
|
||||
│
|
||||
├── docs/
|
||||
│ ├── architecture-v2.md # 本文件
|
||||
│ ├── deviation-analysis.md # 偏离分析报告
|
||||
│ ├── DEVELOPMENT.md
|
||||
│ └── autoclaw界面/ # AutoClaw 参考截图
|
||||
│
|
||||
├── package.json # 根项目管理
|
||||
├── tsconfig.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、与 AutoClaw 功能对标
|
||||
|
||||
### AutoClaw 设置页面 → ZCLAW 实现方式
|
||||
|
||||
| AutoClaw 功能 | ZCLAW 实现 |
|
||||
|---|---|
|
||||
| **通用** (账号/主题/开机启动/工具调用显示) | Tauri 窗口设置 + Gateway config |
|
||||
| **用量统计** (会话/消息/Token 按模型分) | 读取 OpenClaw sessions JSONL + 统计 |
|
||||
| **积分详情** | 自定义积分系统 (可选) |
|
||||
| **模型与API** (内置+自定义模型+Gateway URL) | `openclaw config` + Provider Plugin |
|
||||
| **MCP 服务** (File System/Web Fetch/+添加) | 读取 OpenClaw MCP 配置 + UI 管理 |
|
||||
| **技能** (SKILL.md 管理/额外目录) | 读取 Skills 目录 + UI 管理 |
|
||||
| **IM 频道** (添加/管理/快速添加飞书) | Channel Plugin 配置 UI |
|
||||
| **工作区** (项目目录/文件限制/上下文保存/文件监听) | `agents.defaults.workspace` + sandbox 配置 |
|
||||
| **数据与隐私** (本地路径/优化计划) | OpenClaw 数据目录 + 隐私配置 |
|
||||
| **提交反馈** | 自定义反馈表单 |
|
||||
| **关于** (版本/更新) | 显示 ZCLAW + OpenClaw 版本 |
|
||||
|
||||
### AutoClaw 主界面 → ZCLAW 对标
|
||||
|
||||
| 功能 | 实现 |
|
||||
|---|---|
|
||||
| **左侧 - 分身 Tab** | 通过 `agents.list` 配置管理多个 Agent |
|
||||
| **左侧 - IM 频道 Tab** | 通过 `channels.*` 配置显示已连接频道 |
|
||||
| **左侧 - 定时任务 Tab** | 通过 heartbeat + cron 事件显示 |
|
||||
| **中间 - 聊天区域** | WebSocket 订阅 `agent` stream 事件 |
|
||||
| **中间 - 模型选择器** | 通过 `agents.defaults.models` 配置 |
|
||||
| **右侧 - 代码/文件面板** | 显示 Agent 工具调用结果 (file/bash output) |
|
||||
| **快速配置弹窗** | 修改 IDENTITY.md + SOUL.md + USER.md |
|
||||
|
||||
---
|
||||
|
||||
## 五、WebSocket 通信协议
|
||||
|
||||
ZCLAW Tauri 客户端通过标准 OpenClaw Gateway 协议通信：
|
||||
|
||||
### 连接握手
|
||||
```json
|
||||
// 1. 服务器发送 challenge
|
||||
{"type": "event", "event": "connect.challenge", "payload": {"nonce": "...", "ts": 1737264000000}}
|
||||
|
||||
// 2. 客户端发送 connect
|
||||
{"type": "req", "id": "1", "method": "connect", "params": {
|
||||
"minProtocol": 3, "maxProtocol": 3,
|
||||
"client": {"id": "zclaw-tauri", "version": "0.1.0", "platform": "windows", "mode": "operator"},
|
||||
"role": "operator",
|
||||
"scopes": ["operator.read", "operator.write"],
|
||||
"auth": {"token": "..."}
|
||||
}}
|
||||
|
||||
// 3. 服务器回复 hello-ok
|
||||
{"type": "res", "id": "1", "ok": true, "payload": {"type": "hello-ok", "protocol": 3}}
|
||||
```
|
||||
|
||||
### 核心 RPC 方法
|
||||
```
|
||||
agent → 发送消息给 Agent (触发 Agent Loop)
|
||||
agent.wait → 等待 Agent 运行完成
|
||||
send → 通过 IM 频道发送消息
|
||||
health → 健康检查
|
||||
status → 获取 Gateway 状态
|
||||
system-presence → 系统状态
|
||||
```
|
||||
|
||||
### 事件订阅
|
||||
```
|
||||
agent → Agent 流式输出 (assistant/tool/lifecycle)
|
||||
chat → 聊天消息
|
||||
presence → 在线状态
|
||||
health → 健康状态
|
||||
heartbeat → 心跳
|
||||
cron → 定时任务
|
||||
tick → 定时心跳
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、开发分期
|
||||
|
||||
### Phase 1: 基础连通 (当前优先)
|
||||
1. 安装 OpenClaw 并验证 Gateway 可运行
|
||||
2. 创建 Tauri 项目结构 (保留现有 desktop/)
|
||||
3. 实现 Gateway 子进程管理 (Rust sidecar)
|
||||
4. 实现 WebSocket 客户端连接
|
||||
5. 前端显示 Gateway 状态 + 基础聊天
|
||||
|
||||
### Phase 2: 自定义插件
|
||||
1. 实现 `@zclaw/chinese-models` Provider Plugin (智谱GLM/Qwen/Kimi)
|
||||
2. 实现 `@zclaw/feishu` Channel Plugin
|
||||
3. 注册插件到 OpenClaw Gateway
|
||||
|
||||
### Phase 3: 完整 UI
|
||||
1. 实现设置页面体系 (对标 AutoClaw 10 个页面)
|
||||
2. 实现分身管理 UI
|
||||
3. 实现 Skills 管理 UI
|
||||
4. 实现 MCP 服务管理 UI
|
||||
|
||||
### Phase 4: 高级功能
|
||||
1. 微信/QQ Channel Plugin
|
||||
2. 自定义 Skills 开发
|
||||
3. 工作区管理
|
||||
4. 打包发布
|
||||
|
||||
---
|
||||
|
||||
## 七、与之前代码的关系
|
||||
|
||||
### 可复用
|
||||
- `desktop/` 前端组件 (需大幅扩展)
|
||||
- `plugins/zclaw-chinese-models/` 可复用之前的 AI Provider 代码 (zhipu.ts/openai.ts)
|
||||
- `plugins/zclaw-feishu/` 可复用之前的飞书适配器代码
|
||||
|
||||
### 废弃
|
||||
- `src/core/remote-execution/` → OpenClaw 自带工具执行
|
||||
- `src/core/task-orchestration/` → OpenClaw Agent Loop 自带
|
||||
- `src/core/multi-agent/` → 改为 OpenClaw agents.list 多 Agent
|
||||
- `src/core/memory/` → OpenClaw Memory Plugin 自带
|
||||
- `src/core/proactive/` → OpenClaw Heartbeat Engine 自带
|
||||
- `src/im/gateway.ts` → OpenClaw Channel 系统自带
|
||||
- `src/app.ts` → OpenClaw Gateway 就是 app
|
||||
- `src/api/` → 通过 WebSocket + Tauri Commands 替代
|
||||
- `src/db/` → OpenClaw 自带 SQLite
|
||||
- `src/config/` → OpenClaw 配置系统替代
|
||||
|
||||
---
|
||||
|
||||
*本架构设计基于对 OpenClaw 官方文档 (docs.openclaw.ai) 的深度研究，
|
||||
参考 AutoClaw v0.2.12 的 13 张界面截图进行功能对标。*
|
||||
1197
docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md
Normal file
1197
docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
196
docs/archive/new-session-prompt-openfang-migration.md
Normal file
196
docs/archive/new-session-prompt-openfang-migration.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# ZClaw OpenFang 迁移 - 新会话提示词
|
||||
|
||||
> **更新日期**: 2026-03-13 (Session 4)
|
||||
> **状态**: Phase 1-7 基本完成
|
||||
|
||||
---
|
||||
|
||||
## 当前状态
|
||||
|
||||
### ✅ 已完成
|
||||
|
||||
1. **OpenFang 打包架构** (Phase 1-2) ✅
|
||||
- 创建 `prepare-openfang-runtime.mjs` 跨平台下载脚本
|
||||
- 更新 Rust `lib.rs` 支持二进制运行时
|
||||
- 配置 Tauri 打包 `resources/openfang-runtime/`
|
||||
- 验证构建成功
|
||||
|
||||
2. **OpenFang 特性 UI 组件** ✅
|
||||
- `HandsPanel.tsx` - Hands 管理界面 (含审批流程)
|
||||
- `WorkflowList.tsx` - 工作流列表
|
||||
- `SecurityStatus.tsx` - 16层安全状态
|
||||
- `TriggersPanel.tsx` - 触发器管理
|
||||
- `AuditLogsPanel.tsx` - 审计日志 (已集成到 RightPanel)
|
||||
|
||||
3. **状态管理更新** ✅
|
||||
- `gatewayStore.ts` 添加 OpenFang 类型定义
|
||||
- `gateway-config.ts` 配置管理
|
||||
- `loadHands()`, `loadWorkflows()`, `loadTriggers()`, `loadSecurityStatus()` 方法
|
||||
- `approveHand()`, `cancelHand()`, `cancelWorkflow()` 方法
|
||||
- `isLoading` 状态管理
|
||||
- `connect()` 后自动加载 OpenFang 数据
|
||||
|
||||
4. **Gateway Client** ✅
|
||||
- `gateway-client.ts` 已适配 OpenFang 协议
|
||||
- WebSocket 连接到 `ws://127.0.0.1:4200/ws`
|
||||
- REST API 调用 `/api/*` 端点
|
||||
- Ed25519 设备认证 + JWT
|
||||
- Hand 审批/取消 API
|
||||
|
||||
5. **后端切换功能** ✅
|
||||
- `Settings/General.tsx` 添加后端类型选择器
|
||||
- 支持 OpenClaw (TypeScript) 和 OpenFang (Rust) 切换
|
||||
- localStorage 持久化 `zclaw-backend`
|
||||
|
||||
6. **Tauri 后端完善** (Phase 5) ✅
|
||||
- `openfang_process_list` - 列出 OpenFang 进程
|
||||
- `openfang_process_logs` - 获取进程日志
|
||||
- `openfang_version` - 获取版本信息
|
||||
- 前端 `tauri-gateway.ts` 适配
|
||||
|
||||
7. **Hand 审批流程** (Phase 6.1) ✅
|
||||
- `approveHand()` / `cancelHand()` API
|
||||
- `HandsPanel.tsx` 审批 UI (批准/拒绝按钮)
|
||||
- 运行中取消执行功能
|
||||
|
||||
8. **测试基础设施** (Phase 7) ✅
|
||||
- `tests/fixtures/openfang-mock-server.ts` - 完整 Mock Server
|
||||
- 支持 REST API 和 WebSocket 模拟
|
||||
- `tests/desktop/integration/openfang-api.test.ts` - 34 个集成测试
|
||||
- 所有 63 个桌面端测试全部通过
|
||||
|
||||
9. **构建脚本修复** ✅
|
||||
- `tauri-build-bundled.mjs` 更新为使用 `prepare-openfang-runtime.mjs`
|
||||
|
||||
### 📋 可选后续工作
|
||||
|
||||
| Phase | 任务 | 状态 |
|
||||
|-------|------|------|
|
||||
| Phase 7.3 | E2E 测试 (Playwright) | 可选 |
|
||||
| - | CSP 配置 (生产环境) | 可选 |
|
||||
| - | chinese-writing 插件迁移 | 待定 |
|
||||
|
||||
---
|
||||
|
||||
## 关键架构
|
||||
|
||||
### 打包结构
|
||||
|
||||
```
|
||||
ZClaw-Desktop-Setup.exe
|
||||
├── desktop.exe # Tauri 应用
|
||||
└── resources/
|
||||
└── openfang-runtime/
|
||||
├── openfang.exe # 57MB OpenFang 二进制
|
||||
├── openfang.cmd # Windows 启动脚本
|
||||
├── openfang.sh # Unix 启动脚本
|
||||
└── runtime-manifest.json
|
||||
```
|
||||
|
||||
### 运行时解析优先级
|
||||
|
||||
1. `ZCLAW_OPENFANG_BIN` 环境变量
|
||||
2. 打包的 `openfang-runtime/` 目录
|
||||
3. 系统 PATH (`openfang`)
|
||||
|
||||
### 端点和协议
|
||||
|
||||
| 项目 | OpenClaw (旧) | OpenFang (新) |
|
||||
|------|---------------|---------------|
|
||||
| WebSocket | `ws://127.0.0.1:18789` | `ws://127.0.0.1:4200/ws` |
|
||||
| REST API | 无 | `http://127.0.0.1:4200/api` |
|
||||
| 配置格式 | JSON | TOML |
|
||||
| 配置目录 | `~/.openclaw/` | `~/.openfang/` |
|
||||
|
||||
---
|
||||
|
||||
## 测试
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 所有桌面端测试 (63 个)
|
||||
pnpm vitest run tests/desktop/
|
||||
|
||||
# 仅集成测试 (34 个)
|
||||
pnpm vitest run tests/desktop/integration/
|
||||
|
||||
# 单元测试
|
||||
pnpm vitest run tests/desktop/chatStore.test.ts
|
||||
pnpm vitest run tests/desktop/gatewayStore.test.ts
|
||||
```
|
||||
|
||||
### Mock Server
|
||||
|
||||
Mock Server (`tests/fixtures/openfang-mock-server.ts`) 提供：
|
||||
|
||||
- **REST API**: 所有 `/api/*` 端点
|
||||
- **WebSocket**: `/ws` 路径握手
|
||||
- **可配置数据**: Hands, Workflows, Triggers, Agents, Security Layers
|
||||
- **审计日志**: 可添加自定义日志条目
|
||||
|
||||
---
|
||||
|
||||
## 下一步工作
|
||||
|
||||
### 优先级 1: 真实 OpenFang 集成测试
|
||||
|
||||
```bash
|
||||
# 1. 启动 OpenFang
|
||||
cd desktop/src-tauri/resources/openfang-runtime
|
||||
./openfang.exe gateway start
|
||||
|
||||
# 2. 运行 Tauri 开发模式
|
||||
pnpm tauri:dev
|
||||
|
||||
# 3. 验证连接
|
||||
# - WebSocket 连接到 4200 端口
|
||||
# - 消息发送和接收
|
||||
# - Hands/Workflow 功能
|
||||
```
|
||||
|
||||
### 优先级 2: 插件迁移 (chinese-writing)
|
||||
|
||||
将 `plugins/zclaw-chinese-models` 中的模型配置迁移到 OpenFang TOML 格式。
|
||||
|
||||
参考: `config/chinese-providers.toml`
|
||||
|
||||
---
|
||||
|
||||
## 构建命令
|
||||
|
||||
```bash
|
||||
# 开发
|
||||
pnpm tauri:dev
|
||||
|
||||
# 生产构建 (自动下载 OpenFang)
|
||||
pnpm tauri:build:bundled
|
||||
|
||||
# 手动准备运行时
|
||||
pnpm prepare:openfang-runtime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- 迁移计划: `plans/immutable-imagining-naur.md`
|
||||
- OpenFang 技术参考: `docs/openfang-technical-reference.md`
|
||||
- 运行时 README: `desktop/src-tauri/resources/openfang-runtime/README.md`
|
||||
- OpenFang GitHub: https://github.com/RightNow-AI/openfang
|
||||
|
||||
---
|
||||
|
||||
## 新会话提示词模板
|
||||
|
||||
```
|
||||
我正在开发 ZClaw Desktop，一个从 OpenClaw 迁移到 OpenFang 的 AI Agent 桌面客户端。
|
||||
|
||||
当前状态:
|
||||
- Phase 1-7 基本完成
|
||||
- 63 个测试全部通过
|
||||
- Mock Server 集成测试可用
|
||||
|
||||
请阅读 docs/new-session-prompt-openfang-migration.md 了解详细上下文，然后继续以下工作:
|
||||
[具体任务]
|
||||
```
|
||||
532
docs/archive/openclaw-to-openfang-migration-brainstorm.md
Normal file
532
docs/archive/openclaw-to-openfang-migration-brainstorm.md
Normal file
@@ -0,0 +1,532 @@
|
||||
# ZClaw: 从 OpenClaw 切换到 OpenFang 头脑风暴分析
|
||||
|
||||
> **分析日期**：2026-03-13
|
||||
> **目标**：评估 ZClaw 从 OpenClaw 切换到 OpenFang 的可行性、成本和收益
|
||||
|
||||
---
|
||||
|
||||
## 一、核心架构对比
|
||||
|
||||
### 1.1 当前 ZClaw 架构 (基于 OpenClaw)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ZClaw Desktop (当前) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ React 19 │ │ Zustand │ │ TypeScript │ │
|
||||
│ │ UI Layer │───►│ Store │───►│ Gateway │ │
|
||||
│ │ │ │ │ │ Client │ │
|
||||
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ OpenClaw Gateway (Node.js) │ │
|
||||
│ │ ws://127.0.0.1:18789 │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │Sessions │ │Channels │ │ Config │ │ Cron │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Plugins/Skills (TypeScript) │ │
|
||||
│ │ • zclaw-chinese-models • zclaw-feishu • zclaw-ui │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
技术栈：Tauri 2.0 + React 19 + TypeScript + Node.js Gateway
|
||||
内存占用：>1GB (含 Node.js)
|
||||
启动时间：2-5 秒
|
||||
```
|
||||
|
||||
### 1.2 切换后架构 (基于 OpenFang)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ZClaw Desktop (OpenFang) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ React 19 │ │ Zustand │ │ TypeScript │ │
|
||||
│ │ UI Layer │───►│ Store │───►│ Gateway │ │
|
||||
│ │ │ │ │ │ Client │ │
|
||||
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ OpenFang Kernel (Rust) │ │
|
||||
│ │ ws://127.0.0.1:???? │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ Runtime │ │ Hands │ │ 16-Layer│ │ 40 │ │ │
|
||||
│ │ │ Engine │ │ System │ │ Security│ │ Channels│ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Skills + Hands (Rust/WASM) │ │
|
||||
│ │ • 60 内置技能 • 7 个 Hands • MCP 模板 • WASM 沙箱 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
技术栈：Tauri 2.0 + React 19 + TypeScript + Rust Gateway
|
||||
内存占用：~40MB
|
||||
启动时间：180ms
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、功能维度分析
|
||||
|
||||
### 2.1 功能增强
|
||||
|
||||
| 功能 | OpenClaw | OpenFang | 影响 |
|
||||
|------|----------|----------|------|
|
||||
| **Hands 自主系统** | ❌ 无 | ✅ 7 个 Hands | 🔥 **重大增强**：可提供自主工作流 |
|
||||
| **Workflow 引擎** | ❌ 基础 Cron | ✅ 完整 Workflow | 🔥 **重大增强**：多步骤编排 |
|
||||
| **通道支持** | 20+ | 40 | ✅ **增强**：覆盖更广 |
|
||||
| **LLM 提供商** | 50+ | 27 | ⚠️ **略减**：但覆盖主流 |
|
||||
| **技能生态** | 13,729+ | 60 内置 + 兼容 | ⚠️ **需要迁移**：生态差异 |
|
||||
| **Trigger 引擎** | ❌ 基础 | ✅ 9 种事件 | 🔥 **重大增强**：事件驱动 |
|
||||
|
||||
### 2.2 Hands 系统对 ZClaw 的价值
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OpenFang Hands 对 ZClaw 的潜在价值 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Clip Hand - 视频处理 │ │
|
||||
│ │ • 用户发送 YouTube 链接 → 自动生成竖屏短视频 │ │
|
||||
│ │ • 自动添加字幕和 AI 配音 │ │
|
||||
│ │ • 直接发布到社交媒体 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Lead Hand - 销售线索 │ │
|
||||
│ │ • 每日自动发现潜在客户 │ │
|
||||
│ │ • 生成评分报告 │ │
|
||||
│ │ • 适合 B2B 用户 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Researcher Hand - 深度研究 │ │
|
||||
│ │ • 跨源交叉验证 │ │
|
||||
│ │ • CRAAP 可信度评估 │ │
|
||||
│ │ • 适合知识工作者 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Browser Hand - 网页自动化 │ │
|
||||
│ │ • 自动填表、点击、导航 │ │
|
||||
│ │ • 多步骤工作流 │ │
|
||||
│ │ • 审批门控（安全） │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
💡 用户价值：从"被动响应"到"主动工作"的体验升级
|
||||
```
|
||||
|
||||
### 2.3 功能风险
|
||||
|
||||
| 风险 | 描述 | 缓解措施 |
|
||||
|------|------|----------|
|
||||
| **技能迁移** | 现有 zclaw-* 插件需要重写 | OpenFang 提供迁移工具，支持 SKILL.md 格式 |
|
||||
| **API 差异** | Gateway 协议可能不同 | 需要适配新的 WebSocket 协议 |
|
||||
| **生态不成熟** | OpenFang 社区较小 | 可考虑贡献代码，建立合作关系 |
|
||||
|
||||
---
|
||||
|
||||
## 三、安全性维度分析
|
||||
|
||||
### 3.1 安全架构对比
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 安全架构对比 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ OpenClaw (3 层) OpenFang (16 层) │
|
||||
│ ───────────── ──────────────── │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ 1. 应用级权限 │ │ 1. WASM 双重计量沙箱 │ │
|
||||
│ │ 2. DM 配对 │ │ 2. Merkle 哈希链审计 │ │
|
||||
│ │ 3. 沙箱隔离 │ │ 3. 信息流污染追踪 │ │
|
||||
│ └─────────────────┘ │ 4. Ed25519 签名代理清单 │ │
|
||||
│ │ 5. SSRF 防护 │ │
|
||||
│ │ 6. 机密零化 │ │
|
||||
│ │ 7. OFP 互认证 │ │
|
||||
│ │ 8. 能力门控 │ │
|
||||
│ │ 9. 安全头 │ │
|
||||
│ │ 10. 健康端点编辑 │ │
|
||||
│ │ 11. 子进程沙箱 │ │
|
||||
│ │ 12. 提示注入扫描器 │ │
|
||||
│ │ 13. 循环守卫 │ │
|
||||
│ │ 14. 会话修复 │ │
|
||||
│ │ 15. 路径遍历防护 │ │
|
||||
│ │ 16. GCRA 速率限制 │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.2 安全性对用户体验的影响
|
||||
|
||||
| 安全特性 | 用户体验影响 | 评分 |
|
||||
|----------|-------------|------|
|
||||
| **WASM 沙箱** | 透明，用户无感知 | ✅ 正面 |
|
||||
| **Merkle 审计链** | 可提供操作历史查看 | ✅ 正面 |
|
||||
| **提示注入扫描** | 可能误报，需要用户确认 | ⚠️ 中性 |
|
||||
| **能力门控 (RBAC)** | 首次使用需授权 | ⚠️ 轻微负面 |
|
||||
| **循环守卫** | 自动断路，保护用户 | ✅ 正面 |
|
||||
| **速率限制** | 高频使用时可能触发 | ⚠️ 轻微负面 |
|
||||
|
||||
### 3.3 安全性营销价值
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 安全性作为产品卖点 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ "基于 OpenFang 的 ZClaw 提供： │
|
||||
│ │
|
||||
│ ✅ 16 层纵深防御 - 金融级安全保障 │
|
||||
│ ✅ WASM 沙箱隔离 - 代码执行安全可控 │
|
||||
│ ✅ Merkle 审计链 - 所有操作可追溯 │
|
||||
│ ✅ Ed25519 签名 - 设备身份验证 │
|
||||
│ ✅ 信息流追踪 - 防止数据泄露 │
|
||||
│ │
|
||||
│ 适合：企业用户、金融行业、医疗健康、政府机构 │
|
||||
│ " │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
💡 安全性可成为企业版/专业版的差异化卖点
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、性能维度分析
|
||||
|
||||
### 4.1 性能指标对比
|
||||
|
||||
| 指标 | OpenClaw | OpenFang | 提升幅度 |
|
||||
|------|----------|----------|----------|
|
||||
| **冷启动时间** | 5.98s | 180ms | **33x 更快** |
|
||||
| **空闲内存** | 394MB | 40MB | **90% 更少** |
|
||||
| **安装大小** | 500MB | 32MB | **94% 更小** |
|
||||
| **响应延迟** | ~100ms | ~10ms | **10x 更快** |
|
||||
|
||||
### 4.2 性能对用户体验的影响
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 性能提升带来的 UX 改善 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 启动体验： │
|
||||
│ ───────── │
|
||||
│ OpenClaw: 点击图标 → 等待 6 秒 → 可用 │
|
||||
│ OpenFang: 点击图标 → 等待 0.2 秒 → 可用 ⚡ "秒开"体验 │
|
||||
│ │
|
||||
│ 运行时体验： │
|
||||
│ ────────── │
|
||||
│ OpenClaw: 后台占用 400MB+ 内存，多任务时卡顿 │
|
||||
│ OpenFang: 后台占用 40MB 内存，几乎无感 💪 轻盈 │
|
||||
│ │
|
||||
│ 安装体验： │
|
||||
│ ───────── │
|
||||
│ OpenClaw: 下载 500MB，安装 2-3 分钟 │
|
||||
│ OpenFang: 下载 32MB，安装 10 秒 🚀 快速部署 │
|
||||
│ │
|
||||
│ 低配设备： │
|
||||
│ ───────── │
|
||||
│ OpenClaw: 8GB 以下内存设备体验差 │
|
||||
│ OpenFang: 可在 4GB 内存设备流畅运行 📱 覆盖更广 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
💡 性能提升 = 更好的首次印象 + 更广的设备覆盖 + 更低的用户流失
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、开发成本分析
|
||||
|
||||
### 5.1 迁移工作量估算
|
||||
|
||||
| 模块 | 工作内容 | 工作量 | 风险 |
|
||||
|------|----------|--------|------|
|
||||
| **GatewayClient** | 适配 OpenFang WebSocket 协议 | 3-5 天 | 中 |
|
||||
| **插件迁移** | 重写 zclaw-* 插件 | 10-15 天 | 高 |
|
||||
| **技能迁移** | 转换 SKILL.md 格式 | 2-3 天 | 低 |
|
||||
| **UI 适配** | 新增 Hands/Workflow 管理界面 | 5-7 天 | 低 |
|
||||
| **测试** | 全量回归测试 | 5-7 天 | 中 |
|
||||
| **文档更新** | 更新用户/开发文档 | 2-3 天 | 低 |
|
||||
|
||||
**总计**：27-40 天（约 1.5-2 个月）
|
||||
|
||||
### 5.2 技术栈变化
|
||||
|
||||
| 方面 | 变化 | 影响 |
|
||||
|------|------|------|
|
||||
| **后端语言** | TypeScript → Rust | 需要学习 Rust 或依赖社区 |
|
||||
| **插件开发** | TypeScript → Rust/WASM | 插件开发门槛提高 |
|
||||
| **调试工具** | Node.js 调试 → Rust 调试 | 调试方式变化 |
|
||||
| **构建流程** | npm/pnpm → Cargo + npm | CI/CD 需要调整 |
|
||||
|
||||
### 5.3 风险缓解
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 迁移风险缓解策略 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 渐进式迁移 │
|
||||
│ ───────────── │
|
||||
│ • 先保持 OpenClaw 版本维护 │
|
||||
│ • 并行开发 OpenFang 版本 │
|
||||
│ • 双版本并行运行一段时间 │
|
||||
│ │
|
||||
│ 2. 兼容层设计 │
|
||||
│ ───────────── │
|
||||
│ • 实现 OpenClaw 协议适配器 │
|
||||
│ • 现有插件无需修改即可运行 │
|
||||
│ • 逐步迁移到原生 OpenFang API │
|
||||
│ │
|
||||
│ 3. 社区合作 │
|
||||
│ ───────────── │
|
||||
│ • 与 OpenFang 团队建立联系 │
|
||||
│ • 贡献代码换取优先支持 │
|
||||
│ • 参与路线图讨论 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、用户使用体验分析
|
||||
|
||||
### 6.1 用户体验变化矩阵
|
||||
|
||||
| 维度 | 变化 | 用户感知 | 重要性 |
|
||||
|------|------|----------|--------|
|
||||
| **启动速度** | 6s → 0.2s | ⭐⭐⭐⭐⭐ 极大提升 | 高 |
|
||||
| **内存占用** | 400MB → 40MB | ⭐⭐⭐⭐ 显著提升 | 中 |
|
||||
| **安装包大小** | 500MB → 32MB | ⭐⭐⭐⭐ 显著提升 | 中 |
|
||||
| **功能丰富度** | 基础 → +Hands | ⭐⭐⭐⭐⭐ 极大提升 | 高 |
|
||||
| **安全感** | 3 层 → 16 层 | ⭐⭐⭐⭐ 提升 | 中 |
|
||||
| **学习曲线** | 相似 | ⭐⭐⭐ 无变化 | - |
|
||||
| **稳定性** | 相似或更好 | ⭐⭐⭐⭐ 可能提升 | 高 |
|
||||
|
||||
### 6.2 新功能带来的用户体验升级
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OpenFang 带来的 UX 升级 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 场景 1：内容创作者 │
|
||||
│ ────────────────── │
|
||||
│ Before: 手动下载视频 → 剪辑 → 添加字幕 → 上传 │
|
||||
│ After: 发送 YouTube 链接 → Clip Hand 自动完成全流程 │
|
||||
│ 价值：节省 90% 时间 │
|
||||
│ │
|
||||
│ 场景 2：销售人员 │
|
||||
│ ──────────────── │
|
||||
│ Before: 手动搜索潜在客户 → 整理信息 → 评分 │
|
||||
│ After: Lead Hand 每日自动发现 → 生成报告 → 推送通知 │
|
||||
│ 价值：被动获客，效率倍增 │
|
||||
│ │
|
||||
│ 场景 3：研究人员 │
|
||||
│ ──────────────── │
|
||||
│ Before: 手动搜索 → 多源对比 → 整理引用 │
|
||||
│ After: Researcher Hand 自动研究 → CRAAP 评估 → APA 引用 │
|
||||
│ 价值：研究效率提升 5x │
|
||||
│ │
|
||||
│ 场景 4：日常办公 │
|
||||
│ ──────────────── │
|
||||
│ Before: 手动填表 → 点击按钮 → 重复操作 │
|
||||
│ After: Browser Hand 自动化工作流 → 审批确认 → 完成 │
|
||||
│ 价值：从重复劳动中解放 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.3 潜在负面体验
|
||||
|
||||
| 负面因素 | 描述 | 缓解措施 |
|
||||
|----------|------|----------|
|
||||
| **首次授权繁琐** | RBAC 需要用户确认权限 | 设计友好的授权引导流程 |
|
||||
| **速率限制** | 高频使用可能触发限制 | 可配置的速率限制策略 |
|
||||
| **功能缺失** | 部分技能尚未迁移 | 明确标注"即将推出" |
|
||||
| **学习成本** | Hands/Workflow 新概念 | 提供交互式教程 |
|
||||
|
||||
---
|
||||
|
||||
## 七、商业化影响分析
|
||||
|
||||
### 7.1 产品定位升级
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 产品定位变化 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 当前 (OpenClaw)： │
|
||||
│ ───────────────── │
|
||||
│ "基于 OpenClaw 的 AI Agent 桌面客户端" │
|
||||
│ 定位：个人 AI 助手 │
|
||||
│ 差异化：桌面客户端、中文优化 │
|
||||
│ │
|
||||
│ 升级后 (OpenFang)： │
|
||||
│ ────────────────── │
|
||||
│ "基于 OpenFang 的生产级 AI Agent 桌面客户端" │
|
||||
│ 定位：生产力工具 / 企业级助手 │
|
||||
│ 差异化： │
|
||||
│ • 16 层金融级安全 │
|
||||
│ • Hands 自主工作流 │
|
||||
│ • 33x 更快启动 │
|
||||
│ • 90% 更低资源占用 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 7.2 定价策略影响
|
||||
|
||||
| 版本 | 当前定价建议 | 升级后定价建议 | 理由 |
|
||||
|------|-------------|---------------|------|
|
||||
| **免费版** | 基础功能 | 基础功能 + 1 个 Hand | 吸引用户体验 |
|
||||
| **专业版** | ¥99/月 | ¥149/月 | Hands 带来价值提升 |
|
||||
| **企业版** | ¥299/月 | ¥499/月 | 安全合规价值 |
|
||||
| **定制版** | 按需 | 按需 + Hands 定制 | 新增服务收入 |
|
||||
|
||||
### 7.3 目标客户变化
|
||||
|
||||
| 客户群 | 当前匹配度 | 升级后匹配度 | 变化原因 |
|
||||
|--------|-----------|-------------|----------|
|
||||
| **个人用户** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 功能更强但可能过于复杂 |
|
||||
| **内容创作者** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Clip Hand 完美匹配 |
|
||||
| **销售人员** | ⭐⭐ | ⭐⭐⭐⭐⭐ | Lead Hand 完美匹配 |
|
||||
| **研究人员** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Researcher Hand 完美匹配 |
|
||||
| **企业用户** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 16 层安全 + 审计 |
|
||||
| **金融/医疗** | ⭐⭐ | ⭐⭐⭐⭐⭐ | 合规 + 安全 |
|
||||
|
||||
---
|
||||
|
||||
## 八、决策建议
|
||||
|
||||
### 8.1 SWOT 分析
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SWOT 分析 │
|
||||
├──────────────────────┬──────────────────────────────────────────┤
|
||||
│ 优势 (S) │ 劣势 (W) │
|
||||
├──────────────────────┼──────────────────────────────────────────┤
|
||||
│ • 33x 启动速度提升 │ • 迁移成本 1.5-2 个月 │
|
||||
│ • 90% 内存减少 │ • 插件需要重写 │
|
||||
│ • 16 层安全防护 │ • 社区生态较小 │
|
||||
│ • Hands 自主系统 │ • Rust 开发门槛 │
|
||||
│ • Workflow 引擎 │ • API 需要适配 │
|
||||
│ • 40 通道支持 │ │
|
||||
├──────────────────────┼──────────────────────────────────────────┤
|
||||
│ 机会 (O) │ 威胁 (T) │
|
||||
├──────────────────────┼──────────────────────────────────────────┤
|
||||
│ • 企业市场拓展 │ • OpenFang 项目不够成熟 │
|
||||
│ • 金融/医疗行业 │ • 社区支持可能不足 │
|
||||
│ • 内容创作者市场 │ • 技术路线变化风险 │
|
||||
│ • 差异化竞争 │ • 用户学习成本 │
|
||||
│ • 定价提升空间 │ │
|
||||
└──────────────────────┴──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 8.2 推荐策略
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 推荐策略：渐进式双轨 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 阶段 1：调研验证 (1-2 周) │
|
||||
│ ──────────────────────── │
|
||||
│ • 深入研究 OpenFang API 文档 │
|
||||
│ • 评估 GatewayClient 适配工作量 │
|
||||
│ • 与 OpenFang 团队建立联系 │
|
||||
│ • 评估插件迁移可行性 │
|
||||
│ │
|
||||
│ 阶段 2：原型验证 (2-3 周) │
|
||||
│ ──────────────────────── │
|
||||
│ • 实现基础 GatewayClient 适配 │
|
||||
│ • 验证核心功能可用性 │
|
||||
│ • 评估性能提升实际效果 │
|
||||
│ • 收集团队反馈 │
|
||||
│ │
|
||||
│ 阶段 3：并行开发 (1-2 月) │
|
||||
│ ──────────────────────── │
|
||||
│ • 保持 OpenClaw 版本维护 │
|
||||
│ • 并行开发 OpenFang 版本 │
|
||||
│ • 实现插件兼容层 │
|
||||
│ • 内部测试和优化 │
|
||||
│ │
|
||||
│ 阶段 4：灰度发布 (2-4 周) │
|
||||
│ ──────────────────────── │
|
||||
│ • 选择部分用户进行 Beta 测试 │
|
||||
│ • 收集反馈并优化 │
|
||||
│ • 完善文档和教程 │
|
||||
│ │
|
||||
│ 阶段 5：正式切换 │
|
||||
│ ──────────────── │
|
||||
│ • 发布 OpenFang 版本为默认 │
|
||||
│ • OpenClaw 版本进入维护模式 │
|
||||
│ • 持续优化和迭代 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 8.3 最终建议
|
||||
|
||||
| 条件 | 建议 |
|
||||
|------|------|
|
||||
| **如果追求快速迭代** | 保持 OpenClaw，关注 OpenFang 发展 |
|
||||
| **如果追求企业市场** | **强烈建议切换** OpenFang |
|
||||
| **如果追求差异化竞争** | **建议切换** OpenFang |
|
||||
| **如果资源有限** | 保持 OpenClaw，渐进评估 |
|
||||
| **如果目标是内容创作者/销售** | **强烈建议切换** OpenFang |
|
||||
|
||||
---
|
||||
|
||||
## 九、结论
|
||||
|
||||
### 切换到 OpenFang 的核心价值
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ 🚀 性能：33x 启动速度 + 90% 内存节省 │
|
||||
│ │
|
||||
│ 🔒 安全：16 层纵深防御 + 金融级合规 │
|
||||
│ │
|
||||
│ 🤖 智能：Hands 自主系统 + Workflow 引擎 │
|
||||
│ │
|
||||
│ 📈 商业：企业市场 + 定价提升空间 │
|
||||
│ │
|
||||
│ ⚠️ 成本：1.5-2 个月迁移 + 插件重写 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
💡 总结：如果 ZClaw 的目标是成为"生产级 AI Agent 客户端"，
|
||||
切换到 OpenFang 是值得投入的战略选择。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*分析日期：2026-03-13*
|
||||
*分析版本：v1.0*
|
||||
816
docs/archive/research-reports/claw-ecosystem-deep-dive-report.md
Normal file
816
docs/archive/research-reports/claw-ecosystem-deep-dive-report.md
Normal file
@@ -0,0 +1,816 @@
|
||||
# Claw 生态系统深度调研报告
|
||||
|
||||
> **调研主题**：深度对比分析 OpenClaw 及其衍生系统（OpenFang/ZeroClaw/NanoClaw）功能架构，评估 QClaw、AutoClaw 的技术选型建议
|
||||
>
|
||||
> **调研日期**：2026-03-13
|
||||
>
|
||||
> **调研方法**：多源搜索（GitHub、技术博客、知乎、Medium、Reddit）、交叉验证、架构分析
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [执行摘要](#执行摘要)
|
||||
2. [Claw 系列发展脉络](#claw-系列发展脉络)
|
||||
3. [OpenClaw 核心架构深度分析](#openclaw-核心架构深度分析)
|
||||
4. [衍生系统对比分析](#衍生系统对比分析)
|
||||
5. [QClaw 与 AutoClaw 技术分析](#qclaw-与-autoclaw-技术分析)
|
||||
6. [技术选型建议](#技术选型建议)
|
||||
7. [独立洞察与趋势预测](#独立洞察与趋势预测)
|
||||
8. [参考来源](#参考来源)
|
||||
|
||||
---
|
||||
|
||||
## 执行摘要
|
||||
|
||||
### 核心发现
|
||||
|
||||
1. **OpenClaw 是当前最成熟的个人 AI 助手框架**，由奥地利开发者 Peter Steinberger 于 2025 年 11 月创建，4 个月内获得 25 万+ GitHub Stars，成为 GitHub 历史增长最快的开源项目。
|
||||
|
||||
2. **Claw 生态系统呈现三层分化**：
|
||||
- **完整方案层**：OpenClaw（功能全、生态丰富）
|
||||
- **轻量替代层**：ZeroClaw（Rust 极致性能）、NanoClaw（容器隔离）
|
||||
- **专用变体层**：PicoClaw、TinyClaw、IronClaw 等
|
||||
|
||||
3. **QClaw 和 AutoClaw 的技术选型建议**：
|
||||
- **QClaw（腾讯）**：建议基于 **OpenClaw**，因其需要微信/QQ 深度集成和大规模用户支持
|
||||
- **AutoClaw**：建议基于 **ZeroClaw**，因其定位为边缘计算、Docker 容器化的轻量级 Agent
|
||||
|
||||
### 关键数据
|
||||
|
||||
| 指标 | OpenClaw | ZeroClaw | NanoClaw |
|
||||
|------|----------|----------|----------|
|
||||
| **GitHub Stars** | 250,000+ | ~15,000 | ~8,000 |
|
||||
| **代码规模** | ~390,000 行 | ~50,000 行 | ~5,000 行 |
|
||||
| **内存占用** | >1GB | <5MB | >100MB |
|
||||
| **启动时间** | 2-5 秒 | <10ms | ~30 秒 |
|
||||
| **语言** | TypeScript | Rust | TypeScript |
|
||||
| **技能数量** | 13,729+ | 兼容 OpenClaw | Skills 系统 |
|
||||
|
||||
---
|
||||
|
||||
## Claw 系列发展脉络
|
||||
|
||||
### 时间线
|
||||
|
||||
```
|
||||
2025-11 ─────────────────────────────────────────────────────────────► 2026-03
|
||||
|
||||
│
|
||||
├─► OpenClaw v1.0 发布 (Peter Steinberger)
|
||||
│ └─ 原名 Clawdbot/Moltbot
|
||||
│
|
||||
├─► 2025-12: GitHub Stars 突破 10 万
|
||||
│
|
||||
├─► 2026-01: 生态爆发期
|
||||
│ ├─ ZeroClaw 发布 (Rust 重写)
|
||||
│ ├─ NanoClaw 发布 (精简版)
|
||||
│ ├─ PicoClaw, TinyClaw, IronClaw 相继出现
|
||||
│ └─ ClawHub 技能市场上线
|
||||
│
|
||||
├─► 2026-02: 企业采用期
|
||||
│ ├─ 腾讯发布 QClaw 内测
|
||||
│ ├─ OpenAI 成立 OpenClaw 基金会
|
||||
│ └─ LongCat 效率引擎集成
|
||||
│
|
||||
└─► 2026-03: 生态成熟期
|
||||
├─ 13,729+ 技能发布
|
||||
├─ 100,000+ 活跃用户
|
||||
└─ 多个企业级变体发布
|
||||
```
|
||||
|
||||
### 系统关系图谱
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ OpenClaw (核心) │
|
||||
│ Peter Steinberger @steipete │
|
||||
│ 2025-11 首发 │
|
||||
│ 250,000+ GitHub Stars │
|
||||
└─────────────────┬───────────────────┘
|
||||
│
|
||||
┌────────────────────────────┼────────────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ OpenFang │ │ ZeroClaw │ │ NanoClaw │
|
||||
│ Rust 重写 │ │ Rust 重写 │ │ TypeScript │
|
||||
│ 生产级 OS │ │ 极致轻量 │ │ 容器隔离 │
|
||||
│ 16 层安全 │ │ <5MB RAM │ │ Agent Swarms │
|
||||
│ 40 通道 │ │ 边缘计算 │ │ 群组隔离 │
|
||||
│ Hands 系统 │ │ │ │ │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
└────────────────────────────┼────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ 其他变体 │
|
||||
│ │
|
||||
│ • PicoClaw (极简) │
|
||||
│ • TinyClaw (轻量) │
|
||||
│ • IronClaw (安全强化) │
|
||||
│ • Nanobot (自动化) │
|
||||
│ • ClawWork (工作流) │
|
||||
└─────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ 企业定制版本 │
|
||||
│ │
|
||||
│ • QClaw (腾讯) │
|
||||
│ • AutoClaw (轻量容器) │
|
||||
│ • LongCat (美团) │
|
||||
└─────────────────────────┘
|
||||
```
|
||||
|
||||
### 设计哲学对比
|
||||
|
||||
| 系统 | 设计哲学 | 核心取舍 |
|
||||
|------|----------|----------|
|
||||
| **OpenClaw** | "Gateway 是控制平面，助手才是产品" | 功能完整 vs 复杂度高 |
|
||||
| **ZeroClaw** | "极致轻量，边缘优先" | 性能 vs 生态丰富度 |
|
||||
| **NanoClaw** | "小到可以理解" | 简洁 vs 功能完整 |
|
||||
| **PicoClaw** | "最小可行" | 极简 vs 扩展性 |
|
||||
|
||||
---
|
||||
|
||||
## OpenClaw 核心架构深度分析
|
||||
|
||||
### 整体架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 通信渠道层 (Channels) │
|
||||
│ WhatsApp | Telegram | Slack | Discord | Signal | iMessage | Matrix │
|
||||
│ Feishu | LINE | Teams | WebChat | Nostr | Twitch | Zalo | IRC │
|
||||
└───────────────────────────────────┬─────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Gateway 控制平面 │
|
||||
│ ws://127.0.0.1:18789 │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Sessions │ │ Channels │ │ Config │ │ Cron │ │
|
||||
│ │ 会话管理 │ │ 渠道管理 │ │ 配置管理 │ │ 定时任务 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Webhooks │ │ Presence │ │ Tools │ │ Canvas │ │
|
||||
│ │ 钩子触发 │ │ 在线状态 │ │ 工具调用 │ │ 可视化面板 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└───────────────────────────────────┬─────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────┼─────────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Pi Agent │ │ CLI / WebChat │ │ Companion Apps │
|
||||
│ (RPC 模式) │ │ 命令行/Web │ │ macOS/iOS/And │
|
||||
│ │ │ │ │ roid │
|
||||
│ ┌───────────┐ │ │ ┌───────────┐ │ │ │
|
||||
│ │ Tool │ │ │ │ Agent │ │ │ Voice Wake │
|
||||
│ │ Streaming │ │ │ │ Commands │ │ │ Canvas │
|
||||
│ │ Block │ │ │ │ Control │ │ │ Camera │
|
||||
│ │ Streaming │ │ │ │ Debug │ │ │ Notifications│
|
||||
│ └───────────┘ │ │ └───────────┘ │ │ │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### 核心子系统
|
||||
|
||||
#### 1. Gateway WebSocket 网络
|
||||
|
||||
**职责**：单一 WebSocket 控制平面，管理所有客户端、工具和事件
|
||||
|
||||
**关键特性**：
|
||||
- 会话管理、状态持久化、配置热更新
|
||||
- Cron 定时任务、Webhook 触发器
|
||||
- 默认端口：18789
|
||||
|
||||
```typescript
|
||||
// 配置示例
|
||||
gateway:
|
||||
bind: loopback // 绑定到本地回环
|
||||
port: 18789 // WebSocket 端口
|
||||
tailscale:
|
||||
mode: off|serve|funnel // Tailscale 暴露模式
|
||||
auth:
|
||||
mode: password // 认证模式
|
||||
```
|
||||
|
||||
#### 2. Agent Runtime (Pi)
|
||||
|
||||
**设计模式**：RPC 模式的 Agent 运行时
|
||||
|
||||
**Agent Loop 架构**：
|
||||
```
|
||||
Think → Plan → Act → Observe → (循环)
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
推理 规划 执行 观察
|
||||
```
|
||||
|
||||
**核心能力**：
|
||||
- Tool Streaming：工具执行状态的实时流式传输
|
||||
- Block Streaming：响应内容的分块流式输出
|
||||
- Session Model：main 会话、群组隔离、激活模式
|
||||
|
||||
#### 3. 插件/技能系统
|
||||
|
||||
**三层技能架构**：
|
||||
|
||||
| 类型 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| **Bundled Skills** | 内置 | 核心技能，随 Gateway 分发 |
|
||||
| **Managed Skills** | ClawHub | 自动搜索、按需拉取 |
|
||||
| **Workspace Skills** | `~/.openclaw/workspace/skills/` | 用户自定义技能 |
|
||||
|
||||
**技能定义结构**：
|
||||
```
|
||||
~/.openclaw/workspace/
|
||||
├── AGENTS.md # Agent 行为定义
|
||||
├── SOUL.md # 人格/身份定义
|
||||
├── TOOLS.md # 工具使用指南
|
||||
└── skills/
|
||||
└── <skill-name>/
|
||||
└── SKILL.md # 技能描述文件
|
||||
```
|
||||
|
||||
#### 4. 多渠道适配器
|
||||
|
||||
**支持渠道** (20+)：
|
||||
|
||||
| 渠道 | 实现库 | 特性 |
|
||||
|------|--------|------|
|
||||
| WhatsApp | Baileys | 设备配对、群组支持 |
|
||||
| Telegram | grammY | Bot Token、Webhook |
|
||||
| Slack | Bolt | App Token、事件订阅 |
|
||||
| Discord | discord.js | Guilds、DM Policy |
|
||||
| Signal | signal-cli | 端到端加密 |
|
||||
| iMessage | BlueBubbles | macOS 专用 |
|
||||
| Feishu | 飞书开放平台 | 企业通讯 |
|
||||
|
||||
#### 5. 工具系统
|
||||
|
||||
**内置工具类别**：
|
||||
|
||||
| 类别 | 工具 | 说明 |
|
||||
|------|------|------|
|
||||
| **执行** | `bash`, `process` | 命令执行、进程管理 |
|
||||
| **文件** | `read`, `write`, `edit` | 文件操作 |
|
||||
| **浏览器** | `browser` | CDP 控制的 Chrome/Chromium |
|
||||
| **Canvas** | `canvas.*` | A2UI 可视化工作区 |
|
||||
| **节点** | `nodes.*` | 设备能力调用 |
|
||||
| **会话** | `sessions_*` | 多 Agent 协作 |
|
||||
| **调度** | `cron` | 定时任务 |
|
||||
|
||||
### 技术栈详情
|
||||
|
||||
| 组件 | 技术选型 |
|
||||
|------|----------|
|
||||
| **运行时** | Node.js 22+ |
|
||||
| **语言** | TypeScript (390,000+ 行) |
|
||||
| **包管理** | npm / pnpm / bun |
|
||||
| **构建** | tsx (开发) / tsc (生产) |
|
||||
|
||||
### 优劣势分析
|
||||
|
||||
#### 优势
|
||||
|
||||
| 优势 | 详情 |
|
||||
|------|------|
|
||||
| **完整的个人助手解决方案** | 不是框架，而是可直接使用的产品 |
|
||||
| **多渠道原生支持** | 20+ 平台开箱即用 |
|
||||
| **本地优先架构** | 数据隐私、低延迟、无云依赖 |
|
||||
| **丰富的工具生态** | 内置浏览器、Canvas、节点控制等 |
|
||||
| **灵活的模型支持** | 多 LLM 提供商、故障转移 |
|
||||
| **活跃的社区** | 500+ 贡献者、快速增长 |
|
||||
| **企业级特性** | 沙箱、权限、远程访问 |
|
||||
|
||||
#### 劣势
|
||||
|
||||
| 劣势 | 详情 |
|
||||
|------|------|
|
||||
| **学习曲线陡峭** | 390,000+ 行代码，架构复杂 |
|
||||
| **资源消耗较高** | Node.js 22+、浏览器实例、多进程 |
|
||||
| **文档分散** | 大量文档但需要时间导航 |
|
||||
| **TypeScript 依赖** | 不熟悉 TS 的开发者上手困难 |
|
||||
| **主要面向个人** | 企业多租户场景需要定制 |
|
||||
|
||||
---
|
||||
|
||||
## 衍生系统对比分析
|
||||
|
||||
### ZeroClaw - Rust 极致性能版
|
||||
|
||||
#### 核心特性
|
||||
|
||||
| 特性 | 数据 |
|
||||
|------|------|
|
||||
| **编程语言** | Rust (100%) |
|
||||
| **二进制大小** | ~8.8 MB |
|
||||
| **内存占用** | <5 MB |
|
||||
| **启动时间** | <10ms (0.8GHz 核心) |
|
||||
| **部署方式** | 单二进制文件 |
|
||||
| **运行平台** | Linux, macOS, Windows (ARM64, x86, RISC-V) |
|
||||
|
||||
#### Trait 驱动架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ ZeroClaw Runtime │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │Provider │ │ Channel │ │ Memory │ │ Tools │ │
|
||||
│ │ (Trait) │ │ (Trait) │ │ (Trait) │ │ (Trait) │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ ┌────┴──────────┴──────────┴──────────┴────┐ │
|
||||
│ │ Core Orchestrator │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────┴────┐ │
|
||||
│ │ Runtime │ ── Native / Docker │
|
||||
│ └─────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**可替换 Trait**：
|
||||
- **Provider**：支持 22+ AI 模型提供商
|
||||
- **Channel**：CLI, Telegram, Discord, Slack, WhatsApp, Matrix 等
|
||||
- **Memory**：SQLite 混合搜索、PostgreSQL、Markdown 文件
|
||||
- **Runtime**：Native 或 Docker 沙箱
|
||||
|
||||
#### 最佳适用场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| **边缘计算/IoT** | 可在 $10 硬件、树莓派等低功耗设备运行 |
|
||||
| **资源受限环境** | VPS、嵌入式系统、低内存云实例 |
|
||||
| **高安全性要求** | 金融、合规场景，需要 RBAC 和审计日志 |
|
||||
| **多模型切换** | 需要在 22+ 模型提供商间灵活切换 |
|
||||
| **离线/本地部署** | 支持 Ollama、llama.cpp、vLLM 本地推理 |
|
||||
|
||||
---
|
||||
|
||||
### NanoClaw - 容器隔离精简版
|
||||
|
||||
#### 核心特性
|
||||
|
||||
| 特性 | 数据 |
|
||||
|------|------|
|
||||
| **编程语言** | TypeScript/Node.js |
|
||||
| **代码规模** | ~几百行核心代码 |
|
||||
| **部署方式** | Node.js 环境 + Docker |
|
||||
| **运行平台** | macOS, Linux |
|
||||
|
||||
#### 架构设计
|
||||
|
||||
```
|
||||
Channels --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Response
|
||||
```
|
||||
|
||||
**关键特性**：
|
||||
1. **容器隔离安全**：Agent 在 Linux 容器中运行，文件系统隔离
|
||||
2. **AI 原生设计**：无安装向导 - Claude Code 引导设置
|
||||
3. **Skills 优于 Features**：通过 `/add-whatsapp`, `/add-telegram` 等 skills 添加功能
|
||||
4. **Agent Swarms**：首个支持 Agent 群体的个人 AI 助手
|
||||
5. **群组隔离**：每个群组有独立的 CLAUDE.md 记忆
|
||||
|
||||
#### 最佳适用场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| **个人定制** | 想要完全理解并定制自己 AI 助手的用户 |
|
||||
| **快速原型** | 用 Claude Code 快速迭代和定制 |
|
||||
| **隐私敏感用户** | 不信任复杂软件，希望审计代码 |
|
||||
| **Agent 协作** | 需要 Agent Swarms 协作的复杂任务 |
|
||||
|
||||
---
|
||||
|
||||
### OpenFang - 生产级 Agent 操作系统
|
||||
|
||||
#### 基本信息
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| **开发者** | Jaber (RightNow) |
|
||||
| **发布时间** | 2026年 |
|
||||
| **当前版本** | v0.3.30 |
|
||||
| **语言** | Rust (137,728 行) |
|
||||
| **GitHub Stars** | 12,000+ |
|
||||
|
||||
#### 与 OpenClaw 的关系
|
||||
|
||||
OpenFang 是**受 OpenClaw 启发但完全独立构建**的项目：
|
||||
- 不是 OpenClaw 的 fork
|
||||
- 从零开始用 Rust 重写
|
||||
- 提供 OpenClaw 迁移工具 (`openfang migrate --from openclaw`)
|
||||
- 兼容 SKILL.md 格式和 ClawHub 市场
|
||||
|
||||
#### 核心创新：Hands 自主智能体系统
|
||||
|
||||
| Hand | 功能描述 |
|
||||
|------|----------|
|
||||
| **Clip** | YouTube 视频处理：下载、识别精彩片段、生成竖屏短视频、添加字幕和 AI 配音、发布到 Telegram/WhatsApp |
|
||||
| **Lead** | 每日自动发现潜在客户、网络调研丰富信息、0-100 评分、去重、生成 CSV/JSON/Markdown 报告 |
|
||||
| **Collector** | OSINT 级情报收集：持续监控目标（公司/人物/话题）、变化检测、情感追踪、知识图谱构建 |
|
||||
| **Predictor** | 超级预测引擎：多源信号收集、校准推理链、置信区间预测、Brier 评分跟踪准确度 |
|
||||
| **Researcher** | 深度自主研究：跨源交叉验证、CRAAP 可信度评估、APA 格式引用、多语言支持 |
|
||||
| **Twitter** | 自主 Twitter 账户管理：7种内容格式轮换、最佳发布时间调度、提及响应、审批队列 |
|
||||
| **Browser** | 网页自动化：导航网站、填表、点击按钮、多步骤工作流（强制购买审批门控） |
|
||||
|
||||
#### 16 层安全系统
|
||||
|
||||
| # | 安全系统 | 功能 |
|
||||
|---|----------|------|
|
||||
| 1 | WASM 双重计量沙箱 | 工具代码在 WebAssembly 中运行，带燃料计量 + 纪元中断 |
|
||||
| 2 | Merkle 哈希链审计 | 每个操作加密链接到前一个，篡改任一条目整个链断裂 |
|
||||
| 3 | 信息流污染追踪 | 标签在执行中传播，机密从源头到汇点全程追踪 |
|
||||
| 4 | Ed25519 签名代理清单 | 每个代理身份和能力集加密签名 |
|
||||
| 5 | SSRF 防护 | 阻止私有 IP、云元数据端点、DNS 重绑定攻击 |
|
||||
| 6 | 机密零化 | `Zeroizing<String>` 自动从内存中擦除 API 密钥 |
|
||||
| 7 | OFP 互认证 | HMAC-SHA256 基于随机数的 P2P 网络验证 |
|
||||
| 8 | 能力门控 | 基于角色的访问控制 |
|
||||
| 9 | 安全头 | CSP, X-Frame-Options, HSTS 等 |
|
||||
| 10 | 健康端点编辑 | 公共健康检查返回最少信息 |
|
||||
| 11 | 子进程沙箱 | `env_clear()` + 选择性变量传递 |
|
||||
| 12 | 提示注入扫描器 | 检测覆盖尝试和数据泄露模式 |
|
||||
| 13 | 循环守卫 | SHA256 工具调用循环检测 + 断路器 |
|
||||
| 14 | 会话修复 | 7 阶段消息历史验证和自动恢复 |
|
||||
| 15 | 路径遍历防护 | 规范化 + 符号链接转义防护 |
|
||||
| 16 | GCRA 速率限制 | 成本感知令牌桶限流 |
|
||||
|
||||
#### 性能基准对比
|
||||
|
||||
| 指标 | OpenFang | OpenClaw | ZeroClaw |
|
||||
|------|----------|----------|----------|
|
||||
| **冷启动时间** | 180ms | 5.98s | 10ms |
|
||||
| **空闲内存** | 40MB | 394MB | 5MB |
|
||||
| **安装大小** | 32MB | 500MB | 8.8MB |
|
||||
| **安全系统** | 16层 | 3层 | 6层 |
|
||||
| **通道适配器** | 40 | 13 | 15 |
|
||||
| **LLM 提供商** | 27 | 10 | 28 |
|
||||
|
||||
#### 适用场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| **企业生产环境** | 7x24 小时稳定运行、16 层安全防护 |
|
||||
| **自主工作流** | 需要代理在无人工干预下持续执行任务 |
|
||||
| **安全敏感场景** | 金融、医疗等需要审计追踪的行业 |
|
||||
| **多通道集成** | 需要同时接入 40+ 消息平台 |
|
||||
|
||||
---
|
||||
|
||||
### 其他变体一览
|
||||
|
||||
| 变体 | 定位 | 核心差异 |
|
||||
|------|------|----------|
|
||||
| **PicoClaw** | 最小可行 | 极简实现，适合学习 |
|
||||
| **TinyClaw** | 轻量级 | 资源占用小，功能精简 |
|
||||
| **IronClaw** | 安全强化 | 安全审计、合规支持 |
|
||||
| **Nanobot** | 自动化 | 任务自动化、工作流 |
|
||||
| **ClawWork** | 工作流 | 企业工作流集成 |
|
||||
|
||||
---
|
||||
|
||||
### 综合对比矩阵
|
||||
|
||||
| 维度 | OpenClaw | OpenFang | ZeroClaw | NanoClaw | PicoClaw |
|
||||
|------|----------|----------|----------|----------|----------|
|
||||
| **语言** | TypeScript | Rust | Rust | TypeScript | TypeScript |
|
||||
| **代码规模** | ~390,000 行 | ~137,000 行 | ~50,000 行 | ~5,000 行 | ~2,000 行 |
|
||||
| **内存** | >1GB | 40MB | <5MB | >100MB | <50MB |
|
||||
| **启动** | 2-5 秒 | 180ms | <10ms | ~30 秒 | <1 秒 |
|
||||
| **安全模型** | 3 层 | 16 层纵深防御 | 6 层 | 容器隔离 | 基础隔离 |
|
||||
| **配置** | 53 个配置文件 | 单个 TOML 文件 | 单个 TOML 文件 | 无配置文件 | 最小配置 |
|
||||
| **依赖** | 70+ | 零运行时依赖 | 零运行时依赖 | Node.js + Docker | Node.js |
|
||||
| **模型支持** | 50+ | 27 | 22+ | Claude Agent SDK | 少量 |
|
||||
| **渠道** | 20+ | 40 | 15+ | WhatsApp, Telegram 等 | 基础 |
|
||||
| **技能/工具** | 53 个 + 13,729 技能 | 53 个 + 60 技能 + 7 Hands | 12 个 | Skills 系统 | 基础 |
|
||||
| **适用规模** | 企业级 | 生产级企业 | 边缘/个人/企业 | 个人 | 学习/实验 |
|
||||
| **部署复杂度** | 高 | 中 | 低 | 中 | 低 |
|
||||
| **自主能力** | 被动响应 | 主动 Hands 系统 | 被动响应 | Agent Swarms | 无 |
|
||||
|
||||
---
|
||||
|
||||
## QClaw 与 AutoClaw 技术分析
|
||||
|
||||
### QClaw (腾讯 QuantumClaw)
|
||||
|
||||
#### 基本信息
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| **开发者** | 腾讯 |
|
||||
| **发布时间** | 2026-03-09 内测 |
|
||||
| **定位** | 一键安装器，在微信和 QQ 内部署 OpenClaw AI Agent |
|
||||
| **技术栈** | 基于 OpenClaw |
|
||||
|
||||
#### 核心特性
|
||||
|
||||
1. **微信/QQ 深度集成**：直接在腾讯生态内运行 AI Agent
|
||||
2. **一键安装**：简化 OpenClaw 的部署流程
|
||||
3. **大规模用户支持**：面向腾讯 10 亿+ 用户
|
||||
|
||||
#### 技术选型建议：基于 OpenClaw
|
||||
|
||||
**推荐理由**：
|
||||
|
||||
| 因素 | 分析 |
|
||||
|------|------|
|
||||
| **生态兼容** | OpenClaw 已有 13,729+ 技能，可直接复用 |
|
||||
| **多渠道支持** | OpenClaw 的 20+ 渠道架构成熟 |
|
||||
| **社区支持** | 250,000+ Stars，活跃的开发者社区 |
|
||||
| **微信集成** | OpenClaw 已有 IM 集成经验 |
|
||||
| **企业级特性** | 沙箱、权限、多租户支持 |
|
||||
|
||||
**集成路径**：
|
||||
```
|
||||
OpenClaw Gateway
|
||||
│
|
||||
├──► WeChat Adapter (新增)
|
||||
│
|
||||
├──► QQ Adapter (新增)
|
||||
│
|
||||
└──► 腾讯云模型支持 (新增)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### AutoClaw (智谱AI 澳龙)
|
||||
|
||||
> **重要澄清**：AutoClaw 是智谱AI推出的商业化版本，与之前提到的 Docker 容器化版本不同。
|
||||
|
||||
#### 基本信息
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| **开发者** | 智谱AI |
|
||||
| **定位** | 一键本地安装的 OpenClaw 商业版 |
|
||||
| **目标用户** | 小白用户、办公自动化 |
|
||||
| **技术门槛** | 极低（1分钟安装） |
|
||||
|
||||
#### 核心特性
|
||||
|
||||
1. **1分钟安装**：一键本地部署
|
||||
2. **50+ 预置技能**：开箱即用的办公技能
|
||||
3. **飞书深度集成**：企业通讯原生支持
|
||||
4. **GLM 模型支持**：智谱自研大模型
|
||||
|
||||
#### 商业化版本对比
|
||||
|
||||
| 产品 | 开发者 | 部署方式 | 技术门槛 | 核心优势 | 主要场景 |
|
||||
|------|--------|---------|---------|---------|---------|
|
||||
| **AutoClaw** | 智谱AI | 本地一键安装 | 极低 | 1分钟安装、50+预置技能、飞书集成 | 小白用户、办公自动化 |
|
||||
| **KimiClaw** | 月之暗面 | 云端托管 | 极低 | 5000+技能库、40GB云存储、多设备同步 | 需要丰富技能生态 |
|
||||
| **MaxClaw** | MiniMax | 云端托管 | 极低 | 10000+模板、原生图片视频生成 | 内容创作者 |
|
||||
| **QClaw** | 腾讯 | 微信/QQ 集成 | 极低 | 微信生态、腾讯云模型 | 微信用户 |
|
||||
|
||||
---
|
||||
|
||||
### 轻量级容器化版本（Docker 微服务场景）
|
||||
|
||||
对于需要 Docker 容器化、边缘计算场景的**轻量级 AI Agent**，推荐基于 **ZeroClaw**：
|
||||
|
||||
#### 技术选型建议：基于 ZeroClaw
|
||||
|
||||
**推荐理由**：
|
||||
|
||||
| 因素 | 分析 |
|
||||
|------|------|
|
||||
| **资源效率** | ZeroClaw <5MB 内存，适合边缘计算 |
|
||||
| **启动速度** | <10ms 启动，适合微服务 |
|
||||
| **Docker 友好** | 单二进制文件，容器化简单 |
|
||||
| **多平台支持** | ARM64, x86, RISC-V 全覆盖 |
|
||||
| **安全设计** | Gateway 配对、文件系统隔离 |
|
||||
|
||||
**集成路径**：
|
||||
```
|
||||
ZeroClaw Binary (< 9MB)
|
||||
│
|
||||
├──► Docker 镜像 (Alpine 基础)
|
||||
│
|
||||
├──► Kubernetes Helm Chart
|
||||
│
|
||||
└──► 边缘设备支持 (树莓派等)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技术选型建议
|
||||
|
||||
### 决策矩阵
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 你的需求是什么？ │
|
||||
└─────────────────┬───────────────────┘
|
||||
│
|
||||
┌─────────────────┬───────────────────┼───────────────────┬─────────────────┐
|
||||
│ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐
|
||||
│ 完整功能 │ │ 生产级 OS │ │ 极致性能 │ │ 简洁可控 │ │ 最小化 │
|
||||
│ 丰富生态 │ │ 自主运行 │ │ 边缘部署 │ │ 快速定制 │ │ 学习 │
|
||||
└────┬────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └────┬────┘
|
||||
│ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐
|
||||
│OpenClaw │ │ OpenFang │ │ ZeroClaw │ │ NanoClaw │ │PicoClaw │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│• 企业级 │ │• 7x24 运行 │ │• IoT/边缘 │ │• 个人定制 │ │• 极简 │
|
||||
│• 多渠道 │ │• 16 层安全 │ │• 资源受限 │ │• 容器隔离 │ │• 学习 │
|
||||
│• 大规模 │ │• Hands 系统 │ │• 安全优先 │ │• Agent群 │ │• 实验 │
|
||||
│• 技能多 │ │• 40 通道 │ │• Rust 性能 │ │• Claude原生│ │ │
|
||||
└─────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘
|
||||
```
|
||||
|
||||
### 场景推荐
|
||||
|
||||
| 场景 | 推荐系统 | 理由 |
|
||||
|------|----------|------|
|
||||
| **企业级 AI 助手** | OpenClaw | 功能完整、生态丰富、企业级支持 |
|
||||
| **生产级自主运行** | OpenFang | Hands 系统、7x24 小时稳定运行、16 层安全 |
|
||||
| **微信/QQ 集成** | OpenClaw | 多渠道架构成熟、技能生态 |
|
||||
| **边缘计算** | ZeroClaw | <5MB 内存、<10ms 启动 |
|
||||
| **Docker 微服务** | ZeroClaw | 单二进制、容器友好 |
|
||||
| **个人定制** | NanoClaw | 代码简洁、Claude Code 集成 |
|
||||
| **学习/实验** | PicoClaw | 最小实现、易于理解 |
|
||||
| **安全敏感** | OpenFang | 16 层纵深防御、Merkle 审计链 |
|
||||
| **金融/合规** | OpenFang | WASM 沙箱、信息流追踪、RBAC |
|
||||
|
||||
### QClaw 与 AutoClaw 的最终建议
|
||||
|
||||
#### QClaw（腾讯）选型建议
|
||||
|
||||
| 系统 | 推荐基础 | 核心理由 |
|
||||
|------|----------|----------|
|
||||
| **QClaw** | **OpenClaw** 或 **OpenFang** | 微信/QQ 集成需要成熟的 IM 框架。OpenClaw 有更丰富的技能生态；OpenFang 有更强的安全性和自主能力 |
|
||||
|
||||
**选择 OpenClaw 的理由**：
|
||||
- 13,729+ 技能生态，可直接复用
|
||||
- 250,000+ 社区，技术支持丰富
|
||||
- 多渠道架构成熟，微信集成经验已有
|
||||
- TypeScript 生态，中国开发者熟悉
|
||||
|
||||
**选择 OpenFang 的理由**：
|
||||
- 16 层安全系统，满足合规要求
|
||||
- 40 个通道适配器，覆盖更广
|
||||
- Hands 自主系统，更智能化
|
||||
- Rust 性能优势，资源消耗低 90%
|
||||
|
||||
**建议**：
|
||||
- 如果追求**快速上线和生态复用** → 选择 OpenClaw
|
||||
- 如果追求**安全合规和长期运营** → 选择 OpenFang
|
||||
|
||||
#### AutoClaw（智谱AI）分析
|
||||
|
||||
**澄清**：AutoClaw 是智谱AI 推出的**商业化产品**，而非需要选型的技术基础。它是基于 OpenClaw 的打包优化版本：
|
||||
|
||||
- 1分钟本地安装
|
||||
- 50+ 预置技能
|
||||
- 飞书深度集成
|
||||
- GLM 模型支持
|
||||
|
||||
**市场定位**：面向小白用户和办公自动化场景，降低 OpenClaw 的使用门槛。
|
||||
|
||||
#### 轻量级容器化 Agent 选型建议
|
||||
|
||||
对于需要 Docker 容器化、边缘计算场景的**轻量级 AI Agent**：
|
||||
|
||||
| 系统 | 推荐基础 | 核心理由 |
|
||||
|------|----------|----------|
|
||||
| **边缘计算/微服务 Agent** | **ZeroClaw** | <5MB 内存、<10ms 启动、单二进制文件 |
|
||||
| **安全敏感场景** | **OpenFang** | 16 层纵深防御、WASM 沙箱、Merkle 审计链 |
|
||||
| **个人定制/快速原型** | **NanoClaw** | 代码简洁、Claude Code 集成、容器隔离 |
|
||||
|
||||
#### 商业化版本选型建议
|
||||
|
||||
| 用户类型 | 推荐方案 | 理由 |
|
||||
|---------|---------|------|
|
||||
| **技术小白** | AutoClaw（智谱AI） | 1分钟安装、预置技能、无门槛 |
|
||||
| **内容创作者** | MaxClaw（MiniMax） | 10000+ 模板、图片视频生成 |
|
||||
| **需要丰富技能** | KimiClaw（月之暗面） | 5000+ 技能库、40GB 云存储 |
|
||||
| **微信生态用户** | QClaw（腾讯） | 微信/QQ 深度集成 |
|
||||
| **技术用户/企业** | OpenClaw/OpenFang 自托管 | 完全控制、数据主权 |
|
||||
|
||||
---
|
||||
|
||||
## 独立洞察与趋势预测
|
||||
|
||||
### 洞察 1：Claw 生态的三层分化将持续
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Claw 生态三层架构 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 第一层：完整方案层 │
|
||||
│ ├── OpenClaw (核心) │
|
||||
│ └── 企业定制版 (QClaw, LongCat) │
|
||||
│ • 功能完整、生态丰富 │
|
||||
│ • 适合企业级部署 │
|
||||
│ │
|
||||
│ 第二层：轻量替代层 │
|
||||
│ ├── ZeroClaw (Rust) │
|
||||
│ └── NanoClaw (容器) │
|
||||
│ • 性能优先、资源高效 │
|
||||
│ • 适合边缘计算、个人定制 │
|
||||
│ │
|
||||
│ 第三层：专用变体层 │
|
||||
│ ├── PicoClaw, TinyClaw, IronClaw │
|
||||
│ └── 特定场景优化 │
|
||||
│ • 极简、专用、学习 │
|
||||
│ • 适合实验和特定需求 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 洞察 2：Rust 在 AI Agent 领域的崛起
|
||||
|
||||
ZeroClaw 的成功证明 Rust 在 AI Agent 领域的潜力：
|
||||
- **内存安全**：消除整类内存漏洞
|
||||
- **零成本抽象**：Trait 系统实现高度可组合性
|
||||
- **性能优势**：<5MB 内存 vs >1GB (TypeScript)
|
||||
|
||||
**预测**：未来会有更多 AI Agent 框架采用 Rust 重写。
|
||||
|
||||
### 洞察 3：容器隔离成为安全标准
|
||||
|
||||
NanoClaw 的容器隔离设计代表了一个趋势：
|
||||
- **沙箱隔离**：Agent 在容器内运行
|
||||
- **文件系统隔离**：只能访问显式挂载的目录
|
||||
- **资源限制**：CPU/内存/网络可控制
|
||||
|
||||
**预测**：企业级 AI Agent 部署将普遍采用容器隔离。
|
||||
|
||||
### 洞察 4：技能生态成为核心竞争力
|
||||
|
||||
OpenClaw 的 13,729+ 技能形成了强大的网络效应：
|
||||
- 用户选择框架时，技能数量是关键因素
|
||||
- 技能可移植性成为框架间竞争的焦点
|
||||
- ClawHub 模式可能被其他框架复制
|
||||
|
||||
**预测**：技能标准化和跨框架移植将成为 2026 年的重点。
|
||||
|
||||
### 洞察 5：中国企业定制化加速
|
||||
|
||||
QClaw、LongCat 等中国企业的定制版本表明：
|
||||
- 微信、飞书等本土渠道的深度集成需求
|
||||
- 中国本土 LLM 的支持需求
|
||||
- 合规和数据本地化要求
|
||||
|
||||
**预测**：2026 年将出现更多中国本土化的 AI Agent 框架。
|
||||
|
||||
---
|
||||
|
||||
## 参考来源
|
||||
|
||||
### 英文资源
|
||||
|
||||
- [OpenClaw GitHub Repository](https://github.com/openclaw/openclaw)
|
||||
- [OpenFang GitHub Repository](https://github.com/RightNow-AI/openfang)
|
||||
- [ZeroClaw GitHub Repository](https://github.com/zeroclaw-labs/zeroclaw)
|
||||
- [NanoClaw GitHub Repository](https://github.com/qwibitai/nanoclaw)
|
||||
- [QClaw (QuantumClaw) GitHub](https://github.com/QuantumClaw/QClaw)
|
||||
- [AutoClaw Official Site](https://autoclaws.org/lightweight-ai-agent/)
|
||||
- [OpenClaw Architecture Deep Dive (Towards AI)](https://pub.towardsai.net/openclaw-architecture-deep-dive-building-production-ready-ai-agents-from-scratch-e693c1002ae8)
|
||||
- [210,000 GitHub Stars Analysis (Medium)](https://medium.com/@Micheal-Lanham/210-000-github-stars-in-10-days-what-openclaws-architecture-teaches-us-about-building-personal-ai-dae040fab58f)
|
||||
- [OpenClaw vs ZeroClaw Comparison (SparkCo)](https://sparkco.ai/blog/openclaw-vs-zeroclaw-which-ai-agent-framework-should-you-choose-in-2026)
|
||||
- [ZeroClaw vs OpenClaw vs PicoClaw](https://zeroclaw.net/zeroclaw-vs-openclaw-vs-picoclaw)
|
||||
- [5 Best OpenClaw Alternatives (BuildMVPFast)](https://www.buildmvpfast.com/blog/best-openclaw-alternatives-personal-ai-agents-2026)
|
||||
- [AI Agent Frameworks - The Claw Ecosystem](https://waelmansour.com/blog/ai-agent-frameworks-the-claw-ecosystem/)
|
||||
- [Tencent QClaw Launch (Beam.ai)](https://beam.ai/agentic-insights/tencent-launches-qclaw-what-the-ai-agent-mainstream-moment-means-for-enterprise)
|
||||
- [OpenFang Official Documentation](https://openfang.sh/)
|
||||
- [OpenFang Workflows Documentation](https://openfang.sh/docs/workflows)
|
||||
- [Medium: I Ignored 30+ OpenClaw Alternatives Until OpenFang](https://medium.com/@agentnativedev/i-ignored-30-openclaw-alternatives-until-openfang-ff11851b83f1)
|
||||
- [Slashdot: OpenFang vs ZeroClaw Comparison](https://slashdot.org/software/comparison/OpenFang-vs-ZeroClaw/)
|
||||
- [DataCamp: OpenClaw vs Nanobot](https://www.datacamp.com/blog/openclaw-vs-nanobot)
|
||||
- [OpenClaw Design Patterns (Part 5 of 7)](https://kenhuangus.substack.com/p/openclaw-design-patterns-part-5-of)
|
||||
- [OpenClaw for Product Managers 2026 Guide](https://medium.com/@mohit15856/openclaw-for-product-managers-building-products-in-the-ai-agent-era-2026-guide-71d18641200f)
|
||||
|
||||
### 中文资源
|
||||
|
||||
- [OpenClaw 生态全解析 - 知乎](https://zhuanlan.zhihu.com/p/2009662986390876443)
|
||||
- [深度解读：OpenClaw 架构及生态 - 53AI](https://www.53ai.com/news/Openclaw/2026020325180.html)
|
||||
- [OpenClaw 深度研究报告 - ModelScope](https://www.modelscope.cn/learn/5618)
|
||||
- [OpenClaw 是什么？- 飞书博客](https://www.larksuite.com/zh_cn/blog/openclaw)
|
||||
- [LongCat 为 OpenClaw 装上效率引擎 - 美团技术团队](https://tech.meituan.com/2026/03/09/longcat-openclaw.html)
|
||||
- [OpenClaw 官方指南 (GitBook)](https://yeasy.gitbook.io/openclaw_guide)
|
||||
- [OpenClaw Skills 开发教程 - 知乎](https://zhuanlan.zhihu.com/p/2013710082840469620)
|
||||
- [OpenFang 中文官网](https://openfang.cc)
|
||||
- [Rang's Note: OpenFang 项目介绍](https://wurang.net/posts/openfang-intro/)
|
||||
- [智谱AI 发布 AutoClaw - Pandaily](https://pandaily.com/zhipu-ai-launches-auto-claw-a-one-click-local-open-claw-that-turns-p-cs-into-24-7-ai-agents)
|
||||
- [OpenClaw 中文社区](https://clawd.org.cn/)
|
||||
- [OpenClaw 真实评测 2026 - 腾讯云](https://cloud.tencent.com/developer/article/2636337)
|
||||
- [企业级 OpenClaw 四大方案技术路径深度解析 - 新浪财经](https://finance.sina.com.cn/tech/roll/2026-03-10/doc-inhqpaep9999746.shtml)
|
||||
- [OpenClaw 引爆全球 AI 代理革命 - 知乎](https://zhuanlan.zhihu.com/p/2011161924377794450)
|
||||
- [2026 年 OpenClaw Skills 生态完全指南 - 阿里云开发者](https://developer.aliyun.com/article/1712034)
|
||||
|
||||
---
|
||||
|
||||
*报告生成时间：2026-03-13*
|
||||
*调研方法：多源搜索、交叉验证、架构分析*
|
||||
*数据来源：GitHub、技术博客、知乎、Medium、Reddit、官方文档*
|
||||
Reference in New Issue
Block a user