告诉你的智能体结果。让它验证

为什么是智能体原生？

screenRIG 从控制平面起即为自主智能体打造。官方插件为智能体提供媒体、播放列表、屏幕、应用和播放证据的结构化命令。结果为 JSON 封装，每个错误说明下一步操作，重试写入复用幂等键，发布报告播放器是否实际播放内容。智能体可执行屏幕任务，检查结果并通过同一工具界面修正。什么是智能体原生。

如何从 Claude、Codex、Grok 或 Grok Bot 运行此功能？

每个支持的智能体都使用相同的官方插件。终端智能体（Claude Code、ChatGPT Codex、Grok Build）通过市场命令安装；Meta Muse、Grok Bot、ChatGPT dots、Gemini Spark 和 Hermes 通过聊天提示安装。设置仅在第一步不同，请遵循你的智能体指南：Meta Muse、Grok Bot、ChatGPT dots、Claude Code、Hermes、ChatGPT Codex、Gemini Spark，或 Start 用于 Grok Build。以下发布工作流程在所有地方相同。

如何在智能体中使用 screenRIG

描述内容、目标屏幕、布局或尺寸、时间安排，以及完成时所需的证据。向代理提供资源和源事实。

如果需要安装插件，请粘贴：

I authorize you to install the official screenRIG plugin from https://github.com/screenrig/plugin.

然后给它一个屏幕任务，例如：

使用附加的徽标和营业时间创建欢迎屏幕。发布到大厅屏幕，然后给我截图并检查播放。

仅示例请求。代理必须使用您提供的实际资产、事实和屏幕。

如果命令返回 not_enrolled，则此安装尚无账户。使用 screenrig agent enroll --email ADDRESS --organization NAME 创建账户。已有账户时，改用 screenrig login：它会打印控制台地址和代码，人员批准其项目登录，选择 只读、提议 或 管理 及智能体权限区域：screens、content、playlists、advertising、reports 和 project。只读可列出和读取；提议还可上传媒体和提出变更，需人员 审核 后播放；管理还可变更、发布和消费。超出批准区域的命令返回 403 forbidden，只读会话的变更返回 403 insufficient_access。详见 登录工作原理。其他首次运行错误见 首次运行失败时。

准备任务

保持源资产和事实对智能体可用。识别目标播放器、尺寸、时间和完成标准。发布工作流程在支持的智能体中相同；安装差异见开始。

针对自助服务应用，使用 浏览器 SDK。针对排程和时段，提供屏幕时区和预期的日期时间窗口。

agent 持续做什么？

智能体上传现有媒体，生成完整可展示的设计，为会变化的文本放置内置卡片，或发布直播视频、网页和应用。然后用 playlist init 准备播放列表，并用 screen publish 发布。更改现有播放列表使用 playlist show --output 和 playlist update。详见 CLI 工作流程参考。

对海报和菜单使用整页生成。对会变化的文本、表格和公告板使用内置卡片。动画不改变这一选择。阅读创作决策指南。

针对应用，当智能体应对命名事件时使用 emit，诊断时用 log，跨版本持久状态用 kv。阅读 SDK 参考。

智能体如何管理车队？

按用途标记屏幕，按地点将其归入文件夹，然后定位标签或文件夹。播放器配对后，智能体会命名屏幕并标记：screen pair CODE，然后是 screen tag scr_ID --add Lobby,Floor2。每个屏幕最多携带 16 个标签，且最多位于一个文件夹中（screen move scr_ID --folder sfd_ID）。

1. 01

   发布一次。 playlist create 制作播放列表，screen assign --tag Lobby --playlist-id ID 一次车队操作将所有活动大厅屏幕指向该播放列表。

2. 02

   对设备群执行操作。 screen reload、screen toast 和 screen tag 接受相同的 --tag，或多个屏幕 ID。一次设备群命令计费一次操作，无屏幕数量上限。CLI 自动跟踪分页结果并等待控制预算重置，保持相同操作键。响应列出每个屏幕为 ok 或带有自身问题，智能体准确报告失败屏幕并按 ID 操作。

3. 03

   在屏幕上验证。 screen screenshot --tag Lobby --output lobby-shots 将所有标记屏幕捕获到一个目录。报告设备更新前检查每张图片。

4. 04

   监控掉线。 保持 events follow 打开。screen.offline 在屏幕离线 60 秒后到达，screen.online 返回时到达；两者在监听流中免费。

查看设备群命令。

智能体如何管理时段和接管？

