前言¶

在 DeepSeek Harness（DSH）裏讓智能體「畫圖」，常見難點不在提示詞本身，而在鏈路是否可靠：接口返回的是外鏈還是字節、生成成功後第二跳下載是否失敗、IPv6 與 happy-eyeballs 導致的長時間連接超時，以及錯誤信息是否足夠讓模型繼續推理。許多圖片類插件只做一層 fetch 封裝，智能體拿到 URL 或空錯誤，難以在會話工作區裏直接展示、對比或再次引用。

下面介紹社區插件 dsh-agnes-image（維護者 Lijianan-123）。它在 DSH 中暴露單一工具，對接 Agnes Image 2.5 Flash（agnes-image-2.5-flash），支持文生圖、單圖參考編輯與多圖合成，並把結果寫成會話工作區內的 PNG 文件，便於後續用 read_image 查看或再傳入 image 參數。

這是什麼¶

dsh-agnes-image 是 npm 包 @dsh-external/dsh-agnes-image（當前版本 0.2.0，MIT 許可證）對應的 DSH 插件。源碼與說明見 GitHub：Lijianan-123/dsh-agnes-image；社區目錄頁：skillhub.cn/plugins/Lijianan-123/dsh-agnes-image。目錄站爲社區獨立站點，與 DeepSeek / 幻方無官方從屬關係。

插件面向已使用 DSH 的 web、desktop 或 headless 配置文件的開發者：在智能體側用自然語言或工具參數調用即可，無需額外運行時 npm 依賴（實現僅依賴 node:https 與 harness SDK）。

核心功能¶

三種模式，一套參數¶

是否傳入參考圖由參數 image 決定，模型不必在多個工具之間選擇：

文件落盤，而非僅返回 URL¶

生成結果以 inline base64 從 API 取回，寫入當前會話工作區內的 PNG 路徑（默認可落在 agnes-images/ 下）。智能體得到的是本地路徑，便於渲染、diff 或作爲下一輪 image 輸入。

連接與重試（實現側要點）¶

作者在 README 中記錄了實測結論（非泛泛而談）：對 Agnes 端點固定 IPv4、關閉 happy-eyeballs，可將易出現的 20s+ 全地址 ETIMEDOUT 收斂到約 9s 的穩定連接；僅在未收到 HTTP 響應的連接級失敗上有限次重試（默認 3 次，退避 600/1200 ms），HTTP 狀態碼與 AbortError 不重試；錯誤會歸一化爲帶嘗試次數的單行說明。默認走單跳 inline base64，避免「生成成功、下載第二跳失敗」的兩段式鏈路。

密鑰熱更新¶

API Key 每次調用按順序解析，不緩存：插件內聯配置 → harness 憑據存儲 → 環境變量（AGONES_API_KEY / AGNES_API_KEY）→ 密鑰文件。輪換密鑰後下一次調用即生效，無需重啓 harness。

環境與安裝¶

需要 Node.js 22+ 以及已配置的 DSH profile（web、desktop 或 headless 之一）。

從 GitHub 安裝（以 README 原文爲準，web 僅爲示例 profile，請按你的環境替換）：

dsh plugin --profile web add github:Lijianan-123/dsh-agnes-image

安裝後重啓 harness，再配置 API Key（任選其一）：

# 環境變量
export AGNES_API_KEY=sk-...

或通過 harness 憑據存儲 ~/.dsh/.credentials.yaml 中的 refs.AGONES_API_KEY，或密鑰文件 ~/.dsh/agnes-image.json（形如 {"apiKey": "sk-..."}）。

插件以當前 dsh 進程權限運行；安裝前建議自行審閱 倉庫源碼 與許可證，並妥善保管密鑰。

典型用法¶

安裝完成後，在對話中用自然語言描述即可，例如 README 中的示意：

Generate a 16:9 hero image for my landing page: a glass-and-steel medical device on a dark background, soft rim light, product photography style.

Take this UI screenshot and this logo, compose them into a clean App Store preview card.

工具參數（摘要，完整說明見倉庫 README）：

官方文檔對齊的示例分辨率（README 實測表）：例如 1:1 在 2K 爲 2048×2048，16:9 在 2K 爲 2624×1472。

可選配置¶

Loader 可在默認值上覆蓋以下字段（均可選）：

{
  "apiKey": "",
  "credentialRef": "AGONES_API_KEY",
  "endpoint": "https://apihub.agnes-ai.com/v1/images/generations",
  "model": "agnes-image-2.5-flash",
  "defaultSize": "2K",
  "defaultRatio": "1:1",
  "outputDir": "",
  "timeoutMs": 300000,
  "attempts": 3
}

outputDir 爲空時，輸出目錄爲 <session cwd>/agnes-images。

適用場景與注意¶

適合：已在 DSH 中開發智能體、需要 Agnes Image 2.5 Flash 文生圖 / 參考圖編輯 / 多圖合成，且希望結果直接落在會話工作區、減少外鏈與第二跳下載失敗的情況。

注意：

• 需自行申請並配置 Agnes API Key；網絡行爲（固定 IPv4、重試策略）針對作者文檔中的端點實測，若上游變更需關注插件更新。
• 參考圖需爲公網 HTTPS 或 data: URI；生成耗時受 timeoutMs（默認 300000 ms）約束。
• 社區插件星標與演進以 GitHub 爲準；使用前閱讀 README 中的 Engineering deep-dive 有助於理解失敗面與 payload 細節（例如 reference 模式下 response_format 須放在 extra_body 內）。

結尾¶

dsh-agnes-image 把 Agnes Image 2.5 Flash 的三種生成方式收斂到一個 DSH 工具裏，並把 PNG 寫入會話工作區，同時在連接與取圖路徑上做了可覈對的技術取捨。若你在 harness 生態中擴展「可落地的圖像能力」，可從社區目錄或 GitHub 獲取插件並按 README 安裝、配置密鑰後直接在對話中試用。

• 目錄頁：https://www.skillhub.cn/plugins/Lijianan-123/dsh-agnes-image
• GitHub：https://github.com/Lijianan-123/dsh-agnes-image