前言¶
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 图片生成能力的工具。它通过动态能力检查和灵活的配置方式，为开发者提供了在智能体工作流中直接生成和编辑图片的能力。
