dsh-plugin-custom-provider-enhancer

Readme

# DSH Custom Provider Enhancer

[![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-5B4CF0?style=flat-square)](https://github.com/AdamPlatin123/awesome-dsh-plugins)
[![Cordis 3.x](https://img.shields.io/badge/Cordis-3.x-blue?style=flat-square)](https://cordis.moe)
[![License: MIT](https://img.shields.io/badge/license-MIT-0B7285?style=flat-square)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%5E20.0%20%7C%20%5E22.0%20%7C%20%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
[![Verified Tests](https://img.shields.io/badge/verified-5%20tests-2EA44F?style=flat-square)](tests)

English | [简体中文](README.zh.md)

**DSH Custom Provider Enhancer** is an out-of-the-box DeepSeek Harness (DSH) / Cordis plugin designed for **Custom Model Providers** (e.g. OneAPI, NewAPI, OpenRouter, vLLM, Ollama, and OpenAI-compatible API gateways).

When discovering or saving models in the Web GUI, it automatically queries a 3000+ model database to populate **Context Window (`contextWindow`)**, **Max Output Tokens (`maxTokens`)**, **Multimodal Vision (`input: [text, image]`)**, and **Deep Thinking / Reasoning (`reasoningEfforts`)**.

---

## 📋 Table of Contents
- [Overview](#-overview)
- [Compatibility](#-compatibility)
- [Key Features](#-key-features)
- [Install](#install)
- [Configuration](#-configuration)
- [Quick Start](#-quick-start)
- [Permissions & Data Security](#-permissions--data-security)
- [Troubleshooting & Rollback](#-troubleshooting--rollback)
- [Development & Testing](#-development--testing)
- [License](#-license)

---

## 🎯 Overview

### What problem does it solve?
When users connect custom third-party gateways (e.g. OneAPI, NewAPI, vLLM, Ollama) to DeepSeek Harness, the standard `GET /models` discovery endpoint only returns raw model IDs (such as `gemini-3.7-flash`, `deepseek-v4-pro`, or `mimo-v2.5`). It omits critical runtime parameters:
- ❌ Missing context limits causes inaccurate token pressure metering or context overflows.
- ❌ Missing multimodal flags (`input: ['text', 'image']`) disables image uploads in the conversation interface.
- ❌ Missing reasoning levels (`reasoningEfforts`) hides the thinking intensity slider in chat.

### How does this plugin solve it?
1. **Auto Discovery & Specification Enrichment**: Intercepts `llm.discoverModels` and automatically fills correct context size and max output tokens.
2. **Vision & Thinking Auto-Injection**: Intercepts `llm.resolveModelInfo` and `settings.mutate` to automatically attach vision input and thinking levels both in runtime and in `settings.yaml` (`~/.dsh/settings.yaml`).
3. **Zero Official Interference**: Only affects custom third-party providers; native DeepSeek channels remain untouched.

---

## 🧭 Compatibility

| Environment | Supported Versions | Status |
| :--- | :--- | :--- |
| **DeepSeek Harness (DSH)** | `0.1.0-rc.1` ~ `mainline` | ✅ Verified (Runtime Compatible) |
| **Cordis Framework** | `^3.0.0` | ✅ Verified |
| **Node.js** | `^20.0.0 || ^22.0.0 || >=24.0.0` | ✅ Verified |
| **OS** | Linux, macOS, Windows | ✅ Cross-Platform |

---

## ✨ Key Features

- ⚡ **Zero-Config Automation**: Works right out of the box when adding custom providers in Web Settings.
- 📏 **Accurate Capacities**: Automatic 1M context for Gemini 3.7 Flash, 1000K for DeepSeek V4 Pro, 128K for GPT-4o, 256K for MiMo 2.5, etc.
- 👁️ **Automatic Vision Activation**: Unlocks image uploads and visual reasoning in Web chat for multimodal models (Gemini, Claude, GPT-4o, MiMo, Qwen-VL, etc.).
- 🧠 **Thinking Intensity Tiers**: Injects reasoning effort gears (`off`, `low`, `medium`, `high`, `max`) for reasoning models.
- 💾 **Dual-Layer Persistence**: Automatically writes clean parameters into `settings.yaml` on save, and patches legacy placeholder models in memory.
- 🛡️ **Fault-Tolerant & Offline Fallback**: Built-in 30+ core model definitions, local caching, timeout circuit-breaking, and fuzzy matching for dated model snapshots (`-20241120`).

---

## Install

As a standard DSH Profile Bundle, installation is one simple command:

```bash
dsh plugin --profile web add github:cinob/dsh-plugin-custom-provider-enhancer
```

> **Note**: As a Profile Bundle, the plugin automatically mounts and activates. There is **no need** to manually insert `custom-provider-enhancer` in `profiles/web/cordis.patch.yml`.

### Uninstallation

```bash
dsh plugin --profile web remove dsh-plugin-custom-provider-enhancer
```

---

## ⚙️ Configuration

Optional configuration in `$DSH_HOME/profiles/web/cordis.patch.yml`:

```yaml
- id: custom-provider-enhancer
  config:
    # Remote LiteLLM metadata catalog URL
    metadataUrl: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
    # Remote OpenRouter official model metadata URL
    openrouterMetadataUrl: https://openrouter.ai/api/v1/models
    # Request timeout in milliseconds (default: 6000ms)
    timeoutMs: 6000
    # In-memory cache TTL in milliseconds (default: 1 hour)
    cacheTtlMs: 3600000
    # Fallback context window when model is unknown (default: 128000)
    defaultContextWindow: 128000
    # Fallback max output tokens (default: 4096)
    defaultMaxTokens: 4096
```

---

## ⚡ Quick Start

1. Start DSH Web GUI (`dsh web`).
2. Go to **Settings ➔ Models ➔ Add Provider**.
3. Fill in your Base URL and API Key, then click **Fetch available models**.
4. Check desired models and click **Adopt**, then click **Save**.
5. All specifications (`contextWindow`, `maxTokens`, `input`, `reasoningEfforts`) are automatically configured and saved!

---

## 🔒 Permissions & Data Security

- **Network Access**: Only requests the user-specified custom endpoint `GET /models` and public model specification database (`github.com/BerriAI/litellm`).
- **Zero Credential Leaks**: API Keys are passed through standard authorization headers only during user-initiated discovery; keys are never logged, forwarded, or stored by this plugin.
- **Local Sandbox Safe**: Strictly operates in-process through Cordis service hooks (`ctx.llm`, `ctx.settings`); creates no subprocesses or arbitrary file modifications.

---

## 🛠️ Troubleshooting & Rollback

- **Changes not reflecting**:
  Ensure you click **Save** in Web Settings. If models were added prior to installing the plugin, opening Settings and clicking **Save** will auto-enrich them.
- **Rollback**:
  Run `dsh plugin --profile web remove dsh-plugin-custom-provider-enhancer`.

---

## 💻 Development & Testing

```bash
# Clone repository
git clone https://github.com/cinob/dsh-plugin-custom-provider-enhancer.git
cd dsh-plugin-custom-provider-enhancer

# Install dependencies
pnpm install

# Run automated tests
pnpm test

# Build distribution bundle
pnpm build
```

---

## 📄 License

[MIT License](LICENSE)