ModLens Guard 机制源码解读：如何精准嗅探模型有无视觉能力，杜绝无效图片调用

ModLens Guard 机制源码解读如何精准嗅探模型有无视觉能力杜绝无效图片调用【免费下载链接】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 是一个为纯文本模型外挂视觉的开源视觉插件在 Claude Code、Codex、Pi、OpenCode 或 DeepSeek Harness 中粘贴图片即得 OCR、版面、语义齐全的结构化 JSON 证据。而它的 Guard 机制是整套插件的守门人——每次调用视觉引擎前先精准嗅探当前模型是否已具备原生视觉能力能自己看图就直接拒绝调用从而杜绝无效图片调用、省掉每一次浪费的 API 开销。全文不到 600 行核心源码带你读懂这套三层信号 fail-open的判定设计。一、为什么需要 Guard先问一句模型能自己看图吗 ️视觉引擎的每一次调用都是真实开销Gemini 的免费额度、OpenAI 兼容端点的配额、本地 CLI 的订阅时长都不该被浪费。ModLens 面向 DeepSeek、GLM 等纯文本模型但同一模型家族里往往混着自带视觉的成员例如 GLM-5.3 本身是纯文本GLM-5.3-Flash 则是原生多模态。没有守门人时视觉引擎会对本来就能看图的模型也触发一遍——纯粹的无效图片调用。这正是 Guard 要解决的问题源码注释里对应 issue #15keep the vision engine from firing when the active model already has native vision。上图是一次真实运行在 Claude Code 的 DeepSeek 会话中粘贴图片后skill 自动触发Guard 先确认这个模型确实没有视觉图片才进入视觉引擎最终把幻灯片的标题、版面、背景逐项读出。二、三层嗅探信号从环境变量到会话存储的判定链核心入口是 detectActiveModel它按证据强度从高到低依次检查三个信号第一个命中者定案1. 最强信号MODLENS_MODEL环境变量用户说了算用户显式设置的模型名拥有最高优先级直接覆盖一切。特别地MODLENS_MODELnone表示我明确不知道当前模型检测器会把模型标记为null而不是跳过检测。2. 次强信号会话存储嗅探transcript 才是地面真相检测器识别出当前宿主harness后直接读取它的本地会话存储。源码里的注释一语道破a model does not always know its own name, but its transcript does——模型未必报得出自己的名字但它的会话记录一定写清楚了。若存储证据与自报名称不一致还会把自报值保留在selfReported字段中留档方便排查。3. 最弱信号--model自报模型自己说模型可以报错名字所以自报仅在存储嗅探一无所获时才被采用三者皆无时判定source: none模型为未知。三、窗口式嗅探如何低成本读出 4 种 Harness 的当前模型 会话 transcript 可能内嵌 base64 图片、膨胀到数百 MB而 Guard 只需要两样东西文件末尾最新一条 assistant 记录模型名在这以及文件头部的 cwd 归属证据。因此 readWindowedLines 只做头尾各 512KB 的窗口读取并丢弃窗口边缘被截断的半行绝不全量解析。4 种宿主各有存储格式sniffModel 统一分发Harness存储位置定位当前会话的方式Claude Code~/.claude/projects/slug/session.jsonl优先用注入的CLAUDE_CODE_SESSION_ID精确锁定会话再按目录扫描Codex~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl用CODEX_THREAD_ID锁定或按文件名mtime 只查最近 20 个Pi~/.pi/agent/sessions/slug/按项目目录扫描OpenCode本地 SQLite以只读模式打开SQL 直接取最新一条 assistant 消息的modelID细节上还有不少工程考量Codex 的 rollout 按日期分层存放利用相对路径即创建时间免去海量 stat 调用sniffCodexModelOpenCode 走node:sqlite运行时不支持时直接放弃opencodeModelForCwd。四、规则引擎deny 优先的 glob 匹配与 allow 白名单 ⚙️判定规则集中在 rules.ts配置只有三个旋钮GuardsConfig配置键语义denyModels带原生视觉的模型 glob 模式列表命中即永不触发引擎allowModels白名单模式非空时只有列出的模型能跑引擎denyWhenUnknown模型无法识别时是否拒绝默认 false即放行evaluateGuard 的判定链条很短模型未知 →denyWhenUnknown为真则 deny否则 allowfail open未配置任何规则 → allow命中 deny 列表 →denydeny 永远压过 allowallow 列表非空 → 命中 allow 则 allow未命中即 deny其余情况 → allow。匹配函数 globMatch 只认*和?两个通配符大小写不敏感、首尾锚定其余字符一律按字面转义——因为模型 ID 里满是正则元字符gpt-5.6、provider/model手写转义极易埋雷。匹配时会同时尝试模型名和provider/模型名两种候选。经典组合是白名单里再挖坑allow: glm-*deny: glm-*v*一句话把带视觉的变体从宽泛放行中剔除。五、fail-open 设计为什么未知模型默认放行 这是 Guard 最有意思的哲学文件头注释 说得很透错杀一次误拦会打断本工具存在的意义——纯文本模型的读图桥错放一次误许只是浪费单次的 provider 调用。所以未知模型默认放行。为守护这个原则代码处处设防配置文件允许手改且不校验denyWhenUnknown用严格 true判断字符串false也是真值会意外翻转为拒绝嗅探器任何异常都返回null、绝不阻断读取。还有一条性能快路径runGuard当不存在任何可能拒绝的规则时直接跳过全部检测工作——省去进程探测与存储读取零开销放行。六、落地位置analyze 硬门禁与 modlens guard 建议命令Guard 有两个出口姿态不同main.ts硬门禁analyze命令内仅当用户显式设置了MODLENS_MODEL且模型被识别时生效命中 deny 就抛错拒绝并附带覆盖提示解除MODLENS_MODEL或编辑~/.modlens/config.json中的 guards。建议式modlens guard命令main.ts输出判定供 agent 参考deny 是建议而非上锁的门deny 时退出码为 1。存储嗅探与denyWhenUnknown策略只在这一侧发声永不阻断analyze。被拒绝时你会看到这样的报错解读见 docs/troubleshooting.zh-CN.mdInvocation guard denied this read: active model gemini-3.1-pro matches guards.denyModels pattern gemini-3*. A model with native vision should read the image itself. To override, unset MODLENS_MODEL or edit guards in /Users/you/.modlens/config.json.一个已知盲区同一项目目录里并发跑两个不同模型的会话可能互相遮蔽Claude Code 和 Codex 靠注入的会话 ID 可锁定Pi 和 OpenCode 不能——中招时用MODLENS_MODEL覆盖即可。上图是 ModLens 的整体链路Guard 就站在modlens skill与视觉引擎之间的那道闸门上——嗅探通过才放行从源头上杜绝无效图片调用。七、快速上手3 条命令完成 Guard 配置 配置键的完整说明见 docs/cli.zh-CN.md日常最常用的就三条modlens config set guards.denyModels # 彻底关闭 deny 规则 MODLENS_MODELnone modlens guard # 把模型标为未知查看判定结果 modlens doctor # Guard 小节规则、检测来源、最终判定八、源码文件速查表文件职责src/guard/index.ts入口三层信号检测detectActiveModelrunGuard快路径src/guard/rules.ts规则引擎glob 匹配、deny/allow 判定、fail-opensrc/guard/modelSniff.ts嗅探器4 种 Harness 会话存储的窗口式读取src/main.tsanalyze中的硬门禁docs/troubleshooting.zh-CN.md报错解读、覆盖方式与已知盲区docs/cli.zh-CN.mdguards.*配置键说明一句话总结ModLens Guard 用环境变量 会话存储 自报的三层信号精准嗅探模型视觉能力用 deny 优先的 glob 规则做判定用 fail-open 兜底所有意外——既拦住了对原生视觉模型的无效图片调用又绝不误伤纯文本模型的读图桥。【免费下载链接】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），仅供参考