8b9d506893
Phase 0: 知识库
- docs/knowledge-base/loco-rs-patterns.md — loco-rs 10 个可借鉴模式研究
Phase 1: 数据层重构
- crates/zclaw-saas/src/models/ — 15 个 FromRow 类型化模型
- Login 3 次查询合并为 1 次 AccountLoginRow 查询
- 所有 service 文件从元组解构迁移到 FromRow 结构体
Phase 2: Worker + Scheduler 系统
- crates/zclaw-saas/src/workers/ — Worker trait + 5 个具体实现
- crates/zclaw-saas/src/scheduler.rs — TOML 声明式调度器
- crates/zclaw-saas/src/tasks/ — CLI 任务系统
Phase 3: 性能修复
- Relay N+1 查询 → 精准 SQL (relay/handlers.rs)
- Config RwLock → AtomicU32 无锁 rate limit (state.rs, middleware.rs)
- SSE std::sync::Mutex → tokio::sync::Mutex (relay/service.rs)
- /auth/refresh 阻塞清理 → Scheduler 定期执行
Phase 4: 多环境配置
- config/saas-{development,production,test}.toml
- ZCLAW_ENV 环境选择 + ZCLAW_SAAS_CONFIG 精确覆盖
- scheduler 配置集成到 TOML
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 | 流式响应, 事件类型, 消息格式 |
| REST API | zclaw-technical-reference.md | Agent, Hands, Health |
| 配置系统 | configuration.md | TOML, 环境变量 |
故障排查
| 问题类型 | 文件 | 常见原因 |
|---|---|---|
| 连接失败 | troubleshooting.md | 端口、认证、配置 |
| 流式响应不工作 | troubleshooting.md | 事件类型、代理配置 |
| LLM 错误 | troubleshooting.md | API Key 未配置 |
开发指南
| 主题 | 文件 | 说明 |
|---|---|---|
| 前端集成 | 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-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 | 初始创建 |
贡献指南
当遇到以下情况时，请更新知识库：
- 发现协议与文档不一致 - 记录实际行为
- 解决了一个棘手的 bug - 记录根因和解决方案
- 找到了更好的实现方式 - 记录模式和最佳实践
- 踩了坑 - 记录避坑指南
文档格式
# 主题
## 问题描述
简要描述遇到的问题
## 根本原因
解释为什么会发生
## 解决方案
具体的解决步骤
## 代码示例
相关代码片段
## 相关文件
列出涉及的源文件