screenRIG
登录开始使用

文档

通知 CLI 命令

屏幕状态变化时，用通知和 webhook 告知人员与系统，跟踪事件日志，处理警报，并等待操作完成。

这里的每个命令都按 CLI 参考所述运行：全局标志、JSON 输出、退出代码、修订和重试。

操作

上传和发布以操作的形式运行。media upload、media replace 和 app upload 默认会等待各自的操作完成；这些命令用于完成你用 --no-wait 留在后台运行的操作。

operations show#

读取一个操作的当前状态。

operations show <id>
参数类型必填默认备注
<id>string是无启动该操作的信封中的操作 ID。
screenrig operations show op_01EXAMPLEOPERATION00000

state 为 receiving、queued、running、succeeded、failed 或 cancelled；最后三种表示操作结束。成功的操作带有 result，失败的操作带有 error，其中包含问题的 code 和 detail。

operations wait#

轮询一个操作直到完成。

operations wait <id> [--timeout MS] [--poll-ms MS]
参数类型必填默认备注
<id>string是无操作 ID。
--timeout MSinteger否120000等待的截止时间。它也限制每个底层请求。
--poll-ms MSinteger否1000等待时操作轮询间隔。
screenrig operations wait op_01EXAMPLEOPERATION00000

操作变为 succeeded、failed 或 cancelled 时，等待结束。失败或已取消的操作以 13 退出，并附带其自身的错误。等待超时则以 11 退出，操作仍继续运行；错误中的 next 为 operations wait ID，它会在不重新启动操作的情况下恢复等待。

operations cancel#

请求控制平面取消一个操作。

operations cancel <id>
参数类型必填默认备注
<id>string是无操作 ID。
screenrig operations cancel op_01EXAMPLEOPERATION00000

取消需要管理权限。返回的是已取消的操作。

事件

项目事件日志记录项目和车队的操作。发布的版本追加 application.published；调用 screenrig.emit(code) 的应用追加自身事件，这是其在屏幕上运行的最直接证据。

在线状态也记录在日志中。screen.offline在屏幕离线60秒后写入，screen.online在其重新上线时写入；60秒内重连不写入。screen.offline携带details.offline_since，且当屏幕之前在线过时，携带details.last_online_at。screen.online携带details.last_online_at，当屏幕之前离线后返回时，还携带details.offline_at。如所有screen.*事件，监听流上免费，代理可保持events follow打开以监视屏幕组。

播放器的内容更新以 screen.manifest_changed、screen.manifest_activated 和 screen.manifest_upgrade 的形式到达，其 details 包含 manifest_revision、state，以及存在时的 code 和 attempt。failed 的升级严重级别为错误，retrying、blocked 和 partial 为警告。

events list#

读取项目事件的一个有限页面。

events list [--after CURSOR] [--limit N] [--type TYPE] [--source project|log] [--screen-id ID] [--playlist-id ID] [--app-id ID]
参数类型必填默认备注
--after CURSORstring否第一页从上一页的 next_cursor 之后继续。
--limit Ninteger否50页面大小，1 到 200。
--type TYPEstring否每种类型一种事件类型，或以点结尾的前缀表示的事件族，如 note.。
--source SOURCEstring否projectproject 列出项目事件。log 列出播放器日志记录，这些记录属于某个屏幕：请与 --screen-id 一起使用。
--screen-id IDstring否每个屏幕以此屏幕为资源的事件，包括 SDK 发出的事件。 带 --source log 时，为该屏幕的播放器日志记录。
--playlist-id IDstring否每个播放列表以此播放列表为资源的事件，以及在 details.playlist_id 中指明它的事件，例如某个屏幕采用它。不能与 --source log 同用。
--app-id IDstring否所有应用应用资源、发布版本和 K/V 事件；不包含 SDK 发出的事件。 不能与 --source log 同用。
screenrig events list --limit 25
screenrig events list --type application.event --screen-id scr_SCREEN
screenrig events list --playlist-id pl_PLAYLIST
screenrig events list --source log --screen-id scr_SCREEN

SDK 的 emit() 和 emitConfirmed() 会添加以屏幕为资源的 application.event 记录。使用 --type application.event 读取，可选择添加 --screen-id。返回的 details.primitive_id 和 details.code 标识发出事件的图元和命名操作。--app-id 选择应用资源、发布版本和 K/V 事件，因此不包含这些屏幕事件。

--source log 读取播放器日志：播放器报告的状况，按项目的事件保留期保存。它没有序号，因此不会出现在 events follow 中，也不会投递到 webhook，且与它一起使用的 --playlist-id 和 --app-id 会被拒绝（usage_error，退出码 2）。类型错误的 ID 会在发出任何请求前被拒绝。到达历史末尾时，data.next_cursor 为 null。

默认输出为页面的一个 JSON 信封。使用 --human 时，输出每个事件一行 logfmt：at=、type=、severity= 和标量详情。

events follow#

保持事件流连接，实时打印事件。

events follow [--after CURSOR] [--timeout MS] [--type TYPE]
参数类型必填默认备注
--after CURSORstring否实时尾部从此游标恢复。
--timeout MSinteger否无截止日期结束整个跟踪，包括重新连接退避。
--type TYPEstring否每种类型一种事件类型，或以点结尾的前缀表示的事件族，如 note.。
screenrig events follow

断开或临时故障时，使用退避重连并从最后事件 ID 恢复。重连后重放免费。授权和未找到问题停止命令而非重试。

带 --type 时，流仍会携带所有事件，CLI 只打印匹配的事件，而描述流本身的 stream.* 帧始终会打印：screenrig events follow --type note. 用来监视项目备注。

