Box 的 crate 地图

定义

Box 的实现位于仓库的 src/ workspace（版本 3.2.7）。根目录只做编排：安装脚本、文档、多语言 SDK 包与部署样例。Rust 检查与库测试都应在 src/ 下运行。crate 之间的依赖是单向的：core 不依赖 runtime；cli / sdk / cri 通过 ExecutionManager 使用 runtime；shim 与 guest-init 是被拉起的独立二进制。

问题背景

若把镜像、网络、CLI 解析和 libkrun 调用写在同一 crate，任何一层的测试都会拖入 hypervisor。拆分 crate 的目的是：类型与错误可以在无 I/O 条件下测试；执行后端可以替换；CLI 与 CRI 可以共享同一状态机而不共享命令行解析。

机制说明

workspace 成员

src/Cargo.toml 声明的成员如下。行数为 2026-09-18 对 *.rs 的统计，只用于建立体量直觉。

crate	约行数	职责
`core`	2.0 万	协议类型、`ExecutionIsolation`、`BoxConfig`、错误、事件、日志、Compose 模型、`ExecutionManager` trait
`runtime`	16.8 万	`LocalExecutionManager`、VM / OCI 后端、路由器、镜像、rootfs、卷、网络、快照、池、TEE、扩缩
`netproxy`	0.3 万	基于 passt 的桥接与端口发布
`shim`	0.5 万	`a3s-box-shim`：libkrun 进入客户机的独立进程
`guest/init`	1.7 万	MicroVM 内 PID 1：挂载、网络、exec / PTY / 证明服务、回收僵尸进程
`cli`	5.2 万	`a3s-box` 命令行
`sdk`	1.5 万	原生 Rust SDK 与 `sdk-bridge`
`cri`	2.0 万	CRI v1 gRPC 服务器
`deps/libkrun-sys`	—	libkrun FFI
`third_party/mkext4`	—	发布所有的字节保真 ext4 写入器
`third_party/h2`	—	为 Unix 套接字 gRPC 修补的 HTTP/2 库

runtime 内部再分层

runtime 体量最大，阅读时应先抓住：

local_execution/：持久生命周期，是产品心脏；
oci/：镜像分发与构建；
rootfs/、volume/、network/、snapshot/、pool/、tee/、scale/：各自独立的产品资源；
vm/、vmm/、sandbox/：两条隔离路径的具体适配。

不要从 oci_backend_tests.rs 一类文件开始。先读 local_execution/mod.rs、backend.rs、router.rs、box_record.rs。

仓库根上的非 crate 目录

路径	内容
`sdk/python`、`sdk/typescript`、`sdk/go`	通过 machine bridge 访问的语言包
`containerd-shim/`	containerd runtime-v2 集成
`docs/`	设计、安装、证据与符合性
`deploy/`	Helm 与示例
`scripts/`	主机准备与冒烟

在 Box 中的位置

本词条描述的就是仓库本身。README 的「仓库地图」一节与上表对应。开发命令示例：

cd src
cargo test -p a3s-box-core
cargo test -p a3s-box-runtime --lib
cargo test -p a3s-box-cli --test command_coverage
cargo test -p a3s-box-sdk

基于主机的 MicroVM、Sandbox、网络、构建与 CRI 测试需要单独准备的机器，不能用默认 cargo test 代替。