Dify代码执行结果如何配置为文件（File）格式输出？

Question

**常见技术问题：** 在Dify中，当使用代码解释器（Code Interpreter）节点执行Python脚本（如生成CSV、PDF或Excel报表）时，如何将执行结果（如`pandas.DataFrame.to_csv()`生成的字节流）正确配置为可下载的文件（File）格式输出？用户常误以为直接`print()`或`return`文件路径即可触发前端下载，但实际上Dify仅支持通过特定结构返回二进制内容及元数据——若未按规范构造`{"type": "file", "data": base64_str, "name": "report.csv"}`格式的JSON响应，系统将忽略文件意图，仅显示文本输出。此外，本地文件路径（如`./output.xlsx`）无法被Dify沙箱环境外部访问，且未设置`Content-Type`或编码错误会导致文件损坏。如何在保证安全沙箱约束的前提下，正确序列化、Base64编码并声明MIME类型，是实现可靠文件输出的关键难点。

Answer 1

```html

一、常见技术问题：Dify代码解释器中文件输出失效的典型现象

• 用户调用 pandas.DataFrame.to_csv() 生成字节流后，直接 print(csv_bytes) —— 前端仅显示乱码文本，无下载按钮；
• 使用 return "./output.csv" 或 os.path.abspath("output.csv") —— Dify沙箱禁止外部路径访问，返回空响应或报错；
• 手动写入文件（df.to_csv("report.csv")）后尝试读取并返回 —— 若未以 rb 模式打开、未 Base64 编码、未声明 name 和 type 字段，系统视作普通字符串输出；
• Base64 编码时忽略 utf-8 与 bytes 类型转换（如对 str 直接 b64encode），导致解码失败、Excel 打开报“文件损坏”；
• PDF/Excel 文件未指定正确 MIME type（如 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet），浏览器无法识别格式。

二、底层机制解析：Dify沙箱的文件输出契约

Dify 的 Code Interpreter 节点运行于隔离容器中，其输出通道仅接受严格结构化的 JSON 响应。系统通过以下字段识别文件意图：

字段名	类型	必填	说明
type	string	✅	必须为 "file"，否则降级为 text 输出
data	string	✅	Base64 编码后的二进制内容（非路径、非原始 bytes）
name	string	✅	含扩展名（如 "sales_q3.xlsx"），决定下载文件名及 MIME 推断
mime_type	string	⚠️建议	显式声明可规避浏览器 MIME sniffing 错误（尤其对 CSV/PDF）

三、标准化解决方案：四步安全文件构造法

1. 内存生成：全程使用 io.BytesIO，杜绝磁盘 I/O（沙箱禁写持久化路径）；
2. 二进制序列化：CSV → df.to_csv(..., index=False).encode("utf-8")；Excel → with pd.ExcelWriter(buf, engine="openpyxl") as w: df.to_excel(w...)；
3. Base64 安全编码：调用 base64.b64encode(buf.getvalue()).decode("ascii")（注意 .decode("ascii") 得到字符串）；
4. 结构化返回：构造 dict 并 return json.dumps({...})（Dify 自动解析 JSON，无需手动 print）。

四、实战代码模板（支持 CSV / Excel / PDF）

import pandas as pd
import base64
import io
import json

# 示例数据
df = pd.DataFrame({"产品": ["A", "B"], "销量": [120, 89]})

# ✅ 正确：CSV 内存生成 + Base64
csv_buffer = io.BytesIO()
df.to_csv(csv_buffer, index=False, encoding="utf-8")
csv_buffer.seek(0)
csv_b64 = base64.b64encode(csv_buffer.read()).decode("ascii")

# ✅ 正确：Excel（.xlsx）
xlsx_buffer = io.BytesIO()
with pd.ExcelWriter(xlsx_buffer, engine="openpyxl") as writer:
    df.to_excel(writer, index=False, sheet_name="Report")
xlsx_buffer.seek(0)
xlsx_b64 = base64.b64encode(xlsx_buffer.read()).decode("ascii")

# ✅ 正确：PDF（需 reportlab 或 matplotlib）
from reportlab.pdfgen import canvas
pdf_buffer = io.BytesIO()
p = canvas.Canvas(pdf_buffer)
p.drawString(100, 750, "销售报表")
p.showPage()
p.save()
pdf_buffer.seek(0)
pdf_b64 = base64.b64encode(pdf_buffer.read()).decode("ascii")

# 统一返回结构（Dify 识别的关键！）
response = {
    "type": "file",
    "data": csv_b64,  # 可替换为 xlsx_b64 / pdf_b64
    "name": "report.csv",
    "mime_type": "text/csv"
}
return json.dumps(response)  # ⚠️ 必须 return 字符串形式 JSON

五、关键避坑指南与验证流程

graph TD
    A[生成DataFrame] --> B{选择输出格式}
    B -->|CSV| C[.to_csv → encode utf-8 → BytesIO]
    B -->|Excel| D[ExcelWriter → BytesIO]
    B -->|PDF| E[reportlab/matplotlib → BytesIO]
    C & D & E --> F[buf.getvalue → base64.b64encode → .decode ascii]
    F --> G[构造 dict：type/file, data/base64, name/xxx.ext]
    G --> H[return json.dumps dict]
    H --> I[Dify 前端自动渲染下载按钮]
    I --> J[用户点击 → 浏览器按 mime_type 处理]

六、扩展能力：动态 MIME 映射表

为提升健壮性，建议内置扩展名→MIME 映射（避免硬编码错误）：

MIME_MAP = {
    ".csv": "text/csv",
    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    ".xls": "application/vnd.ms-excel",
    ".pdf": "application/pdf",
    ".png": "image/png",
    ".jpg": "image/jpeg"
}

def get_mime(name):
    ext = os.path.splitext(name.lower())[1]
    return MIME_MAP.get(ext, "application/octet-stream")

# 使用示例
response["mime_type"] = get_mime(response["name"])

```