默认输出为 NDJSON：每个事件一个信封，独立一行，而非单个信封。使用 --human 输出 logfmt 行。

通知

当屏幕状态改变时，通知会告知某个人或其他系统。电子邮件通知向每位收件人发送邮件，Webhook 通知发送签名的 HTTPS POST，Slack、Teams、PagerDuty 或 Telegram 通知则向聊天工具或告警呼叫服务发布消息。每个组织所有渠道合计、跨其所有项目最多 50 个，每个项目起初都有一封在屏幕离线 10 分钟时发给所有者的电子邮件。

通知会监视你指定的条件：

条件开始条件结束条件
screen_offline播放器已离线 60 秒。屏幕重新上线。
display_disconnected播放器报告其显示器已断开连接。显示器重新连接。
running_hot设备报告的温度达到或超过过热阈值。温度恢复正常。
on_battery带电池的设备报告其正在使用电池供电，未接通电源。设备报告了其他供电来源。
storage_full播放器的存储空间无法容纳其内容。存储不足的情况已消除。
content_stuck屏幕的内容更新正在重试、已失败、被阻止或仅部分完成。更新进入任何其他状态。
not_playing播放器显示错误而不是其内容。存储空间已满属于 storage_full。播放器的状态不再是错误。
loop_stalled一块在线、按计划运行且内容最新的屏幕，在超过其循环所允许的时间内没有开始任何图像或视频。图像或视频重新开始，或 screenRIG 不再判定该屏幕。
glass_blankscreenRIG 在覆盖整个循环的一组截图中，所有截图都是同一种纯色。连续两张截图显示出画面，或 screenRIG 不再判定该屏幕。
glass_frozenscreenRIG 在覆盖整个循环的一组截图中，所有截图都是同一幅画面。连续两张截图显示出变化的画面，或 screenRIG 不再判定该屏幕。
crashing播放器反复崩溃或重启其渲染器。从不：每次突发都是单独的一条提醒。
source_failed数据源刷新失败。刷新成功。
source_stale数据源持续失败，直到其数据过期。刷新成功。
card_data_stale卡片的数据带有过期时间写入，在屏幕显示该卡片期间到达了过期时间，且无人续期。对卡片数据的写入成功。
reach_dropped活动触达的屏幕比上次发布时更少，原因是屏幕离开了其标签或文件夹，或已被归档或删除。活动重新触达同样多的屏幕，或再次发布。
group_empty活动受众中的某个标签或文件夹不匹配任何屏幕。该标签或文件夹再次匹配屏幕，或发布时将其从受众中移除。

条件持续 --hold 分钟后会发出提醒（默认 10 分钟），因此短暂的重新连接不会发出提醒。如果条件先结束，则不发送任何内容；如果在提醒发出后结束，则随后会发送一条“已解决”提醒。crashing 会立即发送。如果有人在保持时间内确认或暂缓了该屏幕的警报，或有静音覆盖该屏幕，提醒也会被跳过。--tag 将通知限定为带有该标签的屏幕；不使用它时，所有屏幕都适用。

每条提醒都有严重级别。已开启的提醒，对 screen_offline 为 error，对其他每个条件为 warning，已解决的提醒或测试为 info。--min-severity LEVEL（info、warning 或 error）不会创建低于该级别的已开启提醒，已解决提醒跟随其对应的已开启提醒。--severity CONDITION=LEVEL 可重复，设置此通知中某个条件的级别，例如 --severity not_playing=error；它计入 --min-severity。Teams 和 PagerDuty 始终显示该级别，通知设置了 --min-severity 或 --severity 时，电子邮件、Slack 和 Telegram 文本也会写明该级别，webhook 请求体携带 severity。

--active-hours SPEC 仅在每周窗口内发送已开启的提醒，窗口按 --timezone ZONE 解读，该项为必填。SPEC 为 DAYS HH:MM-HH:MM，例如 "Mon-Fri 08:00-22:00"；最多可重复 16 次。使用 --outside-hours hold（默认）时，在时段之外到期的提醒会等到下一个窗口，若届时条件仍然成立才发出，因此条件先行解除则不发送任何内容。使用 drop 时，该提醒会作为 outside_hours 被跳过，notifications deliveries 会列出它。已发送的已开启提醒对应的已解决提醒始终发出，crashing 与其他条件一样遵循时段，暂缓会先检查，而 notifications test 忽略时段、严重级别和受众。

--audience FILE（内联 JSON、文件，或用 - 表示标准输入）按活动受众的规则选择屏幕，例如 {"all":[{"tag":"level2"},{"tag":"overhead"}]} 表示同时带有两个标签的屏幕；--all-tags TAG 和 --any-tag TAG 分别是标签的 all 规则和 any 规则的简写，--tag 表示任一标签。--tag、--any-tag、--all-tags 和 --audience 互相排斥。

loop_stalled、glass_blank 和 glass_frozen 是 screenRIG 根据收到的播放报告和截图得出的判定，对其无法判断的情形不作判定：离线的屏幕、显示器关闭的屏幕、处于接管或已暂停的屏幕、只显示单张静态图或视频墙的屏幕，或其 Player 不发送播放序号的屏幕。当 screenRIG 不再判定一块曾处于其中某种状态的屏幕时，警报会关闭，但电子邮件、Slack、Teams 和 Telegram 不会发送已解决通知，因为没有任何迹象表明屏幕已恢复；PagerDuty 仍会解决其事件。

source_failed 和 source_stale 监视的是项目的数据源而不是屏幕：通知会写明数据源并链接其页面，并且 --tag 永远不会匹配数据源。

