oh-my-pi 纯文本模型图片附件视觉回退机制image-attachment-describe 提示词详解与实现原理【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读在 oh-my-pi⌥ 编码 Agent与 IDE 深度集成中当用户把截图、报错画面或界面截图附加给一个不支持图像输入vision的纯文本模型时图片不会简单地被丢弃而是会触发一套视觉回退vision fallback机制由注册的视觉模型对图片进行详尽的文字描述再以文本块形式注入下游上下文让纯文本模型也能看见图片并参与推理。本文以 image-attachment-describe.md 提示词为切入点完整讲解该提示词覆盖的要素规范、配套系统提示词以及它在 image-vision-fallback.ts 中的实现原理、模型解析优先级与相关配置项。读完本文你将掌握该机制的全貌并能在自己的 Agent 或 RAG 应用中复刻一套图片 → 结构化文字描述 → 纯文本推理的降级管线。为什么纯文本模型需要看图图片附件的降级问题对话型大模型的输入模态并不统一有的模型原生支持多模态图像输入input中包含image能力有的则是纯文本模型。当用户在 oh-my-pi 的会话中粘贴一张图片给纯文本模型时若不处理Provider 层会直接丢弃图片内容源码注释中记为NON_VISION_IMAGE_PLACEHOLDER见 image-vision-fallback.ts模型对图片内容一无所知——截图里的报错、界面上的按钮状态、图表中的数据全部丢失。oh-my-pi 的解决方案是降级为文字与其让图片被静默丢弃不如用另一个具备视觉能力的模型把图片翻译成详尽的文字描述再把这段描述作为文本块替换图片注入上下文。这样纯文本模型依然可以基于描述进行推理整个流程对用户透明且不改变下游模型的能力边界。这一思路的核心载体就是本文的主角——image-attachment-describe.md。它作为user 提示词user prompt在 image-vision-fallback.ts 中被以文本资源方式导入import describeUserPrompt from ../prompts/tools/image-attachment-describe.md with { type: text }; import describeSystemPrompt from ../prompts/tools/image-attachment-describe-system.md with { type: text };调用时用户消息包含原始图片与这段 user 提示词系统消息则使用配套的 image-attachment-describe-system.md见describeImage中的prompt.render(describeSystemPrompt)与消息组装image-vision-fallback.ts。提示词主体把图片描述成看不见也能推理的文字image-attachment-describe.md全文虽然精炼却是一份高度可操作、面向多模态场景的图片要素清单。它的总目标是Describe the image in enough detail for a model unable to see it to reason about its content.以足够详尽的细节描述图片让一个看不见图片的模型也能对其内容进行推理。这个总目标界定了描述的服务对象不是给人看的赏析而是给下游纯文本模型补充推理所需的事实输入。因此它要求描述证据充分、可独立支撑推理而不是生动形象。覆盖要素一整体场景、主体与动作提示词要求覆盖overall scene, subject, action整体场景、主体、动作。视觉模型需要交代这是一张什么样的图、拍的是什么、正在发生什么为下游模型建立第一层上下文。例如对一张报错截图至少要说清这是终端窗口的截图顶部是命令提示符下方输出了一段红色的错误信息。覆盖要素二人物与物体——关系、位置、颜色、数量对于包含人物或物体的图片提示词明确要求覆盖relationships, positions, colors, counts关系、位置、颜色、数量。这四个维度都是可验证的客观事实关系谁在谁旁边、谁指向谁、谁在操作什么位置物体在画面中的相对布局左上、右下、居中……颜色关键物体的颜色往往是定位或状态判断的线索数量出现了几个同类物体例如页面底部有 3 个按钮。覆盖要素三可见文字逐字转写OCR提示词特别强调all visible text verbatim (OCR)——所有可见文字必须逐字转写。这是整个提示词中对下游推理最关键的一条报错信息、日志输出、界面标签、代码片段几乎全部依赖文字内容任何错字、漏字都会直接误导下游模型。配套系统提示词进一步强化了这条纪律见下文系统提示词的行为准则。覆盖要素四UI / 截图元素的状态与细节对 UI 截图提示词要求覆盖labels, buttons, inputs, states, errors, highlighted or disabled controls——即标签、按钮、输入框、控件状态、错误提示、高亮或禁用状态。这类信息直接对应 Agent 场景中最常见的需求IDE 报错面板、浏览器控制台、表单校验提示、设置界面开关状态等。描述必须落到某个具体控件处于什么状态而不是笼统说这是一个设置页面。覆盖要素五图表的结构与编码值对于diagrams, charts, tables提示词要求覆盖structure, axes, series, encoded values——结构、坐标轴、数据系列、编码值。也就是说描述不能只说这是一张折线图而要交代坐标轴含义、有几条数据系列、趋势方向、关键数据点对应的数值使下游模型可以据此进行定量或半定量分析。输出纪律标注歧义、只输出散文最后两条同样重要Flag anything ambiguous or unreadable凡是模糊、无法辨认的内容必须明确标注出来不能装作看得清Output plain prose only只输出纯散文文本不输出 Markdown 列表、JSON、XML 或其他结构化外壳保证描述作为纯文本块干净地注入下游上下文。配套系统提示词八条行为准则保证描述可信image-attachment-describe-system.md 为视觉模型定义了身份与行为边界开头即点明Description replaces attached image in downstream model context; downstream relies entirely on text, never sees pixels.描述将替换下游上下文中的附加图片下游完全依赖文本永远看不到像素。这意味着视觉模型是下游模型的唯一眼睛其描述质量直接决定纯文本模型的推理质量。系统提示词核心行为如下证据优先faithful, evidence-first明确区分直接观察与推断观察在前、推断在后不得混为一谈逐字转写全部可见文字保留大小写、标点、布局顺序对不可读片段明确标注绝不猜测禁止编造绝不虚构被遮挡、模糊或不确定的细节必须陈述不确定性详尽而紧凑信息密度高的散文无填充废话只输出描述禁止元评论、禁止这张图片展示了……之类的开场白禁止收尾寒暄。这组准则与 user 提示词形成互补user 提示词解决覆盖哪些要素system 提示词解决以什么态度和格式输出。二者共同保证了注入下游的文本块是忠实、完整、干净的。实现原理图片如何被保存、描述并注入第一步判断是否需要回退回退触发条件在会话 Provider 边界处判定session-provider-boundary.tsconst shouldDescribe !!model !model.input.includes(image) // 当前模型是纯文本模型 !this.#host.settings.get(images.blockImages) this.#host.settings.get(images.describeForTextModels);即当前活动模型不支持图像输入、且用户没有在设置中全局禁用图片images.blockImages为 false、且开启了为纯文本模型描述图片images.describeForTextModels默认 true时才走回退管线。命中后调用describeAttachedImagesForTextModel结果为一段custom类型的隐藏消息display: false注入会话不打断主对话流。第二步保存图片到 session 本地根目录在 image-vision-fallback.ts 中每张图片会按内容寻址方式保存function imageFileName(image: ImageContent): string { const hash Bun.hash(image.data).toString(16); return image-${hash}.${extensionForMime(image.mimeType)}; } async function saveImage(image: ImageContent, localRoot: string): Promisestring { const fileName imageFileName(image); const filePath path.join(localRoot, fileName); await Bun.write(filePath, Buffer.from(image.data, base64)); return local://${fileName}; }要点有二内容寻址文件名由图片字节的 hash 决定同一张图片重复粘贴只产生一个 artifact且重复写入是幂等的Bun.write自动创建父目录MIME 扩展名映射extensionForMime将 jpeg/png/gif/webp 映射为对应扩展名未知 subtype 会做净化处理兜底为pngimage-vision-fallback.ts。保存后的图片以local://image-hash.png形式供后续read工具访问即使描述失败图片也不会丢失可用于后续人工或工具二次分析。第三步解析视觉模型并调用模型解析函数resolveVisionModel采用与显式图像问答一致的优先级image-vision-fallback.tsvision → default → 当前活动模型字符串 → 第一个支持 image 输入的可用模型每一步都会通过model.input.includes(image)过滤掉纯文本模型保证最终选中的一定是视觉模型。解析失败无可用模型或未配置 API Key时describeAttachedImagesForTextModel会降级输出一段说明性占位文本NO_VISION_MODEL_NOTE/DESCRIPTION_UNAVAILABLE_NOTE见 image-vision-fallback.ts提示用户配置modelRoles.vision角色。调用本身是一次性问答oneshotsystem 提示词 图片 user 提示词stopReason为error或aborted时记为失败并返回null由上层兜底为占位说明image-vision-fallback.ts。整个描述调用通过ONESHOT_KIND image_attachment_describe打点进 telemetry便于观测。第四步以文本块形式注入formatImageBlock将描述包装为结构化文本块image-vision-fallback.tsfunction formatImageBlock(localUrl: string, description: string): string { return image path${localUrl}\n${description}\n/image; }最终每张输入图片对应一个TextContent文本块顺序与输入一致Promise.all保持次序image-vision-fallback.ts。单张图片的描述失败不会抛异常影响其他图片失败时仍会输出带保存路径的占位块。由于文本块中携带local://路径下游或用户在后续会话中仍可通过read工具定位原始图片。关键配置项控制图片回退行为该机制由images配置组下的多个键控制均定义在 settings-schema.ts配置键类型默认值作用images.describeForTextModelsbooleantrue当图片附加到无视觉支持的模型时保存到local://并用视觉模型生成描述注入而不是直接丢弃settings-schema.tsimages.blockImagesbooleanfalse阻止图片发送给 LLM Provider开启后回退管线与显式图像问答都会被禁用settings-schema.tsimages.questionTimeoutMsnumber300_000read的?q图像问答单次请求超时毫秒设为0禁用超时settings-schema.tsimages.autoResizeAppearance 组boolean—将大图自动缩放至最大 2000×2000 以提升模型兼容性settings-schema.ts其中images.describeForTextModels是本文机制的总开关若某次描述调用因配置了vision角色之外的模型而解析失败错误提示会引导用户为modelRoles.vision配置一个视觉模型——该角色名与模型角色类型定义一致default | smol | slow | vision | ...见 model-roles.ts。与显式图像问答read ?q的分工与自动回退不同oh-my-pi 还提供显式图像问答能力通过read image?qquestion主动向视觉模型提问read.ts 限定?q仅支持图像类输入。其实现位于 image-question.ts模型解析优先级同样是vision → default → 活动模型随后回退到同 Provider 的图像模型 → 任意图像模型image-question.ts支持images.questionTimeoutMs超时、思维链reasoning配置以及模型级resolveThinkingLevelForModel推理强度映射image-question.ts若解析到的模型不支持图像输入会直接抛出引导性错误建议配置modelRoles.visionimage-question.ts。两者的分工很清晰自动回退解决用户贴图给纯文本模型的默认体验问题显式?q解决用户想针对某张图片深挖细节的主动提问需求。前者是本文描述机制的运行场景后者是互补的按需分析手段。当自动回退因未配置视觉模型而失败时提示语也会指引用户配置视觉模型角色后用?qquestion分析已保存的图片两条路径由此闭环。总结image-attachment-describe.md虽然只有寥寥数行却定义了一套纯文本模型看图的关键契约覆盖要素上要求场景/主体/动作、人物物体关系与颜色数量、文字逐字转写、UI 状态、图表结构五类信息全覆盖输出纪律上要求标注歧义、只输出纯散文。配合系统提示词的行为准则与 image-vision-fallback.ts 的实现oh-my-pi 把图片被静默丢弃的糟糕体验变成了图片先被视觉模型翻译成可推理的文字再注入纯文本模型的稳健降级方案——图片按内容寻址保存到local://描述以image path....../image文本块注入失败时也不丢图、不中断并提供images.describeForTextModels、images.blockImages、images.questionTimeoutMs等开关精细控制行为。这套模态降级 结构化描述提示词的设计对任何需要同时兼容多模态与纯文本模型的 Agent 应用都具有直接的参考价值描述提示词要围绕下游无法看图这一前提来覆盖要素系统提示词要守住忠实、不编造、纯文本的底线管线实现则要保证单图失败不拖垮整轮、图片永远可追溯。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考