当前位置：首页 > news >正文

ZeroClaw 目录与关键文件详解

news 2026/5/31 2:02:28

1. 顶层目录总览

以下文件数为当前仓库快照下的递归统计结果。

目录	文件数	作用
`.cargo/`	2	Cargo 构建与审计相关配置
`.claude/`	26	面向 Claude/Codex 类协作代理的技能与辅助资料
`.gemini/`	1	Gemini 相关风格规范文件
`.githooks/`	2	Git 钩子脚本
`.github/`	31	CI、Issue/PR 模板、Code Owners、自动化配置
`.vscode/`	4	VS Code 工作区建议配置
`apps/`	37	桌面应用，目前主要是`tauri`伴侣应用
`benches/`	1	Criterion 基准测试
`crates/`	23	工作区子 crate，如`robot-kit`、`aardvark-sys`、`zeroclaw-macros`
`dev/`	14	本地开发、CI、Docker、本地测试辅助脚本
`dist/`	3	分发清单，如 Scoop/AUR
`docs/`	253	文档中心、多语言文档、维护者文档、参考文档
`firmware/`	36	微控制器/开发板固件与协议
`fuzz/`	6	模糊测试目标
`marketplace/`	8	部署市场模板，如 Dokploy、Coolify、Easypanel
`scripts/`	16	发布、浏览器、CI、部署脚本
`src/`	386	Rust 主工程源码
`tests/`	57	组件、集成、系统、live、手工测试
`tool_descriptions/`	31	工具描述的多语言 TOML 文本资源
`web/`	68	React + Vite Web 控制台

2. 顶层关键文件

文件	作用
`AGENTS.md`	仓库级 AI 代理协作说明，定义命令、风险级别、扩展点、开发约束
`README.md`	产品入口文档、功能说明、快速启动
`Cargo.toml`	工作区定义、主包定义、feature、构建 profile
`Cargo.lock`	精确依赖锁定
`build.rs`	自动构建/拷贝前端资源，保证 Gateway 能嵌入 Web 资产
`install.sh`	跨平台一键安装/引导脚本
`setup.bat`	Windows 启动与安装脚本
`Dockerfile`	容器化构建与运行镜像定义
`docker-compose.yml`	容器编排入口
`Justfile`	常用开发命令快捷入口
`SECURITY.md`	安全策略与默认安全模型说明
`CONTRIBUTING.md`	贡献指南
`.env.example`	环境变量示例
`deny.toml`	依赖许可/来源约束
`clippy.toml`/`rustfmt.toml`	Rust 代码质量与格式配置

3.`src/`根文件

文件	作用
`src/main.rs`	CLI 主入口，解析命令并路由到各子系统
`src/lib.rs`	统一导出模块与共享命令枚举，供库/二进制共同使用
`src/cli_input.rs`	CLI 输入辅助逻辑
`src/i18n.rs`	语言与本地化支持
`src/identity.rs`	Agent 身份配置、人格与描述相关逻辑
`src/migration.rs`	从 OpenClaw 等外部运行时迁移数据
`src/multimodal.rs`	图片/多模态消息预处理与限制控制
`src/util.rs`	通用工具函数

4.`src/`子目录逐项说明

