@deepseek-ai/dsh-model-catalog-xai

Readme

# DSH Plugin: LLM Provider - xAI Grok

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

Allows connecting to the **xAI / Grok** Coding Plan as an LLM Provider, enabling [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) to automatically discover the latest official Grok models and select top models like **`grok-4.6`** directly from the model picker.

## Target Audience and Use Cases

Designed for users with an xAI API key or xAI subscription who want to leverage Grok 4.6's advanced coding and reasoning capabilities inside the DeepSeek Harness workspace.

## Key Features

- **Real-Time Official Sync**: Queries the xAI `/models` endpoint to dynamically surface account-available Grok models.
- **Out-of-the-Box Grok 4.6 Support**: Provides verified configuration presets (including context windows, output limits, and reasoning controls) for immediate and reliable use.
- **Independent Mixed-Protocol Route**: The plugin registers its own `xai` adapter. `grok-4.3` and `grok-build-0.1` use Chat Completions; `grok-4.5` and `grok-4.6` use Responses.
- **OAuth Resolution and Refresh**: The plugin reads JSON credentials through `XAI_OAUTH_CREDENTIAL`, reuses pi-ai's built-in xAI OAuth handler to refresh expired tokens, and writes rotations back through the Harness credential service.
- **Secure Credential Isolation**: OAuth JSON never enters Cordis configuration or logs. Only the handler-derived access token reaches the exported `PiAiAdapter` as a request-level auth override.
- **Zero Overhead**: Injects no extra prompts, headers, token overhead, or transport alterations.

## Installation and Quick Start

Install a reviewed revision into a DeepSeek Harness profile. The repository includes a `dsh.bundle` patch and prebuilt runtime artifacts so no local build steps are required:

```sh
dsh plugin --profile <profile> add github:OpenSaozi/dsh-xai-catalog#<commit-sha>
```

The installed bundle contributes the following Cordis configuration:

```yaml
- id: model-catalog-xai
  name: '@deepseek-ai/dsh-model-catalog-xai'
  config:
    oauthCredentialEnv: XAI_OAUTH_CREDENTIAL
    baseURL: https://api.x.ai/v1
    displayName: xAI
```

The plugin owns the complete `xai` route: mixed-protocol catalog, live filtering, OAuth resolution and refresh, and adapter registration all live here. It only reuses the generic `PiAiAdapter` exported by `@deepseek-ai/dsh-llm-pi-ai`.

## Contributing

Issues and focused pull requests are welcome. New model descriptors must include evidence for exact model ID, protocol, modalities, context/output limits, and reasoning controls. Update both README languages and run package tests in a matching DeepSeek Harness checkout.

## License and Disclaimer

MIT License. This independent integration is not affiliated with or endorsed by xAI, DeepSeek, or pi-ai maintainers. Grok and related model names are trademarks of their respective owners.

## Model Experience

### Catalog Selection

#### What the model sees

No package-owned text. The plugin controls which xAI model descriptor, such as `grok-4.6`, can be selected; the exported `PiAiAdapter` owns request conversion.

#### Token effect

No direct token effect. Tokenization and context use remain properties of the selected xAI model and pi-ai protocol implementation.

#### KV Cache effect

No direct effect. Selecting a different model may change provider-side cache eligibility, but this plugin adds no request content.

## Known Limitations and Deferred Work

- Refresh runs when the plugin mounts or `XAI_OAUTH_CREDENTIAL` changes. A failed or unauthenticated refresh keeps the maintained catalog and logs the error; it does not replace the list with empty data.
- The Models endpoint proves availability but not protocol, context capacity, modalities, or reasoning controls. New ids require a maintained descriptor before they are exposed.
- This package provides no login UI. It reads the credential already stored at `XAI_OAUTH_CREDENTIAL` before migration and refreshes it itself. Re-login still requires the deployment to write the result of pi-ai's xAI handler to that reference.