dsh-ssh-vault 0.0.0-stage → 2.0.0

package/lib/ssh.js

@@ -0,0 +1,723 @@
+/**
+ * OpenSSH 驱动 —— 让模型可以通过别名调用本机 `ssh` / `scp`，而口令从不出现在命令行。
+ *
+ * 密码注入原理：Windows OpenSSH 9.x 支持 `SSH_ASKPASS_REQUIRE=force`，
+ * 在没有终端时改用 `SSH_ASKPASS` 指定的辅助程序索取口令。我们生成一个
+ * `.cmd` 包装器，由它以 Node 模式启动辅助脚本，脚本把口令写到标准输出。
+ * 口令仅存在于本次 `ssh` 子进程的环境变量中，既不落盘也不进入命令行。
+ *
+ * @module dsh-ssh-vault/ssh
+ */
+
+import { spawn } from 'node:child_process'
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { t } from './i18n.js'
+
+/** 生成 askpass 辅助脚本时使用的文件基名。 */
+const ASKPASS_JS = 'askpass.js'
+const ASKPASS_CMD = 'askpass.cmd'
+
+/**
+ * 在保险库目录中准备好 askpass 辅助脚本（内容固定、不含任何机密）。
+ * @param dir - 保险库目录。
+ * @returns `.cmd` 包装器的绝对路径，供 `SSH_ASKPASS` 使用。
+ */
+export async function ensureAskpass(dir) {
+  const jsPath = path.join(dir, ASKPASS_JS)
+  const cmdPath = path.join(dir, ASKPASS_CMD)
+  await writeFile(
+    jsPath,
+    '// 由 ssh 以 askpass 身份调用：把本次连接的口令写到标准输出。\n'
+    + 'process.stdout.write(process.env.DSH_SSH_ASKPASS_SECRET ?? "");\n'
+    + 'process.exit(0);\n',
+    'utf8',
+  )
+  // 以 Node 模式启动宿主可执行文件；路径中的 % 需要在批处理中转义。
+  const exe = process.execPath.replace(/%/g, '%%')
+  const cmd = [
+    '@echo off',
+    'setlocal',
+    'set ELECTRON_RUN_AS_NODE=1',
+    `"${exe}" "${jsPath.replace(/%/g, '%%')}"`,
+    '',
+  ].join('\r\n')
+  await writeFile(cmdPath, cmd, 'ascii')
+  return cmdPath
+}
+
+/**
+ * PowerShell 的错误流压平器。
+ *
+ * `powershell.exe` 在输出被重定向时会把 error 流序列化成 CLIXML 写进 stderr——连脚本源码
+ * 都被当成错误上下文回显，真正的错误信息淹没在一大段 XML 里。`-OutputFormat` 只作用于
+ * stdout，压不住它。所以脚本内部就把 error 流并进 stdout，再用这个过滤器把 ErrorRecord
+ * 压成一行 `[error] 消息`，避免 CategoryInfo 之类的框架细节。
+ */
+const POWERSHELL_ERROR_FILTER = 'ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) '
+  + '{ "[error] " + $_.Exception.Message } else { $_ } }'
+
+/**
+ * 把 shell 名称翻译成远端要执行的命令与参数。
+ *
+ * POSIX shell 统一用 `<shell> -s`，从标准输入读脚本；`cmd.exe` 也直接读标准输入。
+ *
+ * **PowerShell 例外**：`-Command -` 是从标准输入逐行读取的，here-string（`@'…'@`）、
+ * `foreach (…) {…}` 这类多行块会在读的过程中被拆散——拆散后产生的语法错误不会以非零
+ * 退出码回传，于是整条命令看起来"执行了但什么都没发生"。`-EncodedCommand` 把整段脚本
+ * 作为 Base64(UTF-16LE) 参数一次传过去，由 PowerShell 一次性解析，没有 stdin 依赖。
+ *
+ * @param shell - 主机记录里的 shell 字段。
+ * @param script - 要执行的脚本；PowerShell 需要它来编码，其它 shell 忽略。
+ * @returns 远端命令行数组。
+ */
+export function shellArgv(shell, script = '') {
+  const name = typeof shell === 'string' && shell.trim().length > 0 ? shell.trim() : 'bash'
+  const lower = name.toLowerCase()
+  if (lower === 'cmd' || lower === 'cmd.exe') return ['cmd.exe', '/Q']
+  if (lower.startsWith('powershell') || lower.startsWith('pwsh')) {
+    // 脚本头部：固定输出编码（否则非 ASCII 变乱码）、关掉进度偏好。
+    const head = '[Console]::OutputEncoding=[System.Text.Encoding]::UTF8\n'
+      + '$ProgressPreference="SilentlyContinue"\n'
+    const body = script.endsWith('\n') || script.length === 0 ? script : `${script}\n`
+    // **在脚本内部把 error 流并入 stdout**。powershell.exe 在输出被重定向时会把 error 流
+    // 序列化成 CLIXML 写到 stderr，连脚本源码都被当成错误上下文回显；-OutputFormat 只管
+    // stdout，压不住它。合并之后这条路径就不再被触发，Out-String -Stream 同时保住对象的
+    // 常规文本形态，不至于让 Get-Process 之类变成一行类型名。
+    const wrapped = `${head}& {\n${body}} 2>&1 | ${POWERSHELL_ERROR_FILTER} | Out-String -Stream\n`
+    const encoded = Buffer.from(wrapped, 'utf16le').toString('base64')
+    return [name, '-NoProfile', '-NonInteractive', '-EncodedCommand', encoded]
+  }
+  return [name, '-s']
+}
+
+/**
+ * 远端 shell 是否从标准输入读取脚本。
+ *
+ * PowerShell 走 `-EncodedCommand`，脚本已经在参数里了；再往 stdin 写内容不会被执行，
+ * 只会被当成输入残留。
+ *
+ * @param shell - 主机记录里的 shell 字段。
+ * @returns PowerShell 目标返回 false。
+ */
+export function shellReadsStdin(shell) {
+  return shellKind(shell) !== 'powershell'
+}
+
+/**
+ * 归一化 shell 名称，用于选择探测命令与说明文字。
+ * @param shell - 主机记录里的 shell。
+ * @returns `cmd` / `powershell` / `posix` 之一。
+ */
+export function shellKind(shell) {
+  const lower = (typeof shell === 'string' && shell.trim().length > 0 ? shell.trim() : 'bash').toLowerCase()
+  if (lower === 'cmd' || lower === 'cmd.exe') return 'cmd'
+  if (lower.startsWith('powershell') || lower.startsWith('pwsh')) return 'powershell'
+  return 'posix'
+}
+
+/**
+ * 按目标平台的 shell 生成自检命令。
+ *
+ * Windows 的 cmd 与 PowerShell 不认 `uname` / `id`，因此自检必须换一套命令，
+ * 否则在 Windows 目标上探测会永远失败。
+ *
+ * @param shell - 主机记录里的 shell。
+ * @returns 远端自检脚本。
+ */
+export function probeCommand(shell) {
+  const kind = shellKind(shell)
+  if (kind === 'cmd') {
+    return 'echo ##identity## %USERNAME%@%COMPUTERNAME%'
+      + ' & echo ##kernel## & ver'
+      + ' & echo ##os## & wmic os get Caption /value 2>nul'
+      + ' & echo ##cwd## %CD%'
+  }
+  if (kind === 'powershell') {
+    return 'Write-Output "##identity## $env:USERNAME@$env:COMPUTERNAME";'
+      + ' Write-Output "##kernel## $([Environment]::OSVersion.VersionString)";'
+      + ' Write-Output "##os## $((Get-CimInstance Win32_OperatingSystem -ErrorAction SilentlyContinue).Caption)";'
+      + ' Write-Output "##uptime## $((Get-Date) - (Get-CimInstance Win32_OperatingSystem -ErrorAction SilentlyContinue).LastBootUpTime)";'
+      + ' Write-Output "##cwd## $($PWD.Path)"'
+  }
+  return 'echo "##identity## $(id -un)@$(hostname)"; echo "##kernel## $(uname -srm)"; '
+    + 'echo "##os## $( (cat /etc/os-release 2>/dev/null | grep -E \'^(PRETTY_NAME|NAME)=\' | head -1) || cat /etc/redhat-release 2>/dev/null || echo unknown)"; '
+    + 'echo "##uptime## $(uptime -p 2>/dev/null || uptime)"; echo "##cwd## $(pwd)"'
+}
+
+/**
+ * 还原 OpenSSH 用 vis 风格八进制转义写出的非 ASCII 路径。
+ *
+ * ssh 客户端会把错误信息里的中文路径写成 `\346\223\215\344\275\234` 这样的形式，
+ * 直接展示几乎无法阅读。这里把连续的八进制转义还原成 UTF-8 文本；只有确实解出
+ * 非 ASCII 内容时才替换，避免破坏正常路径。
+ *
+ * @param text - 原始文本。
+ * @returns 可读文本。
+ */
+export function decodeOctalEscapes(text) {
+  if (typeof text !== 'string' || !text.includes('\\')) return text
+  return text.replace(/(?:\\[0-7]{3})+/g, (match) => {
+    const bytes = []
+    for (const part of match.matchAll(/\\([0-7]{3})/g)) bytes.push(Number.parseInt(part[1], 8))
+    if (!bytes.some((byte) => byte > 0x7f)) return match
+    const decoded = Buffer.from(bytes).toString('utf8')
+    return decoded.includes('\uFFFD') ? match : decoded
+  })
+}
+
+/**
+ * 组装一次 SSH 调用的认证选项。
+ * @param auth - 主机认证配置。
+ * @returns 追加到命令行末尾的选项数组。
+ */
+function authOptions(auth) {
+  switch (auth?.type) {
+    case 'password':
+      return ['-o', 'PreferredAuthentications=password,keyboard-interactive', '-o', 'PubkeyAuthentication=no']
+    case 'key':
+      return [
+        '-i', auth.privateKeyPath,
+        '-o', 'PreferredAuthentications=publickey',
+        '-o', 'IdentitiesOnly=yes',
+      ]
+    default:
+      return []
+  }
+}
+
+/**
+ * 公共连接选项：连接超时、主机密钥策略、保活与保险库私有的 known_hosts。
+ *
+ * `HashKnownHosts` 让 known_hosts 只保存主机名的哈希，避免地址以明文落盘；
+ * `UserKnownHostsFile` 永远指向保险库目录，因此不会去写用户的 `~/.ssh`。
+ * `ServerAliveInterval` 让长时间无输出的命令不被中间设备静默切断。
+ *
+ * @param options - 连接与超时设置。
+ * @returns 选项数组。
+ */
+function connectionOptions({ knownHostsPath, connectTimeoutSec, sshConfigFile }) {
+  return [
+    ...(typeof sshConfigFile === 'string' && sshConfigFile.length > 0 ? ['-F', sshConfigFile] : []),
+    '-o', `ConnectTimeout=${connectTimeoutSec}`,
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'HashKnownHosts=yes',
+    '-o', `UserKnownHostsFile=${knownHostsPath}`,
+    '-o', 'NumberOfPasswordPrompts=1',
+    '-o', 'ServerAliveInterval=30',
+    '-o', 'ServerAliveCountMax=4',
+    '-o', 'LogLevel=ERROR',
+  ]
+}
+
+/**
+ * 组装一次 `ssh` 调用的完整参数。
+ * @param options - 主机记录、连接设置与要执行的远端命令。
+ * @returns 传给 ssh 的参数数组。
+ */
+export function buildSshArgs({ record, knownHostsPath, connectTimeoutSec, sshConfigFile, bindAddress, remoteCommand = '' }) {
+  return [
+    '-T',
+    ...connectionOptions({ knownHostsPath, connectTimeoutSec, sshConfigFile }),
+    ...authOptions(record.auth),
+    ...(typeof bindAddress === 'string' && bindAddress.length > 0 ? ['-b', bindAddress] : []),
+    '-p', String(record.port),
+    '--',
+    `${record.username}@${record.host}`,
+    ...shellArgv(record.shell, remoteCommand),
+  ]
+}
+
+/**
+ * 组装一次 `scp` 调用的完整参数。
+ * @param options - 主机记录、传输方向与连接设置。
+ * @returns 传给 scp 的参数数组。
+ */
+export function buildScpArgs({
+  record, direction, local, remote, recursive,
+  knownHostsPath, connectTimeoutSec, sshConfigFile, bindAddress,
+}) {
+  const remoteSpec = `${record.username}@${record.host}:${remote}`
+  return [
+    '-P', String(record.port),
+    ...connectionOptions({ knownHostsPath, connectTimeoutSec, sshConfigFile }),
+    ...authOptions(record.auth),
+    ...(typeof bindAddress === 'string' && bindAddress.length > 0 ? ['-o', `BindAddress=${bindAddress}`] : []),
+    ...(recursive === true ? ['-r'] : []),
+    '--',
+    ...(direction === 'upload' ? [local, remoteSpec] : [remoteSpec, local]),
+  ]
+}
+
+/**
+ * 把子进程的输出收集成有界的字符串。
+ * @param stream - 可读流。
+ * @param limit - 保留的最大字节数。
+ * @param channel - 该流的通道名。
+ * @param onData - 可选的实时回调，用于把输出同步送进后台任务的环形缓冲。
+ * @returns 读取最终文本的函数。
+ */
+function collector(stream, limit, channel, onData) {
+  let text = ''
+  let truncated = false
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk) => {
+    try {
+      onData?.(chunk, channel)
+    } catch {
+      // 后台任务可能已经结算，实时回调失败不影响本次调用结果。
+    }
+    if (text.length >= limit) {
+      truncated = true
+      return
+    }
+    text += chunk
+    if (text.length > limit) {
+      text = text.slice(0, limit)
+      truncated = true
+    }
+  })
+  return () => ({ text, truncated })
+}
+
+/**
+ * 执行一次子进程并等待结束，支持超时、取消与实时输出回调。
+ *
+ * 无论超时还是取消，已收到的输出都会随结果返回——中断不等于失明。
+ *
+ * @param exe - 可执行文件。
+ * @param args - 参数数组。
+ * @param options - 标准输入、环境变量、超时、取消信号与回调。
+ * @returns 退出码、标准输出、标准错误、是否超时或取消。
+ */
+export function runProcess(exe, args, { input, env, timeoutMs, signal, maxOutputBytes, onSpawn, onData }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(exe, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+      env,
+    })
+    const readOut = collector(child.stdout, maxOutputBytes, 'stdout', onData)
+    const readErr = collector(child.stderr, maxOutputBytes, 'stderr', onData)
+    let timedOut = false
+    let aborted = false
+    let settled = false
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+      fn(value)
+    }
+    const kill = () => { try { child.kill() } catch { /* 进程可能已退出 */ } }
+    // timeoutMs 为 0 表示不限时，供后台任务使用。
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      timedOut = true
+      kill()
+    }, timeoutMs) : undefined
+    const onAbort = () => {
+      aborted = true
+      kill()
+    }
+    if (signal !== undefined) {
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+    }
+    try {
+      onSpawn?.(child)
+    } catch {
+      // 回调失败不应让本次调用挂起。
+    }
+    child.on('error', (error) => finish(reject, error))
+    child.on('close', (code) => {
+      const out = readOut()
+      const err = readErr()
+      finish(resolve, {
+        exitCode: code,
+        stdout: out.text,
+        stdoutTruncated: out.truncated,
+        stderr: err.text,
+        stderrTruncated: err.truncated,
+        timedOut,
+        aborted,
+      })
+    })
+    if (input !== undefined) child.stdin.end(input)
+    else child.stdin.end()
+  })
+}
+
+/**
+ * 把一次失败翻译成可执行的诊断建议。
+ *
+ * 顺序很重要：本地密钥文件的问题（权限过宽、误传公钥、路径不存在）常常与
+ * `Permission denied` 同时出现，必须先于服务器侧结论给出，否则会把本地问题
+ * 误报成“账号或口令不正确”。
+ *
+ * @param result - 子进程结果。
+ * @param target - 连接目标描述。
+ * @returns 去重后的诊断行数组。
+ */
+export function diagnose(result, target) {
+  const err = decodeOctalEscapes(result.stderr ?? '')
+  const local = []
+  const server = []
+  const transport = []
+
+  // —— 本地密钥与配置：ssh 客户端在发起认证前就失败了 ——
+  if (/UNPROTECTED PRIVATE KEY FILE|are too open|bad permissions|Permissions for/i.test(err)) {
+    local.push(t('ssh.keyPermissionsTooOpen'))
+  }
+  if (/Load key .*(invalid format|error in libcrypto)|invalid format/i.test(err)) {
+    local.push(t('ssh.publicKeyAsPrivate'))
+  }
+  if (/Could not open a connection to your authentication agent|No such file or directory.*(private|identity)/i.test(err)) {
+    local.push(t('ssh.keyUnavailable'))
+  }
+  if (/a terminal is required to read the password|no tty present|askpass program specified|需要密码|sudo: .*password/i.test(err)) {
+    local.push(t('ssh.sudoNoPassword'))
+  }
+
+  // —— 服务器侧认证 ——
+  // `Permission denied (publickey,password,...)` 只是服务器在列举它接受的方式，不能据此断言公钥被拒；
+  // 只有确实在用密钥认证（且本地密钥已被加载），或列表里只剩下 publickey 时，公钥结论才成立。
+  const localKeyProblem = /UNPROTECTED PRIVATE KEY FILE|are too open|bad permissions|Permissions for|invalid format|Load key/i.test(err)
+  const denied = err.match(/Permission denied \(([^)]*)\)/i)
+  const methods = denied === null
+    ? []
+    : denied[1].split(',').map((method) => method.trim().toLowerCase()).filter((method) => method.length > 0)
+  const publickeyOnly = methods.length > 0 && methods.every((method) => method === 'publickey')
+  if (!localKeyProblem && /Permission denied/i.test(err) && (target.authType === 'key' || publickeyOnly)) {
+    server.push(t('ssh.publicKeyNotInstalled'))
+  }
+  if (/Too many authentication failures/i.test(err)) {
+    server.push(t('ssh.tooManyAuthAttempts'))
+  }
+  if (/no mutual signature algorithm|unsupported public key algorithm/i.test(err)) {
+    server.push(t('ssh.algorithmMismatch'))
+  }
+  // 直接出现的锁定提示（部分平台会明确报出来）。
+  if (/account is locked|account has been locked|Account active\s+Locked|账户.*锁定/i.test(err)) {
+    server.push(t('ssh.accountLocked'))
+  }
+
+  // —— 传输层 ——
+  if (/bind .*: (Unknown error|Cannot assign requested address)|bind: Cannot assign|Cannot assign requested address/i.test(err)) {
+    transport.push(t('ssh.bindUnavailable', {
+      address: target.bindAddress ? t('ssh.bindAddressSuffix', { address: target.bindAddress }) : '',
+    }))
+  }
+  if (/Connection refused/i.test(err)) {
+    transport.push(t('ssh.portRefused', { port: target.port }))
+  }
+  if (/Connection timed out|No route to host|Network is unreachable|Connection timed out during banner exchange/i.test(err)) {
+    transport.push(t('ssh.networkUnreachable', {
+      bound: target.bindAddress ? t('ssh.boundSuffix', { address: target.bindAddress }) : '',
+    }))
+  }
+  if (/Connection reset by peer|Connection closed by .* port|kex_exchange_identification/i.test(err)) {
+    // Windows OpenSSH 对**已锁定**的账户是直接断开连接，而不是回 Permission denied，
+    // 因此这里不能只归因于防火墙——否则「端口通、banner 正常、就是连不上」会被引向错误方向。
+    transport.push(t('ssh.handshakeClosed'))
+  }
+  if (/REMOTE HOST IDENTIFICATION HAS CHANGED/i.test(err)) {
+    transport.push(t('ssh.hostKeyChanged'))
+  } else if (/Host key verification failed/i.test(err)) {
+    transport.push(t('ssh.hostKeyRejected'))
+  }
+  if (/command not found|No such file or directory.*shell|is not recognized as an internal/i.test(err)) {
+    transport.push(t('ssh.shellMissing'))
+  }
+  if (result.timedOut) {
+    transport.push(t('ssh.timeout', { ms: target.timeoutMs }))
+  }
+
+  // 只有在没有更具体结论时，才给出“账号或口令不正确”这一通用判断。
+  if (local.length === 0 && server.length === 0 && /Permission denied/i.test(err)) {
+    server.push(t('ssh.authFailed'))
+  }
+  return [...local, ...server, ...transport]
+}
+
+/** 用单引号把一段文本安全地嵌进 POSIX shell 脚本。 */
+function shellQuote(text) {
+  return `'${String(text).replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * 生成 sudo 预热脚本。
+ *
+ * 口令以字面量写进脚本，脚本本身通过 SSH 的**标准输入**送进远端 shell，因此口令
+ * 不出现在本地命令行、不出现在 ssh 进程参数、不出现在远端的 `ps` 输出里，也不落盘。
+ * 预热后 `sudo` 在时间戳窗口内免密，用户命令里照常写 `sudo ...` 即可。
+ *
+ * @param password - 用于 sudo 的口令。
+ * @returns 拼在用户命令之前的脚本片段。
+ */
+export function sudoPrelude(password) {
+  return `printf '%s\\n' ${shellQuote(password)} | sudo -S -p '' -v 2>/dev/null`
+    + ' || { echo "[dsh-ssh-vault] sudo 凭据校验失败：保存的口令可能不是该账户的 sudo 口令，'
+    + '或目标 sudoers 要求 tty（Defaults requiretty）。" >&2; exit 1; }\n'
+}
+
+/**
+ * 生成远端条件等待脚本。
+ *
+ * 长任务（升级、扩容、扫描）不必再用「sleep + 读日志」轮询：把等待条件交给远端，
+ * 一次调用就等到满足或超时，命中时回传匹配到的最后一行。配合 run_in_background
+ * 使用时，等待本身也不占用一次前台调用的额度。
+ *
+ * @param options - 目标路径、可选正则、超时与轮询间隔。
+ * @returns 远端脚本。
+ */
+export function buildWaitScript({ path, regex, timeoutMs, intervalMs }) {
+  const waitSeconds = Math.max(1, Math.ceil((Number.isFinite(timeoutMs) ? timeoutMs : 600000) / 1000))
+  const interval = Math.max(1, Math.ceil((Number.isFinite(intervalMs) ? intervalMs : 3000) / 1000))
+  const hasPattern = typeof regex === 'string' && regex.length > 0
+  const lines = [
+    `DSH_TARGET=${shellQuote(path)}`,
+    `DSH_DEADLINE=$(( $(date +%s) + ${waitSeconds} ))`,
+  ]
+  if (hasPattern) lines.push(`DSH_PATTERN=${shellQuote(regex)}`)
+  lines.push('while :; do')
+  lines.push('  if [ -e "$DSH_TARGET" ]; then')
+  if (hasPattern) {
+    lines.push('    if grep -qE "$DSH_PATTERN" "$DSH_TARGET" 2>/dev/null; then')
+    lines.push('      echo "[dsh-ssh-vault] 条件满足，匹配行："')
+    lines.push('      grep -E "$DSH_PATTERN" "$DSH_TARGET" | tail -1')
+    lines.push('      exit 0')
+    lines.push('    fi')
+  } else {
+    lines.push('    echo "[dsh-ssh-vault] 目标已出现：$DSH_TARGET"')
+    lines.push('    exit 0')
+  }
+  lines.push('  fi')
+  lines.push('  if [ "$(date +%s)" -ge "$DSH_DEADLINE" ]; then')
+  lines.push('    echo "[dsh-ssh-vault] 等待超时：$DSH_TARGET 未满足条件" >&2')
+  lines.push('    exit 124')
+  lines.push('  fi')
+  lines.push(`  sleep ${interval}`)
+  lines.push('done')
+  return lines.join('\n')
+}
+
+/**
+ * 生成远端脱离脚本：用 `setsid` 让命令脱离 SSH 会话独立运行，输出落到日志文件。
+ *
+ * 与「本地长连接式后台」相比，这种方式不怕本地连接断开、代理超时或调用被取消——
+ * 远端进程活着，pid 与日志文件就在，随时可以回来查状态、读增量输出。
+ *
+ * @param options - 要执行的命令与本次标记。
+ * @returns 远端脚本。
+ */
+export function buildDetachScript({ command, token }) {
+  const log = `/tmp/.dsh-ssh-${token}.log`
+  const pidFile = `/tmp/.dsh-ssh-${token}.pid`
+  return [
+    `DSH_LOG=${shellQuote(log)}`,
+    `DSH_PID=${shellQuote(pidFile)}`,
+    `setsid sh -c ${shellQuote(command)} > "$DSH_LOG" 2>&1 < /dev/null &`,
+    'echo $! > "$DSH_PID"',
+    'sleep 1',
+    'if kill -0 "$(cat "$DSH_PID")" 2>/dev/null; then',
+    '  echo "[dsh-ssh-vault] 已在远端后台启动：pid=$(cat "$DSH_PID")"',
+    'else',
+    '  echo "[dsh-ssh-vault] 远端进程启动后已退出，请读日志确认结果" >&2',
+    'fi',
+    'echo "[dsh-ssh-vault] 日志：$DSH_LOG"',
+    'echo "[dsh-ssh-vault] 存活查询：ps -p $(cat "$DSH_PID") >/dev/null 2>&1 && echo ALIVE || echo GONE"',
+    'echo "[dsh-ssh-vault] 结束标记：在命令末尾追加 `echo DONE > ${DSH_LOG}.done`，再用 wait_for 等待它"',
+  ].join('\n')
+}
+
+/**
+ * 在一台已保存的主机上执行命令。
+ * @param options - 调用参数。
+ * @returns 归一化后的执行结果。
+ */
+export async function runRemote({
+  record,
+  secret,
+  command,
+  askpassPath,
+  knownHostsPath,
+  connectTimeoutSec,
+  timeoutMs,
+  maxOutputBytes,
+  signal,
+  bindAddress,
+  sshConfigFile,
+  sudoPassword,
+  extraNotes,
+  sshExecutable = 'ssh',
+  env = process.env,
+  onSpawn,
+  onData,
+}) {
+  const childEnv = { ...env, ...askpassEnvironment(askpassPath, secret) }
+  const body = command.endsWith('\n') ? command : `${command}\n`
+  const inputScript = typeof sudoPassword === 'string' && sudoPassword.length > 0
+    ? `${sudoPrelude(sudoPassword)}${body}`
+    : body
+  // PowerShell 目标把完整脚本（含可能的前置）编进 -EncodedCommand；其余 shell 仍走 stdin。
+  const readsStdin = shellReadsStdin(record.shell)
+  const args = buildSshArgs({
+    record,
+    knownHostsPath,
+    connectTimeoutSec,
+    sshConfigFile,
+    bindAddress,
+    remoteCommand: readsStdin ? '' : inputScript,
+  })
+  const result = await runProcess(sshExecutable, args, {
+    input: readsStdin ? inputScript : undefined,
+    env: childEnv,
+    timeoutMs,
+    signal,
+    maxOutputBytes,
+    onSpawn,
+    onData,
+  })
+  return {
+    ...result,
+    stderr: decodeOctalEscapes(result.stderr ?? ''),
+    notes: [
+      ...(Array.isArray(extraNotes) ? extraNotes : []),
+      ...diagnose(result, { port: record.port, timeoutMs, bindAddress, authType: record.auth?.type }),
+    ],
+  }
+}
+
+/**
+ * 在主机与本地之间传输文件。
+ * @param options - 调用参数。
+ * @returns 归一化后的传输结果。
+ */
+export async function transferFile({
+  record,
+  secret,
+  direction,
+  local,
+  remote,
+  recursive,
+  askpassPath,
+  knownHostsPath,
+  connectTimeoutSec,
+  timeoutMs,
+  maxOutputBytes,
+  signal,
+  bindAddress,
+  sshConfigFile,
+  scpExecutable = 'scp',
+  env = process.env,
+  onSpawn,
+  onData,
+}) {
+  const args = buildScpArgs({
+    record, direction, local, remote, recursive, knownHostsPath, connectTimeoutSec, sshConfigFile, bindAddress,
+  })
+  const childEnv = { ...env, ...askpassEnvironment(askpassPath, secret) }
+  const result = await runProcess(scpExecutable, args, {
+    env: childEnv,
+    timeoutMs,
+    signal,
+    maxOutputBytes,
+    onSpawn,
+    onData,
+  })
+  const err = decodeOctalEscapes(result.stderr ?? '')
+  const notes = diagnose(result, { port: record.port, timeoutMs, bindAddress, authType: record.auth?.type })
+  // 连接层面的错误优先。`No such file or directory` 在同一次失败里可能只是连接中断的连带
+  // 结果，此时再提示"路径不存在"会把排查引向外层——先给出传输层结论就够了。
+  const transportBroken = /Connection (reset|closed|refused|timed out)|kex_exchange_identification|No route to host/i.test(err)
+  if (!transportBroken && /No such file or directory/i.test(err)) {
+    notes.push(t('ssh.transferPathMissing'))
+  }
+  return { ...result, stderr: err, notes }
+}
+
+/**
+ * 构造把口令交给 askpass 的环境变量。
+ * @param askpassPath - askpass 包装器路径。
+ * @param secret - 本次连接使用的口令。
+ * @returns 需要并入子进程环境的环境变量。
+ */
+function askpassEnvironment(askpassPath, secret) {
+  if (typeof secret !== 'string' || secret.length === 0) return {}
+  return {
+    SSH_ASKPASS: askpassPath,
+    SSH_ASKPASS_REQUIRE: 'force',
+    DSH_SSH_ASKPASS_SECRET: secret,
+  }
+}
+
+/**
+ * 从渲染好的结果文本里取出退出状态，供对话里的终端卡片显示状态标签。
+ *
+ * 与 `@deepseek-ai/dsh-shell` 的同名函数行为一致，但不引入那个依赖；区别只在匹配
+ * 更宽松——我们的标记后面还可能跟着诊断建议，所以不要求它在整个文本的最末尾。
+ *
+ * @param text - 工具的展示文本。
+ * @returns 去掉状态标记的正文，以及退出码或终止信号。
+ */
+export function parseExitStatus(text) {
+  const signal = /\n\[killed by signal: ([^\]\n]+)\](?:\n|$)/.exec(text)
+  if (signal?.[1] !== undefined) {
+    return { body: text.replace(signal[0], '\n').replace(/\n+$/, ''), signal: signal[1] }
+  }
+  const exit = /\n\[exit code: (\d+)\](?:\n|$)/.exec(text)
+  if (exit?.[1] !== undefined) {
+    return { body: text.replace(exit[0], '\n').replace(/\n+$/, ''), exitCode: Number(exit[1]) }
+  }
+  return { body: text.replace(/\n+$/, ''), exitCode: 0 }
+}
+
+/**
+ * 把工具输出包成终端样式的 Markdown 代码块。
+ *
+ * `presentCall` / `presentResult` 才是官方的「终端卡片」契约，但它们在本机安装里
+ * 找不到消费方——只在各工具包中被定义、被 `defineTool` 包装，没有任何代码调用它们，
+ * 因此不能作为插件可依赖的路径。内置 pwsh 工具在后台任务那条路上返回的正是这种
+ * ```console 代码块，所以它一定会被渲染。
+ *
+ * @param text - 工具的展示文本。
+ * @returns 带 console 语言标记的围栏代码块。
+ */
+export function renderTerminalBlock(text) {
+  return `\`\`\`console\n${String(text).replace(/\n+$/, '')}\n\`\`\``
+}
+
+/**
+ * 一句话开头是常见命令名时，即使带中文参数也仍按命令处理。
+ *
+ * 判据只能靠启发式：`echo 你好` 和「帮我看看磁盘」都含中文、都没有元字符。用白名单
+ * 认命令的开头是唯一能拉开两者的办法。漏判的方向是安全的——漏掉一条命令只会多跑一次
+ * shell 并报语法错；误判成自然语言则会让一条本该执行的命令被静默拦下。
+ */
+const COMMON_COMMAND_HEAD = /^(?:sudo|doas|su|apt|apt-get|apk|dnf|yum|pacman|zypper|snap|ls|ll|la|cat|tac|cd|pwd|cp|mv|rm|rmdir|mkdir|touch|chmod|chown|chgrp|ln|echo|printf|grep|egrep|find|locate|awk|sed|sort|uniq|head|tail|wc|cut|tr|xargs|tee|du|df|free|ps|pgrep|pkill|kill|killall|top|htop|systemctl|service|journalctl|dmesg|ip|ifconfig|ss|netstat|ping|traceroute|dig|nslookup|curl|wget|tar|zip|unzip|gzip|gunzip|python|python3|pip|pip3|node|npm|pnpm|yarn|git|docker|podman|kubectl|helm|mysql|psql|redis-cli|vim|vi|nano|emacs|date|hostname|whoami|id|groups|uname|uptime|hostnamectl|mount|umount|lsblk|blkid|fdisk|ufw|iptables|firewall-cmd|useradd|userdel|usermod|groupadd|passwd|ssh|scp|sftp|rsync|bash|sh|zsh|fish|env|export|source|which|whereis|type|file|stat|readlink|md5sum|sha1sum|sha256sum|openssl|crontab|at|watch|nohup|screen|tmux|reboot|shutdown|sleep|yes|seq|basename|dirname|realpath|test|expr)\b/i
+
+/**
+ * 判断一段文字看起来是自然语言，而不是 shell 命令。
+ *
+ * 先看是不是明确的命令形态：shell 元字符、路径前缀、或常见命令名开头——三者任一命中
+ * 就是命令，哪怕参数里带中文。都不命中且含中日韩文字时，才认为是在让模型做事。
+ *
+ * 用在 `/hosts 别名; …` 的后半段上：命令的产出不会回流给模型，所以识别出自然语言时
+ * 只能停下并交还给用户，不能硬当成命令执行。
+ *
+ * @param text - 分号之后的内容。
+ * @returns 看起来是自然语言时为 true。
+ */
+export function looksLikeNaturalLanguage(text) {
+  const trimmed = String(text ?? '').trim()
+  if (trimmed.length === 0) return false
+  // shell 元字符，或者以路径开头：就是命令，哪怕参数里带中文。
+  if (/[|&<>$()`]/.test(trimmed)) return false
+  if (/^(?:\.{0,2}\/|~\/)/.test(trimmed)) return false
+  // 以常见命令名开头：也是命令，例如 `echo 你好`。
+  if (COMMON_COMMAND_HEAD.test(trimmed)) return false
+  return /[\u3400-\u9fff\u3040-\u30ff\uac00-\ud7af]/.test(trimmed)
+}
+
+/** 一次 SSH 调用的超时上限，防止误配置导致永久挂起。 */
+export const MAX_TIMEOUT_MS = 30 * 60 * 1000