dsh-provider-passport

Readme

# DSH Provider Passport

[简体中文](README.zh-CN.md)

> Public preview. Independent community project; not affiliated with or endorsed by DeepSeek.

DSH Provider Passport finds request-dialect differences between a custom OpenAI Chat Completions endpoint and DeepSeek Harness **before the first real task fails**. It runs a bounded, review-first preflight, proposes only the compatibility fields supported by Harness, verifies the change through the real Harness LLM runtime, and keeps rollback available.

![A proposed profile applied and verified through DSH 0.1.2-alpha.4](docs/screenshots/08-alpha4-applied-and-verified.png)

## Why this exists

A generic OpenAI-compatible connectivity check can pass while Harness still fails because the endpoint rejects one of these request-shape choices:

- `developer` instead of `system`
- `max_completion_tokens` instead of `max_tokens`
- `store`
- `reasoning_effort`
- `stream_options.include_usage`

Harness already exposes the corresponding `compat` settings. The missing product layer is a safe way to discover the minimum settings, preview them, apply them to one model, verify the result through Harness, and recover if verification fails.

## Install the preview

Requires Node.js 22.19+ and a DeepSeek Harness Web profile.

```powershell
npx @deepseek-ai/dsh plugin --profile web add dsh-provider-passport@preview
npx @deepseek-ai/dsh web
```

If `dsh` is already available on your PATH, omit `npx @deepseek-ai/dsh` and use `dsh`.

Open **Settings → Plugins**, expand **Provider compatibility passport**, select a custom OpenAI Chat Completions model, review the request budget, and confirm the preflight.

The route must explicitly set `api: openai-completions`. When `api` is omitted, Harness may inherit a different wire protocol for each installed-catalog model; the public model metadata does not expose that resolved protocol, so the plugin excludes the route instead of guessing. Routes using Responses, Anthropic Messages, or another protocol remain out of scope.

To remove it:

```powershell
npx @deepseek-ai/dsh plugin --profile web remove dsh-provider-passport
```

## Safety and privacy contract

- Nothing runs in the background. Every preflight requires explicit confirmation.
- At most 10 fixed requests are sent, with at most 1 output token each and a 12-second per-request timeout.
- No user files, conversations, prompts, sessions, or tool data are used.
- Credentials and custom headers stay in memory and never enter reports or logs.
- The selected model receives only the smallest observed compatibility profile; other models are untouched.
- A route is eligible only when its editable settings explicitly declare `api: openai-completions`; ambiguous and other-protocol routes are shown as safely skipped.
- Proposals are restricted to `maxTokensField`, `supportsDeveloperRole`, `supportsStore`, `supportsReasoningEffort`, and `supportsUsageInStreaming`. Catalog-withheld fields are never configured.
- Cancellation never writes settings. A failed Harness verification automatically restores the previous settings.
- If Harness rejects a proposed field during its atomic settings validation, the plugin reports the refusal and leaves settings unchanged.
- **Copy redacted report** removes endpoint, model id, credentials, headers, request text, response bodies, and model output. Nothing is uploaded automatically.

Read the full [privacy design](PRIVACY.md) before testing a sensitive enterprise endpoint.

## Help validate the real-world need

This preview has deterministic and real-Harness runtime coverage. It is public so people can test their own third-party, enterprise, or self-hosted OpenAI-compatible endpoints without sharing credentials.

1. Run the preflight.
2. Click **Copy redacted report**.
3. Submit a [compatibility report](https://github.com/ArmyWas/dsh-provider-passport/issues/new?template=compatibility-report.yml).

Please never post an API key, authorization header, full private endpoint, proprietary prompt, or response body. See the [tester guide](docs/TESTER_GUIDE.md) for the evidence standard.

Questions, product ideas, and unclear results belong in [GitHub Discussions](https://github.com/ArmyWas/dsh-provider-passport/discussions).

## Current evidence

- 11 automated unit/contract tests cover redaction, protocol gating, offered-field restrictions, minimal proposals, cancellation, settings isolation, and runtime verification.
- The packaged plugin completes install → probe → apply → real-runtime verify → rollback on DSH `0.1.1-rc.2` (npm default at release time) and `0.1.2-alpha.4` (latest alpha at release time).
- A deterministic strict gateway reproduces three request-dialect failures that pass a generic compatibility control but fail under the default Harness request shape.
- The settings-card flow was manually audited in the real DSH Web UI, including cancellation and rollback.

The full product-discovery evidence is in the [opportunity report](docs/research/opportunity-report.html).

## Deliberate scope

This project does **not** replace:

- generic API, streaming, tool, or structured-output conformance tools such as [CompatCanary](https://github.com/CognizenOrg/compatcanary);
- model capability discovery;
- provider health monitoring;
- routing, fallback, or proxy adapters.

It owns only the last mile between a custom OpenAI Chat Completions endpoint and the request dialect generated by Harness.

This preview does not infer `/v1/responses`, Anthropic Messages, or vendor-specific routing from a failed Chat Completions request. A blocked result may mean the route speaks another protocol or depends on provider-managed behavior; the plugin reports that boundary and writes nothing. Multi-protocol discovery remains a separate research question so this plugin does not silently become a general conformance suite.

## Development

```powershell
npm test
npm pack --dry-run
```

For the isolated real-bundle test, set `DSH_CLI_JS` to a packaged DSH CLI entry and run:

```powershell
npm run harness-e2e
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).

## Trademark and license

“DeepSeek Harness” is used only to describe compatibility. The project uses the recommended `DSH` abbreviation and does not imply official endorsement. See the upstream [brand guidelines](https://github.com/deepseek-ai/deepseek-harness/blob/master/BRAND_GUIDELINES.md).

MIT © ArmyWas