用途：这是 Cloudflare Sandbox SDK 的架构文档，帮助开发者首次浏览代码库、新增客户端方法、新增容器处理器/服务，或理解请求如何流转。
三层架构：@cloudflare/sandbox（packages/sandbox/，发布到 npm）提供 Sandbox 类（管理容器生命周期的 Durable Object）、按能力划分的模块化 HTTP 客户端（CommandClient、FileClient、ProcessClient 等）、CodeInterpreter 高层 API 及 proxyToSandbox() 预览 URL 路由处理器；@repo/shared（packages/shared/）为内部共享类型、错误类与日志，不发布；@repo/sandbox-container（packages/sandbox-container/）为容器运行时，基于 Bun 的 HTTP 服务器，含依赖注入容器与路由处理器，不发布（打包进 Docker 镜像）。
请求流转：主控制路径为 Worker → Sandbox DO → ContainerControlClient → 经 /rpc WebSocket 的 capnweb → SandboxControlAPI → 容器服务 → Shell/文件系统；基于路由的兼容路径为 Worker → Sandbox DO → SandboxClient/transport → 端口 3000 的容器 HTTP API → Router/handlers → 容器服务。错误沿相同路径回传，使用 packages/shared/src/errors/ 中按 ErrorCode 枚举的自定义错误类。
新增容器控制操作：在 services/ 添加业务逻辑，在 control-plane/ 添加方法，在 packages/sandbox/src/container-control/ 镜像调用，两侧加单元测试，涉及真实 shell/文件系统时加 E2E 测试；仅在维护 HTTP/WebSocket 兼容性时才添加 handlers/ 路由与基于路由的 SDK 客户端。
Monorepo 使用 npm workspaces + Turbo，含 packages/sandbox、packages/shared、packages/sandbox-container、examples/、tooling/。跨切面模式包括 Sessions（隔离执行上下文）、Ports（经预览 URL 暴露内部服务，生产需通配符 DNS 自定义域名，.workers.dev 不支持）、容器隔离由 Cloudflare 平台层处理。容器基础镜像为 Ubuntu 22.04，含 Python 3.11、Node.js 20 LTS、Bun 1.x 及常用工具。