dsh-ffmpeg 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.5.1（2026-10-26）
+
+- 抽帧默认使用每次独立的 run 目录；显式帧序列检查实际文件冲突。输出保护覆盖所有拼接输入、字幕源、符号链接及硬链接别名。
+- Windows 回归 114 项通过、1 项跳过；宿主与未验收范围见[本次记录](docs/validation-0.5.1.md)。
+
 ## 0.5.0 (2026-10-15)
 
 - 修复 GIF 的起点和时长选项作用到错误输入，调色板以单帧写入；非零起点也能按指定区间导出。

package/docs/USAGE.en.md

@@ -2,6 +2,10 @@
 
 [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
 
+## Frame output and source protection
+
+Default frame sequences go to a fresh `<input>-frames/run-*/` directory. An explicit pattern needs `overwrite=true` for existing outputs; even then it cannot overwrite any input/subtitle source or its file aliases.
+
 ## Current improvements
 
 Relative paths resolve against the current session workspace. Explicit start / duration values must be valid; invalid values never silently fall back to full-video processing.
@@ -71,7 +75,7 @@ ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }
 
 ```bash
 pnpm install
-pnpm test       # build + 110 tests
+pnpm test       # build + 115 tests
 ```
 
 ## License

package/docs/USAGE.md

@@ -2,6 +2,10 @@
 
 [返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
 
+## 抽帧与源文件保护
+
+默认帧序列写入 `<输入名>-frames/run-*/`，每次使用新目录。显式指定序列时，已有输出需要 `overwrite=true`；即使允许覆盖，也不能覆盖任何输入或字幕源及其文件别名。
+
 ## 本次改进
 
 相对文件路径以当前会话工作区为基准。提供 start / duration 时必须是合法时间，非法输入不会退回默认值或意外处理整段视频。
@@ -75,7 +79,7 @@ ffmpeg_adjust { input: E:\videos\raw.mp4, volume: +2dB }
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 110 个测试
+pnpm test       # 构建 + 115 个测试
 ```
 
 ## License

package/docs/VALIDATION.md

@@ -1,5 +1,9 @@
 # dsh-ffmpeg 验证记录
 
+## 2026-10-26：0.5.1
+
+[本次修复、回归与未验收范围](validation-0.5.1.md)。
+
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
 ## 原中文记录

package/docs/validation-0.5.1.md

@@ -0,0 +1,19 @@
+# 0.5.1 验证记录
+
+日期：2026-10-26。官方 Windows 宿主：DSH 0.2.1-rc.3。
+
+## 行为变化
+
+抽帧默认使用每次独立的 run 目录；显式帧序列检查实际文件冲突。输出保护覆盖所有拼接输入、字幕源、符号链接及硬链接别名。
+
+## 验证与限制
+
+- Windows 本地：115 项，114 通过、1 跳过；没有把跳过计为通过。
+- 官方 RC.3 调用真实 FFmpeg 连续抽帧两次，目录互不覆盖，原有帧哨兵保持不变。Windows 跳过 1 项 POSIX 大小写检查，Linux 结果以 CI 为准。
+- GitHub 的跨平台 CI 和 npm 发布完整性以该版本工作流及 registry 为准；本记录不把本地测试等同于已发布。
+
+## English
+
+Frame extraction uses a separate run directory by default. Explicit frame sequences check existing output names. Output protection covers every concat input, subtitle sources and symlink/hard-link aliases.
+
+Runtime/account limits are listed above. Synthetic peers and model adapters do not establish live account delivery or model quality.

package/lib/paths.d.ts

@@ -2,8 +2,12 @@
 export declare function assertInputFile(input: string, cwd?: string): string;
 /** 清洗文件名中的危险字符。 */
 export declare function sanitizeName(name: string): string;
+/** Compare every source, resolving junctions/symlinks and detecting hard-link aliases. */
+export declare function assertOutputNotSource(inputs: readonly string[], target: string, cwd?: string): void;
+/** image2's -n does not protect expanded sequence files. Check a supported pattern first. */
+export declare function resolveFramePattern(input: string, explicit: string | undefined, overwrite: boolean, cwd?: string): string;
 /**
  * 决定输出路径：缺省时放在输入同目录，名字 = 输入名 + suffix + ext。
  * 目标已存在且不允许覆写时自动追加 _1/_2…。
  */
-export declare function resolveOutputPath(input: string, explicit: string | undefined, suffix: string, ext: string, overwrite: boolean, cwd?: string): string;
+export declare function resolveOutputPath(input: string | readonly string[], explicit: string | undefined, suffix: string, ext: string, overwrite: boolean, cwd?: string): string;

package/lib/paths.js

@@ -3,7 +3,7 @@
  *
  * @module dsh-ffmpeg/paths
  */
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, lstatSync, realpathSync, mkdirSync, mkdtempSync, readdirSync } from 'node:fs';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 /** 校验输入文件存在且是文件；返回绝对路径。 */
 export function assertInputFile(input, cwd = process.cwd()) {
@@ -21,22 +21,96 @@ export function sanitizeName(name) {
     const cleaned = name.trim().replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').replace(/\s+/g, '_').slice(0, 120);
     return cleaned === '' ? 'output' : cleaned;
 }
+function canonicalPath(file) {
+    let parent = resolve(file);
+    const missing = [];
+    while (!existsSync(parent)) {
+        if (lstatSync(parent, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error('输出路径包含悬空链接，已拒绝：' + file);
+        const next = dirname(parent);
+        if (next === parent)
+            throw new Error('无法解析输出路径：' + file);
+        missing.unshift(basename(parent));
+        parent = next;
+    }
+    const result = join(realpathSync(parent), ...missing);
+    return process.platform === 'win32' ? result.toLowerCase() : result;
+}
+/** Compare every source, resolving junctions/symlinks and detecting hard-link aliases. */
+export function assertOutputNotSource(inputs, target, cwd = process.cwd()) {
+    const absolute = resolve(cwd, target), canonical = canonicalPath(absolute);
+    const targetStat = existsSync(absolute) ? statSync(absolute, { bigint: true }) : undefined;
+    for (const input of inputs) {
+        const source = resolve(cwd, input), sourceStat = existsSync(source) ? statSync(source, { bigint: true }) : undefined;
+        if (canonicalPath(source) === canonical || (targetStat && sourceStat && sourceStat.ino !== 0n && targetStat.ino === sourceStat.ino && targetStat.dev === sourceStat.dev)) {
+            throw new Error('输出路径与输入文件相同或指向同一文件，已拒绝（避免覆盖源文件）。');
+        }
+    }
+}
+/** image2's -n does not protect expanded sequence files. Check a supported pattern first. */
+export function resolveFramePattern(input, explicit, overwrite, cwd = process.cwd()) {
+    if (!explicit?.trim()) {
+        const directory = join(dirname(input), sanitizeName(basename(input, extname(input))) + '-frames');
+        mkdirSync(directory, { recursive: true });
+        return join(mkdtempSync(join(directory, 'run-')), sanitizeName(basename(input, extname(input))) + '-%03d.png');
+    }
+    let pattern = resolve(cwd, explicit.trim());
+    if (!basename(pattern).includes('%')) {
+        const ext = extname(pattern);
+        pattern = ext ? pattern.slice(0, -ext.length) + '-%03d' + ext : pattern + '-%03d.png';
+    }
+    if (dirname(pattern).includes('%'))
+        throw new Error('序列占位符只能放在输出文件名中，不能放在目录名中。');
+    const filename = basename(pattern);
+    let source = '^', count = 0;
+    const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    for (let i = 0; i < filename.length;) {
+        if (filename[i] !== '%') {
+            source += literal(filename[i++]);
+            continue;
+        }
+        if (filename[i + 1] === '%') {
+            source += '%';
+            i += 2;
+            continue;
+        }
+        const marker = /^%(?:0([1-9][0-9]?))?d/.exec(filename.slice(i));
+        if (!marker)
+            throw new Error('抽帧序列文件名只支持 %d 或 %0Nd（例如 %03d），字面的 % 请写成 %%。');
+        count++;
+        source += '[0-9]{' + (marker[1] ? Number(marker[1]) : 1) + ',}';
+        i += marker[0].length;
+    }
+    if (count !== 1)
+        throw new Error('抽帧序列文件名必须包含且只包含一个 %d 或 %0Nd。');
+    const matcher = new RegExp(source + '$', process.platform === 'win32' ? 'i' : '');
+    const directory = dirname(pattern);
+    mkdirSync(directory, { recursive: true });
+    const existing = readdirSync(directory).filter(name => matcher.test(name));
+    for (const name of existing)
+        assertOutputNotSource([input], join(directory, name), cwd);
+    if (!overwrite && existing.length)
+        throw new Error('抽帧输出已存在（' + existing.length + ' 个同名序列文件），已拒绝覆盖；请更换输出目录或文件名前缀。');
+    return pattern;
+}
 /**
  * 决定输出路径：缺省时放在输入同目录，名字 = 输入名 + suffix + ext。
  * 目标已存在且不允许覆写时自动追加 _1/_2…。
  */
 export function resolveOutputPath(input, explicit, suffix, ext, overwrite, cwd = process.cwd()) {
+    const inputs = typeof input === 'string' ? [input] : input;
+    if (!inputs.length)
+        throw new Error('至少需要一个输入源文件。');
+    const primary = resolve(cwd, inputs[0]);
     let target;
     if (explicit !== undefined && explicit.trim() !== '') {
         target = resolve(cwd, 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('输出路径与输入文件相同，已拒绝（避免覆盖源文件）。');
+        const base = basename(primary, extname(primary));
+        target = join(dirname(primary), sanitizeName(base) + suffix + ext);
     }
+    assertOutputNotSource(inputs, target, cwd);
     if (overwrite || !existsSync(target))
         return target;
     const directory = dirname(target);

package/lib/tools.js

@@ -10,7 +10,7 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { adjustArgs, 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 { assertInputFile, resolveOutputPath, resolveFramePattern, sanitizeName } from './paths.js';
 import { parseTimeArg } from './config.js';
 function executionCwd(exec) { return exec?.agent?.session?.header?.cwd || process.cwd(); }
 /** 编译作者 DSL 为原始 JSON Schema（正是 defineTool 存为 definition.parameters 的值）。 */
@@ -282,7 +282,7 @@ export function buildFfmpegTools(config, runner) {
             if (requestedFps !== undefined && (!Number.isFinite(requestedFps) || requestedFps < 1 || requestedFps > 240))
                 throw new Error('fps 必须在 1-240 之间。');
             const firstExt = extname(absolute[0]) || '.mp4';
-            const output = resolveOutputPath(absolute[0], optionalString(args, 'output'), '.concat', firstExt, cfg.overwrite, executionCwd(exec));
+            const output = resolveOutputPath(absolute, optionalString(args, 'output'), '.concat', firstExt, cfg.overwrite, executionCwd(exec));
             let normalized;
             if (!reencode) {
                 const listPath = join(tmpdir(), 'dsh-ffmpeg-concat-' + Date.now() + '-' + randomUUID().slice(0, 8) + '.txt');
@@ -391,7 +391,7 @@ export function buildFfmpegTools(config, runner) {
             const args = asRecord(rawArgs);
             const input = assertInputFile(requiredString(args, 'input', '输入视频'), executionCwd(exec));
             const subtitlePath = assertInputFile(requiredString(args, 'subtitle', '字幕文件'), executionCwd(exec));
-            const output = resolveOutputPath(input, optionalString(args, 'output'), '.sub', extname(input) || '.mp4', cfg.overwrite, executionCwd(exec));
+            const output = resolveOutputPath([input, subtitlePath], optionalString(args, 'output'), '.sub', extname(input) || '.mp4', cfg.overwrite, executionCwd(exec));
             await runChecked(runner, subtitleArgs(cfg.ffmpegPath, { input, subtitle: subtitlePath, output, overwrite: cfg.overwrite }), timeout, 'ffmpeg 字幕', exec?.signal);
             return { output, mode: 'burn' };
         },
@@ -438,20 +438,7 @@ export function buildFfmpegTools(config, runner) {
                 output = resolveOutputPath(input, optionalString(args, 'output'), '.subtitle', '.srt', cfg.overwrite, executionCwd(exec));
             }
             else {
-                const rawOutput = optionalString(args, 'output');
-                const explicit = rawOutput === undefined ? undefined : resolve(executionCwd(exec), rawOutput);
-                if (explicit !== undefined) {
-                    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');
-                }
+                output = resolveFramePattern(input, optionalString(args, 'output'), cfg.overwrite, executionCwd(exec));
             }
             const spec = { input, what: what, output, overwrite: cfg.overwrite, start, duration, fps, streamIndex };
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ffmpeg",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "用自然语言调用 FFmpeg，处理已有音视频文件。",
   "type": "module",
   "main": "lib/index.js",