dsh-ffmpeg 0.1.1 → 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,13 +6,26 @@
 
 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
 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.
+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
 
@@ -22,8 +35,8 @@ Override the plugin row in your profile's `cordis.patch.yml` (defaults apply whe
 - 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
+    # ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe   # explicit path (or DSH_FFMPEG_PATH)
+    # ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe # or DSH_FFPROBE_PATH
     timeoutMs: 300000                                # per-operation timeout (default 5 min, 10s - 2h)
     # overwrite: true                                 # allow overwriting outputs (default auto-suffix _1/_2)
 ```
@@ -32,7 +45,7 @@ Override the plugin row in your profile's `cordis.patch.yml` (defaults apply whe
 
 | Tool | Purpose | Key parameters |
 | :-- | :-- | :-- |
-| `ffmpeg_probe` | Probe media info (format/duration/resolution/fps/bitrate/audio/subtitle streams) | `input` required |
+| `ffmpeg_probe` | Probe media info (format/duration/resolution/fps/bitrate/audio/subtitle streams; multi-video files return a full videos list) | `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 |
@@ -53,18 +66,18 @@ 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
+- **Runs on the official DSH subprocess service**: the timeout AbortSignal now really drives tree-scoped termination (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
+- **Input validation**: time formats, preset enums, crf/fps/scale ranges are validated up front; directory inputs are rejected and extension-less frame-sequence outputs are auto-fixed
 
 ## Development
 
 ```bash
 pnpm install
-pnpm test       # build + 50 tests, including a real-ffmpeg end-to-end suite (auto-skipped without ffmpeg)
+pnpm test       # build + 57 tests, including a real-ffmpeg end-to-end suite (auto-skipped without ffmpeg)
 ```
 
 ## License
 
-MIT
+MIT

package/README.md

@@ -11,13 +11,26 @@
 
 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
 dsh plugin --profile web add dsh-ffmpeg
 ```
 
-需要本机已安装 ffmpeg（`ffmpeg -version` 能出结果即可）；不在 PATH 上时用 `ffmpegPath`/`ffprobePath` 显式指定。
+需要本机已安装 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` 中覆盖的插件行。
+
 
 ## 配置
 
@@ -27,8 +40,8 @@ dsh plugin --profile web add dsh-ffmpeg
 - id: ffmpeg
   name: 'dsh-ffmpeg'
   config:
-    # ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe   # 非 PATH 时显式指定
-    # ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe
+    # ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe   # 非 PATH 时显式指定（也可用 DSH_FFMPEG_PATH）
+    # ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe # 也可用 DSH_FFPROBE_PATH
     timeoutMs: 300000                                # 单次操作超时（默认 5 分钟，10 秒 - 2 小时）
     # overwrite: true                                 # 允许覆盖同名输出（默认自动加 _1/_2 序号）
 ```
@@ -37,7 +50,7 @@ dsh plugin --profile web add dsh-ffmpeg
 
 | 工具 | 作用 | 关键参数 |
 | :-- | :-- | :-- |
-| `ffmpeg_probe` | 探测媒体信息（格式/时长/分辨率/帧率/码率/音轨/字幕轨） | `input` 必填 |
+| `ffmpeg_probe` | 探测媒体信息（格式/时长/分辨率/帧率/码率/音轨/字幕轨；多视频流时返回完整 videos 列表） | `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` 可选 |
@@ -58,19 +71,18 @@ ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }
 ## 安全设计
 
 - **无 shell**：所有参数以独立 argv 数组传递，用户输入不可能注入命令
-- **进程走 DSH 官方 subprocess 服务**：树级终止（超时自动 SIGTERM → 强杀，Windows taskkill /T），本插件零运行时依赖
+- **进程走 DSH 官方 subprocess 服务**：超时 AbortSignal 会真正触发树级终止（SIGTERM → 强杀，Windows taskkill /T），本插件零运行时依赖
 - **防覆写**：默认不覆盖同名文件（自动加序号），输出与输入相同直接拒绝
 - **超时钳制**：单次操作 10 秒 - 2 小时；探测额外限制 60 秒
-- **参数校验**：时间格式、预设枚举、crf/fps/scale 范围全部前置校验，错误带中文指引
+- **参数校验**：时间格式、预设枚举、crf/fps/scale 范围全部前置校验，输入目录、抽帧无扩展名输出等边界也有中文错误/自动修复
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 50 个测试（含真实 ffmpeg 端到端集成，缺 ffmpeg 自动跳过）
+pnpm test       # 构建 + 57 个测试（含真实 ffmpeg 端到端集成，缺 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/config.d.ts

@@ -25,7 +25,7 @@ export interface ResolvedFfmpegConfig {
  * @param config - 插件行配置（可能为 undefined/null）。
  * @throws 配置值非法时抛出中文错误。
  */
-export declare function resolveConfig(config: FfmpegConfig | undefined | null): ResolvedFfmpegConfig;
+export declare function resolveConfig(config: FfmpegConfig | undefined | null, env?: NodeJS.ProcessEnv): ResolvedFfmpegConfig;
 /**
  * 解析时间参数：接受秒数（正数）或 HH:MM:SS[.mmm] 字符串。
  * 返回秒（浮点）；非法返回 null。

package/lib/config.js

@@ -11,10 +11,10 @@ const DEFAULT_GRACE_MS = 15000;
  * @param config - 插件行配置（可能为 undefined/null）。
  * @throws 配置值非法时抛出中文错误。
  */
-export function resolveConfig(config) {
+export function resolveConfig(config, env = process.env) {
     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';
+    const ffmpegPath = typeof cfg.ffmpegPath === 'string' && cfg.ffmpegPath.trim() !== '' ? cfg.ffmpegPath.trim() : (env.DSH_FFMPEG_PATH?.trim() || 'ffmpeg');
+    const ffprobePath = typeof cfg.ffprobePath === 'string' && cfg.ffprobePath.trim() !== '' ? cfg.ffprobePath.trim() : (env.DSH_FFPROBE_PATH?.trim() || 'ffprobe');
     let timeoutMs = DEFAULT_TIMEOUT_MS;
     if (cfg.timeoutMs !== undefined) {
         if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0) {

package/lib/exec.js

@@ -28,14 +28,14 @@ export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
                     graceMs,
                     signal: controller.signal,
                 });
+                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 };
             }
             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

@@ -30,7 +30,10 @@ export interface MediaInfo {
     durationSeconds: number | null;
     sizeBytes: number | null;
     bitrate: number | null;
+    /** 第一个视频流（保持旧字段兼容）。 */
     video: VideoStreamInfo | null;
+    /** 全部视频流（多机位/多角度视频可完整枚举）。 */
+    videos: VideoStreamInfo[];
     audio: AudioStreamInfo[];
     subtitles: SubtitleStreamInfo[];
 }

package/lib/ffprobe.js

@@ -52,20 +52,20 @@ export function parseProbeJson(text) {
     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 videos = [];
     const audio = [];
     const subtitles = [];
     for (const stream of streams) {
         const codecType = str(stream.codec_type);
-        if (codecType === 'video' && video === null) {
-            video = {
+        if (codecType === 'video') {
+            videos.push({
                 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({
@@ -88,7 +88,8 @@ export function parseProbeJson(text) {
         durationSeconds: num(format.duration) ?? null,
         sizeBytes: num(format.size) ?? null,
         bitrate: num(format.bit_rate) ?? null,
-        video,
+        video: videos[0] ?? null,
+        videos,
         audio,
         subtitles,
     };

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/paths.js

@@ -3,7 +3,7 @@
  *
  * @module dsh-ffmpeg/paths
  */
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 /** 校验输入文件存在且是文件；返回绝对路径。 */
 export function assertInputFile(input) {
@@ -11,6 +11,9 @@ export function assertInputFile(input) {
     if (!existsSync(absolute)) {
         throw new Error('输入文件不存在：' + input);
     }
+    if (!statSync(absolute).isFile()) {
+        throw new Error('输入路径不是文件：' + input);
+    }
     return absolute;
 }
 /** 清洗文件名中的危险字符。 */

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,11 +98,13 @@ const probeSchema = {
     properties: {
         ok: { type: 'boolean' },
         input: { type: 'string' },
+        summary: { type: 'string' },
         formatName: { type: 'string' },
         durationSeconds: { type: 'number' },
         sizeBytes: { type: 'number' },
         bitrate: { type: 'number' },
         video: videoStreamSchema,
+        videos: { type: 'array', items: videoStreamSchema },
         audio: { type: 'array', items: audioStreamSchema },
         subtitles: { type: 'array', items: subtitleStreamSchema },
     },
@@ -113,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('，');
+}
 // ---------- 工具构建 ----------
 /**
  * 构建七个工具定义。
@@ -132,11 +164,15 @@ export function buildFfmpegTools(config, runner) {
             schema: probeSchema,
             render: buildTextRenderer((_args, value) => {
                 const rec = asRecord(value);
-                const video = asRecord(rec.video);
+                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 (rec.video !== null && rec.video !== undefined)
-                    lines.push('- 视频：' + video.codec + ' ' + video.width + 'x' + video.height + '，帧率：' + (video.fps ?? '未知'));
+                if (videos.length > 0) {
+                    lines.push('- 视频流 ' + videos.length + ' 个；主视频：' + video.codec + ' ' + video.width + 'x' + video.height + '，帧率：' + (video.fps ?? '未知'));
+                }
                 lines.push('- 音频流：' + (Array.isArray(rec.audio) ? rec.audio.length : 0) + ' 个，字幕流：' + (Array.isArray(rec.subtitles) ? rec.subtitles.length : 0) + ' 个');
                 return lines;
             }),
@@ -146,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),
     };
@@ -355,7 +391,13 @@ export function buildFfmpegTools(config, runner) {
             else {
                 const explicit = optionalString(args, 'output');
                 if (explicit !== undefined) {
-                    output = explicit.includes('%') ? explicit : explicit.replace(/(\.[^.]+)$/, '-%03d$1');
+                    if (explicit.includes('%')) {
+                        output = explicit;
+                    }
+                    else {
+                        const explicitExt = extname(explicit);
+                        output = explicitExt === '' ? explicit + '-%03d.png' : explicit.slice(0, -explicitExt.length) + '-%03d' + explicitExt;
+                    }
                 }
                 else {
                     output = join(dirname(input), sanitizeName(basename(input, extname(input))) + '-%03d.png');
@@ -409,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.1.1",
-  "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"
+}