图像生成路由 PerryLink/dsh-draw

🎨 dsh-draw

🧊 自 2026-10-05 起冻结（FROZEN） — 只修复真正的故障。生态已收敛到一个更广泛采用的实现，记录如下。
- 1024 商店渠道：先执行一次 npm i -g dsh1024，再执行 dsh1024 plugin --profile web add dsh-draw（计入 deepseek1024.com 安装排行）。

dshfind

为 DeepSeek Harness 提供统一的静态图像生成路由。

一个工具，多种引擎 —— 感知健康状态的故障回退、持久保存结果、统计用量。

dsh-doctor
DSH Market

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-draw

📖 生态知识库 —— 实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

安装与卸载

- git 渠道（最新 main）：dsh plugin --profile web add github:PerryLink/dsh-draw —— prepare 脚本只用生产依赖构建。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-draw。
- tarball 渠道：在本仓库执行 pnpm pack，再执行 dsh plugin --profile web add ./dsh-draw-<version>.tgz。
- 卸载：dsh plugin --profile web remove dsh-draw（或从配置档补丁里删掉对应行）。
如果 pnpm 对这个包报 ERR_PNPM_IGNORED_BUILDS（esbuild 的平台二进制校验，无害），在 pnpm-workspace.yaml 里加上 allowBuilds: { esbuild: true } —— dsh 命令行会打印出这段配置。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（共 95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

dsh-draw 是什么？

为 DeepSeek Harness 提供统一的静态图片生成路由。

一个工具，多种引擎 —— 按健康状态回退，结果持久保存，用量可统计。

dsh-draw 的工作流示意图：调用 → 插件 → 结果。

工作流概览：调用 → 插件 → 结果。下面的示例用的都是真实命令。

维护状态：🧊 冻结

2026-10-05 冻结。不再加新功能。 这个包仍然可用，也没有退役 —— 但不再做功能开发。只有真正的故障才会修。

维护者认为这项能力生态里已经有更广泛采用的实现，所以精力转到了别处。下面的对比数据测于 2026-10-05，记录下来，省得别人再测一遍。

| | 包 | 每周下载量 |
| 本包 | dsh-draw | 973 |
| 更广泛采用的实现 | dsh-image-gen | 7,216 |
| 另一个替代品 | @goodandready/dsh-image-gen | 4,822 |

为什么它是主流选择。 dsh-image-gen 在一个插件里提供 Gemini、OpenAI、Seedream、DashScope 和本地 ComfyUI。

兼容性。 它没有声明任何 dsh peer，所以兼容性守卫永远不会拦它。

👉 新项目请用 dsh-image-gen，它是主流选择。 已经装好的照常可用，什么都不会被移除。

完整证据，包括宿主版本兼容矩阵：dsh-plugin-supersession-review-20261005.md。

对比

dsh-draw 的实测对比图

测于 2026-10-05 · 数据来自 README 的 FROZEN 维护表（npm 每周下载量）

兼容性

| 层面 | 状态 |
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1（声明兼容 0.1.5-rc.2） |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 引擎 | 任意 OpenAI 兼容的 images 端点；内置 OpenAI Images（gpt-image-1）和智谱 CogView（cogview-3-flash）预设 |
| 界面 | 宿主 image_generate 工具 + 网页结果卡片 + 插件设置页 |
浏览器端跑在 cordis Context 和已发布的客户端包（dsh-client-ui-slots、dsh-client-ui-settings、dsh-client-ui-tool、dsh-client-locale、dsh-client-connection）上；不再依赖已移除的 dsh-client-runtime 包（工具调用块通过本地结构契约读取），因此客户端接口也与 0.1.2-rc.1 宿主对齐。

0.1.2-rc.1（适配于 2026-09-02）：会话信封保留其可忽略字段，仅用于兼容已存日志的读取——Session.append 仍无法写入该字段，所以审计门禁行为不变。已于 2026-09-06 对照 dsh-v0.1.7-alpha.1 master 检出验证（完整门禁链 + 配置档安装冒烟）。

0.1.6-alpha.2（适配于 2026-09-18）：Session.append 的第三个参数只为可上浮事件类型而存在，且类型是 SurfaceIntent，绝不是 ignorable 信封，所以 draw/generated（非上浮类型）在这条线上仍然不写入——配额按会话在内存中计数，会话重启即重置，与下文「Quota durability」说明完全一致。已于 2026-09-18 验证（双类型检查标尺 + 完整测试套件 + self-contained/artifacts/readme 门禁）。