播放列表排程按时间更改屏幕播放内容；活动会在其日期或时段内将整个设备群切换到一个播放列表；接管会中断所有内容进行公告，并自行结束。

1. 01

   为屏幕设置时段。 每个时段创建一个播放列表，使用 playlist create，用 screen assign 保持默认分配，并确保屏幕有时区。将条目写入文件并运行 screen schedule set scr_ID --file dayparts.json，或对每个咖啡馆屏幕运行 --tag Cafe。screen show 报告 effective_playlist 及其 source 和 until，以便智能体确认哪个时段正在播放及其变更时间。

2. 02

   在设备群上运行活动。 对于每家 north 门店的午餐菜单，campaign create --name Lunch --playlist-id pl_LUNCH --tag north --window mon-fri@11:00-14:00 会在每个屏幕各自的本地时间 11:00 切换，并在 14:00 切回，之后标记为 north 的屏幕也会获得它。每个屏幕都需要默认播放列表和时区。campaign screens cmp_ID 列出活动覆盖的每个屏幕及其状态（playing、pending、带 next_start 的 waiting、outranked、blocked），campaign explain scr_ID 说明某个屏幕为何不播放它。用 --from 和 --until 设定促销的日期，用 --monthly、--date 和 --except 设定每月和一次性日期，用 --on-touch 设定在有人使用屏幕时播放的层级，两个活动可能同时生效时用 --priority。更改活动需要管理权限。

3. 03

   紧急或启动时接管。 screen takeover --tag Lobby --playlist-id pl_NOTICE --for 30m --reason "Fire drill" 在所有大厅屏幕上优先播放一个播放列表，覆盖活动、排程和分配。使用 --until 设定固定结束，或 --until none 持续播放直到 screen takeover clear --tag Lobby。

4. 04

   验证并监控。 接管生效后请求 screen screenshot --tag Lobby，并在事件日志中跟踪 screen.takeover_started、screen.takeover_ended 和 screen.playlist_switched。screen.playlist_unavailable 表示无法显示计划播放列表。

阅读排程与接管命令和活动命令。要通过电子表格为多个屏幕排程，请使用排程导入。

草稿、测试和提升、历史

对播放内容的更改可以先作为草稿，先到达少数测试屏幕，在执行前检查，并可从历史中恢复。

1. 01

   创建草稿。campaign create --paused 创建一个不到达任何屏幕的活动，在 screen schedule set 文件的排程条目上加 "paused": true 对该条目也是如此。草稿不在任何屏幕的层级栈中，日历以虚线显示。

2. 02

   在更改前检查。campaign preview 接受 campaign create 或 campaign update 的标志，screen schedule preview scr_ID --file FILE 接受排程文件。两者都不会写入任何内容。各自列出将获得或失去该层级的屏幕，以及一周内（用 --calendar-from 和 --calendar-to 最长 93 天）更改前后的日历。campaign preview cmp_ID --publish 预览草稿的发布。

3. 03

   测试。campaign publish cmp_ID --test-folder sfd_TEST 或 --test-screen scr_A,scr_B 仅对这些屏幕取消草稿的暂停。用 screen screenshot 检查它们。不带测试选项的 campaign publish cmp_ID 会把它发送给自己的受众。

4. 04

   提升。campaign promote cmp_ID --revision N 把草稿修订 N（即 campaign revisions cmp_ID 列出的暂停修订）的受众交给活动，使其到达真正的屏幕。

5. 05

   读取历史并恢复。campaign revisions cmp_ID 和 screen schedule revisions scr_ID 按从新到旧列出每个版本。campaign restore cmp_ID --revision N 和 screen schedule restore scr_ID --revision N 把较早的版本向前复制为新修订，其他修订保持不变。来自 Propose 会话的排程恢复与 screen schedule set 一样，要等有人批准；活动恢复需要 Manage 权限。

控制台有相同的控件：历史视图列出更改，并提供“恢复”和“移回”；发布、推广或恢复前会显示前后对比以供确认。

阅读活动命令和排程命令。

智能体如何报告播放证明？

每个可见的图像或视频开始都是播放记录，因此智能体可以向客户端、广告商或审计员提供某一时期的精确播放数据。

1. 01

   选择范围。 报告涵盖最多 31 天的播放，按 --screen-id、--media-id 或 --tag 过滤。使用 RFC 3339 时间点表示日历周期，或使用诸如 7d 的年龄。

