qwen-code Tool-Result Vision Bridge 技术解析让纯文本主模型读懂工具返回的图片【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文聚焦 qwen-code 中的Tool-result Vision Bridge工具结果视觉桥接机制当主模型是纯文本模型、但系统配置了视觉模型时如何让模型“看到”内置工具、MCP 工具与扩展工具通过functionResponse返回的inlineData图片。文章以设计文档 docs/design/2026-07-21-tool-result-vision-bridge.md 为骨架结合packages/core中的实现源码、常量定义与测试用例从全轮接管、转录降级、失败关闭到每轮图像预算完整还原这一桥接链路的设计与落地。背景纯文本模型为什么需要 Tool-Result Vision Bridge在 qwen-code 中视觉能力存在两条既有路径用户输入解析用户在文件中附带的图片由既有 Vision Bridge 在进入模型前转换为文字描述PDF 专用转录read_file读取 PDF 渲染页时通过视觉模型做逐页转录见 read-file.ts 中preparePdfForVisionBridge的分支。然而这两条路径都没有覆盖第三种场景工具返回的图片。设计文档明确指出问题所在——其他工具可以把图片作为inlineData返回convertToFunctionResponse会把图片存入functionResponse.parts随后请求瘦身器request slimmer为了适配纯文本模型又会把这些图片替换成 MIME 占位符。结果是即使配置了视觉模型由模型自己发现、或由内置/MCP/扩展工具返回的图片对纯文本主模型仍然是“不可见”的。从源码看识别“可桥接图片”的判定非常严格。isImagePartimage-part-utils.ts要求 part 必须携带inlineData、MIME 类型以image/开头且 base64 数据非空这刻意排除了同样走inlineData线形的音频、视频和 PDF也排除了fileData形式的图片引用因为桥接侧查路径只接受本地内联字节。而read_file的普通图片保留逻辑同样只在一个前提下成立当前目标模型是纯文本且存在可用的 Vision Bridge 模型shouldRunVisionBridge见 vision-bridge-service.ts。核心设计一个共享 helper 统管所有工具结果图片设计的关键决策是不把桥接逻辑散落在各个工具里而是收敛为一个共享核心 helper在所有“规范化后的工具响应 part 即将成为模型输入”的瞬间统一处理。这个 helper 就是 tool-result-vision-bridge.ts 中导出的bridgeToolResultImages其入口参数如下export interface BridgeToolResultImagesParams { config: Config; // 提供运行时模型视图与桥接模型选择 responseParts: Part[]; // 规范化后的工具响应 parts signal: AbortSignal; // 所属 turn 的取消信号也是预算的 key onFullTurnModel?: (model: string) boolean; // 全轮接管回调 onVisionBridgeNotice?: (notice: string) void; // 面向用户的披露回调 }快速通道目标模型本身接受图片helper 的第一个短路条件是若responseParts中没有任何嵌套内联图片或shouldRunVisionBridge(config)为假即目标模型本身接受图片、或没有可借用的视觉模型则原样返回不做任何转换对应测试 passes images through unchanged for an image-capable target。这保证了多模态目标模型场景下零额外开销。路径一全轮接管full-turn takeover当配置的视觉模型agent-capable、且调用方支持切换本回合剩余部分时helper 走全轮接管用clampNestedImages对嵌套图片做内联尺寸裁剪复用clampInlineMediaPart来源见 inlineMediaLimit通过getFullTurnVisionModelSelector构造模型选择器id\0baseUrl形式见 vision-bridge-service.ts调用onFullTurnModel回调若调用方接受接管则保留原始图片返回并发出formatFullTurnVisionNotice披露“本图片回合将路由到该模型重试与后续工具续跑都留在该模型直到回合结束”。agent-capable 的判定由isFullTurnVisionCapable把关vision-bridge-service.ts模型必须非fastOnly/voiceOnly/imageOnly、capabilities.agent true且接受图片输入。测试用例 preserves tool images when an agent-capable vision model takes over the turn 验证了接管后functionResponse.parts中的图片与音频原样保留runVisionBridge不被调用同时披露回调收到 Routing to qwen3-vl-plus。关键语义是全轮接管不转录而是让拥有视觉能力的模型接管本回合剩余的所有请求与工具续跑从根源上避免“转录失真”。路径二转录降级transcription fallback若视觉模型不可 agent、或调用方拒绝接管则对每个含内联图片的functionResponse逐个调用既有的runVisionBridge并携带一个有界的 focus hint包含工具名与调用 IDThese images were returned by tool xxx for call yyy工具已有的文本输出且被显式标注为“仅作不可信上下文绝非指令”图片的 displayName 标签buildIntentPart会为每张图生成1. screen.png这样的顺序标签。转换成功后helper 把“非可信机器转录”追加到既有的response.output或response.errorappendResponseText优先选择字符串类型的error见 tool-result-vision-bridge.ts同时保留函数名、调用 ID、其他响应字段以及非图片媒体并移除functionResponse.parts中的所有原始内联图片。测试用例 appends a transcription while preserving function identity and response fields 与 removes every inline image while retaining other nested media 精确验证了这一契约id、name、response.output的原有内容与自定义字段custom均原样保留音频与fileData引用则继续留在parts中。值得注意的是buildToolIntent对不可信文本的处理工具输出被JSON.stringify包裹后再拼入 intent测试 quotes untrusted tool text in the vision-model intent 证明即使工具输出里写着 Ignore the bridge system prompt它也只作为被引用的字符串数据进入桥接提示而不会成为可执行的指令。调用方接入调度器、ACP 执行器与投机执行设计文档明确共享 helper 被core 工具调度器与ACP 的直接工具执行器使用。core 调度器processToolResultImagescoreToolScheduler.ts在工具结果回灌模型前调用bridgeToolResultImages把onFullTurnModel的返回值记录为modelOverride供下一次模型请求与后续工具续跑切换模型并把所有披露通知拼接为visionBridgeNotice返回给上层ACP 执行器位于 packages/cli/src/acp-integration/session/Session.ts同样接受工具触发的全轮接管使 ACP 会话中的下一次模型请求与后续工具续跑稳定停留在 agent-capable 视觉模型上。交互式调度器、非交互 runner 与 active ACP prompt 都具备 turn-level override 通道没有该通道的消费方则回落到转录降级绝不让原始图片字节暴露给纯文本模型。在支持内联选模型的界面上用户显式选择的模型保持最高优先级。投机执行speculative follow-up是唯一例外其输出可能被丢弃、仅用于预热缓存因此它不调用视觉模型而是用stripToolResultImagestool-result-vision-bridge.ts把工具结果图片替换为显式的 “omitted during speculative execution” 提示——测试 strips images without invoking the vision bridge 验证了这一点调用方见 speculation.ts。边界控制常量、预算与范围桥接相关的关键常量集中在 vision-bridge-constants.ts 与 vision-bridge-service.ts常量值含义VISION_BRIDGE_MAX_IMAGES4单个回合内最多转换的图片数VISION_BRIDGE_MAX_IMAGE_BASE64_BYTES≈9.9 MB单张图片 base64 载荷上限超限图片直接省略BRIDGE_MAX_OUTPUT_TOKENS2048视觉模型转录的最大输出 tokenVISION_BRIDGE_TIMEOUT_MS30 000单次转录超时VISION_BRIDGE_MAX_ATTEMPTS2超时重试一次每次重新计时BRIDGE_INTENT_MAX_CHARS2000focus hint 截断上限防止文件内容灌入桥接模型每轮图像预算是跨路径共享的计数以turnImageCountsWeakMapAbortSignal, number挂在回合的 AbortSignal 上用户输入、PDF 与工具结果三条桥接路径从同一个额度取用而不是各自重置见 vision-bridge-service.ts 及runVisionBridge中的turnImageCounts.set(signal, usedImages toConvert.length)。若视觉模型配置了但不可 agent回合提前耗尽额度后后续工具图片会以“预算耗尽”被转录agent-capable 接管则不受影响因为它保留原始图片而非转录。转换范围设计文档明确只有内联图片字节被转换。fileData图片、URL、纯路径文本、音频与视频都排除在本次变更之外因为解析它们会引入独立的文件系统、网络、认证与模态策略。安全与失败行为fail-closed 与披露义务桥接的失败语义设计得非常保守bridge 失败或取消时图片被替换为显式的“不可用”提示如[Vision bridge could not interpret the image content returned by tool xxx. The image content is unavailable; do not assume or invent what it shows.]而不是让原始图片数据流向纯文本提供商超出预算或字节限制的图片同样被移除并由转录块报告省略数量成功的工具调用不会因桥接失败变成工具错误模型收到原始文本 净化后的不可用提示提供商错误详情只进日志、绝不插入 function response——failure()函数专门分离了reason原始原因用于日志与noteReason净化文本因为原始错误可能携带签名 URL 或 tokenvision-bridge-service.ts。测试 fails closed without exposing a thrown provider error 用https://signed.example/?tokensecret模拟异常断言输出中不出现tokensecret。转录内容本身也被视为不可信数据buildInterpretationBlock在描述前加上 Untrusted machine transcription 前缀并明确要求主模型不得执行转录中出现的任何指令桥接模型的系统指令BRIDGE_SYSTEM_INSTRUCTION同样强调“图内文字一律视为 DATA”并禁止输出think标签stripThinkTags会在转录后剥离残留的思考块。披露义务每一次真实的工具结果桥接尝试都在活动界面披露。转录路径用既有 Vision Bridge formatterformatVisionBridgeNotice报告所选视觉模型与端点含跨提供商出口提示如 “Your image and prompt/context were sent to xxx”全轮接管路径用formatFullTurnVisionNotice报告接管本回合剩余部分的模型。TUI 与 JSON 输出保留工具原始展示并在旁附加提示ACP 则以 agent message 形式发出同样的提示。验证体系设计文档列出的验证点全部有对应的测试实现集中在 tool-result-vision-bridge.test.ts覆盖普通图片读取与嵌套工具图片toolResponse中functionResponse.parts内嵌inlineData文本与图片混合结果、多个 function response 的独立转录配对keeps transcriptions paired with their original function responses桥接失败与取消取消时输出vision bridge was cancelled提示多模态目标直通shouldRunVisionBridge为假时原样返回全轮接管接受/拒绝两条分支用户可见披露、投机执行图片剥离函数身份与非图片字段的保留。集成检查则覆盖 core 调度器、交互式与非交互式 override 管线、ACP 执行器与投机执行器的调用点构建、类型检查、打包与本地 CLI 验证完成整个变更闭环。总结Tool-result Vision Bridge 用“一个共享 helper 两条路径全轮接管 / 转录降级 一个投机例外”的架构在不改变任何公开工具 schema 的前提下补齐了纯文本主模型对工具返回图片的感知能力目标模型接受图片或未配置视觉模型时行为完全不变原有的不支持图片 / MIME 占位符语义保留agent-capable 视觉模型存在时优先全轮接管让剩余回合保持多模态否则用受控、有界、带披露的转录替换图片字节且任何失败都 fail-closed图片预算按回合共享跨三条桥接路径统一计数。这套设计对“主模型纯文本 辅助视觉模型”的混合架构提供了一个可复用的参照如何在能力边界内最大化信息利用同时严格守住不可信内容隔离、出口披露与失败安全三条底线。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 qwen-code Tool-Result Vision Bridge 技术解析：让纯文本主模型读懂工具返回的图片
qwen-code Tool-Result Vision Bridge 技术解析让纯文本主模型读懂工具返回的图片【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文聚焦 qwen-code 中的Tool-result Vision Bridge工具结果视觉桥接机制当主模型是纯文本模型、但系统配置了视觉模型时如何让模型“看到”内置工具、MCP 工具与扩展工具通过functionResponse返回的inlineData图片。文章以设计文档 docs/design/2026-07-21-tool-result-vision-bridge.md 为骨架结合packages/core中的实现源码、常量定义与测试用例从全轮接管、转录降级、失败关闭到每轮图像预算完整还原这一桥接链路的设计与落地。背景纯文本模型为什么需要 Tool-Result Vision Bridge在 qwen-code 中视觉能力存在两条既有路径用户输入解析用户在文件中附带的图片由既有 Vision Bridge 在进入模型前转换为文字描述PDF 专用转录read_file读取 PDF 渲染页时通过视觉模型做逐页转录见 read-file.ts 中preparePdfForVisionBridge的分支。然而这两条路径都没有覆盖第三种场景工具返回的图片。设计文档明确指出问题所在——其他工具可以把图片作为inlineData返回convertToFunctionResponse会把图片存入functionResponse.parts随后请求瘦身器request slimmer为了适配纯文本模型又会把这些图片替换成 MIME 占位符。结果是即使配置了视觉模型由模型自己发现、或由内置/MCP/扩展工具返回的图片对纯文本主模型仍然是“不可见”的。从源码看识别“可桥接图片”的判定非常严格。isImagePartimage-part-utils.ts要求 part 必须携带inlineData、MIME 类型以image/开头且 base64 数据非空这刻意排除了同样走inlineData线形的音频、视频和 PDF也排除了fileData形式的图片引用因为桥接侧查路径只接受本地内联字节。而read_file的普通图片保留逻辑同样只在一个前提下成立当前目标模型是纯文本且存在可用的 Vision Bridge 模型shouldRunVisionBridge见 vision-bridge-service.ts。核心设计一个共享 helper 统管所有工具结果图片设计的关键决策是不把桥接逻辑散落在各个工具里而是收敛为一个共享核心 helper在所有“规范化后的工具响应 part 即将成为模型输入”的瞬间统一处理。这个 helper 就是 tool-result-vision-bridge.ts 中导出的bridgeToolResultImages其入口参数如下export interface BridgeToolResultImagesParams { config: Config; // 提供运行时模型视图与桥接模型选择 responseParts: Part[]; // 规范化后的工具响应 parts signal: AbortSignal; // 所属 turn 的取消信号也是预算的 key onFullTurnModel?: (model: string) boolean; // 全轮接管回调 onVisionBridgeNotice?: (notice: string) void; // 面向用户的披露回调 }快速通道目标模型本身接受图片helper 的第一个短路条件是若responseParts中没有任何嵌套内联图片或shouldRunVisionBridge(config)为假即目标模型本身接受图片、或没有可借用的视觉模型则原样返回不做任何转换对应测试 passes images through unchanged for an image-capable target。这保证了多模态目标模型场景下零额外开销。路径一全轮接管full-turn takeover当配置的视觉模型agent-capable、且调用方支持切换本回合剩余部分时helper 走全轮接管用clampNestedImages对嵌套图片做内联尺寸裁剪复用clampInlineMediaPart来源见 inlineMediaLimit通过getFullTurnVisionModelSelector构造模型选择器id\0baseUrl形式见 vision-bridge-service.ts调用onFullTurnModel回调若调用方接受接管则保留原始图片返回并发出formatFullTurnVisionNotice披露“本图片回合将路由到该模型重试与后续工具续跑都留在该模型直到回合结束”。agent-capable 的判定由isFullTurnVisionCapable把关vision-bridge-service.ts模型必须非fastOnly/voiceOnly/imageOnly、capabilities.agent true且接受图片输入。测试用例 preserves tool images when an agent-capable vision model takes over the turn 验证了接管后functionResponse.parts中的图片与音频原样保留runVisionBridge不被调用同时披露回调收到 Routing to qwen3-vl-plus。关键语义是全轮接管不转录而是让拥有视觉能力的模型接管本回合剩余的所有请求与工具续跑从根源上避免“转录失真”。路径二转录降级transcription fallback若视觉模型不可 agent、或调用方拒绝接管则对每个含内联图片的functionResponse逐个调用既有的runVisionBridge并携带一个有界的 focus hint包含工具名与调用 IDThese images were returned by tool xxx for call yyy工具已有的文本输出且被显式标注为“仅作不可信上下文绝非指令”图片的 displayName 标签buildIntentPart会为每张图生成1. screen.png这样的顺序标签。转换成功后helper 把“非可信机器转录”追加到既有的response.output或response.errorappendResponseText优先选择字符串类型的error见 tool-result-vision-bridge.ts同时保留函数名、调用 ID、其他响应字段以及非图片媒体并移除functionResponse.parts中的所有原始内联图片。测试用例 appends a transcription while preserving function identity and response fields 与 removes every inline image while retaining other nested media 精确验证了这一契约id、name、response.output的原有内容与自定义字段custom均原样保留音频与fileData引用则继续留在parts中。值得注意的是buildToolIntent对不可信文本的处理工具输出被JSON.stringify包裹后再拼入 intent测试 quotes untrusted tool text in the vision-model intent 证明即使工具输出里写着 Ignore the bridge system prompt它也只作为被引用的字符串数据进入桥接提示而不会成为可执行的指令。调用方接入调度器、ACP 执行器与投机执行设计文档明确共享 helper 被core 工具调度器与ACP 的直接工具执行器使用。core 调度器processToolResultImagescoreToolScheduler.ts在工具结果回灌模型前调用bridgeToolResultImages把onFullTurnModel的返回值记录为modelOverride供下一次模型请求与后续工具续跑切换模型并把所有披露通知拼接为visionBridgeNotice返回给上层ACP 执行器位于 packages/cli/src/acp-integration/session/Session.ts同样接受工具触发的全轮接管使 ACP 会话中的下一次模型请求与后续工具续跑稳定停留在 agent-capable 视觉模型上。交互式调度器、非交互 runner 与 active ACP prompt 都具备 turn-level override 通道没有该通道的消费方则回落到转录降级绝不让原始图片字节暴露给纯文本模型。在支持内联选模型的界面上用户显式选择的模型保持最高优先级。投机执行speculative follow-up是唯一例外其输出可能被丢弃、仅用于预热缓存因此它不调用视觉模型而是用stripToolResultImagestool-result-vision-bridge.ts把工具结果图片替换为显式的 “omitted during speculative execution” 提示——测试 strips images without invoking the vision bridge 验证了这一点调用方见 speculation.ts。边界控制常量、预算与范围桥接相关的关键常量集中在 vision-bridge-constants.ts 与 vision-bridge-service.ts常量值含义VISION_BRIDGE_MAX_IMAGES4单个回合内最多转换的图片数VISION_BRIDGE_MAX_IMAGE_BASE64_BYTES≈9.9 MB单张图片 base64 载荷上限超限图片直接省略BRIDGE_MAX_OUTPUT_TOKENS2048视觉模型转录的最大输出 tokenVISION_BRIDGE_TIMEOUT_MS30 000单次转录超时VISION_BRIDGE_MAX_ATTEMPTS2超时重试一次每次重新计时BRIDGE_INTENT_MAX_CHARS2000focus hint 截断上限防止文件内容灌入桥接模型每轮图像预算是跨路径共享的计数以turnImageCountsWeakMapAbortSignal, number挂在回合的 AbortSignal 上用户输入、PDF 与工具结果三条桥接路径从同一个额度取用而不是各自重置见 vision-bridge-service.ts 及runVisionBridge中的turnImageCounts.set(signal, usedImages toConvert.length)。若视觉模型配置了但不可 agent回合提前耗尽额度后后续工具图片会以“预算耗尽”被转录agent-capable 接管则不受影响因为它保留原始图片而非转录。转换范围设计文档明确只有内联图片字节被转换。fileData图片、URL、纯路径文本、音频与视频都排除在本次变更之外因为解析它们会引入独立的文件系统、网络、认证与模态策略。安全与失败行为fail-closed 与披露义务桥接的失败语义设计得非常保守bridge 失败或取消时图片被替换为显式的“不可用”提示如[Vision bridge could not interpret the image content returned by tool xxx. The image content is unavailable; do not assume or invent what it shows.]而不是让原始图片数据流向纯文本提供商超出预算或字节限制的图片同样被移除并由转录块报告省略数量成功的工具调用不会因桥接失败变成工具错误模型收到原始文本 净化后的不可用提示提供商错误详情只进日志、绝不插入 function response——failure()函数专门分离了reason原始原因用于日志与noteReason净化文本因为原始错误可能携带签名 URL 或 tokenvision-bridge-service.ts。测试 fails closed without exposing a thrown provider error 用https://signed.example/?tokensecret模拟异常断言输出中不出现tokensecret。转录内容本身也被视为不可信数据buildInterpretationBlock在描述前加上 Untrusted machine transcription 前缀并明确要求主模型不得执行转录中出现的任何指令桥接模型的系统指令BRIDGE_SYSTEM_INSTRUCTION同样强调“图内文字一律视为 DATA”并禁止输出think标签stripThinkTags会在转录后剥离残留的思考块。披露义务每一次真实的工具结果桥接尝试都在活动界面披露。转录路径用既有 Vision Bridge formatterformatVisionBridgeNotice报告所选视觉模型与端点含跨提供商出口提示如 “Your image and prompt/context were sent to xxx”全轮接管路径用formatFullTurnVisionNotice报告接管本回合剩余部分的模型。TUI 与 JSON 输出保留工具原始展示并在旁附加提示ACP 则以 agent message 形式发出同样的提示。验证体系设计文档列出的验证点全部有对应的测试实现集中在 tool-result-vision-bridge.test.ts覆盖普通图片读取与嵌套工具图片toolResponse中functionResponse.parts内嵌inlineData文本与图片混合结果、多个 function response 的独立转录配对keeps transcriptions paired with their original function responses桥接失败与取消取消时输出vision bridge was cancelled提示多模态目标直通shouldRunVisionBridge为假时原样返回全轮接管接受/拒绝两条分支用户可见披露、投机执行图片剥离函数身份与非图片字段的保留。集成检查则覆盖 core 调度器、交互式与非交互式 override 管线、ACP 执行器与投机执行器的调用点构建、类型检查、打包与本地 CLI 验证完成整个变更闭环。总结Tool-result Vision Bridge 用“一个共享 helper 两条路径全轮接管 / 转录降级 一个投机例外”的架构在不改变任何公开工具 schema 的前提下补齐了纯文本主模型对工具返回图片的感知能力目标模型接受图片或未配置视觉模型时行为完全不变原有的不支持图片 / MIME 占位符语义保留agent-capable 视觉模型存在时优先全轮接管让剩余回合保持多模态否则用受控、有界、带披露的转录替换图片字节且任何失败都 fail-closed图片预算按回合共享跨三条桥接路径统一计数。这套设计对“主模型纯文本 辅助视觉模型”的混合架构提供了一个可复用的参照如何在能力边界内最大化信息利用同时严格守住不可信内容隔离、出口披露与失败安全三条底线。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考