外挂视觉层的架构：ModLens 的引擎抽象与证据化输出
DeepSeek 主力对话模型与 GLM-5.3 本体仍是纯文本，读不了图。liustack/modlens 的解法不是改模型，而是在模型外侧架一层视觉抽象：把「看图」剥离出来交给一组可替换的引擎，再把结果以结构化证据送回对话。这篇只谈这层抽象怎么搭，以及它把哪些取舍留给了使用者。
层的位置：插件、工具与两个粘贴入口
ModLens 的分类是 dsh 原生插件 · vision，安装就一条命令：
dsh plugin --profile web add @liustack/modlens
它不 hook、不套壳、不跑本地代理进程、不改 harness 配置的一行字。这决定了它的定位：一个薄适配层，而不是常驻服务。粘贴入口有两个——直接粘贴时，图片被自主转成文件路径进输入框（与 OpenCode、Pi 同款交互），再由 modlens_read_image 工具接手读图；或者切到带 (modlens vision) 后缀的模型变体（选择器有记忆，选一次就行）再粘贴，缩略图直接可见、所见即所得。
modlens_read_image：粘贴之后的工具链路
在 dsh 里装完即有 modlens_read_image 工具。它在链路中的位置是：图片 → 文件路径 → 工具读取 → 交给视觉引擎 → 引擎返回结构化结果 → 对话模型据此作答。工具本身不产出视觉能力，它只负责把这张图喂给已配好的引擎，并把返回的 JSON 证据转成模型能引用的上下文。所以链路成立的前提是「引擎池里至少有一个可用来源」——这是整套架构的第一性约定：ModLens 提供的是调度与契约，不是模型权重。
引擎池：六个内置 provider 加四家可复用 CLI
视觉来源一共十个：六个内置 provider（配好任意一个就能用），加四家本机 agent CLI 的登录可以复用。内置的六个，区别主要在「需要什么」和「单次识别耗时」：
gemini-api：免费 Gemini key（三分钟领取，无需信用卡），5–10 秒，推荐默认。openai：任意 OpenAI 兼容端点（key + baseUrl + model），5–10 秒，适合 qwen-vl、GLM、自建网关。anthropic：Anthropic API key，5–10 秒，适合手上已有 key 的机器。antigravity-cli：免费的 agy CLI，浏览器登录一次、无需 key，15–45 秒，适合完全免注册起步。claude-cli：已登录的 Claude Code，20–45 秒，适合复用现有 Claude 订阅。kimi-cli：已登录的 Kimi Code，20–45 秒，适合复用现有 Kimi 订阅，需显式点名。
可复用的四家是 Codex、OpenCode、Pi、Grok，各家对应一条授权命令，语义是「与你自己配的 key 平级入池，不插队」。其中 openai 值得单独一提：任何讲 OpenAI chat-completions 协议、支持图片输入的端点都能直接插上，它其实是「万能接口」，不只是 OpenAI。
故障转移链与可观测性
不钉死 provider 时，所有配好的引擎组成一条故障转移链：API 快车道先试，agent CLI 兜底，第一个可用结果胜出。这条链把延迟与可用性做了分工——5–10 秒的 API 通道优先满足速度，15–45 秒的 CLI 通道在 API 不可用时顶上。
回退永远不是无声的：meta.attempts 记录每一次尝试，meta.warnings 在复用来源时标明「花的是谁的额度」。这两个字段是架构里最被低估的部分——它把调度决策变成可审计数据，而不是黑盒。
模型变体自动发现与「只接管纯文本模型」的裁决
带 (modlens vision) 后缀的变体不是手工枚举的，而是插件自动发现生成：每条承载纯文本 DeepSeek 或 GLM 模型的 provider 路由各得一组包装条目，默认安装下就是 DeepSeek-V4-Flash (modlens vision) 与 DeepSeek-V4-Pro (modlens vision)。接管与否由一个保守的裁决逻辑决定：只有被真实模型元数据确认纯文本的模型才会被接管，确认不了的一律不动。两家自己的视觉型号（含 GLM-5.3-Flash）因此被自动排除，保留原生贴图。宁可少接管，也不把一个原生多模态模型再包一层，这是这套机制的核心取向。
结构化 JSON 证据：与「看图说话」的差别
输出契约是一份结构化 JSON：全文转录（OCR）、按阅读顺序划分的版面区块、实体与关系列表。模型引用的是具体内容，而不是「再看一眼、再描述一遍」。差别在密集图表上最明显。README 的原样记录里有一条压力测试：128 个模型的对比散点图，双轴定义、对数刻度、按厂商的配色、高亮区域，以及虚线标注的每一个 DeepSeek 型号全部识别。描述型输出会把印象当成事实，证据型输出则要求把读数逐项落到字段上。
边界与取舍
回退是可见的，但需要主动去看。 meta.attempts 与 meta.warnings 把每次尝试和额度归属都写了出来，可它们不会自己跳到眼前。当你觉得「怎么变慢了、变贵了」，第一反应该是查这两个字段，而不是凭感觉猜。
模型变体列表会比预期长。 变体由插件自动发现生成，装了 opencode-go、zai 等额外路由的机器会各自多出一组 (modlens vision) 条目。这是设计行为——列表长短直接反映你机器上有多少条纯文本路由。
偏好与钉死是两套语义。 modlens config set provider <name> 表达的是偏好，链会继续兜底；-p <name> 是钉死单个、不回退。想要「优先 A、挂了退 B」用前者，想要「只用 A、挂了就报错」用后者。把两者搞反，要么得不到兜底，要么得不到确定性。
总结
ModLens 的架构价值不在于「补上了视觉」，而在于把视觉做成一个可替换、可观测、可回退的抽象层：工具链路负责搬运，故障转移链负责调度，两个 meta 字段负责留痕，结构化 JSON 负责把读到的内容变成可引用的证据。想对照同类插件的中文清单与安装形态，见 DeepSeek Harness Hub 插件清单。
适合与不适合
适合：手上只有纯文本 DeepSeek / GLM 模型、却经常要读截图与图表的人；已经在用 Claude Code、Codex、Pi、OpenCode、想把现成登录态复用进来的机器；需要把读图结果接进下游工具、因此在意结构化 JSON 输出契约的开发者；希望卸载时「删个文件夹就回到原样」的用户。
不适合：本机没有任何可用视觉引擎、又不愿意配 key 或复用已登录 CLI 的人——它会什么也读不了；对延迟敏感、却只想走免费通道的人——antigravity-cli 单次 15–45 秒，claude-cli 与 kimi-cli 20–45 秒，比 API 快车道慢数倍；以及在意「图片会被交给第三方视觉服务」、或要求插件已通过人工安全评估的团队——站点安全扫描判定其「含敏感能力」且尚无人工评估。
标签：ModLens、DeepSeek Harness、视觉插件架构、故障转移链、结构化输出
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。