dsh-runninghub-plugin

DSH RunningHub 插件

在 DSH 中调用 RunningHub 工作流，生成图片、视频、音频或其它文件。

支持由 AI 对话自动解析并配置工作流，也可在浏览器面板中直观调整节点参数、管理 Key 池与维护提示词规范文档。

[!NOTE]

平台入口与准备工作：

- 国内站：RunningHub 国内 ｜ 获取国内 API Key

- 海外站：RunningHub 海外 ｜ 获取海外 API Key

💎 通过上述邀请链接注册，可获得 500 RH 币（平台积分，可用于运行工作流）。

使用前需要准备：DSH 桌面版、RunningHub API Key，以及支持 API 调用的工作流。国内平台（.cn）与海外平台（.ai）的账号和 Key 分开使用、互不通用，运行费用由 RunningHub 按平台标准收取。

安装

# 安装到 DSH 桌面端
dsh plugin --profile desktop add github:achenjins/dsh-runninghub-plugin

安装后重启 DSH 并刷新页面。配置面板位于「插件」→「dsh-runninghub-plugin」。

卸载：

dsh plugin --profile desktop remove dsh-runninghub-plugin

• 锁定版本：可在安装地址后追加 #。
• 免构建：纯手写原生代码，安装时无需额外批准执行脚本。

本地开发安装

在仓库根目录执行：

node tools/install.mjs             # 安装到 profile（自动备份配置）
node tools/install.mjs --uninstall # 撤销安装

主要功能

• 提示词深度优化（核心功能）
• 规范文档库：在面板上传或编写提示词规范（Markdown / 纯文本），随时挂载到指定工作流。
• 两种优化模式：支持主模型读取文档后自行改写；也可开启「独立子代理」模式，将文档作为系统设定交由极简子代理专职润色，不占用主模型对话上下文，出词风格更统一。
• AI 辅助工作流配置
• 把 RunningHub 工作流链接直接发给 AI，AI 自动读取 ComfyUI 节点结构，推断提示词、参考图、采样步数等角色，用提问方式确认后自动保存配置。
• 节点可视化精细调优
• 提供开箱即用的浏览器配置面板，支持逐项调整节点角色、默认值、必填项、数值范围及下拉枚举选项，未保存的修改拥有草稿保护。
• 多 Key 轮换与资产保护
• 支持添加多把 Key 并自动识别所属地域。
• 物理隔离：国内池与海外池互不混用，避免无谓调用浪费。
• 余额不足自动换号：某把 Key 余额不足时标记为「余额不足」并轮换下一把可用 Key；充值后自动（或在面板点「查余额」）恢复，不会每隔几分钟拿没钱的 Key 再试一次。
• 并发已满自动排队：账号并发上限（1520）或独占机器不足（415）时，任务在本地排队、按 30s → 60s → 120s 退避自动重投；前面的任务结束时会提前唤醒。这两种情况 RunningHub 都没有受理、不扣费，Key 也不会被冷却。
• 防止重复扣费：网络超时或异常时严格记录为 UNCERTAIN（待核对），绝不盲目重投；核对后可用 task.adopt 接回远端任务，或用 task.dismiss 结案。
• 异步后台生成与结果直达聊天
• 任务提交后秒级返回任务 ID，后台静默轮询。支持作业系统通知，调用 task.wait 即可将生成的图片/视频作为附件直接渲染在聊天中。
• 若远端已生成完毕但本地因网络波动下载中断，支持随时一键补下载，无需重新运行。

快速上手

只需要三步即可跑通：

1. 获取并添加 Key：

• 登录对应平台的 API 页面复制专属 API Key：
• 国内站：打开国内 API 页面
• 海外站：打开海外 API 页面
• 在 DSH 打开配置面板「Key 池管理」添加 API Key（地域可选国内、海外，或直接选自动探测）。

1. 让 AI 配置工作流：

把你的 RunningHub 工作流链接发给 AI 辅助配置。

[!TIP]

推荐体验工作流：

可以体验我的国内平台qwen image2.1工作流 【Qwen Image 2.1】万能输入工作流。进入页面后点击保存为自己的工作流，然后将你账号下保存后的工作流链接（或 ID）发给 AI。

向 AI 发送指令，例如：

“帮我配置这个工作流：https://www.runninghub.cn/workflow/xxxxxxxxxxxxxxxxxxx”

AI 会读取节点结构，向你确认提示词节点、参考图输入和常用参数，确认后自动保存。该工作流建议让 AI 只保留一个提示词输入节点、6 个图片输入节点和画幅比例调节节点。

RunningHub 的画幅比例与分辨率参数通常以下列格式显示，可直接复制发给ai辅助配置或在面板编辑该节点时直接填入枚举选项（options）：

• 1:1 (Square)
• 2:3 (Portrait Photo)
• 3:2 (Photo)
• 3:4 (Portrait Standard)
• 4:3 (Standard)
• 9:16 (Portrait Widescreen)
• 16:9 (Widescreen)
• 21:9 (Ultrawide)

