给纯文本大模型装上眼睛：Agent钩子桥接图片实战

agent-">一、组合的选择：Agent当壳，大模型当脑

近两年，“命令行Agent + 自选大模型”的解耦式组合在开发者中越来越流行：Agent框架负责工具调用、会话管理、上下文组织等“手脚”层面的能力，而模型本身通过标准API接入，充当“大脑”。这种架构带来两个直接收益：

1. 成本可控：模型侧按token计费，日常编码量级下每月成本可以压到几十元人民币，相比订阅制编程助手（常见定价每月一两百元）或按席位收费的一体化方案，开销显著下降；
2. 模型可替换：哪家模型在编码任务上表现更好就切换哪家，不被单一供应商绑定，也便于按任务类型混搭。

我日常使用的是一个支持生命周期扩展的命令行编码Agent，后端接一个纯文本大模型。在写代码、重构、排查Bug这些纯文本场景里，这套组合完全够用，甚至因为上下文组织得力，体验比不少一体化工具更顺手。

直到有一天，我截了一张前端报错的图，直接粘贴进终端想让Agent帮忙排查——屏幕上冷冰冰地弹出一行：

[Unsupported Image]

二、问题比想象中严重：图片是高频刚需

纯文本模型看不见图片，这绝不是一个边角问题。盘点日常开发工作流，图片交互至少覆盖四类高频场景：

• 前端报错排查：截图扔给AI，让它定位原因；
• UI设计稿还原：把设计稿喂给AI，让它生成页面结构；
• 浏览器自动化测试：脚本跑完截图，让AI判断页面状态是否符合预期；
• 文档扫描件处理：合同、法律文书的扫描件，让AI提取关键条款。

这些场景在原生支持多模态的编码助手里毫无障碍，因为它们背后的模型本身就能看图。而一旦换成纯文本模型，全线失效——不是模型不够聪明，而是它的输入空间里根本不存在“图像”这个维度。

三、两条常规路子，为什么都“太笨了”

最直觉的解决方案有两个，我都实际试过：

方案一：先OCR，再手动粘贴。 用OCR工具把截图里的文字识别出来，复制给AI。能用，但缺陷明显：每次多出好几步手工操作，操作链路被拉长；OCR只识字，图表、布局、颜色信息全部丢失；报错弹窗在页面上的位置、控制台的上下文关系，这些视觉线索也一并蒸发。

方案二：遇到图片临时切换模型。 碰到图就切到多模态模型问一句，问完再切回来。同样能用，但整个工作流被打断：上下文断了，问题需要重新描述一遍，来回横跳的心态成本甚至比操作成本更高。

这两个方案有一个共同的本质问题：人在适配机器。用户的自然动作是“截图—粘贴”，机器却要求用户“先OCR再粘贴”或“换个工具再提问”。好的工具应该反过来——机器适配人。

四、正确姿势：用生命周期钩子做“翻译官”

Agent工程实践中有一个值得重申的公式：Agent的价值 = 模型能力 × 可扩展性。模型是大脑，但决定体验上限的往往是那条“神经反射弧”——你能不能在关键节点插入自己的逻辑。

主流Agent框架大多提供了生命周期钩子（Hook）机制：在会话的各个阶段（用户提交输入、工具调用前后、会话结束等）允许开发者挂载自定义脚本，对输入输出进行观察、改写或增强。

于是思路豁然清晰：

能不能在图片到达纯文本模型之前，用钩子把它拦截下来，先发给一个能看懂图的多模态模型翻译成文字，再把文字喂回去？

本质上，就是给一个盲人配了一个随身翻译。盲人（纯文本模型）负责推理和编码，翻译（多模态模型）负责把视觉世界转述成语言。两者各自做擅长的事，用户则完全无感。

五、踩坑实录：钩子根本拿不到图片

想法很美好，落地第一脚就踩空了。

我的初始假设是：用户粘贴图片提交时，“用户提交”阶段的钩子总能收到图片数据吧？调研后发现——收不到。钩子通过标准输入接收的JSON大致长这样（示意）：

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "hook_event_name": "user_prompt_submit"
}

里面只有会话ID、会话记录文件路径、事件名等元数据，图片本体根本不在这条通道里传递。

转机藏在transcript_path这个字段里。Agent框架会把整个会话落盘为JSONL格式的transcript文件，用户粘贴的图片在其中以引用形式存在（本地路径或资源句柄）。这意味着：

