Grok 全能力集成 NingYuanLee/dsh-grok-byapi

Grok ByAPI for DeepSeek Harness

dsh-grok-byapi

在 DeepSeek Harness 中通过你自己的 OpenAI 兼容 Grok 网关使用 Grok：原生聊天提供方，外加图片、视频和语音合成工具。

0.2.1，npm 频道 latest。 聊天路由依赖 dsh 0.2.1-rc.2 这一档的适配器注册方式，升级宿主后要重跑集成测试。验收范围见 VALIDATION.md。

一个插件、一套网关连接。聊天模型出现在模型选择器里；图片、视频、TTS 模型不进入选择器，改由工具调用。任何聊天模型——Grok 或其他提供方——都能调用这些工具。插件只连接你已有的 Grok 网关（默认 CLIProxyAPI），把调用密钥存进 dsh 凭据服务，生成物保存在本地。它不是 OAuth 客户端，不提供账号或额度，也不读取 Grok CLI 的 OAuth 令牌。

演示

| 插件页 | 设置页 |
| 插件列表中已安装 dsh-grok-byapi | 英文界面下的插件设置页，两个组件运行中 |

下面两张都是这个插件用 grok_generate_image 和 grok-imagine-image-2.0 生成的，没有后期拼图：

| 冷色静物 | 暖色静物 |
| 桌面上卷起的纸和一颗映着青光的玻璃球 | 同一题材的暖色灯和一道离开玻璃球的光弧 |

下面这条是 grok_generate_video 生成的 4 秒片子，转成了动图。它不是上面静帧的逐帧动画：

纸张缓缓卷起，青光从玻璃球飘过桌面

功能

| 方面 | 当前实现范围 |
| 聊天提供方 | 注册原生 dsh LLM 提供方：路由名 xAI-CLIProxyAPI，显示名 Grok。流式文本与工具调用复用官方 pi-ai 适配器。 |
| 模型目录 | GET /models 自动发现，分类为聊天、图片、视频、语音、研究或未知。只有聊天模型进入选择器，未知模型不会。支持逐模型覆盖。 |
| 设置页 | 连接、密钥、验证、超时、对话模型表格（选择器名单的来源）以及媒体模型选择。 |
| 持久媒体任务 | 任务记录按会话隔离，重启后保留。下载先写 .part，校验后改名。存储按连接和任务隔离。 |
| 结果展示 | 工具结果卡片、文件预览，以及 MP4、MP3、WAV 侧栏播放器。 |

插件的两个组件合计注册 10 个工具。插件页只放连接和模型；grok-byapi 的详情只列对话和模型目录，dsh-grok-imagine 的详情只列图片、视频和语音：

| 工具 | 作用 |
| grok_models | 刷新模型目录，按能力分组返回。可选 verify_key，用一次 GET /models 检查地址与密钥。 |
| grok_generate_image | 文生图：prompt，可选 model、n（1–4，默认 1）。 |
| grok_edit_image | 图生图：prompt，加 image_url / image_urls（最多 5 张）或已保存图片任务。 |
| grok_generate_video | 文生视频；带一张 image_url 或已保存图片任务时是图生视频。duration 1–15 秒，默认 2。 |
| grok_edit_video | 视频生视频：按文字改已有视频（video_url 或已保存视频任务）。 |
| grok_extend_video | 从最后一帧延长，并和原片接成一条。 |
| grok_speak | 文字转语音并保存为 MP3：input，可选 model 和 voice。 |
| grok_media_list | 列出当前会话创建过的媒体任务。 |
| grok_media_status | 查询任务状态，就绪时下载保存：task_id。 |
| grok_media_retry_download | 只重试下载，不重新生成：task_id。 |

不提供：语音识别、实时语音、直接 OAuth、实时任务面板。视频会在本进程后台查询，但结果卡片不会自己刷新。模型分类是规则推断，不是可用性保证。

兼容性

| 组件 | 要求 | 已验证 |
| dsh | 由 engines.dsh 声明 >=0.2.1-rc.2 <0.3.0-0 | 0.2.1-rc.2 端到端（聊天、图片、视频、TTS、播放） |
| Node.js | >=22.19.0 | Windows + Node 24；CI 在 Linux 与 Windows 上用 Node 22.19 与 24 |
| 网关 | OpenAI 兼容 /v1 端点；推荐 CLIProxyAPI | CLIProxyAPI v8.0.30 |
| 其他 dsh 0.2.x | 在 engines.dsh 范围内 | 未逐版验证 |

