@local/dsh-imagegen

配置

打开「插件」页面，进入本插件（@local/dsh-imagegen）的详情页，页面下半部分就是「生图接口」表单。 填好后点「保存」，配置写入当前 profile 的 cordis.patch.yml，并在下一次调用生图工具时生效，无需重启。

插件注册了自己的 plugins.bundle.config 页面；DSH 不会按 Schema 自动生成表单，所以这个注册就是配置入口存在的原因。配置字段用 Schemastery .volatile() 声明，插件在每次调用时重新读取，因此保存后立即可用。

字段	默认值	含义
baseUrl	https://api.openai.com/v1	API 根地址，必须包含 /v1 这类根路径。缺失时会返回网页而不是 JSON，插件会直接指出这一点。
apiKey	空	生图服务密钥，标记为 secret，不回显、不暴露为工具参数。只在填写了内容时才写入。
apiKeyEnv	OPENAI_API_KEY	apiKey 留空时，从 DSH 启动进程的环境变量读取。桌面版推荐直接使用配置字段。
model	gpt-image-2	默认图片模型；需要你的服务支持该模型。不会自动降级。
size	auto	OpenAI 模型填 WIDTHxHEIGHT；按比例取值的服务填 9:16 这类比例。
resolution	空	服务商特有的分辨率档位（如 1k、2k、4k）。留空表示不发送该字段。
quality	auto	auto、low、medium、high，另接受 xhigh、max。
background	auto	auto、opaque、transparent。
outputFormat	auto	auto（不发送该字段）、png、jpeg、webp。
submitMode	sync	async 会以 ?async=true 提交并轮询任务接口 —— 图片接口返回 task_id 的服务必须选它。
taskPollMs	4000	任务状态轮询间隔，单位毫秒。
timeoutMs	300000	覆盖整次付费操作的超时（提交 + 轮询 + 下载），单位毫秒。
maxImages	4	单次最多生成数量，最大 10，同时受 DSH 附件限制。
maxImageBytes	52428800	单张输入/生成图片的字节限制。
maxResponseBytes	150000000	图片 API JSON 响应字节限制。
downloadHosts	[]	其它可信 HTTPS 域名精确列表。API 接口地址本身的域名始终允许；密钥不会发给其它域名。

远程 API 必须使用 HTTPS；本机 localhost/127.0.0.1 可以使用 HTTP。密钥不要写进提示词、工具调用或提交到仓库。

配置为空时插件仍然正常加载；只有真正调用 generate_image 且缺少接口地址或密钥时，才会返回一条可执行的提示，而不是让插件启动失败。

异步（任务制）服务商

部分服务商（例如 MigeAPI）的图片接口不直接返回图片，而是返回 task_id，需要再查询任务。对这类服务：

1. 把 submitMode 设为 async（提交时带 ?async=true，这是拿到可查询任务的关键）；
2. size 填比例（如 9:16），resolution 填档位（如 4k）；
3. 插件会自动轮询 GET {baseUrl}/images/tasks/{task_id}，直到 SUCCESS/FAILURE，然后下载 result_url。

插件同时兼容两种提交响应结构：顶层 task_id（MigeAPI 图像接口）和 data[].task_id（其视频接口风格的结构），并且只要响应里已经有图片就直接使用、绝不轮询。任务失败会把服务商给出的原因原样报告；整次操作受 timeoutMs 约束，不会无限等待。

使用

直接在 DSH 对话里描述要生成的图片，智能体调用 generate_image。参考 Codex 的提示词规则已通过独立 system prompt section 注册：保持用户要求、逐字保留图片文字、编辑时明确不变项、不同素材使用不同请求。

工具示例：

{
  "prompt": "产品摄影：白色陶瓷杯放在灰色桌面，柔和侧光，保留自然材质细节，无文字、无标志。",
  "size": "1536x1024",
  "n": 1
}

参考图/改图：

{
  "mode": "edit",
  "prompt": "仅将背景替换为海边日落；保持第一张图中的产品、外形、颜色、标志与边缘不变。第二张图仅作色调参考。",
  "image_paths": ["product.png", "style-reference.png"]
}

局部编辑可额外提供 mask_path：PNG 蒙版须与首张输入图尺寸一致，透明区域表示修改区域。输入文件经 DSH ctx.fs 读取，不绕过文件权限。蒙版的 alpha 和尺寸由生图服务进一步验证。

同一提示词生成多个版本用 n；不同素材分别调用工具。透明背景需要兼容的模型和 PNG/WebP。参考资料中 gpt-image-2 不支持原生透明参数，因此插件拒绝该组合，不会擅自换成 gpt-image-1.5。