@mqn00/file-manager-plugin-compress 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# file-manager-plugin-compress
+
+File Manager 压缩插件：将内置压缩功能提取为独立插件并增强。
+
+## 功能
+
+- **多选压缩**：支持同时选择多个**文件**与**文件夹**压缩为单个 zip（原有内置压缩仅支持单选文件夹）
+- **指定输出文件夹**：压缩结果可放入任意已存在文件夹，默认输出到**当前浏览文件夹**
+- **压缩前权限预检**：
+  - 确认每个选中条目的**读取权限**（`R_OK`）
+  - 确认输出文件夹的**写入权限**（`W_OK`）且必须存在
+  - 禁止输出文件夹位于某个选中文件夹内部（避免把 zip 压进自己）
+- **后台任务**：压缩任务推入**主项目后台任务系统**——后台任务面板（TaskPanel）展示进度/速度/当前文件并可取消；任务持久化，页面刷新后可继续跟踪；取消/失败自动清理半成品
+- **命名规则**：单项 `<名称>.zip`；多项 `<首项名称> 等 N 项.zip`；目标已存在自动追加 ` (1)`、` (2)`… 后缀，不覆盖
+
+## 使用
+
+安装/启用插件后，文件浏览器**多选任意文件/文件夹**（复选框）→ 工具栏批量操作区出现「压缩」按钮 →
+点击弹出对话框：确认默认输出文件夹（可点「选择」更换）→ 权限预检通过后「开始压缩」→
+任务推送到后台（对话框关闭），在**后台任务面板**查看进度/取消；完成后输出目录自动刷新。
+
+## 接口
+
+均需登录，挂在 `/api/plugin/compress` 下（详见主项目 `API.md`「4. 压缩（compress 插件）」）：
+
+| 接口 | 说明 |
+|------|------|
+| `POST /api/plugin/compress/check` | 权限预检（源读取 + 输出目录写入 + 目录包含防护），返回逐项状态与目标 zip 路径 |
+| `POST /api/plugin/compress/zip` | **创建压缩后台任务**，返回 `taskId`；进度/取消/完成走主项目任务系统（`GET /api/tasks`、`GET /api/tasks/:id/stream`、`POST /api/tasks/:id/cancel`） |
+
+## 构建与测试
+
+```bash
+npm install --registry=https://registry.npmmirror.com   # 安装依赖（archiver 等）
+npm run build                                            # tsc 编译后端 + esbuild 打包前端
+npm test                                                 # vitest 单元测试（命名/权限/条目收集/压缩/取消）
+```
+
+## 依赖
+
+- 运行时：`archiver`
+- 主项目：`file-manager`（peerDependencies，类型与平台能力：`ctx.utils.path.safe`、`ctx.services.task` 外部任务（createExternal/updateProgress/finalize）、日志等；工具栏操作经主应用 `window.__fm_bulk_actions` 注册表挂载）
+
+## 任务系统接入示例
+
+本插件演示如何将耗时操作接入主项目后台任务系统：
+
+**后端**（创建任务 + 执行 + 进度上报）：
+
+```ts
+// 1. 创建任务条目
+const task = ctx.services.task.createExternal(
+  'compress',
+  { paths, names, outputDir, targetPath },
+  { phase: 'compress', totalCount: paths.length }
+)
+
+// 2. 获取取消信号
+const signal = ctx.services.task.signal(task.id)
+
+// 3. 异步执行（不阻塞响应）
+void (async () => {
+  try {
+    // ... 执行压缩 ...
+    ctx.services.task.updateProgress(task.id, { progress: 50, currentFile: 'xxx.txt' })
+    ctx.services.task.finalize(task.id, 'completed')
+  } catch (e) {
+    if (e?.message === 'CANCELLED') {
+      ctx.services.task.finalize(task.id, 'cancelled', { message: '已取消' })
+    } else {
+      ctx.services.task.finalize(task.id, 'failed', { error: e.message })
+    }
+  }
+})()
+
+// 4. 立即返回 taskId
+res.json({ taskId: task.id })
+```
+
+**前端**（挂载任务到 TaskPanel）：
+
+```ts
+export const install: FrontendPluginInstallFunction = (ctx) => {
+  // 注册批量操作
+  const api = window.__fm_bulk_actions
+  api?.register({
+    id: 'compress',
+    label: '压缩',
+    visible: (p) => p.count > 0,
+    run: (payload) => openCompressDialog(ctx, payload),
+  })
+}
+
+// 对话框中创建任务后：
+const { taskId } = await ctx.api.instance.post('/plugin/compress/zip', { paths, outputDir })
+ctx.stores.task.attachTask(taskId, taskInfo, () => {
+  // 完成回调：刷新文件列表等
+})
+```

