@pyrokine/mcp-ssh 3.0.0 → 3.1.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
@@ -22,15 +22,52 @@ now count raw bytes. A raw read with `clear=true` returns the counts and `rawBuf
22
22
  next read reflects the cleared buffer. Use `dataBase64` for exact ANSI or binary output and `data` for a UTF-8 preview.
23
23
 
24
24
  File reads accept `encoding` (`auto`, `utf8`, `utf16le`, `utf16be`, `gbk`) and lossless `binary=true`. Keep offsets in
25
- bytes and continue with `next_offset`; choose an explicit UTF-16 encoding for nonzero offsets. A budget too small for
26
- the next complete text character returns an error instead of an empty page; malformed encoding at EOF also fails. Binary
27
- reads advance byte by byte. `lineRange` metadata describes only the returned prefix, including whether its last line
28
- ends with a newline.
25
+ bytes and continue with `next_offset`; `auto` detects encoding at the file start, including for later pages. A U+FEFF at
26
+ a nonzero offset remains content. A budget too small for the next complete text character returns an error instead of an
27
+ empty page; malformed encoding at EOF also fails. Binary reads advance byte by byte. `lineRange` metadata describes only
28
+ the returned prefix, including whether its last line ends with a newline.
29
29
 
30
30
  Windows connections require `remotePlatform="windows"`; local Windows does not change the remote default. Set
31
31
  `commandShell` and `remotePathStyle` for the host, and an explicit `rsyncProfile` when using rsync with Windows. The
32
32
  Windows behavior and examples below remain available.
33
33
 
34
+ ## Reusing an existing OpenSSH master
35
+
36
+ The default `backend="ssh2"` retains password/key authentication, bastion connections, SFTP, PTY, and forwarding. Choose
37
+ `backend="openssh"` to reuse a master already opened by your terminal:
38
+
39
+ ```text
40
+ ssh_connect(backend="openssh", configHost="myserver", alias="shared")
41
+ ssh_exec(alias="shared", command="pwd", cwd="/tmp", env={TASK: "inspect"})
42
+ ssh_sync(alias="shared", localPath="/local/data", remotePath="/remote/data", direction="upload", verify={sha256: true})
43
+ ```
44
+
45
+ `ssh -G` resolves the effective host, user, port, and `ControlPath`; an explicit `controlPath` overrides the socket
46
+ path. Custom `configPath` files retain the existing path and size checks. OpenSSH evaluates its normal `Host`, `Match`,
47
+ `Include`, and `ProxyJump` configuration, including user-configured `Match exec` commands. Execution then uses the
48
+ resolved target and socket without rereading that configuration.
49
+
50
+ This backend only reuses existing connections. A missing, replaced, or disconnected master returns an error; actual
51
+ command and rsync channels use a failing proxy if multiplexing fails, so they cannot start another SSH connection or
52
+ switch to ssh2/SFTP. Do not pass password, key, agent, or `jumpHost` authentication parameters in this mode.
53
+
54
+ Connection results include `backend`, `masterReused`, `masterPid`, `identityStatus="master_trusted"`, and observed login
55
+ metadata. Trust belongs to the user-selected master, as in native OpenSSH multiplexing. Socket ownership, configuration
56
+ conflicts, and login-user mismatches are checked; the response does not claim independent host identity authentication
57
+ from `ssh -G` or `ssh -O check`.
58
+
59
+ Commands, tracked operations, file metadata, and rsync synchronization work on local and remote POSIX systems. Sync
60
+ requires local/remote rsync and remote GNU `find`, `stat`, `head`, and `realpath`; missing capabilities fail explicitly.
61
+ Bounded directory manifests and streamed SHA-256 checks use the same master and do not require an ssh2 session or a
62
+ remote Python installation. Separate SFTP tools, temporary script uploads, PTY, forwarding, and Windows combinations
63
+ return `unsupported_backend`.
64
+
65
+ Each command uses an independent shell. `runAs`, `cwd`, and `env` remain explicit; a terminal's `su` or exported
66
+ variables do not carry over. Canceling an operation only targets its verified process. Disconnecting an alias closes
67
+ that alias's own channels; MCP shutdown closes its own channels and subprocesses. The user's master and terminal
68
+ connections remain open. Interrupted operations retain `unknown` when their remote exit cannot be verified.
69
+ `ssh_reconnect` binds the alias to the existing configured master again and never creates a replacement master.
70
+
34
71
  ## Features
35
72
 
36
73
  - **Multiple Authentication**: Password, SSH key
@@ -49,7 +86,8 @@ Windows behavior and examples below remain available.
49
86
  - Send keystrokes and commands
50
87
  - Window resize support
51
88
  - **File Operations**: Upload, download, read, write, list directory (via SFTP)
52
- - **Smart Sync**: Directory sync with rsync (auto-fallback to SFTP if rsync unavailable)
89
+ - **Smart Sync**: File and directory synchronization; default ssh2 can use SFTP when rsync is unavailable, while the
90
+ OpenSSH backend requires rsync
53
91
  - **Environment Configuration**: LANG, LC_ALL, custom env vars
54
92
  - **Bastion Support**: Connect through jump hosts
55
93
 
@@ -125,10 +163,11 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
125
163
  | `ssh_reconnect` | Reconnect a disconnected session |
126
164
  | `ssh_config_list` | List hosts from ~/.ssh/config |
127
165
 
128
- `ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use
129
- `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
166
+ `ssh_list_sessions()` returns `backend`, `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`; OpenSSH
167
+ entries also include `masterReused` and `identityStatus`. Use `detail=true` for connection details or `fields=[...]` to
168
+ select fields. Neither mode returns `keyPath`.
130
169
 
131
- Connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests. Direct,
170
+ ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests. Direct,
132
171
  jump-host, and replacement connections share this behavior without an additional option.
133
172
 
134
173
  `ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before
