前言¶

DeepSeek Harness（dsh）是 DeepSeek 開源的智能體運行時，官方定位是開發者預覽版，口號是「一切皆插件」：模型適配、工具註冊、會話日誌、Agent 循環，都可以用插件替換，而不必改運行時源碼。啓動 Web UI 的官方入口是：

npx @deepseek-ai/dsh web

日常編碼裏更常見的矛盾是另一面：DeepSeek、GLM 這類主力對話模型是純文本的，看不見截圖。報錯界面、設計稿、PDF 頁、前端渲染結果，往往只能先口述，再讓模型猜。社區目錄 deepseek-harness-plugin.com 是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係；它把這類擴展按分類收錄，其中「工具與能力」下有一個被標成精選的插件：modlens。

本文按該目錄詳情頁、GitHub 倉庫 README / INSTALL.md / 宿主接入文檔 / 輸出契約，以及 DeepSeek Harness 官方說明覈對後整理：它是什麼、裝完能做什麼、命令怎麼寫、讀圖結果長什麼樣。

這是什麼¶

modlens 是由 liustack（作者署名 Leon Liu）維護的視覺插件，npm 包名 @liustack/modlens，許可證 MIT，主要語言 TypeScript。寫作時倉庫 package.json 版本爲 3.18.1（2026-08-17），要求 Node.js >= 22.19。社區目錄把它分在「工具與能力」，收錄日期 2026-08-14；GitHub 倉庫頁面在 2026-08-17 顯示 2384 star（目錄頁快照爲 1548，星標以倉庫頁面爲準）。

目錄頁和倉庫 README 的定位一致：它是 DeepSeek Harness 上的視覺插件，也是純文本編碼 agent 的視覺橋樑——把圖片交給外掛視覺引擎，返回帶 OCR、版面和語義的結構化 JSON，再交給當前會話裏的純文本模型去推理。

在 dsh 裏，它不是一份靠提示詞觸發的 Skill。倉庫 INSTALL.md 寫得很明確：只拷貝 skills/modlens 文件夾，用戶拿不到 modlens_read_image 工具，也看不到 (modlens vision) 模型條目（相關說明見 issue #32）。正確形態是原生插件（dsh bundle）：註冊工具、包裝純文本路由、在 Web UI 裏接管粘貼。

同一套讀圖引擎也以 Skill 形式出現在 Claude Code、Codex、Pi、OpenCode 上，配置都寫在 ~/.modlens/config.json。本文以 dsh 爲主。

核心功能¶

1. 原生工具 modlens_read_image¶

裝進 dsh 之後，插件註冊 modlens_read_image。工具 schema 隨每次請求發給模型，不靠關鍵詞啓發式。模型看到圖片路徑或附件時調用它，插件在包內跑自己的 CLI，把結構化證據作爲工具輸出返回。

倉庫 CHANGELOG 3.16.3 解釋過命名原因：dsh 若已有宿主自己的 read_image，分層註冊不會報衝突，模型仍會打到宿主工具，而宿主工具對純文本模型是拒絕的。所以插件改用自己的名字，避免搶注。

2. 兩種粘貼路徑¶

倉庫 README 把 dsh 上的貼圖分成兩條，走哪一條由宿主根據模型元數據（inputModalities）判斷，而不是按名字猜：

1. 直接粘貼（paste-to-path）
   當前模型被確認是純文本時，瀏覽器端把圖片發到本機 dsh web 服務器的 /modlens/paste（僅迴環、校驗 magic byte、上限 25 MB），落成私有臨時文件，輸入框裏出現的是文件路徑。消息不帶圖片附件，dsh 的圖片准入檢查不會攔住。這和 Pi、OpenCode、Claude Code 遞給模型的形態接近，也是 modlens_read_image 的首要觸發條件。

2. 切到 (modlens vision) 變體再粘貼
   插件會給每條承載純文本 DeepSeek / GLM 的 provider 路由自動加包裝條目。默認安裝下常見的是 DeepSeek-V4-Flash (modlens vision) 和 DeepSeek-V4-Pro (modlens vision)；額外路由（如 opencode-go、zai）會各自多一組。兩家自己的視覺型號會被排除。這條路徑保留縮略圖，在發請求時把圖片塊轉成證據文本。選擇器有記憶，選一次即可。

