@pyrokine/mcp-ssh 2.0.2 → 2.2.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
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * SSH File Operations - 文件操作
3
3
  */
4
- import { execSync, spawnSync } from 'child_process';
4
+ import { spawn } from 'child_process';
5
+ import { createHash } from 'crypto';
5
6
  import * as fs from 'fs';
6
7
  import * as os from 'os';
7
8
  import * as path from 'path';
@@ -14,7 +15,57 @@ const S_IFREG = 0o100000;
14
15
  const S_IFLNK = 0o120000;
15
16
  // rsync 可用性缓存(per alias,连接存续期内不变,disconnect 时由 SessionManager 主动清理)
16
17
  const RSYNC_CACHE_TTL_MS = 5 * 60_000;
18
+ const LOCAL_PROCESS_OUTPUT_LIMIT = 200_000;
17
19
  const rsyncCache = new Map();
20
+ function appendLimitedOutput(current, chunk) {
21
+ if (current.length >= LOCAL_PROCESS_OUTPUT_LIMIT) {
22
+ return current;
23
+ }
24
+ return (current + chunk).slice(0, LOCAL_PROCESS_OUTPUT_LIMIT);
25
+ }
26
+ function runLocalProcess(command, args, timeout) {
27
+ return new Promise((resolve) => {
28
+ let stdout = '';
29
+ let stderr = '';
30
+ let settled = false;
31
+ let timedOut = false;
32
+ let killTimer;
33
+ const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
34
+ const timer = setTimeout(() => {
35
+ timedOut = true;
36
+ child.kill('SIGTERM');
37
+ killTimer = setTimeout(() => child.kill('SIGKILL'), 5000);
38
+ }, timeout);
39
+ child.stdout.on('data', (chunk) => {
40
+ stdout = appendLimitedOutput(stdout, chunk.toString('utf-8'));
41
+ });
42
+ child.stderr.on('data', (chunk) => {
43
+ stderr = appendLimitedOutput(stderr, chunk.toString('utf-8'));
44
+ });
45
+ child.on('error', (error) => {
46
+ if (settled) {
47
+ return;
48
+ }
49
+ settled = true;
50
+ clearTimeout(timer);
51
+ if (killTimer) {
52
+ clearTimeout(killTimer);
53
+ }
54
+ resolve({ status: null, stdout, stderr, error, timedOut });
55
+ });
56
+ child.on('close', (status) => {
57
+ if (settled) {
58
+ return;
59
+ }
60
+ settled = true;
61
+ clearTimeout(timer);
62
+ if (killTimer) {
63
+ clearTimeout(killTimer);
64
+ }
65
+ resolve({ status, stdout, stderr, timedOut });
66
+ });
67
+ });
68
+ }
18
69
  /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