@@ -552,10 +591,49 @@ text. The text uses `s`/`S` for setuid and setgid and `t`/`T` for sticky. `verif
552
591
  such as `4755` and permission text such as `-rwsr-xr-x`; checks compare the numeric mask rather than reconstructing it
553
592
  from the display text.
554
593
 
594
+ ### Directory filters and pages
595
+
596
+ `ssh_list_dir` returns the complete `{success, path, count, files}` result when all six parameters below are omitted.
597
+ Entries retain directory-first, name-based ordering, and `showHidden=false` excludes dot-prefixed names. Supplying any
598
+ filter or pagination parameter enables bounded responses, with defaults of 100 entries and 64 KiB per page.
599
+
600
+ | Parameter | Type | Contract |
601
+ | ---------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
602
+ | `namePattern` | string | Case-sensitive name match using the same `*` and `?` wildcard rules as sync exclusions; other characters are literal |
603
+ | `modifiedAfter` | ISO 8601 string with timezone | Inclusive modification-time lower bound, such as `2026-01-01T00:00:00Z` |
604
+ | `modifiedBefore` | ISO 8601 string with timezone | Exclusive modification-time upper bound; it must be at or after `modifiedAfter` |
605
+ | `offset` | nonnegative integer | Position in the filtered, sorted entries; default `0` |
606
+ | `limit` | positive integer | Maximum returned entries; default `100` in bounded mode |
607
+ | `maxBytes` | positive integer | UTF-8 byte budget for the emitted JSON text, including metadata and formatting; default `65536` in bounded mode |
608
+
609
+ Name, time, and hidden-file conditions are combined with AND. The time interval is `[modifiedAfter, modifiedBefore)`;
610
+ equal bounds return an empty result. Bounded results include `count` for this page, `total_count` for all matching
611
+ entries, `offset`, `has_more`, and `next_offset`. Continue with `next_offset` and the same conditions until
612
+ `has_more=false`. An offset at or beyond the end returns an empty page and retains that offset.
613
+
614
+ ```text
615
+ ssh_list_dir(
616
+ alias="server", remotePath="/var/log/app", namePattern="*.log",
617
+ modifiedAfter="2026-01-01T00:00:00Z", modifiedBefore="2026-01-02T00:00:00Z",
618
+ offset=0, limit=100, maxBytes=65536
619
+ )
620
+ ```
621
+
622
+ The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete entry
623
+ cannot fit, the tool returns `LIST_DIR_MAX_BYTES_TOO_SMALL`, `requiredBytes`, and an unchanged `offset`/`next_offset`;
624
+ raise `maxBytes` and retry that offset. Error diagnostics can exceed the requested budget. Entries are never split or
625
+ silently skipped to fit a page.
626
+
627
+ Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination, not
628
+ incremental remote enumeration or a frozen snapshot; directory changes between calls can shift offsets. Internal
629
+ listing, recursive downloads, sync, and directory verification retain their existing enumeration contracts. The default
630
+ ssh2/SFTP backend is unchanged; OpenSSH master mode still rejects standalone SFTP directory listing.
631
+
555
632
  ### Directory sync with rsync or SFTP
556
633
 
557
- Smart sync selects rsync only for a direct connection with a validated key path or usable SSH agent. Password,
558
- inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use SFTP directly:
634
+ With the default ssh2 backend, smart sync selects rsync for a direct connection with a validated key path or usable SSH
635
+ agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to a separate OpenSSH process use
636
+ SFTP directly. The OpenSSH master backend always uses its selected master and requires rsync:
559
637
 
560
638
  ```
561
639
  // Sync local directory to remote (upload)
@@ -590,6 +668,9 @@ ssh_sync(..., dryRun=true)
590
668
  // Upload one file and verify remote owner/mode after transfer
591
669
  ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
592
670
 
671
+ // Verify one file after upload or download, including a directory destination
672
+ ssh_sync(..., verify={sha256: true, owner: true, mode: true, maxFileBytes: 268435456})
673
+
593
674
  // Verify a directory with bounded manifests
