# ZCLAW 文档中心

## 快速导航

| 文档 | 说明 |
|------|------|
| [快速启动](quick-start.md) | 5 分钟内启动 ZCLAW 开发环境 |
| [开发指南](DEVELOPMENT.md) | 开发环境设置、构建、测试 |
| [用户手册](USER_MANUAL.md) | 终端用户使用指南 |
| [Agent 进化计划](ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md) | 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 核心由 8 个 Rust Crate 组成：

| Crate | 层级 | 职责 |
|-------|------|------|
| `zclaw-types` | L1 | 基础类型 (AgentId, Message, Error) |
| `zclaw-memory` | L2 | 存储层 (SQLite, 会话管理) |
| `zclaw-runtime` | L3 | 运行时 (LLM 驱动, 工具, Agent 循环) |
| `zclaw-kernel` | L4 | 核心协调 (注册, 调度, 事件, 工作流) |
| `zclaw-skills` | - | 技能系统 (SKILL.md 解析, 执行器) |
| `zclaw-hands` | - | 自主能力 (Hand/Trigger 注册管理) |
| `zclaw-protocols` | - | 协议支持 (MCP, A2A) |

### 依赖关系

```
zclaw-types          (无依赖)
    ↑
zclaw-memory         (→ types)
    ↑
zclaw-runtime        (→ types, memory)
    ↑
zclaw-kernel         (→ types, memory, runtime)
    ↑
desktop/src-tauri    (→ kernel, skills, hands, channels, protocols)
```

## 支持的 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 |
| local | `http://localhost:11434/v1` | Ollama/LMStudio |

## 项目状态

- **架构迁移**: Phase 5 完成 - 内部 Kernel 集成
- **Agent 智能层**: Phase 1-3 完成
- **测试覆盖**: 161 E2E tests passing, 26 Rust tests passing

## 贡献指南

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

---

**最后更新**: 2026-03-22