元數據確認不了、或模型聲明支持圖片輸入時，粘貼保持原生，視覺模型繼續自己讀圖。插件配置行裏設 pasteToPath: false 可以關掉第一條路徑。

3. 結構化證據，而不是一段散文¶

每次識別向 stdout 打一個 JSON（輸出契約 v2）。外層大致是：

{
  "image": "/abs/path/or/url",
  "provider": "gemini-api",
  "result": { },
  "meta": {
    "generatedAt": "2026-08-01T12:00:00.000Z",
    "model": "gemini-3.6-flash-low",
    "durationSeconds": 25.4,
    "attempts": [],
    "warnings": []
  }
}

result 的必填頂層字段是 summary、ocr、layout、semantics、visual、uncertainty：

• ocr：全文轉錄，以及按行切分的文本
• layout.regions：按閱讀順序劃分的區塊，type 是自由字符串（title、paragraph、table、chart、code、link、nav 等只是文檔裏的常用詞，不是封閉枚舉）
• semantics：場景、實體、關係
• visual：主色、風格等補充
• uncertainty：讀不清的地方如實列出，而不是填進去

相對 v1，v2 刪掉了像素級 bbox 和數值型 confidence。文檔的理由是視覺模型最容易把這兩項編圓。結構不合格的結果會走故障轉移，而不是直接交給上游模型。meta.attempts 記錄鏈上每一次嘗試；複用了本機某個 CLI 的額度時，meta.warnings 會標明花的是誰的配額。

4. 多引擎，一條故障轉移鏈¶

modlens 不綁定單一視覺服務。倉庫文檔列出六個內置 provider，配好其中一個就能用：

不釘死 provider 時，已配置的引擎組成故障轉移鏈：API 快車道先試，agent CLI 兜底，第一個可用結果勝出。openai 在這裏是協議插座，不是「只能連 OpenAI」：DashScope 上的 qwen-vl、GLM 開放平臺、SiliconFlow、OpenRouter、自建 vLLM / Ollama，只要走 chat-completions 且支持圖片輸入，都可以用同一組鍵。

本機已登錄的 Codex、OpenCode、Pi、Grok CLI，要先 config set reuse.<name> true 纔會進鏈，不會默認扣別人的訂閱。kimi-cli 也是顯式點名才跑，因爲它會消耗 Kimi Code 訂閱。

安裝與啓用¶

社區目錄給出的命令¶

插件詳情頁上的安裝命令原文是：

dsh plugin add github:liustack/modlens

需要可復現安裝時，目錄頁要求固定 commit 哈希：

dsh plugin add github:liustack/modlens#<commit>

目錄頁同時提示：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；安裝前應檢查源代碼倉庫和許可證。

倉庫針對 dsh 的版本釘死寫法¶

INSTALL.md 和 docs/harness-setup.md 給 dsh 用戶的命令是另一條。寫作時釘在 3.18.1：

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

倉庫刻意不用 @latest：pnpm 11 默認開啓 minimumReleaseAge（24 小時），dist-tag 只在過了冷靜期的版本里解析，@latest 可能裝到一天前的舊版。點名版本號是明確指定。更新也用 add 而不是 update：update 只在已記錄的 semver 範圍內移動，caret 範圍裝進來的 2.x 到不了 3.x。

當前版本可用下面命令查詢，再把命令裏的版本號換成輸出值：

npm view @liustack/modlens version

裝完重啓 dsh，在模型選擇器裏找帶 (modlens vision) 後綴的條目。列表確認可以：

npx -y @deepseek-ai/dsh plugin --profile web list

若出現 declares no dsh.bundle，倉庫的判斷是發佈冷靜期裝到了舊包，按宿主接入文檔的「保持更新」一節處理，不要改去拷貝 Skill 目錄。

web 只是文檔裏的示例 profile。實際 profile 名以本機爲準，把 --profile 換成自己的即可。

