第二章 · ARCHITECTURE

架构 · 模块 · 文件结构

zeroclaw 采用清晰的五层垂直架构，10 个核心模块各司其职，安全系统贯穿整个执行链。本页详解每层职责、模块接口、安全子系统、支持的 LLM 提供商，以及完整的 Rust 项目文件树。

🏗️ 五层架构

从用户输入到数据持久化，zeroclaw 将所有功能划分为五个水平层，每层仅依赖其正下方的层，层间通过明确定义的 Rust trait 边界解耦。

Layer 1 · 输入层

Input Layer

CLI TUI HTTP API WebSocket Voice iOS SDK Browser Extension Webhook 30+ 渠道

Layer 2 · 核心 Agent 层

Core Agent Layer

agent_loop sop_engine scheduler 上下文管理会话状态

Layer 3 · 执行层

Execution Layer

provider_router tool_registry (50+) wasm_runtime 20+ LLM 提供商

Layer 4 · 基础设施层

Infrastructure Layer

config_manager 硬件检测 plugin_system safety_engine 日志 / 追踪

Layer 5 · 存储层

Storage Layer

SQLite (会话) Vector DB (嵌入) 文件系统内存缓存

📦 十大核心模块

每个模块对应 src/ 下的一个子目录，职责单一，通过 Rust 异步 trait 相互调用。

agent_loop

Layer 2

核心对话循环。负责管理与 LLM 的完整交互周期：发送消息、接收流式响应、检测工具调用意图、收集工具结果后拼接上下文、判断循环终止条件。是整个 Agent 的心脏。

sop_engine

Layer 2

标准操作程序引擎。将复杂任务分解为有序步骤（Step），按依赖顺序执行，每步完成后进行验证。主要用于 Daemon 模式的自治任务规划与执行。

scheduler

Layer 2

并发任务调度器。维护优先级任务队列，通过 tokio::spawn 并发调度多个工具执行任务，支持超时控制和任务取消。

tool_registry

Layer 3

工具注册中心。管理 50+ 内置工具（file_read, file_write, shell_exec, web_fetch, grep 等）与 WASM 插件工具的统一注册、查找、调用入口。每个工具声明参数 schema 和所需权限。

provider_router

Layer 3

LLM 提供商路由器。抽象 20+ 提供商的差异化 API，提供统一的 complete() 接口。支持按配置、命令行参数或运行时动态选择提供商，自动处理认证和重试。

wasm_runtime

Layer 3

WebAssembly 插件运行时。基于 Wasmtime 实现 WASM 插件的加载、实例化和沙箱执行。插件通过 JSON-RPC 2.0 协议暴露工具，受限文件系统和网络访问。

safety_engine

Layer 4

安全引擎。对每个工具调用请求进行风险评分（low / medium / high），根据 approval_mode 决定是否自动执行或要求用户确认。并为实际执行提供 OS 级沙箱隔离。

gateway_server

Layer 1

HTTP / WebSocket 服务器。实现 JSON-RPC 2.0 API，管理多客户端并发会话，支持 SSE 流式响应。Gateway 模式的核心组件，基于 tokio + axum 构建。

daemon_manager

Layer 1

后台进程管理器。负责 daemon 的启动、停止、状态监控，集成 systemd / launchd 服务注册，以及 watchdog 崩溃自恢复。是 Daemon 运行模式的入口。

memory_store

Layer 5

持久化存储层。使用 SQLite 存储会话历史，使用向量数据库存储嵌入用于语义检索，支持跨会话的长期记忆查询和上下文注入。

🔒 安全子系统

zeroclaw 的安全系统分为两层：风险评分（决定是否需要用户确认）和 OS 沙箱隔离（限制实际执行权限）。两层独立工作，互为补充。

风险评分等级

LOW · 低风险

自动执行，无需确认

MEDIUM · 中风险

提示用户，可一键确认

HIGH · 高风险

必须显式输入 yes 确认

OS 级别沙箱技术

Linux

Landlock

内核级文件系统访问控制，限制可读写路径

Linux Container

Bubblewrap

用户态命名空间隔离，网络和进程沙箱

macOS

Seatbelt

Apple 沙箱配置文件，系统调用过滤

可配置权限	配置键	默认值	说明
文件系统访问路径	tools.allowed_paths	[]（需手动配置）	白名单目录列表，沙箱外路径拒绝访问
网络访问	tools.allow_network	true	是否允许 web_fetch 等工具发起网络请求
Shell 执行	tools.allow_shell	true	是否允许 shell_exec 工具
进程创建	tools.allow_spawn	confirm	创建子进程时的审批策略
OS 沙箱开关	safety.sandbox	true	全局沙箱开关，生产环境建议保持启用

🤖 20+ LLM 提供商支持

