// 使用基于 SSH 的 CLI 安全操作已配置的远端服务器。适用于需要列出连接、远程执行命令、上传文件、下载文件，以及确认参数、返回值、配置文件位置和环境校验步骤的场景。
| name | agent-ssh-cli |
| description | 使用基于 SSH 的 CLI 安全操作已配置的远端服务器。适用于需要列出连接、远程执行命令、上传文件、下载文件，以及确认参数、返回值、配置文件位置和环境校验步骤的场景。 |
agentsshcli 是一个通过 npm 安装、由 Rust 原生执行器完成 SSH 操作的命令行工具，用于让 AI 或用户通过本地配置安全地操作远端服务器。
它能做的事：
它不做的事：
命令黑白名单使用 JavaScript RegExp 语法，不是 POSIX 正则。空白字符要写成 \\s，不要写 [:space:]。例如：
{
"commandBlacklist": [
"(^|[;&|()\\s])rm(\\s|$)",
"(^|[;&|()\\s])shutdown(\\s|$)",
"(^|[;&|()\\s])reboot(\\s|$)"
]
}
执行危险操作前必须先向用户确认，不能直接执行。
危险操作包括：
rm、truncate、重定向覆盖、批量删除reboot、shutdown、systemctl stop、killchmod、chown、编辑 /etc 下文件确认时必须说明目标连接名、命令或文件路径、可能影响，并等待用户明确同意后再执行。
调用前优先检查 CLI 本身是否可用：
agentsshcli --help
如果上面的命令失败，再向下检查基础环境：
node --version
npm --version
如果 node 或 npm 不存在，提示用户先安装 Node.js >= 18 和 npm >= 8。
CLI 可用后，再检查配置文件是否存在：
test -f "${AGENT_SSH_CONFIG:-$HOME/.agent-ssh-cli/config.json}"
如果配置文件不存在，提示用户创建配置文件，不继续执行 SSH 命令：
mkdir -p ~/.agent-ssh-cli
# 然后让用户编辑 ~/.agent-ssh-cli/config.json，填入真实服务器配置
默认配置文件：
~/.agent-ssh-cli/config.json
为防止配置文件中的密码泄露，密码认证会在第一次使用该服务器时被动加密保存：如果目标连接的 password 是非空明文，下一次执行 exec、upload 或 download 连接该服务器前，CLI 会把密码加密写入配置目录的 secrets.json，生成本地 secret.key，并把 config.json 中该连接改成 password: "" 加 passwordRef。改密码时直接把空的 password 重新填成新密码，下一次连接会自动覆盖旧密文。私钥认证不参与这个流程。
隐藏后的密码配置示例：
{
"name": "server",
"host": "192.0.2.10",
"port": 22,
"username": "root",
"password": "",
"passwordRef": "agentsshcli:server"
}
指定其它配置文件：
AGENT_SSH_CONFIG=/path/to/config.json agentsshcli list
如果 CLI 不可用但 Node/npm 正常，提示用户安装：
npm install -g agent-ssh-cli
agentsshcli --help
从源码开发或本地调试时，需要先构建 Rust 原生执行器：
npm run build:native
npm test
--config <path>: 指定配置文件路径，优先级高于默认配置--help, -h: 输出帮助--version, -v: 输出版本exec、upload、download 默认使用 Rust daemon 连接缓存，用于减少连续操作时重复 SSH 握手和认证的开销；只有传入 --no-cache 时才会跳过缓存并直连。缓存相关参数如下：
--no-cache: 跳过 Rust daemon 连接缓存，本次命令独立建立并关闭连接，即直连模式--cache-ttl <ms>: 设置 Rust daemon 连接缓存空闲毫秒数，默认 180000缓存参数属于子命令级参数，必须放在 exec、upload、download 后、连接名或 --connection 前。放在命令末尾会被当作未知参数。
列出配置中的服务器。
agentsshcli list
agentsshcli list --json
参数：
--json: 输出 JSON 格式。当前默认输出也是 JSON。--config <path>: 指定配置文件返回值：
name、host、port、username0示例输出：
[
{
"name": "服务器",
"host": "192.0.2.10",
"port": 22,
"username": "root"
}
]
在远端执行命令。
位置参数形式：
agentsshcli exec "<connectionName>" "<command>"
agentsshcli exec --no-cache "<connectionName>" "<command>"
agentsshcli exec --cache-ttl 60000 "<connectionName>" "<command>"
agentsshcli exec --pty "<connectionName>" "<command>"
agentsshcli exec --no-pty "<connectionName>" "<command>"
命名参数形式：
agentsshcli exec --connection "<connectionName>" --command "<command>" --directory "/root" --timeout 5000
agentsshcli exec --connection "<connectionName>" --command-file "./script.sh" --timeout 5000
agentsshcli exec --no-cache --connection "<connectionName>" --command "<command>"
参数：
<connectionName>: 连接名<command>: 远端命令--connection <name>, -c <name>: 连接名--command <command>: 远端命令--command-file <path>: 从本地 UTF-8 文件读取远端命令，适合执行多行脚本，文件必须使用 LF 换行，不能使用 Windows CRLF 换行；不能和 --command 或位置参数 <command> 同时使用--directory <dir>, -d <dir>: 远端工作目录--timeout <ms>, -t <ms>: 超时毫秒值，默认 30000--pty: 本次命令分配伪终端，优先级高于配置文件--no-pty: 本次命令不分配伪终端，优先级高于配置文件--no-cache: 不复用连接，必须放在连接名或 --connection 前--cache-ttl <ms>: 连接缓存空闲毫秒数，必须放在连接名或 --connection 前使用 --command-file 时，必须确保脚本文件是 LF 换行。CRLF 文件会把 \r 传到远端 bash，可能导致 $'xxx\r': command not found。
macOS/Linux 推荐写法：
cat > /tmp/remote-command.sh <<'EOF'
pwd
EOF
agentsshcli exec --connection "<connectionName>" --command-file /tmp/remote-command.sh
Windows PowerShell 推荐显式写 LF：
[System.IO.File]::WriteAllText("$env:TEMP\remote-command.sh", "pwd`n", [System.Text.UTF8Encoding]::new($false))
agentsshcli exec --connection "<connectionName>" --command-file "$env:TEMP\remote-command.sh"
返回值：
01上传本地文件到远端。
位置参数形式：
agentsshcli upload "<connectionName>" "<localPath>" "<remotePath>"
agentsshcli upload --no-cache "<connectionName>" "<localPath>" "<remotePath>"
命名参数形式：
agentsshcli upload --connection "<connectionName>" --local "./tmp/upload.txt" --remote "/usr/local/test/upload.txt"
agentsshcli upload --no-cache --connection "<connectionName>" --local "./tmp/upload.txt" --remote "/usr/local/test/upload.txt"
参数：
<connectionName>: 连接名<localPath>: 本地文件路径<remotePath>: 远端目标文件路径--connection <name>, -c <name>: 连接名--local <path>, -l <path>: 本地文件路径--remote <path>, -r <path>: 远端目标文件路径--no-cache: 不复用连接，必须放在连接名或 --connection 前--cache-ttl <ms>: 连接缓存空闲毫秒数，必须放在连接名或 --connection 前返回值：
File uploaded successfully01下载远端文件到本地。
位置参数形式：
agentsshcli download "<connectionName>" "<remotePath>" "<localPath>"
agentsshcli download --no-cache "<connectionName>" "<remotePath>" "<localPath>"
命名参数形式：
agentsshcli download --connection "<connectionName>" --remote "/usr/local/test/upload.txt" --local "./tmp/download.txt"
agentsshcli download --no-cache --connection "<connectionName>" --remote "/usr/local/test/upload.txt" --local "./tmp/download.txt"
参数：
<connectionName>: 连接名<remotePath>: 远端文件路径<localPath>: 本地目标文件路径--connection <name>, -c <name>: 连接名--remote <path>, -r <path>: 远端文件路径--local <path>, -l <path>: 本地目标文件路径--no-cache: 不复用连接，必须放在连接名或 --connection 前--cache-ttl <ms>: 连接缓存空闲毫秒数，必须放在连接名或 --connection 前返回值：
File downloaded successfully01agentsshcli --help
agentsshcli help list
agentsshcli help exec
agentsshcli help upload
agentsshcli help download
agentsshcli --version
返回值：
00--no-cache 和 --cache-ttl 必须放在 exec、upload、download 后、连接名或 --connection 前timeout 和 cache-ttl 必须是正整数毫秒值list 不接受位置参数upload / download 的本地路径必须位于当前工作目录、项目目录或 allowedLocalPaths 内启动 SSH 缓存进程失败 通常表示本地 Rust daemon 或其 socket 启动/握手失败；如需绕过缓存验证远端命令，应在子命令后添加 --no-cache1