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

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

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

主要功能

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

快速上手

只需要三步即可跑通：

1. 获取并添加 Key：

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

2. 让 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)

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

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

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

配置面板与节点配置详解

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

1. 工作流基本信息区

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

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

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

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 用于调度。

1. 发现已配置的工作流

runninghub_search({ kind: "workflow" })

2. 提交生成任务

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

3. 查询进度与取回结果

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

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

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

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

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

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

• 保存目录规则：缺省时优先使用配置的 outputDir；未配置时保存在会话工作目录下的 runninghub-output 中。
• 批量提交：支持传 repeat: 1~20 一次提交多条独立任务。

常用 Action 清单

Key 策略与安全保障

• 优先级与轮换：优先使用优先级数值较小的 Key；相同优先级下，优先使用较久未使用的 Key。
• 自动熔断与换号：
  • 认证失败：标记该 Key 失效，自动切换同地域下一把 Key。
  • 余额不足：自动冷却 10 分钟，切换同地域下一把 Key。
  • 物理隔离：国内池为空时直接报错，绝不挪用海外 Key。
• 资金防重复扣费： 提交过程中若遭遇网络断开、超时或服务端 5xx 异常，任务将记录为 UNCERTAIN，插件绝不自动重试，防止重复扣费。用户可在确认云端状态后再决定是否重投。

插件配置与本地数据

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

数据目录结构

secrets.json          API Key 明文与池状态（严格 0600 权限，禁止明文备份）
state.json            非机密运行时状态（冷却时间、用量快照）
workflows/*.json      已配置的工作流参数
prompts/*.md          提示词规范文档
tasks/*.json          任务流水与本地结果映射
outputs/<taskId>/     缺省保存目录

[!IMPORTANT] API Key 明文存放在本机的 secrets.json 中，工具回执、面板和日志输出均已自动脱敏掩码。在分享插件数据目录前，请务必移除 secrets.json 文件。

常见问题排查

开发与测试

本地开发要求 Node.js ≥ 20（推荐 Node.js 24）。

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

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

# 快速入口自检
npm run loadcheck

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

开源协议

MIT License