配置一個視覺引擎¶

插件能掛上工具，但真正讀圖的是引擎。配置文件是 ~/.modlens/config.json，dsh 和其他 harness 共用。Web UI 用戶可以打開 設置 → 插件 → 插件配置 裏的卡片：選引擎、填 key / 地址 / 模型、授權本機哪些登錄可被借用。卡片通過迴環路由讀寫同一份文件，不會把已保存的密鑰送進瀏覽器；密鑰框留空表示保持原值。

倉庫推薦的命令行起步是 Gemini API（Google AI Studio 申請，條款和額度以 Google 爲準）：

modlens config set gemini-api.apiKey
modlens config set provider gemini-api

不跟參數時，apiKey 會隱藏回顯提示輸入，避免 key 進 argv 和 shell history。想完全免註冊，倉庫給出的是 Antigravity CLI：

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy

在瀏覽器完成登錄後退出。無圖形界面、SSH 無桌面的環境，文檔建議不要走這條，改用 API key。

接 OpenAI 兼容的視覺模型（示例來自倉庫 README，端點以各平臺當前文檔爲準）：

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

三個字段都要齊，且模型必須接受圖片輸入。同一套鍵可換成其他兼容網關。從 3.17.0 起，某個 provider 一旦寫進配置文件，憑據就以文件爲準，不再和 OPENAI_API_KEY 這類環境變量按字段混用，避免「地址來自文件、密鑰來自環境」拼出一份兩邊都不存在的憑證。

體檢¶

modlens doctor

成功時看兩行：Selected provider 下面的名字，以及它在 Providers 列表裏是否爲 [ok]。其餘 provider 顯示 [!!] 是正常的。常見問題文檔已經列過：Node 低於 22.19、Gemini 沒寫入 apiKey、agy 不在 PATH。加 --json 可拿到機器可讀報告。

端到端試一次（會消耗一次識別額度）：

modlens -i /path/to/image.png

典型用法¶

裝好之後，在 dsh 里正常對話即可。下面幾條都來自倉庫文檔和目錄頁，不是另行編造的案例。

1. 純文本模型下直接粘貼截圖¶

選普通的 DeepSeek-V4-Flash / DeepSeek-V4-Pro 這類純文本條目，把報錯界面或 UI 異常粘進輸入框。瀏覽器半邊把圖片落成臨時文件，路徑進入 composer，模型調用 modlens_read_image，再根據 JSON 裏的 OCR 和版面回答。目錄頁把這個變化概括成：從「幫我描述這張截圖」變成「屏幕上到底有什麼」。

2. 切到視覺變體，保留縮略圖¶

在模型選擇器裏選 DeepSeek-V4-Flash (modlens vision)（或本機自動生成的對應條目），再粘貼。縮略圖留在消息裏，軌跡裏可以看到圖片在發請求時已被轉寫。倉庫 README 用一張 DeepSeek Harness 貼圖演示過這條路徑，驅動的是純文本 DeepSeek-V4-Flash。

注意倉庫 issue #40 寫明的限制：會話裏一旦存在圖片附件，dsh 會拒絕切回聲明不含圖片模態的普通純文本條目。(modlens vision) 變體能切過去，是因爲它在發請求時把圖片塊轉成證據文本。走第一條「粘貼轉路徑」則不會產生附件，選擇器也不會被鎖住。

3. 文檔頁、設計稿、前端還原¶

目錄頁列出的三類場景：

• 文檔提取：長 PDF 頁、幻燈片、截圖變成可查詢的結構化數據
• 前端工作：給智能體看設計稿或渲染後的頁面，按佈局語義寫或改代碼
• 用截圖調試：報錯和 UI 異常直接貼進對話

需要大規模長截圖 OCR 時，目錄頁建議再搭配 dsh-vision-toolkit（相關列表裏對應條目是 agent-vision-toolkit）。modlens 自己定位的是「粘貼一張圖，拿回一份證據 JSON」，不是長圖流水線。

4. 倉庫 README 裏的實測記錄¶