package/dist/backend.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 压缩插件后端入口
+ *
+ * 注册路由（均需登录）：
+ * - POST /api/plugin/compress/check ：压缩前预检（源读取权限 + 输出目录写入权限 + 目录包含防护）
+ * - POST /api/plugin/compress/zip   ：创建压缩后台任务（推入主项目任务系统，返回 taskId；
+ *                                      进度/取消/完成由主项目 /api/tasks 系列端点承载）
+ */
+import type { BackendPluginContext, PluginInstallFunction } from '@mqn00/file-manager/plugin';
+export declare const install: PluginInstallFunction<BackendPluginContext>;

package/dist/backend.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.install = void 0;
+const compress_js_1 = require("./compress.js");
+const install = (ctx) => {
+    const service = (0, compress_js_1.createCompressService)({
+        safePath: ctx.utils.path.safe,
+        getStorageRoot: ctx.utils.path.getStorageRoot,
+        log: (level, tag, message) => ctx.utils.logger.log(level, tag, message),
+    });
+    const toStrArray = (v) => Array.isArray(v)
+        ? v.filter((x) => typeof x === 'string' && x.length > 0)
+        : [];
+    const toStr = (v) => (typeof v === 'string' ? v : '');
+    const router = ctx.express.Router();
+    // ---- 权限预检 ----
+    router.post('/check', ctx.middleware.auth, async (req, res) => {
+        const { paths, outputDir } = (req.body ?? {});
+        try {
+            if (!outputDir) {
+                res.status(400).json({ message: '缺少输出文件夹' });
+                return;
+            }
+            const result = await service.checkPermissions(toStrArray(paths), toStr(outputDir));
+            res.json(result);
+        }
+        catch (e) {
+            ctx.utils.logger.log('ERROR', 'compress', `权限预检失败: ${e?.message || '未知错误'}`);
+            res.status(400).json({ message: e?.message || '权限预检失败' });
+        }
+    });
+    // ---- 创建压缩后台任务 ----
+    router.post('/zip', ctx.middleware.auth, async (req, res) => {
+        const { paths, outputDir } = (req.body ?? {});
+        const pathsArr = toStrArray(paths);
+        const output = toStr(outputDir);
+        if (!output) {
+            res.status(400).json({ message: '缺少输出文件夹' });
+            return;
+        }
+        if (!pathsArr.length) {
+            res.status(400).json({ message: '未选择任何文件/文件夹' });
+            return;
+        }
+        try {
+            // 预计算输出 zip 目标（与 runJob 内部幂等一致：命名只依赖首项名称与数量）
+            const sources = pathsArr.map((p) => service.resolveSource(p));
+            const target = service.computeTarget(sources, output);
+            // 任务条目注册进主项目任务系统（冲突检测失败抛 TASK_CONFLICT）
+            const task = ctx.services.task.createExternal('compress', {
+                paths: pathsArr,
+                names: sources.map((s) => s.name),
+                outputDir: output,
+                targetPath: target.relativePath,
+            }, { phase: 'compress', totalCount: pathsArr.length });
+            // 异步执行压缩，进度/终态经任务系统广播（不阻塞创建响应）
+            const signal = ctx.services.task.signal(task.id);
+            void (async () => {
+                try {
+                    const result = await service.runJob({
+                        paths: pathsArr,
+                        outputDir: output,
+                        signal,
+                        onProgress: (percent, _processedBytes, totalBytes) => {
+                            ctx.services.task.updateProgress(task.id, {
+                                progress: percent,
+                                totalSize: totalBytes,
+                            });
+                        },
+                    });
+                    // 完成：回写最终目标路径后收尾
+                    ctx.services.task.updateProgress(task.id, {
+                        progress: 100,
+                        metadata: { ...task.metadata, targetPath: result.target.relativePath },
+                    });
+                    ctx.services.task.finalize(task.id, 'completed');
+                }
+                catch (e) {
+                    if (e?.message === 'CANCELLED') {
+                        ctx.services.task.finalize(task.id, 'cancelled', { message: '压缩已取消' });
+                    }
+                    else {
+                        const msg = e instanceof compress_js_1.ZCompressError ? e.message : `压缩失败: ${e?.message || '未知错误'}`;
+                        ctx.utils.logger.log('ERROR', 'compress', `压缩任务失败: ${msg}`);
+                        ctx.services.task.finalize(task.id, 'failed', { error: msg });
+                    }
+                }
+            })();
+            res.json({ taskId: task.id });
+        }
+        catch (e) {
+            if (e?.code === 'TASK_CONFLICT') {
+                res.status(409).json({ message: e.message });
+                return;
+            }
+            ctx.utils.logger.log('ERROR', 'compress', `创建压缩任务失败: ${e?.message || '未知错误'}`);
+            res.status(400).json({ message: e?.message || '创建压缩任务失败' });
+        }
+    });
+    ctx.app.use('/api/plugin/compress', router);
+};
+exports.install = install;

