dsh-config-manager 0.1.71 → 0.1.73

package/lib/utils/messages-utils.js

@@ -0,0 +1,216 @@
+/**
+ * src/utils/** 的领域消息目录（zh 源语言 / en 镜像）——「英文界面零中文」迁移（t5）。
+ *
+ * 口径（与 src/core/messages.ts 一致，见 docs/design/2026-10-08-i18n-en-hardcoding.md）：
+ *  - zh 值 = 迁移前的既有中文文案**逐字不变**（既有测试断言依赖它，只允许新增 en）；
+ *  - en 值类型为 Record<keyof typeof zh, string> —— 缺键/多键即编译错误；
+ *  - 动态明细一律走 {param} 插值传参，不得丢信息；
+ *  - 本目录经 registerMessageCatalog 注册（模块加载即注册），查找顺序在既有基础目录之后；
+ *  - zh 对象字面量必须叫 `zh`（守卫 E3 目录 zh 区豁免；改名会让本文件自身变成 300+ 命中）。
+ *
+ * 使用者：`utilsMsg`（本域唯一出口）——它 import 了 engineMsg，因此 import 本函数即完成注册，
+ * 不会出现「用了键但目录没注册」的裸键名输出。
+ */
+import { engineMsg, registerMessageCatalog } from '../core/engine-locale.js';
+export const zh = {
+    // ---------- utils/json.ts：深度/体积保护 ----------
+    'utils.json.depthDefault': 'JSON 嵌套深度超过上限 {max}',
+    'utils.json.bytesExceeded': 'JSON 体积超过上限 {max} 字节',
+    'utils.json.parseFailedDeep': 'JSON 解析失败（可能是嵌套过深）: {reason}',
+    'utils.json.depthExceeded': 'JSON 嵌套深度 {depth} 超过上限 {max}',
+    // ---------- utils/atomic-write.ts：tmp 名清洗 / symlink 策略 ----------
+    'utils.atomicWrite.invalidBaseName': '原子写：非法目标文件名「{base}」',
+    'utils.atomicWrite.illegalChars': '原子写：目标文件名含非法字符「{base}」',
+    'utils.atomicWrite.controlChars': '原子写：目标文件名含控制字符「{base}」',
+    'utils.atomicWrite.symlinkRejected': '原子写：目标为符号链接且策略为 reject，拒绝写入「{target}」',
+    'utils.atomicWrite.symlinkRejectedSync': '原子写（同步）：目标为符号链接且策略为 reject，拒绝写入「{target}」',
+    // ---------- utils/zip.ts：条目数 / 条目名 / 解压校验 ----------
+    'utils.zip.entryCountWriteExceeded': 'ZIP 条目数 {count} 超过上限 {max}（导出上限与读取上限一致；请缩小导出分区范围后重试）',
+    'utils.zip.unsafeEntryNameWrite': '拒绝写入不安全的条目名: {name}',
+    'utils.zip.entryInflateFailed': '条目 "{name}" 解压失败: {reason}',
+    'utils.zip.unknownCompression': '条目 "{name}" 使用未知压缩方法 {method}',
+    'utils.zip.entryMissing': 'ZIP 中不存在条目: {name}',
+    'utils.zip.localHeaderCorrupt': '条目 "{name}" 的本地文件头损坏',
+    'utils.zip.dataOutOfRange': '条目 "{name}" 数据越界',
+    'utils.zip.sizeMismatch': '条目 "{name}" 解压尺寸不符（{actual} ≠ {expected}）',
+    'utils.zip.crcMismatch': '条目 "{name}" CRC32 校验失败（ZIP 已损坏）',
+    'utils.zip.totalUncompressedExceeded': 'ZIP 解压总字节数超过上限',
+    'utils.zip.ratioExceeded': '条目 "{name}" 压缩比 {ratio} 超过上限（疑似 zip bomb）',
+    'utils.zip.tooSmall': '不是合法的 ZIP 文件（体积过小）',
+    'utils.zip.missingEocd': '不是合法的 ZIP 文件（缺少中央目录结束记录）',
+    'utils.zip.centralDirOutOfRange': '中央目录越界（ZIP 损坏）',
+    'utils.zip.entryCountReadExceeded': 'ZIP 条目数 {count} 超过上限 {max}',
+    'utils.zip.centralEntryOutOfRange': '中央目录条目越界（ZIP 损坏）',
+    'utils.zip.centralSignatureCorrupt': '中央目录签名损坏',
+    'utils.zip.unsafeEntryName': 'ZIP 条目名不安全: {name}',
+    'utils.zip.duplicateEntryName': 'ZIP 条目名重复: {name}',
+    'utils.zip.symlinkEntryRejected': 'ZIP 含符号链接条目，已拒绝: {name}',
+    'utils.zip.localHeaderOutOfRange': '条目 "{name}" 本地文件头越界',
+    'utils.zip.compressedTotalExceeded': 'ZIP 压缩数据总量超过上限',
+    'utils.zip.extractTargetOutOfRange': '解压目标越界: {name}',
+    // ---------- utils/env-lock.ts：环境锁诊断 detail（内部诊断文案，供 CLI/日志/事故恢复展示） ----------
+    'utils.envLock.probeFailed': '进程探测失败 pid={pid}: {reason}',
+    'utils.envLock.probeUndetermined': '进程探测未确定 pid={pid}',
+    'utils.envLock.probeFailedShort': '进程探测失败 pid={pid}',
+    'utils.envLock.mkdirLocksDir': '创建锁目录 {dir}',
+    'utils.envLock.openWxPermissionNoExisting': "open('wx') {path}: 权限/ACL 错误 ({code})，且未发现既有锁文件",
+    'utils.envLock.writeOwner': '写入 owner {path}',
+    'utils.envLock.releaseForeignToken': 'release: token 不匹配当前持有（foreign/已被接管），拒绝 unlink',
+    'utils.envLock.releaseOwnershipUnreadable': 'release: 磁盘 ownership 无法读取/损坏（可能被异常恢复或人工修改），拒绝 unlink（ownership-lost）',
+    'utils.envLock.releaseOwnershipMismatch': 'release: 磁盘 ownership.instanceId={diskId} !== 本 token {tokenId}（ownership-lost）',
+    'utils.envLock.releaseUnlinkFailed': 'release: unlink {path} 失败: {reason}',
+    'utils.envLock.ownershipMissing': 'ownership file 不存在（可能正被创建中）',
+    'utils.envLock.ownershipCorrupt': 'ownership 存在但无有效 owner（可能崩溃残留空/损坏文件），不删除、不执行；可用 --recover-stale-lock 回收',
+    'utils.envLock.heartbeatPermissionDenied': '无法读取 heartbeat（权限/ACL），保守拒绝',
+    'utils.envLock.heartbeatReadFailed': 'heartbeat 读取失败，保守拒绝',
+    'utils.envLock.ownerConfirmedDead': 'owner pid={pid} 确证不存在 (heartbeat expired)',
+    'utils.envLock.ownerAliveUnverifiable': 'owner pid={pid} 存活但无法验证进程身份（可能是 PID 复用），且 heartbeat {longExpired} → 判定为残留锁，可显式回收',
+    'utils.envLock.heartbeatExpiredNoIdentity': 'heartbeat 过期且 pid={pid} 存活，但无法可靠取得 OS process identity，保守拒绝删除',
+    'utils.envLock.pidReuse': 'pid reuse：pid={pid} identity 与 recorded 不同',
+    'utils.envLock.ownerAliveDegraded': 'owner 进程存活（heartbeat 可能 degraded），非 stale',
+    'utils.envLock.notStaleRefuseRecovery': '非 stale，拒绝 recovery',
+    'utils.envLock.ownershipGone': 'ownership 已消失（被他人接管/清除），停止 recovery',
+    'utils.envLock.captureRenameFailed': '捕获 rename 失败（可能被他人接管），停止',
+    'utils.envLock.captureReadFailed': '捕获文件读取失败，保留 recovering 供诊断',
+    'utils.envLock.corruptReclaimAnomaly': 'corrupt 回收二次验证异常：captured 具有效 owner，保留 {name} quarantine；不覆盖当前 environment.lock',
+    'utils.envLock.reverifyFailed': '二次验证失败：保留 {name} quarantine；不覆盖当前 environment.lock（若有 successor）',
+    'utils.envLock.removeCapturedFailed': '删除 captured 失败',
+    'utils.envLock.removedStaleOwnership': '已移除 stale ownership (op={op}, pid={pid})',
+    'utils.envLock.removedCorruptOwnership': '已移除 corrupt/崩溃残留所有权文件',
+    'utils.envLock.longExpired': '已过期 {age}（阈值 {threshold}）',
+    'utils.envLock.durationDays': '{value} 天',
+    'utils.envLock.durationHours': '{value} 小时',
+    'utils.envLock.durationMinutes': '{value} 分钟',
+    'utils.envLock.durationSeconds': '{value} 秒',
+    'utils.envLock.ioPermissionNotLock': '{what}: 权限/ACL 错误 ({code})，非锁占用',
+    // ---------- utils/env-lock.ts：锁被挡时给用户的分类文案（长 / 短两套，同源同分类） ----------
+    'utils.envLock.block.locked': '另一个任务正在运行，请稍后重试。',
+    'utils.envLock.block.blocked': '配置修改已被保护，请先处理恢复事项后再继续。',
+    'utils.envLock.block.unavailable': '操作暂时无法执行，请稍后重试；若持续失败请查看日志。',
+    'utils.envLock.block.stale': '检测到上次异常退出残留的配置锁（其持有进程已不存在），操作已被阻止。'
+        + '该锁不会自动清除，重试或重启 DSH 均无效：请在「事故恢复」中点击「回收残留锁」，'
+        + '或运行 dsh-config-manager recover-stale-lock 回收后再重试。',
+    'utils.envLock.brief.locked': '环境锁被另一项任务占用',
+    'utils.envLock.brief.blocked': '配置修改已被保护，需先处理恢复事项',
+    'utils.envLock.brief.unavailable': '环境锁暂时不可用',
+    'utils.envLock.brief.stale': '残留配置锁（持有进程已不存在），需先回收',
+    // ---------- utils/proxy.ts：代理隧道（保留原文的双语形态，zh 逐字不变） ----------
+    'utils.proxy.connectTimeout': '代理连接超时 / proxy connect timed out ({ms}ms)',
+    'utils.proxy.malformedConnectResponse': '代理 CONNECT 响应异常（头部过长）/ malformed CONNECT response',
+    'utils.proxy.refusedConnect': '代理拒绝 CONNECT（HTTP {status}）/ proxy refused CONNECT',
+    'utils.proxy.closedDuringConnect': '代理连接在 CONNECT 完成前关闭 / proxy closed during CONNECT',
+    // ---------- utils/session-log-repair.ts：会话日志修复计划/告警 ----------
+    'utils.sessionRepair.closerReferenced': '收尾块区间的 seq 被保留行引用 → 本次不丢弃该收尾块（避免把引用静默改指）',
+    'utils.sessionRepair.truncateBreaksRefs': '截断会让保留行的引用失去目标或被改指（seq {seqs}）→ 拒绝本次修复',
+    'utils.sessionRepair.keptRefersDropped': '保留行引用到本次将被丢弃的行（seq {seqs}）→ 拒绝本次修复',
+    'utils.sessionRepair.danglingRef': '先前就存在的悬空引用：seq {seq}（本次修复未丢弃它）',
+    'utils.sessionRepair.dropDuplicateRows': '丢弃 {rows} 行重放重复事件（字节相同 + seq 相同）',
+    'utils.sessionRepair.dropSyntheticCloser': '丢弃 {rows} 行崩溃恢复补写的收尾块（turn {turn} 之后仍在续写，真实内容保留）',
+    'utils.sessionRepair.truncateTail': '在首个异常处截断：丢弃其后 {rows} 行（**有损**，备份可回滚）',
+};
+export const en = {
+    // ---------- utils/json.ts ----------
+    'utils.json.depthDefault': 'JSON nesting depth exceeds the limit of {max}',
+    'utils.json.bytesExceeded': 'JSON payload exceeds the limit of {max} bytes',
+    'utils.json.parseFailedDeep': 'JSON parsing failed (possibly nested too deeply): {reason}',
+    'utils.json.depthExceeded': 'JSON nesting depth {depth} exceeds the limit of {max}',
+    // ---------- utils/atomic-write.ts ----------
+    'utils.atomicWrite.invalidBaseName': 'Atomic write: invalid target file name "{base}"',
+    'utils.atomicWrite.illegalChars': 'Atomic write: target file name contains illegal characters "{base}"',
+    'utils.atomicWrite.controlChars': 'Atomic write: target file name contains control characters "{base}"',
+    'utils.atomicWrite.symlinkRejected': 'Atomic write: target is a symbolic link and the policy is reject — refusing to write "{target}"',
+    'utils.atomicWrite.symlinkRejectedSync': 'Atomic write (sync): target is a symbolic link and the policy is reject — refusing to write "{target}"',
+    // ---------- utils/zip.ts ----------
+    'utils.zip.entryCountWriteExceeded': 'ZIP entry count {count} exceeds the limit of {max} (write and read limits are the same; narrow the exported section range and retry)',
+    'utils.zip.unsafeEntryNameWrite': 'Refusing to write an unsafe entry name: {name}',
+    'utils.zip.entryInflateFailed': 'Entry "{name}" failed to decompress: {reason}',
+    'utils.zip.unknownCompression': 'Entry "{name}" uses an unknown compression method {method}',
+    'utils.zip.entryMissing': 'No such entry in the ZIP: {name}',
+    'utils.zip.localHeaderCorrupt': 'Entry "{name}" has a corrupt local file header',
+    'utils.zip.dataOutOfRange': 'Entry "{name}" data is out of range',
+    'utils.zip.sizeMismatch': 'Entry "{name}" decompressed size mismatch ({actual} ≠ {expected})',
+    'utils.zip.crcMismatch': 'Entry "{name}" CRC32 check failed (the ZIP is corrupt)',
+    'utils.zip.totalUncompressedExceeded': 'Total uncompressed ZIP bytes exceed the limit',
+    'utils.zip.ratioExceeded': 'Entry "{name}" compression ratio {ratio} exceeds the limit (possible zip bomb)',
+    'utils.zip.tooSmall': 'Not a valid ZIP file (too small)',
+    'utils.zip.missingEocd': 'Not a valid ZIP file (missing end of central directory record)',
+    'utils.zip.centralDirOutOfRange': 'Central directory is out of range (corrupt ZIP)',
+    'utils.zip.entryCountReadExceeded': 'ZIP entry count {count} exceeds the limit of {max}',
+    'utils.zip.centralEntryOutOfRange': 'Central directory entry is out of range (corrupt ZIP)',
+    'utils.zip.centralSignatureCorrupt': 'Central directory signature is corrupt',
+    'utils.zip.unsafeEntryName': 'Unsafe ZIP entry name: {name}',
+    'utils.zip.duplicateEntryName': 'Duplicate ZIP entry name: {name}',
+    'utils.zip.symlinkEntryRejected': 'ZIP contains a symbolic link entry — rejected: {name}',
+    'utils.zip.localHeaderOutOfRange': 'Entry "{name}" local file header is out of range',
+    'utils.zip.compressedTotalExceeded': 'Total compressed ZIP bytes exceed the limit',
+    'utils.zip.extractTargetOutOfRange': 'Extraction target is out of range: {name}',
+    // ---------- utils/env-lock.ts ----------
+    'utils.envLock.probeFailed': 'Process probe failed for pid={pid}: {reason}',
+    'utils.envLock.probeUndetermined': 'Process probe for pid={pid} was inconclusive',
+    'utils.envLock.probeFailedShort': 'Process probe failed for pid={pid}',
+    'utils.envLock.mkdirLocksDir': 'create lock directory {dir}',
+    'utils.envLock.openWxPermissionNoExisting': "open('wx') {path}: permission/ACL error ({code}), and no existing lock file was found",
+    'utils.envLock.writeOwner': 'write owner {path}',
+    'utils.envLock.releaseForeignToken': 'release: token does not match the current holder (foreign/taken over) — refusing to unlink',
+    'utils.envLock.releaseOwnershipUnreadable': 'release: on-disk ownership is unreadable/corrupt (possibly recovered abnormally or edited by hand) — refusing to unlink (ownership-lost)',
+    'utils.envLock.releaseOwnershipMismatch': 'release: on-disk ownership.instanceId={diskId} !== this token {tokenId} (ownership-lost)',
+    'utils.envLock.releaseUnlinkFailed': 'release: unlink {path} failed: {reason}',
+    'utils.envLock.ownershipMissing': 'ownership file does not exist (possibly being created right now)',
+    'utils.envLock.ownershipCorrupt': 'ownership exists but has no valid owner (possibly an empty/corrupt file left by a crash); not deleted, not executed; reclaim with --recover-stale-lock',
+    'utils.envLock.heartbeatPermissionDenied': 'Cannot read heartbeat (permission/ACL) — conservatively refusing',
+    'utils.envLock.heartbeatReadFailed': 'Heartbeat read failed — conservatively refusing',
+    'utils.envLock.ownerConfirmedDead': 'owner pid={pid} is confirmed gone (heartbeat expired)',
+    'utils.envLock.ownerAliveUnverifiable': 'owner pid={pid} is alive but its process identity cannot be verified (possible PID reuse), and heartbeat {longExpired} → judged a stale lock, explicit reclaim allowed',
+    'utils.envLock.heartbeatExpiredNoIdentity': 'heartbeat expired and pid={pid} is alive, but the OS process identity cannot be obtained reliably — conservatively refusing to delete',
+    'utils.envLock.pidReuse': 'pid reuse: pid={pid} identity differs from the recorded one',
+    'utils.envLock.ownerAliveDegraded': 'owner process is alive (heartbeat may be degraded), not stale',
+    'utils.envLock.notStaleRefuseRecovery': 'not stale — refusing recovery',
+    'utils.envLock.ownershipGone': 'ownership has disappeared (taken over/cleared by someone else) — stopping recovery',
+    'utils.envLock.captureRenameFailed': 'capture rename failed (possibly taken over by someone else) — stopping',
+    'utils.envLock.captureReadFailed': 'reading the captured file failed; keeping the recovering file for diagnosis',
+    'utils.envLock.corruptReclaimAnomaly': 'corrupt reclaim second verification anomaly: the captured file has a valid owner; keeping {name} quarantined and not overwriting the current environment.lock',
+    'utils.envLock.reverifyFailed': 'second verification failed: keeping {name} quarantined and not overwriting the current environment.lock (if any successor exists)',
+    'utils.envLock.removeCapturedFailed': 'failed to delete the captured file',
+    'utils.envLock.removedStaleOwnership': 'removed stale ownership (op={op}, pid={pid})',
+    'utils.envLock.removedCorruptOwnership': 'removed the corrupt/crash-left ownership file',
+    'utils.envLock.longExpired': 'expired {age} ago (threshold {threshold})',
+    'utils.envLock.durationDays': '{value} days',
+    'utils.envLock.durationHours': '{value} hours',
+    'utils.envLock.durationMinutes': '{value} minutes',
+    'utils.envLock.durationSeconds': '{value} seconds',
+    'utils.envLock.ioPermissionNotLock': '{what}: permission/ACL error ({code}), not lock contention',
+    'utils.envLock.block.locked': 'Another task is running, please retry later.',
+    'utils.envLock.block.blocked': 'Configuration changes are protected — resolve the recovery items before continuing.',
+    'utils.envLock.block.unavailable': 'The operation cannot run right now, please retry later; if it keeps failing, check the logs.',
+    'utils.envLock.block.stale': 'A configuration lock left behind by a previous abnormal exit was detected (its owning process no longer exists), so the operation was blocked.'
+        + 'This lock will not clear itself — retrying or restarting DSH will not help: click "Reclaim stale lock" under "Incident recovery",'
+        + 'or run dsh-config-manager recover-stale-lock and then retry.',
+    'utils.envLock.brief.locked': 'Environment lock held by another task',
+    'utils.envLock.brief.blocked': 'Configuration changes are protected; resolve recovery items first',
+    'utils.envLock.brief.unavailable': 'Environment lock temporarily unavailable',
+    'utils.envLock.brief.stale': 'Stale configuration lock (owning process is gone); reclaim it first',
+    // ---------- utils/proxy.ts ----------
+    'utils.proxy.connectTimeout': 'Proxy connection timed out ({ms}ms)',
+    'utils.proxy.malformedConnectResponse': 'Malformed proxy CONNECT response (headers too long)',
+    'utils.proxy.refusedConnect': 'Proxy refused CONNECT (HTTP {status})',
+    'utils.proxy.closedDuringConnect': 'Proxy connection closed before CONNECT completed',
+    // ---------- utils/session-log-repair.ts ----------
+    'utils.sessionRepair.closerReferenced': 'The seq range of the closer block is referenced by kept rows → this run will not drop that closer block (avoid silently redirecting references)',
+    'utils.sessionRepair.truncateBreaksRefs': 'Truncation would leave references from kept rows without a target, or redirect them (seq {seqs}) → refusing this repair',
+    'utils.sessionRepair.keptRefersDropped': 'Kept rows reference rows that would be dropped by this repair (seq {seqs}) → refusing this repair',
+    'utils.sessionRepair.danglingRef': 'Pre-existing dangling reference: seq {seq} (this repair does not drop it)',
+    'utils.sessionRepair.dropDuplicateRows': 'Drop {rows} row(s) that replay duplicate events (identical bytes + identical seq)',
+    'utils.sessionRepair.dropSyntheticCloser': 'Drop {rows} row(s) of the crash-recovery closer block (writing continued after turn {turn}; real content is preserved)',
+    'utils.sessionRepair.truncateTail': 'Truncate at the first anomaly: drop the following {rows} row(s) (**lossy**, a backup can roll it back)',
+};
+registerMessageCatalog({ id: 'utils', zh, en });
+/**
+ * 本域唯一出口：取一条 src/utils/** 的文案（键名受类型约束，拼错即编译错误）。
+ *
+ * 为什么不让调用方直接 import engineMsg：import 本函数即保证目录已注册（模块加载期注册一次），
+ * 否则会出现「用了键但注册表里没有 → 输出裸键名」的静默失败。
+ */
+export function utilsMsg(key, params) {
+    return engineMsg(key, params);
+}
+//# sourceMappingURL=messages-utils.js.map

