[dsh-plugin] dsh-genbox-plugin：让 agent 直接生图、改图、生视频（含本地 ffmpeg 剪辑）

[liwei9745]

把本地开源的 GenBox（FastAPI 媒体生成工作台，支持 GPT-Image / Gemini / Qwen / 火山等多家 provider）做成了 DSH 插件 dsh-genbox-plugin。装进任意 profile 之后，agent 会多出 13 个工具。

装法

dsh plugin --profile <profile> add dsh-genbox-plugin

0.1.0 已在 npm：https://www.npmjs.com/package/dsh-genbox-plugin

能干什么

• 生图：genbox_image_generate（多 provider 并排对比、一次多张、内置提示词增强）
• 改图：genbox_image_edit —— 图生图 / 局部重绘（inpaint）/ 精准改图（箭头、方框、椭圆、画笔批注，插件自己合成蒙版，不需要手工画 mask）
• 图片工具：genbox_image_upscale、genbox_image_variations、genbox_cutout
• 视频：genbox_video_generate（文生 / 图生 / 首尾关键帧）、genbox_video_edit（11 种本地 ffmpeg 操作：裁剪、拼接、变速、静音、缩放、裁切、音量、换音轨、烧字幕、转 GIF、抽帧）
• 其他：genbox_task、genbox_gallery（带过滤）、genbox_prompt_optimize、genbox_providers、genbox_doctor

设计取舍

• 纯 HTTP 客户端：GenBox 自己已经有完整的 REST 接口（117 条路由），插件不碰它的源码，两边可以独立升级。
• 产出写到配置目录，并把绝对路径返回给模型，模型可以直接用 read_image 看结果。
• 长任务：background: true + genbox_task 收取；另有实验性的 nativeJobs 把任务挂到 ctx.jobs（默认关闭，避免影响已验证行为）。
• 媒体工具实现了 presentCall / presentResult / output.presentationMeta，结果卡片从持久化的 meta 重建（回放安全），并把产出文件放进 locations。

可复现的验证（不是"跑通了"三个字）

仓库里带一个不需要任何 API Key 的端到端测试台（自己写的 OpenAI + 火山双协议 mock provider），所以任何人都能把整条链路跑一遍：

node scripts/verify-all.mjs
→ 10 个套件全绿：批注渲染、本地视频剪辑 11/11、doctor 自检、生图+生视频、
  后台任务、图库与提示词、图库过滤、原生 job registry、精准改图批注、UI 渲染契约

每个套件都有真实产物落盘（图片、MP4），CI 里也跑同一套。

欢迎拍砖

• 工具的参数设计与输出结构，有没有更适合程序化调用的做法？
• DSH 侧有没有比"一个能力一个工具"更好的组织方式（比如合并成少数几个带 op 参数的工具）？

仓库（MIT，已打 dsh-plugin topic）：https://github.com/liwei9745/dsh-genbox-plugin

[liwei9745]

发布后的更新（作者补充）：

• 已上 npm：dsh plugin --profile <profile> add dsh-genbox-plugin（当前 0.1.0，装的是预构建产物，不需要构建授权）。
• 新增首装引导：genbox_open_workbench 会报告/打开 GenBox 自己的工作台（没在运行时会明确说出来，不会假装成功）；genbox_doctor 现在会附一份 next-steps 清单（开工作台 → 说一句具体需求 → 用 genbox_gallery 收结果）。
• 失败信息可执行：连不上 GenBox 时不再只抛 fetch failed，而是告诉你「GenBox is not answering at …，先启动它」，并指向上面两个工具。
• 验证：套件数 11 → 12（新增报错信息与首装引导的断言），GitHub Actions CI 全绿；另外在真实 profile 里用从 npm 安装的那份产物（不是本地源码）跑通了一次完整生图，genbox_doctor 全 ok。

仓库：https://github.com/liwei9745/dsh-genbox-plugin

[liwei9745]

0.1.1 已发布 —— dsh plugin --profile <profile> add dsh-genbox-plugin（或市场里点「更新」）。

• 新增 genbox_open_workbench（第 14 个工具）：装完插件后的第一步，报告/打开 GenBox 自己的工作台；GenBox 没在跑时会明确说「没有应答」，不会假装成功。
• genbox_doctor 现在附一份 next-steps 清单（开工作台 → 说一句具体需求 → 用 genbox_gallery 收结果）。
• 连不上 GenBox 的报错从裸 fetch failed 改成可执行的一句话，并指向上面两个工具；取消（abort）语义保持不变。
• 验证：套件 12 → 14（新增「插件市场就绪性」用市场自己的模块判定 host 兼容，以及「已安装包与仓库构建的工具集一致」）；CI 全绿；并已确认从 npm 安装的 0.1.1 恰好注册 14 个工具、与仓库构建逐一对齐。

