> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 云端沙盒

> 声明式沙盒架构——每次对话都有自己的隔离开发环境

当专家需要「动手做事」——写代码、运行程序、操作文件——它不是在某台共享服务器上执行，而是在一个专属的云端隔离容器中操作。这是袋袋的声明式沙盒架构：每次对话都拥有自己的完整开发环境，互不干扰，用完即走。

## 为什么需要沙盒？

<CardGroup cols={2}>
  <Card title="安全隔离" icon="shield">
    AI 执行的代码可能有错误甚至风险。沙盒确保任何操作都被限制在容器内，无法影响宿主系统或其他用户。
  </Card>

  <Card title="环境一致" icon="check">
    预装完整的开发工具链（Node.js、Python、系统工具），专家不需要花时间配环境，上来就能干活。
  </Card>

  <Card title="状态持久" icon="database">
    文件系统在对话期间持久化。专家写的代码、安装的依赖、生成的文件，下次消息还在。
  </Card>

  <Card title="按需启动" icon="bolt">
    只有当专家真正需要执行工具时才创建沙盒，纯对话不付资源成本。
  </Card>
</CardGroup>

## 沙盒生命周期

```mermaid theme={null}
stateDiagram-v2
    [*] --> 等待: 对话开始（无沙盒）
    等待 --> 创建中: 专家首次调用工具
    创建中 --> 运行中: 容器就绪（亚秒级）
    运行中 --> 运行中: 执行工具操作
    运行中 --> 休眠: 对话空闲超时
    休眠 --> 运行中: 用户发送新消息
    运行中 --> 已终止: 会话结束/手动关闭
    休眠 --> 已终止: 超过保留期限
    已终止 --> [*]
```

<Steps>
  <Step title="按需创建（Lazy Provision）">
    沙盒不在对话开始时创建，而是等到专家第一次需要执行工具操作时才启动。纯文字对话零资源消耗。
  </Step>

  <Step title="亚秒级热启动">
    基于预热的容器镜像，沙盒从创建到可用通常在 1 秒以内完成。用户几乎感知不到等待。
  </Step>

  <Step title="跨消息持久化">
    同一会话内的多条消息共享同一个沙盒实例。专家在第一条消息中安装的依赖，在第五条消息中仍然可用。
  </Step>

  <Step title="空闲休眠">
    对话暂停时沙盒自动休眠，释放计算资源。文件系统通过云文件存储（CFS）持久化，不会丢失。
  </Step>

  <Step title="无缝恢复">
    用户再次发消息时，沙盒被唤醒到上次的文件系统状态。专家可以无缝继续之前的工作。
  </Step>
</Steps>

## 镜像预烘焙

沙盒不是一个空白容器——它预装了丰富的开发工具链，让专家开箱即用：

<Accordion title="编程语言与包管理">
  * **Node.js** + bun（JavaScript/TypeScript 全栈）
  * **Python 3** + uv 包管理器（数据科学 + AI 开发）
  * **TypeScript** 编译器 + 语言服务器
  * **Biome** 代码格式化与静态分析
</Accordion>

<Accordion title="数据科学工具栈">
  * pandas、numpy、matplotlib、seaborn
  * scipy、scikit-learn
  * Pillow 图像处理
  * openpyxl Excel 处理
</Accordion>

<Accordion title="文档处理能力">
  * Pandoc 文档格式转换
  * WeasyPrint PDF 渲染
  * Tesseract OCR 文字识别
  * ImageMagick 图像处理
  * Poppler PDF 工具
</Accordion>

<Accordion title="Web 开发框架">
  * TanStack Start（预烘焙 + node\_modules）
  * FastAPI / Flask（Python Web）
  * 完整的 HTTP 客户端工具链
</Accordion>

<Tip>
  预烘焙策略的核心思想是「把等待时间从运行时转移到构建时」。用户不需要等 `npm install` 或 `pip install`——几百 MB 的依赖在镜像构建时就已经安装好了。
</Tip>

## 工作目录架构

```mermaid theme={null}
graph TD
    subgraph 沙盒文件系统
        Root[/home/user/]
        Root --> Project[project/<br/>只读种子模板]
        Root --> Workspace[workspace/<br/>可写工作区]
        Project --> Web[web/<br/>预烘焙 Web 项目]
        Workspace --> UserWeb[web/<br/>用户的 Web 项目]
        Workspace --> Scripts[scripts/<br/>脚本文件]
        Workspace --> Data[data/<br/>数据文件]
    end
```