1. 钩子虽然拿不到图片本体，但能拿到transcript的文件路径；
2. 解析transcript，就能定位到本轮新增的图片条目；
3. 从磁盘读取图片交给多模态模型，再把翻译结果以新条目形式追加回transcript——纯文本模型在下一轮读取上下文时，“看到”的就是一段结构化的文字描述。

整条链路在用户提交之后、模型推理之前完成，对用户完全透明。

六、架构与示意实现

整体数据流如下：

用户粘贴图片
      │
      ▼
Agent前端 → 会话落盘（transcript.jsonl，图片以引用记录）
      │
      ▼
"用户提交"钩子触发
      │  读取 stdin 元数据 + 解析 transcript
      ▼
拦截新增图片 → 多模态模型翻译为结构化文字
      │
      ▼
翻译结果回填 transcript → 纯文本模型读到文字描述

钩子脚本的核心逻辑（伪代码，示意）：

def main():
    payload = json.load(sys.stdin)                    # 1. 读取钩子元数据
    entries = read_jsonl(payload["transcript_path"])  # 2. 读取会话记录
    for image in extract_new_image_refs(entries):     # 3. 提取本轮新增图片
        if image.hash in CACHE:                       # 4. 缓存命中直接跳过
            continue
        caption = vision_model.describe(              # 5. 调用多模态模型翻译
            image.load(),
            prompt=build_prompt(image.context),
        )
        append_to_transcript(                         # 6. 结构化回填
            payload["transcript_path"],
            role="assistant",
            content=f"[图片自动翻译]\n{caption}",
        )
        CACHE[image.hash] = caption

视觉模型的选型不需要纠结：直接复用公有云上的多模态大模型服务即可，例如百度智能云等厂商提供的视觉理解类模型服务，以标准API按量调用，无需自建推理环境，日常截图量级下的成本几乎可以忽略。

七、提问角度决定翻译质量

这套方案里最容易被忽视、却最影响最终效果的环节，是给多模态模型的提示词。翻译不是一句“描述这张图”就能敷衍的，而要针对下游任务定制提问角度——这本质上回到了“如何向模型提问”的经典命题。

场景一：报错截图。 目标是让纯文本模型像亲眼看图一样排查问题，提问应聚焦信息提取：

你是资深前端工程师。请从这张报错截图中提取：
1. 完整报错信息（逐字保留，不要意译）；
2. 调用栈关键路径与涉及的文件名；
3. 页面URL、时间戳等环境线索；
4. 可见的渲染异常区域及其在页面中的位置。
以Markdown结构化输出，不要省略任何文字。

场景二：设计稿还原。 目标是“可还原”，提问应约束输出粒度：

请以"能据此写出页面代码"为标准描述这张设计稿：
1. 整体布局（栅格/分栏/留白节奏）；
2. 组件清单及层级关系；
3. 配色（主色、辅助色，尽量给出十六进制估值）；
4. 字号层级与字重；
5. 可推断的交互状态（悬停、禁用等）。

场景三：测试截图。 目标是状态判定，提问应先给出判定基准，要求对比输出而非泛泛描述。

几条通用经验：结构化优先，用编号列表约束输出，便于下游模型解析；信息优先级显式声明，报错文本在前、视觉细节在后；禁止主观发挥，明确要求“不要猜测图中不存在的内容”，从源头抑制幻觉。

八、工程化细节

方案要走向生产，还需考虑三件事：

1. 缓存：同一张图可能被多次粘贴或跨轮引用，以图片内容哈希为键建立翻译缓存，避免重复调用多模态模型造成浪费；
2. 兜底：多模态服务超时或失败时，钩子应写入一条明确的占位说明（如“图片暂不可用，请用户补充关键信息”），而不是静默失败，让纯文本模型凭空幻觉；
3. 合规与脱敏：截图可能包含内网地址、密钥、个人信息，翻译链路上传前应评估敏感信息暴露风险，必要时在本地先行裁剪或打码。

九、总结

回头看，这次实践带来三点启示：

• 交互设计的第一性原理是机器适配人。用户的最短路径是“截图—粘贴”，工具就有义务在这条路径上把问题消化掉，而不是要求用户绕路；
• Agent的竞争力一半在可扩展性。生命周期钩子这类“神经接口”让开发者无需修改框架源码就能重组数据流，这正是组合式架构的精髓；
• 纯文本模型 + 翻译层，是多模态能力的一种廉价替代。不追求模型自己“长出眼睛”，而是用工程手段把视觉信息转译进它的语言世界。

给盲人配一个翻译，比强行做手术便宜得多，也优雅得多。