dsh-ffmpeg 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -6,6 +6,10 @@
 
 DSH (DeepSeek Harness) video-processing plugin: seven tools covering probing, cutting, concatenation, transcoding, subtitles, extraction and GIF creation — all powered by ffmpeg/ffprobe.
 
+## Compatibility
+
+Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+
 ## Installation
 
 ```bash
@@ -14,6 +18,15 @@ dsh plugin --profile web add dsh-ffmpeg
 
 ffmpeg must be installed locally (`ffmpeg -version` should work); use `ffmpegPath` / `ffprobePath`, or the `DSH_FFMPEG_PATH` / `DSH_FFPROBE_PATH` environment variables, when it is not on PATH.
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-ffmpeg
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 Override the plugin row in your profile's `cordis.patch.yml` (defaults apply when absent):
@@ -67,4 +80,4 @@ pnpm test       # build + 57 tests, including a real-ffmpeg end-to-end suite (au
 
 ## License
 
-MIT
+MIT

package/README.md

@@ -11,6 +11,10 @@
 
 DSH（DeepSeek Harness）视频处理工具插件：七个工具覆盖探测、剪辑、拼接、转码、字幕、提取与 GIF 制作，全部由 ffmpeg/ffprobe 完成。
 
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
 ## 安装
 
 ```bash
@@ -19,6 +23,15 @@ dsh plugin --profile web add dsh-ffmpeg
 
 需要本机已安装 ffmpeg（`ffmpeg -version` 能出结果即可）；不在 PATH 上时可用 `ffmpegPath`/`ffprobePath` 显式指定，或设置环境变量 `DSH_FFMPEG_PATH` / `DSH_FFPROBE_PATH`。
 
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-ffmpeg
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+
+
 ## 配置
 
 在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时全部用默认值）：
@@ -72,5 +85,4 @@ pnpm test       # 构建 + 57 个测试（含真实 ffmpeg 端到端集成，缺
 
 ## License
 
-MIT
-
+MIT

package/lib/args.d.ts

@@ -62,9 +62,17 @@ export interface ExtractSpec {
     duration?: number;
     fps?: number;
     streamIndex: number;
+    maxFrames?: number;
 }
 /** 提取：音频（拷贝）/ 抽帧序列 / 单帧 / 字幕流。 */
 export declare function extractArgs(ffmpeg: string, spec: ExtractSpec): string[];
