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

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 工具链路 |