百炼文生图 aefbda/dsh-zimage-gen

dsh-zimage-gen

DeepSeek Harness（DSH）工具插件：把阿里云百炼（DashScope）的 Z-Image-Turbo 文生图能力做成两个 Host 工具，并在本地记账。

English — A DeepSeek Harness tool plugin that generates images with Alibaba Cloud Model Studio Z-Image-Turbo (zimage_generate) and tracks local call counts and cost (zimage_quota). Zero runtime dependencies, no build step.

| 工具 | 作用 |
| zimage_generate | 调用 Z-Image-Turbo 出图；提示词过短时先用当前会话的 DSH LLM 自动扩写；图片渲染成图片卡片 |
| zimage_quota | 读取本地调用记录，统计次数与费用（按 prompt_extend 分档 ¥0.1 / ¥0.2） |

- 零运行时依赖：只用 node: 内置模块和 DSH 的 ctx 服务，没有 dependencies、没有构建步骤，指向源码目录就能装。
- 短提示词自动扩写：提示词不足 30 字符时，用当前会话的 LLM 按「主体 → 场景 → 构图 → 光照 → 风格 → 约束」补全；扩写失败只降级，不影响出图。
- 图片卡片：生成的图片下载后登记为 DSH 附件，直接渲染在会话里（附件服务缺失时降级为 URL）。
- 本地记账：每次成功出图追加一条记录，按两档价目统计次数与费用，金额按“分”累加避免浮点误差。

环境要求

| 项 | 要求 |
| Node.js | >= 20（用到全局 fetch） |
| DSH | 0.1.5-rc.x（在 0.1.5-rc.3 上开发验证） |
| 凭据 | 一个百炼 API-KEY（不是 AccessKey ID/Secret，见 鉴权） |
| 网络 | 能访问 dashscope.aliyuncs.com 与返回图片的 OSS 域名 |

安装

插件是 bundle 形态：package.json 声明 dsh.bundle.patch，装进某个 profile 后其 cordis.patch.yml 会被合进该 profile 的层栈。因为零依赖、无构建，指向源码目录即可。

CLI 可管理的 profile（web、headless、自定义 profile …）

git clone https://github.com/aefbda/dsh-zimage-gen.git
dsh plugin --profile web add ./dsh-zimage-gen
dsh --profile web --dump-config | grep zimage # 确认出现 id: zimage-gen 层

装完后重启该 profile 的 host；新插件通常会被热加载，刷新页面即可。

桌面应用使用的 desktop profile

该 profile 由 Electron 应用独占，CLI 会拒绝管理（profile "desktop" is managed exclusively by the Electron application），需要手工复刻 dsh plugin 做的两件事：用应用自带的 pnpm 装上，再把包名加进 dsh.profile.bundles。

$prof = "$env:USERPROFILE\.dsh\profiles\desktop"
$pnpm = "<DeepSeek Harness 安装目录>\resources\runtime\pnpm\bin\pnpm.cjs" Copy-Item "$prof\package.json" "$prof\package.json.bak" # 先备份 Push-Location $prof & node $pnpm add "/path/to/dsh-zimage-gen" Pop-Location 然后编辑 $prof\package.json，把 "dsh-zimage-gen" 追加进 dsh.profile.bundles

运行中的 host 会热加载新 bundle，一般无需重启。

鉴权

按顺序解析：

1. 环境变量 DASHSCOPE_API_KEY（百炼 API-KEY）；
2. ~/.alibabacloud/credentials（INI）里的 [default] 段，字段名可以是 api_key / apikey / dashscope_api_key；段名可用 ZIMAGE_CREDENTIALS_PROFILE 覆盖。

[default]
api_key = sk-xxxxxxxxxxxxxxxx

凭据是每次调用时重新读取的，所以改完文件不需要重启 host（环境变量才需要重启，因为进程只在启动时继承一次）。

AK/SK 不可用。 如果凭据段里只有 access_key_id / access_key_secret，插件会明确报错而不是拿错凭据去发请求——Z-Image 走的是百炼多模态生成的 REST 端点，鉴权方式是 Authorization: Bearer <API-KEY>，REST 端点不做 AK/SK 签名。

请求形状（与官方文档一致）：

{
"model": "z-image-turbo",
"input": { "messages": [{ "role": "user", "content": [{ "text": "<prompt>" }] }] },
"parameters": { "size": "<宽><高>", "prompt_extend": false }
}

配置

