zclaw_openfang/docs

ZCLAW 文档中心

快速导航

文档	说明
快速启动	5 分钟内启动 ZCLAW 开发环境
开发指南	开发环境设置、构建、测试
用户手册	终端用户使用指南
Agent 进化计划	Agent 智能层发展规划

架构概述

ZCLAW 采用内部 Kernel 架构，所有核心能力都集成在 Tauri 桌面应用中：

┌─────────────────────────────────────────────────────────────────┐
│                      ZCLAW 桌面应用                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐     ┌─────────────────────────────────┐   │
│  │  React 前端     │     │  Tauri 后端 (Rust)              │   │
│  │  ├─ UI 组件     │     │  ├─ zclaw-kernel (核心协调)     │   │
│  │  ├─ Zustand     │────▶│  ├─ zclaw-runtime (LLM 驱动)    │   │
│  │  └─ KernelClient│     │  ├─ zclaw-memory (存储层)       │   │
│  └─────────────────┘     │  └─ zclaw-types (基础类型)      │   │
│                          └─────────────────────────────────┘   │
│                                       │                         │
│                                       ▼                         │
│                          ┌─────────────────────────────────┐   │
│                          │  多 LLM 提供商支持               │   │
│                          │  Kimi | Qwen | DeepSeek | Zhipu │   │
│                          │  OpenAI | Anthropic | Local     │   │
│                          └─────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

关键特性：

• 无外部依赖 - 不需要启动独立的后端进程
• 单安装包运行 - 用户安装后即可使用
• UI 配置模型 - 在"模型与 API"设置页面配置 LLM 提供商

文档结构

docs/
├── quick-start.md                    # 快速启动指南
├── DEVELOPMENT.md                    # 开发指南
├── USER_MANUAL.md                    # 用户手册
├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md  # Agent 进化计划
│
├── features/                         # 功能文档
│   ├── 00-architecture/              # 架构设计
│   │   ├── 01-communication-layer.md # 通信层
│   │   ├── 02-state-management.md    # 状态管理
│   │   └── 03-security-auth.md       # 安全认证
│   ├── 01-core-features/             # 核心功能
│   ├── 02-intelligence-layer/        # 智能层
│   └── 06-tauri-backend/             # Tauri 后端
│
├── knowledge-base/                   # 技术知识库
│   ├── troubleshooting.md            # 故障排除
│   └── ...
│
├── archive/                          # 归档文档
│   ├── completed-plans/              # 已完成的计划
│   ├── research-reports/             # 研究报告
│   └── zclaw-legacy/              # 历史遗留文档
│
├── plans/                            # 执行计划
│   └── ...
│
└── test-reports/                     # 测试报告
    └── ...

Crate 架构

ZCLAW 核心由 10 个 Rust Crate 组成：

Crate	层级	职责
zclaw-types	L1	基础类型 (AgentId, Message, Error)
zclaw-memory	L2	存储层 (SQLite, 会话管理)
zclaw-runtime	L3	运行时 (LLM 驱动, 工具, Agent 循环)
zclaw-kernel	L4	核心协调 (注册, 调度, 事件, 工作流)
zclaw-skills	L5	技能系统 (SKILL.md 解析, 执行器)
zclaw-hands	L5	自主能力 (Hand/Trigger 注册管理)
zclaw-protocols	L5	协议支持 (MCP, A2A)
zclaw-pipeline	L5	Pipeline DSL (v1/v2, 模板)
zclaw-growth	L5	记忆增长 (FTS5 + TF-IDF)
zclaw-saas	独立	SaaS 后端 (Axum + PostgreSQL)

依赖关系

zclaw-types          (无依赖)
    ↑
zclaw-memory         (→ types)
    ↑
zclaw-runtime        (→ types, memory)
    ↑
zclaw-kernel         (→ types, memory, runtime)
    ↑
┌───┴───┬───────┬───────────┬──────────┐
│       │       │           │          │
skills  hands  protocols  pipeline  growth

desktop/src-tauri    (→ kernel, skills, hands, protocols)
zclaw-saas           (独立运行于 8080 端口)

支持的 LLM 提供商

Provider	Base URL	说明
kimi	https://api.kimi.com/coding/v1	Kimi Code
qwen	https://dashscope.aliyuncs.com/compatible-mode/v1	百炼/通义千问
deepseek	https://api.deepseek.com/v1	DeepSeek
zhipu	https://open.bigmodel.cn/api/paas/v4	智谱 GLM
openai	https://api.openai.com/v1	OpenAI
anthropic	https://api.anthropic.com	Anthropic Claude
gemini	https://generativeai.googleapis.com/v1beta	Google Gemini
local	http://localhost:11434/v1	Ollama/LMStudio

项目状态

• 架构迁移: Phase 5 完成 - 内部 Kernel 集成
• Agent 智能层: Phase 1-3 完成
• Rust Crates: 10 个 (171 Tauri 命令, 383 单元测试)
• SaaS 平台: 131 API 路由, 12 模块, 34 数据表
• 前端: React 19 + Zustand 18 Stores, 135 组件
• 安全审计: V1 通过 (B+)

贡献指南

1. 新文档放在适当的目录中
2. 使用清晰的文件命名（小写、连字符分隔）
3. 计划文件使用日期前缀：YYYY-MM-DD-description.md
4. 完成后将计划移动到 archive/completed-plans/

---

最后更新: 2026-04-03