19
70
  export function clearRsyncCache(alias) {
20
71
  if (alias === undefined) {
@@ -24,8 +75,39 @@ export function clearRsyncCache(alias) {
24
75
  rsyncCache.delete(alias);
25
76
  }
26
77
  }
78
+ function positiveIntegerEnv(name, defaultValue) {
79
+ const value = Number(process.env[name]);
80
+ return Number.isInteger(value) && value > 0 ? value : defaultValue;
81
+ }
27
82
  /** SFTP 并发上限,避免单 SSH session 上太多 channel */
28
- const SFTP_PARALLEL_LIMIT = Number(process.env.SSH_MCP_SFTP_PARALLEL) || 8;
83
+ const SFTP_PARALLEL_LIMIT = positiveIntegerEnv('SSH_MCP_SFTP_PARALLEL', 8);
84
+ const SFTP_SYNC_MAX_FILES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_FILES', 10_000);
85
+ const SFTP_SYNC_MAX_DIRECTORIES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DIRECTORIES', 2_000);
86
+ const SFTP_SYNC_MAX_DEPTH = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DEPTH', 64);
87
+ const SFTP_SYNC_MAX_BYTES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_BYTES', 10 * 1024 * 1024 * 1024);
88
+ function assertSftpTraversalBudget(state, depth, currentPath) {
89
+ if (depth > SFTP_SYNC_MAX_DEPTH) {
90
+ throw new Error(`SFTP sync traversal depth exceeded at ${currentPath} (max ${SFTP_SYNC_MAX_DEPTH})`);
91
+ }
92
+ if (state.files > SFTP_SYNC_MAX_FILES) {
93
+ throw new Error(`SFTP sync file count exceeded at ${currentPath} (max ${SFTP_SYNC_MAX_FILES})`);
94
+ }
95
+ if (state.directories > SFTP_SYNC_MAX_DIRECTORIES) {
96
+ throw new Error(`SFTP sync directory count exceeded at ${currentPath} (max ${SFTP_SYNC_MAX_DIRECTORIES})`);
97
+ }
98
+ if (state.bytes > SFTP_SYNC_MAX_BYTES) {
99
+ throw new Error(`SFTP sync byte budget exceeded at ${currentPath} (max ${SFTP_SYNC_MAX_BYTES})`);
100
+ }
101
+ }
102
+ function recordSftpDirectory(state, depth, currentPath) {
103
+ state.directories++;
104
+ assertSftpTraversalBudget(state, depth, currentPath);
105
+ }
106
+ function recordSftpFile(state, size, depth, currentPath) {
107
+ state.files++;
108
+ state.bytes += size;
109
+ assertSftpTraversalBudget(state, depth, currentPath);
110
+ }
29
111
  /**
30
112
  * 简单的并发控制:把异步任务限制在 limit 个 in-flight,串行入队
31
113
  */
@@ -57,27 +139,17 @@ async function runWithConcurrency(items, limit, worker) {
57
139
  * 格式:path.delimiter 分隔的绝对路径列表(POSIX `:`,Windows `;`),如 `/tmp:/home/user/work`
58
140
  * 安全性:路径会通过 fs.realpathSync 解析 symlink,防止 symlink 逃出白名单
59
141
  */
60
- function validateLocalPathAgainstAllowList(localPath) {
142
+ function quoteRsyncSshArg(value) {
143
+ return escapeShellArg(String(value));
144
+ }
145
+ function getAllowListStatus(localPath) {
61
146
  const allowEnv = process.env.SSH_MCP_FILE_OPS_ALLOW_DIRS;
62
- if (!allowEnv) {
63
- return;
64
- }
65
- const allowDirs = allowEnv
66
- .split(path.delimiter)
67
- .map((p) => p.trim())
68
- .filter((p) => p.length > 0);
147
+ const allowDirs = allowEnv?.split(path.delimiter).filter((item) => item.trim().length > 0) ?? [];
69
148
  if (allowDirs.length === 0) {
70
- return;
149
+ return { configured: false };
71
150
  }
72
- let resolvedLocal;
73
- try {
74
- // 路径不存在时,向上找到第一个存在的祖先 realpathSync 后再拼接剩余
75
- resolvedLocal = resolvePathOrAncestor(localPath);
76
- }
77
- catch (e) {
78
- throw new Error(`无法解析路径 ${localPath}: ${e instanceof Error ? e.message : String(e)}`);
79
- }
80
- const inAllowList = allowDirs.some((dir) => {
151
+ const resolvedLocal = resolvePathOrAncestor(localPath);
152
+ const matched = allowDirs.some((dir) => {
81
153
  try {
82
154
  const resolvedDir = fs.realpathSync(dir);
83
155
  const rel = path.relative(resolvedDir, resolvedLocal);
@@ -87,8 +159,12 @@ function validateLocalPathAgainstAllowList(localPath) {
87
159
  return false;
88
160
  }
89
161
  });
90
- if (!inAllowList) {
91
- throw new Error(`localPath "${localPath}" 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 白名单内(白名单: ${allowDirs.join(', ')})`);
162
+ return { configured: true, matched };
163
+ }
164
+ function validateLocalPathAgainstAllowList(localPath) {
165
+ const allowList = getAllowListStatus(localPath);
166
+ if (allowList.configured && !allowList.matched) {
167
+ throw new Error('localPath 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 允许目录内');
92
168
  }
93
169
  }
94
170
  function resolvePathOrAncestor(p) {
@@ -111,6 +187,28 @@ function resolvePathOrAncestor(p) {
111
187
  return absolute;
112
188
  }
113
189
  }
190
+ export function probeLocalPath(localPath) {
191
+ const expanded = expandTilde(localPath);
192
+ const resolvedPath = resolvePathOrAncestor(expanded);
193
+ const allowList = getAllowListStatus(expanded);
194
+ if (!fs.existsSync(expanded)) {
195
+ return { exists: false, inputPath: localPath, expandedPath: expanded, resolvedPath, allowList };
196
+ }
197
+ const stats = fs.lstatSync(expanded);
198
+ return {
199
+ exists: true,
200
+ inputPath: localPath,
201
+ expandedPath: expanded,
202
+ resolvedPath,
203
+ size: stats.size,
204
+ mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
205
+ mtimeMs: Math.round(stats.mtimeMs),
206
+ isSymlink: stats.isSymbolicLink(),
207
+ isDirectory: stats.isDirectory(),
208
+ isFile: stats.isFile(),
209
+ allowList,
210
+ };
211
+ }
114
212
  /**
115
213
  * sftp.stat 的 Promise 包装
116
214
  */
@@ -126,6 +224,24 @@ function sftpStat(sftp, remotePath) {
126
224
  });
127
225
  });
128
226
  }
227
+ async function sftpExists(sftp, remotePath) {
228
+ try {
229
+ await sftpStat(sftp, remotePath);
230
+ return true;
231
+ }
232
+ catch {
233
+ return false;
234
+ }
235
+ }
236
+ async function remoteExists(alias, remotePath) {
237
+ const sftp = await sessionManager.getSftp(alias);
238
+ try {
239
+ return await sftpExists(sftp, remotePath);
240
+ }
241
+ finally {
242
+ sftp.end();
243
+ }
244
+ }
129
245
  /**
130
246
  * 带进度追踪的流传输
131
247
  */
@@ -195,13 +311,19 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
195
311
  localPath = expandTilde(localPath);
196
312
  validateLocalPathAgainstAllowList(localPath);
197
313
  if (!fs.existsSync(localPath)) {
198
- throw new Error(`Local file not found: ${localPath}`);
314
+ throw new Error('Local file not found');
199
315
  }
200
316
  // 用 lstat 拒绝顶层 symlink,与 ssh_sync 顶层 followSymlinks=false 行为一致;
201
317
  // 单文件接口不引入 followSymlinks 选项,需走 symlink 请用 ssh_sync
202
318
  const lstats = fs.lstatSync(localPath);
203
319
  if (lstats.isSymbolicLink()) {
204
- throw new Error(`Refusing to upload symlink at top level: ${localPath} (use ssh_sync with followSymlinks=true to traverse)`);
320
+ throw new Error('Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)');
321
+ }
322
+ if (lstats.isDirectory()) {
323
+ throw new Error('UPLOAD_PATH_IS_DIRECTORY: localPath is a directory, use ssh_sync for directory upload');
324
+ }
325
+ if (!lstats.isFile()) {
326
+ throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
205
327
  }
206
328
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
207
329
  const totalSize = lstats.size;
@@ -222,36 +344,138 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
222
344
  }
223
345
  return pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp);
224
346
  }
