dsh-runninghub-plugin

DSH RunningHub 插件

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

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

[!NOTE] 平台入口与准备工作：

• 国内站：RunningHub 国内 ｜ 获取国内 API Key
• 海外站：RunningHub 海外 ｜ 获取海外 API Key

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

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

安装

DSH 桌面版：在桌面应用的插件页面安装，可以使用 npm 包名 dsh-runninghub-plugin、GitHub 仓库 achenjins/dsh-runninghub-plugin，或下载 Releases 里的 .tgz 安装包后从本地安装；也可以在已收录本插件的插件市场中搜索安装。桌面版的 profile 由应用自己管理，命令行的 dsh plugin --profile desktop … 不能用于桌面版。

DSH Web 版 / 命令行（从 npm 安装）：

dsh plugin --profile web add dsh-runninghub-plugin

也可以直接从 GitHub 安装：dsh plugin --profile web add github:achenjins/dsh-runninghub-plugin。

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

卸载：桌面版在插件页面移除；Web 版执行

dsh plugin --profile web remove dsh-runninghub-plugin

• 锁定版本：命令行安装时可在包名后加版本号，例如 dsh-runninghub-plugin@0.3.3；从 GitHub 安装时可追加 tag 或 commit，例如 github:achenjins/dsh-runninghub-plugin#v0.3.3。
• 免构建：纯手写原生代码，没有构建步骤，安装时无需批准执行任何脚本。

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

主要功能

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

快速上手

只需要三步即可跑通：

1. 获取并添加 Key

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

2. 让 AI 配置工作流

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

[!TIP] 推荐体验工作流：可以试试我发布的 Qwen Image 2.1 工作流：

• 国内站：【Qwen Image 2.1】万能输入工作流
• 海外站：【Qwen Image 2.1】文生图，图生图工作流

进入页面后一定要先点击「运行工作流」，进入工作流后再保存为自己的工作流；然后把你账号下这份工作流页面的网页链接（或 ID）发给 AI。海外站保存后，还可以在工作台页面看到你保存的工作流。

新用户通过上面的链接注册，或注册时填写邀请码（国内站 8cq8uhl8，海外站 c1ooihmg），可获得 500 RH 币。

向 AI 发送指令，例如：

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

AI 会读取节点结构，向你确认提示词节点、参考图输入和常用参数，确认后自动保存。配置上面推荐的工作流时，建议让 AI 只保留 1 个提示词输入节点、6 个图片输入节点和画幅比例节点。

RunningHub 的画幅比例参数通常是下面这种格式，但也可能不同，实际取值需要进入 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)

3. 开始生图

配置完成后，直接向 AI 发送指令：

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

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

配置面板与节点配置详解

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

1. 工作流基本信息区

• 名称与英文标识：支持设置直观的中文名称，以及供大模型内部识别的稳定英文标识（displayNameEn）。
• 重命名与克隆：重命名保留本地 ID；克隆创建独立本地 ID，复制已保存的配置。面板中当前未保存的修改会继续保留。
• 地域选择：指定该工作流默认使用国内池还是海外池的 Key。
• 输出类型：指定生成类型，支持 image（图片）、video（视频）、audio（音频）、3d、text、mixed。
• 描述（给模型看）：向模型说明该工作流的适用场景，模型挑选工作流时会参考这里的描述。
• 运行设备：每个工作流分别选择 Standard（24GB）/ Plus（48GB）/ Ultra（84GB），保存后模型运行直接使用。模型辅助配置时会询问并保存机型，生成时无需重复选择。三档分别传 instanceType: default / plus / ultra，包括 Standard 也明确发送；设备支持与计费以 RunningHub 账号权益为准。
• 查看 JSON：支持随时一键展开/收起底层原始 JSON 配置，便于技术排查。

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

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

3. 节点内联编辑功能

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

• 角色重指派（role）：自动推断有偏差时可随时手动修正，共 10 种标准角色：
  • 正向提示词（prompt）、负向提示词（negative_prompt）
  • 参考图（image）、参考视频（video）、参考音频（audio）
  • 数值（number）、下拉选择（select）、布尔开关（boolean）、随机种子（seed）、其他（other）
• 显示名与字段名（label / fieldName）：自定义界面上显示的标签，以及提交时使用的内部字段名。
• 自定义分组（group）：可自由调整该节点所属的分组，方便梳理庞大复杂的节点图。
• 值类型与默认值（valueType / default）：
  • 支持 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 的对应动作查询。

插件还自带两个 Skill，模型在对应场景下会先读取：

• runninghub-generate：生成操作手册。用户要求生图、生视频、生音频或运行工作流时读取，内容包括怎么选工作流、写提示词、提交任务、取回结果，以及排队、待核对等状态的处理，避免模型不会用插件或重复提交付费任务。
• runninghub-workflow-setup：工作流配置流程。用户要接入新工作流时读取，按提问的方式逐项确认节点后保存配置。