cordis.patch.yml 里的 config 可直接覆盖，省略即用默认值：

- insert:
- id: zimage-gen
name: 'dsh-zimage-gen'
config:
defaultSize: '10241024'
autoExpandBelow: 30
downloadImages: true

| 键 | 默认 | 说明 |
| baseUrl | DashScope 多模态生成端点 | 端点覆盖 |
| model | z-image-turbo | 模型 id |
| defaultSize | 10241024 | 未传 size 时的分辨率 |
| credentialsFile | ~/.alibabacloud/credentials | 凭据文件（支持 ~ 展开） |
| quotaFile | ~/.dsh/zimage-quota.json | 调用记录文件 |
| autoExpandBelow | 30 | 提示词短于该字符数时自动扩写；0 关闭 |
| expandMinChars / expandMaxChars | 200 / 600 | 扩写目标长度区间 |
| expandProvider / expandModel | 空 | 扩写模型路由覆盖；空则用当前 Agent 的模型选择 |
| expandTimeoutMs / expandMaxTokens | 60000 / 1024 | 扩写调用参数 |
| requestTimeoutMs | 120000 | 生图请求超时 |
| downloadImages | true | 是否把图片下载并登记为附件（false 只返回 URL） |
| maxImageBytes / imageTimeoutMs | 8388608 / 60000 | 附件登记限制 |
| priceStandard / priceExtended | 0.1 / 0.2 | 计价单价（元/张） |
| freeQuota | 0 | >0 时 remainingFreeQuota 才给出数字，否则为 null（未知） |

环境变量可覆盖关键项（这些需要 host 重启才可见）：ZIMAGE_BASE_URL、ZIMAGE_MODEL、 ZIMAGE_QUOTA_FILE、ZIMAGE_CREDENTIALS_FILE、ZIMAGE_EXPAND_PROVIDER、 ZIMAGE_EXPAND_MODEL、ZIMAGE_CREDENTIALS_PROFILE。

用法

zimage_generate(prompt="一只坐在窗台上的橘猫，午后阳光") # 短提示词 → 自动扩写
zimage_generate(prompt="<长提示词>", size="1280x720") # size 接受 / x / ×
zimage_generate(prompt="<长提示词>", prompt_extend=true) # 开启服务端改写（¥0.2）

zimage_quota() # 全部记录
zimage_quota(since="2026-10-01") # 时间过滤

zimage_generate 返回：

{
"imageUrl": "https://.../out.png",
"rewrittenPrompt": "响应里的 text 字段", "finalPrompt": "实际发给模型的提示词", "promptExpanded": true, "size": "10241024", "promptExtend": false, "timestamp": "2026-10-08T11:13:50.818Z", "costCNY": 0.1, "durationMs": 3889, "requestId": "…",
"image": { "attachmentId": "…", "mediaType": "image/jpeg", "bytes": 137433, "width": 1024, "height": 1024 },
"notes": []
}

image 为 null 表示附件登记失败（例如没有 ctx.attachments），此时只有 imageUrl 可用，失败原因写在 notes 里。

size 的单边取值范围是 512~2048，推荐 10241024、1280720、7201280。

提示词优化

当 prompt 字符数 < autoExpandBelow 时，用当前会话的 DSH LLM（ctx.llm.stream）扩写：

- 顺序覆盖 主体 → 场景 → 构图 → 光照 → 风格 → 约束；
- 目标长度 200~600 字符；
- Z-Image-Turbo 不支持 negative prompt，因此 system 指令要求全部约束写成肯定式语言 （例如「画面干净通透」而不是「不要模糊」）；
- 路由解析优先级：expandProvider/expandModel 配置 > 当前 Agent 的 options.provider/model
ctx.agentDefaultModel.currentSelection()；
- 任何失败（无 llm 服务、无路由、超时、模型报错、输出为空）都只记入 notes 并回退原始提示词， 不会让生图失败。

计费与配额

每次 zimage_generate 成功后向 quotaFile 追加一条记录：

{ "version": 1, "records": [
{ "timestamp": "2026-10-08T11:13:50.818Z", "size": "10241024", "promptExtend": false, "cost": 0.1 }
] }

写入采用「临时文件 + rename」的原子替换，并在进程内串行化以抵御并发调用。官方计价为 prompt_extend=false ¥0.1/张、=true ¥0.2/张，速率上限 120 RPM；官方调价时改 priceStandard / priceExtended 即可。

开发与测试

