# DSH Plugin: LLM Provider - xAI Grok

中文 | [English](README.md)

允许接入 **xAI / Grok** 的 Coding Plan 作为 LLM Provider，让 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) 能够自动同步官方最新的 Grok 系列模型列表，并在模型下拉菜单中一键选用 **`grok-4.6`** 等最新强力模型。

## 适用人群与场景

适合拥有 xAI API Key 或 xAI 订阅，想要在 DeepSeek Harness 工作台中体验 Grok 4.6 最强编程与逻辑推理能力的用户。

## 核心特性

- **官方模型实时同步**：自动核对 xAI 官方 `/models` 端点，动态发现账号下可用的 Grok 系列模型。
- **开箱即用支持 Grok 4.6**：内建严格测试过的参数配置（包括上下文容量、最大输出上限与推理控制），选了就能直接稳定工作。
- **混合协议独立路由**：插件自己注册 `xai` adapter；`grok-4.3` 与 `grok-build-0.1` 走 Chat Completions，`grok-4.5` 与 `grok-4.6` 走 Responses。
- **OAuth 读取与刷新**：插件通过 `XAI_OAUTH_CREDENTIAL` 读取 JSON 凭据，复用 pi-ai 内置 xAI OAuth handler 刷新过期 token，并把轮换结果写回 Harness 凭据服务。
- **安全凭据隔离**：OAuth JSON 不进入 Cordis 配置或日志；请求只把 handler 产生的 access token 作为请求级鉴权覆盖交给官方 `PiAiAdapter`。
- **零额外开销**：不添加任何额外提示词、请求头、Token 损耗或传输层修改。

## 极简安装与使用

请把经过评审的提交安装进指定的 DeepSeek Harness profile。仓库携带 `dsh.bundle` 配置和预构建运行文件，通过 Git 安装无需在本地执行构建：

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

安装后，插件会自动在 Cordis 配置中注入以下内容：

```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
```

插件拥有完整的 `xai` 路由：混合协议目录、在线筛选、OAuth 读取与刷新、adapter 注册都在本包内完成；仅复用 `@deepseek-ai/dsh-llm-pi-ai` 导出的通用 `PiAiAdapter`。

## 参与贡献

欢迎提交 issue 和范围明确的 pull request。新模型描述必须附带准确模型 id、协议、输入类型、上下文与输出上限、推理控制和价格的证据。请同时更新中英文 README，并在版本匹配的 DeepSeek Harness 工作区中运行包测试。

## 许可证与声明

采用 MIT 许可证。该独立集成与 xAI、DeepSeek 或 pi-ai 维护者无隶属或背书关系。Grok 及相关模型名称是其各自所有者的商标。

## 模型体验

### 清单选择

#### 模型看到的内容

没有本包自带的文本。插件决定可选择的 xAI 模型描述，例如 `grok-4.6`；请求转换由官方导出的 `PiAiAdapter` 负责。

#### Token 影响

没有直接 Token 影响。分词和上下文占用仍由所选 xAI 模型及 pi-ai 协议实现决定。

#### KV Cache 影响

没有直接影响。切换模型可能改变供应商端缓存的适用性，但本插件不会增加请求内容。

## 已知限制与暂缓事项

- 插件挂载或 `XAI_OAUTH_CREDENTIAL` 变化时会刷新。刷新失败或尚未配置认证时，会保留代码维护的清单并记录错误，不会用空数据覆盖清单。
- Models 接口只能证明模型当前可用，不能证明协议、上下文容量、输入类型或推理控制。新 id 必须先补齐经过验证的描述，才会显示。
- 本包不提供登录界面；它读取迁移前已经存入 `XAI_OAUTH_CREDENTIAL` 的凭据，并能自行刷新。需要重新登录时，仍须由部署侧把 pi-ai xAI handler 的登录结果写入该引用。