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
分类：模型推理