2. 02

   导出。 screenrig playback plays --format csv --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z --tag Lobby --output september-lobby.csv 每次计费请求写入一行播放记录。screenrig playback list --format csv --day-from 2026-09-01 --day-to 2026-09-30 添加每日总计。

3. 03

   检查并交接。 信封报告 rows、bytes 和 sha256；与文件一起引用。若流中途失败，遵循 error.next，将剩余范围导出到第二个文件。

查看播放命令。

智能体如何分类健康状况并设置显示时间？

健康报告和显示控制让智能体在无人值守时保持屏幕运行且保持黑屏。

1. 01

   分诊。 screenrig alerts list 显示当前未解决的内容，每个屏幕和条件一条警报，screenrig screen list --human 在其 HEALTH 列中标记需要关注的屏幕。screenrig screen show scr_ID 提供完整报告：显示器连接、温度、电池、运行时间、崩溃情况以及报告是否过期。当 screenRIG 能够判断时，它还会给出最近一次中断的可能原因：设备重启、Player 重启或崩溃、屏幕的网络，或 screenRIG 的服务中断。screenrig alerts ack ID 会标记有人正在处理的警报，alerts snooze ID --for 4h 会将其搁置 4 小时。为 screen_offline、display_disconnected、running_hot、not_playing 和 crashing 创建通知，以便由提醒启动这项工作。

2. 02

   按干扰最小的顺序修复。 screen reload 刷新内容。如果播放器声明了 restart_app，screen restart-app scr_ID 会重启播放器应用；如果声明了 clear_cache，screen clear-cache scr_ID 会清除其缓存并重新下载内容；如果声明了 reboot，screen reboot scr_ID 会重启设备；整个机群需要 --yes。离线屏幕若在 24 小时内恢复在线，会收到其中任意一种。对于周期性重启，screenrig screen reboot-schedule set --tag Cafe --window "Mon-Sun 04:00-04:30" 让 screenRIG 在窗口开始时按每个屏幕自己的时区重启它；当时离线的屏幕只在窗口结束前保留该重启，而十分钟内完成的重启不会触发离线警报。screen update-software scr_ID 会在播放器声明了 update 时安装最新的播放器版本。断开的显示器通常需要有人到现场处理；请在报告中说明。

3. 03

   设置非工作时间电源。 将营业时间写入文件并运行 screenrig screen display-schedule set --tag Cafe --file hours.json；播放器将在这些时间之外关闭显示器，即使离线。对于一次性操作，screen display scr_ID --power on --for 2h 会覆盖排程，直到下一个边界或指定时间。screen display-idle scr_ID --after 300 --wake touch,presence 会让无人使用的屏幕变暗，并在有人触摸或走近时重新亮起。

4. 04

   确认。 screen show 报告播放器达到的显示器功率，screen.display_changed 和 screen.reboot_requested 出现在事件日志中，commands 中的命令以 done 或 failed 结束并附带其原因。

5. 05

   检查屏幕画面。 screenrig screen show scr_ID 会在屏幕在线且内容为最新、但 screenRIG 已超过其循环允许的时间没有收到任何图片或视频开始报告时显示 Playlist stalled，并会在 screenRIG 对覆盖整个循环的一组截图中，所有截图都是同一种纯色或都是同一幅画面时显示 Blank screen 或 Frozen picture。loop_stalled、glass_blank 或 glass_frozen 的通知会提示这一情况，screen screenshot 会报告单张图片是否为纯色，但这本身并不是判定。对于显示器已关闭、处于接管中、只显示单张静态图片或视频墙、或其播放器不发送播放编号的屏幕，这些检查不作判断，因此安静的屏幕并不能证明它正在播放。

查看设备健康与电源命令。

发生事件时，如何收到警报或唤醒智能体？

当屏幕离线、失去显示、过热、使用电池供电、无法存储内容、卡在内容更新上、显示错误而不播放、不断崩溃、不再推进播放列表、变黑或画面冻结时，通知会向人员发送电子邮件、发布到 Slack、Teams、PagerDuty 或 Telegram，或发送签名的 HTTPS 请求。即使没有人盯着事件流，也会有人得知，或由智能体开始处理。每个项目在屏幕离线 10 分钟时已会向其所有者发送电子邮件，通知邮件和屏幕通知均免费。

在五分钟内进入同一状态、并共用网络、位置、型号、Player 版本或标签的三块或更多屏幕，在电子邮件、聊天或告警工具消息中只算一条通知、一次恢复，通知会说明它们共用什么以及有多少块；已签名的 Webhook 仍按每块屏幕发送一个 POST。只有当 screenRIG 确实看到屏幕恢复时，恢复消息才会说明屏幕已恢复：如果停滞、黑屏或冻结的屏幕只是因为离线或显示器关闭而不再被检查，警报会关闭，且不会发送恢复消息。

