前言¶
在 DSH 裏選 provider、換模型時，列表裏經常出現和路由 ID 幾乎一樣的字符串：分組標題、設置頁裏的「配置提供方」、模型下拉項都混在一起，可讀性很差。若在 Cordis patch 或 config 裏逐條改顯示名，還要面對 llm-pi-ai 裏 models 整體替換、modelOverrides 與 models 互斥、以及部分內置路由 provider 名硬編碼等限制，維護成本偏高。
下面介紹社區插件 dsh-model-names（維護者 KouzakiUmi，分類：客戶端）。它用一份全量命名數據庫，在載入時按當前環境裏實際存在的 provider 與模型改寫 UI 上的展示字符串，不動模型 ID、路由、憑據與請求體。
這是什麼¶
dsh-model-names 是 DSH 客戶端側插件：內置 provider / 模型顯示名的映射數據，運行時包裝 ctx.llm 的目錄讀取方法，隻影響用戶看到的名稱。
- 改的是「用戶看到的」provider / 模型顯示名。
- 不改 config、不改 patch 裏的路由與模型定義、不改發出的 LLM 請求。
社區目錄頁：KouzakiUmi/dsh-model-names。源碼與說明：GitHub - KouzakiUmi/dsh-model-names。
核心機制¶
插件主要由三部分組成（見倉庫 README）：
data/model-names.json：全量命名數據庫。由scripts/build-catalog.mjs從宿主內置的 pi-ai provider / model 目錄生成，併合並 DSH 自帶路由；sourceVersion記錄上游目錄版本。條目是模型 ID 與可讀顯示名的映射，隨上游目錄更新，文檔不固定數量。lib/index.js：載入時包裝ctx.llm的目錄讀取，僅對當前環境裏已有的 provider 與模型做映射：
| 被包裝的方法 | 改寫的展示字段 | 影響面 |
|---|---|---|
listProviders() |
provider.name |
模型選擇器裏的 provider 分組標題 |
listConfigurableProviders() |
displayName |
設置頁「配置提供方」 |
listModels(provider) |
model.name |
模型選擇器 / 設置頁的模型列表 |
數據庫裏沒有的 id 原樣返回；未啓用的 provider 不會被激活（本來就不在目錄裏）。路由 id、憑據、模型集合、請求與會話記錄都不受影響。
cordis.patch.yml：只insert本插件自己一行，不寫任何 provider / 模型配置。
爲什麼不在 patch 裏改名¶
README 說明：llm-pi-ai 的 models 是整體替換（會收窄模型集合、丟掉未照抄的默認值）；modelOverrides 只對已在 config 裏聲明的路由生效，且與 models 互斥；內置 DeepSeek 兩條路由的 provider 顯示名更是硬編碼，config schema 裏沒有對應字段。顯示層映射繞開這些限制，也免去爲每條路由單獨維護 config。
邊界與行爲¶
dsh-codex-connect的模型名、內置 DeepSeek 兩條路由的 provider 名：若數據庫有對應條目會被映射。codex 若走自己 RPC 報告的目錄、且不經過ctx.llm.listModels，則此處覆蓋不到。- 搜索、選擇、提交仍按 id 進行，只改展示字符串。
命名數據庫如何更新¶
倉庫 .github/workflows/update-catalog.yml 每週一 02:13 UTC 檢查 npm 上最新的 @earendil-works/pi-ai，也可在 Actions 裏手動運行並指定精確版本。工作流下載該版本包、讀取 provider / model 目錄；對新增且上游缺名或名稱仍等於 ID 的條目，可調用配置的 OpenAI-compatible Chat Completions API 生成候選名。已有人工命名會在上游仍缺名或名稱仍爲 ID 時保留。
工作流只創建 automation/update-provider-model-catalog 分支和 PR，不直接改主分支或發 Release。除配置變量與 Secret 外，需在倉庫 Settings → Actions → General 允許 GitHub Actions 創建 Pull Request。
| 名稱 | 類型 | 內容 |
|---|---|---|
MODEL_API_URL |
Variable | 完整 Chat Completions URL，例如 https://api.example/v1/chat/completions |
MODEL_API_MODEL |
Variable | 服務商支持的模型 ID |
MODEL_API_KEY |
Secret | 模型 API 密鑰 |
API 需返回 OpenAI-compatible 格式，且在 choices[0].message.content 中爲 JSON：{"items":[{"key":"provider:example","name":"Example Provider"}]}。工作流會拒絕缺失、重複、額外或仍等於 ID 的結果；API 失敗時不創建更新 PR。若某次上游更新沒有未命名條目，構建不需要模型 API；首次運行會處理數據庫裏仍等於 ID 的條目，因此應先配好上述三項。
手動改字與本地重建¶
- 在
scripts/build-catalog.mjs維護PROVIDER_DISPLAY_NAMES/EXCEPTIONS，避免直接改自動生成的data/model-names.json。 - 本地重建：
node scripts/build-catalog.mjs --pi-ai <pi-ai 包目錄>
--enrich 會用環境變量裏的模型 API 爲未命名條目生成候選名；--check 比較並在過期時以非零狀態退出。
- 審覈生成結果後再提交。插件數據庫變更後需重啓 DSH NEXT（Host 插件代碼/數據變更不熱加載）。
安裝與啓用¶
從 npm 安裝（命令來自倉庫 README）：
dsh plugin --profile <profile> add dsh-model-names
版本標籤觸發的發佈 CI 會校驗並構建安裝包，同時發佈到 GitHub Release 和 npm。
若使用本地插件目錄，README 還給出了：
dsh plugin add <插件目錄絕對路徑>
安裝前建議自行查看源碼與許可證（package.json 中爲 MIT）。插件在當前 dsh 進程權限下運行，與任何社區插件一樣，啓用前應確認其只做 UI 層展示映射、符合你的安全預期。
典型用法¶
對最終用戶而言，安裝並重啓 DSH NEXT 後無需額外配置：打開模型選擇器或設置裏的 provider / 模型列表，即可看到數據庫覆蓋後的可讀名稱；未在庫中的 id 仍顯示原樣，行爲與 README 描述一致。
維護者或貢獻者若需修正顯示名或跟進上游 pi-ai，按上一節在 build-catalog.mjs 裏維護例外並重建 catalog，或通過倉庫 Actions 與 PR 流程更新 model-names.json。
適用場景¶
- 希望模型選擇器、設置頁 provider 分組與模型列表統一、可讀，又不想動路由與請求。
- 接受「只改展示、id 不變」的邊界，且瞭解 codex 等特殊路徑可能不完全走同一套
listModels包裝。
不適合指望通過本插件改模型 ID、增刪路由、改憑據或 patch 裏模型集合的場景——這些都不在插件設計範圍內。
結尾¶
dsh-model-names 用全量映射 + 運行時包裝 ctx.llm 目錄 API，在 DSH 客戶端側統一 provider / 模型的顯示名，避開 patch/config 改名的結構性限制，且明確不動路由與請求。需要安裝命令與邊界說明時，以 README 爲準。