package/lib/utils/proxy.js

@@ -23,10 +23,19 @@ import http from 'node:http';
 import https from 'node:https';
 import net from 'node:net';
 import tls from 'node:tls';
+import { utilsMsg } from './messages-utils.js';
 /** 环境变量开关：`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;
+/**
+ * 默认 User-Agent（issue #86）。
+ *
+ * node 原生 `http`/`https` **不会**像 undici 那样自动补 UA，而本模块正是「配了代理」时唯一
+ * 的出站通道 —— 于是同一份代码出现「不配代理能用、配了代理反而 403」（GitHub 前置层直接拒绝
+ * 无 UA 请求）。统一兜底使两条通道的请求语义一致；调用方显式传入时绝不覆盖。
+ */
+const DEFAULT_USER_AGENT = 'DSH-Config-Manager';
 /** 视为可跟随的重定向状态码（与 WebDAV 通道同一套语义） */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 /** 不能带响应体的状态码（`new Response(body, {status})` 会抛错） */
@@ -171,7 +180,7 @@ function connectToProxy(proxy, timeoutMs) {
             : net.connect({ host: proxy.hostname, port }, onConnect);
         socket.setTimeout(timeoutMs, () => {
             socket.destroy();
-            reject(new Error(`代理连接超时 / proxy connect timed out (${timeoutMs}ms)`));
+            reject(new Error(utilsMsg('utils.proxy.connectTimeout', { ms: timeoutMs })));
         });
         socket.once('error', (err) => { reject(err); });
     });