347
+ export const DEFAULT_READ_FILE_MAX_BYTES = 1024 * 1024;
348
+ export const HARD_READ_FILE_MAX_BYTES = 16 * 1024 * 1024;
349
+ function normalizeReadFileOptions(options) {
350
+ if (typeof options === 'number') {
351
+ return { maxBytes: options };
352
+ }
353
+ return { ...options, maxBytes: options?.maxBytes ?? DEFAULT_READ_FILE_MAX_BYTES };
354
+ }
355
+ function parseLineRange(lineRange) {
356
+ const match = /^(?<start>\d+)(?:-(?<end>\d+))?$/.exec(lineRange.trim());
357
+ if (!match?.groups) {
358
+ throw new Error('lineRange 必须使用 "start-end" 或 "start" 格式,例如 "120-180"');
359
+ }
360
+ const start = Number(match.groups.start);
361
+ const end = match.groups.end ? Number(match.groups.end) : start;
362
+ if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start) {
363
+ throw new Error('lineRange 必须是从 1 开始且 end >= start 的行号范围');
364
+ }
365
+ return { start, end };
366
+ }
367
+ function validateReadFileOptions(options) {
368
+ if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) {
369
+ throw new Error('maxBytes 必须是正整数');
370
+ }
371
+ if (options.maxBytes > HARD_READ_FILE_MAX_BYTES) {
372
+ throw new Error(`maxBytes 不能超过 ${HARD_READ_FILE_MAX_BYTES},请使用 offset、tail 或 lineRange 分块读取`);
373
+ }
374
+ if (options.offset !== undefined && (!Number.isSafeInteger(options.offset) || options.offset < 0)) {
375
+ throw new Error('offset 必须是非负整数');
376
+ }
377
+ const selectors = [options.offset !== undefined, options.tail === true, options.lineRange !== undefined].filter(Boolean);
378
+ if (selectors.length > 1) {
379
+ throw new Error('offset、tail、lineRange 只能同时指定一个');
380
+ }
381
+ }
382
+ function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
383
+ return {
384
+ content: '',
385
+ size: totalSize,
386
+ total_size: totalSize,
387
+ read_offset: readOffset,
388
+ read_bytes: 0,
389
+ remaining_bytes: Math.max(0, totalSize - readOffset),
390
+ sample_kind: sampleKind,
391
+ truncated: readOffset < totalSize,
392
+ };
393
+ }
394
+ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange) {
395
+ const { start, end } = parseLineRange(lineRange);
396
+ const command = [
397
+ `awk 'NR>=${start} && NR<=${end} { print } NR>${end} { exit }'`,
398
+ escapeShellArg(remotePath),
399
+ '|',
400
+ 'head',
401
+ '-c',
402
+ String(maxBytes),
403
+ ].join(' ');
404
+ const result = await sessionManager.exec(alias, command, {
405
+ timeout: 30000,
406
+ useLoginUser: true,
407
+ maxOutputSize: maxBytes + 4096,
408
+ });
409
+ if (!result.success && result.stderr.trim().length > 0) {
410
+ throw new Error(result.stderr.trim());
411
+ }
412
+ const readBytes = Buffer.byteLength(result.stdout, 'utf-8');
413
+ return {
414
+ content: result.stdout,
415
+ size: totalSize,
416
+ total_size: totalSize,
417
+ read_offset: 0,
418
+ read_bytes: readBytes,
419
+ remaining_bytes: Math.max(0, totalSize - readBytes),
420
+ sample_kind: 'line_range',
421
+ truncated: readBytes >= maxBytes,
422
+ line_start: start,
423
+ line_end: end,
424
+ };
425
+ }
225
426
  /**
226
427
  * 读取远程文件内容
227
428
  */