兼容门禁看 engines.dsh；peerDependencies 只锁定源码用到的 SDK 包，不决定兼容性，升级 dsh 后应重跑集成测试。xAI 直连或其他兼容端点可以承载聊天，但图片、视频、TTS 需要网关暴露对应的 Grok 接口。

安装

从 npm 安装（推荐）：

dsh --profile grok-byapi-test --from-default-profile web --dump-config
dsh plugin --profile grok-byapi-test add dsh-grok-byapi

这会安装当前 latest，也就是 0.2.1。

从 git 安装，固定 tag：

dsh --profile grok-byapi-test --from-default-profile web --dump-config
dsh plugin --profile grok-byapi-test add "git+https://github.com/NingYuanLee/dsh-grok-byapi.git#v0.2.1"

--dump-config 会基于默认 profile 创建新 profile、打印合并后的配置，不启动服务。dsh plugin add 会把插件记进该 profile 的 dsh.profile.bundles，不需要手动改 YAML。仓库没有 prepare / postinstall 脚本，安装期不执行构建代码，也不需要 allowBuilds。

GitHub Release tarball（发布后可用）：

dsh plugin --profile grok-byapi-test add "https://github.com/NingYuanLee/dsh-grok-byapi/releases/download/v0.2.1/dsh-grok-byapi-0.2.1.tgz"

本地源码（开发调试）：

git clone https://github.com/NingYuanLee/dsh-grok-byapi.git
cd dsh-grok-byapi
npm install --ignore-scripts
dsh --profile grok-byapi-test --from-default-profile web --dump-config
dsh plugin --profile grok-byapi-test add "$PWD" # bash/zsh: "$(pwd)"

用这个 profile 启动：

dsh --profile grok-byapi-test --no-open

建议先把插件放在独立 profile 里试，满意后再进日常 profile，这样提供方、工具和设置不会混进日常环境。需要完全隔离时，把 DSH_HOME 指到临时目录。

更新与卸载

固定 tag 的 git 安装：先移除再装新 tag；本地源码安装：git pull 后 npm install --ignore-scripts；tarball 安装：移除后装新的 .tgz。以上操作完成后重启 dsh。

dsh plugin --profile grok-byapi-test remove dsh-grok-byapi

移除后，插件贡献的 layer 从 profile 消失：提供方、10 个工具和设置页都不再出现。生成物与任务记录不会被删除，需要的话手动清理数据目录。为插件创建的凭据也不会随卸载删除，不再需要时在 dsh 里删掉。

配置

日常配置请用插件设置页。也可以在 profile 的 cordis.patch.yml 里手动覆盖，但这是可选项：

- id: grok-byapi
name: dsh-grok-byapi
config:
connection:
baseURL: http://127.0.0.1:8317/v1
api: openai-responses
apiKeyEnv: GROK_ALL_API_KEY
timeoutMs: 60000
media:
imageModel: grok-imagine-image-2.0
videoModel: grok-imagine-video-1.5
speechModel: grok-tts
dataDir: ''

| 配置项 | 默认值 | 说明 |
| connection.baseURL | http://127.0.0.1:8317/v1 | 网关基础地址。127.0.0.1 指运行 dsh 的电脑；远程网关请用你自己的 HTTPS 地址。 |
| connection.api | openai-responses | 聊天协议，可选 openai-completions。 |
| connection.apiKey | 空 | 本地测试用的直接密钥覆盖，优先于凭据；正常使用保持为空。 |
| connection.apiKeyEnv | GROK_ALL_API_KEY | dsh 凭据服务里的引用名。 |
| connection.verify | true | 保存设置时用已存密钥验证一次 GET /models。 |
| connection.timeoutMs | 60000 | 请求超时，单位毫秒（1000–600000）。 |
| media.imageModel | 空 | 调用未指定 model 时使用的图片模型。 |
| media.videoModel | 空 | 调用未指定 model 时使用的视频模型。 |
| media.speechModel | 空 | 调用未指定 model 时使用的 TTS 模型。 |
| media.dataDir | 空 | 媒体输出目录；为空表示 $DSH_HOME/plugins/dsh-grok-byapi。 |
| modelOverrides | [] | 设置页写入的逐模型覆盖：分类、显示名、是否支持图片、上下文窗口、最大输出、思考强度。下次刷新时生效。 |

设置页会把调用密钥写进 dsh 凭据服务，引用名就是上面的 apiKeyEnv；配置文件只保留引用名，不要把密钥手写进 YAML。示例里的媒体模型 ID 来自测试网关，请用 grok_models 看你的网关实际提供哪些 ID。

