dsh-nous-portal-free-provider：接入 Nous Portal 免費層的 DeepSeek Harness 插件

前言¶

DeepSeek Harness (DSH) 的核心設計理念之一是「一切皆插件」。通過插件，用戶可以擴展模型來源。Nous Portal 提供了包含 Hy3、Ox Alpha 等在內的免費模型層。jiesou/dsh-nous-portal-free-provider 這個插件的作用，是將 Nous Portal 的免費層級接入 DSH 的 web profile，通過 OAuth device code 登錄流程使用這些模型。

核心功能¶

本插件實現了以下功能：
* OAuth Device Code 登錄：通過獨立的 CLI 完成授權登錄。
* 模型動態發現：啓動時從上游 /v1/models 接口抓取模型列表，過濾出價格爲 $0 的模型作爲目錄，不寫死 ID。
* Reasoning Effort 支持：暴露上游支持的檔位，默認不發送字段，提供 Off 開關。
* 圖片 Offload 機制：當圖片超過配置大小時，觸發 IMAGE_OFFLOAD_REQUIRED，由 DSH 將最舊圖片存入 image/offload 並重試。
* Refresh Token 輪換：支持單次使用的 Refresh Token，通過 modifyRecord 鎖機制確保併發安全。

安裝與啓用¶

在終端中執行以下命令安裝插件：

dsh plugin --profile web add @jiesou/dsh-nous-portal-free-provider

安裝完成後，運行插件自帶的 CLI 進行登錄：

node ~/.dsh/profiles/web/node_modules/@jiesou/dsh-nous-portal-free-provider/lib/cli.js

登錄過程中，請根據終端提示使用 device code 登錄。運行中的 dsh 會熱加載，無需重啓。

CLI 選項¶

登錄 CLI 支持以下參數，用於覆蓋默認配置：

--portal-url <url>       Portal 地址（默認 https://portal.nousresearch.com）
--client-id <id>         OAuth client id（默認 hermes-cli）
--scope <scope>          申請的 scope（默認 inference:invoke）
--dsh-home <dir>         憑據文檔所在 home（默認 $DSH_HOME 或 ~/.dsh）
--path <file>            憑據文檔完整路徑，優先於 --dsh-home

配置與機制¶

插件使用 ctx.credentials 統一接口管理憑據。存儲結構支持普通 API Key 和 OAuth Grant 兩種來源。

插件提供以下 Settings 配置項：
* retryPolicy：模型請求重試策略，默認 always（每次失敗都重試）。
* maxRequestImageBytes：單次請求內聯的 base64 圖片上限，默認 2097152（2 MiB）。
* requestImageMaxBytes：單張圖片重編碼後的上限，默認 1048576（1 MiB）。

注意事項¶

依賴版本：需要 DSH 版本 >=0.2.0-rc.2。
Token 單次使用：Portal 的 Refresh Token 每次刷新都會生成新 Token，舊 Token 立即作廢。若重複提交已用過的舊 Token，服務端會判定令牌被盜並吊銷整條會話。因此插件在刷新 Token 時使用了鎖機制。若看到 Refresh token reuse detected 提示，需按上述步驟重新登錄。
UI 渲染 Bug：Portal 端的 device-code 審批頁曾存在渲染 Bug（Issue #47950）。如果授權卡住，請先確認瀏覽器已登錄 Portal 再重試。
協議變更：Portal 已下線舊版鑄造端點，本插件已適配新版 hermes-cli 的登錄流程。

結語¶

該插件爲 DSH 用戶提供了接入 Nous Portal 免費模型的途徑。更多細節與源碼可參考：
* GitHub: https://github.com/jiesou/dsh-nous-portal-free-provider
* 目錄頁: https://www.skillhub.cn/plugins/jiesou/dsh-nous-portal-free-provider