228
- export async function readFile(alias, remotePath, maxBytes = 1024 * 1024 // 默认最大 1MB
229
- ) {
429
+ export async function readFile(alias, remotePath, options) {
430
+ const readOptions = normalizeReadFileOptions(options);
431
+ validateReadFileOptions(readOptions);
230
432
  const sftp = await sessionManager.getSftp(alias);
231
433
  const actualSize = (await sftpStat(sftp, remotePath)).size;
232
- const truncated = actualSize > maxBytes;
233
- // 处理空文件
434
+ if (readOptions.lineRange) {
435
+ sftp.end();
436
+ return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange);
437
+ }
234
438
  if (actualSize === 0) {
235
439
  sftp.end();
236
- return { content: '', size: 0, truncated: false };
440
+ return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full');
441
+ }
442
+ const readOffset = readOptions.tail
443
+ ? Math.max(0, actualSize - readOptions.maxBytes)
444
+ : Math.min(readOptions.offset ?? 0, actualSize);
445
+ const readSize = Math.min(actualSize - readOffset, readOptions.maxBytes);
446
+ const sampleKind = readOptions.tail
447
+ ? 'tail'
448
+ : readOptions.offset !== undefined
449
+ ? 'range'
450
+ : actualSize <= readOptions.maxBytes
451
+ ? 'full'
452
+ : 'head';
453
+ if (readSize === 0) {
454
+ sftp.end();
455
+ return emptyReadResult(actualSize, sampleKind, readOffset);
237
456
  }
238
- const readSize = Math.min(actualSize, maxBytes);
239
457
  return new Promise((resolve, reject) => {
240
458
  const chunks = [];
241
459
  const readStream = sftp.createReadStream(remotePath, {
242
- start: 0,
243
- end: readSize - 1,
460
+ start: readOffset,
461
+ end: readOffset + readSize - 1,
244
462
  });
245
463
  readStream.on('data', (chunk) => {
246
464
  chunks.push(chunk);
247
465
  });
248
466
  readStream.on('end', () => {
249
467
  sftp.end();
250
- const content = Buffer.concat(chunks).toString('utf-8');
468
+ const buffer = Buffer.concat(chunks);
469
+ const remainingBytes = Math.max(0, actualSize - readOffset - buffer.length);
251
470
  resolve({
252
- content,
471
+ content: buffer.toString('utf-8'),
253
472
  size: actualSize,
254
- truncated,
473
+ total_size: actualSize,
474
+ read_offset: readOffset,
475
+ read_bytes: buffer.length,
476
+ remaining_bytes: remainingBytes,
477
+ sample_kind: sampleKind,
478
+ truncated: readOffset > 0 || remainingBytes > 0,
255
479
  });
256
480
  });
257
481
  readStream.on('error', (err) => {
@@ -403,30 +627,29 @@ export async function checkRsync(alias) {
403
627
  * @param options 同步选项
404
628
  */
405
629
  export async function syncFiles(alias, localPath, remotePath, direction, options = {}) {
630
+ const startedAt = Date.now();
406
631
  localPath = expandTilde(localPath);
407
632
  validateLocalPathAgainstAllowList(localPath);
408
633
  const hasRsync = await checkRsync(alias);
409
- if (hasRsync) {
410
- return syncWithRsync(alias, localPath, remotePath, direction, options);
411
- }
412
- return syncWithSftp(alias, localPath, remotePath, direction, options);
634
+ const result = hasRsync
635
+ ? await syncWithRsync(alias, localPath, remotePath, direction, options)
636
+ : await syncWithSftp(alias, localPath, remotePath, direction, options);
637
+ return {
638
+ ...result,
639
+ transport: result.method,
640
+ direction,
641
+ dryRun: options.dryRun === true,
642
+ duration: Date.now() - startedAt,
643
+ };
413
644
  }
414
645
  /**
415
646
  * 使用 rsync 同步文件
416
647
  * 通过本地执行 rsync 连接到远程(需要密钥认证或 ssh-agent)
417
648
  */
418
649
  async function syncWithRsync(alias, localPath, remotePath, direction, options) {
419
- // 检查本地是否有 rsync
420
- let hasLocalRsync = false;
421
- try {
422
- const cmd = os.platform() === 'win32' ? 'where rsync' : 'which rsync';
423
- execSync(cmd, { stdio: 'pipe' });
424
- hasLocalRsync = true;
425
- }
426
- catch {
427
- // rsync 不可用,由 hasLocalRsync 标记处理
428
- }
429
- if (!hasLocalRsync) {
650
+ const checkCommand = os.platform() === 'win32' ? 'where' : 'which';
651
+ const checkResult = await runLocalProcess(checkCommand, ['rsync'], 10_000);
652
+ if (checkResult.status !== 0) {
430
653
  // 本地没有 rsync,回退到 SFTP
431
654
  return syncWithSftp(alias, localPath, remotePath, direction, options);
432
655
  }
@@ -436,8 +659,12 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
436
659
  if (!sessionInfo) {
437
660
  throw new Error(`Session '${alias}' not found`);
438
661
  }
662
+ // 密码认证无法透传给 rsync 的 ssh 子进程,直接走 SFTP
663
+ if (sessionInfo.authMethod === 'password') {
664
+ return syncWithSftp(alias, localPath, remotePath, direction, options);
665
+ }
439
666
  // 构建 rsync 参数
440
- const args = ['-avz', '--progress'];
667
+ const args = ['-avz', '--itemize-changes', '--stats'];
441
668
  if (options.delete) {
442
669
  args.push('--delete');
443
670
  }
@@ -459,7 +686,7 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
459
686
  }
460
687
  // path 安全校验:以 `-` 起始的路径会被 rsync 当成选项解析(即便有 `--` 兜底,也避免 OS/rsync 实现差异)
461
688
  if (localPath.startsWith('-') || remotePath.startsWith('-')) {
462
- throw new Error(`Invalid path: must not start with '-' (localPath=${localPath}, remotePath=${remotePath})`);
689
+ throw new Error('Invalid path: localPath and remotePath must not start with -');
463
690
  }
464
691
  // username/host 安全校验:拒绝 shell 元字符与 ssh 选项注入
465
692
  const sshIdentifierAllowed = /^[a-zA-Z0-9.:_-]+$/;
@@ -471,7 +698,21 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
471
698
  }
472
699
  // 构建 rsync argv(不用 shell=true,避免 username/host 含 shell 元字符时注入)
473
700
  // ProxyCommand=none 显式禁用 ssh-config 中可能定义的 ProxyCommand,防止外部命令注入
474
- const sshCmd = `ssh -p ${sessionInfo.port} -o StrictHostKeyChecking=accept-new -o BatchMode=yes -o ProxyCommand=none`;
701
+ const sshParts = [
702
+ 'ssh',
703
+ '-p',
704
+ String(sessionInfo.port),
705
+ '-o',
706
+ 'StrictHostKeyChecking=accept-new',
707
+ '-o',
708
+ 'BatchMode=yes',
709
+ '-o',
710
+ 'ProxyCommand=none',
711
+ ];
712
+ if (sessionInfo.keyPath) {
713
+ sshParts.push('-i', sessionInfo.keyPath);
714
+ }
715
+ const sshCmd = sshParts.map(quoteRsyncSshArg).join(' ');
475
716
  // remoteSpec 作为单独 argv 元素,不经 shell 解析
476
717
  const remoteSpec = `${sessionInfo.username}@${sessionInfo.host}:${remotePath}`;
477
718
  // 在 path 参数前插 `--`,明确剩余为路径而非选项(双重保险)
@@ -479,14 +720,12 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
479
720
  ? [...args, '-e', sshCmd, '--', localPath, remoteSpec]
480
721
  : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
481
722
  try {
482
- const result = spawnSync('rsync', rsyncArgs, {
483
- encoding: 'utf-8',
484
- timeout: 600000,
485
- stdio: ['pipe', 'pipe', 'pipe'],
486
- });
723
+ const result = await runLocalProcess('rsync', rsyncArgs, 600000);
487
724
  if (result.error || result.status !== 0) {
488
- const stderr = (result.stderr ?? '').trim();
489
- const reason = result.error?.message ?? `exit code ${result.status}`;
725
+ const stderr = result.stderr.trim();
726
+ const reason = result.timedOut
727
+ ? 'timed out after 600000ms'
728
+ : (result.error?.message ?? `exit code ${result.status}`);
490
729
  const fallback = await syncWithSftp(alias, localPath, remotePath, direction, options);
491
730
  const warning = `rsync 失败原因: ${reason}${stderr ? ` | stderr: ${stderr}` : ''} | 已 fallback 到 SFTP(性能可能较差)`;
492
731
  console.warn(`[mcp-ssh] ${warning}`);
@@ -495,22 +734,23 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
495
734
  output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
496
735
  };
497
736
  }
498
- const output = result.stdout ?? '';
499
- // 解析 rsync 输出统计文件数
500
- const lines = output.split('\n');
501
- let filesTransferred = 0;
502
- for (const line of lines) {
503
- if (line.trim() &&
504
- !line.startsWith('sending') &&
505
- !line.startsWith('receiving') &&
506
- !line.startsWith('total')) {
507
- filesTransferred++;
508
- }
509
- }
737
+ const output = result.stdout;
738
+ const stats = parseRsyncStats(output);
739
+ const filesTransferred = stats.added + stats.updated;
510
740
  return {
511
741
  success: true,
512
742
  method: 'rsync',
513
743
  filesTransferred,
744
+ stats,
745
+ commandSummary: {
746
+ tool: 'rsync',
747
+ dryRun: options.dryRun === true,
748
+ delete: options.delete === true,
749
+ recursive: options.recursive !== false,
750
+ followSymlinks: options.followSymlinks === true,
751
+ excludeCount: options.exclude?.length ?? 0,
752
+ usedKeyPath: Boolean(sessionInfo.keyPath),
753
+ },
514
754
  output,
515
755
  };
516
756
  }
@@ -525,7 +765,51 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
525
765
  };
526
766
  }
527
767
  }
528
- function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0) {
768
+ class DirectoryTransferAccumulator {
769
+ result = {
770
+ fileCount: 0,
771
+ totalSize: 0,
772
+ skippedSymlinks: 0,
773
+ added: 0,
774
+ updated: 0,
775
+ failed: 0,
776
+ };
777
+ addFile(size, existed) {
778
+ this.result.fileCount++;
779
+ this.result.totalSize += size;
780
+ if (existed) {
781
+ this.result.updated++;
782
+ }
783
+ else {
784
+ this.result.added++;
785
+ }
786
+ }
787
+ addSkippedSymlink() {
788
+ this.result.skippedSymlinks++;
789
+ }
790
+ addFailed() {
791
+ this.result.failed++;
792
+ }
793
+ merge(result) {
794
+ this.result.fileCount += result.fileCount;
795
+ this.result.totalSize += result.totalSize;
796
+ this.result.skippedSymlinks += result.skippedSymlinks;
797
+ this.result.added += result.added;
798
+ this.result.updated += result.updated;
799
+ this.result.failed += result.failed;
800
+ }
801
+ toResult() {
802
+ return { ...this.result };
803
+ }
804
+ }
805
+ function buildDirectorySyncResult(result, warnings) {
806
+ return buildSyncResult(result.fileCount, result.totalSize, warnings, result.skippedSymlinks, {
807
+ added: result.added,
808
+ updated: result.updated,
809
+ failed: result.failed,
810
+ });
811
+ }
812
+ function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0, stats) {
529
813
  if (skippedSymlinks > 0) {
530
814
  warnings.push(`skipped ${skippedSymlinks} symlink(s) (set followSymlinks=true to traverse)`);
531
815
  }
@@ -535,18 +819,106 @@ function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0) {
535
819
  filesTransferred: fileCount,
536
820
  bytesTransferred: totalSize,
537
821
  skippedSymlinks: skippedSymlinks > 0 ? skippedSymlinks : undefined,
822
+ stats: {
823
+ added: stats?.added ?? 0,
824
+ updated: stats?.updated ?? fileCount,
825
+ deleted: stats?.deleted ?? 0,
826
+ skipped: stats?.skipped ?? skippedSymlinks,
827
+ failed: stats?.failed ?? 0,
828
+ },
538
829
  output: warnings.length ? `Warning: ${warnings.join('; ')}` : undefined,
539
830
  };
540
831
  }
