前言¶
用 DeepSeek Harness（DSH）的 Web GUI 做智能體，有三個和圖片有關的場景一直不好處理：
1、模型想讓你在幾個候選裏挑一張圖（比如給小說選封面），但選項卡里放不了圖，模型只能把路徑打印出來讓你自己開文件；
2、模型生成了圖，想在回覆正文裏圖文混排，同樣沒有通道；
3、你往聊天裏發一張圖，文本-only 的模型適配器直接報 UNSUPPORTED_CONTENT，回合中斷。
dsh-plugin-image-tools 就是針對這三個場景的 DSH 插件：圖片選擇卡、回覆內嵌圖片、盲模型收圖，三個工具各管一攤，全部零 token 本地渲染，純插件實現，不改核心包。
這是什麼¶
dsh-plugin-image-tools 由 Pasumao 維護，MIT 許可證，運行平臺爲 Web GUI（package.json 裏 dsh.client.platform 爲 web），當前版本 0.6.6。
爲什麼做成插件而不是改核心：瀏覽器端消費 question/requested 幀時用 zod schema 嚴格解析，選項對象上的未知字段會被剝離；助手消息 content 由模型文本生成，也沒有攜帶結構化圖片塊的通道。圖片沒法直接塞進 option / content 字段。插件的解法是：服務端把圖片字節歸一化進內存註冊表，用自定義 web 路由直接供字節；客戶端部分在 conversation.composer slot 鏈註冊條目，負責渲染和增強。
代碼與文檔由 AI 輔助生成，均經人工審查與實機驗證（npm run smoke）。
安裝與啓用¶
npm 安裝（推薦）：
dsh plugin --profile web add dsh-plugin-image-tools
或從 GitHub 源安裝：
dsh plugin --profile web add github:Pasumao/dsh-plugin-image-tools
裝完重啓 dsh（launcher），再刷新瀏覽器頁面。包自帶 cordis.patch.yml 掛載行，經 dsh.profile.bundles 自動應用，不需要手動改配置。插件不讀取環境變量、不需要 API Key / token、不寫配置文件，裝好即用。純文字問題不帶圖片時自動放行給原生 UI，互不影響。
三個工具¶
三個工具的圖片來源統一支持三種形態：本地路徑（相對會話工作區或絕對路徑）、http(s) URL（服務端拉取後轉存）、base64 data URI。單張上限 20 MiB，僅支持 PNG / JPEG / WebP / GIF（按魔數校驗，聲明不符會報錯）。
ask_user_choice：在選項裏挑圖¶
模型傳入 questions 數組，每個選項可帶一張圖（path / url / data 三選一），純圖片、純文字、圖文選項可在同一題混排。支持多題分頁、單選/多選、自定義答案、跳過；label 末尾寫 (Recommended) 或 (推薦) 會顯示推薦標註。縮略圖點擊彈出 Lightbox 大圖，Esc / 點遮罩 / 關閉按鈕退出。選擇卡由 Web GUI 渲染，答案協議與原生一致：
{
"questions": [
{
"id": "cover",
"question": "選一張封面圖",
"header": "封面選擇",
"options": [
{ "label": "深海鯨魚 (Recommended)", "image": { "path": "novel/assets/covers/whale.png" } },
{ "label": "星空", "image": { "url": "https://example.com/stars.png" } },
{ "label": "手繪風",
"image": { "data": "data:image/png;base64,iVBORw0KGgo..." } },
{ "label": "都不選，我自己說", "description": "選這個可以在下方輸入自定義答案" }
],
"multi_select": false
}
]
}
// 返回：{ "answers": [ { "id": "cover", "selected": ["深海鯨魚 (Recommended)"] } ] }
show_images：在回覆正文裏展示圖¶
調用時傳 images 數組（一次 1~9 張，每張可帶 caption），工具返回絕對 URL 的 markdown 圖片片段，模型把片段原樣逐行粘貼進回覆正文，圖片就隨文字顯示：
// 調用 show_images
{
"images": [
{ "image": { "path": "novel/assets/covers/whale.png" }, "caption": "深海鯨魚封面" },
{ "image": { "url": "https://example.com/stars.png" }, "caption": "星空" }
]
}
// 返回：{ "markdown": ["", ""] }
客戶端插件會對這類圖片做漸進增強：圓角樣式、懸停顯示說明、點擊放大、加載失敗降級。
save_received_images：盲模型收圖存成文件¶
用戶往聊天裏發圖時，插件註冊的 agent/pre-step 監聽器把進入 LLM 步驟的消息裏的 image 塊重寫爲 dshimg:<attachmentId> 文本佔位符，文本-only 適配器不再因圖片塊報 UNSUPPORTED_CONTENT，回合照常運行；用戶氣泡裏由客戶端增強器把佔位符替換爲可放大的圖片回顯。
模型看到佔位符後調用 save_received_images，把圖片按 attachmentId 保存爲工作區文件，默認目錄 received/；文件名優先用附件自帶的安全文件名，否則按 image-<n>-<時間戳>.<ext> 生成。之後就能用文件/命令工具對圖片做分析（尺寸、像素、哈希等）。
限制與注意¶
- 圖片字節僅存進程內存：選擇卡圖片隨問題回答/取消立即釋放；內嵌圖片與附件回顯依賴 30 分鐘 TTL 清理。
- 圖片路由 URL 是內容尋址的，響應頭下發
Cache-Control: private, max-age=2592000, immutable（30 天瀏覽器緩存）；服務端清理後刷新頁面仍可命中本地緩存。 - 圖片路由爲同源普通 HTTP 路由（與 GUI 同信任級別），未加額外鑑權。
- 內嵌圖片的 markdown URL 是絕對地址，若 GUI 經反向代理或換端口訪問，歷史消息裏的圖片地址可能失效。
- 兼容性：實測於 DSH
0.1.2-rc.1（0.6.5 起適配該版選擇卡新協議，0.6.6 起測試自帶 react/react-dom），依賴客戶端服務slots/locale。 - 插件以當前 dsh 進程權限運行，安裝前建議自行查看源碼與許可證（MIT）。
結尾¶
dsh-plugin-image-tools 用三個工具覆蓋了 Web GUI 裏「選圖、看圖、發圖」三件事，零 token 本地渲染，不改核心包，也不需要配置。如果你在 DSH 上做涉及圖片的工作流（封面挑選、出圖展示、給文本模型傳圖分析），可以直接裝來試。
- 社區插件目錄（獨立站點，與 DeepSeek / 幻方無官方從屬關係）：https://www.skillhub.cn/plugins/Pasumao/dsh-plugin-image-tools
- GitHub 倉庫：https://github.com/Pasumao/dsh-plugin-image-tools