card_data_stale 监视的是卡片，而不是屏幕。写入卡片数据时，设置一个与写入方的计划相匹配的过期时间（card data put --ttl 30m）：当负责续期的作业或智能体停止时，数据会过期，卡片在每块显示它的屏幕上都会变为空白，并由此条件通知您。通知会写明卡片以及其数据的过期时间，并链接到放置该卡片的页面的页面编辑器。数据源的文档不会在这里通知（由 source_stale 负责），没有屏幕显示的卡片、没有过期时间的数据，或已被删除的数据也不会通知。--tag 从不匹配卡片。

reach_dropped 和 group_empty 监视的是活动而不是屏幕。提醒会写明活动及其此前和现在触达的屏幕，或写明为空的标签或文件夹，并链接到该活动的日历。活动属于项目，因此 --tag、--any-tag、--all-tags 和 --audience 永远不会限制这两者；--min-severity、--severity、--active-hours 和 --hold 与其他条件一样适用，并且两者默认都是 warning。--reach-drop-screens N 和 --reach-drop-percent P 仅在屏幕减少至少 N 个且至少占活动发布时所触达屏幕的 P% 时才发送 reach_dropped 提醒；减少必须同时满足两者，未设置时任何减少都会发出提醒。它们需要 --conditions 中有 reach_dropped。活动的每个空标签或文件夹各自是一条提醒，notifications deliveries 将其显示为 audience_group（tag:Lobby 或 folder:sfd_…）。发布时若把空分组从受众中移除，会关闭 PagerDuty 事件和 webhook 的警报，但不会发送恢复邮件或聊天消息。

邮件发送到每位收件人的已验证地址；约两分钟内到期的所有提醒合并为每位收件人一封邮件，其中包含指向控制台中每个屏幕和该通知的链接。收件人为 owner（即提醒发送时拥有该项目的人）和项目成员的用户 ID。没有已验证地址或已离开项目的收件人会被跳过。通知邮件和屏幕状态提醒免费。

每封邮件都带有专属于其收件人的取消订阅链接：邮件应用中的取消订阅按钮，以及页脚中的链接。点击后，该通知的邮件将不再发给这一个人，无需登录，打开的页面上有 Resubscribe 按钮。其他收件人不受影响，此人仍留在收件人中。notifications show 会用 unsubscribed 列出已取消订阅的人，notifications resubscribe 可让他们重新收到邮件。没有人可发邮件的通知会以 no_recipients 跳过。

Webhook 通知以 JSON 形式 POST 每条提醒，你可按验证交付中所述进行验证。使用 --events 时，它还会在原始项目事件发生时 POST 这些事件；这些交付按Webhooks中所述计量。

Slack、Teams、PagerDuty 或 Telegram 通知会针对每次故障、每块屏幕，或每组屏幕发布一条消息：屏幕、发生了什么变化、从何时开始、项目、屏幕链接，以及离线屏幕恢复时的可能原因（若届时已知）。第一条消息发出后会再发一条恢复消息，在 PagerDuty 中它会解决第一条消息打开的事件。凭据只需提供一次（--slack 使用传入 Webhook 的 URL，--teams 使用 Workflows Webhook 的 URL，--pagerduty 使用 Events API v2 路由密钥，--telegram 使用机器人令牌并配合 --telegram-chat）；它会被加密封存，不再显示，destination_hint 只显示遮蔽后的末尾。- 会从 stdin 的一行读取，使其不进入你的 shell 历史。发布失败会重试 24 小时，连续失败 72 小时的通知会被停用。

当三个或更多屏幕在彼此五分钟内进入同一条件，并且共享同一网络、位置、型号、Player 版本或标签时，电子邮件、Slack、Teams、PagerDuty 或 Telegram 通知会为它们发送一条提醒，而不是每个屏幕一条；该组最后一个屏幕恢复时，同样用一条提醒说明该组；其余每个屏幕的提醒会被跳过，记为 grouped。Webhook 仍然为每个屏幕发送一条提醒。

读取通知及其投递记录需要只读访问；创建、更改、测试和删除通知、轮换其密钥以及重新订阅某人需要管理访问。

问题代码退出含义
webhook_url_rejected8URL 不是 https，端口非 443 或 8443，或其主机不只解析为公共互联网地址。error.detail 说明服务器原因。未创建或更改任何内容。
notification_destination_rejected8目标与其渠道不符，或是已停用的 Office 365 连接器 URL。error.detail 会说明正确的形式。未创建或更改任何内容。
notification_limit_reached5组织已有 50 个通知。请先删除一个。
revision_conflict6--expect-rev 版本已过时。运行 notifications show，然后重试。
rate_limited7此组织一分钟内超过 20 次 notifications test 调用。
invalid_request8--email 收件人不是项目成员，或使用了属于其他渠道的选项，例如在电子邮件通知上使用 --url。未创建或更改任何内容。

notifications create#

创建电子邮件、Webhook、Slack、Teams、PagerDuty 或 Telegram 通知。

notifications create (--email RECIPIENTS | --webhook URL | --slack URL | --teams URL | --pagerduty KEY
                      | --telegram TOKEN --telegram-chat CHAT_ID) [--conditions LIST] [--events TYPES]
                     [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE] [--hold MINUTES]
                     [--min-severity LEVEL] [--severity CONDITION=LEVEL]... [--active-hours SPEC]...
                     [--timezone ZONE] [--outside-hours hold|drop] [--reach-drop-screens N] [--reach-drop-percent P]
                     [--description TEXT] [--disabled]