1. 01

   向个人发送邮件。 screenrig notifications create --email owner --conditions screen_offline,display_disconnected 向项目所有者发送邮件；在 owner 之后添加项目成员的用户 ID，即可将他们包含在内。--tag Lobby 将其限定为带标签的屏幕，提醒会等待 --hold 分钟（默认 10 分钟），因此短暂的重新连接不会发出提醒。屏幕恢复后，会再发送一封“已解决”邮件。每封邮件都带有仅针对其收件人的取消订阅链接，screenrig notifications resubscribe ID --user USER_ID 可让某人重新收到邮件。如需改为唤醒智能体或其他系统，请使用 webhook。

2. 02

   发布到聊天工具或告警呼叫服务。 screenrig notifications create --slack - --conditions screen_offline 发布到 Slack 频道，--teams、--pagerduty、--telegram 对 Teams、PagerDuty 和 Telegram 做同样的事。Slack 使用传入 Webhook 的 URL，Teams 使用 Workflows Webhook 的 URL，PagerDuty 使用 Events API v2 路由密钥，Telegram 使用机器人令牌并配合 --telegram-chat CHAT_ID。- 会从 stdin 的一行读取凭据，使其不进入 shell 历史；screenRIG 会将其加密封存，只显示已遮蔽的 destination_hint。每次故障、每块屏幕只发布一次，PagerDuty 为此只打开一个事件，该消息发出后会再发一条恢复消息，并解决该事件。screenrig notifications test ID 会发布一条测试消息；对 PagerDuty，它会打开一个信息事件并立即解决。

3. 03

   运行接收器。 任何你控制的 443 或 8443 端口的 HTTPS 端点：小型服务、无服务器函数，或你的智能体或机器人平台的入站触发器。它使用 webhook 密钥验证 ScreenRig-Signature，基于 ScreenRig-Event-Id 去重，并在 10 秒内返回 2xx。

4. 04

   订阅。 screenrig notifications create --webhook https://HOST/PATH --conditions screen_offline,crashing 只返回一次签名密钥；请将其存储在接收方的密钥库中。添加 --events application.event 还可接收原始项目事件。screenrig notifications test ID 发送一次签名测试 POST，以验证路径。

5. 05

   交接。 接收方以该提醒为任务启动智能体运行：触发定时或按需智能体任务，或将该提醒发布到 Grok Bot 或其他带 screenRIG 插件的智能体所在的聊天中。例如：“屏幕 scr_LOBBY 于 14:02 离线。请检查并报告。”智能体随后照常通过插件工作，借助 screen show、screen reload 和截图。

6. 06

   保持健康。 screenrig notifications deliveries ID 列出每次尝试，并说明通知未发送的原因。连续失败 72 小时的通知会被禁用；screenrig notifications update ID --enable 从当前事件恢复。--snooze 2h 在维护期间暂停提醒。

7. 07

   维护期间让屏幕静音。 screenrig alerts mute --tag Lobby --for 2h --note "Rewiring" 会在最长 30 天内，让这些屏幕的警报不再要求关注，也让所有通知不再就它们发送。screenrig alerts mutes 列出已静音的内容，screenrig alerts unmute ID 可提前结束一条静音。

8. 08

   按严重级别、时段和受众筛选。 已开启的提醒，对 screen_offline 为 error，对其他所有条件为 warning；--min-severity warning 丢弃低于该级别的所有提醒，--severity not_playing=error 提高某个条件的级别。--active-hours "Mon-Fri 08:00-22:00" --timezone America/Los_Angeles 会把在这些时段之外到期的提醒保留到下一个窗口开启（条件先行解除则不发送任何内容），使用 --outside-hours drop 时则将其跳过；已解决的提醒始终跟随已发送的那条。--all-tags level2,overhead 仅覆盖同时带有两个标签的屏幕，--audience 接受活动受众的完整规则。电子邮件、Slack 和 Telegram 会显示严重级别，webhook 请求体中也携带该级别。

