Modlens

功能说明

Modlens 让「看不见」的模型能够处理图片。但它的工作方式需要说清楚，因为「为纯文本模型提供视觉」最直白的理解是错的：Modlens 并不会自己给 Harness 装上眼睛。它把图片发给由你配置、由你付费的视觉引擎，再把引擎返回的内容转换成正文本模型可以阅读的结构化证据——完整转录、按阅读顺序排列的布局区域，以及实体与关系列表。

这个区别决定了它对你是否有用。在配置至少一个视觉引擎之前，它什么都不做：要么一个 API key，要么你已有的某个 CLI 登录态。Modlens 贡献的是管道部分——路由、故障转移，以及一种文本模型能据以推理的输出形状，而不是一段只能选择相信的段落。

它如何获得视觉能力

内置六家供应商，而且它们并不等价。README 为每一家给出了「需要什么」与「单次读取耗时」：

gemini-api 是 README 推荐的默认项。另外还可以借用四个本地代理 CLI 的视觉能力——Codex、OpenCode、Pi 与 Grok——但每一个都需要在配置里留下明确的逐项授权；每一次借用的读取都会在输出里标注用的是谁的配额，因此回退不会悄悄产生账单。

若不固定供应商，所有已配置的引擎会组成单一故障转移链：快的 API 供应商先试，代理 CLI 兜底，第一个成功的结果胜出，输出中记录每一次尝试。你也可以设置偏好而不解除这条链，或者固定唯一供应商并完全关闭回退。API key 支持逗号分隔的列表，遇到鉴权、限流或配额失败时会轮换到下一个 key。

它接在哪里

在 Harness 中，Modlens 会向模型选择器加入包装后的条目，并提供一个 modlens_read_image 工具。它会检查各条路由，只接管那些元数据明确确认为纯文本的模型——原生视觉模型会被自动排除，未确认的一律不动。粘贴的图片以结构化证据的形式到达，而不是像素。

要求与成本

需要 Node.js 22.19 或更新版本。该包只有两个运行时依赖：commander 与 undici，并自带 CLI、文档与技能。除此之外，真正的门槛是引擎：至少一个 API key 或一个已登录的 CLI。README 称 Gemini key 是免费的、agy 路线无需 key，但没有给出任何配额数值、速率限制或价格，并明确说明：你对各上游引擎的使用受这些供应商自身条款约束。

什么时候用它、什么时候不要用

如果你在纯文本模型的 Harness 里工作，并且手上已经有某处的视觉能力——一个 Gemini key、一个 OpenAI 兼容网关，或者一个你愿意借出的 Claude Code / Codex 登录态——那就用它。故障转移链是它最有力的理由：你可以配置多家引擎让它自己挑，而不必自己写路由逻辑。

不要指望它的视觉是自包含的、免费的或无人值守的。它需要引擎，引擎有配额，而插件明确表示上游条款由你自己遵守。如果你的 Harness 本来就跑着原生多模态模型，Modlens 会有意避让。

两点来自源码的诚实限制。密集图表被点名为视觉桥接最容易失败的场景。而 README 没有公布准确率基准，也没有图片尺寸、分块上限或最大图片数量，因此质量天花板取决于你选的那家引擎。

兼容性说明

这里真正重要的只有版本固定：README 的安装说明写明了确切版本，对于一个输出结构可能被下游解析依赖的插件来说，这是正确的习惯。项目由单一作者维护，每一行都亲自审阅，且不接受 pull request，所以修复按维护者的节奏到来，而不是按你的。它以 MIT 许可、按原样提供，对任何用途（包括商业用途）均不作担保。

FAQ

我需要一个视觉模型才能用它吗？

不需要，但你需要一个视觉引擎。Modlens 在 Harness 侧配合纯文本模型工作——这正是它的意义——但你必须配置六家内置供应商中的至少一个，或借用四个本地 CLI 之一。Harness 保持纯文本；图片在别处被读取。

它会把我的图片发到某个地方吗？

会。图片会被发送到当前配置且作出响应的那家视觉引擎，通常是一个托管 API，你对那个服务的使用受其条款约束。替代方案是你已经登录的本地 CLI。README 指向其安全文档说明远程 URL 的抓取行为；其中没有说明数据保留策略，也没有描述遥测。

返回的具体是什么？

README 把输出描述为完整转录、按阅读顺序排列的布局区域，以及实体与关系列表——是被设计用来引用的证据，而不是概括。JSON 契约写在项目自己的输出 schema 文档里，解析字段名之前应当先看那里。

能在其他 Harness 里用吗？

可以。该包同时也以技能形式分发，README 记录了面向其他 Harness 的技能安装方式。截屏功能不包含在内——那是另一个插件——网页搜索则是同作者的兄弟项目，不属于 Modlens。