iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
1c697d0b46b3ca447c179a5d864c24272582e339
zclaw_openfang/docs/knowledge-base/README.md
iven e7b2d1c099 docs: 审计后文档同步 — feature-checklist/roadmap/technical-reference 更新 
- feature-checklist: 新增 Admin V2 章节(12项全通过)，Speech/Twitter 状态提升，
  Hands 9/11 可用，安全备注更新
- roadmap: 标记 S1/S3 审批/Hand 为已完成，更新 crate 数量(10)，
  新增审计/依赖/清理已完成项
- technical-reference: 更新日期至 03-30，crate 数量 10
2026-03-30 18:32:02 +08:00

4.1 KiB
Raw Blame History

ZCLAW 知识库

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

目录结构

knowledge-base/
├── README.md                       # 本文件 - 索引
├── axum-dashmap-deadlock.md        # Axum + DashMap 运行时死锁：根因分析与修复
├── 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 流式响应, 事件类型, 消息格式
REST API zclaw-technical-reference.md Agent, Hands, Health
配置系统 configuration.md TOML, 环境变量

故障排查

问题类型 文件 常见原因
连接失败 troubleshooting.md 端口、认证、配置
流式响应不工作 troubleshooting.md 事件类型、代理配置
LLM 错误 troubleshooting.md API Key 未配置
运行时死锁 axum-dashmap-deadlock.md DashMap/Mutex 锁跨 await、parking_lot 阻塞 worker thread

开发指南

主题 文件 说明
前端集成 frontend-integration.md React + Zustand 模式
Agent 配置 agent-provider-config.md LLM 提供商配置
Tauri 开发 tauri-desktop.md 桌面端开发注意事项
功能清单 feature-checklist.md 所有功能的验证状态
Hands 集成 hands-integration-lessons.md Hands 功能集成经验
语义记忆审计 semantic-memory-audit.md 审计方法论 + 差距记录 + 可复用清单

参考项目分析

主题 文件 说明
OpenMAIC 分析 openmaic-analysis.md 清华大学 AI 教育平台深度分析
对比分析 openmaic-zclaw-comparison.md OpenMAIC vs ZCLAW 功能对比

版本历史

日期 版本 变更
2026-03-30 v2.3 添加 Axum + DashMap 运行时死锁根因分析，含死锁机制、修复方案、防范模式和审计清单
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. 踩了坑 - 记录避坑指南

文档格式

# 主题

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

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

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

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

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