DSH 的生態理念是「一切皆插件」。在使用 llm-pi-ai 適配器時，其 models 列表直接替換路由的 catalog，且該 catalog 不會自我刷新。這意味着若想使用 OpenRouter 的免費模型，通常需要手動維護 settings.yaml。
dsh-openrouter-free 插件旨在填補這一自動化缺口。它通過 GUI 提供免費模型清單，支持一鍵切換並自動適配推理檔位，免去手動配置的麻煩。
核心功能¶
免費清單面板
GUI 會話視圖新增「免費模型」標籤頁。這裏實時列出 OpenRouter 全部免費模型（包含名稱、ID、上下文窗口及圖片/推理支持情況）。插件內置 10 分鐘內存緩存，支持手動強刷。
一鍵切換
點擊列表中的任意行，插件會將該模型 ID 寫入 llm-pi-ai.providers.openrouter.models，同時通過原生 sessionController.selectModel() 更新當前會話的模型選擇，並同步更新 agent-default-model。這種會話級 + 全局雙寫的機制能確保切換立即生效，無需重啓。
推理檔自動預校驗
切換模型時，插件會從高到低嘗試該模型支持的檔位（low/medium/high）。若模型不支持推理，會自動移除 reasoningEffort 參數，避免因參數不匹配導致請求失敗。
憑據面板
內置 OpenRouter API Key 設置入口。若檢測到密鑰缺失，會直接提示補填。
全部裝進選擇器
執行「全部裝進選擇器」操作後，所有免費模型會被寫入路由。之後用戶既可通過本插件切換，也可直接使用 DSH 自帶的原生模型選擇器。
安全保留手工條目
插件在同步或切換模型時，會保留所有非免費的手工條目（例如 stealth/ox-alpha 等精調條目）。「全部裝進選擇器」操作也僅刷新免費條目。
安裝¶
本插件需手動複製源碼並註冊 bundle。
# 複製源碼到 profile 的 node_modules 目錄
Copy-Item -Recurse -Force . "C:\Users\73618\.dsh\profiles\web\node_modules\dsh-openrouter-free"
// 編輯 profile 的 package.json，在 dsh.profile.bundles 中追加 "dsh-openrouter-free"
// 示例片段
"dsh.profile.bundles": [
"dsh-openrouter-free"
]
安裝完成後需要重啓 DSH（host 改動需重啓；client 改動硬刷新即可）。
典型用法¶
插件提供 HTTP API 接口 POST /__orfree/api，支持以下操作：
| 方法 | 參數說明 | 說明 |
|---|---|---|
free.list({refresh}) |
refresh (可選) |
獲取免費清單。緩存 10 分鐘，傳入 refresh: true 可強刷。 |
current() |
無 | 獲取當前 agent-default-model 與已裝入的模型 ID 列表。 |
model.use({id}) |
id (必填) |
安裝單個免費模型並設爲當前對話模型。 |
sync.all() |
無 | 將所有免費模型裝入 openrouter 路由。 |
free.remove({id}) |
id (必填) |
移除某個免費模型（當前選中模型拒絕操作）。 |
前置條件與注意事項¶
前置條件
本機 settings.yaml 中必須已配置 llm-pi-ai.providers.openrouter 路由（baseURL: https://openrouter.ai/api/v1）。同時，環境變量 OPENROUTER_API_KEY 必須存在，即使拉取清單本身是公開 API，使用免費模型進行對話仍需密鑰。
注意事項
* 插件運行在當前 DSH 進程權限下，安裝前建議檢查源碼與許可證（MIT）。
* settings.yaml 的更新在下一次請求生效，無需重啓 DSH。
* DSH 社區目錄（如 SkillHub）與 DeepSeek / 幻方無官方從屬關係，本插件爲社區維護項目。
