前言¶

在 DeepSeek Harness（DSH）裏，若你通過 @deepseek-ai/dsh-llm-pi-ai 接入 OpenRouter、自建網關等 OpenAI / Anthropic 兼容端點，模型下拉列表通常來自 pi-ai 安裝包內的靜態快照，而不是向端點發起 GET /models。快照裏帶有 contextWindow、maxTokens 等 listing 接口往往不返回的字段，這是有意爲之；代價是新發布的模型不會自動出現，手寫 models 也會一直停在當初錄入的版本。社區裏關於「列表陳舊、與線上一致性差」的討論已有多條（例如 deepseek-harness 倉庫 discussions #3816、#5306、#5691、#4685）。dsh-llm-pi-ai-live 走另一條路：不改寫適配器內部的 discover 邏輯，而是通過官方 settings、credentials、llm、tools 接縫，向各路由的 live 端點拉取模型 id，合併 pi-ai 目錄元數據，並以追加方式寫回配置。

這是什麼¶

dsh-llm-pi-ai-live 由 WeatherWind 維護，歸類爲聯網工具類 DSH 插件（當前 GitHub 星標爲 0）。一句話定位：爲使用 llm-pi-ai 的可配置 provider 路由，定期或按需查詢端點上的模型列表，把新 id 追加進路由的 models 配置，並在失敗時保留原配置不動。

它不 patch 核心包；也不替換 llm-pi-ai 自帶的 model discovery（外部插件無法註冊重複的 discovery）。它解決的是「配置裏的模型表與 endpoint 實際對外公佈的 id 長期脫節」這一問題。

核心功能¶

一次刷新（啓動延遲後、定時週期內，或通過工具觸發）大致分四步：

1. Plan — 通過 llm.listConfigurableProviders() 讀取可配置 provider 目錄，得到每條路由對應的 settings 命名空間與路徑。命名空間來自 profile 裏 loader 的 entry id（例如 include:llm-pi-ai），因此不會寫死插件名；若 profile 未加載 pi-ai 相關條目，插件不會對錯誤命名空間生效。
2. Interrogate — OpenAI 方言：GET {baseURL}/models（Bearer）；Anthropic Messages 方言：GET {root}/v1/models?limit=1000（x-api-key 與 anthropic-version）。兩種回覆歸一化爲同一候選結構。
3. Merge — 以 live 返回的 id 決定「有哪些模型」；name、contextWindow、maxTokens、input 優先從已安裝的 pi-ai catalog 補齊，端點上報的容量作後備。
4. Persist — 經 settings.mutate() 寫入，寫前讀 revision，寫後確認值已落地。

行爲保證（README 原文要點）：

• 僅追加：已有條目按引用、順序原樣保留；新 id 追加在末尾；端點不再公佈的 id 不會被刪除。
• 無法完整理解則跳過：若存儲的 models 不是可處理的列表（例如字符串、或缺少 id 的項），整條路由跳過並在報告中說明，而不是用猜測覆蓋。
• 失敗不改配置：5xx、超時、非 JSON、協議無法解析或寫入被拒，路由保持原樣，並在報告中體現。
• 不寫推斷性字段：只寫 id、name、contextWindow、maxTokens、input；不推斷 reasoningEfforts、compat。

可選能力 reasoning 規則（cordis.patch.yml 內 reasoning 塊）：對 pi-ai catalog 未覆蓋、且路由上未聲明 reasoningEfforts 的第三方模型，按 provider / model 的 glob 規則補全思考檔位映射；已聲明或 catalog 已知條目不會被改動，規則寫錯檔位會在日誌中按索引拒絕。

工具 refresh_model_catalog：可選參數 provider 限定單條路由；供智能體在不發版、不重啓的情況下拉一次新模型。

安裝與啓用¶

插件版本 0.1.0，許可證 MIT，Node 引擎要求 ^22.19.0 || >=24（見 package.json）。安裝步驟以倉庫 README 爲準：

# 1) build
cd dsh-plugins/dsh-llm-pi-ai-live
npm install && npm run verify && npm run build

# 2) add to the target profile (local path uses link:)
dsh plugin --profile <profile> add link:$PWD

# 3) restart DSH

也可將倉庫中 cordis.patch.yml 的 insert 塊合併進 <DSH_PROFILE_DIR>/cordis.patch.yml。

首次建議開啓 dry run。 dryRun: true 時只計算並打日誌，不寫 settings。README 給出的 OpenRouter 實機啓動日誌示例：

[live-catalog] mounted (first pass in 0ms, periodic refresh off, dry run)
[live-catalog] openrouter: dry run — would add 464 model(s): openai/gpt-6.1-sol-pro, ...
[live-catalog] scheduled: 1 updated, 464 added, 0 failed, 0 skipped in 932ms

確認報告合理後再將 dryRun 設爲 false。

配置項均在 cordis.patch.yml 中有默認值說明，常用字段如下：

第三方網關若需爲新型號聲明 reasoningEfforts，可在 patch 中啓用 reasoning.enabled 與 rules（provider / model glob + efforts 或 efforts: false），詳見 README 「Declaring reasoning effort for third-party models」一節。

典型用法¶

1. 在目標 profile 按上文完成 build 與 dsh plugin add link:$PWD，重啓 DSH。
2. 保持 dryRun: true，觀察日誌裏各路由「would add」的 id 是否與你的 endpoint 一致。
3. 關閉 dry run，按需調整 startupDelayMs、intervalMs，或用 exclude: ['某路由'] 跳過本地或不可 listing 的 provider。
4. 發佈新模型後，讓 Agent 調用 refresh_model_catalog，必要時傳入 provider 縮小範圍，無需改 yaml 再重啓。

適用場景與注意¶

適合誰： 已用 DSH llm-pi-ai 接 OpenAI / Anthropic 兼容 API，且希望配置中的模型表與線上一致、又不想手工維護幾百個 id 的開發者與運維。

務必知曉：

• 插件以 當前 DSH 進程權限 運行，會向各路由配置的 base URL 發起聯網請求並使用已有 credentials；安裝前應閱讀源碼與 MIT 許可證，確認 endpoint 與密鑰歸屬可信。
• 它 不能 替代 UI 裏「從 provider fetch models」若與內置 discovery 衝突的那條路徑；它改的是 持久化在 settings 裏的 models 列表。
• 列表 只增不減；若要從配置裏下線某 id，仍需人工編輯 settings。
• DSH 生態強調「一切皆插件」；社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-llm-pi-ai-live 在不動核心適配器的前提下，用官方 settings 接縫把 llm-pi-ai 路由的模型表與 live listing 對齊，並保留 catalog 元數據與保守的寫入策略。目錄頁：https://www.skillhub.cn/plugins/WeatherWind/dsh-llm-pi-ai-live；源碼與完整說明：https://github.com/WeatherWind/dsh-llm-pi-ai-live。