参数类型必填默认备注
--email RECIPIENTSstring一个渠道标志无向这些逗号分隔的收件人发送邮件：owner，或项目成员的用户 ID，最多 20 个。
--webhook URLstring一个渠道标志无一个 https URL，端口为 443（默认）或 8443，主机仅解析为公共互联网地址。服务器在每次写入时检查，并在每次交付前再次检查。携带凭据的 URL（user:pass@ 或 token@）或带有 # 片段的 URL 在本地拒绝，退出码为 2。
--conditions LISTstring是（Webhook 除外）无以逗号分隔的条件，取自上表。Webhook 需要此项、--events 或两者兼有。
--slack URLstring一个渠道标志无通过 hooks.slack.com 上的传入 Webhook URL 发布到 Slack，或用 - 从 stdin 的一行读取。
--teams URLstring一个渠道标志无通过 Workflows Webhook 的 URL（触发器“收到 Teams Webhook 请求时”）发布到 Teams，或用 - 从 stdin 读取。Office 365 连接器 URL 已停用，会被拒绝。
--pagerduty KEYstring一个渠道标志无使用 32 个字符的 Events API v2 路由密钥触发并解决 PagerDuty 事件，或用 - 从 stdin 读取。
--telegram TOKENstring一个渠道标志无使用机器人令牌发布到 Telegram，或用 - 从 stdin 读取。需要 --telegram-chat。
--telegram-chat CHAT_IDstring配合 --telegram无要发布到的聊天：其数字 ID，例如 -1001234567890，或 @channelname。
--events TYPESstring否无仅限 webhook。同时 POST 这些原始项目事件：1 到 32 个逗号分隔的精确类型，如 screen.online，或以 .* 结尾的前缀，如 screen.*。
--tag TAGstring否每个屏幕仅限带有其中任一标签的屏幕。重复该标志或用逗号分隔，最多 16 个标签。
--hold MINUTESinteger否10条件必须持续多长时间才会发出提醒，0 到 1440。crashing 不适用保持时间。
--all-tags TAGstring否无仅带有所列全部标签的屏幕。重复该标志或用逗号分隔。
--any-tag TAGstring否无仅带有至少一个所列标签的屏幕，如 --tag。重复该标志或用逗号分隔。
--audience FILEstring否每个屏幕作为 JSON 格式活动受众规则的屏幕：内联、文件，或用 - 表示标准输入。不能与标签选项一起使用。
--min-severity LEVELstring否无info、warning 或 error：低于该级别的已开启提醒不发送。
--severity CONDITION=LEVELstring否默认值设置此通知中某个条件的严重级别。重复该标志。
--active-hours SPECstring否始终仅在此每周窗口内发送已开启的提醒，DAYS HH:MM-HH:MM 例如 "Mon-Fri 08:00-22:00"。最多重复 16 次。需要 --timezone。
--timezone ZONEstring配合 --active-hours无读取时段所用的 IANA 时区，例如 America/Los_Angeles。
--outside-hours MODEstring否holdhold 等待下一个窗口；drop 跳过该提醒。
--reach-drop-screens Ninteger否任何减少仅与 reach_dropped 同用：仅当活动至少失去 N 个屏幕（1 或更多）时才发送提醒。
--reach-drop-percent Pinteger否任何减少仅与 reach_dropped 同用：同时要求活动发布时所触达的屏幕至少减少 P% (1 到 100)。
--description TEXTstring否无最多 200 个字符。
--disabledboolean否关闭创建时禁用。在 notifications update --enable 之前不会发送任何内容。
screenrig notifications create --email owner --conditions screen_offline,display_disconnected --tag Lobby
screenrig notifications create --webhook https://hooks.example.com/screenrig --conditions screen_offline,crashing
screenrig notifications create --slack - --conditions screen_offline,crashing < slack-url.txt

信封就是该通知。webhook 通知的信封在 data.secret（whsec_…）中携带其签名密钥，并附有警告 webhook_secret_shown_once。请立即将密钥存入接收方的密钥库。只有 notifications rotate-secret 会再次返回该密钥，CLI 也不会将其写入配置、操作日志或写恢复状态。中断或不明确的创建之后，24 小时内重新运行相同命令：它会重用保存的幂等键，服务器返回相同答案，包括密钥。提醒从通知创建后的第一个事件开始。

notifications list#

列出该项目的通知，绝不包含其密钥。

notifications list
screenrig notifications list

每一行是任意渠道的一条通知，按从旧到新排列，带有其 status。Slack、Teams、PagerDuty 或 Telegram 通知会在 --human 的 TO 列显示 destination_hint，即遮蔽到主机和末尾字符的凭据。在管理访问以下，webhook 的 url 为空且 url_redacted 为 true，TO 显示 (withheld)。

notifications show#

检查通知及其交付健康状况。

notifications show <id>
参数类型必填默认备注
<id>string是无通知 ID，ntf_（除 Webhook 外的任何渠道）或 whk_（Webhook）。
screenrig notifications show ntf_01EXAMPLENOTICE00000

status 为 active、failing（自 failing_since 起没有任何交付成功时）或 disabled。连续失败 72 小时后，通知会因 disabled_reason: delivery_failures 被禁用，事件日志会记录 notification.disabled。设置了暂停提醒时会出现 snoozed_until。last_success_at 和 last_failure_at 报告最新结果。revision 是 --expect-rev 所校验的值。min_severity、severity、active_hours（带 outside）、audience 和 reach_drop 在设置后才会出现，电子邮件通知还会列出 unsubscribed。

notifications update#

更改通知的收件人、URL、目标、条件、屏幕、等待时间、暂停或启用状态。

