前言¶

做智能體開發常碰到這樣一個缺口：主 agent 用的模型路由沒有聲明 image 輸入，是個純文本模型。用戶丟過來一個圖片路徑讓它描述，它做不到——要麼手動換到有視覺能力的會話，要麼自己看一眼圖再轉述給它。DeepSeek Harness（下稱 DSH）的理念是「一切皆插件」，這種單點能力缺口正適合用一個小插件補上。下面介紹 Mappedinfo 維護的 dsh-tool-vision-read，它註冊一個 vision_read 工具，把讀圖這一步路由給專用視覺模型，純文本 agent 調用一次就能拿到圖片的文字描述。

這是什麼¶

dsh-tool-vision-read 是一個 DSH 社區插件，包名 @deepseek-ai/dsh-tool-vision-read，當前版本 0.1.0-rc.6，MIT 許可，由 Mappedinfo 獨立開發維護，不屬於官方 DeepSeek Harness 發行版。

一句話定位：註冊 vision_read 工具，通過專用視覺模型路由讀取圖片文件並返回文字描述，使純文本 agent 也能「看到」圖片。它把「按能力把任務路由到不同模型」的思路收斂到讀圖這一件事上，不依賴第三方工具，也不需要人工轉述。

核心功能¶

工具契約¶

vision_read(file_path: string, focus?: string)

返回 { path, provider, model, description }，其中 description 是視覺模型對圖片的文字描述。只接受 PNG/JPEG/WebP/GIF 路徑，路徑按調用會話的工作區 cwd 解析。

兩種執行模式¶

• direct（默認）：插件讀文件並經附件服務提交，單次 llm.stream 調用配置的視覺提供方/模型。一次往返，沒有 agent loop。
• subagent：進程內啓動一個固定到視覺路由的子代理，由它自行調用 read_image，可以迭代縮放、OCR、追問。更靈活，代價是完整的 agent loop。

配置項¶

• provider（string，必填）：持有視覺模型的已註冊提供方路由
• model（string，必填）：該路由上的視覺模型 id
• toolName（string，默認 vision_read）：模型側看到的工具名
• mode（'direct' | 'subagent'，默認 'direct'）：執行模式
• maxImageBytes（number，默認跟隨附件服務限制）：發給視覺路由的圖片字節上限
• maxOutputTokens（number，默認 1024）：視覺路由輸出 token 上限
• prompt（string）：隨圖發送的指令，支持 {{path}} 與 {{focus}} 佔位符

路由校驗¶

調用前會先解析路由；如果解析出的路由沒有聲明 image 輸入，調用會失敗並給出指引——例如 pi-ai 路由需要在 provider 設置裏聲明 defaultInput: [text, image]。配置解析在路由 id 缺失時也會直接失敗，所以 provider 和 model 必須寫清楚。

安裝與啓用¶

前提：已有 DeepSeek Harness 部署（源碼檢出或 out-of-tree profile 安裝），以及一條支持圖片輸入的模型路由。插件已針對 Kimi Coding API（k3-256k）驗證。

推薦以 Profile Bundle 形式安裝到 web profile：

dsh plugin --profile web add github:Mappedinfo/dsh-tool-vision-read

先執行安裝，再重啓 dsh web。安裝成功後包會加入 dsh.profile.bundles，重啓後由捆綁的 cordis.patch.yml 自動掛載 vision_read。默認路由是 kimi-coding / k3-256k。

如果你的視覺路由或模型不同，有兩種覆蓋方式。單次啓動用環境變量，不用編輯包：

DSH_VISION_PROVIDER=my-provider DSH_VISION_MODEL=my-vision-model dsh web

持久覆蓋則在 profile 自己的 cordis.patch.yml 裏按 id 覆蓋：

- id: tool-vision-read
  config:
    provider: my-provider
    model: my-vision-model
    mode: direct

兩點注意：profile 自身的 cordis.patch.yml 在 Bundle 之後應用；不要在 profile 裏插入第二個 tool-vision-read 行。

移除 Bundle 用這條命令：

dsh plugin --profile web remove @deepseek-ai/dsh-tool-vision-read

本地開發時可以鏈接本地檢出：

dsh plugin --profile web add link:/absolute/path/to/dsh-tool-vision-read

如果你在 deepseek-harness monorepo 裏開發，也可以把包複製到 packages/vision/tool-vision-read 後執行 pnpm install，再按官方 adding-a-package cookbook 註冊與掛載。另外，@deepseek-ai/* 的 peer 依賴由 DSH 安裝的模塊閉包滿足（$DSH_HOME/profiles/node_modules 平鋪回退），autoInstallPeers: false 防止 pnpm 拉取舊註冊表副本，一般不需要額外處理。

典型用法¶

README 裏的端到端示例：純文本 agent（deepseek-v4-flash）對一個 JPEG 調用 vision_read，描述由 Kimi K3-256K 經 kimi-coding 路由返回。

user: 請用 vision_read 看一下 /Users/shiqi/Downloads/微信圖片_20260816082109_883_131.jpg 並描述內容
agent: (vision_read) → "這是一張橫構圖、白天拍攝的現代城市/園區街景照片……天空與雲約佔畫面上方 2/3……
        左側一棟多層建築轉角呈弧形……中右一座較低的建築帶弧形屋頂邊緣和豎向格柵外立面……"

agent 本身全程沒有處理圖片，圖片 I/O 全部發生在視覺路由那一側，它拿到的只是文字描述。

適用場景與注意¶

適合的場景：主 agent 是純文本模型、但需要偶爾讀圖（截圖、照片、圖表）的 DSH 部署；已經配好多模型路由、想把讀圖固定交給某個視覺模型的使用者。

需要注意：

1、這是非官方社區插件，獨立開發維護。插件以當前 dsh 進程的權限運行，安裝前建議先讀一遍源碼，確認行爲與權限邊界可以接受；許可證爲 MIT。
2、路由必須聲明 image 輸入，否則調用會失敗並給出指引，比如爲 pi-ai 路由設置 defaultInput: [text, image]。
3、圖片只接受 PNG/JPEG/WebP/GIF，路徑按調用會話的工作區 cwd 解析，跨工作區引用時留意路徑解析基準。

結尾¶

經過上面的步驟，一個純文本 agent 就有了讀圖能力：vision_read 把圖片交給專用視覺模型，再把文字描述帶回 agent 的上下文。插件很薄，只做一件事，但正好補上了 DSH「一切皆插件」思路下的一個常見缺口。

GitHub：https://github.com/Mappedinfo/dsh-tool-vision-read
社區目錄頁：https://www.skillhub.cn/plugins/Mappedinfo/dsh-tool-vision-read （社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係，信息以 GitHub 倉庫爲準）