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/modlensModLens 是一个为 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 实现Provider需要什么单次耗时定位gemini-api免费 Gemini API key5-10 秒推荐首选openai任意 OpenAI 兼容端点5-10 秒通用水口qwen-vl、GLM、自建网关anthropicAnthropic API key5-10 秒手里已有 key 的机器antigravity-cli免费agyCLI浏览器登录15-45 秒零注册起步claude-cli已登录的 Claude Code20-45 秒复用你的 Claude 订阅kimi-cli已登录的 Kimi Code20-45 秒仅被点名时运行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三条设计原则值得细看快车道优先。注释里写得很直白内联 API 5-10 秒出结果Agent 类要 15-45 秒所以快的在前Agent 兜底L129-L135。远程 URL 链是安全边界。远程图片只有走内联下载路径才会经过 SSRF 防护、图片魔数校验和大小上限所以 Agent 类 CLI 永远不进入远程链claude-cli只读本地文件也永远不进入远程链L131-L135。kimi-cli是点名专属。它消耗 Kimi 订阅且没有内置即同意的历史所以被放进PIN_ONLY_PROVIDERS只有你显式-p kimi-cli或写入配置才会加入本地链L144-L148。可用性过滤只把真能用的引擎放进链providerAvailableavailability.ts L108-L127在运行时过滤链条子进程类 Provider 检查二进制是否在 PATH 上含 Windows 的.exe/.cmd后缀处理见 L86-L92API 类 Provider 检查必填配置是否齐备。过滤后的链由providerChain返回若用户配置了首选 provider它会移到所在区段的最前但不会越过安全边界。复用来的引擎则由 src/analyzer.ts 的composeChain按区段合并借用来的 API key 插在内联区尾部借用来的 Agent 插在claude-cli之前——速度档位决定位置授权先后不决定优先级。三、故障转移的瞬间一次失败的完整旅程主循环在 src/analyzer.ts 的analyzeImage里一次失败要经历四道关卡才轮到下一路关卡 1先换 key再换路同一 Provider 的apiKey支持逗号分隔多 key。鉴权、限流、配额类失败会continue到下一把 keyL269-L272而网络、5xx、解析类失败跳过剩余 key直接进入下一个 Provider。这避免了一把 key 限流就整个引擎下线的浪费。关卡 2配额冷却不浪费第二次撞墙配额类失败会被 src/cooldown.ts 记录到~/.modlens/state.json无重置时间的配额失败冷却45 分钟月度预算类冷却24 小时L60-L67。冷却中的引擎不淘汰只是被reorderByCooldownanalyzer.ts L421-L455挪到自己所在区段的末尾——注意是区内末尾不是全链末尾这样远程 URL 不会因为冷却而被 Agent 抢走下载安全边界依然成立。状态文件用临时文件 原子重命名写入并发写互相合并崩溃也不会留下半个文件L137-L171。关卡 3超时兜底绝不挂死子进程由 analyzer.ts 的 runCommand 托管到点先 SIGTERM2 秒不退再 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 等可复用视觉要不要授权的提示reuseHintL469-L508。效果层面这就是纯文本模型看懂图片的体验粘贴截图模型逐元素描述界面而背后的多路故障转移对使用者完全透明。五、延伸阅读文件看点src/providers/availability.ts失败链排序、可用性过滤的唯一事实源src/analyzer.ts主循环key 轮换、冷却重排、结构校验src/auto/discover.ts本机 5 个 Agent CLI 的只读探测src/auto/routes.ts借用引擎的路线构造与额度标注src/cooldown.ts配额冷却存储原子写、并发合并docs/output-schema.zh-CN.mdattempts/warnings输出契约docs/troubleshooting.zh-CN.md故障报错的逐条解读一句话总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考