| 路径                      | 权限 | 用途                           |
| ----------------------- | -- | ---------------------------- |
| `/home/user/project/`   | 只读 | 镜像中预烘焙的模板文件（含 node\_modules） |
| `/home/user/workspace/` | 读写 | 专家的实际工作目录，所有创作在此进行           |

这种设计让专家可以快速从模板起步（零安装延迟），同时保证用户的实际工作不会被后续镜像更新影响。

## Dev Server 懒启动

Web 预览是专家常用的能力——让用户实时看到代码的视觉效果。但 Dev Server 是资源密集型进程：

```mermaid theme={null}
sequenceDiagram
    participant Expert as 专家
    participant RT as Runtime
    participant SB as 沙盒

    Note over Expert,SB: 普通对话（不需要 Web 预览）
    Expert->>RT: 写 Python 脚本
    RT->>SB: write + bash 执行
    Note over SB: 无 Dev Server 启动，节省资源

    Note over Expert,SB: 需要 Web 预览
    Expert->>RT: 调用 website_init 工具
    RT->>SB: 启动 Dev Server
    SB-->>RT: 预览 URL 就绪
    RT-->>Expert: 网站预览面板打开
```

**不变式**：Dev Server 唯一的启动入口是专家主动调用初始化工具。不做预览的对话（数据分析、脚本执行、文档处理）永远不付 Dev Server 的内存和 CPU 成本。

## 网络与安全策略

沙盒具备受控的网络访问能力：

<CardGroup cols={2}>
  <Card title="出站访问" icon="arrow-up-right">
    专家可以访问外部 API、下载资源、进行网络请求。这对 Web 开发和数据采集是必需的。
  </Card>

  <Card title="进程隔离" icon="lock">
    每个沙盒是独立的 Linux 容器，具有完整的进程命名空间隔离。一个用户的操作绝不可能影响另一个用户。
  </Card>

  <Card title="资源上限" icon="gauge">
    CPU、内存、磁盘用量都有容器级别的硬限制，防止恶意或失控的程序耗尽共享基础设施。
  </Card>

  <Card title="文件系统隔离" icon="folder-tree">
    云文件存储按会话隔离挂载，跨会话不可访问。即使同一用户的不同会话也看不到彼此的文件。
  </Card>
</CardGroup>

## Provider 抽象

沙盒系统采用 Provider 抽象设计，使底层实现可以透明切换：

```mermaid theme={null}
graph TD
    RT[智能体运行时] --> |统一 SDK 接口| Provider[Provider 抽象层]
    Provider --> E2B[E2B Provider<br/>云端容器]
    Provider --> Future[未来 Provider<br/>可扩展]

    E2B --> |provision| Create[创建容器]
    E2B --> |resume| Wake[唤醒容器]
    E2B --> |pause| Sleep[休眠容器]
    E2B --> |terminate| Destroy[销毁容器]
```

Runtime 不关心容器的具体实现细节——它通过统一的 Provider 接口与沙盒交互。这意味着未来可以无缝接入新的容器供应商，而上层的 Agent 逻辑无需任何改动。

## 文件同步与预览

沙盒中专家创建的文件可以被用户实时预览和下载：

* **代码文件**：语法高亮展示，支持 diff 对比
* **Web 项目**：通过 Dev Server 实时预览，支持 HMR 热更新
* **数据文件**：表格、图表内联渲染
* **文档**：PDF、Markdown 即时预览

用户还可以将沙盒中的文件同步到云端存储，在对话结束后继续访问。

<Note>
  沙盒是袋袋「AI 不只是说，还能做」理念的技术基石。没有它，专家只能生成文本；有了它，专家可以写代码、运行程序、创建项目、生成文档——像一个真正的数字同事一样工作。
</Note>

## 设计权衡

| 决策         | 选择                | 原因             |
| ---------- | ----------------- | -------------- |
| 启动时机       | 懒加载（首次工具调用时）      | 纯对话不付资源成本      |
| 持久化层       | 云文件存储（CFS）        | 跨容器状态保持，休眠不丢文件 |
| 模板策略       | 预烘焙 node\_modules | 用户零等待，空间换时间    |
| Dev Server | 仅按需启动             | 非 Web 场景零额外开销  |
| 镜像更新       | 工作目录与种子分离         | 升级镜像不破坏用户项目    |