这是一份 Capsem 开发环境搭建文档，用于新成员入职、机器初始化，或排查环境与容器运行时问题。
用途与平台前提：Linux 需 Debian/Ubuntu 或 dnf 系发行版、x86_64/arm64，并在初始装包时有 sudo/root，同时需要 /dev/kvm 与 /dev/vhost-vsock 以支持虚拟机执行与 guest 通信。macOS 需 13+（Ventura 起）与 Apple Silicon，Intel Mac 不支持虚拟机功能。构建内核与 rootfs 需要 Docker（macOS 用 Colima）；macOS 的干净安装测试还需 Tart 与 sshpass。
主要能力：文档给出必需工具清单（Rust stable、just、pnpm、Node.js 24+、uv、Docker/BuildKit、Linux 的 Bubblewrap、cpio、Tart+sshpass）及安装方式；说明 Rust 交叉目标与 Cargo 工具（cargo-nextest、cargo-llvm-cov、cargo-audit、cargo-tauri、cargo-sbom、b3sum）由 just doctor fix 自动安装。容器运行时方面，macOS 的 Docker 运行在 Colima VM 中，建议至少 12GB、推荐 16GB 内存与 8 CPU，并提供 colima start --vm-type vz --vz-rosetta --memory 16 --cpu 8 等命令与半启动状态恢复步骤；Linux 上 Docker 原生运行，由 bootstrap 安装原生构建库、Docker/Buildx、Bubblewrap，注册 QEMU binfmt、启用守护进程并加载 KVM 与 vhost-vsock 设备。
使用方式：克隆仓库后运行 ./bootstrap.sh（交互式，或 --yes 非交互），其分三阶段安装硬前置、工具链与依赖，并执行 doctor --fix；随后 just exec "echo hello from capsem" 验证虚拟机启动。逐步流程为 just doctor、just doctor fix、just _build-assets、just exec "echo hi"。日常命令包括 just shell、just exec、just fast-test、just focus-test functional、just test、just dev ui 与 just dev。
限制与注意事项：不要创建 ~/.capsem/user.toml；凭据由 credential broker 按 profile/corp 策略处理，不应新增 setup 期 admin 或 guest 配置根。内核版本由 build contract 固定，不要自行添加并行内核设置。文档还给出签名（com.apple.security.virtualization 权利）、退出码 137 内存不足、容器 VM 时钟漂移、凭据助手缺失、缓存回收（应使用 just cache prune 而非 Broad docker prune）、VM 启动挂起等排查指引，以及 doctor 三脚本与修复注册表结构说明。