@pyrokine/mcp-ssh 2.3.2 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/file-ops.js CHANGED
@@ -6,6 +6,8 @@ import { createHash } from 'crypto';
6
6
  import * as fs from 'fs';
7
7
  import * as os from 'os';
8
8
  import * as path from 'path';
9
+ import { StringDecoder } from 'string_decoder';
10
+ import { matchesDirectoryExclude } from './directory-verification.js';
9
11
  import { sessionManager } from './session-manager.js';
10
12
  import { escapeShellArg, expandTilde } from './tools/utils.js';
11
13
  // 文件类型 mode 常量
@@ -85,6 +87,22 @@ const SFTP_SYNC_MAX_FILES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_FILES', 10_000)
85
87
  const SFTP_SYNC_MAX_DIRECTORIES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DIRECTORIES', 2_000);
86
88
  const SFTP_SYNC_MAX_DEPTH = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DEPTH', 64);
87
89
  const SFTP_SYNC_MAX_BYTES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_BYTES', 10 * 1024 * 1024 * 1024);
90
+ class SftpOperationTimeoutError extends Error {
91
+ timeout;
92
+ constructor(timeout) {
93
+ super(`SFTP operation timed out after ${timeout}ms; remote transfer state is unknown`);
94
+ this.timeout = timeout;
95
+ this.name = 'SftpOperationTimeoutError';
96
+ }
97
+ }
98
+ function abortError(signal) {
99
+ return signal.reason instanceof Error ? signal.reason : new Error('SFTP operation aborted');
100
+ }
101
+ function throwIfAborted(signal) {
102
+ if (signal?.aborted) {
103
+ throw abortError(signal);
104
+ }
105
+ }
88
106
  function assertSftpTraversalBudget(state, depth, currentPath) {
89
107
  if (depth > SFTP_SYNC_MAX_DEPTH) {
90
108
  throw new Error(`SFTP sync traversal depth exceeded at ${currentPath} (max ${SFTP_SYNC_MAX_DEPTH})`);
@@ -187,14 +205,15 @@ function resolvePathOrAncestor(p) {
187
205
  return absolute;
188
206
  }
189
207
  }
190
- export function probeLocalPath(localPath) {
208
+ export function probeLocalPath(localPath, followSymlinks = false) {
191
209
  const expanded = expandTilde(localPath);
192
210
  const resolvedPath = resolvePathOrAncestor(expanded);
193
211
  const allowList = getAllowListStatus(expanded);
194
212
  if (!fs.existsSync(expanded)) {
195
213
  return { exists: false, inputPath: localPath, expandedPath: expanded, resolvedPath, allowList };
196
214
  }
197
- const stats = fs.lstatSync(expanded);
215
+ const linkStats = fs.lstatSync(expanded);
216
+ const stats = followSymlinks ? fs.statSync(expanded) : linkStats;
198
217
  return {
199
218
  exists: true,
200
219
  inputPath: localPath,
@@ -203,7 +222,7 @@ export function probeLocalPath(localPath) {
203
222
  size: stats.size,
204
223
  mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
205
224
  mtimeMs: Math.round(stats.mtimeMs),
206
- isSymlink: stats.isSymbolicLink(),
225
+ isSymlink: linkStats.isSymbolicLink(),
207
226
  isDirectory: stats.isDirectory(),
208
227
  isFile: stats.isFile(),
209
228
  allowList,
@@ -224,13 +243,27 @@ function sftpStat(sftp, remotePath) {
224
243
  });
225
244
  });
226
245
  }
246
+ function isSftpMissingError(error) {
247
+ if (!error || typeof error !== 'object') {
248
+ return false;
249
+ }
250
+ const code = 'code' in error ? error.code : undefined;
251
+ if (code === 2 || code === 'ENOENT') {
252
+ return true;
253
+ }
254
+ const message = error instanceof Error ? error.message : String(error);
255
+ return /no such file|not found/i.test(message);
256
+ }
227
257
  async function sftpExists(sftp, remotePath) {
228
258
  try {
229
259
  await sftpStat(sftp, remotePath);
230
260
  return true;
231
261
  }
232
- catch {
233
- return false;
262
+ catch (error) {
263
+ if (isSftpMissingError(error)) {
264
+ return false;
265
+ }
266
+ throw error;
234
267
  }
235
268
  }
236
269
  async function remoteExists(alias, remotePath) {
@@ -245,14 +278,17 @@ async function remoteExists(alias, remotePath) {
245
278
  /**
246
279
  * 带进度追踪的流传输
247
280
  */
248
- function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, closeSftp = true) {
281
+ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, closeSftp = true, signal) {
249
282
  return new Promise((resolve, reject) => {
250
283
  let settled = false;
284
+ const onAbort = () => cleanup(abortError(signal));
285
+ const detachAbort = () => signal?.removeEventListener('abort', onAbort);
251
286
  const cleanup = (err) => {
252
287
  if (settled) {
253
288
  return;
254
289
  }
255
290
  settled = true;
291
+ detachAbort();
256
292
  // 先解管道并强制销毁两端,避免错误后流仍持有 sftp 资源
257
293
  try {
258
294
  readStream.unpipe(writeStream);
@@ -262,14 +298,14 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
262
298
  }
263
299
  try {
264
300
  ;
265
- readStream.destroy?.();
301
+ readStream.destroy?.(err);
266
302
  }
267
303
  catch {
268
304
  /* ignore */
269
305
  }
270
306
  try {
271
307
  ;
272
- writeStream.destroy?.();
308
+ writeStream.destroy?.(err);
273
309
  }
274
310
  catch {
275
311
  /* ignore */
@@ -295,19 +331,26 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
295
331
  writeStream.on('close', () => {
296
332
  if (!settled) {
297
333
  settled = true;
334
+ detachAbort();
298
335
  if (closeSftp) {
299
336
  sftp.end();
300
337
  }
301
338
  resolve({ success: true, size: totalSize });
302
339
  }
303
340
  });
341
+ if (signal?.aborted) {
342
+ cleanup(abortError(signal));
343
+ return;
344
+ }
345
+ signal?.addEventListener('abort', onAbort, { once: true });
304
346
  readStream.pipe(writeStream);
305
347
  });
306
348
  }
307
349
  /**
308
350
  * 上传文件
309
351
  */
310
- export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp) {
352
+ export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal) {
353
+ throwIfAborted(signal);
311
354
  localPath = expandTilde(localPath);
312
355
  validateLocalPathAgainstAllowList(localPath);
313
356
  if (!fs.existsSync(localPath)) {
@@ -327,12 +370,15 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
327
370
  }
328
371
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
329
372
  const totalSize = lstats.size;
330
- return pipeWithProgress(fs.createReadStream(localPath), sftp.createWriteStream(remotePath), sftp, totalSize, onProgress, !sharedSftp);
373
+ const safeCreateMode = (createMode ?? lstats.mode) & 0o777;
374
+ const result = await pipeWithProgress(fs.createReadStream(localPath), sftp.createWriteStream(remotePath, { mode: safeCreateMode }), sftp, totalSize, onProgress, !sharedSftp, signal);
375
+ return { ...result, createMode: safeCreateMode.toString(8).padStart(4, '0') };
331
376
  }
332
377
  /**
333
378
  * 下载文件
334
379
  */
335
- export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp) {
380
+ export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal) {
381
+ throwIfAborted(signal);
336
382
  localPath = expandTilde(localPath);
337
383
  validateLocalPathAgainstAllowList(localPath);
338
384
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
@@ -343,7 +389,7 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
343
389
  if (!fs.existsSync(localDir)) {
344
390
  fs.mkdirSync(localDir, { recursive: true });
345
391
  }
346
- return await pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp);
392
+ return await pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp, signal);
347
393
  }
348
394
  catch (error) {
349
395
  if (!sharedSftp) {
@@ -399,25 +445,49 @@ function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
399
445
  truncated: readOffset < totalSize,
400
446
  };
401
447
  }
448
+ export function buildLineRangeAwkProgram(start, end) {
449
+ return [
450
+ 'BEGIN { written = 0; actual_start = 0; actual_end = 0; byte_limit = 0; saw_after = 0; full_body = 0 }',
451
+ `NR >= ${start} && NR <= ${end} {`,
452
+ ' if (actual_start == 0) { actual_start = NR }',
453
+ ' actual_end = NR',
454
+ ' remaining = max - written',
455
+ ' if (remaining <= 0) { byte_limit = 1; exit }',
456
+ ' body_length = length($0)',
457
+ ' if (body_length >= remaining) {',
458
+ ' printf "%s", substr($0, 1, remaining)',
459
+ ' written += remaining',
460
+ ' if (body_length > remaining) { byte_limit = 1; exit }',
461
+ ' full_body = 1',
462
+ ' next',
463
+ ' }',
464
+ ' printf "%s\\n", $0',
465
+ ' written += body_length + 1',
466
+ ' full_body = 0',
467
+ '}',
468
+ `NR > ${end} { if (full_body) { byte_limit = 1 } saw_after = 1; exit }`,
469
+ 'END {',
470
+ ' if (full_body && final_terminated) { byte_limit = 1 }',
471
+ ' printf "__MCP_LINE_META__%d:%d:%d:%d:%d\\n", actual_start, actual_end, written, byte_limit, saw_after > "/dev/stderr"',
472
+ '}',
473
+ ].join('\n');
474
+ }
402
475
  async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange) {
403
476
  const { start, end } = parseLineRange(lineRange);
404
- const awkProgram = [
405
- 'BEGIN { written = 0 }',
406
- `NR>=${start} && NR<=${end} {`,
407
- 'line = $0 "\\n"',
408
- 'remaining = max - written',
409
- 'if (remaining <= 0) { exit }',
410
- 'if (length(line) > remaining) { printf "%s", substr(line, 1, remaining); exit }',
411
- 'printf "%s", line',
412
- 'written += length(line)',
413
- '}',
414
- `NR>${end} { exit }`,
415
- ].join(' ');
416
- const command = `LC_ALL=C awk -v max=${maxBytes} ${escapeShellArg(awkProgram)} ${escapeShellArg(remotePath)}`;
417
- const result = await sessionManager.exec(alias, command, {
477
+ const awkProgram = buildLineRangeAwkProgram(start, end);
478
+ const escapedPath = escapeShellArg(remotePath);
479
+ const command = [
480
+ `last_byte=$(tail -c 1 -- ${escapedPath} 2>/dev/null | od -An -tu1 | tr -d ' ')`,
481
+ 'if [ "$last_byte" = "10" ]; then terminated=1; else terminated=0; fi',
482
+ `LC_ALL=C awk -v max=${maxBytes} -v final_terminated="$terminated" ${escapeShellArg(awkProgram)} ${escapedPath} | base64 | tr -d '\\n'`,
483
+ 'status=${PIPESTATUS[0]}',
484
+ 'printf "__MCP_LINE_END__%s\\n" "$terminated" >&2',
485
+ 'exit "$status"',
486
+ ].join('; ');
487
+ const result = await sessionManager.exec(alias, `bash -c ${escapeShellArg(command)}`, {
418
488
  timeout: 30000,
419
489
  useLoginUser: true,
420
- maxOutputSize: maxBytes + 4096,
490
+ maxOutputSize: Math.ceil(maxBytes / 3) * 4 + 4096,
421
491
  });
422
492
  if (!result.success) {
423
493
  const message = result.stderr.trim() ||
@@ -425,18 +495,43 @@ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange)
425
495
  `remote lineRange command failed with exit code ${result.exitCode}`;
426
496
  throw new Error(message);
427
497
  }
428
- const readBytes = Buffer.byteLength(result.stdout, 'utf-8');
498
+ const metadataMatch = result.stderr.match(/__MCP_LINE_META__(\d+):(\d+):(\d+):([01]):([01])/);
499
+ const terminatedMatch = result.stderr.match(/__MCP_LINE_END__([01])/);
500
+ if (!metadataMatch || !terminatedMatch) {
501
+ throw new Error('remote lineRange command returned incomplete metadata');
502
+ }
503
+ const actualStart = Number(metadataMatch[1]);
504
+ const actualEnd = Number(metadataMatch[2]);
505
+ const encoded = result.stdout.trim();
506
+ if (encoded && (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 !== 0)) {
507
+ throw new Error('remote lineRange command returned malformed base64 content');
508
+ }
509
+ let rawContent = Buffer.from(encoded, 'base64');
510
+ const metadataByteLimitReached = metadataMatch[4] === '1';
511
+ const sawAfter = metadataMatch[5] === '1';
512
+ const finalLineTerminated = terminatedMatch[1] === '1';
513
+ if (!sawAfter && !metadataByteLimitReached && !finalLineTerminated && rawContent.at(-1) === 0x0a) {
514
+ rawContent = rawContent.subarray(0, -1);
515
+ }
516
+ const decoder = new StringDecoder('utf8');
517
+ const content = decoder.write(rawContent);
518
+ const incompleteUtf8 = decoder.end().length > 0;
519
+ const readBytes = Buffer.byteLength(content, 'utf8');
520
+ const byteLimitReached = metadataByteLimitReached || incompleteUtf8;
521
+ const eof = !sawAfter && !byteLimitReached;
429
522
  return {
430
- content: result.stdout,
523
+ content,
431
524
  size: totalSize,
432
525
  total_size: totalSize,
433
526
  read_offset: 0,
434
527
  read_bytes: readBytes,
435
- remaining_bytes: Math.max(0, totalSize - readBytes),
436
528
  sample_kind: 'line_range',
437
- truncated: readBytes >= maxBytes,
438
- line_start: start,
439
- line_end: end,
529
+ truncated: byteLimitReached || sawAfter,
530
+ line_start: actualStart || undefined,
531
+ line_end: actualEnd || undefined,
532
+ eof,
533
+ byte_limit_reached: byteLimitReached,
534
+ final_line_terminated: actualEnd === 0 ? undefined : finalLineTerminated,
440
535
  };
441
536
  }
442
537
  /**
@@ -607,7 +702,11 @@ export async function mkdir(alias, remotePath, recursive = false) {
607
702
  if (recursive) {
608
703
  // 通过 exec 实现递归创建
609
704
  const result = await sessionManager.exec(alias, `mkdir -p ${escapeShellArg(remotePath)}`);
610
- return result.exitCode === 0;
705
+ if (!result.success || result.exitCode !== 0) {
706
+ const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
707
+ throw new Error(`Remote mkdir failed for ${remotePath}: ${detail}`);
708
+ }
709
+ return true;
611
710
  }
612
711
  const sftp = await sessionManager.getSftp(alias);
613
712
  return new Promise((resolve, reject) => {
@@ -625,24 +724,85 @@ export async function mkdir(alias, remotePath, recursive = false) {
625
724
  /**
626
725
  * 检查远程是否安装 rsync
627
726
  */
628
- export async function checkRsync(alias) {
727
+ export async function checkRsync(alias, timeout = 10_000) {
629
728
  const cached = rsyncCache.get(alias);
630
729
  if (cached !== undefined && cached.expiresAt > Date.now()) {
631
730
  return cached.value;
632
731
  }
732
+ const startedAt = Date.now();
633
733
  try {
634
- const result = await sessionManager.exec(alias, 'which rsync');
635
- const available = result.exitCode === 0 && result.stdout.trim().length > 0;
636
- rsyncCache.set(alias, { value: available, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
637
- return available;
734
+ const result = await sessionManager.exec(alias, 'command -v rsync', {
735
+ timeout,
736
+ useLoginUser: true,
737
+ maxOutputSize: 4096,
738
+ });
739
+ const duration = Date.now() - startedAt;
740
+ if (result.success && result.exitCode === 0 && result.stdout.trim().length > 0) {
741
+ const probe = {
742
+ available: true,
743
+ status: 'available',
744
+ duration,
745
+ retryable: false,
746
+ exitCode: result.exitCode,
747
+ };
748
+ rsyncCache.set(alias, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
749
+ return probe;
750
+ }
751
+ if (result.failureKind === 'timeout' || result.timedOut) {
752
+ return {
753
+ available: false,
754
+ status: 'timeout',
755
+ duration,
756
+ retryable: true,
757
+ exitCode: result.exitCode,
758
+ failureKind: result.failureKind,
759
+ error: result.stderr.trim() || result.stdout.trim() || `rsync probe timed out after ${timeout}ms`,
760
+ };
761
+ }
762
+ if (result.failureKind === 'ssh_transport') {
763
+ return {
764
+ available: false,
765
+ status: 'error',
766
+ duration,
767
+ retryable: true,
768
+ exitCode: result.exitCode,
769
+ failureKind: result.failureKind,
770
+ error: result.stderr.trim() || result.stdout.trim() || 'SSH transport failed during rsync probe',
771
+ };
772
+ }
773
+ if (result.exitCode === 1 && result.stderr.trim().length === 0) {
774
+ const probe = {
775
+ available: false,
776
+ status: 'unavailable',
777
+ duration,
778
+ retryable: false,
779
+ exitCode: result.exitCode,
780
+ };
781
+ rsyncCache.set(alias, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
782
+ return probe;
783
+ }
784
+ return {
785
+ available: false,
786
+ status: 'error',
787
+ duration,
788
+ retryable: result.failureKind !== 'remote_command',
789
+ exitCode: result.exitCode,
790
+ failureKind: result.failureKind,
791
+ error: result.stderr.trim() || result.stdout.trim() || `rsync probe failed with exit code ${result.exitCode}`,
792
+ };
638
793
  }
639
- catch {
640
- rsyncCache.set(alias, { value: false, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
641
- return false;
794
+ catch (error) {
795
+ return {
796
+ available: false,
797
+ status: 'error',
798
+ duration: Date.now() - startedAt,
799
+ retryable: true,
800
+ error: error instanceof Error ? error.message : String(error),
801
+ };
642
802
  }
643
803
  }
644
804
  /**
645
- * 智能文件同步(优先使用 rsync)
805
+ * 智能文件同步(根据连接能力选择 rsync 或 SFTP)
646
806
  *
647
807
  * @param alias SSH 连接别名
648
808
  * @param localPath 本地路径
@@ -654,13 +814,75 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
654
814
  const startedAt = Date.now();
655
815
  localPath = expandTilde(localPath);
656
816
  validateLocalPathAgainstAllowList(localPath);
657
- const hasRsync = await checkRsync(alias);
658
- const result = hasRsync
659
- ? await syncWithRsync(alias, localPath, remotePath, direction, options)
660
- : await syncWithSftp(alias, localPath, remotePath, direction, options);
817
+ if (remotePath === '~' || remotePath.startsWith('~/')) {
818
+ throw new Error('remotePath must be absolute or relative to the SSH working directory; ~ is not supported');
819
+ }
820
+ const capabilityStartedAt = Date.now();
821
+ const capability = sessionManager.getExternalTransferCapability(alias);
822
+ let sourceIsDirectory;
823
+ if (direction === 'upload') {
824
+ if (!fs.existsSync(localPath)) {
825
+ throw new Error(`Local source does not exist: ${localPath}`);
826
+ }
827
+ const linkStats = fs.lstatSync(localPath);
828
+ if (linkStats.isSymbolicLink() && !options.followSymlinks) {
829
+ throw new Error('Refusing to sync a top-level symlink; set followSymlinks=true to traverse its target');
830
+ }
831
+ sourceIsDirectory = (options.followSymlinks ? fs.statSync(localPath) : linkStats).isDirectory();
832
+ }
833
+ else {
834
+ sourceIsDirectory = (await getFileInfo(alias, remotePath)).isDirectory;
835
+ }
836
+ if (sourceIsDirectory && options.recursive === false) {
837
+ throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
838
+ }
839
+ const preflightTimeout = options.preflightTimeout ?? 10_000;
840
+ const rsyncProbe = capability.rsyncEligible
841
+ ? await checkRsync(alias, preflightTimeout)
842
+ : {
843
+ available: false,
844
+ status: 'skipped',
845
+ duration: 0,
846
+ retryable: false,
847
+ reason: capability.decisionReason,
848
+ };
849
+ const resolvedOptions = { ...options, sourceIsDirectory };
850
+ const capabilityDuration = Date.now() - capabilityStartedAt;
851
+ const selectedTransport = capability.rsyncEligible && rsyncProbe?.available ? 'rsync' : 'sftp';
852
+ const decisionReason = !capability.rsyncEligible
853
+ ? capability.decisionReason
854
+ : rsyncProbe?.status === 'available'
855
+ ? capability.decisionReason
856
+ : rsyncProbe?.status === 'unavailable'
857
+ ? 'remote_rsync_unavailable'
858
+ : rsyncProbe?.status === 'timeout'
859
+ ? 'remote_rsync_probe_timeout'
860
+ : 'remote_rsync_probe_failed';
861
+ const operationStartedAt = Date.now();
862
+ const result = selectedTransport === 'rsync'
863
+ ? await syncWithRsync(alias, localPath, remotePath, direction, resolvedOptions, capability)
864
+ : await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, resolvedOptions);
865
+ const operationDuration = Date.now() - operationStartedAt;
866
+ const operationStatus = result.operationStatus ?? (result.success ? 'completed' : 'failed');
867
+ const connectStatus = result.connectStatus ?? (selectedTransport === 'rsync' ? 'completed' : 'not_applicable');
661
868
  return {
662
869
  ...result,
663
870
  transport: result.method,
871
+ selectedTransport,
872
+ decisionReason,
873
+ rsyncProbe,
874
+ fallbackReason: result.fallbackReason,
875
+ phaseDurations: {
876
+ capabilityPreflight: capabilityDuration,
877
+ connect: result.connectDuration,
878
+ operation: operationDuration,
879
+ total: Date.now() - startedAt,
880
+ },
881
+ phaseStatus: {
882
+ capabilityPreflight: rsyncProbe?.status === 'timeout' || rsyncProbe?.status === 'error' ? 'failed' : 'completed',
883
+ connect: connectStatus,
884
+ operation: operationStatus,
885
+ },
664
886
  direction,
665
887
  dryRun: options.dryRun === true,
666
888
  duration: Date.now() - startedAt,
@@ -670,22 +892,16 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
670
892
  * 使用 rsync 同步文件
671
893
  * 通过本地执行 rsync 连接到远程(需要密钥认证或 ssh-agent)
672
894
  */
673
- async function syncWithRsync(alias, localPath, remotePath, direction, options) {
895
+ async function syncWithRsync(alias, localPath, remotePath, direction, options, capability) {
674
896
  const checkCommand = os.platform() === 'win32' ? 'where' : 'which';
675
- const checkResult = await runLocalProcess(checkCommand, ['rsync'], 10_000);
897
+ const checkResult = await runLocalProcess(checkCommand, ['rsync'], options.preflightTimeout ?? 10_000);
676
898
  if (checkResult.status !== 0) {
677
- // 本地没有 rsync,回退到 SFTP
678
- return syncWithSftp(alias, localPath, remotePath, direction, options);
679
- }
680
- // 获取会话信息以构建 rsync 命令
681
- const sessions = sessionManager.listSessions();
682
- const sessionInfo = sessions.find((s) => s.alias === alias);
683
- if (!sessionInfo) {
684
- throw new Error(`Session '${alias}' not found`);
685
- }
686
- // 密码认证无法透传给 rsync 的 ssh 子进程,直接走 SFTP
687
- if (sessionInfo.authMethod === 'password') {
688
- return syncWithSftp(alias, localPath, remotePath, direction, options);
899
+ const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
900
+ return {
901
+ ...fallback,
902
+ connectStatus: 'not_applicable',
903
+ fallbackReason: checkResult.timedOut ? 'local_rsync_preflight_timeout' : 'local_rsync_unavailable',
904
+ };
689
905
  }
690
906
  // 构建 rsync 参数
691
907
  const args = ['-avz', '--itemize-changes', '--stats'];
@@ -695,66 +911,110 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
695
911
  if (options.dryRun) {
696
912
  args.push('--dry-run');
697
913
  }
698
- if (options.recursive === false) {
699
- args.push('--dirs'); // 不递归,只传输目录本身
700
- }
701
914
  if (options.exclude) {
702
915
  for (const pattern of options.exclude) {
703
916
  args.push(`--exclude=${pattern}`);
704
917
  }
705
918
  }
706
919
  if (options.followSymlinks) {
707
- // -L / --copy-links: 跟随 symlink,上传链接目标内容(与 SFTP 路径 followSymlinks=true 行为对齐)
708
- // 默认不传则用 rsync -a 自带的 -l:保留 symlink 本身,不上传目标内容
920
+ // -L / --copy-links: 跟随 symlink,上传链接目标内容(与 SFTP 路径 followSymlinks=true 行为一致)
709
921
  args.push('-L');
710
922
  }
923
+ else {
924
+ // -a 隐含 -l,显式关闭后默认跳过 symlink,与 SFTP 默认行为一致
925
+ args.push('--no-links');
926
+ }
927
+ args.push('--no-devices', '--no-specials');
711
928
  // path 安全校验:以 `-` 起始的路径会被 rsync 当成选项解析(即便有 `--` 兜底,也避免 OS/rsync 实现差异)
712
929
  if (localPath.startsWith('-') || remotePath.startsWith('-')) {
713
930
  throw new Error('Invalid path: localPath and remotePath must not start with -');
714
931
  }
715
932
  // username/host 安全校验:拒绝 shell 元字符与 ssh 选项注入
716
933
  const sshIdentifierAllowed = /^[a-zA-Z0-9.:_-]+$/;
717
- if (!sshIdentifierAllowed.test(sessionInfo.username)) {
718
- throw new Error(`Invalid username for rsync: "${sessionInfo.username}" 含非法字符`);
934
+ if (!sshIdentifierAllowed.test(capability.username)) {
935
+ throw new Error(`Invalid username for rsync: "${capability.username}" 含非法字符`);
719
936
  }
720
- if (!sshIdentifierAllowed.test(sessionInfo.host)) {
721
- throw new Error(`Invalid host for rsync: "${sessionInfo.host}" 含非法字符`);
937
+ if (!sshIdentifierAllowed.test(capability.host)) {
938
+ throw new Error(`Invalid host for rsync: "${capability.host}" 含非法字符`);
722
939
  }
723
940
  // 构建 rsync argv(不用 shell=true,避免 username/host 含 shell 元字符时注入)
724
941
  // ProxyCommand=none 显式禁用 ssh-config 中可能定义的 ProxyCommand,防止外部命令注入
725
- const sshParts = [
726
- 'ssh',
942
+ const connectTimeout = options.connectTimeout ?? 30_000;
943
+ const sshOptions = [
727
944
  '-p',
728
- String(sessionInfo.port),
945
+ String(capability.port),
729
946
  '-o',
730
947
  'StrictHostKeyChecking=accept-new',
731
948
  '-o',
732
949
  'BatchMode=yes',
733
950
  '-o',
951
+ `ConnectTimeout=${Math.max(1, Math.ceil(connectTimeout / 1000))}`,
952
+ '-o',
734
953
  'ProxyCommand=none',
735
954
  ];
736
- if (sessionInfo.keyPath) {
737
- sshParts.push('-i', sessionInfo.keyPath);
955
+ if (capability.keyPath) {
956
+ sshOptions.push('-i', capability.keyPath);
957
+ }
958
+ const destination = `${capability.username}@${capability.host}`;
959
+ const connectStartedAt = Date.now();
960
+ const connectResult = await runLocalProcess('ssh', [...sshOptions, destination, 'true'], connectTimeout);
961
+ const connectDuration = Date.now() - connectStartedAt;
962
+ if (connectResult.error || connectResult.status !== 0) {
963
+ const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
964
+ const fallbackReason = connectResult.timedOut ? 'rsync_connect_timeout' : 'rsync_connect_failed';
965
+ const detail = connectResult.stderr.trim() || connectResult.error?.message;
966
+ return {
967
+ ...fallback,
968
+ connectDuration,
969
+ connectStatus: 'failed',
970
+ fallbackReason,
971
+ output: detail
972
+ ? `OpenSSH connect preflight failed: ${detail}\n${fallback.output ?? ''}`.trim()
973
+ : fallback.output,
974
+ };
738
975
  }
739
- const sshCmd = sshParts.map(quoteRsyncSshArg).join(' ');
976
+ const sshCmd = ['ssh', ...sshOptions].map(quoteRsyncSshArg).join(' ');
977
+ const rsyncLocalPath = options.sourceIsDirectory && direction === 'upload' && !localPath.endsWith(path.sep)
978
+ ? `${localPath}${path.sep}`
979
+ : localPath;
980
+ const rsyncRemotePath = options.sourceIsDirectory && direction === 'download' && !remotePath.endsWith('/')
981
+ ? `${remotePath}/`
982
+ : remotePath;
740
983
  // remoteSpec 作为单独 argv 元素,不经 shell 解析
741
- const remoteSpec = `${sessionInfo.username}@${sessionInfo.host}:${remotePath}`;
984
+ const remoteSpec = `${destination}:${rsyncRemotePath}`;
742
985
  // 在 path 参数前插 `--`,明确剩余为路径而非选项(双重保险)
743
986
  const rsyncArgs = direction === 'upload'
744
- ? [...args, '-e', sshCmd, '--', localPath, remoteSpec]
987
+ ? [...args, '-e', sshCmd, '--', rsyncLocalPath, remoteSpec]
745
988
  : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
746
989
  try {
747
- const result = await runLocalProcess('rsync', rsyncArgs, 600000);
990
+ const operationTimeout = options.operationTimeout ?? 600_000;
991
+ const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout);
748
992
  if (result.error || result.status !== 0) {
749
993
  const stderr = result.stderr.trim();
750
994
  const reason = result.timedOut
751
- ? 'timed out after 600000ms'
995
+ ? `timed out after ${operationTimeout}ms`
752
996
  : (result.error?.message ?? `exit code ${result.status}`);
753
- const fallback = await syncWithSftp(alias, localPath, remotePath, direction, options);
997
+ if (result.timedOut) {
998
+ return {
999
+ success: false,
1000
+ method: 'rsync',
1001
+ connectDuration,
1002
+ connectStatus: 'completed',
1003
+ operationStatus: 'unknown',
1004
+ timedOut: true,
1005
+ retryable: true,
1006
+ fallbackReason: 'rsync_operation_timeout',
1007
+ output: `rsync ${reason}${stderr ? ` | stderr: ${stderr}` : ''}; remote transfer state is unknown`,
1008
+ };
1009
+ }
1010
+ const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
754
1011
  const warning = `rsync 失败原因: ${reason}${stderr ? ` | stderr: ${stderr}` : ''} | 已 fallback 到 SFTP(性能可能较差)`;
755
1012
  console.warn(`[mcp-ssh] ${warning}`);
756
1013
  return {
757
1014
  ...fallback,
1015
+ connectDuration,
1016
+ connectStatus: 'completed',
1017
+ fallbackReason: 'rsync_operation_failed',
758
1018
  output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
759
1019
  };
760
1020
  }
@@ -764,6 +1024,9 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
764
1024
  return {
765
1025
  success: true,
766
1026
  method: 'rsync',
1027
+ connectDuration,
1028
+ connectStatus: 'completed',
1029
+ operationStatus: 'completed',
767
1030
  filesTransferred,
768
1031
  stats,
769
1032
  commandSummary: {
@@ -773,18 +1036,21 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
773
1036
  recursive: options.recursive !== false,
774
1037
  followSymlinks: options.followSymlinks === true,
775
1038
  excludeCount: options.exclude?.length ?? 0,
776
- usedKeyPath: Boolean(sessionInfo.keyPath),
1039
+ usedKeyPath: Boolean(capability.keyPath),
777
1040
  },
778
1041
  output,
779
1042
  };
780
1043
  }
781
1044
  catch (e) {
782
- // rsync 执行异常,回退到 SFTP(保留原因供调用方追溯)
783
- const fallback = await syncWithSftp(alias, localPath, remotePath, direction, options);
1045
+ // rsync 启动异常发生在传输进程建立前,可安全改用 SFTP
1046
+ const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
784
1047
  const warning = `rsync 异常: ${e instanceof Error ? e.message : String(e)} | 已 fallback 到 SFTP(性能可能较差)`;
785
1048
  console.warn(`[mcp-ssh] ${warning}`);
786
1049
  return {
787
1050
  ...fallback,
1051
+ connectDuration,
1052
+ connectStatus: 'completed',
1053
+ fallbackReason: 'rsync_execution_error',
788
1054
  output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
789
1055
  };
790
1056
  }
@@ -794,6 +1060,8 @@ class DirectoryTransferAccumulator {
794
1060
  fileCount: 0,
795
1061
  totalSize: 0,
796
1062
  skippedSymlinks: 0,
1063
+ skippedUnsupported: 0,
1064
+ unsupportedSamples: [],
797
1065
  added: 0,
798
1066
  updated: 0,
799
1067
  failed: 0,
@@ -811,6 +1079,12 @@ class DirectoryTransferAccumulator {
811
1079
  addSkippedSymlink() {
812
1080
  this.result.skippedSymlinks++;
813
1081
  }
1082
+ addSkippedUnsupported(itemPath) {
1083
+ this.result.skippedUnsupported++;
1084
+ if (this.result.unsupportedSamples.length < 10) {
1085
+ this.result.unsupportedSamples.push(itemPath);
1086
+ }
1087
+ }
814
1088
  addFailed() {
815
1089
  this.result.failed++;
816
1090
  }
@@ -818,6 +1092,12 @@ class DirectoryTransferAccumulator {
818
1092
  this.result.fileCount += result.fileCount;
819
1093
  this.result.totalSize += result.totalSize;
820
1094
  this.result.skippedSymlinks += result.skippedSymlinks;
1095
+ this.result.skippedUnsupported += result.skippedUnsupported;
1096
+ for (const itemPath of result.unsupportedSamples) {
1097
+ if (this.result.unsupportedSamples.length < 10) {
1098
+ this.result.unsupportedSamples.push(itemPath);
1099
+ }
1100
+ }
821
1101
  this.result.added += result.added;
822
1102
  this.result.updated += result.updated;
823
1103
  this.result.failed += result.failed;
@@ -827,11 +1107,17 @@ class DirectoryTransferAccumulator {
827
1107
  }
828
1108
  }
829
1109
  function buildDirectorySyncResult(result, warnings) {
830
- return buildSyncResult(result.fileCount, result.totalSize, warnings, result.skippedSymlinks, {
1110
+ const syncResult = buildSyncResult(result.fileCount, result.totalSize, warnings, result.skippedSymlinks, {
831
1111
  added: result.added,
832
1112
  updated: result.updated,
1113
+ skipped: result.skippedSymlinks + result.skippedUnsupported,
833
1114
  failed: result.failed,
834
1115
  });
1116
+ return {
1117
+ ...syncResult,
1118
+ skippedUnsupported: result.skippedUnsupported > 0 ? result.skippedUnsupported : undefined,
1119
+ unsupportedSamples: result.unsupportedSamples.length > 0 ? result.unsupportedSamples : undefined,
1120
+ };
835
1121
  }
836
1122
  function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0, stats) {
837
1123
  if (skippedSymlinks > 0) {
@@ -888,35 +1174,71 @@ async function hashRemoteFile(alias, remotePath) {
888
1174
  maxOutputSize: 4096,
889
1175
  });
890
1176
  if (!result.success) {
891
- return undefined;
1177
+ return {
1178
+ status: 'error',
1179
+ exitCode: result.exitCode,
1180
+ failureKind: result.failureKind,
1181
+ retryable: result.failureKind !== 'remote_command',
1182
+ error: result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`,
1183
+ };
892
1184
  }
893
1185
  const digest = result.stdout.trim().split(/\s+/)[0];
894
- return /^[a-fA-F0-9]{64}$/.test(digest) ? digest : undefined;
1186
+ if (!/^[a-fA-F0-9]{64}$/.test(digest)) {
1187
+ return {
1188
+ status: 'error',
1189
+ exitCode: result.exitCode,
1190
+ failureKind: result.failureKind,
1191
+ retryable: false,
1192
+ error: 'remote SHA-256 command returned an invalid digest',
1193
+ };
1194
+ }
1195
+ return { status: 'available', digest, retryable: false };
895
1196
  }
896
1197
  async function buildSingleFileVerification(alias, localPath, remotePath, direction) {
897
- const localStats = fs.statSync(localPath);
898
- const remoteInfo = await getFileInfo(alias, remotePath);
899
- const [localSha256, remoteSha256] = await Promise.all([hashLocalFile(localPath), hashRemoteFile(alias, remotePath)]);
900
- return {
901
- kind: 'single_file',
902
- direction,
903
- hashAlgorithm: 'sha256',
904
- hashMatch: remoteSha256 ? localSha256 === remoteSha256 : undefined,
905
- local: {
906
- size: localStats.size,
907
- mode: (localStats.mode & 0o777).toString(8),
908
- mtimeMs: Math.round(localStats.mtimeMs),
909
- sha256: localSha256,
910
- },
911
- remote: {
912
- size: remoteInfo.size,
913
- permissions: remoteInfo.permissions,
914
- owner: remoteInfo.owner,
915
- group: remoteInfo.group,
916
- mtime: remoteInfo.mtime,
917
- sha256: remoteSha256,
918
- },
919
- };
1198
+ try {
1199
+ const localStats = fs.statSync(localPath);
1200
+ const [remoteInfo, localSha256, remoteHash] = await Promise.all([
1201
+ getFileInfo(alias, remotePath),
1202
+ hashLocalFile(localPath),
1203
+ hashRemoteFile(alias, remotePath),
1204
+ ]);
1205
+ return {
1206
+ kind: 'single_file',
1207
+ direction,
1208
+ status: remoteHash.status === 'available' ? 'completed' : 'error',
1209
+ failureStage: remoteHash.status === 'error' ? 'remote_hash' : undefined,
1210
+ retryable: remoteHash.retryable,
1211
+ error: remoteHash.error,
1212
+ exitCode: remoteHash.exitCode,
1213
+ failureKind: remoteHash.failureKind,
1214
+ hashAlgorithm: 'sha256',
1215
+ hashMatch: remoteHash.digest ? localSha256 === remoteHash.digest : undefined,
1216
+ local: {
1217
+ size: localStats.size,
1218
+ mode: (localStats.mode & 0o777).toString(8),
1219
+ mtimeMs: Math.round(localStats.mtimeMs),
1220
+ sha256: localSha256,
1221
+ },
1222
+ remote: {
1223
+ size: remoteInfo.size,
1224
+ permissions: remoteInfo.permissions,
1225
+ owner: remoteInfo.owner,
1226
+ group: remoteInfo.group,
1227
+ mtime: remoteInfo.mtime,
1228
+ sha256: remoteHash.digest,
1229
+ },
1230
+ };
1231
+ }
1232
+ catch (error) {
1233
+ return {
1234
+ kind: 'single_file',
1235
+ direction,
1236
+ status: 'error',
1237
+ failureStage: 'remote_metadata_or_hash',
1238
+ retryable: true,
1239
+ error: error instanceof Error ? error.message : String(error),
1240
+ };
1241
+ }
920
1242
  }
921
1243
  async function resolveSftpUploadFileTarget(alias, localPath, remotePath) {
922
1244
  if (remotePath.endsWith('/')) {
@@ -928,12 +1250,53 @@ async function resolveSftpUploadFileTarget(alias, localPath, remotePath) {
928
1250
  return path.posix.join(remotePath, path.basename(localPath));
929
1251
  }
930
1252
  }
931
- catch {
1253
+ catch (error) {
1254
+ if (!isSftpMissingError(error)) {
1255
+ throw error;
1256
+ }
932
1257
  // Missing remote targets are handled by uploadFile below.
933
1258
  }
934
1259
  return remotePath;
935
1260
  }
1261
+ function resolveSftpDownloadFileTarget(remotePath, localPath) {
1262
+ if (localPath.endsWith(path.sep)) {
1263
+ fs.mkdirSync(localPath, { recursive: true });
1264
+ return path.join(localPath, path.posix.basename(remotePath));
1265
+ }
1266
+ if (fs.existsSync(localPath) && fs.statSync(localPath).isDirectory()) {
1267
+ return path.join(localPath, path.posix.basename(remotePath));
1268
+ }
1269
+ return localPath;
1270
+ }
1271
+ async function syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options) {
1272
+ const timeout = options.operationTimeout ?? 600_000;
1273
+ const controller = new AbortController();
1274
+ const operation = syncWithSftp(alias, localPath, remotePath, direction, {
1275
+ ...options,
1276
+ signal: controller.signal,
1277
+ });
1278
+ let timer;
1279
+ const timedOut = new Promise((resolve) => {
1280
+ timer = setTimeout(() => {
1281
+ controller.abort(new SftpOperationTimeoutError(timeout));
1282
+ resolve({
1283
+ success: false,
1284
+ method: 'sftp',
1285
+ operationStatus: 'unknown',
1286
+ timedOut: true,
1287
+ retryable: true,
1288
+ output: `SFTP operation timed out after ${timeout}ms; remote transfer state is unknown`,
1289
+ });
1290
+ }, timeout);
1291
+ });
1292
+ const result = await Promise.race([operation, timedOut]);
1293
+ if (timer) {
1294
+ clearTimeout(timer);
1295
+ }
1296
+ return result;
1297
+ }
936
1298
  async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1299
+ throwIfAborted(options.signal);
937
1300
  const warnings = [];
938
1301
  if (options.delete) {
939
1302
  warnings.push('delete option is not supported in SFTP mode (requires rsync)');
@@ -941,7 +1304,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
941
1304
  if (options.dryRun) {
942
1305
  const localExists = fs.existsSync(localPath);
943
1306
  const localStats = localExists ? fs.lstatSync(localPath) : undefined;
944
- const remoteTargetExists = await remoteExists(alias, remotePath).catch(() => false);
1307
+ const remoteTargetExists = await remoteExists(alias, remotePath);
945
1308
  return {
946
1309
  success: true,
947
1310
  method: 'sftp',
@@ -982,13 +1345,16 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
982
1345
  output: 'Refusing to upload symlink at top level (set followSymlinks=true to traverse)',
983
1346
  };
984
1347
  }
985
- if (stats.isDirectory() && options.recursive !== false) {
986
- const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0);
1348
+ if (stats.isDirectory() && options.recursive === false) {
1349
+ throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1350
+ }
1351
+ if (stats.isDirectory()) {
1352
+ const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal);
987
1353
  return buildDirectorySyncResult(result, warnings);
988
1354
  }
989
1355
  const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath);
990
1356
  const existed = await remoteExists(alias, targetRemotePath);
991
- const { size } = await uploadFile(alias, localPath, targetRemotePath);
1357
+ const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal);
992
1358
  return {
993
1359
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
994
1360
  verification: await buildSingleFileVerification(alias, localPath, targetRemotePath, 'upload'),
@@ -996,25 +1362,41 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
996
1362
  }
997
1363
  // download
998
1364
  const info = await getFileInfo(alias, remotePath);
999
- if (info.isDirectory && options.recursive !== false) {
1365
+ if (info.isDirectory && options.recursive === false) {
1366
+ throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1367
+ }
1368
+ if (info.isDirectory) {
1000
1369
  const result = await downloadDirectory(alias, remotePath, localPath, options.exclude, undefined, {
1001
1370
  files: 0,
1002
1371
  directories: 0,
1003
1372
  bytes: 0,
1004
- }, 0);
1373
+ }, 0, options.signal);
1005
1374
  return buildDirectorySyncResult(result, warnings);
1006
1375
  }
1007
- const existed = fs.existsSync(localPath);
1008
- const { size } = await downloadFile(alias, remotePath, localPath);
1376
+ const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath);
1377
+ const existed = fs.existsSync(targetLocalPath);
1378
+ const { size } = await downloadFile(alias, remotePath, targetLocalPath, undefined, undefined, options.signal);
1009
1379
  return {
1010
1380
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
1011
- verification: await buildSingleFileVerification(alias, localPath, remotePath, 'download'),
1381
+ verification: await buildSingleFileVerification(alias, targetLocalPath, remotePath, 'download'),
1012
1382
  };
1013
1383
  }
1014
1384
  catch (err) {
1385
+ if (err instanceof SftpOperationTimeoutError) {
1386
+ return {
1387
+ success: false,
1388
+ method: 'sftp',
1389
+ operationStatus: 'unknown',
1390
+ timedOut: true,
1391
+ retryable: true,
1392
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1393
+ output: err.message,
1394
+ };
1395
+ }
1015
1396
  return {
1016
1397
  success: false,
1017
1398
  method: 'sftp',
1399
+ operationStatus: 'failed',
1018
1400
  stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1019
1401
  output: err instanceof Error ? err.message : String(err),
1020
1402
  };
@@ -1023,19 +1405,32 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1023
1405
  /**
1024
1406
  * 递归上传目录
1025
1407
  */
1026
- async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0) {
1408
+ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '') {
1409
+ throwIfAborted(signal);
1027
1410
  const accumulator = new DirectoryTransferAccumulator();
1028
1411
  recordSftpDirectory(traversal, depth, localPath);
1029
1412
  const ownSftp = !sharedSftp;
1030
1413
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
1414
+ const activeDirectories = (traversal.activeDirectories ??= new Set());
1415
+ const realPath = fs.realpathSync(localPath);
1416
+ if (activeDirectories.has(realPath)) {
1417
+ accumulator.addSkippedSymlink();
1418
+ if (ownSftp) {
1419
+ sftp.end();
1420
+ }
1421
+ return accumulator.toResult();
1422
+ }
1423
+ activeDirectories.add(realPath);
1031
1424
  try {
1032
1425
  await mkdir(alias, remotePath, true);
1426
+ throwIfAborted(signal);
1033
1427
  const items = fs.readdirSync(localPath);
1034
1428
  // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
1035
1429
  const subDirItems = [];
1036
1430
  const fileItems = [];
1037
1431
  for (const item of items) {
1038
- if (exclude && exclude.some((pattern) => matchPattern(item, pattern))) {
1432
+ const itemRelativePath = relativeBase ? `${relativeBase}/${item}` : item;
1433
+ if (matchesDirectoryExclude(itemRelativePath, exclude)) {
1039
1434
  continue;
1040
1435
  }
1041
1436
  const itemLocalPath = path.join(localPath, item);
@@ -1052,6 +1447,9 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1052
1447
  recordSftpFile(traversal, stats.size, depth, itemLocalPath);
1053
1448
  fileItems.push({ name: item, stats });
1054
1449
  }
1450
+ else {
1451
+ accumulator.addSkippedUnsupported(itemRelativePath);
1452
+ }
1055
1453
  }
1056
1454
  // 文件并发上传
1057
1455
  await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
@@ -1059,7 +1457,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1059
1457
  const itemRemotePath = path.posix.join(remotePath, name);
1060
1458
  const existed = await sftpExists(sftp, itemRemotePath);
1061
1459
  try {
1062
- await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp);
1460
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal);
1063
1461
  accumulator.addFile(stats.size, existed);
1064
1462
  }
1065
1463
  catch (error) {
@@ -1071,11 +1469,12 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1071
1469
  for (const item of subDirItems) {
1072
1470
  const itemLocalPath = path.join(localPath, item);
1073
1471
  const itemRemotePath = path.posix.join(remotePath, item);
1074
- const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1);
1472
+ const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item);
1075
1473
  accumulator.merge(result);
1076
1474
  }
1077
1475
  }
1078
1476
  finally {
1477
+ activeDirectories.delete(realPath);
1079
1478
  if (ownSftp) {
1080
1479
  sftp.end();
1081
1480
  }
@@ -1085,7 +1484,8 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1085
1484
  /**
1086
1485
  * 递归下载目录
1087
1486
  */
1088
- async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0) {
1487
+ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '') {
1488
+ throwIfAborted(signal);
1089
1489
  const accumulator = new DirectoryTransferAccumulator();
1090
1490
  recordSftpDirectory(traversal, depth, remotePath);
1091
1491
  const ownSftp = !sharedSftp;
@@ -1095,12 +1495,14 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1095
1495
  fs.mkdirSync(localPath, { recursive: true });
1096
1496
  }
1097
1497
  const items = await listDir(alias, remotePath, true, sftp);
1498
+ throwIfAborted(signal);
1098
1499
  // 分类:文件并发下载,目录串行递归
1099
1500
  const fileItems = [];
1100
1501
  const dirItems = [];
1101
1502
  const symlinkItems = [];
1102
1503
  for (const item of items) {
1103
- if (exclude && exclude.some((pattern) => matchPattern(item.name, pattern))) {
1504
+ const itemRelativePath = relativeBase ? `${relativeBase}/${item.name}` : item.name;
1505
+ if (matchesDirectoryExclude(itemRelativePath, exclude)) {
1104
1506
  continue;
1105
1507
  }
1106
1508
  if (item.isDirectory) {
@@ -1114,14 +1516,14 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1114
1516
  symlinkItems.push(item);
1115
1517
  }
1116
1518
  else {
1117
- console.warn(`[ssh_sync] skipping unknown item type: ${item.path}`);
1519
+ accumulator.addSkippedUnsupported(itemRelativePath);
1118
1520
  }
1119
1521
  }
1120
1522
  await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async (item) => {
1121
1523
  const itemLocalPath = path.join(localPath, item.name);
1122
1524
  const existed = fs.existsSync(itemLocalPath);
1123
1525
  try {
1124
- await downloadFile(alias, item.path, itemLocalPath, undefined, sftp);
1526
+ await downloadFile(alias, item.path, itemLocalPath, undefined, sftp, signal);
1125
1527
  accumulator.addFile(item.size, existed);
1126
1528
  }
1127
1529
  catch (error) {
@@ -1131,7 +1533,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1131
1533
  });
1132
1534
  for (const item of dirItems) {
1133
1535
  const itemLocalPath = path.join(localPath, item.name);
1134
- const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1);
1536
+ const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name);
1135
1537
  accumulator.merge(result);
1136
1538
  }
1137
1539
  for (const item of symlinkItems) {
@@ -1146,22 +1548,6 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1146
1548
  }
1147
1549
  return accumulator.toResult();
1148
1550
  }
1149
- /**
1150
- * 简单的模式匹配(支持 * 和 ?)
1151
- */
1152
- const matchPatternCache = new Map();
1153
- function matchPattern(name, pattern) {
1154
- let regex = matchPatternCache.get(pattern);
1155
- if (!regex) {
1156
- const regexPattern = pattern
1157
- .replace(/[.+^${}()|[\]\\]/g, '\\$&') // 转义特殊字符
1158
- .replace(/\*/g, '.*')
1159
- .replace(/\?/g, '.');
1160
- regex = new RegExp(`^${regexPattern}$`);
1161
- matchPatternCache.set(pattern, regex);
1162
- }
1163
- return regex.test(name);
1164
- }
1165
1551
  /**
1166
1552
  * 格式化权限字符串
1167
1553
  */