dsh-imgdraw

dsh-imgdraw

English | 简体中文（中文为准，英文翻译可能滞后）

DeepSeek Harness 文生图插件：输入框「🎨 生图」按钮 + 弹窗（提示词 / 尺寸 / 数量 / 后端 / 配额 / 异步生成 / 4 格网格 / 下载 / 选定保留 / 删除 / 历史重新生成），并注册模型工具 draw_image 与 /imgdraw/ 图片路由。正式 bundle：重启不丢，随 profile 自动加载。后端：DashScope wan2.7-image（免费默认）与 SiliconFlow Qwen-Image。

特性

• draw_image 模型工具 — 同步等待生成，返回 /imgdraw/<文件名> URL 列表。支持 prompt / count / size / backend / tag 参数，AI 可直接在对话中调用。180s 超时，适合大图生成。

• 🎨 生图弹窗 — 输入框左侧按钮 → 弹窗交互：提示词输入（可一键填入 Sin v10 头像模板）、尺寸选择（1:1 / 16:9 / 9:16 / 4:3 / 3:4）、数量选择（1–4 张）、后端切换（dashscope / siliconflow）、实时配额显示（剩余次数/总额度）。提交后异步生成（2s 轮询），结果以 4 格网格展示，每张可下载 / 选定保留（永不清理） / 删除。

• /imgdraw 图片路由 — 直链图片访问：http://127.0.0.1:3080/imgdraw/<文件名>。历史记录跨重启持久化（~/.dsh/imgdraw/index.json，原子写入）。

• 历史持久化与清理 — 所有 job 记录在 index.json，跨重启保留。选定保留的图片永不清理；每轮自动清理保留最新 N 张（默认 24）。支持从历史记录重新生成。

• 多后端支持 — 配置可切换后端与模型，无需改代码。默认 DashScope wan2.7-image（免费额度），可选 SiliconFlow Qwen-Image，用尽后切 qwen-image-2.0 / z-image-turbo。

安装

# npm 发布后
dsh plugin add dsh-imgdraw

本地开发（本机 web profile，指向本单库目录）：

cd ~/.dsh/profiles/web
npm add dsh-imgdraw@file:/path/to/dsh-imgdraw
# 并在 package.json 的 dsh.profile.bundles 列表加入 "dsh-imgdraw"，然后重启 dsh web

配置（cordis.patch.yml / profile overlay，均可选）

字段	默认	说明
outDir	~/.dsh/imgdraw	图片输出目录
keysPath	~/.dsh/image-api-keys.json	API keys JSON（dashscope / siliconflow 字段）
routePrefix	/imgdraw	图片路由前缀（无尾斜杠）
rpcPath	/imgdraw-rpc	浏览器 JSON RPC 路由
keepLatest	24	每轮清理后保留的最新文件数（选定保留的文件永不清理）
maxCount	4	单次最大生成数量
defaultBackend	dashscope	默认后端：dashscope（百炼 wan2.7-image 免费）或 siliconflow（Qwen-Image）
dashscopeModel	wan2.7-image	百炼模型
siliconflowModel	Qwen/Qwen-Image	SiliconFlow 模型
historyCap	50	历史记录条数上限（index.json 最多保留的 job 数）

示例：

- id: imgdraw
  name: 'dsh-imgdraw'
  config:
    keepLatest: 40
    defaultBackend: 'dashscope'

使用

• 模型工具：draw_image（prompt / count / size / backend / tag）——同步等待生成，返回 /imgdraw/<文件名> 列表。
• 浏览器：输入框左侧「🎨 生图」→ 弹窗填提示词（可一键填入 Sin v10 头像模板）→ 生成 → 4 格网格预览 → 下载 / 保留 / 删除；「最近生成」历史跨重启持久化（~/.dsh/imgdraw/index.json）。
• 直链：http://127.0.0.1:3080/imgdraw/<文件名>。

HTTP API

两条路由均绑定 127.0.0.1（loopback）。所有响应统一 JSON 封套 { ok: true, result } / { ok: false, error }。

GET