安全与隐私

- 网络：只连你配置的网关。发现模型请求 GET /models，聊天走配置的 OpenAI 兼容路由，媒体工具调用同一地址下的图片、视频、TTS 接口。没有遥测。
- 凭据：密钥保存在 dsh 凭据服务里，不写入 YAML、日志、任务记录或仓库；第三方媒体下载不携带网关密钥。
- 文件：生成物写入 $DSH_HOME/plugins/dsh-grok-byapi（或 media.dataDir）。任务记录可能包含上游签名 URL，请当作私有数据。
- 不做的事：不读取或复用 Grok CLI 的 OAuth 令牌，不安装或执行其他插件，不在安装期拉取运行时依赖。

安装任何 dsh 插件都等于用你的用户权限执行第三方代码，工具审批不会隔离插件代码，安装前请先看源码。安全问题请按 SECURITY.md 私下报告。

用法

- 聊天：在模型选择器里选 Grok。选择器只列聊天模型；设置页的对话模型表格就是选择器内容，删掉某行并保存后该模型消失。
- 图片：一次调用完成生成与保存；用本地绝对路径内联结果——说明。dsh Web 通过 /api/file 读取，单文件上限 20 MiB。
- 视频：提交任务（1–15 秒），用返回的 task_id 调 grok_media_status 直到 saved 或 failed；submission-unknown 表示不要重复提交。没有自动轮询，也没有完成通知。
- 语音：grok_speak 生成 MP3；grok_media_retry_download 只重试下载，不会重新生成。
- 展示：视频和音频由工具结果卡片的播放器呈现，不要用 Markdown 图片语法内联；聊天不渲染它们，只会显示破图。

常见问题

以下四项都通过，才算安装成功：

1. dsh --profile grok-byapi-test --dump-config 的输出里能看到 grok-byapi layer。
2. 插件页里本插件存在，且两个组件（提供方与 dsh-grok-imagine）都在运行。
3. grok_models 能返回分类后的模型 ID。
4. 执行 dsh plugin --profile grok-byapi-test remove dsh-grok-byapi 后，layer 与组件都消失。

| 现象 | 处理 |
| dsh plugin add 失败或报 404 | 确认安装的是 npm 上的 dsh-grok-byapi@0.2.1，或改用上面的 git / tarball。 |
| 插件列表里有，但加载不成功 | dsh 不在 >=0.2.1-rc.2 <0.3.0-0 范围内，升级到 0.2.x 构建。 |
| 设置页报 401 或 403 | 密钥或基础地址不对，重新保存密钥并检查 /v1 后缀。 |
| 连接被拒或超时 | 网关没启动或不可达；127.0.0.1 指运行 dsh 的电脑。 |
| 选择器里没有 Grok 模型 | /models 没有返回可判定为聊天的模型；刷新 grok_models 并添加覆盖。 |
| 模型未发现或分类不对 | 刷新 grok_models，再到设置页修正分类。 |
| 聊天正常，图片/视频/TTS 失败 | 网关没有暴露对应的 Grok 接口，插件无法补上。 |
| 视频一直显示生成中 | 用 grok_media_status 查询；submission-unknown 的任务不要重复提交。 |

更多实测行为与限制见 VALIDATION.md。

开发

npm install --ignore-scripts
npm test # 70 项自动测试
npm run check # 源文件语法检查
npm run build # 由 src/client.js 重新生成 lib/client.js
npm pack --dry-run

CI（.github/workflows/ci.yml）在 Linux 与 Windows 上用 Node 22.19 与 24 运行：安装、测试、语法检查、构建、校验 lib/client.js 与构建产物一致、打包预演。推送 v* tag 会触发 .github/workflows/release.yml：校验 tag 与 package.json 版本一致、重跑检查、把打包产物附到 GitHub Release，并且只在配置了 NPM_TOKEN secret 时发布到 npm。npm 发布目前受阻，所以目前以 git / tarball 分发。规划见 ROADMAP.md，变更见 CHANGELOG.md。

社区、许可与免责声明

- Bug 与功能请求：Issues（仓库带 bug report 与 feature request 模板）。
- 安全：SECURITY.md，请使用 GitHub 私有漏洞报告。
- 许可：MIT。Copyright (c) 2026 NingYuanLee。
- 仓库：<https://github.com/NingYuanLee/dsh-grok-byapi>。这是社区插件项目，不是 DeepSeek 或 xAI 官方产品。「ByAPI」表示插件通过你自己的 API 网关访问 Grok，并不代表实现了 Grok 官网的全部功能。