dsh-grok-provider

让 DeepSeek Harness 使用你已登录的官方 Grok Build 账号：动态模型发现、流式推理、图片输入、可选 Web/X Search、工具调用，以及账号额度与模型能力面板。

非官方社区项目，与 xAI 或 DeepSeek Harness 官方无隶属关系。本说明对应 dsh-grok-provider@1.0.6 制品；0.1.8 曾发布后撤回且版本号不可复用。

1.0.6 修复带透明通道的 WebP 图片在 Grok 请求前被拒绝的问题。透明 WebP 会在写入 Responses 请求前转码为 PNG，不透明 WebP 转码为 JPEG。

本 README 随 1.0.6 一起进入 npm tarball，下面的精确安装命令也固定为 1.0.6。上一份已完成供应链回读的版本为 1.0.5。

它解决什么问题

能力	当前实现
登录	调用官方 `grok login --oauth`；登录 URL 生成与外部浏览器打开均由官方 CLI 负责，插件不实现 OAuth grant
凭据	复用官方 CLI 的登录状态；插件不创建第二份 token 存储
模型	运行时读取账号可见的全部 Grok Build 模型，不维护静态模型白名单
对话	Responses 流式文本、reasoning、加密 reasoning replay、usage 与 finish reason
图片	仅精确 `grok-4.6` 接收 Harness attachment 中有界的 JPEG/PNG/WebP 图片；WebP 在发送前转为 Grok 接受的 PNG/JPEG，`grok-4.5` 与其他模型保持 text-only
搜索	精确 `grok-4.6` 提供默认关闭的 Web/X Search；使用实时 settings service 保存开关
工具	将 function call 交回 Harness 权限层；Provider 本身不执行工具，关闭对应 Search 开关时保留本地 `web_search` / `x_search`
账户面板	登录状态、每周/月额度、重置时间、动态模型能力与 reasoning 档位
界面	Web 设置页中英文切换；TUI 提供闭合的 `/grok` 命令

快速开始

1. 准备环境

DeepSeek Harness 0.1.5-rc.2
Node.js 24.19.0 或更高版本
macOS arm64 或 Windows x64
官方 Grok Build CLI（支持 login --oauth，并使用官方默认 Grok home）

请从 Grok Build 官方文档安装 CLI，并先确认：

grok --version
grok models

当网络可达且 OIDC discovery 成功时，首次运行 Grok CLI 会打开浏览器登录。插件只支持官方默认的 ~/.grok（Windows 为 %USERPROFILE%\.grok）目录。

2. 安装 Provider

安装精确版本：

dsh plugin --profile web add dsh-grok-provider@1.0.6
dsh web

3. 登录并选择模型

打开 设置 → Grok Build：

点击“通过浏览器登录”；
在官方 Grok CLI 打开的浏览器页面完成授权；
返回 Harness，刷新账户面板；
在模型选择器中选择当前账号可见的 Grok 模型。

插件不会接管登录页面，也不会要求粘贴 access token 或 refresh token。

使用界面

Web 设置页展示：

当前登录状态、Provider/Grok Build CLI 版本及登录、取消、退出操作；
CLI 缺失或无效时的官方安装入口与“重新检测”操作；
已使用/剩余额度和真实周期重置时间；
当前账号可见模型、上下文窗口、reasoning 档位，以及图片输入、streaming 与 tool capability。
默认关闭且相互独立的 Web Search / X Search 开关，以及远端检索、额外用量、citation 和 prompt injection 风险提示。

当 protobuf-backed billing 返回完整的 weekly/monthly 周期但省略零值百分比时，页面会恢复为“已使用 0% / 剩余 100%”；其他不完整响应保持未知，不伪造额度。

Harness 0.1.5-rc.2 的 settings.section 没有插件图标字段。Provider 内嵌来自 @deepseek-ai/dsh-client-ui-primitives@0.1.0-rc.7、采用 MIT 许可的 IconThinkOutline16 路径几何；仅当设置对话框中的标签与 DOM 结构都精确且唯一匹配时，才用它显示 Grok Build 导航项，否则安全保留宿主齿轮。兼容层的观察器、标记和样式均随插件卸载清理。

