DSH · 插件教程 · 配置导出

生图工具：插件与配置教程

把当前这台 DSH Web 上的生图能力拆开讲清楚：它是哪个插件、接到谁、每个配置项管什么、怎么改、出问题怎么查。内容按机器上的实际配置导出，可以直接当交接材料。

导出时间 2026-10-21 15:22（Asia/Shanghai）。依据 dsh --profile web --dump-config 的组合结果、凭据库中的键名、以及 dsh.service 的运行状态。文中不含任何密钥值。

这套东西是什么

image_gen 是一个注册给模型调用的工具。用户在对话里说“生成一张……”，模型决定调用它，参数经过 Host 侧插件校验后发到 OpenAI 兼容网关；回来的图片写进 DSH 附件仓，界面渲染成有预览和下载的卡片，会话重载后还能回放同一张。

插件本体是 dsh-studio-image-gen（dsh-image-gen 的 Studio 分支：每张图有稳定的 IMG- 编号，预览卡片浮在对话上方）。它同时提供 Host 半（注册工具、鉴权、HTTP 取图）和浏览器半（工具卡、灯箱、下载）。

生成链路

旁路两条：卡片通过 Host 私有路由按 sessionId + callId 取图；归属索引写进 $DSH_HOME/image-gen-index/，会话删掉后由后台清扫。

现网快照

配置放在哪

合并顺序是 插件 schema 默认值 → bundle patch → profile patch。profile patch 里没写的键一律落回默认值，所以覆盖层可以只保留真正要改的 4 行：

# 生图插件：使用 hfsy NewAPI 网关（OpenAI 兼容 images/generations）
- id: image-gen
  config:
    authMode: api-key
    apiKeyEnv: HFSY_API_KEY
    baseUrl: https://www.hfsyapi.cn/v1
    model: gpt-image-2.5

配置项全表

“现网”列取自组合后的实际配置；标 已改 的 4 项是相对默认值的覆盖，其余均为 schema 默认。

凭据与认证模式

凭据解析的优先级是：~/.dsh/.credentials.yaml → 进程环境变量 → 启动目录 .env → ~/.dsh/.env。管理库优先，所以凭据页里存过 Key，就不会被 shell 里残留的旧变量顶掉。

安装与启用

# 本地 link 安装（当前方式）
dsh plugin --profile web add link:/home/ubuntu/dsh/plugins/dsh-studio-image-gen

# package.json 里对应两处：
#   "dependencies":        "dsh-studio-image-gen": "link:/home/ubuntu/dsh/plugins/dsh-studio-image-gen"
#   "dsh.profile.bundles": "dsh-studio-image-gen"

refs:
  HFSY_API_KEY: <你的 hfsy 密钥>
  # 同文件还存有 DEEPSEEK_API_KEY、OPENCODE_GO_API_KEY

# 组合结果里看这一段是否生效
dsh --profile web --dump-config | sed -n "/id: image-gen/,/^# ==/p"

# 重载（重启 + 30 次探测 + 失败自动回滚）
~/.dsh/reload-dsh.sh

# 起来了吗
systemctl --user is-active dsh.service
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:13080/

怎么调用

不需要写命令，直接描述需求即可；模型会自己拼参数。想控制结果，就把尺寸、画幅、质量、格式写进需求里。

# 基础
生成一张电影感 16:9 产品摄影：半透明机械键盘放在深色玻璃桌面上，
紫色轮廓光，浅景深，不要文字。

# 指定尺寸与质量
用 1536x1024、high 质量，画一张海边日落的扁平插画。

# 指定格式（要更小的文件）
生成一张 1024x1024 的贴纸风图标，输出 webp、压缩 80。

# 单次换模型（仅 api-key 模式有效）
用 gpt-image-2pro 生成一张 2048x2048 的科幻城市全景。

工具参数

卡片与图片编号

• 渐进显示：API Key 模式最多收到 3 张服务端真实局部图，在同一画布上交叉淡入、逐步对焦；Codex 订阅通道是非流式，用显影动画撑到成图返回。系统开启“减少动态效果”时动画自动降级。
• 成图持久化：只有最终图片会写成 DSH 不可变附件，因此刷新页面、重开会话都能回放同一张卡片。
• 编号：IMG-XXXXXX 由 callId 哈希得到，同一次调用稳定不变；卡片上可复制，对话里提它等于指这张图。
• 取图：浏览器拿到的是 Host 私有路由，不是公开静态目录。Host 先在会话记录里核对该 callId 确实属于这个会话，再读附件——“猜 URL 看别人的图”走不通。

路由形如 /api/dsh-image-gen/image?sessionId=…&callId=…&variant=display。附件是内容寻址的，响应标了 immutable 长缓存，同一 URL 永远对应同一份字节。

改配置与重载

插件配置在启动时组合成快照，改文件不会热生效。改 cordis.patch.yml 之后必须重载。

# 推荐：带健康探测和自动回滚
~/.dsh/reload-dsh.sh

# 脚本做的事：
#   1. 把改动后的文件复制成 cordis.patch.yml.applied
#   2. systemctl --user restart dsh.service
#   3. 每 2 秒探测 13080，最多 30 次
#   4. 起不来就用 cordis.patch.yml.rollback 回滚再重启

# 手动等价（不保留回滚）
systemctl --user restart dsh.service

回滚材料就在 profile 目录：cordis.patch.yml.rollback、.bak.20261021-015536、以及 backups/ 下按时间戳存的副本。

避坑清单

排错对照

文件与数据

会话被删掉后，后台会按索引逐条 stat 对应会话，清掉孤儿图片；启动 90 秒后跑第一次，之后每 6 小时一次，1 小时内新建的条目跳过。所以删会话不会马上腾空间，最多等一轮清扫。