`tuofangzhe/dsh-plugin-image-gen`：DeepSeek Harness 圖像生成工具

在 DeepSeek Harness (DSH) 的生態中，通過插件擴展能力是核心設計理念。當開發需要圖像輸出的智能體時，通常需要處理異步 API 調用、後端存儲或複雜的文件管理。本插件旨在將圖像生成能力以工具的形式直接集成到對話流中，通過 OpenAI 兼容的接口，將圖像生成請求封裝爲同步操作，並將結果直接寫入工作區。

插件定位¶

這是一個 DeepSeek Harness 插件，由 tuofangzhe 維護。它通過暴露一個 OpenAI 兼容的 generate_image 工具，將圖像生成請求封裝爲同步操作，直接將生成的圖像寫入當前會話的工作區，並存儲附件引用，供後續對話使用。

核心功能¶

OpenAI 兼容工具：提供標準的 generate_image 工具接口。
同步請求處理：發送同步 POST 請求到配置的圖像生成接口。
工作區寫入：將返回的圖像直接寫入當前會話的工作區，便於模型查看。
附件引用：存儲附件引用，使支持圖像輸入的模型能夠查看生成結果。
多提供商支持：支持配置多個提供商（如 OpenAI、Gateway），並在工具調用時指定使用哪個提供商。
嚴格驗證：對文件名和路徑進行嚴格驗證，確保安全性。
排他性寫入：文件創建採用排他性 wx 語義，即不覆蓋已存在的文件。

安裝與啓用¶

插件需要通過官方命令安裝到指定的 DSH 配置文件中。

安裝¶

dsh plugin --profile web add @dopilot/dsh-plugin-image-gen

啓用與配置¶

安裝後，插件會插入一個名爲 dopilot-image-gen 的行到配置文件中。需要在同配置文件下的 cordis.patch.yml 中覆蓋該行以啓用功能。

配置說明：
* config 字段是完全替換，不是深度合併。修改時需要重寫所有需要的鍵。
* providers 字段必須配置，否則插件處於休眠狀態，不會註冊工具。
* apiKeyEnv 是憑證引用名稱（如 OPENAI_IMAGE_API_KEY），不是實際密鑰，DSH 會通過憑證服務解析。

示例配置 (cordis.patch.yml)：

- id: dopilot-image-gen
  config:
    providers:
      openai:
        baseURL: https://api.openai.com/v1
        apiKeyEnv: OPENAI_IMAGE_API_KEY
        defaultModel: gpt-image-1
        models: [gpt-image-1]
        responseFormat: png
        timeoutMs: 120000
    defaultProvider: openai
    maxImagesPerCall: 4
    outputDir: generated-images

典型用法¶

工具調用¶

在 DSH 會話中，模型可以調用 generate_image 工具。參數必須包含 prompt 和 output_paths。

調用示例：

{
  "prompt": "A red circle centered on a clean white background",
  "provider": "openai",
  "size": "1024x1024",
  "output_paths": ["generated-images/red-circle-1.png"]
}

文件命名規則¶

output_paths 中的路徑必須相對於 outputDir。文件名必須由 ASCII 字母、數字、下劃線或連字符組成，並以正確的擴展名結尾。支持的格式由提供商的 responseFormat 決定（png, jpeg, webp）。

提供商配置¶

支持配置多個提供商，並在調用時通過 provider 參數指定。apiKeyEnv 可選，對於不需要認證的網關可省略。

多提供商示例：

- id: dopilot-image-gen
  config:
    providers:
      openai:
        baseURL: https://api.openai.com/v1
        apiKeyEnv: OPENAI_IMAGE_API_KEY
        defaultModel: gpt-image-1
      gateway:
        baseURL: https://images.example.com/openai/v1
        # gateway 不需要 apiKeyEnv
        defaultModel: organization/image-model
    defaultProvider: openai

適用場景與注意¶

適用場景¶

適合需要在 DSH 工作流中直接生成圖像並讓模型看到結果的場景，例如生成 UI 組件示意圖、數據可視化圖表等。

注意事項¶

依賴環境：插件僅支持 ESM 模塊，需要 Node.js 22.19 或更新版本。
休眠狀態：如果未在 config 中配置 providers，插件將保持休眠狀態，不註冊任何工具。
文件覆蓋：由於採用 wx 語義，嘗試生成已存在的文件名會失敗，且不會覆蓋原文件。
格式限制：responseFormat 僅支持 png, jpeg, webp，插件不會對提供商返回的格式進行轉碼。

總結¶

該插件通過提供 OpenAI 兼容的接口，簡化了 DeepSeek Harness 中圖像生成的集成難度。它將異步的圖像生成過程轉化爲同步的工具調用，並自動處理文件的寫入與附件的引用，降低了開發複雜度。