dsh-llm-grok
用于 DeepSeek Harness 的 xAI Grok 订阅登录和聊天
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:NOirBRight/dsh-llm-grok#17b1ba5a241a89c83ff073ed535e68de5615737cLlm Grok 以 dsh-llm-grok 发布，当前版本为 0.3.17。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
xAI Grok integration for DeepSeek Harness. This plugin is a separate provider route (grok) and settings namespace (llm-grok). It does not replace the built-in xai console API-key route, and it does not declare apiKeyEnv.
The package root exposes the Cordis plugin contract. The same artifact exports ./client, which contributes the Grok card under Settings → LLM Providers.
Host @deepseek-ai/dsh-* packages are not version-locked: peers are * and optional. devDependencies pin the compile target (0.1.5-rc.1). Cordis stays >=4.0.2 <5.0.0.
Verified Hosts in package.json#dsh.compatibility.dshReleases are evidence, not an allowlist. Unknown newer Hosts warn once and keep the normal mount path. Only a reproduced failure is blocklisted.
catalogId and the unresolved unknown account state are attached at runtime. Published dsh-llm-providers-ui 0.2.8 omits those fields and treats unknown as unconnected; they only take effect on a newer Owner.
The LLM Providers Settings page (settings.section id: providers with child settings.provider.item) and the shared llm-providers order store are owned solely by dsh-llm-providers-ui.
key: llm-grok) and its Host llm route; it does not install the page or the shared llm-providers namespace. Load order with the owner does not matter.dsh-llm-providers-ui): the Host model route grok still works; in Web the Providers page and this card are omitted. pack:check verifies the owner artifact identity, ./sortable export, and packed client closure.dsh-llm-providers-ui (src/client/nav-icon.ts); this plugin does not ship that adapter.tsconfig.json maps @deepseek-ai/dsh-client-ui-slots and @deepseek-ai/cordis to their installed type declarations so the client typecheck resolves a single copy of each instead of duplicate type closures.Install dsh-llm-providers-ui explicitly in the profile alongside provider plugins (see that package's cordis.patch.yml).
Verified on DeepSeek Harness 0.1.2-alpha.4, 0.1.2-rc.1, 0.1.5-rc.1, and 0.1.5-rc.2 (Cordis 4.0.2). Install directly from GitHub:
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.9/dsh-llm-providers-ui-0.2.9.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/download/v0.3.17/dsh-llm-grok-0.3.17.tgz
dsh web
The repository tracks release-ready lib artifacts, so GitHub installation needs no build-script allowlist.
Open Settings → LLM Providers → Grok. Sign in with xAI starts a Host-owned PKCE flow against auth.x.ai (the Grok CLI public client), opens the system browser, and stores the session only on the Host at $DSH_HOME/grok-oauth.json (mode 0600). The card then shows the account email. Sign out deletes that file. The browser never receives tokens. This plugin does not read or write ~/.grok/auth.json.
Grok Plugin card: subscription login, usage, and model catalog
The Plugin card keeps two catalogs: the signed-in account list from GET /v1/models-v2, and the displayed subset stored as settings.models. The conversation picker uses only the displayed subset. Each row can set Default thinking and a Context window used as the DSH compaction budget. Official grok-4.6 / grok-4.5 default to 500,000 tokens. The card catalog starts collapsed; it can be reordered, edited, deleted, or replaced from the account list. When the subset has never been saved, the frozen default is grok-4.6 and grok-4.5. Chat goes to POST https://cli-chat-proxy.grok.com/v1/responses. Every request includes DSH function tools plus always-on server-side { type: "web_search" } and { type: "x_search" }. Search is not a ctx.web provider. Server search returns encrypted tco_* reasoning items with empty summaries; those stay in replay and no longer each paint an empty Think row. If Grok also echoes the same search as a client custom_tool_call (xs_call-* / ws_call-*, often named x_keyword_search), the plugin drops it so DSH does not report unknown tool. Reasoning is sent as official Responses reasoning: { effort }, with values low / medium / high (default) / xhigh (4.6 only). When signed in, the card also shows subscription usage from a Host billing read (GET /v1/billing?format=credits). The signed-in card starts its cached billing read while collapsed; expansion does not refetch. Logged-out cards do not request billing. For a valid active credits period with no paid or legacy budget, omitted proto3 zero usage is decoded as zero; malformed or ambiguous paid data is not defaulted. Only a missing billing endpoint (404) is unsupported; malformed or unrecognized successful responses are query errors, without invented quota values.
The collapsed header first-paints the last successful quota from the shared browser cache when no live reading is available (never on error or unsupported); signing in, signing out, or an authoritative signed-out status purges the cached quota in every bundle copy, even without providerDirectory; so does a usage read that cannot resolve a usable credential, which the Host answers as INVALID_CREDENTIAL instead of a generic failure.
With dsh-model-switch v0.4.x, Grok also registers an optional Image-only adapter for the stable generate_image router. It reuses the same authenticated implementation and registers no Search or Vision adapter. Standalone behavior is unchanged.
Optional grok_image_gen (default off) registers a model-facing tool that generates an image with Grok Imagine. It reuses the same Host OAuth session and posts https://api.x.ai/v1/images/generations — the same rail Grok Build's local image_gen uses, not a console API key and not the chat proxy. The name is distinct from Codex codex_generate_image. Generated bytes are saved to the workspace and committed through the attachment store.
Chat without a session fails MISSING_CREDENTIAL. A stored session whose refresh fails is cleared and fails AUTH. ensureFreshSession runs before each chat request. A later content-less AUTH (HTTP 401) force-refreshes the session and retries the request once; remaining AUTH failures are eligible for the bundle's eight normal retries.
Every proxy request sends this plugin's X-Dsh-Plugin identity plus the CLI version headers the proxy requires (x-grok-client-version / x-grok-client-identifier). A missing version is answered 426. Those headers are required by the proxy and do not attempt to impersonate the official CLI product.
The Models page, if it lists Grok at all, is hint-only. Because this package does not declare apiKeyEnv, that row must not show a missing-API-key badge.
- id: llm-grok
name: 'dsh-llm-grok'
config:
streamIdleTimeoutMs: 300000
retryPolicy:
mode: normal
maxRetries: 8
backoff:
initialDelayMs: 500
maxDelayMs: 10000
jitterRatio: 0.1
The bundle retries eligible model-request failures up to eight times by default, including AUTH. xAI capacity/high-demand failures are classified as RATE_LIMIT; temporary availability degradation is classified as SERVER.
There is no apiKeyEnv and no user-editable base URL. models is the displayed conversation catalog, a subset of the account list.
The composer picker groups sibling catalog rows that share a base id after peeling a Fast suffix (-fast) and a generic context suffix (-<n>k / -<n>m). Product names such as kimi-k3-max are not treated as a context tier. This package's catalog comes from discovery; add extra suffix rows yourself if you want DSH to compact against a smaller budget. This plugin does not peel those suffixes on the wire.
xAI Grok subscription login, Responses chat, usage, search, and Imagine. The release artifact targets DeepSeek Harness 0.1.2-alpha.4, 0.1.2-rc.1, 0.1.5-rc.1, and 0.1.5-rc.2 and contains built Host/Client files only; it has no sibling-repository source, workstation path, link:, or workspace: dependency.
The dsh-llm-providers-ui package owns the LLM Providers page, navigation, and shared order store. This package owns only its provider card, models, credentials, and Host route. Install the Owner first for Web; headless Host routing works without the Owner.
Latest (Owner + this plugin; required together on Web):
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.9.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.17.tgz
Fixed versions (reproducible):
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.9/dsh-llm-providers-ui-0.2.9.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/download/v0.3.17/dsh-llm-grok-0.3.17.tgz
Update, uninstall, and verify:
# Update Owner + this plugin to Latest
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.9.tgz
dsh plugin --profile web add --force \
https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.17.tgz
# Verify the loaded version
dsh plugin --profile web list
dsh plugin --profile web doctor
# Uninstall only this plugin
dsh plugin --profile web remove dsh-llm-grok
Configuration: use the plugin section in Settings for Web UI plugins, or the profile dsh.profile.bundles entry for Host-only plugins. Start with this README's minimal YAML/JSON example and provide credentials/backend addresses explicitly.
Rollback: rerun the fixed v0.3.17 command, verify the profile list, then restart the Web service once. Inspect journalctl --user -u dsh-web.service and dsh plugin --profile web doctor; never put a source checkout in the production profile.
Release and integrity: v0.3.17 · SHA256SUMS.
The Host registers Search and Image adapters together through the existing Model Switch registry, with lifecycle disposal. Independent search declares the supported Grok chat models and calls the existing subscription Responses endpoint with required server-side search tools. It reuses the provider token resolver and identity headers. Only native URL citations/search-call results become sources; missing credentials, unsupported models and responses without search evidence fail explicitly. Upstream error bodies are not exposed. This is distinct from a conversational model merely having native networking enabled.
This requires the coordinated Model Switch dynamic-search implementation (dsh-model-switch 0.4.7; the adapter itself builds against the 0.4.6 registry contract). Registering an adapter does not select global Web routing: explicitly configure web.searchProvider: model-switch, retaining every other Web config field, then choose the provider/model in Model Switch. No replacement web tool is registered; web_fetch is unchanged. ProviderDirectory deferred role/usage integration is preserved.
Validation: pnpm test (143 passed), pnpm run build; 3082 official Web selection returned real sources with both grok-4.6 and grok-4.5 in sequence. See the Model Switch integration audit for exact lab composition and evidence.