文生图画布 NinjaSln-labs/dsh-imgdraw

dsh-imgdraw

npm version
License
GitHub stars

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--[-].。

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 起转蓝。