ZeroClaw 目录与关键文件详解

1. 顶层目录总览以下文件数为当前仓库快照下的递归统计结果。目录文件数作用.cargo/2Cargo 构建与审计相关配置.claude/26面向 Claude/Codex 类协作代理的技能与辅助资料.gemini/1Gemini 相关风格规范文件.githooks/2Git 钩子脚本.github/31CI、Issue/PR 模板、Code Owners、自动化配置.vscode/4VS Code 工作区建议配置apps/37桌面应用目前主要是tauri伴侣应用benches/1Criterion 基准测试crates/23工作区子 crate如robot-kit、aardvark-sys、zeroclaw-macrosdev/14本地开发、CI、Docker、本地测试辅助脚本dist/3分发清单如 Scoop/AURdocs/253文档中心、多语言文档、维护者文档、参考文档firmware/36微控制器/开发板固件与协议fuzz/6模糊测试目标marketplace/8部署市场模板如 Dokploy、Coolify、Easypanelscripts/16发布、浏览器、CI、部署脚本src/386Rust 主工程源码tests/57组件、集成、系统、live、手工测试tool_descriptions/31工具描述的多语言 TOML 文本资源web/68React Vite Web 控制台2. 顶层关键文件文件作用AGENTS.md仓库级 AI 代理协作说明定义命令、风险级别、扩展点、开发约束README.md产品入口文档、功能说明、快速启动Cargo.toml工作区定义、主包定义、feature、构建 profileCargo.lock精确依赖锁定build.rs自动构建/拷贝前端资源保证 Gateway 能嵌入 Web 资产install.sh跨平台一键安装/引导脚本setup.batWindows 启动与安装脚本Dockerfile容器化构建与运行镜像定义docker-compose.yml容器编排入口Justfile常用开发命令快捷入口SECURITY.md安全策略与默认安全模型说明CONTRIBUTING.md贡献指南.env.example环境变量示例deny.toml依赖许可/来源约束clippy.toml/rustfmt.tomlRust 代码质量与格式配置3.src/根文件文件作用src/main.rsCLI 主入口解析命令并路由到各子系统src/lib.rs统一导出模块与共享命令枚举供库/二进制共同使用src/cli_input.rsCLI 输入辅助逻辑src/i18n.rs语言与本地化支持src/identity.rsAgent 身份配置、人格与描述相关逻辑src/migration.rs从 OpenClaw 等外部运行时迁移数据src/multimodal.rs图片/多模态消息预处理与限制控制src/util.rs通用工具函数4.src/子目录逐项说明目录文件数作用agent/18Agent 核心编排层负责 prompt、上下文、tool loop、历史裁剪、分类、思考流approval/1对中高风险动作做审批门控auth/6OAuth、认证资料、Profile、Token 刷新channels/45消息渠道实现与共享运行逻辑commands/3update、self_test等辅助命令config/4配置 schema、序列化、prop 反射、workspace profile 管理cost/3Token/API 使用成本跟踪与预算控制cron/5调度任务模型、存储与调度器daemon/1全量后台运行编排器监督 gateway/channels/scheduler 等doctor/1诊断、模型探测、trace 查看gateway/14HTTP API、SSE、WebSocket、Webhook、静态前端服务hands/2“手”这一类自主子任务定义与运行上下文存储hardware/20硬件发现、板卡清单、数据手册、协议与工具注册health/1进程内组件健康状态注册表heartbeat/3心跳任务、Dead-man switch、状态文件hooks/6生命周期 hook 与内置 hookintegrations/2集成目录与状态展示注册表memory/25记忆后端、召回、衰减、快照、向量检索、缓存nodes/2节点传输层供 gateway 节点发现/连接使用observability/10日志、Prometheus、OTel、Verbose、运行 traceonboard/2初始配置向导和模型管理入口peripherals/10外设抽象、串口连接、烧录与板卡集成plugins/6WASM 插件系统providers/19LLM Provider 抽象、工厂、回退、路由rag/1针对硬件数据手册的 RAG 检索层routines/3轻量事件驱动自动化规则引擎runtime/5Native/Docker 运行时适配security/23策略、沙箱、Pairing、OTP、审计、应急停止、密钥管理service/1系统服务安装与管理skillforge/4技能发现、评估、集成流水线skills/6技能加载、审计、改进、创建sop/7标准操作流程引擎tools/98所有 Agent 工具实现与工具工厂trust/3信任评分与类型定义tui/4终端 UI onboardingtunnel/8Cloudflare/Tailscale/ngrok/OpenVPN/自定义隧道verifiable_intent/6Verifiable Intent 凭证链与约束验证5.src/中最关键的几个目录src/agent/这是“脑子”所在。关键内容agent.rsAgent与AgentBuilderloop_.rs多轮工具调用主循环prompt.rs系统提示构造memory_loader.rs记忆上下文装载dispatcher.rs原生 tool call / XML 风格 tool call 分发classifier.rs按 query hint 路由模型src/providers/这是“模型后端适配层”。关键内容traits.rs统一 Provider 接口mod.rsProvider 工厂和别名解析reliable.rs重试、回退、认证错误判定router.rs按 hint 或路由规则切换模型src/channels/这是“消息输入输出总线”。关键内容traits.rs统一 Channel 接口mod.rs渠道启动、会话管理、共享处理逻辑telegram.rsTelegram 实现其他单文件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.rsOTP 验证audit.rs安全审计detect.rs、docker.rs、bubblewrap.rs、firejail.rs、landlock.rs沙箱后端src/gateway/这是“控制平面”。关键内容mod.rsAxum 路由与 AppState 装配api.rsREST APIapi_pairing.rs增强配对与设备管理ws.rsWebSocket 聊天sse.rs事件流static_files.rs嵌入式前端资源服务6. 其他重要顶层子结构6.1web/子目录/文件作用web/src/pages/页面级功能如 Dashboard、AgentChat、Tools、Cron、Memory、Config、Cost、Logs、Doctor、Pairing、Canvasweb/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.2apps/tauri/子目录/文件作用src/lib.rsTauri 应用装配、托盘、自动配对、健康轮询src/commands/Tauri 与前端之间的 invoke bridgesrc/tray/系统托盘菜单与事件src/gateway_client.rs连接 Gateway 的轻量客户端tauri.conf.jsonTauri 配置前端地址直接指向 Gateway 的/_app/capabilities/Tauri 权限能力定义icons/桌面端图标资源结论桌面端是 Gateway 的伴侣壳不是独立业务后端。6.3crates/子 crate作用crates/robot-kit/面向机器人/树莓派场景的独立工具包crates/aardvark-sys/Total Phase Aardvark USB 适配器的底层绑定 stubcrates/zeroclaw-macros/Configurable等过程宏给配置系统做字段反射与 secret 处理6.4firmware/子目录作用arduino/Arduino 草图esp32/ESP32 固件esp32-ui/带 UI 的 ESP32 固件样例nucleo/STM32 Nucleo 固件pico/RP2040/Pico 固件uno-q-bridge/Uno Q 桥接工程含 Arduino 草图和 Python 端zeroclaw-fw-protocol/固件侧协议 crate6.5tests/子目录文件数作用component/12单组件/单边界测试integration/14模块联动测试system/2更完整的系统流测试live/5需要真实外部依赖的 live 测试manual/7手工/脚本型测试support/7测试辅助基建fixtures/6测试样本数据6.6docs/子目录文件数作用architecture/1架构 ADRassets/10文档图片与架构图contributing/18贡献与 CI 规则getting-started/1入门主题hardware/8硬件相关说明i18n/169多语言文档maintainers/8维护者视角的仓库地图、重构候选等ops/6运行、排障、资源与部署reference/10CLI、API、配置参考security/7安全策略与路线图setup-guides/8安装/引导指南superpowers/2特定能力设计文档7. 当前最关键的文件以下文件对理解项目最重要。文件当前行数作用为什么重要src/main.rs2809CLI 主入口所有命令的实际路由都在这里src/lib.rs547模块导出与共享命令枚举二进制与库层的连接点src/config/schema.rs14917全局配置 schema、默认值、加载/保存、校验是整个系统的配置中枢src/agent/agent.rs1883Agent结构与 BuilderAgent 实例装配中心src/agent/loop_.rs8702Tool loop 和主推理流程决定 Agent 的真实运行行为src/providers/mod.rs3442Provider 工厂与别名体系决定模型接入广度和复杂性src/channels/mod.rs11136渠道启动与共享运行逻辑消息系统的总装配层src/tools/mod.rs1308工具工厂和全量工具注册Agent 行为上限由它定义src/security/policy.rs3092安全策略与执行限制真正的安全边界核心src/gateway/mod.rs3316HTTP 路由与 Gateway 组装Web/API/Webhook 的总入口src/onboard/wizard.rs7220引导安装与配置流程首次使用体验关键文件src/daemon/mod.rs1097后台运行监督器生产运行模式核心build.rs163Web 构建与资源注入决定前端是否被正确嵌入二进制web/src/App.tsx235前端路由总入口决定控制台信息架构apps/tauri/src/lib.rs120桌面伴侣主装配决定桌面端与 Gateway 的耦合方式8. 从目录设计看出的几个结论8.1 这是一个“平台型仓库”不是单一业务目录而是RuntimeWebDesktopFirmwareDocsMarketplaceTest/Fuzz/Bench全部放在一个 monorepo/workspace 内。8.2src/已经明显进入中后期复杂度单看src/就有386个文件而且多个关键文件行数已经非常高后续维护一定要重视拆分。8.3 Web 和桌面端都依赖 Gateway这是一个很重要的设计点。它意味着后端控制面是统一的Web/桌面不是两套不同产品Gateway 是控制中枢8.4 文档体系非常重docs/有253个文件i18n/占了其中绝大多数。说明项目已经进入“对外传播 多语言运营 维护治理”阶段。