为 AI 应用添加代码解释器，需将模型请求的代码执行路由到隔离的沙箱中，该沙箱具有作用域限定的文件、明确的包策略、资源和时间限制、捕获的输出，以及在结果展示或持久化之前由应用端进行审核。模型可以决定何时使用代码有用，但你的应用应掌控执行边界：仅上传任务所需的文件，创建或复用短期沙箱会话，在严格限制下运行 Python，捕获标准输出、标准错误、生成的文件和日志，向模型返回结构化结果，并在工作流完成后清理会话。
代码解释器为 AI 应用带来了什么
代码解释器将语言模型从纯文本助手转变为能使用工具的应用程序，可以计算、转换文件、检查数据、生成图表并生成可审核的产物。应用无需让模型仅凭提示来推理电子表格，而是可以让模型编写 Python 代码，针对上传的文件运行，检查输出，并解释结果。
有用的模式不是“让模型运行任何东西”。有用的模式是受控执行。你的应用接受用户任务，让模型请求一个工具调用（例如 run_python），然后在沙箱内执行该请求，而不是在主应用进程中执行。沙箱成为临时文件、包安装、脚本、图表和日志的工作台。
代码解释器功能在以下场景尤其有用：
- CSV、Excel、JSON 和日志分析
- 根据上传数据生成图表
- 格式转换和数据清洗
- 需要精确计算的数学和模拟任务
- 需要先测试再让模型解释的代码片段
- 多步骤 Agent 工作流，其中一步的输出成为下一步的输入
它们不适合需要不受限制的生产凭证、对私有系统的长期访问或没有用户可见审计追踪的静默执行的任务。如果结果可能影响资金、基础设施、安全或访问控制，请在沙箱产生任何副作用之前添加审核关卡。
参考架构
一个实用的代码解释器架构包含五个部分：
| 层 | 职责 | 常见设计选择 |
|---|---|---|
| 用户界面 | 上传文件、显示进度、展示产物、请求批准 | 将上传的文件限定在当前对话或项目范围内 |
| 应用服务器 | 验证用户身份、执行策略、创建沙箱会话、存储日志 | 切勿将原始沙箱凭证暴露给浏览器 |
| 模型编排 | 决定何时调用代码工具并总结结果 | 使用结构化工具调用，而非解析自由文本 |
| 沙箱运行时 | 执行 Python、保存临时文件、安装允许的包 | 在资源、超时和清理控制下运行 |
| 产物存储 | 保存已批准的输出，如图表、CSV、报告和日志 | 仅存储应用或用户已接受的输出 |
模型不应直接控制基础设施。它应请求一个工具调用。你的应用决定该工具调用是否被允许、附加了哪些文件、允许运行多长时间、哪些包可用以及返回哪些输出。
这种分离使模型保持有用，同时不将其作为安全边界。
实现流程
一个强大的实现流程在代码执行之前就开始了。
1. 接受用户任务和文件
当用户上传文件时，将其存储在应用级别的文件记录下，包含所有者、工作空间、内容类型、大小和保留策略。不要立即将用户账户中的每个文件都暴露给解释器。沙箱应仅接收当前任务所需的文件。
例如，用户可能要求：
“分析这个 CSV，找出主要的收入驱动因素，并返回一个图表和简短的解释。”
你的应用可以将上传的 CSV 作为可用文件附加到模型的下一次交互中，但实际的文件字节应仅在代码执行被批准后才移入沙箱。
2. 让模型请求工具调用
定义一个狭窄的工具接口。一个典型的初版只需要几个工具：
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}
保持模式明确。模型应声明代码、输入文件、预期输出和超时请求。应用可以缩短超时时间、拒绝未知文件或阻止与策略冲突的命令。
3. 创建或复用沙箱会话
对于一次性助手响应，创建一个全新的沙箱会话，上传输入文件，运行代码，收集结果，然后终止会话。对于类似笔记本的用户体验，保持会话在当前对话期间存活，以便后续的单元格可以重用之前的变量和文件。
短期会话更容易推理。有状态会话对于分析任务更符合人体工程学。有意识地选择，并在存在状态时向用户显示。
4. 执行 Python 并捕获结果
通过沙箱执行 API 或你自己的沙箱内工作进程运行代码。捕获结构化的执行输出：
{
"status": "success",
"stdout": "Loaded 12,448 rows\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}
将此结构化结果返回给模型。模型随后可以解释发生了什么，引用生成的文件，并询问用户是否想要再次尝试。
5. 将结果返回给用户
除非出现故障，否则不要强迫用户阅读原始日志。一个好的界面会显示答案、生成的图表或文件，以及一个关于已执行代码的小提示。提供一个可展开的执行日志以供审核。
对于失败的执行，显示简洁的错误信息，并让模型修改代码。除非用户正在调试，否则避免将冗长的回溯信息转储到主聊天中。
处理文件、输出和生成的产物
文件处理是许多代码解释器项目变得混乱的地方。将输入和输出视为独立的对象。
输入文件应复制到沙箱中，路径稳定且经过清理。避免保留包含空格、shell 字符或嵌套目录的用户提供的路径名。在应用状态中维护一个从显示名称到沙箱路径的映射。
生成的文件应在成为可下载产物之前进行扫描和分类。图表图像、清理后的 CSV、JSON 摘要或 PDF 报告可能可以直接安全呈现。生成的脚本、可执行文件或存档则需要更严格的处理。
对于图表生成，要求模型显式保存图像文件，而不仅仅依赖内联显示。对于数据分析，要求生成机器可读的摘要文件以及自然语言解释。这为你的应用提供了可验证和存储的稳定内容。
一个有用的产物策略如下所示：
| 产物类型 | 默认处理方式 |
|---|---|
.png、.jpg、.webp、.svg 图表 |
在 UI 中预览，经过大小和类型检查后 |
.csv、.json、.xlsx 数据输出 |
提供下载并总结更改 |
.txt、.md、.pdf 报告 |
根据大小预览或下载 |
.py、.sh、二进制文件、存档 |
不自动运行或自动打开；需要明确审核 |
如果你的应用支持持久化项目，请将已接受的产物存储在沙箱之外。沙箱应保持可丢弃状态。
设置包和网络策略
大多数代码解释器工作流需要诸如 pandas、NumPy、matplotlib、seaborn、scikit-learn 或 openpyxl 等包。问题是包是预安装、按需安装还是构建到自定义沙箱模板中。
预安装的包使执行可预测。按需安装很灵活，但可能减慢任务速度并引入依赖漂移。一旦你了解了常见工作负载，自定义模板通常是生产环境的最佳路径。
在启动前设置包策略：
- 哪些包始终可用
- 模型是否可以请求安装包
- 安装是否可以访问公共包索引
- 是否需要版本锁定
- 安装允许运行多长时间
- 是否允许编译包或原生包
网络策略同样重要。许多数据处理任务在上传文件后不需要互联网访问。如果工作流确实需要外部 API，请通过应用批准的工具路由凭证，而不是将广泛的秘密直接放入沙箱。默认情况下，模型不应接收不受限制的环境变量。
应用限制、日志、清理和审核
代码解释器是一个生产级功能，而不是演示单元格运行器。从一开始就为其设置限制。
最低控制应包括：
- 每个单元格或工具调用的最大执行时间
- 标准输出和标准错误的最大输出大小
- 最大产物大小和文件数量
- 适合任务的 CPU 和内存限制
- 允许预览和下载的文件扩展名
- 每个用户和每个工作空间的并发限制
- 临时会话和文件的清理规则
日志应回答三个问题：谁请求了执行、运行了什么代码、产生了什么输出。存储足够的信息以调试和审计工作流，但避免保留私有上传数据超过产品策略要求的时间。
人工或用户审核是最终控制。对于低风险分析，审核可能意味着用户在下载图表前看到它。对于可以更新工单、写入数据库或调用外部 API 的 Agent 工作流，审核应在副作用发生之前进行，而不是之后。
Novita Agent Sandbox 的定位
Novita Agent Sandbox 专为需要隔离运行时环境的 AI Agent 设计，用于代码执行、浏览器工作流、类计算机使用任务、评估、强化学习环境和长时间运行的工作流。对于代码解释器功能，这意味着沙箱可以作为执行层，而你的应用仍负责用户认证、模型编排、文件策略、审核和产品特定的保留。
Novita 的沙箱文档包括用于在沙箱中读取、写入、上传、下载和监视文件的文件系统工作流。这些功能直接映射到代码解释器的需求：将用户文件移入执行环境，让代码生成图表或转换后的数据，然后将选定的输出带回应用。请参阅 Novita 沙箱文件系统文档 了解当前的文件操作概述。
如果你的解释器超越了简单的 Python 运行器，自定义沙箱模板可以帮助标准化依赖项和运行时设置。当每个会话都需要相同的分析栈、内部命令行工具或项目特定库时，这很有用。从一个小型的允许包集开始，一旦工作负载稳定，将重复的设置移入模板。
将 Novita 特定的集成决策与通用架构分开。你的代码解释器仍然需要应用级别的策略来处理文件可见性、包安装、网络访问、日志保留和审核。沙箱提供受控的运行时；你的产品定义如何使用该运行时。
评估清单
在发布之前，使用真实工作流和对抗性提示测试该功能。
| 问题 | 需要验证的内容 |
|---|---|
| 用户能否上传正确的文件？ | 文件大小、类型检查、所有者检查和清晰的错误消息 |
| 模型能否干净地请求执行？ | 包含代码、输入、预期输出和超时的结构化工具调用 |
| 沙箱作用域是否正确？ | 只有批准的文件和环境变量可用 |
| 包是否可预测？ | 常用包正常工作，被拒绝的包清晰失败，安装有限制 |
| 输出是否可用？ | 图表渲染、文件下载、摘要与生成的产物匹配 |
| 失败是否可恢复？ | 捕获回溯，模型可以修改代码，用户看到简洁的错误 |
| 限制是否得到执行？ | 无限循环、巨大输出、内存密集型任务和长时间安装被终止 |
| 是否内置了审核？ | 用户可以在重要副作用发生前检查代码、日志和产物 |
| 清理是否可靠？ | 临时文件和会话按计划删除或过期 |
最好的首次发布通常是狭窄的：Python 执行、一个小型包集、文件上传、图表和可下载文件、明确的限制以及执行日志。只有在基本循环可观察且可靠之后，才添加更广泛的包安装、持久会话、外部 API 访问和 Agent 副作用。
结论
当模型可以请求执行，但你的应用控制沙箱、文件、限制和审核步骤时，代码解释器效果最佳。从一个狭窄的 Python 工具开始，保持输入和输出明确，只有在流程稳定后才进行扩展。
常见问题
添加代码解释器最安全的方式是什么？
使用隔离的沙箱，限定输入文件的范围，限制运行时间和内存，并返回结构化输出而不是原始 shell 访问。
模型应该控制包安装吗？
仅在你定义的策略内。许多应用从固定的包集开始，如果工作负载需要，稍后添加安装。
所有代码解释器任务都需要网络访问吗？
不需要。一旦用户文件上传，许多分析工作流可以完全离线工作，这使执行模型更简单。
执行后用户应该看到什么？
结果、生成的产物以及简洁的日志或错误摘要，并可以选择检查代码或重新运行任务。