从 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 保存。

素材槽默认可选，提示词、开关、范围与候选值仍需确认，推断风险会列在 warnings。默认隐藏 other 内部记录，includeInternal: true 可展开；includeGraph: true 返回精简连线图，mediaNodes.targets 给出素材的目标输入。overridable 仅表示 RunningHub 界面的可编辑标记，API 显式覆盖不受它限制。每次 probe 都重新取远端数据，并返回 fetchedAt、内容指纹 cacheId 和 cacheHit: false。

文档可用 prompt.doc_list 列出，再按 docId 或文档名称 name 读取；workflow 参数明确按工作流读取关联文档及附加指令。重命名与克隆分别使用 workflow.rename { name, newName }、workflow.clone { name, newName }，其中 name 也可传本地 ID。

2. 提交生成任务

runninghub_call({
  action: "workflow.run",
  args: {
    name: "我的文生图",
    prompt: "一只在竹林里吃竹子的熊猫",
    background: true // 后台运行：立即返回，完成后通知当前会话
  }
})

启用 background: true 后，模型继续处理会话中的其它事项，或结束本轮回复等待完成通知；无需立即 task.wait 或循环查询。收到完成通知后，尚未展示的结果再通过 task.wait 取回附件。后台参数默认为 false，不能安排通知时回执会说明，并提示主动取回。

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" } })

若文件已保存在本地，只是想在聊天中重新发一遍附件，可在 args 中加上 resend: true。

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

同步等待（args.waitMs > 0）时，任务完成会直接返回附件，不再另发后台通知；等待超时仍未完成的任务会转入后台，完成后再发通知。两种优化模式都可直接调用 prompt.optimize；自行模式首次返回规范，由主模型改写，已读文档时传 includeDoc:false 避免重复正文。子代理模式由插件加载规范，直接返回优化结果。

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

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

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

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

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

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: "后台没有这个任务" } })

task.adopt 会先用同地域的 Key 查一次远端任务；查不到（ID 写错或属于另一个地域）时直接报错，原记录保持不变。面板的任务卡片上也有「关联远端任务」和「确认未创建并结案」两个按钮。

配置与等待的边界

工作流同名不同本地 id 会被拒绝；覆盖已有 id 必须先确认并传 overwrite: true。workflow.update 的对象局部合并，数组整体替换；替换 nodes 时需要提供完整节点记录。文档新建名称冲突返回 DOC_EXISTS，确认后才覆盖。

workflow.probe 会对已有同 RH ID/地域配置列出节点增删与变化字段，素材节点 targets 标明真实远端输入，不能按节点编号猜图序。workflow.configure / workflow.update 支持 dryRun:true 只预览；workflow.update 的 mergeNodes:true 只刷新已选节点的连线、类型和标题，保留人工命名、枚举、范围、默认值和节点选择。

必填主提示词必须通过本次 prompt 或 params 提供；确认使用模板提示词才传 useDefaults:true。辅助提示词片段、其它参数默认值和素材可选规则保持原语义。

默认提交后立即 task.wait 取结果；只有 background: true 或同步等待超时才创建后台通知，已取回的附件不要重复取回。工具单次等待上限25分钟，批量共享总预算；停止等待不等于取消远端任务。费用只展示远端任务明确返回的 consumeCoins，不能用余额变化推算。

重启恢复会先查询一次远端状态，以取回离线期间完成的结果，但不会重置原有跟踪超时预算。停止提交不会再创建后台通知；部分提交失败时，仅显式后台模式为已经提交的任务安排通知。

workflow.validate 默认用表格只展示变化字段，长文本显示摘要，警告直接显示在正文；details:true 才展开完整提交字段。启发式范围只警告，用户或工作流声明的约束才拦截。远端表达式、帧数和时长量化无法在本地执行，最终输出以实际测量为准。配置保存会提示文档不存在、提示词目标不匹配及用户枚举来源待确认的问题。

结果携带已知的 width、height、duration、fps、hasAudio 和 bytes，可测时还带 audio:{codec,sampleRate,channels}。有音轨或音频规格不能证明内容是音乐。PNG/GIF/JPEG 可从文件头读取尺寸；其它媒体可使用系统 PATH 中的可选 ffprobe，仅探测已保存的本地文件，每次最多 2 秒。没有安装或探测失败时仍保留文件、附件和已知字段，其余字段保持未知；探测耗时不挤占其它结果的下载预算。任务费用和本地已记录的近期消耗来自 consumeCoins，钱包余额可能包含邀请奖励等外部入账。

