dsh-grok-kit

dsh plugin --profile web add dsh-grok-kit

dsh-grok-kit

中文 · [English](README.en.md)

<p align="center">

<img src="assets/readme/hero.svg" width="100%" alt="dsh-grok-kit：DeepSeek Harness 的 Grok 对话、网页/X 搜索与可选图片、视频工具；媒体默认关闭">

</p>

<p align="center">

<a href="https://github.com/MaRi23333/dsh-grok-kit/actions/workflows/ci.yml"><img src="https://github.com/MaRi23333/dsh-grok-kit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>

<a href="https://www.npmjs.com/package/dsh-grok-kit"><img src="https://img.shields.io/npm/v/dsh-grok-kit.svg" alt="npm version"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-4d6bfe.svg" alt="Apache-2.0"></a>

<img src="https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.2-4d6bfe" alt="DeepSeek Harness 0.2.0-rc.2">

<img src="https://img.shields.io/badge/status-unofficial%20community%20plugin-7c84a8" alt="Unofficial community plugin">

</p>

通过 OAuth 在 DeepSeek Harness 中使用 Grok：主循环融合网页与 X 搜索、多轮推理衔接、图片生成与编辑、视频生成（实验性），以及仅作用于 xAI 的独立代理。

不止于 OAuth 登录

dsh-grok-kit 为 DeepSeek Harness 增加独立的 xai-oauth 路由。它不要求 XAI_API_KEY，也不修改 dsh 源码；重点不只是“能登录”，而是把服务端搜索和连续 reasoning 所需的请求字段接进主聊天路径。

• 搜索融入主循环： 网页与 X 检索发生在 Grok 的同一轮 Think 中，推理可以直接使用刚搜到的材料
• 多轮推理衔接： 默认使用 high effort，并保留 reasoning.encrypted_content，让后续回合能够带回加密推理上下文
• 登录状态与 Grok CLI 同步： 直接共用并回写 ~/.grok/auth.json，不是只复制一次后各自轮换 refresh token
• 图片生成与编辑（实验性）： grok_imagine 文生图、grok_imagine_edit 图生图（复用主 OAuth session），默认关闭，在设置页确认风险后开启；非聊天模型不会混进对话模型列表
• 会话图片卡片： 生成与编辑的结果保存在 DSH 附件库，在会话卡片里直接显示提示词、输入图与结果，支持下载与再次生成/编辑
• 视频生成（实验性）： 单图生成视频，任务持久化、断线恢复与按账号隔离的下载；默认关闭，确认风险并重启 DSH 后开启

此外还包括 xAI 专用代理、聊天 401 强制刷新重试、凭据原子写入、能力状态页与诊断脱敏等支撑能力。

X Subscription 与原订阅

