前言¶

DeepSeek Harness (DSH) 生態奉行“一切皆插件”的理念。在使用 DSH 時，配置 OpenAI 兼容的主機（包括官方 API、中轉網關或本地推理服務）通常需要手動維護模型列表、定價策略和推理參數。

Model Catalog 插件解決了這個重複勞動。它通過探測目標主機的端點，自動拉取模型信息、定價和能力，並進行歸一化處理，最終生成可直接加載的配置文件。

插件定位¶

• 名稱: model-catalog
• 作者: JohnXu22786
• 分類: 模型推理
• 許可證: MIT
• 核心價值: 自動發現、歸一化配置、交互式生成

安裝與啓用¶

在 DSH 中安裝該插件，使用以下命令：

dsh plugin --profile demo add github:JohnXu22786/model-catalog

如果需要移除，可以使用：

dsh plugin --profile demo remove model-catalog

核心功能¶

該插件包含以下核心能力：

• 主機類型自動檢測: 自動識別標準兼容、豐富元數據、額度計費、能力標誌代理、Ollama 或 vLLM 等不同類型的主機。
• 歸一化的模型記錄: 輸出的模型記錄包含 ID、上下文窗口、最大輸出、定價族（含緩存讀寫/內部推理價格，單位爲 USD/1M）、能力標誌和來源溯源。
• 定價來源鏈: 按照主機端點 > 用戶覆蓋 > 外部價格鏡像 > 內置默認表的優先級填充定價信息。
• 內置默認表: 針對官方 API（如 DeepSeek）內置了默認的事實和定價回退表。
• 能力探測驗證: 可選地發送最小請求，探測主機元數據中缺失的能力（如工具調用、結構化輸出、流式傳輸）。
• 緩存和併發安全: 分類、探測和鏡像結果會被緩存；文件鎖和原子寫入防止併發進程損壞緩存。
• 交互式配置生成: 通過 pick 命令列出模型和價格，供用戶選擇後生成 dsh 配置片段。
• 自包含: 包含清單、入口工廠和工具接口，可被 Harness 直接加載。

工作流程¶

插件的工作流程分爲以下步驟：

1. 主機檢測: 探測端點，根據 /models、/v1/models、/api/pricing、/model/info 等不同響應判斷主機類型。
2. 拉取: 根據類型解析模型列表、定價和參數。
3. 歸一化: 進行單位轉換（如 USD/Token 轉 USD/1M）、源鏈補全和別名解析。
4. 能力探測: （可選）探測缺失的能力並緩存。
5. 輸出: 生成完整目錄、dsh 配置片段和人類可讀報告。

使用示例¶

使用前需滿足 Node.js >= 21（無運行時依賴，僅構建需要 TypeScript）。

1. 安裝依賴並構建：

    npm install
    npm run build

2. 發現官方 API：

    export DEEPSEEK_API_KEY=sk-xxx
    node dist/src/main.js discover --base-url https://api.deepseek.com

3. 發現本地 Ollama：

    node dist/src/main.js discover --base-url http://127.0.0.1:11434 --probe always

4. 發現網關（需指定環境變量）：

    node dist/src/main.js discover --base-url https://gateway.example.com --api-key-env GATEWAY_KEY

5. 交互式選擇模型：

    node dist/src/main.js pick --base-url https://api.deepseek.com

技術細節¶

• 輸出文件: 運行後會在 out/ 目錄下生成三個文件：
  • catalog.json: 完整目錄（schema: model-catalog/v1）。
  • dsh-models.json: dsh 配置片段（schema: dsh/models/v1）。
  • report.md: 人類可讀報告。
• 主機類型: 插件支持 bare（標準兼容）、augmented（豐富元數據）、quota（額度計費）、flag（能力標誌）、ollama 和 vllm 等類型。
• 定價單位: 所有定價均歸一化爲 USD per million tokens (USD/1M)。
• 容錯: 如果所有端點探測均失敗，插件會報錯。可通過 --kind 手動指定主機類型。

結尾¶

Model Catalog 插件通過自動化和標準化，簡化了 DSH 環境下的模型配置流程。

• GitHub 倉庫: https://github.com/JohnXu22786/model-catalog
• 目錄頁面: https://www.skillhub.cn/plugins/JohnXu22786/model-catalog