目录	文件数	作用
`agent/`	18	Agent 核心编排层，负责 prompt、上下文、tool loop、历史裁剪、分类、思考流
`approval/`	1	对中高风险动作做审批门控
`auth/`	6	OAuth、认证资料、Profile、Token 刷新
`channels/`	45	消息渠道实现与共享运行逻辑
`commands/`	3	`update`、`self_test`等辅助命令
`config/`	4	配置 schema、序列化、prop 反射、workspace profile 管理
`cost/`	3	Token/API 使用成本跟踪与预算控制
`cron/`	5	调度任务模型、存储与调度器
`daemon/`	1	全量后台运行编排器，监督 gateway/channels/scheduler 等
`doctor/`	1	诊断、模型探测、trace 查看
`gateway/`	14	HTTP API、SSE、WebSocket、Webhook、静态前端服务
`hands/`	2	“手”这一类自主子任务定义与运行上下文存储
`hardware/`	20	硬件发现、板卡清单、数据手册、协议与工具注册
`health/`	1	进程内组件健康状态注册表
`heartbeat/`	3	心跳任务、Dead-man switch、状态文件
`hooks/`	6	生命周期 hook 与内置 hook
`integrations/`	2	集成目录与状态展示注册表
`memory/`	25	记忆后端、召回、衰减、快照、向量检索、缓存
`nodes/`	2	节点传输层，供 gateway 节点发现/连接使用
`observability/`	10	日志、Prometheus、OTel、Verbose、运行 trace
`onboard/`	2	初始配置向导和模型管理入口
`peripherals/`	10	外设抽象、串口连接、烧录与板卡集成
`plugins/`	6	WASM 插件系统
`providers/`	19	LLM Provider 抽象、工厂、回退、路由
`rag/`	1	针对硬件数据手册的 RAG 检索层
`routines/`	3	轻量事件驱动自动化规则引擎
`runtime/`	5	Native/Docker 运行时适配
`security/`	23	策略、沙箱、Pairing、OTP、审计、应急停止、密钥管理
`service/`	1	系统服务安装与管理
`skillforge/`	4	技能发现、评估、集成流水线
`skills/`	6	技能加载、审计、改进、创建
`sop/`	7	标准操作流程引擎
`tools/`	98	所有 Agent 工具实现与工具工厂
`trust/`	3	信任评分与类型定义
`tui/`	4	终端 UI onboarding
`tunnel/`	8	Cloudflare/Tailscale/ngrok/OpenVPN/自定义隧道
`verifiable_intent/`	6	Verifiable Intent 凭证链与约束验证

5.`src/`中最关键的几个目录

`src/agent/`

这是“脑子”所在。

关键内容：

agent.rs：Agent与AgentBuilder
loop_.rs：多轮工具调用主循环
prompt.rs：系统提示构造
memory_loader.rs：记忆上下文装载
dispatcher.rs：原生 tool call / XML 风格 tool call 分发
classifier.rs：按 query hint 路由模型

`src/providers/`

这是“模型后端适配层”。

关键内容：

traits.rs：统一 Provider 接口
mod.rs：Provider 工厂和别名解析
reliable.rs：重试、回退、认证错误判定
router.rs：按 hint 或路由规则切换模型

`src/channels/`

这是“消息输入输出总线”。

关键内容：

traits.rs：统一 Channel 接口
mod.rs：渠道启动、会话管理、共享处理逻辑
telegram.rs：Telegram 实现
其他单文件：Discord、Slack、Signal、Email、Matrix 等各自实现

`src/tools/`

这是“能力库”。

关键内容：

traits.rs：统一 Tool 接口
mod.rs：工具工厂与装配逻辑
细分工具文件：shell、file、memory、browser、cron、MCP、SOP、project intel 等

`src/security/`

这是“安全边界层”。

关键内容：

policy.rs：权限/风险/路径/命令限制核心逻辑
pairing.rs：设备配对与 bearer token 认证
otp.rs：OTP 验证
audit.rs：安全审计
detect.rs、docker.rs、bubblewrap.rs、firejail.rs、landlock.rs：沙箱后端

`src/gateway/`

这是“控制平面”。

关键内容：

mod.rs：Axum 路由与 AppState 装配
api.rs：REST API
api_pairing.rs：增强配对与设备管理
ws.rs：WebSocket 聊天
sse.rs：事件流
static_files.rs：嵌入式前端资源服务

6. 其他重要顶层子结构

6.1`web/`

子目录/文件	作用
`web/src/pages/`	页面级功能，如 Dashboard、AgentChat、Tools、Cron、Memory、Config、Cost、Logs、Doctor、Pairing、Canvas
`web/src/components/`	通用组件和布局组件
`web/src/hooks/`	`useAuth`、`useApi`、`useDraft`、`useSSE`、`useWebSocket`等
`web/src/lib/`	API 客户端、鉴权、SSE/WS 封装、i18n、基础路径工具
`web/src/contexts/`	主题与颜色主题上下文
`web/public/`	静态资源
`web/package.json`	前端依赖与构建脚本
`web/src/App.tsx`	前端路由总入口