832
+ function parseRsyncStats(output) {
833
+ const stats = { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 0 };
834
+ for (const line of output.split('\n')) {
835
+ if (line.startsWith('*deleting')) {
836
+ stats.deleted++;
837
+ }
838
+ else if (/^>f\+{9}\s/.test(line)) {
839
+ stats.added++;
840
+ }
841
+ else if (/^>f/.test(line)) {
842
+ stats.updated++;
843
+ }
844
+ }
845
+ const transferredMatch = output.match(/Number of regular files transferred:\s*(?<count>\d+)/);
846
+ if (transferredMatch?.groups && stats.added + stats.updated === 0) {
847
+ stats.updated = Number(transferredMatch.groups.count);
848
+ }
849
+ return stats;
850
+ }
851
+ function hashLocalFile(filePath) {
852
+ return new Promise((resolve, reject) => {
853
+ const hash = createHash('sha256');
854
+ const stream = fs.createReadStream(filePath);
855
+ stream.on('data', (chunk) => hash.update(chunk));
856
+ stream.on('error', reject);
857
+ stream.on('end', () => resolve(hash.digest('hex')));
858
+ });
859
+ }
860
+ async function hashRemoteFile(alias, remotePath) {
861
+ const result = await sessionManager.exec(alias, `sha256sum ${escapeShellArg(remotePath)} | awk '{print $1}'`, {
862
+ timeout: 30000,
863
+ useLoginUser: true,
864
+ maxOutputSize: 4096,
865
+ });
866
+ if (!result.success) {
867
+ return undefined;
868
+ }
869
+ const digest = result.stdout.trim().split(/\s+/)[0];
870
+ return /^[a-fA-F0-9]{64}$/.test(digest) ? digest : undefined;
871
+ }
872
+ async function buildSingleFileVerification(alias, localPath, remotePath, direction) {
873
+ const localStats = fs.statSync(localPath);
874
+ const remoteInfo = await getFileInfo(alias, remotePath);
875
+ const [localSha256, remoteSha256] = await Promise.all([hashLocalFile(localPath), hashRemoteFile(alias, remotePath)]);
876
+ return {
877
+ kind: 'single_file',
878
+ direction,
879
+ hashAlgorithm: 'sha256',
880
+ hashMatch: remoteSha256 ? localSha256 === remoteSha256 : undefined,
881
+ local: {
882
+ size: localStats.size,
883
+ mode: (localStats.mode & 0o777).toString(8),
884
+ mtimeMs: Math.round(localStats.mtimeMs),
885
+ sha256: localSha256,
886
+ },
887
+ remote: {
888
+ size: remoteInfo.size,
889
+ permissions: remoteInfo.permissions,
890
+ owner: remoteInfo.owner,
891
+ group: remoteInfo.group,
892
+ mtime: remoteInfo.mtime,
893
+ sha256: remoteSha256,
894
+ },
895
+ };
896
+ }
541
897
  async function syncWithSftp(alias, localPath, remotePath, direction, options) {
542
898
  const warnings = [];
543
899
  if (options.delete) {
544
900
  warnings.push('delete option is not supported in SFTP mode (requires rsync)');
545
901
  }
546
902
  if (options.dryRun) {
903
+ const localExists = fs.existsSync(localPath);
904
+ const localStats = localExists ? fs.lstatSync(localPath) : undefined;
905
+ const remoteTargetExists = await remoteExists(alias, remotePath).catch(() => false);
547
906
  return {
548
907
  success: true,
549
908
  method: 'sftp',
909
+ commandSummary: {
910
+ dryRun: true,
911
+ direction,
912
+ recursive: options.recursive !== false,
913
+ followSymlinks: options.followSymlinks === true,
914
+ deleteRequested: options.delete === true,
915
+ excludeCount: options.exclude?.length ?? 0,
916
+ localExists,
917
+ localIsDirectory: localStats?.isDirectory(),
918
+ localIsSymlink: localStats?.isSymbolicLink(),
919
+ remoteTargetExists,
920
+ wouldOverwrite: direction === 'upload' ? remoteTargetExists : localExists,
921
+ },
550
922
  output: 'Dry run mode: would transfer files via SFTP' +
551
923
  (warnings.length ? `. Warning: ${warnings.join('; ')}` : ''),
552
924
  };
@@ -555,28 +927,46 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
555
927
  if (direction === 'upload') {
556
928
  const stats = options.followSymlinks ? fs.statSync(localPath) : fs.lstatSync(localPath);
557
929
  if (stats.isSymbolicLink()) {
558
- throw new Error(`Refusing to upload symlink at top level: ${localPath} (set followSymlinks=true to traverse)`);
930
+ return {
931
+ success: false,
932
+ method: 'sftp',
933
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
934
+ output: 'Refusing to upload symlink at top level (set followSymlinks=true to traverse)',
935
+ };
559
936
  }
560
937
  if (stats.isDirectory() && options.recursive !== false) {
561
- const { fileCount, totalSize, skippedSymlinks } = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false);
562
- return buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks);
938
+ const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0);
939
+ return buildDirectorySyncResult(result, warnings);
563
940
  }