+/** 定点抽帧：在指定时间点取一帧。 */
+export declare function frameAtArgs(ffmpeg: string, spec: {
+    input: string;
+    time: number;
+    output: string;
+    overwrite: boolean;
+}): string[];
 export interface GifSpec {
     input: string;
     output: string;

package/lib/args.js

@@ -91,9 +91,16 @@ export function extractArgs(ffmpeg, spec) {
         parts.push('-ss', fmtSeconds(spec.start));
     if (spec.duration !== undefined)
         parts.push('-t', fmtSeconds(spec.duration));
+    if (spec.maxFrames !== undefined)
+        parts.push('-frames:v', String(spec.maxFrames));
     parts.push('-vf', 'fps=' + (spec.fps ?? 1), spec.output);
     return parts;
 }
+/** 定点抽帧：在指定时间点取一帧。 */
+export function frameAtArgs(ffmpeg, spec) {
+    const flag = overwriteFlag(spec.overwrite);
+    return [ffmpeg, flag, '-ss', fmtSeconds(spec.time), '-i', spec.input, '-frames:v', '1', spec.output];
+}
 /** GIF 第一遍：调色板生成（palettegen）。 */
 export function gifPaletteArgs(ffmpeg, spec) {
     const filter = 'fps=' + spec.fps + ',scale=' + spec.width + ':-1:flags=lanczos,palettegen';

package/lib/index.d.ts

@@ -12,6 +12,7 @@ import { type FfmpegConfig } from './config.js';
 import { type SubprocessSpawnLike } from './exec.js';
 import { type FfmpegToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools，必须显式声明，否则宿主会抛 cannot get property without inject。 */
+export declare const name = "ffmpeg";
 export declare const inject: string[];
 /** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
 export interface FfmpegPluginContext {

package/lib/index.js

@@ -12,6 +12,7 @@ import { resolveConfig } from './config.js';
 import { createSubprocessRunner } from './exec.js';
 import { buildFfmpegTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools，必须显式声明，否则宿主会抛 cannot get property without inject。 */
+export const name = 'ffmpeg';
 export const inject = ['subprocess', 'tools'];
 /**
  * 插件入口：解析配置、封装 subprocess 执行器并注册七个视频工具。

package/lib/tools.d.ts

@@ -1,11 +1,12 @@
 /**
- * 七个面向模型的视频工具：probe / cut / concat / encode / subtitle / extract / gif。
+ * 八个面向模型的视频工具：probe / cut / concat / encode / subtitle / extract / gif / frames。
  * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
  *
  * @module dsh-ffmpeg/tools
  */
 import { type ResolvedFfmpegConfig } from './config.js';
 import { type ProcessRunner } from './exec.js';
+import { type MediaInfo } from './ffprobe.js';
 /** 模型可见的内容块。 */
 export interface ContentBlock {
     type: 'text';
@@ -27,6 +28,8 @@ export interface FfmpegToolDefinition {
     execute(args: unknown, exec: unknown): Promise<unknown>;
     timeoutMs?: number;
 }
+/** 生成一行人类可读的媒体摘要：容器、时长、主视频、帧率、码率、体积。 */
+export declare function buildProbeSummary(media: MediaInfo): string;
 /**
  * 构建七个工具定义。
  * @param config - 已解析配置。

package/lib/tools.js

@@ -1,14 +1,14 @@
 /**
- * 七个面向模型的视频工具：probe / cut / concat / encode / subtitle / extract / gif。
+ * 八个面向模型的视频工具：probe / cut / concat / encode / subtitle / extract / gif / frames。
  * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
  *
  * @module dsh-ffmpeg/tools
  */
-import { rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
-import { concatArgs, concatListContent, cutArgs, ENCODE_PRESETS, encodeArgs, extractArgs, fmtSeconds, gifPaletteArgs, gifUseArgs, probeArgs, subtitleArgs, } from './args.js';
+import { concatArgs, concatListContent, cutArgs, ENCODE_PRESETS, encodeArgs, extractArgs, fmtSeconds, frameAtArgs, gifPaletteArgs, gifUseArgs, probeArgs, subtitleArgs, } from './args.js';
 import { parseProbeJson } from './ffprobe.js';
 import { assertInputFile, resolveOutputPath, sanitizeName } from './paths.js';
 import { parseTimeArg } from './config.js';
@@ -98,6 +98,7 @@ const probeSchema = {
     properties: {
         ok: { type: 'boolean' },
         input: { type: 'string' },
+        summary: { type: 'string' },
         formatName: { type: 'string' },
         durationSeconds: { type: 'number' },
         sizeBytes: { type: 'number' },
@@ -114,6 +115,36 @@ const produceSchema = {
     properties: { output: { type: 'string' } },
     additionalProperties: true,
 };
+// ---------- probe 摘要 ----------
+/** 码率人类可读。 */
+function formatBitrate(bps) {
+    if (bps === null)
+        return '码率未知';
+    if (bps >= 1000000)
+        return (bps / 1000000).toFixed(2) + ' Mbps';
+    return Math.round(bps / 1000) + ' kbps';
+}
+/** 生成一行人类可读的媒体摘要：容器、时长、主视频、帧率、码率、体积。 */
+export function buildProbeSummary(media) {
+    const parts = [];
+    if (media.formatName !== '')
+        parts.push(media.formatName);
+    if (media.durationSeconds !== null)
+        parts.push(fmtSeconds(media.durationSeconds));
+    if (media.video !== null) {
+        const v = media.video;
+        parts.push((v.codec !== '' ? v.codec + ' ' : '') + v.width + 'x' + v.height);
+        if (v.fps !== null)
+            parts.push(Math.round(v.fps * 100) / 100 + ' fps');
+    }
+    parts.push(formatBitrate(media.bitrate));
+    if (media.sizeBytes !== null) {
+        const mb = media.sizeBytes / 1024 / 1024;
+        parts.push(mb >= 1 ? mb.toFixed(1) + ' MB' : Math.round(media.sizeBytes / 1024) + ' KB');
+    }
+    parts.push('音频流 ' + media.audio.length + ' / 字幕流 ' + media.subtitles.length);
+    return parts.join('，');
+}
 // ---------- 工具构建 ----------
 /**
  * 构建七个工具定义。
@@ -136,6 +167,8 @@ export function buildFfmpegTools(config, runner) {
                 const videos = Array.isArray(rec.videos) ? rec.videos : [];
                 const video = videos.length > 0 ? asRecord(videos[0]) : asRecord(rec.video);
                 const lines = ['媒体信息（' + rec.input + '）：'];
+                if (typeof rec.summary === 'string' && rec.summary !== '')
+                    lines.push('- 摘要：' + rec.summary);
                 lines.push('- 容器：' + rec.formatName + '，时长：' + (rec.durationSeconds ?? '未知') + ' 秒，大小：' + (rec.sizeBytes ?? '未知') + ' 字节');
                 if (videos.length > 0) {
                     lines.push('- 视频流 ' + videos.length + ' 个；主视频：' + video.codec + ' ' + video.width + 'x' + video.height + '，帧率：' + (video.fps ?? '未知'));
@@ -149,7 +182,7 @@ export function buildFfmpegTools(config, runner) {
             const input = assertInputFile(requiredString(args, 'input', '输入文件'));
             const result = await runChecked(runner, probeArgs(cfg.ffprobePath, input), Math.min(timeout, 60000), 'ffprobe');
             const media = parseProbeJson(result.stdout);
-            return { ok: true, input, ...media };
+            return { ok: true, input, summary: buildProbeSummary(media), ...media };
         },
         timeoutMs: Math.min(timeout, 60000),
     };
@@ -418,5 +451,102 @@ export function buildFfmpegTools(config, runner) {
         },
         timeoutMs: timeout,
     };
-    return [probe, cut, concat, encode, subtitle, extract, gif];
+    const frames = {
+        name: 'ffmpeg_frames',
+        description: '从视频批量抽帧为图片（PNG/JPG）。两种模式：every（固定秒间隔抽帧，如 every=2 表示每 2 秒一帧，默认 1）或 times（指定时间点列表，如 ["00:00:05","00:01:30"]，最多 20 个）。maxFrames 限制 every 模式的帧数上限（1-500，默认 100）。返回输出目录、文件清单与数量，便于后续视觉模型读图。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '输入视频（必填）。' },
+            every: { type: 'number', description: '抽帧间隔秒数（与 times 二选一，默认 1）。' },
+            times: { type: 'array', items: { type: 'string' }, description: '时间点列表（与 every 二选一，最多 20 个，秒数或 HH:MM:SS.mmm）。' },
+            maxFrames: { type: 'integer', description: 'every 模式帧数上限 1-500（默认 100）。' },
+            outputDir: { type: 'string', description: '输出目录（可选，默认输入同目录 <文件名>-frames）。' },
+            format: { type: 'string', description: '图片格式：png（默认）或 jpg。' },
+        }),
+        output: {
+            schema: baseSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['抽帧完成：共 ' + rec.count + ' 张，输出目录 ' + rec.outputDir + (rec.mode === 'times' ? '（指定时间点）' : '（每 ' + rec.every + ' 秒一帧）')];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const input = assertInputFile(requiredString(args, 'input', '输入文件'));
+            const formatRaw = optionalString(args, 'format')?.toLowerCase() ?? 'png';
+            if (formatRaw !== 'png' && formatRaw !== 'jpg' && formatRaw !== 'jpeg')
+                throw new Error('format 只支持 png 或 jpg。');
+            const ext = formatRaw === 'png' ? '.png' : '.jpg';
+            const times = stringArray(args, 'times');
+            const outDir = optionalString(args, 'outputDir') ?? join(dirname(input), sanitizeName(basename(input, extname(input))) + '-frames');
+            mkdirSync(outDir, { recursive: true });
+            if (times.length > 0) {
+                if (times.length > 20)
+                    throw new Error('times 最多 20 个时间点（当前 ' + times.length + ' 个）。');
+                let i = 0;
+                for (const raw of times) {
+                    const at = parseTimeArg(raw);
+                    if (at === null)
+                        throw new Error('times 里第 ' + (i + 1) + ' 个时间点非法：' + raw + '（请用秒数或 HH:MM:SS.mmm）。');
+                    const target = join(outDir, 'frame-' + String(i + 1).padStart(3, '0') + ext);
+                    await runChecked(runner, frameAtArgs(cfg.ffmpegPath, { input, time: at, output: target, overwrite: cfg.overwrite }), timeout, 'ffmpeg 定点抽帧');
+                    i++;
+                }
+            }
+            else {
+                const every = optionalNumber(args, 'every') ?? 1;
+                if (every <= 0)
+                    throw new Error('every 必须大于 0。');
+                const maxFramesRaw = args.maxFrames;
+                const maxFrames = typeof maxFramesRaw === 'number' && Number.isInteger(maxFramesRaw) ? Math.min(500, Math.max(1, maxFramesRaw)) : 100;
+                const pattern = join(outDir, 'frame-%03d' + ext);
+                await runChecked(runner, extractArgs(cfg.ffmpegPath, { input, what: 'frames', output: pattern, overwrite: cfg.overwrite, fps: 1 / every, streamIndex: 0, maxFrames }), timeout, 'ffmpeg 抽帧');
+            }
+            const files = readdirSync(outDir).filter((f) => f.startsWith('frame-') && f.endsWith(ext)).sort();
+            const every = optionalNumber(args, 'every') ?? 1;
+            return { outputDir: outDir, mode: times.length > 0 ? 'times' : 'every', every: times.length > 0 ? null : every, count: files.length, files: files.slice(0, 200) };
+        },
+        timeoutMs: timeout,
+    };
+    const health = {
+        name: 'ffmpeg_health',
+        description: 'dsh-ffmpeg 自检：验证 ffmpeg / ffprobe 可执行文件是否可用（执行 -version）。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: baseSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                const checks = Array.isArray(rec.checks) ? rec.checks : [];
+                const lines = ['dsh-ffmpeg 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const item of checks) {
+                    const c = asRecord(item);
+                    lines.push('- ' + c.name + '：' + (c.ok === true ? '✅ ' + String(c.version ?? '') : '❌ ' + String(c.detail ?? '')));
+                }
+                return lines;
+            }),
+        },
+        async execute() {
+            const checks = [];
+            let ok = true;
+            for (const [label, bin] of [['ffmpeg', cfg.ffmpegPath], ['ffprobe', cfg.ffprobePath]]) {
+                try {
+                    const result = await runner.run([bin, '-version'], { timeoutMs: 15000 });
+                    const firstLine = result.stdout.split(/\r?\n/)[0]?.trim() ?? '';
+                    if (result.exitCode === 0) {
+                        checks.push({ name: label, ok: true, path: bin, version: firstLine });
+                    }
+                    else {
+                        ok = false;
+                        checks.push({ name: label, ok: false, path: bin, detail: '退出码 ' + String(result.exitCode) + '：' + firstLine });
+                    }
+                }
+                catch (error) {
+                    ok = false;
+                    checks.push({ name: label, ok: false, path: bin, detail: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return { ok, plugin: 'dsh-ffmpeg', checks };
+        },
+        timeoutMs: 30000,
+    };
+    return [probe, cut, concat, encode, subtitle, extract, gif, frames, health];
 }

package/package.json

@@ -1,61 +1,60 @@
-{
-  "name": "dsh-ffmpeg",
-  "version": "0.2.0",
-  "description": "DSH 视频处理工具插件：ffmpeg_probe/cut/concat/encode/subtitle/extract/gif 七工具，进程走官方 subprocess 服务，超时树级终止、环境变量路径回退与多视频流探测，零运行时依赖（ffmpeg 本体除外）。",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md",
-    "README.en.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepare": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
-    "prepublishOnly": "pnpm run build"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "ffmpeg",
-    "video",
-    "media",
-    "dsh-plugin"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.6.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/STARDUSTLC666/dsh-ffmpeg.git"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-ffmpeg/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-ffmpeg#readme",
-  "author": "stardustlc",
-  "packageManager": "pnpm@11.7.0"
-}
+{
+  "name": "dsh-ffmpeg",
+  "version": "0.3.0",
+  "description": "DSH 视频处理工具插件：ffmpeg_probe/cut/concat/encode/subtitle/extract/gif 七工具，进程走官方 subprocess 服务，超时树级终止、环境变量路径回退与多视频流探测，零运行时依赖（ffmpeg 本体除外）。",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "ffmpeg",
+    "video",
+    "media",
+    "dsh-plugin"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-ffmpeg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-ffmpeg/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-ffmpeg#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}