前言¶
在 DeepSeek Harness（DSH）裏接 LLM 時，模型列表往往來自安裝目錄裏的 pi-ai 靜態 catalog。上游 pi-ai 發佈新版本後，新模型不會自動出現在你的路由裏；若手工改安裝樹或 ASAR，升級 DSH 或 pi-ai 時容易衝突，也難以回滾。
下面介紹社區插件 dsh-model-refresh（維護者 KouzakiUmi，分類：模型推理）。它把「從 pi-ai 上游補缺、按 provider 管控、安全寫入與回滾」做成可獨立升級的 DSH bundle，目標不是把網上所有模型名塞進選擇器，而是補齊當前 provider 真正可用、且能正確物化的新模型。插件當前版本 v0.7.2，MIT 許可證；手動模型相關能力對照本機 DSH core 0.2.1-alpha.1 的 configEditor 與 pi-ai 接口開發，其它核心版本需自行覈對兼容性。
這是什麼¶
dsh-model-refresh 是帶 dsh.bundle.patch 的 DSH 插件包，displayName 爲「模型目錄刷新（pi-ai 上游 → 路由）」。主數據源是 npm 上最新發布的 pi-ai 模型目錄；models.dev 僅作可選備份源，默認關閉。自動發現與「是否寫入安裝目錄」分離：首次加載默認不寫安裝目錄，也默認不啓用各 provider 的 catalog 寫入，需在設置頁顯式打開。
運行時狀態默認位於 ~/.dsh/model-refresh/state.json。真實 API 密鑰只應放在環境變量或 DSH credentials 服務中，配置裏只填憑據名稱。
核心功能¶
自動發現與證據規劃¶
- pi-ai 爲主源：啓動、定時或手動刷新時查詢 npm 最新 pi-ai 版本；僅版本變化時下載並校驗官方包完整性與 provider 文件散列。完整 catalog 緩存在狀態目錄；上游故障時保留舊緩存。
- 模型與服務可用性分開覈對：上游決定候選 ID、協議與能力；可選的 provider 官方清單隻提供本套餐「正向存在」證據。
GET /models成功不能證明套餐完整或推理已測通。 - 不猜字段：協議、上下文容量、輸出容量和聊天用途缺少證據的新模型進入待確認，不用鄰居數據猜測。
- 不污染原生目錄：已有模型的原生容量、image/reasoning 等不被外部舊數據覆蓋；只同步 pi-ai 中同一 provider、同一 model ID 的記錄。
- 刪除需負向證據：僅在你明確確認當前套餐爲權威全量清單（
complete: true）、響應無分頁/不完整跡象，且連續缺失確認並過寬限期（默認 24 小時 + 2 次）後，才計劃移除。失敗、缺 key、部分頁會中斷連續觀察。 - 寫入可選且可審計：catalog 寫入默認關閉；啓用後使用協調鎖、寫前 journal、修訂指紋和內容所有權校驗。回滾需證明當前內容與目錄修訂均匹配臺賬記錄。
設置頁與監控¶
設置頁展示發現、已應用、待確認、衝突、是否需要重啓消費進程，以及寫入權限狀態。可按 provider 開關、配置 keep / exclude 名單，並查看代理與全局開關。授權說明在獨立彈窗中，插件不代你執行提權命令。
手動增加模型與 DSH 配置編輯¶
在設置頁可手動增加模型，配置協議、端點、推理檔位與協議兼容參數，通過官方 configEditor 預覽、應用和撤銷，無需爲了試用新模型而改安裝目錄裏的 catalog。
當前可選協議包括 openai-completions、openai-responses、anthropic-messages。同一 provider 須使用相同協議與端點；覆蓋已有 provider 時保留原有模型、憑據及其它配置，並將 modelOverrides 合併進模型列表。聲明保存在 settings.manualModels，自動發現不會覆蓋。
簡要流程：
- 填寫 provider 名稱、模型 ID、顯示名、推理協議、根 URL、上下文與輸出容量等，點擊 保存模型聲明。
- 選擇 DSH 配置入口與目標 provider；憑據欄只填環境變量或 credentials 的名稱。
- 點擊 預覽配置變更，覈對後 應用到 DSH；需要恢復時用 撤銷此 provider 的插件變更。
應用只表示配置通過了 DSH 的編輯與加載流程，不表示端點、權限、工具調用或遠端推理已經驗證。
產物格式¶
啓用目錄寫入後，會在狀態目錄（或你配置的路徑）輸出 <route>.models.json、<route>.models.yml、<route>.diff.json，保留原文件名與 models 數組結構。catalog 是 pi-ai 的靜態 import，寫盤後需重啓消費 DSH 的進程纔會生效；插件不會自動重啓 DSH。
安裝與接入¶
倉庫是 bundle，推薦通過當前 DSH 版本支持的插件管理入口安裝；不要手工改 DSH 核心、ASAR 或包管理器維護的依賴。cordis.patch.yml 只插入 dsh-model-refresh，不會替用戶修改 provider 路由。
若從源碼做本地鏈接開發，README 給出的步驟是安裝依賴、構建客戶端並跑測試，再由目標 profile 的官方插件/本地鏈接流程加載該目錄（詳見 GitHub 倉庫）。Host 或 bundle 源碼變更後通常需要重載對應 DSH 消費進程。
快速配置¶
首次可複製 config.example.json 爲本地 config.json，或直接在設置頁保存。示例種子配置：
{
"intervalMinutes": 360,
"routes": [
{
"route": "opencode-go",
"enabled": false,
"keep": [],
"exclude": []
}
]
}
intervalMinutes 控制定時刷新間隔（示例爲 360 分鐘）。每個 route 可單獨 enabled，並用 keep / exclude 約束同步範圍。
環境變量¶
| 變量 | 用途 |
|---|---|
DSH_MODEL_REFRESH_STATE |
狀態路徑；默認產物也在狀態目錄 |
DSH_MODEL_REFRESH_CONFIG |
首次種子配置路徑 |
DSH_PI_AI_DATA_DIR |
當前 DSH 使用的 pi-ai dist/providers/data |
目錄優先從真實 DSH 消費入口解析 pi-ai；找不到時可設 DSH_PI_AI_DATA_DIR。
每 provider 官方清單（高級）¶
在設置頁或 settings.officialRoutes 中配置，例如：
{
"officialRoutes": {
"kimi-coding": {
"endpoint": "https://api.kimi.com/coding/v1/models",
"apiKeyEnv": "KIMI_CODING_API_KEY",
"auth": "bearer",
"protocol": "anthropic-messages",
"complete": false
}
}
}
要點：endpoint 是完整清單 URL，baseUrl 是推理根 URL；complete: false 時可用於正向發現，但不能據此刪模型。assumeChat 默認 false，無明確聊天類型元數據的官方新 ID 會進入待確認。
Host 提供 loopback Web API，例如 GET /plugins/dsh-model-refresh/status，以及 POST .../refresh、.../config、.../route（需同源、JSON，請求體有界）。
典型用法（建議順序）¶
- 通過 DSH 插件管理入口安裝 dsh-model-refresh，重載消費進程使 bundle 生效。
- 在設置頁爲需要的 route 啓用 provider，按需配置
keep/exclude與官方清單；確認是否開啓 catalog 寫入（首次默認關閉）。 - 執行手動刷新或等待定時任務，在界面查看待確認項並完成人工確認。
- 若寫入安裝目錄或產物文件，按設置頁提示重啓加載 pi-ai catalog 的 DSH 進程。
- 若只需改 DSH 運行時 provider 配置而不動 catalog，使用手動增加模型流程預覽並應用；驗證失敗時先撤銷再調整聲明。
適用場景與注意¶
適合：希望 pi-ai 上游新模型以可控方式進入 DSH 路由；需要按 provider 開關、待確認 gate、可回滾的目錄寫入；或希望通過 configEditor 安全地手工加模型而不改 ASAR/安裝樹。
務必注意：
- 插件以當前 DSH 進程權限運行；安裝前請閱讀 源碼與 README 及 MIT 許可證，自行評估是否滿足環境要求。
- 默認不寫安裝目錄、默認停用自動發現的 provider，避免無意擴大寫入範圍。
- 狀態從 v1/v2 遷移到 v3 時會備份舊文件；舊版臺賬不能證明所有權的歷史新增會進入保護列表，不會自動刪除。
- 同一安裝目錄建議只由一個狀態實例管理 catalog；更新 pi-ai 時宜停止插件消費者，避免競態。
- 社區目錄頁 skillhub.cn 上的條目 與 GitHub 倉庫由維護者發佈；DSH 生態強調「一切皆插件」，該目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-model-refresh 把 pi-ai 靜態目錄的補缺從「改安裝樹」拆成可升級的插件：上游以 pi-ai 爲準、寫入可關、刪除有寬限與證據鏈、手動模型走官方配置編輯。若你正在維護多 provider 的 DSH 部署，可以從設置頁的刷新與待確認流程開始，再按需打開 catalog 寫入或手動應用配置。
- 目錄頁：https://www.skillhub.cn/plugins/KouzakiUmi/dsh-model-refresh
- GitHub：https://github.com/KouzakiUmi/dsh-model-refresh