路由	说明
GET /imgdraw/	{ ok, route, files: JobFile[] } —— 输出目录扫描结果（最近 40 个）
GET /imgdraw/<文件名>	图片二进制（image/png 等）；文件名非法（. / .. / 路径分隔符 / >200 字符）→ 400 { ok:false, error:'invalid name' }；文件名合法但不存在 → 404

POST /imgdraw-rpc

请求体为单一封套 { "method": "...", "args": { ... } }。

方法	参数	返回 result
submit	prompt（必填）· count 1–4，默认 1 · size 默认 1024*1024 · backend dashscope | siliconflow，默认取配置 · tag 默认 img（仅保留 \w-，截断 40 字符）	{ jobId }；prompt 为空时 ok:false
status	jobId（注意不是 id）	{ jobId, status, prompt, backend, files, createdAt, finishedAt }（error 仅失败时出现）；查不到时 ok:false 任务不存在
latest	—	{ files, jobs, quota }（quota 为累计成功次数，非剩余额度）
select	name（文件名）· keep（true 保留 / false 取消）	{ kept }
delete	name（文件名）	{ deleted }；只删文件，任务记录与 quota 计数均保留
backends	—	{ backends: [{ id, label, model, keyPresent, quota, quotaHint, sizeHint }] }
refresh-keys	—	{ ok }；重新读取 keys 文件（新增 key 后不必重启）

文件名参数经 basename 归一化并拒绝路径分隔符、. / .. 与超长（>200）名称；tag 参与生成文件名 draw-<tag>-<时间戳>[-<序号>].<ext>。

status 只读进程内任务表（仅由 submit 填充，boot 时不从 index.json 回填）—— 重启后重启前提交的任何 jobId 都查不到（运行中的任务被标记为 interrupted）；latest 与 GET /imgdraw/ 读磁盘，历史与文件跨重启仍可见。

后端说明

• 百炼 wan2.7-image（默认）：DashScope multimodal-generation/generation 同步端点（国内域名优先，intl 备用）；免费额度有限，用尽后建议切 qwen-image 系列或 z-image-turbo。
• SiliconFlow Qwen-Image：images/generations 端点，依赖账户券/余额。
• keys 文件：~/.dsh/image-api-keys.json（{"dashscope": "sk-...", "siliconflow": "sk-...", ...}）。

开发

npm install --legacy-peer-deps   # peer 由宿主 dsh 提供，devDeps 供构建/类型检查
npm run build                    # tsc → lib/ + esbuild → lib/client.js
npm run typecheck                # 严格类型检查

已知坑：客户端 RPC 无 harness.handle（bundle 半无此桥），Client→Host 走同源 /imgdraw-rpc HTTP；生成必须异步提交 + 轮询（浏览器 fetch 30s 上限）；动态插件重启丢失是 DSH 机制，本包为正式 bundle 不受影响。

设计决策

决策	原因
正式 bundle 而非动态插件	动态插件重启丢失是 DSH 机制；正式 bundle 重启不丢、随 profile 自动加载、无需重新批准
Client→Host 走同源 /imgdraw-rpc HTTP	bundle Client 无 harness.handle 桥，RPC 需自建同源路由（loopback，文件名 basename 防穿越）
生成异步提交 + 2s 轮询	浏览器 fetch 30s 上限，长耗时生成必须异步；draw_image 工具路径可同步等待（180s 超时）
默认 DashScope 而非 Gemini	Gemini 有地区限制（AI Studio "Unable to check subscription"）；百炼 wan2.7-image 免费额度且国内直连
本地计数配额	API 无账单查询接口，先本地计数 + 手动核对，不做假对接

⭐ 支持

如果这个插件对你有帮助，欢迎到 GitHub 仓库 点个 ⭐ Star——它是我持续维护的动力。也欢迎提 issue / PR 一起改进。

贡献与发版

贡献指南见 CONTRIBUTING.md，开发流程与部署纪律见 DEVELOPMENT.md，发布流程见 .github/workflows/publish.yml。

License

MIT — Copyright (c) 2026 ninjasln

上方 version 徽章在 0.x 期间显示为橙色，这是 shields.io 对 semver 预发布/零版本的通用着色规则（esbuild 0.x 同样为橙色），不是包状态异常；1.0.0 起转蓝。