npm test # 离线自检：58 项检查，不访问网络、不消耗任何 API 额度
npm run check # node --check + npm test

自检用 globalThis.fetch 桩替身跑通完整的 execute 路径，覆盖：size 校验、请求体契约、响应解析、凭据解析（含 AK/SK 拒绝路径）、配额持久化/统计/并发/since 过滤、扩写契约与降级、附件登记与降级、插件装载与工具定义契约、连续 3 次调用后的记账核对，以及包自洽性（零依赖、可发布字段、cordis.patch.yml 与包名一致、repository 与包名同步等）。

若本机装有 DSH，自检会额外用 @deepseek-ai/dsh-tools 的真实校验器（assertSupportedJsonSchema / validateJsonSchemaValue）校验 output.schema 与返回值；找不到时自动跳过，可用 DSH_TOOLS_PATH 显式指定 …/@deepseek-ai/dsh-tools/lib/index.js。CI 在 Node 20 / 22 / 24 上跑同样的检查。

目录结构

dsh-zimage-gen/
package.json 声明 dsh.bundle.patch -> cordis.patch.yml；零 dependencies cordis.patch.yml bundle patch：插入 id=zimage-gen 的插件行及其 config index.js 插件入口：name / inject 导出 + apply(ctx, config) lib/credentials.js DASHSCOPE_API_KEY / ~/.alibabacloud/credentials 解析 lib/zimage-api.js size 校验、请求体组装、响应解析、HTTP 错误归类 lib/prompt-expander.js 短提示词自动扩写（ctx.llm.stream） lib/quota.js 调用记录持久化与统计（原子写 + 进程内串行化） lib/image-attachment.js 下载图片并登记为 DSH 附件 lib/paths.js ~ 展开等路径小工具 lib/tools.js 两个工具的 definition（parameters / output.schema / render / execute）
locale/{en,zh}.json 插件卡片显示文本
icon.svg 插件图标 test/offline-selfcheck.mjs 离线自检 .github/workflows/ci.yml CI

实测记录

在 DSH 桌面应用（desktop profile）里连续调用 3 次，结果与离线自检的预期完全一致：

| 次序 | 提示词 | size 入参 | prompt_extend | 本地扩写 | 耗时 | 计费 |
| 1 | 一只坐在窗台上的橘猫，午后阳光（15 字） | 默认 | false | ✅ 触发 | 3.9s | ¥0.1 |
| 2 | 一只柯基犬在雨后的青石板街道上奔跑…（40 字） | 默认 | true | ⏭ 未触发 | 22.3s | ¥0.2 |
| 3 | 雪山日出，云海翻涌（9 字） | 1280x720 | false | ✅ 触发 | 3.6s | ¥0.1 |

- zimage_quota 返回 总次数 3 · 总费用 ¥0.4 · 标准 2 · 改写 1，与逐条记录相加一致；
- since 过滤边界正确；三张图都以图片卡片渲染；size 分隔符 x 被归一化为 。

设计说明与已知限制

- 零运行时依赖是刻意的：只用 node: 内置模块和 ctx 服务，不 import 任何 @deepseek-ai/* 包。profile 里安装的 bundle 运行时不保证能解析这些裸包名（社区插件同样只依赖 ctx），因此这里直接构造 ctx.tools.register() 需要的定义对象——形状与 defineTool
的产物一致（{ name, description, parameters, output: { schema, render }, execute }），
参数校验由 lib/tools.js 自己完成。自检里有一条断言守住这个约束。
- 未声明 Config：声明 Config 需要 @deepseek-ai/schemastery，与零依赖冲突；配置在
normalizeConfig() 里做默认值合并与类型纠正，validateConfig() 在加载时只告警不阻断。
- ctx.tools.register() 不做参数校验（那是 defineTool 的包装行为），所以插件自己校验形状与取值；模型传入非法参数会得到一条 Error: … 结果，而不会中断本轮对话。
- 图片卡片依赖 ctx.attachments；该服务缺失或图片下载失败时降级为纯文本 + imageUrl。
附件库中的对象是归一化后的副本（统一 JPEG、可能缩放、无扩展名），不是百炼返回的原始字节。
- 图片 URL 会过期（OSS 签名链接），需要长期留存请用附件副本或自行转存。
- remainingFreeQuota 只有在配置了 freeQuota > 0 时才是数字，否则返回 null （百炼免费额度是账号维度、随活动变化，插件不猜测）。

许可证

MIT。变更记录见 CHANGELOG.md。