Workflow & Automation

dsh-runninghub-plugin

achenjins/dsh-runninghub-plugin · ★ 6

achenjins

一个dsh插件,用于让ai在dsh内调用runninghub在线工作流

README body is shown in Chinese.

License
MIT
Added
2026-10-28
Maintenance
active
Install kind
npm
npm
dsh-runninghub-plugin
Manifest details
Manifest status
Declared
Manifest path
package.json#dsh
Manifest checked
2026-10-30T09:38:17.597Z
Lifecycle scripts
None found

Static manifest checks report declarations only; they are not compatibility or security review.

安装

dsh plugin --profile web add 'dsh-runninghub-plugin@0.3.3'

从 npm 安装预构建包

For install and environment setup, plus plugin development tutorials, see DSH community docs ↗

README

Source README · body: zh · Read Chinese README

Table of contents
  1. 安装
  2. 主要功能
  3. 快速上手
  4. 1. 获取并添加 Key
  5. 2. 让 AI 配置工作流
  6. 3. 开始生图
  7. 配置面板与节点配置详解
  8. 1. 工作流基本信息区
  9. 2. 节点表格与自动分组(8 列清晰呈现)
  10. 3. 节点内联编辑功能
  11. 4. 提示词优化联动配置
  12. 5. 草稿保护与确认机制
  13. 面板其他模块
  14. 模型工具调用参考
  15. 1. 查询动作并选择工作流
  16. 2. 提交生成任务
  17. 3. 查询进度与取回结果
  18. 4. 补取文件或附件(无需重复生成)
  19. 5. 传入参考图与自定义参数
  20. 6. 处理「待核对」任务
  21. 配置与等待的边界
  22. 常用 Action 清单
  23. Key 策略与安全保障
  24. 插件配置与本地数据
  25. 数据目录结构
  26. 常见问题排查
  27. 开发与测试
  28. 开源协议

访问次数

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

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

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

💎 通过上述邀请链接注册,可获得 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:
  • 在 DSH 配置面板的「Key 池管理」中添加 API Key(地域可选国内、海外或自动探测)。

2. 让 AI 配置工作流

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

[!TIP] 推荐体验工作流:可以试试我发布的 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 项核心属性:

列名 说明
节点 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 / 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 清单

分类 动作 说明
工作流 workflow.get / probe / configure / update / rename / clone / delete / validate / price get 不传 name 时列出简介,可用 query 筛选;传 name 才返回完整节点配置。其余动作用于探测、保存、更新、重命名、克隆、删除(需带 confirm: true)、预检和查询预计费用
任务 workflow.run / task.status / task.wait / task.retry / task.cancel / task.list / task.limit / task.adopt / task.dismiss 提交任务、查询进度、取回结果、补取文件、取消任务(含撤销本地排队)、查询最近 24 小时的结果链接、设置记录保留条数、接回或结案待核对任务
Key 与账户 account.keys / account.balance / account.queue / key.detect / key.balance 查看 Key 池、查询余额、查看并发与排队、验证地域、查询单把 Key 的余额;添加、修改和删除 Key 请在面板操作
提示词 prompt.doc_list / prompt.doc_read / prompt.doc_write / prompt.optimize 列出与读取规范文档、编写文档、调用优化润色
诊断 diagnostics 检查核心装配状态、数据目录及宿主通信通道

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 配置文件中指定以下参数:

字段 默认值 说明
dataDir <DSH_HOME>/runninghub 数据存储根目录(未设置 DSH_HOME 时为 ~/.dsh/runninghub)
outputDir 空 默认生成文件保存目录;单次调用时的 saveDir 优先
httpTimeoutMs 60000 HTTP 超时时间(毫秒);提交任务至少等待 60 秒
pollIntervalMs 3000 轮询起始间隔(毫秒);之后逐步拉长,最长 15 秒(配置值超过 15 秒时以配置值为准)
maxWaitMs 1800000 单个任务最长等待时间(毫秒,默认 30 分钟),本地排队也以此为上限
maxTasks 10 保留最近已结束的任务明细条数,0 表示不限制;面板设置优先,清理后仍保留轻量历史。待恢复与待核对任务另有独立上限:max(20, 2 × maxTasks)
registerSkill true 是否注册插件自带的两个 Skill(生成操作手册、工作流配置流程)
exposeClientPanel true 是否开启前端配置面板通道
fakeIpHosts [] TUN / fake-IP 代理兼容:追加允许解析到 fake-IP 的结果域名(精确主机名,不支持通配)
fakeIpRanges [] 代理的 fake-IP 网段(IPv4 CIDR);留空即默认的 198.18.0.0/15,若在代理中改过 fake-ip-range,这里填相同的值

数据目录结构

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 通道使用宿主的连接鉴权。


常见问题排查

确认已重启 DSH 并刷新了客户端页面;检查是否在多个 profile 中重复安装了插件。

在聊天中调用 runninghub_call({ action: "diagnostics" }) 查看自检信息。面板优先走宿主 Remote 通道,若宿主未导出该协议,会自动退回本地 HTTP 路由。

检查对应地域池中是否有启用的 Key。状态为「余额不足」的 Key 充值后在面板点「查余额」即可恢复(下次提交前插件也会自动复查);「冷却」只来自短时限流或网络异常,会自动到期。

说明账号并发已满或平台独占机器不足,任务还没有提交到 RunningHub,也没有扣费。插件会自动重投;可以在面板取消排队,或调用 account.queue 查看并发占用。

调用 task.status 重新查询。若只是本地等待超时,重新查询即可恢复后台跟踪或取回已完成的结果,无需重复提交。

可能是网络波动。直接在面板对应任务卡片上点击「补下载 / 补附件」,或调用 task.retry;已保存成功的文件不会重复下载,也不会重新运行工作流、重复扣费。

可能是 RunningHub 的「隐写载图」格式(视频或音频藏在 PNG 中)。插件会完整保留原文件并给出提示。


开发与测试

本地开发要求 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