1. 开始生图：配置完成后，直接向 AI 发送指令：

“用刚才配置的文生图工作流，画一只在竹林里吃竹子的熊猫”

任务提交后会立刻返回任务 ID。调用 task.wait 即可将结果图片取回并直接展示在聊天气泡中。

配置面板与节点配置详解

打开 DSH「插件」→「dsh-runninghub-plugin」即可进入配置面板。点击任意工作流展开，即可进入节点配置详情页：

1. 工作流基本信息区

• 名称与英文标识：支持设置直观的中文名称，以及供大模型内部识别的稳定英文标识（displayNameEn）。
• 地域选择：指定该工作流默认使用国内池还是海外池的 Key。
• 输出类型：指定生成类型，支持 image（图片）、video（视频）、audio（音频）、3d、text、mixed。
• 描述（给模型看）：向模型说明该工作流的适用场景。大模型在寻找合适工具时会参考此处的描述。
• 查看 JSON：支持随时一键展开/收起底层原始 JSON 配置，便于技术排查。

2. 节点表格与自动分组（8 列清晰呈现）

工作流导入后，插件会自动将底层 ComfyUI 节点按功能分类（如画面、采样器、模型、提示词等），支持按分组折叠。表格清晰呈现 8 项核心属性：

列名 · 说明 节点 · ComfyUI 内部原生数字 ID（如 6、9） 类型 · 节点 ClassType（如 CLIPTextEncode、KSampler、LoadImage） 角色 · 当前赋予的语义角色（如提示词、参考素材、参数等） 字段 · 对应的内部字段名（如 text、image、seed、steps） 默认值 · 运行未显式传参时使用的缺省值 范围 / 枚举 · 数值步长限制，或下拉候选列表 必填 · 标注该输入是否必须提供 操作 · 点击展开/收起该节点的内联编辑面板

3. 节点内联编辑功能

点击任意节点右侧的「编辑」，即可在下方展开表单进行精细调节：

• 角色重指派（role）：提供 10 种标准角色：
• 正向提示词（prompt）、负向提示词（negative_prompt）
• 参考图（image）、参考视频（video）、参考音频（audio）
• 数值（number）、下拉选择（select）、布尔开关（boolean）、随机种子（seed）、其他（other）

若自动推断有偏差，可随时手动修正。

• 显示名与字段名（label / fieldName）：自定义展示给界面的友好标签与内部提交字段。
• 自定义分组（group）：可自由调整该节点所属的分组，方便梳理庞大复杂的节点图。
• 值类型与默认值（valueType / defaultValue）：
• 支持 string、number、boolean、enum。
• 设定默认值后，若用户或模型调用时未指定该参数，系统会自动带上默认值提交。
• 数值范围硬校验（min / max / step）：
• 系统内置的推断范围仅作建议提示；
• 用户手动设置的数值范围会在调用前强制校验。若参数越界将直接拦截，防止把错误参数发给云端导致任务失败。
• 枚举候选值列表（options）：
• 支持按行编辑画幅比例、采样器等下拉列表。配置后，前端与模型只能选择预设值，杜绝随意填错。
• 必填项与备注（required / note）：勾选必填后，参数缺失将阻止发起调用；备注用于记录特殊调整心得。

4. 提示词优化联动配置

在节点表格下方，可直接配置该工作流专用的提示词增强链路：

• 启用开关：一键开启或关闭优化。
• 绑定规范文档：从已上传的文档库中下拉挑选对应的规范指南（如《人像生成提示词指南.md》）。
• 指定写入目标节点：可指定优化后的提示词写入哪个正向提示词节点（默认自动寻找）。
• 极简子代理模式：勾选后，运行前会将规范文档作为系统设定，唤起一个专注的极简子代理来润色提示词。
• 附加指令：支持配置固定补充指令（如“画质优先，画面不要出现文字”）。

5. 草稿保护与确认机制

• 草稿保护：修改任意参数后，即便折叠手风琴或切换查看其他工作流，当前修改都会暂存在面板中，不会意外丢失。
• 放弃修改：可随时点击「放弃修改」一键复原到已保存状态。
• 首次配置确认：新导入的工作流在初次保存前，需要勾选“我已确认节点角色、默认值和输出类型”，防止误操作。

面板其他模块

• Key 池管理：增删 Key、查询单 Key 余额、切换国内/海外节点、启用/禁用与优先级设置。
• 文档库：在线上传或直接编辑提示词规范 Markdown 文档，供工作流挂载。
• 任务流水看板：
• 查看任务历史，支持按状态筛选。
• 面板展开且页面在前台时，有正在执行的任务会自动每 3 秒刷新进度。
• 任务卡片上直接提供「补下载 / 补附件」按钮：若远端已生成完毕但本地文件没下完整，点击即可直接补拉，无需重新跑图。

