dsh-genbox-plugin

dsh plugin --profile web add dsh-genbox-plugin

dsh-genbox-plugin




把 GenBox（本地 FastAPI 媒体生成工作台）接入

DeepSeek Harness 的插件 bundle，让 DSH 里的 agent

能直接生图、改图、生视频、改视频（再生成式）并取回媒体库素材。

English: [README.en.md](./README.en.md)

插件驱动的是你本机的 GenBox 工作台：provider、API Key、尺寸、风格都在那个界面里管理；

插件只负责把这些能力交给 agent，并把生成的图片/视频落到本地目录后把路径交回给模型。

真图示例（全部由本插件跑出来，未做后期）

文生图 · 局部重绘（白框内替换，其余原样保留） · 变体（同底图重画）

 ·  · 

精准改图：左侧画布手绘批注，右侧实时预览（批注会被转成打码叠加图交给 GenBox）：

全部工具的参数速查见 [docs/tools.md](./docs/tools.md)（由代码自动生成，不会和实现漂移）；

与 GenBox 集成的实测踩坑清单（含根因与源码位置）见 [docs/genbox-pitfalls.md](./docs/genbox-pitfalls.md)；

前端可达性检查覆盖矩阵（为什么必须"先命中测试再发真实指针"）见 [docs/browser-checks.md](./docs/browser-checks.md)。

验证与证据（三条入口）

想看什么 · 去哪 · 一键复跑

现在到底通不通 · [docs/verification.md](./docs/verification.md)（内嵌一次真实运行的原始输出，22 个套件） · node scripts/verify-all.mjs

前端交互是否真的能点/能拖 · [docs/browser-checks.md](./docs/browser-checks.md)（可达性覆盖矩阵，6 项断言） · node scripts/browser/measure-splitters.cjs

接 GenBox 会踩哪些坑 · [docs/genbox-pitfalls.md](./docs/genbox-pitfalls.md)（10 条，含根因源码位置） · —

我们改过 GenBox 本体什么 · [ROADMAP.md](./ROADMAP.md) 的「上游修复台账」 · —

全部套件默认跑零成本 mock provider；真实 provider 联调是显式的 GENBOX_REAL_PROVIDER=...，绝不隐式花钱。

缺前置（GenBox / ffmpeg / Playwright / 已装 profile）时套件会 SKIP 并写明怎么补，不会假装通过。

调研结论与设计见 [PLAN.md](./PLAN.md)；内部结构与如何加工具见 [docs/architecture.md](./docs/architecture.md)；

安装、配置与排错见 [docs/install.md](./docs/install.md)；本机联调环境（含免 Key 的 mock provider）见

[docs/local-dev.md](./docs/local-dev.md)；发布流程见 [docs/releasing.md](./docs/releasing.md)。

30 秒上手

装完之后三步（也可以直接让 agent 替你做）：

1. 打开工作台：对 agent 说「打开 GenBox 工作台」（它会调 genbox_open_workbench），

或自己用浏览器打开 http://127.0.0.1:8892/ —— provider、API Key、设置都在这个界面里。

2. 自检：「跑一下 GenBox 自检」（genbox_doctor）—— 它会逐项告诉你还缺什么，并给出下一步清单。

3. 开始用：直接说「用 GenBox 画一只在雪地里的柴犬」。

GenBox 没在跑时，第 1 步会明确告诉你它没应答，并指向 [docs/local-dev.md](./docs/local-dev.md) 的启动命令。

形态

DSH agent → dsh-genbox-plugin (TypeScript) ──HTTP──▶ GenBox FastAPI (127.0.0.1:8892) ──▶ providers

不修改 GenBox 本体：它本身已有 117 条 REST 路由，本插件只是调用方，因此 GenBox 可以独立升级。

GenBox 是 GPL-3.0，本插件是 MIT——只通过 HTTP 调用，不含其源码。

证据看板（不需要模型凭据）

`sh

node scripts/lab.mjs # http://127.0.0.1:3098/

`

打开后可以看到：GenBox 连接状态与 provider、插件注册的工具清单（从构建产物里解析，不会撒谎）、

GenBox 图库素材、本地产物缩略图，以及每条复现命令。

三个端口别搞混：

端口 · 是什么

3098 · 证据看板（本插件自带，只读，无需凭据）

3099 · DSH 会话页（agent 聊天；需要模型凭据）

