# https://github.com/e2b-dev/code-interpreter 项目说明书
生成时间：2026-06-14 00:17:50 UTC
## 目录
- [总览、架构与 Monorepo 结构](#page-overview)
- [SDK 使用与 API 参考（JS & Python）](#page-sdk-usage)
- [自定义 Code Interpreter 沙箱模板](#page-template-customization)
- [Chart 数据提取与常见故障运维](#page-operations)
## 总览、架构与 Monorepo 结构
### 相关页面
相关主题：[SDK 使用与 API 参考（JS & Python）](#page-sdk-usage), [自定义 Code Interpreter 沙箱模板](#page-template-customization)
相关源码文件
以下源码文件用于生成本页说明：
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json)
- [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/js/tsup.config.js)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [python/e2b_code_interpreter/code_interpreter_sync.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/code_interpreter_sync.py)
- [template/server/main.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/server/main.py)
- [template/server/api/models/context.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/server/api/models/context.py)
- [template/build_prod.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_prod.py)
- [template/build_test.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_test.py)
- [template/build_ci.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_ci.py)
- [template/ipython_kernel_config.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py)
- [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)
# 总览、架构与 Monorepo 结构
## 项目定位与核心能力
`e2b-dev/code-interpreter` 是一个基于 [E2B 沙箱](https://e2b.dev) 构建的可执行代码沙箱开源项目。它由两个面向开发者的 SDK 与一个运行在沙箱内的服务端模板组成,目标是让 AI Agent、工具链或 Web 应用以"代码即数据"的方式安全地执行 Python/JavaScript 代码,并把结构化结果(文本、图表、HTML、JSON、LaTeX 等)回流给调用方。客户端 SDK 通过 HTTP 与沙箱内部的 FastAPI 服务通信,服务端在 Jupyter 多内核之上托管多个执行上下文(资料来源:[js/package.json:1-30](),[template/README.md:1-30]())。
社区中也围绕该项目出现了若干常见问题,例如 Docker 镜像未版本化导致回滚困难([issue #150](https://github.com/e2b-dev/code-interpreter/issues/150))、沙盒超时被误判为"未找到"([issue #147](https://github.com/e2b-dev/code-interpreter/issues/147))、`beta_pause` / `beta_create` 在早期版本中误删沙箱([issue #157](https://github.com/e2b-dev/code-interpreter/issues/157)),以及希望替换 `pip` 为 `uv` 加速自定义模板构建([issue #175](https://github.com/e2b-dev/code-interpreter/issues/175))。这些问题说明本仓库涉及"客户端 SDK + 远端模板 + 构建产物"三方协调,任何改动都需在仓库的多子包中同步。
## Monorepo 顶层结构
仓库采用 pnpm 风格的多包布局,把 Python SDK、JavaScript/TypeScript SDK、沙箱模板与图表数据抽取工具放在同一棵源代码树下,统一通过 [Changesets](https://github.com/changesets/changesets) 维护多包版本。各子包职责如下:
| 子包路径 | 角色 | 关键配置 / 入口 |
| --- | --- | --- |
| `python/` | 同步与异步 Python SDK,包名 `e2b_code_interpreter` | `e2b_code_interpreter/code_interpreter_sync.py`、`models.py` |
| `js/` | TypeScript SDK,包名 `@e2b/code-interpreter`,依赖 `e2b@^2.28.0`,Node `>=20` | `src/messaging.ts`、`tsup.config.js` |
| `template/` | 沙箱内部运行的 FastAPI 服务与 Jupyter 多内核定义 | `server/main.py`、`build_prod.py`、`build_ci.py` |
| `chart_data_extractor/` | 从 DataFrame / matplotlib 提取数据供 SDK 使用 | `README.md` |
JS SDK 通过 `tsup` 把 `src/index.ts` 编译为 `esm` 与 `cjs` 双产物,保留 sourcemap 与 `.d.ts`(资料来源:[js/tsup.config.js:1-20](),[js/package.json:1-30]())。Python 端则对外暴露 `Sandbox`、`Context`、`Result` 等高层抽象,把"创建沙箱 → 建立上下文 → 执行代码 → 取回结果"封装成同步与异步两套 API(资料来源:[python/e2b_code_interpreter/code_interpreter_sync.py:1-30]())。
## 三层架构与请求路径
从用户视角看,系统由"客户端 SDK → E2B 控制平面 → 沙箱内服务"三段式构成:
```mermaid
flowchart LR
A["客户端应用
(Python/JS SDK)"] -->|HTTPS + Headers| B["E2B 控制平面
envd / Sandbox API"]
B -->|启动沙箱| C["FastAPI 服务
server/main.py"]
C --> D["Jupyter 内核
python / javascript"]
C --> E["ContextWebSocket
多上下文 WebSocket"]
D -->|display_data / execute_result| E
E -->|结构化结果| A
```
- **客户端层**:Python 同步客户端通过 `httpx` 携带 `X-Access-Token`、`E2B-Traffic-Access-Token` 等头部访问沙箱内 `/contexts` 等端点;JS SDK 与之等价,但走 TypeScript Promise 链路(资料来源:[python/e2b_code_interpreter/code_interpreter_sync.py:1-30](),[js/src/messaging.ts:1-40]())。
- **服务层**:`server/main.py` 在启动期通过 `lifespan` 创建 `python` 与 `javascript` 两个默认内核上下文,并用 `LockedMap` 维护 `Context` → `ContextWebSocket` 的映射,后端实际复用 Jupyter `jupyter-server` 提供的 `root_dir` 策略以兼容新版本硬化(资料来源:[template/server/main.py:1-30](),[release @e2b/code-interpreter-template@0.4.3](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.3))。
- **数据模型层**:`Context` 是带 `id`、`language`、`cwd` 的不可变 Pydantic 模型,既是 API 响应也是内部哈希键;`Result` 则统一收集 `text/html/markdown/svg/png/jpeg/pdf/latex/json/javascript/data/chart/extra` 等多模态字段,这是 SDK 与服务端协议对齐的"最大公约数"(资料来源:[template/server/api/models/context.py:1-10](),[python/e2b_code_interpreter/models.py:1-50](),[js/src/messaging.ts:1-40]())。
## 构建、发布与版本协调
模板的发布是本仓库最复杂的一环。`template/build_prod.py` 是 CI 与发布使用的"生产模板"构建脚本,产出官方 `code-interpreter-v1`;`template/build_ci.py` 把构建结果写入 `GITHUB_OUTPUT` 以供后续 Job 使用;`template/build_test.py` 则面向本地与 `code-interpreter-dev` 别名,启用 Python + JavaScript 双内核(资料来源:[template/README.md:1-60](),[template/build_ci.py:1-15](),[template/build_test.py:1-12]())。
发布管线由 Changesets 驱动,因此你可以同时看到三类版本号:
- **SDK 版本**:`@e2b/code-interpreter@2.6.0` 与 `@e2b/code-interpreter-python@2.8.0` 等 minor 升级通常仅同步升级底层 `e2b` SDK、移除 `Sandbox.betaCreate` / `beta_create` 之类的过渡 API,并把 `lifecycle` 配置并入 `Sandbox.create`([release @e2b/code-interpreter@2.5.0](https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.5.0))。
- **模板版本**:`@e2b/code-interpreter-template` 的 patch/minor 与 SDK 解耦,例如 `0.4.3` 仅 pin `jupyter-server` 的 `root_dir` 以规避路径遍历硬化、`0.4.1` 把 `cwd` 透传给 bash 内核、`0.4.0` 移除 Deno 内核(资料来源:[releases @e2b/code-interpreter-template@0.4.0–0.4.3](https://github.com/e2b-dev/code-interpreter/releases))。
- **依赖基线**:依赖更新由 Renovate 维护,见 [Dependency Dashboard #200](https://github.com/e2b-dev/code-interpreter/issues/200)。
## 常见失败模式
- **沙箱"消失"**:客户端在超时或长空闲后会触发 `e2b.exceptions.TimeoutException`,沙箱被回收;这是 `timeout` 与 `auto_pause` 生命周期共同作用的结果,详见 [issue #147](https://github.com/e2b-dev/code-interpreter/issues/147)。
- **API 误用迁移**:旧代码中 `Sandbox.betaCreate({ autoPause: true })` 需替换为 `Sandbox.create({ lifecycle: { autoPause: true } })`,否则在 `2.5.0` 之后会直接抛 `AttributeError`。
- **模板不版本化**:`build_prod.py` 默认走 layer cache,生产回滚依赖发布到固定 `template_id`;若不主动固定别名,会复现 [issue #150](https://github.com/e2b-dev/code-interpreter/issues/150) 中"全部是 `latest`"的痛点。
- **自定义模板构建慢**:若频繁 `pip install`,建议基于 `from_template("code-interpreter-v1")` 烘焙预装包,或迁移到 `uv`(社区诉求见 [issue #175](https://github.com/e2b-dev/code-interpreter/issues/175))。
## See Also
- [E2B 官方文档:自定义沙箱模板](https://e2b.dev/docs/template/quickstart)
- 相关 Issues:#147(超时)、#150(版本化)、#157(beta API)、#175(uv 模板)
- Releases:`@e2b/code-interpreter@2.6.0`、`@e2b/code-interpreter-python@2.8.0`、`@e2b/code-interpreter-template@0.4.3`
---
## SDK 使用与 API 参考（JS & Python）
### 相关页面
相关主题：[总览、架构与 Monorepo 结构](#page-overview), [Chart 数据提取与常见故障运维](#page-operations)
相关源码文件
以下源码文件用于生成本页说明：
- [python/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/python/README.md)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [python/e2b_code_interpreter/code_interpreter_sync.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/code_interpreter_sync.py)
- [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json)
- [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/js/tsup.config.js)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [template/template.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/template.py)
- [template/build_test.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_test.py)
- [template/build_debug.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_debug.py)
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)
- [template/ipython_kernel_config.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py)
# SDK 使用与 API 参考（JS & Python）
## 概述
本仓库提供两套一等公民 SDK，用于在 E2B 隔离云沙箱中安全执行 AI 生成代码：[Python SDK `e2b_code_interpreter`](https://pypi.org/project/e2b_code_interpreter/) 与 [JavaScript SDK `@e2b/code-interpreter`](https://www.npmjs.com/package/@e2b/code-interpreter)。两者共享同一份运行在沙箱中的 Jupyter 后端服务，对外暴露同步与异步的代码执行、上下文管理与结果解析能力，资料来源：[python/README.md:1-30]()。
## 安装与运行时依赖
Python 侧通过 `pip install e2b-code-interpreter` 安装，并在环境变量 `E2B_API_KEY` 中提供密钥；JavaScript 侧要求 Node `>=20`，并通过 `e2b ^2.28.0` 完成底层 RPC 通信，资料来源：[js/package.json:30-44]()、`python/README.md:18-25]()`。JS SDK 由 `tsup` 打包为 ESM 与 CJS 双产物，并生成 `.d.ts` 类型声明，资料来源：[js/tsup.config.js:1-15]()`。
## 沙箱生命周期与代码执行
### 模板与可用内核
模板构造函数 `make_template` 起始于 `python:3.13` 基础镜像，通过 `apt_install` 安装构建工具、`nodejs`（经 NodeSource 仓库）等系统依赖，随后用 `pip_install` 安装 Python 需求并按需启用 Jupyter 内核：默认启用 `python` 与 `javascript`，可选启用 `r`、`bash`、`java`，资料来源：[template/template.py:9-58]()`。
```python
# 仅启用 Python 与 JavaScript 内核
make_template(kernels=["python", "javascript"])
```
模板通过 `Template.build` 注册到 E2B 后台；开发期可使用 `build_test.py` 构建 `code-interpreter-dev` 别名进行联调，资料来源：[template/build_test.py:1-12]()`。调试构建 `build_debug.py` 则改用 `wait_for_timeout(60_000)` 而非 `/health` 健康检查，并在 systemd drop-in 中将 Jupyter 的 stdout 重定向至 journal，便于 `journalctl -u jupyter` 排查，资料来源：[template/build_debug.py:1-14]()`、`[template/README.md:36-50]()`。
### 上下文（Code Context）管理
SDK 在沙箱内通过 Jupyter 协议隔离多个执行上下文。同步实现提供了 `list_code_contexts()` 与 `restart_code_context(context)`：前者调用 `GET /contexts` 列出全部上下文，后者在 `POST` 指定上下文路径前会校验 `Context` 对象或字符串 ID，资料来源：[python/e2b_code_interpreter/code_interpreter_sync.py:1-60]()`。所有请求附带 `Content-Type: application/json`，并在持有 `X-Access-Token`（envd）或 `E2B-Traffic-Access-Token`（流量层）时一并下发，资料来源：[python/e2b_code_interpreter/code_interpreter_sync.py:8-60]()`。
### 迁移说明：`beta_create` / `beta_pause` 已移除
社区曾广泛使用 `Sandbox.beta_create` + `beta_pause` 组合以实现自动暂停，但该实现曾误删沙箱（[issue #157](https://github.com/e2b-dev/code-interpreter/issues/157)）。`@e2b/code-interpreter@2.5.0` 与 `@e2b/code-interpreter-python@2.7.0` 起移除 Beta API，请改用 `Sandbox.create({ lifecycle: ... })` 进行生命周期配置。
## 数据模型：`Result` 与 `Logs`
`Result` 同时提供 Jupyter 全部 MIME 类型的字段；Python 端以 `@dataclass(repr=False)` 实现，并通过 `_repr_html_`、`_repr_markdown_`、`_repr_png_` 等钩子在 Jupyter 中直接渲染，资料来源：[python/e2b_code_interpreter/models.py:1-120]()`。JS 端 `Result` 在构造时剥离 `type` 与 `is_main_result`，再将剩余键暴露为只读字段，并通过 `toJSON()` 进行序列化，资料来源：[js/src/messaging.ts:1-90]()`。
| 字段 | Python 类型 | JS 类型 | 说明 |
| --- | --- | --- | --- |
| `text` / `html` / `markdown` | `Optional[str]` | `string` | 文本 / HTML / Markdown 表示 |
| `svg` / `png` / `jpeg` / `pdf` | `Optional[str]` | `string` | 图像或 PDF 的 base64 内容 |
| `latex` / `javascript` / `json` | `Optional[str]` | `string` | LaTeX、JS、JSON 表示 |
| `data` / `chart` | `Optional[Any]` | `Record` / `ChartTypes` | DataFrame / matplotlib 抽取数据 |
| `Logs.stdout` / `stderr` | `List[str]` | `string[]` | 执行期间 stdout / stderr 收集 |
资料来源：[python/e2b_code_interpreter/models.py:60-200]()`、`[js/src/messaging.ts:60-140]()`、`[chart_data_extractor/README.md:1-3]()`。`Result.formats()` 仅返回实际非空的 MIME 名称，便于 UI 按需渲染。
## 已知限制与排错
- **沙箱超时失效**：使用 Pro 账号设置较长 `timeout` 后仍可能抛 `TimeoutException`（[issue #147](https://github.com/e2b-dev/code-interpreter/issues/147)）。建议在 SDK 层捕获异常并触发幂等重建。
- **Docker 镜像无版本标签**：社区反馈 `code-interpreter` 镜像始终为 `latest`，难以回滚（[issue #150](https://github.com/e2b-dev/code-interpreter/issues/150)）。生产环境建议固定 `code-interpreter-v1` 别名对应的模板版本，并自建派生模板。
- **依赖治理**：仓库启用 Renovate 维护依赖矩阵，详见 [issue #200](https://github.com/e2b-dev/code-interpreter/issues/200)。
- **自定义模板安装速度**：用户希望默认使用 `uv` 加速 pip 流程（[issue #175](https://github.com/e2b-dev/code-interpreter/issues/175)），可在 `template.py` 的 `pip_install` 阶段替换为 `uv pip install`，再通过自定义 `build_prod.py` 打包，资料来源：[template/README.md:1-20]()`。
## 另请参阅
- E2B 平台文档：https://e2b.dev/docs
- 自定义沙箱模板指南：https://e2b.dev/docs/template/quickstart
- Python SDK PyPI 页面：https://pypi.org/project/e2b_code_interpreter/
- JS SDK npm 页面：https://www.npmjs.com/package/@e2b/code-interpreter
---
## 自定义 Code Interpreter 沙箱模板
### 相关页面
相关主题：[总览、架构与 Monorepo 结构](#page-overview), [Chart 数据提取与常见故障运维](#page-operations)
相关源码文件
以下源码文件用于生成本页说明：
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [template/build_test.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/build_test.py)
- [template/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/template/package.json)
- [template/ipython_kernel_config.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/ipython_kernel_config.py)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [python/e2b_code_interpreter/code_interpreter_async.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/code_interpreter_async.py)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [js/src/index.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/index.ts)
- [js/package.json](https://github.com/e2b-dev/code-interpreter/blob/main/js/package.json)
- [js/tsup.config.js](https://github.com/e2b-dev/code-interpreter/blob/main/js/tsup.config.js)
# 自定义 Code Interpreter 沙箱模板
## 概述与目的
Code Interpreter 沙箱模板定义了远端代码执行环境的"基础镜像"：包含 Jupyter Server、IPython / JavaScript 内核、依赖库以及预置文件。E2B 官方发布的默认模板名为 `code-interpreter-v1`，而**自定义模板**允许开发者在此基础上增减内核与依赖，从而在生产环境中获得一致、确定性的执行体验。资料来源：[template/README.md:1-10]()。
官方仓库提供了三种构建入口：
| 构建入口 | 用途 | 关键文件 |
| --- | --- | --- |
| 生产构建 | CI 与正式发布 `code-interpreter-v1` | `template/build_prod.py` |
| 测试构建 | 仅构建开发镜像，含 Python / JS 内核 | `template/build_test.py` |
| 调试构建 | 模拟崩溃场景并收集日志 | `template/build_prod.py` 中的 `debug=True` |
资料来源：[template/README.md:3-13]()、[template/build_test.py:1-9]()。
## 生产模板构建流程
生产构建脚本 `build_prod.py` 由 CI 与官方发布流程调用。运行前需要：
1. 安装构建依赖：`pip install -r requirements-dev.txt`。
2. 在 `.env` 中注入 `E2B_API_KEY=e2b_***`。
3. 执行 `python build_prod.py`。
如果想绕过层缓存强制重新构建，可设置环境变量 `SKIP_CACHE=true`：
```bash
SKIP_CACHE=true python build_prod.py
```
资料来源：[template/README.md:5-23]()。
> 社区关注点：官方模板当前没有为每次构建打语义化版本号，社区报告 #150 指出 Docker 镜像一律被标记为 `latest`，导致无法回滚到历史可用版本，生产环境难以锁定。
## 创建自定义模板
当用户需要预装特定的 Python 包、切换默认包管理器（例如 uv，见社区 #175）或自定义工作目录时，应基于官方模板派生自定义模板。资料来源：[template/README.md:25-41]()。
### 步骤一：派生模板定义
```python
# template.py
from e2b import Template
template = Template().from_template("code-interpreter-v1")
```
### 步骤二：编写构建脚本
```python
# build.py
from dotenv import load_dotenv
from .template import template
from e2b import Template, default_build_logger
load_dotenv()
Template.build(
template,
alias="code-interpreter-custom",
cpu_count=2,
memory_mb=2048,
on_build_logs=default_build_logger(),
)
```
### 步骤三：环境变量
`.env` 必须包含 `E2B_API_KEY`，并通过 `dotenv` 加载。
资料来源：[template/README.md:30-50]()。
模板构建完成后，使用 Python SDK 或 JS SDK 即可在 `Sandbox.create(template="code-interpreter-custom")` 时复用该镜像。
## 内核配置与结果数据模型
`template/ipython_kernel_config.py` 是 IPython 内核的配置文件副本，控制异常展示模式 (`xmode`)、缓存大小 (`cache_size`)、彩色信息输出 (`color_info`) 等行为。资料来源：[template/ipython_kernel_config.py:20-120]()。
模板当前默认提供两类内核：
```python
make_template(kernels=["python", "javascript"])
```
资料来源：[template/build_test.py:3-7]()。注意 0.4.0 版本起 Deno 内核已被移除（参见发布说明 `@e2b/code-interpreter-template@0.4.0`）。
代码执行返回的数据模型在 Python 与 JS SDK 中保持一致：
```python
# python/e2b_code_interpreter/models.py
@dataclass(repr=False)
class Logs:
stdout: List[str]
stderr: List[str]
```
```typescript
// js/src/messaging.ts
export type Logs = {
stdout: string[]
stderr: string[]
}
```
`Result` 对象同时携带多种 MIME 表示（`text`、`html`、`markdown`、`svg`、`png`、`jpeg`、`pdf`、`latex`、`json`、`javascript`），调用方可通过 `formats()` 方法枚举所有可用表示。资料来源：[python/e2b_code_interpreter/models.py:180-220]()、[js/src/messaging.ts:60-110]()。
## 调试模板与故障排查
当自定义模板在生产环境出现启动失败时，应使用调试模板定位根因。运行 `make debug-template` 会触发 `make_template(debug=True)`，构建一个固定超时而非依赖 `/health` 检查的调试镜像，并在沙箱内自动启用 systemd journal 转储：
```bash
make debug-template
```
调试构建还会通过 systemd drop-in 把 Jupyter 的 stdout 重定向到 journal；而**生产构建**保持 `StandardOutput=null`，因此日志只会出现在调试模板里。资料来源：[template/README.md:54-71]()。
进入运行中的沙箱后，可使用以下命令进一步排查：
```bash
journalctl -u jupyter -u code-interpreter
systemctl status code-interpreter
```
资料来源：[template/README.md:64-71]()。
## 常见失败模式与版本兼容性
下表汇总社区频繁报告的与模板/生命周期相关的失败模式，以及对应的来源：
| 现象 | 触发条件 | 缓解方法 | 资料来源 |
| --- | --- | --- | --- |
| 沙箱"未找到" | 长任务超过模板 `timeout` | 提高 `Sandbox.create(timeout=…)` 并使用持久化模板 | 社区 #147 |
| `beta_pause`/`beta_create` 直接删除沙箱 | 仍在使用 2.5.0 之前的 API | 迁移到 `Sandbox.create(lifecycle=…)` | 社区 #157、发布说明 2.5.0 |
| 镜像无法回滚 | 未做语义化版本化 | 基于 Git tag 或 alias 显式钉版本 | 社区 #150 |
| `pip install` 成为瓶颈 | 启动时按需安装依赖 | 使用自定义模板预装依赖，或改用 uv | 社区 #175 |
此外，JS SDK 依赖 `e2b ^2.28.0`，Node 引擎要求 `>=20`；构建工具为 `tsup`，输出 `esm` 与 `cjs` 两种格式，并附带 `.d.ts` 类型声明。资料来源：[js/package.json:30-58]()、[js/tsup.config.js:1-15]()。模板包 `template/package.json` 当前版本 `0.4.3`，依赖 `ruff` 用于 lint 与 format。资料来源：[template/package.json:1-9]()。
## See Also
- [E2B 官方模板快速开始指南](https://e2b.dev/docs/template/quickstart)
- [@e2b/code-interpreter 发布说明](https://github.com/e2b-dev/code-interpreter/releases)
- 社区讨论：#147、#150、#157、#175
---
## Chart 数据提取与常见故障运维
### 相关页面
相关主题：[SDK 使用与 API 参考（JS & Python）](#page-sdk-usage), [自定义 Code Interpreter 沙箱模板](#page-template-customization)
相关源码文件
以下源码文件用于生成本页说明：
- [chart_data_extractor/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/chart_data_extractor/README.md)
- [python/e2b_code_interpreter/models.py](https://github.com/e2b-dev/code-interpreter/blob/main/python/e2b_code_interpreter/models.py)
- [template/server/api/models/result.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/server/api/models/result.py)
- [js/src/messaging.ts](https://github.com/e2b-dev/code-interpreter/blob/main/js/src/messaging.ts)
- [template/template.py](https://github.com/e2b-dev/code-interpreter/blob/main/template/template.py)
- [template/README.md](https://github.com/e2b-dev/code-interpreter/blob/main/template/README.md)
- [pnpm-workspace.yaml](https://github.com/e2b-dev/code-interpreter/blob/main/pnpm-workspace.yaml)
# Chart 数据提取与常见故障运维
## 概述与定位
`chart_data_extractor` 是 e2b Code Interpreter 仓库中的独立工具包，专注于从代码执行产物中抽取结构化图表数据。该包被设计为服务端模板与客户端 SDK 的"桥梁"：服务端模板在 Jupyter 内核返回结果时附带 `chart` 字段，客户端 SDK 在 [python/e2b_code_interpreter/models.py](python/e2b_code_interpreter/models.py) 与 [js/src/messaging.ts](js/src/messaging.ts) 中将该字段反序列化为可编程对象。
资料来源：[chart_data_extractor/README.md:1-3]() 指出："This package is a utility used to extract data in the Code Interpreter SDK from, e.g., DataFrames and matplotlib plots."
仓库同时通过 monorepo 组织方式管理多语言构件。资料来源：[pnpm-workspace.yaml:1-5]() 显示工作区包含 `js`、`python`、`chart_data_extractor`、`template` 四个包，这意味着图表提取逻辑与 SDK 同源演化。
## 数据流与架构
Chart 数据在执行链路上按如下顺序流转：用户在沙箱内调用 matplotlib/DataFrame 等绘制函数 → 内核产生多种 MIME 表示 → 服务端 `Result` 聚合后通过 `chart` 字段暴露 → 客户端 SDK 反序列化 → `chart_data_extractor` 提供进一步的结构化访问。
```mermaid
flowchart LR
A[Sandbox 内核执行] --> B[Result 多 MIME 输出]
B --> C[服务端 Result.chart]
C --> D[Python Result.chart]
C --> E[JS Result.chart]
D --> F[chart_data_extractor]
E --> F
F --> G[结构化 Bar/Pie/Planar 数据]
```
资料来源：[template/server/api/models/result.py:13-29]() 定义 `chart: Optional[dict] = None` 字段；[python/e2b_code_interpreter/models.py:78-83]() 在 `Result` 中镜像该字段；[js/src/messaging.ts:39-43]() 同样在 `Result` 类上声明 `readonly chart?: ChartTypes`。
## 数据模型与多语言一致性
| 字段 | Python | JavaScript | 服务端 Pydantic |
|------|--------|------------|----------------|
| `text` / `html` / `markdown` | ✔ | ✔ | ✔ |
| `svg` / `png` / `jpeg` / `pdf` | ✔ | ✔ | ✔ |
| `latex` / `json` / `javascript` | ✔ | ✔ | ✔ |
| `data` / `chart` / `extra` | ✔ | ✔ | ✔ |
`Result` 类同时实现了 Jupyter 风格的 `_repr_*_` 方法（如 `_repr_png_`、`_repr_latex_`），便于在 Notebook 环境中直接渲染。资料来源：[python/e2b_code_interpreter/models.py:107-152]() 完整列举了这些渲染方法。
`formats()` 方法会动态枚举当前结果中所有非空表示。资料来源：[python/e2b_code_interpreter/models.py:166-189]() 与 [js/src/messaging.ts:88-119]() 各自维护了一份等价枚举逻辑，以保证跨 SDK 行为一致。
## 常见故障与运维要点
### 沙箱生命周期异常
社区多次反馈 `The sandbox was not found` 与 `TimeoutException`。资料来源：issue [#147](https://github.com/e2b-dev/code-interpreter/issues/147) 描述"成功写入文件后数分钟内调用 shell 返回沙箱不存在"；issue [#157](https://github.com/e2b-dev/code-interpreter/issues/157) 反映 `beta_pause` / `beta_create` 实际触发删除而非暂停。运维建议：
- 在 `Sandbox.create` 时显式传入 `lifecycle` 选项，避免使用已废弃的 `betaCreate` / `beta_create`。
- 设置 `timeout` 时考虑计费窗口，沙箱可能在空闲超时后被回收。
资料来源：发布说明 `@e2b/code-interpreter@2.5.0` 明确移除 `Sandbox.betaCreate` 并迁移到 `Sandbox.create` 的 `lifecycle` 参数。
### 模板不可复现
issue [#150](https://github.com/e2b-dev/code-interpreter/issues/150) 反映 Docker 镜像仅使用 `latest` 标签导致无法回滚。资料来源：[template/README.md:11-23]() 建议通过 `build_prod.py` 构建 `code-interpreter-v1` 模板，并可设置 `SKIP_CACHE=true` 强制重建。生产部署应锁定具体模板别名而非 `latest`。
### 自定义模板与依赖优化
issue [#175](https://github.com/e2b-dev/code-interpreter/issues/175) 提出基于 `uv` 的自定义模板以缩短 `pip install` 时间。资料来源：[template/template.py:14-26]() 演示了从 `code-interpreter-v1` 派生自定义模板的链式 API (`from_template`、`copy`、`pip_install`、`run_cmd`)。推荐做法是在构建期预装常用库，而非在每次沙箱启动时安装。
### 内核与工作目录修复
发布说明 `@e2b/code-interpreter-template@0.4.1` 修复了 bash kernel 忽略 `cwd` 的问题（`pwd` 此前始终返回 `/`）；`0.4.3` 将 `jupyter-server` 的 `root_dir` 固定到 `/home/user` 以兼容 2.18.0 的路径遍历加固。运维时应跟踪这些 patch 版本以避免回退。
### 依赖基线提升
`@e2b/code-interpreter@2.4.2` 与 `@e2b/code-interpreter-python@2.6.2` 提升了 e2b SDK 最低依赖版本；`@e2b/code-interpreter@2.6.0` 新增"API-only 自定义 header"能力。升级前应核查调用方是否依赖旧版 API 签名。
## 调试与排障路径
资料来源：[template/README.md:25-39]() 提供 `make debug-template` 工具，注入 systemd drop-in 将 Jupyter stdout 路由到 journal，便于在沙箱内通过 `journalctl -u jupyter -u code-interpreter` 与 `systemctl status code-interpreter` 实时定位问题。生产模板保持 `StandardOutput=null`，因此该日志仅在调试构建中可见。
调试模板以固定超时取代 `/health` 探活，可在服务崩溃循环中仍正常 finalize，便于捕获完整堆栈。
## See Also
- Code Interpreter 主仓库 README 与快速上手
- E2B 自定义模板文档：https://e2b.dev/docs/template/quickstart
- Sandbox 生命周期与 `lifecycle` 选项迁移指南（`@e2b/code-interpreter@2.5.0` changelog）
- Jupyter 内核消息格式：https://ipython.readthedocs.io/en/stable/development/execution.html#execution-semantics
---
---
## Doramagic 踩坑日志
项目：e2b-dev/code-interpreter
摘要：发现 26 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Docker images are not versioned - everything is `latest`。
## 1. 安装坑 · 来源证据：Docker images are not versioned - everything is `latest`
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docker images are not versioned - everything is `latest`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/150 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 2. 安全/权限坑 · 来源证据：Dependency Dashboard
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/200 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 失败模式：installation: @e2b/code-interpreter-python@2.6.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: @e2b/code-interpreter-python@2.6.2
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-python@2.6.2
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.6.2 | @e2b/code-interpreter-python@2.6.2
## 4. 安装坑 · 失败模式：installation: @e2b/code-interpreter@2.4.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: @e2b/code-interpreter@2.4.2
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter@2.4.2
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.4.2 | @e2b/code-interpreter@2.4.2
## 5. 安装坑 · 失败模式：installation: Dependency Dashboard
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Dependency Dashboard
- 对用户的影响：Developers may fail before the first successful local run: Dependency Dashboard
- 证据：failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/200 | Dependency Dashboard
## 6. 安装坑 · 失败模式：installation: Need UV-based code-interpreter custom template
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Need UV-based code-interpreter custom template
- 对用户的影响：Developers may fail before the first successful local run: Need UV-based code-interpreter custom template
- 证据：failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/175 | Need UV-based code-interpreter custom template
## 7. 安装坑 · 来源证据：Need UV-based code-interpreter custom template
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Need UV-based code-interpreter custom template
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/175 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 配置坑 · 失败模式：configuration: @e2b/code-interpreter-python@2.7.0
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: @e2b/code-interpreter-python@2.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-python@2.7.0
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.7.0 | @e2b/code-interpreter-python@2.7.0
## 9. 配置坑 · 失败模式：configuration: @e2b/code-interpreter@2.5.0
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: @e2b/code-interpreter@2.5.0
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter@2.5.0
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.5.0 | @e2b/code-interpreter@2.5.0
## 10. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter | README/documentation is current enough for a first validation pass.
## 11. 运行坑 · 失败模式：runtime: The beta_pause and beta_create delete my sandbox directly
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: The beta_pause and beta_create delete my sandbox directly
- 对用户的影响：Developers may hit a documented source-backed failure mode: The beta_pause and beta_create delete my sandbox directly
- 证据：failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/157 | The beta_pause and beta_create delete my sandbox directly
## 12. 运行坑 · 来源证据：The beta_pause and beta_create delete my sandbox directly
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：The beta_pause and beta_create delete my sandbox directly
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/157 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 13. 运行坑 · 来源证据：The sandbox was not found
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：The sandbox was not found
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/e2b-dev/code-interpreter/issues/147 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 14. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter | no_demo; severity=medium
## 16. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter | no_demo; severity=medium
## 17. 能力坑 · 失败模式：capability: Docker images are not versioned - everything is `latest`
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Docker images are not versioned - everything is `latest`
- 对用户的影响：Developers may hit a documented source-backed failure mode: Docker images are not versioned - everything is `latest`
- 证据：failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/150 | Docker images are not versioned - everything is `latest`
## 18. 运行坑 · 失败模式：performance: The sandbox was not found
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: The sandbox was not found
- 对用户的影响：Developers may hit a documented source-backed failure mode: The sandbox was not found
- 证据：failure_mode_cluster:github_issue | https://github.com/e2b-dev/code-interpreter/issues/147 | The sandbox was not found
## 19. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter | issue_or_pr_quality=unknown
## 20. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | github_repo:770633006 | https://github.com/e2b-dev/code-interpreter | release_recency=unknown
## 21. 维护坑 · 失败模式：maintenance: @e2b/code-interpreter-python@2.8.0
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-python@2.8.0
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-python@2.8.0
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-python%402.8.0 | @e2b/code-interpreter-python@2.8.0
## 22. 维护坑 · 失败模式：maintenance: @e2b/code-interpreter-template@0.4.0
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.0
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.0
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.0 | @e2b/code-interpreter-template@0.4.0
## 23. 维护坑 · 失败模式：maintenance: @e2b/code-interpreter-template@0.4.1
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.1
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.1
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.1 | @e2b/code-interpreter-template@0.4.1
## 24. 维护坑 · 失败模式：maintenance: @e2b/code-interpreter-template@0.4.2
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.2
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.2
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.2 | @e2b/code-interpreter-template@0.4.2
## 25. 维护坑 · 失败模式：maintenance: @e2b/code-interpreter-template@0.4.3
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter-template@0.4.3
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter-template@0.4.3
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter-template%400.4.3 | @e2b/code-interpreter-template@0.4.3
## 26. 维护坑 · 失败模式：maintenance: @e2b/code-interpreter@2.6.0
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @e2b/code-interpreter@2.6.0
- 对用户的影响：Upgrade or migration may change expected behavior: @e2b/code-interpreter@2.6.0
- 证据：failure_mode_cluster:github_release | https://github.com/e2b-dev/code-interpreter/releases/tag/%40e2b/code-interpreter%402.6.0 | @e2b/code-interpreter@2.6.0