Sandbox SDK — @next（1.0 预览版）：在 Cloudflare Containers 上提供隔离的 Linux 环境，并由 Workers 驱动。
使用原则：优先参考预览文档和已安装的 @next 类型，而不是凭记忆。API 会变化；本技能是门禁、契约和检索地图，不是完整手册。新项目建议采用此线。仍使用默认包的应用应使用 sandbox-stable。仅在用户要求时才移植，并使用 sandbox-migrate-to-next。
一、门禁：确认包线 编写代码前先检查应用。npm 依赖须为 @cloudflare/sandbox@next（或其他 preview 标签），容器镜像须为同一条线（例如 cloudflare/sandbox:next、next-python）。若发现默认的 @cloudflare/sandbox（无 @next），应停止并加载 sandbox-stable，不要套用本技能的 API。若用户要把稳定版移植到 @next，应停止并加载 sandbox-migrate-to-next。若仅为自部署 bridge，bridge 尚未处于 1.0 预览线，应让 bridge 保持稳定包与镜像。切勿混用 @next 的 Worker 包与稳定容器镜像（或反之）。
二、契约：不可协商事项 sandbox.exec(argv) 接收参数列表，在进程启动时即 resolve，返回句柄而非已完成的命令结果。用句柄方法收集结果：output()、logs()、waitForExit()、waitForPort()、waitForLog()、kill(signal?)。没有隐式 shell；shell 语法需显式指定 shell，例如 ["/bin/bash", "-lc", script]。每次启动相互独立，一次 exec 中的 cd / export 不会对下一次可见；应每次启动传入 cwd 和 env，或写成单个 shell 脚本。进程句柄没有 stdin；交互式使用需用 terminals（createTerminal + connect）。本地等待超时或 AbortSignal 只取消等待，不会杀掉进程；应使用 kill 或 exec 的远程超时。getProcess / listProcesses / getTerminal / listTerminals 不会启动容器，当没有容器运行时返回 null / []。进程与终端 ID 属于当前容器，而不永久属于某个 sandbox ID；对于必须经受容器替换的工作，应存储完整作业（argv、cwd、env、应用状态），而不只是 ID。setEnvVars / 启动 env 中只放非机密配置，实时凭据留在 Worker 中；当沙箱调用外部 API 时使用出站处理器。不要臆造已移除的稳定版 API（核心上的 gitCheckout、字符串 exec 完成、session 执行、sandbox.terminal(request)）。不要对所有错误都用同一个重试循环（参见 Errors 文档）。
最小形态示例：
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123"); const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]); const result = await process.output({ encoding: "utf8" }); // result.stdout, result.exitCode
任务相关的 API 文档见 references/api-quick-ref.md，示例索引（next 分支）见 references/examples.md。
三、检索：按任务打开文档 实现前先获取页面。已安装的 @next 类型优先于猜测。按需求查阅对应文档：概览选择预览版 → 1.0 preview overview；首个 Worker、wrangler、Dockerfile → Get started；exec、句柄、就绪性、持久性 → Process execution；进程 API 签名 → Processes API；sandbox ID 与容器及 sleep/destroy → Lifecycle；cwd / env / setEnvVars → Environment；交互式 PTY 或浏览器终端 → Terminals · Terminals API；Python/JS 代码解释器 → Interpreter · Interpreter API；扩展模型 → Extensions；错误类与恢复 → Errors · Errors API；常见故障 → Troubleshooting；API 总入口 → API reference。共享能力主文档包括 Files、Storage / mounts、Ports、Tunnels、Backups、Outbound traffic、Expose services、Production（忽略仅限稳定版的 session/transport/sandbox.terminal）。其他：示例应用见 next 分支 examples；仍使用稳定包见 sandbox-stable 与主 Sandbox 文档；移植现有稳定应用见 sandbox-migrate-to-next 与 Migrate。
四、发布前检查 lockfile 与 Dockerfile 处于同一 @next 线；针对已安装的 @next 类型做类型检查；沙箱 env 中不含实时机密；使用相关 URL 模式时，生产预览主机名需要自定义域上的通配 DNS。
说明：分类为编程与开发；本技能的具体收费、价格等信息资料未提供；安装方式请参考 Agent setup · cloudflare/skills。