dsh-ffmpeg 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * dsh-ffmpeg —— 视频处理工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：把七个面向模型的工具（ffmpeg_probe / ffmpeg_cut /
+ * ffmpeg_concat / ffmpeg_encode / ffmpeg_subtitle / ffmpeg_extract / ffmpeg_gif）注册进
+ * 宿主进程的工具注册表。进程执行走 DSH 官方 subprocess 服务（argv 数组、无 shell），
+ * 零运行时依赖。配置缺失时插件照常加载，工具在 execute 时才抛出带中文指引的错误。
+ *
+ * @module dsh-ffmpeg
+ */
+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 inject: string[];
+/** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
+export interface FfmpegPluginContext {
+    subprocess: {
+        spawn: SubprocessSpawnLike;
+    };
+    tools: {
+        register(definition: FfmpegToolDefinition): () => void;
+    };
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：解析配置、封装 subprocess 执行器并注册七个视频工具。
+ * @param ctx - 宿主上下文（至少含 subprocess.spawn 与 tools.register）。
+ * @param config - 插件配置（可缺省）。
+ */
+export declare function apply(ctx: FfmpegPluginContext, config?: FfmpegConfig | null): void;
+export * from './args.js';
+export * from './config.js';
+export * from './exec.js';
+export * from './ffprobe.js';
+export * from './paths.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,47 @@
+/**
+ * dsh-ffmpeg —— 视频处理工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：把七个面向模型的工具（ffmpeg_probe / ffmpeg_cut /
+ * ffmpeg_concat / ffmpeg_encode / ffmpeg_subtitle / ffmpeg_extract / ffmpeg_gif）注册进
+ * 宿主进程的工具注册表。进程执行走 DSH 官方 subprocess 服务（argv 数组、无 shell），
+ * 零运行时依赖。配置缺失时插件照常加载，工具在 execute 时才抛出带中文指引的错误。
+ *
+ * @module dsh-ffmpeg
+ */
+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 inject = ['subprocess', 'tools'];
+/**
+ * 插件入口：解析配置、封装 subprocess 执行器并注册七个视频工具。
+ * @param ctx - 宿主上下文（至少含 subprocess.spawn 与 tools.register）。
+ * @param config - 插件配置（可缺省）。
+ */
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-ffmpeg] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const runner = createSubprocessRunner(ctx.subprocess.spawn, cfg.graceMs, cfg.timeoutMs);
+    const disposers = [];
+    for (const definition of buildFfmpegTools(cfg, runner)) {
+        disposers.push(ctx.tools.register(definition));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}
+export * from './args.js';
+export * from './config.js';
+export * from './exec.js';
+export * from './ffprobe.js';
+export * from './paths.js';
+export * from './tools.js';

package/lib/paths.d.ts

@@ -0,0 +1,9 @@
+/** 校验输入文件存在且是文件；返回绝对路径。 */
+export declare function assertInputFile(input: string): string;
+/** 清洗文件名中的危险字符。 */
+export declare function sanitizeName(name: string): string;
+/**
+ * 决定输出路径：缺省时放在输入同目录，名字 = 输入名 + suffix + ext。
+ * 目标已存在且不允许覆写时自动追加 _1/_2…。
+ */
+export declare function resolveOutputPath(input: string, explicit: string | undefined, suffix: string, ext: string, overwrite: boolean): string;

package/lib/paths.js

