生图模型怎么换 · 设计文档

结论先说

image_gen 的模型是一个全局配置项，不是工具参数。 改 ~/.dsh/profiles/web/cordis.patch.yml 里 image-gen 的 model: 一行即可， 改完立刻生效（热加载），不用重启。

现状已经是 gpt-image-2.5。

一、为什么看起来"不能换"#

工具 image_gen 的参数只有六项：

prompt / size / quality / output_format / output_compression / background

没有 model。 所以按次指定模型是做不到的 —— 这是我最初以为"不能换"的原因，但那是只看了工具签名，没看提供它的插件。

二、三层结构#

层	在哪	说明
工具参数	`image_gen` 的 schema	原本没有 `model`；已补（见第四节），待重启生效
插件配置	`cordis.patch.yml` → `image-gen.model`	✅ 一直可配，改这里就生效
代码分支	`src/index.ts` 的 `requestModel`	⚠️ Codex 订阅模式下模型被写死

第三层是真正的坑。插件源码里是这么写的：

const requestModel = auth.kind === 'codex-subscription' ? 'gpt-image-2' : config.model

走 Codex 订阅时，改配置**完全没用**

auth.kind === 'codex-subscription' 时无条件用 gpt-image-2，config.model 被彻底忽略。原因是 Codex 订阅的图片端点只服务 gpt-image-2 这一个模型，传别的没有意义。

本机不受这一条影响，因为配置里是 authMode: api-key（走 HFSY 网关）。

三、配置在哪、怎么改#

文件：~/.dsh/profiles/web/cordis.patch.yml

- id: image-gen
  config:
    authMode: api-key
    apiKeyEnv: HFSY_API_KEY
    baseUrl: https://www.hfsyapi.cn/v1
    model: gpt-image-2.5        # ← 就改这一行

为什么配置在这个文件里：DSH 的 profile 根（cordis.yml）是一个空数组，整棵树由「bundle 列表 + cordis.patch.yml + 命令行 --patch」三层叠加而成。所以要改插件的运行配置，改 cordis.patch.yml，不要改 cordis.yml。

插件自己的 cordis.patch.yml（在插件仓库里）只声明"挂载这个插件"，不带配置：

- insert:
    - id: image-gen
      name: 'dsh-studio-image-gen'

可换的模型#

网关 https://www.hfsyapi.cn/v1/models 上可用的生图模型：

模型	备注
`gpt-image-2.5`	现行
`gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`	2.5 的两个变体
`gpt-image-2pro` / `gpt-image-2pro-4k`	2pro 系列
`gpt-image-2`	旧档
`gemini-3-pro-image-preview` / `gemini-3.1-flash-image-preview`	Gemini 系
`sd-2.5-720` / `sd-2.5-1080` / `sd-2.0-*`	SD 系列

想确认某个模型名对不对，直接问网关

curl -s -H "Authorization: Bearer $HFSY_API_KEY" \
  https://www.hfsyapi.cn/v1/models | grep -o '"id":"[^"]*image[^"]*"'

四、已做的改动：按次指定模型#

给插件加了 model 参数，这样就能一张图一个模型（对比不同模型的效果时特别有用）。

改了两个文件：

src/index.ts（源码）— 加参数声明 + 用 argsModel ?? config.model
lib/index.js（运行时真正加载的文件）— 同样改动

const argsModel = args.model?.trim() === "" ? undefined : args.model?.trim()
if (argsModel !== undefined && argsModel.length > 128) throw new Error("model must not exceed 128 characters")

const requestModel = auth.kind === "codex-subscription" ? "gpt-image-2" : argsModel ?? config.model

这个改动**目前还没生效**，需要重启一次

实测验证：传一个不存在的模型名 zzz-not-a-real-model，照样正常出图 —— 说明参数被丢弃在工具注册表之外了。

原因是 工具 schema 只在进程启动时注册一次。我试过"改配置文件触发插件重载"，也不生效 —— 配置热加载只重新应用配置值， 不会重新 import 模块、更不会重建工具注册表。

另外确认一下：DSH 是裸进程（node .../dsh web --host 127.0.0.1 --port 13080， 不在 systemd 里），所以重启它会中断正在进行的会话。这就是我没有直接重启的原因。

重启之后就可以这样用：

image_gen(model="gpt-image-2.5-flare", prompt="...", ...)

五、两个已知的小瑕疵#

客户端卡片副标题硬写着 GPT Image 2（src/client/index.tsx），失败态下会显示这个字符串。显示层，不影响功能。
下载文件名的兜底也硬写着 gpt-image-2： result?.image.name ?? \gpt-image-2.${ext}`。只有 image.name` 为空时才会走到，同样是显示层。

六、一句话备忘#

改模型 → 改 ~/.dsh/profiles/web/cordis.patch.yml 的 image-gen.model，立即生效。但只有在 authMode: api-key 时才有效；Codex 订阅模式下这个值被代码忽略。