前言¶
在 DeepSeek Harness（DSH）裏讓 Agent 出圖，常見做法是再套一層 OpenAI 兼容網關，把 fal.ai 的隊列協議翻譯成通用 Chat Completions 或 Images API。多一層轉發，調試時要同時覈對網關配置、fal 端點 slug 和 DSH 工具參數，出錯點也分散。
dsh-fal-imagegen（維護者 Enchanted0911，GitHub：Enchanted0911/dsh-fal-imagegen）走另一條路：Agent 工具直接 POST https://queue.fal.run/<slug>，用 fal 文檔裏的 Authorization: Key <key_id>:<key_secret> 提交任務、輪詢隊列票據，並消費 { images: [{ url, width, height }] }。設置頁提供 FAL_KEY 卡片，與 ~/.dsh/settings.yaml 中 dsh-fal-imagegen: 段一致。npm 包版本爲 0.2.1，許可證 MIT。
這是什麼¶
一句話：面向 DSH 的 fal.ai 原生文生圖 / 圖生圖插件——設置卡片 + 四個 Agent 工具，不經過 OpenAI 兼容中間層。
分類上屬於「模型推理」：推理請求發往 fal 隊列，結果以附件和本地文件兩種形式回到對話。
核心功能¶
原生 fal 協議¶
工具鏈按 fal 隊列語義工作：提交 → 拿到 status_url / response_url → 輪詢 → 解析 images[]。密鑰格式爲 fal.ai → Keys 頁複製的完整字符串 key_id:key_secret。
設置卡片¶
入口在 Settings → Plugins，名稱隨 DSH 語言顯示爲「fal 生圖」或「fal imagegen」（與 Settings → General → Language 一致，未匹配時英文）。卡片與內置插件同款交互：摺疊、髒狀態、字段級重置、保存/丟棄。
主要配置項（默認值見下表）：
| 字段 | 默認 | 含義 |
|---|---|---|
enabled |
true |
總開關（工具 + 系統提示公告） |
falKey |
空 | FAL_KEY；留空表示不改動已保存密鑰 |
defaultTextToImageModel |
openai/gpt-image-2.5/flare/text-to-image |
文生圖端點 |
defaultImageToImageModel |
openai/gpt-image-2.5/flare/edit |
圖生圖端點 |
defaultImageSize |
1:1 |
比例、WxH 或 auto |
quality |
high |
auto / low / medium / high / xhigh / max |
outputFormat |
png |
png / jpeg / webp |
timeoutSeconds |
300 |
單次請求總超時（提交 + 隊列 + 拉取） |
saveDir |
空 | 落盤目錄；空則 <DSH_HOME>/fal-imagegen |
announceToAgent |
true |
是否在 Agent 系統提示中公告本插件 |
Agent 工具¶
| 工具 | 作用 |
|---|---|
fal_generate_image |
文生圖；默認異步，參數含 prompt / model / size / quality / count / wait |
fal_get_image_task |
按 task_id 或 fal request_id 查進度；無 id 時列出近期任務 |
fal_edit_image |
圖生圖，同步；需 prompt 與附件引用或磁盤 image_path |
fal_list_image_models |
列出內置別名、當前默認項與輸出目錄 |
生成圖會掛到對話附件（工具調用旁渲染），並寫入輸出目錄；返回的 path 可直接傳給 fal_edit_image 的 image_path。
異步文生圖¶
默認不再佔用整輪 Agent 等待 fal 隊列：
fal_generate_image提交後立即返回{ status: "queued", task_id, request_id, ... }。- 後臺 collector 輪詢隊列、下載圖片、寫附件並複製到輸出目錄。
fal_get_image_task報告queued / running / completed / failed；wait_seconds爲 0–120 時可阻塞等待，完成後返回帶attachment_id與本地path的images[]。- 需要舊式阻塞行爲時，對
fal_generate_image傳wait=true。
任務記錄保存在當前 dsh 進程內（約保留 6 小時、最新 64 條）；後臺等待超時後，下次查詢會自動重試。fal_edit_image 仍爲同步，便於鏈式編輯。
模型別名¶
內置別名已對照 fal 端點 schema；含 / 的未知 slug 原樣透傳；文生圖 slug 誤用於編輯會被拒絕。節選：
| 別名 | 文生圖 | 圖生圖 |
|---|---|---|
gpt-image-2.5-flare（默認，亦接受 gpt-image-2.5 / gpt-image-2.5-flash） |
openai/gpt-image-2.5/flare/text-to-image |
openai/gpt-image-2.5/flare/edit |
flux-2-flash |
fal-ai/flux-2/flash |
fal-ai/flux-2/flash/edit |
nano-banana-2 |
fal-ai/nano-banana-2 |
fal-ai/nano-banana-2/edit |
完整表見倉庫 README 的 Model aliases 一節。
安裝與啓用¶
推薦通過 npm 包安裝（CLI 管理的 profile）：
dsh plugin --profile web add dsh-fal-imagegen
安裝後需重啓對應 profile 的 DSH 進程。
desktop profile 由 DSH Desktop 應用管理（dsh plugin --profile desktop 會被拒絕）：應在 Settings → Plugins → market 安裝，或按 README 在 ~/.dsh/profiles/des… 下手動註冊（截斷處請以 GitHub 原文爲準）。
啓用後先在設置卡片或 settings.yaml 填入 falKey，並確認 enabled 爲 true。
典型用法¶
下面步驟可在 Agent 對話中復現（具體措辭由模型決定，工具名固定）。
文生圖（異步，推薦）
- 調用
fal_generate_image，例如prompt描述畫面，可選model別名、size、quality。 - 記下返回的
task_id。 - 調用
fal_get_image_task，傳入task_id；需要時可設wait_seconds等待完成。 - 在
completed結果裏使用images[].path或附件 id 做後續步驟。
圖生圖（同步）
- 準備源圖：對話附件引用，或上一步落盤的
image_path。 - 調用
fal_edit_image，傳入prompt與源圖參數。 - 在同一輪內使用返回的圖片路徑繼續編輯。
查看默認與別名
調用 fal_list_image_models 可覈對當前默認端點、別名列表與輸出目錄。
適用場景與注意¶
適合已在 fal.ai 開通 API、希望在 DSH Agent 裏原生使用隊列生圖/編輯的開發者。異步默認更適合長隊列，避免 Agent 回合被單次生圖拖住；短鏈路圖生圖仍用同步的 fal_edit_image。
安裝前建議自行閱讀 GitHub 倉庫 源碼與 MIT 許可證。插件以當前 dsh 進程的用戶與網絡權限運行：密鑰寫入本地配置、圖片寫入 saveDir 或默認目錄，並會向 queue.fal.run 發起外網請求。社區插件目錄 SkillHub 條目 與 DeepSeek / 幻方無官方從屬關係，僅作發現與索引。
DSH 生態強調「一切皆插件」；本插件屬於社區「模型推理」類擴展，星標與熱度以倉庫頁面實時數據爲準。
鏈接¶
- 目錄頁：https://www.skillhub.cn/plugins/Enchanted0911/dsh-fal-imagegen
- GitHub：https://github.com/Enchanted0911/dsh-fal-imagegen
- npm：
dsh-fal-imagegen@0.2.1
