dsh-grok-byapi

dsh plugin --profile web add dsh-grok-byapi

dsh-grok-byapi

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

       

[English](README.md) | 中文

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

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

演示

插件页 · 设置页

 · 

下面两张都是这个插件用 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.

…(truncated)