594
675
  ssh_sync(
595
676
  ...,
@@ -604,6 +685,11 @@ A directory source always means “copy the source directory contents into the d
604
685
  mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
605
686
  source root; patterns without `/` match each basename.
606
687
 
688
+ For a regular file, `verify.sha256`, `verify.owner`, `verify.mode`, and Windows `verify.aclSddl` apply to the actual
689
+ transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a directory
690
+ root hash. `verify.count`, `verify.deletions`, and `verify.staleFiles` require a directory source and are rejected
691
+ before transfer for a file. A known source file larger than the requested hash budget is also rejected before transfer.
692
+
607
693
  Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root manifest,
608
694
  owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
609
695
  `verify.deletions=true` requires `delete=true`; it records the destination before transfer and only checks whether those
@@ -617,19 +703,28 @@ If verification is requested, a mismatch, skipped check, or verification error s
617
703
  `transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
618
704
  `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode or
619
705
  permissions, mtime, owner/group, and a streamed SFTP SHA-256 comparison. `verifyOwner` and `verifyMode` apply to upload
620
- single-file sync; use `verify.owner` and `verify.mode` for directory manifests. Verification does not run `chown` or
621
- `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`; replacing an
622
- existing local regular file preserves its `rwx` bits. These permissions can differ from the source even when content and
623
- owner match, so a requested mode check can fail after a completed transfer.
624
-
625
- Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
626
- jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
706
+ single-file sync; `verify.owner` and `verify.mode` work for files and directory manifests. Verification does not run
707
+ `chown` or `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`;
708
+ replacing an existing local regular file preserves its `rwx` bits. These permissions can differ from the source even
709
+ when content and owner match, so a requested mode check can fail after a completed transfer.
710
+
711
+ For ssh2 sessions, rsync is selected for a direct connection with a validated key path or usable SSH agent. Password,
712
+ inline-key, and jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate
713
+ OpenSSH process. OpenSSH master sessions bypass this credential selection and do not fall back to SFTP.
627
714
  `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup,
628
715
  and the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
629
716
  for rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
630
717
  probe. Rsync mode sets `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails
631
718
  explicitly instead of claiming deletion. If you require strict host key verification and management, use SFTP mode.
632
719
 
720
+ When symlinks are skipped, verification describes the incomplete tree. For downloads, exclude those links and repeat the
721
+ sync and verification; `followSymlinks` only controls uploads. Directory transfer failures retain known successful
722
+ file/byte counts and failure counters. A timeout can leave remote state `unknown` even when some files completed.
723
+
724
+ `ssh_upload(timeout=...)` applies that timeout to each metadata, digest, transfer, verification, rename, and cleanup
725
+ operation. A cleanup failure is reported separately. Tracked output ending with an incomplete UTF-8 character returns an
726
+ explicit encoding error once the operation is terminal; pending partial characters can still complete while running.
727
+
633
728
  ### Persistent PTY Sessions (top, tmux, etc.)
634
729
 
635
730
  For interactive commands that continuously refresh or require ongoing interaction:
@@ -734,21 +829,23 @@ accumulate. Disconnect the alias to release a channel request that never complet
734
829
 
735
830
  ### Connection Options
736
831
 
737
- | Option | Type | Default | Description |
738
- | ----------------------- | ------ | --------------- | ------------------------------------ |
739
- | `host` | string | _required_ | Server address |
740
- | `user` | string | _required_ | Username |
741
- | `password` | string | - | Password authentication |
742
- | `keyPath` | string | - | Path to SSH private key |
743
- | `port` | number | 22 | SSH port |
744
- | `alias` | string | auto-generated | Connection alias for reference |
745
- | `template` | string | - | Template name |
746
- | `env` | object | - | Environment variables |
747
- | `defaultEnv` | object | - | Default env for this session |
748
- | `runAs` | string | - | Default execution user |
749
- | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
750
- | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
751
- | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
832
+ | Option | Type | Default | Description |
833
+ | ----------------------- | ------ | --------------- | ---------------------------------------- |
834
+ | `backend` | string | `ssh2` | `ssh2` or existing-master-only `openssh` |
835
+ | `controlPath` | string | `ssh -G` value | Existing OpenSSH control socket |
836
+ | `host` | string | _required_ | Server address |
837
+ | `user` | string | _required_ | Username |
838
+ | `password` | string | - | Password authentication |
839
+ | `keyPath` | string | - | Path to SSH private key |
840
+ | `port` | number | 22 | SSH port |
841
+ | `alias` | string | auto-generated | Connection alias for reference |
842
+ | `template` | string | - | Template name |
843
+ | `env` | object | - | Environment variables |
844
+ | `defaultEnv` | object | - | Default env for this session |
845
+ | `runAs` | string | - | Default execution user |
846
+ | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
847
+ | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
848
+ | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
752
849
 
753
850
  Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`,
754
851
  `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include
package/README_zh.md CHANGED
@@ -22,12 +22,50 @@ PTY 的 `bufferSize` 参数与列表结果中的 `bufferSize`,以及 read/list
22
22
  描述清理前的状态,下次读取才反映清理后的缓冲区;精确读取 ANSI 或二进制输出用 `dataBase64`,`data` 是 UTF-8 文本预览
23
23
 
24
24
  文件读取支持 `encoding`(`auto`、`utf8`、`utf16le`、`utf16be`、`gbk`)和无损 `binary=true`;偏移按字节计量,分页使用
25
- `next_offset`,非零偏移读取 UTF-16 时显式指定编码;预算不足以容纳下一个完整字符时返回错误,不再成功返回空页,EOF 处编码无效也会失败;binary 读取按实际字节前移;`lineRange`
25
+ `next_offset`,`auto`
26
+ 在文件起始处判断编码,后续分页也使用该判断,非零偏移的 U+FEFF 保留为正文;预算不足以容纳下一个完整字符时返回错误,EOF 处编码无效也会失败;binary 读取按实际字节前移;`lineRange`
26
27
  的行号和末行换行状态只描述已返回的前缀
27
28
 
28
29
  连接 Windows 主机须设置 `remotePlatform="windows"`,本机为 Windows 不会改变远端默认值;按主机设置 `commandShell` 和
29
30
  `remotePathStyle`,使用 Windows rsync 时显式设置 `rsyncProfile`;下文 Windows 功能和示例继续适用
30
31
 
32
+ ## 复用已有 OpenSSH 主连接
33
+
34
+ 默认 `backend="ssh2"` 保留密码与密钥认证、跳板、SFTP、PTY 和转发,设置 `backend="openssh"` 复用终端已经建立的 master:
35
+
36
+ ```text
37
+ ssh_connect(backend="openssh", configHost="myserver", alias="shared")
38
+ ssh_exec(alias="shared", command="pwd", cwd="/tmp", env={TASK: "inspect"})
39
+ ssh_sync(alias="shared", localPath="/local/data", remotePath="/remote/data", direction="upload", verify={sha256: true})
40
+ ```
41
+
42
+ `ssh -G` 解析有效的 host、user、port 和 `ControlPath`,也可通过 `controlPath` 显式指定 socket,`configPath`
43
+ 保留原有路径与文件大小校验
44
+
45
+ OpenSSH 按原生规则处理 `Host`、`Match`、`Include` 和 `ProxyJump`,其中包含用户配置的 `Match exec`
46
+ 命令;实际执行阶段使用已经解析的目标和 socket,不重新读取这份配置
47
+
48
+ 该后端只复用已有连接,master 不存在、被替换或失效时明确报错;实际命令和 rsync 通道在复用失败后通过失败代理终止,不新建 SSH 连接、重新认证或转用 ssh2/SFTP
49
+
50
+ 通过 configHost 或 controlPath 选择已有 master,password、key、agent 和 `jumpHost` 等新认证参数在连接前拒绝
51
+
52
+ 连接结果包含 `backend`、`masterReused`、`masterPid`、`identityStatus="master_trusted"`
53
+ 和实际观测的登录信息,沿用用户所选 master 的信任;工具检查 socket 所有权、alias 配置冲突和登录用户不符,不把 `ssh -G` 或
54
+ `ssh -O check` 描述成独立的远端主机身份认证
55
+
56
+ 支持本机和远端均为 POSIX 的命令、tracked operation、文件元数据与 rsync 同步;同步要求本机和远端具备 rsync,远端具备 GNU
57
+ `find`、`stat`、`head` 和 `realpath`,缺少能力时具体报错
58
+
59
+ 有界目录 manifest 和流式 SHA-256 校验均使用同一 master,不要求先建立 ssh2 会话或额外安装远端 Python;独立 SFTP 工具、临时脚本上传、PTY、转发和 Windows 组合返回
60
+ `unsupported_backend`
61
+
62
+ 每条命令使用独立 shell,`runAs`、`cwd` 和 `env` 显式指定,原终端的 `su` 或环境变量变更不作为新通道状态
63
+
64
+ 取消单项只针对已经验证的目标进程;断开 alias 关闭该 alias 的自有通道;MCP 退出关闭自身通道和子进程,用户 master 与终端连接保持打开
65
+
66
+ 远端退出状态无法确认时,受影响 operation 保持 `unknown`;`ssh_reconnect`
67
+ 重新绑定配置所指的已有 master,不创建新的 master
68
+
31
69
  ## 功能特性
32
70
 
33
71
  - **多种认证方式**:密码、SSH 密钥
@@ -46,7 +84,7 @@ PTY 的 `bufferSize` 参数与列表结果中的 `bufferSize`,以及 read/list
46
84
  - 发送按键和命令
47
85
  - 窗口大小调整
48
86
  - **文件操作**:上传、下载、读取、写入、目录列表(通过 SFTP)
49
- - **智能同步**:目录同步,优先使用 rsync(无 rsync 时自动回退到 SFTP)
87
+ - **智能同步**:文件与目录同步,默认 ssh2 在 rsync 不可用时使用 SFTP,OpenSSH 后端保持 rsync
50
88
  - **环境配置**:LANG、LC_ALL、自定义环境变量
51
89
  - **跳板机支持**:通过堡垒机连接
52
90
 
@@ -64,7 +102,7 @@ PTY 的 `bufferSize` 参数与列表结果中的 `bufferSize`,以及 read/list
64
102
 
65
103
  ## 安装
66
104
 
67
- 需要 Node.js 20.19 或更新版本。
105
+ 需要 Node.js 20.19 或更新版本
68
106
 
69
107
  ### npm(推荐)
70
108
 
@@ -122,14 +160,15 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
122
160
  | `ssh_reconnect` | 重新连接断开的会话 |
123
161
  | `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
124
162
 
125
- `ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true`
126
- 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
163
+ `ssh_list_sessions()` 默认返回 `backend`、`alias`、规范化 `identity`、`runAs`、`connected` 和
164
+ `lastUsedAt`,OpenSSH 条目另含 `masterReused` 与 `identityStatus`;使用 `detail=true` 获取连接详情,或通过
165
+ `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
127
166
 
128
- 连接启用 TCP_NODELAY,减少交互命令和小文件 SFTP 请求之间的等待,直连、跳板和替代连接使用相同行为,无需新增选项
167
+ ssh2 连接启用 TCP_NODELAY,减少交互命令和小文件 SFTP 请求之间的等待,直连、跳板和替代连接使用相同行为,无需新增选项
129
168
 
130
- `ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward 和传输能力缓存失效。
169
+ `ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward 和传输能力缓存失效
131
170
 
132
- 自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias 下后来发布的新会话。
171
+ 自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias 下后来发布的新会话
133
172
 
134
173
  旧 client 延迟到达的 `close` 不会让过期资源继续挂在同一 alias 下;通过 jump host 建立目标连接时,如果取消发生在
135
174
  `forwardOut` pending 阶段,延迟 callback 返回的 channel 会先销毁再结束连接请求
@@ -147,7 +186,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
147
186
  | `ssh_exec_script` | 上传并执行远端临时脚本 |
148
187
 
149
188
  远端为 Windows 时,`ssh_exec_script` 给 PowerShell 脚本写入 UTF-8 BOM,避免 Windows
150
- PowerShell 将 Unicode 脚本误读为系统编码;CMD 脚本先切换到代码页 65001 再执行 UTF-8 内容,切换失败则终止。POSIX 脚本内容保持不变
189
+ PowerShell 将 Unicode 脚本误读为系统编码;CMD 脚本先切换到代码页 65001 再执行 UTF-8 内容,切换失败则终止;POSIX 脚本内容保持不变
151
190
 
152
191
  ### 可跟踪任务
153
192
 
@@ -288,7 +327,7 @@ ssh_connect(configHost="myserver", configPath="/custom/path/config")
288
327
  4. ssh_exec_parallel(aliases=["server1", "server2", "server3"], command="uptime")
289
328
  ```
290
329
 
291
- 每台主机的结果包含与 `ssh_exec` 相同的元数据,包括 `failureKind`、`effectiveUser`、`cwd`、截断字段和诊断建议。
330
+ 每台主机的结果包含与 `ssh_exec` 相同的元数据,包括 `failureKind`、`effectiveUser`、`cwd`、截断字段和诊断建议
292
331
  `ssh_exec_parallel` 单次最多 32 个 alias,默认最多并发 4 台主机,可用 `maxConcurrency` 调整(最大 8),并支持
293
332
  `maxOutputSize` 限制每台主机的输出
294
333
 
@@ -303,7 +342,7 @@ ssh_disconnect(alias="myserver")
303
342
  ### 连接模板和 runAs
304
343
 
305
344
  模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json`
306
- 提供,工具显式参数优先于模板值。选中的模板会在连接前校验,SSH 端口必须是 1 到 65535 的整数。模板无效时,错误只返回模板名和字段路径,不返回认证值
345
+ 提供,工具显式参数优先于模板值;选中的模板会在连接前校验,SSH 端口必须是 1 到 65535 的整数;模板无效时,错误只返回模板名和字段路径,不返回认证值
307
346
 
308
347
  ```json
309
348
  {
@@ -364,15 +403,15 @@ ssh_connect(
364
403
  )及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
365
404
 
366
405
  `ssh_exec`、`ssh_exec_as_user` 和 `ssh_exec_sudo` 使用相同的身份优先级:`useLoginUser=true` 使用登录用户,否则本次
367
- `runAs` 覆盖连接级 `runAs`,再使用连接级 `runAs`。
406
+ `runAs` 覆盖连接级 `runAs`,再使用连接级 `runAs`
368
407
 
369
408
  `ssh_exec` 和 `ssh_exec_as_user`
370
409
  返回执行元数据:`loginUser`、`effectiveUser`、`identity`、`cwd`、`resolvedCwd`、`shell`、
371
410
  `profileLoaded`、`envInjectedKeys`、`failureKind`、`stdoutBytes`、`stderrBytes` 和截断提示,大输出会返回 `stdoutHead`、
372
- `stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`。
411
+ `stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`
373
412
 
374
- timeout 错误也包含超时前已经产生的 head/tail 输出。stdout 和 stderr 使用增量解码,UTF-8 字符即使跨越多个 SSH data
375
- chunk,也会完整返回。
413
+ timeout 错误也包含超时前已经产生的 head/tail 输出;stdout 和 stderr 使用增量解码,UTF-8 字符即使跨越多个 SSH data
414
+ chunk,也会完整返回
376
415
 
377
416
  `commandRisk`
378
417
  按所选 shell 报告破坏性、提权、凭据参数、进程控制及资源使用风险,只读搜索中的敏感词和普通 Python/Node 命令不会仅凭词语触发风险提示
@@ -442,7 +481,7 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
442
481
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
443
482
  ```
444
483
 
445
- 日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具。`ssh_exec_script.timeout`
484
+ 日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具;`ssh_exec_script.timeout`
446
485
  同时用于临时脚本上传、权限准备和执行阶段;SFTP 上传停滞时按请求的 timeout 结束,不再使用默认 SFTP 预算
447
486
 
448
487
  ### 设置环境变量
@@ -458,7 +497,7 @@ ssh_connect(
458
497
 
459
498
  ### 快速一次性执行
460
499
 
461
- 无需管理连接,适用于单次命令。`ssh_quick_exec` 为每次调用创建唯一临时 alias,`readyTimeout` 只限制连接阶段,`timeout`
500
+ 无需管理连接,适用于单次命令;`ssh_quick_exec` 为每次调用创建唯一临时 alias,`readyTimeout` 只限制连接阶段,`timeout`
462
501
  只限制远端命令执行阶段:
463
502
 
464
503
  ```
@@ -512,28 +551,62 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
512
551
  `rm`,可用于禁用 exec 的 SFTP-only 服务和 BSD 系统,目录 manifest 校验也通过 SFTP 读取远端目录树
513
552
 
514
553
  `ssh_download` 先以 `0600` mode 写入目标同目录的临时文件,SFTP 流关闭且传输字节数与 SFTP `stat`
515
- 报告的大小一致后再 rename 到本地目标。新文件保持 `0600`;替换普通文件时保留其 `rwx`
516
- 位,但不复制 setuid、setgid 或 sticky 位。目标是 symlink、目录或其他非普通对象时,在远端读取开始前拒绝。下载失败、提前截断或取消时会删除临时文件,已有本地目标保持原内容。SFTP 目录列表在构造子路径前会拒绝空名称、`.`、`..`、NUL 和路径分隔符
554
+ 报告的大小一致后再 rename 到本地目标;新文件保持 `0600`;替换普通文件时保留其 `rwx`
555
+ 位,但不复制 setuid、setgid 或 sticky 位;目标是 symlink、目录或其他非普通对象时,在远端读取开始前拒绝;下载失败、提前截断或取消时会删除临时文件,已有本地目标保持原内容;SFTP 目录列表在构造子路径前会拒绝空名称、`.`、`..`、NUL 和路径分隔符
517
556
 
518
557
  命令执行结果在远端命令非零退出且没有 stdout/stderr 时返回 `emptyOutputFailure=true`,同时给出 effective
519
558
  user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过 16 MiB 时会在远端传输前拒绝,返回
520
559
  `total_size`、
521
560
  `read_offset`、`requested_offset`、`read_bytes`、`read_end`、`next_offset`、`remaining_bytes`、`sample_kind` 和
522
- `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围。文本读取不会截断 UTF-8 字符,后续分段应使用
523
- `next_offset`。行范围读取不执行远端 shell 工具。
561
+ `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围;文本读取不会截断 UTF-8 字符,后续分段应使用
562
+ `next_offset`;行范围读取不执行远端 shell 工具
524
563
 
525
564
  `ssh_upload`、`ssh_download`、`ssh_read_file`、`ssh_write_file`、`ssh_list_dir`、`ssh_file_info` 和 `ssh_mkdir`
526
- 支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1 小时。超时返回 `operationStatus="unknown"` 和
565
+ 支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1 小时;超时返回 `operationStatus="unknown"` 和
527
566
  `retryable=true`,重试前应检查受影响的远端或本地路径
528
567
 
529
568
  `ssh_list_dir` 和 `ssh_file_info` 返回按 `07777` 掩码提取的数值 `mode`,`permissions` 用作展示,其中 setuid/setgid 使用
530
- `s`/`S`,sticky 使用 `t`/`T`。`verifyMode` 支持 `4755` 等四位八进制值和 `-rwsr-xr-x`
569
+ `s`/`S`,sticky 使用 `t`/`T`;`verifyMode` 支持 `4755` 等四位八进制值和 `-rwsr-xr-x`
531
570
  等权限文本;校验直接比较数值 mode,不从展示文本反向推导
532
571
 
572
+ ### 目录筛选与分页
573
+
574
+ `ssh_list_dir` 未传下列六个参数时,继续返回完整的 `{success, path, count, files}`,条目按目录优先、名称排序,
575
+ `showHidden=false` 排除名称以点开头的条目;传入任一筛选或分页参数后启用有界响应,默认每页最多 100 条、64 KiB
576
+
577
+ | 参数 | 类型 | 合同 |
578
+ | ---------------- | ------------------------ | --------------------------------------------------------------------------- |
579
+ | `namePattern` | string | 名称区分大小写,复用同步 exclude 的 `*` 和 `?` 通配规则,其他字符按字面匹配 |
580
+ | `modifiedAfter` | 带时区的 ISO 8601 string | 修改时间下界,包含,例如 `2026-01-01T00:00:00Z` |
581
+ | `modifiedBefore` | 带时区的 ISO 8601 string | 修改时间上界,不包含,须大于或等于 `modifiedAfter` |
582
+ | `offset` | 非负整数 | 筛选并排序后的条目位置,默认 `0` |
583
+ | `limit` | 正整数 | 单页最多返回条数,有界模式默认 `100` |
584
+ | `maxBytes` | 正整数 | 返回 JSON 文本的 UTF-8 字节预算,包含元数据和格式空白,有界模式默认 `65536` |
585
+
586
+ 名称、时间和隐藏文件条件取交集,时间区间为 `[modifiedAfter, modifiedBefore)`,起止相同时返回空结果;有界响应中, `count`
587
+ 表示本页条数,`total_count` 表示全部匹配条数,并返回 `offset`、`has_more` 和 `next_offset`,保持筛选条件不变,使用
588
+ `next_offset` 续查,直到 `has_more=false`;偏移达到或超过末尾时返回空页,保留该偏移
589
+
590
+ ```text
591
+ ssh_list_dir(
592
+ alias="server", remotePath="/var/log/app", namePattern="*.log",
593
+ modifiedAfter="2026-01-01T00:00:00Z", modifiedBefore="2026-01-02T00:00:00Z",
594
+ offset=0, limit=100, maxBytes=65536
595
+ )
596
+ ```
597
+
598
+ 字节预算约束成功响应的 JSON 文本,不包含 MCP 协议外层;分页元数据或下一完整条目无法放入预算时,工具返回
599
+ `LIST_DIR_MAX_BYTES_TOO_SMALL`、`requiredBytes`,`offset` 和 `next_offset` 保持不变,提高 `maxBytes`
600
+ 后从该位置重试,错误诊断可超过请求预算;条目始终完整返回,不为满足预算而跳过条目
601
+
602
+ 每次调用都完成 SFTP `readdir`
603
+ 后再筛选和分页,分页只限制响应,不提供远端增量枚举或冻结快照,调用之间目录变化会改变偏移对应的条目;内部目录读取、递归下载、同步和目录校验保持现有枚举合同;默认 ssh2/SFTP 后端不变,OpenSSH
604
+ master 模式仍拒绝独立 SFTP 目录读取
605
+
533
606
  ### 使用 rsync 或 SFTP 同步目录
534
607
 
535
- 智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump
536
- host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
608
+ 默认 ssh2 后端在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump
609
+ host 和其他无法安全交给独立 OpenSSH 进程的路由直接使用 SFTP OpenSSH master 后端始终使用所选主连接,要求 rsync 可用:
537
610
 
538
611
  ```
539
612
  // 同步本地目录到远程(上传)
@@ -568,6 +641,9 @@ ssh_sync(..., dryRun=true)
568
641
  // 上传单文件后校验远端 owner/mode
569
642
  ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
570
643
 
644
+ // 上传或下载单文件后校验,目标也可为目录
645
+ ssh_sync(..., verify={sha256: true, owner: true, mode: true, maxFileBytes: 268435456})
646
+
571
647
  // 使用有界 manifest 校验目录
572
648
  ssh_sync(
573
649
  ...,
@@ -581,8 +657,13 @@ ssh_sync(..., delete=true, verify={deletions: true})
581
657
  目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false`
582
658
  会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
583
659
 
660
+ 普通文件可在 upload 和 download 中使用 `verify.sha256`、`verify.owner`、`verify.mode` 与 Windows
661
+ `verify.aclSddl`,校验目标为实际传输的文件,结果使用 `kind="single_file"`,返回文件摘要
662
+ `verify.count`、`verify.deletions` 和 `verify.staleFiles`
663
+ 要求目录源,单文件传输前会明确拒绝;已知源文件超过请求的哈希字节上限时,也在传输前拒绝
664
+
584
665
  目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root
585
- manifest、owner、包括 setuid、setgid、sticky 在内的四位八进制 mode、旧文件和删除结果。`verify.deletions=true`
666
+ manifest、owner、包括 setuid、setgid、sticky 在内的四位八进制 mode、旧文件和删除结果;`verify.deletions=true`
586
667
  必须同时设置 `delete=true`,工具会在传输前记录目标目录,只检查这些删除候选是否消失,`staleFiles`
587
668
  则独立检查目标端全部额外条目,响应只返回摘要和最多 20 个 mismatch 样本,不返回完整 manifest,默认上限为 10000 个条目、单文件 256
588
669
  MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileBytes` 和 `verify.maxTotalBytes`
@@ -592,17 +673,24 @@ MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileByt
592
673
  请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,
593
674
  `verificationStatus`、`verificationSuccess` 和 `failedChecks`
594
675
  描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group,以及通过 SFTP 流读取计算的 SHA-256 对比,upload 单文件使用
595
- `verifyOwner` 和 `verifyMode`,目录逐项校验使用 `verify.owner` 和 `verify.mode`
676
+ `verifyOwner` 和 `verifyMode`,文件和目录逐项校验均可使用 `verify.owner` 和 `verify.mode`
596
677
  校验不会自动执行 chown/chmod,SFTP 新目录使用目标端默认权限,新下载文件使用
597
678
  `0600`,覆盖既有本地普通文件保留其 rwx 内容和 owner 匹配不代表 mode 匹配,请求 mode 校验时,已完成的传输仍会因权限不同而返回校验失败
598
679
 
599
- 只有直连且存在已校验 key path 或可用 SSH agent 时才选择 rsync,password、inline key 和 jump
600
- host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料,`preflightTimeout`、`connectTimeout` 和
601
- `operationTimeout` 分别限制能力预检、rsync
602
- SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回 `rsyncProbe.status="skipped"`
603
- 和路由判定原因,不再省略 probe,rsync 模式设置 `StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`
680
+ ssh2 session 在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key 和 jump
681
+ host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料 OpenSSH master
682
+ session 不经过这项凭证选择,也不回退到 SFTP,`preflightTimeout`、`connectTimeout` 和 `operationTimeout`
683
+ 分别限制能力预检、rsync SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回
684
+ `rsyncProbe.status="skipped"` 和路由判定原因,不再省略 probe,rsync 模式设置
685
+ `StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`
604
686
  ,此类请求会明确失败,不会报告已经删除,如需严格的主机密钥验证与管理,请使用 SFTP 模式
605
687
 
688
+ 符号链接被跳过时,校验会说明目录不完整,download 可排除这些链接后重新同步和校验,`followSymlinks`
689
+ 只控制 upload 目录传输失败会保留已知成功文件数、字节数和失败计数;部分文件完成后发生超时,远端状态仍可为 `unknown`
690
+
691
+ `ssh_upload(timeout=...)` 将该期限应用于每次元数据、摘要、传输、校验、rename 和清理操作,清理失败单独报告 tracked
692
+ operation 终态输出以残缺 UTF-8 字符结束时明确返回编码错误;运行中的未完成字符仍可等待后续字节
693
+
606
694
  ### 持久化 PTY 会话(top、tmux 等)
607
695
 
608
696
  用于持续刷新或需要持续交互的命令:
@@ -642,12 +730,12 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
642
730
  `ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、
643
731
  `unreadRawBytes`、`rawBufferLimit`、`rawBufferTruncated`、`foregroundProcess`,列表项还返回
644
732
  `bufferSize`,这些 size 字段都按字节计数,screen 输出使用增量解码;raw 的 `dataBase64`
645
- 无损保存原始字节,包括不完整的 UTF-8 序列,`data` 是文本预览。`rawBufferTruncated=true`
646
- 表示从上次 clear 起已有更早的 raw 输出因字节上限被丢弃。raw 读取默认
647
- `clear=true`,响应返回清理前的字节数和截断标志,随后重置 raw 缓冲区和标志;screen 读取不清理 raw 状态。有限命令自然结束后仍可读取最终 screen,返回
733
+ 无损保存原始字节,包括不完整的 UTF-8 序列,`data` 是文本预览;`rawBufferTruncated=true`
734
+ 表示从上次 clear 起已有更早的 raw 输出因字节上限被丢弃;raw 读取默认
735
+ `clear=true`,响应返回清理前的字节数和截断标志,随后重置 raw 缓冲区和标志;screen 读取不清理 raw 状态;有限命令自然结束后仍可读取最终 screen,返回
648
736
  `active=false`,直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS`
649
- 调整。`ssh_pty_write` 返回 `accepted=true` 表示本地 stream 已接收输入, `backpressured=true`
650
- 只表示缓冲区达到高水位,不代表输入丢失。`ssh_pty_close` 返回 `closed`、`not_found`、`failed` 或
737
+ 调整;`ssh_pty_write` 返回 `accepted=true` 表示本地 stream 已接收输入, `backpressured=true`
738
+ 只表示缓冲区达到高水位,不代表输入丢失;`ssh_pty_close` 返回 `closed`、`not_found`、`failed` 或
651
739
  `unknown`,可重试的失败会保留 PTY 状态
652
740
 
653
741
  常用控制序列:
@@ -684,18 +772,18 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
684
772
  ```
685
773
 
686
774
  关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、`remoteUnforwarded`、
687
- `activeConnections`、`closeMode` 和 `retryable`。`ssh_forward_list` 返回 `lifecycle` 和
688
- `acceptingConnections`,`closing` 状态仍可重试,但不再接收流量。超时或 callback 失败时 forward 仍保留在
775
+ `activeConnections`、`closeMode` 和 `retryable`;`ssh_forward_list` 返回 `lifecycle` 和
776
+ `acceptingConnections`,`closing` 状态仍可重试,但不再接收流量;超时或 callback 失败时 forward 仍保留在
689
777
  `ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind,`remotePort=0`
690
778
  会返回实际分配端口,后续连接路由和 `unforwardIn` 都使用该端口
691
779
 
692
780
  forward 在 `listen` 或 `forwardIn` 完成前就进入生命周期管理,disconnect 会取消 pending
693
- creation。延迟返回的本地 listener 会被关闭,延迟分配的远端 listener 会被移除;close 开始后立即拒绝新的本地或远端连接。
781
+ creation;延迟返回的本地 listener 会被关闭,延迟分配的远端 listener 会被移除;close 开始后立即拒绝新的本地或远端连接
694
782
  `forwardOut`、close 和 unforward 的延迟 callback 修改状态前会检查同一生命周期记录,已关闭的 forward 不会重新出现在
695
783
  `ssh_forward_list`;每条本地转发连接同时跟踪本地 socket 和 SSH `forwardOut`
696
- channel,任一端关闭或失败都会销毁另一端,force close 只在两端都销毁且 `activeConnections` 归零后返回。remote force
784
+ channel,任一端关闭或失败都会销毁另一端,force close 只在两端都销毁且 `activeConnections` 归零后返回;remote force
697
785
  close 在 `unforwardIn`
698
- 后遵循相同的连接排空规则,同一连接两端的 close/error 事件只递减一次计数。每个 alias 最多允许 32 个 pending `forwardOut`
786
+ 后遵循相同的连接排空规则,同一连接两端的 close/error 事件只递减一次计数;每个 alias 最多允许 32 个 pending `forwardOut`
699
787
  请求,close 会等待全部 callback;如果 SSH 服务端始终不回应 channel-open,请求会超时并保留可重试的 forward,同时拒绝同 alias 新建 local
700
788
  forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能释放始终不返回的底层请求
701
789
 
@@ -703,21 +791,23 @@ forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能
703
791
 
704
792
  ### 连接选项
705
793
 
706
- | 选项 | 类型 | 默认值 | 描述 |
707
- | ----------------------- | ------ | ---------- | --------------------------------------------- |
708
- | `host` | string | _必需_ | 服务器地址 |
709
- | `user` | string | _必需_ | 用户名 |
710
- | `password` | string | - | 密码认证 |
711
- | `keyPath` | string | - | SSH 私钥路径 |
712
- | `port` | number | 22 | SSH 端口 |
713
- | `alias` | string | 自动生成 | 连接别名,用于后续引用 |
714
- | `template` | string | - | 连接模板名 |
715
- | `env` | object | - | 环境变量 |
716
- | `defaultEnv` | object | - | 连接级默认环境变量 |
717
- | `runAs` | string | - | 默认执行用户 |
718
- | `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
719
- | `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
720
- | `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
794
+ | 选项 | 类型 | 默认值 | 描述 |
795
+ | ----------------------- | ------ | ----------- | --------------------------------------------- |
796
+ | `backend` | string | `ssh2` | `ssh2` 或仅复用已有 master 的 `openssh` |
797
+ | `controlPath` | string | `ssh -G` 值 | 已有 OpenSSH control socket |
798
+ | `host` | string | _必需_ | 服务器地址 |
799
+ | `user` | string | _必需_ | 用户名 |
800
+ | `password` | string | - | 密码认证 |
801
+ | `keyPath` | string | - | SSH 私钥路径 |
802
+ | `port` | number | 22 | SSH 端口 |
803
+ | `alias` | string | 自动生成 | 连接别名,用于后续引用 |
804
+ | `template` | string | - | 连接模板名 |
805
+ | `env` | object | - | 环境变量 |
806
+ | `defaultEnv` | object | - | 连接级默认环境变量 |
807
+ | `runAs` | string | - | 默认执行用户 |
808
+ | `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
809
+ | `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
810
+ | `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
721
811
 
722
812
  连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、
723
813
  `transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、
@@ -1,5 +1,6 @@
1
1
  import type { SFTPWrapper } from 'ssh2';
2
2
  import type { RemotePathStyle } from './types.js';
3
+ import type { OpenSshConnection } from './openssh.js';
3
4
  export declare const DIRECTORY_VERIFY_MAX_ENTRIES = 50000;
4
5
  export declare const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
5
6
  export declare const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES: number;
@@ -40,6 +41,7 @@ export type DirectoryManifest = {
40
41
  export declare function matchesDirectoryExclude(relativePath: string, patterns: string[] | undefined): boolean;
41
42
  export declare function createLocalDirectoryManifest(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean): Promise<DirectoryManifest>;
42
43
  export declare function createRemoteDirectoryManifest(sftp: SFTPWrapper, rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean, style?: RemotePathStyle): Promise<DirectoryManifest>;
44
+ export declare function createOpenSshDirectoryManifest(connection: OpenSshConnection, rootPath: string, request: DirectoryVerifyRequest, timeout: number, exclude?: string[], followSymlinks?: boolean): Promise<DirectoryManifest>;
43
45
  export declare function createEmptyDirectoryManifest(): DirectoryManifest;
44
46
  export declare function compareDirectoryManifests(expected: DirectoryManifest, actual: DirectoryManifest, request: DirectoryVerifyRequest, deletionBaseline?: DirectoryManifest): Record<string, unknown>;
45
47
  export {};