0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
101 lines
3.8 KiB
Markdown
101 lines
3.8 KiB
Markdown
# ZCLAW 知识库
|
|
|
|
> 记录开发过程中的经验、问题和解决方案，为项目演化提供知识储备。
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
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 集成经验总结
|
|
├── semantic-memory-audit.md # 语义记忆审计记录与审计方法论
|
|
├── openmaic-analysis.md # OpenMAIC 项目深度分析
|
|
└── openmaic-zclaw-comparison.md # OpenMAIC vs ZCLAW 对比分析
|
|
```
|
|
|
|
## 快速索引
|
|
|
|
### 协议与通信
|
|
|
|
| 主题 | 文件 | 关键词 |
|
|
|------|------|--------|
|
|
| WebSocket 流式聊天 | [websocket-protocol.md](./websocket-protocol.md) | 流式响应, 事件类型, 消息格式 |
|
|
| REST API | [zclaw-technical-reference.md](./zclaw-technical-reference.md) | Agent, Hands, Health |
|
|
| 配置系统 | [configuration.md](./configuration.md) | TOML, 环境变量 |
|
|
|
|
### 故障排查
|
|
|
|
| 问题类型 | 文件 | 常见原因 |
|
|
|---------|------|----------|
|
|
| 连接失败 | [troubleshooting.md](./troubleshooting.md) | 端口、认证、配置 |
|
|
| 流式响应不工作 | [troubleshooting.md](./troubleshooting.md) | 事件类型、代理配置 |
|
|
| LLM 错误 | [troubleshooting.md](./troubleshooting.md) | API Key 未配置 |
|
|
|
|
### 开发指南
|
|
|
|
| 主题 | 文件 | 说明 |
|
|
|------|------|------|
|
|
| 前端集成 | [frontend-integration.md](./frontend-integration.md) | React + Zustand 模式 |
|
|
| Agent 配置 | [agent-provider-config.md](./agent-provider-config.md) | LLM 提供商配置 |
|
|
| 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) | 审计方法论 + 差距记录 + 可复用清单 |
|
|
|
|
### 参考项目分析
|
|
|
|
| 主题 | 文件 | 说明 |
|
|
|------|------|------|
|
|
| OpenMAIC 分析 | [openmaic-analysis.md](./openmaic-analysis.md) | 清华大学 AI 教育平台深度分析 |
|
|
| 对比分析 | [openmaic-zclaw-comparison.md](./openmaic-zclaw-comparison.md) | OpenMAIC vs ZCLAW 功能对比 |
|
|
|
|
## 版本历史
|
|
|
|
| 日期 | 版本 | 变更 |
|
|
|------|------|------|
|
|
| 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 集成经验总结、功能清单 |
|
|
| 2026-03-14 | v1.0 | 初始创建 |
|
|
|
|
---
|
|
|
|
## 贡献指南
|
|
|
|
当遇到以下情况时，请更新知识库：
|
|
|
|
1. **发现协议与文档不一致** - 记录实际行为
|
|
2. **解决了一个棘手的 bug** - 记录根因和解决方案
|
|
3. **找到了更好的实现方式** - 记录模式和最佳实践
|
|
4. **踩了坑** - 记录避坑指南
|
|
|
|
### 文档格式
|
|
|
|
```markdown
|
|
# 主题
|
|
|
|
## 问题描述
|
|
简要描述遇到的问题
|
|
|
|
## 根本原因
|
|
解释为什么会发生
|
|
|
|
## 解决方案
|
|
具体的解决步骤
|
|
|
|
## 代码示例
|
|
相关代码片段
|
|
|
|
## 相关文件
|
|
列出涉及的源文件
|
|
```
|