# 播控软件与中控Pad接入文档

<!-- 源文件：docs/api/播控与中控Pad接入模板.md，修改后运行 node docs/deploy/build-api-docs.mjs 生成；“中控Pad指令协议”一章直接取自《互动应用开发接入文档》的“中控Pad TCP 协议”小节，两处始终一致。 -->

## 文档说明

2026-10-14 扫码器兼容参数由AgentOS“用户与来宾卡 → 身份服务设置 → 扫码器设置”统一保存。互动网页经现有身份桥接读取`GET /api/identity/scan-settings`；该地址随后台点位接口清单下发，部署后重新打开播控读取最新配置，无需因本项更换EXE。此设置不修改Windows键盘、屏幕或音频设备。

本文档面向门店现场部署、播控电脑运维和中控对接方，说明 AIVA 点位播控软件如何接入 AgentOS、中控（Pad 经中控网关）如何在局域网控制播控。播控用到的 HTTP 接口（配对、配置下发、运行回报等）见《互动应用开发接入文档》的[播控配对与配置下发](index.html#player)。

| 角色 | 职责 |
| --- | --- |
| AgentOS 后台 | 登记点位、点位的屏幕（几块屏、各放什么素材）、播放设置、播控运行参数、各屏互动网页地址、中控监听端口；生成点位码；接收运行回报；也可直接下发播放控制指令；提供“中控指令对照表” |
| 播控软件（Windows 电脑） | 用点位码绑定一个点位（互动点位或展示点位），按后台定义的屏幕输出到本机一块或多块屏幕；从 AgentOS 读取全部配置、下载并校验素材；接收中控指令并切换画面 |
| 中控（Pad + 中控网关） | Pad 按钮经中控网关（如哈曼视听逻辑编程软件）在门店专用局域网内通过 TCP 向各台播控发送固定的文本指令（如 `PLAY`），决定什么时候播放展览内容、什么时候切到互动应用等；声音由中控控制 |
| 互动网页 | 在播控的“互动应用”窗口中运行，通过播控提供的桥接调用 AgentOS 互动接口 |

**网络前提（2026-10-07 中控通信简化确认）**：中控与所有播控电脑处于门店专用局域网。播控不校验来源 IP、指令不签名，**这个局域网里任何设备都能向播控发送指令**，因此必须与访客 Wi-Fi、办公网和公网隔离。

**当前状态**：播控软件 0.3.0（2026-10-10）已完成构建、单元测试、本机模拟联调（含本机两块真实屏幕的多屏测试）。0.3.0 起：中控文本指令、一个点位多块屏各放各的素材、界面简化（取消运维口令、配置核对、本地接管、停止/启用播控、TLS）、托盘常驻、开机自动启动默认开。真实 Pad/中控网关、防火墙、视频与声音设备尚未现场验收。

**近期版本**（覆盖安装即可，配对保留）：0.3.7（2026-10-13）屏幕对应改为按屏幕在 Windows 桌面上的位置记忆，重启后 Windows 屏幕编号变化也不用重新对应；0.3.8（2026-10-14）开机自启动时运维窗口只在托盘，播放/互动画面在最前；0.3.9（2026-10-14）播控画面上不出现任何弹窗（见“互动网页接入”）；0.3.10（2026-10-14）合并扫码枪焦点修正（切到互动应用时输入焦点给可触摸屏上的互动网页）。当前最新 0.3.10。

## 后台准备

在 AgentOS 后台按以下顺序完成（点位详情页顶部的页签分别为“展示与现场模式”“播控”“设备接入”“Agent 配置”）：

1. **点位**：互动点位随门店创建；纯展示点位在“点位总览 → 新建展示点位”创建。
2. **展示与现场模式**：
   - **屏幕**：每个点位默认 1 块“主屏”。一个点位有多块屏（如 AI音乐台上方 16:9 屏、下方触摸长条屏）时点“＋ 添加屏幕”，为每块屏填名称、建议分辨率（播控据此自动对应本机屏幕）、是否触摸。声音由中控控制，这里不设置。
   - **素材**：点哪块屏就编辑哪块屏的素材与播放方式（可“复制主屏素材”）；添加已审核的素材并选择显示尺寸；播放方式默认“按清单顺序轮播”、整单结束默认“重新循环整单”，图片/图文默认展示10秒。保存一次，所有屏一起生成一个新版本。
3. **播控**：登记网络超时、切换超时、同步间隔、心跳间隔（未登记时按默认 3000 / 10000 / 30000 / 5000 毫秒生效）。网络超时对接口请求是单次请求的最长等待；对素材下载是“连续这么久没收到任何数据”才中断，一直在收数据就不限总时长（播控 0.3.0 起，2026-10-11），大视频不必为此调大；互动点位登记互动网页正式地址，多屏时“其他屏幕的互动网页”可为每块屏单独登记（不登记的屏在互动时继续播自己的展览素材）；选择**播控打开后显示**：等待中控指令（默认）、自动播放展览内容、自动打开互动应用。
4. **门店中控Pad**：在“点位总览”页的“门店中控Pad”卡片登记监听端口，全店统一，默认 9850。点“指令对照表”可查看并导出各台播控的局域网地址与可用指令，交给中控集成商。
5. **点位码**：在点位“播控”页签生成点位码，交给现场安装人员。点位码永久有效；同一点位已绑定其他播控电脑时拒绝新电脑，须先在后台“解绑”；重置点位码后旧码作废，该点位已连接的播控全部失效。

## 播控软件安装与连接

安装版需在现场 Windows 用户会话中运行。安装后打开程序：

| 步骤 | 操作 | 说明 |
| --- | --- | --- |
| 连接 | 输入服务器地址（预填测试环境 `https://aiva.dev.vavedigital.com`，可改）和点位码，点“连接” | 本机计算机名作为设备名上报。点位码无效、已被其他电脑绑定、设备停用时分别提示，不自动重试。连接成功后自动读取点位配置（不再需要核对勾选、不再设置运维口令） |
| 屏幕对应 | 一般自动完成 | 只有一块后台屏幕且本机只有一块屏：直接对应；多块屏：按后台填的建议分辨率找本机分辨率相同的屏，**只有唯一对得上才自动**。对不上（或两块屏分辨率一样）时出现“屏幕对应”页面：点“在屏幕上显示编号”辨认后为每块后台屏幕选择本机屏幕，没选中的屏（如运维显示器）不播放。对应关系保存在本机（记住每块屏在 Windows 桌面上的位置与分辨率，0.3.7 起），下次打开不再问；只有在 Windows 显示设置里调换过屏幕排列或少接了屏时才会再次出现 |
| 开始工作 | 自动 | 监听 `0.0.0.0:后台登记的端口`，再按后台“播控打开后显示”显示画面（默认等待中控指令） |

之后每次打开程序都会自动开始工作。启动时先读取后台最新配置；后台配置不一致（如互动点位没登记网页地址）时明确报错、不启动。

**打开后画面**（2026-10-10）：播控每次开始工作后（打开程序，或“重新启动播控”）按后台“播控打开后显示”执行一次：

| 后台选择 | 打开后 | 断网打开时 |
| --- | --- | --- |
| 等待中控指令 | 不显示画面，等中控或后台指令 | 同左 |
| 自动播放展览内容 | 每块屏播放后台最新保存版本中自己的素材 | 播放最后同步的版本（与断网规则一致） |
| 自动打开互动应用 | 每块屏打开自己登记的网页并开放互动 | 互动网页离不开 AgentOS，打不开，报错 |

之后中控与后台随时可以切换画面。自动显示失败时照常报错（主界面显示，写本机日志），不改播其他内容、不自动重试。

**升级**：覆盖安装新版本即可，配对会保留，不需要重新输入点位码；旧版本只登记了一块输出屏的自动对应为主屏，多块的按分辨率重新对应。旧版的运维口令与 TLS 设置不再使用。后台“展示与现场模式 → 播控实际状态”的“播控版本”一列可核对每台电脑装的版本（显示“0.1.0 或更早”即尚未升级）。

**防火墙**：程序不会修改 Windows 防火墙。开启防火墙时，须放行后台登记的中控端口（默认 9850 的 TCP 入站）。

**无人值守**：开机自动启动默认打开（Windows 当前用户登录后启动，仅安装版生效），可在“设置”关闭。开机自启动时运维窗口不弹出、只在托盘，播放或互动画面在最前；只有需要运维处理时（尚未连接、需要对应屏幕、启动失败、打开后画面未能显示）才弹出运维窗口（0.3.8 起）。从旧版本升级后须手动打开一次程序，开机启动项才会改为新方式。Windows 自动登录、安全策略由部署人员配置。关闭窗口只是缩到右下角托盘，程序继续工作；退出须在托盘菜单或“设置 → 退出程序”。

## 播控软件界面

| 位置 | 内容 |
| --- | --- |
| 主界面 · 正在播放 | 当前实际显示（展览内容及版本 / 互动应用 / 画面已关闭）、AgentOS 连接、中控连接（最近一条中控指令及来源IP）、播控版本 |
| 主界面 · 本机操作 | 播放展览、打开互动应用、上一个、下一个、暂停/继续、关闭画面、回到首页、刷新网页，与中控按钮效果相同（本机、后台、中控谁最后发谁生效） |
| 主界面 · 中控接入 | 本机局域网地址与端口（一键复制）、中控Pad按钮与发送文本对照表、网关 tcp out 节点填写说明 |
| 主界面 · 最近指令 | 最近收到的指令（中控/后台/本机/打开后画面）、来源与结果 |
| 设置 | 屏幕对应（重新对应）、开机自动启动、中控端口、连接的点位（换点位）、重新启动播控、诊断信息（后台配置全文、内容同步、完整日志）、退出程序 |

0.3.0 起取消：运维口令、连接时的配置核对勾选、本地接管/交还中控、停止/启用播控、TLS 设置（2026-10-10 用户确认，不考虑安全只求简单）。能接触这台电脑的人都能操作播控，现场须靠机柜、锁屏等物理措施管控。

## 中控接入步骤

1. 确认中控与播控电脑在同一个门店专用局域网，并与访客 Wi-Fi、办公网、公网隔离。
2. 在 AgentOS 后台“门店中控Pad”登记端口（默认 9850，全店统一），播控会自动读取，端口改动后播控自动切换到新端口监听并断开旧连接。
3. 在后台“门店中控Pad → 指令对照表”导出 CSV 交给中控集成商：每台播控电脑的局域网 IP、端口与可用指令（播控 0.3.0 起自动回报 IP；也可在播控主界面“中控接入”查看）。
4. 中控网关为每台播控配一个 tcp out 节点：类型“连接”、主机地址填播控 IP、端口填上面的端口、不勾选“是否在成功发送每条信息后断开连接”。
5. “通用控制”节点第一列填 Pad 按钮编号，第二列填发送文本（`PLAY`、`APP`、`PREV`、`NEXT`、`HOME`、`RELOAD`、`PAUSE`、`RESUME`、`EXIT`），第三列不填。原来填的 `SET_MODE` 等字符串须改掉（播控回复“未知指令”）。
6. 声音加/减由中控控制，不发给播控。

## 中控Pad指令协议

本节不是 HTTP 接口：中控（Pad 经中控网关，如哈曼视听逻辑编程软件）在门店专用局域网内直接连接播控。播控监听本机所有网卡 `0.0.0.0`，端口由设备配置 `control.listenPort` 下发（后台“门店中控Pad”登记，全店统一，默认9850）。不校验来源IP、指令不签名，因此**专用局域网内任何设备都能向播控发送指令**，该局域网须与访客Wi-Fi、办公网和公网隔离。同一端口同时接收两种格式：以 `{` 开头的按 JSON 指令处理，其他按文本指令处理。

#### 文本指令（推荐，2026-10-10 用户确认）

中控网关每个按钮只能发一个**固定字符串**，因此播控提供文本指令：发一个英文单词就执行对应动作，全部点位用同一套单词。

| 中控Pad 按钮 | 网关发送文本 | 播控执行 | 可用于 |
| --- | --- | --- | --- |
| 品牌内容播放 | `PLAY` | 播放展览内容：后台最新保存的版本（未缓存先下载校验）；断网时只播最后同步的版本 | 所有点位 |
| 互动程序 | `APP` | 打开互动应用：每块屏打开自己登记的网页，未登记网页的屏继续播自己的展览素材；断网时打不开，报错 | 登记了网页的互动点位 |
| 上一个素材 / 下一个素材 | `PREV` / `NEXT` | 所有屏各自切到自己的上一个/下一个素材，到头循环；暂停中切换后接着播 | 正在播放展览时 |
| 回到首页 / 刷新网页 | `HOME` / `RELOAD` | 重新打开登记的网页地址 / 重新加载当前页，网页重新握手后再开放互动 | 正在显示互动应用时 |
| 暂停 / 继续 | `PAUSE` / `RESUME` | 定格当前画面 / 从暂停位置继续（多屏一起） | 正在播放展览时 |
| 关闭画面（闭馆） | `EXIT` | 关闭全部播放窗口，程序与监听继续运行 | 所有点位 |
| （查询） | `STATUS` / `PING` | 回复当前模式、版本、阶段 / 回复 `OK PING` | 所有点位 |

| 项目 | 规则 |
| --- | --- |
| 格式 | UTF-8 英文单词，不区分大小写；**不需要换行**：遇到换行/回车，或一包数据发完约0.1秒内没有新数据，即为一条指令结束；一条最长64字节 |
| 执行 | 按一次执行一次（不去重）；不核对点位编号——网关发到哪台播控（哪个IP）就是哪个点位 |
| 回复 | 每条回一行：成功 `OK 单词 说明`（如 `OK PLAY 已播放展览内容 r12`），失败 `ERR 单词 原因`（如 `ERR HOME 当前没有在显示互动应用，不能回到首页`）；网关不读回复也不影响执行 |
| 当前模式不支持 | 如播放展览时发 `HOME`、互动时发 `NEXT`/`PAUSE`：回 `ERR`，不执行、不自动切换模式 |
| 未知单词 | 回 `ERR 单词 未知指令`，**不断开连接**（如旧配置里的 `SET_MODE`、音量类按钮） |
| 声音 | 音量由中控控制，播控不提供音量指令 |
| 连接 | 长连接，不因空闲断开；播控开启TCP保活（15秒起探测），掉线由系统释放连接，网关可随时重连；后台改端口时播控主动断开已有连接 |

**网关配置（以哈曼视听逻辑编程软件为例）**：每台播控电脑一个 tcp out 节点——类型“连接”、主机地址填播控电脑的局域网IP、端口填后台“门店中控Pad”的端口（默认9850）、**不勾选**“是否在成功发送每条信息后断开连接”；“通用控制”节点第一列填 Pad 发来的按钮编号（如 `custom37_1`），第二列填上表的发送文本（如 `PLAY`），第三列不填。“开馆模式”按钮可同时向多台播控发送 `PLAY` 或 `APP`。各播控的IP与可用指令见后台“点位总览 → 门店中控Pad → 指令对照表”（可导出CSV）。

#### JSON 指令（ndjson_v1，兼容保留）

| 项目 | 规则 |
| --- | --- |
| 格式 | UTF-8 JSON，一行一条指令，以LF（`\n`）结尾，每帧最多16KiB；无效UTF-8/JSON帧回复 `INVALID_FRAME` 并断开 |
| 重发 | 同一个请求号 `requestId` 原样重发不会重复执行，返回第一次的结果（带 `idempotentHit:true`）；同一请求号内容不同则拒绝（`ID_CONFLICT`）。播控进程重启时未完成的指令记为 `interrupted`，不自动重放 |
| 旧字段 | 旧版签名协议字段 `controllerId`、`keyId`、`seq`、`issuedAt`、`signature` 收到时忽略；其他未知字段拒绝（`BAD_COMMAND`） |

指令字段（2026-10-10 补充每个字段由谁提供）：

| 字段 | 必填 | 含义 | 由谁提供 / 从哪里取 |
| --- | --- | --- | --- |
| `v` | 必填 | 协议版本，固定为 `1` | 固定值，中控Pad程序写死 |
| `requestId` | 必填 | 指令流水号：这条指令的唯一编号，1—64位字母、数字、下划线、短横线。网络不好时 Pad 用**同一个编号**重发同一条指令，播控不会重复执行，只返回第一次的结果；同一编号内容不同则拒绝（`ID_CONFLICT`）；换新编号即视为一条新指令 | **中控Pad程序自己生成**，每发一条新指令生成一个新编号（如按顺序 `pad-0001`、`pad-0002`，或“时间+序号”）；后台没有、也不需要查看。重发同一条指令时沿用原编号。只能发固定字符串的网关无法生成，请改用文本指令 |
| `pointId` | 必填 | 点位编号：这条指令发给哪个点位，如 `P02`、`D01`。须与这台播控电脑绑定的点位一致，否则拒绝（`POINT_MISMATCH`），防止发错电脑 | **AgentOS 后台分配**，即后台显示的“PID”：“点位总览”每张点位卡片左上角、点位详情标题旁“PID P02 · 门店名称” |
| `command` | 必填 | 要执行的指令：`SET_MODE`、`PAUSE`、`RESUME`、`EXIT`、`GET_STATUS`、`PING`（见下表） | 中控Pad按现场操作选择 |
| `mode` | 仅 `SET_MODE` | 切换到哪种画面：`app` 互动应用 / `cms` 展览内容 | 中控Pad按现场操作选择；`app` 只对登记了互动网页地址的点位有效 |
| `contentRevision` | 仅 `SET_MODE` + `cms` | 要播放的展览内容版本号，整数≥1，须是这台播控已下载并校验过的版本；`app` 及其他指令不得携带 | **AgentOS 后台生成**：点位详情“展示与现场模式”每保存一次素材与播放设置，版本号加1，显示在点位素材下方“配置 vN”。Pad 也可先发 `GET_STATUS`，从回执的可用版本（`availableRevisions`）中选择 |

| command | 作用 | 最终回执 |
| --- | --- | --- |
| `SET_MODE` | 切换整个输出组到互动应用或指定版本的展览内容 | `applied`（带 `actualMode`、`contentRevision`）或 `failed` |
| `PAUSE` / `RESUME` | 暂停（定格当前画面）/ 从暂停位置继续；仅展览稳定显示时可用 | `applied`（带 `paused`）或 `failed` |
| `EXIT` | 退出播放，关闭全部播放窗口，程序与监听继续运行 | `applied`（带 `closed:true`）或 `failed` |
| `GET_STATUS` / `PING` | 查询实际模式、阶段、平台连接、可用版本等（不能代替观察物理屏幕） | `ok` |

示例（实际发送为单行并以LF结尾；点位与版本不能照抄到现场）：

```json
{"v":1,"requestId":"pad-0001","pointId":"实际点位ID","command":"SET_MODE","mode":"cms","contentRevision":12}
```

回执：每条有效指令先回复 `accepted`（已写入本机账本），再回复最终结果；格式或点位错误直接回复 `rejected` 与 `errorCode`。常见 `errorCode`（文本指令的 `ERR` 原因与之对应）：

| errorCode | 含义 |
| --- | --- |
| `BAD_COMMAND` / `POINT_MISMATCH` / `ID_CONFLICT` / `INVALID_FRAME` | 指令格式错误 / 点位不符 / 同一请求号内容不同 / 帧无效（回执 `rejected`） |
| `BUSY` | 输出组正在切换或校验素材 |
| `PROFILE_HOLD` | 后台新配置未能应用（不一致、需重新启动播控或凭据失效），拒绝一切切换 |
| `PAUSE_APP_DENIED` / `NOT_PLAYING_CMS` / `NOT_IN_APP` | 应用模式不能暂停 / 当前没有在播放展览内容 / 当前没有在显示互动应用 |
| `APP_DENIED` / `APP_NOT_READY` / `ADMISSION_DENIED` | 后台为普通展示应用或没有登记网页 / 互动网页未完成握手 / AgentOS未确认互动准入 |
| `PLATFORM_OFFLINE_APP` | AgentOS离线时拒绝切到互动应用（当前没有离线互动方案，待确认） |
| `OFFLINE_NO_CACHE` / `OFFLINE_REVISION_DENIED` / `MEDIA_NOT_READY` | 断网且本机从未同步 / 断网时只能播放最后同步的版本 / 指定版本文件缺失或校验不通过 |
| `PERSISTENCE_ERROR` | 本机账本写入失败，结果需运维核对，不自动重放 |
| `INTERNAL_ERROR` | 播控内部错误，查看本机日志 |

后台指令与中控指令同等对待，同一点位以最后一条为准（播控 0.3.0 起已取消“本机接管”）。联调没有真实Pad时，可在播控目录用 `node tools/pad-sim.cjs <播控IP> PLAY`（文本指令，与网关一样不带换行）或 `node tools/pad-sim.cjs <播控IP> <点位ID> cms <内容版本号>`（JSON 指令）模拟发送，仅限联调。

## 后台播放控制

除中控外，运维也可在 AgentOS 后台对点位直接下发指令：在点位详情“展示与现场模式”的“播放控制”中点“立即播放”“暂停”“继续”“上一个素材”“下一个素材”“切换应用模式”“互动回到首页”“刷新互动网页”或“退出播放”。

- 后台“立即播放”与中控 PLAY 播放的是后台最新保存的版本。新版本还在下载时（2026-10-11 确认），PLAY 及其他指令都作用于上一个已完整下载的版本，回复里注明“新版本 rX 还没下载完（已下载 n%），已播放上一版本 rY”；新版本下完不自动切换，下一次 PLAY 才播。播控从没下载过任何版本时，等下载完成再播放，失败直接报错。下载期间中控指令照常执行，播控主界面“内容同步”显示下载进度。播控不校验素材内容（不计算 SHA-256），只按文件在不在、大小是否与清单一致判断是否下载完成，云端同步什么就播放什么。
- 播控每次心跳成功后领取后台指令并执行，结果回报后台；指令写入后 30 秒内没被领取即作废，后台显示“未送达”，恢复联网后不补执行。
- 后台指令与中控指令同等对待，同一点位以最后一条为准。
- 保存配置本身不会切换画面，只有明确的播放控制指令才会。
- “播控实际状态”显示每台播控的版本、局域网地址和最近一条指令（来源、结果），可用来判断中控到底有没有发到。

## 断网播放与配置更新

**断网播放（2026-10-07 确认）**：启动或运行中 AgentOS 连不上时，播控使用本地加密保存的最后一次同步的配置、中控端口与素材继续监听和播放，主界面标明“AgentOS 暂时连不上”。

- `PLAY` / `SET_MODE cms` 只能播放最后一次同步成功、素材已全部下载到本机的版本；指定其他版本返回 `OFFLINE_REVISION_DENIED`，文件缺失或被改返回 `MEDIA_NOT_READY`，本机从未同步过返回 `OFFLINE_NO_CACHE`。
- `APP` / `SET_MODE app` 返回 `PLATFORM_OFFLINE_APP`：互动网页依赖 AgentOS，目前没有离线互动方案（待确认）。
- 断网期间的运行回报按发生顺序排队，恢复连接后按顺序补报。

**配置自动更新**：播控每个同步间隔读取一次后台配置，有变化就自动应用。中控端口、运行参数、接口清单、素材域名、应用类型、打开后画面即时生效；互动网页地址或屏幕变化需点主界面提示里的“重新启动播控”才生效，期间拒绝一切切换。新配置不完整或不一致时阻止切换并报错，不沿用旧配置静默运行。

## 素材显示尺寸

素材规格由后台上传决定，播控不修改素材文件。每个素材的显示方式在后台“展示与现场模式”的素材编排里选择（多屏时按所在屏幕的尺寸计算）：

| 显示方式 | 效果 |
| --- | --- |
| 等比完整显示（contain，默认） | 按屏幕宽高等比完整显示，比例不一致时留边 |
| 裁切铺满（cover） | 按屏幕宽高裁切铺满 |
| 自定义（custom） | 按屏幕宽、高百分比（1—100）居中显示，区域内等比完整显示 |

清单里缺少或填错显示方式时整份清单校验失败（`MANIFEST_INVALID`），播控不会替换成其他显示方式。

## 互动网页接入

互动网页在播控的隔离窗口中运行，没有本机文件和系统权限，只能通过 `window.aivaPlayer` 桥接与播控通信（参考播控目录 `examples/app-bridge.js`）：

- 网页加载完成后调用 `ready(版本号)`；“回到首页”“刷新网页”后网页会重新加载，须再次调用。
- 监听 `onPresentation`：画面被隐藏或关闭输入时，网页须停止摄像头、麦克风和语音识别，暂停或静音媒体，关闭新的用户输入；处理完后调用 `presentationApplied` 如实回报（不能用固定值假装已停止）。只有后台标为“触摸”的屏会被开放输入与摄像头/麦克风。
- 调用 AgentOS 互动接口时使用 `request({path,method,body,userSession})`：设备凭证由播控主进程自动加上，网页拿不到；`userSession` 为扫码登录得到的用户会话。只允许 `/api/interactions`、`/api/identity`、`/api/p03`、`/api/users` 下、且在后台下发接口清单中的路径。
- 多屏点位每块屏打开自己登记的网页（如 AI音乐主屏、副屏页面），各自握手；声音由中控控制，播控只在网页被隐藏时静音。
- 切换显示不会结束互动、不会撤回或重试模型任务、不会改动 Token；已经提交的任务继续执行。
- **不弹任何对话框**（2026-10-14，播控 0.3.9 起）：网页里的 `alert` 不显示，`confirm` 一律返回 `false`（视为取消），`prompt` 一律返回 `null`，“离开此页”确认框直接放行；这些调用只记入播控“诊断信息 → 互动网页诊断”。网页需要提示或确认时，请在页面内自行绘制。

## 联调与验收

**没有真实中控时**：在同一局域网任意电脑上，于播控程序目录执行模拟脚本（仅联调用，端口省略时为 9850）：

```bash
node tools/pad-sim.cjs 192.168.1.20 PLAY
```

把 `PLAY` 换成 `APP`、`PREV`、`NEXT`、`HOME`、`RELOAD`、`PAUSE`、`RESUME`、`EXIT`、`STATUS` 即为其他指令（与网关一样只发单词、不带换行）；IP 按现场实际填写。

**现场验收清单**：

| 检查项 | 预期 |
| --- | --- |
| 连接 | 填服务器地址与点位码后连接成功，主界面显示的门店、点位、端口与后台一致 |
| 屏幕对应 | 多屏点位每块后台屏幕对上正确的物理屏；运维显示器不播放；再次打开不再询问 |
| 中控连接 | 网关 tcp out 节点显示“已连接”；按 Pad 按钮后播控主界面“最近指令”出现该指令和网关 IP |
| 展览播放 | `PLAY` 后每块屏显示自己的素材；`NEXT`/`PREV` 两块屏一起切换，到头循环 |
| 互动应用 | `APP` 后每块屏打开自己登记的网页；`HOME`/`RELOAD` 回到首页/刷新后可继续互动 |
| 打开后画面 | 后台选“自动播放展览内容”或“自动打开互动应用”后，关闭并重新打开播控程序，无需任何指令即显示对应画面 |
| 播控版本 | 后台“播控实际状态”显示播控版本 0.3.10、播控地址与最近指令 |
| 开机自启 | 重启电脑后无需操作即按“播控打开后显示”出画面，画面在最前，任务栏没有运维窗口，屏幕上没有任何弹窗 |
| 暂停/继续/关闭画面 | 展览画面定格与继续；关闭画面后窗口关闭、程序与监听仍在 |
| 后台指令 | 后台“立即播放”“下一个素材”等指令在下一次心跳后执行，后台显示结果 |
| 断网 | 断开 AgentOS 后仍能播放最后同步的版本；切互动应用被拒绝 |
| 网络隔离 | 访客 Wi-Fi、办公网连不上播控端口 |

**相关资料**：播控程序说明 `project/player-control/README.md`；调整方案与界面确认稿 `docs/ux/播控客户端与中控对接-调整方案与UI-V1.1.html`；早期方案 `docs/ux/CMS点位播控-UI与开发方案-V1.0.html`；实施与验证记录 `docs/develops/21-CMS播控实施与验证-20261005.md`。