package/dist/compress.d.ts

@@ -0,0 +1,82 @@
+export interface ServiceDeps {
+    /** 安全路径解析：相对路径 → 存储根内的绝对路径（越界抛错） */
+    safePath(userPath: string): string;
+    /** 存储根绝对路径 */
+    getStorageRoot(): string;
+    /** 日志 */
+    log(level: 'INFO' | 'WARNING' | 'ERROR', tag: string, message: string): void;
+}
+export interface SourceItem {
+    /** 相对路径（用户输入） */
+    path: string;
+    /** 存取根内的绝对路径 */
+    fullPath: string;
+    name: string;
+    kind: 'file' | 'dir';
+}
+export interface SourceCheck {
+    path: string;
+    name: string;
+    kind: 'file' | 'dir';
+    exists: boolean;
+    readable: boolean;
+    error?: string;
+}
+export interface OutputCheck {
+    path: string;
+    exists: boolean;
+    isDir: boolean;
+    writable: boolean;
+    error?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    items: SourceCheck[];
+    output: OutputCheck;
+    /** 计划生成的 zip 相对路径（冲突已考虑后缀），输出目录非法时为空 */
+    targetPath: string;
+    /** 输出目录是否落在某个选中文件夹内部（禁止） */
+    forbidden: boolean;
+    forbiddenMessage?: string;
+}
+export interface ZipEntry {
+    filePath: string;
+    zipName: string;
+    size: number;
+}
+export interface TargetInfo {
+    fullPath: string;
+    relativePath: string;
+}
+export declare function createCompressService(deps: ServiceDeps): {
+    resolveSource: (userPath: string) => SourceItem;
+    computeTarget: (sources: SourceItem[], outputDirUserPath: string) => TargetInfo;
+    targetBaseName: (sources: SourceItem[]) => string;
+    isForbiddenOutput: (sources: SourceItem[], outputDirFull: string) => string | null;
+    checkPermissions: (paths: string[], outputDir: string) => Promise<CheckResult>;
+    collectEntries: (sources: SourceItem[]) => Promise<{
+        entries: ZipEntry[];
+        totalBytes: number;
+    }>;
+    createArchive: (opts: {
+        entries: ZipEntry[];
+        targetFull: string;
+        totalBytes: number;
+        signal?: AbortSignal;
+        onProgress?: (percent: number, processedBytes: number, totalBytes: number) => void;
+    }) => Promise<TargetInfo>;
+    runJob: (opts: {
+        paths: string[];
+        outputDir: string;
+        signal?: AbortSignal;
+        onProgress?: (percent: number, processedBytes: number, totalBytes: number) => void;
+    }) => Promise<{
+        target: TargetInfo;
+        entries: number;
+    }>;
+};
+/** 用户可读的压缩业务错误（路由层转为 SSE error / HTTP 400） */
+export declare class ZCompressError extends Error {
+    constructor(message: string);
+}
+export type CompressService = ReturnType<typeof createCompressService>;

package/dist/compress.js

