前言¶

在 DeepSeek Harness（DSH）桌面端裏做智能體，常見需求是讓模型根據對話生成配圖或短視頻，而不是隻輸出文字。若自行對接各家生成 API，往往要處理鑑權、下載臨時 URL、異步輪詢和落盤路徑，還要控制返回給模型的上下文體積。社區插件 dsh-plugin-agnes-image（維護者 neil-ji，GitHub 分類爲模型推理）把 Agnes Image / Video 2.5 Flash 封裝成 Agent 可調用的工具，並把 API Key 放進 DSH 內置憑據庫。下面介紹它是什麼、能做什麼，以及如何安裝與配置。

這是什麼¶

dsh-plugin-agnes-image 是非官方社區插件：對 Agnes 生成接口做調用封裝，與 Agnes 官方無隸屬關係。當前 package 版本爲 0.3.1，許可證 MIT。

它解決的主要問題是：在帶 tools 服務、read_image 工具和憑據服務的 DSH 桌面端上，爲 Agent 提供文生圖、圖生圖、文生視頻能力；生成結果落到會話工作目錄，模型側主要拿到文件路徑、尺寸或時長、字節數，看圖用內置 read_image，交付用 present，避免把整圖塞進上下文。

核心功能¶

插件向 Agent 註冊四個工具，後端爲 Agnes Image 2.5 Flash（圖片）與 agnes-video-2.5-flash（視頻）。

圖片¶

• 調用 POST /v1/images/generations，將結果下載保存爲 PNG（返回 URL 爲臨時直鏈，不落盤會過期）。
• 從 PNG/JPEG/WebP 文件頭讀取真實寬高。
• 同名文件不覆蓋（例如已有 art.png 則寫入 art-2.png）。
• 尺寸檔位 1K/2K/3K/4K，比例含 1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9（README 註明 16:9 的 2K 爲 2624×1472，而非 1920×1080）。
• 引擎不支持的參數（seed、negative_prompt、steps、n>1）不會出現在工具 schema 中。

視頻¶

Agnes 視頻爲異步任務：先創建，再按 video_id 輪詢，完成後從 url 下載。

• 分辨率固定 720P，時長 "4"–"12" 秒，n 固定爲 1。
• 模式：text（僅提示詞）、keyframe（first_frame / last_frame 至少一個）、reference（最多 5 張參考圖 + 3 段參考音頻，提示詞中用 <Picture 1>、<Audio 1> 指代）。
• 視頻參考素材須爲公共 HTTPS URL；本地文件與 data: URI 不可用；Flash 不支持參考視頻。
• 工具默認最多等待 3 分鐘；未完成則返回 pending 與 videoId，可再調 agnes_video_status；也可設 wait: false 立即拿到 videoId。
• 下載 MP4 後在文件頭校驗（ftyp），非視頻不落盤；同名不覆蓋。

默認輸出目錄爲相對會話工作目錄的 agnes-output（可通過配置 outputDir 修改）。

安裝與啓用¶

桌面端插件頁（推薦）¶

打開 設置 → 插件 → 添加插件，粘貼倉庫地址：

https://github.com/neil-ji/dsh-plugin-agnes-image

本地目錄（開發時）¶

plugin_manager install_bundle "F:\path\to\dsh-plugin-agnes-image"

將路徑替換爲本機插件目錄；README 示例爲 Windows 路徑格式。

配置 API Key¶

圖片與視頻共用同一個 Key，在 設置 → Agnes 生圖 中配置：

1. 打開 設置 → Agnes 生圖。
2. 粘貼 API Key，點擊保存（密碼框，可臨時「顯示」覈對）。
3. 狀態指示變綠後，下一次生圖或生視頻即生效，無需重啓 DSH。

Key 寫入本機 DSH 憑據庫（~/.dsh/.credentials.yaml 中 AGNES_API_KEY 引用）。界面只寫不讀，已存 Key 不會回顯到瀏覽器。解析優先級爲：apiKey 配置（僅 CI）→ 憑據庫 → 同名環境變量。

常用配置字段（完整列表見倉庫 README）包括：credentialRef（默認 AGNES_API_KEY）、model（默認 agnes-image-2.5-flash）、defaultSize / defaultRatio（默認 2K / 1:1）、videoModel（默認 agnes-video-2.5-flash）、videoWaitMs（默認 180000）等。

典型用法¶

在 Agent 對話中用自然語言觸發即可，README 給出如下示例方向：

# 文生圖
生成一張 2K、16:9 的賽博朋克街景，霓虹燈、雨後反光

# 圖生圖
把 C:\work\hero.png 裏的角色改成揮劍動作，保持角色和構圖，2K 16:9

# 文生視頻
生成 6 秒、16:9 的視頻：雨後的未來城市街道，霓虹倒映，銀色跑車緩慢駛過，低機位跟拍，自然環境聲

# 首尾幀視頻（圖片需公共 URL）
用這兩張圖做首尾幀，5 秒、16:9，人物自然轉身走向窗邊

適用場景與注意¶

適合誰：需要在 DSH 桌面 Agent 裏直接出圖、改圖或出短視頻，且願意使用 Agnes 2.5 Flash 能力鏈路的開發者。

引擎限制（摘要）：

• 圖片：無 seed，同提示詞結果不可復現；一次一張；無 negative prompt / steps；輸出無 alpha。
• 視頻：僅 720P；參考圖、音頻須公網 URL；隊列滿時可能返回 503 video queue is full，README 建議約一分鐘後重試。

安全與權限：插件以當前 DSH 進程權限運行，會讀寫會話工作目錄並訪問網絡調用 Agnes。安裝前請閱讀倉庫源碼與 MIT 許可證；README 說明代碼與文檔中不含示例密鑰，Bearer 令牌在日誌中會打碼。

DSH 生態強調「一切皆插件」；插件目錄頁 skillhub.cn 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-plugin-agnes-image 把 Agnes 文生圖、圖生圖與 720P 短視頻封裝成四個 Agent 工具，並把 Key 納入 DSH 憑據庫與設置頁，減少自建 HTTP 與落盤邏輯。進一步瞭解與提 Issue 見：

• 目錄頁：https://www.skillhub.cn/plugins/neil-ji/dsh-plugin-agnes-image
• GitHub：https://github.com/neil-ji/dsh-plugin-agnes-image