前言¶

在使用 DeepSeek Harness (DSH) 時，大多數 provider 的 /v1/models 接口僅返回模型 ID，缺少 name、contextWindow、maxTokens、reasoningEfforts 和 input 等關鍵能力字段。這導致模型列表顯示不完整，增加了手動配置的負擔。本插件旨在解決這一痛點，通過讀取本地緩存的 models.dev 目錄，自動補全這些缺失字段。

介紹¶

dsh-model-parameters 是一個 DSH 插件，用於在設置寫入（包括模型同步）時，檢測並補全缺失的模型元數據。它由 fonlan 維護，遵循 MIT 許可證。

核心功能¶

• 自動補全元數據：自動從 models.dev 目錄獲取並填充顯示名稱、上下文窗口、最大輸出 token、推理檔位和輸入模態。
• 智能觸發機制：監聽 settings/updated 命名空間。任何設置變更（如新同步 provider、編輯 provider 卡片、手動編輯 settings.yaml）都會觸發 reconcile。插件啓動時也會對現有配置執行一次全量回填。
• 確定性匹配邏輯：支持 Provider 映射（providerMap）、精確 ID 匹配、官方優先級（officialProviders）。對於裸 ID，支持對最後一段路徑段做大小寫不敏感匹配。
• 填充式更新：只補全缺失字段，絕不覆蓋已有的值。reconcile 天然是 fill-only 的，不會造成循環寫入。
• 設置卡片與刷新：提供可視化的配置界面，包括總開關、逐字段開關、TTL 配置、目錄刷新按鈕以及補全報告。

匹配邏輯¶

插件在匹配 models.dev 目錄條目時，遵循以下優先級：
1. Provider 映射：優先使用顯式的 providerMap，其次同 ID 匹配。
2. 完整 ID 精確匹配：已帶 vendor/ 前綴的 dsh 模型 ID 與完全相同的 models.dev key 匹配。
3. 官方優先級：在衝突時，優先選擇 officialProviders（如 deepseek、openai、anthropic 等）的條目。
4. 完整性：兩個 limit 都已知的條目優於部分已知的。
5. Provider ID 字母序：作爲穩定的兜底策略。
裸 ID（如 qwen3.7-max）會對最後一段路徑段做大小寫不敏感匹配（如 Qwen/Qwen3.7-Max）。

補全字段¶

插件會將 models.dev 的以下字段映射到 DSH 模型配置：
* name：對應 models.dev 的 name。
* contextWindow：對應 limit.context。
* maxTokens：對應 limit.output。
* reasoningEfforts：對應 reasoning_options[type=effort].values，過濾爲恆等字典（如 {high:"high", max:"max"}）。
* input：對應 modalities.input，過濾爲 text 或 image。

目錄緩存與更新¶

• 緩存位置：~/.dsh/model-parameters/catalog.json（約 4 MB）。
• 更新機制：默認緩存 TTL 爲 7 天。超過 TTL 後，下一次 reconcile 時惰性刷新。
• 容錯策略：拉取失敗時保留上次成功的緩存；完全沒有緩存時插件不執行補全，直到刷新成功。
• 手動刷新：設置卡片提供“立即更新目錄並補全”按鈕，可強制刷新並顯示上次更新時間與新鮮度。

安裝與啓用¶

通過 dsh plugin 命令安裝（請將 --profile web 替換爲你的實際 profile 名）：

dsh plugin --profile web add @fonlan/dsh-model-parameters

安裝後，在 DSH 設置 → 插件 → 插件配置 中，展開“模型參數補全 / Model Parameters”卡片進行配置。

適用場景與注意¶

• 適用場景：provider 列表信息不全，需要依賴 models.dev 目錄獲取元數據的場景。
• 權限注意：插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證（MIT）。
• 行爲注意：補全是填充式（fill-only），不會覆蓋已存在的值；目錄中無匹配的模型（如本地網關模型）保持原樣，並在補全報告中列爲 unmatched。

結語¶

該插件通過自動化元數據補全，降低了智能體開發的配置門檻。更多詳情與源碼可查看 GitHub 倉庫。