# 核心概念

<subtitle>用最短路径建立 UCloud Sandbox 的心智模型：沙箱、模板、快照与生命周期。</subtitle>

在深入 SDK 细节之前，请先理解以下核心概念。

---

## 沙箱 (Sandbox)

沙箱是一个**隔离的运行环境**，提供完整的操作系统能力。您可以在其中：

- 执行 Shell 命令与代码
- 读写文件系统
- 访问网络（可配置）
- 安装软件包

**生命周期**：创建 → 使用 → 销毁

```python
from ucloud_sandbox import Sandbox

# 创建
sandbox = Sandbox.create(timeout=60)

# 使用
result = sandbox.commands.run("echo 'Hello'")

# 销毁
sandbox.kill()
```

> [!NOTE]
> 详见：[沙箱生命周期](/docs/agent-sandbox/sdk/sandbox/01-lifecycle.md)

---

## 模板 (Template)

模板是沙箱的**蓝图**。通过模板，您可以：

- 预装软件依赖（Python 包、Node 模块等）
- 预置配置文件
- 设置环境变量
- 启动常驻服务（如 Web 服务器）

**核心价值**：将初始化成本前移到构建阶段，让后续创建沙箱更快、更稳定。

```python
from ucloud_sandbox import Template

template = (
    Template()
    .from_base_image()
    .pip_install(["pandas", "numpy"])
    .set_envs({"ENV": "production"})
)
```

> [!NOTE]
> 详见：[模板快速开始](/docs/agent-sandbox/template/01-quick-start.md)

---

## 快照 (Snapshot)

模板构建结束时会生成**快照**。快照的特殊之处在于：

- 不仅包含文件系统状态
- 还包含**运行中的进程状态**（内存快照）

这使得从模板创建沙箱时，可以直接恢复到就绪状态，通常可实现 **50-200ms 级别的极速启动**（实际时间受模板复杂度、网络环境等因素影响）。

```
┌─────────────────────────────────────────────────────────────┐
│  传统方式：启动容器 → 安装依赖 → 启动服务 → 就绪（分钟级）    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  UCloud Sandbox：从快照恢复 → 立即就绪（毫秒级）             │
└─────────────────────────────────────────────────────────────┘
```

> [!NOTE]
> 详见：[模板工作原理](/docs/agent-sandbox/coreConcept/02-how-it-works.md)

---

## 启动命令与就绪命令

在构建模板时，您可以定义：

| 命令类型 | 作用 | 典型用途 |
|---------|------|---------|
| **启动命令** (Start Command) | 在构建时启动后台服务，并将其运行状态写入快照 | Web 服务器、数据库 |
| **就绪命令** (Ready Command) | 判断环境是否达到可用状态，退出码为 0 时生成快照 | 端口检测、文件存在检测 |

```python
from ucloud_sandbox import Template, wait_for_port

template = (
    Template()
    .from_node_image("20")
    .run_cmd("npm install")
    .set_start_cmd("npm start", wait_for_port(3000))
)
```

> [!NOTE]
> 详见：[启动与就绪命令](/docs/agent-sandbox/template/08-start-and-ready-commands.md)

---

## 概念关系图

```
┌────────────────────────────────────────────────────────────────┐
│                        模板 (Template)                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  定义：基础镜像 + 依赖安装 + 环境变量 + 启动命令          │  │
│  └──────────────────────────────────────────────────────────┘  │
│                            │                                    │
│                            ▼ 构建                               │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  快照 (Snapshot)：文件系统 + 内存状态                     │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘
                             │
                             ▼ 创建
┌────────────────────────────────────────────────────────────────┐
│                        沙箱 (Sandbox)                           │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  能力：命令执行 / 文件系统 / 网络访问 / 指标监控          │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘
```

---

## 下一步

- [产品架构](/docs/agent-sandbox/coreConcept/02-concepts.md) - 了解系统组件与数据流
- [SDK 快速开始](/docs/agent-sandbox/product/00-quick-start.md) - 动手实践
- [词汇表](/docs/agent-sandbox/_glossary.md) - 术语速查