企业官网建设流程全解析

ModLens 源码剖析：10 路视觉来源的 Failover 链如何做到"永不沉默"的故障转移

【免费下载链接】modlensThe first vision plugin for DeepSeek Harness, and the vision bridge for every text-only coding agent. Paste an image, get structured JSON evidence (OCR, layout, semantics). | 全网最强 DeepSeek Harness 外挂视觉插件，为 DeepSeek、GLM 等纯文本模型外挂视觉能力，粘贴图片即得结构化 JSON 证据（OCR、版面、语义）。项目地址: https://gitcode.com/gh_mirrors/mo/modlens

ModLens 是一个为 DeepSeek Harness 等纯文本编码代理外挂视觉能力的开源插件：粘贴图片即得结构化 JSON 证据（OCR 全文、版面区块、语义）。它的底层维护了10 路视觉来源和一条故障转移（Failover）链——任何一路挂了，下一路无缝顶上，且每一次尝试都会留下记录。这篇文章带你读懂这条链的组装逻辑和"永不沉默"的实现方式，不需要你写过一行 TypeScript。

先看图理解整体数据流：图片进入 ModLens 后，先由 skill 接管，再交给视觉引擎池，最后产出结构化 JSON。

一、10 路视觉来源：6 个内置 Provider + 4 个可复用 CLI

所谓"10 路"，来自 README.md 中"Vision engines"一节的说法：六个内置 Provider，加四个本机可复用的 Agent CLI。

6 个内置 Provider

注册表在 src/providers/index.ts，每个名字（含别名）都映射到同一个 Provider 实现：

4 个可复用 CLI

安装流程会发现机器上的 Codex、OpenCode、Pi、Grok（探测逻辑见 src/auto/discover.ts），逐个征求授权后，对应路线由 src/auto/routes.ts 的reuseProviders构造，并入同一条链。授权复用绝不插队，且每次复用都会在结果里标注"这次花了谁的额度"——这就是"永不沉默"的第一层含义：不静默计费。

二、Failover 链是如何组装的

链的排序规则写在 src/providers/availability.ts，核心是两条常量：

本地图片链：gemini-api → openai → anthropic → antigravity-cli → claude-cli 远程 URL 链：gemini-api → openai → anthropic → antigravity-cli

三条设计原则值得细看：

1. 快车道优先。注释里写得很直白：内联 API 5-10 秒出结果，Agent 类要 15-45 秒，所以"快的在前，Agent 兜底"（L129-L135）。
2. 远程 URL 链是安全边界。远程图片只有走内联下载路径才会经过 SSRF 防护、图片魔数校验和大小上限，所以 Agent 类 CLI 永远不进入远程链；claude-cli只读本地文件，也永远不进入远程链（L131-L135）。
3. kimi-cli是"点名专属"。它消耗 Kimi 订阅且没有"内置即同意"的历史，所以被放进PIN_ONLY_PROVIDERS：只有你显式-p kimi-cli或写入配置才会加入本地链（L144-L148）。

可用性过滤：只把"真能用"的引擎放进链

providerAvailable（availability.ts L108-L127）在运行时过滤链条：子进程类 Provider 检查二进制是否在 PATH 上（含 Windows 的.exe/.cmd后缀处理，见 L86-L92），API 类 Provider 检查必填配置是否齐备。过滤后的链由providerChain返回；若用户配置了首选 provider，它会"移到所在区段的最前"，但不会越过安全边界。

复用来的引擎则由 src/analyzer.ts 的composeChain按区段合并：借用来的 API key 插在"内联区"尾部，借用来的 Agent 插在claude-cli之前——速度档位决定位置，授权先后不决定优先级。

三、故障转移的瞬间：一次失败的完整旅程

主循环在 src/analyzer.ts 的analyzeImage里，一次失败要经历四道关卡才轮到下一路：

关卡 1：先换 key，再换路

同一 Provider 的apiKey支持逗号分隔多 key。鉴权、限流、配额类失败会continue到下一把 key（L269-L272）；而网络、5xx、解析类失败跳过剩余 key，直接进入下一个 Provider。这避免了"一把 key 限流就整个引擎下线"的浪费。

关卡 2：配额冷却，不浪费第二次撞墙

配额类失败会被 src/cooldown.ts 记录到~/.modlens/state.json：无重置时间的配额失败冷却45 分钟，月度预算类冷却24 小时（L60-L67）。冷却中的引擎不淘汰，只是被reorderByCooldown（analyzer.ts L421-L455）挪到自己所在区段的末尾——注意是区内末尾，不是全链末尾，这样远程 URL 不会因为冷却而被 Agent 抢走下载，安全边界依然成立。状态文件用临时文件 + 原子重命名写入，并发写互相合并，崩溃也不会留下半个文件（L137-L171）。

关卡 3：超时兜底，绝不挂死

子进程由 analyzer.ts 的 runCommand 托管：到点先 SIGTERM，2 秒不退再 SIGKILL；输出管道在进程退出后有 500 毫秒排空窗口，专门防"语言服务器继承管道导致永远等不到 close"这类经典坑（L794-L801）。

关卡 4：结构校验，"像 JSON 但不合规"也算失败

很多 Provider 能返回 JSON，但漏字段或结构不对。L585-L598 对每一路的结果做 schema 校验（src/schema.ts 定义契约），不合规直接判失败、移交下一路——而不是把残缺证据交给下游模型。

四、"永不沉默"：attempts 与 warnings 双账本

以上每一次尝试都写入meta.attempts，每一条路由通知都写入meta.warnings（结构见 analyzer.ts L57-L82）。一次"gemini 限流 → 切到 openai 第二把 key"的运行，输出会是这样：

"attempts": [ { "provider": "gemini-api", "ok": false, "error": "429 quota exceeded" }, { "provider": "openai", "keyIndex": 1, "ok": true, "durationSeconds": 7.2 } ], "warnings": ["Rotated to openai API key 2 after: openai (API key 1): 429 …"]

这就是"永不沉默"的完整定义：换路了会告诉你为什么换，花了谁的额度会告诉你，全链失败时把每一路的报错拼成一条聚合错误抛给你（L356-L360），甚至还会附上"这台机器上还有 Codex 等可复用视觉，要不要授权"的提示（reuseHint，L469-L508）。

效果层面，这就是纯文本模型"看懂"图片的体验：粘贴截图，模型逐元素描述界面，而背后的多路故障转移对使用者完全透明。

五、延伸阅读

一句话总结：ModLens 的 failover 链 =按速度分区的候选集 + 可用性过滤 + 区内换 key + 配额冷却 + 结构校验，外加一本从不缺席的"尝试账本"。任何一路沉默了，你都能从meta.attempts里找到它沉默的原因。

【免费下载链接】modlensThe first vision plugin for DeepSeek Harness, and the vision bridge for every text-only coding agent. Paste an image, get structured JSON evidence (OCR, layout, semantics). | 全网最强 DeepSeek Harness 外挂视觉插件，为 DeepSeek、GLM 等纯文本模型外挂视觉能力，粘贴图片即得结构化 JSON 证据（OCR、版面、语义）。项目地址: https://gitcode.com/gh_mirrors/mo/modlens