@@ -207,7 +216,7 @@ async function openTunnel(target, proxy, timeoutMs) {
             if (end === -1) {
                 if (buffered.length > 8192) {
                     socket.off('data', onData);
-                    fail('代理 CONNECT 响应异常（头部过长）/ malformed CONNECT response');
+                    fail(utilsMsg('utils.proxy.malformedConnectResponse'));
                 }
                 return;
             }
@@ -215,7 +224,7 @@ async function openTunnel(target, proxy, timeoutMs) {
             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`);
+                fail(utilsMsg('utils.proxy.refusedConnect', { status }));
                 return;
             }
             // CONNECT 响应头之后的字节已属隧道数据 → 回填，避免 TLS 握手丢包
@@ -226,7 +235,7 @@ async function openTunnel(target, proxy, timeoutMs) {
         };
         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.once('close', () => { socket.off('data', onData); reject(new Error(utilsMsg('utils.proxy.closedDuringConnect'))); });
         socket.write(lines.join('\r\n'));
     });
 }
@@ -275,9 +284,13 @@ export async function requestOnce(options) {
     const payload = options.body === undefined
         ? undefined
         : Buffer.isBuffer(options.body) ? options.body : Buffer.from(options.body, 'utf8');
+    // 调用方显式传入的 User-Agent（大小写不敏感）优先；缺省补默认 UA（见 DEFAULT_USER_AGENT）。
+    const callerHeaders = options.headers ?? {};
+    const hasUserAgent = Object.keys(callerHeaders).some((key) => key.toLowerCase() === 'user-agent');
     const headers = {
         ...(payload !== undefined ? { 'content-length': String(payload.length) } : {}),
-        ...(options.headers ?? {}),
+        ...(hasUserAgent ? {} : { 'user-agent': DEFAULT_USER_AGENT }),
+        ...callerHeaders,
     };
     /** url 非 null → 以 URL 形态发起（node 自行解析 host/port/path/TLS）；否则按显式 options 发起。 */
     const send = (lib, url, requestOptions) => new Promise((resolve, reject) => {

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

@@ -6,11 +6,33 @@ export interface SkippedLink {
      *  broken=断链；unreadable=目标既非文件也非目录（设备/FIFO 等）；too-deep=超过深度上限 */
     reason: 'loop' | 'outside-home' | 'broken' | 'unreadable' | 'too-deep';
 }
+/**
+ * 被整棵跳过的「运行时依赖目录」（任意深度的 `node_modules`，issue #76）。
+ *
+ * 为什么是硬规则：技能目录自带依赖时，`skills` 分区能被遍历出上万个条目，撞上导出侧的
+ * 10 000 条目闸门 → **定时备份永久失败且用户无解**（定时备份与「立即备份」都没有分区范围，
+ * `backup-schedule.json` 也没有排除项）。而 `plugins` 分区早就按 `npm pack` 的产物度量
+ * （`core/local-plugin-pack.ts` 明写「node_modules 由 npm pack 自身排除」）、宿主的
+ * `dirSizeBytes` 也显式跳过它 —— 同一个概念此前在通用递归里缺了同一排除项。
+ *
+ * 依赖树可由包内保留的 `package.json` / lock 重建，不属于用户配置，故不进备份；
+ * 但**必须留痕**（见 RecursiveListing.skippedDepDirs），绝不静默。
+ */
+export declare const EXCLUDED_DEP_DIR_NAMES: readonly string[];
+/** 被跳过的运行时依赖目录（内容未进备份；必须在报告里可见） */
+export interface SkippedDepDir {
+    /** homeDir 相对路径（被跳过的目录本身） */
+    path: string;
+    /** 该目录下递归的普通文件数；null = 计数预算耗尽未统计（不猜，也不假装是 0） */
+    files: number | null;
+}
 export interface RecursiveListing {
     /** homeDir 相对、斜杠分隔、已排序的文件路径 */
     paths: string[];
     /** 被跳过的链接（含原因）；空 = 本次遍历无内容缺失 */
     skippedLinks: SkippedLink[];
+    /** 因「可重建的运行时依赖」整棵跳过的目录（EXCLUDED_DEP_DIR_NAMES）；空 = 本次没有跳过 */
+    skippedDepDirs: SkippedDepDir[];
     /** 成功跟随（内容已收集）的链接数；用于「链接结构不会被还原」的提示 */
     followedLinks: number;
     /** 读取失败的目录（ACL / 竞态删除等）——这些目录下的内容同样没进备份，必须留痕 */

package/lib/utils/recursive-walk.js

@@ -16,8 +16,29 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { isSameOrChild } from './paths.js';
+/**
+ * 被整棵跳过的「运行时依赖目录」（任意深度的 `node_modules`，issue #76）。
+ *
+ * 为什么是硬规则：技能目录自带依赖时，`skills` 分区能被遍历出上万个条目，撞上导出侧的
+ * 10 000 条目闸门 → **定时备份永久失败且用户无解**（定时备份与「立即备份」都没有分区范围，
+ * `backup-schedule.json` 也没有排除项）。而 `plugins` 分区早就按 `npm pack` 的产物度量
+ * （`core/local-plugin-pack.ts` 明写「node_modules 由 npm pack 自身排除」）、宿主的
+ * `dirSizeBytes` 也显式跳过它 —— 同一个概念此前在通用递归里缺了同一排除项。
+ *
+ * 依赖树可由包内保留的 `package.json` / lock 重建，不属于用户配置，故不进备份；
+ * 但**必须留痕**（见 RecursiveListing.skippedDepDirs），绝不静默。
+ */
+export const EXCLUDED_DEP_DIR_NAMES = ['node_modules'];
 /** 深度上限：防御病态目录树 / realpath 去重失效时的栈爆炸 */
 const MAX_DEPTH = 64;
+/**
+ * 依赖目录计数的**全局预算**（本次遍历合计；按**条目**扣，文件与目录都算）。
+ *
+ * 计数只走 readdir（不 stat、不读内容、不跟随链接），但病态树仍可能是成千上万次系统调用 ——
+ * 超预算即停，未统计的目录记 `files: null`。宁可少一个数字，也不让「跳过一个目录」变成
+ * 第二次全量遍历；按条目而非只按文件扣，是为了挡「上万层空目录」这种只要目录不要文件的树。
+ */
+const MAX_DEP_FILES_COUNTED = 100_000;
 function normalizeSlashes(p) {
     return p.split(path.sep).join('/');
 }
@@ -29,6 +50,47 @@ async function realpathSafe(p) {
         return null;
     }
 }
+/** 该路径（跟随链接）是否目录；读不到 → false（按「不是依赖目录」处理，宁可多带不可误丢） */
+async function statIsDir(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 只数文件个数的有界递归（不 stat、不读内容、不跟随链接；预算按条目扣，见 MAX_DEP_FILES_COUNTED）。
+ * @returns 完整计数；预算耗尽 → null（下界不冒充精确值）
+ */
+async function countFilesBounded(dir, budget) {
+    let files = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (cur === undefined)
+            break;
+        let entries;
+        try {
+            entries = await fs.readdir(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (budget.left <= 0)
+                return null;
+            budget.left -= 1;
+            if (entry.isDirectory()) {
+                stack.push(path.join(cur, entry.name));
+                continue;
+            }
+            if (entry.isFile())
+                files += 1;
+        }
+    }
+    return files;
+}
 /**
  * 遍历 baseDir 下的所有文件（跟随目录链接）。
  * @param baseDir 绝对路径；不在 homeDir 内则返回空清单（与既有语义一致）
@@ -44,6 +106,8 @@ export async function listRecursiveFollowingLinks(baseDir, homeDir) {
     const homeReal = (await realpathSafe(home)) ?? home;
     const paths = [];
     const skippedLinks = [];
+    const skippedDepDirs = [];
+    const depFileBudget = { left: MAX_DEP_FILES_COUNTED };
     const unreadableDirs = [];
     let followedLinks = 0;
     /** 已进入过的目录 realpath（防环 / 防同一目标被两条链接重复收集） */
@@ -86,6 +150,16 @@ export async function listRecursiveFollowingLinks(baseDir, homeDir) {
         for (const entry of entries) {
             const abs = path.join(dir, entry.name);
             const entryRel = rel(abs);
+            // issue #76：运行时依赖目录**整棵跳过**（任意深度）。内容不进备份，但必须留痕（见 SkippedDepDir）。
+            // 链接形态也算（junction 指向的 node_modules 同样是依赖树）；判不出类型时按普通目录继续走。
+            if (EXCLUDED_DEP_DIR_NAMES.includes(entry.name)
+                && (entry.isDirectory() || (entry.isSymbolicLink() && (await statIsDir(abs))))) {
+                skippedDepDirs.push({
+                    path: entryRel,
+                    files: depFileBudget.left > 0 ? await countFilesBounded(abs, depFileBudget) : null,
+                });
+                continue;
+            }
             if (entry.isDirectory()) {
                 await walk(abs, depth + 1, null);
             }
@@ -128,6 +202,6 @@ export async function listRecursiveFollowingLinks(baseDir, homeDir) {
         return true;
     };
     await walk(base, 0, null);
-    return { paths: paths.sort(), skippedLinks, followedLinks, unreadableDirs };
+    return { paths: paths.sort(), skippedLinks, skippedDepDirs, followedLinks, unreadableDirs };
 }
 //# sourceMappingURL=recursive-walk.js.map

package/lib/utils/session-log-repair.js

@@ -19,6 +19,7 @@
 import fs from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
+import { utilsMsg } from './messages-utils.js';
 import { isSessionLogName } from './session-log.js';
 import { collectSessionRowReferences, findSyntheticCloserRun, parseSessionRowFacts, referencesContain, sessionRowMayHaveReferences, walkSessionRowContinuity, } from './session-row-facts.js';
 import { decodeZstdFrame, encodeZstdFrame, scanZstdFrames, zstdAvailable } from './zstd-frame.js';
@@ -270,7 +271,7 @@ export function planSessionLogRepair(bytes, opts = {}) {
         const referencing = firstKeptRowReferencing(rows, keptWithoutCloser, candidateSeqs);
         if (referencing !== undefined) {
             closerSkippedByReference = true;
-            warnings.push('收尾块区间的 seq 被保留行引用 → 本次不丢弃该收尾块（避免把引用静默改指）');
+            warnings.push(utilsMsg('utils.sessionRepair.closerReferenced'));
         }
         else {
             const anomalyAfter = walkRows(rows, keptWithoutCloser).firstAnomalyIndex;
@@ -304,9 +305,9 @@ export function planSessionLogRepair(bytes, opts = {}) {
         // 整个计划直接 refuse —— 绝不返回一个「注定在 apply 期被拒」的有损预览。
         const closure = compareReferenceClosure(rows, before, kept, keptAfterTruncation);
         if (closure.missing.length > 0 || closure.redirected.length > 0) {
-            warnings.push('截断会让保留行的引用失去目标或被改指（seq ' +
-                [...closure.missing, ...closure.redirected].sort((a, b) => a - b).join(', ') +
-                '）→ 拒绝本次修复');
+            warnings.push(utilsMsg('utils.sessionRepair.truncateBreaksRefs', {
+                seqs: [...closure.missing, ...closure.redirected].sort((a, b) => a - b).join(', '),
+            }));
             return { ok: false, reason: 'dropped-ref', actions: [], lossy: false, warnings };
         }
         if (opts.allowLossy !== true) {
@@ -330,11 +331,11 @@ export function planSessionLogRepair(bytes, opts = {}) {
     // 先前就存在的悬空引用（引用的 seq 本来就不在日志里）**只告警**，绝不 refuse。
     const finalClosure = compareReferenceClosure(rows, before, kept, kept);
     if (finalClosure.missing.length > 0 || finalClosure.redirected.length > 0) {
-        warnings.push('保留行引用到本次将被丢弃的行（seq ' + [...finalClosure.missing, ...finalClosure.redirected].join(', ') + '）→ 拒绝本次修复');
+        warnings.push(utilsMsg('utils.sessionRepair.keptRefersDropped', { seqs: [...finalClosure.missing, ...finalClosure.redirected].join(', ') }));
         return { ok: false, reason: 'dropped-ref', actions, lossy: false, warnings };
     }
     for (const seq of finalClosure.dangling)
-        warnings.push('先前就存在的悬空引用：seq ' + String(seq) + '（本次修复未丢弃它）');
+        warnings.push(utilsMsg('utils.sessionRepair.danglingRef', { seq }));
     return {
         ok: true,
         actions,
@@ -353,7 +354,7 @@ function buildActions(dupRows, closerDropped, closerRun, truncateRows) {
     if (dupRows > 0) {
         actions.push({
             code: 'drop-duplicate-rows',
-            detail: '丢弃 ' + String(dupRows) + ' 行重放重复事件（字节相同 + seq 相同）',
+            detail: utilsMsg('utils.sessionRepair.dropDuplicateRows', { rows: dupRows }),
             lossy: false,
             rows: dupRows,
         });
@@ -361,7 +362,7 @@ function buildActions(dupRows, closerDropped, closerRun, truncateRows) {
     if (closerDropped && closerRun !== undefined) {
         actions.push({
             code: 'drop-synthetic-closer',
-            detail: '丢弃 ' + String(closerRun.end - closerRun.start) + ' 行崩溃恢复补写的收尾块（turn ' + String(closerRun.turn) + ' 之后仍在续写，真实内容保留）',
+            detail: utilsMsg('utils.sessionRepair.dropSyntheticCloser', { rows: closerRun.end - closerRun.start, turn: closerRun.turn }),
             lossy: false,
             rows: closerRun.end - closerRun.start,
         });
@@ -369,7 +370,7 @@ function buildActions(dupRows, closerDropped, closerRun, truncateRows) {
     if (truncateRows > 0) {
         actions.push({
             code: 'truncate-tail',
-            detail: '在首个异常处截断：丢弃其后 ' + String(truncateRows) + ' 行（**有损**，备份可回滚）',
+            detail: utilsMsg('utils.sessionRepair.truncateTail', { rows: truncateRows }),
             lossy: true,
             rows: truncateRows,
         });