# 终端说明
基线日期：2026-11-09。当前是 Armbian/Xorg POC，正式目标仍为 Weston/Wayland。
同日已部署 Qt HTTPS 平台适配：现场存在 `~/.config/vdi-terminal/platform.json` 时，设备认证、桌面列表和一次性连接票据由真实平台提供，原 `desktops.json` 不再作为授权来源。启动、现场验收和回退见[真实云管接入](cloud-live-integration.md)。Qt 编译依赖新增 Network 模块，编码/显示配置沿用接入前版本。
## 开机与进出云桌面
产品入口由 LightDM 管理 `vdi-kiosk` 独占会话，再运行 `vdi-kiosk-start → vdi-kiosk-monitor → kiosk-shell`。开机直接进入“选择云桌面”，不再通过普通 MATE 桌面或旧登录页中转。Moonlight 只在选择桌面后启动，不能与 kiosk 分别设置开机自启。
主要配置/实现入口：
- [LightDM 配置](../terminal/kiosk-shell/etc/92-vdi-kiosk.conf)、[会话定义](../terminal/kiosk-shell/vdi-kiosk-session.desktop)、[启动脚本](../terminal/kiosk-shell/scripts/vdi-kiosk-start)。
- `~/.config/vdi-terminal/desktops.json` 保存各桌面地址、应用名、分辨率和 FPS；基础配置在 `client.conf`。`moonlight.conf` 属于旧独立调试入口，不代表产品连接参数。
- 当前常见状态流为 `BOOT → DESKTOP_LIST → CONNECTING → SESSION → DESKTOP_LIST`；首配、认证、重连和错误分支仍保留在状态机中。
11-09 的交接修复包括：
1. 串流期间保持全屏列表窗口映射在 Moonlight 下方，预先完成绘制；Moonlight 自己处理退出快捷键并销毁串流窗口时，下面已经是产品页面。
2. 串流期间释放 kiosk 键盘抓取，几何回调不抢焦点、不抬高列表；页面切换后再显示窗口。
3. 连接遮罩使用不透明 X11 override-redirect 窗口，无合成器时直接隐藏，不依赖透明淡出。
4. [Moonlight 0007](../terminal/moonlight/patches/0007-vdi-kiosk-launch-surface.patch) 由子进程环境 `VDI_KIOSK_STREAM=1` 启用：CLI Qt 启动/错误界面不映射，隐藏根窗口同步加载 QML，SDL 创建时即按输出位置与尺寸无边框全屏；失败通过非零退出码交给 kiosk 提示。独立 Moonlight GUI 不受此环境外的逻辑影响。
5. 部署采用二进制原子替换，由 LightDM 管理会话。停止会话主进程后从 SSH 脱离启动会使 LightDM 回到系统 greeter，不能用作正常恢复方式。
当日回归：进入阶段 Windows/Ubuntu/麒麟分别采样 819/908/968 次，启动 Qt 小窗和非全屏违规均为 0；后续返回采样 525/527/510 次，暴露违规为 0。另有此前两轮返回共 3121 个有效采样。证据见 [entry-surface](evidence/entry-surface-20261109/) 与 [return-surface](evidence/return-surface-20261109/)。这些是 X11 状态与截图验证，未做外置物理逐帧采集。
## 快捷键边界
用户要求从选择页到三种云桌面均不能通过快捷键唤起盒子系统内容。`MoonlightSession` 已使用 `--capture-system-keys always`，将 Win/Super、Alt+Tab 等系统组合键交给客体；无 MATE 会话也减少了宿主桌面快捷键入口。
- `Ctrl+Alt+Shift+Q`：结束当前串流并返回产品桌面列表，属于保留的退出入口。
- `Ctrl+Alt+Shift+M`：kiosk 管理菜单入口，和客户云桌面内的快捷键职责不同。
- `Win+Shift+S`：目标是在 Windows 内截屏；能否弹出还取决于客体截图工具/组件及键盘传递，不能把“没有盒子弹窗”当成“截图已成功”。
- [0004 电源键策略](../terminal/moonlight/patches/0004-vdi-power-key-policy.patch) 属于客户端输入策略；客体菜单关机限制由独立系统策略实施，详见[电源策略](desktop-guide.md#power)。历史现场构建与构建器补丁集合曾不同，核验二进制来源后再判断覆盖范围。
验收应同时覆盖选择页、连接中、串流中、退出后，逐一检查 Windows/Ubuntu/麒麟的系统键和截图快捷键。不能以一个系统通过推断另外两个通过。
## 显示器关开与 2K 恢复
当前盒子使用 `2560x1440_60_fixed297`，已验证时序：
```text
297.00 2560 2608 2640 2720 1440 1443 1448 1820 +HSync -VSync
```
[vdi-display-guard](../terminal/kiosk-shell/scripts/vdi-display-guard) 每 2 秒检查输出，异常持续至少 2 秒后恢复；健康状态只查询，断开时等待，失败按 2～60 秒退避。该盒子 vendor PHY 与显示器原厂 241.70MHz 时序存在兼容问题，不能直接换回原厂时序。
11-03 模拟两次 1920×1440 回退均自动恢复，用户实际关开显示器也确认恢复全屏；会话 PID 保持不变。当前验证局限于这台盒子、单 HDMI 显示器与 Xorg，不覆盖任意显示器或 Wayland。模式确实回退时驱动与守护切换可能需要约 15 秒。
仅部署显示守护入口为 [tools/deploy_display_guard.sh](../tools/deploy_display_guard.sh)，状态查询见[运维说明](operations.md#diagnosis)，证据见 [display-resume](evidence/display-resume-20261103/)。
## 构建与版本回退
在具备 Qt5 开发依赖的 ARM64 环境编译 kiosk：
```bash
cd terminal/kiosk-shell
cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
cmake --build build
QT_QPA_PLATFORM=offscreen ctest --test-dir build --output-on-failure
```
完整终端部署入口是 [tools/deploy_kiosk.sh](../tools/deploy_kiosk.sh)（开发机 Git Bash）；它会重启 LightDM、打断盒子当前串流。私有硬解客户端由 [tools/build-rkmpp-client.sh](../tools/build-rkmpp-client.sh) 在盒子构建。补丁范围、未采用实验和版本来源见 [Moonlight 模块说明](../terminal/moonlight/README.md)。以上命令是维护入口，本次文档整理未执行部署。
11-09 已验证 Moonlight SHA256：
```text
2e7441df1f6af5c4ddc79b89af15eed3b6b63cf265bea294ffc090483d8c6c51
```
旧二进制和 Linux 光标配置备份在盒子 `~/vdi-terminal/backups/return-surface-20261109/`。回退必须同时匹配 Moonlight 二进制与两台 Linux 原生光标 profile 中的客户端 SHA，不能只换二进制。显示守护旧文件备份为 `~/vdi-terminal/backups/display-guard-20261103-095920/`，恢复旧布局也会恢复原先的显示回退风险。
当日 CTest 3/3、原生光标边界测试 4/4 通过；完整实验过程及较早版本校验值见[归档](archive/README.md)。