dsh-ffmpeg 0.1.0

package/README.en.md

@@ -0,0 +1,68 @@
+[中文](README.md)
+
+# dsh-ffmpeg
+
+DSH (DeepSeek Harness) video-processing plugin: seven tools covering probing, cutting, concatenation, transcoding, subtitles, extraction and GIF creation — all powered by ffmpeg/ffprobe.
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-ffmpeg
+```
+
+ffmpeg must be installed locally (`ffmpeg -version` should work); use `ffmpegPath` / `ffprobePath` when it is not on PATH.
+
+## Configuration
+
+Override the plugin row in your profile's `cordis.patch.yml` (defaults apply when absent):
+
+```yaml
+- id: ffmpeg
+  name: 'dsh-ffmpeg'
+  config:
+    # ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe   # explicit path when not on PATH
+    # ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe
+    timeoutMs: 300000                                # per-operation timeout (default 5 min, 10s - 2h)
+    # overwrite: true                                 # allow overwriting outputs (default auto-suffix _1/_2)
+```
+
+## Tools
+
+| Tool | Purpose | Key parameters |
+| :-- | :-- | :-- |
+| `ffmpeg_probe` | Probe media info (format/duration/resolution/fps/bitrate/audio/subtitle streams) | `input` required |
+| `ffmpeg_cut` | Cut a clip (stream copy by default, accurate re-encode optional) | `input` required; `start`/`end`/`duration` |
+| `ffmpeg_concat` | Concatenate 2-20 clips (stream copy for identical codecs / re-encode for mixed) | `inputs` array required |
+| `ffmpeg_encode` | Transcode with presets (bilibili 1080p/4K, vertical 1080p, web-720p) plus crf/fps/scale overrides | `input` required; `preset` optional |
+| `ffmpeg_subtitle` | Burn subtitles (SRT/ASS hard subs) | `input` + `subtitle` required |
+| `ffmpeg_extract` | Extract audio (m4a) / frame sequences / single frame / subtitle stream | `input` + `what` required |
+| `ffmpeg_gif` | Video to high-quality GIF (two-pass palette) | `input` required; `fps`/`width`/`duration` optional |
+
+### Examples
+
+```text
+ffmpeg_probe { input: E:\videos\raw.mp4 }
+ffmpeg_cut { input: E:\videos\raw.mp4, start: 10, end: 30 }
+ffmpeg_encode { input: E:\videos\raw.mp4, preset: bilibili-1080p }
+ffmpeg_subtitle { input: E:\videos\raw.mp4, subtitle: E:\videos\subs.srt }
+ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }
+```
+
+## Safety
+
+- **No shell**: every argument is passed as its own argv element — user input cannot inject commands
+- **Runs on the official DSH subprocess service**: tree-scoped termination (timeout escalates SIGTERM → kill; taskkill /T on Windows), zero runtime dependencies
+- **No accidental overwrites**: existing outputs get auto-suffixed; output == input is rejected
+- **Timeout clamps**: per-operation 10s - 2h; probes additionally capped at 60s
+- **Input validation**: time formats, preset enums, crf/fps/scale ranges are validated up front with actionable errors
+
+## Development
+
+```bash
+pnpm install
+pnpm test       # build + 50 tests, including a real-ffmpeg end-to-end suite (auto-skipped without ffmpeg)
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,68 @@
+[English](README.en.md)
+
+# dsh-ffmpeg
+
+DSH（DeepSeek Harness）视频处理工具插件：七个工具覆盖探测、剪辑、拼接、转码、字幕、提取与 GIF 制作，全部由 ffmpeg/ffprobe 完成。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-ffmpeg
+```
+
+需要本机已安装 ffmpeg（`ffmpeg -version` 能出结果即可）；不在 PATH 上时用 `ffmpegPath`/`ffprobePath` 显式指定。
+
+## 配置
+
+在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时全部用默认值）：
+
+```yaml
+- id: ffmpeg
+  name: 'dsh-ffmpeg'
+  config:
+    # ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe   # 非 PATH 时显式指定
+    # ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe
+    timeoutMs: 300000                                # 单次操作超时（默认 5 分钟，10 秒 - 2 小时）
+    # overwrite: true                                 # 允许覆盖同名输出（默认自动加 _1/_2 序号）
+```
+
+## 工具一览
+
+| 工具 | 作用 | 关键参数 |
+| :-- | :-- | :-- |
+| `ffmpeg_probe` | 探测媒体信息（格式/时长/分辨率/帧率/码率/音轨/字幕轨） | `input` 必填 |
+| `ffmpeg_cut` | 剪辑片段（默认流拷贝秒级，可精确重编码） | `input` 必填；`start`/`end`/`duration` |
+| `ffmpeg_concat` | 拼接 2-20 个片段（同编码流拷贝 / 混合编码重编码） | `inputs` 数组必填 |
+| `ffmpeg_encode` | 转码（B 站 1080p/4K、竖屏 1080p、web-720p 预设 + crf/fps/scale 覆盖） | `input` 必填；`preset` 可选 |
+| `ffmpeg_subtitle` | 字幕烧录（SRT/ASS 硬字幕） | `input`+`subtitle` 必填 |
+| `ffmpeg_extract` | 提取音轨（m4a）/ 抽帧序列 / 单帧 / 字幕流 | `input`+`what` 必填 |
+| `ffmpeg_gif` | 视频转高质量 GIF（两遍调色板） | `input` 必填；`fps`/`width`/`duration` 可选 |
+
+### 示例
+
+```text
+ffmpeg_probe { input: E:\videos\raw.mp4 }
+ffmpeg_cut { input: E:\videos\raw.mp4, start: 10, end: 30 }
+ffmpeg_encode { input: E:\videos\raw.mp4, preset: bilibili-1080p }
+ffmpeg_subtitle { input: E:\videos\raw.mp4, subtitle: E:\videos\subs.srt }
+ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }
+```
+
+## 安全设计
+
+- **无 shell**：所有参数以独立 argv 数组传递，用户输入不可能注入命令
+- **进程走 DSH 官方 subprocess 服务**：树级终止（超时自动 SIGTERM → 强杀，Windows taskkill /T），本插件零运行时依赖
+- **防覆写**：默认不覆盖同名文件（自动加序号），输出与输入相同直接拒绝
+- **超时钳制**：单次操作 10 秒 - 2 小时；探测额外限制 60 秒
+- **参数校验**：时间格式、预设枚举、crf/fps/scale 范围全部前置校验，错误带中文指引
+
+## 开发
+
+```bash
+pnpm install
+pnpm test       # 构建 + 50 个测试（含真实 ffmpeg 端到端集成，缺 ffmpeg 自动跳过）
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# dsh-ffmpeg 组合包补丁：把视频处理工具插件行插入 profile。
+# 本补丁按 id 覆盖；用户应在自己 profile 的 cordis.patch.yml 里覆盖本行的整个
+# config（见 README 的配置示例）。配置缺失时插件仍会加载（依赖 PATH 上的 ffmpeg）。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: ffmpeg
+#     name: 'dsh-ffmpeg'
+#     config:
+#       # ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe   # 非 PATH 时显式指定
+#       # ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe
+#       timeoutMs: 300000                                # 单次操作超时（默认 5 分钟）
+#       # overwrite: true                                 # 允许覆盖同名输出（默认自动加后缀）
+#
+- insert:
+    - id: ffmpeg
+      name: 'dsh-ffmpeg'
+      config:
+        timeoutMs: 300000