941
+ const existed = await remoteExists(alias, remotePath);
564
942
  const { size } = await uploadFile(alias, localPath, remotePath);
565
- return buildSyncResult(1, size, warnings);
943
+ return {
944
+ ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
945
+ verification: await buildSingleFileVerification(alias, localPath, remotePath, 'upload'),
946
+ };
566
947
  }
567
948
  // download
568
949
  const info = await getFileInfo(alias, remotePath);
569
950
  if (info.isDirectory && options.recursive !== false) {
570
- const { fileCount, totalSize, skippedSymlinks } = await downloadDirectory(alias, remotePath, localPath, options.exclude);
571
- return buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks);
951
+ const result = await downloadDirectory(alias, remotePath, localPath, options.exclude, undefined, {
952
+ files: 0,
953
+ directories: 0,
954
+ bytes: 0,
955
+ }, 0);
956
+ return buildDirectorySyncResult(result, warnings);
572
957
  }
958
+ const existed = fs.existsSync(localPath);
573
959
  const { size } = await downloadFile(alias, remotePath, localPath);
574
- return buildSyncResult(1, size, warnings);
960
+ return {
961
+ ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
962
+ verification: await buildSingleFileVerification(alias, localPath, remotePath, 'download'),
963
+ };
575
964
  }
