dsh-grok-provider
简体中文 | English
让 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 导航项，否则安全保留宿主齿轮。兼容层的观察器、标记和样式均随插件卸载清理。
插件预览
点击预览图可查看原图。
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 或本机证据。
项目导航：
提交 Issue 或 PR 前请阅读贡献指南。认证、传输、凭据格式或发布边界的变化必须先更新对应 ADR/威胁模型，再开发和测试。
路线图
完整切片、门禁与永久非目标见能力路线图。路线图不是兼容性承诺；新增能力必须通过独立 ADR 与安全门禁。prompt_cache_key 不与图片输入捆绑；不引入任意 URL 下载或 API Key 模式。
许可证
MIT。复用的 Harness 图标几何及其许可见 THIRD_PARTY_NOTICES.md。
