@liustack/modlens v3.24.0 安装教程（DeepSeek Harness / dsh）

DeepSeek Harness 多模态插件安装、配置与验证说明。

编写日期：2026-08-22 ｜ 已在本机实测安装成功 官方仓库：https://github.com/liustack/modlens ｜ npm：https://www.npmjs.com/package/@liustack/modlens

一、这个插件是什么

@liustack/modlens 是作者 Leon Liu（liustack） 发布的 MIT 协议 npm 包，全称 ModLens，是给纯文本模型外挂视觉能力的桥插件。同门还有联网插件 @liustack/modsearch。

在 DSH 上它注册两样东西：

  1. modlens_read_image 工具 —— 模型每次请求都会看到这个工具 schema；消息里出现图片（本地路径或 http(s) URL）时调用它，返回结构化 JSON 证据（OCR 全文、版面区域、语义、不确定性列表）。
  2. (modlens vision) 模型变体 —— 自动为每条纯文本 DeepSeek/GLM provider 路由生成一组包装模型条目，模型选择器里带 (modlens vision) 后缀的就是它们；纯文本条目上粘贴图片也会变成文件路径走工具。

二、安装前提

项目要求
宿主DeepSeek Harness（~\.dsh 存在；Web 或桌面版均可）
Node.js>= 22.19（modlens 的 engines 硬性要求）
pnpm在 PATH 上（本机在 C:\Users\ASUS\AppData\Roaming\@deepseek-ai\dsh-desktop\runtime-bin\pnpm.cmd）
PowerShell若执行策略禁止 .ps1，用 npx.cmd 代替 npx

三、方法一：官方一条命令（推荐）

在 PowerShell 里执行（注意最后带 @3.24.0 版本号）：

powershell
npx.cmd -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.0

这条命令做了什么：

  1. 解析 profile 目录（默认 $DSH_HOME\profiles\web，DSH_HOME 未设置时取 ~\.dsh）；
  2. 在该目录里执行 pnpm add @liustack/modlens@3.24.0（参数原样转发给 pnpm）；
  3. 装完自动 reconcile：检测到该包 manifest 声明了 dsh.bundle.patch（v3.24.0 为 ./cordis.patch.yml），就自动把 @liustack/modlens 追加进 package.json 的 dsh.profile.bundles 列表——无需手改任何文件。

两个必须注意的坑（本次实测踩过）：

  1. DSH_HOME 陷阱：如果当前 shell 的 $env:DSH_HOME 被指到了别处（例如 DSH 的 free-mode 会话沙箱目录），CLI 会把 profile 初始化/安装到错误位置。先确认再装：
powershell
   Write-Output $env:DSH_HOME   # 应为 C:\Users\ASUS\.dsh
   $env:DSH_HOME = "$env:USERPROFILE\.dsh"   # 不是就手动指回来
   npx.cmd -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@3.24.0
  1. 版本号必须显式写：不写版本时，dsh 的 release-age 门控可能装到旧版并警告 declares no dsh.bundle（旧版没有 bundle 声明就不会进 bundles 列表，等于白装）。写 @3.24.0 表示用户明确指定版本，pnpm 会按精确版本解析。

装完后重启 DSH，插件即加载。

四、方法二：离线安装（用备份的 tgz）

没有网络或想完全离线时，用备份目录里的 tarball：

powershell
cd C:\Users\ASUS\.dsh\profiles\web
pnpm add C:\Users\ASUS\Documents\dsh-modlens\modlens-3.24.0.tgz
# 然后触发一次 reconcile（任何成功的 pnpm 子命令都会跑），把包加进 bundles：
npx.cmd -y @deepseek-ai/dsh plugin --profile web install

也可以手动编辑 C:\Users\ASUS\.dsh\profiles\web\package.json，在 dsh.profile.bundles 数组末尾追加 "@liustack/modlens"，再 pnpm install。

五、验证是否装好

  1. 重启 DSH（必须，profile 启动时才读 bundle 列表）；
  2. 打开模型选择器：出现带 (modlens vision) 后缀的模型条目 = 插件已生效；
  3. 工具列表里出现 modlens_read_image；
  4. 终端跑体检（不需要引擎也能跑，不耗额度）：
powershell
   npx.cmd -y modlens doctor

Selected provider 两行出现且对应 provider 显示 [ok] 即健康。

六、配置视觉引擎（必做，否则工具没有引擎可用）

modlens 需要恰好一个可用的视觉引擎，配置统一存在 ~\.modlens\config.json。三种路径任选：

路径 1：Gemini API key（推荐，免费 key 约 3 分钟，无卡）

powershell
npx.cmd -y modlens config set gemini-api.apiKey <你的KEY>
npx.cmd -y modlens config set provider gemini-api

key 支持逗号分隔多把，自动轮换。申请地址：https://aistudio.google.com

路径 2：Antigravity CLI（agy，无需 key，需要浏览器登录一次） —— 安装 curl -fsSL https://antigravity.google/cli/install.sh | bash，跑一次 agy 完成浏览器登录。无头环境（cron/SSH）不可用。

路径 3：已有的 OpenAI 兼容端点

powershell
npx.cmd -y modlens config set openai.baseUrl <url>
npx.cmd -y modlens config set openai.apiKey <key>
npx.cmd -y modlens config set openai.model <模型名>   # 必须支持图片输入
npx.cmd -y modlens config set provider openai

配置完再跑一次 npx.cmd -y modlens doctor 确认 [ok]。

⚠️ 注意：命令里的包名是 @liustack/modlens（scoped），npx modlens 会 404。

本机已配置（2026-08-23，路径 3 实测通过）：

配置项值
openai.baseUrlhttps://api.treeapi.online/v1
openai.apiKey复用 ~\.dsh\.credentials.yaml 的 TREEAPI_API_KEY
openai.modelqwen3.8-max（实测可读图；kimi-k2.6 也可用；glm-5.x/mimo/minimax 不支持 vision；seed-2.1-pro 大图报错）
provideropenai

实测 modlens doctor 显示 [ok] openai: baseUrl: file, apiKey: file (1 key), model: file；真实读图端到端通过（banner.jpg → OCR 精确输出，42s，4001 tokens）。

七、更新与卸载

powershell
# 更新（仍写显式新版本号）
npx.cmd -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@<新版本>

# 卸载（reconcile 会自动把 bundle 从列表移除）
npx.cmd -y @deepseek-ai/dsh plugin --profile web remove @liustack/modlens

八、本机文件位置清单

内容路径
安装位置（生效副本）C:\Users\ASUS\.dsh\profiles\web\node_modules\@liustack\modlens\
profile 清单（依赖 + bundles）C:\Users\ASUS\.dsh\profiles\web\package.json
独立备份副本（完整包体）C:\Users\ASUS\Documents\dsh-modlens\modlens-3.24.0\
离线安装包（tgz）C:\Users\ASUS\Documents\dsh-modlens\modlens-3.24.0.tgz
本教程C:\Users\ASUS\Documents\dsh-modlens\安装教程.md
视觉引擎配置（首次配置后生成）C:\Users\ASUS\.modlens\config.json

备份副本与安装副本是各自独立的真实文件（不是链接），安装副本被删/损坏时可直接从备份恢复。

九、本次实测记录（2026-08-22）

json
{
  "dependencies": {
    "@liustack/modlens": "3.24.0"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@liustack/modlens"
      ]
    }
  }
}

十、安全提示