@@ -0,0 +1,48 @@
+/**
+ * 路径与文件校验：输入存在性、输出命名（防覆写）、文件名清洗。
+ *
+ * @module dsh-ffmpeg/paths
+ */
+import { existsSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+/** 校验输入文件存在且是文件；返回绝对路径。 */
+export function assertInputFile(input) {
+    const absolute = resolve(input);
+    if (!existsSync(absolute)) {
+        throw new Error('输入文件不存在：' + input);
+    }
+    return absolute;
+}
+/** 清洗文件名中的危险字符。 */
+export function sanitizeName(name) {
+    const cleaned = name.trim().replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').replace(/\s+/g, '_').slice(0, 120);
+    return cleaned === '' ? 'output' : cleaned;
+}
+/**
+ * 决定输出路径：缺省时放在输入同目录，名字 = 输入名 + suffix + ext。
+ * 目标已存在且不允许覆写时自动追加 _1/_2…。
+ */
+export function resolveOutputPath(input, explicit, suffix, ext, overwrite) {
+    let target;
+    if (explicit !== undefined && explicit.trim() !== '') {
+        target = resolve(explicit.trim());
+    }
+    else {
+        const base = basename(input, extname(input));
+        target = join(dirname(input), sanitizeName(base) + suffix + ext);
+    }
+    if (target.toLowerCase() === resolve(input).toLowerCase()) {
+        throw new Error('输出路径与输入文件相同，已拒绝（避免覆盖源文件）。');
+    }
+    if (overwrite || !existsSync(target))
+        return target;
+    const directory = dirname(target);
+    const base = basename(target, extname(target));
+    const extension = extname(target);
+    for (let index = 1; index < 1000; index++) {
+        const candidate = join(directory, base + '_' + index + extension);
+        if (!existsSync(candidate))
+            return candidate;
+    }
+    throw new Error('找不到可用的输出文件名（同名文件超过 999 个），请显式指定 output。');
+}

package/lib/tools.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 七个面向模型的视频工具：probe / cut / concat / encode / subtitle / extract / gif。
+ * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
+ *
+ * @module dsh-ffmpeg/tools
+ */
+import { type ResolvedFfmpegConfig } from './config.js';
+import { type ProcessRunner } from './exec.js';
+/** 模型可见的内容块。 */
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+/** 注册给 ctx.tools.register 的原始工具定义。 */
+export interface FfmpegToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    timeoutMs?: number;
+}
+/**
+ * 构建七个工具定义。
+ * @param config - 已解析配置。
+ * @param runner - 进程执行器（生产为 subprocess 服务封装，测试可注入假实现）。
+ */
+export declare function buildFfmpegTools(config: ResolvedFfmpegConfig, runner: ProcessRunner): FfmpegToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,412 @@
+/**
+ * 七个面向模型的视频工具：probe / cut / concat / encode / subtitle / extract / gif。
+ * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
+ *
+ * @module dsh-ffmpeg/tools
+ */
+import { rmSync, writeFileSync } from 'node:fs';
+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 { parseProbeJson } from './ffprobe.js';
+import { assertInputFile, resolveOutputPath, sanitizeName } from './paths.js';
+import { parseTimeArg } from './config.js';
+/** 编译作者 DSL 为原始 JSON Schema（正是 defineTool 存为 definition.parameters 的值）。 */
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        if (prop?.type === 'array' && prop.items !== null && typeof prop.items === 'object') {
+            node.items = { type: 'string' };
+        }
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    return value;
+}
+function optionalNumber(args, key) {
+    const value = args[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function requiredTime(args, key, label) {
+    const value = parseTimeArg(args[key]);
+    if (value === null)
+        throw new Error(label + '（参数 ' + key + '）非法：请用秒数或 HH:MM:SS[.mmm] 格式。');
+    return value;
+}
+function optionalTime(args, key) {
+    const value = parseTimeArg(args[key]);
+    return value === null ? undefined : value;
+}
+function stringArray(args, key) {
+    const value = args[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string' && item.trim() !== '').map((item) => item.trim());
+}
+/** 执行并检查退出码；非零抛中文错误（附 stderr 尾部）。 */
+async function runChecked(runner, argv, timeoutMs, label) {
+    const result = await runner.run(argv, { timeoutMs });
+    if (result.exitCode !== 0) {
+        const tail = result.stderr.trim().split(/\r?\n/).slice(-6).join(' | ');
+        throw new Error(label + '失败（退出码 ' + String(result.exitCode ?? 'null') + (result.signal ? '，信号 ' + result.signal : '') + '）：' + (tail || '无错误输出'));
+    }
+    return result;
+}
+function buildTextRenderer(lines) {
+    return (args, value) => [{ type: 'text', text: lines(args, value).join('\n') }];
+}
+// ---------- 输出 JSON Schema ----------
+const baseSchema = { type: 'object', additionalProperties: true };
+const videoStreamSchema = {
+    type: 'object',
+    properties: { width: { type: 'number' }, height: { type: 'number' }, fps: { type: 'number' }, codec: { type: 'string' }, durationSeconds: { type: 'number' }, bitrate: { type: 'number' } },
+    additionalProperties: true,
+};
+const audioStreamSchema = {
+    type: 'object',
+    properties: { codec: { type: 'string' }, sampleRate: { type: 'number' }, channels: { type: 'number' }, durationSeconds: { type: 'number' } },
+    additionalProperties: true,
+};
+const subtitleStreamSchema = {
+    type: 'object',
+    properties: { codec: { type: 'string' }, language: { type: 'string' } },
+    additionalProperties: true,
+};
+const probeSchema = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        input: { type: 'string' },
+        formatName: { type: 'string' },
+        durationSeconds: { type: 'number' },
+        sizeBytes: { type: 'number' },
+        bitrate: { type: 'number' },
+        video: videoStreamSchema,
+        audio: { type: 'array', items: audioStreamSchema },
+        subtitles: { type: 'array', items: subtitleStreamSchema },
+    },
+    additionalProperties: true,
+};
+const produceSchema = {
+    type: 'object',
+    properties: { output: { type: 'string' } },
+    additionalProperties: true,
+};
+// ---------- 工具构建 ----------
+/**
+ * 构建七个工具定义。
+ * @param config - 已解析配置。
+ * @param runner - 进程执行器（生产为 subprocess 服务封装，测试可注入假实现）。
+ */
+export function buildFfmpegTools(config, runner) {
+    const cfg = config;
+    const timeout = cfg.timeoutMs;
+    const probe = {
+        name: 'ffmpeg_probe',
+        description: '探测媒体文件信息：容器格式、时长、体积、码率，以及视频流（分辨率/帧率/编码）、音频流、字幕流。所有后续处理前建议先 probe。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '媒体文件路径（必填）。' },
+        }),
+        output: {
+            schema: probeSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                const video = asRecord(rec.video);
+                const lines = ['媒体信息（' + rec.input + '）：'];
+                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 ?? '未知'));
+                lines.push('- 音频流：' + (Array.isArray(rec.audio) ? rec.audio.length : 0) + ' 个，字幕流：' + (Array.isArray(rec.subtitles) ? rec.subtitles.length : 0) + ' 个');
+                return lines;
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            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 };
+        },
+        timeoutMs: Math.min(timeout, 60000),
+    };
+    const cut = {
+        name: 'ffmpeg_cut',
+        description: '剪辑视频片段。默认流拷贝（极快、关键帧对齐）；reencode=true 时精确到帧重编码（慢）。start 为起始时间（秒或 HH:MM:SS.mmm，默认 0）；end 与 duration 至少给一个（end 优先）。输出默认放在输入同目录，同名自动加序号。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '输入文件（必填）。' },
+            start: { type: 'string', description: '起始时间（秒或 HH:MM:SS.mmm，默认 0）。' },
+            end: { type: 'string', description: '结束时间；与 duration 至少给一个。' },
+            duration: { type: 'string', description: '片段时长；与 end 至少给一个。' },
+            output: { type: 'string', description: '输出路径（可选，默认输入同目录加 .cut 后缀）。' },
+            reencode: { type: 'boolean', description: '是否精确重编码（默认 false=流拷贝）。' },
+        }),
+        output: {
+            schema: produceSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['剪辑完成：' + rec.output + '（' + fmtSeconds(Number(rec.duration ?? 0)) + ' 秒' + (rec.reencode === true ? '，已重编码' : '，流拷贝') + '）'];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const input = assertInputFile(requiredString(args, 'input', '输入文件'));
+            const start = optionalTime(args, 'start') ?? 0;
+            const end = optionalTime(args, 'end');
+            let duration;
+            if (end !== undefined) {
+                duration = end - start;
+                if (duration <= 0)
+                    throw new Error('end 必须晚于 start。');
+            }
+            else {
+                duration = requiredTime(args, 'duration', '片段时长');
+                if (duration <= 0)
+                    throw new Error('duration 必须大于 0。');
+            }
+            const reencode = args.reencode === true;
+            const output = resolveOutputPath(input, optionalString(args, 'output'), '.cut', extname(input) || '.mp4', cfg.overwrite);
+            await runChecked(runner, cutArgs(cfg.ffmpegPath, { input, start, duration, output, overwrite: cfg.overwrite, reencode }), timeout, 'ffmpeg 剪辑');
+            return { output, start, duration, reencode };
+        },
+        timeoutMs: timeout,
+    };
+    const concat = {
+        name: 'ffmpeg_concat',
+        description: '拼接多个视频片段。默认要求编码一致（流拷贝，秒级完成）；reencode=true 时任意格式统一重编码拼接（慢）。inputs 为 2-20 个文件路径。',
+        parameters: compileParameters({
+            inputs: { type: 'array', items: { type: 'string' }, required: true, description: '输入文件路径数组（2-20 个，必填）。' },
+            output: { type: 'string', description: '输出路径（可选，默认第一个输入同目录加 .concat 后缀）。' },
+            reencode: { type: 'boolean', description: '是否统一重编码拼接（默认 false=流拷贝）。' },
+        }),
+        output: {
+            schema: produceSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['拼接完成：' + rec.output + '（' + rec.count + ' 个片段' + (rec.reencode === true ? '，已重编码' : '，流拷贝') + '）'];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const inputs = stringArray(args, 'inputs');
+            if (inputs.length < 2)
+                throw new Error('inputs 至少需要 2 个文件（当前 ' + inputs.length + ' 个）。');
+            if (inputs.length > 20)
+                throw new Error('inputs 最多 20 个文件（当前 ' + inputs.length + ' 个）。');
+            const absolute = inputs.map(assertInputFile);
+            const reencode = args.reencode === true;
+            const firstExt = extname(absolute[0]) || '.mp4';
+            const output = resolveOutputPath(absolute[0], optionalString(args, 'output'), '.concat', firstExt, cfg.overwrite);
+            if (!reencode) {
+                const listPath = join(tmpdir(), 'dsh-ffmpeg-concat-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8) + '.txt');
+                writeFileSync(listPath, concatListContent(absolute), 'utf8');
+                try {
+                    await runChecked(runner, concatArgs(cfg.ffmpegPath, { inputs: absolute, listFilePath: listPath, output, overwrite: cfg.overwrite, reencode: false }), timeout, 'ffmpeg 拼接');
+                }
+                finally {
+                    rmSync(listPath, { force: true });
+                }
+            }
+            else {
+                await runChecked(runner, concatArgs(cfg.ffmpegPath, { inputs: absolute, output, overwrite: cfg.overwrite, reencode: true }), timeout, 'ffmpeg 拼接');
+            }
+            return { output, count: absolute.length, reencode };
+        },
+        timeoutMs: timeout,
+    };
+    const encode = {
+        name: 'ffmpeg_encode',
+        description: '转码输出。预设：bilibili-1080p（H.264+AAC，码率上限 6000k，faststart，B 站推荐）、bilibili-4k（上限 20000k）、vertical-1080p（竖屏 1080x1920）、web-720p（轻量）。可选覆盖 crf（0-51）、fps、scale（如 1920:1080）。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '输入文件（必填）。' },
+            preset: { type: 'string', description: '预设档位：bilibili-1080p / bilibili-4k / vertical-1080p / web-720p（默认 bilibili-1080p）。' },
+            crf: { type: 'integer', description: '质量系数 0-51，越小越清晰（可选，覆盖预设）。' },
+            fps: { type: 'number', description: '输出帧率（可选）。' },
+            scale: { type: 'string', description: '输出分辨率，如 1920:1080 或 -2:720（可选）。' },
+            output: { type: 'string', description: '输出路径（可选，默认输入同目录加 .encoded 后缀）。' },
+        }),
+        output: {
+            schema: produceSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['转码完成：' + rec.output + '（预设 ' + rec.preset + '，crf=' + rec.crf + '）'];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const input = assertInputFile(requiredString(args, 'input', '输入文件'));
+            const presetRaw = optionalString(args, 'preset') ?? 'bilibili-1080p';
+            if (!ENCODE_PRESETS.includes(presetRaw)) {
+                throw new Error('preset 必须是 ' + ENCODE_PRESETS.join(' / ') + ' 之一（当前：' + presetRaw + '）。');
+            }
+            const preset = presetRaw;
+            let crf;
+            const crfRaw = args.crf;
+            if (crfRaw !== undefined) {
+                if (typeof crfRaw !== 'number' || !Number.isInteger(crfRaw) || crfRaw < 0 || crfRaw > 51)
+                    throw new Error('crf 必须是 0-51 的整数。');
+                crf = crfRaw;
+            }
+            let fps;
+            const fpsRaw = optionalNumber(args, 'fps');
+            if (fpsRaw !== undefined) {
+                if (fpsRaw <= 0 || fpsRaw > 240)
+                    throw new Error('fps 必须是 0-240 之间的正数。');
+                fps = fpsRaw;
+            }
+            let scale;
+            const scaleRaw = optionalString(args, 'scale');
+            if (scaleRaw !== undefined) {
+                if (!/^-?\d+:-?\d+$/.test(scaleRaw))
+                    throw new Error('scale 格式必须是 宽:高，如 1920:1080 或 -2:720。');
+                scale = scaleRaw;
+            }
+            const output = resolveOutputPath(input, optionalString(args, 'output'), '.encoded', extname(input) || '.mp4', cfg.overwrite);
+            await runChecked(runner, encodeArgs(cfg.ffmpegPath, { input, output, preset, crf, fps, scale, overwrite: cfg.overwrite }), timeout, 'ffmpeg 转码');
+            return { output, preset, crf: crf ?? 'preset', fps: fps ?? null, scale: scale ?? null };
+        },
+        timeoutMs: timeout,
+    };
+    const subtitle = {
+        name: 'ffmpeg_subtitle',
+        description: '把字幕文件（SRT/ASS 等）烧录进视频画面（硬字幕，任何播放器可见）。subtitle 为字幕文件路径。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '输入视频（必填）。' },
+            subtitle: { type: 'string', required: true, description: '字幕文件路径（SRT/ASS，必填）。' },
+            output: { type: 'string', description: '输出路径（可选，默认输入同目录加 .sub 后缀）。' },
+        }),
+        output: {
+            schema: produceSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['字幕烧录完成：' + rec.output + '（硬字幕）'];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const input = assertInputFile(requiredString(args, 'input', '输入视频'));
+            const subtitlePath = assertInputFile(requiredString(args, 'subtitle', '字幕文件'));
+            const output = resolveOutputPath(input, optionalString(args, 'output'), '.sub', extname(input) || '.mp4', cfg.overwrite);
+            await runChecked(runner, subtitleArgs(cfg.ffmpegPath, { input, subtitle: subtitlePath, output, overwrite: cfg.overwrite }), timeout, 'ffmpeg 字幕');
+            return { output, mode: 'burn' };
+        },
+        timeoutMs: timeout,
+    };
+    const extract = {
+        name: 'ffmpeg_extract',
+        description: '提取媒体成分。what=audio 提取音轨（流拷贝 m4a）；what=frames 按 fps 抽帧序列（输出为含 %03d 的 PNG 序列）；what=frame 抽单帧（start 时刻，默认首帧）；what=subtitle 提取字幕流（streamIndex 默认 0）。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '输入文件（必填）。' },
+            what: { type: 'string', required: true, description: '提取内容：audio / frames / frame / subtitle（必填）。' },
+            output: { type: 'string', description: '输出路径（可选，frames 默认 输入名-%03d.png）。' },
+            start: { type: 'string', description: '起始时间（可选）。' },
+            duration: { type: 'string', description: '时长（frames 用，可选）。' },
+            fps: { type: 'number', description: '抽帧帧率（frames 用，默认 1）。' },
+            streamIndex: { type: 'integer', description: '字幕流序号（subtitle 用，默认 0）。' },
+        }),
+        output: {
+            schema: produceSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['提取完成（' + rec.what + '）：' + rec.output];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const input = assertInputFile(requiredString(args, 'input', '输入文件'));
+            const what = requiredString(args, 'what', '提取内容');
+            const allowed = ['audio', 'frames', 'frame', 'subtitle'];
+            if (!allowed.includes(what))
+                throw new Error('what 必须是 ' + allowed.join(' / ') + ' 之一（当前：' + what + '）。');
+            const start = optionalTime(args, 'start');
+            const duration = optionalTime(args, 'duration');
+            const fps = optionalNumber(args, 'fps');
+            const streamIndex = typeof args.streamIndex === 'number' && Number.isInteger(args.streamIndex) && args.streamIndex >= 0 ? args.streamIndex : 0;
+            let output;
+            if (what === 'audio') {
+                output = resolveOutputPath(input, optionalString(args, 'output'), '.audio', '.m4a', cfg.overwrite);
+            }
+            else if (what === 'frame') {
+                output = resolveOutputPath(input, optionalString(args, 'output'), '.frame', '.png', cfg.overwrite);
+            }
+            else if (what === 'subtitle') {
+                output = resolveOutputPath(input, optionalString(args, 'output'), '.subtitle', '.srt', cfg.overwrite);
+            }
+            else {
+                const explicit = optionalString(args, 'output');
+                if (explicit !== undefined) {
+                    output = explicit.includes('%') ? explicit : explicit.replace(/(\.[^.]+)$/, '-%03d$1');
+                }
+                else {
+                    output = join(dirname(input), sanitizeName(basename(input, extname(input))) + '-%03d.png');
+                }
+            }
+            await runChecked(runner, extractArgs(cfg.ffmpegPath, { input, what: what, output, overwrite: cfg.overwrite, start, duration, fps, streamIndex }), timeout, 'ffmpeg 提取');
+            return { output, what, start: start ?? null, duration: duration ?? null, fps: fps ?? null, streamIndex };
+        },
+        timeoutMs: timeout,
+    };
+    const gif = {
+        name: 'ffmpeg_gif',
+        description: '视频转高质量 GIF（两遍调色板）。start 默认 0；duration 默认 10 秒；fps 默认 10（1-30）；width 默认 480（64-1280）。',
+        parameters: compileParameters({
+            input: { type: 'string', required: true, description: '输入视频（必填）。' },
+            start: { type: 'string', description: '起始时间（默认 0）。' },
+            duration: { type: 'string', description: '时长（默认 10 秒）。' },
+            fps: { type: 'integer', description: '帧率 1-30（默认 10）。' },
+            width: { type: 'integer', description: '输出宽度 64-1280（默认 480）。' },
+            output: { type: 'string', description: '输出路径（可选，默认输入同目录加 .gif 后缀）。' },
+        }),
+        output: {
+            schema: produceSchema,
+            render: buildTextRenderer((_args, value) => {
+                const rec = asRecord(value);
+                return ['GIF 生成完成：' + rec.output + '（' + rec.width + 'px，' + rec.fps + 'fps，' + fmtSeconds(Number(rec.duration ?? 0)) + ' 秒）'];
+            }),
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const input = assertInputFile(requiredString(args, 'input', '输入视频'));
+            const start = optionalTime(args, 'start') ?? 0;
+            const duration = optionalTime(args, 'duration') ?? 10;
+            if (duration <= 0)
+                throw new Error('duration 必须大于 0。');
+            const fpsRaw = args.fps;
+            const fps = typeof fpsRaw === 'number' && Number.isInteger(fpsRaw) ? Math.min(30, Math.max(1, fpsRaw)) : 10;
+            const widthRaw = args.width;
+            const width = typeof widthRaw === 'number' && Number.isInteger(widthRaw) ? Math.min(1280, Math.max(64, widthRaw)) : 480;
+            const output = resolveOutputPath(input, optionalString(args, 'output'), '.gif', '.gif', cfg.overwrite);
+            const palettePath = output + '.palette.png';
+            const spec = { input, output, palettePath, overwrite: cfg.overwrite, start, duration, fps, width };
+            try {
+                await runChecked(runner, gifPaletteArgs(cfg.ffmpegPath, spec), timeout, 'ffmpeg GIF 调色板');
+                await runChecked(runner, gifUseArgs(cfg.ffmpegPath, spec), timeout, 'ffmpeg GIF 合成');
+            }
+            finally {
+                rmSync(palettePath, { force: true });
+            }
+            return { output, start, duration, fps, width };
+        },
+        timeoutMs: timeout,
+    };
+    return [probe, cut, concat, encode, subtitle, extract, gif];
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "dsh-ffmpeg",
+  "version": "0.1.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"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/STARDUSTLC666/dsh-ffmpeg"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-ffmpeg/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-ffmpeg#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}