dsh-pi-catalog-sync

前言¶

DeepSeek Harness (DSH) 的 llm-pi-ai provider 使用的是打包在 @earendil-works/pi-ai 裏的靜態快照，這些快照不會自動更新。當 pi.dev 上架新模型時，本地的 DSH 無法實時獲取。dsh-pi-catalog-sync 插件通過官方的 settings 接縫，將 pi.dev 的實時模型目錄同步到 DSH 的 provider 路由中，解決模型列表滯後的問題。

功能概述¶

該插件專注於將 pi.dev 的模型目錄同步至 DSH，核心能力包括：

官方接口同步：不通過源碼補丁，直接通過 DSH 官方的 settings 接口讀寫模型配置。
混合協議支持：針對 OpenRouter 等跨協議路由（如同時支持 anthropic-messages 和 openai-completions），支持使用伴生路由來寫入新模型，而不破壞原路由。
命令行與 Web 控制：提供 CLI 命令和 Web UI 面板，支持手動觸發、預覽（dry-run）以及定時刷新。
智能過濾：自動跳過帶有 modelOverrides 的路由，僅同步 pi.dev 目錄中存在的路由。

安裝與啓用¶

通過 DSH 的插件系統安裝。安裝後，插件會在 ~/.dsh/profiles/web/package.json 中記錄，並僅在 settings 命名空間中留痕。

dsh plugin add <repo path or package name>

配置說明¶

在 ~/.dsh/settings.yaml 中配置插件的同步策略。

pi-catalog-sync:
  # 空 = 自動使用 DSH 已知且 pi.dev 有目錄的路由
  managedRoutes: []
  # companion | route-api | skip
  mixedProtocolStrategy: companion
  # 伴生路由定義
  companions:
    - source: openrouter
      route: openrouter-live
      api: openai-completions
      baseURL: https://openrouter.ai/api/v1
      apiKeyEnv: OPENROUTER_API_KEY
  keepBuiltinOnly: true
  forceMaxReasoningEffort: false
  dryRun: false
  intervalMinutes: 240
  startupDelaySeconds: 10
  catalogTimeoutMs: 30000

配置項	說明
`managedRoutes`	指定要同步的路由；留空則自動發現。
`mixedProtocolStrategy`	`companion`：新模型進伴生路由；`route-api`：在原路由接管（會改變協議）；`skip`：僅報告。
`companions`	定義伴生路由的來源、目標路由、協議和憑證。
`keepBuiltinOnly`	保留 pi.dev 已移除的模型，防止模型憑空消失。
`dryRun`	是否僅計算不寫入。
`intervalMinutes`	週期刷新間隔，0 表示僅在啓動後運行一次。

使用方式¶

安裝並配置完成後，可以通過以下方式使用：

CLI 同步：
在 DSH 中執行命令進行同步或預覽。

    /pi-catalog-sync
    /pi-catalog-sync --dry-run

報告示例：

    pi.dev catalog: 39 routes, etag W/"1a2b"
    managed routes: openrouter, zai-coding-cn
    openrouter: mixed-protocol → companion
      pi.dev 377 · builtin 366 · new 23
      companion openrouter-live (openai-completions) wrote 23 models

Web UI 控制：
進入 DSH Web 界面的 Settings -> Models，會看到對應的 pi.dev 目錄同步面板。面板顯示每輪同步的觸發者、時間、各路由的新增/內置模型數量，並提供“預覽”和“立即同步”按鈕。

工作原理¶

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

獲取目錄：從 pi.dev/api/models 獲取全量目錄，支持 ETag/304 緩存機制。
協議判定：分析路由協議。僅有一種 API 的路由原地同步；跨多種協議的混合路由（如 OpenRouter）則啓用伴生路由策略。
翻譯轉換：將 pi.dev 的模型數據映射爲 DSH settings 可寫的格式，處理字段對齊、thinkingLevelMap 推導以及非正整數等衛生門檢查。
寫入設置：通過 settings.mutate 寫入 llm-pi-ai 命名空間，僅寫入變化部分，遇到衝突時重試一次。

已知限制¶

環境變量依賴：使用伴生路由時，必須在環境變量中配置對應的 API Key（如 OpenRouter 需要 OPENROUTER_API_KEY）。
配置衝突：若某路由的 llm-pi-ai 配置中包含非空的 modelOverrides，該路由將被跳過並明確報告，不會覆蓋用戶配置。
目錄範圍：僅處理 pi.dev 目錄中存在的路由，不處理未在目錄中的路由。
單協議限制：DSH 的 models 條目不支持 per-model 的 api 字段，因此混合協議路由上的新增模型必須通過伴生路由處理，不能直接寫入原路由。

維護與生態¶

作者：jiawei322
許可證：MIT
倉庫：https://github.com/jiawei322/dsh-pi-catalog-sync
分類：模型推理