576
965
  catch (err) {
577
966
  return {
578
967
  success: false,
579
968
  method: 'sftp',
969
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
580
970
  output: err instanceof Error ? err.message : String(err),
581
971
  };
582
972
  }
@@ -584,15 +974,12 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
584
974
  /**
585
975
  * 递归上传目录
586
976
  */
587
- async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false) {
588
- let fileCount = 0;
589
- let totalSize = 0;
590
- let skippedSymlinks = 0;
591
- // 顶层调用时开启一个 SFTP 会话,递归调用复用
977
+ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0) {
978
+ const accumulator = new DirectoryTransferAccumulator();
979
+ recordSftpDirectory(traversal, depth, localPath);
592
980
  const ownSftp = !sharedSftp;
593
981
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
594
982
  try {
595
- // 确保远程目录存在
596
983
  await mkdir(alias, remotePath, true);
597
984
  const items = fs.readdirSync(localPath);
598
985
  // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
@@ -606,13 +993,14 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
606
993
  const stats = followSymlinks ? fs.statSync(itemLocalPath) : fs.lstatSync(itemLocalPath);
607
994
  if (!followSymlinks && stats.isSymbolicLink()) {
608
995
  console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
609
- skippedSymlinks++;
996
+ accumulator.addSkippedSymlink();
610
997
  continue;
611
998
  }
612
999
  if (stats.isDirectory()) {
613
1000
  subDirItems.push(item);
614
1001
  }
615
1002
  else if (stats.isFile()) {
1003
+ recordSftpFile(traversal, stats.size, depth, itemLocalPath);
616
1004
  fileItems.push({ name: item, stats });
617
1005
  }
618
1006
  }
@@ -620,18 +1008,22 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
620
1008
  await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
621
1009
  const itemLocalPath = path.join(localPath, name);
622
1010
  const itemRemotePath = path.posix.join(remotePath, name);
623
- await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp);
624
- fileCount++;
625
- totalSize += stats.size;
1011
+ const existed = await sftpExists(sftp, itemRemotePath);
1012
+ try {
1013
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp);
1014
+ accumulator.addFile(stats.size, existed);
1015
+ }
1016
+ catch (error) {
1017
+ accumulator.addFailed();
1018
+ throw error;
1019
+ }
626
1020
  });