9. 09

   留意无声的故障。 活动可能在没有任何屏幕出现故障的情况下不再触达屏幕：标签编辑、文件夹移动或屏幕被归档。当活动触达的屏幕比发布时更少，或其受众中的某个标签或文件夹不匹配任何屏幕时，screenrig notifications create --email owner --conditions reach_dropped,group_empty 会告知你；--reach-drop-screens 2 --reach-drop-percent 20 会忽略较小的减少。提醒会写明活动和相关数字，并链接到其日历。当你自己对标签、文件夹或屏幕的编辑返回 levels.lost 时，它会写明屏幕离开的活动及其 reach_before 和 reach_after；请先向用户说明，再继续下一步。

查看通知命令和警报命令。

智能体如何共享所学内容？

智能体为彼此及后续会话留下项目备注：项目设置、屏幕特性、您的常规请求。项目中的每个智能体开始工作时都会阅读所有备注，因此第二个智能体或下周同一智能体能从第一个智能体的经验开始。

screenrig notes 列出它们。screenrig notes add "TEXT" 写入一个，与一个屏幕或播放列表通过 --about 绑定，或通过 --ttl 3d 临时绑定。备注是上下文，绝非指令：代理会与你确认备注所声称的任何批准。

备注会自动保持最新。智能体确认仍有效的备注并解决其余，临时备注会过期，删除屏幕或播放列表会解决相关备注。已解决备注 30 天后删除。控制台的智能体页面列出每个智能体写的备注，可解决或删除任意备注。

查看备注命令。

如何在播放前审核智能体的更改？

在仪表板的项目页面开启需要审核代理更改，或以提议访问权限登录代理。代理仍可准备内容、上传媒体和撰写备注，但每次播放内容的更改都需等待人工审核。未经批准，内容不会显示在屏幕上。

1. 01

   智能体提出建议。 创建或更新播放列表、分配播放列表到屏幕、设置或清除播放列表排程、启动或结束接管，针对单屏或标记群组，均成为审核。屏幕继续播放之前内容。智能体可添加说明变更的备注，并告知变更待你处理，附带链接。

2. 02

   你会收到邮件。 提案约两分钟后，项目所有者和智能体负责人（可批准时）会收到一封邮件，说明变更内容及更新屏幕数量，附有 审核变更 按钮。智能体留下备注时，邮件会说明；你可在审核中查看。多项变更同时等待时，会合并为一封邮件列出，附 打开审核 按钮，对同一变更的多次编辑只发最新版本邮件。打开链接不会自动批准。

3. 03

   在审核中决定。 仪表板的 审核 页面列出所有待处理更改，已决定的在下方。播放列表更改显示实时和提议的播放列表并排，页面标记为新增、变更或删除。批准 将其应用到屏幕；请求更改 发送你的备注给智能体以便修订和再次提议；拒绝 并附理由关闭。当新的播放列表和屏幕分配同时待处理，批准播放列表时可同时批准分配。大规模设备变更后台完成，审核显示每个屏幕的结果。

4. 04

   智能体跟进。 智能体通过 screenrig reviews show ID 或其事件读取决策，变更请求或拒绝后修订，批准后检查屏幕。

项目所有者始终可以审批，除非所有者在人员页面上为某位成员关闭可批准，否则每位成员也都可以。不能审批的成员，其智能体最多以提议权限工作。当实时播放列表在提议之后发生变化时，提议即过时；智能体需在新版本的基础上重新提议。当标签、文件夹或 all 选择器现在会播放提议时未见过的媒体时，批准播放列表更改也会过时。标记为受保护的文件夹会把涉及其屏幕的每项更改都交给第二位审批人；参见按屏幕文件夹设置权限。

媒体变更也需等待。新上传仅在人员批准后在标签、文件夹和所有播放列表中播放，代理重新标记或移动已批准媒体时，屏幕继续播放批准版本，直到变更获批。每个项目有独立审核，显示变更前后标签和文件夹，列出将加入或离开的播放列表及其覆盖屏幕数。批准即应用变更；拒绝或请求更改则恢复为批准状态，拒绝上传保持不播放。已批准媒体的替换文件或恢复的版本同样需要等待，在有人批准之前继续播放旧文件。广告网络在同一审核页面审核买家的创意。访问级别和审核设置 · 审核命令。

什么算完成？

确认预期播放列表已分配给预期屏幕，或分配给整个屏幕群。请求截图，群组中每个标记屏幕一张，检查播放记录，审查相关事件，包括任何screen.offline。报告观察结果及剩余不确定性。等待审核的更改尚未显示：报告其审核链接，人员决定后再次检查。

成功命令是证据的一步。它本身不证明物理屏幕显示了预期结果。

影片 / 你的智能体如何知道它正在播放

1:17