@@ -0,0 +1,350 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZCompressError = void 0;
+exports.createCompressService = createCompressService;
+/**
+ * 压缩插件后端服务
+ *
+ * 多源（文件 + 文件夹）压缩为单个 zip：
+ * - `computeTarget`：确定输出 zip 路径（命名 + 冲突自动加 (n) 后缀）
+ * - `checkPermissions`：压缩前预检（源读取权限 R_OK、输出目录写入权限 W_OK）
+ * - `collectEntries`：收集全部待压缩条目并汇总字节数
+ * - `createArchive`：以 archiver 流式压缩（支持 AbortSignal 取消，取消/失败清理半成品）
+ *
+ * 路径解析依赖注入（来自主应用 ctx.utils.path.safe / getStorageRoot），
+ * 单测可通过假 ctx（临时 storageRoot）直接构造服务。
+ */
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const archiver_1 = __importDefault(require("archiver"));
+const VALID_LEVELS = ['INFO', 'WARNING', 'ERROR'];
+function isLogLevel(v) {
+    return typeof v === 'string' && VALID_LEVELS.includes(v);
+}
+function createCompressService(deps) {
+    const { safePath, getStorageRoot, log } = deps;
+    const logSafe = (level, tag, message) => {
+        try {
+            log(level, tag, message);
+        }
+        catch {
+            // 日志失败不影响主流程
+        }
+    };
+    /** 解析用户相对路径为绝对路径（越界/非法抛 AppError） */
+    function resolveSource(userPath) {
+        const fullPath = safePath(userPath);
+        const name = path_1.default.basename(userPath) || userPath;
+        return { path: userPath, fullPath, name, kind: 'file' };
+    }
+    /** 相对路径转 zip 文件名（单项 / 多项目命名规则） */
+    function targetBaseName(sources) {
+        const firstName = sources[0].name;
+        if (sources.length === 1)
+            return `${firstName}.zip`;
+        return `${firstName} 等 ${sources.length} 项.zip`;
+    }
+    /**
+     * 计算输出 zip 目标路径：outputDir/<name>.zip；
+     * 已存在时依次尝试 `name (1).zip`、`name (2).zip`… 避免覆盖。
+     */
+    function computeTarget(sources, outputDirUserPath) {
+        const outputDirFull = safePath(outputDirUserPath);
+        const base = targetBaseName(sources);
+        let candidate = path_1.default.join(outputDirFull, base);
+        let n = 1;
+        while ((0, fs_1.existsSync)(candidate)) {
+            const stem = base.replace(/\.zip$/, '');
+            candidate = path_1.default.join(outputDirFull, `${stem} (${n}).zip`);
+            n += 1;
+        }
+        const relativePath = path_1.default.relative(getStorageRoot(), candidate).replace(/\\/g, '/');
+        return { fullPath: candidate, relativePath };
+    }
+    /** 输出目录是否等于或位于某个选中文件夹内部（禁止项） */
+    function isForbiddenOutput(sources, outputDirFull) {
+        for (const s of sources) {
+            if (s.kind !== 'dir')
+                continue;
+            if (outputDirFull === s.fullPath || outputDirFull.startsWith(s.fullPath + path_1.default.sep)) {
+                return `输出目录不能位于待压缩文件夹「${s.name}」内部`;
+            }
+        }
+        return null;
+    }
+    /**
+     * 压缩前权限预检：逐项读取权限 + 输出目录写入权限 + 目录包含防护。
+     */
+    async function checkPermissions(paths, outputDir) {
+        const items = [];
+        let sources = [];
+        for (const p of paths) {
+            const src = resolveSource(p);
+            try {
+                const st = await fs_1.promises.lstat(src.fullPath);
+                src.kind = st.isDirectory() ? 'dir' : 'file';
+            }
+            catch (e) {
+                items.push({
+                    path: p,
+                    name: src.name,
+                    kind: 'file',
+                    exists: false,
+                    readable: false,
+                    error: e?.message || '不存在或无访问权限',
+                });
+                continue;
+            }
+            let readable = false;
+            let error;
+            try {
+                await fs_1.promises.access(src.fullPath, fs_1.promises.constants.R_OK);
+                readable = true;
+            }
+            catch (e) {
+                error = e?.message || '无读取权限';
+            }
+            sources.push(src);
+            items.push({ path: p, name: src.name, kind: src.kind, exists: true, readable, error });
+        }
+        let output = { path: outputDir, exists: false, isDir: false, writable: false };
+        let forbidden = null;
+        try {
+            const st = await fs_1.promises.stat(safePath(outputDir));
+            output = { path: outputDir, exists: true, isDir: st.isDirectory(), writable: false };
+            if (!st.isDirectory()) {
+                output.error = '输出位置不是文件夹';
+            }
+            else {
+                try {
+                    await fs_1.promises.access(safePath(outputDir), fs_1.promises.constants.W_OK);
+                    output.writable = true;
+                }
+                catch (e) {
+                    output.error = e?.message || '无写入权限';
+                }
+                forbidden = isForbiddenOutput(sources, safePath(outputDir));
+            }
+        }
+        catch (e) {
+            output.error = e?.message || '输出文件夹不存在或无访问权限';
+        }
+        const targetPath = items.every((i) => i.readable) && output.exists && output.isDir && output.writable && !forbidden
+            ? computeTarget(sources, outputDir).relativePath
+            : '';
+        return {
+            ok: items.every((i) => i.readable) &&
+                output.exists &&
+                output.isDir &&
+                output.writable &&
+                !forbidden,
+            items,
+            output,
+            targetPath,
+            forbidden: !!forbidden,
+            forbiddenMessage: forbidden ?? undefined,
+        };
+    }
+    /**
+     * 收集全部待压缩条目（文件直接一项；文件夹递归，zipName = 文件夹名/…）。
+     * 不可读文件跳过（readdir 阶段已有 R_OK 预检，这里是兜底）。
+     */
+    async function collectEntries(sources) {
+        const entries = [];
+        let totalBytes = 0;
+        const walk = async (dirFull, zipPrefix) => {
+            let names;
+            try {
+                names = await fs_1.promises.readdir(dirFull);
+            }
+            catch {
+                return;
+            }
+            for (const name of names) {
+                const childFull = path_1.default.join(dirFull, name);
+                const zipName = `${zipPrefix}/${name}`;
+                try {
+                    const st = await fs_1.promises.lstat(childFull);
+                    if (st.isDirectory()) {
+                        await walk(childFull, zipName);
+                    }
+                    else if (st.isFile()) {
+                        entries.push({ filePath: childFull, zipName, size: st.size });
+                        totalBytes += st.size;
+                    }
+                }
+                catch {
+                    // 跳过不可读条目
+                }
+            }
+        };
+        for (const src of sources) {
+            if (src.kind === 'file') {
+                try {
+                    const st = await fs_1.promises.stat(src.fullPath);
+                    entries.push({ filePath: src.fullPath, zipName: src.name, size: st.size });
+                    totalBytes += st.size;
+                }
+                catch {
+                    // 源文件已不可读：跳过（压缩结果缺少该项）
+                }
+            }
+            else {
+                await walk(src.fullPath, src.name);
+            }
+        }
+        return { entries, totalBytes };
+    }
+    /**
+     * 流式压缩（Per-entry 进度回调）。
+     * 成功 resolve({ relativePath })；取消 reject(new Error('CANCELLED')) 并清理半成品；
+     * 出错 reject 并清理半成品。
+     */
+    function createArchive(opts) {
+        const { entries, targetFull, totalBytes, signal, onProgress } = opts;
+        const relativePath = path_1.default.relative(getStorageRoot(), targetFull).replace(/\\/g, '/');
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                try {
+                    if ((0, fs_1.existsSync)(targetFull))
+                        (0, fs_1.unlinkSync)(targetFull);
+                }
+                catch {
+                    // 忽略清理失败
+                }
+            };
+            const cleanupAbort = () => {
+                if (signal?.aborted) {
+                    cleanup();
+                    reject(new Error('CANCELLED'));
+                }
+            };
+            const output = (0, fs_1.createWriteStream)(targetFull);
+            const archive = archiver_1.default.create('zip', { zlib: { level: 9 } });
+            let processedBytes = 0;
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                archive.abort();
+                reject(new Error('CANCELLED'));
+            };
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+            archive.on('entry', (entry) => {
+                if (entry.stats && !entry.stats.isDirectory()) {
+                    processedBytes += entry.stats.size;
+                    const denom = totalBytes > 0 ? totalBytes : 1;
+                    const percent = Math.min(100, Math.round((processedBytes / denom) * 100));
+                    onProgress?.(percent, processedBytes, totalBytes);
+                }
+            });
+            output.on('close', () => {
+                finish(() => {
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve({ fullPath: targetFull, relativePath });
+                });
+            });
+            archive.on('error', (err) => {
+                finish(() => {
+                    cleanupAbort();
+                    signal?.removeEventListener('abort', onAbort);
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                });
+            });
+            output.on('error', (err) => {
+                finish(() => {
+                    cleanup();
+                    signal?.removeEventListener('abort', onAbort);
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                });
+            });
+            archive.pipe(output);
+            for (const entry of entries) {
+                // 条目可能已消失（压缩开始后源被删除）：archiver 对不存在文件会抛错，由 error 分支兜底
+                archive.file(entry.filePath, { name: entry.zipName });
+            }
+            archive.finalize();
+        });
+    }
+    /**
+     * 一次压缩任务（路由层调用，返回结构化结果而非直接写 SSE，便于测试）。
+     * - ZCompressError 携带用户可读错误（含校验失败）
+     * - CANCELLED 表示被取消
+     */
+    async function runJob(opts) {
+        // 去重（多选列表理论上不重复，防呆）
+        const paths = [...new Set(opts.paths)];
+        const { outputDir } = opts;
+        if (!paths.length) {
+            throw new ZCompressError('未选择任何文件/文件夹');
+        }
+        // 预检：存在性 + 读取/写入权限 + 目录包含防护
+        const check = await checkPermissions(paths, outputDir);
+        if (!check.ok) {
+            const detail = [...check.items.map((i) => `${i.name}: ${i.error || (i.readable ? '可读' : '不可读')}`)]
+                .concat(check.output.error ? [`输出目录: ${check.output.error}`] : [])
+                .concat(check.forbiddenMessage ? [check.forbiddenMessage] : []);
+            throw new ZCompressError(detail.join('；'));
+        }
+        const sources = check.items.map((item) => resolveSource(item.path));
+        sources.forEach((s, i) => (s.kind = check.items[i].kind));
+        const target = computeTarget(sources, outputDir);
+        const { entries, totalBytes } = await collectEntries(sources);
+        if (!entries.length) {
+            throw new ZCompressError('没有可压缩的文件');
+        }
+        logSafe('INFO', 'compress', `开始压缩 ${paths.length} 项 → ${target.relativePath}（${entries.length} 个文件，${totalBytes} 字节）`);
+        try {
+            await createArchive({
+                entries,
+                targetFull: target.fullPath,
+                totalBytes,
+                signal: opts.signal,
+                onProgress: opts.onProgress,
+            });
+        }
+        catch (e) {
+            if (e?.message === 'CANCELLED') {
+                logSafe('INFO', 'compress', `压缩已取消：${target.relativePath}`);
+                throw e;
+            }
+            logSafe('ERROR', 'compress', `压缩失败 ${target.relativePath}: ${e?.message || '未知错误'}`);
+            throw e;
+        }
+        logSafe('INFO', 'compress', `压缩完成：${target.relativePath}`);
+        return { target, entries: entries.length };
+    }
+    return {
+        resolveSource,
+        computeTarget,
+        targetBaseName,
+        isForbiddenOutput,
+        checkPermissions,
+        collectEntries,
+        createArchive,
+        runJob,
+    };
+}
+/** 用户可读的压缩业务错误（路由层转为 SSE error / HTTP 400） */
+class ZCompressError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ZCompressError';
+    }
+}
+exports.ZCompressError = ZCompressError;

