前言¶
在 DeepSeek Harness（DSH）里做 agent，常见做法是直接调云端生图、生视频 API：Key 和计费绑在对话侧，产物路径也要自己管。若你本机已经在跑 GenBox（FastAPI 媒体工作台），provider、尺寸、风格都在浏览器里配好，更自然的诉求是让 agent 走同一套服务，并把图片、视频落到工作目录后把路径交回模型。
下面介绍社区插件 dsh-genbox-plugin（维护者 liwei9745），它在 SkillHub 分类为「工作流」，通过 HTTP 调用本机 GenBox，不修改 GenBox 本体；GenBox 为 GPL-3.0，插件为 MIT，仅作调用方。
这是什么¶
dsh-genbox-plugin 是 DSH 的 Cordis bundle 插件：DSH agent → 插件（TypeScript）→ GenBox FastAPI（默认 127.0.0.1:8892）→ 各 provider。插件负责注册工具、轮询任务、下载媒体到本地；API Key 与模型选择仍在 GenBox 工作台界面管理。
形态可以概括为：
DSH agent → dsh-genbox-plugin (TypeScript) ──HTTP──▶ GenBox FastAPI (127.0.0.1:8892) ──▶ providers
核心功能¶
README 中为 agent 注册了 15 个工具，覆盖自检、生图、改图、视频与本地剪辑、图库等能力。
| 类别 | 工具 | 作用（摘要） |
|---|---|---|
| 服务与诊断 | genbox_server |
启动 / 停止 / 重启 / 查看本机 GenBox |
genbox_doctor |
可达性、认证、provider/Key、输出目录、ffmpeg 等自检 | |
genbox_open_workbench |
打开 GenBox 工作台（首装常用） | |
genbox_health |
探测 GenBox 是否在线 | |
genbox_providers |
列出 provider、模型与能力 | |
| 图像 | genbox_image_generate |
文生图 |
genbox_image_edit |
i2i、inpaint、精准改图（批注）等 | |
genbox_image_upscale |
本地超分（无需 API Key） | |
genbox_image_variations |
变体 | |
genbox_cutout |
抠图（需 GenBox 侧 checkpoint） | |
| 视频 | genbox_video_generate |
文生视频 / 图生视频 / 关键帧等 |
genbox_task |
查询或取消后台任务（支持 background: true） |
|
genbox_video_edit |
本地 ffmpeg 剪辑（trim、concat、字幕等，无需 GenBox Key） | |
| 其它 | genbox_gallery |
媒体库检索并复制到本地 |
genbox_prompt_optimize |
提示词优化 |
生成结果默认写入配置项 outputDir（默认 .genbox），返回绝对路径；模型可用 DSH 内置的 read_image 查看图片。
从 DSH 0.2.0 起，插件还提供原生侧边栏面板：在 DSH NEXT 中 Ctrl+Shift+G 或右侧边栏 GenBox 卡片可嵌入 GenBox Web UI（桌面端通过 webview 租约加载，因 GenBox 禁止 iframe）。
仓库提供免模型凭据的证据看板（node scripts/lab.mjs，默认 http://127.0.0.1:3098/），可查看连接状态、工具清单与复现命令；验证套件默认使用零成本 mock provider，真实 provider 需显式设置 GENBOX_REAL_PROVIDER。
安装与启用¶
前提：GenBox 已在本机运行。GenBox 本体默认端口 8891，插件 dev 文档常用 8892；插件通过 baseUrl 与 baseUrlFallbacks 依次探测并记住可用地址。
从 npm 安装（README 已发布流程）：
dsh plugin --profile <profile> add dsh-genbox-plugin
dsh --profile <profile> --dump-config | Select-String genbox # 确认插件层已生效
从 tarball（示例版本 0.1.0）：
corepack pnpm pack # 产出 dsh-genbox-plugin-0.1.0.tgz
dsh plugin --profile <profile> add ./dsh-genbox-plugin-0.1.0.tgz
因 package.json 声明了 dsh.bundle，安装后会写入 profile 的 bundles；启动时应看到类似：
[genbox] plugin loaded (baseUrl=http://127.0.0.1:8892)
装进 desktop profile 后需重启 DSH NEXT。建议先用独立 profile 验证，例如：
dsh --profile genbox-dev --from-default-profile web
本地源码联调可使用 overlay patch（路径按你本机仓库位置替换）：
dsh --profile <profile> --patch E:/AI/GenBox-dsh/dev/overlay.cordis.yml
package.json 要求 Node >=20、DSH >=0.1.5-rc.1；当前包版本为 0.2.1（npm 包名 dsh-genbox-plugin）。
常用配置字段：
| 字段 | 默认 | 说明 |
|---|---|---|
baseUrl |
http://127.0.0.1:8892 |
GenBox 服务地址 |
adminKey |
空 | prod 模式 X-Admin-Key（dev 不需要） |
defaultProviderId |
空 | 未指定 provider 时的默认值 |
outputDir |
.genbox |
媒体落盘目录 |
pollIntervalMs |
2000 | 轮询间隔 |
taskTimeoutMs |
900000 | 单任务超时 |
ffmpegPath / ffprobePath |
ffmpeg / ffprobe |
本地视频编辑与探测 |
典型用法¶
README 给出的「30 秒上手」可按下面三步走（也可直接让 agent 执行对应工具）：
- 打开工作台：对 agent 说「打开 GenBox 工作台」（
genbox_open_workbench），或浏览器访问http://127.0.0.1:8892/配置 provider 与 Key。 - 自检：「跑一下 GenBox 自检」（
genbox_doctor），按返回清单补全环境。 - 开始用：例如「用 GenBox 画一只在雪地里的柴犬」。
GenBox 未启动时，插件会明确提示无应答，并指向文档中的本地启动说明。
三个端口不要混淆：
| 端口 | 用途 |
|---|---|
| 3098 | 插件证据看板（只读，无需凭据） |
| 3099 | DSH 会话页（需模型凭据） |
| 8892 | GenBox 工作台（画图、图库、配 provider） |
工具参数速查见仓库 docs/tools.md（由代码自动生成）；安装与排错见 docs/install.md。
适用场景与注意¶
适合谁： 已在或计划在本机跑 GenBox，希望 DSH agent 统一调用生图、改图、生视频、本地 ffmpeg 剪辑与图库，而不是在 agent 里重复封装各云 API 的同学。
权限与安全： 插件随当前 DSH 进程权限运行，可启停本机 GenBox 进程、读写 outputDir、调用 ffmpeg。安装前请阅读 GitHub 仓库 源码与 MIT 许可证；第三方 provider 的 Key 仍在 GenBox 界面配置，插件经 HTTP 转发请求。
生态说明： DSH 社区插件目录托管在 SkillHub 等独立站点，与 DeepSeek / 幻方无官方从属关系；选插件时以仓库文档与自测为准。
链接¶
- 目录页：https://www.skillhub.cn/plugins/liwei9745/dsh-genbox-plugin
- 源码与 README：https://github.com/liwei9745/dsh-genbox-plugin
若你本地已有 GenBox，按上文安装 bundle 并完成自检后，即可在对话里把媒体生成纳入 agent 工作流，产物路径可直接交给后续步骤使用。