模型工具调用参考

插件向大模型注册两个工具：runninghub_search 无参数，只返回 runninghub_call 各动作的使用方式；runninghub_call 执行查询、配置和生成。工作流、生成记录等数据都要通过 call 的对应动作查询。

从 0.2.0 起，call 只暴露 action 和 args：动作名称放 action，其余参数统一放 args 对象。无参数动作可以省略 args。旧的平铺参数写法需要调整；已知动作时可以直接调用，不必每次重新 search。

1. 查动作，再选择工作流

runninghub_search({}) // 获取全部动作的使用方式，无需传参数
runninghub_call({ action: "workflow.get" }) // 列出已配置工作流的简短介绍
runninghub_call({ action: "workflow.get", args: { query: "文生图" } }) // 按名称、英文名、描述或标签筛选
runninghub_call({ action: "workflow.get", args: { name: "我的文生图" } }) // 选定后读取完整节点配置

不传 name 时，workflow.get 只返回 name、displayNameEn、description、outputKind 和 tags。先根据这些介绍选工作流，再传 name 查看输入节点、参数范围及提示词优化要求。

接入新工作流时，workflow.probe 返回一份待确认的 config，节点在 config.nodes 中。确认并修改后，把它传给 workflow.configure 保存。

2. 提交生成任务

runninghub_call({
  action: "workflow.run",
  args: {
    name: "我的文生图",
    prompt: "一只在竹林里吃竹子的熊猫",
    background: true // 推荐后台模式：立即返回 taskId，不阻塞聊天对话
  }
})

3. 查询进度与取回结果

runninghub_call({ action: "task.status", args: { taskId: "任务 ID" } }) // 仅查询状态
runninghub_call({ action: "task.status", args: { taskId: "任务 ID", details: true } }) // 排查时读取详情
runninghub_call({ action: "task.wait", args: { taskId: "任务 ID" } })   // 等待完成并取回附件

4. 补取文件或附件（无需重复生成）

runninghub_call({ action: "task.retry", args: { taskId: "任务 ID" } })

若文件已在本地，只需在聊天中重新发一遍图片，可传 { resend: true }。

生成、等待和补取结果的回执只带任务 ID、状态和结果。文件保存且附件就绪后只返回本地路径；下载或附件失败时保留最近 24 小时的在线链接和失败原因，不重复返回提示词、节点参数或 Key 信息。task.status 默认只返回状态和错误摘要；排查时传 details: true 读取详情。完整请求信息保存在本地任务记录中。

同步等待（args.waitMs > 0）完成后直接返回附件，不再重复发送后台通知；超时仍在运行的任务会转入后台通知。子代理优化模式直接调用 prompt.optimize，由插件加载规范文档，主模型不用先读一遍；自行优化模式才需要 prompt.doc_read。

5. 传入参考图与自定义参数

runninghub_call({
  action: "workflow.run",
  args: {
    name: "我的图像编辑",
    prompt: "把背景换成星空",
    images: { "470": "E:/images/reference.png" }, // 节点 ID: 本地文件绝对路径或云端文件名
    params: { "3:steps": 30 },                   // 推荐 "节点 ID:字段名" 精确覆盖
    saveDir: "生成结果",                         // 本地保存目录（相对会话目录或绝对路径）
    fileName: "星空"                             // 自定义保存文件名（同名自动加序号）
  }
})

• 保存目录规则：缺省时优先使用配置的 outputDir；未配置时保存在会话工作目录下的 runninghub-output 中。
• 批量提交：支持传 repeat: 1~20 一次提交多条独立任务。
• 素材上传：同次调用中，重复节点和批量任务会复用未变化素材的上传结果。复用限于同一 Key 和地域，提交结束后释放，不跨调用缓存。

提交前可用 workflow.validate 预检，传入与运行时相同的 prompt、negativePrompt、params 和 images。它检查输入参数与可用 Key，不上传素材、不提交任务；本地文件在运行上传时检查。

查最近的生成记录：runninghub_call({ action: "task.list", args: { limit: 20 } })。每条记录只有本地 id 和在线结果 links，没有提示词或工作流详情。查询过滤超过 24 小时的链接；本地文件和任务记录仍可在面板查看、补发。

6. 处理「待核对」任务

提交时网络中断，任务会记为 UNCERTAIN（待核对）。到 RunningHub 后台按提交时间、工作流 ID、所用 Key（面板上都有显示）核对：

// 后台找到了：把远端任务 ID 接回来，插件会继续轮询并下载结果
runninghub_call({ action: "task.adopt", args: { taskId: "uncertain-xxxx", remoteTaskId: "1904152026220003329" } })

// 确认后台没有创建：结案，不再占用待核对名额
runninghub_call({ action: "task.dismiss", args: { taskId: "uncertain-xxxx", reason: "后台没有这个任务" } })