跳到主要内容

文件输入

workflow-code 支持通过 executor params 声明文件输入。Desktop、server 和外部调用会先上传文件，workflow 中再通过 file reference 解析文件内容。

file param​

params: [
  {
    name: "images",
    flag: "--images",
    type: "file",
    multiple: true,
    accept: ["image/png", "image/jpeg", "image/webp"],
    format: "json",
    required: false,
    description: "图片附件。",
  },
]

文件 param 的 value 会被序列化为 JSON 字符串传给 createInput。

FileInputNode​

const imageInputNode = workflow.createFileInputNode({
  name: "images",
  accept: ["image/png", "image/jpeg", "image/webp"],
  multiple: true,
});

const images = await workflow.runNode(imageInputNode, input.images, context);
const imageParts = await Promise.all(images.map((file) => file.toLLMImagePart()));

createFileInputNode 会通过 context.files 解析引用，返回 WorkflowResolvedFile[]。

WorkflowResolvedFile​

解析后的文件支持：

file.readBuffer()
file.readBase64()
file.readDataUrl()
file.toLLMImagePart()
file.toJSON()

toLLMImagePart() 只接受图片文件；非图片会抛出输入校验错误。

Runtime 生成文件​

workflow 运行中生成截图、导出物或其它文件时，使用 context.files.createFile(...)：

const file = await context.files?.createFile?.({
  name: "frame.png",
  mimeType: "image/png",
  buffer,
  kind: "image",
});

server/web 运行会自动注入 server 管理文件存储，返回的引用可用 /api/workflows/files/{fileId} 打开。Desktop/CLI 本地运行在已连接 server 时会代理到同一个 server 文件 API；未连接 server 时调用会抛错，不会把 运行生成文件落到本地 store。输入附件的本地解析仍继续通过 context.files.resolveFile(...) 工作。

存储建议​

不要把 base64 文件内容保存进 KV 或会话历史。需要跨轮复用时，保存 file.toJSON() 返回的引用元数据。

workspace/workflow/gpt-image 示例使用同一套 file param 流程接收一张或多张参考图： 有当前图片或最近会话历史中存在输入图片引用时，workflow 会解析为 WorkflowResolvedFile[] 并调用图片编辑；完全没有图片上下文时才调用图片生成。该示例开启 conversation 模式，跨轮只把 用户提示、生成摘要和 file.toJSON() 引用元数据写入会话历史；后续轮次会尽力解析最近输入图片 引用并作为上下文参考图传给图片编辑，示例本地最多保留 16 张图片输入。生成结果作为 Markdown output item 中的 data:image/...;base64,... 预览返回，也不把生成图 base64 写入会话 KV， 因此生成图本身不会自动成为下一轮图片输入。需要跨页面或知识库复用生成文件时，应改用 context.files.createFile(...) 生成 server file reference。

Desktop 与 server 行为​

  • Desktop 本地运行会把附件上传到本地文件 store，storage 字段是 local。
  • server 管理接口 POST /api/workflows/{name}/files 会保存运行文件，storage 字段是 server。
  • runtime 生成文件使用同一套 server 文件引用；Desktop/CLI 已连接 server 时自动上传，未连接时调用报错。
  • GET /api/workflows/files/{fileId} 可读取或下载 server 文件。

如果 conversation workflow 启用了 conversation.defaultInput.attachments，共享 composer 里的图片/文件粘贴、拖拽和上传也复用同一套 file reference 协议。宿主会先把 浏览器/Electron File 写入本地或 server managed file store，再把引用写回固定参数 --images / --files；workflow 侧继续按普通 file param 或 workflow.parseConversationDefaultInputArgs(args) 解析即可。

MCP 文件参数​

本地 stdio MCP 的 file 参数直接接收绝对路径，multiple file 接收绝对路径数组。host 会校验普通文件和 50 MB 上限后导入本地 managed-file store；不接受相对路径、URL 或 Base64。

Server Streamable HTTP MCP 的 file 参数接收 { "id": "<file-id>" }，multiple file 接收该对象数组。先调用 POST /api/workflows/{workflowName}/files 上传文件，再只把响应中的 ID 传给 tool。Server 会重新读取权威 metadata 并校验文件属于当前项目，不信任调用方提交的名称、类型或路径。完整示例见 Server MCP 指南。

外部 API 文件​

外部 Dify 风格 /workflows/run 接收 files 字段并保存到 run metadata。具体 workflow 是否使用文件，需要由 inputs 或 args 与 executor params 对齐。