仓库：https://github.com/liwei9745/dsh-genbox-plugin

[liwei9745]

真实 provider 端到端联调完成（本机 gpt-image / gpt-image-2-vip）：

• 文生图：a red paper lantern floating over a misty lake at dusk, photographic → 972 KB PNG，1024×1024，约 54 秒
• 图生图：repaint it as a snowy morning → 1.38 MB PNG（不覆盖原图）
• 校验：产物是真实 PNG 容器、能被独立解析、两次产出路径不同；这条检查做成脚本，默认 SKIP，只有显式给 GENBOX_REAL_PROVIDER 才会花钱跑：node scripts/verify-real-provider.mjs

顺手在真实 provider 上又抓到一个坑并修掉：mask inpaint 的 provider 不只是要声明 capabilities.inpaint_mask，还必须 endpoint_type=openai。我们的 gpt-image 是 auto，声明了 mask 一样被 GenBox 拒绝（inpaint_provider_unsupported）。现在插件被拒时只列出真正满足全部条件的 provider，不再给一份看起来能用、其实不能用的清单；genbox_providers 也新增了 endpointType 字段，模型动手前就能看出传输方式不匹配。

验证套件现在 21 个（20 跑 + 1 个 opt-in 真实 provider），其中一条是覆盖整条产品链路的「用户旅程」：自检 → 生图 → 图生图 → 精准改图 → 后台生视频 → 收取 → 取消 → 本地 ffmpeg 剪辑 → 图库，共 17 项断言。

仓库：https://github.com/liwei9745/dsh-genbox-plugin

[liwei9745]

局部重绘 / 超分 / 变体 —— 三个能力都实测打通了（附踩坑根因）

这轮把之前三个「看起来不可用」的能力逐个查到底，结论是都不需要改 GenBox 源码，最短路径是「一个配置字段 + 插件侧归一化」：

1. 局部重绘（inpaint）—— 一个字段的事

GenBox 对 inpaint 的校验是声明式静态门禁（main.py:1504-1510）：要求 endpoint_type == 'openai'。我的 provider 是 auto，
即使它运行时本来就解析成 openai 协议（生成状态里 request_contract.protocol=openai 可证），门禁也不认。改成 openai 后实测：

status: completed | 62.6s | 1024x1024 | 1,168,239 B
白框内的纸灯笼 → 热气球，湖面 / 远山 / 天空保持不变

插件同时改进了报错：会点名「哪个 provider 声明了 inpaint_mask 但不是 openai 传输」，并直接给出要改的字段。

2. 超分（生成后放大）—— GenBox 的 int() 陷阱

upscale_to 是用 int(target_size) 解析的，所以传 "1024x1024" 会抛异常，然后静默保留原图（不报错！）：

upscale_to=1024x1024 → ⚠ 放大失败(保留原图): invalid literal for int() with base 10: '1024x1024'
upscale_to=1024      → ✔ 放大完成

插件现在把 WxH 归一化成长边整数再发送，upscaleTo: "1024x1024" 真的产出 1024×1024。

3. 变体（variations）—— 网关不实现遗留协议

GenBox 的 native 路径代理 OpenAI 的遗留 /images/variations（DALL·E-2 时代的多部分协议），我的网关直接回
400 Model name not specified，而 gpt-image 系列本身也没有 variants API。插件新增 strategy：
native / prompt（用同一底图走 mode=i2i + quantities 生成 N 个候选，任何能改图的 provider 都能用）/
auto（先试 native，失败自动降级）。实测 auto 在真实 provider 上自动降级到 prompt 并产出图片（120.4s）。

给做同类插件的两条通用经验：① 上游说「能力不支持」时先读它的校验代码——很多是声明式门禁，不是真实能力缺失；
② 上游的静默降级（放大失败保留原图）比直接报错更危险，插件应把参数归一化成上游真正接受的形状，而不是照搬文档字面。

仓库与文档：https://github.com/liwei9745/dsh-genbox-plugin

[liwei9745]

前端可用性：把「看起来能拖」变成「真的能拖」（附审计结论）

接着上一条，这轮把「可达性」做成了自动化断言。方法很朴素但很有效：先做 document.elementFromPoint() 命中测试，
再发真实指针序列——合成 dispatchEvent 会绕过命中测试，把「点不到」伪装成「能用」（我就被它骗过一轮）。

#	检查	结果
1	生图页纵向分隔条（1920×1080 / 1280×800）	✅ 真实指针拖拽，相邻面板互换空间、总和恒定
2	生图页左侧分隔条	✅ 左栏 +120 / 预览 −120
3	精准画布右下角抓点	✅ 可达（此前命中 div.status-bar）
4	精准画布底部竖条	✅ 只改高度（h +120、w 0）

修掉的三类问题：

