URL Scheme Automation

URL Scheme 自动化

English

Screen Remote 通过可浏览的 screen-remote:// URL Scheme 接收外部应用、AI 或 MCP 工具发起的导航、会话、设备管理和设置操作。入口由 app/MainActivity.kt 与 app/deeplink/ 拥有；MainActivity 使用 singleTask，冷启动和已运行实例都会解析新 Intent。

选择目标与持久化边界

• 会话 selector 按大小写敏感的 session id、第一条同名 session、合法的 host:port 临时目标依次解析。IPv6 endpoint 必须包含方括号并进行 URL 编码。
• scrcpy URL 会复制已保存会话的有效 profile 配置，只覆盖 URL 明确给出的字段，然后创建内存运行会话；不会修改已保存会话或 profile。
• 直接使用 endpoint 时创建临时 TCP 会话。管理 URL 同样可使用已保存会话或临时 endpoint。
• 新建会话 URL 只预填编辑器，仍由用户确认保存。命令管理 URL 只预填命令，不自动执行。

支持的路由

目的	URL 形式
会话 / 操作页	screen-remote://open/sessions、screen-remote://open/actions
设置页	`screen-remote://open/settings[/about
新建 / 编辑会话	screen-remote://session/new?...、screen-remote://session/edit/{selector}
启动远控	screen-remote://session/{selector}/scrcpy?...
打开设备管理	`screen-remote://session/{selector}/manage/{device
文件路径 / 命令预填	在 file 路由后追加编码路径，或给 command 路由传 command=
修改全局设置	screen-remote://setting/{setting}/{value}
ADB / 诊断 / 断开	screen-remote://adb/keys/generate、screen-remote://diagnostics/logs、screen-remote://remote/disconnect

新建会话参数包括 name、address、color、profileId、useProfileDefaults、逗号分隔的 backupAddresses 与 groupIds，也可同时携带远控参数。

远控与设置参数

远控 URL 支持：

maxSize、videoBitRate、maxFps、videoEncoder、videoDecoder、audio、audioBitRate、audioEncoder、audioDecoder、gameMode、compatibilityMode、fullScreen、floatingBall、hardwareDecoding、followOrientation、clipboard、turnScreenOff、powerOffOnClose、cleanupOnDisconnect、stayAwake、keepDeviceAwake、showTouches、ignoreVideoEncoderConstraints、displayId、newDisplayEnabled、newDisplay、virtualDisplaySystemDecorations、preserveVirtualDisplayContent、startApp、codecOptions 与 tunnelMode。

兼容别名为 enableAudio、useFullScreen、showFloatingBall、enableHardwareDecoding、followRemoteOrientation、clipboardSync。参数名忽略大小写并归一到权威名称；路由、selector 和枚举值保持大小写敏感。布尔值接受 on/true/1/yes 与 off/false/0/no。开启 compatibilityMode 后，音频与自动剪贴板同步始终关闭。

可修改的全局设置为 debugmode、activitylog、audiolog、videolog、controllog、eventlog、shelllog、managementlog、haptic、performancestats、autoupdate、updatechannel、theme 与 language。枚举值分别为 stable|prerelease、system|light|dark、auto|chinese|english。

校验与诊断

• Scheme、host、路径和未知参数使用白名单；URL authority 不接受 credentials、port 或 fragment。
• 外部调用者必须对路径段、endpoint、文件路径、命令和查询值做 UTF-8 URL 编码。
• 不支持或不合法的 URL 只记录英文警告，不执行部分操作。
• Debug 构建额外暴露受系统 android.permission.DUMP 保护的只读 diagnostics provider，可读取设备、会话、socket、codec、日志、指标和动态 URL catalog；release 构建不包含该 provider。

代码与回归锚点

• app/deeplink/ScreenRemoteDeepLink.kt、ScrcpyUrlParameters.kt、UrlRuntimeSession.kt
• feature/session/ui/MainScreen.kt、feature/session/viewmodel/MainViewModel.kt
• ScreenRemoteDeepLinkTest、ScrcpyUrlParametersTest、UrlRuntimeSessionTest