package/lib/args.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ffmpeg/ffprobe 命令行构建器：纯函数，输入业务参数输出完整 argv 数组（argv[0] 为程序）。
+ * 所有参数以独立数组元素传递，绝不经过 shell 解释——用户输入无法注入命令。
+ *
+ * @module dsh-ffmpeg/args
+ */
+/** 秒数格式化为 ffmpeg 友好的定点字符串。 */
+export declare function fmtSeconds(seconds: number): string;
+/** 转义 filter 路径（Windows 冒号与反斜杠、单引号）。 */
+export declare function escapeFilterPath(path: string): string;
+/** ffprobe 探测命令。 */
+export declare function probeArgs(ffprobe: string, input: string): string[];
+export interface CutArgsSpec {
+    input: string;
+    start: number;
+    duration: number;
+    output: string;
+    overwrite: boolean;
+    reencode: boolean;
+}
+/** 剪辑：流拷贝（快、关键帧对齐）或重编码（精确到帧）。 */
+export declare function cutArgs(ffmpeg: string, spec: CutArgsSpec): string[];
+export interface ConcatSpec {
+    inputs: string[];
+    listFilePath?: string;
+    output: string;
+    overwrite: boolean;
+    reencode: boolean;
+}
+/** 拼接：同编码流拷贝走 concat demuxer（需 list 文件），否则 filter_complex 重编码。 */
+export declare function concatArgs(ffmpeg: string, spec: ConcatSpec): string[];
+/** concat demuxer 的 list 文件内容（路径中的单引号按 ffmpeg 规则转义）。 */
+export declare function concatListContent(inputs: string[]): string;
+export type EncodePreset = 'bilibili-1080p' | 'bilibili-4k' | 'vertical-1080p' | 'web-720p';
+export declare const ENCODE_PRESETS: EncodePreset[];
+export interface EncodeSpec {
+    input: string;
+    output: string;
+    preset: EncodePreset;
+    crf?: number;
+    fps?: number;
+    scale?: string;
+    overwrite: boolean;
+}
+/** 转码：预设 + 可选的 crf/fps/scale 覆盖。 */
+export declare function encodeArgs(ffmpeg: string, spec: EncodeSpec): string[];
+export interface SubtitleSpec {
+    input: string;
+    subtitle: string;
+    output: string;
+    overwrite: boolean;
+}
+/** 字幕烧录（subtitles filter，路径转义）。 */
+export declare function subtitleArgs(ffmpeg: string, spec: SubtitleSpec): string[];
+export type ExtractWhat = 'audio' | 'frames' | 'frame' | 'subtitle';
+export interface ExtractSpec {
+    input: string;
+    what: ExtractWhat;
+    output: string;
+    overwrite: boolean;
+    start?: number;
+    duration?: number;
+    fps?: number;
+    streamIndex: number;
+}
+/** 提取：音频（拷贝）/ 抽帧序列 / 单帧 / 字幕流。 */
+export declare function extractArgs(ffmpeg: string, spec: ExtractSpec): string[];
+export interface GifSpec {
+    input: string;
+    output: string;
+    palettePath: string;
+    overwrite: boolean;
+    start: number;
+    duration: number;
+    fps: number;
+    width: number;
+}
+/** GIF 第一遍：调色板生成（palettegen）。 */
+export declare function gifPaletteArgs(ffmpeg: string, spec: GifSpec): string[];
+/** GIF 第二遍：paletteuse 合成。 */
+export declare function gifUseArgs(ffmpeg: string, spec: GifSpec): string[];

