dsh-agnes-media：Agnes AI 圖像與視頻生成插件

前言¶

DeepSeek Harness (DSH) 的 LLM 端點主要處理文本對話。然而，像 Agnes 這樣的圖像和視頻生成服務返回的是媒體文件，而非聊天消息。dsh-agnes-media 插件通過提供 agnes_image 和 agnes_video 工具，填補了這一空白，將媒體生成能力集成到 DSH 的工具生態中。

插件簡介¶

dsh-agnes-media 是一個面向 Agnes AI 圖像和視頻生成工具的插件，包含兩個核心工具：agnes_image 和 agnes_video。該插件由 zlforward 維護。

核心功能¶

agnes_image：支持文本到圖像、圖像到圖像、多圖像組合。
agnes_video：支持文本到視頻、關鍵幀、多模態參考（異步任務）。

安裝與啓用¶

使用官方命令安裝插件：

dsh plugin --profile <profile> add dsh-agnes-media

或在 profile 的 package.json 中聲明 bundle：

{
  "dsh": { "profile": { "bundles": ["dsh-agnes-media"] } }
}

安裝後需要重啓 DSH 進程。

典型用法¶

在 credentials.yaml 中設置 API 密鑰：

# $DSH_HOME/.credentials.yaml
refs:
  AGNES_API_KEY: sk-...

在 profile 的補丁層中覆蓋配置：

- id: agnes-media
  config:
    baseURL: https://apihub.agnes-ai.com/v1
    apiKeyEnv: AGNES_API_KEY
    imageModel: agnes-image-2.5-flash
    videoModel: agnes-video-2.5-flash
    outputDir: agnes-media
    requestTimeoutMs: 300000
    imageTimeoutMs: 360000
    videoTimeoutMs: 1800000
    videoPollIntervalMs: 3000

輸出路徑：默認情況下，生成的文件保存在調用智能體會話的工作空間中：

<workspace>/agnes-media/image-<UTC timestamp>.png
<workspace>/agnes-media/video-<UTC timestamp>.mp4

適用場景與注意事項¶

該插件適合需要在智能體工作流中直接調用圖像和視頻生成能力的場景。

密鑰管理：插件不存儲祕密，通過環境變量 AGNES_API_KEY 解析憑證。未配置的引用會導致報錯，而非靜默失敗。
結果權威性：Agnes 返回的託管 URL 可能會過期，插件會下載字節流並保存爲本地文件，本地文件是權威來源。
視頻任務特性：agnes_video 是長時間運行的任務（最長約 30 分鐘），涉及輪詢和異步處理，默認超時時間較長。
輸入限制：視頻媒體必須是公共 URL，無法直接訪問本地文件系統；圖片支持數據 URI，無需上傳步驟。
錯誤處理：插件內置了對 429（速率限制）和 503（服務不可用）的重試機制，並會處理 video_queue_full 錯誤。
API 差異：視頻結果 URL 結構位於頂層（url）而非文檔中的 metadata.url；任務狀態拼寫（如 pending）與文檔不一致，插件已做適配。
模型配置：模型名稱（如 agnes-image-2.5-flash）需在配置中指定，無法從端點自動發現。

結語¶

dsh-agnes-media 解決了 DSH LLM 路由無法處理非對話類生成請求的問題。通過提供標準的工具接口和本地化文件處理能力，它爲構建多模態智能體提供了可靠的底層支持。