前言¶
在 DSH 的插件化擴展方式下，社區目錄是獨立站點，本文介紹的 @dsh-extension/dsh-vision-bridge 是一個第三方插件。它面向 text-only DSH 會話，解決一個具體問題：會話中會出現上傳圖片或工具產生的圖片，但文本模型請求不適合攜帶 image blocks；如果爲了“看圖”直接把長會話歷史發給視覺模型，成本和控制都不好把握。
這個插件讓會話繼續走文本模型，只在需要理解圖片時調用 vision_describe。每次視覺調用只發送指定圖片和一個聚焦問題，把視覺模型作爲按需調用的外部能力。
這是什麼¶
@dsh-extension/dsh-vision-bridge 由 sfyyy 維護，許可證爲 MIT。它的一行定位是：
On-demand vision for text-only DSH sessions: images become markers, and a vision_describe tool sends only image + question to an OpenAI-compatible vision model.
簡單說，它給 text-only DSH 會話提供按需視覺能力：圖片在會話和 UI 中仍作爲圖片存在，進入文本模型輸入層時被改寫成 text marker；模型需要看圖時調用工具，由 OpenAI-compatible 視覺端點返回文本結果。
核心能力¶
按需調用視覺模型¶
插件不把所有圖片都主動發給視覺模型。它註冊 vision_describe 工具，由文本模型在需要時調用。每次調用只發送圖片和 question，不發送長 conversation history，從而把視覺調用控制在“只發當前要看的內容”這一層。
會話保留原圖，只改寫模型輸入¶
插件通過 agent/pre-step hook 記錄會話中出現的圖片附件，並建立 attachment index，供 vision_describe 按 id 解析圖片。
同時，它包裝 session.deriveMessages()，讓發給文本模型的消息不包含 image blocks。會話日誌和 UI 仍然保留原始圖片；被改寫的只是模型輸入。
使用 OpenAI-compatible 視覺端點¶
插件支持任何 OpenAI-compatible /v1/chat/completions endpoint 作爲視覺端點。它在 DSH llm-pi-ai providers 中只維護一條 vision-bridge provider route。
禁用後恢復原生行爲¶
配置 enabled: false 會關閉整條鏈路：不註冊工具、不做圖片改寫、不保留 admission bypass，恢復 native behavior。
安裝與啓用¶
安裝命令¶
從 npm registry 安裝，不使用 local checkout：
dsh plugin --profile web add @dsh-extension/dsh-vision-bridge
如果一直通過 npx 調用 DSH CLI，也可以用：
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @dsh-extension/dsh-vision-bridge
--profile 指向你要啓動的 profile；web 是瀏覽器 UI profile。如果新增 client bundle，需要重啓一次 dsh web，讓 UI 加載到插件。
基本配置¶
可以在 DSH Web 的 Settings -> Vision Bridge 中配置，也可以編輯 ~/.dsh/vision-bridge.json：
{
"enabled": true,
"baseUrl": "https://api.openai.com/v1",
"apiKey": "sk-xxxx",
"apiKeyEnv": "",
"model": "gpt-5.6-terra"
}
配置項包括：
enabled：是否啓用整條鏈路。baseUrl：OpenAI-compatible/v1/chat/completions視覺端點。apiKey：直接填入的 API key。apiKeyEnv：用於引用環境變量的字段；與apiKey互斥。model：視覺模型名稱。
直接填入的 key 會同步到 DSH credential store，並被引用爲 DSH_VISION_BRIDGE_API_KEY。
配置優先級¶
優先級從高到低：
Settings page (with schema defaults) -> environment variables -> config file
可用的環境覆蓋項包括：
DSH_VISION_BRIDGE_BASE_URL
DSH_VISION_BRIDGE_API_KEY
DSH_VISION_BRIDGE_API_KEY_ENV
DSH_VISION_BRIDGE_MODEL
DSH_VISION_BRIDGE_ENABLED
檢查運行狀態¶
可以請求插件提供的 settings 接口，查看當前 live 的 value.admissionBypass 和 dependency-service status：
GET /_dsh/vision-bridge/settings
典型用法¶
調用 vision_describe¶
vision_describe 用於讓視覺模型回答關於圖片的問題。它接受：
attachmentIds：當前會話中的圖片 attachment ids。paths：圖片文件路徑，通過 DSH 的 sandbox-aware file service 解析，支持png、jpeg、webp、gif。question：必填，必須是聚焦、具體的問題。
一次調用的圖片總數爲 1-4。
一個參數層面的調用可以寫成模板形式：
vision_describe(
attachmentIds: ["<current-conversation-attachment-id>"],
paths: ["<image-path>"],
question: "<question>"
)
多張圖片¶
如果需要一次查看多張圖片，可以把 1-4 張圖片一起傳給 vision_describe，並在 question 中說明要觀察或比較的內容。
驗證與本地開發¶
運行測試：
npm test
測試覆蓋 marker rewriting、attachment resolution、event-log indexing、disabled shutdown 和 text-only session behavior。
如果從 local checkout 開發，可以注入本地路徑：
dsh plugin inject /path/to/dsh-vision-bridge
適用場景與注意¶
適合以下情況：
- text-only DSH 會話中偶爾需要理解截圖、上傳圖片或圖表。
- 希望視覺模型只接收圖片和聚焦問題，不接收長會話歷史。
- 已有 OpenAI-compatible
/v1/chat/completions視覺端點。 - 希望 UI 和會話日誌繼續顯示原始圖片，只改寫發給文本模型的輸入。
使用前注意：
- 插件以當前
dsh進程權限運行，安裝前建議檢查源碼與 MIT 許可證。 apiKey與apiKeyEnv互斥；不要同時依賴兩種方式產生歧義。enabled: false會關閉工具註冊、圖片改寫和 admission bypass。- attachment ids 必須來自當前會話；
paths走 DSH 的 sandbox-aware file service。
結尾¶
@dsh-extension/dsh-vision-bridge 的價值在於給 text-only DSH 會話補上“按需看圖”的能力：圖片留在會話和 UI 中，文本模型通過 text marker 感知圖片，真正需要時再用最小 payload 調用視覺模型。
GitHub 倉庫：
https://github.com/sfyyy/dsh-vision-bridge
社區目錄頁 URL 未在已覈實資料中提供；安裝時可用上面的 npm registry 安裝命令。