1. 分隔条挂在滚动容器上被裁：bottom: -6px 的 12px 条，中心和 top:5px 的抓手标记都落在面板外，
   真实指针只有顶沿约 4px 能点到（elementFromPoint(中心) 返回 div#previewPanel）→ 移回面板内。
2. 画布钻到状态栏下面：尺寸上限按视口估算（viewportHeight - 120）→ 改为量「画布顶到状态栏顶」的真实空间（760 → 733）。
3. z-index 不是万能药：抓点的祖先带 backdrop-filter、自成层叠上下文，把子元素提到 z-index: 30 也无效。

顺带审计（未改动）：左侧分隔条健康；创作工具侧栏是点击折叠而非拖拽条；
provider 列宽手柄可用（真实拖拽卡片 454→534），但可点区域只有约 4/8px——卡片 overflow: hidden 裁掉一半。

这些检查都在 scripts/browser/measure-splitters.cjs 里，已接入 verify-all（缺 Playwright 时 SKIP，不影响 CI）。

[liwei9745]

上游修复 10 项已提 PR（含实测证据）；插件侧又修掉了「生成图片按钮被挤出屏幕」

1. GenBox 本体修复：PR #16（分支 fix/creator-splitters-and-narrow-layout，10 个提交），
   仓库要求走 PR + 必过检查，现已 mergeable_state=clean（Quality Gate 跑通）。涵盖：

   • 生成页纵向分隔条原来完全没反应（flex 打在孙节点上）→ 现在是真正的 Splitter（相邻面板互换空间，总和恒定）
   • 分隔条被 overflow: auto 裁到只剩约 4px 可点 → 移回面板内（bottom: 0）
   • 精准画布抓点纵向拖动被忽略（只读 dx）→ 按主导轴生效
   • 画布钻到状态栏下、抓点指针不可达 → 上限改为量「画布顶到状态栏顶」（760 → 733）
   • ≤800px 两栏溢出 118px → 该断点共享列高（839 → 534）
   • 另修一个基线就红的前端测试（vm 沙箱缺依赖，坏的是脚手架不是行为）

2. 插件侧（本轮新增）：生成页「生成图片」按钮实测在 1920×1080 下 bottom=1120、视口只有 1080 —— 掉出屏幕 40px，必须拖滚动条。
   已改为面板内吸底常驻（position: sticky; bottom: 0）→ 按钮 973..1017，永远可见。
   同时发现按钮 tooltip 一直写着「Enter 或 Ctrl+Enter 生成」，但代码只在精准改图模式生效——文生图/图生图根本没有快捷键；
   已补 Ctrl/Cmd+Enter（输入框内也生效，普通 Enter 仍换行）。

3. 方法上的一句话：这两个 bug 都是「合成 dispatchEvent 会绕过命中测试」骗过来的——
   现在浏览器断言一律先 elementFromPoint() 命中测试、再发真实指针序列，快捷键则用桩掉 doGenerate 的方式验证接线（不花真实额度）。
   6 项断言与覆盖矩阵见仓库 docs/browser-checks.md。

[liwei9745]

dsh-genbox-plugin@0.1.2 已发布到 npm（npm view dsh-genbox-plugin version → 0.1.2，latest 已指向它）

验证（node scripts/verify-published.mjs，发布后实跑）：

[ok] dsh-genbox-plugin exists on the registry -> 0.1.2
[ok] registry version matches package.json -> 0.1.2 vs 0.1.2
[ok] declares engines.dsh -> >=0.1.5-rc.1
[ok] dsh-plugin keyword present
[ok] dist.tarball advertised -> .../dsh-genbox-plugin-0.1.2.tgz
[ok] published tarball ships lib/index.js + cordis.patch.yml
published package verified

这一版攒了几个实测驱动的改进：

• 429 不再直接失败：GenBox 对 /api/generate 限流（默认 10 次/分钟/IP），提交类调用现在按 5s/10s/20s 退避重试；仍失败时把规则写进错误里
• 错误消息说人话：把上游的 detail/message 引出来，而不是丢一段 JSON
• 局部重绘：provider 声明了 inpaint_mask 但不是 openai 传输时，直接点名是哪个 provider、该改哪个字段（实测翻一个字段就跑通了真实局部重绘）
• 超分：upscaleTo 把 WxH 归一化成 GenBox 唯一接受的长边整数（此前传 1024x1024 会静默保留原图）
• 变体：新增 strategy=auto/native/prompt——native 走 OpenAI 遗留协议，网关不支持时自动降级为同底图 i2i 候选
• 多参考图：genbox_image_edit 支持 referenceImages（走 image_data_list）

更新方式：

• 非 desktop profile：dsh plugin --profile <名字> add dsh-genbox-plugin
• desktop profile：CLI 明确拒绝（实测 error: profile "desktop" is managed exclusively by the Electron application），请在插件市场点「更新」，然后重启 DSH NEXT——桌面端只在启动时读 profile。