插件预览

点击预览图可查看原图。

_{图片输入 — Grok 4.6 直接分析 Harness 附件}			_{模型选择 — 按当前账户能力选择 Grok 4.6 或 Grok 4.5}
_{对话上下文 — 查看上下文统计与工具调用}				_{账户面板 — 额度、重置时间与动态模型能力}

TUI 命令：

/grok status
/grok login
/grok cancel
/grok logout

这些命令不会进入模型上下文。退出操作需要二次确认，因为它会调用官方 grok logout，并影响共享同一 Grok home 的其他客户端。

更新与卸载

更新已安装版本：

dsh plugin --profile web update dsh-grok-provider
dsh web

卸载：

dsh plugin --profile web remove dsh-grok-provider
dsh web

卸载插件不会删除官方 Grok CLI，也不会直接修改或删除 auth.json。

项目来源与发现

本说明对应的 npm 精确版本：dsh-grok-provider@1.0.3
当前已完成回读的 GitHub Release：v1.0.3
发布证据：release commit 07ebd35c56348a1b3296bd46d1a69f5b0f430241，annotated tag object 7ec8a8a1086749e7ac1dfb0ef2bd50c821838363 peel 至该提交，final CI run 33378215345，Trusted Publisher run 33379149158 attempt 1。仓库所有者明确授权的唯一 tarball 含 77 个文件、267,403 bytes，unpacked size 829,862 bytes；SHA-1 为 6197c3d30ec1ef5f559371911d612f6236eee2f9，SHA-256 为 7f740c7258ab7eee0c96e1ddae3398b41a25e718cf267e244f8693c3c99aeb0d，SRI 为 sha512-kJgN0NKKV7Te3oAgbPnEua/EQCLnj5S0KWAWrhP0ixudJBepplRFARYHCxwxOwbG87bnX07Mz/dxCoBiphWhqQ==。冻结制品、GitHub Release asset 与 npm Registry tarball 逐字节一致，Registry 锁定安装通过 Host/client 加载且生产审计为 0 漏洞；本包公开 metadata 含 1 个 Registry signature、2 个 attestations，安装图为 11 个已验证签名包与 2 个 attested 包。SLSA provenance 精确绑定 release.yml、refs/tags/v1.0.3、release commit 与 publish run。
npm 页面文档修正：1.0.1 tarball 内曾保留旧安装示例；已发布的 1.0.2 tarball 内，本 README 使用精确 @1.0.2 命令。已发布的 1.0.1 字节不会被覆盖。
GitHub 社区发现：仓库已添加 DeepSeek Harness 官方推荐的 dsh-plugin 与 dsh Topics
YukiRyou 受管来源：deepseek-yukiryou-plugin-catalog，当前仍锁定已完成真机验收的 dsh-grok-provider@0.1.0，且只标记 darwin-arm64

出现在目录中不代表 xAI 或 DeepSeek Harness 官方背书。项目已通过收录 PR #3415 进入公共 awesome-dsh-plugin 的 model 分类；该目录是仓库级发现入口，不承载精确 npm 版本或平台验收声明。

兼容性与范围

`1.0.6` 修复边界

修复 DSH 附件库把带透明通道的图片规范化为 image/webp 后，grok-4.6 在网络请求前失败的问题。
捕获阶段接受有界 WebP；透明 WebP 转为 PNG，不透明 WebP 转为 JPEG，Responses wire 不直接发送 WebP。
增加透明与不透明 WebP 的回归覆盖；本地真实 Grok 请求确认透明 WebP 以 PNG MIME 发出并完成 SSE。

`1.0.5` 修复边界