provider_router 统一抽象所有提供商 API，每个提供商实现相同的 Rust trait，对上层完全透明。

Anthropic

云端 · 推荐默认

OpenAI

云端

Google Gemini

云端

AWS Bedrock

云端企业

Google Vertex AI

云端企业

Mistral AI

云端

Cohere

云端

Together AI

云端

Fireworks AI

云端

Groq

云端 · 极速

DeepSeek

云端

Ollama

本地

LM Studio

本地

vLLM

本地

llama.cpp

本地

+ 更多

扩展中

📁 Rust 项目文件树

zeroclaw 采用 Cargo workspace 组织，主 crate 在 src/，核心子系统拆分为独立的 sub-crate。

zeroclaw/
├── Cargo.toml          # workspace 配置，声明所有 crate
├── Cargo.lock
├── src/                # 主 crate: zeroclaw
│   ├── main.rs         # 入口：解析 CLI 参数，分发到三种运行模式
│   ├── agent/          # Layer 2 · 核心 Agent 层
│   │   ├── loop.rs     # 对话循环主逻辑
│   │   ├── sop.rs      # SOP 任务分解与执行
│   │   └── scheduler.rs # 并发任务调度
│   ├── provider/       # Layer 3 · LLM 提供商适配
│   │   ├── anthropic.rs
│   │   ├── openai.rs
│   │   ├── gemini.rs
│   │   ├── bedrock.rs
│   │   ├── local.rs    # Ollama / LM Studio / vLLM 通用适配
│   │   └── router.rs   # 统一 trait + 提供商选择逻辑
│   ├── tools/          # Layer 3 · 工具实现
│   │   ├── file.rs     # file_read, file_write, file_list
│   │   ├── shell.rs    # shell_exec, process_spawn
│   │   ├── web.rs      # web_fetch, web_search
│   │   ├── grep.rs     # grep, find, regex_search
│   │   └── registry.rs # 工具注册与分发中心
│   ├── gateway/        # Layer 1 · HTTP/WS 服务器
│   │   ├── server.rs   # axum HTTP + WebSocket 服务器
│   │   ├── rpc.rs      # JSON-RPC 2.0 协议处理
│   │   └── session.rs  # 多客户端会话管理
│   ├── daemon/         # Layer 1 · 后台进程管理
│   │   ├── manager.rs  # 进程生命周期控制
│   │   └── watchdog.rs # 崩溃检测与自动恢复
│   ├── safety/         # Layer 4 · 安全子系统
│   │   ├── sandbox.rs  # Landlock / Bubblewrap / Seatbelt
│   │   └── risk.rs     # 工具调用风险评分
│   ├── wasm/           # Layer 3 · WASM 插件运行时
│   │   ├── runtime.rs  # Wasmtime 集成
│   │   └── plugin.rs   # 插件加载与生命周期管理
│   └── storage/        # Layer 5 · 持久化存储
│       ├── sqlite.rs   # 会话历史持久化
│       └── vector.rs   # 向量嵌入存储与检索
│
├── crates/             # Cargo workspace sub-crates
│   ├── zeroclaw-core/  # 核心 Agent 逻辑（可作为 lib 被集成）
│   │   ├── Cargo.toml
│   │   └── src/
│   ├── zeroclaw-tools/ # 所有工具实现（独立测试）
│   │   ├── Cargo.toml
│   │   └── src/
│   └── zeroclaw-wasm/  # WASM 运行时抽象
│       ├── Cargo.toml
│       └── src/
│
├── plugins/            # 示例 WASM 插件源码
│   ├── web-scraper/
│   └── image-analyzer/
│
├── config/             # 默认配置模板
│   └── config.toml.example
│
└── tests/              # 集成测试
    ├── integration_test.rs
    └── e2e_test.rs

📐 命名规范

zeroclaw 严格遵循 Rust 社区命名规范。所有文件名、模块名、变量名使用 snake_case，类型名（struct / enum / trait）使用 PascalCase，常量使用 SCREAMING_SNAKE_CASE。模块边界即 crate 边界：每个主要子系统抽取为独立 sub-crate，暴露最小必要的 pub 接口。

目标对象	命名规范	示例
文件名 / 模块名	snake_case	agent_loop.rs, provider_router.rs
Struct / Enum / Trait	PascalCase	AgentLoop, ProviderError
函数 / 方法	snake_case	run_loop(), dispatch_tool()
常量 / 静态变量	SCREAMING_SNAKE_CASE	MAX_TOKENS, DEFAULT_TIMEOUT_MS
Crate 名称	kebab-case	zeroclaw-core, zeroclaw-tools
feature flag	kebab-case	wasm-plugins, gateway-mode
错误类型	PascalCase + Error 后缀	ToolExecutionError, ProviderError
async trait	PascalCase	LlmProvider, ToolHandler