​
文件输入

workflow-code 支持通过 executor params 声明文件输入。App、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} 打开。App/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。

​
App 与 server 行为

  • App 本地运行会把附件上传到本地文件 store，storage 字段是 local。
  • server 管理接口 POST /api/workflows/{name}/files 会保存运行文件，storage 字段是 server。
  • runtime 生成文件使用同一套 server 文件引用；App/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) 解析即可。

​
外部 API 文件

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

​
追踪

本文档首版由 issue #32 记录。runtime 生成文件由 issue #86 记录。文件行为对齐 core/files/index.ts、core/files/remote.ts、core/node/file-input/index.ts 和 server/src/routes/api.ts。