企业官网建设流程全解析

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/modlens

ModLens 是一个为纯文本模型外挂视觉的开源视觉插件：在 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 #15）：keep the vision engine from firing when the active model already has native vision。

上图是一次真实运行：在 Claude Code 的 DeepSeek 会话中粘贴图片后，skill 自动触发，Guard 先确认"这个模型确实没有视觉"，图片才进入视觉引擎，最终把幻灯片的标题、版面、背景逐项读出。

二、三层嗅探信号：从环境变量到会话存储的判定链

核心入口是 detectActiveModel，它按证据强度从高到低依次检查三个信号，第一个命中者定案：

1. 最强信号：MODLENS_MODEL环境变量（用户说了算）

用户显式设置的模型名拥有最高优先级，直接覆盖一切。特别地，MODLENS_MODEL=none表示"我明确不知道当前模型"，检测器会把模型标记为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 统一分发：

细节上还有不少工程考量：Codex 的 rollout 按日期分层存放，利用"相对路径即创建时间"免去海量 stat 调用（sniffCodexModel）；OpenCode 走node:sqlite，运行时不支持时直接放弃（opencodeModelForCwd）。

四、规则引擎：deny 优先的 glob 匹配与 allow 白名单 ⚙️

判定规则集中在 rules.ts，配置只有三个旋钮（GuardsConfig）：

evaluateGuard 的判定链条很短：

1. 模型未知 →denyWhenUnknown为真则 deny，否则 allow（fail open）；
2. 未配置任何规则 → allow；
3. 命中 deny 列表 →deny（deny 永远压过 allow）；
4. allow 列表非空 → 命中 allow 则 allow，未命中即 deny；
5. 其余情况 → 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.md）：

Invocation 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_MODEL=none modlens guard # 把模型标为未知，查看判定结果 modlens doctor # Guard 小节：规则、检测来源、最终判定

八、源码文件速查表

一句话总结：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