结论：生产态 Web UI 不是单独服务，而是被 Rust Gateway 嵌入和托管。

6.2`apps/tauri/`

子目录/文件	作用
`src/lib.rs`	Tauri 应用装配、托盘、自动配对、健康轮询
`src/commands/`	Tauri 与前端之间的 invoke bridge
`src/tray/`	系统托盘菜单与事件
`src/gateway_client.rs`	连接 Gateway 的轻量客户端
`tauri.conf.json`	Tauri 配置，前端地址直接指向 Gateway 的`/_app/`
`capabilities/`	Tauri 权限能力定义
`icons/`	桌面端图标资源

结论：桌面端是 Gateway 的伴侣壳，不是独立业务后端。

6.3`crates/`

子 crate	作用
`crates/robot-kit/`	面向机器人/树莓派场景的独立工具包
`crates/aardvark-sys/`	Total Phase Aardvark USB 适配器的底层绑定 stub
`crates/zeroclaw-macros/`	`Configurable`等过程宏，给配置系统做字段反射与 secret 处理

6.4`firmware/`

子目录	作用
`arduino/`	Arduino 草图
`esp32/`	ESP32 固件
`esp32-ui/`	带 UI 的 ESP32 固件样例
`nucleo/`	STM32 Nucleo 固件
`pico/`	RP2040/Pico 固件
`uno-q-bridge/`	Uno Q 桥接工程，含 Arduino 草图和 Python 端
`zeroclaw-fw-protocol/`	固件侧协议 crate

6.5`tests/`

子目录	文件数	作用
`component/`	12	单组件/单边界测试
`integration/`	14	模块联动测试
`system/`	2	更完整的系统流测试
`live/`	5	需要真实外部依赖的 live 测试
`manual/`	7	手工/脚本型测试
`support/`	7	测试辅助基建
`fixtures/`	6	测试样本数据

6.6`docs/`

子目录	文件数	作用
`architecture/`	1	架构 ADR
`assets/`	10	文档图片与架构图
`contributing/`	18	贡献与 CI 规则
`getting-started/`	1	入门主题
`hardware/`	8	硬件相关说明
`i18n/`	169	多语言文档
`maintainers/`	8	维护者视角的仓库地图、重构候选等
`ops/`	6	运行、排障、资源与部署
`reference/`	10	CLI、API、配置参考
`security/`	7	安全策略与路线图
`setup-guides/`	8	安装/引导指南
`superpowers/`	2	特定能力设计文档

7. 当前最关键的文件

以下文件对理解项目最重要。

文件	当前行数	作用	为什么重要
`src/main.rs`	2809	CLI 主入口	所有命令的实际路由都在这里
`src/lib.rs`	547	模块导出与共享命令枚举	二进制与库层的连接点
`src/config/schema.rs`	14917	全局配置 schema、默认值、加载/保存、校验	是整个系统的配置中枢
`src/agent/agent.rs`	1883	`Agent`结构与 Builder	Agent 实例装配中心
`src/agent/loop_.rs`	8702	Tool loop 和主推理流程	决定 Agent 的真实运行行为
`src/providers/mod.rs`	3442	Provider 工厂与别名体系	决定模型接入广度和复杂性
`src/channels/mod.rs`	11136	渠道启动与共享运行逻辑	消息系统的总装配层
`src/tools/mod.rs`	1308	工具工厂和全量工具注册	Agent 行为上限由它定义
`src/security/policy.rs`	3092	安全策略与执行限制	真正的安全边界核心
`src/gateway/mod.rs`	3316	HTTP 路由与 Gateway 组装	Web/API/Webhook 的总入口
`src/onboard/wizard.rs`	7220	引导安装与配置流程	首次使用体验关键文件
`src/daemon/mod.rs`	1097	后台运行监督器	生产运行模式核心
`build.rs`	163	Web 构建与资源注入	决定前端是否被正确嵌入二进制
`web/src/App.tsx`	235	前端路由总入口	决定控制台信息架构
`apps/tauri/src/lib.rs`	120	桌面伴侣主装配	决定桌面端与 Gateway 的耦合方式