前言¶
DeepSeek Harness（DSH）的會話能力依賴你在運行時選用的 LLM。若模型跑在本地 Magpie 網關後面，常見做法是單獨維護一份模型列表、手寫 OpenAI 兼容地址，或在 harness 外再掛一層代理。插件 dsh-magpie-connect（維護者 bitxeno，倉庫 bitxeno/dsh-magpie-connect）把 Magpie 網關上的模型註冊爲 DSH 原生 LLM 適配器：裝好後在 Web 端設置裏填網關地址和 Key，模型會進入 DSH 模型選擇器，無需爲網關單獨起進程或配系統代理。
這是什麼¶
dsh-magpie-connect 是 DSH 社區插件目錄中「模型推理」類插件，簡介爲：將 Magpie 網關模型快速接入 DeepSeek Harness。它在 DSH 內實現 MagpieAdapter（LlmAdapter），通過 OpenAI 兼容的 chat/completions 或 responses 流與網關通信；模型目錄來自網關 GET {baseUrl}/models，並在本地緩存，網關不可達時還有編譯期靜態快照兜底。
狀態與設置寫在 ~/.dsh-magpie-connect/（含 settings.json、模型緩存、adapter-status.json）。插件以當前 dsh 進程權限運行，安裝前建議在 GitHub 上查看源碼與 MIT 許可證。
核心功能¶
以下能力均來自插件 README 與 package.json 說明：
- 模型自動同步 — 網關列出的模型可進入 DSH 模型選擇器；具體顯示哪些由白名單（
enabledModels）決定，語義與 DSH 自帶「模型」設置一致。 - 圖片識別 — 網關聲明支持圖片的模型可發圖；純文本模型收到圖片會直接報錯，不會靜默丟棄。
- 思考檔位 — 網關支持的思考檔位（含
none、ultra）原樣出現在選擇器；none關閉思考，ultra直通網關，不在本地截斷。 - 容錯與刷新 — 啓動即註冊適配器，目錄後臺預熱；可配置刷新間隔、重試與多種超時；暴露模型集合變化時會通知瀏覽器重讀緩存。
安裝與啓用¶
環境要求：DSH 的 web profile、Node.js ≥ 20、運行 DSH 的環境能訪問 Magpie 網關。package.json 中聲明的 DSH 引擎範圍爲 >=0.2.0-rc.1 <0.2.1-0 或 >=0.2.1-alpha.1 <0.3.0-0（以你實際安裝的 DSH 版本爲準）。
官方安裝命令如下：
dsh plugin --profile web add dsh-magpie-connect
安裝後重啓 dsh web。已安裝時用同一條命令可更新到最新版本（npm 包當前版本爲 0.4.1）。
典型用法¶
第一步：在設置頁填網關地址和 Key¶
打開 設置 → Magpie 網關，確認兩項後點「保存」：
- API 地址 — 須帶版本段，默認
http://127.0.0.1:3425/v1；網關不在本機時改爲實際地址。插件只在你填的 base URL 後接資源路徑，不會自動補/v1。 - API Key — 必填；即使網關不校驗 Key，也需要非空字符串纔會生效。
保存後可點「測試連接」查看是否連通及網關上有多少模型。地址有默認值而 Key 沒有，未填 Key 前模型選擇器爲空。
第二步：選擇要顯示的模型¶
點 獲取可用模型，在彈窗中勾選需要的模型，再點「應用選擇」。列表是白名單：網關新上架的模型不會自動出現，需在彈窗裏勾選並應用；刪掉的行會從列表和選擇器一起移除，網關某條 lane 臨時抖動也不會把已刪模型偷偷加回。
恢復默認模型 會清掉自定義列表，回到直接使用網關完整目錄；空列表 [] 與「繼承網關目錄」是兩種不同狀態——前者不提供任何模型，後者全量提供。
「獲取可用模型」成功時會用網關當前目錄整體替換本地目錄，下架模型會同步消失；讀取失敗則不會清空本地目錄，避免誤清選擇器。彈窗使用的是當前表單裏的地址和 Key（即使尚未保存），便於換網關時一次試連。
模型增刪會自動保存；地址和 Key 須點「保存」才生效。
用配置文件代替設置頁（可選）¶
可在 profile 的 cordis.patch.yml 中寫入插件配置，例如：
- id: dsh-magpie-connect
name: 'dsh-magpie-connect'
config:
providerId: dsh-magpie-connect
displayName: Magpie
baseUrl: http://127.0.0.1:3425/v1 # 帶版本號的完整地址
apiKey: not-needed # 網關通常不校驗，但必須非空
refreshSeconds: 300
maxRetries: 2
timeoutMs: 300000
firstEventTimeoutMs: 90000
idleTimeoutMs: 60000
優先級爲：設置頁 > cordis.patch.yml > 默認值；設置頁只覆蓋你保存過的字段。其餘配置項（如 dataDir、各超時與 refreshSeconds）見 README 中的表格說明。
適用場景與注意¶
適合誰：已在用或計劃用 Magpie 作爲 LAN 網關、希望在 DSH Web 裏統一選模型、並需要圖片與思考檔位與網關聲明一致對齊的開發者。
常見問題（摘自文檔）：
- 選擇器爲空 — 先確認地址（含
/v1等版本段）、Key 已保存，再「測試連接」。 - 發圖失敗 — 僅支持網關聲明爲可收圖的模型；且圖片需經 harness 附件服務讀取，缺少該服務的組合也會失敗。
- 從舊版升級 — 首次啓動會把舊
hiddenModels轉爲enabledModels並寫入~/.dsh-magpie-connect/settings.json，只執行一次。
DSH 生態強調「一切皆插件」；SkillHub 插件目錄 是社區站點，與 DeepSeek / 幻方無官方從屬關係。安裝第三方插件前請自行審閱源碼與權限影響。
