ModLens 是什么？让 DeepSeek Harness 纯文本模型看懂图片

ModLens 是 DeepSeek Harness（DSH）的视觉插件，专门解决 DeepSeek、GLM 等纯文本模型无法读取图片的问题：把图片直接粘贴进聊天，就能得到包含 OCR 转录、版面与语义的结构化 JSON 证据，模型引用具体细节而不是凭空想象。 本文介绍 ModLens 是什么、核心功能、完整的安装更新卸载命令、典型用法与常见排错，帮助你在 DSH Plugin 生态中零配置获得视觉能力。

modlens 是什么？

ModLens 是一个插件式视觉引擎，给纯文本模型装上「眼睛」，让它们能看懂直接粘贴进聊天的图片。 ModLens 由 liustack 维护、采用 MIT 协议，官方将其定位为 DSH 生态中能力最全面的视觉插件（来源）。DeepSeek 旗舰聊天模型与 GLM-5.3 都是纯文本模型，本身读不了图，GLM-5.3-Flash 才是原生多模态。过去要看图，得先把图片存成文件再把路径塞给模型，但纯文本模型依然「看不见」那个路径。ModLens 把流程压成「粘贴即读」：图片进入会话后由原生 modlens_read_image 工具接管，输出完整转录、阅读顺序版面区域、实体与关系列表。它安装一次即可在 Claude Code、Codex、Pi、OpenCode 等多个环境复用，属于 DSH Plugin 生态的一员。

modlens 的核心功能有哪些？

ModLens 的核心能力是粘贴即读、自动发现纯文本模型路由、零配置启动、多密钥轮换与故障转移，以及证据式结构化输出。 这些能力全部来自官方 README（来源）：

• 粘贴即读：在聊天里直接粘贴图片，无需先保存文件再传路径；一次粘贴后，对同一张图的后续提问无需再次粘贴。
• 自动发现与包装模型路由：自动发现每条携带纯文本 DeepSeek、GLM 或 MiMo Pro 模型的路由并追加包装条目，默认生成 DeepSeek-V4-Flash (modlens vision) 与 DeepSeek-V4-Pro (modlens vision)；原生视觉模型（如 GLM-5.3-Flash）自动排除。
• 零配置启动：复用 Claude Code、Codex、OpenCode、Pi 的现有登录；本机什么都没有时，免费 Antigravity CLI 无密钥可用，免费 Gemini 密钥能把读取降到 5-10 秒。
• 多密钥轮换与故障转移：逗号分隔的 API 密钥在认证、限流、配额失败时轮换到下一个；网络、5xx、解析类失败跳过剩余密钥并保留提供商故障转移。
• 证据而非想象：输出完整转录、版面区域、实体与关系列表；meta.attempts 记录每次尝试，回退不会静默发生。

怎么安装与启用 modlens？

在 DeepSeek Harness 中安装、更新与卸载 ModLens 都只需一条 dsh plugin 命令，启用后直接粘贴图片即可使用。 官方安装命令钉死了显式版本 @liustack/modlens@3.25.2，避免 pnpm 11 对新发布版本延迟导致装到旧版（来源）：

1. 安装 ModLens：在 DeepSeek Harness 终端执行安装命令，把插件装进 web profile：

npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.25.2

等待命令输出安装完成；通过 DSH Plugin 市场安装的，直接在「设置 → 插件市场」搜索 modlens 一键安装。

2. 启用 ModLens：DSH 启动时自动加载插件，无需额外命令。在「设置 → 插件」确认出现 ModLens 卡片即已启用，零配置即可用。

3. 更新 ModLens：执行更新命令，把已安装版本升到最新：

dsh plugin --profile web update @liustack/modlens

重跑安装命令与更新同义，都能拿到最新版本。

4. 卸载 ModLens：执行卸载命令，从当前环境移除插件：

dsh plugin remove @liustack/modlens

在 Claude Code、Codex 等 skill 类 harness 上，卸载就是删除对应 skill 文件夹，代理立即恢复原样。

modlens 典型用法

ModLens 的典型用法是直接粘贴图片，或在模型选择器选中带 (modlens vision) 的条目再粘贴；进阶用法是用 modlens config set 接入任意 OpenAI 兼容视觉模型。（来源）

1. 直接粘贴：在聊天输入框粘贴图片，图片以私有临时文件进入编辑器并带路径，modlens_read_image 自动接管并转换为结构化证据，无需任何命令。 2. 选包装条目再粘贴：在模型选择器选中 DeepSeek-V4-Flash (modlens vision)（它记住选择，一次即可），缩略图保留在消息里，请求时转换，由同一条底层路由回答，无需任何命令。 3. 健康检查：运行健康检查命令，查看本机哪些 agent CLI 可复用、引擎池是否就绪：

modlens doctor

4. 指定视觉引擎：设置偏好引擎（如免费且快的 gemini-api），执行命令：

modlens config set provider gemini-api

要接入 OpenAI 兼容端点（如 qwen-vl），依次执行三条配置命令：

modlens config set openai.baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1
modlens config set openai.apiKey <key>
modlens config set openai.model qwen3-vl-plus

5. 多密钥与代理：openai.apiKey 可写逗号分隔列表自动轮换；代理环境执行命令，让 API 提供商走代理：

modlens config set proxy <url>

modlens 常见问题与排错

ModLens 最常见的三类问题是模型不读图、读图失败或超时、代理环境请求失败，分别通过选 vision 条目、modlens doctor 检查、配置代理解决。 官方还提供独立的 Troubleshooting 文档（来源）：

1. 粘贴图片后模型不读图：症状是图片粘贴后模型答非所问或忽略图片；原因是当前模型未被 ModLens 接管——它只接管元数据确认为纯文本的模型。解决：在模型选择器选中 (modlens vision) 条目，或换用 DeepSeek/GLM 纯文本系列模型。 2. 读图失败或长时间无响应：症状是 modlens_read_image 报错或一直转圈；原因是引擎未配置或密钥额度耗尽。解决：先运行健康检查命令排查引擎状态：

modlens doctor

再配置免费 Gemini 密钥把读取降到 5-10 秒；多个密钥用逗号分隔，让 ModLens 在认证、限流、配额失败时自动轮换。

3. 代理环境下安装或读图失败：症状是联网请求超时或被拒；原因是请求没走系统代理。解决：设置环境变量 HTTPS_PROXY，或执行命令让 API 提供商走代理：

modlens config set proxy <url>

适用场景与注意

ModLens 适合所有在 DeepSeek Harness 里运行纯文本模型又需要读图的场景，但注意它只接管纯文本模型、需要 Node.js 环境、且不接受 pull request。（来源）

适用场景包括：DeepSeek-V4 纯文本模型看截图、读数据图表（README 展示过 128 模型散点图逐轴读取）、一次粘贴多张图逐张分析、读推文截图里的作者、文案与互动数。注意事项：

1. 只接管元数据确认为纯文本的模型，视觉模型自动排除，未确认的保持原生粘贴，视觉模型的原生粘贴体验不受影响。
2. 基于 TypeScript 开发，需要 Node.js 环境。
3. 项目不接受 pull request，作者逐行审查；贡献方式是开 Issue 或 fork 自用（MIT 协议）。
4. 上游引擎（Antigravity CLI、Gemini/OpenAI/Anthropic API 及兼容端点）受各自条款与配额约束，使用前需自行确认。

项目链接

ModLens 是 liustack 维护的 MIT 开源项目。 插件详情页：ModLens 插件详情。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：liustack/modlens。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。