docs/features/agents/code_interpreter.md
代码解释器（Code Interpreter）是 GPT Academic 中一项强大的智能体功能。它的独特之处在于，您只需要用自然语言描述想要完成的任务，AI 就会自动生成相应的 Python 代码并立即执行，将执行结果返回给您。这种"需求描述 → 代码生成 → 自动执行"的工作流程，让您无需编写任何代码就能完成图像处理、数据转换、文件操作等各种任务。
代码解释器的运作分为三个核心阶段。首先是需求理解阶段：当您上传文件并用自然语言描述任务后，系统会将您的需求和文件类型信息发送给 AI 模型。AI 会分析您想要完成什么操作，然后生成能够处理该文件的 Python 函数。
接下来是代码验证阶段：AI 生成的代码会被解析和检查。系统会尝试导入代码中使用的依赖包，确保代码结构正确且可执行。如果初次生成的代码存在问题，系统会自动将错误信息反馈给 AI，让它进行修正。这个过程最多会重试 3 次，以确保生成可用的代码。
最后是安全执行阶段：验证通过的代码会在一个独立的子进程中执行。这种设计既隔离了潜在风险，又设置了 15 秒的执行时间限制，防止代码陷入死循环。执行完成后，结果（可能是生成的文件或计算结果）会返回到主界面供您查看和下载。
这种设计让代码解释器成为一个灵活的通用工具——只要能用 Python 实现的任务，理论上都可以通过自然语言描述来完成。
代码解释器特别适合处理以下类型的任务：
图像处理：裁剪图片、调整尺寸、转换格式、添加滤镜效果、提取颜色通道、生成缩略图等。例如"把图片的下半部分裁剪掉"或"将这张图片转换为灰度图"。
数据转换：CSV 与 Excel 互转、JSON 格式化、数据清洗、简单的统计分析等。例如"把这个 CSV 文件转换成 Excel 格式"或"统计这个数据文件中每列的平均值"。
文件操作：批量重命名、格式转换、内容提取等。例如"提取这个 PDF 的文字内容"或"把这个文档的所有图片提取出来"。
简单计算：数学计算、公式求解、数据可视化等。例如"根据这些数据绘制一个折线图"。
!!! info "能力边界" 代码解释器的能力取决于两个因素：AI 模型的代码生成能力，以及系统中已安装的 Python 依赖包。对于需要特殊依赖包的任务（如深度学习模型推理），可能会因缺少依赖而执行失败。常见的数据处理和图像处理任务通常都能顺利完成。
使用代码解释器的标准流程如下：
上传文件：将需要处理的文件拖拽到界面上方的文件上传区域。支持各种常见文件格式，如图片（PNG、JPG）、数据文件（CSV、Excel）、文本文件等
描述任务：在输入框中用自然语言描述您想对这个文件做什么。描述要尽量具体明确
选择插件：在函数插件区的智能体分类中，找到并点击 动态代码解释器（CodeInterpreter）
等待执行：系统会依次进行代码生成、验证和执行。整个过程通常在 10-30 秒内完成
获取结果：执行结果会显示在对话区，如果生成了新文件，文件会出现在下载区
任务描述的清晰程度直接影响 AI 生成代码的质量。以下是一些有效的描述方式：
裁剪图像，保留下半部分
交换图像的蓝色通道和红色通道
将 CSV 文件转换为 Excel 表格
统计文本文件中每个单词出现的次数，并按频率排序
描述时应注意：明确指出要对文件做什么操作；如果有具体的参数（如尺寸、比例），最好一并说明；避免过于复杂或歧义的表达。
当您点击插件按钮后，系统会在对话区实时显示执行进度：
| 阶段 | 显示内容 | 说明 |
|---|---|---|
| 启动 | "正在启动: 插件动态生成插件" | 开始处理请求 |
| 文件检测 | "当前文件处理列表: [文件路径]" | 显示检测到的上传文件 |
| 代码生成 | AI 生成的 Python 代码 | 展示 AI 编写的处理代码 |
| 代码验证 | "正在验证上述代码的有效性" | 检查代码是否可执行 |
| 执行中 | "开始创建新进程并执行代码" | 在隔离环境中运行代码 |
| 完成 | 执行结果或生成的文件 | 显示最终结果 |
如果代码生成或执行失败，系统会显示错误信息并自动重试。重试过程中，AI 会参考之前的错误来改进代码。如果 3 次重试后仍然失败，系统会显示详细的错误追踪信息，帮助您了解问题所在。
代码解释器虽然功能强大，但在设计上充分考虑了安全性：
进程隔离：AI 生成的代码在独立的子进程中执行，与主应用完全隔离。即使代码出现异常或崩溃，也不会影响 GPT Academic 的正常运行。
时间限制：每次代码执行有 15 秒的超时限制。如果代码运行时间超过这个限制（例如陷入死循环），进程会被强制终止。
文件范围：代码只能访问您上传的文件和系统的临时目录。它无法读取或修改您计算机上的其他文件。
依赖控制：代码只能使用系统已安装的 Python 包。这在一定程度上限制了代码的能力，但也防止了恶意代码的执行。
!!! warning "使用建议" 尽管有上述安全机制，我们仍建议您：
- 不要用于处理包含敏感信息的文件
- 查看 AI 生成的代码，了解它要执行的操作
- 对于重要文件，先在备份上测试
???+ question "提示'没有发现任何近期上传的文件'" 代码解释器需要您先上传文件才能使用。请确保：
1. 文件已成功上传（上传区会显示文件名）
2. 上传后不要等待太久再点击插件（超过 5 分钟的上传会被视为过期）
3. 先点击上传区确认文件已就绪，再描述任务
???+ question "代码生成失败，多次重试后仍然报错" 这可能是因为：
1. **任务描述不清晰**：尝试用更简单、更明确的语言重新描述
2. **任务过于复杂**：将复杂任务拆分成多个简单步骤
3. **缺少必要的依赖包**：某些特殊功能需要额外安装依赖
4. **模型能力限制**：尝试切换到更强的模型（如 GPT-4o）
???+ question "执行超时，提示'进程被终止'" 代码执行有 15 秒的时间限制。如果您的任务超时：
1. 尝试处理更小的文件
2. 将任务简化（如处理图片的一部分而非全部）
3. 某些耗时操作可能不适合用代码解释器完成
???+ question "生成的结果不符合预期" AI 生成的代码可能没有完全理解您的意图。建议：
1. 查看对话区显示的代码，了解它实际做了什么
2. 在任务描述中添加更多细节
3. 尝试用不同的方式描述同一个任务
???+ question "图片处理后颜色异常" 这通常是颜色通道顺序（RGB vs BGR）的问题。可以在任务描述中明确指出：
```
处理图片时请保持 RGB 颜色顺序
```
代码解释器与 GPT Academic 的其他功能有所不同，了解这些差异有助于选择合适的工具：
| 特性 | 代码解释器 | 预设插件（如图像处理插件） |
|---|---|---|
| 灵活性 | 高 - 可处理任意任务 | 低 - 只能完成预设功能 |
| 可靠性 | 中 - 依赖 AI 代码生成质量 | 高 - 经过测试的稳定代码 |
| 使用门槛 | 低 - 自然语言描述 | 低 - 点击按钮即可 |
| 适用场景 | 一次性、非标准任务 | 重复性、标准化任务 |
简而言之，如果已有现成的插件能完成您的任务，优先使用现成插件；如果没有合适的插件，或者您有特殊的自定义需求，代码解释器是一个灵活的补充选择。