前言¶
DSH 本身不提供生圖能力。智能體要在對話或任務裏產出一張圖片，就得自己對接外部圖像模型，寫請求、處理重試、落盤、維護提示詞規範，成本不低。這個插件做的事就是把火山方舟 / 豆包 Seedream 的文生圖、圖生圖封裝成 DSH 可直接調用的模型工具，並附帶一個內置技能，讓模型知道怎麼用它。
下面介紹這個插件：它由 zmengle 維護，分類是模型推理，GitHub 倉庫是 zmengle/dsh-plugin-ark-image-gen，許可爲 MIT，版本 0.1.1。
插件定位¶
這是一個 DSH 插件，README 裏的位置說明是：給 DeepSeek Harness 兩個模型工具加一個內置技能。
ark_generate_image：文生圖 / 圖生圖，支持單張或多張參考圖、一次出多張、固定 seed 復現。ark_image_gen_status：自檢工具，報告密鑰是否就緒、生效模型、網關、輸出目錄，不發請求、不計費。
出圖會落盤到輸出目錄，並追加寫 manifest.json，記錄文件名、模型、尺寸、seed、prompt、時間。
安裝與啓用¶
安裝命令來自 README，兩種來源都可以。下面這步把插件裝進 web profile：
# npm
dsh plugin --profile web add dsh-plugin-ark-image-gen
如果要直接裝源碼，用 GitHub 地址：
dsh plugin --profile web add https://github.com/zmengle/dsh-plugin-ark-image-gen
裝好後重啓 dsh web（或桌面端）。插件行是 ark-image-gen。注意本插件對 Node 的要求是 >=18，並且 peer 依賴 @deepseek-ai/cordis、@deepseek-ai/dsh-skill、@deepseek-ai/dsh-tools，實際安裝前需要確認這些依賴版本與當前 DSH 環境匹配。
配置¶
密鑰只從環境變量或插件配置讀取，不寫入任何文件。
# Windows：設置環境變量後重開終端
setx ARK_API_KEY "ark-xxxx"
也可以寫進 profile 補丁。下面這個補丁用 !!js process.env.ARK_API_KEY 讀環境變量，避免把密鑰明文留在倉庫裏：
- id: ark-image-gen
config:
apiKey: !!js process.env.ARK_API_KEY
outDir: D:/ark-output
配置項對照如下：
| 環境變量 | 插件配置鍵 | 默認值 | 說明 |
|---|---|---|---|
ARK_API_KEY |
apiKey |
—（必填） | 火山方舟 API Key，形如 ark-... |
ARK_MODEL |
model |
doubao-seedream-5-0-flash-260915 |
生圖模型 |
ARK_BASE_URL |
baseUrl |
https://ark.cn-beijing.volces.com/api/v3 |
網關地址 |
ARK_OUT_DIR |
outDir |
<工作目錄>/ark-output |
出圖目錄 |
outDir 等配置可以在工具參數裏臨時覆蓋，見下一節。
典型用法¶
模型側直接調用 ark_generate_image。參數如下：
| 參數 | 類型 | 說明 |
|---|---|---|
prompt |
string（必填） | 提示詞。不要用 ASCII 雙引號，用「」或轉義 |
size |
string | "2K"（默認，沿用參考圖比例）/ "4K" / "1024x1024" 這類精確尺寸 |
seed |
integer | 隨機種子，固定它可復現 |
image |
string[] | 參考圖：本地絕對路徑 / http URL / data URL。單張也用數組 |
count |
integer | 出幾張（1-4，默認 1）；多張時 seed 依次 +1 |
file |
string | 輸出文件名（不帶擴展名），默認 ark_<時間戳> |
model |
string | 覆蓋默認模型（必須是 doubao-seedream-*） |
outDir |
string | 覆蓋輸出目錄 |
調用成功後的返回形如：
{
"ok": true,
"model": "doubao-seedream-5-0-flash-260915",
"size": "2K",
"files": [{ "path": "D:/ark-output/ark_1750000000000.png", "bytes": 1843200, "seed": 42 }]
}
插件同時註冊技能 ark-image-gen（skills/ark-image-gen/SKILL.md），裏面說明用法和踩坑表。模型可以自己發現它，也可以直接說一句「用 ark 生成一張……」觸發。
行爲說明¶
請求形態是 POST <baseUrl>/images/generations，response_format: url，watermark: false。幾點實現細節：
- 429 與 5xx 自動重試 2 次，指數退避；單次請求超時 300 秒，工具級超時 600 秒。
- 圖片按文件頭（magic number）識別
png/jpg/webp再落盤，不信任響應裏的擴展名。 - 本地參考圖會轉成 base64 data URL 發送，大圖會顯著增加請求體體積。
- 默認模型名可能隨火山方舟下線調整，遇到 404 用
model參數或ARK_MODEL指定當前可用模型。
安全與適用範圍¶
安全方面，密鑰只從 ARK_API_KEY 或 config.apiKey 讀取，不寫入任何文件、不進日誌、不進 manifest.json；ark_image_gen_status 只報告「已配置（長度 N）」，不顯示密鑰片段的任何字符。密鑰隨 Authorization 頭髮送，因此 baseUrl 必須是 https，明文 http 只允許 localhost / 127.0.0.1 / [::1] 的本機調試，其他地址直接拒絕。報錯只帶 HTTP 狀態碼和響應體前 400 字符，不回顯請求頭。參考圖會以 base64 data URL 隨請求發送，圖片越大請求體越大，注意不要順手把含隱私的截圖發出去。
適用場景是：已經在 DSH 裏跑智能體或工作流，需要穩定調用火山方舟 Seedream 出圖，尤其是要讓模型自己決定何時出圖、出什麼圖的場景。
要注意兩點。第一，插件運行在當前 dsh 進程權限下，裝之前應檢查源碼與許可證，確認它滿足你環境的信任要求。第二，本插件就是按 DSH「一切皆插件」的方式接入的，其能力邊界就是上面的工具和技能，不涉及 DSH 核心行爲。
結尾¶
這個插件的價值在於把「接一個外部生圖模型」這件事壓縮成一次安裝加一份配置，出圖、重試、落盤、manifest 都由插件處理，模型側只需要按參數調用。維護者是 zmengle，分類爲模型推理，許可 MIT。
目錄頁：https://www.skillhub.cn/plugins/zmengle/dsh-plugin-ark-image-gen
GitHub：https://github.com/zmengle/dsh-plugin-ark-image-gen
