OpenSandbox 1.1.1 学习区
这门课只讲一件事：一次沙箱任务，从意图到证据，中间经过了谁。 目标不是背 API，而是建立一套判断力——看到“支持”两个字，会先问：在哪个运行时、什么配置、什么版本、什么代价。
版本与来源
跳转到“版本与来源”| 项目 | 内容 |
|---|---|
| 教材对象 | OpenSandbox 官方稳定版 |
| 版本标签 | release-1.1.1 |
| 提交 | 531700ca18a7fa5fab6a2f25d6dc68a76eddab12 |
| 发布时间 | 2026-10-09 |
| 源码获取 | 官方 release，请自行检出；本站不分发源码 |
| 官方仓库 | https://github.com/opensandbox-group/OpenSandbox |
| 官方发布页 | https://github.com/opensandbox-group/OpenSandbox/releases/tag/release-1.1.1 |
这些笔记以官方 release-1.1.1 源码和公开文档交叉校对。公开仓库只收录学习笔记，不包含上游源码、.git 目录或本地备份。
这门课要解决什么问题
跳转到“这门课要解决什么问题”一个 AI 应用要让模型“真的做事”，至少要回答四个问题：
1. 代码在哪里跑，才不会伤到宿主机？2. 跑起来之后，命令、文件、输出怎样被可靠地收集？3. 它怎样联网、怎样拿凭据，而不把数据或密钥送出去？4. 当模型自己决定下一步时，谁保证它不失控、成本可控、事后可查？OpenSandbox 用一套分层设计回答这四个问题。这门课沿着一次沙箱任务的生命周期，把这套设计拆开、跑通、再合起来。
一条主线
跳转到“一条主线”创建意图 -> 控制面受理（认证、TTL、状态） -> 运行时落地（容器 / Pod / 微虚拟机） -> 端点解析（地址不是猜的） -> 执行（execd：命令、文件、流） -> 网络与凭据（该通的通，该断的断） -> 证据回流（退出码、stderr、产物） -> TTL / 暂停 / 销毁每一阶段只回答这条链上的一个岔路口。阶段之间不是“知识点堆叠”，而是同一个任务在不同层上的展开。
怎么学：五步循环
跳转到“怎么学：五步循环”每一章都走同一个循环，不跳步：
1. 提问：如果我是设计者，我会怎么解决？2. 画图：把这一层的输入、输出、失败点画出来3. 读码：只读能回答问题的文件，不做无目的通读4. 实验：跑一个最小验证，记录成功与失败两种形态5. 复述：不看资料讲回来，并说出两个边界判断“学会了”的标准不是“跑通了”，而是：能解释为什么这样设计，能指出它在什么条件下失效。
阶段地图
跳转到“阶段地图”| 阶段 | 只解决一个大问题 | 产出 | 类型 |
|---|---|---|---|
| 阶段 0 | 最小闭环能不能真实跑起来？ | 一次成功脚本 + 一次失败记录 | 准备 |
| 阶段 1 | 一次任务怎样穿过平台？ | 架构图 + 创建/执行时序图 + 失败点清单 | 核心 |
| 阶段 2 | 环境从生到死，谁负责？ | 成功/异常/取消都能清理的封装 | 核心 |
| 阶段 3 | 命令、文件、代码怎样变成可验证的动作？ | 带超时、截断、结构化返回的工具层 | 核心 |
| 阶段 4 | 同一份契约怎样落到 Docker/K8s/FastSandbox？ | 运行时能力矩阵 + 选择决策树 | 进阶 |
| 阶段 5 | 怎样该通的通、该断的断、密钥不被拿走？ | 一页网络策略设计 + 允许/拒绝验证 | 进阶 |
| 阶段 6 | SDK、CLI、MCP 与契约是什么关系？ | 入口选型表 + 契约变更顺序 | 进阶 |
| 阶段 7 | 把沙箱交给模型后，怎样不失控？ | 工具契约 + 预算 + 最小 Agent 环 | AI 应用核心 |
| 阶段 8 | 凭什么敢上线？ | 生产就绪评审 + 故障分层流程 | 核心 |
| 阶段 9 | 能不能独立交付一个完整系统？ | 数据分析与报告 Agent + 证据包 | 实战 |
配套两篇：
横向扩展读 选修区导读：Code Interpreter、浏览器/桌面、存储挂载、K8s/FastSandbox、Agent 框架与编码 CLI、评测。
八个部件
跳转到“八个部件”不管目录怎么变，任何 AI 执行平台都要回答这八件事：
| 部件 | 要回答的问题 | OpenSandbox 中的对应 | 阶段 |
|---|---|---|---|
| 入口 | 人和程序通过什么使用平台？ | Python/JS/Go/Kotlin/C# SDK、osb CLI、MCP |
6 |
| 契约 | 客户端为什么不被某个后端锁死？ | specs/ 下的 OpenAPI |
1、6 |
| 生命周期 | 环境何时创建、过期、销毁？ | server/ 控制面 |
2 |
| 运行时 | 环境跑在容器、Pod 还是微虚拟机？ | Docker、Kubernetes、FastSandbox | 4 |
| 执行 | 模型动作怎样真正发生？ | components/execd/ |
3 |
| 网络 | 流量怎样进入、出去、被限制？ | endpoint、ingress、egress | 5 |
| 安全 | 不可信代码和密钥怎样被约束？ | 隔离运行时、资源限制、网络策略、Vault、租户 | 4、5、8 |
| 工程 | 怎样证明可靠、可观测、可演进？ | 测试、诊断、指标、发布验证 | 8 |
一句话串起来：入口发起，契约约束，控制面安排，运行时落地，数据面执行，网络面治理，安全面兜底，工程面证明。
三条纵线
跳转到“三条纵线”每一章都会反复出现这三条线，不要把它们当“附录”：
| 纵线 | 问题 | 典型落点 |
|---|---|---|
| 证据流 | 这个结论凭什么可信？ | exit_code、stderr、文件、conditions、日志、trace |
| 信任边界 | 谁不可信？密钥在哪？ | 沙箱内容、egress、Credential Vault、租户隔离 |
| 能力条件 | “支持”需要什么前提？ | runtime、配置、版本、镜像、Pool/模板约束 |
推荐节奏
跳转到“推荐节奏”| 周次 | 内容 | 周末应能拿出 |
|---|---|---|
| 第 1 周 | 阶段 0–1 | 能跑通；能画出端到端链路 |
| 第 2 周 | 阶段 2 | 一个三路径都能清理的生命周期封装 |
| 第 3 周 | 阶段 3 | 一个安全的命令/文件工具层 |
| 第 4 周 | 阶段 4 | 一张运行时能力矩阵与选型理由 |
| 第 5 周 | 阶段 5 | 一页默认拒绝的网络与凭据设计 |
| 第 6 周 | 阶段 6–7 | 入口选型 + 一个受控的最小 Agent |
| 第 7 周 | 阶段 8 | 生产就绪评审与故障演练记录 |
| 第 8 周 | 阶段 9 | 毕业项目 + 证据包 + 复盘 |
时间紧可以走“最短闭环”（0→1→2→3→9）；做平台方向可以加读 4、5、8；做 Agent 方向可以加读 5、6、7。
文档地图
跳转到“文档地图”| 文件 | 回答的问题 |
|---|---|
| 整体架构 | OpenSandbox 是什么？分层、主线、七个设计取舍 |
| 学习路线 | 8 周怎么学？每阶段产出什么？怎样算学会？ |
| 阶段 0 | 怎样把源码版、Docker、服务端和第一个沙箱跑起来？ |
| 阶段 1 | 系统地图：一次任务怎样穿过控制面、运行时和数据面？ |
| 阶段 2 | 生命周期、TTL、暂停恢复、快照与清理语义 |
| 阶段 3 | execd：命令、会话、文件、PTY、Code Interpreter |
| 阶段 4 | 运行时：Docker/K8s/FastSandbox、Pool、模板、隔离等级 |
| 阶段 5 | 网络与凭据：端点、ingress、egress、Vault |
| 阶段 6 | 契约、五种 SDK、CLI、MCP 与变更顺序 |
| 阶段 7 | Agent 集成：拓扑、工具、预算、注入、可观测 |
| 阶段 8 | 工程与生产：多租户、测试、指标、发布、回滚 |
| 阶段 9 | 毕业设计：数据分析与报告 Agent |
| 选修区 | 主线之外的按需深入路线 |
内容结构
跳转到“内容结构”Cairn Notes · OpenSandbox 学习区├── 总览与阶段地图├── 核心十阶段 0–9└── 选修区环境提醒
跳转到“环境提醒”- 阶段 0–3 需要可用的 Docker daemon；Windows 上使用 Docker Desktop + Linux 容器（依赖 WSL2）。
- 服务端与示例主要使用 Python 3.10+；其他语言 SDK 需要对应工具链。
- Kubernetes、FastSandbox、Pool、快照、Credential Vault 都有后端与配置前置条件，不能把“接口存在”当成“当前环境可用”。
- 作者编写这套笔记时没有安装 Helm，Docker daemon 也未运行，因此 Kubernetes 部署、Pool、快照等实验未实际执行；文中已逐处标注“需集群/未验证”。阅读时请把“命令存在”和“本机已验证”分开。
- 教材基于 1.1.1 源码与官方文档交叉校对；实际运行以当前配置和后端能力为准。
学习契约
跳转到“学习契约”读完不等于学会。每个阶段结束时，至少做到：
- 不看资料讲清该模块解决什么问题、边界在哪。
- 能画出一次调用的时序图，并指出失败点。
- 能写出最小可运行示例，或给出有依据的伪代码。
- 能说出两个常见误用及其后果。
- 能诚实标注“我验证了什么、没验证什么”。
最终要同时具备四种能力：把模型能力产品化、把工具边界工程化、把风险治理显式化、把系统行为可观测化。 OpenSandbox 是训练这四种能力的一个高质量样本。
从 阶段 0 开始。