DSH RunningHub 插件

在 DSH 中调用 RunningHub 工作流，生成图片、视频、音频或其它文件。可以让 AI 帮你配置工作流，也可以在插件面板中管理 Key、节点参数和提示词文档。

需要 DSH 桌面版、RunningHub API Key，以及可通过 API 调用的工作流。国内和海外平台的 Key 分开使用，运行费用由 RunningHub 收取。

安装

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 --dry-run
node tools/install.mjs

脚本会备份修改前的 profile 文件。使用 node tools/install.mjs --uninstall 撤销安装。也可以将仓库以 link: 依赖加入 profile，并将包名加入 dsh.profile.bundles；随后在 profile 目录运行 pnpm install。

不要同时使用 bundle 安装和手工添加 cordis.patch.yml 的方式，否则会重复注册工具。

第一次使用

在插件面板添加 API Key。地域可以选国内、海外，或让插件自动探测。
把 RunningHub 工作流链接发给 AI，例如：「帮我配置这个工作流：……」。
AI 会读取工作流，与你确认提示词、参考素材和可调参数，然后保存配置。
配置完成后，可以说：「用这个工作流画一只在竹林里的熊猫」。

工作流里的节点角色由插件推断，保存前需要确认。参考素材可以使用本地文件路径，也可以使用已上传到 RunningHub 的文件名。

任务提交后会返回任务 ID。宿主提供后台作业服务时，可以查看进度并收到完成通知；调用 task.wait 可以取回结果，图片以附件显示在聊天中。

配置面板

面板中可以管理 Key、编辑工作流节点、上传提示词文档，以及查看或取消任务。工作流列表默认折叠，点击名称展开。

节点的角色、默认值、必填项、数值范围和候选值均可编辑。插件推断的常见数值范围用于提示；手动设置的范围会参与运行前校验。

工具调用

插件向模型提供两个工具：runninghub_search 用于发现，runninghub_call 用于执行。

查看已配置的工作流：

runninghub_search({ kind: "workflow" })

提交任务：

runninghub_call({
  action: "workflow.run",
  name: "我的文生图",
  prompt: "一只在竹林里吃竹子的熊猫",
  background: true
})

查询和取回结果：

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

传入参考图或覆盖参数：

runninghub_call({
  action: "workflow.run",
  name: "我的图像编辑",
  prompt: "把背景换成星空",
  images: { "470": "E:/images/reference.png" },
  params: { "3:steps": 30 },
  saveDir: "生成结果",
  fileName: "星空"
})

images 中的键是素材节点 ID；params 推荐使用 节点 ID:字段名，避免同名字段匹配错节点。也支持按节点传入多个字段，例如 { "3": { "seed": 123, "steps": 30 } }。

saveDir 可以是绝对路径，也可以相对于会话工作目录。省略时优先使用插件的 outputDir；没有设置时，保存到会话工作目录下的 runninghub-output。宿主没有提供工作目录时，使用插件数据目录下的 outputs/<taskId>。同名文件会自动加序号。

repeat 可以一次提交 1–20 个独立任务。waitMs 可以让提交调用额外等待一段时间；默认立即返回，background: true 时也立即返回。等待超时不会取消任务，可以稍后继续查询。

动作	用途
`workflow.get` / `probe` / `configure` / `update` / `delete` / `validate`	查看、配置和校验工作流；删除需传 `confirm: true`
`workflow.run`	提交一个或多个任务
`task.list` / `status` / `wait` / `cancel`	查询任务、取回结果或取消任务
`account.keys` / `balance` / `queue`	查看 Key 池、余额和队列
`key.add` / `update` / `remove` / `detect` / `balance`	管理 Key；单 Key 余额查询使用 `id`
`prompt.doc_read` / `doc_write` / `optimize`	管理提示词文档和优化提示词
`diagnostics`	查看装配状态、数据目录和面板通道

表中省略的动作前缀与每行第一个动作相同，例如 workflow.probe、task.wait。传入未知动作时，工具会返回完整清单。

Key 和提交失败

Key 按优先级选择，数值越小越先使用；同优先级下优先选择较久未使用的 Key。失效、禁用和冷却中的 Key 不参与新任务提交。

认证失败：标记 Key 失效，尝试同地域的下一把。
额度不足：冷却 10 分钟，尝试同地域的下一把。
限流：查询请求退避重试；提交被明确拒绝时尝试下一把 Key。
提交时断线、超时或收到服务端错误：记录为 UNCERTAIN，不自动重投。任务可能已创建，需要到 RunningHub 后台核对。

