dsh-auto-visual：DSH 插件的圖片素材編排工具

下面介紹 DeepSeek Harness（DSH）插件 herbert-wang820/dsh-image（即 dsh-auto-visual）。它解決的是 DSH Agent 在處理文檔、網頁或演示文稿時的配圖需求：把“需要什麼圖”變成結構化計劃，交給可替換的供應方生成，再登記每張圖被用在哪裏。

核心功能¶

該插件將圖片生成任務拆解爲三個獨立步驟，各自負責不同職責：

visual_plan：分析任務，給出結構化的素材需求清單（用途、主體、風格、比例等），返回確定的提示詞與素材 ID。
visual_generate：根據計劃 ID 和素材 ID，調用配置的供應方生成圖片。已生成的結果會直接複用，不重複調用。
visual_finalize：主 Agent 在完成文檔或網頁製作後，登記每張圖的實際放置位置和工作區相對路徑。

安裝¶

通過 DSH 命令行安裝該插件。安裝後需重啓 Host 並刷新頁面。

dsh plugin --profile <profile> add github:Herbert-wang820/dsh-image

配置¶

插件提供一組配置項，用於控制生成模式、供應方及資源限制。默認出廠配置爲安全模式，不會產生任何調用與費用。

字段	取值	含義
`mode`	`off` / `suggest` / `auto`	關閉 / 僅規劃 / 允許生成
`provider`	`disabled` / `mock` / `openai`	禁用 / 本地測試圖 / OpenAI 兼容 API
`model`	模型 ID	如 `gpt-image-2`；`mock` 僅接受 `mock-v1`
`baseURL`	API 根地址	默認 `https://api.openai.com/v1`
`apiKey`	API Key	保存後不回顯，留空不覆蓋已有密鑰
`maxAssets`	1–100	每個會話的素材上限，默認 3

默認配置示例：

mode: suggest
provider: disabled
model: mock-v1
baseURL: https://api.openai.com/v1
apiKey: ''
maxAssets: 3

使用流程：
1. 先將 mode 設爲 auto、provider 設爲 mock，在無網絡環境下驗證全流程。
2. 驗證通過後，將 provider 切換爲 openai，填入模型 ID、Base URL 和 API Key。

使用示例¶

在 Agent 工作流中，通常按以下順序調用工具：

調用 visual_plan 傳入任務描述和素材列表。
調用 visual_generate 傳入 planId 和 assetId 生成圖片。
主 Agent 完成文檔編輯後，調用 visual_finalize 填入圖片的路徑和位置。

工具輸入示例：

{
  "task": "網站首頁配圖",
  "assets": [{
    "purpose": "website hero illustration",
    "subject": "abstract collaborative research workspace",
    "style": "navy and teal, minimal flat illustration",
    "placement": "right side hero; leave left side clear for text",
    "ratio": "1:1",
    "required": true
  }]
}

安全與權限¶

該插件對安全性和權限有明確要求：

密鑰安全：API Key 以 Host 側 role('secret') 配置字段保存。寫入後不回顯，不隨配置描述回傳瀏覽器，不進入對話、提示詞或日誌。
文件權限：工具需要寫權限，連查詢也會取工作區鎖。
沙箱要求：沙箱策略必須返回 full enforcement，否則插件會拒絕運行。
存儲限制：僅支持映射到 Host 的本地/同世界文件系統，不支持遠程執行世界。

已知限制¶

中斷恢復：中斷的請求不會自動重試，狀態恢復爲 uncertain。
圖片格式：OpenAI 兼容適配器僅支持同步返回 base64 PNG，固定比例 1:1。
Mock 限制：不會用 Mock 圖片充當用戶要求的真實圖片交付。
校驗範圍：PNG 校驗僅覆蓋特定子集（非隔行、8-bit、最長邊 4096 等），不覆蓋所有合法 PNG。
功能邊界：不提供視覺質量判定，不重寫編輯器，不保證主 Agent 會主動觸發配圖。

許可證¶

MIT