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 功能全景文档
版本: v0.7.0 更新日期: 2026-03-28 项目状态: 完整 Rust Workspace 架构，11 个核心 Crates，69 技能，Pipeline DSL + Smart Presentation + Agent Growth System + SaaS 平台 整体完成度: ~85% (核心功能完整，SaaS 平台全面上线)
一、文档索引
1.1 架构层 (Architecture)
| 文档 | 功能 | 成熟度 | 测试覆盖 |
|---|---|---|---|
| 01-communication-layer.md | 通信层 (3 种连接模式) | L4 (90%) | 高 |
| 02-state-management.md | 状态管理 | L3 (80%) | 高 |
| 03-security-auth.md | 安全认证 | L3 (75%) | 高 |
1.2 核心功能 (Core Features)
| 文档 | 功能 | 成熟度 | 测试覆盖 |
|---|---|---|---|
| 00-chat-interface.md | 聊天界面 | L4 (92%) | 高 |
| 01-agent-clones.md | Agent 分身 | L3 (85%) | 高 |
| 02-hands-system.md | Hands 系统 | L3 (60%) | 中 |
1.3 智能层 (Intelligence Layer)
| 文档 | 功能 | 成熟度 | 聊天集成 |
|---|---|---|---|
| 00-agent-memory.md | Agent 记忆 | L4 (90%) | pre-hook (FTS5+TF-IDF+Embedding) |
| 01-identity-evolution.md | 身份演化 | L2 (70%) | pre-hook (SOUL.md) |
| 06-context-compaction.md | 上下文压缩 | L3 (75%) | 内核 AgentLoop 集成 |
| 03-reflection-engine.md | 自我反思 | L2 (65%) | post-hook (自动触发) |
| 04-heartbeat-engine.md | 心跳巡检 | L3 (70%) | post-hook (持久化) |
| 05-autonomy-manager.md | 自主授权 | L3 (75%) | RightPanel UI |
1.4 上下文数据库 (Context Database)
| 文档 | 功能 | 成熟度 | 测试覆盖 |
|---|---|---|---|
| 00-openviking-integration.md | OpenViking 集成 | L3 (70%) | 高 |
1.5 Skills 生态
| 文档 | 功能 | 成熟度 | UI 集成 |
|---|---|---|---|
| 00-skill-system.md | Skill 系统概述 | L3 (80%) | Tauri 命令 |
| 01-intelligent-routing.md | 智能路由 | L2 (50%) | 意图路由 |
技能总数: 69 个 SKILL.md，3 种执行模式 (PromptOnly/Shell/Python)，Wasm/Native 待实现
1.6 Hands 系统
| 文档 | 功能 | 成熟度 | 可用 Hands |
|---|---|---|---|
| 00-hands-overview.md | Hands 概述 | L3 (60%) | 9 个 (编程式注册) |
9 Hands: Browser, Slideshow, Speech (demo), Quiz, Whiteboard, Researcher, Collector, Clip, Twitter (demo)
1.7 Tauri 后端
| 文档 | 功能 | 成熟度 | Tauri 命令 |
|---|---|---|---|
| 00-backend-integration.md | 后端集成 | L4 (85%) | 58+ (kernel 29 + pipeline 13 + viking 13 + llm 3) |
1.8 Pipeline DSL
| 文档 | 功能 | 成熟度 | UI 集成 |
|---|---|---|---|
| 00-pipeline-overview.md | Pipeline 概述 | L3 (75%) | PipelinesPanel |
1.9 SaaS 平台
| 文档 | 功能 | 成熟度 | API 路由 |
|---|---|---|---|
| 00-saas-overview.md | SaaS 平台总览 | L4 (95%) | 76+ (9 个模块) |
SaaS 后端: Axum + PostgreSQL, 9 模块 (Auth, Account, Model Config, Relay, Migration, Role, Prompt OTA, Agent Template, Telemetry), Admin 管理后台, 桌面端完整集成
二、关键指标
| 指标 | 数值 |
|---|---|
| Rust Crates | 11 (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, channels, saas) |
| SKILL.md 文件 | 69 |
| Hands 总数 | 9 (编程式注册) |
| Pipeline 模板 | 5 |
| Tauri 命令 | 58+ |
| SaaS API 路由 | 76+ |
| Zustand Store | 14+ |
| LLM Provider | 8 (Kimi, Qwen, DeepSeek, Zhipu, OpenAI, Anthropic, Gemini, Local) |
| Embedding Provider | 6 (OpenAI, Zhipu, Doubao, Qwen, DeepSeek, Local/TF-IDF) |
| SaaS 数据表 | 25 (PostgreSQL) |
| 内置工具 | 5 (file_read, file_write, shell_exec, web_fetch, execute_skill) |
| Agent Growth System | SqliteStorage + FTS5 + TF-IDF + Memory Extractor |
三、Crate 依赖关系
zclaw-types (L1: 基础类型, 无依赖) — 95%
↑
zclaw-memory (L2: 存储层, SQLite) — 90%
↑
zclaw-runtime (L3: 运行时, 4 Driver, 5 工具) — 90%
↑
zclaw-kernel (L4: 核心协调, 9 Hands, 69 Skills) — 85%
↑
┌───┴───┬───────┬───────────┬──────────┬────────┐
│ │ │ │ │ │
skills hands protocols pipeline growth channels
(80%) (85%) (75%) (90%) (95%) (规划中)
zclaw-saas — 独立运行 (Axum + PostgreSQL, 端口 8080) — 95%
四、SaaS 平台模块
| 模块 | API 路由 | 核心能力 |
|---|---|---|
| Auth | 8 | JWT + API Token 双认证, TOTP 2FA (AES-256-GCM), 密码修改 |
| Account | 12 | CRUD, 角色管理, 设备注册/心跳, Dashboard, API Token |
| Model Config | 14 | Provider/Model/Key CRUD, Key 轮换, 用量统计 |
| Relay | 9 | SSE 流式中转, Key 池 (RPM/TPM), 重试策略, SSRF 防护 |
| Migration | 9 | 配置 CRUD, 种子数据, push/merge/diff/pull 同步 |
| Role | 7 | 角色 CRUD, 权限模板, 批量应用 |
| Prompt OTA | 8 | 模板 + 版本管理, OTA 检查, 回滚 |
| Agent Template | 5 | 模板 CRUD, tools/capabilities/model 绑定 |
| Telemetry | 4 | Token 用量上报, 统计聚合, 审计摘要 |
五、连接模式
| 模式 | 客户端 | 说明 |
|---|---|---|
| Mode A: Tauri Kernel | KernelClient | 本地直连 LLM (默认模式) |
| Mode B: Gateway | GatewayClient | WebSocket 本地中转 |
| Mode C: SaaS Cloud | SaaSClient (30+ 方法) | 云端中转 + Key 池管理 |
六、变更历史
| 日期 | 版本 | 变更内容 |
|---|---|---|
| 2026-03-28 | v0.7.0 | 基于 2026-03-28 代码状态全面更新：SaaS 平台 76+ API 路由/9 模块/25 表，58+ Tauri 命令，8 LLM Provider，3 种连接模式 |
| 2026-03-27 | v0.6.4 | 审计修复第四轮，S9 消息搜索跨会话，自主授权后端守卫 |
| 2026-03-27 | v0.6.0 | 深度审计更新，整体完成度调整 |
| 2026-03-26 | v0.1.0 | v1.0 发布准备，移除 Team/Swarm |
| 2026-03-25 | v0.5.0 | Smart Presentation Layer |
| 2026-03-25 | v0.4.0 | 代码现状深度分析 |
| 2026-03-24 | v0.3.0 | Pipeline DSL 系统实现 |