# ZCLAW 知识库

> 记录开发过程中的经验、问题和解决方案，为项目演化提供知识储备。

## 目录结构

```
knowledge-base/
├── README.md                    # 本文件 - 索引
├── openfang-websocket-protocol.md   # OpenFang WebSocket 协议实际实现
├── troubleshooting.md           # 常见问题排查
├── frontend-integration.md      # 前端集成模式
├── agent-provider-config.md     # Agent 和 LLM 提供商配置
├── tauri-desktop.md            # Tauri 桌面端开发笔记
├── feature-checklist.md        # 功能清单和验证状态
└── hands-integration-lessons.md # Hands 集成经验总结
```

> **系统分析**: 完整的系统偏离分析和演化路线图见 [../SYSTEM_ANALYSIS.md](../SYSTEM_ANALYSIS.md)

## 快速索引

### 协议与通信

| 主题 | 文件 | 关键词 |
|------|------|--------|
| WebSocket 流式聊天 | [openfang-websocket-protocol.md](./openfang-websocket-protocol.md) | 流式响应, 事件类型, 消息格式 |
| REST API | [openfang-websocket-protocol.md](./openfang-websocket-protocol.md#rest-api) | Agent, Hands, Health |

### 故障排查

| 问题类型 | 文件 | 常见原因 |
|---------|------|----------|
| 连接失败 | [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 功能集成经验 |

## 版本历史

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-03-14 | v1.1 | 添加 Hands 集成经验总结、功能清单 |
| 2026-03-14 | v1.0 | 初始创建，记录 OpenFang WebSocket 协议发现 |

---

## 贡献指南

当遇到以下情况时，请更新知识库：

1. **发现协议与文档不一致** - 记录实际行为
2. **解决了一个棘手的 bug** - 记录根因和解决方案
3. **找到了更好的实现方式** - 记录模式和最佳实践
4. **踩了坑** - 记录避坑指南

### 文档格式

```markdown
# 主题

## 问题描述
简要描述遇到的问题

## 根本原因
解释为什么会发生

## 解决方案
具体的解决步骤

## 代码示例
相关代码片段

## 相关文件
列出涉及的源文件
```