账号页的 登录 Grok / X 订阅共用官方 Grok OAuth，兼容 X Subscription 与原 SuperGrok / X Premium 订阅；已登录时可重新授权以切换账号，不必先删除共享凭据。账号页也提供[官方订阅管理入口](<https://grok.com/dashboard>)。

额度使用官方 billing/settings 返回的百分比、周期、套餐及预付余额。REST 缺少使用百分比时会补查一次 gRPC；只有响应完整、状态成功且周期有效时，才按 proto3 隐式零值显示已用 0%／剩余 100%，不能核实时仍保留订阅详情、已用/剩余未知，不冒充无限额度。补查使用独立短超时，失败或补查超时不会抹去已读取的部分数据；整次读取超时、取消和账号校验仍然生效。结果按账号最多缓存 60 秒，已核实用量的缓存不跨有效周期，返回前也会重新校验周期；缺百分比的未缓存读取至多多发一次 gRPC 请求，REST 429 不触发补查。周期有效性依赖本机时钟，时钟偏差可能影响周期判断和隐式零值显示。统一计费标记来自接口，不根据套餐名猜测；仅展示当前登录身份，不汇总不同工作区或席位。本插件不提供 Cursor 登录或其他模型、外部 Agent 的接入。

0.2.11 适配 DSH 0.2.2 的原生设置侧栏图标，保留五页设置界面与按会话控制融合搜索的接口。账号处理与媒体风险确认规则不变；更新后重载插件或重启 DSH。

主循环融合搜索

同一个模型 id，不代表不同接入方式一定有相同的使用体验。xAI 官方说明 Grok Build 与公开 API 都提供 grok-4.6；真正影响搜索体验的，是服务端工具是否和主对话处在同一轮请求里。

分离式搜索会额外发起一轮模型请求完成检索或摘要，再把结果交回主对话。它仍然适合需要独立过滤条件的任务，但会多出一轮模型处理，而且搜索摘要不是在当前回复的 Think 中生成。

主循环融合搜索则按 xAI Responses API 的服务端搜索方式，把 {type:web_search} 与 {type:x_search} 直接放进主 Grok 请求。检索发生在 Think 里，模型能在同一轮推理中使用刚获得的网页和 X 材料；这条路径默认关闭（v0.1.8 起），可在设置页或配置中打开。

为让两类搜索共存，宿主原生 web_search 仍保留在 DSH 工具列表中，但会从启用融合搜索的 xAI payload 里移除，避免服务端工具重名；其他模型路由仍可照常使用宿主搜索。

从 0.2.10 起，接入插件可为各会话单独设置搜索开关，明确开启或关闭均可覆盖全局 backendSearch；未绑定的 DSH 会话仍使用全局配置。接入插件需支持此接口。

开启主循环搜索时，插件会剥掉 xAI 的 x_keyword_search 等收尾桩，避免 DSH 再开一轮并把同一篇正文再写一遍。这些名称若仍出现，属于故障诊断路径，不是正常用户体验。

需要按域名、账号或日期过滤时，改走独立的 grok_web_search / x_search（backendSearch 关闭时的默认路径）；开启 backendSearch 后这条独立路径退居可选。

statefulResponses 默认关闭。开启后，插件通过 store: true 和 previous_response_id 续接对话，只追加新的用户消息；若上一轮调用了 bash 等客户端工具，则不续接，以免重复生成已有的搜索正文。续接对话不保证缓存上一轮的全部搜索材料。

界面与效果

图片生成与会话卡片

<p align="center">

<img src="assets/readme/imagine-result.png" width="900" alt="Grok Imagine 实际生成结果：会话内图片预览，以及查看大图、下载、复制图片、复制提示词和重新生成按钮">

</p>

<p align="center"><em>一次实际文生图结果：图片直接显示在会话卡片中，可查看大图、下载、复制图片、复制提示词或重新生成。</em></p>

视频结果沿用同类卡片布局。图片生成、编辑和视频均为实验性能力，默认关闭，需在设置页确认风险后启用；实际可用性取决于账号资格与服务端限制。

<br><br>

设置页：账户、搜索与媒体

以下展示 0.2.10 的新版设置页，分为账户、模型、搜索、媒体和网络五页。

账户与配额

<p align="center">

<img src="assets/readme/settings-account.png" width="900" alt="Grok Kit 账户页：登录状态、订阅剩余配额、套餐、余额、重置时间和刷新配额按钮">

</p>

<p align="center"><em>账户页集中展示订阅用量与余额，可手动刷新配额。图中数据是截图时该账号的状态，不代表所有账号的配额或套餐。</em></p>

搜索与连续对话

<p align="center">

<img src="assets/readme/settings-search.png" width="840" alt="Grok Kit 搜索页：融合搜索已开启，连续对话已关闭，两项均标注为实验性功能">

</p>

<p align="center"><em>分别控制同一轮回答中的 Web / X 融合搜索与连续对话。两项均为实验性功能，默认关闭；图中融合搜索由用户手动开启。</em></p>

图片与视频工具

<p align="center">

<img src="assets/readme/settings-media.png" width="840" alt="Grok Kit 媒体页：图片生成和编辑已开启，grok_video 视频工具已关闭">

</p>

<p align="center"><em>图片开关同时控制生成与编辑，并显示两项实际状态；视频工具单独设置。媒体能力均为实验性功能，默认关闭，需确认风险后启用；视频还需重启 DSH，实际可用性取决于账号资格与服务端限制。</em></p>

<br><br>

网页搜索融入主循环

<p align="center">

<img src="assets/readme/main-loop-search.png" width="760" alt="Grok 在同一轮 Think 中完成网页搜索并回答">

</p>

<p align="center"><em>没有另起嵌套搜索工具卡片：网页检索直接发生在同一轮 Think 中，材料随即用于当前回复。截图里的新闻内容只用于展示交互，不作为事实来源。</em></p>

安装

桌面客户端和 Web 使用独立的插件安装与启用状态。请选择你实际使用的客户端；装到 Web profile 不会自动装到桌面端。

桌面客户端

1. 打开桌面客户端，在侧栏进入 插件（Plugins）→ 添加插件（Add plugin）。

2. 输入 dsh-grok-kit@latest 并安装；需要固定本版时输入 dsh-grok-kit@0.2.11。

3. 安装完成后点击 立即启用（Enable now）。若提示需要重启，通过应用菜单或托盘的 Quit / 退出 完整退出后重新打开；仅关闭窗口可能只是隐藏应用。

4. 在 设置 → xAI Grok 中确认插件入口出现，再按账号资格完成登录。

此方式不需要在 PATH 中配置 dsh。终端用户可按 [桌面配套 CLI 的安装步骤](INSTALL.zh.md#桌面端命令行) 操作；npm 全局安装或 npx 启动的 CLI 不能管理 desktop profile。

Web / CLI

使用启动该 Web 实例的同一套 DSH CLI，从 npm 安装到 web profile：

dsh plugin --profile web add dsh-grok-kit@latest
dsh web

如果 Web 进程已经在运行，先停止它，安装后再运行 dsh web 并刷新页面。以下命令均用于 Web。

也可以固定安装 0.2.11：

dsh plugin --profile web add dsh-grok-kit@0.2.11
dsh web

如果 PATH 中没有 dsh，可以使用同一个 CLI 包（固定宿主版本）：

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-grok-kit@latest
npx @deepseek-ai/dsh@0.2.0-rc.2 web

如果这个 profile 以前安装的是 GitHub 来源，可先尝试 dsh plugin --profile web add dsh-grok-kit@latest；若来源没有切换，先移除旧包再重新添加。

0.2.10 包含设置界面、会话搜索接入及依赖安全更新，不改变账号的订阅权限。配额请求兼容模式默认关闭，仅影响额度查询；图片、编辑和视频仍默认关闭，首次开启需确认风险、保存并重启。宿主支持仍为 DeepSeek Harness 0.2.0-rc.2 与 @earendil-works/pi-ai@0.87.1（Node 22/24），不支持旧 0.1 宿主线。完整变更见 [CHANGELOG.md](CHANGELOG.md)。

需要可复现的 Git 安装

…(truncated)