前言¶

在 DeepSeek Harness（DSH）裏做智能體或日常對話，通常要先選 provider、再配 API Key，還要自己處理某個免費端點 429 或 5xx 之後換哪家。社區插件 dsh-freellmapi（維護者 lion231226）把「按請求選模型、失敗自動換候選、流式回傳」收進一條 DSH provider 路由：安裝後在模型選擇器裏選 FreeLLMAPI (Auto) 和模型 auto 即可。默認 direct 模式不需要單獨跑網關或 Docker，也不強制先填 Key——內置池裏包含維護者用無憑證請求驗證過的 provider。

README 明確說明：這是社區項目，與 DeepSeek、各上游廠商均無隸屬或背書關係；使用各 provider 免費檔時需自行遵守其服務條款，並注意免費檔可能記錄或用於訓練的數據。插件在 當前 DSH 進程權限 下運行，安裝前建議查看 GitHub 倉庫 源碼與 MIT License。

這是什麼¶

dsh-freellmapi 是 DSH 的 Free-tier multi-provider routing 插件：在 Cordis bundle 裏註冊 provider 路由 freellmapi，對外呈現爲 FreeLLMAPI (Auto)，核心模型 id 爲 auto。每次請求會先做一次複雜度分類（simple / medium / complex），再按能力、速度等元數據排序候選模型；遇到 429、5xx、超時或 model_unavailable 會在 尚未發出第一個 chunk 之前 嘗試下一個候選，避免同一條回答被兩個模型拼接。

與「自己維護一長串 OpenAI 兼容 base URL」相比，插件自帶 17 個 provider、46 個模型 的目錄（README 表格寫 18 provider entries；package 描述爲 18 catalogued providers），其中 默認只啓用 5 個，且這 5 個均含免費檔。未配置 Key 的 provider 在模型列表裏會收成 setup:<provider> 指引，而不是一堆無法調用的死模型；若你 固定（pin）某個具體 model id，則不會靜默換成別的模型——無 Key、不存在或冷卻中會返回明確錯誤。

另保留 gateway 模式：行爲與 v0.1.0 一致，把請求轉發到外部的 freellmapi 網關（需自行部署），適合仍想用網關側 bandit、緩存、fusion 的用戶。默認 direct 則路由邏輯全在插件內完成。

分類上，SkillHub 目錄將其歸爲 模型推理。當前 package 版本爲 0.7.18（見倉庫 package.json）。

核心功能¶

下面按 README「What you get」歸納，均可在倉庫文檔中核對。

自包含路由（direct）
不依賴外部進程；DSH 啓動並加載 bundle 後即可使用。

內置模型池與默認啓用範圍
目錄覆蓋 Groq、Cerebras、OpenRouter、Mistral、Z.ai、Volcengine Ark、LongCat、LLM7、Kilo、NVIDIA NIM、OVH AI Endpoints，以及 ModelScope、訊飛星火、SiliconFlow、SambaNova、HuggingFace Router、Routeway 等；每個模型帶有能力、速度、上下文、視覺與 tool calling 等事實字段。開箱僅啓用其中五個 provider。

按請求複雜度選模型
簡單列舉類任務與多工具重構類任務不會強制走同一模型；tier 決定排序時更偏重能力還是速度。

失敗轉移與健康度
首個可重試失敗即將候選 park（默認 2 分鐘），連續失敗按 2 分鐘 → 10 分鐘 → 1 小時 → 24 小時升級；provider 返回的 Retry-After 優先；401/403 會將該 provider park 24 小時。評分懲罰約 60 秒半衰期，單次 429 不會長期封死路由。

零配置可用
維護者於 2026-10-13 用無 Authorization 請求驗證過 keyless 線路（詳見倉庫 _lead/live-probe-2026-10-13.md）。其中 Kilo、LLM7 默認啓用且可無 Key 完成補全；OVH 同樣 keyless 但默認關閉。

可觀測
默認開啓 logRouting 時，每個請求一行日誌，例如：

dsh-freellmapi: tier=complex -> openrouter/nvidia/nemotron-3-ultra-550b-a55b:free (capability=5, speed=3, 2 candidates tried)

失敗以 in-band finish chunk 返回穩定錯誤碼，而不是未捕獲異常。