8892 · GenBox 自己的工作台（画图、看图库、配 provider）

状态

里程碑 · 内容 · 状态

M0 · GenBox 本地跑起来 · ✅ Python 3.11 venv + dev 模式 127.0.0.1:8892，v2.6.12

M1 · 插件骨架 + genbox_health · ✅ 构建、注册、调用通过；已作为 bundle 装进 profile 并启动

M2 · genbox_image_generate 文生图 · ✅ 端到端实测（mock provider）

M3 · 改图 / 超分 / 变体 / 抠图 · ✅ i2i、inpaint、超分、变体端到端实测；抠图缺 checkpoint 时报 cutout_model_missing

M4 · genbox_video_generate 视频 · ✅ 端到端实测（mock volcengine provider，下载到本地 mp4）

M5 · genbox_gallery / 提示词优化 · ✅ 图库列出并复制；无 LLM provider 时返回原文回退

M6 · 打包与分发 · ✅ pnpm pack → dsh plugin add <tarball> → 启动打印 [genbox] plugin loaded

M7 · 发布到 npm · ✅ dsh-genbox-plugin@0.1.0，并已用从 npm 安装的那份产物实跑生图

M8 · 插件市场就绪性 · ✅ 用市场自己的模块验证：dsh.bundle.patch 就位、host 兼容（0.2.0-rc.2 → compatible）、profile 预检 0 risks

M9 · 真实 provider 端到端 · ✅ 用本机 gpt-image（model gpt-image-2-vip）实跑：真文生图 844KB PNG 1024×1024（50s）+ 真 i2i 改图 1.25MB；6 项断言全过

M10 · 验收旅程 · ✅ verify-journey.mjs 17 项断言：自检 → 生图 → 图生图 → 精准改图 → 后台生视频 → 收取 → 取消 → 本地剪辑 → 图库

安装

三种方式任选其一，都要求 GenBox 已在本机运行（默认 http://127.0.0.1:8892）。

1. 从 tarball（已实测）

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，dsh plugin 会自动把 dsh-genbox-plugin 追加进

dsh.profile.bundles。启动时会打印：

[genbox] plugin loaded (baseUrl=http://127.0.0.1:8892)

2. 从本地源码（开发用）

dsh --profile <profile> --patch E:/AI/GenBox-dsh/dev/overlay.cordis.yml

3. 从 npm 安装（已发布）

# 0.1.0 已在 npm 上，装的是预构建产物，不需要任何构建授权
dsh plugin --profile <profile> add dsh-genbox-plugin

dsh --profile <profile> --dump-config | Select-String genbox   # 确认插件层已生效

装进 desktop profile 后需要重启 DSH NEXT 才生效。建议先用独立 profile

（dsh --profile genbox-dev --from-default-profile web）验证。

在 DSH NEXT 里直接用 GenBox（不跳浏览器）

从 0.2.0 起，插件带一个原生侧边栏面板：GenBox 自己的 Web UI 直接嵌在 DSH NEXT 右侧边栏里。

• 打开：Ctrl+Shift+G，或右侧边栏「新标签页」里的 GenBox 卡片；
• 面板自带地址栏（默认 http://127.0.0.1:8892/，可改成 8891 或别的端口，会记住）、刷新、在系统浏览器中打开；
• 为什么不是 iframe：GenBox 的 HTML 发 X-Frame-Options: DENY 和 frame-ancestors 'none'，

浏览器一定拒绝。桌面端因此走 DSH 官方的 webview 租约

（dshDesktop.browser.acquire(workspace) → about:blank#<lease> + partition → loadURL），

与内置浏览器同一套主进程审批 / 隔离策略；纯浏览器环境下没有该通道，面板会明确提示改用系统浏览器。

工具

工具 · 作用

genbox_server · 启停服务：在对话里启动 / 停止 / 重启 / 查看本机 GenBox（action=status\ · start\ · stop\ · restart）。自动找安装目录，启动后等到真的应答；停止只杀命令行确实是 GenBox main.py 的进程

genbox_doctor · 自检：可达性、认证模式、provider/Key 就绪、输出目录可写、ffmpeg 是否可用，并给出修复建议

genbox_open_workbench · 打印/打开 GenBox 工作台（首装后的第一步）

genbox_health · 探测 GenBox 是否在线

genbox_providers · 列出 provider / 模型 / 能力（调用前先查能力）

…(truncated)