這些是 README 標明的原樣記錄，驅動模型都是純文本 DeepSeek-V4-Flash，用來說明輸出粒度，不是第三方評測：

• Codex 桌面裏讀推文截圖：作者、配文、照片細節、時間和互動數字
• 一次三張圖：逐張讀取，並判斷是否同屬一個視覺家族
• 128 個模型的對比散點圖：座標軸、對數刻度、廠商配色、高亮區域和虛線標註的 DeepSeek 型號
• Claude Code 終端裏粘貼幻燈片：標題、版式、背景；文件名被截斷時寫入 uncertainty，而不是編一個完整文件名

適用場景與注意事項¶

比較適合：

• 在 dsh 裏用 DeepSeek / GLM 純文本模型做編碼，但經常要看截圖、設計稿、報錯界面
• 希望模型引用圖上的具體文字和區塊，而不是憑空描述
• 已經有 Gemini / 兼容視覺 API，或本機已登錄 Claude Code、Codex 等，希望複用而不是再搭一套多模態網關

使用前注意下面幾條，均來自目錄頁或倉庫文檔：

1. 權限與許可證。 插件以當前 dsh 進程權限運行，安裝時可能執行代碼。安裝前檢查 源碼 和 MIT 許可證。社區目錄不是官方應用商店。
2. dsh 仍是開發者預覽。 插件接口可能變化。modlens 自稱接觸面很小（工具註冊、視覺變體用的 llm 適配層、附件讀取、一個 agent 執行前鉤子），接口挪了會報錯而不是靜默失效。
3. 圖片內容按不可信輸入處理。 截圖裏可以寫給模型看的指令。安全文檔要求：只分析你願意打開的圖；不信任的圖優先釘死 -p gemini-api（由 modlens 下載字節、不跑本地 agent）。遠程 URL 由誰抓取因 provider 而異：gemini-api 本地下載並做私有地址 / magic-byte / 25 MB 檢查；openai / anthropic 把 URL 交給對方去抓；agent CLI 則自己去拉。
4. 本機運行時。 需要 Node 22.19+。macOS / Linux 在 CI 的 Node 22 和 24 上驗證；Windows 跑同一套矩陣，但 Antigravity、Claude CLI 等外部引擎只在有對應 Windows 構建的平臺上可用。
5. 臨時文件。 3.18.1 起，paste-to-path 的文件集中存放並按一週或 1 GB 上限清理（先刪最舊的），因爲路徑會進 composer，請求結束時不能立刻刪。目錄按不可信地面處理：解析後創建、拒絕符號鏈接和無法設爲私有的目錄。
6. 不要用 @latest 更新。 查出當前版本號再點名安裝。Skill 安裝流程只適用於 Claude Code / Codex / Pi / OpenCode，不要在 dsh 上走那條路。
7. 倉庫不接受 Pull Request。 作者說明是單人審閱全部代碼。反饋走 Issues；MIT 下可以自行 fork。
8. 上游額度自負。 Gemini、OpenAI、Anthropic、Antigravity 以及任何兼容端點，使用受各自條款約束。複用本機 CLI 時，結果裏會標註花了誰的配額。

小結¶

modlens 要解決的問題很具體：dsh 背後的純文本模型看不見圖。它以原生插件接入，註冊 modlens_read_image，按模型元數據決定是把粘貼變成文件路徑，還是走 (modlens vision) 變體在發請求時轉寫；讀圖結果是帶 OCR、版面、語義和不確定項的 JSON，而不是一段無法覈驗的描述。引擎可以是 Gemini、OpenAI 兼容端點，或本機已經登錄的 agent CLI，配置集中在 ~/.modlens/config.json。

目錄頁與倉庫：

• 社區目錄：https://deepseek-harness-plugin.com/zh-CN/plugins/modlens/
• GitHub：https://github.com/liustack/modlens
• dsh 安裝說明：https://github.com/liustack/modlens/blob/main/INSTALL.md
• 宿主接入：https://github.com/liustack/modlens/blob/main/docs/harness-setup.md
• 輸出契約：https://github.com/liustack/modlens/blob/main/docs/output-schema.md
• DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness