@logictan/dsh-config-manager 0.1.60

package/lib/utils/proxy.js

@@ -0,0 +1,455 @@
+/**
+ * 插件私有出站代理（issue #30）。
+ *
+ * 背景：Node 内置 `fetch()`（undici）**默认不读** `HTTP_PROXY` / `HTTPS_PROXY`，因此「必须经代理
+ * 访问 GitHub」的网络下，GitHub 登录（device flow）与市场 API 全部失败（`fetch failed`），
+ * 而浏览器与 git 都正常。全局开关（`NODE_USE_ENV_PROXY` / `http.setGlobalProxyFromEnv()`）虽然
+ * 有效，但那是**进程级**的：它会连带改变宿主自身（含模型 API）的出站行为 —— 一个备份插件不该
+ * 有这种越界副作用（且该 API 需 Node ≥ 24.14，覆盖不全）。
+ *
+ * 本模块只服务本插件自己的出站请求，**不改动任何全局状态**，且**零第三方依赖**：
+ *  - `http:` 目标经 HTTP 代理 → 使用 absolute-form 请求（`GET http://host/path HTTP/1.1`）；
+ *  - `https:` 目标经 HTTP 代理 → 自行完成 `CONNECT` 隧道，再在该 socket 上叠加 TLS（SNI 保留）；
+ *  - 命中 `NO_PROXY` 或未配置代理 → 完全直连，行为与未启用前一致。
+ *
+ * 与全局开关的分工：插件侧默认直连（不改变现状）；仅当检测到代理环境变量时才启用代理路由。
+ * 如需在已配置代理的环境下刻意直连，设置 `DSH_CONFIG_MANAGER_PROXY=off`。
+ *
+ * 安​全：代理 URL 的 userinfo（账号/密码）只用于 `Proxy-Authorization` 头，绝不进日志；
+ * `describeProxy()` 输出的代理描述已剥离凭据；跨源重定向剥离 `authorization`（GitHub token
+ * 绝不转发给第三方域名）。
+ */
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import tls from 'node:tls';
+/** 环境变量开关：`DSH_CONFIG_MANAGER_PROXY=off|none|0` 时即使配了代理也强制直连（调试/特殊情况）。 */
+const PROXY_OFF_VALUES = new Set(['off', 'none', '0', 'false', 'disable', 'disabled']);
+/** 隧道建立与单次请求的默认上限（避免代理不可达时无限挂起）。 */
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+/** 视为可跟随的重定向状态码（与 WebDAV 通道同一套语义） */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** 不能带响应体的状态码（`new Response(body, {status})` 会抛错） */
+const BODYLESS_STATUSES = new Set([101, 204, 205, 304]);
+/** 取第一个非空值（环境变量大小写与平台差异的归一） */
+function firstNonEmpty(...values) {
+    for (const v of values) {
+        if (typeof v === 'string' && v.trim() !== '')
+            return v.trim();
+    }
+    return null;
+}
+/** 读代理环境变量（纯函数，便于测试注​入任意 env） */
+export function readProxyEnv(env = process.env) {
+    const off = firstNonEmpty(env['DSH_CONFIG_MANAGER_PROXY']);
+    if (off !== null && PROXY_OFF_VALUES.has(off.toLowerCase())) {
+        return { httpProxy: null, httpsProxy: null, noProxy: null };
+    }
+    return {
+        httpProxy: firstNonEmpty(env['HTTP_PROXY'], env['http_proxy']),
+        httpsProxy: firstNonEmpty(env['HTTPS_PROXY'], env['https_proxy']),
+        noProxy: firstNonEmpty(env['NO_PROXY'], env['no_proxy']),
+    };
+}
+/** 是否配置了任何代理（用于启动日志与「是否需要走代理链路」的判定） */
+export function isProxyConfigured(env = readProxyEnv()) {
+    return env.httpProxy !== null || env.httpsProxy !== null;
+}
+/** `host[:port]` 切分（兼容 IPv6 方括号形态）；无端口 → null */
+function splitHostPort(entry) {
+    if (entry.startsWith('[')) {
+        const end = entry.indexOf(']');
+        if (end !== -1) {
+            const host = entry.slice(0, end + 1);
+            const rest = entry.slice(end + 1);
+            return rest.startsWith(':') ? { host, port: rest.slice(1) } : { host, port: null };
+        }
+        return { host: entry, port: null };
+    }
+    const at = entry.lastIndexOf(':');
+    // 仅当冒号后全是数字才视作端口（避免把裸 IPv6 误切）
+    if (at !== -1 && /^\d+$/.test(entry.slice(at + 1))) {
+        return { host: entry.slice(0, at), port: entry.slice(at + 1) };
+    }
+    return { host: entry, port: null };
+}
+/**
+ * 目标是否命中 `NO_PROXY`。
+ * 支持：`*`（全直连）、精确主机、`.example.com` 与 `example.com`（含子域）、可选 `:port` 限定。
+ */
+export function matchesNoProxy(host, port, noProxy) {
+    if (noProxy === null)
+        return false;
+    const target = host.toLowerCase();
+    for (const raw of noProxy.split(',')) {
+        const entry = raw.trim().toLowerCase();
+        if (entry === '')
+            continue;
+        if (entry === '*')
+            return true;
+        const { host: entryHost, port: entryPort } = splitHostPort(entry);
+        if (entryPort !== null && entryPort !== port)
+            continue;
+        const bare = entryHost.startsWith('.') ? entryHost.slice(1) : entryHost;
+        if (bare === '')
+            continue;
+        if (target === bare || target.endsWith(`.${bare}`))
+            return true;
+    }
+    return false;
+}
+/** URL 的有效端口（缺省按协议补） */
+function effectivePort(url) {
+    if (url.port !== '')
+        return url.port;
+    return url.protocol === 'https:' ? '443' : '80';
+}
+/**
+ * 该目标应使用的代理 URL；无需代理（未配置 / 命中 NO_PROXY / 非法）→ null。
+ *
+ * 选择规则（对齐 undici `EnvHttpProxyAgent` 的直觉语义）：
+ *  - `https:` 目标 → `HTTPS_PROXY`，缺省回退 `HTTP_PROXY`；
+ *  - `http:` 目标 → `HTTP_PROXY`，缺省回退 `HTTPS_PROXY`。
+ */
+export function proxyUrlFor(target, env = readProxyEnv()) {
+    let url;
+    try {
+        url = typeof target === 'string' ? new URL(target) : target;
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    if (matchesNoProxy(url.hostname, effectivePort(url), env.noProxy))
+        return null;
+    const candidate = url.protocol === 'https:'
+        ? (env.httpsProxy ?? env.httpProxy)
+        : (env.httpProxy ?? env.httpsProxy);
+    if (candidate === null)
+        return null;
+    try {
+        const proxy = new URL(candidate.includes('://') ? candidate : `http://${candidate}`);
+        if (proxy.hostname === '')
+            return null;
+        if (proxy.protocol !== 'http:' && proxy.protocol !== 'https:')
+            return null;
+        return proxy.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/** 代理的**脱敏**描述（供日志/报错提示；凭据一律剥离，绝不外泄） */
+export function describeProxy(proxyUrl) {
+    try {
+        const u = new URL(proxyUrl);
+        return `${u.protocol}//${u.hostname}${u.port !== '' ? `:${u.port}` : ''}`;
+    }
+    catch {
+        return '(invalid proxy)';
+    }
+}
+/** 一次性 socket 的 agent（隧道已建立；keepAlive 关闭，用完即毁） */
+class TunnelAgent extends https.Agent {
+    tunnel;
+    constructor(tunnel) {
+        super({ keepAlive: false, maxSockets: 1 });
+        this.tunnel = tunnel;
+    }
+    createConnection() {
+        return this.tunnel;
+    }
+}
+/** 建立到代理的连接（代理本身可能是 https） */
+function connectToProxy(proxy, timeoutMs) {
+    const port = Number(proxy.port !== '' ? proxy.port : (proxy.protocol === 'https:' ? 443 : 80));
+    return new Promise((resolve, reject) => {
+        const onConnect = () => { socket.setTimeout(0); resolve(socket); };
+        const socket = proxy.protocol === 'https:'
+            ? tls.connect({ host: proxy.hostname, port, servername: proxy.hostname }, onConnect)
+            : net.connect({ host: proxy.hostname, port }, onConnect);
+        socket.setTimeout(timeoutMs, () => {
+            socket.destroy();
+            reject(new Error(`代理连接超时 / proxy connect timed out (${timeoutMs}ms)`));
+        });
+        socket.once('error', (err) => { reject(err); });
+    });
+}
+/**
+ * 经 HTTP 代理建立到目标的隧道（`CONNECT host:port`）。
+ * 返回的 socket 已与目标建立字节通道；https 目标再由调用方叠加 TLS。
+ */
+async function openTunnel(target, proxy, timeoutMs) {
+    const socket = await connectToProxy(proxy, timeoutMs);
+    const targetPort = effectivePort(target);
+    const authority = `${target.hostname}:${targetPort}`;
+    const lines = [
+        `CONNECT ${authority} HTTP/1.1`,
+        `Host: ${authority}`,
+        // 代理凭据只在此处使用，绝不写日志
+        ...(proxy.username !== '' || proxy.password !== ''
+            ? [`Proxy-Authorization: Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString('base64')}`]
+            : []),
+        'Proxy-Connection: keep-alive',
+        '',
+        '',
+    ];
+    return await new Promise((resolve, reject) => {
+        let buffered = '';
+        const fail = (message) => {
+            socket.destroy();
+            reject(new Error(message));
+        };
+        const onData = (chunk) => {
+            buffered += chunk.toString('latin1');
+            const end = buffered.indexOf('\r\n\r\n');
+            if (end === -1) {
+                if (buffered.length > 8192) {
+                    socket.off('data', onData);
+                    fail('代理 CONNECT 响应异常（头部过长）/ malformed CONNECT response');
+                }
+                return;
+            }
+            socket.off('data', onData);
+            const head = buffered.slice(0, end);
+            const status = Number((head.split('\r\n')[0] ?? '').split(' ')[1]);
+            if (status !== 200) {
+                fail(`代理拒绝 CONNECT（HTTP ${status}）/ proxy refused CONNECT`);
+                return;
+            }
+            // CONNECT 响应头之后的字节已属隧道数据 → 回填，避免 TLS 握手丢包
+            const rest = Buffer.from(buffered.slice(end + 4), 'latin1');
+            if (rest.length > 0)
+                socket.unshift(rest);
+            resolve(socket);
+        };
+        socket.on('data', onData);
+        socket.once('error', (err) => { socket.off('data', onData); reject(err); });
+        socket.once('close', () => { socket.off('data', onData); reject(new Error('代理连接在 CONNECT 完成前关闭 / proxy closed during CONNECT')); });
+        socket.write(lines.join('\r\n'));
+    });
+}
+/** 请求结果归一到 node 的 IncomingMessage（直连与经代理两条路径共用收尾逻辑） */
+function collectResponse(res, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on('end', () => {
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(res.headers)) {
+                if (value === undefined)
+                    continue;
+                if (Array.isArray(value))
+                    for (const v of value)
+                        headers.append(key, v);
+                else
+                    headers.set(key, String(value));
+            }
+            resolve({
+                status: res.statusCode ?? 0,
+                statusText: res.statusMessage ?? '',
+                headers,
+                body: Buffer.concat(chunks),
+            });
+        });
+        res.on('error', reject);
+        if (timeoutMs > 0) {
+            res.setTimeout(timeoutMs, () => {
+                res.destroy();
+                reject(new Error(`Request timed out after ${timeoutMs}ms`));
+            });
+        }
+    });
+}
+/**
+ * 发起一次 HTTP/1.1 请求（自动：直连 / 经代理 absolute-form / 经代理 CONNECT 隧道）。
+ * 不跟随重定向（跟随策略由调用方决定：WebDAV 保方法语义，fetch 按浏览器语义）。
+ */
+export async function requestOnce(options) {
+    const target = new URL(options.url);
+    const env = options.env ?? readProxyEnv();
+    const proxyUrl = proxyUrlFor(target, env);
+    const method = (options.method ?? 'GET').toUpperCase();
+    const timeoutMs = options.timeoutMs ?? 0;
+    const payload = options.body === undefined
+        ? undefined
+        : Buffer.isBuffer(options.body) ? options.body : Buffer.from(options.body, 'utf8');
+    const headers = {
+        ...(payload !== undefined ? { 'content-length': String(payload.length) } : {}),
+        ...(options.headers ?? {}),
+    };
+    /** url 非 null → 以 URL 形态发起（node 自行解析 host/port/path/TLS）；否则按显式 options 发起。 */
+    const send = (lib, url, requestOptions) => new Promise((resolve, reject) => {
+        const onResponse = (res) => {
+            collectResponse(res, timeoutMs).then(resolve, reject);
+        };
+        const req = url === null
+            ? lib.request(requestOptions, onResponse)
+            : lib.request(url, requestOptions, onResponse);
+        if (timeoutMs > 0) {
+            req.setTimeout(timeoutMs, () => {
+                req.destroy();
+                reject(new Error(`Request timed out after ${timeoutMs}ms`));
+            });
+        }
+        req.on('error', reject);
+        if (options.signal !== undefined) {
+            const onAbort = () => { req.destroy(new Error('The operation was aborted.')); };
+            if (options.signal.aborted)
+                onAbort();
+            else
+                options.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        if (payload !== undefined)
+            req.write(payload);
+        req.end();
+    });
+    // ---- 未经代理：直连（默认路径，行为与此前一致）----
+    if (proxyUrl === null) {
+        const lib = target.protocol === 'https:' ? https : http;
+        return await send(lib, options.url, { method, headers });
+    }
+    const proxy = new URL(proxyUrl);
+    // ---- http 目标经代理：absolute-form 直接把完整 URL 交给代理 ----
+    if (target.protocol === 'http:') {
+        const port = Number(proxy.port !== '' ? proxy.port : (proxy.protocol === 'https:' ? 443 : 80));
+        const lib = proxy.protocol === 'https:' ? https : http;
+        return await send(lib, null, {
+            method,
+            host: proxy.hostname,
+            port,
+            path: target.toString(),
+            headers: {
+                ...headers,
+                host: target.host,
+                ...(proxy.username !== '' || proxy.password !== ''
+                    ? { 'proxy-authorization': `Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString('base64')}` }
+                    : {}),
+            },
+        });
+    }
+    // ---- https 目标经代理：CONNECT 隧道 + TLS（SNI 保留目标主机名）----
+    const tunnel = await openTunnel(target, proxy, timeoutMs > 0 ? timeoutMs : DEFAULT_CONNECT_TIMEOUT_MS);
+    const secure = tls.connect({
+        socket: tunnel,
+        servername: target.hostname,
+        // 与直连一致：默认校验证书链；不做任何降级
+    });
+    await new Promise((resolve, reject) => {
+        secure.once('secureConnect', () => { resolve(); });
+        secure.once('error', reject);
+    });
+    return await send(https, null, {
+        method,
+        headers,
+        host: target.hostname,
+        port: Number(effectivePort(target)),
+        path: `${target.pathname}${target.search}`,
+        agent: new TunnelAgent(secure),
+    });
+}
+/** 把 `HeadersInit` 归一为小写键的普通对象 */
+function normalizeHeaders(init) {
+    const out = {};
+    if (init === undefined)
+        return out;
+    if (init instanceof Headers) {
+        init.forEach((value, key) => { out[key.toLowerCase()] = value; });
+        return out;
+    }
+    if (Array.isArray(init)) {
+        for (const [key, value] of init)
+            out[String(key).toLowerCase()] = String(value);
+        return out;
+    }
+    for (const [key, value] of Object.entries(init)) {
+        if (value !== undefined)
+            out[key.toLowerCase()] = String(value);
+    }
+    return out;
+}
+/** 同源判断（协议 + host，含端口） */
+function sameOrigin(a, b) {
+    try {
+        const ua = new URL(a);
+        const ub = new URL(b);
+        return ua.protocol === ub.protocol && ua.host === ub.host;
+    }
+    catch {
+        return false;
+    }
+}
+/** 重定向上限（与 WebDAV 通道一致） */
+const MAX_REDIRECTS = 5;
+/**
+ * 代理感知的 fetch 兼容实现（仅插件自身使用；替代 `globalThis.fetch` 的默认值）。
+ *
+ * 与浏览器 fetch 的关键语义对齐：自动跟随 301/302/303/307/308（上限 5 跳）；303 且非 GET/HEAD
+ * 降级为 GET 并丢弃请求体；**跨源跳转剥离 `authorization`**（token 不转发给第三方域名）；
+ * 无响应体状态（204/304 等）不构造 body。
+ */
+export function createProxyAwareFetch(env = readProxyEnv()) {
+    const impl = async (input, init) => {
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL ? input.toString() : input.url;
+        let currentUrl = url;
+        let method = (init?.method ?? 'GET').toUpperCase();
+        let headers = normalizeHeaders(init?.headers);
+        let body = init?.body === undefined || init?.body === null
+            ? undefined
+            : String(init.body);
+        for (let hop = 0;; hop += 1) {
+            const res = await requestOnce({
+                method,
+                url: currentUrl,
+                headers,
+                ...(body !== undefined ? { body } : {}),
+                ...(init?.signal != null ? { signal: init.signal } : {}),
+                env,
+            });
+            const location = res.headers.get('location');
+            if (!REDIRECT_STATUSES.has(res.status) || location === null) {
+                return new Response(BODYLESS_STATUSES.has(res.status) ? null : new Uint8Array(res.body), { status: res.status, statusText: res.statusText, headers: res.headers });
+            }
+            if (hop >= MAX_REDIRECTS) {
+                throw new TypeError(`fetch failed: too many redirects (${MAX_REDIRECTS} max)`);
+            }
+            let nextUrl;
+            try {
+                nextUrl = new URL(location, currentUrl).toString();
+            }
+            catch {
+                return new Response(BODYLESS_STATUSES.has(res.status) ? null : new Uint8Array(res.body), { status: res.status, statusText: res.statusText, headers: res.headers });
+            }
+            if (!sameOrigin(currentUrl, nextUrl))
+                delete headers['authorization'];
+            if (res.status === 303 && method !== 'GET' && method !== 'HEAD') {
+                method = 'GET';
+                body = undefined;
+                delete headers['content-length'];
+            }
+            currentUrl = nextUrl;
+        }
+    };
+    return impl;
+}
+/**
+ * 默认出站 fetcher：**未配置代理时原样返回全局 `fetch`**（保持既有行为零变化）；
+ * 配置了代理才切到代理感知实现。
+ */
+export function defaultFetcher(env = readProxyEnv()) {
+    return isProxyConfigured(env) ? createProxyAwareFetch(env) : globalThis.fetch;
+}
+/** 启动日志用：当前生效的代理描述（已脱敏），未启用 → null */
+export function activeProxySummary(env = readProxyEnv()) {
+    if (!isProxyConfigured(env))
+        return null;
+    return {
+        http: env.httpProxy !== null ? describeProxy(env.httpProxy) : null,
+        https: env.httpsProxy !== null ? describeProxy(env.httpsProxy) : null,
+        noProxyEntries: env.noProxy !== null ? env.noProxy.split(',').filter((s) => s.trim() !== '').length : 0,
+    };
+}
+//# sourceMappingURL=proxy.js.map

package/lib/utils/recursive-walk.d.ts

@@ -0,0 +1,24 @@
+/** 遍历中跳过的链接（备份必须能说明「哪些内容没进来」） */
+export interface SkippedLink {
+    /** homeDir 相对路径（链接本身，不是目标） */
+    path: string;
+    /** loop=指向已遍历目录（自引用/重复）；outside-home=目标越出 homeDir；
+     *  broken=断链；unreadable=目标既非文件也非目录（设备/FIFO 等）；too-deep=超过深度上限 */
+    reason: 'loop' | 'outside-home' | 'broken' | 'unreadable' | 'too-deep';
+}
+export interface RecursiveListing {
+    /** homeDir 相对、斜杠分隔、已排序的文件路径 */
+    paths: string[];
+    /** 被跳过的链接（含原因）；空 = 本次遍历无内容缺失 */
+    skippedLinks: SkippedLink[];
+    /** 成功跟随（内容已收集）的链接数；用于「链接结构不会被还原」的提示 */
+    followedLinks: number;
+    /** 读取失败的目录（ACL / 竞态删除等）——这些目录下的内容同样没进备份，必须留痕 */
+    unreadableDirs: string[];
+}
+/**
+ * 遍历 baseDir 下的所有文件（跟随目录链接）。
+ * @param baseDir 绝对路径；不在 homeDir 内则返回空清单（与既有语义一致）
+ * @param homeDir 绝对路径；产出相对它，跟随边界也是它
+ */
+export declare function listRecursiveFollowingLinks(baseDir: string, homeDir: string): Promise<RecursiveListing>;

package/lib/utils/recursive-walk.js

@@ -0,0 +1,134 @@
+/**
+ * 递归遍历（跟随 junction / 符号链接）—— 文件类分区（skills / agentPresets / sessions / pluginFiles）
+ * 的收集内核（issue #37）。
+ *
+ * 背景：`fs.readdir(withFileTypes)` 对 **目录 junction / 符号链接** 返回的是
+ * `isSymbolicLink() === true`、`isDirectory() === false`。此前调用方只处理
+ * `isDirectory() / isFile()` 两个分支，于是链接目录及其**全部真实内容**被静默排除，
+ * 备份照样报成功（issue #37：Windows 下 8 个链接目录约 12 MB 内容丢失，且无任何提示）。
+ *
+ * 本模块的语义：
+ *  - **跟随**目录链接（内容进备份），并用 realpath 去重防环（自引用 / 重复链接 / 深度爆炸）；
+ *  - 链接目标**越出 homeDir** 或**损坏**时跳过，但**记入 skippedLinks** —— 让「没进备份」
+ *    变成备份报告里可见的一行，而不是无声缺失；
+ *  - 产出与 `FileSystemFacade.listRecursive` 一致的 **homeDir 相对** 斜杠路径，且已排序。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** 深度上限：防御病态目录树 / realpath 去重失效时的栈爆炸 */
+const MAX_DEPTH = 64;
+function normalizeSlashes(p) {
+    return p.split(path.sep).join('/');
+}
+/** current 是否等于 base 或位于其下（win32 折叠大小写） */
+function isSameOrChild(current, base) {
+    const c = path.resolve(current);
+    const b = path.resolve(base);
+    const cl = process.platform === 'win32' ? c.toLowerCase() : c;
+    const bl = process.platform === 'win32' ? b.toLowerCase() : b;
+    return cl === bl || cl.startsWith(bl.endsWith(path.sep) ? bl : bl + path.sep);
+}
+async function realpathSafe(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 遍历 baseDir 下的所有文件（跟随目录链接）。
+ * @param baseDir 绝对路径；不在 homeDir 内则返回空清单（与既有语义一致）
+ * @param homeDir 绝对路径；产出相对它，跟随边界也是它
+ */
+export async function listRecursiveFollowingLinks(baseDir, homeDir) {
+    const base = path.resolve(baseDir);
+    const home = path.resolve(homeDir);
+    const paths = [];
+    const skippedLinks = [];
+    const unreadableDirs = [];
+    let followedLinks = 0;
+    /** 已进入过的目录 realpath（防环 / 防同一目标被两条链接重复收集） */
+    const visited = new Set();
+    const rel = (abs) => normalizeSlashes(path.relative(home, abs));
+    /** @returns 是否真的进入了该目录（false = 被边界/去重/IO 挡下） */
+    const walk = async (dir, depth, viaLink) => {
+        if (!isSameOrChild(dir, home))
+            return false;
+        if (depth > MAX_DEPTH) {
+            if (viaLink !== null)
+                skippedLinks.push({ path: viaLink, reason: 'too-deep' });
+            return false;
+        }
+        const real = await realpathSafe(dir);
+        // 去重只针对**链接**：链接目标已经进过（自引用 / 两条链接指向同一处）→ 跳过。
+        // 普通目录永远遍历（否则「真实目录 + 指向它的链接」会有一边被静默吞掉）。
+        if (viaLink !== null && real !== null && visited.has(real)) {
+            skippedLinks.push({ path: viaLink, reason: 'loop' });
+            return false;
+        }
+        if (real !== null)
+            visited.add(real);
+        let entries;
+        try {
+            // 排序：让「链接 vs 真实目录」的遍历顺序与去重结果可复现（readdir 顺序依 FS 而异）
+            entries = (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch (err) {
+            // 目录不可读（ACL / 竞态删除）：不中断整次遍历，但**必须留痕** ——
+            // 静默吞掉同样会造成「备份成功但内容缺失」（issue #37 的同类症状）。
+            // 根目录不存在（ENOENT）例外：调用方语义是「目录不存在视为空」，不告警。
+            if (viaLink !== null)
+                skippedLinks.push({ path: viaLink, reason: 'unreadable' });
+            else if (err?.code !== 'ENOENT')
+                unreadableDirs.push(rel(dir));
+            return false;
+        }
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            const entryRel = rel(abs);
+            if (entry.isDirectory()) {
+                await walk(abs, depth + 1, null);
+            }
+            else if (entry.isFile()) {
+                paths.push(entryRel);
+            }
+            else if (entry.isSymbolicLink()) {
+                // 目录 junction / 符号链接：跟随（issue #37 的核心修复）。
+                // 注意：Dirent 对链接一律 isDirectory()===false，必须显式 stat 目标才知道类型。
+                let st;
+                try {
+                    st = await fs.stat(abs); // 跟随链接
+                }
+                catch {
+                    skippedLinks.push({ path: entryRel, reason: 'broken' });
+                    continue;
+                }
+                // 链接目标必须落在 homeDir 内——**文件链接同样如此**。
+                // 只对目录链接做这个检查会漏掉「skills/link.md → ~/外部文件」：
+                // 内容会被读进备份（T2-P3 实测就是这种文件链接，属真实越界读取）。
+                const target = await realpathSafe(abs);
+                if (target === null || !isSameOrChild(target, home)) {
+                    skippedLinks.push({ path: entryRel, reason: 'outside-home' });
+                    continue;
+                }
+                if (st.isDirectory()) {
+                    if (await walk(abs, depth + 1, entryRel))
+                        followedLinks += 1;
+                }
+                else if (st.isFile()) {
+                    paths.push(entryRel);
+                    followedLinks += 1;
+                }
+                else {
+                    skippedLinks.push({ path: entryRel, reason: 'unreadable' });
+                }
+            }
+            // 其余类型（socket / FIFO / 设备）：与既有实现一致，静默忽略
+        }
+        return true;
+    };
+    await walk(base, 0, null);
+    return { paths: paths.sort(), skippedLinks, followedLinks, unreadableDirs };
+}
+//# sourceMappingURL=recursive-walk.js.map

package/lib/utils/zip.d.ts

@@ -0,0 +1,54 @@
+export interface ZipEntryMeta {
+    name: string;
+    method: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    crc32: number;
+    isDirectory: boolean;
+    /** 本地文件头在 ZIP 字节流中的偏移 */
+    localOffset: number;
+}
+export interface ZipSafetyLimits {
+    maxEntries?: number;
+    maxTotalBytes?: number;
+    maxCompressedBytes?: number;
+    maxSingleBytes?: number;
+    maxRatio?: number;
+}
+export declare const DEFAULT_ZIP_SAFETY_LIMITS: Required<ZipSafetyLimits>;
+export declare class ZipSafetyError extends Error {
+    constructor(message: string);
+}
+export declare function crc32(data: Uint8Array): number;
+export interface ZipWriteEntry {
+    name: string;
+    data: Uint8Array;
+}
+/** 组装 ZIP 字节（全部条目 method=8 deflate，UTF-8 文件名，含中央目录与 EOCD） */
+export declare function zipToBuffer(entries: ZipWriteEntry[]): Uint8Array;
+/** 写出 ZIP 文件（原子写，避免半写 zip） */
+export declare function writeZip(zipPath: string, entries: ZipWriteEntry[]): Promise<void>;
+/** 内存 ZIP 归档：构造时校验全部条目名与上限；读取时逐条解压 + CRC/尺寸/比预算校验 */
+export declare class ZipArchive {
+    private readonly buf;
+    private readonly metas;
+    readonly limits: Required<ZipSafetyLimits>;
+    private totalUncompressed;
+    constructor(buf: Uint8Array, metas: ZipEntryMeta[], limits: Required<ZipSafetyLimits>);
+    names(): string[];
+    entries(): ZipEntryMeta[];
+    has(name: string): boolean;
+    /** 读取并解压单条目（带 CRC32 / 尺寸 / 体积预算 / 压缩比校验） */
+    readEntry(name: string): Uint8Array;
+    readEntryText(name: string): string;
+    /** 读取并深度保护解析 JSON 条目 */
+    readEntryJson(name: string): unknown;
+}
+/** 解析 ZIP（含安全校验：条目名 / 条目数 / 压缩体积） */
+export declare function parseZip(buf: Uint8Array, limits?: ZipSafetyLimits): ZipArchive;
+/**
+ * 安全解压到受控目录（对齐设计 §13.4 safeExtract 签名）。
+ * 返回条目相对路径列表；任何越界/损坏即整体拒绝（不部分落盘）。
+ * m4 的 zip-security 可替换/强化本实现。
+ */
+export declare function safeExtract(zipPath: string, destDir: string, limits?: ZipSafetyLimits): Promise<string[]>;