跳到主要内容

wsh 命令

wsh 是 Termia 的命令行搭档。它和图形界面用的是同一个 wavesrv 后端,所以很多原本要靠点击 才能做的事——打开一个文件预览、新建一个终端、读另一个面板存下的值、弹一条通知——在命令行里 也能做到。它是终端命令与应用里各个面板、标签页、窗口之间的桥梁。

它在哪里生效​

不管是在这台 Mac 本机运行,还是通过 SSH 连到远端主机,你打开的每个终端面板里都已经能直接用 wsh 了,不需要自己安装或配置任何东西。

  • 二进制文件:Termia 为它支持的每个平台/架构各自打包了一份 wsh 二进制,和 wavesrv 一起放进应用自带的资源里。正式安装下这些文件在 .app 包内部;应用启动时按相对于 wavesrv 的位置找到它们,用的是和定位 wavesrv 本身一样的那套逻辑。
  • 本地终端:Termia 会把对应的 wsh 二进制复制到自己的数据目录,并通过它接管的 zsh、bash 和 fish 启动文件把这个目录加进 PATH。这些启动文件在你自己的 .zshrc/.bashrc 之前运行, 所以新面板一打开、第一行提示符出现时 wsh 就已经能用了。
  • 远端主机(SSH):第一次连接一台主机时,Termia 会检查上面有没有现成且版本够新的 wsh; 如果没有,就通过同一条 SSH 会话把匹配该主机操作系统/架构的二进制传过去,放到 ~/.termia/bin/wsh。从那以后,连到这台主机的每个面板也都能直接用 wsh。

想知道 wsh 和它的数据到底存在哪里,直接问它本身,不要自己猜路径:

wsh wavepath config   # settings.json 等配置文件
wsh wavepath data     # wsh 二进制、shell 集成文件、本地面板存储
wsh wavepath log      # wavesrv 的日志文件
wsh wavepath log --tail   # 打印日志最后 100 行

在远端主机上​

远端那份副本放在 ~/.termia/bin/wsh。Termia 只在应用版本号比主机上已有的 wsh 版本更新时 才会自动重新推送——这是一次纯粹的版本号比较,不是内容比较。也就是说,如果 wsh 旁边那些 shell 集成文件(rc 片段、PATH 设置)在没有跟着升版本号的情况下改了内容,一台你之前已经连过 一次的主机不会自己去取新的那份。

针对这种情况有一个手动入口:打开一个连着那台主机的终端面板,点它的齿轮图标,选择 重装远端 wsh…(这一项只在远端面板上出现——本机没有什么可重装的)。它会通过现有的 SSH 会话重新传输二进制并重写 rc 文件;那台主机上新开的终端会用上刷新后的集成,已经打开的 终端不受影响。这一项在齿轮菜单里的具体位置见面板标题条。

命令行里也有同样的操作,方便写脚本,或者用来处理一个你此刻没有打开的连接:

wsh conn ensure myuser@myhost       # wsh 缺失或过期时才安装
wsh conn reinstall myuser@myhost    # 不管版本号,强制重装
wsh conn status                     # 查看每个连接,以及它上面的 wsh 是否是最新的

启动时提示 wsh 缺失​

Termia 启动时会检查有没有内置的 wsh 二进制。如果找不到,会出现一条常驻通知——标题是 "部分功能不可用",内容是:"缺少远程 shell 组件 wsh,SSH 相关功能将不可用。"这是一条警告, 不是启动失败:应用照常打开,本机终端照常能用,只是连到远端主机时没法在那边安装 shell 集成 了。出现这条提示说明这份安装是坏的——重新安装应用即可恢复。Termia 在启动和连接失败时还会 展示哪些提示,见疑难排解。

怎么指定一个面板​

大多数 wsh 命令作用于某个面板、标签页或窗口,用 -b/--block 参数指定是哪一个——这个参数 仍然叫 --block,因为它寻址的是面板底层对应的同一个后端对象。不写这个参数时,命令默认作用于 你正在输入命令的这个面板。-b 支持几种简写形式:

取值含义
this(默认)你正在输入命令的这个面板
tab当前标签页
workspace(或 ws)当前窗口(Termia 把一个窗口的身份叫作工作区)
client(或 global)客户端范围,所有窗口共享
5当前标签页里的第 5 个面板,按从左上到右下编号
tab:2当前窗口里的第 2 个标签页
term 或 term:2当前标签页里第 1 个(或第 2 个)视图类型是 term 的面板
a67f55a3截取前 8 位的面板/标签页 id
d6ff4966-231a-4074-b78a-20acc7226b41完整 id

按住 ⌃⇧ 会在当前标签页里每个面板的左上角叠加显示编号,方便你在敲命令之前先对上号。

