源码系统概览
文章正文
ModLens 是一款为纯文本大模型补上视觉能力的识别插件，粘贴图片即可返回结构化 JSON 证据。
项目面向 DeepSeek Harness（dsh）深度集成，同时以标准 Skill 与 CLI 形式支持 Claude Code、Codex 等编程智能体环境。
源码简介
ModLens 的核心流程是把图片交给视觉模型，再以强制 JSON Schema 输出 OCR 文本、版面结构与语义摘要。
默认使用免费的 Antigravity CLI 驱动，未配置任何密钥也可以直接使用。
失败切换链按顺序尝试已配置的 provider，包括 Gemini API、Anthropic API，以及本机已登录的 Claude、Codex、Pi、Grok、OpenCode CLI。
自动模式会扫描本机已存在的模型环境，复用其凭据与模型配方，省去手工配置。
项目采用 MIT 协议开源，作者为 Leon Liu，npm 包名 @liustack/modlens，GitHub 已有 3049 颗星，当前版本 3.20.0。
适用场景
适合给纯文本模型补视觉的场景，例如把截图、图表、票据图片粘贴进 DeepSeek 对话并获得结构化读取结果。
适合批量图片识别任务，多张图片可一次粘贴，逐张生成证据记录。
适合零密钥起步的用户，Antigravity CLI 免费通道即可完成基础 OCR 与版面识别。
与 Tesseract 这类传统 OCR 引擎相比，ModLens 输出的是语义化的 JSON 证据，而不是纯文本行，更适合智能体消费。
功能亮点
粘贴图片即触发识别，dsh 原生插件模式通过 npx 一条命令安装，标准 Skill 模式覆盖其他智能体环境。
输出契约固定为 JSON Schema，包含 OCR、版面、语义三类证据，方便程序化消费。
provider 失败切换链保证单点故障不中断，自动发现复用本机 Claude、Codex 等已登录 CLI。
远程图片下载带 SSRF 防护，密钥在日志与配置输出中自动打码，仓库内置泄漏回归测试。
模型守卫支持 allowModels 白名单，防止配置外的模型被调用。
与纯 OCR 库相比，ModLens 更侧重智能体工作流中的证据消费，而不是通用文字识别引擎。
| 维度 | ModLens | Tesseract OCR |
|---|---|---|
| 技术栈 | TypeScript CLI、多 provider 桥接 | C++ 引擎、多语言绑定 |
| 部署复杂度 | npm 安装，自动发现本机 CLI | 需安装引擎与语言包 |
| 功能侧重 | 结构化 JSON 证据、智能体工作流 | 纯文本行识别 |
技术架构与部署指南
技术栈与运行环境
前端：CLI 与插件形态，无独立 Web 界面，dsh 内置卡片渲染识别结果。
后端：TypeScript CLI，基于 Commander 命令解析，Vite 打包为 ES 模块。
数据库：无外部数据库，配置存于 ~/.modlens/config.json，会话缓存读取本机智能体记录。
运行环境：Node.js 与 npm 或 pnpm，macOS、Linux、Windows 均可运行。
其他依赖：Antigravity CLI、Gemini 或 Anthropic API Key，或本机 Claude、Codex、Pi、Grok、OpenCode CLI。
安装与部署提示
dsh 环境执行 npx -y @deepseek-ai/dsh plugin –profile web add @liustack/modlens@3.20.0 安装原生插件。
通用智能体环境通过 npm 安装 modlens，或把 skills/modlens 目录挂为 Skill。
首次使用执行 modlens config init 生成配置，modlens config show 查看生效配置，密钥自动打码。
选择默认 provider 用 modlens config set provider gemini-api，各字段可分别设置。
未配置任何 provider 时自动落到 antigravity-cli 免费通道。
截图与演示说明
在 DeepSeek Harness 中直接粘贴图片，插件自动触发 modlens_read_image 工具并返回证据卡片。
assets 目录演示图展示把推文截图粘贴进纯文本 DeepSeek，识别结果逐字还原内容。
多图场景演示三张图片同时拖入，按顺序逐张读取并合并结果。
图表场景演示 128 模型散点图的坐标轴、对数刻度与高亮区域全部还原。
Claude Code 会话演示 Skill 自动触发并读取粘贴的幻灯片。
常见问题
问：ModLens 免费吗？
是，项目以 MIT 协议开源，源码免费下载，默认 Antigravity CLI 通道免费，其余 provider 按各自计费。
问：没有 API 密钥能用吗？
能，默认 fallback 到免费的 Antigravity CLI，配置了 Gemini 或 Anthropic Key 后走对应通道。
问：和 Tesseract 有什么区别？
Tesseract 输出纯文本，ModLens 输出结构化 JSON 证据，包含 OCR、版面与语义三层信息，更适合智能体直接消费。
问：支持哪些智能体环境？
DeepSeek Harness 用原生插件，Claude Code、Codex 等环境用 Skill 或 CLI 方式接入。
安全风险提示
本次检查未发现明显恶意文件，源码涉及本地 CLI 调用与模型密钥处理。
路径：src/guard；类型：模型守卫；证据：allowModels 白名单限制可调用模型；建议：按需收紧白名单。
路径：src/net；类型：远程图片下载；证据：SSRF 防护覆盖远程图片抓取路径；建议：保持防护开关开启。
路径：src/providers；类型：密钥管理；证据：API Key 存于本地配置，日志自动打码；建议：配置文件权限设为仅当前用户可读。
特别提示：本源码未检测安全风险文件，下载后请务必进行安全审计，删除恶意代码后再部署使用！
下载说明
源码仅供学习研究、测试部署和二次开发参考，商用前请自行确认授权、版权和安全风险。
插件会调用本机已登录的智能体 CLI 与模型 API，请妥善保管密钥并理解调用产生的费用。
最后更新：2026-08-18。
GitHub项目开源地址：https://github.com/liustack/modlens