1.0.5 发布与 npm latest 已更新；双平台 CI、唯一制品字节、Registry 签名和 provenance 均已验证。
六个账户操作迁移到共享 /api 精确 POST 路由；主机保留浏览器会话认证、Host/Origin 检查和请求体限制。
使用主机请求 schema，拒绝错误方法、畸形请求和路径不匹配；随插件卸载清理路由。
依赖对齐 DSH 0.1.5-rc.2。macOS 隔离实例验证状态、CLI 1.0.5、两个模型和额度；未认证返回 401，跨来源返回 403。
Windows 真机浏览器登录和本版真实生成未重测。见版本说明。

`1.0.4` 修复边界

Host 不再从 @deepseek-ai/dsh-settings named import installSettingsSection 或 settingsNamespace；改用 settings service 的 installSection，namespace 为合法字符串常量 llm-grok。
settings service 缺失或重载时仍回退组合配置；启用、停用和失败回滚不删除 receipt、generation 或账号状态。
required peer 提升到 Harness 0.1.2-rc.1 实际提供的 dsh-settings / dsh-llm 与 Cordis 4.0.2、Schemastery 3.18.2；Web client inject 用 @deepseek-ai/dsh-client-ui-renderer 取代已删除的 dsh-client-runtime。
本版不改变认证恢复、部分输出保留、Search 协议、图片、固定 endpoint 或 Windows 浏览器登录边界。详情见 docs/releases/v1.0.4.md。

`1.0.3` 修复边界

仅在 200/SSE 开始前的 401/403 上，通过官方 Grok CLI 做一次有界共享会话刷新、重新读取凭据并最多重试一次；持续拒绝仍返回 AUTH，不新增 API Key 模式。
流开始后绝不自动重放。transport interruption、干净过早 EOF 或连续两分钟没有任何 wire bytes 时，只有无工具副作用且有界的 text/reasoning 可以被保留并附加“发送继续”提示；工具调用、未知事件、畸形协议、用户 abort 或空部分响应继续失败关闭。
精确 Node 24.19.0 门禁为 274 tests、272 pass、0 fail、2 platform skips；唯一 77 文件制品的 final release commit、双平台 CI、明确授权、隔离安装、Registry、签名、attestations 与 provenance 回读均已完成。真实账号成功路径只验证当前连接，不模拟未来 401 或断流；本版也不构成 Windows 真机浏览器登录验收。详情见 docs/releases/v1.0.3.md。

`1.0.2` 修复边界

普通严格空 reasoning item 继续执行既有 ID/type、sequence、output index、状态、summary/content 空性、大小、可选 encrypted content 与闭合校验；Search-backed 同 ID 复用项继续额外执行精确 own-data 键集与 accessor 拒绝。本版没有扩大协议接受域。
Provider 延迟创建 Harness reasoning block，只有收到首个非空 summary/raw delta 才发送 block-start，随后按原顺序发送 delta 和 block-end。完整生命周期最终为空时产生零个可见 reasoning chunk。
多个非空 reasoning item 继续按 output index 保持独立块；正文、工具调用、usage、finish reason、可见非空 reasoning replay、Search 后 replay 抑制和失败关闭行为不变。被隐藏的普通空 item 不占可见 block/replay 对齐槽，其有界 encrypted content 通过校验后不持久化。
精确 Node 24.19.0 本地门禁为 265 tests、263 pass、0 fail、2 platform skips；生产依赖审计 0 漏洞，74 文件制品的 final release commit be200f9352afe93b27dd2856d89c01674f0cd637 与 final CI run 33318426571 已在 macOS 14 / Windows 2022 全绿。唯一授权制品、隔离安装、Registry、签名、attestations 与 provenance 回读均已完成。
修复只影响升级后的新回复；旧会话中已经持久化的空 Think 行不会被回写删除。
本版不改变 Search 开关、模型、认证、图片、固定 endpoint、citation/URL 或 Harness 工具权限边界，也不构成 Windows 真机浏览器登录验收。

`1.0.1` 修复边界

