Agent V2 sends uploaded images through shell download instead of native multimodal input

快速结论：这是在 Dify Agent V2（Agent App）中上传图片后，系统没有将图片作为原生多模态输入发送给支持 vision 的模型，而是把图片转成文本指令并让 Agent 通过 shell 命令（dify-agent file download）去下载文件，导致多出不必要的工具调用、延迟和潜在的下载失败。优先排查：检查 AgentAppGenerator 路径是否已根据模型 schema 的 ModelFeature.VISION 做多模态路由，以及该修复是否已合入你使用的 Dify 版本。

适用环境：Self Hosted（源码构建），Dify 版本为 main 分支 commit e577c007a0（以及相近版本）。涉及组件：API、Web、Worker、Plugin Daemon、Sandbox、独立 dify-agent 后端。

最快修复方案：暂无确认的一步修复方案。截至 Issue 讨论时间（2026-09-07 关闭），没有任何已合并或进行中的 PR 覆盖“将 vision 图片作为结构化多模态内容发送”这条路径；Agent V2 仍会将所有上传图片文本化为 shell 下载指令。官方需在 API 侧（AgentAppGenerator/AgentAppRuntimeRequestBuilder）解析文件、检查 ModelFeature.VISION 并填充 user_files 字段，同时在 dify-agent 侧重新启用 dify.user_prompt 层，这尚未实现。

注意事项：已有相关修复只处理了相邻问题，未触及 vision 原生路由：PR #40586（已合并，修复前端在 supportVision=false 时丢弃非图片附件）；PR #40889（进行中，将文件映射解析为 File 实体用于 MessageFile 持久化，但明确仍让后端只消费文本 prompt 定位器）；PR #41135（进行中，仅增加配置 UI 对 vision 能力的感知）。切勿依赖这些 PR 来解决本问题。

问题场景

在从源码自托管的 Dify 环境中启用 Agent V2，并创建一个 Agent App。选择一个模型 schema 声明了 vision 功能的 LLM，在聊天中上传图片并让 Agent 描述或检查该图片。检查 Agent trace 以及发送到 Agent Backend 的请求时，会发现上传的图片并未作为结构化多模态内容发送给模型，而是被转换成了文本指令块，促使 Agent 执行 shell 下载命令。

报错原文

User provided files: use dify-agent file download with the listed transfer_method and reference/url to get the files and investigate them
[{"transfer_method":"local_file","reference":"dify-file-ref:..."}]

Agent 随后可能执行类似命令：

dify-agent file download local_file "dify-file-ref:..."

原因分析

可能原因：当前 Agent App 的请求生成器路径存在架构性缺口。上传的文件只以 prompt_file_mappings 形式传递，_append_prompt_file_mappings() 方法无条件将所有上传文件文本化为“User provided files: use dify-agent file download …”指令块，并拼接到每次轮询的 query 文本中。在该路径的 AgentBackendAgentAppRunInput 构建过程中，没有检查所选模型 schema 是否具备 ModelFeature.VISION，request_builder.py 只通过 PromptLayerConfig 层发出纯字符串 user_prompt，因此模型后端从未收到原生多模态图片内容。

值得注意的是，Issue 中提议的正确实现边界（解析文件、检查 VISION、结构化发送图片、保留不支持文件和模型的降级方案）曾短暂存在于 PR #37926，该 PR 添加了 dify.user_prompt 层（DifyUserPromptLayerConfig / DifyUserPromptFileConfig），将上传文件以 pydantic-ai BinaryContent 形式携带并加入了 user_files 字段，且日志中会脱敏 base64_data。但当前 request_builder.py 已不再包含 user_files 字段，也未在 build_for_agent_app() 中使用该层——即 dify-agent 侧存在 BinaryContent 路径，但 API 侧未接线。

环境排查

确认 Dify 版本是否包含 commit e577c007a0 或处于该时间段的 main 分支。
确认所选 Agent App 模型的 model schema 确实声明了 vision feature（ModelFeature.VISION）。
检查 Agent trace，确认生成请求中是否包含 files=[] 且仅携带 prompt_file_mappings。
检查后端请求 user_prompt 是否是纯字符串，而非结构化多模态内容。
检查 api/clients/agent_backend/request_builder.py 是否还存在 user_files 字段以及 dify.user_prompt 层配置。
参考：PR #40586（已合并）、PR #40889（进行中）、PR #40889（进行中）、PR #41135（进行中）——这些仅处理相邻问题，不能作为修复依赖。

解决步骤

确认当前使用的 Dify 版本是否仍存在此问题——查看 api/core/app/apps/agent_app/app_generator.py 中 AgentAppGenerateEntity 是否保留 files=[]，且仅保留 prompt_file_mappings。
若确认为旧版本，可尝试升级到更新版本，并关注官方是否合入针对 ModelFeature.VISION 路由的修复（截至 Issue 关闭时尚未合并/开放）——官方需在 AgentAppGenerator/AgentAppRuntimeRequestBuilder 侧解析文件为 File 对象、检查 ModelFeature.VISION 并填充 user_files 字段。
在 dify-agent 侧，需在 AgentBackendRunRequestBuilder.build_for_agent_app() 中重新启用 dify.user_prompt 层，使 URL 图片可转换为 ImageUrl、内联图片可转换为 BinaryContent。
在官方修复之前，可优先尝试的方式：在 Agent App 的编排或应用层，对支持 vision 的模型单独走非 Agent V2 的对话/聊天流程（如 Chatflow/Agent 旧版），看是否走原生多模态输入；或在使用 Agent V2 上传前将图片通过外部工具转成公网 URL 再粘贴文本链接（仅绕过路径，并非官方推荐）。
如果你需要不依赖 Sandbox 与 Agent Stub 网络通道，可将图片内容在下发前预置为 Base64 并走对话上下文（取决于模型能力），但此方法未在 Issue 中得到验证。

验证方法

检查 Agent App 的调试 trace 以及发送至 Agent Backend 的请求负载，确认：不再生成文本化“User provided files: use dify-agent file download …”指令块，files/user_files 中包含结构化文件内容（如 ImageUrl 或 BinaryContent 携带 Base64），且在模型支持 vision 时不再出现 dify-agent file download shell 命令调用，模型能直接基于原生图片内容描述/检查图片。同时确认对不支持 vision 的模型仍保留原 shell 下载定位器的降级逻辑。