2ceeeaba3d
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
Batch 1 — User-facing fixes: - B1-1: Pipeline verified end-to-end (14 Rust commands, 8 frontend invoke, fully connected) - B1-2: MessageSearch restored to ChatArea with search button in DeerFlow header - B1-3: Viking cleanup — removed 5 orphan invokes (no Rust impl), added addWithMetadata + storeWithSummaries methods + summary generation UI - B1-4: api-fallbacks transparency — added _isFallback markers + console.warn to all 6 fallback functions Batch 2 — System health: - B2-1: Document drift calibration — TRUTH.md/README.md numbers verified and updated - B2-2: @reserved annotations on 15 SaaS handler functions with no frontend callers - B2-3: Scheduled Task Admin V2 — new service + page + route + sidebar navigation - B2-4: TRUTH.md Pipeline/Viking/ScheduledTask records corrected Batch 3 — Long-term quality: - B3-1: hand_run_status/hand_run_list verified as fully implemented (not stubs) - B3-2: Identity snapshot rollback UI added to RightPanel - B3-3: P2 code quality — 4 fixes (TODO comments, fire-and-forget notes, design notes, table name validation), 2 verified N/A, 1 upstream - B3-4: Config PATCH→PUT alignment (admin-v2 config.ts matched to SaaS backend)
146 lines
6.7 KiB
Markdown
146 lines
6.7 KiB
Markdown
# 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 核心由 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
|