根因不是模型、账号、Search 响应形状或 42 项工具总数，而是启用 server Search 时，同名 Harness function definition 与 { type: "web_search" } / { type: "x_search" } 共存；固定 Proxy 对该组合返回 HTTP 400。
编译器先完整验证 40 个源 functions，再仅过滤与已启用 server Search 同名的 wire definitions。关闭对应开关时，本地工具保持原样；已有会话中的历史 function_call / function_call_output 也不删除或改名。
最终 request receipt 拒绝 function/server-tool 名称交集；SSE parser 保留 source transport error，HTTP 400 因而映射到 PROVIDER_ERROR，真正的 SSE/协议错误仍为 INVALID_RESPONSE。
一次经明确授权的脱敏真实账号回放使用原失败 X 会话结构：8 条 messages、40 个 source functions、wire 38 functions + 2 server tools、保留 2 个历史 reserved-name calls；只执行 1 次 models GET 和 1 次 Responses POST，接收 314 events 并以 response.completed 闭合。未保存消息/回复正文、URL、身份或凭据。
精确 Node 24.19.0 本地全量门禁为 253 tests、251 pass、0 fail、2 platform skips；生产依赖审计为 0 漏洞，隔离 cache 的 dry-run pack 列出 73 个文件，秘密模式扫描只命中显式 fixture canary 及其检查表记录。代码 PR #31、main CI run 33312621786、最终 release commit、双平台 final CI、唯一授权制品、隔离安装、Registry、签名、attestations 与 provenance 回读均已完成；这些证据仍不代表 Windows 真机浏览器登录已经完成。详情见 docs/releases/v1.0.1.md。

`1.0.0` 修复边界

一个 reasoning ID 的原始生命周期必须先闭合，并且首次复用前必须已有一个完成的 Web/X server Search；之后只允许它以严格空占位再次出现。
“严格空”是指可见 summary/content 为空，且没有 summary/raw lifecycle；允许有界、不透明的 encrypted_content，但不会把它当作可见 reasoning 或保存上游明文。
每次复用都必须收到独立的 response.output_item.done；若 response.incomplete 到来时仍有复用段未闭合，则返回通用非法响应错误，所有复用段已闭合后的 max_output_tokens 终态仍有效。非空 summary/raw、跨类型、未知 terminal 字段或 accessor 字段继续拒绝。
完成态 open_page 只接受精确 type + url，streamed/final action 的类型与 URL 必须一致；Provider 校验后丢弃 URL，不会访问、预览、下载或回放。
最终源码完成两层脱敏真实账号复验：原始 Web/X 协议探针各 1 次请求、各 64 events，分别观察到对应 Search 且终态 completed；生产 adapter 共完成 5 次 Responses，direct Web/X 均为 stop，Harness 形状的本地 x_search call/result 续跑三轮依次为 tool-calls、tool-calls、stop，前两轮各 1 次本地调用。该续跑没有在同一 wire request 中同时放入 Harness x_search function definition 与 xAI { type: "x_search" } server descriptor；1.0.1 后续才隔离出这一 HTTP 400 冲突。未保存结果、URL、prompt、身份或凭据；这些不是发布、OAuth 或 Windows 真机证据。
manifest/lock 已同步为 1.0.0；Node 24 全量测试为 245 项、243 pass、0 fail、2 项平台跳过，生产依赖审计为 0 漏洞，确定性 build/bundle、72 项 dry-run pack、秘密模式扫描与 diff 检查均通过。代码 PR #28、main CI run 33308371009、最终 release commit、双平台 final CI、唯一制品、精确授权及 Registry/signature/attestation/provenance 回读均已完成。

项目	`1.0.6` 兼容边界
DeepSeek Harness	精确支持 `0.1.5-rc.2`
Node.js	`>=24.19.0`
macOS arm64	图片发送已完成真实 Harness 验证；`1.0.5` 验证 `0.1.5-rc.2` 账户 RPC
Windows x64	代码路径与现有 slow-fake 保持不变；网络可达时由官方 CLI 生成 URL 并打开浏览器，该路径仍未完成 Windows 真机验收
macOS x64 / Linux	不支持
Grok CLI	不锁完整版本；严格校验官方路径、`login --oauth` 能力与生产 OIDC 凭据契约
模型	当前账号目录中 backend 已被严格 codec 支持的全部模型

