@xcanwin/manyoyo 8.7.3 → 8.7.4

package/lib/archive/plan.js

@@ -0,0 +1,197 @@
+'use strict';
+
+// 容器导出 / 导入的档位与范围：服务端单一数据源，前端只渲染（GET /api/transfer/preview 下发）。
+
+const path = require('path');
+
+const FORMAT = 1;
+const AGENT_HOME = '/root';
+
+// 内容项。always：每档都带，不可取消的核心（取消 agentSessions 会让续接失效，自定义里允许取消，导入时会清掉续接标记）
+const ITEMS = [
+    { id: 'history', label: '网页聊天记录', hint: '对话、备注、置顶、标题', tiers: ['light', 'standard', 'full'] },
+    { id: 'agentSessions', label: 'Agent 会话记录', hint: '换机器后能接着聊的关键', tiers: ['light', 'standard', 'full'] },
+    { id: 'settings', label: '容器设置', hint: '环境变量、自启动脚本、系统提示词、网络规则', tiers: ['light', 'standard', 'full'] },
+    { id: 'uploads', label: '聊天里的图片', hint: '', tiers: ['standard', 'full'] },
+    { id: 'agentExtras', label: 'Agent 其余改动', hint: '技能、MCP、设置、记忆', tiers: ['standard', 'full'] },
+    { id: 'workdir', label: '工作目录', hint: '宿主机上的项目文件', tiers: ['standard', 'full'] },
+    { id: 'systemLayer', label: '容器里其它改动', hint: '装的软件、全局包；只在镜像版本相同时还原', tiers: ['full'] },
+    { id: 'snapshots', label: '按轮回退快照', hint: '可能很大', tiers: ['full'] }
+];
+
+const TIERS = [
+    { id: 'light', label: '轻量' },
+    { id: 'standard', label: '标准', recommended: true },
+    { id: 'full', label: '完整' }
+];
+
+function itemsForTier(tier) {
+    return ITEMS.filter(item => item.tiers.includes(tier)).map(item => item.id);
+}
+
+// 勾选集合正好等于某档就返回那一档，否则 'custom'
+function matchTier(itemIds) {
+    const set = new Set(itemIds);
+    for (const tier of TIERS) {
+        const expected = itemsForTier(tier.id);
+        if (expected.length === set.size && expected.every(id => set.has(id))) return tier.id;
+    }
+    return 'custom';
+}
+
+function normalizeItems(input, tier) {
+    const known = new Set(ITEMS.map(item => item.id));
+    if (Array.isArray(input)) {
+        const picked = [...new Set(input.map(String))];
+        const unknown = picked.find(id => !known.has(id));
+        if (unknown) throw new Error(`未知的导出内容: ${unknown}`);
+        return ITEMS.map(item => item.id).filter(id => picked.includes(id));
+    }
+    if (!TIERS.some(item => item.id === tier)) throw new Error(`未知的档位: ${tier}`);
+    return itemsForTier(tier);
+}
+
+// 容器里永远不导出的位置：缓存、临时目录、运行时生成的文件
+const EXCLUDED_PREFIXES = [
+    '/tmp', '/var/tmp', '/run', '/var/run', '/var/cache', '/var/lib/apt/lists', '/var/log',
+    '/root/.cache', '/root/.npm/_cacache', '/root/.codex/.tmp', '/root/.codex/tmp',
+    '/proc', '/sys', '/dev',
+    '/etc/hosts', '/etc/hostname', '/etc/resolv.conf', '/etc/mtab'
+];
+
+// 容器内路径统一成不含 .. 的绝对 POSIX 路径；不是绝对路径返回 null
+function normalizeContainerPath(input) {
+    if (typeof input !== 'string' || !input.startsWith('/') || input.includes('\0')) return null;
+    const normalized = path.posix.normalize(input);
+    if (normalized.split('/').includes('..')) return null;
+    return normalized === '/' ? '/' : normalized.replace(/\/+$/, '');
+}
+
+function isUnder(target, base) {
+    return target === base || target.startsWith(`${base}/`);
+}
+
+function isExcludedPath(containerPath) {
+    const p = normalizeContainerPath(containerPath);
+    if (!p) return true;
+    if (EXCLUDED_PREFIXES.some(prefix => isUnder(p, prefix))) return true;
+    return p.split('/').some((segment, index, all) => segment === 'node_modules' && all[index + 1] === '.cache');
+}
+
+// Agent 会话记录：续接必需。清单由真实续接实测校准（见 FEEDBACK），少了补、多了无妨
+const AGENT_SESSION_PATHS = [
+    `${AGENT_HOME}/.claude/projects`,
+    `${AGENT_HOME}/.claude.json`,
+    `${AGENT_HOME}/.codex/sessions`,
+    `${AGENT_HOME}/.codex/archived_sessions`,
+    `${AGENT_HOME}/.codex/session_index.jsonl`,
+    `${AGENT_HOME}/.gemini/tmp`,
+    `${AGENT_HOME}/.local/share/opencode`
+];
+const AGENT_SESSION_PATTERNS = [/^\/root\/\.codex\/[^/]+\.sqlite[^/]*$/];
+// Agent 其余目录：整个目录里相对镜像有变化的文件（会话记录部分已单独归类）
+const AGENT_DIRS = [`${AGENT_HOME}/.claude`, `${AGENT_HOME}/.codex`, `${AGENT_HOME}/.gemini`, `${AGENT_HOME}/.config/opencode`, `${AGENT_HOME}/.local/share/opencode`];
+
+function isAgentSessionPath(p) {
+    return AGENT_SESSION_PATHS.some(base => isUnder(p, base)) || AGENT_SESSION_PATTERNS.some(re => re.test(p));
+}
+
+/**
+ * 容器内一个路径属于哪一类：'agentSessions' | 'agentExtras' | 'systemLayer'；永远不导出的返回 null。
+ * mounts：容器的挂载点目的地（含其下全部内容都不导出）。
+ */
+function classifyLayerPath(containerPath, mounts = []) {
+    const p = normalizeContainerPath(containerPath);
+    if (!p || p === '/') return null;
+    if (isExcludedPath(p)) return null;
+    for (const mount of mounts) {
+        const m = normalizeContainerPath(mount);
+        if (m && isUnder(p, m)) return null;
+    }
+    if (isAgentSessionPath(p)) return 'agentSessions';
+    if (AGENT_DIRS.some(base => isUnder(p, base))) return 'agentExtras';
+    return 'systemLayer';
+}
+
+// 要 cp 的容器内顶层路径（cp 整棵子树，再按 diff 与分类过滤）。enabled：启用的内容项 id 集合
+function layerScopes(enabled, diffPaths) {
+    const has = id => enabled.has(id);
+    const scopes = new Set();
+    if (has('agentExtras')) {
+        AGENT_DIRS.forEach(dir => scopes.add(dir));
+        scopes.add(`${AGENT_HOME}/.claude.json`);
+    } else if (has('agentSessions')) {
+        [`${AGENT_HOME}/.claude/projects`, `${AGENT_HOME}/.claude.json`, `${AGENT_HOME}/.codex`, `${AGENT_HOME}/.gemini/tmp`, `${AGENT_HOME}/.local/share/opencode`]
+            .forEach(dir => scopes.add(dir));
+    }
+    if (has('systemLayer')) {
+        for (const raw of diffPaths) {
+            const p = normalizeContainerPath(raw);
+            if (!p || classifyLayerPath(p) !== 'systemLayer') continue;
+            const parts = p.split('/').filter(Boolean);
+            scopes.add(`/${parts.slice(0, Math.min(parts.length, 2)).join('/')}`);
+        }
+    }
+    // 去掉被别的范围包含的
+    const list = [...scopes].sort();
+    return list.filter(scope => !list.some(other => other !== scope && isUnder(scope, other)));
+}
+
+// 解析 `diff` 输出：每行 `A|C|D <绝对路径>`
+function parseDiff(output) {
+    const added = new Map();
+    const deleted = [];
+    for (const line of String(output || '').split('\n')) {
+        const match = /^([ACD])\s+(\/.*)$/.exec(line.trim());
+        if (!match) continue;
+        const p = normalizeContainerPath(match[2]);
+        if (!p) continue;
+        if (match[1] === 'D') deleted.push(p);
+        else added.set(p, match[1]);
+    }
+    return { added, deleted };
+}
+
+// 各 Agent 在容器里保存登录凭据的文件：不带密钥导出时必须跳过
+const CREDENTIAL_FILES = [
+    `${AGENT_HOME}/.claude/.credentials.json`,
+    `${AGENT_HOME}/.codex/auth.json`,
+    `${AGENT_HOME}/.gemini/oauth_creds.json`,
+    `${AGENT_HOME}/.gemini/google_accounts.json`,
+    `${AGENT_HOME}/.local/share/opencode/auth.json`,
+    `${AGENT_HOME}/.config/opencode/auth.json`
+];
+const isCredentialFile = p => CREDENTIAL_FILES.includes(p);
+
+// 命令 / 脚本文本里写死的 `NAME=值`（名字含密钥词）：值清空
+function redactCommandText(text) {
+    return String(text || '').replace(/([A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|AUTH|CREDENTIAL)[A-Za-z0-9_]*=)(?:"[^"]*"|'[^']*'|[^\s"';&|]+)/gi, '$1');
+}
+
+// 密钥变量：名字含这些词的值
+const SECRET_NAME_PATTERN = /(KEY|TOKEN|SECRET|PASSWORD|AUTH|CREDENTIAL)/i;
+const isSecretName = name => SECRET_NAME_PATTERN.test(String(name || ''));
+
+module.exports = {
+    FORMAT,
+    AGENT_HOME,
+    ITEMS,
+    TIERS,
+    EXCLUDED_PREFIXES,
+    AGENT_SESSION_PATHS,
+    AGENT_DIRS,
+    itemsForTier,
+    matchTier,
+    normalizeItems,
+    normalizeContainerPath,
+    isExcludedPath,
+    isUnder,
+    isAgentSessionPath,
+    classifyLayerPath,
+    layerScopes,
+    parseDiff,
+    isSecretName,
+    isCredentialFile,
+    redactCommandText,
+    CREDENTIAL_FILES
+};

package/lib/archive/risks.js

@@ -0,0 +1,121 @@
+'use strict';
+
+// 归档里的创建参数（runtimeSnapshot）来自别人时，哪些设置会让导入后的容器拥有更大的权限，
+// 以及用户没有逐项确认时怎么处理。导出端把摘要写进清单，导入端据此让用户确认，并在建容器前过滤。
+
+const path = require('path');
+const { normalizePolicy, isUnrestricted } = require('../network-policy');
+
+const RISKY_MODES = new Set(['sock', 'dind']);
+
+function asArray(value) {
+    return Array.isArray(value) ? value.filter(item => typeof item === 'string') : [];
+}
+
+function volumeSource(volume) {
+    const first = String(volume).split(':')[0];
+    return first.startsWith('/') || first.startsWith('~') ? first : '';
+}
+
+// 需要确认的网络设置：任何“自定义”策略（里面可能放行内网 / 元数据地址，或干脆不限制），策略读不懂时也算（宁可多问一次）
+function isNetworkOpen(network) {
+    if (!network || typeof network !== 'object') return false;
+    try {
+        const policy = normalizePolicy(network);
+        return policy.preset === 'custom' || isUnrestricted(policy);
+    } catch (error) {
+        return true;
+    }
+}
+
+// 默认只信任 manyoyo 自己的镜像名：归档里写别的镜像名会让导入后的容器拉取并运行别人指定的镜像（带着工作目录）
+const TRUSTED_IMAGE_NAMES = ['ghcr.io/xcanwin/manyoyo', 'localhost/xcanwin/manyoyo'];
+
+/**
+ * 摘要：{ containerMode, volumes, ports, autostart, networkOpen }
+ * autostartText：状态目录里的自启动脚本（快照里的 autostart 为空时用它）。
+ */
+function summarizeRisks(snapshot, autostartText = '') {
+    const snap = snapshot && typeof snapshot === 'object' ? snapshot : {};
+    const autostart = String(snap.autostart || autostartText || '').trim();
+    return {
+        containerMode: RISKY_MODES.has(snap.containerMode) ? snap.containerMode : '',
+        volumes: asArray(snap.volumes),
+        ports: asArray(snap.ports),
+        autostart: autostart.length > 0,
+        envFiles: asArray(snap.envFile),
+        networkOpen: isNetworkOpen(snap.network)
+    };
+}
+
+/**
+ * 按用户确认过滤快照，得到可交给 buildCreateRuntime 的 createOptions。
+ * confirm：{ containerMode, volumes: [字符串], ports: bool, autostart: bool, envFiles: [路径], networkOpen: bool }
+ * options：{ hostPath, imageMode, pathExists(p), trustedImages? }
+ * 返回 { createOptions, dropped: [说明] }。first 永远不带；containerPath 保持原样（续接依赖它）。
+ */
+function buildImportCreateOptions(snapshot, confirm, options) {
+    const snap = snapshot && typeof snapshot === 'object' ? snapshot : {};
+    const ok = confirm && typeof confirm === 'object' ? confirm : {};
+    const pathExists = options.pathExists || (() => false);
+    const dropped = [];
+    const createOptions = {
+        hostPath: options.hostPath,
+        containerPath: typeof snap.containerPath === 'string' ? snap.containerPath : '',
+        shellPrefix: snap.shellPrefix || '',
+        shell: snap.shell || '',
+        shellSuffix: snap.shellSuffix || '',
+        agentPromptCommand: snap.agentPromptCommand || '',
+        yolo: snap.yolo || '',
+        env: snap.env && typeof snap.env === 'object' && !Array.isArray(snap.env) ? snap.env : {},
+        systemPrompt: snap.systemPrompt || undefined
+    };
+    if (options.imageMode !== 'default') {
+        const trusted = [...TRUSTED_IMAGE_NAMES, ...asArray(options.trustedImages)];
+        if (snap.imageName && !trusted.includes(String(snap.imageName))) {
+            dropped.push(`镜像 ${String(snap.imageName).slice(0, 80)} 不是 manyoyo 的镜像，改用本机默认镜像`);
+        } else {
+            createOptions.imageName = snap.imageName || '';
+            createOptions.imageVersion = snap.imageVersion || '';
+        }
+    }
+    if (RISKY_MODES.has(snap.containerMode)) {
+        if (ok.containerMode === snap.containerMode) createOptions.containerMode = snap.containerMode;
+        else dropped.push(`容器模式 ${snap.containerMode} 未确认，改用普通模式`);
+    } else {
+        createOptions.containerMode = snap.containerMode || '';
+    }
+    const confirmedVolumes = new Set(asArray(ok.volumes));
+    createOptions.volumes = asArray(snap.volumes).filter(volume => {
+        if (!confirmedVolumes.has(volume)) { dropped.push(`挂载 ${volume} 未确认`); return false; }
+        const source = volumeSource(volume);
+        if (source && !pathExists(source.startsWith('~') ? path.join(process.env.HOME || '', source.slice(1)) : source)) {
+            dropped.push(`挂载 ${volume} 的宿主机路径在本机不存在`);
+            return false;
+        }
+        return true;
+    });
+    createOptions.ports = ok.ports === true ? asArray(snap.ports) : [];
+    if (!createOptions.ports.length && asArray(snap.ports).length) dropped.push('端口映射未确认');
+    createOptions.autostart = ok.autostart === true ? String(snap.autostart || '') : '';
+    if (snap.autostart && ok.autostart !== true) dropped.push('自启动脚本未确认');
+    // 环境变量文件里的内容会进容器环境：宿主机上的任意绝对路径，必须逐个确认
+    const confirmedEnvFiles = new Set(asArray(ok.envFiles));
+    createOptions.envFile = asArray(snap.envFile).filter(file => {
+        if (!path.isAbsolute(file) || !pathExists(file)) return false;
+        if (!confirmedEnvFiles.has(file)) { dropped.push(`环境变量文件 ${file} 未确认`); return false; }
+        return true;
+    });
+    if (snap.network && typeof snap.network === 'object') {
+        if (isNetworkOpen(snap.network) && ok.networkOpen !== true) {
+            dropped.push('自定义网络规则未确认，改用默认的受限网络');
+        } else {
+            createOptions.network = snap.network;
+            // 用户确认过“自定义”才跳过后面的风险检查；其它策略仍要过 buildCreateRuntime 里的宽规则检查
+            if (ok.networkOpen === true) createOptions.confirmRisk = true;
+        }
+    }
+    return { createOptions, dropped };
+}
+
+module.exports = { summarizeRisks, buildImportCreateOptions, isNetworkOpen, RISKY_MODES, TRUSTED_IMAGE_NAMES };

package/lib/archive/runtime.js

@@ -0,0 +1,72 @@
+'use strict';
+
+// 导出 / 导入用的容器运行时封装（docker / podman 命令行）。
+// 导出导入的核心逻辑只依赖这里的接口，测试里用假实现替换。
+
+const { spawn, spawnSync } = require('child_process');
+
+function createCliRuntime({ command, env }) {
+    const sync = (args, options = {}) => spawnSync(command, args, { env: env || process.env, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, ...options });
+    const must = (args, what) => {
+        const result = sync(args);
+        if (result.status !== 0) throw new Error(`${what}失败: ${String(result.stderr || '').trim().slice(0, 300)}`);
+        return result.stdout;
+    };
+
+    return {
+        // 容器信息；容器不存在返回 null
+        inspect(name) {
+            const result = sync(['inspect', '--format', '{{json .}}', name]);
+            if (result.status !== 0) return null;
+            let data;
+            try {
+                data = JSON.parse(result.stdout.split('\n')[0]);
+            } catch (error) {
+                return null;
+            }
+            const labels = (data.Config && data.Config.Labels) || {};
+            return {
+                id: labels['manyoyo.id'] || '',
+                image: (data.Config && data.Config.Image) || '',
+                status: data.State && data.State.Paused ? 'paused' : (data.State && data.State.Running ? 'running' : 'stopped'),
+                mounts: (data.Mounts || []).map(item => item.Destination).filter(Boolean),
+                defaultCmd: labels['manyoyo.default_cmd'] || ''
+            };
+        },
+        pause(name) {
+            must(['pause', name], '暂停容器');
+        },
+        unpause(name) {
+            must(['unpause', name], '恢复容器');
+        },
+        // 暂停不可用时的退路：停止 / 启动（启动会重新跑自启动脚本）
+        stop(name) {
+            must(['stop', '-t', '10', name], '停止容器');
+        },
+        start(name) {
+            must(['start', name], '启动容器');
+        },
+        diff(name) {
+            return must(['diff', name], '读取容器改动');
+        },
+        // 返回 { stream, done }：stream 是 tar 输出；done 在进程结束后给出 { code, stderr }
+        cp(name, containerPath) {
+            const child = spawn(command, ['cp', `${name}:${containerPath}`, '-'], { env: env || process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+            let stderr = '';
+            child.stderr.on('data', chunk => { if (stderr.length < 4096) stderr += chunk; });
+            const done = new Promise(resolve => child.on('close', code => resolve({ code, stderr })));
+            child.on('error', error => child.stdout.destroy(error));
+            return { stream: child.stdout, done, kill: () => child.kill('SIGKILL') };
+        },
+        // 把 tar 流写进容器：返回 { stdin, done }
+        cpIn(name, containerPath) {
+            const child = spawn(command, ['cp', '-', `${name}:${containerPath}`], { env: env || process.env, stdio: ['pipe', 'ignore', 'pipe'] });
+            let stderr = '';
+            child.stderr.on('data', chunk => { if (stderr.length < 4096) stderr += chunk; });
+            const done = new Promise(resolve => child.on('close', code => resolve({ code, stderr })));
+            return { stdin: child.stdin, done, kill: () => child.kill('SIGKILL') };
+        }
+    };
+}
+
+module.exports = { createCliRuntime };

package/lib/archive/safe-extract.js

@@ -0,0 +1,163 @@
+'use strict';
+
+// 宿主机侧解包的安全规则（导入的归档可能来自别人）：
+// - 拒绝绝对路径、`..`、空段、NUL、硬链接、设备等特殊文件；
+// - 写文件前逐级 lstat：父目录必须是本次新建的真实目录（不是符号链接），目标不能是已存在的符号链接；
+// - 去掉 setuid / setgid / sticky；
+// - 符号链接不在解包时创建：先记下来，最后只在“相对路径且解析后仍在根目录内”时创建，其余跳过并计数。
+
+const fs = require('fs');
+const path = require('path');
+const { pipeline } = require('stream/promises');
+const { Readable } = require('stream');
+
+class UnsafeEntryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsafeEntryError';
+    }
+}
+
+// 归档里的相对路径 → 段数组；不合规直接抛错
+function splitEntryPath(name) {
+    if (typeof name !== 'string' || name.length === 0) throw new UnsafeEntryError('条目名为空');
+    if (name.includes('\0')) throw new UnsafeEntryError('条目名含 NUL');
+    if (name.includes('\\')) throw new UnsafeEntryError(`条目名含反斜杠: ${name}`);
+    if (name.startsWith('/')) throw new UnsafeEntryError(`条目名是绝对路径: ${name}`);
+    const segments = name.split('/');
+    if (segments[segments.length - 1] === '') segments.pop();
+    if (!segments.length) throw new UnsafeEntryError('条目名为空');
+    for (const segment of segments) {
+        if (segment === '' ) throw new UnsafeEntryError(`条目名含空段: ${name}`);
+        if (segment === '.' || segment === '..') throw new UnsafeEntryError(`条目名含 ${segment}: ${name}`);
+    }
+    return segments;
+}
+
+function safeMode(mode, isDir) {
+    // 只留 rwx 九位，去掉 setuid / setgid / sticky；目录至少本人可进入可写（解包过程需要）
+    const base = (Number(mode) || 0) & 0o777;
+    return isDir ? (base | 0o700) : (base || 0o600);
+}
+
+class SafeExtractor {
+    /**
+     * root：本次导入的临时目录（调用方新建，已存在）。
+     * limits：{ maxFiles, maxBytes }，防止无限膨胀。
+     */
+    constructor(root, limits = {}) {
+        this.root = fs.realpathSync(root);
+        this.created = new Set([this.root]);
+        this.deferredLinks = [];
+        this.skippedLinks = 0;
+        this.skippedSpecial = 0;
+        this.files = 0;
+        this.bytes = 0;
+        this.maxFiles = limits.maxFiles || 5_000_000;
+        this.maxBytes = limits.maxBytes || Infinity;
+    }
+
+    // 逐级确认父目录是“本次新建的真实目录”；缺的就建
+    ensureDir(segments) {
+        let current = this.root;
+        for (const segment of segments) {
+            const next = path.join(current, segment);
+            let stat = null;
+            try {
+                stat = fs.lstatSync(next);
+            } catch (error) {
+                if (error.code !== 'ENOENT') throw error;
+            }
+            if (stat === null) {
+                fs.mkdirSync(next, { mode: 0o700 });
+                this.created.add(next);
+            } else if (!stat.isDirectory() || stat.isSymbolicLink()) {
+                throw new UnsafeEntryError(`父路径不是目录: ${next}`);
+            } else if (!this.created.has(next)) {
+                throw new UnsafeEntryError(`父目录不是本次导入新建的: ${next}`);
+            }
+            current = next;
+        }
+        return current;
+    }
+
+    addDir(name, mode) {
+        const segments = splitEntryPath(name);
+        const dir = this.ensureDir(segments);
+        try { fs.chmodSync(dir, safeMode(mode, true)); } catch (error) { /* 尽力而为 */ }
+    }
+
+    // body：异步可迭代的字节流
+    async addFile(name, mode, body, expectedSize) {
+        const segments = splitEntryPath(name);
+        this.files += 1;
+        if (this.files > this.maxFiles) throw new UnsafeEntryError('条目数量超过上限');
+        if (this.bytes + expectedSize > this.maxBytes) throw new UnsafeEntryError('解包大小超过上限');
+        const parent = this.ensureDir(segments.slice(0, -1));
+        const target = path.join(parent, segments[segments.length - 1]);
+        let flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0);
+        const fd = fs.openSync(target, flags, safeMode(mode, false));
+        try {
+            const stream = fs.createWriteStream(null, { fd, autoClose: false });
+            const counted = Readable.from((async function* count(self) {
+                for await (const chunk of body) {
+                    self.bytes += chunk.length;
+                    if (self.bytes > self.maxBytes) throw new UnsafeEntryError('解包大小超过上限');
+                    yield chunk;
+                }
+            })(this));
+            await pipeline(counted, stream);
+        } finally {
+            fs.closeSync(fd);
+        }
+        return target;
+    }
+
+    // 符号链接：先记下，最后统一处理
+    addSymlink(name, linkname) {
+        const segments = splitEntryPath(name);
+        this.deferredLinks.push({ segments, linkname: String(linkname || '') });
+    }
+
+    skipSpecial() {
+        this.skippedSpecial += 1;
+    }
+
+    // 所有文件落地后调用：只创建“相对路径且解析后仍在 root 内”的链接
+    finalizeSymlinks() {
+        let made = 0;
+        for (const { segments, linkname } of this.deferredLinks) {
+            const verdict = this.checkLink(segments, linkname);
+            if (!verdict) {
+                this.skippedLinks += 1;
+                continue;
+            }
+            try {
+                const parent = this.ensureDir(segments.slice(0, -1));
+                const target = path.join(parent, segments[segments.length - 1]);
+                try {
+                    fs.lstatSync(target);
+                    this.skippedLinks += 1;
+                    continue;
+                } catch (error) {
+                    if (error.code !== 'ENOENT') throw error;
+                }
+                fs.symlinkSync(linkname, target);
+                made += 1;
+            } catch (error) {
+                this.skippedLinks += 1;
+            }
+        }
+        this.deferredLinks = [];
+        return made;
+    }
+
+    checkLink(segments, linkname) {
+        if (!linkname || linkname.includes('\0') || path.isAbsolute(linkname)) return false;
+        const dirOfLink = path.join(this.root, ...segments.slice(0, -1));
+        const resolved = path.resolve(dirOfLink, linkname);
+        return resolved === this.root || resolved.startsWith(`${this.root}${path.sep}`);
+    }
+}
+
+module.exports = { SafeExtractor, UnsafeEntryError, splitEntryPath, safeMode };