前言¶
在 DSH 裏做智能體，常見做法是註冊一堆模型工具，讓 agent 直接調 API。圖像、視頻生成往往還要單獨處理憑據、輸出路徑和異步輪詢，和 harness 的設置頁、會話工作區也對不齊。下面介紹社區插件 dsh-agnes（維護者 Lennon-lylt）：把 Agnes 的生成能力接到 DSH 上，用設置頁管配置和 API Key，用 bundled skill + 獨立 CLI 執行生成，agent 通過 shell 跑命令完成調用，而不是在宿主側註冊模型工具。
這是什麼¶
dsh-agnes 是 DeepSeek Harness 的「模型推理」類插件，一句話定位：Agnes AI 圖像 / 視頻生成 —— 設置頁負責配置，真正的調用走一個 bundled skill。
- 倉庫：github.com/Lennon-lylt/dsh-agnes
- 社區目錄：skillhub.cn/plugins/Lennon-lylt/dsh-agnes
- 當前包版本（資料中的
package.json）：0.6.1，面向 DSH 0.2.x 線；registry 上的dsh-agnes@0.6.0面向 0.1.x，README 明確建議不要在市場裏對舊包點升級，以免與 0.2.x 不兼容。 - 許可證：MIT；Node >= 20。
Host 半邊註冊 agnes 設置命名空間、配置/憑據兩條同源路由，以及 bundled skill（skills/agnes/SKILL.md，其中的 {{CLI}} 會替換成安裝目錄下 CLI 的絕對路徑）。不註冊任何模型工具 —— 能力在 skill 裏，由 agent 用 shell 執行 lib/cli.mjs。
核心功能¶
設置頁與配置存儲¶
Client 半邊在 settings.section 註冊 設置 → Agnes，可配置 API Key、模型、尺寸、輸出目錄、輪詢參數等。頁面按順序探測傳輸：ctx.remote.settings → settingsScope（0.1.x）→ 宿主半邊路由 /api/dsh-agnes.settings（配置）與 /api/dsh-agnes.credential（憑據）。在 DSH 0.2.0-rc.2 的 Web 客戶端裏，前兩條對插件上下文常爲 undefined，實際多走第三條同源 /api 通道。
配置落在插件自有文件：<DSH_HOME>/storages/agnes/config.json，結構爲 { version, revision, values }。讀取優先級：內置默認值 → DSH 設置命名空間（較低）→ 該文件（最高）。頁面 POST 寫入時帶 revision 做衝突檢測；手工改文件後宿主按 mtime 重讀。
API Key 的存放與 CLI 讀取順序¶
權威來源是 DSH 憑據存儲；保存時宿主會鏡像到 <DSH_HOME>/storages/agnes/api-key（0600），供獨立 CLI 進程讀取。環境變量 AGNES_API_KEY 優先級最高。CLI 取用順序：環境變量 → Key 文件（CLI 讀不到 DSH 憑據存儲）。
執行體：純 Node CLI¶
lib/cli.mjs 是無 Cordis、無 DSH ctx 的純 Node 進程，讀同一份設置與 Key 文件，複用 lib/agnes-api.mjs。stdout 只輸出一個 JSON 對象（過程信息走 stderr）：成功 { ok: true, files|task }，失敗 { ok: false, error, kind, hint } 且退出碼 1。
產物會立即從 Agnes 返回的 URL 下載落盤（URL 會過期，不作爲交付物）。落盤順序：
--out → 設置裏的輸出目錄 → <當前工作目錄>/agnes-output/<日期>/ → <DSH_HOME>/agnes-output/<日期>/；回退時結果裏 fellBack: true。
Skill 與 agent 側用法¶
安裝並在設置頁填好 API Key 後，skill 已掛在 skill 目錄；agent 需要時讀取 SKILL.md 並執行 CLI。README 中的示例如下（路徑中的 <插件目錄> 在安裝時會被替換成真實絕對路徑）：
node "<插件目錄>\lib\cli.mjs" image --prompt "雨夜霓虹下的古鎮，國風插畫" --size 2K --aspect 16:9
node "<插件目錄>\lib\cli.mjs" image --prompt "改成線稿風格" --images .\photo.png
node "<插件目錄>\lib\cli.mjs" video --prompt "無人機掠過雪山" --size 720P --wait=180000
node "<插件目錄>\lib\cli.mjs" task list
node "<插件目錄>\lib\cli.mjs" models
node "<插件目錄>\lib\cli.mjs" config
子命令還包括 task status/wait/cancel --id <taskId> 等，詳見倉庫 README。
與 Agnes API 行爲相關的實現取捨（資料中的實測摘要）¶
以下來自插件 README 記載的 2026-10 實測，用於理解 CLI/skill 的設計，而非第三方 SLA：
| 能力 | 說明 |
|---|---|
| 文生圖 | POST /v1/images/generations，默認多返回 URL；支持像素對與 2K/4K + aspect_ratio |
| 圖生圖 | 圖片端點接受 base64 data URI 作爲 image 輸入 |
| 文生視頻 | POST /v1/videos 異步；輪詢 GET /agnesapi?video_id=..&model_name=.. |
| 視頻首幀 | 視頻 image 只接受公網 URL；data URI 會被靜默丟棄 —— 插件側若要用本地圖作首幀，需先經圖生圖等方式換取公網 URL |
安裝與啓用¶
請用 DSH 安裝器，不要手工把包目錄拷進 profiles/<profile>/node_modules（會導致 profile 不一致，harness 無法啓動）。官方 README 給出的命令如下：
dsh plugin --profile web add dsh-agnes
若從本地目錄安裝：
dsh plugin --profile web add file:D:\path\to\dsh-agnes
裝好後重啓 DSH 讓 profile 重新組合，打開 設置 → Agnes 填入 API Key。桌面端熱裝載對宿主半邊即時生效；瀏覽器裏已加載的舊客戶端包需 刷新頁面（F5） 後新設置頁才生效。
本地目錄安裝前：若開發自檢建過指向 profile node_modules 的 junction，安裝前須刪掉該 node_modules 鏈接，否則安裝器整樹複製可能 ENOENT（README 有具體錯誤樣例與 cmd /c rmdir 示例）。
卸載或回滾應使用安裝器或市場 UI；手工殘留需同時清理目錄與 profile manifest 聲明。
典型用法流程¶
- 按上一節安裝插件並重啓 DSH，在 設置 → Agnes 配置 API Key 與模型、輸出目錄等。
- 在 agent 會話中，由模型根據 bundled skill 在 shell 裏調用
cli.mjs（例如文生圖、圖生圖、文生視頻及task wait）。 - 在會話工作區或配置的輸出目錄查看
agnes-output/<日期>/下的文件；需要排查時用node .../cli.mjs config查看解析後的配置（不含密鑰）。
開發者可在倉庫內運行 README 列出的自檢腳本（如 scripts/selfcheck.mjs、scripts/client-page.check.mjs、帶 AGNES_API_KEY 的 scripts/smoke.mjs），安裝前建議至少跑 schema 自檢。
適用場景與注意¶
適合誰：已在 DSH 0.2.x 上使用 Web profile、希望 agent 通過 skill + CLI 調用 Agnes 做圖像/視頻生成，並希望在 harness 設置頁統一管理 Key 與默認模型的開發者。
權限與安全：插件與 CLI 以當前 DSH 進程及 agent shell 的權限運行；API Key 會寫入 DSH 憑據存儲，並可能鏡像到本地 Key 文件。安裝前應閱讀源碼與 MIT 許可證，自行評估是否接受明文 Key 文件或改用 AGNES_API_KEY 環境變量。
生態說明：DSH 社區插件目錄（如 SkillHub）是獨立站點，與 DeepSeek / 幻方無官方從屬關係；本文事實來自 GitHub README 與提供的 package 元數據。
排錯提示：若設置頁提示無可用設置傳輸，可展開探測報告，查看 /api/dsh-agnes.settings 是否爲非 JSON（常見於宿主半邊未裝載或路由未註冊）；頁面帶錯誤邊界，避免白屏。更多對照表見倉庫 README「設置頁排錯」一節。
結尾¶
dsh-agnes 把 Agnes 生成能力拆成「DSH 內配置 + skill 引導的 CLI 執行」，適配 0.2.x 的設置與 /api 路由，並處理輸出落盤與視頻首幀 URL 等 API 細節。進一步瞭解可訪問 社區目錄頁 與 GitHub 倉庫。
