根目录文件
仓库根目录包含构建、配置和项目元数据文件：
📁zeroclaw/ # 仓库根目录
📁src/ # 主 crate 源码
📁crates/ # Workspace 子 crates
📁docs/ # 文档（mdBook）
📁web/ # Web Dashboard 前端
📁apps/tauri/ # 桌面应用（Tauri）
📁tests/ # 集成测试
📁scripts/ # 工具脚本
📁deploy-k8s/ # Kubernetes manifests
📄Cargo.toml # Workspace 根配置
📄Cargo.lock # 依赖锁定文件
📄Justfile # just 构建任务（类 Makefile）
📄flake.nix # Nix flake 打包定义
📄Dockerfile # 主 Docker 镜像
📄Dockerfile.minimal # 最小化镜像
📄install.sh # 一键安装脚本
📄README.md # 项目说明
📄NOTICE # 许可声明
src/ — 根级 .rs 文件
主 crate 根目录下的 10 个 Rust 文件定义顶层入口和工具：
📁src/
📄main.rs # CLI 入口：Clap 命令树（4326 行）
📄lib.rs # Library crate 公共 API 导出
📄cli_input.rs # CLI 交互输入处理（readline / TUI）
📄identity.rs # Agent 身份标识（AIEOS 规范）
📄i18n.rs # 国际化支持
📄migration.rs # 数据迁移（from OpenClaw）
📄multimodal.rs # 多模态输入处理（图片/音频）
📄schema_markdown.rs # 配置 schema → Markdown 生成
📄browse.rs # 浏览器集成工具
📄util.rs # 公共工具函数
src/ — 子模块目录（31 个）
每个子目录是一个 Rust 模块，大多为主 crate 对子 crate 的门面（re-export）：
📁src/
📁agent/ # → re-export zeroclaw_runtime::agent
📁approval/ # 人工审批管理器
📁auth/ # Provider 认证 Profile
📁bin/ # 附加二进制入口
📁channels/ # → re-export zeroclaw_channels
📁commands/ # CLI 子命令实现（agent, daemon, config…）
📁config/ # → re-export zeroclaw_config
📁cost/ # Token 用量与费用追踪
📁cron/ # Cron 调度器
📁daemon/ # Daemon 模式启动逻辑
📁doctor/ # 健康诊断命令
📁gateway/ # → re-export zeroclaw_gateway
📁hardware/ # → re-export zeroclaw_hardware
📁health/ # 健康检查端点
📁heartbeat/ # 服务心跳机制
📁hooks/ # 工具调用生命周期钩子
📁integrations/ # 50+ 第三方服务连接器
📁memory/ # → re-export zeroclaw_memory
📁nodes/ # 分布式节点管理
📁observability/ # 指标、追踪、告警
📁peripherals/ # 硬件外设管理
📁platform/ # OS 适配（Linux/macOS/Windows）
📁plugins/ # → re-export zeroclaw_plugins
📁providers/ # → re-export zeroclaw_providers
📁rag/ # 检索增强生成管道
📁routines/ # 自动化例程定义
📁security/ # 安全策略、沙箱、权限
📁service/ # 系统服务（systemd/launchd）集成
📁skillforge/ # 技能构建器与编译器
📁skills/ # 用户自定义技能（DSL）
📁sop/ # 标准操作流程引擎
📁tools/ # → re-export zeroclaw_tools
📁trust/ # 信任链与加密凭证
📁tunnel/ # 安全隧道（内网穿透）
📁verifiable_intent/ # 意图可验证链路
crates/ — Workspace 子 Crate 结构
zeroclaw-runtime 是最核心的 crate，展开其 agent 子模块结构：
📁crates/
📁zeroclaw-runtime/src/
📁agent/ # Agent 核心（18 子模块）
📄mod.rs # 模块聚合与 re-export
📄agent.rs # Agent struct + AgentBuilder
📄loop_.rs # 主 Agent Loop（run/process_message）
📄dispatcher.rs # Tool Call 分发器
📄classifier.rs # 意图分类器
📄context_analyzer.rs # 上下文分析
📄context_compressor.rs# 历史压缩
📄prompt.rs # Prompt 构建
📄system_prompt.rs # System Prompt 组装
📄thinking.rs # Extended Thinking 支持
📄history.rs # 对话历史管理
📄history_pruner.rs # 历史裁剪策略
📄loop_detector.rs # 死循环检测
📄memory_loader.rs # 记忆检索与注入
📄tool_execution.rs # 并行/串行工具执行
📄tool_receipts.rs # 加密工具凭证
📄personality.rs # 人格定义
📄personality_templates.rs# 内置人格模板
📄cost.rs # Token 计费
📄eval.rs # 评估工具
📄lib.rs # Runtime crate 入口
📁zeroclaw-channels/src/
📁discord/ telegram/ matrix/ email/ # 各渠道实现
📁zeroclaw-providers/src/
📁anthropic/ openai/ ollama/ compat/
📁zeroclaw-tools/src/
📁shell/ browser/ http/ files/ schedule/
📁zeroclaw-memory/src/
📁store/ vector/ search/ session/
📁zeroclaw-gateway/src/
📁server/ routes/ ws/ dashboard/
📄zeroclaw-config/ zeroclaw-api/ zeroclaw-log/ # 各自含 src/lib.rs
其他目录
📁docs/ # mdBook 文档源
📁src/ # Markdown 页面
📄book.toml # mdBook 配置
📁web/ # Web Dashboard
📁src/ # React / 前端源码
📄package.json
📁apps/tauri/ # 桌面应用
📁src-tauri/ # Rust Tauri 后端
📁src/ # 前端 UI
📁deploy-k8s/
📄deployment.yaml
📄service.yaml
📄configmap.yaml
📁tests/ # 集成测试
📄*.rs # 各功能集成测试
📁scripts/
📄release.sh # 发布脚本
📄bench.sh # 基准测试
📄e2e.sh # 端到端测试
文件命名约定
ZeroClaw 遵循 Rust 社区惯例并有项目特定规则：
| 模式 | 示例 | 用途 |
|---|
| mod.rs | agent/mod.rs | 模块入口，聚合子模块并 re-export |
| lib.rs | zeroclaw-runtime/src/lib.rs | Crate 公共 API 入口 |
| main.rs | src/main.rs | Binary crate 入口，含完整 Clap 命令树 |
| {noun}.rs | agent.rs, config.rs | 核心数据结构/Trait 定义 |
| {noun}_{role}.rs | memory_loader.rs, loop_detector.rs | 特定职责实现，避免歧义 |
| loop_.rs | agent/loop_.rs | 尾部 _ 避免与 Rust 关键字 loop 冲突 |
| {feature}_sys | aardvark-sys | 底层 FFI 绑定（sys 后缀惯例） |
| zeroclaw-{domain} | zeroclaw-runtime, zeroclaw-memory | Workspace crate 命名：前缀 + 领域名 |
| {verb}_{noun}.rs | build_context, filter_tool_specs | 函数级文件（通常内联在父模块） |
| .env.{env} | 无（使用 TOML） | ZeroClaw 用 TOML 不用 .env 文件 |
src/ 模块模式
- 大多数 src/ 子目录只有 mod.rs，内容是
pub use zeroclaw_xxx::*;
- 实际逻辑在对应 crate 里，src/ 是门面（facade）
- commands/ 是例外：含具体 CLI 实现逻辑
- 模块名用 snake_case，与 Rust 规范一致
Crate 命名规则
- 核心域用
zeroclaw-{domain} 前缀
- 底层绑定用
-sys 后缀
- 工具套件不加前缀（robot-kit）
- Crate 名用 kebab-case，Rust 模块名自动转 snake_case