批量提交途中失败时，回执会保留已提交的任务 ID。不要直接重跑整批，以免重复生成和扣费。国内池没有可用 Key 时，不会使用海外 Key。

提示词文档

在面板的文档库中上传或编写规范，再在工作流的「提示词优化」中选择该文档。

普通模式下，主模型读取文档后改写提示词。开启子代理模式后，prompt.optimize 会调用宿主的子代理服务生成提示词；该子代理不使用工具。是否有子代理服务取决于 DSH 的配置。

插件配置和数据

以下字段可以放在插件的 config 中：

字段	默认值	说明
`dataDir`	`<DSH_HOME>/runninghub`	工作流、文档、任务和 Key 的存储目录
`outputDir`	空	默认结果目录；单次调用的 `saveDir` 优先
`httpTimeoutMs`	`60000`	HTTP 请求超时，单位毫秒；提交请求至少等待 60 秒
`pollIntervalMs`	`3000`	起始轮询间隔；退避在此基础上逐步变慢，最多 15 秒。配得比 15 秒大时以配置值为准（不会被压回去）
`maxWaitMs`	`1800000`	单次等待和后台任务跟踪的上限，单位毫秒
`maxTasks`	`10`	按完成时间保留最近 N 条已结束记录；`0` 不限制。运行中的任务永不删；待恢复（超时 / 无可用 Key）和提交结果待核对的记录另有独立上限（`max(20, 2N)`），留得比普通记录久但同样有界。可在面板修改，保存后重启仍生效
`registerSkill`	`true`	注册工作流配置引导
`exposeClientPanel`	`true`	启用配置面板通道
`baseUrls`	`{}`	覆盖国内、海外接口地址，通常只在测试或代理场景使用

没有设置 DSH_HOME 时，数据目录默认是用户主目录下的 .dsh/runninghub。

secrets.json          API Key 和 Key 池状态
state.json            非机密状态
workflows/*.json      工作流配置
prompts/*.md          提示词文档
prompts/*.meta.json   文档信息
tasks/*.json          任务记录，包括结果路径（默认保留最近完成的 10 条；活任务与待恢复/待核对记录另行保留，见 maxTasks）
outputs/<taskId>/     默认结果目录

API Key 明文存放在本机的 secrets.json 中，工具回执、面板和日志会脱敏。写入时会尝试设置仅当前用户可读写的权限；Windows 上的实际访问权限由文件系统 ACL 决定。

建议将数据目录放在仓库之外。分享数据目录前，要移除 secrets.json 及其副本；旧版状态文件也可能含 Key。写入成功后会清理旧的机密备份和临时文件，损坏文件副本会保留供恢复。

工作流和文档覆盖前保留最近五份备份，机密文件不生成常规备份。重启插件后会继续查询未结束的任务。

排查问题

面板没有出现：确认已重启 DSH 并刷新页面，且没有同时安装两份插件。
面板无法连接：调用 runninghub_call({ action: "diagnostics" })。面板优先使用宿主 Remote 通道；有 webServer 服务时也支持 HTTP 通道。
没有可用 Key：检查地域、启用状态、余额和冷却时间。
任务等待超时：使用 task.status 查询。若只是本地跟踪超时，查询可以恢复跟踪或取回已完成的结果，无需再次提交。
结果下载失败：任务记录中仍保留结果 URL 和失败原因，可以直接下载。再次 task.wait 会读取已有记录。
视频或音频返回 PNG：可能是 RunningHub 的隐写载图。插件保留原文件并给出提示；目前不负责提取其中的媒体。

开发与验证

插件运行要求 Node.js 20 或更新版本。下面的开发验收使用 Node.js 24，同时需要 Git 和 npm。

npm test
node tools/loadcheck.mjs
npm run check:release
node tools/accept.mjs --json

accept 会依次执行发布检查、离线装载和全部测试。发布检查扫描工作区、Git 暂存区、本地已有引用的历史，以及 npm 安装包清单；检查凭据、意外打包的数据文件和缺失入口。发现问题时只报告位置，不打印密钥。

离线装载和测试使用临时数据目录及本地模拟接口，不读取真实 profile，也不会调用真实 RunningHub 或扣费。通过离线测试说明本地逻辑和模拟链路正常，真实平台、宿主版本差异及设备行为仍需要单独验证。

更详细的接口和设计记录见 docs/DESIGN.md 与 docs/dsh/PLUGIN-API.md。

MIT License。

achenjins/dsh-runninghub-plugin