前言¶
在 DeepSeek Harness（DSH）裏做智能體時，常見需求是讓模型根據文字出圖、出視頻，或把本地/網絡圖片轉成文字描述再參與對話。若自行對接 HTTP API、處理二進制回傳與會話上下文，工具層和網關細節會佔不少時間。社區插件 @lingxinsuixing/dsh-agnes 把 Agnes AI 的圖像生成、視頻生成和可選的圖像識別封裝成 DSH 工具：工具返回值始終是文本（路徑、URL、摘要），生成文件落在本地目錄，不把圖片或視頻字節塞進對話。
這是什麼¶
@lingxinsuixing/dsh-agnes 由維護者 lingxinsuixing 發佈，在 SkillHub 等社區目錄中歸類爲「模型推理」。它面向已安裝 DSH、並持有 Agnes API Key 的開發者，在 Harness 內註冊可調用的生成與識別工具，與 DSH「一切皆插件」的擴展方式一致。社區目錄站點與 DeepSeek / 幻方無官方從屬關係，安裝前仍應自行查看倉庫源碼與 MIT 許可證；插件以當前 dsh 進程權限運行。
核心功能¶
插件提供三個工具（識別可關閉），均只返回文本：
| 工具 | 作用 | 主要參數 |
|---|---|---|
agnes_image_generate（主能力） |
按文本提示生成或編輯圖像 | prompt、size、ratio、references、saveTo |
agnes_video_generate（主能力） |
按文本提示生成視頻 | prompt、mode、seconds、size、aspectRatio、images、saveTo |
agnes_image_recognize（可選） |
描述圖像或按問題回答 | image（本地路徑或 http(s) URL）、prompt |
默認模型方面：識別使用 agnes-3.0-flash；圖像生成爲 agnes-image-2.5-flash（文檔稱整條圖像模型線目前免費）；視頻默認爲 agnes-video-2.5，若要用免費檔可改爲 agnes-video-2.5-flash（僅 720P，且不能帶參考視頻）。可在插件頁「Models」中修改。模型列表與價格見 Agnes 文檔概覽。
關於 size：API 會把如 1920x1080 的請求映射到最近檔位，結果裏的 size 是磁盤上文件的實際像素尺寸，不一定與請求完全一致。
生成媒體默認寫入 DSH 主目錄下的 media/（$DSH_HOME/media，未設置 $DSH_HOME 時爲 ~/.dsh/media），可在插件頁「Output folder and read scope」調整 outputDir。每次調用返回所寫文件的絕對路徑。saveTo 必須指向已存在的目錄，插件不會隨意創建目錄，文件名由插件生成，不會覆蓋你已有文件。
安裝與配置¶
下面介紹安裝與密鑰配置，順序與 README 一致。
安裝¶
包無構建步驟，安裝後無需額外審批：
dsh plugin add github:lingxinsuixing/dsh-agnes
配置 API Key¶
在 Web UI 打開 Plugins → @lingxinsuixing/dsh-agnes 粘貼 Agnes API Key，或使用 DSH 憑據存儲：
# ~/.dsh/credentials.yaml（或 Web UI 中的憑據存儲）
AGNES_API_KEY: your-key
查找順序爲：插件配置 config.apiKey → 憑據項 AGNES_API_KEY → 環境變量 AGNES_API_KEY。設置在頁面輸入的 Key 會以明文寫入你的個人配置中的 config.apiKey，不會寫入插件包；包本身不帶任何憑據。
可選：關閉圖像識別¶
若不需要識別，在插件配置中設置 enableRecognition: false，則不會註冊 agnes_image_recognize，僅保留圖像與視頻生成。工具在插件加載時註冊，修改後需重啓 DSH 一次生效。
識別還可通過 allowedReadRoots 限制可讀本地圖像的根目錄列表（絕對路徑）；爲空表示不限制可讀圖像文件。
典型用法與集成注意¶
智能體在對話中調用上述工具即可：例如用 agnes_image_generate 傳入 prompt 與可選的 size、ratio、references，從返回文本中取本地路徑與 URL；視頻同理使用 agnes_video_generate。需要理解圖片內容時，應使用 agnes_image_recognize，而不是依賴 DSH 內置的 read_image。
README 明確說明：一旦模型被標記爲支持圖像，內置 read_image 會把圖像內容塊放進會話；Agnes 網關的 /v1/responses 不理解 input_image，下一次請求可能返回 400 且不會重試，整段會話歷史重建後仍失敗，需新開對話。因此在與 Agnes 通過 openai-responses 對接時，不要用 read_image 處理主對話裏的圖片，改用 agnes_image_recognize，由 Agnes 視覺模型處理圖像，僅文本回到對話。
若 provider 使用 api: openai-completions 對接 Agnes，還應在模型條目中聲明 reasoningEfforts，否則 DSH 不會發送 reasoning_effort，網關無 reasoning_content 時，模型可能把推理過程寫進消息正文。
環境要求：@deepseek-ai/schemastery >=3.18.1（package.json 中對 peer 版本有更細區間）、有效的 Agnes API Key；視頻按 Agnes 計費（-flash 檔目前限制 720P）。
適用場景¶
適合已在 DSH 中編排工具、希望統一用 Agnes 做文生圖、文生視頻，或可選地做圖像問答的開發者。不適合期望工具直接在對話裏嵌入二進制媒體的場景——本插件設計就是文本結果 + 本地文件。
安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認權限與輸出目錄策略符合你的環境。
結尾¶
@lingxinsuixing/dsh-agnes 把 Agnes 的圖像、視頻生成和可選識別收成 DSH 原生工具，會話保持純文本，產物落在可配置的本地目錄。目錄頁：https://www.skillhub.cn/plugins/lingxinsuixing/dsh-agnes；源碼與說明：https://github.com/lingxinsuixing/dsh-agnes。
