dsh-video-gen

Readme

# dsh-video-gen · MiniMax H3 视频生成插件（DeepSeek Harness）

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Platform](https://img.shields.io/badge/platform-web%20profile-lightgrey)
![Version](https://img.shields.io/badge/version-0.3.0-brightgreen)

让 [DeepSeek Harness](https://github.com/deepseek-ai) 一键获得 **MiniMax H3** 视频生成能力
（经 easyframe 中转）：**文生视频 / 首帧图生 / 首尾帧过渡 / 尾帧续写 / 参考生成（图 + 音频）**，
异步任务自动轮询，MP4 保存到 `outputs/video/` 并在对话里直接以预览卡片播放、下载。

**English quick install** — pick one line and run it in your terminal:

```bash
# Already running DSH (web profile):       已经装好 DSH（Web 版）的用户
dsh plugin --profile web add github:oebeliever/dsh-video-gen

# Brand-new machine, one click (auto-installs Node/pnpm/DSH):
# Windows PowerShell:
irm https://raw.githubusercontent.com/oebeliever/dsh-video-gen/main/install.ps1 | iex
# macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/oebeliever/dsh-video-gen/main/install.sh | bash
```

Then restart DSH (`dsh web`), open **Settings → Plugins → Plugin config → MiniMax H3 视频生成**,
paste an easyframe API key (`sk-...`), and ask the AI to call `video-generate`. Full docs in Chinese below ↓

---

## 目录

1. [这是什么](#这是什么)
2. [功能一览](#功能一览)
3. [安装（三种方式，越往下越省事）](#安装)
4. [升级与卸载](#升级与卸载)
5. [配置](#配置)
6. [对话工具](#对话工具)
7. [🎬 视频生成工作台](#-视频生成工作台)
8. [输出与存储](#输出与存储)
9. [常见问题 FAQ](#常见问题-faq)
10. [开发](#开发)
11. [License](#license)

## 这是什么

本插件是 DeepSeek Harness（`web` profile）的双端插件：

- **host 半**（`lib/index.js`）：注册 `video-generate` / `video-image2video` / `video-status` /
  `video-cancel` / `video-queue` 五个工具，以及设置命名空间 `video-gen` 与工作台 HTTP 路由；
- **client 半**（`lib/client.js`）：设置卡片（API Key + 默认参数）+ 对话内 MP4 预览卡片 +
  输入框上方的「🎬 视频生成工作台」。

生成走 **easyframe 中转的 MiniMax H3**（OpenAI 风格 `POST /v1/videos`，`task_` 开头任务 ID），
本地文件自动转 multipart 上传，全程无第三方运行时依赖（仅用 Node ≥ 20 原生 `fetch`）。

## 功能一览

- **5 种生成模式**：文生（t2va）、首帧图生（i2va）、首尾帧过渡（fl2va）、尾帧续写（l2va）、
  参考生成（ref2va，最多 9 张参考图 + 3 个参考音频）；`mode=auto` 按素材自动推断；
- **对话内直接出片**：完成后 MP4 以预览卡片显示，可播放/下载；文件同时落盘 `outputs/video/`；
- **任务全生命周期**：创建即返回 `task_id`，自动轮询到完成；随时 `video-status` 续查续等、
  `video-cancel` 取消、`video-queue` 查看排队与并发；
- **可视化工作台**：即梦式四步界面（画面设置 → 选择模式与素材 → 自动生成提示词 → 生成并查看），
  支持点击/拖拽上传、历史视频库、实时额度与排队面板；
- **参数控制**：模型档位（base / fast / mini）、清晰度（480p / 720p）、画幅 9 种、
  时长 5–15 秒、AI 提示词优化开关；
- **省钱与安全**：默认不并发、限时轮询可调；API Key 只在本机明文保存（`~/.dsh/settings.yaml`），
  也可改用环境变量 `MINIMAX_API_KEY`。

## 安装

> 环境要求（全新机器也只需满足这两条，其余交给一键脚本）：
> - [Node.js](https://nodejs.org) ≥ 20（DSH 官方建议 22.19.x 或 24 LTS）；
> - pnpm（`dsh plugin` 内部调用 pnpm；Node 自带 corepack，`corepack enable` 即可）；
> - 能访问 `registry.npmjs.org` 与 `github.com`（网络受限时请先配置代理）。
> 插件面向 DSH `web` profile（Web 界面版，默认 `http://127.0.0.1:3080`）。

### 方式 A：全新机器一键安装（最省事，推荐给朋友）

Windows PowerShell（复制整行回车）：

```powershell
irm https://raw.githubusercontent.com/oebeliever/dsh-video-gen/main/install.ps1 | iex
```

macOS / Linux 终端：

```bash
curl -fsSL https://raw.githubusercontent.com/oebeliever/dsh-video-gen/main/install.sh | bash
```

脚本自动完成：检查 Node.js（Windows 缺失时用 winget 装 LTS）→ 启用 pnpm →
全局安装 `@deepseek-ai/dsh`（若没有）→ `dsh plugin add` 本插件 → 打印启动指引。

### 方式 B：已装 DSH，一条命令（最快）

```bash
dsh plugin --profile web add github:oebeliever/dsh-video-gen
```

装完**重启 dsh**（重新运行 `dsh web`），插件即出现在设置与对话工具里。

### 方式 C：不想全局装 dsh？用 npx（首次稍慢，免安装）

```bash
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:oebeliever/dsh-video-gen
```

之后也请用同一种方式启动：`npx --yes -p @deepseek-ai/dsh dsh web`。

> 插件包内的 `dsh.bundle` 声明会让 DSH 自动把插件挂进 profile 的 bundle 层，无需手改任何配置。

## 升级与卸载

升级 = 重跑对应的安装命令（`add` 会拉取仓库最新版本），然后重启 dsh。无需先卸载。

卸载：

```bash
dsh plugin --profile web remove dsh-video-gen
```

重启后，工具与「MiniMax H3 视频生成」设置卡片即被移除（历史视频文件保留在 `~/.dsh/storages/video-gen/library`）。

## 配置

打开 **设置 → 插件 → 插件配置 → MiniMax H3 视频生成**：

| 字段 | 说明 |
|---|---|
| API Key（明文） | easyframe 平台创建的 `sk-` 开头 Key；明文保存在本机 `~/.dsh/settings.yaml`，页面可查看/修改。也可不填、改用环境变量 `MINIMAX_API_KEY` |
| 接口地址（可选） | 默认 `https://minimax.api.easyframe.cn`，一般无需修改 |
| 模型档位 | `minimax-h3-base`（默认）/ `minimax-h3-fast` / `minimax-h3-mini` |
| 清晰度 | 480p / 720p |
| 画幅 | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / 9:21 / 4:5 / 5:4 |
| 时长 | 5~15 秒 |
| AI 提示词优化 | 关 = 提示词逐字发送；开 = 授权平台重组结构描述（台词/歌词/画面文字仍逐字保留） |
| 轮询时长 | 默认 600 秒（30~3600），任务排队/生成超过该时长会先返回 `task_id`，可继续用工具续查 |

**没有 easyframe API Key？** 到 easyframe 开通（接口文档与面板入口：
<https://minimax.api.easyframe.cn/docs/>），创建 `sk-` 开头 Key 并在平台钱包充值后即可使用。

## 对话工具

安装后，AI 会自动获得以下工具（也可在对话里直接点名使用）：

| 工具 | 用途 |
|---|---|
| `video-generate` | 文生视频：给一句描述（含运镜/动作/节奏），自动创建 → 轮询 → 下载，对话内出预览卡片 |
| `video-image2video` | 图生/首尾帧/参考生成：传图片路径/URL（1 张=首帧，2 张=首尾帧，≥3 张=参考图），可带音频 |
| `video-status` | 按 `task_id` 只查一次或续等 `waitSeconds`，成功后自动下载并显示预览卡片 |
| `video-cancel` | 取消排队/生成中的任务 |
| `video-queue` | 查看并发上限、排队数与当前 Key 的任务位置 |

示例对话：

```text
调用 video-generate 生成一段 10 秒横版视频：黄昏城市天台，镜头缓缓推近，
一对情侣在晚霞中相拥，发丝被风吹动，背景有远处车流的柔和虚化。
```

```text
video-image2video：首帧用 D:\shots\sky.png，尾帧用 D:\shots\night.png，
过渡 8 秒，提示词「云层从晚霞渐变到星空」。
```

## 🎬 视频生成工作台

聊天输入框上方会出现工作台入口，即梦式步骤化界面：

1. **画面与声音设置**：模型 / 清晰度 / 画幅 / 时长，AI 提示词优化开关；
2. **生成方式页签**：文生 / 首帧图生 / 首尾帧过渡 / 尾帧续写 / 参考生成；素材卡支持点击与
   拖拽上传（图片预览并标注首帧/尾帧/编号；音频可试听，最多 3 个）；
3. **提示词**：点「✨ 自动生成提示词」按模式与素材自动组装官方 H3 结构提示词，可继续编辑；
4. **生成并查看**：任务卡实时轮询（排队/进度/完成/失败），完成后内嵌播放 + 下载；右上
   「💰 额度」实时显示网关用量（60s 自动刷新），「排队情况」查看并发与队列。

## 输出与存储

- 每次生成的 MP4 保存到会话目录的 `outputs/video/video-<时间戳>.mp4`（重名自动编号）；
- 工作台「历史视频」读的是 `~/.dsh/storages/video-gen/library`（保留 7 天、最多 300 条），
  dsh 重启后历史视频仍可播放。

## 常见问题 FAQ

| 现象 | 处理 |
|---|---|
| 提示「未配置 API Key」 | 到 设置 → 插件 → 插件配置 填写，或设置环境变量 `MINIMAX_API_KEY` 后重启 dsh |
| HTTP 401 / 403 | Key 无效或额度不足；到 easyframe 平台核对 Key、余额（钱包页） |
| 一直 queued | 平台高峰期排队；用 `video-queue` 看队列与供给期限，等即可 |
| 提示「等待超时」 | 任务仍在跑；用 `video-status`（`waitSeconds`）续查，或在设置里调大轮询时长 |
| 模型参数报错 | 只支持 `minimax-h3-base` / `-fast` / `-mini` 三个档位（pro 未开放） |
| 想自定义中转 | 自己的服务若兼容 easyframe `/v1/videos` 协议，改「接口地址」即可 |
| 插件装了没出现 | 确认是 `web` profile 且**重启过 dsh**；`dsh --profile web --help` 可看运行参数 |

## 开发

```bash
node --check lib/index.js
node --check lib/client.js
```

目录：`lib/index.js`（host 半：工具 + 设置 + 工作台路由）、`lib/client.js`（Web 客户端：
设置卡片 + 预览卡片 + 工作台 UI）。顶层零第三方运行时依赖，改完同步到本地插件目录并重启 dsh 即可生效。

## License

[MIT](./LICENSE) © 2026 [oebeliever](https://github.com/oebeliever)