`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 中图像生成的集成难度。它将异步的图像生成过程转化为同步的工具调用，并自动处理文件的写入与附件的引用，降低了开发复杂度。