task.limit 只限制详细记录（默认 10，用户已设的上限保持不变）。清理前保存轻量费用、时间和文件路径历史，不保留提示词、请求节点、Key 或附件载荷；历史保存失败时保留原明细。task.list 默认最近 24 小时，sinceHours:0 查询全部成功历史，优先显示本地路径以省去重复链接。task.status 可查询已归档回执；已清理明细不能用于重试下载，旧版本已经删除的记录无法恢复。

常用 Action 清单

Key 策略与安全保障

• 优先级与轮换：优先使用优先级数值较小的 Key；相同优先级下，优先使用较久未使用的 Key。
• 自动熔断与换号：
  • 认证失败：标记该 Key 失效，自动切换同地域下一把 Key。修正配置后，可在面板点「重新验证」，通过后恢复使用。
  • 余额不足：标记为「余额不足」，切换同地域下一把 Key。余额不会随时间自动恢复，所以插件不会定时放行：提交前会对这类 Key 复查余额（每把至多每分钟一次），有余额才恢复；面板 Key 列表显示最近一次查到的余额和查询时间。只有余额查询本身失败、或回执里没有余额字段时，才退回为 10 分钟后自动放行。
  • 并发已满 / 机器不足（1520 / 421 / 415）：不是 Key 的问题，不冷却 Key。有多把 Key 时先换下一把尝试；都满了就在本地排队（状态 LOCAL_QUEUED），按 30s → 60s → 120s 退避重投，本地有任务结束时提前唤醒；排队超过 maxWaitMs 记为 CAPACITY_TIMEOUT。排队期间可以取消，不扣费。
  • 地域隔离：某个地域的池为空时直接报错，绝不挪用另一地域的 Key。
• 资金防重复扣费： 提交过程中若遭遇网络断开、超时或服务端 5xx 异常，任务将记录为 UNCERTAIN，插件绝不自动重试，防止重复扣费。确认云端状态后，用 task.adopt 接回已创建的任务，或用 task.dismiss 结案再重跑。

插件配置与本地数据

可在 DSH 配置文件中指定以下参数：

数据目录结构

secrets.json          API Key 明文与池状态（不保留明文备份）
state.json            非机密运行时状态（冷却时间、用量快照）
workflows/*.json      已配置的工作流参数
prompts/*.md          提示词规范文档
tasks/*.json          任务流水与本地结果映射
task-history/*.json   明细清理后保留的费用、时间、文件回执
outputs/<taskId>/     取不到会话工作目录时的兜底保存目录

[!IMPORTANT] API Key 明文存放在本机的 secrets.json 中。请在面板添加，不要发到聊天里。工具回执、面板列表和日志会脱敏，但这不能清除已经发送的聊天记录。在分享插件数据目录前，请移除 secrets.json。Unix 系统使用 0600 文件权限；Windows 的访问范围由目录和文件的 ACL 决定，chmod(0600) 不提供同等隔离。

本地素材只接受可识别的图片、视频和音频文件，单个文件上限 128 MiB；插件机密和内部配置文件不能作为素材上传。结果先以流的方式写入临时文件，下载完成后再保存，单个文件下载上限 512 MiB。上传、下载和附件读取共用两个并发槽；超过 64 MiB 的结果只保留本地文件和下载链接，不会自动作为聊天附件发送。

结果下载会拒绝本机和非公开网络地址，并逐次检查重定向。为兼容 TUN 代理的 fake-IP DNS，只有主机名精确匹配 RunningHub 官方结果域名（rh-images.xiaoyaoyou.com、rh-images-tos.xiaoyaoyou.com、rh-images-1252422369.cos.ap-beijing.myqcloud.com，以及 fakeIpHosts 中追加的域名）且使用 HTTPS 默认端口时，才允许解析到 fake-IP 网段（默认 198.18.0.0/15，可用 fakeIpRanges 修改）内的地址。本机、链路本地（含云元数据地址）、私网（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）和组播网段不能被配置为 fake-IP 网段；其他内网地址一律拒绝。下载被拒时，错误信息会写明主机名、解析到的地址以及需要修改哪项设置。面板的 HTTP 通道使用宿主的连接鉴权。

常见问题排查

开发与测试

本地开发要求 Node.js ≥ 20（推荐 Node.js 24），无需 npm install（零运行时依赖、零构建步骤）。

# 完整发布验收（含敏感凭据扫描、离线沙箱装载自检与 500+ 项全量串行测试）
node tools/accept.mjs --json

# 仅运行单元与集成测试
npm test

# 快速入口自检
npm run loadcheck

测试均基于本地模拟接口与临时目录，不会发起真实网络请求，不会扣费。

每个 PR 和推送到 main 的提交都会由 GitHub Actions 在 Ubuntu / Windows × Node 20 / 22 上运行 npm test、npm run loadcheck 与 npm run check:release（见 .github/workflows/ci.yml）。错误码、接口字段等外部依据以 RunningHub 官方 API 文档 为准；源码注释直接写结论，或附上官方页面链接。

开源协议

MIT License