remote-ssh

name	remote-ssh
description	连接用户的远程服务器（云服务器、NAS 等）。支持直连 SSH 和 frp STCP 隧道。可在远程服务器上执行命令、传输文件、操作 Docker 容器。当用户提到连接服务器、SSH 到某某、在某某服务器上执行时使用此 skill。
allowed-tools	Bash(*)

远程服务器 SSH 连接（多服务器）

通过 SSH 连接用户的多台远程服务器，支持直连和 frp STCP 隧道。

服务器配置

所有服务器信息存储在 servers.yaml 中。

查看可用服务器：

python3 scripts/remote_tools.py list-servers

添加新服务器：编辑 servers.yaml，在 servers: 下添加新条目。配置示例见 servers.yaml 文件中的注释。

连接方式

通过 remote_tools.py（推荐）

所有命令使用 python3 scripts/remote_tools.py [--server <name>] <command> 调用。

• 不加 --server：连接 servers.yaml 中的 default_server
• 加 --server myserver：连接指定服务器

以下简写为 remote_tools.py。

frp STCP 隧道服务器

如果服务器通过 frp STCP 隧道连接，脚本会自动检测并启动 frpc visitor。也支持手动启动：

# 直接运行 frpc
/path/to/frpc -c /path/to/frpc_visitor.toml &

# 或通过 Docker
docker run -d --name frpc_visitor \
  -p 22222:22222 \
  -v /path/to/frpc_visitor.toml:/etc/frpc/frpc.toml \
  fatedier/frpc:latest -c /etc/frpc/frpc.toml

远程工具命令

文件操作

命令	用途	示例
read <file> [--offset N] [--limit N]	读取文件，带行号	remote_tools.py read /home/user/data.csv --limit 50
write <file> --content <text>	写入文件（覆盖）；也支持 stdin	remote_tools.py write /home/user/config.yaml --content "key: value"
edit <file> --old "..." --new "..."	字符串替换编辑	remote_tools.py edit /home/user/config.yaml --old "port: 8080" --new "port: 9090"
edit <file> --old-file /tmp/old.txt --new-file /tmp/new.txt	通过临时文件传递长内容	避免 shell 转义问题
edit <file> ... --replace-all	替换所有出现	默认要求 old_string 唯一
glob <pattern> [--path <dir>]	按模式查找文件	remote_tools.py glob "*.py" --path /home/user/project
grep <pattern> [--path <dir>] [--type ext] [-C N] [-i]	搜索文件内容	remote_tools.py grep "def main" --path /home/user --type py
bash <command>	执行远程命令	remote_tools.py bash ls -la /home/user
ls [path]	列出目录	remote_tools.py ls /home/user
upload <local> <remote>	上传文件/目录	remote_tools.py upload ./data.csv /home/user/data/
download <remote> <local>	下载文件/目录	remote_tools.py download /home/user/result.csv ./result.csv

Docker 容器操作

仅在服务器配置了 docker: true 时可用：

命令	用途	示例
docker-read <container> <file> [--offset N] [--limit N]	读取容器内文件	remote_tools.py docker-read myapp /app/config.js --limit 20
docker-write <container> <file> --content <text>	写入容器内文件	remote_tools.py docker-write myapp /tmp/test.txt --content "hello"
docker-edit <container> <file> --old "..." --new "..."	编辑容器内文件	remote_tools.py docker-edit myapp /etc/config.json --old '"debug": false' --new '"debug": true'
docker-bash <container> <command>	容器内执行命令	remote_tools.py docker-bash myapp node --version
docker-grep <container> <pattern> [--path <dir>] [--type ext]	搜索容器内文件	remote_tools.py docker-grep myapp "TODO" --path /app
docker-cp <container> <local> <remote>	复制本地文件到容器	remote_tools.py docker-cp myapp /tmp/fix.py /tmp/fix.py
docker-run-script <container> <script> [--interpreter cmd]	上传并执行本地脚本	remote_tools.py docker-run-script myapp /tmp/fix.py
docker ps	列出远程 Docker 容器	remote_tools.py docker ps

指定服务器示例

# 连接默认服务器
remote_tools.py bash whoami

# 连接指定服务器
remote_tools.py --server mycloud bash whoami
remote_tools.py -s mycloud ls /root

Fallback 线路

配置了 fallback 后，主线路连接失败时自动尝试备用线路：

servers:
  my-server-main:
    host: 127.0.0.1
    port: 22222
    # ...
    fallback: my-server-hk  # 主线路失败时切换到此服务器配置

Edit 命令行为

• 默认要求 old_string 在文件中唯一出现，否则报错
• 使用 --replace-all 替换所有出现
• 对于包含特殊字符的长文本，使用 --old-file / --new-file 传递临时文件

环境变量

连接参数可通过环境变量覆盖（优先级高于 servers.yaml）：

变量	说明
NAS_HOST	SSH 主机
NAS_PORT	SSH 端口
NAS_USER	SSH 用户名
NAS_PASSWORD	SSH 密码

Shell 转义陷阱

zsh 的 BANG_HIST 会把 ! 转义为 \!。remote_tools.py 已内置自动修复，但为了安全：

• 当 --old 或 --new 内容包含 ! 时，优先使用 --old-file / --new-file

注意事项

• macOS 下 Docker 不支持 --network host，必须用 -p 端口映射
• 容器内 sed -i 不可靠（device busy），docker-edit 使用 Python 写入
• SFTP 路径映射已在脚本内部处理，用户始终使用 SSH 路径
• 依赖: paramiko, pyyaml（pip install paramiko pyyaml）