0.1.7-rc.2（适配于 2026-10-04）：客户端 tool.call.toolview 契约把它的 owner 拆成三个阶段（preparing / start / result），参数还在流式传输时就会派发带 key 的卡片。因此结果卡片也要为更早的阶段渲染进行中的行——被占用的 key 槽位永远到不了宿主自己的通用行，所以对已准备阶段不作应答，会让整段流式窗口的行变空。其他都没变：已结算卡片、记账行和 regenerate 的行为与之前完全一致。已于 2026-09-23 验证（双类型检查标尺 + 完整测试套件 + 新的宿主契约门禁）。

你能得到什么

dsh-draw 给 harness 提供一个统一的 image_generate 工具，参数是标准的（prompt/size/count/quality/style/engine），再按引擎逐个转换：

- 多引擎路由——配置驱动的链路（OpenAI Images、智谱 CogView，或任意 OpenAI 兼容端点），自上而下遍历，带健康感知回退：连续失败会把引擎推入冷却，由下一个健康引擎接住调用。
- 结果持久化——生成的图片保存为工作区附件（内容寻址，遵循 harness 的附件策略），并以规范文件引用返回。
- 配额记账——按会话限制生成调用次数和图片字节数，从持久会话日志折算，在引擎花费前和存储前强制执行。
- 凭据即引用——引擎 API key 是环境变量名，每次调用通过官方 ctx.credentials 接缝解析；配置里从不存字面 key，日志里也从不记录。
- Web 界面 —— 会话内的结果卡片（图片、引擎、配额、一键重新生成），以及「插件」设置页签（引擎链、凭据状态、探测、配额上限）。

model harness
│ image_generate {prompt, ...} ──▶ validate ──▶ quota check ──▶ router
│ openai ──(fail)──▶ cogview ──▶ images
│ ◀── canonical JSON + image blocks (durable attachment refs)
│ └── draw/generated session event (quota + audit)

快速开始

dsh plugin --profile web add github:PerryLink/dsh-draw

1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-draw

or from npm (published releases)
dsh plugin --profile web add dsh-draw

2. provide the engine keys as credential references (environment variables)
OPENAI_API_KEY and/or ZHIPU_API_KEY — never in the profile patch

3. restart and verify the row
dsh --profile web --dump-config | grep -A2 'id: dsh-draw'

然后让智能体画图：

Draw a 1536x1024 landscape of a lighthouse at dusk, vivid style.

示例

以下是插件的真实入口：安装一次，之后调用其中一个。

详细示例

命令

~~~sh
image_generate

输入

~~~json
{
"prompt": "a cat"
}

输出

~~~text
{
"ok": true,
"engine": "openai",
"images": [
{ "attachmentId": "att-1" }
]
}

观察自 plugins/dsh-draw/tests/index.spec.ts:50-66; same fields asserted at plugins/dsh-draw/tests/drawer.spec.ts:59-69

失败分支

输入

~~~text
{"prompt":" "}

输出

~~~text
Error: image_generate: prompt must be a non-empty string

观察自 plugins/dsh-draw/src/drawer.ts:141-147; plugins/dsh-draw/src/tool.ts:137-140; plugins/dsh-draw/tests/drawer.spec.ts:77-82

简要示例

配置

所有可调项都是 Schemastery 的 Config 字段（可在 cordis.yml 中修改）。按 id 定向的覆盖会替换整行 —— 你需要把用到的每个键都重新写一遍。cordis.patch.yml 在每个键旁都有行内说明。

| 键 | 默认值 | 含义 |
| engines | OpenAI + CogView 预设 | 有序引擎链，自上而下依次尝试并回退；每项包含：id、baseUrl（不含凭据）、model、apiKeyRef（环境变量名）、provider（openai/replicate/fal，默认 openai）、enabled、sizeMap、qualitySupported、styleSupported、responseFormat（b64_json/url）、imageMediaType |
| defaultEngine | openai | 路由优先使用的引擎 id；必须是已配置的引擎 |
| requestTimeoutMs | 120000 | 单次生成的 HTTP 超时（1000..600000） |
| maxImagesPerCall | 4 | 单次调用可产出的图片上限（1..10） |
| maxPromptLength | 4000 | 提示词长度上限，按字符计（1..32000） |
| maxGenerationsPerSession | 200 | 单会话生成调用上限（1..100000） |
| maxBytesPerSession | 209715200 | 单会话图片字节上限（1048576..4294967296） |
| failureThreshold | 2 | 引擎进入冷却前允许的连续失败次数（1..10） |
| cooldownMs | 60000 | 达到阈值后引擎的冷却时长（1000..3600000） |