安裝與啓用¶

DSH 生態強調「一切皆插件」；SkillHub 目錄頁 是社區站點，與 DeepSeek / 幻方無官方從屬關係。安裝 spec 以 README 爲準。

1、通過 Web GUI（推薦）¶

1. 打開 DSH Web 界面，側邊欄進入 Plugins 管理器。
2. 安裝 bundle，粘貼下列之一併確認（若 DSH 提示則重啓）：

github:lion231226/dsh-freellmapi          # from GitHub (no npm publish needed)
github:lion231226/dsh-freellmapi#v0.7.18   # pinned to a tag
dsh-freellmapi                            # from npm, once published

插件自帶 cordis.patch.yml，正確安裝後 不要 在 profile 的 cordis.patch.yml 裏再插入相同 id: freellmapi 的行，否則會因 duplicate loader entry 導致 bundle 組合失敗。

2、CLI（需對照你的 DSH 構建確認）¶

README 給出等價命令（文檔註明未在此端到端驗證）：

dsh plugin --profile desktop add github:lion231226/dsh-freellmapi

3、手動放置¶

將包複製到 $DSH_HOME/profiles/<profile>/node_modules/dsh-freellmapi/，在該 profile 的 package.json 中同時寫入 dependencies 與 dsh.profile.bundles，執行 dsh plugin --profile <profile> install 並重啓。僅寫在 dependencies 不會加載 bundle。

運行環境：package.json 要求 Node ^22.19.0 || >=24.0.0。

典型用法¶

Quick start 概括爲四步：

install the plugin  →  start DSH  →  pick provider "freellmapi" + model "auto"  →  it answers

具體對應關係如下。

1. 完成安裝並啓動 DSH。
2. （可選）在插件配置中粘貼部分 provider 的 API Key，見 README Adding keys；跳過此步時，默認啓用的 keyless provider 仍可響應。
3. 在模型選擇器中選擇 provider FreeLLMAPI (Auto)（路由 id 爲 freellmapi），模型選 auto。
4. 發起對話或 Agent 任務；若需排查路由決策，保持默認 logRouting 並查看上述單行日誌。

若你固定使用某個 catalog 中的 model id 而非 auto，插件會 嚴格 只調該模型；不滿足條件時返回說明，不會偷偷改用其他免費模型。

長跑 Agent 會話：README 專節 Long-running agent sessions 建議在長時間多輪任務裏謹慎使用 auto，必要時改 pin 具體模型或調整配置；寫 Agent 前建議先讀該節。

gateway 模式：在 Configuration 中將 mode 設爲 gateway，並指向你自建的 freellmapi 網關；行爲與早期版本一致，與 direct 的內置排序、failover 是兩套路徑。

更細的配置項、模型列表讀法、故障排除見 README 的 Configuration、Troubleshooting 等章節。

適用場景與注意¶

適合誰

• 希望在 DSH 裏 先跑通再慢慢加 Key，利用默認 keyless + 免費檔做開發或輕量任務。
• 需要 單次請求內 按複雜度選模型，並在上游限流或故障時自動換候選，且接受「僅在首 chunk 前 failover」的語義。
• 已有 DSH 插件習慣，願意使用社區維護的路由表（provider 可用性會隨上游變化，README 也列出 Limitations and unverified claims）。

使用前請留意

• 插件 非官方，你對發往各免費 API 的內容負責。
• 安裝即信任 bundle 代碼；僅在當前工作目錄寫稿約束下，請直接在 GitHub 審閱源碼後再安裝。
• CLI 安裝命令是否與你的 DSH 版本完全一致，以運行時幫助或 GUI 爲準。
• 需要網關側 fusion / 緩存時，用 gateway 模式並自行運維 freellmapi，而不是默認 direct。

結尾¶

dsh-freellmapi 把多廠商免費檔收成 DSH 裏的一條 FreeLLMAPI (Auto) + auto 路由：默認無需外部網關，可無 Key 起步，按請求複雜度選模型並在首 chunk 前 failover，pin 模型則不做靜默替換。

• 目錄頁：https://www.skillhub.cn/plugins/lion231226/dsh-freellmapi
• 源碼與完整文檔：https://github.com/lion231226/dsh-freellmapi