1.0.6 沿用已发布版本的图片边界：只为精确的 grok-4.6 开启图片输入；grok-4.5 与其他动态发现的模型继续按 text-only 处理。图片只能来自 Harness attachment service 的已验证 JPEG/PNG/WebP 投影；WebP 在发送前转换为 Grok 接受的 PNG/JPEG。支持普通用户内容和一层工具结果中的图片，并固定使用 detail:"high"；不接受 URL、文件路径、file ID 或调用方预制的 data URL。普通 user/system 历史中的私有 reasoning 会被省略并保留相邻可见文本。

每张投影图片最多 4 MiB、16,777,216 像素且任一边不超过 8192px；每次请求最多保留 8 张、投影字节合计最多 8 MiB。超限时按全局最旧优先移除图片并保留 Harness 的文本占位，最终 JSON 仍受 16 MiB 上限约束。

已发布的 0.1.10 使用 Harness 官方 settings 模块注册并持久化两个 Search 设置；每个新调用在模型发现前读取一次最新值，已准备和在途调用保持原快照。真实使用随后发现精确 grok-4.6 在 High Effort + Web Search 续跑时，可能先关闭 reasoning 项，在一次 Search 完成后再把同一 ID 使用一次作为空占位，旧解码器会因此失败关闭。已发布的 0.1.11 仅在已完成 Search 位于两段 reasoning 之间时允许该 ID 以严格空项再出现一次，并增加官方 raw reasoning_text 生命周期；raw 与 summary 互斥，replay 元数据不保存 raw 明文，后续请求只发送 encrypted_content 与空 summary，当前流中的 raw delta 仍会作为 Harness 可见 reasoning 输出。脱敏真实探针观察到 34 个 summary delta、0 个 raw delta，因此只验证 summary/Search 路径，raw reasoning 仍只有 fixture 回归。Search 继续只对精确 grok-4.6 默认关闭地开放；远端活动不变成本地工具，citation URL 不会被打开或下载。搜索结果属于不可信远端数据，执行命令或修改文件前应核实来源。图片生成、任意文件下载、API Key 模式、多账号、企业 OIDC、ACP 与 Headless agent 封装仍不在本版本范围内；后续切片见能力路线图。

工作原理

Harness UI / TUI
       │ 仅发送闭合操作与脱敏 DTO
       ▼
dsh-grok-provider Host
       ├── 官方 Grok CLI：login / models / logout
       ├── 固定 Models/Billing endpoint：目录与额度
       └── 固定 Responses endpoint：流式推理
                    │
                    ▼
              xAI Grok Build

模型 ID 来自运行时目录，不是硬编码列表；图片 modality 则只对有独立协议与真机证据的精确模型 ID 开启。如果账号出现当前版本无法安全映射的新 backend，发现过程会失败关闭，而不是隐藏模型后宣称“全部支持”。

安全与隐私

模型、目录和计费请求只允许编译时固定的 HTTPS origin/path，并拒绝重定向。
Renderer 和 RPC 不接收 token、user_id、凭据路径、任意 URL 或原始上游响应。
Host 必须有界读取官方 auth.json，其原始文件可能包含 refresh token；解析器不使用、不缓存、不持久化 refresh token，只保留闭合校验所需元数据与短期 access-token lease。
插件不实现 refresh grant；凭据临近过期时，只能有界调用一次官方 grok models，再重新读取并验证官方文件。
登录子进程使用固定 argv、过滤后的环境、输出上限、deadline 与取消处理，不通过 shell 启动。
提示词、工具结果、用户选择发送的图片投影，以及启用 Search 后的检索词会发往 xAI Grok Build 服务；插件本身不记录这些内容、原图、投影字节或 citation URL。

