iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
9ee23e444cf7b7fd451e41a74a8f11f958e47b89
zclaw_openfang/docs/README.md
iven 3ff08faa56 release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements 
## Major Features

### Streaming Response System
- Implement LlmDriver trait with `stream()` method returning async Stream
- Add SSE parsing for Anthropic and OpenAI API streaming
- Integrate Tauri event system for frontend streaming (`stream:chunk` events)
- Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error

### MCP Protocol Implementation
- Add MCP JSON-RPC 2.0 types (mcp_types.rs)
- Implement stdio-based MCP transport (mcp_transport.rs)
- Support tool discovery, execution, and resource operations

### Browser Hand Implementation
- Complete browser automation with Playwright-style actions
- Support Navigate, Click, Type, Scrape, Screenshot, Wait actions
- Add educational Hands: Whiteboard, Slideshow, Speech, Quiz

### Security Enhancements
- Implement command whitelist/blacklist for shell_exec tool
- Add SSRF protection with private IP blocking
- Create security.toml configuration file

## Test Improvements
- Fix test import paths (security-utils, setup)
- Fix vi.mock hoisting issues with vi.hoisted()
- Update test expectations for validateUrl and sanitizeFilename
- Add getUnsupportedLocalGatewayStatus mock

## Documentation Updates
- Update architecture documentation
- Improve configuration reference
- Add quick-start guide updates

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-24 03:24:24 +08:00

6.1 KiB
Raw Blame History

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/             # 研究报告
│   └── openclaw-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-channels - 通道适配器 (Telegram, Discord, Slack)
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