package/lib/args.js

@@ -0,0 +1,106 @@
+/**
+ * ffmpeg/ffprobe 命令行构建器：纯函数，输入业务参数输出完整 argv 数组（argv[0] 为程序）。
+ * 所有参数以独立数组元素传递，绝不经过 shell 解释——用户输入无法注入命令。
+ *
+ * @module dsh-ffmpeg/args
+ */
+/** 秒数格式化为 ffmpeg 友好的定点字符串。 */
+export function fmtSeconds(seconds) {
+    return seconds.toFixed(3);
+}
+/** 覆写标志：不覆写用 -n（目标存在即报错，双保险），覆写用 -y。 */
+function overwriteFlag(overwrite) {
+    return overwrite ? '-y' : '-n';
+}
+/** 转义 filter 路径（Windows 冒号与反斜杠、单引号）。 */
+export function escapeFilterPath(path) {
+    return path.replace(/\\/g, '/').replace(/:/g, '\\:').replace(/'/g, "\\'");
+}
+/** ffprobe 探测命令。 */
+export function probeArgs(ffprobe, input) {
+    return [ffprobe, '-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', input];
+}
+/** 剪辑：流拷贝（快、关键帧对齐）或重编码（精确到帧）。 */
+export function cutArgs(ffmpeg, spec) {
+    const flag = overwriteFlag(spec.overwrite);
+    if (!spec.reencode) {
+        return [ffmpeg, flag, '-ss', fmtSeconds(spec.start), '-i', spec.input, '-t', fmtSeconds(spec.duration), '-c', 'copy', '-avoid_negative_ts', 'make_zero', spec.output];
+    }
+    return [ffmpeg, flag, '-i', spec.input, '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', '-c:a', 'aac', spec.output];
+}
+/** 拼接：同编码流拷贝走 concat demuxer（需 list 文件），否则 filter_complex 重编码。 */
+export function concatArgs(ffmpeg, spec) {
+    const flag = overwriteFlag(spec.overwrite);
+    if (!spec.reencode) {
+        return [ffmpeg, flag, '-f', 'concat', '-safe', '0', '-i', spec.listFilePath ?? '', '-c', 'copy', spec.output];
+    }
+    const parts = [ffmpeg, flag];
+    for (const input of spec.inputs)
+        parts.push('-i', input);
+    parts.push('-filter_complex', 'concat=n=' + spec.inputs.length + ':v=1:a=1', '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', '-c:a', 'aac', spec.output);
+    return parts;
+}
+/** concat demuxer 的 list 文件内容（路径中的单引号按 ffmpeg 规则转义）。 */
+export function concatListContent(inputs) {
+    return inputs.map((input) => "file '" + input.replace(/\\/g, '/').replace(/'/g, "'\\''") + "'").join('\n') + '\n';
+}
+export const ENCODE_PRESETS = ['bilibili-1080p', 'bilibili-4k', 'vertical-1080p', 'web-720p'];
+const PRESET_TABLE = {
+    'bilibili-1080p': { crf: 20, maxrate: '6000k', bufsize: '12000k' },
+    'bilibili-4k': { crf: 18, maxrate: '20000k', bufsize: '40000k' },
+    'vertical-1080p': { crf: 20, maxrate: '6000k', bufsize: '12000k', vf: 'scale=-2:1920' },
+    'web-720p': { crf: 23, maxrate: '2800k', bufsize: '5600k', vf: 'scale=-2:720' },
+};
+/** 转码：预设 + 可选的 crf/fps/scale 覆盖。 */
+export function encodeArgs(ffmpeg, spec) {
+    const preset = PRESET_TABLE[spec.preset];
+    const crf = spec.crf ?? preset.crf;
+    const parts = [ffmpeg, overwriteFlag(spec.overwrite), '-i', spec.input];
+    const vf = spec.scale !== undefined && spec.scale !== '' ? 'scale=' + spec.scale : preset.vf;
+    if (vf !== undefined && vf !== '')
+        parts.push('-vf', vf);
+    if (spec.fps !== undefined)
+        parts.push('-r', String(spec.fps));
+    parts.push('-c:v', 'libx264', '-preset', 'medium', '-crf', String(crf), '-maxrate', preset.maxrate, '-bufsize', preset.bufsize, '-pix_fmt', 'yuv420p', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', spec.output);
+    return parts;
+}
+/** 字幕烧录（subtitles filter，路径转义）。 */
+export function subtitleArgs(ffmpeg, spec) {
+    const filter = "subtitles='" + escapeFilterPath(spec.subtitle) + "'";
+    return [ffmpeg, overwriteFlag(spec.overwrite), '-i', spec.input, '-vf', filter, '-c:a', 'copy', spec.output];
+}
+/** 提取：音频（拷贝）/ 抽帧序列 / 单帧 / 字幕流。 */
+export function extractArgs(ffmpeg, spec) {
+    const flag = overwriteFlag(spec.overwrite);
+    if (spec.what === 'audio') {
+        return [ffmpeg, flag, '-i', spec.input, '-vn', '-c', 'copy', spec.output];
+    }
+    if (spec.what === 'subtitle') {
+        return [ffmpeg, flag, '-i', spec.input, '-map', '0:s:' + spec.streamIndex, '-c', 'copy', spec.output];
+    }
+    if (spec.what === 'frame') {
+        const parts = [ffmpeg, flag, '-i', spec.input];
+        if (spec.start !== undefined)
+            parts.push('-ss', fmtSeconds(spec.start));
+        parts.push('-frames:v', '1', spec.output);
+        return parts;
+    }
+    // frames 序列
+    const parts = [ffmpeg, flag, '-i', spec.input];
+    if (spec.start !== undefined)
+        parts.push('-ss', fmtSeconds(spec.start));
+    if (spec.duration !== undefined)
+        parts.push('-t', fmtSeconds(spec.duration));
+    parts.push('-vf', 'fps=' + (spec.fps ?? 1), spec.output);
+    return parts;
+}
+/** GIF 第一遍：调色板生成（palettegen）。 */
+export function gifPaletteArgs(ffmpeg, spec) {
+    const filter = 'fps=' + spec.fps + ',scale=' + spec.width + ':-1:flags=lanczos,palettegen';
+    return [ffmpeg, '-y', '-i', spec.input, '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-vf', filter, spec.palettePath];
+}
+/** GIF 第二遍：paletteuse 合成。 */
+export function gifUseArgs(ffmpeg, spec) {
+    const filter = 'fps=' + spec.fps + ',scale=' + spec.width + ':-1:flags=lanczos[x];[x][1:v]paletteuse';
+    return [ffmpeg, overwriteFlag(spec.overwrite), '-i', spec.input, '-ss', fmtSeconds(spec.start), '-t', fmtSeconds(spec.duration), '-i', spec.palettePath, '-filter_complex', filter, spec.output];
+}

package/lib/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * dsh-ffmpeg 配置解析：ffmpeg/ffprobe 路径、超时、覆写策略。
+ * 缺失字段给默认值；非法字段抛中文错误。
+ *
+ * @module dsh-ffmpeg/config
+ */
+/** 插件行配置（cordis.patch.yml 里的 config 段，可缺省）。 */
+export interface FfmpegConfig {
+    ffmpegPath?: string;
+    ffprobePath?: string;
+    timeoutMs?: number;
+    graceMs?: number;
+    overwrite?: boolean;
+}
+/** 解析后的配置：所有字段都有值。 */
+export interface ResolvedFfmpegConfig {
+    ffmpegPath: string;
+    ffprobePath: string;
+    timeoutMs: number;
+    graceMs: number;
+    overwrite: boolean;
+}
+/**
+ * 解析并校验配置。
+ * @param config - 插件行配置（可能为 undefined/null）。
+ * @throws 配置值非法时抛出中文错误。
+ */
+export declare function resolveConfig(config: FfmpegConfig | undefined | null): ResolvedFfmpegConfig;
+/**
+ * 解析时间参数：接受秒数（正数）或 HH:MM:SS[.mmm] 字符串。
+ * 返回秒（浮点）；非法返回 null。
+ */
+export declare function parseTimeArg(value: unknown): number | null;

package/lib/config.js

@@ -0,0 +1,55 @@
+/**
+ * dsh-ffmpeg 配置解析：ffmpeg/ffprobe 路径、超时、覆写策略。
+ * 缺失字段给默认值；非法字段抛中文错误。
+ *
+ * @module dsh-ffmpeg/config
+ */
+const DEFAULT_TIMEOUT_MS = 300000;
+const DEFAULT_GRACE_MS = 15000;
+/**
+ * 解析并校验配置。
+ * @param config - 插件行配置（可能为 undefined/null）。
+ * @throws 配置值非法时抛出中文错误。
+ */
+export function resolveConfig(config) {
+    const cfg = config ?? {};
+    const ffmpegPath = typeof cfg.ffmpegPath === 'string' && cfg.ffmpegPath.trim() !== '' ? cfg.ffmpegPath.trim() : 'ffmpeg';
+    const ffprobePath = typeof cfg.ffprobePath === 'string' && cfg.ffprobePath.trim() !== '' ? cfg.ffprobePath.trim() : 'ffprobe';
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    if (cfg.timeoutMs !== undefined) {
+        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0) {
+            throw new Error('timeoutMs 必须是大于 0 的数字（毫秒），例如 300000。');
+        }
+        timeoutMs = Math.min(2 * 60 * 60 * 1000, Math.max(10000, Math.round(cfg.timeoutMs)));
+    }
+    let graceMs = DEFAULT_GRACE_MS;
+    if (cfg.graceMs !== undefined) {
+        if (typeof cfg.graceMs !== 'number' || !Number.isFinite(cfg.graceMs) || cfg.graceMs <= 0) {
+            throw new Error('graceMs 必须是大于 0 的数字（毫秒），例如 15000。');
+        }
+        graceMs = Math.min(120000, Math.max(1000, Math.round(cfg.graceMs)));
+    }
+    const overwrite = cfg.overwrite === true;
+    return { ffmpegPath, ffprobePath, timeoutMs, graceMs, overwrite };
+}
+/**
+ * 解析时间参数：接受秒数（正数）或 HH:MM:SS[.mmm] 字符串。
+ * 返回秒（浮点）；非法返回 null。
+ */
+export function parseTimeArg(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+        return value;
+    if (typeof value === 'string') {
+        const text = value.trim();
+        if (text === '')
+            return null;
+        const clock = /^(\d{1,3}):([0-5]\d):([0-5]\d)(\.\d+)?$/.exec(text);
+        if (clock) {
+            return Number(clock[1]) * 3600 + Number(clock[2]) * 60 + Number(clock[3]) + (clock[4] ? Number(clock[4]) : 0);
+        }
+        const seconds = Number(text);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return seconds;
+    }
+    return null;
+}

package/lib/exec.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 进程执行层：把 DSH 官方 subprocess 服务包装成 Promise 式的 ProcessRunner。
+ * 全程 argv 数组、无 shell 解释——杜绝命令注入。
+ *
+ * @module dsh-ffmpeg/exec
+ */
+/** 一次运行的结果。 */
+export interface RunResult {
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}
+/** 可注入的进程执行器（生产用 subprocess 服务，测试用假实现）。 */
+export interface ProcessRunner {
+    run(argv: readonly string[], options?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+}
+/** 工具所需的 ctx.subprocess 最小面。 */
+export interface SubprocessHandleLike {
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    collected: {
+        stdout?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+        stderr?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+    };
+    terminate(): void;
+}
+export interface SubprocessSpawnLike {
+    (spec: {
+        argv: readonly string[];
+        cwd: string;
+        stdio: {
+            stdin: 'ignore';
+            stdout: {
+                maxBytes: number;
+            };
+            stderr: {
+                maxBytes: number;
+            };
+        };
+        graceMs: number;
+        signal?: AbortSignal;
+    }): SubprocessHandleLike;
+}
+/**
+ * 用 DSH subprocess 服务构造 ProcessRunner：collect 模式收流，AbortSignal 驱动超时，
+ * 超时自动触发 terminate 树级升级（SIGTERM → graceMs → SIGKILL / Windows 立即强杀）。
+ */
+export declare function createSubprocessRunner(spawn: SubprocessSpawnLike, graceMs: number, defaultTimeoutMs: number): ProcessRunner;

package/lib/exec.js

@@ -0,0 +1,41 @@
+/**
+ * 进程执行层：把 DSH 官方 subprocess 服务包装成 Promise 式的 ProcessRunner。
+ * 全程 argv 数组、无 shell 解释——杜绝命令注入。
+ *
+ * @module dsh-ffmpeg/exec
+ */
+const COLLECT_BYTES = 4 * 1024 * 1024;
+/**
+ * 用 DSH subprocess 服务构造 ProcessRunner：collect 模式收流，AbortSignal 驱动超时，
+ * 超时自动触发 terminate 树级升级（SIGTERM → graceMs → SIGKILL / Windows 立即强杀）。
+ */
+export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
+    return {
+        async run(argv, options) {
+            const timeoutMs = options?.timeoutMs ?? defaultTimeoutMs;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new Error('ffmpeg operation timed out')), timeoutMs);
+            let handle;
+            try {
+                handle = spawn({
+                    argv,
+                    cwd: process.cwd(),
+                    stdio: {
+                        stdin: 'ignore',
+                        stdout: { maxBytes: COLLECT_BYTES },
+                        stderr: { maxBytes: COLLECT_BYTES },
+                    },
+                    graceMs,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const outcome = await handle.done;
+            const stdout = handle.collected.stdout?.readFrom(0).text ?? '';
+            const stderr = handle.collected.stderr?.readFrom(0).text ?? '';
+            return { exitCode: outcome.exitCode, signal: outcome.signal, stdout, stderr };
+        },
+    };
+}

package/lib/ffprobe.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ffprobe JSON 输出解析：格式信息 + 视频/音频/字幕流归一化。
+ *
+ * @module dsh-ffmpeg/ffprobe
+ */
+/** 视频流信息。 */
+export interface VideoStreamInfo {
+    width: number;
+    height: number;
+    fps: number | null;
+    codec: string;
+    durationSeconds: number | null;
+    bitrate: number | null;
+}
+/** 音频流信息。 */
+export interface AudioStreamInfo {
+    codec: string;
+    sampleRate: number | null;
+    channels: number | null;
+    durationSeconds: number | null;
+}
+/** 字幕流信息。 */
+export interface SubtitleStreamInfo {
+    codec: string;
+    language: string | null;
+}
+/** 归一化后的媒体信息。 */
+export interface MediaInfo {
+    formatName: string;
+    durationSeconds: number | null;
+    sizeBytes: number | null;
+    bitrate: number | null;
+    video: VideoStreamInfo | null;
+    audio: AudioStreamInfo[];
+    subtitles: SubtitleStreamInfo[];
+}
+/**
+ * 解析 ffprobe -print_format json 输出。
+ * @param text - ffprobe 的 stdout。
+ * @throws 输出不是合法 JSON 时抛中文错误。
+ */
+export declare function parseProbeJson(text: string): MediaInfo;

package/lib/ffprobe.js

@@ -0,0 +1,95 @@
+/**
+ * ffprobe JSON 输出解析：格式信息 + 视频/音频/字幕流归一化。
+ *
+ * @module dsh-ffmpeg/ffprobe
+ */
+function num(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && value.trim().toLowerCase() !== 'n/a') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+function str(value) {
+    return typeof value === 'string' ? value : '';
+}
+/**
+ * 解析帧率字符串（如 30000/1001）为浮点；失败返回 null。
+ */
+function parseFps(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+        return value;
+    if (typeof value === 'string') {
+        const parts = value.split('/');
+        if (parts.length === 2) {
+            const top = Number(parts[0]);
+            const bottom = Number(parts[1]);
+            if (Number.isFinite(top) && Number.isFinite(bottom) && bottom !== 0)
+                return top / bottom;
+        }
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return null;
+}
+/**
+ * 解析 ffprobe -print_format json 输出。
+ * @param text - ffprobe 的 stdout。
+ * @throws 输出不是合法 JSON 时抛中文错误。
+ */
+export function parseProbeJson(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error('ffprobe 输出解析失败：' + (error instanceof Error ? error.message : String(error)));
+    }
+    const root = (typeof raw === 'object' && raw !== null ? raw : {});
+    const format = (typeof root.format === 'object' && root.format !== null ? root.format : {});
+    const streams = Array.isArray(root.streams) ? root.streams : [];
+    let video = null;
+    const audio = [];
+    const subtitles = [];
+    for (const stream of streams) {
+        const codecType = str(stream.codec_type);
+        if (codecType === 'video' && video === null) {
+            video = {
+                width: num(stream.width) ?? 0,
+                height: num(stream.height) ?? 0,
+                fps: parseFps(stream.avg_frame_rate) ?? parseFps(stream.r_frame_rate),
+                codec: str(stream.codec_name),
+                durationSeconds: num(stream.duration) ?? null,
+                bitrate: num(stream.bit_rate) ?? null,
+            };
+        }
+        else if (codecType === 'audio') {
+            audio.push({
+                codec: str(stream.codec_name),
+                sampleRate: num(stream.sample_rate) ?? null,
+                channels: num(stream.channels) ?? null,
+                durationSeconds: num(stream.duration) ?? null,
+            });
+        }
+        else if (codecType === 'subtitle') {
+            const tags = (typeof stream.tags === 'object' && stream.tags !== null ? stream.tags : {});
+            subtitles.push({
+                codec: str(stream.codec_name),
+                language: typeof tags.language === 'string' ? tags.language : null,
+            });
+        }
+    }
+    return {
+        formatName: str(format.format_name),
+        durationSeconds: num(format.duration) ?? null,
+        sizeBytes: num(format.size) ?? null,
+        bitrate: num(format.bit_rate) ?? null,
+        video,
+        audio,
+        subtitles,
+    };
+}