完整边界见威胁模型。发现安全问题时，请阅读安全策略，不要在公开 Issue 中提交 token、auth.json、个人信息或完整诊断日志。

常见问题

页面显示“找不到 Grok CLI”

按页面中的官方安装入口安装 Grok Build CLI，再点击“重新检测”。确认 CLI 位于默认路径，并在终端执行 grok --version。插件不会自动安装 CLI，也不会从 PATH、工作区或 UI 指定的任意路径加载可执行文件。设置页会同时显示 Provider 与已验证 CLI 的版本。

页面要求重新登录

在设置页点击登录，或先在终端运行 grok login --oauth。插件不锁完整 CLI 版本，但路径、--oauth 能力或生产 OIDC 凭据契约不匹配时会失败关闭。

Windows 点击登录后没有弹出浏览器

先直接运行官方 CLI：

& "$env:USERPROFILE\.grok\bin\grok.exe" login --oauth

如果它在 auth.x.ai/.well-known/openid-configuration 超时，失败发生在生成登录链接之前，不是 Provider 的浏览器按钮失效。请检查 Windows 的 DNS、HTTPS 出站、防火墙、VPN 与代理；尤其是浏览器使用 PAC/系统代理、CLI 进程却没有 HTTPS_PROXY 的情况。不要关闭 TLS 校验，也不要把代理凭据、登录 URL、授权码或 token 提交到 Issue。

设置页会及时结算这个已知 discovery 超时并显示“浏览器登录尚未开始”；实际仍在运行的五分钟登录流程可以取消，未知 CLI 输出只显示脱敏的通用错误。这是对失败边界的准确诊断，不是插件自行打开浏览器，也不修复 Windows 的 DNS、代理、防火墙、VPN 或官方 CLI 行为。

没有看到某个模型

先运行 grok models，确认该模型对同一账号可见。Provider 动态返回全部合法目录记录；未知 backend 会让发现失败，而不会被静默过滤。

为什么额度百分比显示未知

完整类型化周期下缺失的 protobuf 零值会恢复为 0%；其他情况下，上游没有提供足够信息，插件会保留未知。OAuth token 过期时间绝不会冒充额度刷新时间。

从其他模型切换到 Grok 后立即提示响应无效

0.1.2 及更早版本不能转换部分包含特殊字符的第三方工具调用历史，典型情况是 Ark 调用 ID 中的 |。请更新到 0.1.3 或更高版本；新版本会保持工具调用与结果的关联，并在发送给 Grok 前安全映射不兼容的历史 ID。

Windows 能用吗

代码、slow-fake 与 0.1.9 Windows 2022 CI 已覆盖 Windows x64。官方 CLI 仍负责生成登录 URL 与打开外部浏览器；网络可达的 Windows 真机浏览器弹出尚未确认，因此不能表述为该问题已经修复或验证。

开发

npm ci --ignore-scripts
npm test
npm run pack:check

该包没有普通 runtime dependency；Harness services 使用精确 peer dependency。npm run build 生成可丢弃的 dist/，npm tarball 不包含 src/、测试、spike 或本机证据。

项目导航：

docs/README.md：设计文档索引与当前决策；
docs/04-harness-contract.md：Harness 集成契约；
docs/05-test-plan.md：平台、安全与发行门禁；
docs/09-implementation-status.md：实现与验收状态；
docs/11-capability-roadmap.md：0.1.4 起的内容类型路线；
CHANGELOG.md：版本变化。

提交 Issue 或 PR 前请阅读贡献指南。认证、传输、凭据格式或发布边界的变化必须先更新对应 ADR/威胁模型，再开发和测试。

路线图

完整切片、门禁与永久非目标见能力路线图。路线图不是兼容性承诺；新增能力必须通过独立 ADR 与安全门禁。prompt_cache_key 不与图片输入捆绑；不引入任意 URL 下载或 API Key 模式。

许可证

MIT。复用的 Harness 图标几何及其许可见 THIRD_PARTY_NOTICES.md。

dsh-grok-provider

安装

README