@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/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  English | [中文](README_zh.md)
4
4
 
5
- A comprehensive SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
5
+ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
6
6
 
7
7
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
8
  [![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)
@@ -88,7 +88,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
88
88
  }
89
89
  ```
90
90
 
91
- ## Available Tools (29 tools)
91
+ ## Available Tools (30 tools)
92
92
 
93
93
  ### Connection Management
94
94
 
@@ -110,6 +110,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
110
110
  | `ssh_exec_batch` | Execute multiple commands sequentially |
111
111
  | `ssh_exec_parallel` | Execute command on multiple hosts in parallel |
112
112
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
113
+ | `ssh_exec_script` | Upload and run a temporary remote script |
113
114
 
114
115
  ### File Operations
115
116
 
@@ -196,18 +197,48 @@ Execute the same command on multiple connected hosts:
196
197
  ### Basic: Connect and Execute
197
198
 
198
199
  ```
199
- ssh_connect(host="192.168.1.100", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
200
+ ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
200
201
  ssh_exec(alias="myserver", command="ls -la /home")
201
202
  ssh_disconnect(alias="myserver")
202
203
  ```
203
204
 
205
+ ### Connection Templates and runAs
206
+
207
+ Templates can be provided through `SSH_MCP_TEMPLATES` or `~/.mcp-ssh/templates.json`. Explicit tool arguments override
208
+ template values.
209
+
210
+ ```json
211
+ {
212
+ "app-dev": {
213
+ "host": "<server-host>",
214
+ "port": 22,
215
+ "user": "root",
216
+ "runAs": "appuser",
217
+ "defaultEnv": {
218
+ "APP_ENV": "dev"
219
+ }
220
+ }
221
+ }
222
+ ```
223
+
224
+ ```
225
+ ssh_connect(template="app-dev", alias="app-dev")
226
+ ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
227
+ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
228
+ ```
229
+
230
+ `ssh_connect` returns `identity`, `loginUser`, `runAs`, `reused`, `defaultEnvKeys`, `envKeys`, and `reusableSessions`
231
+ for already connected aliases with the same `user@host:port` identity. Reusing an alias for a different identity is
232
+ rejected with the existing and requested identities. Missing templates include available template names when they can be
233
+ loaded. Missing `configHost` returns SSH config candidates and suggests `ssh_config_list`.
234
+
204
235
  ### Jump Host (Bastion)
205
236
 
206
237
  Connect to internal server via jump host:
207
238
 
208
239
  ```
209
240
  ssh_connect(
210
- host="10.0.0.5",
241
+ host="<internal-host>",
211
242
  user="root",
212
243
  keyPath="/home/.ssh/id_rsa",
213
244
  alias="internal",
@@ -224,7 +255,7 @@ ssh_connect(
224
255
  Perfect for scenarios where you SSH as root but need to run commands as another user:
225
256
 
226
257
  ```
227
- 1. ssh_connect(host="192.168.1.100", user="root", password="xxx", alias="server")
258
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
228
259
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
229
260
  // Output: appuser
230
261
  ```
@@ -233,6 +264,13 @@ By default, shell profile is loaded to ensure environment variables are availabl
233
264
  non-interactive shell which doesn't execute rc files). Supports bash (`.bashrc`), zsh (`.zshrc`), and other shells (
234
265
  `.profile`). Disable with `loadProfile=false` if not needed.
235
266
 
267
+ `ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
268
+ `resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
269
+ hints. Large output returns `stdoutHead`, `stdoutTail`, `stderrHead`, `stderrTail`, and `recommendedReadCommand`.
270
+ Timeout errors include the same head/tail fields from output produced before the timeout. Commands with destructive,
271
+ process-control, service-control, credential-bearing, unbounded `find`, recursive `grep`, long pipelines, background
272
+ tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` block with `categories` and `signals`.
273
+
236
274
  ### Interactive Commands (PTY mode)
237
275
 
238
276
  For commands that need a terminal:
@@ -241,13 +279,32 @@ For commands that need a terminal:
241
279
  ssh_exec(alias="server", command="top -b -n 1", pty=true)
242
280
  ```
243
281
 
282
+ ### Temporary Script Execution and Log Query Recipe
283
+
284
+ ```
285
+ ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs="appuser")
286
+ ```
287
+
288
+ Use `ssh_exec_script` for log discovery and filtering, then use `ssh_read_file` to read large result files in chunks:
289
+
290
+ ```
291
+ ssh_exec_script(
292
+ alias="server",
293
+ script="find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' | sort -nr | head -20 > /tmp/mcp-log-files.txt\ngrep -n -I -F 'ERROR' /var/log/app/*.log | head -100 > /tmp/mcp-log-errors.txt",
294
+ timeout=30000
295
+ )
296
+ ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
297
+ ```
298
+
299
+ This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
300
+
244
301
  ### With Environment Variables
245
302
 
246
303
  ```
247
304
  ssh_connect(
248
- host="192.168.1.100",
305
+ host="<server-host>",
249
306
  user="root",
250
- password="xxx",
307
+ keyPath="/home/.ssh/id_rsa",
251
308
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
252
309
  )
253
310
  ```
@@ -258,9 +315,9 @@ No need to manage connections for single commands:
258
315
 
259
316
  ```
260
317
  ssh_quick_exec(
261
- host="192.168.1.100",
318
+ host="<server-host>",
262
319
  user="root",
263
- password="xxx",
320
+ keyPath="/home/.ssh/id_rsa",
264
321
  command="uptime"
265
322
  )
266
323
  ```
@@ -270,14 +327,26 @@ ssh_quick_exec(
270
327
  ```
271
328
  // Upload
272
329
  ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
330
+ ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json", atomic=true, verifySize=true, verifyMd5=true, verifyMode="0644")
331
+ // Directories return UPLOAD_PATH_IS_DIRECTORY. Large files complete with a suggestion and recommended ssh_sync call.
273
332
 
274
333
  // Download
275
334
  ssh_download(alias="server", remotePath="/var/log/app.log", localPath="/tmp/app.log")
276
335
 
277
336
  // Read file content
278
337
  ssh_read_file(alias="server", remotePath="/etc/hosts")
338
+ ssh_read_file(alias="server", remotePath="/var/log/app.log", tail=true, maxBytes=65536)
339
+ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, maxBytes=65536)
340
+ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
279
341
  ```
280
342
 
343
+ `ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
344
+ verification checks. `atomic=true` uploads to a same-directory temporary file, then renames it to the target path.
345
+ `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit post-transfer checks.
346
+ `ssh_read_file` defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`,
347
+ `read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
348
+ from a head, tail, byte range, or line range sample.
349
+
281
350
  ### Directory Sync (with rsync)
282
351
 
283
352
  Smart sync automatically detects rsync availability and uses it for efficient incremental transfer:
@@ -313,7 +382,9 @@ ssh_sync(
313
382
  ssh_sync(..., dryRun=true)
314
383
  ```
315
384
 
316
- If rsync is not available on remote or local, it automatically falls back to SFTP.
385
+ If rsync is not available on remote or local, it automatically falls back to SFTP. Sync responses include `transport`,
386
+ `duration`, `dryRun`, `stats`, and `commandSummary`. SFTP single-file transfers include a `verification` object with
387
+ local and remote size, mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`.
317
388
 
318
389
  **Note**: rsync mode uses SSH key/agent authentication and sets `StrictHostKeyChecking=accept-new`.
319
390
  If you require strict host key verification and management, use SFTP mode instead.
@@ -329,7 +400,7 @@ ssh_pty_start(alias="server", command="top", rows=24, cols=80)
329
400
 
330
401
  // 2. Read current output (polling)
331
402
  ssh_pty_read(ptyId="pty_1_1234567890")
332
- // Returns: { "data": "top - 10:30:15 up 5 days...", "active": true }
403
+ // Returns: { "data": "top - 10:30:15 up 5 days...", "active": true, "unreadRawBytes": 123, "foregroundProcess": "top" }
333
404
 
334
405
  // 3. Send commands (e.g., quit top)
335
406
  ssh_pty_write(ptyId="pty_1_1234567890", data="q")
@@ -354,6 +425,9 @@ ssh_pty_read(ptyId="pty_1_xxx")
354
425
  ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
355
426
  ```
356
427
 
428
+ `ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
429
+ `rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
430
+
357
431
  Common control sequences:
358
432
 
359
433
  - Enter: `\r` or `\n`
@@ -368,8 +442,8 @@ Common control sequences:
368
442
  Access remote internal services or expose local services:
369
443
 
370
444
  ```
371
- // Local forward: access remote MySQL (10.0.0.5:3306) via localhost:13306
372
- ssh_forward_local(alias="server", localPort=13306, remoteHost="10.0.0.5", remotePort=3306)
445
+ // Local forward: access remote MySQL (<service-host>:3306) via localhost:13306
446
+ ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>", remotePort=3306)
373
447
 
374
448
  // Remote forward: expose local dev server (3000) to remote port 8080
375
449
  ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
@@ -393,17 +467,24 @@ ssh_forward_close(forwardId="fwd_1_xxx")
393
467
  | `keyPath` | string | - | Path to SSH private key |
394
468
  | `port` | number | 22 | SSH port |
395
469
  | `alias` | string | auto-generated | Connection alias for reference |
470
+ | `template` | string | - | Template name |
396
471
  | `env` | object | - | Environment variables |
472
+ | `defaultEnv` | object | - | Default env for this session |
473
+ | `runAs` | string | - | Default execution user |
397
474
  | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
398
475
 
399
476
  ### Exec Options
400
477
 
401
- | Option | Type | Default | Description |
402
- |-----------|---------|---------|------------------------------------------|
403
- | `timeout` | number | 30000 | Command timeout in ms |
404
- | `cwd` | string | - | Working directory |
405
- | `env` | object | - | Additional environment variables |
406
- | `pty` | boolean | false | Enable PTY mode for interactive commands |
478
+ | Option | Type | Default | Description |
479
+ |-----------------|---------|---------------|--------------------------------------------|
480
+ | `timeout` | number | 30000 | Command timeout in ms |
481
+ | `cwd` | string | - | Working directory |
482
+ | `env` | object | - | Additional environment variables |
483
+ | `pty` | boolean | false | Enable PTY mode for interactive commands |
484
+ | `maxOutputSize` | number | 10 MB chars | Output truncation limit |
485
+ | `runAs` | string | session runAs | Per-command execution user |
486
+ | `useLoginUser` | boolean | false | Skip session-level runAs |
487
+ | `loadProfile` | boolean | true | Load target user's shell profile for runAs |
407
488
 
408
489
  ## Security
409
490
 
package/README_zh.md CHANGED
@@ -88,7 +88,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
88
88
  }
89
89
  ```
90
90
 
91
- ## 可用工具(29 个)
91
+ ## 可用工具(30 个)
92
92
 
93
93
  ### 连接管理
94
94
 
@@ -110,6 +110,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
110
110
  | `ssh_exec_batch` | 批量执行多条命令 |
111
111
  | `ssh_exec_parallel` | 在多台主机上并行执行命令 |
112
112
  | `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
113
+ | `ssh_exec_script` | 上传并执行远端临时脚本 |
113
114
 
114
115
  ### 文件操作
115
116
 
@@ -196,18 +197,46 @@ ssh_connect(configHost="myserver", configPath="/custom/path/config")
196
197
  ### 基础:连接和执行
197
198
 
198
199
  ```
199
- ssh_connect(host="192.168.1.100", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
200
+ ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
200
201
  ssh_exec(alias="myserver", command="ls -la /home")
201
202
  ssh_disconnect(alias="myserver")
202
203
  ```
203
204
 
205
+ ### 连接模板和 runAs
206
+
207
+ 模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json` 提供,工具显式参数优先于模板值
208
+
209
+ ```json
210
+ {
211
+ "app-dev": {
212
+ "host": "<server-host>",
213
+ "port": 22,
214
+ "user": "root",
215
+ "runAs": "appuser",
216
+ "defaultEnv": {
217
+ "APP_ENV": "dev"
218
+ }
219
+ }
220
+ }
221
+ ```
222
+
223
+ ```
224
+ ssh_connect(template="app-dev", alias="app-dev")
225
+ ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
226
+ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
227
+ ```
228
+
229
+ `ssh_connect` 返回 `identity`、`loginUser`、`runAs`、`reused`、`defaultEnvKeys`、`envKeys`,以及同一 `user@host:port` identity
230
+ 下已连接 alias 的 `reusableSessions`,同一个 alias 连接到不同 identity 会被拒绝,并返回现有 identity 和请求
231
+ identity,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
232
+
204
233
  ### 跳板机
205
234
 
206
235
  通过跳板机连接内网服务器:
207
236
 
208
237
  ```
209
238
  ssh_connect(
210
- host="10.0.0.5",
239
+ host="<internal-host>",
211
240
  user="root",
212
241
  keyPath="/home/.ssh/id_rsa",
213
242
  alias="internal",
@@ -224,7 +253,7 @@ ssh_connect(
224
253
  适用于 SSH 以 root 登录,但需要以其他用户执行命令的场景:
225
254
 
226
255
  ```
227
- 1. ssh_connect(host="192.168.1.100", user="root", password="xxx", alias="server")
256
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
228
257
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
229
258
  // 输出: appuser
230
259
  ```
@@ -232,6 +261,12 @@ ssh_connect(
232
261
  默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
233
262
  )及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
234
263
 
264
+ `ssh_exec` 和 `ssh_exec_as_user` 返回执行元数据:`loginUser`、`effectiveUser`、`identity`、`cwd`、`resolvedCwd`、`shell`、
265
+ `profileLoaded`、`envInjectedKeys`、`failureKind`、`stdoutBytes`、`stderrBytes` 和截断提示,大输出会返回 `stdoutHead`、
266
+ `stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`,timeout 错误也包含超时前已经产生的 head/tail 输出,包含
267
+ destructive、process-control、service-control、credential-bearing、未限制 `find`、递归 `grep`、长管道、后台任务、直接
268
+ `su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
269
+
235
270
  ### 交互式命令(PTY 模式)
236
271
 
237
272
  用于需要终端的命令:
@@ -240,13 +275,32 @@ ssh_connect(
240
275
  ssh_exec(alias="server", command="top -b -n 1", pty=true)
241
276
  ```
242
277
 
278
+ ### 临时脚本执行和日志查询 recipe
279
+
280
+ ```
281
+ ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs="appuser")
282
+ ```
283
+
284
+ 日志发现和过滤使用 `ssh_exec_script`,大结果再用 `ssh_read_file` 分块读取:
285
+
286
+ ```
287
+ ssh_exec_script(
288
+ alias="server",
289
+ script="find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' | sort -nr | head -20 > /tmp/mcp-log-files.txt\ngrep -n -I -F 'ERROR' /var/log/app/*.log | head -100 > /tmp/mcp-log-errors.txt",
290
+ timeout=30000
291
+ )
292
+ ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
293
+ ```
294
+
295
+ 日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具
296
+
243
297
  ### 设置环境变量
244
298
 
245
299
  ```
246
300
  ssh_connect(
247
- host="192.168.1.100",
301
+ host="<server-host>",
248
302
  user="root",
249
- password="xxx",
303
+ keyPath="/home/.ssh/id_rsa",
250
304
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
251
305
  )
252
306
  ```
@@ -257,9 +311,9 @@ ssh_connect(
257
311
 
258
312
  ```
259
313
  ssh_quick_exec(
260
- host="192.168.1.100",
314
+ host="<server-host>",
261
315
  user="root",
262
- password="xxx",
316
+ keyPath="/home/.ssh/id_rsa",
263
317
  command="uptime"
264
318
  )
265
319
  ```
@@ -269,14 +323,24 @@ ssh_quick_exec(
269
323
  ```
270
324
  // 上传
271
325
  ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
326
+ ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json", atomic=true, verifySize=true, verifyMd5=true, verifyMode="0644")
327
+ // 目录返回 UPLOAD_PATH_IS_DIRECTORY,大文件上传成功后会提示优先使用 ssh_sync,并返回推荐调用
272
328
 
273
329
  // 下载
274
330
  ssh_download(alias="server", remotePath="/var/log/app.log", localPath="/tmp/app.log")
275
331
 
276
332
  // 读取文件内容
277
333
  ssh_read_file(alias="server", remotePath="/etc/hosts")
334
+ ssh_read_file(alias="server", remotePath="/var/log/app.log", tail=true, maxBytes=65536)
335
+ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, maxBytes=65536)
336
+ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
278
337
  ```
279
338
 
339
+ `ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,再
340
+ rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,`ssh_read_file`
341
+ 默认读取 1 MiB,`maxBytes` 超过 16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、
342
+ `remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
343
+
280
344
  ### 目录同步(rsync)
281
345
 
282
346
  智能同步会自动检测 rsync 可用性,使用 rsync 进行高效增量传输:
@@ -312,7 +376,9 @@ ssh_sync(
312
376
  ssh_sync(..., dryRun=true)
313
377
  ```
314
378
 
315
- 如果远程或本地没有 rsync,会自动回退到 SFTP
379
+ 如果远程或本地没有 rsync,会自动回退到 SFTP,同步响应包含 `transport`、`duration`、`dryRun`、`stats`、`commandSummary` 和
380
+ `diagnostics`,其中 `diagnostics` 包含本地路径策略和远端父目录探测结果,SFTP 单文件传输会返回 `verification`,包含本地和远端的
381
+ size、mode 或 permissions、mtime、owner/group,以及远端支持 `sha256sum` 时的 SHA-256 对比
316
382
 
317
383
  **注意**:rsync 模式使用 SSH 密钥/代理认证,并设置 `StrictHostKeyChecking=accept-new`(首次连接会自动接受主机密钥),
318
384
  如需严格的主机密钥验证与管理,请使用 SFTP 模式
@@ -328,7 +394,7 @@ ssh_pty_start(alias="server", command="top", rows=24, cols=80)
328
394
 
329
395
  // 2. 读取当前输出(轮询)
330
396
  ssh_pty_read(ptyId="pty_1_1234567890")
331
- // 返回: { "data": "top - 10:30:15 up 5 days...", "active": true }
397
+ // 返回: { "data": "top - 10:30:15 up 5 days...", "active": true, "unreadRawBytes": 123, "foregroundProcess": "top" }
332
398
 
333
399
  // 3. 发送命令(如退出 top)
334
400
  ssh_pty_write(ptyId="pty_1_1234567890", data="q")
@@ -353,6 +419,9 @@ ssh_pty_read(ptyId="pty_1_xxx")
353
419
  ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
354
420
  ```
355
421
 
422
+ `ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
423
+ `foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流
424
+
356
425
  常用控制序列:
357
426
 
358
427
  - 回车: `\r` 或 `\n`
@@ -367,8 +436,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
367
436
  访问远程内网服务或暴露本地服务:
368
437
 
369
438
  ```
370
- // 本地转发:通过 localhost:13306 访问远程 MySQL (10.0.0.5:3306)
371
- ssh_forward_local(alias="server", localPort=13306, remoteHost="10.0.0.5", remotePort=3306)
439
+ // 本地转发:通过 localhost:13306 访问远程 MySQL (<service-host>:3306)
440
+ ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>", remotePort=3306)
372
441
 
373
442
  // 远程转发:将本地开发服务器 (3000) 暴露到远程端口 8080
374
443
  ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
@@ -392,17 +461,24 @@ ssh_forward_close(forwardId="fwd_1_xxx")
392
461
  | `keyPath` | string | - | SSH 私钥路径 |
393
462
  | `port` | number | 22 | SSH 端口 |
394
463
  | `alias` | string | 自动生成 | 连接别名,用于后续引用 |
464
+ | `template` | string | - | 连接模板名 |
395
465
  | `env` | object | - | 环境变量 |
466
+ | `defaultEnv` | object | - | 连接级默认环境变量 |
467
+ | `runAs` | string | - | 默认执行用户 |
396
468
  | `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
397
469
 
398
470
  ### 执行选项
399
471
 
400
- | 选项 | 类型 | 默认值 | 描述 |
401
- |-----------|---------|-------|--------------------|
402
- | `timeout` | number | 30000 | 命令超时(毫秒) |
403
- | `cwd` | string | - | 工作目录 |
404
- | `env` | object | - | 额外环境变量 |
405
- | `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
472
+ | 选项 | 类型 | 默认值 | 描述 |
473
+ |-----------------|---------|-----------|------------------------|
474
+ | `timeout` | number | 30000 | 命令超时(毫秒) |
475
+ | `cwd` | string | - | 工作目录 |
476
+ | `env` | object | - | 额外环境变量 |
477
+ | `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
478
+ | `maxOutputSize` | number | 10 MB 字符 | 输出截断上限 |
479
+ | `runAs` | string | 连接级 runAs | 本次命令执行用户 |
480
+ | `useLoginUser` | boolean | false | 跳过连接级 runAs |
481
+ | `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置 |
406
482
 
407
483
  ## 安全
408
484
 
@@ -5,6 +5,37 @@ import { SFTPWrapper } from 'ssh2';
5
5
  import { FileInfo, TransferProgress } from './types.js';
6
6
  /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
7
7
  export declare function clearRsyncCache(alias?: string): void;
8
+ export declare function probeLocalPath(localPath: string): {
9
+ exists: boolean;
10
+ inputPath: string;
11
+ expandedPath: string;
12
+ resolvedPath: string;
13
+ allowList: {
14
+ configured: boolean;
15
+ matched?: boolean;
16
+ };
17
+ size?: undefined;
18
+ mode?: undefined;
19
+ mtimeMs?: undefined;
20
+ isSymlink?: undefined;
21
+ isDirectory?: undefined;
22
+ isFile?: undefined;
23
+ } | {
24
+ exists: boolean;
25
+ inputPath: string;
26
+ expandedPath: string;
27
+ resolvedPath: string;
28
+ size: number;
29
+ mode: string;
30
+ mtimeMs: number;
31
+ isSymlink: boolean;
32
+ isDirectory: boolean;
33
+ isFile: boolean;
34
+ allowList: {
35
+ configured: boolean;
36
+ matched?: boolean;
37
+ };
38
+ };
8
39
  /**
9
40
  * 上传文件
10
41
  */
@@ -19,14 +50,31 @@ export declare function downloadFile(alias: string, remotePath: string, localPat
19
50
  success: boolean;
20
51
  size: number;
21
52
  }>;
22
- /**
23
- * 读取远程文件内容
24
- */
25
- export declare function readFile(alias: string, remotePath: string, maxBytes?: number): Promise<{
53
+ export declare const DEFAULT_READ_FILE_MAX_BYTES: number;
54
+ export declare const HARD_READ_FILE_MAX_BYTES: number;
55
+ type ReadFileSampleKind = 'full' | 'head' | 'tail' | 'range' | 'line_range';
56
+ type ReadFileOptions = {
57
+ maxBytes?: number;
58
+ offset?: number;
59
+ tail?: boolean;
60
+ lineRange?: string;
61
+ };
62
+ type ReadFileResult = {
26
63
  content: string;
27
64
  size: number;
65
+ total_size: number;
66
+ read_offset: number;
67
+ read_bytes: number;
68
+ remaining_bytes: number;
69
+ sample_kind: ReadFileSampleKind;
28
70
  truncated: boolean;
29
- }>;
71
+ line_start?: number;
72
+ line_end?: number;
73
+ };
74
+ /**
75
+ * 读取远程文件内容
76
+ */
77
+ export declare function readFile(alias: string, remotePath: string, options?: number | ReadFileOptions): Promise<ReadFileResult>;
30
78
  /**
31
79
  * 写入远程文件
32
80
  */
@@ -69,12 +117,26 @@ export declare function syncFiles(alias: string, localPath: string, remotePath:
69
117
  /**
70
118
  * 使用 SFTP 同步文件
71
119
  */
120
+ type SyncStats = {
121
+ added: number;
122
+ updated: number;
123
+ deleted: number;
124
+ skipped: number;
125
+ failed: number;
126
+ };
72
127
  type SyncResult = {
73
128
  success: boolean;
74
129
  method: 'rsync' | 'sftp';
130
+ transport?: 'rsync' | 'sftp';
131
+ direction?: 'upload' | 'download';
132
+ dryRun?: boolean;
133
+ duration?: number;
75
134
  filesTransferred?: number;
76
135
  bytesTransferred?: number;
77
136
  skippedSymlinks?: number;
137
+ stats?: SyncStats;
138
+ verification?: Record<string, unknown>;
139
+ commandSummary?: Record<string, unknown>;
78
140
  output?: string;
79
141
  };
80
142
  export {};