在配置档补丁中覆盖配置的示例：

- insert:
- id: dsh-draw
name: dsh-draw
config:
defaultEngine: cogview
maxImagesPerCall: 2

工具与界面

| 界面 | 说明 |
| image_generate | 标准参数；返回规范 JSON（engine/model/size、图片引用、配额、回退标记、尝试记录），外加图片内容块 |
| 结果卡片（tool.call.toolview，键为 image_generate） | 调用每个阶段都有展示：参数流式传入时显示进行中行，随后显示图片、引擎/配额行，结束后可一键重新生成（完整抽屉路径：配额 + 路由 + 审计） |
| 设置页签（Plugins → Image generation） | 引擎链、凭据状态、设置/移除 API key（凭据引用）、连通性探测、配额上限 |

权限与数据

- 权限：插件只向配置好的引擎端点发起出站 HTTPS 调用；其他界面均为只读。设置页签唯一的写操作，是通过官方 ctx.credentials 接口设置/移除凭据。
- 数据：生成的图片经官方附件存储保存，遵循 harness 自身的附件策略。配额用量由 draw/generated 会话事件汇总，另加内存回退账本，用于无法记录这些事件的主机——除此之外不存任何东西。
- 会话日志：draw/generated 事件记录引擎、模型、标准化请求、字节总量和附件 id——只记审计事实，绝不记 API key。仅当主机认识该类型，或接受 ignorable 信封（挂载时探测）时，才追加该事件；在 rc.6/rc.7 主机和 0.1.2-rc.1 系列上（其 Session.append 无法打上标记，且读取时遇到未知类型会直接失败），载荷改走内存回退账本，因此生成图片不会再让会话无法重新打开。

安全边界

- 只认凭据引用，不认字面量。 apiKeyRef 指向环境变量；baseUrl 里内嵌凭据会直接导致加载失败并报错。
- 展示前脱敏。 URL、探测备注和错误文本在展示或写日志前都会脱敏（userinfo 密码、凭据查询值、bearer token、JWT）。
- 先查配额再花钱。 调用引擎前、存储附件前都会检查生成次数和字节上限；配额耗尽的会话快速失败，不消耗引擎额度。
- 该报错就报错，回退要有意为之。 格式错误的响应以结构化错误呈现；引擎失败达到冷却阈值后跳过，整条链都耗尽时返回完整尝试记录，而不是假装成功。

已知限制

- 仅支持图片模型。 没有视频、音频或编辑端点；不支持视觉理解。
- 引擎兼容性。 通过服务商接缝支持三套词汇表：openai（POST /images/generations 的请求形状）、replicate（创建预测 + 轮询）、fal（fal.run 队列）。prompt/尺寸/数量之外的服务商专属扩展项（如 seed、scheduler）不在范围内。
- 成本感知是结构性的。 插件只统计调用次数和字节数，不知道引擎定价——搭配 dsh-budget 做成本治理。
- rc.6/rc.7、0.1.2-rc.1 和 0.1.6-alpha.2 上的配额持久性。 有些宿主无法在会话日志里承载 draw/generated（静态事件白名单，没有 ignorable 信封；0.1.2-rc.1 无法打上标记，读取时遇到未知事件类型会按失败关闭处理；在 0.1.6-alpha.2 上，append 的第三个参数是 SurfaceIntent，只适用于 surface 类型，所以非 surface 事件无法标记），此时配额对当前会话靠内存兜底账本保持精确，但重启后会重置；在带插件事件 surface 的宿主上，持久记账会恢复。第一次被拒绝的提交会警告一次，这样降级的会话可见，而不是悄无声息。

Development

pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc: src + tests against the local harness checkout
pnpm run typecheck:ci # tsc against the published 0.1.7-rc.2 faces (no paths)
pnpm test # vitest: 19 spec files (scripted transport, real Context/Session/ToolRuntime)
pnpm run build # tsc declarations + tsdown bundles (lib/)
pnpm run verify:self-contained # dependency specs resolve from the registry
pnpm run verify:host-contract # the host tool-view contract still matches what this plugin declares
pnpm run verify:artifacts # host ESM face + typert manifest + browser bundle + config files
pnpm pack # the published tarball

