前言¶
DeepSeek Harness (DSH) 的插件機制允許開發者通過擴展功能來增強工作流。對於需要視覺輸出的智能體或工作流，dsh-tool-imagegen 插件提供了一個解決方案。它通過 OpenRouter 的統一圖片生成 API，將文本轉圖片和圖片轉圖片的能力集成到 DSH 中。
核心定位¶
- 作者: Pappet
- 許可證: MIT
- 功能: Text-to-image 和 image-to-image 生成
- 依賴: Node.js >= 22.19
- 接口: OpenRouter 的
POST /api/v1/images(非 OpenAI 兼容接口)
安裝¶
在終端中運行以下命令將插件安裝到 web profile：
dsh plugin --profile web add dsh-tool-imagegen
安裝完成後，插件會出現在 dsh.profile.bundles 中，並自動插入插件行。
配置與啓用¶
插件安裝後需要配置 API 密鑰。推薦將密鑰存儲在憑證文件中，環境變量次之。
- 設置憑證: 在
$DSH_HOME/.credentials.yaml中添加：
refs:
OPENROUTER_API_KEY: sk-or-...
或者在 shell 中導出環境變量：
export OPENROUTER_API_KEY=sk-or-...
- 配置別名與參數: 在
cordis.patch.yml中添加配置覆蓋。由於配置是整行替換而非深度合併，所有需要覆蓋的鍵都必須顯式列出。示例配置如下：
- id: imagegen
config:
apiKeyEnv: OPENROUTER_API_KEY
baseURL: https://openrouter.ai/api/v1
outputDir: .dsh/images
defaultModel: seedream
capabilityTtlMs: 86400000
maxImagesPerCall: 4
maxReferenceBytes: 8388608
maxReferenceTotalBytes: 33554432
showInChat: true
models:
seedream:
id: bytedance-seed/seedream-4.5
defaults: { resolution: "2K", aspect_ratio: "16:9" }
使用方法¶
在 DSH 的對話或工具調用中，可以通過 JSON 格式調用 generate_image 工具。
基礎文本生成¶
{
"prompt": "一隻在太空中的貓",
"model": "seedream"
}
圖生圖¶
通過 input_references 參數傳入路徑或 URL：
{
"prompt": "Turn this into a soft watercolor painting, same composition.",
"input_references": ["bilder/vorlage.png", "https://example.com/style.jpg"]
}
關鍵特性與注意事項¶
1. 模型別名與能力門控¶
模型別名不僅是詞彙表，還是允許列表。插件會根據模型的能力記錄 (GET /api/v1/images/models) 動態檢查參數，而不是硬編碼。如果模型不支持請求的參數（例如不支持某分辨率），會返回具體的錯誤信息。
2. 輸出路徑與編碼¶
output_path 中的文件擴展名僅作爲建議。實際的編碼格式由模型決定。例如，如果你請求生成 .png 但模型返回的是 JPEG，文件名會被重命名爲 .jpg。插件不會因爲文件名錯誤而報錯。
3. 配置覆蓋機制¶
在 cordis.patch.yml 中的配置覆蓋會整行替換配置，而不是深度合併。這意味着如果你不列出某個鍵，它將使用該行的默認值，而不是繼承其他配置的值。
4. 運行時可編輯¶
插件在瀏覽器端註冊了設置卡片，允許在運行時編輯別名和可調參數，無需重啓 DSH 進程。
5. 圖片引用處理¶
圖片引用 (input_references) 支持工作區路徑或 URL。插件通過讀取文件的魔數來判斷格式，忽略文件名中的後綴。引用圖片的數量和大小受模型能力限制（例如 Seedream 4.5 支持 14 張，GPT-Image 系列支持 16 張）。
總結¶
dsh-tool-imagegen 是 DeepSeek Harness 中用於集成 OpenRouter 圖片生成能力的工具。它通過動態能力檢查和靈活的配置方式，爲開發者提供了在智能體工作流中直接生成和編輯圖片的能力。
