前言¶

在 DeepSeek Harness（DSH）裏通過 llm-pi-ai 走 OpenRouter 時，模型目錄會隨 OpenRouter 側更新而變動；若只在配置裏手工維護 models 列表，容易漏掉新模型，也拿不到賬號專屬的 @preset/... 條目。社區插件 dsh-openrouter-sync-models（維護者 m1khal3v，npm 包名同插件 id，當前版本 0.1.7，MIT 許可證）面向這一問題：用 OpenRouter 認證接口拉取目錄，過濾後寫回路由配置中的 api 與 models，並在啓動、定時以及 API Key 變更時重複同步，無需重啓進程即可通過 HMR 生效。

這是什麼¶

一句話定位：爲 DSH 提供「始終接近當前 OpenRouter 目錄」的 OpenRouter 路由模型表，含賬戶 preset。

插件通過 ctx.llm.listConfigurableProviders() 找到 openrouter 路由，經 ctx.credentials 解析 apiKeyEnv 後請求 GET /api/v1/models，將結果過濾、映射爲 DSH 模型 profile，再經 ctx.settings.mutate() 僅寫入 api 與 models；路由其餘字段仍由用戶維護。README 說明其適用於 desktop、web、CLI 等表面，不依賴 DSH_HOME 手改 YAML、不做正則補丁或獨立 status 文件。

核心功能¶

下面介紹 README 中已寫明、且與實現描述一致的能力。

認證目錄與 preset¶

使用 OpenRouter token 請求認證版目錄，因此除公開列表外，還可包含賬號相關的 @preset/... 模型。未配置密鑰且 requireKey 爲默認 true 時，插件會跳過同步，而不是默認清空已有 preset。

同步時機與可觀測性¶

同步在進程啓動時執行，之後按 intervalHours（默認 6 小時）定時刷新；密鑰變化也會觸發更新。結構化日誌走 ctx.logger，併發出 openrouter/models-synced 事件。

默認過濾策略¶

默認只保留「有用」的模型：開啓 tool calling（requireTools: true）、純文本輸出（requireTextOutput: true）、具備 chat 端點（requireChatEndpoint: true）；includePresets: true，付費與免費模型均保留（freeOnly: false）。映射時會投影上下文長度、輸入模態、reasoning effort 以及兼容性相關字段到 model profile。

配置項（均可選）¶

README 示例：在插件 config 中設置 freeOnly: true、minContextWindow: 64000，並在 excludeModels 中列出 openrouter/auto。

安裝與啓用¶

DSH 生態採用「一切皆插件」；插件目錄頁在 skillhub.cn，與 DeepSeek / 幻方無官方從屬關係，安裝前宜自行查看 GitHub 源碼與 MIT 許可證。插件以當前 dsh 進程權限運行，會訪問憑證與設置服務。

1、按 profile 安裝¶

<profile> 指 $DSH_HOME/profiles/<name> 下的 profile 目錄名；實際使用的每個 profile 都應單獨安裝。

dsh plugin --profile <profile> add dsh-openrouter-sync-models

常用 shipped profile 示例（摘自 README）：

dsh plugin --profile web add dsh-openrouter-sync-models
dsh plugin --profile headless add dsh-openrouter-sync-models
dsh plugin --profile sdk add dsh-openrouter-sync-models

desktop profile 需通過 Electron 應用的 Plugins 頁面或桌面版自帶的 dsh 安裝；npm CLI 對 desktop 拒絕插件管理。自定義 profile 可先用 dsh --profile <name> --from-default-profile web 初始化，再執行上述 add 命令。

若 profile 未啓用 settings 或 credentials 服務，插件仍會加載，但同步不會激活。

本地開發包路徑安裝（README 示例）：

pnpm install
pnpm run build
dsh plugin --profile <profile> add file:~/projects/mine/dsh-openrouter-sync-models

package.json 要求 Node ^22.19 || >=24，DSH >=0.2.1-rc.5 <0.3.0。

2、保留 OpenRouter 路由骨架¶

插件只維護 api 與 models；路由 id 與 provider 塊由用戶配置，例如：

- id: llm-pi-ai
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      openrouter:
        apiKeyEnv: OPENROUTER_API_KEY
        # api and models are maintained by dsh-openrouter-sync-models

3、提供 OpenRouter API Key¶

通過 harness 憑證存儲、環境變量或 profile 憑證層配置 OPENROUTER_API_KEY（或與路由、apiKeyEnv 覆蓋項一致的變量名）。

典型用法¶

先做路由與密鑰配置，再做 profile 級插件安裝。經過上面的步驟後，首次啓動會拉取目錄並 patch 設置；之後每 6 小時（或自定義 intervalHours）自動刷新。需要僅免費模型或更大上下文窗口時，在插件條目下增加 config 覆蓋即可，無需手改整份 models 數組。

插件條目形態示例（README）：

- id: openrouter-sync-models
  name: dsh-openrouter-sync-models
  config:
    freeOnly: true
    minContextWindow: 64000
    excludeModels:
      - openrouter/auto

適用場景與注意¶

適合：長期用 DSH + OpenRouter、希望模型列表跟官方目錄走、且依賴賬號 preset 的開發者；希望在 web、headless、SDK 等多 profile 下統一同步策略的團隊。

注意：同步寫回的是活動 profile 的設置 patch，過濾規則過嚴會導致列表變短（README 稱默認策略下 2026-11-02 某次認證樣本約 416 條目錄經篩選後約 305 個模型，含 preset，具體數量隨 OpenRouter 與賬號變化）。無密鑰時默認不同步，避免誤刪 preset。安裝第三方插件前請審閱 GitHub 倉庫 源碼與依賴聲明。

結尾¶

dsh-openrouter-sync-models 把 OpenRouter 認證目錄、定時與密鑰觸發的同步、以及 DSH 原生的 settings mutate 與 HMR 串在一起，減少手工維護 models 的負擔。更多信息見目錄頁 skillhub.cn/plugins/m1khal3v/dsh-openrouter-sync-models 與 GitHub：m1khal3v/dsh-openrouter-sync-models。