Topics

dsh, dsh-plugin, deepseek-harness, deepseek, cordis, image-generation, openai-images, cogview, zhipu, text-to-image

Contributors

- @PerryLink — 创建者兼维护者：引擎路由、绘制器、配额记账、Typert 线格式词汇表、浏览器端，以及五种语言的文档。
- @Mohei-Muun — 报告了 rc.7 宿主上 draw/generated 会话日志卸载 bug（#2），由此引入了自适应事件门控。

PerryLink DSH Plugin Family

本项目属于 PerryLink 的 DeepSeek Harness 插件家族。下面这份名册默认折叠，好让每个 README 的首屏都保持简短；展开即可看到每一行及其状态。

Expand all plugins

| Plugin | Status |
| dsh-aqua-input-check | |
| dsh-archive-check | |
| dsh-auto-review | |
| dsh-autotier | |
| dsh-bid-ca-precheck | |
| dsh-bid-qual-check | |
| dsh-cert-mcp | |
| dsh-checkpoint-rewind | |
| dsh-click | |
| dsh-composer-history | |
| dsh-contract-stance | |
| dsh-customs-doc-check | |
| dsh-data-quality | |
| dsh-demurrage-ledger | |
| dsh-doublecheck | |
| dsh-drill-script-check | |
| dsh-eia-guide-check | |
| dsh-emergency-plan | |
| dsh-essay-rubric-check | |
| dsh-evidence-check | |
| dsh-export-ctl-check | |
| dsh-fast | |
| dsh-fmea-table-check | |
| dsh-forecast-penalty | |
| dsh-fund-research | |
| dsh-github | |
| dsh-gongwen-flow-check | |
| dsh-gongwen-word-check | |
| dsh-guard-plan-qc | |
| dsh-hazchem-check | |
| dsh-hazplan-check | |
| dsh-hidden-risk-map | |
| dsh-hs-classify | |
| dsh-icd-rule-check | |
| dsh-industry-research | |
| dsh-lawcite-adapter | |
| dsh-laya | |
| dsh-lc-doc-check | |
| dsh-learning-gap-check | |
| dsh-library | |
| dsh-local-ai | |
| dsh-lsp-actions | |
| dsh-mask | |
| dsh-mcp-panel | |
| dsh-medrec-qc | |
| dsh-memento | |
| dsh-nsfc-form-check | |
| dsh-nurse-record-check | |
| dsh-observe | |
| dsh-origin-rvc-check | |
| dsh-ota-review-check | |
| dsh-output-styles | |
| dsh-paper-doc-adapter | |
| dsh-permission-rules | |
| dsh-permit-report-check | |
| dsh-pipeline-check | |
| dsh-pleading-draft | |
| dsh-plugin-doctor | |
| dsh-plugin-guide | |
| dsh-plugin-kit | |
| dsh-plugin-upgrade | |
| dsh-policy-brief-draft | |
| dsh-power-loss-split | |
| dsh-power-ticket-check | |
| dsh-ppap-check | |
| dsh-protest-deadline | |
| dsh-railway-window | |
| dsh-repair-order-qc | |
| dsh-research-report | |
| dsh-review-reply-check | |
| dsh-rulefile-check | |
| dsh-safety-brief-check | |
| dsh-score | |
| dsh-session-sync | |
| dsh-site-log-check | |
| dsh-skill-pack-security | |
| dsh-soe-decision-check | |
| dsh-soilwater-check | |
| dsh-sop-sync-check | |
| dsh-spc-gbt-adapter | |
| dsh-talk | |
| dsh-tender-extract | |
| dsh-tender-matrix | |
| dsh-test-drive | |
| dsh-ticktick | |
| dsh-translate | |
| dsh-warranty-calc | |
| dsh-budget | 🧊 已冻结 — 见仓库 README |
| dsh-claude-move | 🧊 已冻结 — 见仓库 README |
| dsh-defend | 🧊 已冻结 — 见仓库 README |
| dsh-draw | 🧊 已冻结 — 见仓库 README |
| dsh-reach | 🧊 已冻结 — 见仓库 README |
| dsh-background-agents | 🚫 已退役 — 见仓库 README |
| dsh-session-pin | 🚫 已退役 — 见仓库 README |
| dsh-team-rooms | 🚫 已退役 — 见仓库 README |

许可证

Apache License 2.0 © 2026 dsh-draw contributors