package/dist/dialog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * compress 插件压缩对话框
+ *
+ * 由工具栏「压缩」操作触发（openCompressDialog），用 ctx.Vue.createApp 挂载到
+ * document.body（插件无法 import 主应用 .vue 组件，故自建对话框与文件夹选择器）。
+ *
+ * 流程：选择输出文件夹（默认当前浏览文件夹）→ 权限预检（POST /check，
+ * 源读取权限 + 输出目录写入权限 + 目录包含防护）→ 全部通过才可「开始压缩」→
+ * POST /zip 创建后台任务（推入主项目任务系统）→ 对话框关闭，任务卡片出现在
+ * 后台任务面板（进度/取消/完成由主项目 TaskPanel 承接）→ 完成后条件刷新输出目录。
+ */
+import type { FrontendPluginContext, BulkActionContext } from '@mqn00/file-manager/plugin/frontend';
+/** 压缩对话框载荷：主应用批量操作点按上下文（类型入口发布，与 BulkActionContext 同一契约） */
+export type CompressPayload = BulkActionContext;
+/**
+ * 关闭并卸载当前打开的压缩对话框（插件 teardown 调用）。
+ * 幂等：未打开时 no-op。
+ */
+export declare function closeCompressDialog(): void;
+export declare function openCompressDialog(ctx: FrontendPluginContext, payload: CompressPayload): void;