Introduction

The llm-pi-ai provider for DeepSeek Harness (DSH) uses static snapshots bundled in @earendil-works/pi-ai, which are not updated automatically. When new models are released on pi.dev, local DSH cannot retrieve them in real time. The dsh-pi-catalog-sync plugin synchronizes the live pi.dev model catalog into DSH provider routing through the official settings API, resolving the delayed model list problem.

Feature Overview

The plugin focuses on syncing the pi.dev model catalog into DSH. Its core capabilities include:

  1. Official API synchronization: It reads and writes model configuration through DSH’s official settings API, without patching source code.
  2. Mixed protocol support: For cross-protocol routing such as OpenRouter (supporting both anthropic-messages and openai-completions), it can write new models using companion routes without breaking existing routes.
  3. CLI and Web control: It provides CLI commands and a Web UI panel, supporting manual triggering, dry-run preview, and scheduled refreshes.
  4. Intelligent filtering: It automatically skips routes with modelOverrides and only syncs routes present in the pi.dev catalog.

Installation and Enablement

Install it through DSH’s plugin system. After installation, the plugin is recorded in ~/.dsh/profiles/web/package.json and leaves traces only in the settings namespace.

dsh plugin add <repo path or package name>

Configuration

Configure the plugin’s sync strategy in ~/.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
Configuration Description
managedRoutes Specifies routes to sync; if empty, routes are auto-discovered.
mixedProtocolStrategy companion: new models go to companion routes; route-api: take over in the original route (changes protocol); skip: report only.
companions Defines companion source, target route, protocol, and credentials.
keepBuiltinOnly Keeps models removed on pi.dev, preventing models from disappearing unexpectedly.
dryRun Whether to compute only without writing.
intervalMinutes Periodic refresh interval; 0 means run once after startup.

Usage

After installing and configuring, use it as follows:

  1. CLI synchronization:
    Run DSH commands to synchronize or preview.
    /pi-catalog-sync
    /pi-catalog-sync --dry-run

Report example:

    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
  1. Web UI control:
    Navigate to Settings -> Models in the DSH Web interface. You will see the corresponding pi.dev catalog sync panel. The panel displays the trigger, time, and new/builtin model counts for each route in each sync round, and provides “Preview” and “Sync Now” buttons.

How It Works

The plugin’s workflow consists of four steps:

  1. Fetch catalog: Get the full catalog from pi.dev/api/models, with support for ETag/304 caching.
  2. Protocol detection: Analyze the route protocol. Routes with only one API are synced in place; mixed routes spanning multiple protocols (such as OpenRouter) use the companion route strategy.
  3. Translation and mapping: Map pi.dev model data into a format writable by DSH settings, handling field alignment, thinkingLevelMap derivation, and sanity checks such as non-positive integers.
  4. Write settings: Write into the llm-pi-ai namespace through settings.mutate, only writing changed parts, and retry once on conflict.

Known Limitations

  1. Environment variable dependency: When using companion routes, the corresponding API Key must be configured in environment variables (for example, OpenRouter requires OPENROUTER_API_KEY).
  2. Configuration conflict: If a route’s llm-pi-ai configuration contains non-empty modelOverrides, that route is skipped and explicitly reported; user configuration is not overridden.
  3. Catalog scope: Only routes present in the pi.dev catalog are processed; routes not in the catalog are not processed.
  4. Single protocol limitation: DSH models entries do not support per-model api fields, so new models on mixed-protocol routes must be handled through companion routes and cannot be written directly to the original route.

Maintenance and Ecosystem