Skip to content

在 iOS 和 macOS 的 NeoServer 中使用 OSC 7501 程序状态通知

在 iOS 和 macOS 的 NeoServer 中接收终端任务完成、失败和审批通知。了解如何启用 OSC 7501 提醒,并通过 SSH 进行测试。

4 分钟阅读NeoServer

远程构建完成时,你正在查看另一台服务器;编程代理在另一个终端里暂停等待审批。NeoServer 现已在 iOS 和 macOS 上支持 OSC 7501 程序状态通知,任务可以在完成、失败或需要审批时主动通知你,不必反复切回它的终端查看。

轻点通知即可回到现有的终端会话。在 macOS 上,NeoServer 还能定位到该会话所在的分屏面板。

什么是 OSC 7501?

OSC 7501 是一种终端转义序列,运行中的程序用它来汇报自己的状态。它可以描述正在进行的工作、已完成的任务、失败,或需要用户输入的暂停。程序通过终端输出发送结构化的状态信息;由终端决定如何呈现。传输格式可参阅 Program Status Protocol 规范。

必须由运行中的程序发出 OSC 7501 报告。 打开通知并不会让每条 shell 命令都汇报状态。兼容的命令行工具可以自己发送报告,你自己的脚本也可以用 printf 发送。

哪些状态会产生通知?

NeoServer 在 iOS 和 macOS 上使用相同的规则:

报告系统通知
state=done任务已完成
state=error任务失败
state=blocked:kind=permission需要审批
state=idle 或 state=working不通知
state=blocked:kind=question 或 kind=auth不通知

应用处于活跃状态时,NeoServer 会对正在查看的终端抑制通知;来自其他会话的报告仍可通知你。应用不活跃时,只要 NeoServer 仍在接收终端输出,通知仍可出现。

重复的消息或进度更新不会产生重复提醒。NeoServer 会合并快速变化,同一会话的通知至少间隔五秒,并用最新的一条替换该会话之前的通知。

启用程序状态通知

  1. 打开 NeoServer 的设置,找到 Terminal Settings。
  2. 在终端设置页的底部找到 Program Status Notifications。它在 iOS 和 macOS 上默认开启。
  3. 运行一个会发送 OSC 7501 报告的程序。NeoServer 在收到第一个非空状态报告后才会请求系统通知权限,而不是在你打开终端或切换开关时。
  4. 在系统权限对话框中允许通知。如果之前拒绝过权限,请在操作系统的通知设置中为 NeoServer 开启通知。

初次测试时,请留在终端里直到回应权限对话框。然后运行下面的延时示例,并切换到 NeoServer 中的另一个终端。

通过 SSH 试用完成通知

用普通的 SSH 终端连接到一台服务器,粘贴以下内容:

printf '\033]7501;state=working:id=demo:app=demo\033\\'
sleep 10
printf '\033]7501;state=done:id=demo:app=demo\033\\'

在十秒延时期间,切换到 NeoServer 中的另一个终端会话。保持 NeoServer 打开,这就是一次对状态通知流程的简单测试。最终报告被处理后应该会送达一条完成通知,具体取决于系统通知设置。

要测试失败或审批通知,运行任一示例并在延时期间切换到其他会话:

# Report a failed task.
sleep 10
printf '\033]7501;state=error:id=demo:app=demo\033\\'
# Report a task waiting for approval.
sleep 10
printf '\033]7501;state=blocked:id=demo:kind=permission:app=demo\033\\'
sleep 10

审批示例末尾的延时是为了在 shell 返回提示符之前保持阻塞报告存在。请留出时间等通知送达再回到源终端。立即清除或替换报告可能取消待发送的提醒。

这些命令只是汇报状态。审批示例不会执行操作,也不会授予权限。轻点它的通知会打开终端,你可以在那里查看实际程序的请求。

在自己的脚本里加入状态报告

把命令包一层,让它的退出结果变成明确的完成或失败报告:

#!/bin/sh

printf '\033]7501;state=working:id=job:app=script\033\\'

# Replace this command with your build or other task.
if sh -c 'sleep 10'; then
    result=0
    state=done
else
    result=$?
    state=error
fi

printf '\033]7501;state=%s:id=job:app=script\033\\' "$state"
exit "$result"

在已连接的终端里运行该脚本,NeoServer 就能收到它的输出。这个示例保留了命令的退出码。如需自定义通知文字,协议的 title 和 msg 字段接受 Base64 编码的单行 UTF-8 文本;app 是简短的程序标识。

iOS 后台行为与收不到提醒的情况

这些是根据收到的终端输出生成的本地系统通知。NeoServer 必须持续接收并解析这些输出。如果 iOS 挂起或终止了应用,它就无法根据远程状态变化生成新通知。远程任务可能仍在运行,但新的提醒到不了你的 iPhone。

如果没有出现提醒,请检查以下几点:

  • 先用直接的 SSH 测试。 如果示例在直接 SSH 下正常、在 tmux 或 screen 里失败,请检查该层是否把 OSC 序列转发给了 NeoServer。
  • 从源终端切走。 处于活跃且可见状态的终端会保持安静,这是有意为之。
  • 同时检查权限和应用开关。 系统通知设置和专注模式设置都会影响横幅是否出现。
  • 让报告存活足够长的时间。 快速清除报告或改变状态可能取消或替换待发送的通知。
  • 检查报告的状态。 询问或认证类的暂停不会触发审批通知;审批通知要求 blocked 且 kind=permission。

轻点通知会选中一个现有会话。如果该会话已经关闭,NeoServer 会告知你;它不会自动重连或执行命令。如果应用处于锁定状态,导航会等你解锁后再进行。

连接的建立方法请阅读 NeoServer 快速开始。其余终端偏好设置请参阅 Terminal Settings。

NeoServer

SSH, Mosh, Docker & SFTP client for iPhone, iPad and Mac

App Store

准备好试试了吗?

NeoServer · SSH, Mosh, Docker & SFTP client for iPhone, iPad and Mac

App Store 免费下载