notifications update <id> [--email RECIPIENTS | --url URL | --destination VALUE] [--telegram-chat CHAT_ID]
                          [--conditions LIST | --clear-conditions]
                          [--events TYPES | --clear-events] [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE | --all-screens]
                          [--hold MINUTES] [--min-severity LEVEL | --clear-min-severity]
                          [--severity CONDITION=LEVEL]... [--clear-severity]
                          [--active-hours SPEC]... [--timezone ZONE] [--outside-hours hold|drop] [--clear-active-hours]
                          [--reach-drop-screens N] [--reach-drop-percent P] [--clear-reach-drop]
                          [--description TEXT | --clear-description] [--enable | --disable]
                          [--snooze WHEN] [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无通知 ID，ntf_（除 Webhook 外的任何渠道）或 whk_（Webhook）。
--email RECIPIENTSstring至少有一处更改未更改邮件通知：替换收件人。
--url URLstring至少有一处更改未更改Webhook 通知：替换 URL，校验方式与 create 相同。
--destination VALUEstring至少有一处更改未更改Slack、Teams、PagerDuty 和 Telegram 通知：替换凭据，检查方式与 create 相同。- 从 stdin 的一行读取。
--telegram-chat CHAT_IDstring至少有一处更改未更改Telegram 通知：替换聊天。
--conditions LISTstring至少有一处更改未更改替换条件。
--clear-conditionsboolean至少有一处更改关闭移除所有条件。此后 webhook 需要 --events。
--events TYPESstring至少有一处更改未更改Webhook 通知：替换原始项目事件。
--clear-eventsboolean至少有一处更改关闭Webhook 通知：停止 POST 原始项目事件。此时它需要条件。
--tag TAGstring至少有一处更改未更改替换屏幕标签；如果通知设有受众，也一并替换。
--all-screensboolean至少有一处更改关闭移除屏幕标签和受众；该通知覆盖每个屏幕。
--hold MINUTESinteger至少有一处更改未更改0 到 1440。
--all-tags TAGstring至少有一处更改未更改用带有所列全部标签的屏幕替换屏幕。
--any-tag TAGstring至少有一处更改未更改用带有至少一个所列标签的屏幕替换屏幕，如 --tag。
--audience FILEstring至少有一处更改未更改用 JSON 格式的活动受众规则替换屏幕：内联、文件，或用 - 表示标准输入。
--min-severity LEVELstring至少有一处更改未更改info、warning 或 error。
--clear-min-severityboolean至少有一处更改关闭移除严重级别过滤。
--severity CONDITION=LEVELstring至少有一处更改未更改用这些替换严重级别覆盖。重复该标志。
--clear-severityboolean至少有一处更改关闭移除所有严重级别覆盖。
--active-hours SPECstring至少有一处更改未更改用这些替换窗口。最多重复 16 次。--timezone 默认为该通知已有的时区。
--timezone ZONEstring至少有一处更改未更改读取时段所用的 IANA 时区。单独使用时，保留当前窗口。
--outside-hours MODEstring至少有一处更改未更改hold 或 drop。单独使用时，保留当前窗口。
--clear-active-hoursboolean至少有一处更改关闭移除活动时段。为其保留的提醒会立即重新判定。
--reach-drop-screens Ninteger至少有一处更改未更改替换 reach_dropped 提醒要求活动至少失去的屏幕数量。
--reach-drop-percent Pinteger至少有一处更改未更改替换活动至少必须失去的已发布触达百分比。
--clear-reach-dropboolean至少有一处更改关闭移除阈值，使任何减少都会发出提醒。仅在同时移除时，才将 reach_dropped 从 --conditions 中去掉。
--description TEXTstring至少有一处更改未更改最多 200 个字符。
--clear-descriptionboolean至少有一处更改关闭移除描述。
--enableboolean至少有一处更改关闭清除失败状态，并从记录该更改的事件开始；禁用期间产生的任何内容都不会发送。
--disableboolean至少有一处更改关闭停止发送提醒；待处理的提醒失败，错误为 webhook_disabled。
--snooze WHENstring至少有一处更改未更改在此之前不发送任何内容：时长，如 30m、1h 或 2d（不足 30 天），带秒和偏移的 RFC 3339 时间点，或用 off 结束暂停提醒。期间到期的提醒会被跳过，不会稍后补发。
--expect-rev REVISIONstring否无可选修订前提条件。
screenrig notifications update ntf_01EXAMPLENOTICE00000 --snooze 2h

update 只会更改您传递的字段。渠道永远不会改变：--email 适用于电子邮件通知，--url 和 --events 适用于 webhook，--destination 和 --telegram-chat 适用于聊天或寻呼通知，其他渠道的选项会返回 invalid_request（退出码 8）。--email、--url 和 --destination 最多给出一个。屏幕标签和受众互相排斥：设置其中一个会清除另一个。电子邮件通知至少保留一个条件，webhook 保留条件或事件。签名密钥不变；请使用 notifications rotate-secret。

notifications delete#

删除通知。其待处理的提醒失败，错误为 webhook_deleted。

notifications delete <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无通知 ID，ntf_（除 Webhook 外的任何渠道）或 whk_（Webhook）。
--expect-rev REVISIONstring否无可选修订前提条件。
screenrig notifications delete ntf_01EXAMPLENOTICE00000

此后无法再读取其投递日志；其记录会随事件保留期过期。

notifications rotate-secret#

替换 Webhook 通知的签名密钥，并只返回一次新密钥。其他渠道没有密钥，会返回 invalid_request（退出码 8）。

notifications rotate-secret <id> [--expect-rev REVISION]
参数类型必填默认备注
<id>string是无通知 ID，ntf_（除 Webhook 外的任何渠道）或 whk_（Webhook）。
--expect-rev REVISIONstring否无可选修订前提条件。
screenrig notifications rotate-secret whk_01EXAMPLEWEBHOOK00000

信封在 data.secret 中携带新密钥，并附带警告 webhook_secret_shown_once；请立即存储。之前的密钥停止签名，但最多允许一个已在进行中的尝试仍可使用旧密钥签名，因此短时间内接受两者。中断或模糊的轮换后，24 小时内重新运行相同命令以恢复相同密钥。

notifications test#

仅向此通知发送一封测试邮件、一个签名的测试 POST 或一条聊天消息。

notifications test <id>
参数类型必填默认备注
<id>string是无通知 ID，ntf_（除 Webhook 外的任何渠道）或 whk_（Webhook）。
screenrig notifications test ntf_01EXAMPLENOTICE00000

信封是排队的交付。它只尝试一次，不重试；对已禁用或已暂停提醒的通知同样有效，并且从不改变通知的失败状态。每个组织每分钟最多 20 次测试交付；超出则为 rate_limited（退出码 7）。使用 notifications deliveries 读取结果。

PagerDuty 测试会触发一个键为 screenrig:test:DELIVERY_ID 的信息事件并立即解决，因此不会留下未解决的事件。

notifications resubscribe#

让已取消订阅某个通知邮件的人重新收到邮件。

notifications resubscribe <id> --user USER_ID
参数类型必填默认备注
<id>string是无电子邮件通知的 ntf_ ID。
--user USER_IDstring是无该人的用户 ID，即 notifications show 在 unsubscribed 下列出的那个。
screenrig notifications resubscribe ntf_01EXAMPLENOTICE00000 --user usr_01EXAMPLEPERSON0000

信封就是该通知。未取消订阅的人不会带来任何变化。重新订阅某人会提高修订号并追加 notification.updated。其他渠道或项目的通知为 not_found（退出码 4）。

notifications deliveries#

读取通知的交付日志，最新优先。

notifications deliveries <id> [--before CURSOR] [--limit N]
参数类型必填默认备注
<id>string是无通知 ID，ntf_（除 Webhook 外的任何渠道）或 whk_（Webhook）。
--before CURSORstring否最新事件上一页的 next_cursor（whc1_… 或 whc2_…）。
--limit Ninteger否50每页行数，1 到 200。
screenrig notifications deliveries ntf_01EXAMPLENOTICE00000 --limit 20

每一行是一个事件，或某个屏幕上一个条件的一条提醒：event_type、state（pending、succeeded、failed 或 skipped）、attempts、last_status，以及固定的 last_error 类别，如 http_status、timeout、connection_failed、tls_failed、dns_failed、url_rejected、email_failed、email_rejected 或 secret_unavailable。屏幕提醒还有 condition、phase（opened 或 resolved）、screen_id、screen_name（数据源、活动或卡片则为其 id 和名称）和 since，电子邮件提醒还有 emailed，即送达的人数。无需发送的提醒为 skipped，原因在 last_error 中：condition_cleared（屏幕在等待结束前离开了该状态）、not_opened（没有已发出的提醒需要解决）、snoozed（通知已暂停提醒）、acknowledged（等待期间有人确认或暂缓了该屏幕的警报）、muted（静音覆盖了该屏幕）、outside_hours（通知的生效时段已关闭，且它会丢弃时段外的提醒）、below_severity（提醒低于 min_severity，该级别是在提醒入队之后调高的）、planned_reboot（屏幕在因 screenRIG 发出的重启而重启期间离线、断开显示或崩溃，直到重启完成或发出后十分钟）、no_recipients（没有收件人是拥有已验证地址且未退订的项目成员）、grouped（屏幕与其他屏幕一起进入该条件，另一行的提醒一并说明了它们）或 no_longer_judged（loop_stalled、glass_blank 或 glass_frozen 条件因 screenRIG 不再判断该屏幕而结束，reach_dropped 因活动被重新发布或删除而结束，group_empty 因某次发布将标签或文件夹从其受众中移除而结束，card_data_stale 因卡片的数据被删除而结束，所以没有报告恢复）。说明一组屏幕的提醒带有 group（id、attribute、value 和 count），该组其余每个屏幕带有 group_id；--human 在 GROUP 列中同时显示两者。行从不包含接收方的响应。日志末尾的 next_cursor 为 null。失败的尝试会按退避重试，从 30 秒起逐次翻倍直到一小时，持续 24 小时，之后该行为 failed。

验证交付

屏幕状态提醒的主体是 JSON：type（alert.opened 或 alert.resolved）、id（交付 ID）、notification_id、project_id、condition、screen（id 和 name）、since（条件开始的时刻）、at（条件保持足够长时间或已清除的时刻）、event_id 和 severity（info、warning 或 error：alert.opened 时为条件的级别，alert.resolved 时为 info）。screen_offline 的 alert.resolved 还包含 likely_cause（device_restart、app_crash、app_restart、network 或 platform），原因未知时为 null。对于数据源、活动或卡片，screen 指向它；活动提醒在 reach_dropped 时增加 reach（published 和 current 个屏幕），在 group_empty 时增加 audience_group（kind 为 tag 或 folder，以及 value）。来自 --events 的原始事件与 events list 返回的 JSON 对象相同。头部为 ScreenRig-Webhook-Id（通知 ID）、ScreenRig-Event-Id（重试间保持不变：提醒为交付 ID，事件为事件游标）和 ScreenRig-Signature: t=<unix seconds>,v1=<hex>，其中 v1 是对 "<t>.<raw body>" 计算的 HMAC-SHA256，以密钥字符串为密钥。请在解析 JSON 之前基于原始字节计算，以恒定时间比较，拒绝过期的 t，并基于 ScreenRig-Event-Id 去重，因为交付至少一次且无序。请在 10 秒内返回 2xx；不跟随重定向。

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

警报

警报是某个屏幕上持续存在的一个问题。当屏幕进入屏幕通知条件之一（screen_offline、display_disconnected、running_hot、on_battery、storage_full、content_stuck、not_playing、loop_stalled、glass_blank 或 glass_frozen）时，无论是否有通知在监视，警报都会打开，条件结束时则解决。每个屏幕的每个条件最多有一条未解决的警报。崩溃激增、数据源、卡片和活动是提醒，绝不是警报。因 screenRIG 发出的重启（screen reboot 或重启计划）而重启的屏幕，在重启完成或发出后十分钟之前，不会打开 screen_offline 或 display_disconnected 警报；届时条件仍然成立才会打开警报。alerts list 显示当前未解决的内容。

未解决的警报会一直需要关注，直到有人确认或暂缓它，或有静音覆盖其屏幕。确认表示已有人在处理：警报保持打开，记录是谁在何时确认的，并且在解决之前无需关注。暂缓是确认到最多 30 天后的某个时间，到那时如果警报仍未解决，就再次需要关注。之后的确认或暂缓会替换之前的。警报处于已确认或已暂缓状态时，通知中仍在保持时间内、与该警报有关的提醒会被跳过。

静音用于维护：它指定屏幕、标签或两者，并在最多 30 天后的某个时间结束。只要屏幕 ID 在列表中，或带有列表中的标签，静音就覆盖该屏幕；因此之后才加上标签的屏幕也会被覆盖，去掉标签的屏幕则不再被覆盖。被静音屏幕的警报仍会打开和解决，并标记为 muted，但从不需要关注，所有通知都会跳过它们的提醒。一个组织跨其所有项目最多有 50 条当前有效的静音。

alerts list 中的 counts.attention 是控制台在“警报”旁边显示的数字。打开、解决和确认警报会向项目事件日志追加 screen.alert_opened、screen.alert_resolved 和 screen.alert_acknowledged，创建和结束静音会追加 alert_mute.created 和 alert_mute.deleted。与所有 screen.* 事件一样，它们在监听流和 webhook 上免费。已解决的警报会在套餐的事件保留期内继续列出。读取警报和静音需要只读访问；确认、暂缓、静音和取消静音需要管理访问。

问题代码退出含义
alert_not_open5该警报已解决，因此没有可确认或暂缓的内容。请运行 alerts list，改用未解决的警报。
alert_mute_limit_reached5组织已有 50 条当前有效的静音。请用 alerts unmute 结束一条，或用一条按标签设置的静音覆盖更多屏幕。
invalid_request8--until 的时间点超过 30 天之后。未做任何更改。
not_found4项目中没有使用此 ID 的警报或静音。已解决的警报在套餐的事件保留期之后消失，静音在结束后消失。

alerts list#

列出此项目的警报，未解决的在前。

alerts list [--state open|resolved|all] [--screen-id ID] [--before CURSOR] [--limit N]
            [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
--state STATEstring否openopen、resolved 或 all。
--screen-id IDstring否每个屏幕仅此屏幕的警报。
--before CURSORstring否第一页上一页的 next_cursor。
--limit Ninteger否100每页行数，1 到 200。
--format FORMATstring否jsonjson，或 csv、xlsx、pdf，将警报写入文件而不是直接打印。
--output FILE路径否./alerts.FORMAT使用 --format csv、xlsx 或 pdf 时写入的文件。不能与 json 一起使用。
screenrig alerts list
screenrig alerts list --state all --screen-id scr_01EXAMPLESCREEN00000000
screenrig alerts list --state all --format csv --output alerts.csv

每一行是一条警报：id（alr_…）、screen_id、screen_name、condition、state（open 或 resolved）、since（条件开始的时间）、解决后有 resolved_at、确认后有 acknowledged_at 和 acknowledged_by（kind、id 和 name 为确认者，即人员或智能体）、暂缓期间有 snoozed_until，以及 muted 和 attention。未解决的警报排在前面，最新的在先。counts 包含整个项目的 open 和 attention，与页面和筛选条件无关，next_cursor 在末尾为 null。

使用 --format csv、xlsx 或 pdf 时，文件包含符合筛选条件的所有警报，最多 50,000 行，信封中带有该文件的 path、bytes 和 sha256。这些文件见报告与导出。

alerts show#

显示一条警报。

alerts show <id>
参数类型必填默认备注
<id>string是无alr_ 警报 ID。
screenrig alerts show alr_01EXAMPLEALERT000000

信封即该警报，格式与 alerts list 的一行相同。

alerts ack#

确认一条未解决的警报：已有人在处理。

alerts ack <id>
参数类型必填默认备注
<id>string是无alr_ 警报 ID。
screenrig alerts ack alr_01EXAMPLEALERT000000

警报保持打开，在解决之前无需关注；acknowledged_by 是确认的人员或智能体，acknowledged_at 是时间。通知中仍在保持时间内的提醒会被跳过。再次确认会替换之前的确认或暂缓。已解决的警报会返回 alert_not_open（退出码 5）。信封即该警报，事件日志会记录 screen.alert_acknowledged。

alerts snooze#

将未解决的警报确认到某个时间，使其到那时再次需要关注。

alerts snooze <id> (--for DURATION | --until TIME)
参数类型必填默认备注
<id>string是无alr_ 警报 ID。
--for DURATIONduration--for、--until 之一无从现在起暂缓多久：时长，如 30m、4h 或 2d，最长 29d23h59m。
--until TIMEstring--for、--until 之一无暂缓何时结束：带秒和偏移的 RFC 3339 时间点，如 2026-11-01T09:00:00-07:00，最多 30 天后。
screenrig alerts snooze alr_01EXAMPLEALERT000000 --for 4h

snoozed_until 是暂缓结束的时间。在此之前，警报无需关注，通知中仍在保持时间内的提醒会被跳过，与 alerts ack 相同；如果到那时警报仍未解决，则再次需要关注。已解决的警报会返回 alert_not_open（退出码 5）。

alerts mute#

为维护让屏幕静音。

alerts mute [--screen-id ID]... [--tag TAG]... (--for DURATION | --until TIME) [--note TEXT]
参数类型必填默认备注
--screen-id IDstring--screen-id、--tag 中至少一个无一个 scr_ 屏幕 ID。重复输入，或用逗号分隔列出；最多 100 个。
--tag TAGstring--screen-id、--tag 中至少一个无带有此标签的每个屏幕。重复输入，或用逗号分隔标签；最多 16 个。
--for DURATIONduration--for、--until 之一无从现在起静音持续多久：时长，如 30m、4h 或 2d，最长 29d23h59m。
--until TIMEstring--for、--until 之一无静音何时结束：带秒和偏移的 RFC 3339 时间点，如 2026-11-01T09:00:00-07:00，最多 30 天后。
--note TEXTstring否无让屏幕静音的原因，供查看该静音的人阅读；最多 200 个字符。
screenrig alerts mute --tag Lobby --for 2h --note "Rewiring the lobby displays"

信封即该静音：id（amt_…）、screen_ids、tags、until、note、created_by 和 created_at。所有被覆盖屏幕的警报会立即显示 muted，包括已经打开的警报。一个组织跨其所有项目最多有 50 条当前有效的静音；超出则返回 alert_mute_limit_reached（退出码 5），已结束的静音不再计数。如果静音请求被中断或结果不明，请先查看 alerts mutes：在 24 小时内用 --until 重新运行相同命令会返回同一条静音，而用 --for 重新运行则从新的时间起算并创建另一条。

alerts mutes#

列出尚未结束的静音，最先结束的排在最前。

alerts mutes
screenrig alerts mutes

每一行都是 alerts mute 输出的一条静音。

alerts unmute#

立即结束一条静音。

alerts unmute <mute-id>
参数类型必填默认备注
<mute-id>string是无amt_ 静音 ID。
screenrig alerts unmute amt_01EXAMPLEMUTE0000000

这些屏幕上未解决的警报会再次需要关注，之后的提醒也不再因静音而被跳过。已结束的静音会返回 not_found（退出码 4）。事件日志会记录 alert_mute.deleted。

Webhooks

Webhook 以签名 POST 的形式，将本项目自身的事件发送到你运行的 HTTPS 端点，因此匹配的事件可以唤醒智能体、机器人或你自己的服务。每个匹配的事件以 events list 返回的同一 JSON 对象的形式到达。Webhook 是原始形态的通知：它计入组织的 50 条通知上限，notifications list 会显示它。新建请使用 notifications，它还会发送邮件和屏幕状态提醒。

每次投递尝试都免费，不计入组织每小时的智能体请求上限。

webhooks create --url URL --event-types TYPES [--description TEXT] [--disabled]
webhooks list
webhooks show <id>
webhooks update <id> [--url URL] [--event-types TYPES] [--description TEXT | --clear-description]
                     [--enable | --disable] [--expect-rev REVISION]
webhooks delete <id> [--expect-rev REVISION]
webhooks rotate-secret <id> [--expect-rev REVISION]
webhooks test <id>
webhooks deliveries <id> [--before CURSOR] [--limit N]

当组织已有 50 个通知时，webhooks create 返回 webhook_limit_reached（退出码 5），而 notifications create 返回 notification_limit_reached。URL 被拒绝时，两者都返回 webhook_url_rejected（退出码 8）。

--url 接受端口为 443 或 8443、且主机仅解析为公共互联网地址的 https URL，检查方式与 notifications create 相同；包含凭据或 # 片段的 URL 会在本地被拒绝，退出码为 2。--event-types 接受 1 到 32 个以逗号分隔的精确类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*）。--description 最多 200 个字符。--disabled 以禁用状态创建 webhook。webhooks update --enable 会清除失败状态并从当前事件开始，因此禁用期间的内容不会发送，而 --disable 会使待处理的投递以 webhook_disabled 失败。--expect-rev 保护修订版本（revision_conflict，退出码 6）。

webhooks create 和 webhooks rotate-secret 会在 data.secret 中只打印一次签名密钥，并附带警告 webhook_secret_shown_once；调用被中断或结果不明时，请在 24 小时内重新运行相同命令，即可取回相同的响应。投递从 webhook 创建之后的第一个事件开始。webhooks test 只为此 webhook 将一次 webhook.test 投递加入队列；它对已禁用的 webhook 同样有效，只尝试一次且不重试，与其他投递一样计量，并限制为每个组织每分钟 20 次（rate_limited，退出码 7）。webhooks list 按从旧到新列出此项目的 webhook 通知，只读凭据收到的每个 url 为空且 url_redacted 为 true。webhooks deliveries 从最新的事件开始读取日志，每页 1 到 200 行（默认 50），用 next_cursor（whc1_…）作为 --before；每行的 state 为 pending、succeeded 或 failed，带有 last_status 和固定的 last_error 类别。验证投递的方法见验证交付。

其他命令组