前言¶
DSH 生態裏「一切皆插件」，出圖這類能力也由社區插件提供。但常見的 DSH 出圖插件走的是「OpenAI 兼容」路線，會把 seed、steps、negative_prompt、guidance_scale 這些擴散模型參數一起發給官方接口，結果第一張圖就報錯：
HTTP 400: Unknown parameter: 'seed'.
本文介紹的插件只發 OpenAI Images API 文檔裏存在的字段，並在輸出 schema 裏避免了 null 對象字段。它由 yangshulin2333 維護，是在社區目錄 SkillHub 上收錄的一個模型推理類插件，定位很窄：把 GPT-Image-2.6 的出圖、改圖和 Roblox 資源上傳三件事做準。
插件概況¶
插件名 yangshulin2333/dsh-openai-image，包名 @yangshulin2333/dsh-openai-image，託管在 GitHub，MIT 許可證，當前版本 0.4.6，要求 Node >= 20。對 DSH 的 peerDependencies 爲：
"@deepseek-ai/cordis": "^4.0.1",
"@deepseek-ai/dsh-tools": "^0.1.7-rc.2 || ^0.2.0-rc.1 || ^0.2.0-rc.2",
"@deepseek-ai/schemastery": "^0.1.0 || ^0.2.0"
它註冊三個工具，形成一條「出圖 → 改圖 → 上傳」的鏈路：
image_generate → 出圖（flare / sunburst，Roblox 預設）
image_edit → 改圖（多圖輸入 + 可選 mask）
roblox_upload → 傳到 Roblox，拿 rbxassetid://（默認關閉，需用戶確認）
底層直接打官方 /v1/images/generations 和 /v1/images/edits，沒有自己造的兼容層。
爲什麼不用現成的圖片插件¶
README 給出兩條理由，都來自實際調用的故障現象：
- 字段不對。舊插件發
seed、steps、negative_prompt、guidance_scale，OpenAI 官方 Images API 不認這些擴散模型參數，直接 400。本插件只發model/prompt/n/size/quality/output_format/background。 - 輸出 schema 有 null 對象字段。另一種常見故障是圖已經存好了，工具卻報
"value.router" must be an object。本插件保證輸出 schema 裏沒有null對象字段。
如果你原來裝的插件出現過這兩種報錯，可以在一個不心疼的會話裏換成這個插件驗證。
安裝¶
從 GitHub 安裝，裝完重啓 DSH，因爲 bundle 補丁在啓動時加載：
# 從 GitHub（推薦）
dsh plugin add github:yangshulin2333/dsh-openai-image
# 或者裝到某個 profile
dsh plugin --profile web add github:yangshulin2333/dsh-openai-image
也可以手動放進 profile 的依賴：
cd ~/.dsh/profiles/desktop
pnpm add @yangshulin2333/dsh-openai-image
配置¶
裝好之後在左側欄「插件」面板裏點開 @yangshulin2333/dsh-openai-image，頁面正文就是配置卡片。按 README 的步驟：
- OpenAI API 密鑰：粘貼
sk-...點「保存」，只寫進 DSH 憑據庫，不進配置文件。 - Roblox Open Cloud 密鑰：在 Roblox Creator Dashboard 建 key，勾
assets的 Read + Write；羣組密鑰要求你是羣組擁有者。 - 創作者類型 / 創作者 ID：發個人賬號填 user id，發羣組填 group id（純數字，例如
726492544）。 - 啓用 Roblox 上傳：默認關閉，打開後工具纔可用，而且每次上傳仍會在對話裏確認。
- 點「保存配置」即時生效，不需要重啓；卡片裏的「測試 OpenAI 連接」「測試 Roblox 連接」直接驗證 key 是否被接受。
適合團隊預置時跳過界面，直接寫進 profile 的 cordis.patch.yml：
- id: dsh-openai-image
name: "@yangshulin2333/dsh-openai-image"
config:
model: gpt-image-2.6-flare
robloxEnabled: true
robloxCreatorType: group
robloxCreatorId: "123456789"
字段與默認值：
| 字段 | 默認值 | 說明 |
|---|---|---|
| 啓用 | true |
總開關 |
| 憑證名稱 | OPENAI_API_KEY |
DSH 憑據庫或環境變量裏的名字 |
| API 地址 | https://api.openai.com/v1 |
走代理時改這裏 |
| 默認模型 | gpt-image-2.6-flare |
快；gpt-image-2.6-sunburst 畫質更好 |
| 默認尺寸 | 1024x1024 |
另支持 1536x1024、1024x1536 |
| 默認畫質 | auto |
low / medium / high |
| 輸出目錄 | generated-images |
相對當前會話工作目錄 |
| 提示詞後綴 | 空 | 追加到每個 prompt 末尾，適合項目統一風格 |
| 默認預設 | 空 | 見下方預設表 |
| 啓用 Roblox 上傳 | false |
打開後 roblox_upload 纔可用 |
| Roblox 憑證名稱 | ROBLOX_API_KEY |
帶 assets 權限的 Open Cloud API key |
| Roblox creator 類型 / id | user / 空 |
個人資產填 userId，組資產填 groupId |
| Roblox 資產類型 | Decal |
或 Image |
三個工具的用法¶
image_generate¶
參數與官方 API 對齊，另外加了幾項本地落盤和 GIF/SVG 相關的擴展：
| 參數 | 說明 |
|---|---|
prompt（必填） |
畫面描述 |
preset |
Roblox 預設名，自動補尺寸/格式/約束 |
model / size / aspect_ratio / quality / count / output_format / background |
與官方 API 一致（count 1-10，size 任意 寬x高，兩邊須被 16 整除、最長邊 ≤ 3840） |
frame_count |
GIF 幀數（2-16，默認 6），只在 output_format: gif 時生效 |
gif_fps |
生成後把 GIF 改成這個幀率（1-50）；接口原始是 5fps |
svg_model |
生成 SVG 的文本模型（默認 gpt-6.1-sol），只在 output_format: svg 時生效 |
moderation / output_compression / user |
安全過濾 auto|low、jpeg/webp 壓縮 0-100、調用方用戶標識 |
output_name / output_dir |
落盤位置 |
輸出格式分三類，選錯會走不通：
png/jpeg/webp是普通靜圖。gif是循環動圖。接口把動畫做成一張雪碧圖再切片，所以尺寸只能是256x256或512x512，幀數 2-16。svg是矢量圖，由文本模型寫代碼生成，size/quality不生效。想改線條就在提示詞裏描述。
image_edit¶
| 參數 | 說明 |
|---|---|
prompt（必填） |
要改什麼；做動畫時按「第 1 幀…第 2 幀…」描述分鏡 |
image（必填） |
源圖路徑，多張用逗號分隔（最多 16 張，內部用 image[] 數組語法提交） |
mask |
可選 PNG 蒙版（必須是帶 alpha 通道的 RGBA PNG），透明區域即重繪區域 |
output_format |
png / jpeg / webp / gif；gif 可以用一張現成圖生成動畫，svg 不支持（編輯接口不出矢量） |
frame_count / gif_fps |
同上，只在 gif 時生效 |
| 其餘 | 同 image_generate（preset 也可用） |
一個能直接用的場景是：已經出好了主體圖，用 image_edit 加 mask 只重繪指定區域，輸出同尺寸的新圖。
roblox_upload¶
| 參數 | 說明 |
|---|---|
image（必填） |
本地 png/jpg/bmp/tga |
confirm（可選） |
不傳時只返回計劃摘要（confirm_required）；用戶明確同意後再傳 true |
display_name / description |
資產名（≤50 字）/ 描述 |
asset_type / creator_type / creator_id |
覆蓋設置裏的默認值 |
調 roblox_upload({ image }) 會先拿到一份上傳計劃；確認後傳 confirm: true 才真正發。這個過程是插件刻意加的確認門檻，不是 bug。
Roblox 預設¶
七套預設都只是「提示詞約束 + 尺寸 + 格式」，不做任何後處理，結果裏會返回完整 prompt，方便複製出來手工復現：
| 預設 | 尺寸 | 用途 |
|---|---|---|
game_icon |
1024×1024 | 遊戲圖標，150px 下仍可辨認 |
thumbnail |
1536×1024 | 縮略圖 / 宣傳圖，主體靠右留標題位 |
gamepass |
1024×1024 | 通行證 / 商品圖標 |
badge |
1024×1024 | 成就徽章 |
decal |
1024×1024（透明） | 通用貼花 |
ui_9slice |
1024×1024 | 九宮格面板，附 sliceHint |
seamless_texture |
1024×1024 | 無縫平鋪材質 |
調用時 preset 填預設名即可，例如給遊戲做一張宣傳圖用 thumbnail。
Roblox 上傳與放進 place¶
上傳本身分三步走：
- 在 Creator Dashboard → Open Cloud → API Keys 建 key，權限勾 assets（讀 + 寫），並允許你的 IP。
- 把 key 存成 DSH 憑據
ROBLOX_API_KEY。 - 插件設置裏打開「啓用 Roblox 上傳」，填
robloxCreatorId（個人賬號在 users 資料頁裏的數字）。
上傳限制來自官方 Assets API：png/jpeg/bmp/tga、小於 8000×8000 px、≤ 20 MB、資產不可更新（改圖等於新資產，所以文件名帶時間戳）。上傳是異步的，插件輪詢 operation 直到 done，返回 assetId、rbxassetid://、moderationState，並把結果寫進圖片旁邊的 .json sidecar。
拿到 rbxassetid:// 之後，插件不碰 Studio，交給 Roblox Studio MCP：
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat # Windows 下的 stdio MCP server 命令
在 Studio 的 Assistant → ⋯ → Manage MCP Servers 裏勾選 Enable Studio as MCP server，然後在 DSH 裏掛一個 stdio MCP server。接着讓 agent 用 rbxassetid://<id> 建 ImageLabel / Decal，或用 Luau 的 Datatype.Content.fromAssetId(id)。
速度與成本¶
README 給出的實測（1024×1024，單張，含下載，2026-11，api.openai.com）：
| 模型 / 畫質 | 耗時 |
|---|---|
gpt-image-2.6-flare / low |
≈ 6.1 s |
gpt-image-2.6-flare / medium |
≈ 7.4 s |
gpt-image-2.6-sunburst / low |
≈ 16.7 s |
計價與 Images 2.5 持平：出圖 $30 / 1M image token，參考圖輸入 $8 / 1M，文本輸入 $5 / 1M。做圖標、貼花這類日常資產，flare + low 夠用；需要細節時再上 sunburst。
排錯¶
| 現象 | 原因 / 處理 |
|---|---|
HTTP 401: Missing bearer or basic authentication |
憑證名對不上：確認設置裏的憑證名稱就是憑據庫裏的名字 |
HTTP 400: Unknown parameter: 'seed' |
你裝的是走 custom provider 的舊插件；本插件不會發這些字段 |
HTTP 403 / Invalid scope |
Roblox key 沒有 assets 讀+寫權限，或 IP 白名單沒放行 |
robloxCreatorId is empty |
設置裏填 userId / groupId |
工具報 must be an object 但圖已生成 |
輸出 schema 裏出現了 null 對象字段，屬於 bug，開 issue |
| 傳了圖但遊戲裏不顯示 | 審覈還沒過（看 moderationState），或者資產是不可更新的舊 version |
代碼結構與測試¶
源碼結構如下，改動前可以按文件定位：
index.js # apply(ctx, config)：註冊三個工具
cordis.patch.yml # bundle 補丁（默認配置）
lib/config.js # 配置 schema + 歸一化
lib/presets.js # Roblox 預設
lib/openai.js # Images API 客戶端 + 落盤
lib/roblox.js # Open Cloud 上傳 + 校驗
lib/tools/*.js # 三個工具
test/*.test.js # node:test 單元測試
本地跑測試和打包預演：
npm test # 31 個純函數單元測試，不聯網
npm run pack:dry
適用場景與注意¶
適合這幾類人：
- 在 DSH 裏用 Roblox 做遊戲資產，需要圖標、貼花、縮略圖、徽章等預設尺寸的智能體開發者。
- 已經用過其他出圖插件、被
seed之類參數報錯或 schemanull報錯打斷過的人。 - 想把出圖結果直接落到 Roblox 資產庫、拿到
rbxassetid://的人。
幾點注意：
- 插件以當前 DSH 進程的權限運行，安裝前應讀一遍源碼並確認許可證（MIT）再接入。
- Roblox 上傳默認關閉，打開後每次上傳仍要對話確認，不要把
confirm自動化掉。 - 羣組的 Open Cloud key 要求調用者是羣組擁有者；IP 白名單沒有放行會導致 403。
- 該倉庫在 GitHub 上目前沒有 star，屬於個人維護項目，長期可用性取決於維護者節奏。倉庫更新、issue 反饋建議走 GitHub。
小結¶
這個插件的價值不在於加了一個新能力，而在於把出圖鏈路做窄做準：只發官方字段、schema 乾淨、預設只做尺寸與提示詞約束、上傳前有確認門檻。如果你需要 Roblox 資源和 GPT-Image-2.6 出圖，值得試一次。
目錄頁：https://www.skillhub.cn/plugins/yangshulin2333/dsh-openai-image
GitHub：https://github.com/yangshulin2333/dsh-openai-image
