前言¶
在 DeepSeek Harness（DSH）里做智能体，常见做法是接一家云厂商的 API，或在本地起一个 OpenAI 兼容网关，再把模型填进配置。若你已经在跑 Grok 的兼容网关（文档默认场景是 CLIProxyAPI），还希望聊天模型出现在模型选择器里，同时把出图、出视频、朗读做成可被任意对话模型调用的工具，就需要一个把「网关连接、模型发现、凭证、本地媒体任务」串起来的插件，而不是在 Harness 里手写多段 HTTP 与文件逻辑。
下面介绍社区插件 dsh-grok-byapi（维护者 NingYuanLee，分类：模型推理）。它通过你自建的 OpenAI 兼容 /v1 端点连接 Grok，在 DSH 中注册原生聊天 Provider，并附带图像、视频、TTS 相关工具；API Key 走 DSH 凭证服务，生成结果落盘。插件不是 OAuth 客户端，不提供账号或配额，也不读取 Grok CLI 的 OAuth Token。
这是什么¶
dsh-grok-byapi（npm 包名 dsh-grok-byapi，显示名 Grok ByAPI）的定位是：在 DeepSeek Harness 里以「一个插件、一条网关连接」的方式使用 Grok——聊天走 Provider，图像 / 视频 / 语音走工具，且媒体任务按会话持久化、支持断点式下载校验。
与「只在 Harness 里配一个 OpenAI 兼容 Base URL」相比，该插件额外做了：GET /models 目录发现与按能力分类、仅聊天模型进入选择器、设置页（连接、Key 校验、超时、聊天模型表、媒体模型选择）、工具结果卡片与侧边栏播放 MP4 / MP3 / WAV。当前 npm latest 为 0.2.1；聊天路由仍依赖 dsh 0.2.1-rc.2 的适配器注册，宿主升级后建议按仓库 VALIDATION.md 重跑集成测试。
目录页：SkillHub - dsh-grok-byapi
源码与说明：GitHub - NingYuanLee/dsh-grok-byapi（MIT 许可证）
核心功能¶
聊天 Provider 与模型目录¶
插件注册原生 dsh LLM Provider，路由名为 xAI-CLIProxyAPI，界面显示为 Grok。流式文本与工具调用经官方 pi-ai 适配器转发。
模型目录通过网关 GET /models 拉取，并按规则归类为 chat、image、video、speech、research 或 unknown；只有 chat 模型进入模型选择器，unknown 不会出现在选择器里。可对单个模型做覆盖配置。设置页中的聊天模型表是选择器的来源。
两个组件与十项工具¶
插件拆成两个组件：插件页负责连接与模型设置；grok-byapi 侧重聊天与目录，dsh-grok-imagine 侧重图像、视频与语音。合计注册 10 个工具：
| 工具 | 作用 |
|---|---|
grok_models |
刷新目录并按能力分组；可选 verify_key 用一次 GET /models 校验地址与 Key |
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 |
视频编辑：prompt 加 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 |
图像、视频、TTS 模型不会进入聊天模型选择器，由工具按配置选用；任意聊天模型（Grok 或其他 Provider）都可以调用这些工具。
媒体任务与界面¶
媒体任务按会话记录，重启后仍可恢复。下载先写 .part 文件，校验通过后重命名；存储按连接与任务隔离。聊天里展示工具结果卡片、文件预览，以及 MP4 / MP3 / WAV 的侧边栏播放器；文案跟随 DSH 语言（英文或中文）。
未提供的能力包括：语音识别、实时语音、直接 OAuth、实时任务仪表盘。视频任务提交后在进程内轮询，但结果卡片不会自动刷新；模型分类为规则推断，不作保证。
环境与兼容¶
| 组件 | 要求 | 文档记载验证情况 |
|---|---|---|
| dsh | >=0.2.1-rc.2 <0.3.0-0（engines.dsh） |
在 0.2.1-rc.2 上端到端验证聊天、图像、视频、TTS、播放 |
| Node.js | >=22.19.0 |
CI 在 Linux / Windows 上跑 Node 22.19 与 24 |
| 网关 | OpenAI 兼容 /v1；推荐 CLIProxyAPI |
文档记载 CLIProxyAPI v8.0.30 |
可直接对接 xAI 或其他兼容端点做聊天，但图像、视频、TTS 需要网关暴露对应的 Grok 接口。engines.dsh 是兼容门槛；升级 dsh 后应重跑集成测试。
安装与启用¶
官方推荐从 npm 安装当前 latest（0.2.1）。先用独立 profile 试用，避免污染日常环境；需要完全隔离时可将 DSH_HOME 指向临时目录。
下面两条命令会基于默认 profile 的 web 配置生成名为 grok-byapi-test 的 profile 并登记插件 bundle，无需手改 YAML；包无 prepare / postinstall，安装不会执行构建脚本：
dsh --profile grok-byapi-test --from-default-profile web --dump-config
dsh plugin --profile grok-byapi-test add dsh-grok-byapi
--dump-config 会合并配置并打印结果，不启动服务。安装完成后用同一 profile 启动：
dsh --profile grok-byapi-test --no-open
若需固定版本，可使用 git 标签或 Release 中的 .tgz（见仓库 README 的 Install 小节）。卸载：
dsh plugin --profile grok-byapi-test remove dsh-grok-byapi
卸载会移除 Provider、10 个工具与设置页；已生成的媒体与任务记录不会自动删除，需自行清理数据目录。
典型用法¶
1、配置网关与 Key¶
在 DSH 插件设置页填写网关地址与 API Key，必要时在设置里做连接校验与超时配置；Key 保存在 DSH 凭证服务中。聊天模型表决定模型选择器内容；媒体相关模型在设置里单独选择。
2、聊天中选 Grok¶
在模型选择器里选用由该 Provider 暴露的 Grok 聊天模型，正常对话即可；流式输出与工具调用走 pi-ai 适配器。
3、用工具生成媒体¶
在对话中让模型调用对应工具，例如：
- 刷新或校验目录：调用
grok_models（需要时可带verify_key）。 - 文生图：
grok_generate_image，传入prompt，可选model、n。 - 文生视频或图生视频：
grok_generate_video，控制duration（1–15 秒）。 - 朗读：
grok_speak，传入input，可选voice。 - 长任务：用
grok_media_status查task_id；下载失败用grok_media_retry_download；会话内枚举用grok_media_list。
仓库 README 中的 Demo 区展示了 grok_generate_image、grok-imagine-image-2.0 出图与 grok_generate_video 短片示例，可作为能力对照，并非额外安装步骤。
适用场景与注意¶
适合：你已有或可部署 OpenAI 兼容 Grok 网关（尤其 CLIProxyAPI），希望在 DSH 里统一完成 Grok 聊天、多模态工具调用与本地媒体留存，且愿意用独立 profile 先验证再并入主环境。
注意：
- 插件在当前 dsh 进程权限下运行，安装前请阅读源码与 MIT 许可证，确认网关与 Key 策略符合你的安全要求。
- 不提供官方账号、配额或 OAuth；计费与限流由你的网关与上游决定。
- 宿主 dsh 版本须在
engines.dsh范围内；README 注明聊天路由依赖0.2.1-rc.2适配器注册，升级 Harness 后请按 VALIDATION 复测。 - 视频轮询与分类规则有 README 中列出的局限，不要假设与官方控制台行为完全一致。
DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-grok-byapi 把自建 Grok 网关上的对话、目录发现、图像 / 视频 / TTS 工具与本地持久化媒体任务收进一个 DSH 插件，适合已有兼容网关、希望在 Harness 里用 Grok 做全链路实验的开发者。进一步了解可访问 SkillHub 插件页 与 GitHub 仓库。
