实时预览与手动操控

设备面板右侧提供手机屏幕的实时画面。除了观察 Agent 运行过程，你还能直接在这块画面上点击、滑动、滚动，像操作真机一样手动控制手机。本指南介绍如何切换显示模式、调整画面宽度，以及如何手动操控设备。

查看实时画面

连接设备并进入对话后，画面会自动出现在右侧面板。默认情况下，本地设备会优先尝试低延迟的视频流；如果环境不支持，会自动回退到图像刷新模式（详见下文「视频流的环境限制」）。

把鼠标移到画面区域上，右上角会出现一个圆形按钮。点击它展开控制条，即可切换显示模式和调整宽度。

切换显示模式

控制条提供三种显示模式：

自动：先尝试视频流，失败时自动切换到图像刷新。这是本地设备的默认模式，无需手动干预。

视频（Video）：强制使用基于 scrcpy 的实时视频流。延迟最低，画面最流畅，适合需要连续观察或频繁手动操作的场景。

图像（Image）：以截图轮询方式显示，约每 0.5 秒刷新一次。兼容性最好，在任何浏览器环境下都能工作，但画面不连续、延迟较高。

画面左下角的标签会显示当前实际生效的模式，方便你一眼确认。远程设备只支持图像模式，不会出现「自动」和「视频」选项。

调整画面宽度

展开控制条后，下方的宽度控制条可以调整面板宽度：

提供「紧凑 / 标准 / 宽屏」三档预设（分别约 320 / 400 / 480 像素），以及「自动」让面板自适应可用空间。固定宽度时，还可以用加减按钮以 40 像素为步长微调，或直接拖动面板左侧边缘来缩放，范围在 240 到 640 像素之间。宽度设置会被记住，下次打开沿用。

手动操控手机

在视频流模式下，画面支持直接交互。把鼠标移到画面上即可操作：

点击：在画面上单击，会在手机对应位置触发一次点击。

滑动：按住鼠标拖动再松开，会在手机上执行一次对应方向和距离的滑动。

滚动：用鼠标滚轮在画面上滚动，会以画面中心为基准在手机上触发滚动。

每次操作完成后，画面右下角会弹出一条反馈提示，例如「已点击」「已滑动」，操作失败时会显示对应的错误信息。这样你不必盯着手机也能确认操作是否生效。

你在画面上的位置是按比例自动换算到手机真实分辨率的，无论面板被缩放成多大，点击和滑动都会落在正确的位置，无需手动计算坐标。

视频流的环境限制

实时视频流基于浏览器的 WebCodecs API 与 H.264 解码，这要求页面运行在安全上下文中。

通过 localhost 访问时一切正常。但当你从其他机器用 IP 或域名访问后端时，浏览器会判定为非安全上下文，禁用 WebCodecs，此时视频流无法建立，会自动回退到图像刷新模式。如果你是主动选择了「视频」模式，画面顶部还会弹出一条提示，说明「视频流需要 HTTPS 或 localhost 环境」。

要在非 localhost 环境下使用视频流，有两种办法：

为后端配置 HTTPS。启动时传入 --ssl-keyfile 和 --ssl-certfile 指定证书，或在反向代理层启用 TLS。参数说明见 命令行参考。

或者使用桌面应用。提示横幅上的「下载桌面应用」按钮会跳转到发布页，桌面端不受浏览器安全上下文限制。

此外，若浏览器本身不支持 WebCodecs（请使用较新版本的 Chrome 或 Edge），同样会回退到图像模式。回退不影响手动操控之外的其他功能，你仍然可以正常观察画面。

遇到视频流始终无法连接或操控无响应的情况，可参考常见问题排查。