一份常用命令导览​

打开东西​

# 预览或编辑一个文件(目录、图片、markdown、代码都能打开)
wsh view ./README.md
wsh view .

# 强制用图形编辑器打开,并等到它关闭为止(适合当 $EDITOR)
wsh edit ./notes.txt

# 在网页面板里打开一个网址
wsh web open https://example.com

# 在某个目录下打开一个新终端
wsh term ./myproject

# 在独立的面板里跑一个命令,正常退出后自动关闭这个面板
wsh run -x -- npm test

面板上的元数据、变量和文件​

# 看看 wavesrv 对你正在输入命令的这个面板都知道些什么
wsh getmeta

# 换成看 3 号面板
wsh getmeta -b 3

# 只读某一个键
wsh getmeta file

# 把某个面板改到用另一个连接
wsh setmeta -b 3 connection=myhost

# 存一个值,重启也不丢,作用域是整个客户端
wsh setvar DEPLOY_ENV=staging

# 在任意终端里读回来
echo $(wsh getvar DEPLOY_ENV)

# 存一个文件,本机或远端的任何面板都能读到
echo "hello" | wsh file write wavefile://client/greeting.txt
wsh file cat wavefile://client/greeting.txt

连接​

# 查看每个 SSH 连接以及它当前是否已连上
wsh conn status

# 一起列出已保存的主机(密钥库里的主机加上临时地址)
wsh server list

# 把这个终端连到一台远端主机
wsh ssh myuser@myhost

# 打开一个新终端,直接连到某台已保存的主机,如果存了密码就一并用上
wsh server open myuser@myhost

主机是怎么进到这份列表里的,见主机;在面板连着的那台机器上装工具(包括 agent 相关的命令行工具),见插件。

在命令行里用 Termia Agent​

# 在远端主机上开一个新终端,直接交给 Termia Agent 并带上一个任务
wsh task myuser@myhost "check disk usage and clean up anything in /tmp older than a week"

在任意终端面板里输入 tt 会在这个面板里交互式启动 Termia Agent。wsh task 对一台你还没 开过终端的主机做的是同一件事,一步到位——确保连接建立、打开一个面板,并带着初始任务启动 agent。

其他常用命令​

# 设置某个标签页的背景图片或颜色
wsh setbg ./wallpaper.jpg
wsh setbg "#1a1a2e"
wsh setbg --clear

# 从脚本里发一条桌面通知
long-build-command && wsh notify "Build finished"

# 按 id 启动一个配置好的小组件
wsh launch sysinfo

wsh 怎么“喊话”回应用​

有几个 wsh 命令不只是向 wavesrv 要数据——它们会请求正在运行的应用本身去做一件事,走的是 应用本来就在用的那条连接。在 macOS 上,能应答这类请求的命令和 Windows/Linux 客户端实现的 完全一样,这方面并没有短一块:

  • wsh notify——弹一条系统通知(同一个事件也会出现在应用内的通知面板里)。
  • 聚焦某个窗口——当某个命令需要把指定窗口带到最前面时在内部用到,如果那个窗口还没打开 会先把它打开。
  • wsh version -v 背后的更新通道查询——在 macOS 上这个查询目前总是回答 none,因为这个 版本还没有接入自动更新通道;在 Windows/Linux 上它可能报出一个真实的通道。这是一个真实的 答案,不是报错,只是答案不同而已。
  • wsh web get 背后的 CSS 选择器查询——在真实的网页面板内容上求值,和另一个平台上的 行为一样。

不在这份名单里、却试图直接跟应用打交道的命令,会立刻收到一条明确写出命令名的错误——不是 悄无声息地什么都不做,也不是干等好几秒才超时。实际上这只影响内部/实验性命令;上面导览里 提到的那些命令根本不走这条路(它们是直接向 wavesrv 创建或查询对象,不管跑的是哪个客户端, 行为都一样)。

获取帮助​

套用其它版本命令前先查看已安装助手的帮助。
套用其它版本命令前先查看已安装助手的帮助。查看原图 ↗

每个命令都支持 -h/--help,直接运行 wsh 不带任何参数会打印完整的命令列表。wsh version 打印这个 CLI 的版本号;wsh version -v 还会打印你的配置目录、数据目录,以及你所在的更新 通道。

下一步​

  • wsh 参考手册——完整的命令列表,以及每个命令的全部参数。
  • 主机——wsh server 和 wsh conn 操作的那些主机是从哪里来的,连接是怎么 建立的。
  • 文件与传输——wsh file 共用的正是 SFTP 视图和传输中心背后的那套后端。
  • 插件——在这台 Mac 或一台远端主机上安装终端工具。
  • 疑难排解——出问题时 Termia 会展示的后端和连接提示条。