627
1021
  // 子目录串行递归
628
1022
  for (const item of subDirItems) {
629
1023
  const itemLocalPath = path.join(localPath, item);
630
1024
  const itemRemotePath = path.posix.join(remotePath, item);
631
- const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks);
632
- fileCount += result.fileCount;
633
- totalSize += result.totalSize;
634
- skippedSymlinks += result.skippedSymlinks;
1025
+ const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1);
1026
+ accumulator.merge(result);
635
1027
  }
636
1028
  }
637
1029
  finally {
@@ -639,20 +1031,17 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
639
1031
  sftp.end();
640
1032
  }
641
1033
  }
642
- return { fileCount, totalSize, skippedSymlinks };
1034
+ return accumulator.toResult();
643
1035
  }
644
1036
  /**
645
1037
  * 递归下载目录
646
1038
  */
647
- async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp) {
648
- let fileCount = 0;
649
- let totalSize = 0;
650
- let skippedSymlinks = 0;
651
- // 顶层调用时开启一个 SFTP 会话,递归调用复用
1039
+ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0) {
1040
+ const accumulator = new DirectoryTransferAccumulator();
1041
+ recordSftpDirectory(traversal, depth, remotePath);
652
1042
  const ownSftp = !sharedSftp;
653
1043
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
654
1044
  try {
655
- // 确保本地目录存在
656
1045
  if (!fs.existsSync(localPath)) {
657
1046
  fs.mkdirSync(localPath, { recursive: true });
658
1047
  }
@@ -669,6 +1058,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
669
1058
  dirItems.push(item);
670
1059
  }
671
1060
  else if (item.isFile) {
1061
+ recordSftpFile(traversal, item.size, depth, item.path);
672
1062
  fileItems.push(item);
673
1063
  }
674
1064
  else if (item.isSymlink) {
@@ -680,20 +1070,24 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
680
1070
  }
681
1071
  await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async (item) => {
682
1072
  const itemLocalPath = path.join(localPath, item.name);
683
- await downloadFile(alias, item.path, itemLocalPath, undefined, sftp);
684
- fileCount++;
685
- totalSize += item.size;
1073
+ const existed = fs.existsSync(itemLocalPath);
1074
+ try {
1075
+ await downloadFile(alias, item.path, itemLocalPath, undefined, sftp);
1076
+ accumulator.addFile(item.size, existed);
1077
+ }
1078
+ catch (error) {
1079
+ accumulator.addFailed();
1080
+ throw error;
1081
+ }
686
1082
  });
687
1083
  for (const item of dirItems) {
688
1084
  const itemLocalPath = path.join(localPath, item.name);
689
- const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp);
690
- fileCount += result.fileCount;
691
- totalSize += result.totalSize;
692
- skippedSymlinks += result.skippedSymlinks;
1085
+ const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1);
1086
+ accumulator.merge(result);
693
1087
  }
694
1088
  for (const item of symlinkItems) {
695
1089
  console.warn(`[ssh_sync] skipping remote symlink: ${item.path}`);
696
- skippedSymlinks++;
1090
+ accumulator.addSkippedSymlink();
697
1091
  }
698
1092
  }
699
1093
  finally {
@@ -701,7 +1095,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
701
1095
  sftp.end();
702
1096
  }
703
1097
  }
704
- return { fileCount, totalSize, skippedSymlinks };
1098
+ return accumulator.toResult();
705
1099
  }
706
1100
  /**
707
1101
  * 简单的模式匹配(支持 * 和 ?)