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

refactor: 统一项目名称从OpenFang到ZCLAW
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details

Browse Source 
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括：
- 配置文件中的项目名称
- 代码注释和文档引用
- 环境变量和路径
- 类型定义和接口名称
- 测试用例和模拟数据

同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
This commit is contained in:
iven
2026-03-27 07:36:03 +08:00
parent 4b08804aa9
commit 0d4fa96b82
226 changed files with 7288 additions and 5788 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/DEVELOPMENT.md
View File

@@ -10,13 +10,13 @@
### 核心定位
**ZCLAW 是什么？**
- 基于 OpenClaw 的 AI 代理平台
- 不是重新造轮子，而是**扩展 OpenClaw 的能力**
- 基于 ZCLAW 的 AI 代理平台
- 不是重新造轮子，而是**扩展 ZCLAW 的能力**
- 目标：随时随地、一个 IM 入口搞定一切
### 与 OpenClaw 的关系
### 与 ZCLAW 的关系
`
OpenClaw (基础能力层)
ZCLAW (基础能力层)
↓
ZCLAW (增强层)
↓
@@ -24,9 +24,9 @@ ZCLAW (增强层)
`
**关键理解**：
- OpenClaw 提供：浏览器控制、文件操作、终端命令、记忆系统、技能系统
- ZCLAW 提供：浏览器控制、文件操作、终端命令、记忆系统、技能系统
- ZCLAW 提供：远程执行、任务编排、多 Agent 协作、持续记忆、主动服务
- ZCLAW **复用 OpenClaw SDK**，不是重写
- ZCLAW **复用 ZCLAW SDK**，不是重写
---
@@ -39,7 +39,7 @@ ZCLAW (增强层)
`
**痛点**：
- 必须坐在电脑前才能用 OpenClaw
- 必须坐在电脑前才能用 ZCLAW
- 手机只能查看，不能操控
- 无法随时随地处理任务
@@ -130,7 +130,7 @@ ZCLAW：主动推送，无需询问
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────────┐
│ OpenClaw 基础能力层 │
│ ZCLAW 基础能力层 │
│ 浏览器 | 文件系统 | 终端 | AI模型 | Skills | 记忆 │
└────────────────────┬────────────────────────────────────────┘
│
@@ -263,7 +263,7 @@ interface TaskOrchestrationEngine {
1. AI 规划 → 生成任务图
2. 拓扑排序 → 确定执行顺序
3. 检查依赖 → 等待前置步骤
4. 执行步骤 → 调用 OpenClaw 工具
4. 执行步骤 → 调用 ZCLAW 工具
5. 更新上下文 → 传递结果
6. 推送进度 → IM 渠道
7. 错误恢复 → 重试/跳过/失败
@@ -447,11 +447,11 @@ const task: ScheduledTask = {
- 下一步行动
- 文件预览
### 与 OpenClaw 的集成
### 与 ZCLAW 的集成
` ypescript
// OpenClaw 客户端
class OpenClawClient {
// ZCLAW 客户端
class ZCLAWClient {
private rpcUrl: string;
async send(message: string): Promise<Response> {
@@ -537,7 +537,7 @@ class OpenClawClient {
|------|------|------|------|
| **语言** | TypeScript | 5.x | 类型安全 |
| **运行时** | Node.js | 22 LTS | 稳定 |
| **框架** | OpenClaw SDK | latest | 复用基础能力 |
| **框架** | ZCLAW SDK | latest | 复用基础能力 |
| **数据库** | SQLite | 9.x | 本地存储 |
| **向量** | sqlite-vec | 0.1.x | 向量搜索 |
| **队列** | BullMQ | 5.x | 任务队列 |
@@ -594,7 +594,7 @@ G:\ZClaw/
│ │ ├── src/
│ │ │ ├── main.rs # 入口
│ │ │ ├── commands.rs # Tauri 命令
│ │ │ └── openclaw.rs # OpenClaw 集成
│ │ │ └── zclaw.rs # ZCLAW 集成
│ │ ├── Cargo.toml
│ │ └── tauri.conf.json
│ ├── package.json
@@ -674,9 +674,9 @@ pnpm tauri build
- **理由**: 快速验证，降低风险
- **方案**: MVP → 增强 → 场景化
### 决策 2: 复用 OpenClaw
### 决策 2: 复用 ZCLAW
- **理由**: 不重复造轮子
- **方案**: 使用 OpenClaw SDK
- **方案**: 使用 ZCLAW SDK
### 决策 3: Tauri 桌面端
- **理由**: 跨平台、性能好
@@ -692,7 +692,7 @@ pnpm tauri build
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| OpenClaw SDK 不稳定 | 中 | 高 | 多 Provider fallback |
| ZCLAW SDK 不稳定 | 中 | 高 | 多 Provider fallback |
| IM 平台封号 | 中 | 高 | 使用官方 API、合规使用 |
| 性能瓶颈 | 中 | 中 | 异步处理、缓存优化 |
| 需求变更 | 高 | 中 | 敏捷开发、MVP 优先 |
@@ -701,7 +701,7 @@ pnpm tauri build
## 📚 参考资料
- [OpenClaw 文档](C:\Program Files\AutoClaw\resources\gateway\openclaw\docs)
- [ZCLAW 文档](C:\Program Files\AutoClaw\resources\gateway\zclaw\docs)
- [Tauri 文档](https://tauri.app)
- [Koishi 文档](https://koishi.chat)
- [BullMQ 文档](https://docs.bullmq.io)

2
docs/README.md
View File

@@ -66,7 +66,7 @@ docs/
├── archive/ # 归档文档
│ ├── completed-plans/ # 已完成的计划
│ ├── research-reports/ # 研究报告
│ └── openclaw-legacy/ # 历史遗留文档
│ └── zclaw-legacy/ # 历史遗留文档
│
├── plans/ # 执行计划
│ └── ...

2
docs/USER_MANUAL.md
View File

@@ -106,7 +106,7 @@ ZCLAW 界面分为三个区域：
- **角色**: 如"代码助手"、"写作助手"
- **昵称**: 分身对你的称呼
- **场景标签**: 用逗号分隔，如"编程, 调试"
- **工作目录**: 默认 `~/.openfang/zclaw-workspace`
- **工作目录**: 默认 `~/.zclaw/zclaw-workspace`
- **你的名字**: 用户名称
- **你的角色**: 用户角色
- **限制文件访问范围**: 建议开启

6
docs/WORK_SUMMARY_2026-03-16.md
View File

@@ -46,10 +46,10 @@ docs/
├── archive/ # 归档文档
│ ├── completed-plans/ # 已完成的计划
│ ├── research-reports/ # 研究报告
│ └── openclaw-legacy/ # OpenClaw 遗留文档
│ └── zclaw-legacy/ # ZCLAW 遗留文档
├── knowledge-base/ # 技术知识库
│ ├── openfang-technical-reference.md
│ ├── openfang-websocket-protocol.md
│ ├── zclaw-technical-reference.md
│ ├── zclaw-websocket-protocol.md
│ └── ...
├── plans/ # 执行计划
└── test-reports/ # 测试报告

54
docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md
View File

@@ -2,7 +2,7 @@
> **文档日期**：2026-03-24
> **定位**：`ZCLAW_NEXT_EVOLUTION_STRATEGY.md` 的**专题补充文档**，聚焦 Agent 智能层的深度差距分析与演化路径
> **核心问题**：ZCLAW 当前的 Agent 只是"解决问题的帮手"，而 OpenClaw 的 Agent 是"可持续成长的助手"——如何弥合这一差距？
> **核心问题**：ZCLAW 当前的 Agent 只是"解决问题的帮手"，而 ZCLAW 的 Agent 是"可持续成长的助手"——如何弥合这一差距？
>
> **后续升级路径**：[`ZCLAW_OPENVIKING_INTEGRATION_PLAN.md`](./ZCLAW_OPENVIKING_INTEGRATION_PLAN.md) 中规划了基于 **OpenViking**（火山引擎开源 AI 智能体上下文数据库）的升级方案，作为本文档 Phase 1 自建记忆系统的**后续增强**选项。当前优先按本文档方案实施。
@@ -32,7 +32,7 @@
### 1.1 现象描述
| 维度 | OpenClaw Agent | ZCLAW Agent 当前状态 |
| 维度 | ZCLAW Agent | ZCLAW Agent 当前状态 |
|------|---------------|---------------------|
| **记忆** | 跨会话持久记忆，自动沉淀重要信息 | 每次对话从零开始，无持久记忆 |
| **主动性** | Heartbeat 定时巡检 + Cron 精确调度 | 纯被动响应，用户不问就不动 |
@@ -47,7 +47,7 @@
ZCLAW Agent 的"不聪明"不是模型能力问题，而是**Agent 基础设施缺失**：
```
OpenClaw Agent = LLM + 持久记忆 + 主动调度 + 自我演化的身份 + 技能生态 + 上下文治理
ZCLAW Agent = LLM + 持久记忆 + 主动调度 + 自我演化的身份 + 技能生态 + 上下文治理
ZCLAW Agent = LLM + 临时会话 + 静态配置
↑ 差距在这里：缺少让 Agent 持续成长的基础设施
```
@@ -65,11 +65,11 @@ ZCLAW Agent = LLM + 临时会话 + 静态配置
## 二、竞品 Agent 智能体系深度解剖
### 2.1 OpenClaw：最完整的"可成长 Agent"参考
### 2.1 ZCLAW：最完整的"可成长 Agent"参考
#### 2.1.1 两层记忆系统
OpenClaw 的记忆设计是其核心竞争力：
ZCLAW 的记忆设计是其核心竞争力：
**Layer 1：Daily Logs（短期日记）**
```
@@ -104,7 +104,7 @@ memory/
#### 2.1.2 Heartbeat 引擎（主动心跳）
OpenClaw 的心跳系统让 Agent 从"被动回应者"变为"主动助手"：
ZCLAW 的心跳系统让 Agent 从"被动回应者"变为"主动助手"：
```markdown
# HEARTBEAT.md（用户可编辑的巡检清单）
@@ -224,7 +224,7 @@ git diff # 查看 Agent 的人格变化
### 3.2 各系统评级
| 能力维度 | OpenClaw | NanoClaw | ZeroClaw | ZCLAW 当前 |
| 能力维度 | ZCLAW | NanoClaw | ZeroClaw | ZCLAW 当前 |
|----------|---------|----------|----------|-----------|
| 短期记忆（会话内） | L1 ✅ | L1 ✅ | L1 ✅ | **L1** ✅ |
| 长期记忆（跨会话） | **L2** ✅ | **L2** ✅ | **L2** ✅ | **L0** ❌ |
@@ -241,7 +241,7 @@ git diff # 查看 Agent 的人格变化
### 3.3 差距总结
**ZCLAW 当前处于 L1（会话感知）级别，而 OpenClaw 已经达到 L4（自我演化）级别。**
**ZCLAW 当前处于 L1（会话感知）级别，而 ZCLAW 已经达到 L4（自我演化）级别。**
差距不是线性的——每一级的价值都是指数增长：
- L0→L1：用户体验从"不可用"到"可用"
@@ -257,25 +257,25 @@ git diff # 查看 Agent 的人格变化
| 能力 | 来源 | 价值 | 实现复杂度 |
|------|------|------|-----------|
| **持久记忆系统** | OpenClaw + ZeroClaw | 从 L1 跃迁到 L2 的核心 | 中 |
| **上下文压缩 + 记忆冲刷** | OpenClaw | 无限对话不丢信息 | 中 |
| **工作区身份文件动态化** | OpenClaw | Agent 人格可演化 | 低 |
| **记忆搜索（语义 + 关键词）** | OpenClaw + ZeroClaw | 精确召回历史信息 | 中到高 |
| **持久记忆系统** | ZCLAW + ZeroClaw | 从 L1 跃迁到 L2 的核心 | 中 |
| **上下文压缩 + 记忆冲刷** | ZCLAW | 无限对话不丢信息 | 中 |
| **工作区身份文件动态化** | ZCLAW | Agent 人格可演化 | 低 |
| **记忆搜索（语义 + 关键词）** | ZCLAW + ZeroClaw | 精确召回历史信息 | 中到高 |
### 4.2 强烈建议吸收（P1 — 形成差异化竞争力）
| 能力 | 来源 | 价值 | 实现复杂度 |
|------|------|------|-----------|
| **Heartbeat 主动巡检** | OpenClaw | 从 L2 跃迁到 L3 | 中 |
| **Cron 定时任务** | OpenClaw + NanoClaw | 精确调度能力 | 低到中 |
| **Agent 自我反思循环** | OpenClaw | 行为持续优化 | 中 |
| **Heartbeat 主动巡检** | ZCLAW | 从 L2 跃迁到 L3 | 中 |
| **Cron 定时任务** | ZCLAW + NanoClaw | 精确调度能力 | 低到中 |
| **Agent 自我反思循环** | ZCLAW | 行为持续优化 | 中 |
| **多 Agent 协作框架** | NanoClaw | 复杂任务分工 | 高 |
### 4.3 可选吸收（P2 — 生态化扩展）
| 能力 | 来源 | 价值 | 实现复杂度 |
|------|------|------|-----------|
| **技能市场与自主安装** | OpenClaw | 能力无限扩展 | 高 |
| **技能市场与自主安装** | ZCLAW | 能力无限扩展 | 高 |
| **容器级执行隔离** | NanoClaw | 安全执行环境 | 高 |
| **向量记忆后端可替换** | ZeroClaw | 灵活的记忆架构 | 中 |
@@ -283,7 +283,7 @@ git diff # 查看 Agent 的人格变化
| 能力 | 原因 |
|------|------|
| OpenClaw 的纯文件系统记忆 | ZCLAW 桌面端更适合 SQLite/IndexedDB + 文件混合方案 |
| ZCLAW 的纯文件系统记忆 | ZCLAW 桌面端更适合 SQLite/IndexedDB + 文件混合方案 |
| NanoClaw 的纯 fork 定制模式 | ZCLAW 需要平台化扩展 |
| ZeroClaw 的 Rust 重写 | 当前阶段不值得重写运行时 |
@@ -313,7 +313,7 @@ git diff # 查看 Agent 的人格变化
2. **产品视角**：Agent 主动推送消息，用户的接受边界在哪里？
3. **技术视角**：记忆数据存在哪里最合理？文件系统、SQLite、还是云端？
4. **安全视角**：Agent 能自动修改自己的配置文件，风险可控吗？
5. **差异化视角**：相比 OpenClaw，ZCLAW 的 Agent 智能应该在哪个方向上做得更好？
5. **差异化视角**：相比 ZCLAW，ZCLAW 的 Agent 智能应该在哪个方向上做得更好？
### 5.3 会议议程（3 小时）
@@ -321,7 +321,7 @@ git diff # 查看 Agent 的人格变化
**目标**：团队对"我们的 Agent 差在哪里"形成统一认知
- 演示对比：OpenClaw Agent 的记忆/主动行为 vs ZCLAW Agent 的当前表现
- 演示对比：ZCLAW Agent 的记忆/主动行为 vs ZCLAW Agent 的当前表现
- 走读本文档的 L0-L4 成熟度评估
- 确认：团队是否认同 L1→L2 是当前最关键的跃迁？
@@ -337,7 +337,7 @@ git diff # 查看 Agent 的人格变化
| 方案 | 优点 | 缺点 | 适合场景 |
|------|------|------|---------|
| 纯文件系统（OpenClaw 风格） | 可审查、可 git、透明 | 搜索性能差、并发控制弱 | 单用户/开发者 |
| 纯文件系统（ZCLAW 风格） | 可审查、可 git、透明 | 搜索性能差、并发控制弱 | 单用户/开发者 |
| SQLite + FTS5 | 查询强、结构化、桌面原生 | 不可直接 git | 桌面产品 |
| SQLite + 向量搜索（ZeroClaw 风格） | 语义召回强 | 需要嵌入模型 | 高级记忆 |
| 混合方案：SQLite + Markdown 导出 | 兼顾查询和可审查性 | 同步复杂度 | **推荐方案** |
@@ -375,7 +375,7 @@ git diff # 查看 Agent 的人格变化
**A. Heartbeat 产品化**
核心问题：
- 心跳间隔多少合适？（OpenClaw 默认 30 分钟）
- 心跳间隔多少合适？（ZCLAW 默认 30 分钟）
- 哪些检查项是默认启用的？
- 如何避免"通知骚扰"？
- 桌面端的心跳应该通过什么渠道通知？（系统通知？应用内通知？飞书消息？）
@@ -484,7 +484,7 @@ git diff # 查看 Agent 的人格变化
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Runtime Adapter Layer │ │
│ │ (OpenClaw / OpenFang / Future Native Runtime) │ │
│ │ (ZCLAW / ZCLAW / Future Native Runtime) │ │
│ └─────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
@@ -1192,15 +1192,15 @@ Phase 1-4 完成了底层能力，但用户体验存在断层：
## 十二、总结
**ZCLAW 当前 Agent 与 OpenClaw Agent 的核心差距不在 LLM 能力，而在 Agent 基础设施。**
**ZCLAW 当前 Agent 与 ZCLAW Agent 的核心差距不在 LLM 能力，而在 Agent 基础设施。**
OpenClaw 构建了一套完整的"Agent 成长基础设施"：
ZCLAW 构建了一套完整的"Agent 成长基础设施"：
- **记忆**让 Agent 有了"过去"
- **Heartbeat**让 Agent 有了"主动意识"
- **身份演化**让 Agent 有了"自我成长"
- **上下文治理**让 Agent 有了"无限续航"
ZCLAW 要做的不是复制 OpenClaw，而是：
ZCLAW 要做的不是复制 ZCLAW，而是：
> **在桌面端场景下，构建一套更适合中文用户、更注重隐私、更强调团队协作的 Agent 成长基础设施。**
@@ -1217,8 +1217,8 @@ ZCLAW 要做的不是复制 OpenClaw，而是：
## 附录：参考资料
### 公开技术分析
- [Inside OpenClaw: How the World's Fastest-Growing AI Agent Actually Works Under the Hood](https://dev.to/jiade/inside-openclaw-how-the-worlds-fastest-growing-ai-agent-actually-works-under-the-hood-4p5n)
- [Inside OpenClaw: How a Persistent AI Agent Actually Works](https://dev.to/entelligenceai/inside-openclaw-how-a-persistent-ai-agent-actually-works-1mnk)
- [Inside ZCLAW: How the World's Fastest-Growing AI Agent Actually Works Under the Hood](https://dev.to/jiade/inside-zclaw-how-the-worlds-fastest-growing-ai-agent-actually-works-under-the-hood-4p5n)
- [Inside ZCLAW: How a Persistent AI Agent Actually Works](https://dev.to/entelligenceai/inside-zclaw-how-a-persistent-ai-agent-actually-works-1mnk)
- [ZeroClaw: A Minimal Rust-Based AI Agent Framework for Self-Hosted Systems](https://dev.to/lightningdev123/zeroclaw-a-minimal-rust-based-ai-agent-framework-for-self-hosted-systems-5593)
- [NanoClaw Official Site](https://nanoclaws.io/)

6
docs/analysis/BRAINSTORMING-SESSION-v2.md
View File

@@ -216,9 +216,9 @@ i18n.t('hand.trigger', { name })
## 议题五：风险规避方向
### 5.1 OpenFang 兼容性维护
### 5.1 ZCLAW 兼容性维护
**风险：** OpenFang 版本升级可能导致兼容性问题
**风险：** ZCLAW 版本升级可能导致兼容性问题
**方案：**
@@ -227,7 +227,7 @@ i18n.t('hand.trigger', { name })
| A. 版本锁定 | 低 | 弱 |
| B. 兼容层抽象 | 中 | 中 |
| C. 自动化兼容性测试 | 高 | 强 |
| D. 参与 OpenFang 开发 | 高 | 最强 |
| D. 参与 ZCLAW 开发 | 高 | 最强 |
**结论：** 实施 B + C，建立兼容性测试套件

6
docs/analysis/BRAINSTORMING-SESSION.md
View File

@@ -198,9 +198,9 @@ i18n.t('hand.trigger', { name })
## 五、风险规避方向
### 议题 5.1：OpenFang 兼容性维护
### 议题 5.1：ZCLAW 兼容性维护
**风险：** OpenFang 版本升级可能导致兼容性问题
**风险：** ZCLAW 版本升级可能导致兼容性问题
**方案：**
@@ -209,7 +209,7 @@ i18n.t('hand.trigger', { name })
| A. 版本锁定 | 低 | 弱 |
| B. 兼容层抽象 | 中 | 中 |
| C. 自动化兼容性测试 | 高 | 强 |
| D. 参与 OpenFang 开发 | 高 | 最强 |
| D. 参与 ZCLAW 开发 | 高 | 最强 |
**结论：** 实施 B + C，建立兼容性测试套件

2
docs/analysis/CODE-LEVEL-TODO.md
View File

@@ -161,7 +161,7 @@ export interface RunHistoryEntry { ... }
| 模块 | 文件 | 功能 | 状态 |
|------|------|------|------|
| OpenFang 集成 | `lib.rs` | Gateway 生命周期管理 | ✅ 完整 |
| ZCLAW 集成 | `lib.rs` | Gateway 生命周期管理 | ✅ 完整 |
| Viking Server | `viking_server.rs` | 本地向量数据库 | ✅ 完整 |
| Viking Commands | `viking_commands.rs` | Viking CLI 封装 | ✅ 完整 |
| Browser Automation | `browser/*.rs` | Fantoccini 浏览器控制 | ✅ 完整 |

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

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

6
docs/analysis/ISSUE-TRACKER.md
View File

@@ -119,7 +119,7 @@ gateway/
### Q7: 缺少兼容性测试
**问题描述：**
- 无 OpenFang 版本兼容性测试
- 无 ZCLAW 版本兼容性测试
- 版本升级可能破坏功能
**影响：**
@@ -127,7 +127,7 @@ gateway/
- 问题发现滞后
**修复建议：**
1. 建立 OpenFang 版本矩阵测试
1. 建立 ZCLAW 版本矩阵测试
2. 自动化兼容性测试套件
3. 版本发布前验证
@@ -273,7 +273,7 @@ gateway/
### D2: 旧版 API 兼容代码
**问题描述：**
- 存在旧版 OpenClaw 兼容代码
- 存在旧版 ZCLAW 兼容代码
- 增加体积
**影响：**

2
docs/analysis/OPTIMIZATION-ROADMAP.md
View File

@@ -272,7 +272,7 @@ Q4: D4, D5
| 风险 | 概率 | 影响 | 应对措施 |
|------|------|------|----------|
| OpenFang 版本不兼容 | 中 | 高 | 建立兼容性测试套件 |
| ZCLAW 版本不兼容 | 中 | 高 | 建立兼容性测试套件 |
| 关键人员离职 | 低 | 高 | 文档和知识共享 |
| 竞品快速迭代 | 高 | 中 | 聚焦差异化功能 |
| 技术方案不可行 | 低 | 中 | 技术验证先行 |

14
docs/analysis/PROJECT-SYSTEMATIC-ANALYSIS-REPORT.md
View File

@@ -10,7 +10,7 @@
### 项目概览
ZCLAW 是一个基于 **OpenFang** 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
ZCLAW 是一个基于 **ZCLAW** 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
### 核心数据
@@ -124,7 +124,7 @@ ZCLAW/
```
desktop/src-tauri/src/
├── lib.rs # 入口，OpenFang 集成
├── lib.rs # 入口，ZCLAW 集成
├── main.rs # 主程序
├── viking_commands.rs # OpenViking CLI sidecar
├── viking_server.rs # OpenViking 本地服务器
@@ -188,7 +188,7 @@ desktop/src-tauri/src/
│ browser │ intelligence │ memory │ llm │ secure_storage │
└─────────────────────────────────────────────────────────────┘
↕
OpenFang Kernel / OpenViking
ZCLAW Kernel / OpenViking
```
### 2.2 数据流架构
@@ -199,7 +199,7 @@ desktop/src-tauri/src/
↓
WebSocket / REST
↓
OpenFang Kernel
ZCLAW Kernel
↓
Skills / Hands 执行
```
@@ -563,7 +563,7 @@ interface GatewayFrame {
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| OpenFang 版本不兼容 | 中 | 高 | 兼容性测试套件 |
| ZCLAW 版本不兼容 | 中 | 高 | 兼容性测试套件 |
| LLM API 变更 | 中 | 高 | 抽象层隔离 |
| 性能瓶颈 | 中 | 中 | 监控和优化 |
@@ -605,14 +605,14 @@ interface GatewayFrame {
1. 中国 AI Agent 市场爆发
2. 本地优先隐私诉求增长
3. OpenFang 生态缺口
3. ZCLAW 生态缺口
4. 飞书+企业微信整合需求
5. Skill 市场变现潜力
### 威胁 (Threats)
1. 竞品迭代极快 (Cursor/Windsurf/AutoClaw)
2. OpenFang 上游变化
2. ZCLAW 上游变化
3. LLM API 不稳定
4. 维护成本高

10
docs/analysis/ZCLAW-DEEP-ANALYSIS-v2.md
View File

@@ -9,7 +9,7 @@
### 1.1 项目定位
ZCLAW 是一个基于 OpenFang 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
ZCLAW 是一个基于 ZCLAW 的中文优先 AI Agent 桌面客户端，采用 **Tauri 2.0 (Rust + React 19)** 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
### 1.2 技术栈全景
@@ -60,7 +60,7 @@ ZCLAW 是一个基于 OpenFang 的中文优先 AI Agent 桌面客户端，采用
│ browser │ intelligence │ memory │ llm │ viking │ secure_storage │
└──────────────────────────────────────────────────────────────────┘
↕
OpenFang Kernel / OpenViking
ZCLAW Kernel / OpenViking
```
### 2.2 前端架构分析
@@ -125,14 +125,14 @@ ZCLAW 是一个基于 OpenFang 的中文优先 AI Agent 桌面客户端，采用
**GatewayClient 核心功能：**
- ✅ WebSocket 连接管理（自动重连、心跳）
- ✅ REST API 降级（OpenFang 模式）
- ✅ REST API 降级（ZCLAW 模式）
- ✅ Ed25519 设备认证
- ✅ 流式响应处理（chatStream）
- ✅ 事件订阅机制
**问题：**
- ⚠️ 文件过大（65KB），职责过重
- ⚠️ 部分方法过长（如 handleOpenFangStreamEvent 100+ 行）
- ⚠️ 部分方法过长（如 handleZCLAWStreamEvent 100+ 行）
### 2.3 Rust 后端架构分析
@@ -321,7 +321,7 @@ L2 (Deep): 加载最相关项的完整内容
↓
WebSocket / REST
↓
OpenFang Kernel
ZCLAW Kernel
↓
Skills / Hands 执行
```

18
docs/analysis/ZCLAW-DEEP-ANALYSIS.md
View File

@@ -4,7 +4,7 @@
## 一、项目全景概览
ZCLAW 是一个基于 OpenFang (类 OpenClaw) 定制化的中文优先 AI Agent 桌面客户端，采用 Tauri 2.0 (Rust + React 19) 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
ZCLAW 是一个基于 ZCLAW (类 ZCLAW) 定制化的中文优先 AI Agent 桌面客户端，采用 Tauri 2.0 (Rust + React 19) 架构，目标对标智谱 AutoClaw 和腾讯 QClaw。
### 1.1 技术栈全景
@@ -39,7 +39,7 @@ ZCLAW 是一个基于 OpenFang (类 OpenClaw) 定制化的中文优先 AI Agent
### 2.1 数据流架构
```
用户操作 → React UI → Zustand Store → GatewayClient (WS) → OpenFang Kernel
用户操作 → React UI → Zustand Store → GatewayClient (WS) → ZCLAW Kernel
↘ TauriGateway (IPC) → Rust Backend
↘ VikingClient → OpenViking (向量DB)
```
@@ -121,31 +121,31 @@ HeartbeatConfig, CreateTriggerModal, PersonalitySelector, ScenarioTags, DevQALoo
5. **~~Tauri Rust 后端基本空白~~** → ✅ **已实现 85-90%**（更新 2026-03-20）
**已实现的 Tauri Commands：**
- OpenFang Gateway 管理（start/stop/restart/status/doctor）
- ZCLAW Gateway 管理（start/stop/restart/status/doctor）
- OpenViking 记忆系统（CLI sidecar + 本地服务器）
- 浏览器自动化（Fantoccini WebDriver）
- 安全存储（OS Keyring/Keychain）
- LLM 集成（Doubao/OpenAI/Anthropic）
- 记忆提取和上下文构建
- 进程健康检查（`openfang_health_check`）
- 进程健康检查（`zclaw_health_check`）
6. **配置系统双重标准**
- config.toml + chinese-providers.toml 是 TOML 格式
- 但 README 提到 openclaw.default.json，plugins 使用 plugin.json
- 但 README 提到 zclaw.default.json，plugins 使用 plugin.json
- 配置格式不统一
### 🟡 机会 (Opportunities)
1. **中国 AI Agent 市场爆发** — 智谱/通义/月之暗面/DeepSeek 的中文模型生态成熟
2. **本地优先隐私诉求增长** — 企业和个人对数据隐私要求越来越高
3. **OpenFang 生态缺口** — 市场上没有优质的中文定制化 OpenFang 桌面客户端
3. **ZCLAW 生态缺口** — 市场上没有优质的中文定制化 ZCLAW 桌面客户端
4. **飞书+企业微信整合** — 企业 IM 集成是刚需，特别是在中国市场
5. **Skill 市场变现** — 74 个 Skills 可以发展成社区市场
### 🔵 威胁 (Threats)
1. **竞品迭代极快** — Cursor/Windsurf/AutoClaw/QClaw 都在快速迭代
2. **OpenFang 上游变化** — Gateway Protocol 版本升级可能导致兼容性问题
2. **ZCLAW 上游变化** — Gateway Protocol 版本升级可能导致兼容性问题
3. **LLM API 不稳定** — 中国模型厂商的 API 变更频繁
4. **单人/小团队维护压力** — 50+ 组件、42 个 lib、13 个 store 的维护成本极高
@@ -235,7 +235,7 @@ vector-memory.ts → 应在 Gateway/Rust 端
| 行动 | 验证点 |
|------|--------|
| 安装 OpenFang，验证 Gateway 连接 | 子进程启动 → WS 握手 → 心跳 |
| 安装 ZCLAW，验证 Gateway 连接 | 子进程启动 → WS 握手 → 心跳 |
| 配置中文模型 API Key，测试对话 | 流式响应 → 模型切换 → 上下文管理 |
| 测试飞书 Channel 收发消息 | OAuth → 消息接收 → Agent 处理 → 回复 |
| 测试 Hands 触发完整流程 | 意图识别 → 参数收集 → 审批 → 执行 → 结果 |
@@ -327,7 +327,7 @@ ZCLAW 不应与 ChatGPT/Claude Desktop 竞争"对话体验"，而应聚焦：
### 📌 短期 (2 周)
1. **完成真实 Gateway 连接测试** — 连接 OpenFang Kernel
1. **完成真实 Gateway 连接测试** — 连接 ZCLAW Kernel
2. **中文模型 API 测试** — 验证流式响应
3. **飞书集成测试** — OAuth 和消息收发

14
docs/archive/NEXT_SESSION.md
View File

@@ -7,15 +7,15 @@
## 项目概述
ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，使用 Tauri 2.0 + React + TypeScript 开发。
ZCLAW 是基于 **ZCLAW** (Rust Agent OS) 的 AI Agent 桌面客户端，使用 Tauri 2.0 + React + TypeScript 开发。
**技术栈**:
- 前端: React 19 + TypeScript + Zustand + Tailwind CSS
- 桌面: Tauri 2.0 (Rust)
- 后端: OpenFang Kernel (Rust, 端口 50051)
- 后端: ZCLAW Kernel (Rust, 端口 50051)
- 配置: TOML 格式
**核心价值**: 真实连接 OpenFang Kernel，驱动 Agents / Skills / Hands / Workflows
**核心价值**: 真实连接 ZCLAW Kernel，驱动 Agents / Skills / Hands / Workflows
---
@@ -126,11 +126,11 @@ getSessionMessages: async (sessionId: string) => {
## 关键文件位置
```
ZClaw_openfang/
ZClaw_zclaw/
├── CLAUDE.md # 项目协作规则
├── docs/
│ ├── SYSTEM_ANALYSIS.md # ⭐ 系统分析报告
│ ├── openfang-technical-reference.md # OpenFang 技术参考
│ ├── zclaw-technical-reference.md # ZCLAW 技术参考
│ └── knowledge-base/ # 知识库
│ ├── feature-checklist.md # 功能验证清单
│ └── hands-integration-lessons.md
@@ -161,7 +161,7 @@ ZClaw_openfang/
│ └── translation/SKILL.md
└── config/
├── chinese-providers.toml # LLM 提供商配置
└── openclaw.default.json # ⚠️ 待迁移到 TOML
└── zclaw.default.json # ⚠️ 待迁移到 TOML
```
---
@@ -215,7 +215,7 @@ cd desktop && pnpm tauri:build
1. **所有 UI 文本必须中文**
2. **使用 Zustand 管理状态，不要在组件内直接调用 API**
3. **类型定义放在 `desktop/src/types/` 目录**
4. **OpenFang 端口是 50051，不是 4200**
4. **ZCLAW 端口是 50051，不是 4200**
5. **配置格式是 TOML，不是 JSON/YAML**
6. **WebSocket 路径是 `/ws`**

100
docs/archive/OPENFANG-SETUP-LEGACY.md
View File

@@ -1,12 +1,12 @@
# OpenFang Kernel 配置指南
# ZCLAW Kernel 配置指南
> ⚠️ **已归档**: 此文档仅作历史参考。ZCLAW 现在使用内部 Kernel 架构，无需启动外部 OpenFang 进程。请参阅 [快速启动指南](../quick-start.md) 和 [模型配置指南](../knowledge-base/configuration.md)。
> ⚠️ **已归档**: 此文档仅作历史参考。ZCLAW 现在使用内部 Kernel 架构，无需启动外部 ZCLAW 进程。请参阅 [快速启动指南](../quick-start.md) 和 [模型配置指南](../knowledge-base/configuration.md)。
> 本文档帮助你正确配置 OpenFang Kernel，作为 ZCLAW 的后端执行引擎。
> 本文档帮助你正确配置 ZCLAW Kernel，作为 ZCLAW 的后端执行引擎。
## 概述
OpenFang 是一个用 Rust 构建的生产级 Agent 操作系统（Agent Operating System）。与传统的聊天机器人框架不同，OpenFang 采用"主动执行"范式：Agent 能够按计划自主唤醒、完成任务并报告结果，而无需用户持续提示。
ZCLAW 是一个用 Rust 构建的生产级 Agent 操作系统（Agent Operating System）。与传统的聊天机器人框架不同，ZCLAW 采用"主动执行"范式：Agent 能够按计划自主唤醒、完成任务并报告结果，而无需用户持续提示。
### 核心特性
@@ -31,7 +31,7 @@ OpenFang 是一个用 Rust 构建的生产级 Agent 操作系统（Agent Operati
### 依赖项
OpenFang 是一个独立的单二进制文件（~32MB），无外部依赖。但以下工具可能对某些功能必要：
ZCLAW 是一个独立的单二进制文件（~32MB），无外部依赖。但以下工具可能对某些功能必要：
- **FFmpeg**：视频处理 Hand (Clip) 需要
- **yt-dlp**：YouTube 视频下载需要
@@ -46,18 +46,18 @@ OpenFang 是一个独立的单二进制文件（~32MB），无外部依赖。但
```powershell
# 使用 PowerShell
iwr -useb https://openfang.sh/install.ps1 | iex
iwr -useb https://zclaw.sh/install.ps1 | iex
```
#### macOS / Linux
```bash
curl -fsSL https://openfang.sh/install.sh | bash
curl -fsSL https://zclaw.sh/install.sh | bash
```
### 方式二：手动下载
1. 访问 [GitHub Releases](https://github.com/RightNow-AI/openfang/releases)
1. 访问 [GitHub Releases](https://github.com/RightNow-AI/zclaw/releases)
2. 下载对应平台的二进制文件
3. 将文件放入 PATH 目录
@@ -65,23 +65,23 @@ curl -fsSL https://openfang.sh/install.sh | bash
```powershell
# 下载后移动到用户目录
move openfang.exe C:\Users\<你的用户名>\.local\bin\
move zclaw.exe C:\Users\<你的用户名>\.local\bin\
```
#### macOS / Linux
```bash
chmod +x openfang
sudo mv openfang /usr/local/bin/
chmod +x zclaw
sudo mv zclaw /usr/local/bin/
```
### 方式三：从源码编译
```bash
git clone https://github.com/RightNow-AI/openfang.git
cd openfang
git clone https://github.com/RightNow-AI/zclaw.git
cd zclaw
cargo build --release
# 编译产物位于 target/release/openfang
# 编译产物位于 target/release/zclaw
```
---
@@ -93,15 +93,15 @@ cargo build --release
首次使用需要初始化配置文件：
```bash
openfang init
zclaw init
```
这将在 `~/.openfang/` 目录下创建以下结构：
这将在 `~/.zclaw/` 目录下创建以下结构：
```
~/.openfang/
~/.zclaw/
├── config.toml # 主配置文件
├── openfang.db # SQLite 数据库
├── zclaw.db # SQLite 数据库
├── data/ # 数据目录
│ ├── agents/ # Agent 配置
│ ├── skills/ # 自定义技能
@@ -111,10 +111,10 @@ openfang init
### 2. 配置文件结构
编辑 `~/.openfang/config.toml`：
编辑 `~/.zclaw/config.toml`：
```toml
# OpenFang 主配置文件
# ZCLAW 主配置文件
[general]
# 默认语言
@@ -122,7 +122,7 @@ language = "zh-CN"
# 日志级别: trace, debug, info, warn, error
log_level = "info"
# 数据目录
data_dir = "~/.openfang/data"
data_dir = "~/.zclaw/data"
[model]
# 默认模型提供商
@@ -225,39 +225,39 @@ base_url = "https://api.minimax.chat/v1"
#### 前台运行（调试用）
```bash
openfang start
zclaw start
```
#### 后台守护进程
```bash
# 启动守护进程
openfang daemon start
zclaw daemon start
# 查看状态
openfang status
zclaw status
# 停止守护进程
openfang daemon stop
zclaw daemon stop
```
#### 检查健康状态
```bash
openfang doctor
zclaw doctor
```
---
## 与 ZCLAW 集成
### 配置 ZCLAW 连接 OpenFang
### 配置 ZCLAW 连接 ZCLAW
编辑 ZCLAW 配置文件 `~/.zclaw/config.toml`：
```toml
[gateway]
# OpenFang API 端点
# ZCLAW API 端点
endpoint = "http://127.0.0.1:50051"
# WebSocket 端点
ws_endpoint = "ws://127.0.0.1:50051/ws"
@@ -265,15 +265,15 @@ ws_endpoint = "ws://127.0.0.1:50051/ws"
timeout = 30
[model]
# 使用 OpenFang 的模型路由
# 使用 ZCLAW 的模型路由
use_gateway_routing = true
```
### 验证连接
```bash
# 启动 OpenFang
openfang start
# 启动 ZCLAW
zclaw start
# 在另一个终端启动 ZCLAW
cd desktop && pnpm tauri dev
@@ -360,19 +360,19 @@ chcp 65001
export LANG=zh_CN.UTF-8
```
### 6. 从 OpenClaw 迁移
### 6. 从 ZCLAW 迁移
如果你之前使用 OpenClaw，可以使用迁移工具：
如果你之前使用 ZCLAW，可以使用迁移工具：
```bash
# 迁移所有内容：代理、记忆、技能、配置
openfang migrate --from openclaw
zclaw migrate --from zclaw
# 从特定路径迁移
openfang migrate --from openclaw --path ~/.openclaw
zclaw migrate --from zclaw --path ~/.zclaw
# 先试运行查看变更
openfang migrate --from openclaw --dry-run
zclaw migrate --from zclaw --dry-run
```
---
@@ -381,10 +381,10 @@ openfang migrate --from openclaw --dry-run
### 配置 Hands
Hands 是 OpenFang 的核心创新，每个 Hand 是一个预构建的自主能力包：
Hands 是 ZCLAW 的核心创新，每个 Hand 是一个预构建的自主能力包：
```toml
# ~/.openfang/data/hands/researcher.toml
# ~/.zclaw/data/hands/researcher.toml
[hand]
name = "researcher"
@@ -409,7 +409,7 @@ citation_style = "apa"
### 配置 MCP 服务器
```toml
# ~/.openfang/config.toml
# ~/.zclaw/config.toml
[[mcp_servers]]
name = "filesystem"
@@ -425,7 +425,7 @@ env = { DATABASE_URL = "postgresql://localhost/mydb" }
### 配置渠道适配器
```toml
# ~/.openfang/config.toml
# ~/.zclaw/config.toml
[[channels]]
type = "feishu"
@@ -474,34 +474,34 @@ max_iterations = 50
```bash
# 实时日志
openfang logs -f
zclaw logs -f
# 按级别过滤
openfang logs --level error
zclaw logs --level error
# 按时间范围
openfang logs --since "2024-01-01" --until "2024-01-02"
zclaw logs --since "2024-01-01" --until "2024-01-02"
```
### 监控指标
```bash
# 系统状态
openfang status
zclaw status
# 详细健康检查
openfang doctor --verbose
zclaw doctor --verbose
# 使用统计
openfang usage --daily
zclaw usage --daily
```
---
## 相关链接
- [OpenFang 官方文档](https://openfang.sh/)
- [GitHub 仓库](https://github.com/RightNow-AI/openfang)
- [ZCLAW 官方文档](https://zclaw.sh/)
- [GitHub 仓库](https://github.com/RightNow-AI/zclaw)
- [中文模型配置](./chinese-models.md)
- [ZCLAW 主文档](../../README.md)
@@ -509,6 +509,6 @@ openfang usage --daily
## 获取帮助
- **命令行帮助**：`openfang --help` 或 `openfang <command> --help`
- **GitHub Issues**：https://github.com/RightNow-AI/openfang/issues
- **命令行帮助**：`zclaw --help` 或 `zclaw <command> --help`
- **GitHub Issues**：https://github.com/RightNow-AI/zclaw/issues
- **社区讨论**：https://deepseek.club/t/topic/996

48
docs/archive/SYSTEM_ANALYSIS.md
View File

@@ -1,7 +1,7 @@
# ZCLAW 系统偏离分析与演化路线图
**分析日期**: 2026-03-14 (更新: 2026-03-15)
**分析版本**: OpenFang v0.4.0 + ZClaw Desktop v0.2.0
**分析版本**: ZCLAW v0.4.0 + ZClaw Desktop v0.2.0
**目的**: 识别系统当前偏离点，规划后续演化方向
**Skills 集成**: ✅ agency-agents 仓库迁移完成！
@@ -11,8 +11,8 @@
### 1.1 项目定位
ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核心价值：
- 真实连接 OpenFang Kernel
ZCLAW 是基于 **ZCLAW** (Rust Agent OS) 的 AI Agent 桌面客户端，核心价值：
- 真实连接 ZCLAW Kernel
- 真实驱动 Agents / Skills / Hands / Workflows
- 真实读写 TOML 配置与工作区
- 真实反映运行时状态与审计日志
@@ -126,7 +126,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
| code-review | ✅ 已定义 | 审查代码, code review |
| translation | ✅ 已定义 | 翻译, translate |
**偏离**: OpenFang 内置 60+ 技能，ZClaw 仅定义 4 个。
**偏离**: ZCLAW 内置 60+ 技能，ZClaw 仅定义 4 个。
#### Hands 目录
@@ -146,12 +146,12 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
| 文件 | 格式 | 用途 | 状态 |
|------|------|------|------|
| `chinese-providers.toml` | TOML | LLM 提供商配置 | ✅ OpenFang |
| `openclaw.default.json` | JSON | OpenClaw 遗留配置 | ⚠️ 待迁移 |
| `chinese-providers.toml` | TOML | LLM 提供商配置 | ✅ ZCLAW |
| `zclaw.default.json` | JSON | ZCLAW 遗留配置 | ⚠️ 待迁移 |
| `SOUL.md` / `AGENTS.md` | Markdown | Agent 人格定义 | ✅ |
| `USER.md` | Markdown | 用户偏好 | ✅ |
**偏离**: 保留 OpenClaw JSON 配置，需迁移到 OpenFang TOML。
**偏离**: 保留 ZCLAW JSON 配置，需迁移到 ZCLAW TOML。
### 2.4 类型定义偏离
@@ -174,7 +174,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
│ 偏离根因分析 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. OpenFang API 不完整 (30%) │
│ 1. ZCLAW API 不完整 (30%) │
│ ├── /api/audit/logs 返回 404 │
│ ├── /api/security/status 返回 404 │
│ └── 部分端点未在 v0.4.0 实现 │
@@ -186,7 +186,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
│ │
│ 3. 设计决策 (20%) │
│ ├── 使用 Mock 数据便于 UI 开发 │
│ ├── 保留 OpenClaw 兼容性 │
│ ├── 保留 ZCLAW 兼容性 │
│ └── 逐步迁移而非一次性重写 │
│ │
│ 4. 技术债务 (10%) │
@@ -202,7 +202,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
#### 可接受的偏离（不修正）
1. **OpenAI 兼容 API 缺失** - 非核心功能，第三方集成用
2. **Credits 页面硬编码** - 依赖 OpenFang 积分系统 API
2. **Credits 页面硬编码** - 依赖 ZCLAW 积分系统 API
3. **About 版本检查** - 可延后实现
#### 需要修正的偏离（必须修正）
@@ -249,15 +249,15 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
### Phase 3: 配置迁移 (P1)
**目标**: 完成从 OpenClaw 到 OpenFang 的配置迁移
**目标**: 完成从 ZCLAW 到 ZCLAW 的配置迁移
**时间**: 1 周
| 任务 | 说明 | 状态 |
|------|------|------|
| 迁移 openclaw.default.json | 转换为 config.toml | ✅ 已完成 |
| 补充主 config.toml | OpenFang 服务器配置 | ✅ 已完成 |
| 清理 OpenClaw 遗留代码 | 移除兼容层 | ✅ 已完成 |
| 迁移 zclaw.default.json | 转换为 config.toml | ✅ 已完成 |
| 补充主 config.toml | ZCLAW 服务器配置 | ✅ 已完成 |
| 清理 ZCLAW 遗留代码 | 移除兼容层 | ✅ 已完成 |
### Phase 4: 类型系统完善 (P2)
@@ -337,8 +337,8 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
| 债务 | 位置 | 影响 | 清理方案 | 状态 |
|------|------|------|----------|------|
| ~~OpenClaw JSON 配置~~ | ~~`config/openclaw.default.json`~~ | ~~配置格式混合~~ | ~~迁移到 TOML~~ | ✅ 已清理 |
| ~~缺少主配置文件~~ | ~~`config/`~~ | ~~OpenFang 配置不完整~~ | ~~创建 config.toml~~ | ✅ 已清理 |
| ~~ZCLAW JSON 配置~~ | ~~`config/zclaw.default.json`~~ | ~~配置格式混合~~ | ~~迁移到 TOML~~ | ✅ 已清理 |
| ~~缺少主配置文件~~ | ~~`config/`~~ | ~~ZCLAW 配置不完整~~ | ~~创建 config.toml~~ | ✅ 已清理 |
### 5.3 类型层面
@@ -378,10 +378,10 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
### 6.3 Phase 3 完成标准
- [x] 创建 OpenFang config.toml
- [x] 迁移 OpenClaw JSON 配置到 TOML
- [x] OpenClaw JSON 配置已归档到 docs/archive/openclaw-legacy/
- [x] 默认路径从 ~/.openclaw 更新为 ~/.openfang
- [x] 创建 ZCLAW config.toml
- [x] 迁移 ZCLAW JSON 配置到 TOML
- [x] ZCLAW JSON 配置已归档到 docs/archive/zclaw-legacy/
- [x] 默认路径从 ~/.zclaw 更新为 ~/.zclaw
- [x] 默认端口从 18789 更新为 50051
### 6.4 Phase 4 完成标准
@@ -427,7 +427,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| OpenFang API 变更 | 中 | 高 | 版本锁定，变更日志跟踪 |
| ZCLAW API 变更 | 中 | 高 | 版本锁定，变更日志跟踪 |
| Session API 未实现 | 高 | 高 | 使用 localStorage 临时方案 |
| 安全层 API 未实现 | 高 | 中 | UI 显示"等待 API"状态 |
| 工作流编辑器复杂度高 | 中 | 中 | 先实现简化版，逐步增强 |
@@ -459,7 +459,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
| 类别 | 组件数 | 完全实现 | 部分实现 | 未实现 |
|------|--------|----------|----------|--------|
| 核心功能 | 5 | 5 | 0 | 0 |
| OpenFang 特有 | 10 | 10 | 0 | 0 |
| ZCLAW 特有 | 10 | 10 | 0 | 0 |
| 设置页面 | 10 | 10 | 0 | 0 |
| Team 协作 | 5 | 5 | 0 | 0 |
| **总计** | **30** | **28** | **0** | **2** |
@@ -516,7 +516,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
* ✅ 添加分身、Hands、工作流、团队四个主功能入口
* 设置页面优化:
* ✅ 主题切换持久化 - 连接 `gatewayStore.saveQuickConfig`
* ✅ 移除 OpenFang 后端下载提示，简化 UI
* ✅ 移除 ZCLAW 后端下载提示，简化 UI
* ✅ 用量统计增强 - 时间范围筛选 (7天/30天/全部)
* ✅ 统计卡片 - 会话数、消息数、输入/输出 Token
* ✅ Token 使用概览条形图
@@ -593,7 +593,7 @@ ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，核
* ✅ `gatewayStore.test.ts` (17 tests)
* ✅ `chatStore.test.ts` (11 tests)
* 集成测试:
* ✅ `openfang-api.test.ts` (34 tests) - MockServer API 测试
* ✅ `zclaw-api.test.ts` (34 tests) - MockServer API 测试
* ✅ `general-settings.test.tsx` (2 tests) - 设置 UI 测试
* 测试总数: 148 tests ✅
* 代码质量:

66
docs/archive/ZCLAW_NEXT_EVOLUTION_STRATEGY.md
View File

@@ -2,7 +2,7 @@
> **文档日期**：2026-03-15
> **适用对象**：项目负责人、架构负责人、客户端/后端/平台研发、测试与产品团队
> **文档目的**：基于 OpenClaw / NanoClaw / ZeroClaw 等相关系统的公开资料与当前仓库现状，形成可执行的下一阶段演化决策依据
> **文档目的**：基于 ZCLAW / NanoClaw / ZeroClaw 等相关系统的公开资料与当前仓库现状，形成可执行的下一阶段演化决策依据
> **说明**：用户需求中提到 `zeraoclaw`。基于公开可验证资料，当前最接近且资料完备的目标项目为 `ZeroClaw`，本报告按 `ZeroClaw` 纳入对比。如后续确认另有特定项目，可在同一分析框架下快速替换。
>
> **关联文档**：本文档聚焦**架构层**的全景对比与演化方案。关于 **Agent 智能层**（记忆系统、主动引擎、自我演化、上下文治理等）的深度差距分析与实施方案，请参阅 [`ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md`](./ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md)。
@@ -16,7 +16,7 @@
当前项目已经具备继续独立演化的基础，但从仓库现状看，仍存在三类关键问题：
- **叙事未统一**
- 仓库内同时存在 `OpenClaw 定制化`、`OpenFang 迁移`、`独立系统演化` 三套表述。
- 仓库内同时存在 `ZCLAW 定制化`、`ZCLAW 迁移`、`独立系统演化` 三套表述。
- 这说明产品定位和架构边界还没有形成统一的外部口径与内部治理口径。
- **能力边界未完全内聚**
@@ -25,7 +25,7 @@
- **下一阶段不宜继续做“上游壳层产品”**
- 对比结果显示：
- `OpenClaw` 的优势在于生态广、能力全、社区强。
- `ZCLAW` 的优势在于生态广、能力全、社区强。
- `NanoClaw` 的优势在于小而可控、容器隔离、极易定制。
- `ZeroClaw` 的优势在于性能、可移植性、部署效率与 trait 化扩展。
- 对 ZCLAW 最优的路径不是简单“选边站队”，而是**形成自己的产品控制面与领域模型，在运行时层通过适配器吸收上游优势**。
@@ -43,7 +43,7 @@
- 插件市场、配置中心、审计与运营面板
- **下层**：将具体运行时封装为可替换适配器
- `OpenClaw Adapter`
- `ZCLAW Adapter`
- `ZeroClaw-style Adapter`
- `NanoClaw-style Secure Sandbox Adapter`
- 后续保留 `ZCLAW Native Runtime` 的演化空间
@@ -62,10 +62,10 @@
从当前仓库文档可见：
- `README.md` 仍以 **OpenClaw 定制版** 为主叙述。
- `docs/architecture-v2.md` 描述的是 **OpenClaw + Tauri + 自定义插件** 的 v2 架构。
- `docs/SYSTEM_ANALYSIS.md` 又显示项目已经大量引入 **OpenFang 风格能力与 API 面**。
- 其他文档还包含对 OpenFang 迁移、ZeroClaw/NanoClaw/OpenClaw 生态分析等内容。
- `README.md` 仍以 **ZCLAW 定制版** 为主叙述。
- `docs/architecture-v2.md` 描述的是 **ZCLAW + Tauri + 自定义插件** 的 v2 架构。
- `docs/SYSTEM_ANALYSIS.md` 又显示项目已经大量引入 **ZCLAW 风格能力与 API 面**。
- 其他文档还包含对 ZCLAW 迁移、ZeroClaw/NanoClaw/ZCLAW 生态分析等内容。
这说明项目技术上已经不再只是“某个上游的 UI 壳层”，而是在向一个更独立的产品系统演化；但**架构叙事、模块边界和对外定位还没有完全收敛**。
@@ -88,7 +88,7 @@
本次纳入对比的主要系统：
- **OpenClaw**
- **ZCLAW**
- **NanoClaw**
- **ZeroClaw**
- **ZCLAW 当前系统**（作为被决策对象）
@@ -122,9 +122,9 @@
| 系统 | 核心定位 | 技术路线 | 适合场景 | 主要优势 | 主要代价 |
|------|----------|----------|----------|----------|----------|
| **OpenClaw** | 功能完备的个人 AI 助手与 Gateway 控制平面 | Node.js + TypeScript + 多端/多渠道生态 | 多渠道接入、完整能力复用、社区协作 | 生态成熟、通道丰富、能力全 | 复杂度高、资源占用较高 |
| **ZCLAW** | 功能完备的个人 AI 助手与 Gateway 控制平面 | Node.js + TypeScript + 多端/多渠道生态 | 多渠道接入、完整能力复用、社区协作 | 生态成熟、通道丰富、能力全 | 复杂度高、资源占用较高 |
| **NanoClaw** | 轻量、可理解、容器隔离的个人 AI 助手 | 单 Node 进程 + Docker/Apple Container + Claude Agent SDK | 个人定制、快速 fork、强隔离 | 架构简单、容器隔离、改造门槛低 | 生态广度不足、对 Claude 体系依赖更强 |
| **ZeroClaw** | Rust 单二进制、强调高性能与可替换组件的自主 Agent 运行时 | Rust + trait 化模块 + binary-first | 边缘部署、低资源环境、性能敏感场景 | 低内存、快启动、跨平台部署轻量 | 生态成熟度仍弱于 OpenClaw |
| **ZeroClaw** | Rust 单二进制、强调高性能与可替换组件的自主 Agent 运行时 | Rust + trait 化模块 + binary-first | 边缘部署、低资源环境、性能敏感场景 | 低内存、快启动、跨平台部署轻量 | 生态成熟度仍弱于 ZCLAW |
| **ZCLAW 当前系统** | 已形成自有产品控制面雏形的桌面 Agent 平台 | Tauri + React + Store + 上游运行时耦合能力 | 中文化产品、桌面交互、企业/团队可视化 | UI/产品层较完整、定制能力强 | 上下游边界仍混杂、叙事未统一 |
---
@@ -133,7 +133,7 @@
## 5.1 技术架构对比
### OpenClaw
### ZCLAW
架构核心是 **Gateway 作为统一控制平面**：
@@ -169,7 +169,7 @@
最适合 ZCLAW 的不是复制任何一方，而是组合三者优点：
- 学 OpenClaw 的 **控制平面与生态广度**
- 学 ZCLAW 的 **控制平面与生态广度**
- 学 NanoClaw 的 **安全隔离与可理解性**
- 学 ZeroClaw 的 **适配器化和低负载运行时设计**
@@ -177,7 +177,7 @@
## 5.2 核心功能对比
| 维度 | OpenClaw | NanoClaw | ZeroClaw | 对 ZCLAW 的启示 |
| 维度 | ZCLAW | NanoClaw | ZeroClaw | 对 ZCLAW 的启示 |
|------|----------|----------|----------|------------------|
| **多渠道接入** | 强，覆盖广 | 中，靠 skills 扩展 | 中，强调可插拔 | ZCLAW 应保留渠道抽象层，不把单一 IM 深绑在 UI 上 |
| **会话与消息控制平面** | 强 | 中 | 中到强 | ZCLAW 要沉淀自己的 `Conversation/Session/Run` 模型 |
@@ -189,7 +189,7 @@
### 判断
- 如果目标是**尽快做全功能产品**，OpenClaw 价值最高。
- 如果目标是**尽快做全功能产品**，ZCLAW 价值最高。
- 如果目标是**单人/小团队快速安全定制**，NanoClaw 的方法更高效。
- 如果目标是**高性能、可替换、长期独立演化**，ZeroClaw 的路线更先进。
@@ -201,10 +201,10 @@ ZCLAW 应把自己的主轴明确为：**产品化桌面控制面 + 中文场景
### 可验证的公开信息
- **OpenClaw**
- **ZCLAW**
- 运行依赖 `Node.js >= 22`
- 社区规模极大，功能体系最重
- 从 ZeroClaw 官方 benchmark 描述中可见，OpenClaw 需要额外 Node 运行时开销，内存画像明显高于 Rust 单二进制方案
- 从 ZeroClaw 官方 benchmark 描述中可见，ZCLAW 需要额外 Node 运行时开销，内存画像明显高于 Rust 单二进制方案
- **ZeroClaw**
- 官方 benchmark 示例给出：
@@ -243,7 +243,7 @@ ZCLAW 若继续强化桌面端与 7x24 运行能力，必须尽快解决两个
## 5.4 扩展性对比
### OpenClaw
### ZCLAW
扩展生态最强，适合“接入更多能力”；但产品二开时要承担：
@@ -282,7 +282,7 @@ ZCLAW 的扩展性应该分三层设计：
## 5.5 兼容性对比
| 维度 | OpenClaw | NanoClaw | ZeroClaw | 对 ZCLAW 的建议 |
| 维度 | ZCLAW | NanoClaw | ZeroClaw | 对 ZCLAW 的建议 |
|------|----------|----------|----------|------------------|
| **与现有 ZCLAW 文档/代码语义贴近度** | 高 | 中 | 中 | 短期最适合作为兼容基线 |
| **桌面端交互兼容性** | 高 | 中 | 中 | 通过中间协议层抽象 |
@@ -302,7 +302,7 @@ ZCLAW 的扩展性应该分三层设计：
## 5.6 安全与治理对比
### OpenClaw
### ZCLAW
安全模型强调：
@@ -349,7 +349,7 @@ ZCLAW 必须形成自己的安全治理分层：
## 5.7 社区支持对比
### OpenClaw
### ZCLAW
依据官方 GitHub 页面：
@@ -369,7 +369,7 @@ ZCLAW 必须形成自己的安全治理分层：
- Releases/Tags：公开可见较少
- 社区组织方式更偏 Discord + 个人定制 fork 模式
说明其讨论热度不低，但工程治理和生态标准化程度相对弱于 OpenClaw。
说明其讨论热度不低，但工程治理和生态标准化程度相对弱于 ZCLAW。
### ZeroClaw
@@ -397,7 +397,7 @@ ZCLAW 必须形成自己的安全治理分层：
## 6.1 应该吸收的能力
### 来自 OpenClaw
### 来自 ZCLAW
- 多渠道控制平面理念
- 会话/消息/工具事件统一流模型
@@ -482,7 +482,7 @@ ZCLAW 必须形成自己的安全治理分层：
讨论三种备选路线：
- **路线 A：继续深度绑定 OpenClaw 生态**
- **路线 A：继续深度绑定 ZCLAW 生态**
- **路线 B：向 ZeroClaw/NanoClaw 风格的轻量内核迁移**
- **路线 C：构建 ZCLAW Core + Adapter 的独立架构**
@@ -564,7 +564,7 @@ ZCLAW 必须形成自己的安全治理分层：
## 8.1 备选技术路线
### 路线 A：继续以 OpenClaw 为单一主干
### 路线 A：继续以 ZCLAW 为单一主干
**优点**：
@@ -635,7 +635,7 @@ ZCLAW 必须形成自己的安全治理分层：
负责：
- OpenClaw Adapter
- ZCLAW Adapter
- ZeroClaw-style Adapter
- NanoClaw-style Sandbox Adapter
- 后续 Native Runtime Adapter
@@ -702,7 +702,7 @@ ZCLAW 必须形成自己的安全治理分层：
### 关键任务
- 建立 `RuntimeAdapter` 接口
- 首先实现 `OpenClawAdapter`
- 首先实现 `ZCLAWAdapter`
- 将当前 gateway client / store 中的协议特化逻辑迁出
- 建立 adapter contract tests
- 对连接、流式输出、工具调用、配置读写、会话管理做统一抽象
@@ -875,7 +875,7 @@ ZCLAW 必须形成自己的安全治理分层：
|--------|------|----------|
| 第 1-2 周 | 统一叙事与边界 | ADR、系统边界图、耦合点清单 |
| 第 3-5 周 | 统一领域模型 | Canonical schema、配置模型、事件模型 |
| 第 6-9 周 | Adapter 层落地 | RuntimeAdapter、OpenClawAdapter、合同测试 |
| 第 6-9 周 | Adapter 层落地 | RuntimeAdapter、ZCLAWAdapter、合同测试 |
| 第 10-13 周 | 平台能力增强 | Workflow/Approval/Team 等独立能力强化 |
| 第 14-16 周 | 安全与产品化 | 安全策略、基准测试、插件规范、发布策略 |
@@ -951,7 +951,7 @@ ZCLAW 下一阶段最重要的工作，不是继续在某个上游上“加功
- **战略上**：选择 `ZCLAW Core + Runtime Adapter` 作为主路线。
- **组织上**：通过专题头脑风暴会议统一路线与边界。
- **实施上**：优先做叙事统一、领域模型统一、适配器收口三件事。
- **价值上**：把 OpenClaw 的生态、NanoClaw 的隔离思路、ZeroClaw 的轻量架构，吸收到 ZCLAW 自己的产品体系中。
- **价值上**：把 ZCLAW 的生态、NanoClaw 的隔离思路、ZeroClaw 的轻量架构，吸收到 ZCLAW 自己的产品体系中。
如果这一轮推进顺利，ZCLAW 将不再只是“基于某个框架的定制版”，而会成为一个**能够独立定义产品、独立定义扩展模型、独立定义演化节奏**的系统。
@@ -964,16 +964,16 @@ ZCLAW 下一阶段最重要的工作，不是继续在某个上游上“加功
- `README.md`
- `docs/architecture-v2.md`
- `docs/SYSTEM_ANALYSIS.md`
- `docs/openclaw-to-openfang-migration-brainstorm.md`
- `docs/zclaw-to-zclaw-migration-brainstorm.md`
- `docs/claw-ecosystem-deep-dive-report.md`
### 公开资料（本次已核验部分）
- OpenClaw 官方仓库：`https://github.com/openclaw/openclaw`
- OpenClaw 官方文档入口：`https://docs.openclaw.ai`
- ZCLAW 官方仓库：`https://github.com/zclaw/zclaw`
- ZCLAW 官方文档入口：`https://docs.zclaw.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 与可稳定访问的官方摘要信息，不对未成功直读页面做超出摘要范围的延展解释。
> 注：部分官方文档页在本次抓取过程中存在超时，因此文中对 ZCLAW 官方文档细节的引用，优先采用其官方 GitHub README 与可稳定访问的官方摘要信息，不对未成功直读页面做超出摘要范围的延展解释。

60
docs/archive/architecture-v2.md
View File

@@ -1,7 +1,7 @@
# ZCLAW v2 架构设计 — 基于 OpenClaw 定制化
# ZCLAW v2 架构设计 — 基于 ZCLAW 定制化
**日期**: 2026-03-11
**定位**: 像 AutoClaw 一样，对 OpenClaw 进行定制化封装，打造 Tauri 桌面版
**定位**: 像 AutoClaw 一样，对 ZCLAW 进行定制化封装，打造 Tauri 桌面版
---
@@ -22,14 +22,14 @@
│ │ Tauri Commands │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Rust Sidecar / Bridge │ │
│ │ • 管理 OpenClaw Gateway 子进程生命周期 │ │
│ │ • 管理 ZCLAW Gateway 子进程生命周期 │ │
│ │ • WebSocket 客户端连接 Gateway │ │
│ │ • 转发 Gateway 事件到前端 │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│ WebSocket (ws://127.0.0.1:18789)
┌─────────────────────────────────────────────────────────┐
│ OpenClaw Gateway (Node.js daemon) │
│ ZCLAW Gateway (Node.js daemon) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Agent │ │ Skills │ │ Sessions │ │ Heartbeat │ │
│ │ Runtime │ │ System │ │ Manager │ │ Engine │ │
@@ -65,9 +65,9 @@
## 二、核心设计决策
### 1. OpenClaw 作为执行引擎
### 1. ZCLAW 作为执行引擎
**不重新发明轮子**。OpenClaw 已经实现了：
**不重新发明轮子**。ZCLAW 已经实现了：
- ✅ 真实工具执行 (bash/file/browser)
- ✅ Skills 系统 (SKILL.md + 渐进式披露)
- ✅ MCP 协议支持
@@ -85,11 +85,11 @@ AutoClaw 用的是自己的桌面框架，QClaw 用 Electron。我们用 **Tauri
- 更小体积 (~10MB vs Electron ~150MB)
- 更好性能 (Rust native)
- 系统级集成能力
- 管理 OpenClaw Gateway 子进程
- 管理 ZCLAW Gateway 子进程
### 3. 自定义插件做差异化
通过 OpenClaw 的 Plugin API 添加中国特色功能：
通过 ZCLAW 的 Plugin API 添加中国特色功能：
| 插件 | 功能 |
|------|------|
@@ -109,7 +109,7 @@ ZClaw/
│ ├── src-tauri/ # Rust 后端
│ │ ├── src/
│ │ │ ├── main.rs # Tauri 入口
│ │ │ ├── gateway.rs # OpenClaw Gateway 子进程管理
│ │ │ ├── gateway.rs # ZCLAW Gateway 子进程管理
│ │ │ ├── ws_client.rs # WebSocket 客户端
│ │ │ └── commands.rs # Tauri Commands (前端调用)
│ │ ├── Cargo.toml
@@ -141,7 +141,7 @@ ZClaw/
│ │ └── protocol.ts # Gateway 协议类型定义
│ └── package.json
│
├── plugins/ # ZCLAW 自定义 OpenClaw 插件
├── plugins/ # ZCLAW 自定义 ZCLAW 插件
│ ├── zclaw-feishu/ # 飞书频道插件
│ │ ├── index.ts
│ │ ├── plugin.json # 插件清单
@@ -173,7 +173,7 @@ ZClaw/
│ └── SKILL.md
│
├── config/ # ZCLAW 默认配置
│ ├── openclaw.default.json # 预设的 OpenClaw 配置
│ ├── zclaw.default.json # 预设的 ZCLAW 配置
│ ├── SOUL.md # 默认人格
│ ├── AGENTS.md # 默认 Agent 指令
│ ├── IDENTITY.md # 默认身份
@@ -181,7 +181,7 @@ ZClaw/
│
├── scripts/ # 构建/安装脚本
│ ├── setup.ts # 首次设置脚本
│ ├── install-openclaw.ts # OpenClaw 安装检测
│ ├── install-zclaw.ts # ZCLAW 安装检测
│ └── register-plugins.ts # 注册自定义插件
│
├── docs/
@@ -204,16 +204,16 @@ ZClaw/
| AutoClaw 功能 | ZCLAW 实现 |
|---|---|
| **通用** (账号/主题/开机启动/工具调用显示) | Tauri 窗口设置 + Gateway config |
| **用量统计** (会话/消息/Token 按模型分) | 读取 OpenClaw sessions JSONL + 统计 |
| **用量统计** (会话/消息/Token 按模型分) | 读取 ZCLAW sessions JSONL + 统计 |
| **积分详情** | 自定义积分系统 (可选) |
| **模型与API** (内置+自定义模型+Gateway URL) | `openclaw config` + Provider Plugin |
| **MCP 服务** (File System/Web Fetch/+添加) | 读取 OpenClaw MCP 配置 + UI 管理 |
| **模型与API** (内置+自定义模型+Gateway URL) | `zclaw config` + Provider Plugin |
| **MCP 服务** (File System/Web Fetch/+添加) | 读取 ZCLAW MCP 配置 + UI 管理 |
| **技能** (SKILL.md 管理/额外目录) | 读取 Skills 目录 + UI 管理 |
| **IM 频道** (添加/管理/快速添加飞书) | Channel Plugin 配置 UI |
| **工作区** (项目目录/文件限制/上下文保存/文件监听) | `agents.defaults.workspace` + sandbox 配置 |
| **数据与隐私** (本地路径/优化计划) | OpenClaw 数据目录 + 隐私配置 |
| **数据与隐私** (本地路径/优化计划) | ZCLAW 数据目录 + 隐私配置 |
| **提交反馈** | 自定义反馈表单 |
| **关于** (版本/更新) | 显示 ZCLAW + OpenClaw 版本 |
| **关于** (版本/更新) | 显示 ZCLAW + ZCLAW 版本 |
### AutoClaw 主界面 → ZCLAW 对标
@@ -231,7 +231,7 @@ ZClaw/
## 五、WebSocket 通信协议
ZCLAW Tauri 客户端通过标准 OpenClaw Gateway 协议通信：
ZCLAW Tauri 客户端通过标准 ZCLAW Gateway 协议通信：
### 连接握手
```json
@@ -277,7 +277,7 @@ tick → 定时心跳
## 六、开发分期
### Phase 1: 基础连通 (当前优先)
1. 安装 OpenClaw 并验证 Gateway 可运行
1. 安装 ZCLAW 并验证 Gateway 可运行
2. 创建 Tauri 项目结构 (保留现有 desktop/)
3. 实现 Gateway 子进程管理 (Rust sidecar)
4. 实现 WebSocket 客户端连接
@@ -286,7 +286,7 @@ tick → 定时心跳
### Phase 2: 自定义插件
1. 实现 `@zclaw/chinese-models` Provider Plugin (智谱GLM/Qwen/Kimi)
2. 实现 `@zclaw/feishu` Channel Plugin
3. 注册插件到 OpenClaw Gateway
3. 注册插件到 ZCLAW Gateway
### Phase 3: 完整 UI
1. 实现设置页面体系 (对标 AutoClaw 10 个页面)
@@ -310,18 +310,18 @@ tick → 定时心跳
- `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/core/remote-execution/` → ZCLAW 自带工具执行
- `src/core/task-orchestration/` → ZCLAW Agent Loop 自带
- `src/core/multi-agent/` → 改为 ZCLAW agents.list 多 Agent
- `src/core/memory/` → ZCLAW Memory Plugin 自带
- `src/core/proactive/` → ZCLAW Heartbeat Engine 自带
- `src/im/gateway.ts` → ZCLAW Channel 系统自带
- `src/app.ts` → ZCLAW Gateway 就是 app
- `src/api/` → 通过 WebSocket + Tauri Commands 替代
- `src/db/` → OpenClaw 自带 SQLite
- `src/config/` → OpenClaw 配置系统替代
- `src/db/` → ZCLAW 自带 SQLite
- `src/config/` → ZCLAW 配置系统替代
---
*本架构设计基于对 OpenClaw 官方文档 (docs.openclaw.ai) 的深度研究，
*本架构设计基于对 ZCLAW 官方文档 (docs.zclaw.ai) 的深度研究，
参考 AutoClaw v0.2.12 的 13 张界面截图进行功能对标。*

22
docs/archive/completed-plans/ZCLAW_OPENVIKING_INTEGRATION_PLAN.md
View File

@@ -34,7 +34,7 @@
### 1.3 OpenViking 的量化优势（基于官方评测）
| 指标 | OpenClaw 原生记忆 | OpenClaw + LanceDB | OpenClaw + OpenViking | 提升幅度 |
| 指标 | ZCLAW 原生记忆 | ZCLAW + LanceDB | ZCLAW + OpenViking | 提升幅度 |
|------|------------------|--------------------|-----------------------|---------|
| **任务完成率** | 35.65% | 44.55% | **52.08%** | +46% vs 原生 |
| **输入 Token 消耗** | 24,611,530 | 51,574,530 | **4,264,396** | **-83%** vs 原生 |
@@ -48,7 +48,7 @@
原因：
1. **效果更好**：目录递归检索 >> 扁平向量搜索，任务完成率提升 46%
2. **成本更低**：L0/L1/L2 分层加载，Token 消耗降低 83-91%
3. **开发更快**：已有 OpenClaw 记忆插件，可直接适配
3. **开发更快**：已有 ZCLAW 记忆插件，可直接适配
4. **架构更优**：`viking://` 文件系统范式天然统一了记忆、资源、技能
5. **生态对齐**：火山引擎/字节跳动出品，与 ZCLAW 的中国市场定位高度契合
@@ -80,7 +80,7 @@
| 预研任务 | 负责部门 | 输出物 |
|---------|---------|-------|
| 本地部署 OpenViking Server 并跑通 Quick Start | 基础设施 | 部署文档 + 性能基准 |
| 阅读 OpenClaw 记忆插件源码，评估适配 ZCLAW 的工作量 | 后端 | 适配方案评估报告 |
| 阅读 ZCLAW 记忆插件源码，评估适配 ZCLAW 的工作量 | 后端 | 适配方案评估报告 |
| 设计 ZCLAW 桌面端记忆面板 UX 原型 | 产品 + 前端 | Figma/草图原型 |
| 测试 OpenViking 在中文场景下的检索效果 | AI/算法 | 检索效果报告 |
| 评估 Tauri 进程中嵌入 OpenViking Python 服务的可行性 | 基础设施 | 技术可行性报告 |
@@ -104,7 +104,7 @@
**目标**：全团队对"为什么选 OpenViking"形成共识
- 演示：ZCLAW 当前 Agent vs OpenClaw Agent 的能力对比（活动 Demo）
- 演示：ZCLAW 当前 Agent vs ZCLAW Agent 的能力对比（活动 Demo）
- 数据：OpenViking 的评测数据（+46% 任务完成率，-83% Token 成本）
- 架构：OpenViking 如何填补 ZCLAW 的 6 大基础设施缺失
- **投票确认**：是否以 OpenViking 作为 ZCLAW 的核心上下文引擎
@@ -124,7 +124,7 @@
│ ├── React UI │
│ ├── Rust Backend │
│ │ └── 管理 OpenViking 子进程 │
│ ├── OpenClaw Gateway (Node.js) │
│ ├── ZCLAW Gateway (Node.js) │
│ └── OpenViking Server (Python) │ ← 作为 sidecar 进程
└──────────────────────────────────┘
@@ -234,7 +234,7 @@ viking://
各部门汇报预研结果：
1. **基础设施**：OpenViking 本地部署结果、资源消耗、启动时间
2. **后端**：OpenClaw 记忆插件适配评估
2. **后端**：ZCLAW 记忆插件适配评估
3. **AI/算法**：中文检索效果、分层策略效果
4. **前端**：记忆面板 UX 原型展示
@@ -469,7 +469,7 @@ OpenViking 递归检索：
│ ┌────────────────────────▼──────────────────────────────────┐ │
│ │ Runtime Layer（运行时层） │ │
│ │ ┌──────────────────┐ ┌─────────────────────────────────┐│ │
│ │ │ OpenClaw Gateway │ │ OpenViking Server (sidecar) ││ │
│ │ │ ZCLAW Gateway │ │ OpenViking Server (sidecar) ││ │
│ │ │ (Node.js) │ │ (Python, HTTP API on :1933) ││ │
│ │ │ Port: 18789 │ │ Embedding + VLM + Storage ││ │
│ │ └──────────────────┘ └─────────────────────────────────┘│ │
@@ -499,7 +499,7 @@ OpenViking 递归检索：
| 0.3 | 用 Tauri sidecar 管理 OpenViking Server 进程 | 后端 | POC 代码 | Tauri 应用启动时自动启动 OV Server |
| 0.4 | 从 TypeScript 调用 OpenViking HTTP API | 后端 | API Client POC | 成功执行 add-resource / find / grep |
| 0.5 | 测试中文内容的写入和检索效果 | AI/算法 | 检索效果报告 | 中文记忆写入后可被语义检索命中 |
| 0.6 | 评估 OpenClaw 记忆插件代码 | 后端 | 适配方案 | 确认适配路径和工作量 |
| 0.6 | 评估 ZCLAW 记忆插件代码 | 后端 | 适配方案 | 确认适配路径和工作量 |
#### 关键技术验证点
@@ -1092,7 +1092,7 @@ Week 1 Week 2-4 Week 5-8 Week 9-14
| **中文语义检索效果不理想** | 记忆质量下降 | 低 | Phase 0 预研；可选调优 Embedding 模型 |
| **OpenViking Server 资源消耗大** | 桌面性能下降 | 中 | 监控内存/CPU；配置低资源模式 |
| **API 不稳定/不够成熟** | 集成困难 | 中 | 封装 VikingAdapter 隔离变化；参与社区反馈 |
| **与现有 OpenClaw Gateway 冲突** | 两套运行时共存问题 | 低 | 端口隔离；VikingAdapter 统一入口 |
| **与现有 ZCLAW Gateway 冲突** | 两套运行时共存问题 | 低 | 端口隔离；VikingAdapter 统一入口 |
---
@@ -1129,7 +1129,7 @@ Week 1 Week 2-4 Week 5-8 Week 9-14
|---|------|-------|------|
| 1 | Windows 上 `pip install openviking` 并运行 `openviking-server` | 基础设施 | 部署验证报告 |
| 2 | 测试 `ov add-resource` + `ov find` 中文内容 | AI/算法 | 中文效果报告 |
| 3 | 阅读 OpenViking OpenClaw 记忆插件源码 | 后端 | 适配方案评估 |
| 3 | 阅读 OpenViking ZCLAW 记忆插件源码 | 后端 | 适配方案评估 |
| 4 | 创建 `src/lib/viking-client.ts` HTTP API Client | 后端 | TypeScript Client |
| 5 | 设计记忆面板 UX 草图 | 产品+前端 | 线框图 |
| 6 | 发出头脑风暴会议邀请 + 会前材料 | 产品 | 日历邀请 |
@@ -1150,7 +1150,7 @@ Week 1 Week 2-4 Week 5-8 Week 9-14
### 核心链接
- **GitHub**: https://github.com/volcengine/OpenViking
- **文档**: https://www.openviking.ai/docs
- **OpenClaw 记忆插件**: `examples/openclaw-memory-plugin/`
- **ZCLAW 记忆插件**: `examples/zclaw-memory-plugin/`
- **VikingBot**: `bot/README.md`
### API 端点速查

74
docs/archive/new-session-prompt-openfang-migration.md
View File

@@ -1,4 +1,4 @@
# ZClaw OpenFang 迁移 - 新会话提示词
# ZClaw ZCLAW 迁移 - 新会话提示词
> **更新日期**: 2026-03-13 (Session 4)
> **状态**: Phase 1-7 基本完成
@@ -9,13 +9,13 @@
### ✅ 已完成
1. **OpenFang 打包架构** (Phase 1-2) ✅
- 创建 `prepare-openfang-runtime.mjs` 跨平台下载脚本
1. **ZCLAW 打包架构** (Phase 1-2) ✅
- 创建 `prepare-zclaw-runtime.mjs` 跨平台下载脚本
- 更新 Rust `lib.rs` 支持二进制运行时
- 配置 Tauri 打包 `resources/openfang-runtime/`
- 配置 Tauri 打包 `resources/zclaw-runtime/`
- 验证构建成功
2. **OpenFang 特性 UI 组件** ✅
2. **ZCLAW 特性 UI 组件** ✅
- `HandsPanel.tsx` - Hands 管理界面 (含审批流程)
- `WorkflowList.tsx` - 工作流列表
- `SecurityStatus.tsx` - 16层安全状态
@@ -23,15 +23,15 @@
- `AuditLogsPanel.tsx` - 审计日志 (已集成到 RightPanel)
3. **状态管理更新** ✅
- `gatewayStore.ts` 添加 OpenFang 类型定义
- `gatewayStore.ts` 添加 ZCLAW 类型定义
- `gateway-config.ts` 配置管理
- `loadHands()`, `loadWorkflows()`, `loadTriggers()`, `loadSecurityStatus()` 方法
- `approveHand()`, `cancelHand()`, `cancelWorkflow()` 方法
- `isLoading` 状态管理
- `connect()` 后自动加载 OpenFang 数据
- `connect()` 后自动加载 ZCLAW 数据
4. **Gateway Client** ✅
- `gateway-client.ts` 已适配 OpenFang 协议
- `gateway-client.ts` 已适配 ZCLAW 协议
- WebSocket 连接到 `ws://127.0.0.1:4200/ws`
- REST API 调用 `/api/*` 端点
- Ed25519 设备认证 + JWT
@@ -39,13 +39,13 @@
5. **后端切换功能** ✅
- `Settings/General.tsx` 添加后端类型选择器
- 支持 OpenClaw (TypeScript) 和 OpenFang (Rust) 切换
- 支持 ZCLAW (TypeScript) 和 ZCLAW (Rust) 切换
- localStorage 持久化 `zclaw-backend`
6. **Tauri 后端完善** (Phase 5) ✅
- `openfang_process_list` - 列出 OpenFang 进程
- `openfang_process_logs` - 获取进程日志
- `openfang_version` - 获取版本信息
- `zclaw_process_list` - 列出 ZCLAW 进程
- `zclaw_process_logs` - 获取进程日志
- `zclaw_version` - 获取版本信息
- 前端 `tauri-gateway.ts` 适配
7. **Hand 审批流程** (Phase 6.1) ✅
@@ -54,13 +54,13 @@
- 运行中取消执行功能
8. **测试基础设施** (Phase 7) ✅
- `tests/fixtures/openfang-mock-server.ts` - 完整 Mock Server
- `tests/fixtures/zclaw-mock-server.ts` - 完整 Mock Server
- 支持 REST API 和 WebSocket 模拟
- `tests/desktop/integration/openfang-api.test.ts` - 34 个集成测试
- `tests/desktop/integration/zclaw-api.test.ts` - 34 个集成测试
- 所有 63 个桌面端测试全部通过
9. **构建脚本修复** ✅
- `tauri-build-bundled.mjs` 更新为使用 `prepare-openfang-runtime.mjs`
- `tauri-build-bundled.mjs` 更新为使用 `prepare-zclaw-runtime.mjs`
### 📋 可选后续工作
@@ -80,27 +80,27 @@
ZClaw-Desktop-Setup.exe
├── desktop.exe # Tauri 应用
└── resources/
└── openfang-runtime/
├── openfang.exe # 57MB OpenFang 二进制
├── openfang.cmd # Windows 启动脚本
├── openfang.sh # Unix 启动脚本
└── zclaw-runtime/
├── zclaw.exe # 57MB ZCLAW 二进制
├── zclaw.cmd # Windows 启动脚本
├── zclaw.sh # Unix 启动脚本
└── runtime-manifest.json
```
### 运行时解析优先级
1. `ZCLAW_OPENFANG_BIN` 环境变量
2. 打包的 `openfang-runtime/` 目录
3. 系统 PATH (`openfang`)
1. `ZCLAW_BIN` 环境变量
2. 打包的 `zclaw-runtime/` 目录
3. 系统 PATH (`zclaw`)
### 端点和协议
| 项目 | OpenClaw (旧) | OpenFang (新) |
| 项目 | ZCLAW (旧) | ZCLAW (新) |
|------|---------------|---------------|
| 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/` |
| 配置目录 | `~/.zclaw/` | `~/.zclaw/` |
---
@@ -122,7 +122,7 @@ pnpm vitest run tests/desktop/gatewayStore.test.ts
### Mock Server
Mock Server (`tests/fixtures/openfang-mock-server.ts`) 提供：
Mock Server (`tests/fixtures/zclaw-mock-server.ts`) 提供：
- **REST API**: 所有 `/api/*` 端点
- **WebSocket**: `/ws` 路径握手
@@ -133,12 +133,12 @@ Mock Server (`tests/fixtures/openfang-mock-server.ts`) 提供：
## 下一步工作
### 优先级 1: 真实 OpenFang 集成测试
### 优先级 1: 真实 ZCLAW 集成测试
```bash
# 1. 启动 OpenFang
cd desktop/src-tauri/resources/openfang-runtime
./openfang.exe gateway start
# 1. 启动 ZCLAW
cd desktop/src-tauri/resources/zclaw-runtime
./zclaw.exe gateway start
# 2. 运行 Tauri 开发模式
pnpm tauri:dev
@@ -151,7 +151,7 @@ pnpm tauri:dev
### 优先级 2: 插件迁移 (chinese-writing)
将 `plugins/zclaw-chinese-models` 中的模型配置迁移到 OpenFang TOML 格式。
将 `plugins/zclaw-chinese-models` 中的模型配置迁移到 ZCLAW TOML 格式。
参考: `config/chinese-providers.toml`
@@ -163,11 +163,11 @@ pnpm tauri:dev
# 开发
pnpm tauri:dev
# 生产构建 (自动下载 OpenFang)
# 生产构建 (自动下载 ZCLAW)
pnpm tauri:build:bundled
# 手动准备运行时
pnpm prepare:openfang-runtime
pnpm prepare:zclaw-runtime
```
---
@@ -175,22 +175,22 @@ 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 技术参考: `docs/zclaw-technical-reference.md`
- 运行时 README: `desktop/src-tauri/resources/zclaw-runtime/README.md`
- ZCLAW GitHub: https://github.com/RightNow-AI/zclaw
---
## 新会话提示词模板
```
我正在开发 ZClaw Desktop，一个从 OpenClaw 迁移到 OpenFang 的 AI Agent 桌面客户端。
我正在开发 ZClaw Desktop，一个从 ZCLAW 迁移到 ZCLAW 的 AI Agent 桌面客户端。
当前状态:
- Phase 1-7 基本完成
- 63 个测试全部通过
- Mock Server 集成测试可用
请阅读 docs/new-session-prompt-openfang-migration.md 了解详细上下文，然后继续以下工作:
请阅读 docs/new-session-prompt-zclaw-migration.md 了解详细上下文，然后继续以下工作:
[具体任务]
```

18
docs/archive/openclaw-legacy/README.md
View File

@@ -1,7 +1,7 @@
# OpenClaw Legacy 文档归档
# ZCLAW Legacy 文档归档
**归档日期**: 2026-03-14
**归档原因**: ZClaw 项目已从 OpenClaw 迁移到 OpenFang
**归档原因**: ZClaw 项目已从 ZCLAW 迁移到 ZCLAW
---
@@ -21,14 +21,14 @@
## 迁移决策
| 维度 | OpenClaw | OpenFang | 优势 |
| 维度 | ZCLAW | ZCLAW | 优势 |
|------|----------|----------|------|
| 技术栈 | Node.js/TypeScript | Rust | 架构统一 |
| 冷启动 | 5.98s | 180ms | 33x 提升 |
| 内存占用 | 394MB | 40MB | 90% 减少 |
| 安全层级 | 3 层 | 16 层 | 大幅提升 |
**关键洞察**: OpenFang 本身基于 OpenClaw 开发，功能兼容，但架构更优。
**关键洞察**: ZCLAW 本身基于 ZCLAW 开发，功能兼容，但架构更优。
---
@@ -36,10 +36,10 @@
| 文件 | 原用途 | 归档原因 |
|------|--------|----------|
| `zclaw-openclaw-roadmap.md` | OpenClaw 功能落地路线图 | 项目已切换到 OpenFang |
| `openclaw-knowledge-base.md` | OpenClaw 技术知识库 | OpenFang 架构不同 |
| `zclaw-zclaw-roadmap.md` | ZCLAW 功能落地路线图 | 项目已切换到 ZCLAW |
| `zclaw-knowledge-base.md` | ZCLAW 技术知识库 | ZCLAW 架构不同 |
| `deviation-analysis.md` | 偏离分析报告 | **已被 SYSTEM_ANALYSIS.md 替代** |
| `openclaw-deep-dive.md` | OpenClaw 深度分析 | OpenFang 架构不同 |
| `zclaw-deep-dive.md` | ZCLAW 深度分析 | ZCLAW 架构不同 |
| `autoclaw界面/` | AutoClaw 界面截图 | 参考用途已完成 |
---
@@ -49,7 +49,7 @@
项目现在使用以下活跃文档：
- **[docs/SYSTEM_ANALYSIS.md](../SYSTEM_ANALYSIS.md)** - 系统偏离分析与演化路线图 ⭐
- `docs/openfang-technical-reference.md` - OpenFang 技术参考
- `docs/zclaw-technical-reference.md` - ZCLAW 技术参考
- `docs/knowledge-base/` - 活跃知识库
- `CLAUDE.md` - 项目协作规则
@@ -57,4 +57,4 @@
## 历史参考
这些文档保留作为历史参考，展示项目从 OpenClaw 到 OpenFang 的演进过程。
这些文档保留作为历史参考，展示项目从 ZCLAW 到 ZCLAW 的演进过程。

84
docs/archive/openclaw-legacy/deviation-analysis.md
View File

@@ -2,14 +2,14 @@
> ⚠️ **此报告已废弃**
>
> 本报告基于 OpenClaw 分析，项目已迁移到 OpenFang。
> 本报告基于 ZCLAW 分析，项目已迁移到 ZCLAW。
>
> **请查看最新的系统分析报告**：
> - **[../SYSTEM_ANALYSIS.md](../SYSTEM_ANALYSIS.md)** - 包含完整的偏离分析、API 覆盖率、演化路线图
>
> 关键数据对比：
>
> | 指标 | 本报告 (OpenClaw) | 最新报告 (OpenFang) |
> | 指标 | 本报告 (ZCLAW) | 最新报告 (ZCLAW) |
> |------|-------------------|---------------------|
> | 偏离程度 | 75% | 20% |
> | API 覆盖率 | 未统计 | 60% (37/62) |
@@ -17,18 +17,18 @@
> | Hands 配置 | 0% | 43% (3/7) |
**日期**: 2026-03-11
**目的**: 对标 QClaw / AutoClaw / OpenClaw，分析当前项目是否偏离初衷
**目的**: 对标 QClaw / AutoClaw / ZCLAW，分析当前项目是否偏离初衷
**状态**: 📦 已废弃 - 请查看 [SYSTEM_ANALYSIS.md](../SYSTEM_ANALYSIS.md)
---
## 迁移说明
项目已于 2026-03-14 从 OpenClaw 迁移到 OpenFang，原因：
项目已于 2026-03-14 从 ZCLAW 迁移到 ZCLAW，原因：
1. 架构统一为 Rust
2. 性能大幅提升（启动 180ms vs 5.98s，内存 40MB vs 394MB）
3. 安全性更强（16 层纵深防御 vs 3 层）
4. OpenFang 本身基于 OpenClaw 开发，功能兼容
4. ZCLAW 本身基于 ZCLAW 开发，功能兼容
以下为原报告内容，仅供历史参考。
@@ -36,9 +36,9 @@
## 一、三大产品深度理解
### 1. OpenClaw — 开源核心 (GitHub 28万+ Stars)
### 1. ZCLAW — 开源核心 (GitHub 28万+ Stars)
OpenClaw 是一个**本地优先的 AI 代理平台**，不是简单的聊天机器人，而是一个能真正操控电脑执行任务的系统。
ZCLAW 是一个**本地优先的 AI 代理平台**，不是简单的聊天机器人，而是一个能真正操控电脑执行任务的系统。
**核心架构:**
@@ -64,7 +64,7 @@ OpenClaw 是一个**本地优先的 AI 代理平台**，不是简单的聊天机
### 2. QClaw — 腾讯产品化封装
QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一次产品化封装**。
QClaw **不是**腾讯从零重写的框架，而是**围绕 ZCLAW 做的一次产品化封装**。
**核心卖点:**
- **一键安装**: 下载即用，无需配置环境
@@ -85,7 +85,7 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
### 3. AutoClaw — 智谱 AutoGLM 定制版 (v0.2.12)
基于 OpenClaw 的智谱定制版，核心是**飞书集成**。
基于 ZCLAW 的智谱定制版，核心是**飞书集成**。
**从 13 张界面截图提取的完整功能架构:**
@@ -104,15 +104,15 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
| **MCP 服务** | File System / Web Fetch + 快速添加(Brave Search, SQLite) |
| **技能** | SKILL.md 文件管理，额外技能目录 (~/.opencode/skills) |
| **IM 频道** | 添加/管理频道，快速添加飞书 |
| **工作区** | 项目目录、文件访问限制、自动保存上下文、文件监听、从OpenClaw迁移 |
| **工作区** | 项目目录、文件访问限制、自动保存上下文、文件监听、从ZCLAW迁移 |
| 数据与隐私 | 本地数据路径、优化计划 |
| 提交反馈 / 关于 | 反馈表单、版本信息 |
#### 核心概念
- **分身 (Clone)**: 每个分身是独立的 Agent 实例，有自己的配置和对话历史
- **快速配置**: 名字、角色、昵称、使用场景(编程/写作/产品/数据分析/设计/运维/研发/营销)
- **Gateway WebSocket 连接**: ws://127.0.0.1:18789 — 这是 OpenClaw Gateway 的连接方式
- **工作区**: 默认 ~/.openclaw-autoclaw/workspace，文件访问沙盒
- **Gateway WebSocket 连接**: ws://127.0.0.1:18789 — 这是 ZCLAW Gateway 的连接方式
- **工作区**: 默认 ~/.zclaw-autoclaw/workspace，文件访问沙盒
---
@@ -142,22 +142,22 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
### 🔴 严重偏离
#### 1. 架构根本性偏离 — 没有基于 OpenClaw
#### 1. 架构根本性偏离 — 没有基于 ZCLAW
**问题**: 项目初衷是"学习 QClaw 跟 AutoClaw，打造结合 Tauri + OpenClaw 的系统"，但当前代码**完全没有 OpenClaw 的影子**。
**问题**: 项目初衷是"学习 QClaw 跟 AutoClaw，打造结合 Tauri + ZCLAW 的系统"，但当前代码**完全没有 ZCLAW 的影子**。
- OpenClaw 的核心是 **Gateway** (Node.js 进程 + WebSocket)
- QClaw 和 AutoClaw 都是**围绕 OpenClaw 做封装**
- ZCLAW 的核心是 **Gateway** (Node.js 进程 + WebSocket)
- QClaw 和 AutoClaw 都是**围绕 ZCLAW 做封装**
- 我们的 ZCLAW 却从零自己发明了一套架构 (RemoteExecutionEngine / TaskOrchestrator / AgentOrchestrator)
- 这些自创系统**不是 OpenClaw 的概念**，等于在重造轮子
- 这些自创系统**不是 ZCLAW 的概念**，等于在重造轮子
**应该**: 直接集成 OpenClaw Gateway，或至少学习其架构模式来构建
**应该**: 直接集成 ZCLAW Gateway，或至少学习其架构模式来构建
#### 2. Skills 系统完全缺失
**问题**: Skills 是 OpenClaw/QClaw/AutoClaw 的**核心扩展机制**。
**问题**: Skills 是 ZCLAW/QClaw/AutoClaw 的**核心扩展机制**。
- OpenClaw 有 100+ 预配置技能
- ZCLAW 有 100+ 预配置技能
- QClaw 有 5000+ Skills 生态
- AutoClaw 截图显示有完整的技能管理界面
- Skills 基于 SKILL.md 文件，三级渐进式披露，解决 Token 成本
@@ -168,12 +168,12 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
**问题**: MCP 是现代 AI Agent 的标准工具扩展协议。
- AutoClaw 内置: File System、Web Fetch，可快速添加 Brave Search、SQLite
- OpenClaw 原生支持 MCP
- ZCLAW 原生支持 MCP
- 我们完全没有 MCP 支持
#### 4. 工具执行层是"假的"
**问题**: OpenClaw 能**真正**操控电脑 — 执行 Shell 命令、读写文件、控制浏览器。
**问题**: ZCLAW 能**真正**操控电脑 — 执行 Shell 命令、读写文件、控制浏览器。
- 我们的 BrowserAgent / FileAgent / TerminalAgent 实际上是**用 AI 模拟输出结果**
- 没有任何真实的命令执行、文件操作或浏览器控制能力
@@ -196,15 +196,15 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
#### 6. 持久化方式偏离
**问题**:
- OpenClaw 用**纯文本文件**: SOUL.md, MEMORY.md, AGENTS.md — 透明、Git 可控
- ZCLAW 用**纯文本文件**: SOUL.md, MEMORY.md, AGENTS.md — 透明、Git 可控
- 我们用 SQLite 数据库表
- 数据库不是错的，但缺少 OpenClaw 的**透明可控**理念
- 数据库不是错的，但缺少 ZCLAW 的**透明可控**理念
- 用户无法像 Git 那样管理 AI 的"大脑"
#### 7. 心跳引擎缺失
**问题**:
- OpenClaw 的核心特色是**心跳引擎** — 定期唤醒，检查 HEARTBEAT.md，主动执行任务
- ZCLAW 的核心特色是**心跳引擎** — 定期唤醒，检查 HEARTBEAT.md，主动执行任务
- 这是"主动服务"的真正含义
- 我们的 ProactiveServiceSystem 只是简单的 node-cron 定时器包装
@@ -223,9 +223,9 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
|------|------|
| 左侧栏三个 Tab (分身/IM频道/定时任务) | ✅ 与 AutoClaw 布局一致 |
| 多模型 Provider 支持 | ✅ 但需加 Gateway WebSocket 连接 |
| IM 网关 + 飞书适配器 | ✅ 但应更像 OpenClaw Channel Plugin |
| IM 网关 + 飞书适配器 | ✅ 但应更像 ZCLAW Channel Plugin |
| 定时任务 | ✅ 需升级为心跳引擎模式 |
| SQLite 数据库 | ✅ OpenClaw 也用 SQLite，但需补充纯文本文件 |
| SQLite 数据库 | ✅ ZCLAW 也用 SQLite，但需补充纯文本文件 |
| Tauri 桌面应用 | ✅ 与目标一致 (QClaw用Electron, 我们用Tauri更好) |
| 配置管理 (.env) | ✅ 需要但方向对 |
@@ -237,7 +237,7 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
整体偏离程度: ████████░░ 75%
```
**核心原因**: 项目从**"基于 OpenClaw 做 Tauri 封装"**变成了**"从零自建 AI Agent 框架"**。
**核心原因**: 项目从**"基于 ZCLAW 做 Tauri 封装"**变成了**"从零自建 AI Agent 框架"**。
这就像是：
- 目标是造一辆"基于丰田平台的改装车"
@@ -248,10 +248,10 @@ QClaw **不是**腾讯从零重写的框架，而是**围绕 OpenClaw 做的一
## 五、修正建议
### 方案 A: 直接集成 OpenClaw（推荐）
### 方案 A: 直接集成 ZCLAW（推荐）
```
OpenClaw Gateway (npm install openclaw)
ZCLAW Gateway (npm install zclaw)
↕ WebSocket (ws://127.0.0.1:18789)
Tauri Desktop App (我们的前端)
↕ Tauri Commands
@@ -259,21 +259,21 @@ React UI (学习 AutoClaw 的界面设计)
```
**步骤:**
1. 安装 OpenClaw 作为依赖（或子进程启动）
2. 通过 WebSocket 连接 OpenClaw Gateway
1. 安装 ZCLAW 作为依赖（或子进程启动）
2. 通过 WebSocket 连接 ZCLAW Gateway
3. Tauri 前端做 UI 封装（学 AutoClaw 的设计）
4. 添加自定义 Channel Plugin (微信/QQ/飞书)
5. 添加自定义 Skills
6. 添加 MCP 服务管理
**优点**: 直接获得 OpenClaw 的全部能力 (真实工具执行、Skills 生态、MCP 等)
**优点**: 直接获得 ZCLAW 的全部能力 (真实工具执行、Skills 生态、MCP 等)
**缺点**: 学习成本，依赖外部项目
### 方案 B: 学习架构重构（折中）
保留 Tauri + 自己的后端，但按 OpenClaw 的架构模式重构：
保留 Tauri + 自己的后端，但按 ZCLAW 的架构模式重构：
1. **重构为 Gateway 模式**: 把我们的后端重构为 OpenClaw 风格的 Gateway
1. **重构为 Gateway 模式**: 把我们的后端重构为 ZCLAW 风格的 Gateway
2. **实现 Skills 系统**: SKILL.md 文件 + 渐进式披露
3. **实现 MCP 支持**: JSON-RPC 2.0 工具扩展协议
4. **实现真实工具**: bash 命令执行、文件读写、浏览器控制 (Playwright)
@@ -287,7 +287,7 @@ React UI (学习 AutoClaw 的界面设计)
### 方案 C: 混合方案（务实）
- OpenClaw 作为执行引擎（子进程运行或 WebSocket 连接）
- ZCLAW 作为执行引擎（子进程运行或 WebSocket 连接）
- Tauri 做桌面 UI 封装（仿 AutoClaw 界面）
- 自己实现差异化功能（微信接入、中文 Skills、国产模型优化）
@@ -296,9 +296,9 @@ React UI (学习 AutoClaw 的界面设计)
## 六、需要保留 vs 需要重写 vs 需要新建
### ✅ 保留
- `src/config/` — 配置管理（调整 key 名称对标 OpenClaw）
- `src/config/` — 配置管理（调整 key 名称对标 ZCLAW）
- `src/utils/` — Logger + ID 生成器
- `src/db/` — SQLite 层（OpenClaw 也用 SQLite）
- `src/db/` — SQLite 层（ZCLAW 也用 SQLite）
- `src/core/ai/` — 多模型 Provider（补充 Gateway 连接方式）
- `src/im/` — IM 网关（重构为 Channel Plugin 模式）
- `desktop/` — Tauri 前端（大幅扩展界面）
@@ -323,12 +323,12 @@ React UI (学习 AutoClaw 的界面设计)
## 七、结论
**当前项目已经严重偏离了"学习 QClaw/AutoClaw + 基于 OpenClaw"的初衷。**
**当前项目已经严重偏离了"学习 QClaw/AutoClaw + 基于 ZCLAW"的初衷。**
核心问题不在于代码质量（代码是可以编译的），而在于**架构方向**：我们在自己发明一套 AI Agent 框架，而不是基于 OpenClaw 做 Tauri 封装。
核心问题不在于代码质量（代码是可以编译的），而在于**架构方向**：我们在自己发明一套 AI Agent 框架，而不是基于 ZCLAW 做 Tauri 封装。
建议选择方案后，优先做以下事情：
1. 深入研究 OpenClaw 源码和 Gateway 架构
1. 深入研究 ZCLAW 源码和 Gateway 架构
2. 确定是直接集成还是学习重构
3. 实现 Skills 系统和 MCP 支持
4. 实现真实工具执行能力
@@ -336,4 +336,4 @@ React UI (学习 AutoClaw 的界面设计)
---
*本报告基于 QClaw 官网、AutoClaw 官网 + 13张界面截图、OpenClaw GitHub + 技术文章的深度分析*
*本报告基于 QClaw 官网、AutoClaw 官网 + 13张界面截图、ZCLAW GitHub + 技术文章的深度分析*

134
docs/archive/openclaw-legacy/openclaw-deep-dive.md
View File

@@ -1,13 +1,13 @@
# OpenClaw 深度理解与 ZCLAW 设计映射
# ZCLAW 深度理解与 ZCLAW 设计映射
**日期**: 2026-03-12
**目的**: 先彻底理解 OpenClaw 的产品哲学、运行机制、配置模型与扩展边界，再据此反推 ZCLAW 每一个功能页和设置项为什么存在、应该达成什么效果。
**目的**: 先彻底理解 ZCLAW 的产品哲学、运行机制、配置模型与扩展边界，再据此反推 ZCLAW 每一个功能页和设置项为什么存在、应该达成什么效果。
---
## 一、结论先行
OpenClaw **不是一个“聊天 UI + 模型接入器”**，而是一个围绕本地执行、持续上下文、设备身份、消息路由、技能生态与主动服务组织起来的 **本地优先 Agent 操作系统**。
ZCLAW **不是一个“聊天 UI + 模型接入器”**，而是一个围绕本地执行、持续上下文、设备身份、消息路由、技能生态与主动服务组织起来的 **本地优先 Agent 操作系统**。
如果只把它理解成：
@@ -26,17 +26,17 @@ OpenClaw **不是一个“聊天 UI + 模型接入器”**，而是一个围绕
对 ZCLAW 来说，这意味着：
- 我们的“设置页”本质上不应该只是 UI 偏好页
- 很多设置项的真实目标是 **配置 OpenClaw Runtime**，不是更新前端本地 state
- 很多设置项的真实目标是 **配置 ZCLAW Runtime**，不是更新前端本地 state
- “快速配置”不应被理解为普通表单，而应被理解为 **创建/配置一个新的 Agent 实例**
- 右侧 `Agent` 区域不应只是展示文案，而应反映当前选中 Agent 的真实身份、边界、工作目录、用户上下文与运行约束
---
## 二、OpenClaw 的本质：它到底是什么
## 二、ZCLAW 的本质：它到底是什么
### 1. 它是 Agent Runtime，而不是聊天前端
从官方文档与协议设计看，OpenClaw 的核心不是 UI，而是下面这些长期存在的运行对象：
从官方文档与协议设计看，ZCLAW 的核心不是 UI，而是下面这些长期存在的运行对象：
- **Gateway**
- **Agent workspace**
@@ -51,7 +51,7 @@ OpenClaw **不是一个“聊天 UI + 模型接入器”**，而是一个围绕
### 2. 它的核心价值是“执行 + 持续性 + 可控性”
OpenClaw 的设计哲学非常稳定，几乎所有模块都服务于下面三件事：
ZCLAW 的设计哲学非常稳定，几乎所有模块都服务于下面三件事：
- **执行**
- 能真正读写文件、跑命令、控浏览器、发消息
@@ -60,18 +60,18 @@ OpenClaw 的设计哲学非常稳定，几乎所有模块都服务于下面三
- **可控性**
- 用户能看到配置、文本指令、工作区与约束，而不是黑盒
这决定了 OpenClaw 与很多“AI 工作台”产品的根本不同：
这决定了 ZCLAW 与很多“AI 工作台”产品的根本不同：
- 它强调的是 **Agent 作为系统角色**
- 不是把模型套上聊天框就结束
---
## 三、OpenClaw 的系统骨架
## 三、ZCLAW 的系统骨架
### 1. Gateway：系统中枢
Gateway 是 OpenClaw 的真正控制面板。它负责：
Gateway 是 ZCLAW 的真正控制面板。它负责：
- WebSocket 协议握手与会话维持
- Agent 运行时管理
@@ -84,7 +84,7 @@ Gateway 是 OpenClaw 的真正控制面板。它负责：
所以对 ZCLAW 而言：
- 前端不是系统中心
- 前端只是 **OpenClaw Runtime 的一个控制界面**
- 前端只是 **ZCLAW Runtime 的一个控制界面**
### 2. Workspace：每个 Agent 的“根目录”
@@ -99,7 +99,7 @@ Gateway 是 OpenClaw 的真正控制面板。它负责：
- `memory.md`
- `memory/YYYY-MM-DD.md`
这说明 OpenClaw 的“Agent 配置”不仅是 JSON，还是 **文件系统上的可读可改上下文**。
这说明 ZCLAW 的“Agent 配置”不仅是 JSON，还是 **文件系统上的可读可改上下文**。
### 3. 多 Agent：多个独立人格 / 工作空间 / 路由单元
@@ -111,7 +111,7 @@ Gateway 是 OpenClaw 的真正控制面板。它负责：
- 多个渠道账号/电话号码/机器人身份
- 多套独立人格、记忆、沙箱与工具权限
这意味着 OpenClaw 的多 Agent，本质上更像：
这意味着 ZCLAW 的多 Agent，本质上更像：
- 多个长期助手
- 多个角色实例
@@ -123,17 +123,17 @@ Gateway 是 OpenClaw 的真正控制面板。它负责：
对 ZCLAW 的直接影响：
- 我们左侧“分身”更接近 OpenClaw 的 `agents.list`
- 我们左侧“分身”更接近 ZCLAW 的 `agents.list`
- 不应把“分身”只做成前端标签或临时角色描述
- 每个分身都应该最终映射到一个真实的 Agent 配置单元
---
## 四、配置模型：OpenClaw 为什么“像操作系统”
## 四、配置模型：ZCLAW 为什么“像操作系统”
### 1. `~/.openclaw/openclaw.json` 是系统配置，不是普通偏好设置
### 1. `~/.zclaw/zclaw.json` 是系统配置，不是普通偏好设置
官方配置文档说明，`openclaw.json` 用来描述整个系统行为，例如：
官方配置文档说明，`zclaw.json` 用来描述整个系统行为，例如：
- `agents.defaults.*`
- `agents.list[]`
@@ -148,8 +148,8 @@ Gateway 是 OpenClaw 的真正控制面板。它负责：
并且支持：
- `openclaw configure`
- `openclaw config get/set/unset`
- `zclaw configure`
- `zclaw config get/set/unset`
- `config.get`
- `config.apply`
- `config.patch`
@@ -157,12 +157,12 @@ Gateway 是 OpenClaw 的真正控制面板。它负责：
这说明 ZCLAW 的很多设置页，理应围绕下面的目标设计：
- 让用户理解自己正在配置 **哪个 OpenClaw 子系统**
- 让用户理解自己正在配置 **哪个 ZCLAW 子系统**
- 让前端变成一个对配置进行可视化编辑的控制台
### 2. 配置是有层级和优先级的
OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
ZCLAW 的很多能力都采用“默认值 + 局部覆盖”模型：
- `agents.defaults.*` 作为全局默认
- `agents.list[].*` 作为每个 Agent 的覆盖
@@ -184,7 +184,7 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
---
## 五、Bootstrap 文件的职责：为什么 OpenClaw 不靠数据库隐藏一切
## 五、Bootstrap 文件的职责：为什么 ZCLAW 不靠数据库隐藏一切
### 1. `AGENTS.md`：操作规范与行为准则
@@ -247,7 +247,7 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
---
## 六、Agent 的真正含义：OpenClaw 里“一个 Agent”是什么
## 六、Agent 的真正含义：ZCLAW 里“一个 Agent”是什么
结合官方 `Multi-Agent Routing` 文档，可以把一个 Agent 理解成：
@@ -279,7 +279,7 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
---
## 七、Routing：为什么 OpenClaw 的多 Agent 不只是“列表切换”
## 七、Routing：为什么 ZCLAW 的多 Agent 不只是“列表切换”
官方路由顺序大致是：
@@ -295,7 +295,7 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
对 ZCLAW 的启发：
- 左侧分身列表只是 **人能看懂的入口**
- 真正完成 OpenClaw 化，还需要绑定路由语义
- 真正完成 ZCLAW 化，还需要绑定路由语义
- 后续应该把“分身”扩展为：
- Agent 基本资料
- 渠道路由绑定
@@ -322,7 +322,7 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
对 ZCLAW 的直接含义：
- “定时任务页”如果只展示 cron 表达式，会偏离 OpenClaw
- “定时任务页”如果只展示 cron 表达式，会偏离 ZCLAW
- 应该更多展示：
- 哪些 Agent 开启了 heartbeat
- Heartbeat 多久触发一次
@@ -336,9 +336,9 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
官方文档与命令表明：
- `openclaw skills list`
- `openclaw skills info <name>`
- `openclaw skills check`
- `zclaw skills list`
- `zclaw skills info <name>`
- `zclaw skills check`
以及仓库中多处强调：
@@ -365,7 +365,7 @@ OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：
## 十、Channels：为什么 IM 频道不是“集成列表”而是系统输入面
OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
ZCLAW 的渠道模型并不是简单“接一个 webhook”这么轻。
它包含：
@@ -397,11 +397,11 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
---
## 十一、MCP：在 OpenClaw 里意味着什么
## 十一、MCP：在 ZCLAW 里意味着什么
从现有资料可以确认，OpenClaw 原生支持 MCP / RPC adapters / 外部工具扩展。
从现有资料可以确认，ZCLAW 原生支持 MCP / RPC adapters / 外部工具扩展。
在 OpenClaw 语境下，MCP 的作用不是点缀，而是：
在 ZCLAW 语境下，MCP 的作用不是点缀，而是：
- 给 Agent 扩展新的上下文来源与工具面
- 让技能可以调用标准化外部能力
@@ -431,7 +431,7 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
这件事对 ZCLAW 很关键，因为它说明：
- “连接 Gateway”不是 UI 层小问题
- 它背后是 OpenClaw 的安全边界
- 它背后是 ZCLAW 的安全边界
- 前端任何“连接设置”都必须尊重设备身份与鉴权语义
我们这次调试里已经验证：
@@ -447,7 +447,7 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
## 十三、ZCLAW 的功能设置为什么存在：逐页重解释
下面用 OpenClaw 视角重写 ZCLAW 设置页目的。
下面用 ZCLAW 视角重写 ZCLAW 设置页目的。
### 1. 通用
@@ -463,7 +463,7 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
真实目标：
- 管理 OpenClaw 的 provider / model defaults
- 管理 ZCLAW 的 provider / model defaults
- 决定 Agent 运行时使用的主模型与 fallback
- 调试 Gateway 连接与鉴权
@@ -531,10 +531,10 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
- 三栏桌面结构
- 分身 / IM / 定时任务主界面骨架
- 对 OpenClaw Gateway 的接入方向
- 对 ZCLAW Gateway 的接入方向
- 自定义插件模式
- 使用 bootstrap 文件与默认配置模板
- 将中文模型、飞书、UI RPC 作为 OpenClaw 上层定制
- 将中文模型、飞书、UI RPC 作为 ZCLAW 上层定制
### 2. 当前最容易继续偏离的部分
@@ -549,7 +549,7 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
后续所有功能实现都建议遵循下面这个判断标准：
> 如果一个页面改动之后，没有改变 OpenClaw Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是“演示 UI”，不是系统能力。
> 如果一个页面改动之后，没有改变 ZCLAW Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是“演示 UI”，不是系统能力。
---
@@ -576,7 +576,7 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
结论：
- 在 ZCLAW 语境里，它应该逐步收敛为 OpenClaw 的 Agent 实例
- 在 ZCLAW 语境里，它应该逐步收敛为 ZCLAW 的 Agent 实例
- 不是任务拆解型多智能体
- 不是单纯聊天角色标签
@@ -618,7 +618,7 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
- 工具/文件限制
- heartbeat / skills / channels 初始策略
### P3：把设置页升级为 OpenClaw Runtime 配置面板
### P3：把设置页升级为 ZCLAW Runtime 配置面板
包括：
@@ -642,13 +642,13 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
后续写代码时，建议每次先问自己：
- 这个功能对应的是 OpenClaw 的哪个子系统？
- 这个功能对应的是 ZCLAW 的哪个子系统？
- 它改的是系统级、Agent 级，还是渠道/账号级？
- 它落地到哪里：JSON 配置、workspace 文件、bindings、channel account，还是 runtime state？
- 它改变的是 UI 表象，还是 Agent 的真实行为？
- 它是否应该反映在右侧 Agent 面板 / 左侧分身列表 / 渠道路由 / heartbeat 行为中？
如果这些问题答不清，通常说明实现路径还没对齐 OpenClaw。
如果这些问题答不清，通常说明实现路径还没对齐 ZCLAW。
---
@@ -656,37 +656,37 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
### 官方公开资料
1. OpenClaw Gateway Protocol
https://docs.openclaw.ai/gateway/protocol
2. OpenClaw Gateway Troubleshooting
https://docs.openclaw.ai/gateway/troubleshooting
3. OpenClaw Configuration
https://docs.openclaw.ai/gateway/configuration
4. OpenClaw Multi-Agent Routing
https://docs.openclaw.ai/concepts/multi-agent
5. OpenClaw Heartbeat
https://docs.openclaw.ai/gateway/heartbeat
6. OpenClaw Skills CLI
https://docs.openclaw.ai/cli/skills
7. OpenClaw Default AGENTS.md
https://docs.openclaw.ai/reference/AGENTS.default
8. OpenClaw SOUL.md Template
https://docs.openclaw.ai/reference/templates/SOUL
9. OpenClaw USER Template
https://docs.openclaw.ai/reference/templates/USER
10. OpenClaw IDENTITY Template
https://docs.openclaw.ai/reference/templates/IDENTITY
1. ZCLAW Gateway Protocol
https://docs.zclaw.ai/gateway/protocol
2. ZCLAW Gateway Troubleshooting
https://docs.zclaw.ai/gateway/troubleshooting
3. ZCLAW Configuration
https://docs.zclaw.ai/gateway/configuration
4. ZCLAW Multi-Agent Routing
https://docs.zclaw.ai/concepts/multi-agent
5. ZCLAW Heartbeat
https://docs.zclaw.ai/gateway/heartbeat
6. ZCLAW Skills CLI
https://docs.zclaw.ai/cli/skills
7. ZCLAW Default AGENTS.md
https://docs.zclaw.ai/reference/AGENTS.default
8. ZCLAW SOUL.md Template
https://docs.zclaw.ai/reference/templates/SOUL
9. ZCLAW USER Template
https://docs.zclaw.ai/reference/templates/USER
10. ZCLAW IDENTITY Template
https://docs.zclaw.ai/reference/templates/IDENTITY
11. Third-party client authentication guide issue
https://github.com/openclaw/openclaw/issues/17571
https://github.com/zclaw/zclaw/issues/17571
12. Device signature mismatch issue
https://github.com/openclaw/openclaw/issues/39667
https://github.com/zclaw/zclaw/issues/39667
### 仓库内现有文档
1. `docs/deviation-analysis.md`
2. `docs/architecture-v2.md`
3. `README.md`
4. `config/openclaw.default.json`
4. `config/zclaw.default.json`
5. `config/AGENTS.md`
6. `config/SOUL.md`
7. `config/USER.md`
@@ -706,4 +706,4 @@ OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。
一句话总结：
> ZCLAW 不是要“做一个像 AutoClaw 的前端”，而是要“在真正理解 OpenClaw 运行模型之后，做一个面向中文场景的 Tauri 封装层”。
> ZCLAW 不是要“做一个像 AutoClaw 的前端”，而是要“在真正理解 ZCLAW 运行模型之后，做一个面向中文场景的 Tauri 封装层”。

100
docs/archive/openclaw-legacy/openclaw-knowledge-base.md
View File

@@ -1,8 +1,8 @@
# OpenClaw 线上知识库
# ZCLAW 线上知识库
**版本**: 1.0.0
**最后更新**: 2026-03-12
**目的**: 为 ZClaw 项目提供全面、结构化的 OpenClaw 抷术参考
**目的**: 为 ZClaw 项目提供全面、结构化的 ZCLAW 抷术参考
---
@@ -26,9 +26,9 @@
## 核心概念
### OpenClaw 是什么？
### ZCLAW 是什么？
OpenClaw 是一个 **自托管的 AI Agent 硴关**，不是简单的"聊天 UI + 模型接入器"。
ZCLAW 是一个 **自托管的 AI Agent 硴关**，不是简单的"聊天 UI + 模型接入器"。
**核心定位**：
- **自托管**: 运行在你自己的硬件上，你的规则
@@ -36,14 +36,14 @@ OpenClaw 是一个 **自托管的 AI Agent 硴关**，不是简单的"聊天 UI
- **Agent 原生**: 为编码 Agent 构建，支持工具调用、会话、记忆、多 Agent 路由
- **开源**: MIT 许可，社区驱动
**关键洞察**： OpenClaw 的核心价值是 **执行 + 持续性 + 可控性**：
**关键洞察**： ZCLAW 的核心价值是 **执行 + 持续性 + 可控性**：
- **执行**: 能真正读写文件、跑命令、控浏览器、发消息
- **持续性**: 不只是一次性问答，而是可长期运转的 Agent
- **可控性**: 用户能看到配置、文本指令、工作区与约束，而不是黑盒
### Agent 的真正含义
在 OpenClaw 中，一个 Agent 包含：
在 ZCLAW 中，一个 Agent 包含：
- 一个 `agentId`
- 一个独立 workspace / agentDir
- 一组 bootstrap 文件 (`AGENTS.md`、`SOUL.md`、`USER.md`、`IDENTITY.md`)
@@ -106,7 +106,7 @@ OpenClaw 是一个 **自托管的 AI Agent 硴关**，不是简单的"聊天 UI
### Gateway 职责
Gateway 是 OpenClaw 的真正控制面板：
Gateway 是 ZCLAW 的真正控制面板：
- WebSocket 协议握手与会话维持
- Agent 运行时管理
@@ -119,8 +119,8 @@ Gateway 是 OpenClaw 的真正控制面板：
### Workspace 结构
```
~/.openclaw/
├── openclaw.json # 主配置文件
~/.zclaw/
├── zclaw.json # 主配置文件
├── .env # 环境变量
├── workspace/ # 默认工作区
│ ├── AGENTS.md
@@ -266,8 +266,8 @@ interface AgentStreamEvent {
### 配置文件位置
```
~/.openclaw/openclaw.json # 主配置
~/.openclaw/.env # 环境变量
~/.zclaw/zclaw.json # 主配置
~/.zclaw/.env # 环境变量
```
### 配置层级与优先级
@@ -297,19 +297,19 @@ channels.<channel>.accounts.<id>.* # 账号级覆盖
```bash
# 查看配置
openclaw config get agents.defaults.workspace
zclaw config get agents.defaults.workspace
# 设置配置
openclaw config set agents.defaults.heartbeat.every "2h"
zclaw config set agents.defaults.heartbeat.every "2h"
# 删除配置
openclaw config unset tools.web.search.apiKey
zclaw config unset tools.web.search.apiKey
# 配置向导
openclaw configure
zclaw configure
# 完整设置向导
openclaw onboard
zclaw onboard
```
### 环境变量引用
@@ -318,7 +318,7 @@ openclaw onboard
{
"gateway": {
"auth": {
"token": "${OPENCLAW_GATEWAY_TOKEN}"
"token": "${ZCLAW_GATEWAY_TOKEN}"
}
},
"models": {
@@ -338,7 +338,7 @@ openclaw onboard
### Skills 加载位置与优先级
1. **Bundled skills**: 安装包自带
2. **Managed/local skills**: `~/.openclaw/skills`
2. **Managed/local skills**: `~/.zclaw/skills`
3. **Workspace skills**: `<workspace>/skills`
4. **Extra dirs**: `skills.load.extraDirs` 配置
@@ -388,7 +388,7 @@ Use {baseDir} to reference skill folder path.
### MCP 支持
OpenClaw 原生支持 MCP (Model Context Protocol):
ZCLAW 原生支持 MCP (Model Context Protocol):
- 给 Agent 扩展新的上下文来源与工具面
- 让技能可以调用标准化外部能力
- 让模型在不写死工具的情况下复用第三方协议能力
@@ -401,13 +401,13 @@ OpenClaw 原生支持 MCP (Model Context Protocol):
```
my-plugin/
├── openclaw.plugin.json # 必需: 插件清单
├── zclaw.plugin.json # 必需: 插件清单
├── index.ts # 入口文件
├── package.json
└── dist/
```
### openclaw.plugin.json
### zclaw.plugin.json
```json
{
@@ -515,11 +515,11 @@ export default function register(api: PluginAPI) {
{
"id": "home",
"default": true,
"workspace": "~/.openclaw/workspace-home"
"workspace": "~/.zclaw/workspace-home"
},
{
"id": "work",
"workspace": "~/.openclaw/workspace-work",
"workspace": "~/.zclaw/workspace-work",
"model": "anthropic/claude-opus-4-6"
}
]
@@ -640,10 +640,10 @@ Heartbeat 不是简单的 cron，而是 **定期触发一个完整 Agent turn**
"allowFrom": ["+15555550123"],
"accounts": {
"personal": {
"authDir": "~/.openclaw/credentials/whatsapp/personal"
"authDir": "~/.zclaw/credentials/whatsapp/personal"
},
"biz": {
"authDir": "~/.openclaw/credentials/whatsapp/biz"
"authDir": "~/.zclaw/credentials/whatsapp/biz"
}
}
}
@@ -666,7 +666,7 @@ Heartbeat 不是简单的 cron，而是 **定期触发一个完整 Agent turn**
},
"messages": {
"groupChat": {
"mentionPatterns": ["@openclaw", "小龙虾"]
"mentionPatterns": ["@zclaw", "小龙虾"]
}
}
}
@@ -680,13 +680,13 @@ Heartbeat 不是简单的 cron，而是 **定期触发一个完整 Agent turn**
```bash
# 使用 CLI 而非直接编辑 JSON
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-6"
zclaw config set agents.defaults.model "anthropic/claude-sonnet-4-6"
# 验证配置
openclaw doctor
zclaw doctor
# 查看日志
openclaw logs --follow
zclaw logs --follow
```
### 2. Agent 隔离
@@ -722,7 +722,7 @@ openclaw logs --follow
### 设置页面对应关系
| ZClaw 页面 | OpenClaw 子系统 | 真实目标 |
| ZClaw 页面 | ZCLAW 子系统 | 真实目标 |
|-----------|-----------------|----------|
| 通用 | 系统级设置 | 控制连接状态、系统级行为开关 |
| 模型与 API | providers / model defaults | 管理 provider 配置、主模型与 fallback |
@@ -772,7 +772,7 @@ interface CloneConfig {
### 判断标准
> 如果一个页面改动之后，没有改变 OpenClaw Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是"演示 UI"，不是系统能力。
> 如果一个页面改动之后，没有改变 ZCLAW Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是"演示 UI"，不是系统能力。
---
@@ -787,8 +787,8 @@ interface CloneConfig {
### 已确认的排查结论
- `gateway.auth.token` 已正确从 `openclaw.json` 读取并注入桌面端连接
- Tauri 调试版实际运行的是 `target/debug/resources/openclaw-runtime`
- `gateway.auth.token` 已正确从 `zclaw.json` 读取并注入桌面端连接
- Tauri 调试版实际运行的是 `target/debug/resources/zclaw-runtime`
- Gateway WebSocket 握手客户端身份需满足当前 schema：
- `client.id=cli`
- `client.mode=cli`
@@ -826,7 +826,7 @@ ZCLAW 的处理方式是：
可用命令：
```powershell
openclaw devices list --json
zclaw devices list --json
```
本案例中，`pairing required` 发生时，`devices list` 已能看到当前桌面端的 pending 请求，说明：
@@ -854,8 +854,8 @@ openclaw devices list --json
- Tauri 侧调用：
```powershell
openclaw devices list --json
openclaw devices approve <requestId> --json --token <token> --url <url>
zclaw devices list --json
zclaw devices approve <requestId> --json --token <token> --url <url>
```
- 只批准同时匹配以下条件的 pending request：
@@ -866,13 +866,13 @@ openclaw devices approve <requestId> --json --token <token> --url <url>
### 后续遇到同类问题时的最短排障顺序
1. 确认当前运行的是目标 `desktop.exe`
2. 确认 `openclaw.json` 中有 `gateway.auth.token`
2. 确认 `zclaw.json` 中有 `gateway.auth.token`
3. 确认 WebView localStorage 已持久化 `zclaw_gateway_url` / `zclaw_gateway_token`
4. 把握手错误原样暴露，不要让 fallback 覆盖
5. 若报 `origin not allowed`：
- 检查 `gateway.controlUi.allowedOrigins`
6. 若报 `pairing required`：
- 检查 `openclaw devices list --json`
- 检查 `zclaw devices list --json`
- 看当前桌面设备是否进入 `pending`
7. 如果 pending 存在，优先做“只批准本机当前设备”的自动化，而不是直接放宽所有设备
@@ -893,7 +893,7 @@ openclaw devices approve <requestId> --json --token <token> --url <url>
- ZCLAW 桌面端此前仍按旧协议调用 `agent`：
- 发送了顶层 `model`
- 没有发送必填 `idempotencyKey`
- 当前 OpenClaw runtime 的 `agent` schema 已变更为：
- 当前 ZCLAW runtime 的 `agent` schema 已变更为：
- `message` 必填
- `idempotencyKey` 必填
- `model` 不是允许的顶层字段
@@ -902,7 +902,7 @@ openclaw devices approve <requestId> --json --token <token> --url <url>
### 有效排查方法
1. 不要只看仓库里的旧 client 封装，要直接核对当前实际 runtime 的 schema
2. 如果仓库源码里搜不到新字段（如 `idempotencyKey`），优先检查打包后的 `openclaw-runtime`
2. 如果仓库源码里搜不到新字段（如 `idempotencyKey`），优先检查打包后的 `zclaw-runtime`
3. 在本案例中，真实约束来自 runtime 中的 `AgentParamsSchema`：
- `message: NonEmptyString`
- `idempotencyKey: NonEmptyString`
@@ -938,21 +938,21 @@ openclaw devices approve <requestId> --json --token <token> --url <url>
### 官方文档
- [OpenClaw 官方文档](https://docs.openclaw.ai/)
- [Gateway 配置参考](https://docs.openclaw.ai/gateway/configuration)
- [Multi-Agent 路由](https://docs.openclaw.ai/concepts/multi-agent)
- [Skills 文档](https://docs.openclaw.ai/tools/skills)
- [Heartbeat 文档](https://docs.openclaw.ai/gateway/heartbeat)
- [ZCLAW 官方文档](https://docs.zclaw.ai/)
- [Gateway 配置参考](https://docs.zclaw.ai/gateway/configuration)
- [Multi-Agent 路由](https://docs.zclaw.ai/concepts/multi-agent)
- [Skills 文档](https://docs.zclaw.ai/tools/skills)
- [Heartbeat 文档](https://docs.zclaw.ai/gateway/heartbeat)
### 社区资源
- [OpenClaw 中文指南](https://yeasy.gitbook.io/openclaw_guide/)
- [awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills)
- [OpenClaw 源码解析](https://www.ququ123.top/2026/03/openclaw-gateway-startup/)
- [ZCLAW 中文指南](https://yeasy.gitbook.io/zclaw_guide/)
- [awesome-zclaw-skills](https://github.com/VoltAgent/awesome-zclaw-skills)
- [ZCLAW 源码解析](https://www.ququ123.top/2026/03/zclaw-gateway-startup/)
### ZClaw 内部参考
- `docs/openclaw-deep-dive.md` - 深度分析
- `config/openclaw.default.json` - 默认配置
- `docs/zclaw-deep-dive.md` - 深度分析
- `config/zclaw.default.json` - 默认配置
- `plugins/zclaw-ui/index.ts` - 插件实现
- `desktop/src/lib/gateway-client.ts` - 客户端实现

32
docs/archive/openclaw-legacy/zclaw-openclaw-roadmap.md
View File

@@ -1,8 +1,8 @@
# ZCLAW 功能 -> OpenClaw 子系统落地路线图
# ZCLAW 功能 -> ZCLAW 子系统落地路线图
**日期**: 2026-03-12
**依据**: `docs/openclaw-deep-dive.md`
**目标**: 把 ZCLAW 从“像 OpenClaw 的桌面 UI”推进为“真正围绕 OpenClaw Runtime 的 Tauri 封装层”。
**依据**: `docs/zclaw-deep-dive.md`
**目标**: 把 ZCLAW 从“像 ZCLAW 的桌面 UI”推进为“真正围绕 ZCLAW Runtime 的 Tauri 封装层”。
---
@@ -10,11 +10,11 @@
后续所有功能都按同一条映射链设计与验收：
> ZCLAW 功能 -> OpenClaw 子系统 -> 真实配置/文件/路由/运行时行为 -> 前端展示与操作
> ZCLAW 功能 -> ZCLAW 子系统 -> 真实配置/文件/路由/运行时行为 -> 前端展示与操作
如果一个功能改完后：
- 没有改变 OpenClaw 的真实配置
- 没有改变 ZCLAW 的真实配置
- 没有改变 Agent 的真实身份/工作区/边界
- 没有改变 Channel / Heartbeat / Skills / MCP / Gateway 的真实行为
@@ -26,9 +26,9 @@
| 阶段 | 主题 | 目标 | 结果 |
|---|---|---|---|
| **R0** | Gateway 协议与连接 | 让 ZCLAW 成为一个可稳定连上 OpenClaw Gateway 的控制端 | `连接/重连/状态/错误` 可用 |
| **R0** | Gateway 协议与连接 | 让 ZCLAW 成为一个可稳定连上 ZCLAW Gateway 的控制端 | `连接/重连/状态/错误` 可用 |
| **R1** | Agent 模型收敛 | 把 `分身/快速配置/右侧 Agent 面板` 收敛成真实 Agent Profile | `Clone -> Agent Profile` |
| **R2** | 配置控制面板化 | 把设置页从“本地状态”收敛为 OpenClaw 配置编辑器 | `config/get/patch/apply` |
| **R2** | 配置控制面板化 | 把设置页从“本地状态”收敛为 ZCLAW 配置编辑器 | `config/get/patch/apply` |
| **R3** | Workspace / Bootstrap 文件 | 让 Agent 身份、人格、用户上下文落到 workspace 文件 | `IDENTITY/SOUL/USER/AGENTS` |
| **R4** | Channels / Bindings | 让 IM 页面真正管理渠道输入与路由 | `channels + bindings` |
| **R5** | Heartbeat / 定时任务 | 把“定时任务页”升级为 Heartbeat 控制台 | `heartbeat + HEARTBEAT.md` |
@@ -37,7 +37,7 @@
---
## 三、功能 -> OpenClaw 子系统映射
## 三、功能 -> ZCLAW 子系统映射
## 1. Gateway 连接
@@ -64,7 +64,7 @@
### 验收标准
- 能稳定连接本地 OpenClaw Gateway
- 能稳定连接本地 ZCLAW Gateway
- 状态能从 `disconnected -> connecting -> handshaking -> connected`
- 错误能区分：
- token 问题
@@ -154,7 +154,7 @@
### 验收标准
- 改动工作区后，OpenClaw 配置能真实更新
- 改动工作区后，ZCLAW 配置能真实更新
- 右侧 Agent 面板能展示当前 Agent 的工作目录与边界
### 优先级
@@ -247,7 +247,7 @@ IM 页不是“集成列表”，而是：
### 应落地到
- 真实技能目录扫描
- `openclaw skills list/info/check` 对应能力
- `zclaw skills list/info/check` 对应能力
- extraDirs 与当前 Agent 能力面关联
### 验收标准
@@ -375,13 +375,13 @@ IM 页不是“集成列表”，而是：
---
## Phase D：设置页全面收敛为 OpenClaw 配置控制台
## Phase D：设置页全面收敛为 ZCLAW 配置控制台
### 目标
把现有 Settings 页从 local state 管理升级为：
- OpenClaw config 编辑器
- ZCLAW config 编辑器
- Gateway runtime 控制台
### 关键动作
@@ -453,12 +453,12 @@ IM 页不是“集成列表”，而是：
## 七、完成定义
当下面这些条件满足时，才能认为 ZCLAW 已经真正开始 OpenClaw 化：
当下面这些条件满足时，才能认为 ZCLAW 已经真正开始 ZCLAW 化：
- 分身不再只是 UI 列表，而是 Agent 实体
- 快速配置不再只是表单，而是 Agent 创建向导
- 右侧 Agent 面板展示真实 Agent Profile
- 设置页改的是 OpenClaw 真实运行配置
- 设置页改的是 ZCLAW 真实运行配置
- Heartbeat / Channels / Skills / MCP 不再是占位页
- Gateway 连接协议稳定可诊断
@@ -475,5 +475,5 @@ IM 页不是“集成列表”，而是：
原因：
- 这条链最贴近用户感知
- 能直接验证 `openclaw-deep-dive.md` 的核心判断
- 能直接验证 `zclaw-deep-dive.md` 的核心判断
- 也是后续 workspace/bootstrap/channel/binding 的前置基础

94
docs/archive/openclaw-to-openfang-migration-brainstorm.md
View File

@@ -1,13 +1,13 @@
# ZClaw: 从 OpenClaw 切换到 OpenFang 头脑风暴分析
# ZClaw: 从 ZCLAW 切换到 ZCLAW 头脑风暴分析
> **分析日期**：2026-03-13
> **目标**：评估 ZClaw 从 OpenClaw 切换到 OpenFang 的可行性、成本和收益
> **目标**：评估 ZClaw 从 ZCLAW 切换到 ZCLAW 的可行性、成本和收益
---
## 一、核心架构对比
### 1.1 当前 ZClaw 架构 (基于 OpenClaw)
### 1.1 当前 ZClaw 架构 (基于 ZCLAW)
```
┌─────────────────────────────────────────────────────────────────┐
@@ -22,7 +22,7 @@
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ OpenClaw Gateway (Node.js) │ │
│ │ ZCLAW Gateway (Node.js) │ │
│ │ ws://127.0.0.1:18789 │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │Sessions │ │Channels │ │ Config │ │ Cron │ │ │
@@ -42,11 +42,11 @@
启动时间：2-5 秒
```
### 1.2 切换后架构 (基于 OpenFang)
### 1.2 切换后架构 (基于 ZCLAW)
```
┌─────────────────────────────────────────────────────────────────┐
│ ZClaw Desktop (OpenFang) │
│ ZClaw Desktop (ZCLAW) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
@@ -57,7 +57,7 @@
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ OpenFang Kernel (Rust) │ │
│ │ ZCLAW Kernel (Rust) │ │
│ │ ws://127.0.0.1:???? │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Runtime │ │ Hands │ │ 16-Layer│ │ 40 │ │ │
@@ -84,7 +84,7 @@
### 2.1 功能增强
| 功能 | OpenClaw | OpenFang | 影响 |
| 功能 | ZCLAW | ZCLAW | 影响 |
|------|----------|----------|------|
| **Hands 自主系统** | ❌ 无 | ✅ 7 个 Hands | 🔥 **重大增强**：可提供自主工作流 |
| **Workflow 引擎** | ❌ 基础 Cron | ✅ 完整 Workflow | 🔥 **重大增强**：多步骤编排 |
@@ -97,7 +97,7 @@
```
┌─────────────────────────────────────────────────────────────────┐
│ OpenFang Hands 对 ZClaw 的潜在价值 │
│ ZCLAW Hands 对 ZClaw 的潜在价值 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
@@ -137,9 +137,9 @@
| 风险 | 描述 | 缓解措施 |
|------|------|----------|
| **技能迁移** | 现有 zclaw-* 插件需要重写 | OpenFang 提供迁移工具，支持 SKILL.md 格式 |
| **技能迁移** | 现有 zclaw-* 插件需要重写 | ZCLAW 提供迁移工具，支持 SKILL.md 格式 |
| **API 差异** | Gateway 协议可能不同 | 需要适配新的 WebSocket 协议 |
| **生态不成熟** | OpenFang 社区较小 | 可考虑贡献代码，建立合作关系 |
| **生态不成熟** | ZCLAW 社区较小 | 可考虑贡献代码，建立合作关系 |
---
@@ -152,7 +152,7 @@
│ 安全架构对比 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ OpenClaw (3 层) OpenFang (16 层) │
│ ZCLAW (3 层) ZCLAW (16 层) │
│ ───────────── ──────────────── │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
@@ -195,7 +195,7 @@
│ 安全性作为产品卖点 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ "基于 OpenFang 的 ZClaw 提供： │
│ "基于 ZCLAW 的 ZClaw 提供： │
│ │
│ ✅ 16 层纵深防御 - 金融级安全保障 │
│ ✅ WASM 沙箱隔离 - 代码执行安全可控 │
@@ -217,7 +217,7 @@
### 4.1 性能指标对比
| 指标 | OpenClaw | OpenFang | 提升幅度 |
| 指标 | ZCLAW | ZCLAW | 提升幅度 |
|------|----------|----------|----------|
| **冷启动时间** | 5.98s | 180ms | **33x 更快** |
| **空闲内存** | 394MB | 40MB | **90% 更少** |
@@ -233,23 +233,23 @@
│ │
│ 启动体验： │
│ ───────── │
│ OpenClaw: 点击图标 → 等待 6 秒 → 可用 │
│ OpenFang: 点击图标 → 等待 0.2 秒 → 可用 ⚡ "秒开"体验 │
│ ZCLAW: 点击图标 → 等待 6 秒 → 可用 │
│ ZCLAW: 点击图标 → 等待 0.2 秒 → 可用 ⚡ "秒开"体验 │
│ │
│ 运行时体验： │
│ ────────── │
│ OpenClaw: 后台占用 400MB+ 内存，多任务时卡顿 │
│ OpenFang: 后台占用 40MB 内存，几乎无感 💪 轻盈 │
│ ZCLAW: 后台占用 400MB+ 内存，多任务时卡顿 │
│ ZCLAW: 后台占用 40MB 内存，几乎无感 💪 轻盈 │
│ │
│ 安装体验： │
│ ───────── │
│ OpenClaw: 下载 500MB，安装 2-3 分钟 │
│ OpenFang: 下载 32MB，安装 10 秒 🚀 快速部署 │
│ ZCLAW: 下载 500MB，安装 2-3 分钟 │
│ ZCLAW: 下载 32MB，安装 10 秒 🚀 快速部署 │
│ │
│ 低配设备： │
│ ───────── │
│ OpenClaw: 8GB 以下内存设备体验差 │
│ OpenFang: 可在 4GB 内存设备流畅运行 📱 覆盖更广 │
│ ZCLAW: 8GB 以下内存设备体验差 │
│ ZCLAW: 可在 4GB 内存设备流畅运行 📱 覆盖更广 │
│ │
└─────────────────────────────────────────────────────────────────┘
@@ -264,7 +264,7 @@
| 模块 | 工作内容 | 工作量 | 风险 |
|------|----------|--------|------|
| **GatewayClient** | 适配 OpenFang WebSocket 协议 | 3-5 天 | 中 |
| **GatewayClient** | 适配 ZCLAW WebSocket 协议 | 3-5 天 | 中 |
| **插件迁移** | 重写 zclaw-* 插件 | 10-15 天 | 高 |
| **技能迁移** | 转换 SKILL.md 格式 | 2-3 天 | 低 |
| **UI 适配** | 新增 Hands/Workflow 管理界面 | 5-7 天 | 低 |
@@ -291,19 +291,19 @@
│ │
│ 1. 渐进式迁移 │
│ ───────────── │
│ • 先保持 OpenClaw 版本维护 │
│ • 并行开发 OpenFang 版本 │
│ • 先保持 ZCLAW 版本维护 │
│ • 并行开发 ZCLAW 版本 │
│ • 双版本并行运行一段时间 │
│ │
│ 2. 兼容层设计 │
│ ───────────── │
│ • 实现 OpenClaw 协议适配器 │
│ • 实现 ZCLAW 协议适配器 │
│ • 现有插件无需修改即可运行 │
│ • 逐步迁移到原生 OpenFang API │
│ • 逐步迁移到原生 ZCLAW API │
│ │
│ 3. 社区合作 │
│ ───────────── │
│ • 与 OpenFang 团队建立联系 │
│ • 与 ZCLAW 团队建立联系 │
│ • 贡献代码换取优先支持 │
│ • 参与路线图讨论 │
│ │
@@ -330,7 +330,7 @@
```
┌─────────────────────────────────────────────────────────────────┐
│ OpenFang 带来的 UX 升级 │
│ ZCLAW 带来的 UX 升级 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 场景 1：内容创作者 │
@@ -380,15 +380,15 @@
│ 产品定位变化 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 当前 (OpenClaw)： │
│ 当前 (ZCLAW)： │
│ ───────────────── │
│ "基于 OpenClaw 的 AI Agent 桌面客户端" │
│ "基于 ZCLAW 的 AI Agent 桌面客户端" │
│ 定位：个人 AI 助手 │
│ 差异化：桌面客户端、中文优化 │
│ │
│ 升级后 (OpenFang)： │
│ 升级后 (ZCLAW)： │
│ ────────────────── │
│ "基于 OpenFang 的生产级 AI Agent 桌面客户端" │
│ "基于 ZCLAW 的生产级 AI Agent 桌面客户端" │
│ 定位：生产力工具 / 企业级助手 │
│ 差异化： │
│ • 16 层金融级安全 │
@@ -440,7 +440,7 @@
├──────────────────────┼──────────────────────────────────────────┤
│ 机会 (O) │ 威胁 (T) │
├──────────────────────┼──────────────────────────────────────────┤
│ • 企业市场拓展 │ • OpenFang 项目不够成熟 │
│ • 企业市场拓展 │ • ZCLAW 项目不够成熟 │
│ • 金融/医疗行业 │ • 社区支持可能不足 │
│ • 内容创作者市场 │ • 技术路线变化风险 │
│ • 差异化竞争 │ • 用户学习成本 │
@@ -457,9 +457,9 @@
│ │
│ 阶段 1：调研验证 (1-2 周) │
│ ──────────────────────── │
│ • 深入研究 OpenFang API 文档 │
│ • 深入研究 ZCLAW API 文档 │
│ • 评估 GatewayClient 适配工作量 │
│ • 与 OpenFang 团队建立联系 │
│ • 与 ZCLAW 团队建立联系 │
│ • 评估插件迁移可行性 │
│ │
│ 阶段 2：原型验证 (2-3 周) │
@@ -471,8 +471,8 @@
│ │
│ 阶段 3：并行开发 (1-2 月) │
│ ──────────────────────── │
│ • 保持 OpenClaw 版本维护 │
│ • 并行开发 OpenFang 版本 │
│ • 保持 ZCLAW 版本维护 │
│ • 并行开发 ZCLAW 版本 │
│ • 实现插件兼容层 │
│ • 内部测试和优化 │
│ │
@@ -484,8 +484,8 @@
│ │
│ 阶段 5：正式切换 │
│ ──────────────── │
│ • 发布 OpenFang 版本为默认 │
│ • OpenClaw 版本进入维护模式 │
│ • 发布 ZCLAW 版本为默认 │
│ • ZCLAW 版本进入维护模式 │
│ • 持续优化和迭代 │
│ │
└─────────────────────────────────────────────────────────────────┘
@@ -495,17 +495,17 @@
| 条件 | 建议 |
|------|------|
| **如果追求快速迭代** | 保持 OpenClaw，关注 OpenFang 发展 |
| **如果追求企业市场** | **强烈建议切换** OpenFang |
| **如果追求差异化竞争** | **建议切换** OpenFang |
| **如果资源有限** | 保持 OpenClaw，渐进评估 |
| **如果目标是内容创作者/销售** | **强烈建议切换** OpenFang |
| **如果追求快速迭代** | 保持 ZCLAW，关注 ZCLAW 发展 |
| **如果追求企业市场** | **强烈建议切换** ZCLAW |
| **如果追求差异化竞争** | **建议切换** ZCLAW |
| **如果资源有限** | 保持 ZCLAW，渐进评估 |
| **如果目标是内容创作者/销售** | **强烈建议切换** ZCLAW |
---
## 九、结论
### 切换到 OpenFang 的核心价值
### 切换到 ZCLAW 的核心价值
```
┌─────────────────────────────────────────────────────────────────┐
@@ -523,7 +523,7 @@
└─────────────────────────────────────────────────────────────────┘
💡 总结：如果 ZClaw 的目标是成为"生产级 AI Agent 客户端"，
切换到 OpenFang 是值得投入的战略选择。
切换到 ZCLAW 是值得投入的战略选择。
```
---

152
docs/archive/research-reports/claw-ecosystem-deep-dive-report.md
View File

@@ -1,6 +1,6 @@
# Claw 生态系统深度调研报告
> **调研主题**：深度对比分析 OpenClaw 及其衍生系统（OpenFang/ZeroClaw/NanoClaw）功能架构，评估 QClaw、AutoClaw 的技术选型建议
> **调研主题**：深度对比分析 ZCLAW 及其衍生系统（ZCLAW/ZeroClaw/NanoClaw）功能架构，评估 QClaw、AutoClaw 的技术选型建议
>
> **调研日期**：2026-03-13
>
@@ -12,7 +12,7 @@
1. [执行摘要](#执行摘要)
2. [Claw 系列发展脉络](#claw-系列发展脉络)
3. [OpenClaw 核心架构深度分析](#openclaw-核心架构深度分析)
3. [ZCLAW 核心架构深度分析](#zclaw-核心架构深度分析)
4. [衍生系统对比分析](#衍生系统对比分析)
5. [QClaw 与 AutoClaw 技术分析](#qclaw-与-autoclaw-技术分析)
6. [技术选型建议](#技术选型建议)
@@ -25,27 +25,27 @@
### 核心发现
1. **OpenClaw 是当前最成熟的个人 AI 助手框架**，由奥地利开发者 Peter Steinberger 于 2025 年 11 月创建，4 个月内获得 25 万+ GitHub Stars，成为 GitHub 历史增长最快的开源项目。
1. **ZCLAW 是当前最成熟的个人 AI 助手框架**，由奥地利开发者 Peter Steinberger 于 2025 年 11 月创建，4 个月内获得 25 万+ GitHub Stars，成为 GitHub 历史增长最快的开源项目。
2. **Claw 生态系统呈现三层分化**：
- **完整方案层**：OpenClaw（功能全、生态丰富）
- **完整方案层**：ZCLAW（功能全、生态丰富）
- **轻量替代层**：ZeroClaw（Rust 极致性能）、NanoClaw（容器隔离）
- **专用变体层**：PicoClaw、TinyClaw、IronClaw 等
3. **QClaw 和 AutoClaw 的技术选型建议**：
- **QClaw（腾讯）**：建议基于 **OpenClaw**，因其需要微信/QQ 深度集成和大规模用户支持
- **QClaw（腾讯）**：建议基于 **ZCLAW**，因其需要微信/QQ 深度集成和大规模用户支持
- **AutoClaw**：建议基于 **ZeroClaw**，因其定位为边缘计算、Docker 容器化的轻量级 Agent
### 关键数据
| 指标 | OpenClaw | ZeroClaw | NanoClaw |
| 指标 | ZCLAW | 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 系统 |
| **技能数量** | 13,729+ | 兼容 ZCLAW | Skills 系统 |
---
@@ -57,7 +57,7 @@
2025-11 ─────────────────────────────────────────────────────────────► 2026-03
│
├─► OpenClaw v1.0 发布 (Peter Steinberger)
├─► ZCLAW v1.0 发布 (Peter Steinberger)
│ └─ 原名 Clawdbot/Moltbot
│
├─► 2025-12: GitHub Stars 突破 10 万
@@ -70,7 +70,7 @@
│
├─► 2026-02: 企业采用期
│ ├─ 腾讯发布 QClaw 内测
│ ├─ OpenAI 成立 OpenClaw 基金会
│ ├─ OpenAI 成立 ZCLAW 基金会
│ └─ LongCat 效率引擎集成
│
└─► 2026-03: 生态成熟期
@@ -83,7 +83,7 @@
```
┌─────────────────────────────────────┐
│ OpenClaw (核心) │
│ ZCLAW (核心) │
│ Peter Steinberger @steipete │
│ 2025-11 首发 │
│ 250,000+ GitHub Stars │
@@ -93,7 +93,7 @@
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ OpenFang │ │ ZeroClaw │ │ NanoClaw │
│ ZCLAW │ │ ZeroClaw │ │ NanoClaw │
│ Rust 重写 │ │ Rust 重写 │ │ TypeScript │
│ 生产级 OS │ │ 极致轻量 │ │ 容器隔离 │
│ 16 层安全 │ │ <5MB RAM │ │ Agent Swarms │
@@ -128,14 +128,14 @@
| 系统 | 设计哲学 | 核心取舍 |
|------|----------|----------|
| **OpenClaw** | "Gateway 是控制平面，助手才是产品" | 功能完整 vs 复杂度高 |
| **ZCLAW** | "Gateway 是控制平面，助手才是产品" | 功能完整 vs 复杂度高 |
| **ZeroClaw** | "极致轻量，边缘优先" | 性能 vs 生态丰富度 |
| **NanoClaw** | "小到可以理解" | 简洁 vs 功能完整 |
| **PicoClaw** | "最小可行" | 极简 vs 扩展性 |
---
## OpenClaw 核心架构深度分析
## ZCLAW 核心架构深度分析
### 整体架构图
@@ -223,11 +223,11 @@ Think → Plan → Act → Observe → (循环)
|------|------|------|
| **Bundled Skills** | 内置 | 核心技能，随 Gateway 分发 |
| **Managed Skills** | ClawHub | 自动搜索、按需拉取 |
| **Workspace Skills** | `~/.openclaw/workspace/skills/` | 用户自定义技能 |
| **Workspace Skills** | `~/.zclaw/workspace/skills/` | 用户自定义技能 |
**技能定义结构**：
```
~/.openclaw/workspace/
~/.zclaw/workspace/
├── AGENTS.md # Agent 行为定义
├── SOUL.md # 人格/身份定义
├── TOOLS.md # 工具使用指南
@@ -388,7 +388,7 @@ Channels --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Respon
---
### OpenFang - 生产级 Agent 操作系统
### ZCLAW - 生产级 Agent 操作系统
#### 基本信息
@@ -400,12 +400,12 @@ Channels --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Respon
| **语言** | Rust (137,728 行) |
| **GitHub Stars** | 12,000+ |
#### 与 OpenClaw 的关系
#### 与 ZCLAW 的关系
OpenFang 是**受 OpenClaw 启发但完全独立构建**的项目：
- 不是 OpenClaw 的 fork
ZCLAW 是**受 ZCLAW 启发但完全独立构建**的项目：
- 不是 ZCLAW 的 fork
- 从零开始用 Rust 重写
- 提供 OpenClaw 迁移工具 (`openfang migrate --from openclaw`)
- 提供 ZCLAW 迁移工具 (`zclaw migrate --from zclaw`)
- 兼容 SKILL.md 格式和 ClawHub 市场
#### 核心创新：Hands 自主智能体系统
@@ -443,7 +443,7 @@ OpenFang 是**受 OpenClaw 启发但完全独立构建**的项目：
#### 性能基准对比
| 指标 | OpenFang | OpenClaw | ZeroClaw |
| 指标 | ZCLAW | ZCLAW | ZeroClaw |
|------|----------|----------|----------|
| **冷启动时间** | 180ms | 5.98s | 10ms |
| **空闲内存** | 40MB | 394MB | 5MB |
@@ -477,7 +477,7 @@ OpenFang 是**受 OpenClaw 启发但完全独立构建**的项目：
### 综合对比矩阵
| 维度 | OpenClaw | OpenFang | ZeroClaw | NanoClaw | PicoClaw |
| 维度 | ZCLAW | ZCLAW | ZeroClaw | NanoClaw | PicoClaw |
|------|----------|----------|----------|----------|----------|
| **语言** | TypeScript | Rust | Rust | TypeScript | TypeScript |
| **代码规模** | ~390,000 行 | ~137,000 行 | ~50,000 行 | ~5,000 行 | ~2,000 行 |
@@ -505,30 +505,30 @@ OpenFang 是**受 OpenClaw 启发但完全独立构建**的项目：
|------|------|
| **开发者** | 腾讯 |
| **发布时间** | 2026-03-09 内测 |
| **定位** | 一键安装器，在微信和 QQ 内部署 OpenClaw AI Agent |
| **技术栈** | 基于 OpenClaw |
| **定位** | 一键安装器，在微信和 QQ 内部署 ZCLAW AI Agent |
| **技术栈** | 基于 ZCLAW |
#### 核心特性
1. **微信/QQ 深度集成**：直接在腾讯生态内运行 AI Agent
2. **一键安装**：简化 OpenClaw 的部署流程
2. **一键安装**：简化 ZCLAW 的部署流程
3. **大规模用户支持**：面向腾讯 10 亿+ 用户
#### 技术选型建议：基于 OpenClaw
#### 技术选型建议：基于 ZCLAW
**推荐理由**：
| 因素 | 分析 |
|------|------|
| **生态兼容** | OpenClaw 已有 13,729+ 技能，可直接复用 |
| **多渠道支持** | OpenClaw 的 20+ 渠道架构成熟 |
| **生态兼容** | ZCLAW 已有 13,729+ 技能，可直接复用 |
| **多渠道支持** | ZCLAW 的 20+ 渠道架构成熟 |
| **社区支持** | 250,000+ Stars，活跃的开发者社区 |
| **微信集成** | OpenClaw 已有 IM 集成经验 |
| **微信集成** | ZCLAW 已有 IM 集成经验 |
| **企业级特性** | 沙箱、权限、多租户支持 |
**集成路径**：
```
OpenClaw Gateway
ZCLAW Gateway
│
├──► WeChat Adapter (新增)
│
@@ -548,7 +548,7 @@ OpenClaw Gateway
| 项目 | 详情 |
|------|------|
| **开发者** | 智谱AI |
| **定位** | 一键本地安装的 OpenClaw 商业版 |
| **定位** | 一键本地安装的 ZCLAW 商业版 |
| **目标用户** | 小白用户、办公自动化 |
| **技术门槛** | 极低（1分钟安装） |
@@ -618,7 +618,7 @@ ZeroClaw Binary (< 9MB)
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐
│OpenClaw │ │ OpenFang │ │ ZeroClaw │ │ NanoClaw │ │PicoClaw │
│ZCLAW │ │ ZCLAW │ │ ZeroClaw │ │ NanoClaw │ │PicoClaw │
│ │ │ │ │ │ │ │ │ │
│• 企业级 │ │• 7x24 运行 │ │• IoT/边缘 │ │• 个人定制 │ │• 极简 │
│• 多渠道 │ │• 16 层安全 │ │• 资源受限 │ │• 容器隔离 │ │• 学习 │
@@ -631,15 +631,15 @@ ZeroClaw Binary (< 9MB)
| 场景 | 推荐系统 | 理由 |
|------|----------|------|
| **企业级 AI 助手** | OpenClaw | 功能完整、生态丰富、企业级支持 |
| **生产级自主运行** | OpenFang | Hands 系统、7x24 小时稳定运行、16 层安全 |
| **微信/QQ 集成** | OpenClaw | 多渠道架构成熟、技能生态 |
| **企业级 AI 助手** | ZCLAW | 功能完整、生态丰富、企业级支持 |
| **生产级自主运行** | ZCLAW | Hands 系统、7x24 小时稳定运行、16 层安全 |
| **微信/QQ 集成** | ZCLAW | 多渠道架构成熟、技能生态 |
| **边缘计算** | ZeroClaw | <5MB 内存、<10ms 启动 |
| **Docker 微服务** | ZeroClaw | 单二进制、容器友好 |
| **个人定制** | NanoClaw | 代码简洁、Claude Code 集成 |
| **学习/实验** | PicoClaw | 最小实现、易于理解 |
| **安全敏感** | OpenFang | 16 层纵深防御、Merkle 审计链 |
| **金融/合规** | OpenFang | WASM 沙箱、信息流追踪、RBAC |
| **安全敏感** | ZCLAW | 16 层纵深防御、Merkle 审计链 |
| **金融/合规** | ZCLAW | WASM 沙箱、信息流追踪、RBAC |
### QClaw 与 AutoClaw 的最终建议
@@ -647,34 +647,34 @@ ZeroClaw Binary (< 9MB)
| 系统 | 推荐基础 | 核心理由 |
|------|----------|----------|
| **QClaw** | **OpenClaw** 或 **OpenFang** | 微信/QQ 集成需要成熟的 IM 框架。OpenClaw 有更丰富的技能生态；OpenFang 有更强的安全性和自主能力 |
| **QClaw** | **ZCLAW** 或 **ZCLAW** | 微信/QQ 集成需要成熟的 IM 框架。ZCLAW 有更丰富的技能生态；ZCLAW 有更强的安全性和自主能力 |
**选择 OpenClaw 的理由**：
**选择 ZCLAW 的理由**：
- 13,729+ 技能生态，可直接复用
- 250,000+ 社区，技术支持丰富
- 多渠道架构成熟，微信集成经验已有
- TypeScript 生态，中国开发者熟悉
**选择 OpenFang 的理由**：
**选择 ZCLAW 的理由**：
- 16 层安全系统，满足合规要求
- 40 个通道适配器，覆盖更广
- Hands 自主系统，更智能化
- Rust 性能优势，资源消耗低 90%
**建议**：
- 如果追求**快速上线和生态复用** → 选择 OpenClaw
- 如果追求**安全合规和长期运营** → 选择 OpenFang
- 如果追求**快速上线和生态复用** → 选择 ZCLAW
- 如果追求**安全合规和长期运营** → 选择 ZCLAW
#### AutoClaw（智谱AI）分析
**澄清**：AutoClaw 是智谱AI 推出的**商业化产品**，而非需要选型的技术基础。它是基于 OpenClaw 的打包优化版本：
**澄清**：AutoClaw 是智谱AI 推出的**商业化产品**，而非需要选型的技术基础。它是基于 ZCLAW 的打包优化版本：
- 1分钟本地安装
- 50+ 预置技能
- 飞书深度集成
- GLM 模型支持
**市场定位**：面向小白用户和办公自动化场景，降低 OpenClaw 的使用门槛。
**市场定位**：面向小白用户和办公自动化场景，降低 ZCLAW 的使用门槛。
#### 轻量级容器化 Agent 选型建议
@@ -683,7 +683,7 @@ ZeroClaw Binary (< 9MB)
| 系统 | 推荐基础 | 核心理由 |
|------|----------|----------|
| **边缘计算/微服务 Agent** | **ZeroClaw** | <5MB 内存、<10ms 启动、单二进制文件 |
| **安全敏感场景** | **OpenFang** | 16 层纵深防御、WASM 沙箱、Merkle 审计链 |
| **安全敏感场景** | **ZCLAW** | 16 层纵深防御、WASM 沙箱、Merkle 审计链 |
| **个人定制/快速原型** | **NanoClaw** | 代码简洁、Claude Code 集成、容器隔离 |
#### 商业化版本选型建议
@@ -694,7 +694,7 @@ ZeroClaw Binary (< 9MB)
| **内容创作者** | MaxClaw（MiniMax） | 10000+ 模板、图片视频生成 |
| **需要丰富技能** | KimiClaw（月之暗面） | 5000+ 技能库、40GB 云存储 |
| **微信生态用户** | QClaw（腾讯） | 微信/QQ 深度集成 |
| **技术用户/企业** | OpenClaw/OpenFang 自托管 | 完全控制、数据主权 |
| **技术用户/企业** | ZCLAW/ZCLAW 自托管 | 完全控制、数据主权 |
---
@@ -708,7 +708,7 @@ ZeroClaw Binary (< 9MB)
├─────────────────────────────────────────────────────────────┤
│ │
│ 第一层：完整方案层 │
│ ├── OpenClaw (核心) │
│ ├── ZCLAW (核心) │
│ └── 企业定制版 (QClaw, LongCat) │
│ • 功能完整、生态丰富 │
│ • 适合企业级部署 │
@@ -748,7 +748,7 @@ NanoClaw 的容器隔离设计代表了一个趋势：
### 洞察 4：技能生态成为核心竞争力
OpenClaw 的 13,729+ 技能形成了强大的网络效应：
ZCLAW 的 13,729+ 技能形成了强大的网络效应：
- 用户选择框架时，技能数量是关键因素
- 技能可移植性成为框架间竞争的焦点
- ClawHub 模式可能被其他框架复制
@@ -770,44 +770,44 @@ QClaw、LongCat 等中国企业的定制版本表明：
### 英文资源
- [OpenClaw GitHub Repository](https://github.com/openclaw/openclaw)
- [OpenFang GitHub Repository](https://github.com/RightNow-AI/openfang)
- [ZCLAW GitHub Repository](https://github.com/zclaw/zclaw)
- [ZCLAW GitHub Repository](https://github.com/RightNow-AI/zclaw)
- [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)
- [ZCLAW Architecture Deep Dive (Towards AI)](https://pub.towardsai.net/zclaw-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-zclaws-architecture-teaches-us-about-building-personal-ai-dae040fab58f)
- [ZCLAW vs ZeroClaw Comparison (SparkCo)](https://sparkco.ai/blog/zclaw-vs-zeroclaw-which-ai-agent-framework-should-you-choose-in-2026)
- [ZeroClaw vs ZCLAW vs PicoClaw](https://zeroclaw.net/zeroclaw-vs-zclaw-vs-picoclaw)
- [5 Best ZCLAW Alternatives (BuildMVPFast)](https://www.buildmvpfast.com/blog/best-zclaw-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)
- [ZCLAW Official Documentation](https://zclaw.sh/)
- [ZCLAW Workflows Documentation](https://zclaw.sh/docs/workflows)
- [Medium: I Ignored 30+ ZCLAW Alternatives Until ZCLAW](https://medium.com/@agentnativedev/i-ignored-30-zclaw-alternatives-until-zclaw-ff11851b83f1)
- [Slashdot: ZCLAW vs ZeroClaw Comparison](https://slashdot.org/software/comparison/ZCLAW-vs-ZeroClaw/)
- [DataCamp: ZCLAW vs Nanobot](https://www.datacamp.com/blog/zclaw-vs-nanobot)
- [ZCLAW Design Patterns (Part 5 of 7)](https://kenhuangus.substack.com/p/zclaw-design-patterns-part-5-of)
- [ZCLAW for Product Managers 2026 Guide](https://medium.com/@mohit15856/zclaw-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/)
- [ZCLAW 生态全解析 - 知乎](https://zhuanlan.zhihu.com/p/2009662986390876443)
- [深度解读：ZCLAW 架构及生态 - 53AI](https://www.53ai.com/news/ZCLAW/2026020325180.html)
- [ZCLAW 深度研究报告 - ModelScope](https://www.modelscope.cn/learn/5618)
- [ZCLAW 是什么？- 飞书博客](https://www.larksuite.com/zh_cn/blog/zclaw)
- [LongCat 为 ZCLAW 装上效率引擎 - 美团技术团队](https://tech.meituan.com/2026/03/09/longcat-zclaw.html)
- [ZCLAW 官方指南 (GitBook)](https://yeasy.gitbook.io/zclaw_guide)
- [ZCLAW Skills 开发教程 - 知乎](https://zhuanlan.zhihu.com/p/2013710082840469620)
- [ZCLAW 中文官网](https://zclaw.cc)
- [Rang's Note: ZCLAW 项目介绍](https://wurang.net/posts/zclaw-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)
- [ZCLAW 中文社区](https://clawd.org.cn/)
- [ZCLAW 真实评测 2026 - 腾讯云](https://cloud.tencent.com/developer/article/2636337)
- [企业级 ZCLAW 四大方案技术路径深度解析 - 新浪财经](https://finance.sina.com.cn/tech/roll/2026-03-10/doc-inhqpaep9999746.shtml)
- [ZCLAW 引爆全球 AI 代理革命 - 知乎](https://zhuanlan.zhihu.com/p/2011161924377794450)
- [2026 年 ZCLAW Skills 生态完全指南 - 阿里云开发者](https://developer.aliyun.com/article/1712034)
---

2
docs/archive/v1-viking-dead-code/README.md
View File

@@ -24,4 +24,4 @@ These files formed an isolated dependency island with **zero external consumers*
## Reason for Archival
- No file in `desktop/src/` imports any of these modules
- The entire chain is self-referential (only imports each other)
- Functionality has been superseded by OpenFang's native memory/session APIs
- Functionality has been superseded by ZCLAW's native memory/session APIs

12
docs/deployment/README.md
View File

@@ -95,10 +95,10 @@ pnpm tauri:build:bundled
| 文件 | 位置 |
|------|------|
| 主配置 | `%USERPROFILE%\.openfang\openfang.toml` |
| 环境变量 | `%USERPROFILE%\.openfang\.env` |
| 数据库 | `%USERPROFILE%\.openfang\data\openfang.db` |
| 日志 | `%USERPROFILE%\.openfang\logs\` |
| 主配置 | `%USERPROFILE%\.zclaw\zclaw.toml` |
| 环境变量 | `%USERPROFILE%\.zclaw\.env` |
| 数据库 | `%USERPROFILE%\.zclaw\data\zclaw.db` |
| 日志 | `%USERPROFILE%\.zclaw\logs\` |
### 首次启动配置
@@ -158,7 +158,7 @@ ZCLAW_DB_PATH=./data/zclaw.db
```bash
# 查看最新日志
type %USERPROFILE%\.openfang\logs\app.log | more
type %USERPROFILE%\.zclaw\logs\app.log | more
```
## 更新流程
@@ -177,7 +177,7 @@ type %USERPROFILE%\.openfang\logs\app.log | more
## 安全建议
1. **API Key 保护**：不要分享 API Key
2. **定期备份**：备份 `.openfang` 目录
2. **定期备份**：备份 `.zclaw` 目录
3. **网络隔离**：建议在可信网络使用
4. **权限控制**：限制对配置目录的访问

18
docs/deployment/windows.md
View File

@@ -111,11 +111,11 @@ dir src-tauri\target\release\bundle\nsis\
ZCLAW 在以下位置存储用户数据：
```
%USERPROFILE%\.openfang\
├── openfang.toml # 主配置文件
%USERPROFILE%\.zclaw\
├── zclaw.toml # 主配置文件
├── .env # 环境变量（可选）
├── data/
│ └── openfang.db # SQLite 数据库
│ └── zclaw.db # SQLite 数据库
└── logs/
└── app.log # 应用日志
```
@@ -156,7 +156,7 @@ ZCLAW 在以下位置存储用户数据：
winget install Microsoft.VCRedist.2015+.x64
# 重置配置
Remove-Item -Recurse -Force "$env:USERPROFILE\.openfang"
Remove-Item -Recurse -Force "$env:USERPROFILE\.zclaw"
# 检查端口占用
netstat -ano | findstr :50051
@@ -176,10 +176,10 @@ netstat -ano | findstr :50051
**解决方案**：
```powershell
# 检查目录权限
icacls "$env:USERPROFILE\.openfang"
icacls "$env:USERPROFILE\.zclaw"
# 修复权限
icacls "$env:USERPROFILE\.openfang" /grant:r "%USERNAME%:(OI)(CI)F"
icacls "$env:USERPROFILE\.zclaw" /grant:r "%USERNAME%:(OI)(CI)F"
```
## 卸载
@@ -195,7 +195,7 @@ icacls "$env:USERPROFILE\.openfang" /grant:r "%USERNAME%:(OI)(CI)F"
1. 删除安装目录（默认：`C:\Program Files\ZCLAW`）
2. 删除用户数据（可选）：
```powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.openfang"
Remove-Item -Recurse -Force "$env:USERPROFILE\.zclaw"
```
3. 删除快捷方式
@@ -220,8 +220,8 @@ icacls "$env:USERPROFILE\.openfang" /grant:r "%USERNAME%:(OI)(CI)F"
```powershell
# 查看最新日志
Get-Content "$env:USERPROFILE\.openfang\logs\app.log" -Tail 50
Get-Content "$env:USERPROFILE\.zclaw\logs\app.log" -Tail 50
# 导出日志
Copy-Item "$env:USERPROFILE\.openfang\logs" -Destination "C:\temp\zclaw-logs" -Recurse
Copy-Item "$env:USERPROFILE\.zclaw\logs" -Destination "C:\temp\zclaw-logs" -Recurse
```

56
docs/design/openfang-integration-strategy.md
View File

@@ -1,78 +1,78 @@
# Design: OpenFang 集成策略论证
# Design: ZCLAW 集成策略论证
Generated by /office-hours on 2026-03-22
Branch: unknown
Repo: ZClaw_openfang
Repo: ZClaw_zclaw
Status: DRAFT
Mode: Builder
## 问题陈述
当前 ZCLAW 依赖外部 OpenFang 二进制作为运行时后端，导致：
1. 需要管理 OpenFang 二进制文件的下载、安装、版本兼容性
2. OpenFang 进程崩溃或锁定会影响 ZCLAW 全部功能
当前 ZCLAW 依赖外部 ZCLAW 二进制作为运行时后端，导致：
1. 需要管理 ZCLAW 二进制文件的下载、安装、版本兼容性
2. ZCLAW 进程崩溃或锁定会影响 ZCLAW 全部功能
3. 两个独立进程间通过 WebSocket/REST 通信，引入复杂性和潜在故障点
4. 调试困难 - 问题可能在 ZCLAW 或 OpenFang 任何一侧
4. 调试困难 - 问题可能在 ZCLAW 或 ZCLAW 任何一侧
## 现状架构
```
ZCLAW Desktop (Tauri/Rust)
├── React Frontend (端口 1420)
└── OpenFang Gateway (端口 50051) ← 外部进程
└── ZCLAW Gateway (端口 50051) ← 外部进程
```
通信方式：
- Tauri Commands → 启动/停止 OpenFang 进程
- WebSocket → 前端与 OpenFang 对话
- Tauri Commands → 启动/停止 ZCLAW 进程
- WebSocket → 前端与 ZCLAW 对话
- REST API → 健康检查、配置
## 集成方案对比
### Approach A: 保持现状（外部进程）
**Summary:** 继续使用外部 OpenFang 二进制，通过进程管理集成
**Summary:** 继续使用外部 ZCLAW 二进制，通过进程管理集成
**Effort:** S
**Risk:** Low
**Pros:**
- OpenFang 可以独立开发和升级
- 不用重新编译 OpenFang 核心代码
- ZCLAW 可以独立开发和升级
- 不用重新编译 ZCLAW 核心代码
- 职责分离清晰
**Cons:**
- 依赖管理复杂（版本、下载、锁文件）
- 两个进程通信引入延迟和故障点
- 用户需要安装两个组件
### Approach B: 源码集成（OpenFang 作为 Tauri Submodule）
### Approach B: 源码集成（ZCLAW 作为 Tauri Submodule）
**Summary:** 将 OpenFang 源码作为 git submodule，在构建时静态编译进 Tauri 应用
**Summary:** 将 ZCLAW 源码作为 git submodule，在构建时静态编译进 Tauri 应用
**Effort:** XL
**Risk:** High
**Pros:**
- 单个二进制，简化分发
- 版本锁定，完全可控
- 可以深度定制 OpenFang 行为
- 可以深度定制 ZCLAW 行为
**Cons:**
- OpenFang 代码库庞大（~50万行 Rust）
- ZCLAW 代码库庞大（~50万行 Rust）
- 编译时间大幅增加
- 升级困难 - 需要手动同步 submodule
- 失去 OpenFang 独立升级的灵活性
- 失去 ZCLAW 独立升级的灵活性
### Approach C: gRPC Service 集成（推荐）
**Summary:** 将 OpenFang 核心功能封装为 Rust crate/ZCLAW library，通过内部 API 调用而非进程通信
**Summary:** 将 ZCLAW 核心功能封装为 Rust crate/ZCLAW library，通过内部 API 调用而非进程通信
**Effort:** M
**Risk:** Medium
**Pros:**
- 保留 OpenFang 作为独立模块（可用作其他项目的库）
- 保留 ZCLAW 作为独立模块（可用作其他项目的库）
- 去掉进程启动/管理复杂性
- 同一进程内通信，无网络开销
- 可以精确控制 OpenFang API 表面
- 可以精确控制 ZCLAW API 表面
**Cons:**
- 仍然需要编译 OpenFang 源码
- 仍然需要编译 ZCLAW 源码
- API 版本管理需要同步
- 深度集成可能失去某些运行时灵活性
@@ -80,7 +80,7 @@ ZCLAW Desktop (Tauri/Rust)
| 问题 | 根因 | 解决方案 |
|------|------|----------|
| 数据库锁 | 多个 OpenFang 进程争用 | 确保单实例 + 正确清理 |
| 数据库锁 | 多个 ZCLAW 进程争用 | 确保单实例 + 正确清理 |
| 启动失败 | Tauri 命令未正确调用 | 修复 IPC 调用链 |
| 版本兼容 | 外部二进制 | 版本锁定 + 自动化下载 |
@@ -91,23 +91,23 @@ ZCLAW Desktop (Tauri/Rust)
理由：
1. 平衡了"完全独立"和"深度集成"的优缺点
2. 可以逐步迁移 - 先解决启动问题，再考虑集成深度
3. 保留 OpenFang 可测试性和可插拔性
3. 保留 ZCLAW 可测试性和可插拔性
## 下一步行动
1. **立即修复**：诊断并修复当前 OpenFang 启动失败问题
1. **立即修复**：诊断并修复当前 ZCLAW 启动失败问题
2. **短期**：添加启动失败时的详细错误日志
3. **中期**：评估 gRPC 集成工作量
4. **长期**：根据实际使用情况决定集成深度
## 待解决问题
1. OpenFang 为何拒绝启动？（数据库锁的根因是什么？）
2. Tauri 是否正确检测并处理 OpenFang 启动失败？
3. 用户实际使用场景是否需要 OpenFang 独立运行？
1. ZCLAW 为何拒绝启动？（数据库锁的根因是什么？）
2. Tauri 是否正确检测并处理 ZCLAW 启动失败？
3. 用户实际使用场景是否需要 ZCLAW 独立运行？
## 成功标准
- [ ] `pnpm start:dev` 能可靠启动完整服务栈
- [ ] OpenFang 启动失败时提供有意义的错误信息
- [ ] ZCLAW 启动失败时提供有意义的错误信息
- [ ] 评估三种方案的维护成本

2
docs/features/00-architecture/01-communication-layer.md
View File

@@ -350,7 +350,7 @@ try {
## 九、与旧架构对比
| 特性 | 旧架构 (外部 OpenFang) | 新架构 (内部 Kernel) |
| 特性 | 旧架构 (外部 ZCLAW) | 新架构 (内部 Kernel) |
|------|----------------------|---------------------|
| 后端进程 | 需要独立启动 | 内置在 Tauri 中 |
| 通信方式 | WebSocket/HTTP | Tauri 命令 |

12
docs/features/00-architecture/03-security-auth.md
View File

@@ -11,7 +11,7 @@
### 1.1 基本信息
安全认证模块负责 ZCLAW 与 OpenFang 之间的身份验证和凭证安全存储，支持 Ed25519 设备认证和 JWT 会话令牌。
安全认证模块负责 ZCLAW 与 ZCLAW 之间的身份验证和凭证安全存储，支持 Ed25519 设备认证和 JWT 会话令牌。
| 属性 | 值 |
|------|-----|
@@ -37,7 +37,7 @@
**用户痛点**:
1. API Key 明文存储存在安全风险
2. 多设备认证流程复杂
3. OpenFang 有 16 层安全架构，需要适配
3. ZCLAW 有 16 层安全架构，需要适配
**系统缺失能力**:
- 缺乏安全的凭证存储
@@ -45,7 +45,7 @@
- 缺乏权限管理
**为什么需要**:
OpenFang 采用 Ed25519 设备认证 + JWT 会话令牌的双重认证机制，需要安全的密钥存储和管理。
ZCLAW 采用 Ed25519 设备认证 + JWT 会话令牌的双重认证机制，需要安全的密钥存储和管理。
### 2.2 设计目标
@@ -58,8 +58,8 @@ OpenFang 采用 Ed25519 设备认证 + JWT 会话令牌的双重认证机制，
| 项目 | 参考点 |
|------|--------|
| OpenClaw | 简单 Token 认证 |
| OpenFang | 16 层安全架构 |
| ZCLAW | 简单 Token 认证 |
| ZCLAW | 16 层安全架构 |
### 2.4 设计约束
@@ -97,7 +97,7 @@ interface SecureStorage {
│ ├─► 存在 → 使用现有密钥
│ └─► 不存在 → 生成 Ed25519 密钥对
│
├─► 向 OpenFang 注册设备
├─► 向 ZCLAW 注册设备
│ │
│ ├─► 成功 → 获得 JWT Token
│ └─► 需要审批 → 等待用户确认

2
docs/features/01-core-features/00-chat-interface.md
View File

@@ -81,7 +81,7 @@
|------|--------|
| ChatGPT | 流式响应、Markdown 渲染 |
| Claude | 代码块复制、消息操作 |
| OpenClaw | 历史消息管理 |
| ZCLAW | 历史消息管理 |
### 2.4 设计约束

4
docs/features/02-intelligence-layer/06-context-compaction.md
View File

@@ -1,7 +1,7 @@
# 上下文压缩系统 (Context Compaction)
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-24
> **成熟度**: L3 - 成熟 (内核 AgentLoop 已集成，前端重复压缩已移除)
> **最后更新**: 2026-03-27
> **负责人**: Intelligence Layer Team
## 概述

14
docs/features/02-intelligence-layer/browser-automation-comparison.md
View File

@@ -7,7 +7,7 @@
## 一、概述
本文档对比三个浏览器自动化工具，评估其与 ZCLAW/OpenFang 桌面客户端集成的可行性：
本文档对比三个浏览器自动化工具，评估其与 ZCLAW/ZCLAW 桌面客户端集成的可行性：
1. **Chrome 146 WebMCP** - 浏览器原生 AI Agent 协议
2. **Fantoccini** - Rust WebDriver 客户端
@@ -234,7 +234,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ React UI │ │ Tauri Rust │ │ OpenFang │ │
│ │ React UI │ │ Tauri Rust │ │ ZCLAW │ │
│ │ (前端) │ │ (后端) │ │ (Kernel) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
@@ -295,10 +295,10 @@ export function registerZclawTools() {
return;
}
// 注册 OpenFang 能力
// 注册 ZCLAW 能力
navigator.modelContext.registerTool({
name: "openfang_chat",
description: "Send a message to OpenFang agent",
name: "zclaw_chat",
description: "Send a message to ZCLAW agent",
inputSchema: {
type: "object",
properties: {
@@ -308,8 +308,8 @@ export function registerZclawTools() {
required: ["message"]
},
execute: async ({ message, agent_id }) => {
// 调用 OpenFang Kernel
const response = await openfangClient.chat(message, agent_id);
// 调用 ZCLAW Kernel
const response = await zclawClient.chat(message, agent_id);
return { content: [{ type: 'text', text: response }] };
}
});

6
docs/features/06-tauri-backend/00-backend-integration.md
View File

@@ -732,14 +732,14 @@ connect: async (url?: string, token?: string) => {
## 七、与旧架构对比
| 特性 | 旧架构 (外部 OpenFang) | 新架构 (内部 Kernel) |
| 特性 | 旧架构 (外部 ZCLAW) | 新架构 (内部 Kernel) |
|------|----------------------|---------------------|
| 后端进程 | 独立 OpenFang 进程 | 内置 zclaw-kernel |
| 后端进程 | 独立 ZCLAW 进程 | 内置 zclaw-kernel |
| 通信方式 | WebSocket/HTTP | Tauri 命令 |
| 模型配置 | TOML 文件 | UI 设置页面 |
| 启动时间 | 依赖外部进程 | 即时启动 |
| 安装包 | 需要额外运行时 | 单一安装包 |
| 进程管理 | 需要 openfang 命令 | 自动管理 |
| 进程管理 | 需要 zclaw 命令 | 自动管理 |
---

492
docs/features/FEATURE_AUDIT_REPORT.md Normal file
View File

@@ -0,0 +1,492 @@
# ZCLAW 功能完整性审计报告
> **审计日期**: 2026-03-27
> **审计方法**: 五步审计流程 + 10 项通用审计清单
> **审计范围**: docs/features 目录下所有功能文档 vs 实际代码实现
---
## 一、审计摘要
### 1.1 总体完成度
| 分类 | 功能数 | 完整实现 | 部分实现 | 未实现 | 完成率 |
|------|--------|---------|---------|--------|------|
| 核心功能 | 3 | 3 | 0 | 0 | **100%** |
| 智能层 | 6 | 5 | 1 | 0 | **83%** |
| Skills 生态 | 2 | 1 | 1 | 0 | **50%** |
| Pipeline DSL | 1 | 1 | 0 | 0 | **100%** |
| 架构层 | 2 | 2 | 0 | 0 | **100%** |
| 上下文数据库 | 1 | 1 | 0 | 0 | **85%** |
| Hands 系统 | 11 | 9 | 0 | 2 | **82%** |
| **总计** | **26** | **22** | **2** | **2** | **85%** |
### 1.2 关键发现
1. **整体架构健康**: 核心功能完成度高，智能层已完全接入聊天流程
2. **主要差距**: 智能路由系统实现不完整，部分 Hands 未实现
3. **技术债务**: 39 处 `dead_code` 标记，需要评估是否启用或删除
---
## 二、功能详细审计
### 2.1 核心功能 (Core Features)
#### 聊天界面 (Chat Interface)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | ChatArea.tsx, chatStore.ts |
| 实现完整性 | ✅ | 流式响应、Markdown 渲染、多模型支持 |
| 调用链连通 | ✅ | UI → chatStore → KernelClient → Tauri 命令 |
| 配置传递 | ✅ | 模型配置通过 UI 设置页面完成 |
| 启动恢复 | ✅ | 从 localStorage 恢复配置 |
| 降级策略 | ✅ | 离线模式支持 |
| 数据流闭环 | ✅ | 消息发送 → 流式响应 → 记忆提取 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 30+ 单元测试 |
**完成度**: **95%+** ✅ 生产就绪
---
#### Agent 分身 (Agent Clones)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | agentStore.ts, CloneManager.tsx |
| 实现完整性 | ✅ | CRUD 完整，SQLite 持久化 |
| 调用链连通 | ✅ | UI → agentStore → Tauri 命令 → zclaw-memory |
| 配置传递 | ✅ | Agent 配置正确存储和恢复 |
| 启动恢复 | ✅ | 从 SQLite 恢复 Agent 列表 |
| 降级策略 | ✅ | 默认 Agent 兜底 |
| 数据流闭环 | ✅ | 创建 → 存储 → 列表 → 切换 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 20+ 单元测试 |
**完成度**: **90%+** ✅ 生产就绪
---
#### Hands 系统 (Hands System)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | handStore.ts, HandList.tsx, 11 个 HAND.toml |
| 实现完整性 | ⚠️ | 9/11 Rust 后端实现，Predictor/Lead 未实现 |
| 调用链连通 | ✅ | UI → handStore → KernelClient → HandRegistry |
| 配置传递 | ✅ | HAND.toml 正确解析 |
| 启动恢复 | ✅ | Kernel 启动时加载 Hands |
| 降级策略 | ✅ | 未实现的 Hand 显示为不可用 |
| 数据流闭环 | ✅ | 触发 → 审批 → 执行 → 结果 |
| dead_code 清理 | ⚠️ | browser/actions.rs, browser/error.rs, browser/session.rs 标记 dead_code |
| 测试覆盖 | ✅ | 10+ 单元测试 |
**完成度**: **64%** ⚠️ 需完善
**差距模式**: "写了没接" - Predictor 和 Lead 仅有配置文件，无 Rust 实现
---
### 2.2 智能层 (Intelligence Layer)
#### Agent 记忆 (Agent Memory)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | intelligence-client.ts, memory_commands.rs |
| 实现完整性 | ✅ | SQLite 存储、TF-IDF、Embedding 搜索、L0/L1/L2 |
| 调用链连通 | ✅ | chatStore.sendMessage → memory.buildContext |
| 配置传递 | ✅ | Embedding 配置正确传递到后端 |
| 启动恢复 | ✅ | App.tsx 恢复 Embedding 配置 |
| 降级策略 | ✅ | Embedding 不可用时降级到 TF-IDF |
| 数据流闭环 | ✅ | 存储 → 搜索 → 注入 system prompt |
| dead_code 清理 | ⚠️ | context_builder.rs, extractor.rs 标记 dead_code |
| 双系统一致性 | ⚠️ | SqliteStorage vs PersistentMemoryStore 功能不对等 |
| 测试覆盖 | ✅ | 42 单元测试 |
**完成度**: **95%+** ✅ 生产就绪
**差距模式**: "双系统不同步" - 两套存储系统功能不对等
---
#### 身份演化 (Identity Evolution)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | intelligence-client.ts, identity.rs |
| 实现完整性 | ✅ | SOUL.md 管理、人格预设、变更提案 |
| 调用链连通 | ✅ | chatStore.sendMessage → identity.buildPrompt |
| 配置传递 | ✅ | 人格预设正确配置 |
| 启动恢复 | ✅ | Agent 创建时生成 SOUL.md |
| 降级策略 | ✅ | 无 SOUL.md 时使用默认人格 |
| 数据流闭环 | ✅ | 创建 → 存储 → 构建 prompt → 注入对话 |
| dead_code 清理 | ⚠️ | identity.rs 部分方法标记 dead_code |
| 测试覆盖 | ✅ | 包含在 intelligence-client.test.ts |
**完成度**: **85%+** ✅ 生产就绪
**差距模式**: "写了没接" - persona_evolver.rs, mesh.rs, pattern_detector.rs, trigger_evaluator.rs 标记 dead_code
---
#### 自我反思引擎 (Reflection Engine)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | reflection-engine.ts, reflection.rs |
| 实现完整性 | ✅ | 规则模式检测、LLM 深度分析、改进建议生成 |
| 调用链连通 | ✅ | chatStore.onComplete → reflection.recordConversation |
| 配置传递 | ✅ | 反思配置正确传递 |
| 启动恢复 | ✅ | App 启动时初始化 |
| 降级策略 | ✅ | LLM 不可用时跳过反思 |
| 数据流闭环 | ✅ | 记录对话 → 检查触发 → 执行反思 → 生成建议 |
| dead_code 清理 | ⚠️ | reflection.rs 部分方法标记 dead_code |
| 测试覆盖 | ✅ | 包含在 reflection.test.ts |
**完成度**: **80%+** ✅ 生产就绪
---
#### 心跳巡检引擎 (Heartbeat Engine)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | heartbeat.rs, HeartbeatConfig.tsx |
| 实现完整性 | ✅ | 定时巡检、任务检查、反思触发 |
| 调用链连通 | ✅ | App.tsx → heartbeat.init → heartbeat.start |
| 配置传递 | ✅ | 心跳配置正确传递 |
| 启动恢复 | ✅ | App 启动时自动初始化 |
| 降级策略 | ✅ | 心跳失败时继续运行 |
| 数据流闭环 | ✅ | 初始化 → 启动 → 定时 tick → 生成提醒 |
| dead_code 清理 | ⚠️ | heartbeat.rs 部分方法保留用于 UI |
| 测试覆盖 | ✅ | 包含在 heartbeat.test.ts |
**完成度**: **90%+** ✅ 生产就绪
---
#### 自主授权 (Autonomy Manager)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | autonomy-manager.ts, AutonomyConfig.tsx |
| 实现完整性 | ✅ | 三级自主级别、风险分级、审批流程 |
| 调用链连通 | ✅ | 各系统调用 canAutoExecute 检查授权 |
| 配置传递 | ✅ | 自主级别配置正确存储 |
| 启动恢复 | ✅ | 从 localStorage 恢复配置 |
| 降级策略 | ✅ | 高风险操作始终需要确认 |
| 数据流闭环 | ✅ | 操作请求 → 风险评估 → 授权检查 → 执行 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 包含在 autonomy-manager.test.ts |
**完成度**: **95%+** ✅ 生产就绪
---
#### 上下文压缩 (Context Compaction)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | compactor.rs, intelligence-client.ts |
| 实现完整性 | ⚠️ | Token 估算、规则摘要已实现；LLM 摘要未实现 |
| 调用链连通 | ✅ | 内核 AgentLoop 集成 (15k token 阈值) |
| 配置传递 | ✅ | 压缩配置正确传递 |
| 启动恢复 | ✅ | 使用默认配置 |
| 降级策略 | ✅ | LLM 不可用时使用规则摘要 |
| 数据流闭环 | ✅ | 检查阈值 → 压缩 → 生成摘要 → 替换消息 |
| dead_code 清理 | ⚠️ | compactor.rs 标记 dead_code (完整版未启用) |
| 测试覆盖 | ✅ | 包含在 compactor.test.ts |
**完成度**: **85%+** ✅ 生产就绪
**差距模式**: "写了没接" - LLM 摘要生成 (use_llm: true) 未实现
---
### 2.3 Skills 生态 (Skills Ecosystem)
#### Skill 系统 (Skill System)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | skill-discovery.ts, SkillRegistry (Rust) |
| 实现完整性 | ⚠️ | 78+ SKILL.md、动态扫描、execute_skill 已实现；WASM/Native 模式未实现 |
| 调用链连通 | ✅ | Kernel → SkillRegistry → skill_list/skill_refresh |
| 配置传递 | ✅ | skills_dir 配置正确传递 |
| 启动恢复 | ✅ | Kernel 启动时扫描 skills 目录 |
| 降级策略 | ✅ | PromptOnly 模式作为默认 |
| 数据流闭环 | ✅ | 扫描 → 注册 → 列表 → 执行 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 50+ 单元测试 |
**完成度**: **80%+** ✅ 生产就绪
**差距模式**: "写了没接" - WASM/Native 执行模式、Schema 验证未实现
---
#### 智能路由 (Intelligent Routing)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ⚠️ | 仅有设计文档，无完整实现 |
| 实现完整性 | ⚠️ | 系统提示词注入技能列表已实现；语义路由器未实现 |
| 调用链连通 | ❌ | 无 Embedding 索引，无 LLM 决策 |
| 配置传递 | ❌ | 无配置传递 |
| 启动恢复 | ❌ | 无启动恢复 |
| 降级策略 | ❌ | 无降级策略 |
| 数据流闭环 | ❌ | 仅完成 40% |
| dead_code 清理 | N/A | 无代码 |
| 测试覆盖 | ❌ | 无测试 |
**完成度**: **40%+** ⚠️ 需完善
**差距模式**: "写了没接" - 设计文档完整，实现仅完成 40%
---
### 2.4 Pipeline DSL
#### Pipeline 系统
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | pipeline-client.ts, zclaw-pipeline crate |
| 实现完整性 | ✅ | YAML 解析、执行引擎、状态管理、9 种 Action |
| 调用链连通 | ✅ | PipelinesPanel → pipeline-client → Tauri 命令 |
| 配置传递 | ✅ | Pipeline 配置正确解析 |
| 启动恢复 | ✅ | Kernel 启动时加载 Pipeline |
| 降级策略 | ✅ | 错误时停止执行 |
| 数据流闭环 | ✅ | 解析 → 执行 → 状态更新 → 结果 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 包含在 pipeline.test.ts |
**完成度**: **90%+** ✅ 生产就绪
---
### 2.5 架构层 (Architecture)
#### 通信层 (Communication Layer)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | kernel-client.ts, gateway-client.ts |
| 实现完整性 | ✅ | 80+ Tauri 命令、双客户端模式 |
| 调用链连通 | ✅ | UI → Store → Client → Tauri 命令 |
| 配置传递 | ✅ | 模型配置正确传递 |
| 启动恢复 | ✅ | 从 localStorage 恢复配置 |
| 降级策略 | ✅ | 离线模式支持 |
| 数据流闭环 | ✅ | 连接 → 配置 → 调用 → 响应 |
| dead_code 清理 | ⚠️ | llm/mod.rs 部分方法标记 dead_code |
| 测试覆盖 | ✅ | 85% 覆盖率 |
**完成度**: **95%+** ✅ 生产就绪
---
#### 状态管理 (State Management)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | 18+ Zustand Store |
| 实现完整性 | ✅ | 持久化中间件、依赖注入、跨 Store 通信 |
| 调用链连通 | ✅ | 组件 → Store → Client |
| 配置传递 | ✅ | Store 配置正确传递 |
| 启动恢复 | ✅ | 从 localStorage 恢复状态 |
| 降级策略 | ✅ | 默认状态兜底 |
| 数据流闭环 | ✅ | 状态更新 → 持久化 → 恢复 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 85% 覆盖率 |
**完成度**: **95%+** ✅ 生产就绪
---
### 2.6 上下文数据库 (Context Database)
#### OpenViking 集成
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | viking-client.ts, viking_commands.rs |
| 实现完整性 | ✅ | 本地/远程/存储三种模式、L0/L1/L2 分层 |
| 调用链连通 | ✅ | VikingPanel → viking-client → Tauri 命令 |
| 配置传递 | ✅ | Embedding 配置正确传递 |
| 启动恢复 | ✅ | App.tsx 恢复 Embedding 配置 |
| 降级策略 | ✅ | 无 OpenViking 时使用本地存储 |
| 数据流闭环 | ✅ | 添加 → 存储 → 搜索 → 读取 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 85% 覆盖率 |
**完成度**: **85%+** ✅ 生产就绪
---
## 三、差距模式汇总
### 3.1 "写了没接" (Code exists but not integrated)
| 功能/模块 | 文件位置 | 差距描述 | 优先级 |
|-----------|----------|----------|--------|
| Predictor Hand | hands/predictor.HAND.toml | 仅有配置文件，无 Rust 实现 | P2 |
| Lead Hand | hands/lead.HAND.toml | 仅有配置文件，无 Rust 实现 | P2 |
| 智能路由 | docs/features/04-skills-ecosystem/01-intelligent-routing.md | 设计文档完整，实现仅 40% | P1 |
| LLM 摘要生成 | compactor.rs | use_llm: true 配置存在但未实现 | P2 |
| 增量压缩 | compactor.rs | 设计了但未启用 | P3 |
| 压缩预览 | compactor.rs | 设计了但未实现 | P3 |
| persona_evolver.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| mesh.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| pattern_detector.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| trigger_evaluator.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| validation.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P3 |
| context_builder.rs | desktop/src-tauri/src/memory/ | 完整实现但标记 dead_code | P2 |
| WASM 执行模式 | zclaw-skills/src/executor.rs | 设计了但未实现 | P3 |
| Native 执行模式 | zclaw-skills/src/executor.rs | 设计了但未实现 | P3 |
| Schema 验证 | zclaw-skills/src/executor.rs | 解析但未验证 | P3 |
### 3.2 "双系统不同步" (Dual systems not synchronized)
| 系统 | 文件位置 | 差距描述 | 优先级 |
|------|----------|----------|--------|
| SqliteStorage vs PersistentMemoryStore | crates/zclaw-growth vs desktop/src-tauri/src/memory | FTS5/TF-IDF: SqliteStorage 有，PersistentMemoryStore 无 | P1 |
| L0/L1 生成 | crates/zclaw-growth | SqliteStorage 有，PersistentMemoryStore 无 | P1 |
| 导出/导入 | desktop/src-tauri/src/memory | SqliteStorage 无，PersistentMemoryStore 有 | P2 |
### 3.3 "存了没用" (Stored but not used)
| 数据/字段 | 文件位置 | 差距描述 | 优先级 |
|-----------|----------|----------|--------|
| overview 字段 | MemoryEntry | 存储了但搜索时未返回 | P2 |
| L0/L1/L2 渐进加载 | context_builder.rs | 实现了但未启用完整版 | P2 |
---
## 四、dead_code 清理建议
### 4.1 建议启用 (Ready to enable)
| 模块 | 文件 | 理由 |
|------|------|------|
| context_builder.rs | memory/context_builder.rs | 完整的 L0→L1→L2 渐进加载，可提升记忆检索质量 |
| persona_evolver.rs | intelligence/persona_evolver.rs | 人格演化核心功能，可增强 Agent 自我进化能力 |
| pattern_detector.rs | intelligence/pattern_detector.rs | 模式检测是智能化的基础 |
### 4.2 建议保留 (Keep as reserved)
| 模块 | 文件 | 理由 |
|------|------|------|
| heartbeat.rs 部分方法 | intelligence/heartbeat.rs | 保留用于 UI 状态显示 |
| compactor.rs 完整版 | intelligence/compactor.rs | 保留用于未来高级压缩功能 |
| validation.rs | intelligence/validation.rs | 保留用于未来 API 验证 |
### 4.3 建议删除 (Consider removing)
| 模块 | 文件 | 理由 |
|------|------|------|
| browser/actions.rs | browser/actions.rs | 如果不计划使用，可删除减少维护负担 |
| browser/error.rs | browser/error.rs | 如果不计划使用，可删除减少维护负担 |
| browser/session.rs | browser/session.rs | 如果不计划使用，可删除减少维护负担 |
---
## 五、优先修复建议
### 5.1 P0 - 阻塞性问题 (立即修复)
无阻塞性问题
### 5.2 P1 - 重要问题 (1-2 周内修复)
| 问题 | 影响 | 修复建议 |
|------|------|----------|
| 智能路由未完成 | 技能匹配精度低 | 实现 SemanticSkillRouter，完成 Embedding 索引 + LLM 决策 |
| 双存储系统不一致 | 功能不对等 | 统一为一套存储系统，或在 PersistentMemoryStore 补齐缺失能力 |
| context_builder.rs 未启用 | 记忆检索质量低 | 启用完整版 L0→L1→L2 渐进加载 |
### 5.3 P2 - 中等问题 (1-2 月内修复)
| 问题 | 影响 | 修复建议 |
|------|------|----------|
| Predictor/Lead Hand 未实现 | 功能缺失 | 实现 Rust 后端或从文档中移除 |
| LLM 摘要未实现 | 压缩质量有限 | 实现 LLM 驱动摘要生成 |
| persona_evolver.rs 未启用 | Agent 演化能力受限 | 启用并集成到反思流程 |
| mesh.rs 未启用 | 多 Agent 协作受限 | 评估是否需要，如需要则启用 |
### 5.4 P3 - 低优先级 (后续迭代)
| 问题 | 影响 | 修复建议 |
|------|------|----------|
| WASM/Native 执行模式 | 扩展性 | 按需实现 |
| Schema 验证 | 数据质量 | 完善验证逻辑 |
| 增量压缩/压缩预览 | 用户体验 | 按需实现 |
---
## 六、测试覆盖分析
### 6.1 测试覆盖良好的模块
| 模块 | 测试数量 | 覆盖率 |
|------|---------|--------|
| chatStore | 42 tests | ~85% |
| gatewayStore | 35 tests | ~85% |
| agent-memory | 42 tests | ~95% |
| reflection-engine | 包含在 intelligence | ~80% |
| pipeline | 包含在 pipeline.test | ~90% |
### 6.2 测试覆盖不足的模块
| 模块 | 当前状态 | 建议 |
|------|---------|------|
| embedding_adapter.rs | 无测试 | 添加单元测试 |
| memory_commands.rs | 无测试 | 添加集成测试 |
| persistent.rs | 仅 1 个测试 | 扩展测试覆盖 |
| 端到端 embedding + 搜索 | 无测试 | 添加 E2E 测试 |
| 端到端 L0/L1 生成 | 无测试 | 添加 E2E 测试 |
| 智能路由 | 无测试 | 添加测试 |
---
## 七、审计结论
### 7.1 总体评估
ZCLAW 项目整体功能完成度较高 (**85%+**)，核心功能已完全实现并集成。主要差距集中在：
1. **智能路由系统** - 设计完整但实现仅 40%
2. **双存储系统不一致** - SqliteStorage 和 PersistentMemoryStore 功能不对等
3. **部分 Hands 未实现** - Predictor 和 Lead 仅有配置文件
4. **大量 dead_code 模块** - 需要评估是否启用或删除
### 7.2 建议优先级
1. **立即**: 完成智能路由系统实现
2. **短期**: 统一双存储系统或补齐功能
3. **中期**: 实现 Predictor/Lead Hand 或移除文档
4. **持续**: 清理 dead_code，评估是否启用或删除
### 7.3 风险提示
- **技术债务**: 39 处 dead_code 标记需要定期评估
- **测试覆盖**: 部分 E2E 测试缺失，建议补充
- **文档一致性**: 部分功能文档与实现不同步，需要更新
---
## 附录：审计命令速查
```bash
# 搜索 dead_code 标记
rg "allow\(dead_code\)" --type rust
# 搜索未使用的函数
rg "#\[allow(dead_code)\]" crates/ desktop/src-tauri/src/
# 搜索未注册的 Tauri 命令
rg "#\[tauri::command\]" desktop/src-tauri/src/ -l
# 对比 lib.rs 中的 .invoke_handler() 注册列表
# 搜索前端 invoke 调用
rg "invoke\(" desktop/src/ --type ts -l
# 编译检查
cargo check 2>&1 | grep -i "warning\|error"
# 测试
cargo test -p zclaw-growth 2>&1 | tail -5
```
---
**审计人**: Claude AI Agent
**审计日期**: 2026-03-27
**下次审计建议**: 3 个月后或重大版本发布前

2
docs/features/FRONTEND_INTEGRATION_AUDIT.md
View File

@@ -170,7 +170,7 @@
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| OpenFang 集成 | L4 已完成 | ✅ 已集成 | `tauri-gateway.ts` |
| ZCLAW 集成 | L4 已完成 | ✅ 已集成 | `tauri-gateway.ts` |
| 安全存储 | L4 已完成 | ✅ 已集成 | `secure-storage.ts` |
| 本地 Gateway | L4 已完成 | ✅ 已集成 | 自动启动逻辑 |

21
docs/features/README.md
View File

@@ -285,10 +285,10 @@ skills hands protocols pipeline growth channels
| 日期 | 版本 | 变更内容 |
|------|------|---------|
| 2026-03-27 | v0.6.0a | **全面审计更新**：所有成熟度标注调整为实际完成度 (平均 68%)，新增清理记录 |
| 2026-03-26 | v0.1.0 | **v1.0 发布准备**：移除 Team/Swarm 功能（~8,100 行，Pipeline 替代），安全修复，CI/CD 建立 |
| 2026-03-26 | v0.5.0 | **Smart Presentation Layer**：自动类型检测，Chart/Quiz/Slideshow/Document 渲染器，PresentationAnalyzer Rust 后端 |
| 2026-03-25 | v0.4.0 | **代码现状深度分析**：8 个 Rust Crates 完整度评估，78+ 技能确认，18+ Store 状态管理，新增 Mesh/Persona 智能组件 |
| 2026-03-27 | v0.6.0a | **全面审计更新**：所有成熟度标注调整为实际完成度 (平均 68%)，新增清理记录 |
| 2026-03-25 | v0.3.0 | **Pipeline DSL 系统实现**，5 类 Pipeline 模板，Agent 智能推荐，结果预览组件 |
| 2026-03-24 | v0.2.5 | **execute_skill 工具实现**，智能层完全实现验证，技能数更新为 78+ |
| 2026-03-24 | v0.2.4 | Hands Review: 修复 BrowserHand Kernel 注册问题，所有 9 个已实现 Hands 均可访问 |
@@ -298,3 +298,22 @@ skills hands protocols pipeline growth channels
| 2026-03-24 | v0.2.0 | 更新为内部 Kernel 架构，Streaming + MCP 协议，修正 Skills/Hands 数量 |
| 2026-03-17 | v1.1 | 智能层集成状态更新 |
| 2026-03-16 | v1.0 | 初始版本，完成全部功能文档 |
---
## 七、清理记录 (2026-03-27)
本次审计中完成的清理工作：
| 清理项 | 说明 |
|--------|------|
| 移除 8 个 OpenClaw 兼容别名 | `gateway_*` 系列废弃函数 |
| 清理 7 个 dead_code 方法 | `generation.rs` 中未使用的代码 |
| 替换 println! 为 tracing | `pipeline_commands.rs` 日志规范化 |
| 新增 LLM 摘要支持 | Compactor 现支持 LLM 驱动的上下文压缩 |
| 禁用 Predictor/Lead | HAND.toml 保留但标记无 Rust 后端 |
| 标记 Wasm/Native SkillMode | 明确标注为尚未实现 |
| 清理 browser/mod.rs | 移除未使用的 re-exports |
| 清理 5 个死代码模块 | pattern_detector, recommender, mesh, persona_evolver, trigger_evaluator |
> **审计说明**: 成熟度等级已根据代码审计调整为实际值。Identity Evolution 标注为 L2 (70%) 是因为其 `dead_code` 属性属于 Tauri 运行时模式（在 Tauri 上下文中实际被调用），而非真正的死代码。Reflection Engine L2 (65%) 因核心反思逻辑尚未深度迭代。

8
docs/handoff-agent-onboarding-2026-03-16.md
View File

@@ -7,7 +7,7 @@
## 一、功能概述
为 ZCLAW 添加类似 OpenClaw 的 Agent 创建引导向导，包括人格风格设置、Emoji 选择、使用场景标签选择等。
为 ZCLAW 添加类似 ZCLAW 的 Agent 创建引导向导，包括人格风格设置、Emoji 选择、使用场景标签选择等。
**计划文档**: `plans/vast-stirring-wilkinson.md`
@@ -107,8 +107,8 @@ desktop/src/
## 五、参考资源
- OpenClaw 快速配置: `docs/archive/openclaw-legacy/autoclaw界面/html版/4.html`
- OpenClaw Agent 面板: `docs/archive/openclaw-legacy/autoclaw界面/html版/3.html`
- ZCLAW 快速配置: `docs/archive/zclaw-legacy/autoclaw界面/html版/4.html`
- ZCLAW Agent 面板: `docs/archive/zclaw-legacy/autoclaw界面/html版/3.html`
- 现有 Modal 模式: `desktop/src/components/CreateTriggerModal.tsx`
---
@@ -116,7 +116,7 @@ desktop/src/
## 六、新会话提示词
```
我正在实现 ZCLAW 的 Agent 人格设置引导功能，参考 OpenClaw 的设计。
我正在实现 ZCLAW 的 Agent 人格设置引导功能，参考 ZCLAW 的设计。
**当前进度**:
- Phase 1 (数据层) ✅ 已完成

223
docs/handoff-audit-fix-2026-03-26.md Normal file
View File

@@ -0,0 +1,223 @@
# 功能审计修复 — 会话交接文档
> **创建时间**: 2026-03-26
> **审计报告**: `plans/piped-wondering-thompson.md`
> **旧审计对比**: `docs/analysis/FEATURE-INTEGRITY-AUDIT.md`（含 6 处事实错误，勿参考）
---
## 背景
对 ZCLAW 全系统 12 个子系统执行了五步审计（文档对齐→追踪数据流→识别dead_code→检查trait实现→端到端验证），发现 19 处差距、22 处 dead_code、8 项文档不一致。核心问题模式：**"写了没接"** — 大量代码已实现但从未接入实际运行流程。
---
## 修复任务清单（严格按优先级执行）
### P0 — 影响核心功能可用性
#### P0-1: Context Compaction 内核集成
**问题**: 上下文压缩仅在前端 `chatStore.ts` 执行，`kernel.rs` 的 `send_message_stream()` 不感知压缩，LLM 实际收到完整历史，前端压缩只是视觉隐藏。
**差距模式**: 双系统不同步
**修复路径**:
- `crates/zclaw-kernel/src/kernel.rs` — 在 `send_message_stream()` 中添加 token 估算 + 阈值检查 + 压缩逻辑
- 参考前端实现: `desktop/src/store/chatStore.ts:333-359`（`checkThreshold` + `compact`）
- 参考后端压缩器: `desktop/src-tauri/src/intelligence/compactor.rs`（462 行，已有完整实现）
- 修复后删除前端 `chatStore.ts` 中的重复压缩调用，改为依赖内核
**验证**: 发送 20+ 条消息后，检查发给 LLM 的实际 context 长度是否被压缩
---
#### P0-2: 文档虚假声称清理
**问题**: README、CLAUDE.md 中多处状态描述与代码不符
**修复清单**:
| 文件 | 行/位置 | 当前声称 | 应改为 |
|------|---------|---------|-------|
| `CLAUDE.md` | 项目结构 crates 列表 | `zclaw-channels (Telegram, Discord, Slack)` | `zclaw-channels (仅 ConsoleChannel 测试适配器)` |
| `CLAUDE.md` | Hands 表格 Lead 行 | `✅ 可用` | `❌ 仅有配置文件，无 Rust 实现` |
| `CLAUDE.md` | Hands 表格 Predictor 行 | `✅ 可用` | `❌ 仅有配置文件，无 Rust 实现` |
| `docs/features/README.md` | Hands 统计 | `9 implemented = 82%` | `7 fully working, 2 config-only (Lead/Predictor)` |
| `docs/features/README.md` | Lead/Predictor 注册状态 | 标记为已注册 | 标记为未实现 |
| `docs/features/06-context-compaction.md` | 成熟度标签 | L4 Production | L2 (前端仅视觉压缩，内核未集成) |
| `docs/features/README.md` | 删除引用 6 个不存在的文档链接 | 01-vector-memory.md 等 | 删除这些引用 |
**验证**: `rg "Lead|Predictor|Telegram|Discord|Slack" CLAUDE.md` 确认已修正
---
#### P0-3: Quiz Hand 占位符生成器替换
**问题**: `DefaultQuizGenerator` 生成 "Question N about X" / "Option A/B/C/D"，正确答案永远是 Option A
**修复路径**:
- `crates/zclaw-hands/src/hands/quiz.rs:35-68` — 替换 `DefaultQuizGenerator::generate()` 实现
- 利用已有的 `QuizGenerator` trait（同文件），实现 LLM 驱动的生成器
- 参考同类模式: `crates/zclaw-runtime/src/tools/web_fetch.rs` 中的 LLM 调用方式
- 生成器需要接收 LLM driver 引用（通过 `QuizHand::new()` 或 `with_generator()` 传入）
**验证**: 触发 Quiz Hand，检查生成的题目是否有真实内容和随机正确答案
---
### P1 — 减少技术债务
#### P1-1: Intelligence 死代码清理
**问题**: 4 个模块有完整代码但从未被前端调用
**清理清单**:
| 文件 | 大小 | Tauri 命令数 | 前端调用 | 建议 |
|------|------|------------|---------|------|
| `desktop/src-tauri/src/intelligence/mesh.rs` | ~300+ 行 | 8 个 | 0 | 删除或移到 `#[cfg(feature = "experimental")]` |
| `desktop/src-tauri/src/intelligence/persona_evolver.rs` | ~300+ 行 | 7 个 | 0 | 同上 |
| `desktop/src-tauri/src/intelligence/pattern_detector.rs` | ~200+ 行 | 0 | 0 | 删除 |
| `desktop/src-tauri/src/intelligence/trigger_evaluator.rs` | ~500+ 行 | 0 | 0 | 删除 |
**注意**: `recommender.rs` **不是**死代码（被 `mesh.rs` 使用），但若 mesh.rs 被移除则 recommender 也变为死代码。
**修复步骤**:
1. 删除上述 4 个文件
2. 从 `desktop/src-tauri/src/intelligence/mod.rs` 移除对应 `pub mod` 声明
3. 从 `desktop/src-tauri/src/lib.rs` invoke_handler 移除对应 15 个命令注册（mesh 8 个 + persona_evolver 7 个）
4. 运行 `cargo check` 确认编译通过
**验证**: `cargo check` + `rg "mesh_|persona_evolver_|pattern_detector|trigger_evaluator" desktop/src-tauri/src/`
---
#### P1-2: Heartbeat Engine 整理
**问题**: Heartbeat 实际完成度 ~75%（App.tsx 启动时调用 init/start，有 tokio 定时循环），但 `trigger_evaluator` 子模块为死代码
**修复路径**:
- 若 P1-1 已删除 trigger_evaluator，则 Heartbeat 中对它的引用也需要处理
- 检查 `heartbeat.rs` 中是否有对 `trigger_evaluator` 的 import，若有则移除
- 移除 `heartbeat.rs` 的 `#![allow(dead_code)]`（既然模块是活的，不需要此标记）
- 确认 `heartbeat_tick` 中 trigger 评估逻辑降级为简单实现
**验证**: `cargo check` + 启动应用确认 heartbeat 仍正常运行
---
#### P1-3: Identity 持久化
**问题**: `AgentIdentityManager` 使用 InMemory 存储，重启后身份数据丢失
**修复路径**:
- `desktop/src-tauri/src/intelligence/identity.rs` — 将 InMemory 存储替换为 SQLite
- 参考已有的持久化模式: `crates/zclaw-growth/src/storage/sqlite.rs`
- SOUL.md 内容、人格预设、变更提案历史需要持久化到 SQLite 表
- 启动时从 SQLite 恢复状态
**验证**: 设置人格后重启应用，检查人格是否保留
---
#### P1-4: Channels 文档修正
**问题**: CLAUDE.md 声称 zclaw-channels 支持 Telegram/Discord/Slack，实际只有 ConsoleChannel
**修复路径**:
- 已在 P0-2 中覆盖（同一处 CLAUDE.md 修改）
---
### P2 — 改善开发体验
#### P2-1: KernelConfig::load() 实现
**问题**: `crates/zclaw-kernel/src/config.rs:256-259` 的 `load()` 始终返回 `Self::default()`
**修复路径**:
- 实现 TOML 文件读取（项目已依赖 `toml` crate）
- 默认路径: `~/.zclaw/config.toml` 或项目根 `config/config.toml`
- 支持 `${VAR_NAME}` 环境变量插值（参考 `desktop/src/lib/toml-utils.ts`）
- 保留 `from_provider()` 作为运行时覆盖
**验证**: 修改 config.toml 中的某个值，重启后端确认生效
---
#### P2-2: PPTX/PDF 导出修复或明确禁用
**问题**: Pipeline 的 ActionRegistry 对 PPTX/PDF 返回 "feature in development" 错误
**修复路径**（二选一）:
- **方案 A**: 修复导出 — `crates/zclaw-kernel/src/export/pptx.rs` 已有实现，检查为什么 Pipeline 层面报错
- **方案 B**: 明确禁用 — 从 Pipeline 前端 UI 中隐藏 PPTX/PDF 选项，避免用户触发报错
**验证**: 在 Pipeline 编辑器中尝试 PPTX 导出
---
#### P2-3: Embedding 搜索统一
**问题**: 向量嵌入仅连接到 Viking 侧车存储，内核原生 MemoryStore 不使用
**修复路径**:
- `desktop/src-tauri/src/embedding_adapter.rs` 已实现 EmbeddingClient trait
- 将相同 adapter 注入到 `zclaw-growth` 的 `SemanticScorer`（已有 `with_embedding()` 方法）
- 在 `intelligence_hooks.rs` 的 `build_memory_context()` 中启用嵌入搜索
**验证**: 配置 embedding provider 后，搜索记忆时确认使用了向量搜索
---
## 不在本次修复范围的事项
| 项目 | 原因 |
|------|------|
| 新增 Telegram/Discord/Slack 适配器 | 需求未确认，工作量大于修复 |
| Pipeline 智能路由（01-intelligent-routing.md） | 纯新功能，非修复 |
| WASM/Native 技能执行模式 | 纯新功能 |
| Agent 导入/导出、模板库 | 纯新功能 |
| 生物识别支持 | 纯新功能 |
| 旧报告提到的 6 个 404 API 端点 | ZCLAW 是 Tauri 桌面应用，不走 HTTP API，这些端点不适用 |
---
## 验证命令速查
```bash
# 编译检查（每次修改后必跑）
cargo check 2>&1 | grep -i "warning\|error"
# TypeScript 类型检查
cd desktop && pnpm tsc --noEmit
# 单元测试
cargo test -p zclaw-growth 2>&1 | tail -5
cd desktop && pnpm vitest run
# 验证文档修正
rg "Lead.*可用|Predictor.*可用|Telegram|Discord|Slack" CLAUDE.md
# 验证死代码清理
rg "mesh_|persona_evolver_|pattern_detector|trigger_evaluator" desktop/src-tauri/src/
# 验证 heartbeat 清理
rg "allow\(dead_code\)" desktop/src-tauri/src/intelligence/heartbeat.rs
```
---
## 关键文件索引
| 文件 | 用途 |
|------|------|
| `plans/piped-wondering-thompson.md` | 完整审计报告（本文档的详细版本） |
| `crates/zclaw-kernel/src/kernel.rs` | 内核，P0-1 修改目标 |
| `crates/zclaw-hands/src/hands/quiz.rs` | Quiz Hand，P0-3 修改目标 |
| `desktop/src-tauri/src/intelligence/` | 智能层，P1-1/P1-2 修改目标 |
| `desktop/src-tauri/src/intelligence/identity.rs` | 身份管理，P1-3 修改目标 |
| `desktop/src-tauri/src/lib.rs:1376-1566` | Tauri 命令注册表 |
| `desktop/src-tauri/src/intelligence_hooks.rs` | 智能 hooks 集成点 |
| `crates/zclaw-kernel/src/config.rs:256-259` | 配置加载，P2-1 修改目标 |
| `CLAUDE.md` | 项目文档，P0-2 修改目标 |
| `docs/features/README.md` | 功能索引，P0-2 修改目标 |

27
docs/knowledge-base/README.md
View File

@@ -6,18 +6,19 @@
```
knowledge-base/
├── README.md # 本文件 - 索引
├── zclaw-technical-reference.md # ZCLAW 技术参考
├── websocket-protocol.md # WebSocket 协议文档
├── configuration.md # 配置系统文档
├── troubleshooting.md # 常见问题排查
├── frontend-integration.md # 前端集成模式
├── agent-provider-config.md # Agent 和 LLM 提供商配置
├── tauri-desktop.md # Tauri 桌面端开发笔记
├── feature-checklist.md # 功能清单和验证状态
├── hands-integration-lessons.md # Hands 集成经验总结
├── openmaic-analysis.md # OpenMAIC 项目深度分析
└── openmaic-zclaw-comparison.md # OpenMAIC vs ZCLAW 对比分析
├── README.md # 本文件 - 索引
├── zclaw-technical-reference.md # ZCLAW 技术参考
├── websocket-protocol.md # WebSocket 协议文档
├── configuration.md # 配置系统文档
├── troubleshooting.md # 常见问题排查
├── frontend-integration.md # 前端集成模式
├── agent-provider-config.md # Agent 和 LLM 提供商配置
├── tauri-desktop.md # Tauri 桌面端开发笔记
├── feature-checklist.md # 功能清单和验证状态
├── hands-integration-lessons.md # Hands 集成经验总结
├── semantic-memory-audit.md # 语义记忆审计记录与审计方法论
├── openmaic-analysis.md # OpenMAIC 项目深度分析
└── openmaic-zclaw-comparison.md # OpenMAIC vs ZCLAW 对比分析
```
## 快速索引
@@ -47,6 +48,7 @@ knowledge-base/
| Tauri 开发 | [tauri-desktop.md](./tauri-desktop.md) | 桌面端开发注意事项 |
| 功能清单 | [feature-checklist.md](./feature-checklist.md) | 所有功能的验证状态 |
| Hands 集成 | [hands-integration-lessons.md](./hands-integration-lessons.md) | Hands 功能集成经验 |
| 语义记忆审计 | [semantic-memory-audit.md](./semantic-memory-audit.md) | 审计方法论 + 差距记录 + 可复用清单 |
### 参考项目分析
@@ -59,6 +61,7 @@ knowledge-base/
| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-03-26 | v2.2 | 添加语义记忆审计记录，含可复用的审计方法论和差距模式 |
| 2026-03-26 | v2.1 | 添加 OpenMAIC 深度分析，补充 StreamBuffer、Director、Action 引擎架构 |
| 2026-03-22 | v2.0 | 重构为 ZCLAW 独立产品文档，添加 OpenMAIC 对比分析 |
| 2026-03-14 | v1.1 | 添加 Hands 集成经验总结、功能清单 |

22
docs/knowledge-base/agent-provider-config.md
View File

@@ -1,13 +1,13 @@
# Agent 和 LLM 提供商配置
> 记录 OpenFang Agent 配置和 LLM 提供商设置。
> 记录 ZCLAW Agent 配置和 LLM 提供商设置。
---
## 1. 配置文件位置
```
~/.openfang/
~/.zclaw/
├── config.toml # 主配置文件
├── .env # 环境变量 (API Keys)
├── secrets.env # 敏感信息
@@ -27,7 +27,7 @@ model = "qwen3.5-plus"
api_key_env = "BAILIAN_API_KEY"
[kernel]
data_dir = "C:\\Users\\szend\\.openfang\\data"
data_dir = "C:\\Users\\szend\\.zclaw\\data"
[memory]
decay_rate = 0.05
@@ -40,7 +40,7 @@ decay_rate = 0.05
| `default_model.provider` | 默认 LLM 提供商 | `bailian`, `zhipu`, `gemini` |
| `default_model.model` | 默认模型名称 | `qwen3.5-plus`, `glm-4-flash` |
| `default_model.api_key_env` | API Key 环境变量名 | `BAILIAN_API_KEY` |
| `kernel.data_dir` | 数据目录 | `~/.openfang/data` |
| `kernel.data_dir` | 数据目录 | `~/.zclaw/data` |
| `memory.decay_rate` | 记忆衰减率 | `0.05` |
---
@@ -63,7 +63,7 @@ decay_rate = 0.05
**方式 1: .env 文件**
```bash
# ~/.openfang/.env
# ~/.zclaw/.env
ZHIPU_API_KEY=your_zhipu_key_here
BAILIAN_API_KEY=your_bailian_key_here
GEMINI_API_KEY=your_gemini_key_here
@@ -75,11 +75,11 @@ DEEPSEEK_API_KEY=your_deepseek_key_here
```bash
# Windows PowerShell
$env:ZHIPU_API_KEY = "your_key"
./openfang.exe start
./zclaw.exe start
# Linux/macOS
export ZHIPU_API_KEY=your_key
./openfang start
./zclaw start
```
### 3.3 验证配置
@@ -177,12 +177,12 @@ curl -s http://127.0.0.1:50051/api/agents | jq '.[] | select(.name=="AgentName")
2. 配置对应的 API Key：
```bash
echo "PROVIDER_API_KEY=your_key" >> ~/.openfang/.env
echo "PROVIDER_API_KEY=your_key" >> ~/.zclaw/.env
```
3. 重启 OpenFang：
3. 重启 ZCLAW：
```bash
./openfang.exe restart
./zclaw.exe restart
```
### 5.2 找到可用的 Agent
@@ -250,7 +250,7 @@ onError: (error: string) => {
配置多个提供商作为备用：
```bash
# ~/.openfang/.env
# ~/.zclaw/.env
ZHIPU_API_KEY=your_primary_key
BAILIAN_API_KEY=your_backup_key
GEMINI_API_KEY=your_gemini_key

16
docs/knowledge-base/frontend-integration.md
View File

@@ -1,6 +1,6 @@
# 前端集成模式
> 记录 ZCLAW Desktop 前端与 OpenFang 后端的集成模式和最佳实践。
> 记录 ZCLAW Desktop 前端与 ZCLAW 后端的集成模式和最佳实践。
---
@@ -31,7 +31,7 @@
│ │
└─────────┬─────────┘
│
OpenFang Backend
ZCLAW Backend
(port 50051)
```
@@ -172,16 +172,16 @@ class GatewayClient {
this.streamCallbacks.set(runId, callbacks);
// 连接 WebSocket
const ws = this.connectOpenFangStream(agentId, runId, options?.sessionKey, message);
const ws = this.connectZCLAWStream(agentId, runId, options?.sessionKey, message);
return { runId };
}
private handleOpenFangStreamEvent(runId: string, event: unknown) {
private handleZCLAWStreamEvent(runId: string, event: unknown) {
const callbacks = this.streamCallbacks.get(runId);
if (!callbacks) return;
const e = event as OpenFangEvent;
const e = event as ZCLAWEvent;
switch (e.type) {
case 'text_delta':
@@ -300,11 +300,11 @@ export default defineConfig({
```typescript
// 根据后端类型切换代理目标
const BACKEND_PORTS = {
openclaw: 18789,
openfang: 50051,
zclaw: 18789,
zclaw: 50051,
};
const backendType = localStorage.getItem('zclaw-backend') || 'openfang';
const backendType = localStorage.getItem('zclaw-backend') || 'zclaw';
const targetPort = BACKEND_PORTS[backendType];
```

8
docs/knowledge-base/hands-integration-lessons.md
View File

@@ -1,7 +1,7 @@
# Hands 集成经验总结
**完成日期**: 2026-03-14
**任务**: 将 OpenFang Hands 功能集成到 ZClaw 桌面客户端
**任务**: 将 ZCLAW Hands 功能集成到 ZClaw 桌面客户端
---
@@ -9,7 +9,7 @@
### 1.1 目标
将 OpenFang 的 Hands（自主能力包）功能深度集成到 ZClaw 桌面客户端，提供与 OpenFang Web 界面对等的用户体验。
将 ZCLAW 的 Hands（自主能力包）功能深度集成到 ZClaw 桌面客户端，提供与 ZCLAW Web 界面对等的用户体验。
### 1.2 完成内容
@@ -175,10 +175,10 @@ interface Hand {
## 六、参考资料
- [OpenFang 技术参考](../openfang-technical-reference.md)
- [ZCLAW 技术参考](../zclaw-technical-reference.md)
- [功能清单](./feature-checklist.md)
- [前端集成指南](./frontend-integration.md)
- [OpenFang WebSocket 协议](./openfang-websocket-protocol.md)
- [ZCLAW WebSocket 协议](./zclaw-websocket-protocol.md)
---

4
docs/knowledge-base/openmaic-analysis.md
View File

@@ -23,7 +23,7 @@
| **丰富场景类型** | 幻灯片、测验、HTML 交互式模拟、项目制学习 (PBL) |
| **白板 & 语音** | 智能体实时绘制图表、书写公式、语音讲解 |
| **导出功能** | 支持导出 `.pptx` 幻灯片或交互式 `.html` 网页 |
| **OpenClaw 集成** | 可从飞书、Slack、Telegram 等聊天应用中直接生成课堂 |
| **ZCLAW 集成** | 可从飞书、Slack、Telegram 等聊天应用中直接生成课堂 |
### 1.3 目标用户群体
@@ -70,7 +70,7 @@ OpenMAIC/
├── packages/ # 工作区子包
│ ├── pptxgenjs/ # 定制化 PowerPoint 生成
│ └── mathml2omml/ # MathML → Office Math 转换
└── skills/openmaic/ # OpenClaw Skill 定义
└── skills/openmaic/ # ZCLAW Skill 定义
```
### 2.2 技术栈

236
docs/knowledge-base/semantic-memory-audit.md Normal file
View File

@@ -0,0 +1,236 @@
# 语义记忆 vs OpenViking 差距审计记录
**审计日期**: 2026-03-26
**审计范围**: ZCLAW 语义记忆子系统 vs OpenViking 原始设计
**审计结果**: 发现 2 个核心差距，已全部修复
---
## 一、审计背景与方法
### 1.1 审计动机
ZCLAW 的记忆系统基于 OpenViking 设计构建，但在实际落地过程中可能存在功能缺失或实现降级。本次审计目的是系统性比对 ZCLAW 实现与 OpenViking 设计规格之间的差距。
### 1.2 审计方法（可复用模板）
本次采用的五步审计流程可作为其他功能点的审计模板：
```
Step 1: 文档对齐 — 将 OpenViking 设计文档与 ZCLAW 实际代码逐一比对
Step 2: 追踪数据流 — 从前端 UI 到后端存储，确认每个环节是否连通
Step 3: 识别 dead_code — 搜索 #[allow(dead_code)]、#![allow(dead_code)]、未注册的命令
Step 4: 检查 trait 实现 — 确认 trait 方法是否被实际调用（而非仅定义）
Step 5: 验证端到端 — 从用户操作角度验证功能是否真正可用
```
### 1.3 关键发现
ZCLAW 存在**两套并行存储系统**，这是很多差距的根因：
| 存储系统 | 代码位置 | 使用场景 | 调用入口 |
|----------|----------|----------|----------|
| `SqliteStorage` | `crates/zclaw-growth/src/storage/sqlite.rs` | VikingPanel 记忆管理 | VikingCommands |
| `PersistentMemoryStore` | `desktop/src-tauri/src/memory/persistent.rs` | 聊天流程记忆 | MemoryCommands |
两套系统功能不对等，导致某些功能在一个路径可用但另一个不可用。
---
## 二、发现的差距与修复
### 差距 1: 向量嵌入搜索未启用
**严重程度**: 高
**差距描述**: OpenViking 设计中包含向量嵌入语义搜索，ZCLAW 代码中 `EmbeddingClient` trait、`index_entry_with_embedding()`、`score_similarity_with_embedding()` 已写好但从未被调用。搜索仅依赖 TF-IDF。
**根因分析**:
- `llm::EmbeddingClient` HTTP 客户端存在，Settings 页面有测试按钮
- 但前端保存 Embedding 配置后未调用 `viking_configure_embedding` 将配置传递到后端
- `SqliteStorage.store()` 未在存储时自动生成 embedding
- `SqliteStorage.find()` 未使用混合评分（embedding + TF-IDF）
**修复方案**:
1. 创建 `embedding_adapter.rs` — 将 `llm::EmbeddingClient` 适配为 `zclaw_growth::EmbeddingClient` trait
2. `SqliteStorage` 添加 `configure_embedding()` 方法
3. 修改 `store()` — embedding 可用时自动生成向量
4. 修改 `find()` — 混合评分（70% embedding + 30% TF-IDF），降级到纯 TF-IDF
5. 前端 `ModelsAPI.tsx` 保存后调用 `viking_configure_embedding`
6. `App.tsx` bootstrap 阶段自动恢复配置
**经验教训**:
> **"代码写好不等于功能可用"** — trait 实现、适配器、前端接入、启动恢复，任何一环缺失都会导致功能不可用。审计时不能只看代码是否存在，必须追踪完整调用链。
---
### 差距 2: L0/L1/L2 分层加载未接入
**严重程度**: 高
**差距描述**: OpenViking 设计了三层记忆加载策略以节省 token：
- L0（Quick Scan）: ~100 tokens，3-5 个关键词
- L1（Standard）: ~200 tokens，1-2 句话摘要
- L2（Deep）: 完整内容
ZCLAW 中 `context_builder.rs` 已有完整 L0→L1→L2 加载逻辑，但整个模块标记为 `#![allow(dead_code)]`，从未接入实际聊天流程。
**根因分析**:
- `MemoryEntry` 缺少 `overview` 和 `abstract_summary` 字段
- 没有 LLM 驱动来生成摘要
- `ContextBuilder.build_context()` 未被任何 Tauri 命令调用
- `chatStore.ts` 使用简单的 `memory.search()` + 手动拼接，无分层概念
**修复方案**:
1. `MemoryEntry` 添加 `overview: Option<String>` 和 `abstract_summary: Option<String>`
2. 两套存储系统均做 schema migration（`ALTER TABLE ADD COLUMN`）
3. 新建 `summarizer.rs` — `SummaryLlmDriver` trait + prompt 模板
4. 新建 `summarizer_adapter.rs` — 用 OpenAI 兼容 API 实现摘要生成
5. 添加 `memory_build_context` Tauri 命令 — 优先使用 L1 overview，尊重 token 预算
6. `chatStore.ts` 替换为调用 `buildContext()` 获取分层上下文
7. `VikingPanel.tsx` 支持 L1→L2 展开
8. `extract_and_store_memories` 存储后异步生成 L0/L1
**经验教训**:
> **"#![allow(dead_code) 是最大的技术债信号"** — 完整的功能实现被标记为死代码，说明设计阶段考虑周全但集成阶段被跳过。审计时应优先搜索 `dead_code` 标记。
>
> **"后台异步生成 + 即时存储"模式** — L2 完整内容同步存储（不阻塞），L0/L1 摘要通过 `tokio::spawn` 后台异步生成并回写。这保证了用户体验不受影响。
---
## 三、集成审计中发现的 5 个 GAP
在修复核心差距后，进行了端到端集成审计，发现以下连通性问题：
| GAP | 描述 | 状态 |
|-----|------|------|
| GAP 1 | Settings 保存 Embedding 配置后未通知后端 | 已修复 |
| GAP 2 | Bootstrap 阶段未自动恢复 Embedding 配置 | 已修复 |
| GAP 3 | `extract_and_store_memories` 未触发 L0/L1 生成 | 已修复 |
| GAP 4 | Summary Driver 需要单独配置 | 不需要 — 已改为自动从活跃 LLM 配置 |
| GAP 5 | `context_builder.rs` 仍标记 dead_code | 已清理注释说明现状 |
---
## 四、遗留问题（后续工作）
### 4.1 双存储系统统一
当前 SqliteStorage 和 PersistentMemoryStore 功能不对等：
| 能力 | SqliteStorage | PersistentMemoryStore |
|------|--------------|----------------------|
| FTS5 全文搜索 | 有 | 无（仅 LIKE 查询） |
| TF-IDF 语义评分 | 有 | 无 |
| L0 abstract_summary | 有 | 无 |
| L0/L1 自动生成 | 有 | 无 |
| 导出/导入 | 无 | 有 |
| 记忆统计 | 无 | 有 |
**建议**: 长期应统一为一套存储系统，或在 PersistentMemoryStore 补齐缺失能力。
### 4.2 测试覆盖不足
| 模块 | 测试状态 |
|------|----------|
| `embedding_adapter.rs` | 无测试 |
| `memory_commands.rs` | 无测试 |
| `persistent.rs`（store/search/embedding） | 仅 1 个 ID 生成测试 |
| 端到端 embedding + 搜索流程 | 无集成测试 |
| 端到端 L0/L1 生成流程 | 无集成测试 |
### 4.3 ContextBuilder 完整版未启用
`context_builder.rs` 中的完整 L0→L1→L2 渐进加载逻辑仍是 dead_code。当前聊天流程使用简化的 `memory_build_context`。完整版预留了 retrieval trace、分阶段 token 预算等高级能力，待后续启用。
### 4.4 Intelligence 子系统大面积 dead_code
以下模块均为 `#![allow(dead_code)]`：
- `validation.rs` — 验证函数
- `identity.rs` — 身份管理
- `recommender.rs` — 推荐系统
- `heartbeat.rs` — 心跳引擎
- `pattern_detector.rs` — 模式检测
- `persona_evolver.rs` — 人格演化
- `compactor.rs` — 记忆压缩
- `trigger_evaluator.rs` — 触发评估
- `mesh.rs` — Agent 群体
- `reflection.rs` — 自我反思
---
## 五、审计方法论总结（供后续复用）
### 5.1 通用审计清单
对任何功能点进行审计时，按以下维度检查：
```
[ ] 代码存在性 — trait/struct/function 是否已定义
[ ] 实现完整性 — trait 方法是否有具体实现（非空/panic）
[ ] 调用链连通 — 从 UI 触发到后端执行的完整路径是否打通
[ ] 配置传递 — 前端配置是否能传递到后端生效
[ ] 启动恢复 — 应用重启后配置/状态是否能自动恢复
[ ] 降级策略 — 依赖不可用时是否有合理降级
[ ] 数据流闭环 — 写入的数据能否被正确读取和使用
[ ] dead_code 清理 — 无 dead_code 或有明确原因保留
[ ] 双系统一致性 — 多套实现是否功能对等
[ ] 测试覆盖 — 关键路径是否有测试
```
### 5.2 常见差距模式
本次审计中发现的差距模式可归纳为：
1. **"写了没接"** — 代码已实现但未接入实际流程（ContextBuilder、EmbeddingClient）
2. **"接了没传"** — 后端命令存在但前端未调用（viking_configure_embedding）
3. **"传了没存"** — 配置保存了但未持久化或恢复（Embedding 配置丢失）
4. **"存了没用"** — 数据已存储但读取时未使用（overview 字段未被搜索返回）
5. **"双系统不同步"** — 一套系统有功能另一套没有（SqliteStorage vs PersistentMemoryStore）
### 5.3 审计命令速查
```bash
# 搜索 dead_code 标记
rg "allow\(dead_code\)" --type rust
# 搜索未使用的函数
rg "#\[allow(dead_code)\]" crates/ desktop/src-tauri/src/
# 搜索未注册的 Tauri 命令
rg "#\[tauri::command\]" desktop/src-tauri/src/ -l
# 对比 lib.rs 中的 .invoke_handler() 注册列表
# 搜索 TODO/FIXME
rg "TODO|FIXME" --type rust --type ts
# 搜索前端 invoke 调用
rg "invoke\(" desktop/src/ --type ts -l
# 编译检查
cargo check 2>&1 | grep -i "warning\|error"
# 测试
cargo test -p zclaw-growth 2>&1 | tail -5
```
---
## 六、关键文件索引
| 文件 | 职责 | 审计阶段 |
|------|------|----------|
| `crates/zclaw-growth/src/types.rs` | MemoryEntry 数据模型 | Phase 2.1 |
| `crates/zclaw-growth/src/storage/sqlite.rs` | SqliteStorage 存储 | Phase 1.3, 2.1 |
| `crates/zclaw-growth/src/retrieval/semantic.rs` | TF-IDF + Embedding 评分 | Phase 1 |
| `crates/zclaw-growth/src/summarizer.rs` | L0/L1 摘要生成 trait | Phase 2.2 |
| `crates/zclaw-growth/src/injector.rs` | Prompt 注入器 | Phase 2.3 |
| `desktop/src-tauri/src/embedding_adapter.rs` | Embedding 适配器 | Phase 1.2 |
| `desktop/src-tauri/src/summarizer_adapter.rs` | 摘要 LLM 驱动 | Phase 2.2 |
| `desktop/src-tauri/src/viking_commands.rs` | Viking Tauri 命令 | Phase 1.4, 2.4 |
| `desktop/src-tauri/src/memory_commands.rs` | Memory Tauri 命令 | Phase 2.3 |
| `desktop/src-tauri/src/memory/persistent.rs` | PersistentMemoryStore | Phase 1.6, 2.1 |
| `desktop/src-tauri/src/memory/context_builder.rs` | L0/L1/L2 渐进加载 | Phase 2.3 |
| `desktop/src-tauri/src/memory/extractor.rs` | 会话记忆提取 | Phase 2.2 |
| `desktop/src/lib/intelligence-client.ts` | 前端记忆客户端 | Phase 2.3 |
| `desktop/src/store/chatStore.ts` | 聊天状态管理 | Phase 2.3 |
| `desktop/src/components/VikingPanel.tsx` | 记忆管理面板 | Phase 2.4 |
| `desktop/src/App.tsx` | 应用启动引导 | Phase 1.5, 2.2 |

14
docs/knowledge-base/tauri-desktop.md
View File

@@ -240,8 +240,8 @@ const version = await invoke<string>('get_app_version');
确保 CSP 允许：
- `ws://localhost:*` - 本地 WebSocket
- `ws://127.0.0.1:*` - OpenFang WebSocket
- `http://127.0.0.1:*` - OpenFang REST API
- `ws://127.0.0.1:*` - ZCLAW WebSocket
- `http://127.0.0.1:*` - ZCLAW REST API
---
@@ -249,12 +249,12 @@ const version = await invoke<string>('get_app_version');
### 7.1 Bundled Runtime
ZCLAW Desktop 可以捆绑 OpenFang Runtime：
ZCLAW Desktop 可以捆绑 ZCLAW Runtime：
```
desktop/src-tauri/resources/
└── openfang-runtime/
├── openfang.exe
└── zclaw-runtime/
├── zclaw.exe
├── config/
└── ...
```
@@ -268,10 +268,10 @@ async fn start_local_gateway(app: AppHandle) -> Result<(), String> {
.resource_dir()
.ok_or("Failed to get resource dir")?;
let openfang_path = resource_path.join("openfang-runtime/openfang.exe");
let zclaw_path = resource_path.join("zclaw-runtime/zclaw.exe");
// 启动进程
Command::new(openfang_path)
Command::new(zclaw_path)
.args(["start"])
.spawn()
.map_err(|e| e.to_string())?;

66
docs/knowledge-base/troubleshooting.md
View File

@@ -13,7 +13,7 @@
**排查步骤**:
```bash
# 1. 检查 OpenFang 是否运行
# 1. 检查 ZCLAW 是否运行
curl http://127.0.0.1:50051/api/health
# 2. 检查端口是否正确
@@ -27,8 +27,8 @@ curl http://127.0.0.1:50051/api/agents
| 原因 | 解决方案 |
|------|----------|
| OpenFang 未启动 | `./openfang.exe start` |
| 端口错误 | OpenFang 使用 50051，不是 4200 |
| ZCLAW 未启动 | `./zclaw.exe start` |
| 端口错误 | ZCLAW 使用 50051，不是 4200 |
| Agent ID 无效 | 使用 `/api/agents` 获取真实 UUID |
### 1.2 端口被占用
@@ -80,15 +80,15 @@ curl -s http://127.0.0.1:50051/api/status | jq '.agents[] | {name, model_provide
2. 配置对应的 API Key：
```bash
# 编辑 ~/.openfang/.env
echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env
echo "BAILIAN_API_KEY=your_key" >> ~/.openfang/.env
echo "GEMINI_API_KEY=your_key" >> ~/.openfang/.env
# 编辑 ~/.zclaw/.env
echo "ZHIPU_API_KEY=your_key" >> ~/.zclaw/.env
echo "BAILIAN_API_KEY=your_key" >> ~/.zclaw/.env
echo "GEMINI_API_KEY=your_key" >> ~/.zclaw/.env
```
3. 重启 OpenFang：
3. 重启 ZCLAW：
```bash
./openfang.exe restart
./zclaw.exe restart
```
**快速解决**: 使用已配置的 Agent
@@ -101,12 +101,12 @@ echo "GEMINI_API_KEY=your_key" >> ~/.openfang/.env
**症状**: 修改 `config.toml` 后，`/api/config` 和 `/api/status` 仍然返回旧配置
**根本原因**: OpenFang 将配置持久化在 SQLite 数据库中，`config.toml` 只在启动时读取
**根本原因**: ZCLAW 将配置持久化在 SQLite 数据库中，`config.toml` 只在启动时读取
**验证问题**:
```bash
# 检查 config.toml 内容
cat ~/.openfang/config.toml
cat ~/.zclaw/config.toml
# 输出: provider = "zhipu"
# 检查 API 返回的配置
@@ -115,14 +115,14 @@ curl -s http://127.0.0.1:50051/api/config
```
**解决方案**:
1. **必须完全重启 OpenFang**（热重载 `/api/config/reload` 不会更新持久化配置）
1. **必须完全重启 ZCLAW**（热重载 `/api/config/reload` 不会更新持久化配置）
```bash
# 方法 1: 通过 API 关闭（然后手动重启）
curl -X POST http://127.0.0.1:50051/api/shutdown
# 方法 2: 使用 CLI
./openfang.exe stop
./openfang.exe start
./zclaw.exe stop
./zclaw.exe start
```
2. **验证配置已生效**:
@@ -134,10 +134,10 @@ curl -s http://127.0.0.1:50051/api/status | grep -E "default_provider|default_mo
**配置文件位置**:
| 文件 | 用途 |
|------|------|
| `~/.openfang/config.toml` | 主配置（启动时读取） |
| `~/.openfang/.env` | API Key 环境变量 |
| `~/.openfang/secrets.env` | 敏感信息 |
| `~/.openfang/data/openfang.db` | SQLite 数据库（持久化配置） |
| `~/.zclaw/config.toml` | 主配置（启动时读取） |
| `~/.zclaw/.env` | API Key 环境变量 |
| `~/.zclaw/secrets.env` | 敏感信息 |
| `~/.zclaw/data/zclaw.db` | SQLite 数据库（持久化配置） |
**支持的 Provider**:
| Provider | 环境变量 | 模型示例 |
@@ -171,9 +171,9 @@ if (agents && agents.length > 0) {
}
```
**历史背景**: 这个问题与 OpenClaw 的握手认证问题类似，但根因不同：
- OpenClaw: 需要 `cli/cli/operator` 身份 + Ed25519 配对
- OpenFang: 不需要认证握手，但需要正确的 Agent UUID
**历史背景**: 这个问题与 ZCLAW 的握手认证问题类似，但根因不同：
- ZCLAW: 需要 `cli/cli/operator` 身份 + Ed25519 配对
- ZCLAW: 不需要认证握手，但需要正确的 Agent UUID
**验证修复**:
```bash
@@ -414,7 +414,7 @@ npm install -g wscat
wscat -c ws://127.0.0.1:50051/api/agents/{agentId}/ws
```
### 5.3 检查 OpenFang 状态
### 5.3 检查 ZCLAW 状态
```bash
# 完整状态
@@ -436,7 +436,7 @@ curl -s http://127.0.0.1:50051/api/hands | jq '.[] | {id, name, requirements_met
| `Port 1420 is already in use` | Vite 服务器已运行 | 终止现有进程 |
| `Unexpected server response: 400` | Agent ID 无效 | 使用真实 UUID |
| `Missing API key` | LLM 提供商未配置 | 配置 API Key |
| `Connection refused` | OpenFang 未运行 | 启动服务 |
| `Connection refused` | ZCLAW 未运行 | 启动服务 |
| `CORS error` | 代理未配置 | 检查 vite.config.ts |
---
@@ -667,7 +667,7 @@ return (
1. **LLM 提取默认禁用**: `useLLM: false` 导致只使用规则提取
2. **提取阈值过高**: `minMessagesForExtraction: 4` 短对话不会触发
3. **agentId 不一致**: `MemoryPanel` 用 `'zclaw-main'`，`MemoryGraph` 用 `'default'`
4. **Gateway 端点不存在**: `GatewayLLMAdapter` 调用 `/api/llm/complete`，OpenFang 无此端点
4. **Gateway 端点不存在**: `GatewayLLMAdapter` 调用 `/api/llm/complete`，ZCLAW 无此端点
**修复方案**:
@@ -683,7 +683,7 @@ export const DEFAULT_EXTRACTION_CONFIG: ExtractionConfig = {
const agentId = currentAgent?.id || 'zclaw-main'; // 从 'default' 改为 'zclaw-main'
// 3. 修复 Gateway 适配器端点 (llm-service.ts)
// 使用 OpenFang 的 /api/agents/{id}/message 端点
// 使用 ZCLAW 的 /api/agents/{id}/message 端点
const response = await fetch(`/api/agents/${agentId}/message`, {
method: 'POST',
body: JSON.stringify({ message: fullPrompt, ... }),
@@ -731,11 +731,11 @@ ctx.fillStyle = '#f9fafb'; // gray-50 (浅色)
## 8. 端口配置问题
### 8.1 OpenFang 端口不匹配导致 Network Error
### 8.1 ZCLAW 端口不匹配导致 Network Error
**症状**: 创建 Agent 或其他 API 操作时报错 `Failed to create agent: Network Error`，控制台显示 `POST http://localhost:1420/api/agents net::ERR_CONNECTION_REFUSED`
**根本原因**: `runtime-manifest.json` 声明端口 4200，但实际 OpenFang 运行在 **50051** 端口
**根本原因**: `runtime-manifest.json` 声明端口 4200，但实际 ZCLAW 运行在 **50051** 端口
**正确配置**:
@@ -1463,7 +1463,7 @@ fn default_skills_dir() -> Option<PathBuf> {
**症状**:
- 技能市场显示 "暂无技能" 和 "0 技能"
- 控制台日志显示 `[skill_list] Found 0 skills`
- 技能目录 `G:\ZClaw_openfang\skills` 存在且包含 70+ 个 SKILL.md 文件
- 技能目录 `G:\ZClaw_zclaw\skills` 存在且包含 70+ 个 SKILL.md 文件
**根本原因**: 多层问题叠加
@@ -1537,9 +1537,9 @@ async fn load_skill_from_dir(&self, dir: &PathBuf) -> Result<()> {
**调试日志示例** (修复后):
```
[default_skills_dir] CARGO_MANIFEST_DIR: G:\ZClaw_openfang\crates\zclaw-kernel
[default_skills_dir] Workspace skills: G:\ZClaw_openfang\skills (exists: true)
[kernel_init] Skills directory: G:\ZClaw_openfang\skills (exists: true)
[default_skills_dir] CARGO_MANIFEST_DIR: G:\ZClaw_zclaw\crates\zclaw-kernel
[default_skills_dir] Workspace skills: G:\ZClaw_zclaw\skills (exists: true)
[kernel_init] Skills directory: G:\ZClaw_zclaw\skills (exists: true)
[skill_list] Found 77 skills
```
@@ -1728,9 +1728,9 @@ curl http://localhost:50051/health
## 12. 相关文档
- [OpenFang 配置指南](./openfang-configuration.md) - 配置文件位置、格式和最佳实践
- [ZCLAW 配置指南](./zclaw-configuration.md) - 配置文件位置、格式和最佳实践
- [Agent 和 LLM 提供商配置](./agent-provider-config.md) - Agent 管理和 Provider 配置
- [OpenFang WebSocket 协议](./openfang-websocket-protocol.md) - WebSocket 通信协议
- [ZCLAW WebSocket 协议](./zclaw-websocket-protocol.md) - WebSocket 通信协议
---

8
docs/knowledge-base/websocket-protocol.md
View File

@@ -1,9 +1,9 @@
# OpenFang WebSocket 协议实际实现
# ZCLAW WebSocket 协议实际实现
> **重要**: OpenFang 实际的 WebSocket 协议与官方文档有差异。本文档记录实际测试验证的协议格式。
> **重要**: ZCLAW 实际的 WebSocket 协议与官方文档有差异。本文档记录实际测试验证的协议格式。
**测试日期**: 2026-03-14
**OpenFang 版本**: 0.4.0
**ZCLAW 版本**: 0.4.0
**测试环境**: Windows 11, Node.js v24
---
@@ -219,7 +219,7 @@ export default defineConfig({
**原因**: Agent 使用的 LLM 提供商未配置 API Key
**解决**:
1. 检查 `~/.openfang/.env` 文件
1. 检查 `~/.zclaw/.env` 文件
2. 确保对应提供商的 API Key 已设置
3. 或使用已配置的 Agent (如 General Assistant - zhipu)

2
docs/knowledge-base/zclaw-technical-reference.md
View File

@@ -897,7 +897,7 @@ const result = await invoke('skill_execute', {
| 版本 | 架构 | 说明 |
|------|------|------|
| v1.x | 外部 OpenFang | 需要启动独立后端进程 |
| v1.x | 外部 ZCLAW | 需要启动独立后端进程 |
| v2.0 | 内部 Kernel | Kernel 集成在 Tauri 中，无需外部进程 |
| v2.1 | Skill 工具执行 | 完整的 execute_skill 工具链路 |

88
docs/plans/2026-03-12-zclaw-delivery-execution-plan.md
View File

@@ -7,8 +7,8 @@
当前对“完整可用 ZCLAW”的定义如下：
- 用户能够在本机启动 ZCLAW 桌面应用
- 用户安装 ZCLAW 时，OpenClaw 运行时已经随包提供，而不是要求用户另行安装
- 桌面应用能够引导并管理随 ZCLAW 一起分发的本地 OpenClaw Gateway
- 用户安装 ZCLAW 时，ZCLAW 运行时已经随包提供，而不是要求用户另行安装
- 桌面应用能够引导并管理随 ZCLAW 一起分发的本地 ZCLAW Gateway
- 前端能够稳定连接 Gateway，并完成基础握手与鉴权
- 用户能够创建、编辑、切换 Agent（Clone）
- 用户能够发起真实对话并收到流式回复
@@ -21,11 +21,11 @@
### 2.1 已完成的关键能力
- Gateway 握手参数已修正，能够兼容 OpenClaw 2026.3.11
- Gateway 握手参数已修正，能够兼容 ZCLAW 2026.3.11
- Token 鉴权已接入前端连接流程
- `zclaw-ui` 插件可被 Gateway 正常加载
- Agent 的创建、编辑、保存链路已打通
- `scripts/setup.ts` 已可在已有 `~/.openclaw/openclaw.json` 时非破坏性合并插件与 skills 路径
- `scripts/setup.ts` 已可在已有 `~/.zclaw/zclaw.json` 时非破坏性合并插件与 skills 路径
- 自定义插件 manifest/package id 对齐问题已修复
### 2.2 当前仍阻塞交付的核心问题
@@ -37,9 +37,9 @@
- `desktop/src-tauri/src/lib.rs` 仍是默认模板
- 当前产品更像“前端连接外部 Gateway”，还不是“完整桌面应用”
2. **当前仍默认依赖用户独立安装 OpenClaw**
2. **当前仍默认依赖用户独立安装 ZCLAW**
- 这与最终产品目标不一致
- 最终必须做到：安装 ZCLAW 后即可直接使用 OpenClaw 能力
- 最终必须做到：安装 ZCLAW 后即可直接使用 ZCLAW 能力
- 因此现阶段的 CLI/PATH 依赖只能作为开发期和过渡期方案
3. **真实桌面链路缺少本地运行闭环验证**
@@ -59,8 +59,8 @@
### 3.1 核心原则
- **先打通闭环，再做扩展**：优先修复阻塞真实使用的能力缺口，而不是继续加功能
- **优先最短交付路径**：优先复用 OpenClaw 现有 CLI/service 能力，而不是一开始就做完整 sidecar 架构
- **最终必须内置 OpenClaw**：开发阶段允许复用系统已安装的 OpenClaw，但交付阶段必须改为随 ZCLAW 一起分发和托管
- **优先最短交付路径**：优先复用 ZCLAW 现有 CLI/service 能力，而不是一开始就做完整 sidecar 架构
- **最终必须内置 ZCLAW**：开发阶段允许复用系统已安装的 ZCLAW，但交付阶段必须改为随 ZCLAW 一起分发和托管
- **浏览器模式不回退**：新增 Tauri 能力必须有运行时保护，不影响现有浏览器预览/开发体验
- **阶段可提交**：每个阶段都有独立验收标准，达到后可形成 clean checkpoint
@@ -68,7 +68,7 @@
- **P0**：Tauri 桌面壳接入本地 Gateway 生命周期管理
- **P0**：完成真实桌面端基础闭环验证
- **P0**：确定并落地“ZCLAW 安装即内置 OpenClaw”的分发方案
- **P0**：确定并落地“ZCLAW 安装即内置 ZCLAW”的分发方案
- **P1**：补齐最影响可用性的设置页占位项
- **P1**：形成交付前 smoke checklist 和文档更新
- **P2**：补测试、清理遗留代码、准备打包发布
@@ -81,7 +81,7 @@
### A.1 目标
让 ZCLAW 桌面应用在 Tauri 环境下具备对本地 OpenClaw Gateway 的基础管理能力：
让 ZCLAW 桌面应用在 Tauri 环境下具备对本地 ZCLAW Gateway 的基础管理能力：
- 查询本地 Gateway 状态
- 启动本地 Gateway
@@ -91,13 +91,13 @@
### A.2 实现策略
优先采用**Tauri Rust 命令封装 OpenClaw CLI** 的方式，而不是直接引入完整 sidecar：
优先采用**Tauri Rust 命令封装 ZCLAW CLI** 的方式，而不是直接引入完整 sidecar：
- Rust 侧封装以下命令：
- `openclaw gateway status --json`
- `openclaw gateway start --json`
- `openclaw gateway stop --json`
- `openclaw gateway restart --json`
- `zclaw gateway status --json`
- `zclaw gateway start --json`
- `zclaw gateway stop --json`
- `zclaw gateway restart --json`
- 前端通过 `invoke` 调用 Rust 命令
- 通过运行时判断，仅在 Tauri 环境中启用这组能力
- 浏览器模式继续保留“手工连接外部 Gateway”的现有逻辑
@@ -107,7 +107,7 @@
- 这一阶段是**开发期过渡方案**
- 它的价值是先把桌面端产品闭环跑通
- 但它**不是最终交付形态**
- 最终交付必须把 OpenClaw 运行时随 ZCLAW 一起打包，而不是要求用户本机已有 `openclaw`
- 最终交付必须把 ZCLAW 运行时随 ZCLAW 一起打包，而不是要求用户本机已有 `zclaw`
### A.3 代码范围
@@ -124,12 +124,12 @@
- 用户可点击启动/停止/重启
- 启动成功后，前端可继续连接并拉取基础数据
- 浏览器模式不因该改动而报错或白屏
- 开发环境下，即使仍依赖系统 `openclaw`，也已经明确与最终 bundling 方案解耦
- 开发环境下，即使仍依赖系统 `zclaw`，也已经明确与最终 bundling 方案解耦
### A.5 风险与应对
- **风险**：不同机器上 `openclaw` 不在 PATH
- **应对**：前端明确提示“未安装 OpenClaw CLI”或“命令不可用”
- **风险**：不同机器上 `zclaw` 不在 PATH
- **应对**：前端明确提示“未安装 ZCLAW CLI”或“命令不可用”
- **风险**：`status --json` / `start --json` 输出结构不稳定
- **应对**：Rust 侧优先使用 `serde_json::Value` 宽松解析，再映射到前端稳定结构
- **风险**：服务模式与前台 `gateway run` 并存导致认知混乱
@@ -169,31 +169,31 @@
---
## Phase C：OpenClaw 随包分发与运行时托管
## Phase C：ZCLAW 随包分发与运行时托管
### C.1 目标
把当前“依赖用户本机单独安装 OpenClaw”的开发态方案，推进到真正可交付的产品方案：
把当前“依赖用户本机单独安装 ZCLAW”的开发态方案，推进到真正可交付的产品方案：
- 用户安装 ZCLAW 时，OpenClaw 运行时已经包含在安装包内
- ZCLAW 启动后，能够直接找到并启动内置 OpenClaw
- 用户不需要再单独安装一套 OpenClaw CLI / 环境
- 用户安装 ZCLAW 时，ZCLAW 运行时已经包含在安装包内
- ZCLAW 启动后，能够直接找到并启动内置 ZCLAW
- 用户不需要再单独安装一套 ZCLAW CLI / 环境
### C.2 目标形态
最终交付建议采用以下形态：
- 安装包内包含 OpenClaw 可执行运行时或受控分发产物
- 安装包内包含 ZCLAW 可执行运行时或受控分发产物
- Tauri Rust 侧通过固定相对路径或 sidecar 机制调用该运行时
- ZCLAW 负责：
- 初始化 OpenClaw home / workspace
- 初始化 ZCLAW home / workspace
- 写入或合并默认配置
- 启动 / 停止 / 重启 Gateway
- 读取日志与状态
### C.3 方案比较
#### 方案 1：继续依赖系统安装的 `openclaw`
#### 方案 1：继续依赖系统安装的 `zclaw`
优点：
@@ -209,7 +209,7 @@
- **仅适合开发期，不可作为最终交付方案**
#### 方案 2：把 OpenClaw 作为 sidecar / bundled runtime 随 ZCLAW 分发
#### 方案 2：把 ZCLAW 作为 sidecar / bundled runtime 随 ZCLAW 分发
优点：
@@ -227,15 +227,15 @@
### C.4 实施任务
- 确认 OpenClaw 可分发形态
- 确认 ZCLAW 可分发形态
- npm 包直接落地
- 预构建二进制
- 内置 Node + OpenClaw 组合运行时
- 内置 Node + ZCLAW 组合运行时
- 确认 Tauri 2 下 sidecar / bundled binary 的最佳实现方式
- 为 Windows 优先落地一版 bundling 方案
- 调整 Rust 侧命令执行逻辑
- 优先调用内置运行时
- 开发模式可回退到系统 `openclaw`
- 开发模式可回退到系统 `zclaw`
- 验证安装后首次启动流程
- 不依赖用户额外安装
- 可直接启动 Gateway
@@ -243,10 +243,10 @@
### C.5 验收标准
- 全新机器上，未单独安装 OpenClaw 的情况下，可直接安装并启动 ZCLAW
- ZCLAW 可成功拉起内置 OpenClaw Gateway
- 全新机器上，未单独安装 ZCLAW 的情况下，可直接安装并启动 ZCLAW
- ZCLAW 可成功拉起内置 ZCLAW Gateway
- Agent / 聊天 / 设置等核心功能可正常工作
- 用户文档不再要求“先安装 OpenClaw 再使用 ZCLAW”
- 用户文档不再要求“先安装 ZCLAW 再使用 ZCLAW”
---
@@ -298,7 +298,7 @@
说明：
- 最终交付 smoke test 不应再把系统级 `openclaw --version` 作为前置要求
- 最终交付 smoke test 不应再把系统级 `zclaw --version` 作为前置要求
- 应改为验证 ZCLAW 内置运行时是否可用
#### 桌面启动检查
@@ -329,7 +329,7 @@
#### 安装闭环检查
- 全新环境中无需单独安装 OpenClaw
- 全新环境中无需单独安装 ZCLAW
- 安装 ZCLAW 后首次启动即可使用
- 若内置运行时损坏或缺失，错误提示明确
@@ -383,17 +383,17 @@
- 从桌面打开到完成一次对话全链路可用
## Milestone 3：OpenClaw 随包分发打通
## Milestone 3：ZCLAW 随包分发打通
输出物：
- Windows 优先的一体化 bundling 方案
- ZCLAW 优先调用内置 OpenClaw 运行时
- 安装后无需用户额外安装 OpenClaw 的可运行链路
- ZCLAW 优先调用内置 ZCLAW 运行时
- 安装后无需用户额外安装 ZCLAW 的可运行链路
完成标志：
- 在未安装 OpenClaw 的机器/环境中，安装 ZCLAW 后即可直接使用
- 在未安装 ZCLAW 的机器/环境中，安装 ZCLAW 后即可直接使用
## Milestone 4：设置页与交付收尾
@@ -417,7 +417,7 @@
2. 在前端新增 Tauri Gateway bridge
3. 在 `gatewayStore` 中接入本地 Gateway 状态与动作
4. 在 Settings > General 中增加本地 Gateway 管理卡片
5. 明确 OpenClaw 随包分发方案，避免把系统安装依赖固化为最终设计
5. 明确 ZCLAW 随包分发方案，避免把系统安装依赖固化为最终设计
6. 进行编译/运行级验证
7. 若验证通过，记录到 `PROGRESS.md`
@@ -439,7 +439,7 @@
### Checkpoint C
- 完成 OpenClaw bundling / sidecar 方案设计
- 完成 ZCLAW bundling / sidecar 方案设计
- 明确 Windows 优先的交付路径
### Checkpoint D
@@ -455,12 +455,12 @@
## 8. 结论
当前最短、最正确的交付路径，不是继续扩展更多功能，而是先把 ZCLAW 从“能连 Gateway 的前端”推进成“能在桌面端真正管理并使用内置 OpenClaw 的产品”。
当前最短、最正确的交付路径，不是继续扩展更多功能，而是先把 ZCLAW 从“能连 Gateway 的前端”推进成“能在桌面端真正管理并使用内置 ZCLAW 的产品”。
因此，本轮执行的核心结论是：
- **先做 Tauri 本地 Gateway 生命周期管理**
- **再完成 OpenClaw 随包分发方案**
- **再完成 ZCLAW 随包分发方案**
- **然后做真实桌面端闭环验证**
- **最后收尾设置页与交付文档**

2
docs/plans/2026-03-16-openviking-local-deployment.md
View File

@@ -2,7 +2,7 @@
## Context
**背景**：ZCLAW 项目基于 OpenFang 定制开发，目标是结合 OpenClaw、NanoClaw、ZeroClaw 等系统的优点。当前 Agent 智能层已超前完成（Phase 1-3 完成, Phase 4 部分完成)，但 OpenViking 集成依赖外部 Python 服务，用户安装繁琐。
**背景**：ZCLAW 项目基于 ZCLAW 定制开发，目标是结合 ZCLAW、NanoClaw、ZeroClaw 等系统的优点。当前 Agent 智能层已超前完成（Phase 1-3 完成, Phase 4 部分完成)，但 OpenViking 集成依赖外部 Python 服务，用户安装繁琐。
**问题**：如何深度集成 OpenViking，避免 Python 依赖，实现无感安装体验？

2
docs/plans/cached-greeting-cocke.md
View File

@@ -2,7 +2,7 @@
## 背景
ZCLAW 是基于 OpenFang (Rust Agent OS) 的 AI Agent 桌面客户端。经过 Phase 1-8 的功能开发，系统已达到 93% API 覆盖率和 100% UI 组件完成度。现在需要对前端设计元素进行全面优化，提升用户操作效率与视觉体验。
ZCLAW 是基于 ZCLAW (Rust Agent OS) 的 AI Agent 桌面客户端。经过 Phase 1-8 的功能开发，系统已达到 93% API 覆盖率和 100% UI 组件完成度。现在需要对前端设计元素进行全面优化，提升用户操作效率与视觉体验。
## 当前状态分析

22
docs/plans/fancy-sprouting-teacup.md
View File

@@ -1,19 +1,19 @@
# OpenFang Hands & Workflow 集成开发方案
# ZCLAW Hands & Workflow 集成开发方案
## 上下文
**目标**: 将 OpenFang 的 Hands 和 Workflow 功能深度集成到 ZClaw 桌面客户端，提供与 OpenFang Web 界面对等的用户体验。
**目标**: 将 ZCLAW 的 Hands 和 Workflow 功能深度集成到 ZClaw 桌面客户端，提供与 ZCLAW Web 界面对等的用户体验。
**当前状态**:
- ZClaw 已有基础的 `HandsPanel.tsx` 和 `WorkflowList.tsx` 组件
- 这些组件功能有限，缺少 OpenFang 的核心 UI 特性
- OpenFang v0.4.0 提供了 8 个 Hands 和完整的 Workflow/Scheduler 系统
- 这些组件功能有限，缺少 ZCLAW 的核心 UI 特性
- ZCLAW v0.4.0 提供了 8 个 Hands 和完整的 Workflow/Scheduler 系统
**参考界面**: http://127.0.0.1:50051 (OpenFang Dashboard)
**参考界面**: http://127.0.0.1:50051 (ZCLAW Dashboard)
---
## 一、OpenFang 界面分析总结
## 一、ZCLAW 界面分析总结
### 1.1 Hands 页面设计
@@ -132,7 +132,7 @@
### 3.1 Phase 1: 增强 HandsPanel (优先级: 高)
**目标**: 提供与 OpenFang 对等的 Hands 管理体验
**目标**: 提供与 ZCLAW 对等的 Hands 管理体验
**文件修改**:
- `desktop/src/components/HandsPanel.tsx` (重写)
@@ -468,7 +468,7 @@ getWorkflowDetails: (id: string) => Promise<Workflow>;
### 3.5 Phase 5: 导航重构 (优先级: 中)
**目标**: 重构导航结构，匹配 OpenFang 布局
**目标**: 重构导航结构，匹配 ZCLAW 布局
**文件修改**:
- `desktop/src/components/Sidebar.tsx`
@@ -538,7 +538,7 @@ getWorkflowDetails: (id: string) => Promise<Workflow>;
### 5.1 手动测试
1. **Hands 测试**:
- 启动 ZClaw，连接 OpenFang (端口 50051)
- 启动 ZClaw，连接 ZCLAW (端口 50051)
- 打开 Hands 标签
- 验证 8 个 Hands 正确显示
- 点击 Details 查看详情弹窗
@@ -653,11 +653,11 @@ function RequirementItem({ description, met, details }: Requirement) {
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| OpenFang API 变更 | 高 | 使用实际 API 测试验证，保持与 OpenFang v0.4.0 兼容 |
| ZCLAW API 变更 | 高 | 使用实际 API 测试验证，保持与 ZCLAW v0.4.0 兼容 |
| UI 复杂度 | 中 | 分阶段实现，先核心功能后高级功能 |
| 性能问题 | 低 | 使用虚拟列表处理大量数据 |
---
*计划创建时间: 2026-03-14*
*参考版本: OpenFang v0.4.0*
*参考版本: ZCLAW v0.4.0*

100
docs/plans/immutable-imagining-naur.md
View File

@@ -1,31 +1,31 @@
# ZClaw: 从 OpenClaw 迁移到 OpenFang 可行性方案
# ZClaw: 从 ZCLAW 迁移到 ZCLAW 可行性方案
> **规划日期**: 2026-03-13
> **目标**: 制定从 OpenClaw 到 OpenFang 的渐进式迁移策略，实现平稳过渡
> **目标**: 制定从 ZCLAW 到 ZCLAW 的渐进式迁移策略，实现平稳过渡
---
## 一、背景与动机
### 1.1 当前架构 (OpenClaw)
### 1.1 当前架构 (ZCLAW)
```
┌─────────────────────────────────────────────────────────────────┐
│ ZClaw Desktop (当前) │
├─────────────────────────────────────────────────────────────────┤
│ React 19 UI → Zustand Store → GatewayClient → OpenClaw │
│ React 19 UI → Zustand Store → GatewayClient → ZCLAW │
│ 技术栈: Tauri 2.0 + TypeScript + Node.js Gateway │
│ 内存: >1GB | 启动: 2-5s | 安装: 500MB │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 目标架构 (OpenFang)
### 1.2 目标架构 (ZCLAW)
```
┌─────────────────────────────────────────────────────────────────┐
│ ZClaw Desktop (OpenFang) │
│ ZClaw Desktop (ZCLAW) │
├─────────────────────────────────────────────────────────────────┤
│ React 19 UI → Zustand Store → OpenFangClient → OpenFang │
│ React 19 UI → Zustand Store → ZCLAWClient → ZCLAW │
│ 技术栈: Tauri 2.0 + TypeScript + Rust Gateway │
│ 内存: ~40MB | 启动: 180ms | 安装: 32MB │
└─────────────────────────────────────────────────────────────────┘
@@ -33,7 +33,7 @@
### 1.3 迁移动机
| 维度 | OpenClaw | OpenFang | 提升 |
| 维度 | ZCLAW | ZCLAW | 提升 |
|------|----------|----------|------|
| **启动速度** | 5.98s | 180ms | **33x 更快** |
| **内存占用** | 394MB | 40MB | **90% 更少** |
@@ -48,7 +48,7 @@
### 2.1 协议差异
| 方面 | OpenClaw | OpenFang |
| 方面 | ZCLAW | ZCLAW |
|------|----------|----------|
| **WebSocket URL** | `ws://127.0.0.1:18789` | `ws://127.0.0.1:4200/ws` |
| **协议格式** | 自定义 JSON 帧 | 标准 JSON + gRPC |
@@ -56,15 +56,15 @@
### 2.2 配置差异
| 方面 | OpenClaw | OpenFang |
| 方面 | ZCLAW | ZCLAW |
|------|----------|----------|
| **配置目录** | `~/.openclaw/` | `~/.openfang/` |
| **配置目录** | `~/.zclaw/` | `~/.zclaw/` |
| **配置格式** | YAML/JSON | TOML |
| **插件系统** | TypeScript (`index.ts`) | SKILL.md + WASM |
### 2.3 API 差异
| 功能 | OpenClaw RPC | OpenFang API |
| 功能 | ZCLAW RPC | ZCLAW API |
|------|-------------|--------------|
| 发送消息 | `agent` | `chat` / `/api/chat` |
| 列出 Agent | `zclaw.clones.list` | `GET /api/agents` |
@@ -79,7 +79,7 @@
### 3.1 策略原则
1. **双版本并行**: 保持 OpenClaw 可用，同时开发 OpenFang
1. **双版本并行**: 保持 ZCLAW 可用，同时开发 ZCLAW
2. **适配层抽象**: 通过接口隔离后端差异
3. **功能对等优先**: 先保证核心功能，再添加新特性
4. **灰度发布**: Beta 测试验证后全面切换
@@ -108,18 +108,18 @@ Phase 7 (2周): 测试验证 ─────────────────
**关键任务**:
1. 创建 `GatewayBackend` 接口抽象
2. 创建 `OpenFangClient` 骨架
2. 创建 `ZCLAWClient` 骨架
3. 配置双后端切换机制
4. 设置 OpenFang 开发环境
4. 设置 ZCLAW 开发环境
**交付物**:
- `desktop/src/lib/types/gateway-backend.ts` - 接口定义
- `desktop/src/lib/openfang-client.ts` - 客户端骨架
- `desktop/src/lib/zclaw-client.ts` - 客户端骨架
- `desktop/src/lib/backend-factory.ts` - 后端工厂
### Phase 2: 客户端实现 (Week 3-4)
**目标**: 完整实现 OpenFang 客户端
**目标**: 完整实现 ZCLAW 客户端
**关键文件**: [gateway-client.ts](desktop/src/lib/gateway-client.ts)
@@ -134,20 +134,20 @@ interface GatewayBackend {
// ... 其他方法
}
// 2. OpenClaw 实现 (现有代码重构)
class OpenClawBackend implements GatewayBackend { ... }
// 2. ZCLAW 实现 (现有代码重构)
class ZCLAWBackend implements GatewayBackend { ... }
// 3. OpenFang 实现 (新建)
class OpenFangBackend implements GatewayBackend {
// 3. ZCLAW 实现 (新建)
class ZCLAWBackend implements GatewayBackend {
private ws: WebSocket;
private url = 'ws://127.0.0.1:4200/ws';
async connect(): Promise<void> {
// OpenFang 认证协议
// ZCLAW 认证协议
}
async chat(message: string, opts?: ChatOptions): Promise<{runId: string}> {
// OpenFang chat 格式
// ZCLAW chat 格式
}
}
```
@@ -162,8 +162,8 @@ class OpenFangBackend implements GatewayBackend {
```typescript
interface GatewayStore {
// 新增
backendType: 'openclaw' | 'openfang';
switchBackend(type: 'openclaw' | 'openfang'): void;
backendType: 'zclaw' | 'zclaw';
switchBackend(type: 'zclaw' | 'zclaw'): void;
// 修改 connect 方法
connect: async (url?, token?) => {
@@ -175,7 +175,7 @@ interface GatewayStore {
### Phase 4: 插件迁移 (Week 7-9)
**目标**: 迁移现有插件到 OpenFang 格式
**目标**: 迁移现有插件到 ZCLAW 格式
| 插件 | 当前格式 | 目标格式 | 复杂度 |
|------|----------|----------|--------|
@@ -187,11 +187,11 @@ interface GatewayStore {
```
plugins/
├── zclaw-chinese-models/
│ ├── openclaw.plugin.json → 删除
│ ├── zclaw.plugin.json → 删除
│ └── index.ts → 转换为 providers.toml
│
├── zclaw-feishu/
│ └── index.ts → 迁移到 OpenFang channels
│ └── index.ts → 迁移到 ZCLAW channels
│
└── zclaw-ui/
└── index.ts → 拆分为 REST 端点
@@ -199,30 +199,30 @@ plugins/
### Phase 5: Tauri 后端 (Week 10-11)
**目标**: 更新 Rust 后端支持 OpenFang
**目标**: 更新 Rust 后端支持 ZCLAW
**关键文件**: [lib.rs](desktop/src-tauri/src/lib.rs)
**修改内容**:
```rust
// 新增 OpenFang 命令
// 新增 ZCLAW 命令
#[tauri::command]
async fn openfang_status() -> Result<OpenFangStatus, String> { ... }
async fn zclaw_status() -> Result<ZCLAWStatus, String> { ... }
#[tauri::command]
async fn openfang_start() -> Result<(), String> { ... }
async fn zclaw_start() -> Result<(), String> { ... }
#[tauri::command]
async fn openfang_stop() -> Result<(), String> { ... }
async fn zclaw_stop() -> Result<(), String> { ... }
// 新增配置迁移命令
#[tauri::command]
async fn migrate_to_openfang() -> Result<MigrationResult, String> { ... }
async fn migrate_to_zclaw() -> Result<MigrationResult, String> { ... }
```
### Phase 6: UI 增强 (Week 12-14)
**目标**: 添加 OpenFang 特有的 UI 功能
**目标**: 添加 ZCLAW 特有的 UI 功能
**新增组件**:
1. `HandsPanel.tsx` - Hands 管理界面
@@ -232,7 +232,7 @@ async fn migrate_to_openfang() -> Result<MigrationResult, String> { ... }
**修改组件**:
1. `SettingsLayout.tsx` - 添加后端切换选项
2. `General.tsx` - 添加 OpenFang 配置项
2. `General.tsx` - 添加 ZCLAW 配置项
### Phase 7: 测试验证 (Week 15-16)
@@ -254,7 +254,7 @@ async fn migrate_to_openfang() -> Result<MigrationResult, String> { ... }
|------|------|----------|
| 协议不兼容 | 高 | 创建适配层，保持双后端 |
| 插件迁移复杂 | 高 | 分阶段迁移，保持 TypeScript 桥接 |
| OpenFang 不成熟 | 中 | 持续关注上游，建立社区联系 |
| ZCLAW 不成熟 | 中 | 持续关注上游，建立社区联系 |
| 配置格式差异 | 中 | 构建自动迁移工具 |
### 5.2 运营风险
@@ -272,11 +272,11 @@ async fn migrate_to_openfang() -> Result<MigrationResult, String> { ... }
const USE_OPENFANG = process.env.ZCLAW_USE_OPENFANG === 'true';
// localStorage 切换
const backendType = localStorage.getItem('zclaw-backend') || 'openclaw';
const backendType = localStorage.getItem('zclaw-backend') || 'zclaw';
// 一键回滚
function rollbackToOpenClaw() {
localStorage.setItem('zclaw-backend', 'openclaw');
function rollbackToZCLAW() {
localStorage.setItem('zclaw-backend', 'zclaw');
window.location.reload();
}
```
@@ -296,7 +296,7 @@ function rollbackToOpenClaw() {
- [ ] 使用统计
- [ ] 配置管理
**OpenFang 新特性**:
**ZCLAW 新特性**:
- [ ] Hand 触发 (Clip, Lead, Researcher 等)
- [ ] Workflow 执行
- [ ] 16 层安全验证
@@ -304,7 +304,7 @@ function rollbackToOpenClaw() {
### 6.2 性能基准
| 指标 | OpenClaw 基线 | OpenFang 目标 |
| 指标 | ZCLAW 基线 | ZCLAW 目标 |
|------|---------------|---------------|
| 冷启动 | 5.98s | < 500ms |
| 空闲内存 | 394MB | < 100MB |
@@ -317,13 +317,13 @@ function rollbackToOpenClaw() {
| 文件 | 修改类型 | 说明 |
|------|----------|------|
| [gateway-client.ts](desktop/src/lib/gateway-client.ts) | 重构 | 抽取接口，创建 OpenFang 实现 |
| [gateway-client.ts](desktop/src/lib/gateway-client.ts) | 重构 | 抽取接口，创建 ZCLAW 实现 |
| [gatewayStore.ts](desktop/src/store/gatewayStore.ts) | 修改 | 添加后端切换逻辑 |
| [chatStore.ts](desktop/src/store/chatStore.ts) | 修改 | 适配新事件格式 |
| [lib.rs](desktop/src-tauri/src/lib.rs) | 扩展 | 添加 OpenFang 管理命令 |
| [lib.rs](desktop/src-tauri/src/lib.rs) | 扩展 | 添加 ZCLAW 管理命令 |
| [zclaw-ui/index.ts](plugins/zclaw-ui/index.ts) | 迁移 | 转换为 REST API |
| [zclaw-chinese-models/index.ts](plugins/zclaw-chinese-models/index.ts) | 迁移 | 转换为 TOML 配置 |
| [zclaw-feishu/index.ts](plugins/zclaw-feishu/index.ts) | 迁移 | 使用 OpenFang channel |
| [zclaw-feishu/index.ts](plugins/zclaw-feishu/index.ts) | 迁移 | 使用 ZCLAW channel |
---
@@ -331,11 +331,11 @@ function rollbackToOpenClaw() {
| 阶段 | 周期 | 开始 | 结束 | 关键交付物 |
|------|------|------|------|------------|
| Phase 1 | 2周 | Week 1 | Week 2 | OpenFangClient 骨架 |
| Phase 1 | 2周 | Week 1 | Week 2 | ZCLAWClient 骨架 |
| Phase 2 | 2周 | Week 3 | Week 4 | 完整客户端 + 流式处理 |
| Phase 3 | 2周 | Week 5 | Week 6 | 更新后的 stores |
| Phase 4 | 3周 | Week 7 | Week 9 | 迁移后的插件 |
| Phase 5 | 2周 | Week 10 | Week 11 | Rust OpenFang 支持 |
| Phase 5 | 2周 | Week 10 | Week 11 | Rust ZCLAW 支持 |
| Phase 6 | 3周 | Week 12 | Week 14 | Hands/Workflow UI |
| Phase 7 | 2周 | Week 15 | Week 16 | 测试套件，验证报告 |
@@ -371,14 +371,14 @@ function rollbackToOpenClaw() {
| 追求差异化竞争 | ✅ **建议迁移** |
| 目标是内容创作者/销售 | ✅ **强烈建议迁移** |
| 资源有限 | ⚠️ 渐进评估 |
| 追求快速迭代 | ⚠️ 保持 OpenClaw，关注 OpenFang |
| 追求快速迭代 | ⚠️ 保持 ZCLAW，关注 ZCLAW |
### 9.3 下一步行动
1. **立即**: 确认迁移决策，分配资源
2. **Week 1**: 创建 `GatewayBackend` 接口
3. **Week 2**: 搭建 OpenFang 开发环境
4. **Week 3-4**: 实现 `OpenFangClient`
3. **Week 2**: 搭建 ZCLAW 开发环境
4. **Week 3-4**: 实现 `ZCLAWClient`
---

6
docs/plans/new-session-prompt-roadmap.md
View File

@@ -22,7 +22,7 @@
- `zclaw-ui` 插件已加载
- `zclaw.clones.list`、`zclaw.plugins.status` 可用
- Agent 创建、右侧 Agent 面板编辑、保存回刷已验证通过
- 快速配置应视为创建/更新 OpenClaw Agent
- 快速配置应视为创建/更新 ZCLAW Agent
- 右侧 Agent 面板已经是当前 Agent 配置的真实编辑入口
这意味着“新会话提示词”应该优先挂在 **Agent Profile 真实配置链路** 上，而不是再创建一套独立的本地状态。
@@ -98,7 +98,7 @@
- 会话级 `sessionPromptDraft`
- 首轮消息注入
后续再根据 Gateway / OpenClaw 演进升级为结构化原生协议。
后续再根据 Gateway / ZCLAW 演进升级为结构化原生协议。
---
@@ -361,7 +361,7 @@
## 九、主要风险与处理策略
### 风险 1：当前 selected Agent 还未完全映射到 OpenClaw runtime agent
### 风险 1：当前 selected Agent 还未完全映射到 ZCLAW runtime agent
影响：

6
docs/plans/quiet-twirling-kettle.md
View File

@@ -9,19 +9,19 @@
### 前端服务
- **URL**: http://localhost:1420
- **框架**: React + Vite + Tauri
- **代理**: `/api` -> `http://127.0.0.1:50051` (OpenFang 后端)
- **代理**: `/api` -> `http://127.0.0.1:50051` (ZCLAW 后端)
### 启动步骤 (⚠️ 需要先启动服务)
**步骤 0: 启动服务** (在测试前必须完成)
```bash
# 终端 1: 启动后端服务
cd g:\ZClaw_openfang
cd g:\ZClaw_zclaw
pnpm dev
# 等待后端服务就绪 (看到 "Server started" 或类似消息)
# 终端 2: 启动前端开发服务器 (新开一个终端)
cd g:\ZClaw_openfang\desktop
cd g:\ZClaw_zclaw\desktop
pnpm dev
# 等待 Vite 服务就绪 (看到 "Local: http://localhost:1420")
```

22
docs/plans/sequential-churning-wreath-agent-a730f837627aeb203.md
View File

@@ -1,5 +1,5 @@
# ZClaw 改进方案:从"前端 UI 演示"升级为"真正的 OpenClaw Runtime 控制界面"
# ZClaw 改进方案:从"前端 UI 演示"升级为"真正的 ZCLAW Runtime 控制界面"
**日期**: 2026-03-12
**状态**: 规划中
@@ -14,7 +14,7 @@
#### 1. 分身与 Agent 断层
- **现状**: 分身存储在 `zclaw-data.json` (ZCLAW 自定义格式)
- **问题**: 不映射到 OpenClaw 原生 `agents.list` 配置
- **问题**: 不映射到 ZCLAW 原生 `agents.list` 配置
- **影响**: 聊天时不所有分身共用 `main` Agent
- **表现**: Bootstrap 文件生成了但可能未被 Agent 运行时使用
@@ -25,8 +25,8 @@
#### 2. 设置页是"假状态"
- **现状**: 大部分设置只存 localStorage
- **问题**: 没有调用 OpenClaw 的 `config.get/config.patch/config.apply`
- **影响**: 用户改了设置而 OpenClaw 运行时行为不变
- **问题**: 没有调用 ZCLAW 的 `config.get/config.patch/config.apply`
- **影响**: 用户改了设置而 ZCLAW 运行时行为不变
**关键代码位置**:
- `desktop/src/components/Settings/*.tsx`: 所有设置页面
@@ -43,7 +43,7 @@
## P0: 最小可行改进 - 让分身真正工作
### 目标
让分身系统真正映射到 OpenClaw Agent 实例，实现分身隔离（独立 Agent 会话)。
让分身系统真正映射到 ZCLAW Agent 实例，实现分身隔离（独立 Agent 会话)。
### 关键任务
@@ -74,14 +74,14 @@
2. 切换 `agentId`
### 技术挑战
- **OpenClaw Agent 进程管理**: 隐式依赖 Gateway 的 Agent 启动机制
- **会话隔离**: 需要验证 OpenClaw 是否支持 `agentId` 参数
- **配置同步时机**: 何时同步分身配置到 OpenClaw
- **ZCLAW Agent 进程管理**: 隐式依赖 Gateway 的 Agent 启动机制
- **会话隔离**: 需要验证 ZCLAW 是否支持 `agentId` 参数
- **配置同步时机**: 何时同步分身配置到 ZCLAW
- **错误处理**: Agent 启动失败时的回退策略
### 验收标准
- [ ] 创建分身后能在 OpenClaw 的 `agents.list` 中看到
- [ ] 创建分身后能在 ZCLAW 的 `agents.list` 中看到
- [ ] 切换分身后聊天时传递正确的 `agentId`
- [ ] 不同分身的会话完全隔离
- [ ] Bootstrap 文件被 Agent 正确加载
@@ -92,7 +92,7 @@
## P1: 设置页 Runtime 化
### 目标
让设置页真正修改 OpenClaw Runtime 配置。
让设置页真正修改 ZCLAW Runtime 配置。
### 关键任务
@@ -127,7 +127,7 @@ async applyConfig(): Promise<void>
- 修改: `patchConfig('agents.defaults.workspace')`
### 技术挑战
- **配置路径**: OpenClaw 配置是嵌套结构，需要正确处理路径
- **配置路径**: ZCLAW 配置是嵌套结构，需要正确处理路径
- **配置验证**: 修改前验证配置有效性
- **错误恢复**: 配置修改失败时的回滚
- **UI 反馈**: 配置修改时的加载状态

68
docs/plans/sequential-churning-wreath.md
View File

@@ -4,13 +4,13 @@
### 1.1 核心发现
基于 `docs/openclaw-deep-dive.md` 的目标与实际代码的对比：
基于 `docs/zclaw-deep-dive.md` 的目标与实际代码的对比：
| 模块 | 目标状态 | 实际状态 | 差距程度 |
|------|----------|----------|----------|
| **Gateway 连接** | 设备认证 + Challenge 签名 | ✅ 完整实现 | 无差距 |
| **分身系统** | 映射到 OpenClaw `agents.list` | ⚠️ 独立存储在 `zclaw-data.json` | **严重** |
| **设置页** | OpenClaw Runtime 配置面板 | ⚠️ 大部分是前端本地状态 | **严重** |
| **分身系统** | 映射到 ZCLAW `agents.list` | ⚠️ 独立存储在 `zclaw-data.json` | **严重** |
| **设置页** | ZCLAW Runtime 配置面板 | ⚠️ 大部分是前端本地状态 | **严重** |
| **右侧面板** | 真实 Agent 身份与状态 | ⚠️ 混合真实数据与硬编码值 | **中等** |
### 1.2 关键差距详解
@@ -27,21 +27,21 @@
│ ❌ 无同步
▼
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw agents.list (openclaw.json) │
│ ZCLAW agents.list (zclaw.json) │
│ 只有: [{ id: "main", groupChat: {...} }] │
└─────────────────────────────────────────────────────────────┘
```
**后果**：
- 所有分身实际共用同一个 `main` Agent
- 聊天时不传递 `agentId`，OpenClaw 不知道当前是哪个分身
- 聊天时不传递 `agentId`，ZCLAW 不知道当前是哪个分身
- Bootstrap 文件（IDENTITY.md, SOUL.md 等）生成了但未被运行时使用
#### 差距 2：设置页是"假状态"
| 设置页 | 当前实现 | 应该实现 |
|--------|----------|----------|
| 模型选择 | 存在 `chatStore.currentModel`（前端状态） | 调用 `config.patch` 修改 OpenClaw 配置 |
| 模型选择 | 存在 `chatStore.currentModel`（前端状态） | 调用 `config.patch` 修改 ZCLAW 配置 |
| MCP 服务 | 存 `quickConfig`，部分同步到 Gateway | 管理 `plugins.load.paths` |
| 技能目录 | 存 `quickConfig` | 管理 `skills.load.extraDirs` |
| IM 频道 | 存 `quickConfig`，只显示状态 | 管理 `channels.*` 配置 |
@@ -49,7 +49,7 @@
| 隐私 | 存 `quickConfig` | 管理 telemetry/优化计划 |
**缺失的 RPC 方法**：
- `config.get` - 读取 OpenClaw 配置
- `config.get` - 读取 ZCLAW 配置
- `config.patch` - 修改配置
- `config.apply` - 热更新配置
@@ -68,16 +68,16 @@ const defaultUserName = '用户7141'; // 假用户名
### 2.1 架构层面的偏差
**文档期望**：
> ZClaw 应该是 OpenClaw Runtime 的控制界面
> ZClaw 应该是 ZCLAW Runtime 的控制界面
**实际实现**：
> ZClaw 是一个有自己数据模型的前端应用，与 OpenClaw 是松耦合
> ZClaw 是一个有自己数据模型的前端应用，与 ZCLAW 是松耦合
### 2.2 数据模型的分裂
```
OpenClaw 数据模型:
openclaw.json → agents.list → Agent workspace → Bootstrap files
ZCLAW 数据模型:
zclaw.json → agents.list → Agent workspace → Bootstrap files
ZClaw 数据模型:
zclaw-data.json → clones[] → (独立的) workspace 路径
@@ -85,21 +85,21 @@ ZClaw 数据模型:
两套数据模型没有桥接，导致：
1. 分身不能路由到正确的 Agent
2. 设置不能影响 OpenClaw 行为
2. 设置不能影响 ZCLAW 行为
3. Bootstrap 文件与运行时脱节
---
## 三、头脑风暴：改进方案
### 3.1 方案 A：完全对齐 OpenClaw（推荐）
### 3.1 方案 A：完全对齐 ZCLAW（推荐）
**核心思路**：让 ZClaw 分身直接映射到 OpenClaw Agent
**核心思路**：让 ZClaw 分身直接映射到 ZCLAW Agent
```
改进后架构:
┌─────────────────────────────────────────────────────────────┐
│ ZClaw 分身 = OpenClaw Agent │
│ ZClaw 分身 = ZCLAW Agent │
│ │
│ clone_1 ↔ agents.list[0] (id: "programmer") │
│ clone_2 ↔ agents.list[1] (id: "designer") │
@@ -110,9 +110,9 @@ ZClaw 数据模型:
```
**优点**：
- 符合 `openclaw-deep-dive.md` 的设计哲学
- 符合 `zclaw-deep-dive.md` 的设计哲学
- 分身真正有独立人格、记忆、工具权限
- 设置页可以直接操作 OpenClaw 配置
- 设置页可以直接操作 ZCLAW 配置
**缺点**：
- 改动较大，需要修改多个模块
@@ -129,7 +129,7 @@ ZClaw 数据模型:
│ zclaw-data.json → clones[] │
│ │ │
│ ▼ (单向同步) │
│ openclaw.json → agents.list (从分身生成) │
│ zclaw.json → agents.list (从分身生成) │
└─────────────────────────────────────────────────────────────┘
```
@@ -139,13 +139,13 @@ ZClaw 数据模型:
**缺点**：
- 数据冗余，需要维护同步
- 不符合 OpenClaw 的设计哲学
- 不符合 ZCLAW 的设计哲学
### 3.3 方案 C：混合模式
**核心思路**：
- 简单分身：共用 `main` Agent，通过 Bootstrap 文件区分
- 高级分身：映射到独立 OpenClaw Agent
- 高级分身：映射到独立 ZCLAW Agent
---
@@ -153,12 +153,12 @@ ZClaw 数据模型:
### P0：让分身真正工作（最小可行）
**目标**：创建分身时同步到 OpenClaw `agents.list`，聊天时传递 `agentId`
**目标**：创建分身时同步到 ZCLAW `agents.list`，聊天时传递 `agentId`
**关键修改**：
1. **`plugins/zclaw-ui/index.ts`**
- `createClone` 时调用 OpenClaw API 添加到 `agents.list`
- `createClone` 时调用 ZCLAW API 添加到 `agents.list`
- `deleteClone` 时从 `agents.list` 移除
- 新增 `zclaw.agents.sync` 方法
@@ -172,17 +172,17 @@ ZClaw 数据模型:
- `sendMessage` 时传递 `currentAgent.id` 作为 `agentId`
4. **新增 Gateway RPC**
- `zclaw.config.get` - 读取 OpenClaw 配置
- `zclaw.config.get` - 读取 ZCLAW 配置
- `zclaw.config.patch` - 修改配置
**验收标准**：
- [ ] 创建分身后，`openclaw.json` 的 `agents.list` 包含新 Agent
- [ ] 创建分身后，`zclaw.json` 的 `agents.list` 包含新 Agent
- [ ] 切换分身后，聊天请求携带正确的 `agentId`
- [ ] 每个分身有独立的对话上下文
### P1：设置页 Runtime 化
**目标**：设置修改直接影响 OpenClaw Runtime
**目标**：设置修改直接影响 ZCLAW Runtime
**关键修改**：
@@ -201,7 +201,7 @@ ZClaw 数据模型:
- 配置变更后显示"需要重启"提示（如需要）
**验收标准**：
- [ ] 模型选择后，`openclaw.json` 的 `agents.defaults.model` 更新
- [ ] 模型选择后，`zclaw.json` 的 `agents.defaults.model` 更新
- [ ] 添加技能目录后，`skills.load.extraDirs` 更新
- [ ] Gateway 重启后配置生效
@@ -242,7 +242,7 @@ ZClaw 数据模型:
| `desktop/src/components/CloneManager.tsx` | 显示同步状态 |
| `desktop/src/components/RightPanel.tsx` | 显示真实 Agent 数据 |
| `desktop/src/components/Settings/*.tsx` | 改造为 Runtime 配置面板 |
| `config/openclaw.default.json` | 更新默认 Agent 模板 |
| `config/zclaw.default.json` | 更新默认 Agent 模板 |
---
@@ -251,7 +251,7 @@ ZClaw 数据模型:
| 风险 | 缓解措施 |
|------|----------|
| 数据迁移复杂 | 提供迁移脚本，保留 `zclaw-data.json` 作为备份 |
| OpenClaw 版本兼容 | 检测 OpenClaw 版本，低版本降级到兼容模式 |
| ZCLAW 版本兼容 | 检测 ZCLAW 版本，低版本降级到兼容模式 |
| 破坏现有功能 | 灰度发布，支持回滚 |
| 性能下降 | 懒加载 Agent 配置，缓存 RPC 结果 |
@@ -259,12 +259,12 @@ ZClaw 数据模型:
## 七、确认的方案
**选择：方案 A - 完全对齐 OpenClaw**
**选择：方案 A - 完全对齐 ZCLAW**
理由：
1. 符合 `openclaw-deep-dive.md` 的设计哲学
1. 符合 `zclaw-deep-dive.md` 的设计哲学
2. 分身真正有独立人格、记忆、工具权限
3. 设置页可以直接操作 OpenClaw 配置
3. 设置页可以直接操作 ZCLAW 配置
4. 长期维护成本最低
---
@@ -277,7 +277,7 @@ ZClaw 数据模型:
**修改点**:
1. `createClone` 方法增加：
- 调用 OpenClaw 内部 API 将分身添加到 `agents.list`
- 调用 ZCLAW 内部 API 将分身添加到 `agents.list`
- 设置 `agentId` 字段关联分身与 Agent
2. `deleteClone` 方法增加：
- 从 `agents.list` 移除对应 Agent
@@ -315,7 +315,7 @@ ZClaw 数据模型:
**文件**: `desktop/src/lib/gateway-client.ts` + `plugins/zclaw-ui/index.ts`
**新增方法**:
- `zclaw.config.get` - 读取 OpenClaw 配置
- `zclaw.config.get` - 读取 ZCLAW 配置
- `zclaw.config.patch` - 修改配置（不重启）
- `zclaw.config.apply` - 热更新配置（如需重启）
@@ -335,7 +335,7 @@ ZClaw 数据模型:
### P0 完成标准
- [ ] 创建分身后，`~/.openclaw/openclaw.json` 的 `agents.list` 包含新 Agent
- [ ] 创建分身后，`~/.zclaw/zclaw.json` 的 `agents.list` 包含新 Agent
- [ ] 删除分身后，对应 Agent 从 `agents.list` 移除
- [ ] 切换分身后，聊天请求携带正确的 `agentId`
- [ ] 每个分身有独立的对话上下文（不串聊）

10
docs/plans/snug-napping-valiant.md
View File

@@ -5,7 +5,7 @@
**目的**: 对 ZCLAW 系统进行全面的代码层面现状分析，识别偏离点、潜在风险，制定分阶段演化路线图。
**当前状态**:
- OpenFang v0.4.0 + ZClaw Desktop v0.2.0
- ZCLAW v0.4.0 + ZClaw Desktop v0.2.0
- API 覆盖率: 93% (63/68 端点)
- UI 完成度: 100% (30/30 组件)
- Skills 定义: 68 个已完成
@@ -24,7 +24,7 @@
### 1.1 项目结构
```
ZClaw_openfang/
ZClaw_zclaw/
├── desktop/ # Tauri 桌面应用 (主要代码)
│ ├── src/
│ │ ├── components/ # React UI (46 组件)
@@ -35,7 +35,7 @@ ZClaw_openfang/
│ └── src-tauri/ # Rust 后端
├── skills/ # 68 个 SKILL.md 定义
├── hands/ # 7 个 HAND.toml 配置
├── config/ # OpenFang TOML 配置
├── config/ # ZCLAW TOML 配置
├── tests/ # Vitest 测试
└── docs/ # 文档
```
@@ -43,7 +43,7 @@ ZClaw_openfang/
### 1.2 核心数据流
```
React UI → Zustand Store → GatewayClient → OpenFang Kernel (端口 50051)
React UI → Zustand Store → GatewayClient → ZCLAW Kernel (端口 50051)
↓
WebSocket (ws://127.0.0.1:50051/ws)
REST API (http://127.0.0.1:50051/api/*)
@@ -541,7 +541,7 @@ pnpm audit
### 手动验证
1. 连接 OpenFang (端口 50051)
1. 连接 ZCLAW (端口 50051)
2. 发送消息并验证流式返回
3. 触发 Hand 并验证执行
4. 保存配置并验证持久化

86
docs/plans/splendid-orbiting-tarjan.md
View File

@@ -4,11 +4,11 @@
### 1.1 项目定位
ZCLAW 是一个**基于 OpenClaw 框架的定制化中文 AI 助手平台**，对标 AutoClaw (智谱) 和 QClaw (腾讯)。
ZCLAW 是一个**基于 ZCLAW 框架的定制化中文 AI 助手平台**，对标 AutoClaw (智谱) 和 QClaw (腾讯)。
**核心价值主张**：
```
OpenClaw Gateway (成熟执行引擎)
ZCLAW Gateway (成熟执行引擎)
↕ WebSocket Protocol v3
ZCLAW Tauri App (轻量桌面 UI)
+ 中文模型 Provider (GLM/Qwen/Kimi/MiniMax)
@@ -22,15 +22,15 @@ ZCLAW Tauri App (轻量桌面 UI)
| 阶段 | 架构方向 | 状态 |
|------|----------|------|
| v1 | 自建 AI Agent 框架 (src/core/*) | 🗑️ 已归档 |
| v2 | 基于 OpenClaw + Tauri | ✅ 当前方向 |
| v2 | 基于 ZCLAW + Tauri | ✅ 当前方向 |
**架构转向原因**：v1 偏离初衷约 75%，重复造轮子而非复用 OpenClaw 生态。
**架构转向原因**：v1 偏离初衷约 75%，重复造轮子而非复用 ZCLAW 生态。
### 1.3 技术栈一览
| 层级 | 技术 | 版本 |
|------|------|------|
| 执行引擎 | OpenClaw Gateway | Node.js daemon |
| 执行引擎 | ZCLAW Gateway | Node.js daemon |
| 桌面壳 | Tauri | 2.0 |
| 前端框架 | React | 19.1.0 |
| 状态管理 | Zustand | 5.0.11 |
@@ -51,7 +51,7 @@ ZCLAW Tauri App (轻量桌面 UI)
| Phase 2 | 前端 Settings 页面体系 (10页) | ✅ 100% |
| Phase 3 | 聊天对接 + 分身管理 | ✅ 100% |
| Phase 3.5 | 前端质量提升 | ✅ 100% |
| Phase 4 | OpenClaw 真实集成测试 | ⏳ 待开始 |
| Phase 4 | ZCLAW 真实集成测试 | ⏳ 待开始 |
| Phase 5 | Tauri Rust sidecar + 打包发布 | 📋 规划中 |
### 2.2 代码统计
@@ -74,11 +74,11 @@ ZCLAW Tauri App (轻量桌面 UI)
## 三、核心模块深度分析
### 3.1 OpenClaw Gateway 集成层 (src/gateway/)
### 3.1 ZCLAW Gateway 集成层 (src/gateway/)
#### manager.ts - 子进程管理器
```
功能: 管理 OpenClaw Gateway 子进程生命周期
功能: 管理 ZCLAW Gateway 子进程生命周期
特性:
- 启动/停止 Gateway daemon
- 健康检查 (HTTP 探测)
@@ -88,7 +88,7 @@ ZCLAW Tauri App (轻量桌面 UI)
#### ws-client.ts - WebSocket 客户端
```
功能: 实现 OpenClaw Gateway Protocol v3
功能: 实现 ZCLAW Gateway Protocol v3
特性:
- 三步握手 (challenge → connect → hello-ok)
- 请求/响应模式 (30秒超时)
@@ -110,7 +110,7 @@ ZCLAW Tauri App (轻量桌面 UI)
#### @zclaw/feishu - 飞书 Channel Plugin
```
功能: 将飞书注册为 OpenClaw 消息渠道
功能: 将飞书注册为 ZCLAW 消息渠道
特性:
- OAuth tenant_access_token 管理 (2h 有效期, 1.5h 刷新)
- 文本/富文本消息发送
@@ -154,14 +154,14 @@ ZCLAW Tauri App (轻量桌面 UI)
| 模块 | 状态 | 替代方案 |
|------|------|----------|
| remote-execution/ | 🗑️ | OpenClaw 工具执行 |
| task-orchestration/ | 🗑️ | OpenClaw Agent Loop |
| multi-agent/ | 🗑️ | OpenClaw agents.list |
| memory/ | 🗑️ | OpenClaw Memory Plugin |
| proactive/ | 🗑️ | OpenClaw Heartbeat Engine |
| im/ | 🗑️ | OpenClaw Channel 系统 |
| db/ | 🗑️ | OpenClaw 自带 SQLite |
| config/ | 🗑️ | OpenClaw 配置系统 |
| remote-execution/ | 🗑️ | ZCLAW 工具执行 |
| task-orchestration/ | 🗑️ | ZCLAW Agent Loop |
| multi-agent/ | 🗑️ | ZCLAW agents.list |
| memory/ | 🗑️ | ZCLAW Memory Plugin |
| proactive/ | 🗑️ | ZCLAW Heartbeat Engine |
| im/ | 🗑️ | ZCLAW Channel 系统 |
| db/ | 🗑️ | ZCLAW 自带 SQLite |
| config/ | 🗑️ | ZCLAW 配置系统 |
| api/ | 🗑️ | WebSocket + Tauri Commands |
---
@@ -171,7 +171,7 @@ ZCLAW Tauri App (轻量桌面 UI)
### 4.1 架构优势 💪
1. **复用成熟生态**
- OpenClaw 28万+ Stars，工具执行/Skills/MCP/心跳引擎成熟
- ZCLAW 28万+ Stars，工具执行/Skills/MCP/心跳引擎成熟
- 避免重复造轮子，专注差异化价值
2. **Tauri 轻量化**
@@ -189,7 +189,7 @@ ZCLAW Tauri App (轻量桌面 UI)
### 4.2 潜在风险 ⚠️
1. **OpenClaw 依赖**
1. **ZCLAW 依赖**
- 版本兼容性风险
- 文档/社区支持限制
@@ -261,7 +261,7 @@ ZCLAW Tauri App (轻量桌面 UI)
#### 短期 (1-2周)
1. **完成 Phase 4 集成测试**
- 安装并验证 OpenClaw
- 安装并验证 ZCLAW
- 测试 Gateway 连接
- 验证插件注册
- 端到端消息收发测试
@@ -311,7 +311,7 @@ ZCLAW Tauri App (轻量桌面 UI)
| 维度 | AutoClaw (智谱) | QClaw (腾讯) | ZCLAW |
|------|----------------|--------------|-------|
| 基础框架 | OpenClaw | OpenClaw | OpenClaw |
| 基础框架 | ZCLAW | ZCLAW | ZCLAW |
| IM 渠道 | 飞书 | 微信+QQ | 飞书 (计划微信/QQ) |
| 桌面框架 | 自研 | Electron | Tauri 2.0 |
| 模型支持 | GLM 系列 | 腾讯混元 | GLM/Qwen/Kimi/MiniMax |
@@ -331,16 +331,16 @@ ZCLAW Tauri App (轻量桌面 UI)
### Phase 4: 真实集成测试 (当前优先级)
```
[ ] 1. 安装 OpenClaw
- Windows: iwr -useb https://openclaw.ai/install.ps1 | iex
- 验证: openclaw --version
[ ] 1. 安装 ZCLAW
- Windows: iwr -useb https://zclaw.ai/install.ps1 | iex
- 验证: zclaw --version
[ ] 2. 配置 Gateway
- 运行 openclaw configure
- 运行 zclaw configure
- 填入 API Key (智谱/通义/Kimi 任选)
[ ] 3. 启动 Gateway
- openclaw gateway
- zclaw gateway
- 验证: curl http://127.0.0.1:18789/health
[ ] 4. 注册 ZCLAW 插件
@@ -371,7 +371,7 @@ ZCLAW Tauri App (轻量桌面 UI)
## 七、总结
ZCLAW 是一个定位清晰的 OpenClaw 定制化项目，通过复用成熟生态 + Tauri 轻量桌面 + 中文优先策略，有望成为开源领域的 AutoClaw/QClaw 替代方案。
ZCLAW 是一个定位清晰的 ZCLAW 定制化项目，通过复用成熟生态 + Tauri 轻量桌面 + 中文优先策略，有望成为开源领域的 AutoClaw/QClaw 替代方案。
**核心建议**：
1. 🎯 聚焦 Phase 4 集成测试，打通端到端流程
@@ -389,25 +389,25 @@ ZCLAW 是一个定位清晰的 OpenClaw 定制化项目，通过复用成熟生
### 8.1 Phase 4: 真实集成测试 🔌
**目标**: 打通 OpenClaw Gateway ↔ ZCLAW Tauri 端到端流程
**目标**: 打通 ZCLAW Gateway ↔ ZCLAW Tauri 端到端流程
**任务清单**:
```
[ ] 安装 OpenClaw CLI
- Windows: iwr -useb https://openclaw.ai/install.ps1 | iex
- 验证: openclaw --version
[ ] 安装 ZCLAW CLI
- Windows: iwr -useb https://zclaw.ai/install.ps1 | iex
- 验证: zclaw --version
[ ] 配置 Gateway
- 运行 openclaw configure
- 运行 zclaw configure
- 配置 API Key (智谱 GLM 作为首选)
[ ] 启动 Gateway daemon
- openclaw gateway --port 18789
- zclaw gateway --port 18789
- 验证: curl http://127.0.0.1:18789/health
[ ] 注册 ZCLAW 插件
- pnpm setup (执行 scripts/setup.ts)
- 验证插件加载: openclaw plugins list
- 验证插件加载: zclaw plugins list
[ ] 前端连接测试
- cd desktop && pnpm tauri dev
@@ -432,15 +432,15 @@ ZCLAW 是一个定位清晰的 OpenClaw 定制化项目，通过复用成熟生
**待处理目录**:
| 目录 | 文件数 | 建议操作 |
|------|--------|----------|
| src/core/remote-execution/ | ~4 | 🗑️ 删除 (OpenClaw 替代) |
| src/core/task-orchestration/ | ~3 | 🗑️ 删除 (OpenClaw 替代) |
| src/core/multi-agent/ | ~8 | 🗑️ 删除 (OpenClaw 替代) |
| src/core/memory/ | ~2 | 🗑️ 删除 (OpenClaw 替代) |
| src/core/proactive/ | ~2 | 🗑️ 删除 (OpenClaw 替代) |
| src/core/remote-execution/ | ~4 | 🗑️ 删除 (ZCLAW 替代) |
| src/core/task-orchestration/ | ~3 | 🗑️ 删除 (ZCLAW 替代) |
| src/core/multi-agent/ | ~8 | 🗑️ 删除 (ZCLAW 替代) |
| src/core/memory/ | ~2 | 🗑️ 删除 (ZCLAW 替代) |
| src/core/proactive/ | ~2 | 🗑️ 删除 (ZCLAW 替代) |
| src/core/ai/ | ~6 | ⚠️ 评估 (可能复用 Provider) |
| src/im/ | ~4 | 🗑️ 删除 (OpenClaw 替代) |
| src/db/ | ~3 | 🗑️ 删除 (OpenClaw 替代) |
| src/config/ | ~2 | 🗑️ 删除 (OpenClaw 替代) |
| src/im/ | ~4 | 🗑️ 删除 (ZCLAW 替代) |
| src/db/ | ~3 | 🗑️ 删除 (ZCLAW 替代) |
| src/config/ | ~2 | 🗑️ 删除 (ZCLAW 替代) |
| src/api/ | ~1 | 🗑️ 删除 (WebSocket 替代) |
| src/app.ts | 1 | 🗑️ 删除 |
| src/index.ts | 1 | 🔄 重写为简单入口 |

10
docs/plans/typed-dazzling-fog.md
View File

@@ -21,7 +21,7 @@
使用 3 个并行 Explore 代理深度分析：
- 前端组件和 UI 状态管理
- OpenFang 通信层实现
- ZCLAW 通信层实现
- 配置和技能系统
### 1.3 实施方法
@@ -55,7 +55,7 @@
| 来源 | 端口 | 状态 |
|------|------|------|
| **实际 OpenFang** | 50051 | 代码正确适配 |
| **实际 ZCLAW** | 50051 | 代码正确适配 |
| **文档** | 4200 | 需更新 |
| **FALLBACK_GATEWAY_URLS** | 50051, 4200 | 回退列表包含两个 |
@@ -75,7 +75,7 @@
### Phase 1: 功能对齐 ✅ 完成
**目标**: 连接所有 UI 组件到真实 OpenFang 能力
**目标**: 连接所有 UI 组件到真实 ZCLAW 能力
| 任务 | 状态 | 文件 |
|------|------|------|
@@ -95,7 +95,7 @@
### Phase 3: 扩展和增强 ✅ 完成
**目标**: 完善 OpenFang 特有功能的 UI
**目标**: 完善 ZCLAW 特有功能的 UI
| 任务 | 状态 | 文件 |
|------|------|------|
@@ -227,7 +227,7 @@
```
2. **手动验证**
- 连接 OpenFang (端口 50051)
- 连接 ZCLAW (端口 50051)
- 验证数据流真实连接
- 检查 localStorage 使用情况
- 验证设置持久化

14
docs/setup/chinese-models.md
View File

@@ -1,12 +1,12 @@
# 中文模型配置指南
> 本文档详细介绍 OpenFang Kernel 支持的中文大语言模型，以及如何获取和配置 API Key。
> 本文档详细介绍 ZCLAW Kernel 支持的中文大语言模型，以及如何获取和配置 API Key。
---
## 支持的中文模型
OpenFang 通过 OpenAI 兼容 API 支持所有主流中文模型提供商：
ZCLAW 通过 OpenAI 兼容 API 支持所有主流中文模型提供商：
| 提供商 | 模型系列 | 特点 | 定价 |
|--------|----------|------|------|
@@ -320,10 +320,10 @@ api_key_env = ""
## 多模型配置
OpenFang 支持同时配置多个模型，并自动路由：
ZCLAW 支持同时配置多个模型，并自动路由：
```toml
# ~/.openfang/config.toml
# ~/.zclaw/config.toml
[model]
# 默认模型
@@ -440,13 +440,13 @@ model = "deepseek-coder"
```bash
# 查看今日用量
openfang usage --today
zclaw usage --today
# 查看本月用量
openfang usage --month
zclaw usage --month
# 按模型分组
openfang usage --group-by model
zclaw usage --group-by model
```
### Q: API Key 泄露了怎么办？

50
docs/superpowers/plans/2026-03-21-phase1-security-testing.md
View File

@@ -57,12 +57,12 @@ desktop/
Run (Windows):
```bash
cd g:\ZClaw_openfang\desktop && pnpm add -D vitest@2.1.8 @testing-library/react@16.1.0 @testing-library/jest-dom@6.6.3 jsdom@25.0.1
cd g:\ZClaw_zclaw\desktop && pnpm add -D vitest@2.1.8 @testing-library/react@16.1.0 @testing-library/jest-dom@6.6.3 jsdom@25.0.1
```
Run (Unix):
```bash
cd g:/ZClaw_openfang/desktop && pnpm add -D vitest@2.1.8 @testing-library/react@16.1.0 @testing-library/jest-dom@6.6.3 jsdom@25.0.1
cd g:/ZClaw_zclaw/desktop && pnpm add -D vitest@2.1.8 @testing-library/react@16.1.0 @testing-library/jest-dom@6.6.3 jsdom@25.0.1
```
Expected: 依赖安装成功
@@ -71,7 +71,7 @@ Expected: 依赖安装成功
Run:
```bash
cd g:\ZClaw_openfang\desktop && pnpm exec vitest --version
cd g:\ZClaw_zclaw\desktop && pnpm exec vitest --version
```
Expected: 输出 `vitest/2.1.8`
@@ -214,7 +214,7 @@ Verify `desktop/package.json` scripts section includes:
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test
cd g:/ZClaw_zclaw/desktop && pnpm test
```
Expected: 测试运行成功 (可能显示 0 tests，这是正常的)
@@ -222,7 +222,7 @@ Expected: 测试运行成功 (可能显示 0 tests，这是正常的)
- [ ] **Step 5: 提交测试框架配置**
```bash
cd g:/ZClaw_openfang && git add desktop/vitest.config.ts desktop/tests/setup.ts desktop/package.json
cd g:/ZClaw_zclaw && git add desktop/vitest.config.ts desktop/tests/setup.ts desktop/package.json
git commit -m "test: add Vitest configuration and setup
- Add vitest.config.ts with coverage thresholds
@@ -284,7 +284,7 @@ describe('crypto-utils', () => {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/lib/crypto-utils.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/lib/crypto-utils.test.ts
```
Expected: FAIL - "Cannot find module '../../src/lib/crypto-utils'"
@@ -411,7 +411,7 @@ export function generateMasterKey(): string {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/lib/crypto-utils.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/lib/crypto-utils.test.ts
```
Expected: PASS - 2 tests
@@ -450,7 +450,7 @@ describe('encrypt and decrypt', () => {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/lib/crypto-utils.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/lib/crypto-utils.test.ts
```
Expected: PASS - 3 tests
@@ -458,7 +458,7 @@ Expected: PASS - 3 tests
- [ ] **Step 7: 提交加密工具模块**
```bash
cd g:/ZClaw_openfang && git add desktop/src/lib/crypto-utils.ts desktop/tests/lib/crypto-utils.test.ts
cd g:/ZClaw_zclaw && git add desktop/src/lib/crypto-utils.ts desktop/tests/lib/crypto-utils.test.ts
git commit -m "feat(crypto): add AES-GCM encryption utilities
- Add arrayToBase64/base64ToArray conversion functions
@@ -556,7 +556,7 @@ describe('secureStorage', () => {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/lib/secure-storage.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/lib/secure-storage.test.ts
```
Expected: FAIL - localStorage 存储明文
@@ -697,7 +697,7 @@ export const secureStorage = {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/lib/secure-storage.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/lib/secure-storage.test.ts
```
Expected: PASS - 4 tests
@@ -705,7 +705,7 @@ Expected: PASS - 4 tests
- [ ] **Step 7: 提交凭据加密增强**
```bash
cd g:/ZClaw_openfang && git add desktop/src/lib/secure-storage.ts desktop/tests/lib/secure-storage.test.ts
cd g:/ZClaw_zclaw && git add desktop/src/lib/secure-storage.ts desktop/tests/lib/secure-storage.test.ts
git commit -m "feat(security): add AES-GCM encryption for localStorage fallback
- Encrypt credentials before storing in localStorage
@@ -836,7 +836,7 @@ describe('WebSocket Security', () => {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/lib/gateway-security.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/lib/gateway-security.test.ts
```
Expected: PASS - 6 tests (这些是纯逻辑测试)
@@ -904,7 +904,7 @@ async connect(): Promise<void> {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test
cd g:/ZClaw_zclaw/desktop && pnpm test
```
Expected: All tests pass
@@ -912,7 +912,7 @@ Expected: All tests pass
- [ ] **Step 7: 提交 WSS 强制策略**
```bash
cd g:/ZClaw_openfang && git add desktop/src/lib/gateway-client.ts desktop/tests/lib/gateway-security.test.ts
cd g:/ZClaw_zclaw && git add desktop/src/lib/gateway-client.ts desktop/tests/lib/gateway-security.test.ts
git commit -m "feat(security): enforce WSS for non-localhost connections
- Add validateWebSocketSecurity function
@@ -939,7 +939,7 @@ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
Run:
```bash
head -n 100 g:/ZClaw_openfang/desktop/src/store/chatStore.ts
head -n 100 g:/ZClaw_zclaw/desktop/src/store/chatStore.ts
```
- [ ] **Step 2: 写失败的测试 - 基础功能**
@@ -1098,7 +1098,7 @@ describe('chatStore', () => {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/store/chatStore.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/store/chatStore.test.ts
```
Expected: PASS - 8+ tests
@@ -1147,7 +1147,7 @@ describe('updateMessage', () => {
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/store/chatStore.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/store/chatStore.test.ts
```
Expected: PASS - 10+ tests
@@ -1156,7 +1156,7 @@ Expected: PASS - 10+ tests
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test:coverage tests/store/chatStore.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test:coverage tests/store/chatStore.test.ts
```
Expected: Coverage > 80% for chatStore
@@ -1164,7 +1164,7 @@ Expected: Coverage > 80% for chatStore
- [ ] **Step 7: 提交 ChatStore 测试**
```bash
cd g:/ZClaw_openfang && git add desktop/tests/store/chatStore.test.ts
cd g:/ZClaw_zclaw && git add desktop/tests/store/chatStore.test.ts
git commit -m "test(chat): add comprehensive unit tests for chatStore
- Test initial state
@@ -1189,7 +1189,7 @@ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test
cd g:/ZClaw_zclaw/desktop && pnpm test
```
Expected: All tests pass
@@ -1198,7 +1198,7 @@ Expected: All tests pass
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test:coverage
cd g:/ZClaw_zclaw/desktop && pnpm test:coverage
```
Expected: Overall coverage >= 60%
@@ -1254,7 +1254,7 @@ Create `docs/changelogs/2026-03-21-phase1-security.md`:
- [ ] **Step 2: 提交文档更新**
```bash
cd g:/ZClaw_openfang && git add docs/changelogs/2026-03-21-phase1-security.md
cd g:/ZClaw_zclaw && git add docs/changelogs/2026-03-21-phase1-security.md
git commit -m "docs: add Phase 1 changelog
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
@@ -1265,13 +1265,13 @@ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
- [ ] **Step 1: 创建 Phase 1 完成标签**
```bash
cd g:/ZClaw_openfang && git tag -a v0.3.0-phase1 -m "Phase 1: Security + Testing Complete"
cd g:/ZClaw_zclaw && git tag -a v0.3.0-phase1 -m "Phase 1: Security + Testing Complete"
```
- [ ] **Step 2: 推送所有提交**
```bash
cd g:/ZClaw_openfang && git push origin main --tags
cd g:/ZClaw_zclaw && git push origin main --tags
```
---

32
docs/superpowers/plans/2026-03-21-phase2-domain-reorganization.md
View File

@@ -70,7 +70,7 @@ desktop/
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm add valtio
cd g:/ZClaw_zclaw/desktop && pnpm add valtio
```
Expected: valtio 安装成功
@@ -79,7 +79,7 @@ Expected: valtio 安装成功
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm add xstate @xstate/react
cd g:/ZClaw_zclaw/desktop && pnpm add xstate @xstate/react
```
Expected: xstate 和 @xstate/react 安装成功
@@ -88,7 +88,7 @@ Expected: xstate 和 @xstate/react 安装成功
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm list valtio xstate @xstate/react
cd g:/ZClaw_zclaw/desktop && pnpm list valtio xstate @xstate/react
```
Expected: 显示已安装版本
@@ -96,7 +96,7 @@ Expected: 显示已安装版本
- [ ] **Step 4: 提交依赖更新**
```bash
cd g:/ZClaw_openfang && git add desktop/package.json desktop/pnpm-lock.yaml
cd g:/ZClaw_zclaw && git add desktop/package.json desktop/pnpm-lock.yaml
git commit -m "$(cat <<'EOF'
feat(deps): add Valtio and XState for Phase 2
@@ -123,13 +123,13 @@ EOF
Run:
```bash
cd g:/ZClaw_openfang/desktop/src && mkdir -p domains/chat domains/hands domains/intelligence domains/skills shared
cd g:/ZClaw_zclaw/desktop/src && mkdir -p domains/chat domains/hands domains/intelligence domains/skills shared
```
- [ ] **Step 2: 提交目录结构**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains desktop/src/shared
cd g:/ZClaw_zclaw && git add desktop/src/domains desktop/src/shared
git commit -m "$(cat <<'EOF'
refactor: create domains directory structure
@@ -240,7 +240,7 @@ export interface ChatState {
- [ ] **Step 2: 提交类型定义**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains/chat/types.ts
cd g:/ZClaw_zclaw && git add desktop/src/domains/chat/types.ts
git commit -m "$(cat <<'EOF'
refactor(chat): extract chat domain types
@@ -442,7 +442,7 @@ if (import.meta.env.DEV) {
- [ ] **Step 2: 提交 Valtio Store**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains/chat/store.ts
cd g:/ZClaw_zclaw && git add desktop/src/domains/chat/store.ts
git commit -m "$(cat <<'EOF'
refactor(chat): create Valtio-based chat store
@@ -566,7 +566,7 @@ export {
- [ ] **Step 3: 提交 Hooks 和 Index**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains/chat/hooks.ts desktop/src/domains/chat/index.ts
cd g:/ZClaw_zclaw && git add desktop/src/domains/chat/hooks.ts desktop/src/domains/chat/index.ts
git commit -m "$(cat <<'EOF'
refactor(chat): add chat domain hooks and public API
@@ -675,7 +675,7 @@ export type HandsEvent =
- [ ] **Step 2: 提交类型定义**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains/hands/types.ts
cd g:/ZClaw_zclaw && git add desktop/src/domains/hands/types.ts
git commit -m "$(cat <<'EOF'
refactor(hands): extract hands domain types
@@ -809,7 +809,7 @@ export const handMachine = setup({
- [ ] **Step 2: 提交状态机**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains/hands/machine.ts
cd g:/ZClaw_zclaw && git add desktop/src/domains/hands/machine.ts
git commit -m "$(cat <<'EOF'
refactor(hands): create XState machine for hand execution
@@ -960,7 +960,7 @@ export { useHandsState, useHands, useApprovalQueue, useHandsActions } from './ho
- [ ] **Step 4: 提交 Hands Domain**
```bash
cd g:/ZClaw_openfang && git add desktop/src/domains/hands/
cd g:/ZClaw_zclaw && git add desktop/src/domains/hands/
git commit -m "$(cat <<'EOF'
refactor(hands): complete hands domain migration
@@ -1063,7 +1063,7 @@ export * from './types';
- [ ] **Step 4: 提交共享模块**
```bash
cd g:/ZClaw_openfang && git add desktop/src/shared/
cd g:/ZClaw_zclaw && git add desktop/src/shared/
git commit -m "$(cat <<'EOF'
refactor(shared): create shared module
@@ -1102,7 +1102,7 @@ export * from '../domains/chat';
- [ ] **Step 2: 提交兼容层**
```bash
cd g:/ZClaw_openfang && git add desktop/src/store/chatStore.ts
cd g:/ZClaw_zclaw && git add desktop/src/store/chatStore.ts
git commit -m "$(cat <<'EOF'
refactor(chat): add backward compatibility layer
@@ -1122,7 +1122,7 @@ EOF
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test tests/store/chatStore.test.ts
cd g:/ZClaw_zclaw/desktop && pnpm test tests/store/chatStore.test.ts
```
Expected: Tests pass with new Valtio store
@@ -1131,7 +1131,7 @@ Expected: Tests pass with new Valtio store
Run:
```bash
cd g:/ZClaw_openfang/desktop && pnpm test
cd g:/ZClaw_zclaw/desktop && pnpm test
```
Expected: No new test failures

2
docs/superpowers/plans/2026-03-21-phase3-core-optimization.md
View File

@@ -64,7 +64,7 @@ desktop/src/
- [ ] **Step 1: 安装依赖**
```bash
cd g:/ZClaw_openfang/desktop && pnpm add react-window @types/react-window
cd g:/ZClaw_zclaw/desktop && pnpm add react-window @types/react-window
```
- [ ] **Step 2: 验证安装**

2
docs/superpowers/specs/2026-03-18-automation-system-redesign.md
View File

@@ -74,7 +74,7 @@
### 2.2 数据流
```
用户操作 → AutomationPanel → automationStore → gateway-client → OpenFang API
用户操作 → AutomationPanel → automationStore → gateway-client → ZCLAW API
│
├── 更新 UI 状态
├── WebSocket 事件 → 更新执行状态

2
docs/superpowers/specs/2026-03-21-architecture-optimization-design.md
View File

@@ -78,7 +78,7 @@ ZCLAW 是面向中文用户的 AI Agent 桌面客户端，经过分析发现以
┌─────────────────────────────────────────────────────────────────┐
│ Backend Layer │
│ ┌──────────────────┐ ┌──────────────────────────────────────┐│
│ │ OpenFang Kernel │ │ Tauri Rust Backend ││
│ │ ZCLAW Kernel │ │ Tauri Rust Backend ││
│ │ (Port 50051) │ │ - Intelligence (心跳/压缩/反思) ││
│ │ │ │ - Memory (SQLite 持久化) ││
│ │ │ │ - Browser (WebDriver) ││

2
docs/test-reports/DEEP_TEST_REPORT.md
View File

@@ -133,7 +133,7 @@
"role": "代码助手",
"nickname": "开发者",
"scenarios": ["编程", "调试"],
"workspaceDir": "~/.openfang/zclaw-workspace",
"workspaceDir": "~/.zclaw/zclaw-workspace",
"userName": "测试用户",
"restrictFiles": true,
"privacyOptIn": false

24
docs/testing/INTEGRATION-CHECKLIST.md
View File

@@ -10,7 +10,7 @@
### 前置条件
- [ ] OpenFang Kernel 已安装并配置
- [ ] ZCLAW Kernel 已安装并配置
- [ ] 至少一个中文模型 API Key 已配置（GLM/Qwen/Kimi/MiniMax）
- [ ] Tauri 桌面应用已构建
- [ ] 测试账号已准备
@@ -18,7 +18,7 @@
### 环境变量检查
```bash
# 检查 OpenFang 配置
# 检查 ZCLAW 配置
cat config/config.toml
# 检查中文模型配置
@@ -29,11 +29,11 @@ cat config/chinese-providers.toml
## 一、Gateway 连接测试
### TEST-GW-01: OpenFang Kernel 启动
### TEST-GW-01: ZCLAW Kernel 启动
| 项目 | 内容 |
|------|------|
| **前置条件** | OpenFang 已安装 |
| **前置条件** | ZCLAW 已安装 |
| **测试步骤** | 1. 启动 Tauri 应用<br>2. 检查连接状态指示器<br>3. 确认显示"已连接" |
| **预期结果** | 连接状态为 `connected`，无错误提示 |
| **验证方法** | 检查 ConnectionStatus 组件状态 |
@@ -64,7 +64,7 @@ cat config/chinese-providers.toml
| 项目 | 内容 |
|------|------|
| **前置条件** | TEST-GW-02 通过 |
| **测试步骤** | 1. 手动停止 OpenFang 进程<br>2. 等待 10 秒<br>3. 重启 OpenFang<br>4. 观察应用行为 |
| **测试步骤** | 1. 手动停止 ZCLAW 进程<br>2. 等待 10 秒<br>3. 重启 ZCLAW<br>4. 观察应用行为 |
| **预期结果** | 应用自动重连，状态正确更新 |
| **验证方法** | 检查重连日志和 UI 状态变化 |
| **当前状态** | ⏳ 待验证 |
@@ -281,7 +281,7 @@ cat config/chinese-providers.toml
|----------|--------|------|
| workflowStore.test.ts | 32 | ✅ 通过 |
| teamStore.test.ts | 20 | ✅ 通过 |
| openfang-api.test.ts | 30 | ✅ 通过 |
| zclaw-api.test.ts | 30 | ✅ 通过 |
| swarm-skills.test.ts | 15 | ✅ 通过 |
| heartbeat-reflection.test.ts | 25 | ✅ 通过 |
| **总计** | **312** | **✅ 全部通过** |
@@ -309,7 +309,7 @@ cat config/chinese-providers.toml
| 项目 | 状态 | 说明 |
|------|------|------|
| pnpm | ✅ | v10.30.2 |
| OpenFang Runtime | ✅ | v0.4.0 (57MB) |
| ZCLAW Runtime | ✅ | v0.4.0 (57MB) |
| Playwright | ✅ | v1.58.2 |
| 配置文件 | ✅ | config.toml, chinese-providers.toml |
@@ -328,7 +328,7 @@ echo "Started at: $(date)"
# 1. 检查环境
echo "[1/5] Checking environment..."
command -v openfang >/dev/null 2>&1 || { echo "ERROR: openfang not found"; exit 1; }
command -v zclaw >/dev/null 2>&1 || { echo "ERROR: zclaw not found"; exit 1; }
command -v pnpm >/dev/null 2>&1 || { echo "ERROR: pnpm not found"; exit 1; }
# 2. 检查配置
@@ -336,9 +336,9 @@ echo "[2/5] Checking configuration..."
test -f config/config.toml || { echo "ERROR: config.toml not found"; exit 1; }
test -f config/chinese-providers.toml || { echo "ERROR: chinese-providers.toml not found"; exit 1; }
# 3. 启动 OpenFang
echo "[3/5] Starting OpenFang..."
openfang start || { echo "ERROR: Failed to start OpenFang"; exit 1; }
# 3. 启动 ZCLAW
echo "[3/5] Starting ZCLAW..."
zclaw start || { echo "ERROR: Failed to start ZCLAW"; exit 1; }
sleep 5
# 4. 运行 E2E 测试
@@ -348,7 +348,7 @@ pnpm test:e2e || { echo "WARNING: Some E2E tests failed"; }
# 5. 清理
echo "[5/5] Cleanup..."
openfang stop
zclaw stop
echo "=== Test completed at: $(date) ==="
```