Feature: Add window/region capture targets to remote_open

Pass the target HWND through the COMMAND_SCREEN_SPY token and send
COMMAND_SCREEN_ROI after session start, so MCP remote control can stream
just the target window or region instead of the scaled virtual desktop.
The session records the target kind, remote_mouse refuses a redundant
window_hwnd basis, and the cached resolution is refreshed per action so
resized windows keep mapping correctly. Cold starts now clear the stale
resolution cache used by the region handshake.
This commit is contained in:
yuanyuanxiang committed 2026-11-10 19:13:45 +01:00
1 parent 5501889d33
commit cdd9c56b3d
7 files changed
+445 -39

No files matched your search

+74
View File
@@ -1208,3 +1208,77 @@ frame_x = (physical_x - desktop.left) / desktop.width
字节流完全不变。
- 窗口在前台且未被缩放时,比例点与窗口截图 1:1 对应;窗口被其他窗口部分遮挡时,
截图本身也是遮挡内容(GDI 语义,见 §21.3),需要无遮挡内容时先 `activate`。
## 23. 增补(2026-11-10:`remote_open` 的 window / region 目标)
### 23.1 问题
`remote_open` 默认推整屏/整虚拟桌面,客户端默认还会把画面等比缩到长边 ≤1920、
短边 ≤1080 再编码。在 4K 屏上,屏幕上 1 个像素对应发送帧不足 1 个像素,模型按截图比例点出来的坐标
天然带量化误差;同时整屏画面里绝大部分像素与本次操作无关,带宽和编码延迟都在为
它们付钱。目标明确时(点某个窗口里的按钮、看某个面板)只推目标窗口或 ROI,
带宽、延迟、点击精度三赢。
### 23.2 window 目标
`remote_open` 新增可选 `window_hwnd`(整数或 `0x` 字符串,与 `region` 互斥):
```
COMMAND_SCREEN_SPY token(32 字节)
[0]=cmd [1]=GDI/DXGI [2]=algo [3]=多屏
[4..11]=HWND uint64 LE // 非 0 = 只推该窗口
[12]=forceVirtualDesktop // window 目标时不使用
```
客户端已有窗口抓屏(人类远程控制的「只显示窗口」同一条路径):帧尺寸取 DWM
可见边框(含标题栏),窗口左上角作为注入原点(`m_iScreenX/Y`),因此
`remote_mouse` 的归一化坐标直接相对窗口帧;客户端强制 GDI 抓取,并在每批注入前
自动 `SetForegroundWindow`。最小化窗口会冻结画面,服务端在开会话前用窗口信息 RPC
(§20.2)校验:窗口不存在 / 最小化 / 矩形为空 → `-32009`;窗口信息响应不带
虚拟桌面尾块(老客户端)→ `-32005`(能力位 `CLIENT_CAP_WINDOW_INFO`)。
window 目标**不受多显示器门限制**:帧来自目标窗口本身,与虚拟桌面抓屏能力无关。
### 23.3 region 目标
`remote_open` 新增可选 `region`(对象,`x`/`y` 可选、`width`/`height` 必填,
1..8192;与 `window_hwnd` 互斥):
1. 参数按虚拟桌面物理像素解释,服务端先取窗口信息响应里的桌面尾块(§22.2),
把矩形裁剪到桌面范围;裁剪后为空 → `-32009`;
2. 按正常流程 `StartRemoteDesktop` 建立整屏会话,拿到发送帧尺寸 `screenW/H`;
3. 把物理矩形按桌面比例换算成**发送帧坐标**(客户端 ROI 坐标与 `screenW/H` 同口径,
已包含缩放),发 `COMMAND_SCREEN_ROI [cmd][RECT]`,客户端据此裁剪抓屏;
4. **等客户端重发 `TOKEN_BITMAPINFO` 且尺寸恰好等于 ROI 尺寸**才标记会话就绪并
返回;超时 → `-32001`。提前返回会让紧随其后的注入仍按旧的全屏 ROI 解释。
region 同样要求新 Windows 客户端(桌面尾块是 `CLIENT_CAP_WINDOW_INFO` 的标志),
老客户端 → `-32005`;多显示器门照旧生效(整屏抓屏能力仍然是前提)。
### 23.4 会话状态与 `remote_mouse` 交互
- `remote_open` 返回 `target`(`screen` / `window` / `region`);window 目标另返回
`window_hwnd`,region 目标返回实际生效的 `region`(已裁剪,虚拟桌面坐标)。
审计记录同样带 `target=` / `window=` / `region=`。
- 目标会话里 `x/y` 就是**相对目标帧**的 0..1,不需要再传 `window_hwnd`
(传了会二次换算,服务端直接 `-32602` 并释放 busy)。
- 目标窗口可能被拖动/缩放:客户端会原地重建并按新尺寸重发 `TOKEN_BITMAPINFO`。
`remote_mouse` 每次注入前对目标会话重新读一次 `GetScreenSize`,用最新帧尺寸
换算,而不是沿用 open 时的快照。
- `remote_keyboard` 的 `expect_hwnd` / `require_foreground` 仍可用;`window_hwnd`
在目标会话里仅作为冗余参数被拒绝。
### 23.5 分辨率缓存的冷启动清理
`screen_width/height` 缓存跨会话保留。`StartRemoteDesktop` 在**冷启动**分支清空
关键帧缓存的同时也清空尺寸缓存:否则 `remote_open` 可能先用上一会话的尺寸
判定 region 握手成功(尤其是目标窗口尺寸恰好接近旧全屏尺寸时)。复用已有子连接的
路径在清空前就 return,Web 观看行为不受影响。
### 23.6 兼容与代价
- 客户端无改动:window 目标复用既有窗口抓屏;region 目标复用 `COMMAND_SCREEN_ROI`。
- 老客户端、Linux 主机不支持 `window_hwnd` / `region`(窗口信息 RPC 仅新 Windows
客户端),返回 `-32005`;默认整屏目标行为与字节流完全不变。
- window/region 目标各自多一次窗口信息 RPC;region 目标还要多等一次
`TOKEN_BITMAPINFO` 到达(通常几十毫秒)。
+1
View File
@@ -513,6 +513,7 @@ P10-C(`3d388f8`)加工具时索性去掉数字——避免每加一个工具
| ~~`search_file` 的描述仍写着「会栈溢出」~~ | — | **已完成**(P10-A,`bb55f52`):描述改为「超过 260 字节的路径会被静默跳过(既不记录也不继续向下递归)」,`tools/mcp_smoke.ps1` 的两处注释改为「MAX_PATH 的条目会被客户端静默跳过(8f718d9 起不再栈溢出)」 |
| ~~`get_screenshot` 无区域裁剪~~ | — | **已完成**(2026-11-10):新增 `mode=region/window/monitor`,默认原生分辨率并返回 `capture` 源矩形元数据;见 `Mcp_Design.md §21` |
| ~~窗口截图坐标要手工换算成屏幕坐标~~ | — | **已完成**(2026-11-10):`remote_mouse` 新增 `window_hwnd` 基准,窗口信息响应追加虚拟桌面矩形尾块;见 `Mcp_Design.md §22` |
| ~~远程控制只能推整虚拟桌面(缩到 1920 宽,点击精度损失)~~ | — | **已完成**(2026-11-10):`remote_open` 新增 `window_hwnd` / `region` 目标,只推目标窗口或 ROI;返回 `target` 与实际矩形,`remote_mouse` 坐标相对目标帧;见 `Mcp_Design.md §23` |
| ~~`terminal_exec` 不能用管道~~ | — | **已完成**(2026-11-10):PTY 会话放开 `\|` / `&&` / `\|\|`(POSIX 还允许 `;`),仅老非 PTY 客户端与 POSIX 裸后台 `&` 仍拒绝;见 `Mcp_Design.md §12.1` |
| 审计不含调用参数 | `Mcp_Design.md §10.8` | 有意设计(防泄漏),维持 |
| `chat_wait` 会取走 inbox | `McpInternal.cpp:431` | 已正确标注非幂等,无需改 |
+64 -4
View File
@@ -2324,7 +2324,7 @@
},
{
"name": "remote_open",
"description": "在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id 与抓屏帧尺寸(screen_w/screen_h,可能是等比缩放后的整屏/整虚拟桌面像素)。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;Windows 多显示器需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝(Linux 截屏/注入天然使用整个 X root,不受此限)。",
"description": "在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。",
"gate": "remote_control",
"write": true,
"platforms": [
@@ -2338,9 +2338,42 @@
"description": "主机 id,取 list_online_hosts / search_hosts 返回的 id 字段",
"type": "string"
},
"region": {
"description": "可选:只推该矩形区域(虚拟桌面物理像素,超出部分自动裁剪;裁剪后为空返回 -32009)。与 window_hwnd 互斥。region 内的归一化坐标 0..1 相对该矩形。要求新 Windows 客户端(窗口信息响应带虚拟桌面矩形),否则返回 -32005。",
"properties": {
"height": {
"description": "矩形高度(像素,1~8192)",
"type": "integer"
},
"width": {
"description": "矩形宽度(像素,1~8192)",
"type": "integer"
},
"x": {
"description": "矩形左上角 X(虚拟桌面绝对坐标,可为负;省略按 0)",
"type": "integer"
},
"y": {
"description": "矩形左上角 Y(虚拟桌面绝对坐标,可为负;省略按 0)",
"type": "integer"
}
},
"required": [
"width",
"height"
],
"type": "object"
},
"timeout_ms": {
"description": "等待屏幕子连接建立 + 分辨率到达的超时毫秒数(可选,默认 20000,上限 600000)",
"type": "integer"
},
"window_hwnd": {
"description": "可选:只推该窗口(DWM 可见边框,含标题栏),帧尺寸与归一化坐标都相对该窗口,带宽和点击精度都优于整屏。取 host_list_windows / get_foreground_window 返回的 hwnd(整数或 0x 前缀字符串);最小化窗口会被拒绝(-32009)。与 region 互斥。要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新 Windows 客户端),老客户端返回 -32005。",
"type": [
"integer",
"string"
]
}
},
"required": [
@@ -2350,21 +2383,48 @@
},
"outputSchema": {
"properties": {
"region": {
"description": "region 目标时实际生效的矩形(虚拟桌面坐标,已裁剪;width/height 为物理像素)",
"properties": {
"height": {
"type": "integer"
},
"width": {
"type": "integer"
},
"x": {
"type": "integer"
},
"y": {
"type": "integer"
}
},
"type": "object"
},
"screen_h": {
"description": "抓屏帧高度(发送帧像素)",
"type": "integer"
},
"screen_w": {
"description": "抓屏帧宽度(发送帧像素:整屏或整虚拟桌面,可能已等比缩放),用于把归一化坐标 0..1 映射为像素",
"description": "抓屏帧宽度(发送帧像素:整屏/整虚拟桌面/目标窗口/区域,可能已等比缩放),用于把归一化坐标 0..1 映射为像素",
"type": "integer"
},
"session_id": {
"description": "控制会话 token,后续 remote_mouse / remote_keyboard / remote_close 用",
"type": "string"
},
"target": {
"description": "抓屏帧目标:screen=整屏/整虚拟桌面;window=目标窗口;region=指定区域",
"type": "string"
},
"window_hwnd": {
"description": "window 目标时的窗口句柄;其他目标不返回",
"type": "integer"
}
},
"required": [
"session_id",
"target",
"screen_w",
"screen_h"
],
@@ -2496,7 +2556,7 @@
},
{
"name": "remote_mouse",
"description": "向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点,默认相对整屏/整虚拟桌面。给 window_hwnd 时改为相对「该窗口与虚拟桌面的交集」(窗口完整可见时即窗口本身;0=左/上边缘,1=右/下边缘),可直接照 get_screenshot mode=window 的图量比例:服务端用该交集与虚拟桌面矩形换算成屏幕坐标,并默认要求该窗口在前台(require_foreground=false 可显式关闭;与 expect_hwnd 同时给出时须指向同一窗口)。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。",
"description": "向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点,默认相对整屏/整虚拟桌面(remote_open 用 window_hwnd/region 时相对该目标帧)。给 window_hwnd 时改为相对「该窗口与虚拟桌面的交集」(窗口完整可见时即窗口本身;0=左/上边缘,1=右/下边缘),可直接照 get_screenshot mode=window 的图量比例:服务端用该交集与虚拟桌面矩形换算成屏幕坐标,并默认要求该窗口在前台(require_foreground=false 可显式关闭;与 expect_hwnd 同时给出时须指向同一窗口);会话本身已锁定窗口/区域时不要再传 window_hwnd。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。",
"gate": "remote_control",
"write": true,
"platforms": [
@@ -2581,7 +2641,7 @@
"integer",
"string"
],
"description": "可选:以该窗口为坐标基准(整数或 0x 前缀字符串)。给定后 x/y(及 drag 的 x2/y2)变为相对「窗口与虚拟桌面的交集」的归一化坐标(窗口完整可见时即窗口本身),服务端用该交集与虚拟桌面矩形换算成屏幕坐标,可直接用 get_screenshot mode=window 图上的比例点。默认要求该窗口是前台(可用 require_foreground=false 显式关闭;与 expect_hwnd 同时给出时须指向同一窗口);窗口不存在/最小化/完全移出虚拟桌面时报错。仅新 Windows 客户端支持(窗口信息 RPC 需带虚拟桌面矩形),否则 -32005。"
"description": "可选:以该窗口为坐标基准(整数或 0x 前缀字符串)。给定后 x/y(及 drag 的 x2/y2)变为相对「窗口与虚拟桌面的交集」的归一化坐标(窗口完整可见时即窗口本身),服务端用该交集与虚拟桌面矩形换算成屏幕坐标,可直接用 get_screenshot mode=window 图上的比例点。默认要求该窗口是前台(可用 require_foreground=false 显式关闭;与 expect_hwnd 同时给出时须指向同一窗口);窗口不存在/最小化/完全移出虚拟桌面时报错。仅新 Windows 客户端支持(窗口信息 RPC 需带虚拟桌面矩形),否则 -32005。会话本身已只推窗口/区域(remote_open 的 window_hwnd/region)时不要再传:坐标本来就相对目标帧。"
}
},
"required": [
+273 -25
View File
@@ -2513,7 +2513,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "remote_open";
tool["description"] = u8"在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id 与抓屏帧尺寸(screen_w/screen_h,可能是等比缩放后的整屏/整虚拟桌面像素)。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;Windows 多显示器需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝(Linux 截屏/注入天然使用整个 X root,不受此限)。";
tool["description"] = u8"在指定在线 Windows 或 Linux 主机上建立远程控制会话(隐藏屏幕子连接)并返回 session_id、抓屏帧尺寸(screen_w/screen_h)与目标(target)。默认推整屏/整虚拟桌面(可能等比缩放);可用 window_hwnd 只推一个窗口,或用 region 只推一个矩形区域,带宽、延迟和点击精度都更好,此时归一化坐标 0..1 相对该目标帧。后续 remote_mouse/remote_keyboard 用归一化坐标(0..1)注入输入,用毕须 remote_close。Linux 需要 X11/Xorg(或 XWayland)桌面,纯 Wayland 会话无法抓屏/注入;window_hwnd/region 仅支持声明 CLIENT_CAP_WINDOW_INFO 的新 Windows 客户端。Windows 多显示器下整屏目标需要新版客户端(整虚拟桌面抓屏),老客户端会被拒绝;window 目标不依赖虚拟桌面抓屏,不受此限。";
tool["inputSchema"] = BuildRemoteOpenInputSchema();
tool["outputSchema"] = BuildRemoteOpenOutputSchema();
tools.append(tool);
@@ -2537,7 +2537,7 @@ std::string BuildToolsListResult(const Json::Value& id) {
{
Json::Value tool(Json::objectValue);
tool["name"] = "remote_mouse";
tool["description"] = u8"向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点,默认相对整屏/整虚拟桌面。给 window_hwnd 时改为相对「该窗口与虚拟桌面的交集」(窗口完整可见时即窗口本身;0=左/上边缘,1=右/下边缘),可直接照 get_screenshot mode=window 的图量比例:服务端用该交集与虚拟桌面矩形换算成屏幕坐标,并默认要求该窗口在前台(require_foreground=false 可显式关闭;与 expect_hwnd 同时给出时须指向同一窗口)。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。";
tool["description"] = u8"向已建立的远程控制会话注入鼠标事件。action 可选 move / down / up / click / right_click / middle_click / drag / scroll;坐标 x/y(及 drag 的 x2/y2)为归一化 0..1 浮点,默认相对整屏/整虚拟桌面(remote_open 用 window_hwnd/region 时相对该目标帧)。给 window_hwnd 时改为相对「该窗口与虚拟桌面的交集」(窗口完整可见时即窗口本身;0=左/上边缘,1=右/下边缘),可直接照 get_screenshot mode=window 的图量比例:服务端用该交集与虚拟桌面矩形换算成屏幕坐标,并默认要求该窗口在前台(require_foreground=false 可显式关闭;与 expect_hwnd 同时给出时须指向同一窗口);会话本身已锁定窗口/区域时不要再传 window_hwnd。button 可选 left/middle/right(默认 left);click 的 clicks 可选 1/2/3(默认 1);scroll 的 delta 正=向下滚、负=向上滚。可选 expect_hwnd / require_foreground / report_foreground 与 remote_keyboard 同义(新 Windows 客户端),可用它确认点击确实落在目标窗口。";
tool["inputSchema"] = BuildRemoteMouseInputSchema();
tool["outputSchema"] = BuildRemoteMouseOutputSchema();
tools.append(tool);
@@ -5050,7 +5050,7 @@ static bool ResolveScreenCtrlSessionHost(const Json::Value& id, const Json::Valu
return true;
}
// remote_open 的 inputSchema(id 必填、timeout_ms 可选)
// remote_open 的 inputSchema(id 必填、timeout_ms / window_hwnd / region 可选)
Json::Value BuildRemoteOpenInputSchema() {
Json::Value props(Json::objectValue);
Json::Value idProp(Json::objectValue);
@@ -5061,6 +5061,41 @@ Json::Value BuildRemoteOpenInputSchema() {
timeoutProp["type"] = "integer";
timeoutProp["description"] = u8"等待屏幕子连接建立 + 分辨率到达的超时毫秒数(可选,默认 20000,上限 600000)";
props["timeout_ms"] = timeoutProp;
Json::Value hwndProp(Json::objectValue);
Json::Value hwndTypes(Json::arrayValue);
hwndTypes.append("integer");
hwndTypes.append("string");
hwndProp["type"] = hwndTypes;
hwndProp["description"] = u8"可选:只推该窗口(DWM 可见边框,含标题栏),帧尺寸与归一化坐标都相对该窗口,带宽和点击精度都优于整屏。取 host_list_windows / get_foreground_window 返回的 hwnd(整数或 0x 前缀字符串);最小化窗口会被拒绝(-32009)。与 region 互斥。要求客户端能力位 CLIENT_CAP_WINDOW_INFO(新 Windows 客户端),老客户端返回 -32005。";
props["window_hwnd"] = hwndProp;
Json::Value regionProp(Json::objectValue);
regionProp["type"] = "object";
regionProp["description"] = u8"可选:只推该矩形区域(虚拟桌面物理像素,超出部分自动裁剪;裁剪后为空返回 -32009)。与 window_hwnd 互斥。region 内的归一化坐标 0..1 相对该矩形。要求新 Windows 客户端(窗口信息响应带虚拟桌面矩形),否则返回 -32005。";
Json::Value regionProps(Json::objectValue);
Json::Value rxProp(Json::objectValue);
rxProp["type"] = "integer";
rxProp["description"] = u8"矩形左上角 X(虚拟桌面绝对坐标,可为负;省略按 0)";
regionProps["x"] = rxProp;
Json::Value ryProp(Json::objectValue);
ryProp["type"] = "integer";
ryProp["description"] = u8"矩形左上角 Y(虚拟桌面绝对坐标,可为负;省略按 0)";
regionProps["y"] = ryProp;
Json::Value rwProp(Json::objectValue);
rwProp["type"] = "integer";
rwProp["description"] = u8"矩形宽度(像素,1~8192)";
regionProps["width"] = rwProp;
Json::Value rhProp(Json::objectValue);
rhProp["type"] = "integer";
rhProp["description"] = u8"矩形高度(像素,1~8192)";
regionProps["height"] = rhProp;
regionProp["properties"] = regionProps;
Json::Value regionRequired(Json::arrayValue);
regionRequired.append("width");
regionRequired.append("height");
regionProp["required"] = regionRequired;
props["region"] = regionProp;
Json::Value schema(Json::objectValue);
schema["type"] = "object";
schema["properties"] = props;
@@ -5076,19 +5111,40 @@ Json::Value BuildRemoteOpenOutputSchema() {
sid["type"] = "string";
sid["description"] = u8"控制会话 token,后续 remote_mouse / remote_keyboard / remote_close 用";
props["session_id"] = sid;
Json::Value target(Json::objectValue);
target["type"] = "string";
target["description"] = u8"抓屏帧目标:screen=整屏/整虚拟桌面;window=目标窗口;region=指定区域";
props["target"] = target;
Json::Value sw(Json::objectValue);
sw["type"] = "integer";
sw["description"] = u8"抓屏帧宽度(发送帧像素:整屏或整虚拟桌面,可能已等比缩放),用于把归一化坐标 0..1 映射为像素";
sw["description"] = u8"抓屏帧宽度(发送帧像素:整屏/整虚拟桌面/目标窗口/区域,可能已等比缩放),用于把归一化坐标 0..1 映射为像素";
props["screen_w"] = sw;
Json::Value sh(Json::objectValue);
sh["type"] = "integer";
sh["description"] = u8"抓屏帧高度(发送帧像素)";
props["screen_h"] = sh;
Json::Value win(Json::objectValue);
win["type"] = "integer";
win["description"] = u8"window 目标时的窗口句柄;其他目标不返回";
props["window_hwnd"] = win;
Json::Value region(Json::objectValue);
region["type"] = "object";
region["description"] = u8"region 目标时实际生效的矩形(虚拟桌面坐标,已裁剪;width/height 为物理像素)";
Json::Value regionProps(Json::objectValue);
const char* regionKeys[] = { "x", "y", "width", "height" };
for (const char* k : regionKeys) {
Json::Value v(Json::objectValue);
v["type"] = "integer";
regionProps[k] = v;
}
region["properties"] = regionProps;
props["region"] = region;
Json::Value schema(Json::objectValue);
schema["type"] = "object";
schema["properties"] = props;
Json::Value required(Json::arrayValue);
required.append("session_id");
required.append("target");
required.append("screen_w");
required.append("screen_h");
schema["required"] = required;
@@ -5130,6 +5186,30 @@ Json::Value BuildRemoteCloseOutputSchema() {
return schema;
}
// region 对象的整数字段(GetIntArg 只查顶层键)
static bool GetNestedIntArg(const Json::Value& obj, const char* key, int& out) {
if (!obj.isMember(key)) return false;
const Json::Value& v = obj[key];
if (!v.isNumeric()) return false;
out = v.asInt();
return true;
}
// 窗口信息单次查询结果(定义在窗口工具族附近,remote_open 的窗口目标也要用)
struct WindowLookup {
int rc = 0; // FetchWindowInfo 返回码
std::string err;
bool found = false;
bool foreground = false;
bool truncated = false; // 客户端可见窗口多于单包上限,列表不完整
WindowDesktopRect desktop; // 新客户端才有的虚拟桌面矩形(window_hwnd 相对坐标用)
WindowEntry entry; // 命中的窗口记录(未命中时字段无意义)
Json::Value json; // 目标窗口快照;未找到时为 null
};
static WindowLookup LookupWindow(context* ctx, uint64_t devId, const char* tool, uint32_t hwnd);
static std::string WindowRpcErrorJson(const Json::Value& id, uint64_t devId, int rc, const std::string& err);
static std::string WindowNotFoundErrorJson(const Json::Value& id, uint32_t hwnd, bool truncated);
// tools/call:remote_open(建立隐藏屏幕子连接 + 取抓屏帧尺寸)
std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2015RemoteDlg* parent) {
CMcpServer& mcp = CMcpServer::Instance();
@@ -5141,13 +5221,84 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
if (!ResolveScreenCtrlSessionHost(id, args, parent, devId, ctx, errJson))
return errJson;
// ---- 帧目标(可选):window_hwnd 只推窗口,region 只推矩形;缺省推整屏/整虚拟桌面 ----
uint32_t windowHwnd = 0;
bool hasWindow = false;
RECT requestedRegion = { 0, 0, 0, 0 };
bool hasRegion = false;
{
std::string oerr;
if (!GetOptionalWindowArg(args, "window_hwnd", windowHwnd, hasWindow, oerr))
return BuildError(id, -32602, oerr);
if (args.isMember("region") && !args["region"].isNull()) {
const Json::Value& rg = args["region"];
if (!rg.isObject())
return BuildError(id, -32602, "Invalid region: expected an object {x,y,width,height}");
int rx = 0, ry = 0, rw = 0, rh = 0;
const bool ok = (!rg.isMember("x") || GetNestedIntArg(rg, "x", rx)) &&
(!rg.isMember("y") || GetNestedIntArg(rg, "y", ry)) &&
GetNestedIntArg(rg, "width", rw) && GetNestedIntArg(rg, "height", rh);
if (!ok)
return BuildError(id, -32602, "Invalid region: x/y/width/height must be integers");
if (rw < 1 || rw > 8192 || rh < 1 || rh > 8192)
return BuildError(id, -32602, "Invalid region: width/height must be 1..8192");
if (rx < -1000000 || rx > 1000000 || ry < -1000000 || ry > 1000000)
return BuildError(id, -32602, "Invalid region: x/y out of range");
requestedRegion = RECT{ rx, ry, rx + rw, ry + rh };
hasRegion = true;
}
if (hasWindow && hasRegion)
return BuildError(id, -32602, "window_hwnd and region are mutually exclusive");
if ((hasWindow || hasRegion) && !ctx->SupportsWindowInfo())
return BuildError(id, -32005,
"window_hwnd/region targets require window info capability, "
"which this host does not support (newer Windows clients only)");
}
// 窗口目标:确认窗口存在且可捕获(窗口列表 RPC);区域目标:取虚拟桌面矩形,
// 用于把物理坐标换算成客户端发送帧坐标。两者都只在新 Windows 客户端可用。
WindowLookup targetWin;
RECT effectiveRegion = { 0, 0, 0, 0 };
if (hasWindow) {
targetWin = LookupWindow(ctx, devId, "remote_open", windowHwnd);
if (targetWin.rc != 0)
return WindowRpcErrorJson(id, devId, targetWin.rc, targetWin.err);
if (!targetWin.found)
return WindowNotFoundErrorJson(id, windowHwnd, targetWin.truncated);
const WindowEntry& we = targetWin.entry;
if (we.flags & WINDOWINFO_MINIMIZED)
return BuildError(id, -32009, "Window hwnd=" + std::to_string(windowHwnd) +
" is minimized; restore it before opening a window-targeted session");
if (we.right <= we.left || we.bottom <= we.top)
return BuildError(id, -32009, "Window hwnd=" + std::to_string(windowHwnd) +
" has an empty rect; window capture is not usable");
} else if (hasRegion) {
std::vector<WindowEntry> wins;
std::string werr;
const int rc = FetchWindowInfo(ctx, devId, "remote_open", 0, wins, werr, nullptr, &targetWin.desktop);
if (rc != 0)
return WindowRpcErrorJson(id, devId, rc, werr);
if (!targetWin.desktop.valid)
return BuildError(id, -32005,
"region target requires a newer Windows client: its window info response "
"does not carry the virtual desktop rect");
const WindowDesktopRect& d = targetWin.desktop;
effectiveRegion.left = requestedRegion.left > d.left ? requestedRegion.left : d.left;
effectiveRegion.top = requestedRegion.top > d.top ? requestedRegion.top : d.top;
effectiveRegion.right = requestedRegion.right < d.left + d.width ? requestedRegion.right : (d.left + d.width);
effectiveRegion.bottom = requestedRegion.bottom < d.top + d.height ? requestedRegion.bottom : (d.top + d.height);
if (effectiveRegion.right <= effectiveRegion.left || effectiveRegion.bottom <= effectiveRegion.top)
return BuildError(id, -32009, "region lies outside the virtual desktop; nothing to capture");
}
// 多显示器门:截图与注入必须共用同一坐标系。Windows 新客户端(CLIENT_CAP_VIRTUAL_DESKTOP)
// 会按 COMMAND_SCREEN_SPY 参数 buffer[11](wire 索引 12)抓整个虚拟桌面,可放行;
// 老 Windows 客户端只能抓单块屏,N>1 时归一化坐标会系统性偏移,拒绝并提示升级。
// 非 Windows(如 Linux)不要求该能力位:其截屏取整个 X root
// (linux/ScreenHandler.h 用 XDisplayWidth/Height),注入用 root 绝对坐标,
// 多输出下天然同源。无冒号(老客户端格式)无法判定,放行不拦。
{
// 窗口目标不依赖虚拟桌面抓屏(帧来自目标窗口),不受此门限制。
if (!hasWindow) {
CString res = ctx->GetAdditionalData(RES_RESOLUTION);
int colon = res.Find(':');
if (colon > 0) {
@@ -5177,9 +5328,17 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
if (!mcp.BeginScreenCtrlOpen(devId, sessionId))
return BuildError(id, -32003, "Device busy: a remote control session is already active for this host");
// 失败清理:会话 + 隐藏对话框 + web-triggered 标记(StartRemoteDesktop 先置标记再发送)。
auto abortOpen = [&]() {
mcp.CloseScreenCtrlSession(devId, sessionId);
if (parent) parent->CloseWebRemoteDesktopByClientID(devId);
WebService().ClearWebTriggered(devId);
};
// 建立隐藏屏幕子连接(发 COMMAND_SCREEN_SPY、标记 web-triggered)。
// 新客户端额外要求抓整个虚拟桌面,保证截图与注入坐标系一致。
if (!WebService().StartRemoteDesktop(devId, ctx->SupportsVirtualDesktop())) {
// 整屏目标额外要求抓整个虚拟桌面,保证截图与注入坐标系一致;窗口目标把 HWND 放进
// token [4..11],客户端进入窗口捕获(DWM 可见边框 + 窗口原点作为注入原点)。
if (!WebService().StartRemoteDesktop(devId, ctx->SupportsVirtualDesktop(), windowHwnd)) {
mcp.CloseScreenCtrlSession(devId, sessionId);
// StartRemoteDesktop 先置 web-triggered 再 Send2Client,发送失败需一并清理,
// 否则该设备残留 web-triggered 标记、后续人类 web 观看会误走隐藏会话路径。
@@ -5204,21 +5363,83 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
}
if (!ready) {
mcp.CloseScreenCtrlSession(devId, sessionId);
if (parent) parent->CloseWebRemoteDesktopByClientID(devId);
WebService().ClearWebTriggered(devId);
abortOpen();
return BuildError(id, -32001, "Timeout waiting for screen sub-connection / resolution");
}
if (!mcp.MarkScreenCtrlReady(devId, sessionId, subCtx, screenW, screenH)) {
// region 目标:客户端 ROI 坐标是「缩放后的整帧」坐标,与服务端拿到的 screenW/H 同口径,
// 所以直接把物理矩形按虚拟桌面比例换算成 ROI 下发,客户端裁掉其余部分。
// 必须等新分辨率到达后才算就绪:否则紧随其后的注入仍会被旧 ROI/全屏解释。
if (hasRegion) {
const WindowDesktopRect& d = targetWin.desktop;
auto toSend = [](int p, int origin, int len, int sendLen) -> int {
if (len <= 0 || sendLen <= 0) return 0;
int val = (int)((double)(p - origin) * (double)sendLen / (double)len + 0.5);
return val < 0 ? 0 : (val > sendLen ? sendLen : val);
};
int rx = toSend(effectiveRegion.left, d.left, d.width, screenW);
int ry = toSend(effectiveRegion.top, d.top, d.height, screenH);
int rx2 = toSend(effectiveRegion.right, d.left, d.width, screenW);
int ry2 = toSend(effectiveRegion.bottom, d.top, d.height, screenH);
int rw = rx2 - rx, rh = ry2 - ry;
if (rw < 1) rw = 1;
if (rh < 1) rh = 1;
if (rw > screenW) rw = screenW;
if (rh > screenH) rh = screenH;
if (rx > screenW - rw) rx = screenW - rw;
if (ry > screenH - rh) ry = screenH - rh;
if (rx < 0) rx = 0;
if (ry < 0) ry = 0;
if (rx != 0 || ry != 0 || rw != screenW || rh != screenH) {
BYTE roiBuf[1 + sizeof(RECT)] = {};
roiBuf[0] = COMMAND_SCREEN_ROI;
RECT roi = { rx, ry, rx + rw, ry + rh };
memcpy(roiBuf + 1, &roi, sizeof(roi));
if (!subCtx->Send2Client(roiBuf, (int)sizeof(roiBuf))) {
abortOpen();
return BuildError(id, -32004, "Failed to send region target to host");
}
bool roiReady = false;
while (std::chrono::steady_clock::now() < deadline) {
int w2 = 0, h2 = 0;
if (WebService().HasActiveSession(devId) &&
WebService().GetScreenSize(devId, w2, h2) && w2 == rw && h2 == rh) {
roiReady = true;
break;
}
if (McpCallCancelled() || !WebService().HasActiveSession(devId)) break;
std::this_thread::sleep_for(std::chrono::milliseconds(50));
}
if (!roiReady) {
abortOpen();
return BuildError(id, -32001,
"Timeout waiting for the host to switch capture to the requested region");
}
screenW = rw;
screenH = rh;
}
}
if (!mcp.MarkScreenCtrlReady(devId, sessionId, subCtx, screenW, screenH,
hasWindow || hasRegion)) {
// 并发 remote_close 已关掉会话:放弃本次 open(子连接已由 close 关闭)。
return BuildError(id, -32002, "Remote control session was closed concurrently: " + sessionId);
}
const char* targetKind = hasWindow ? "window" : (hasRegion ? "region" : "screen");
// 审计:打开会话(不可关闭)。
if (parent) {
std::string text = "host " + std::to_string(devId) + " remote-open: session " + sessionId
+ " (" + std::to_string(screenW) + "x" + std::to_string(screenH) + ")";
+ " (" + std::to_string(screenW) + "x" + std::to_string(screenH) + ")"
+ " target=" + targetKind;
if (hasWindow) {
text += " window=" + std::to_string(windowHwnd);
} else if (hasRegion) {
text += " region=(" + std::to_string(effectiveRegion.left) + "," + std::to_string(effectiveRegion.top)
+ ")-(" + std::to_string(effectiveRegion.right) + "," + std::to_string(effectiveRegion.bottom) + ")";
}
parent->PostMessageA(WM_SHOWERRORMSG,
(WPARAM)new CString(ToAnsi(text, 936).c_str()),
(LPARAM)new CString(_TR("MCP远程控制")));
@@ -5227,8 +5448,19 @@ std::string BuildRemoteOpen(const Json::Value& id, const Json::Value& args, CMy2
Json::Value result(Json::objectValue);
Json::Value structuredContent(Json::objectValue);
structuredContent["session_id"] = sessionId;
structuredContent["target"] = targetKind;
structuredContent["screen_w"] = screenW;
structuredContent["screen_h"] = screenH;
if (hasWindow) {
structuredContent["window_hwnd"] = windowHwnd;
} else if (hasRegion) {
Json::Value region(Json::objectValue);
region["x"] = effectiveRegion.left;
region["y"] = effectiveRegion.top;
region["width"] = effectiveRegion.right - effectiveRegion.left;
region["height"] = effectiveRegion.bottom - effectiveRegion.top;
structuredContent["region"] = region;
}
result["structuredContent"] = structuredContent;
Json::Value content(Json::arrayValue);
@@ -5575,17 +5807,6 @@ static bool GetOptionalBoolArg(const Json::Value& args, const char* key, bool& o
return true;
}
struct WindowLookup {
int rc = 0; // FetchWindowInfo 返回码
std::string err;
bool found = false;
bool foreground = false;
bool truncated = false; // 客户端可见窗口多于单包上限,列表不完整
WindowDesktopRect desktop; // 新客户端才有的虚拟桌面矩形(window_hwnd 相对坐标用)
WindowEntry entry; // 命中的窗口记录(未命中时字段无意义)
Json::Value json; // 目标窗口快照;未找到时为 null
};
// 按 hwnd 在最新可见窗口列表里查找(只发一次窗口信息 RPC)。
static WindowLookup LookupWindow(context* ctx, uint64_t devId, const char* tool, uint32_t hwnd) {
WindowLookup w;
@@ -5923,7 +6144,8 @@ Json::Value BuildRemoteMouseInputSchema() {
u8"服务端用该交集与虚拟桌面矩形换算成屏幕坐标,可直接用 get_screenshot mode=window 图上的比例点。"
u8"默认要求该窗口是前台(可用 require_foreground=false 显式关闭;与 expect_hwnd 同时给出时"
u8"须指向同一窗口);窗口不存在/最小化/完全移出虚拟桌面时报错。"
u8"仅新 Windows 客户端支持(窗口信息 RPC 需带虚拟桌面矩形),否则 -32005。";
u8"仅新 Windows 客户端支持(窗口信息 RPC 需带虚拟桌面矩形),否则 -32005。"
u8"会话本身已只推窗口/区域(remote_open 的 window_hwnd/region)时不要再传:坐标本来就相对目标帧。";
props["window_hwnd"] = winHwnd;
Json::Value schema(Json::objectValue);
@@ -6074,6 +6296,23 @@ std::string BuildRemoteMouse(const Json::Value& id, const Json::Value& args, CMy
// 窗口核对放在会话校验之后:session_id 无效时应当先报会话错误,不白跑一次 RPC;
// busy 已置上,窗口不满足时必须先释放再返回。
// 会话已只推窗口/区域时,x/y 本来就相对目标帧;window_hwnd 的基准是整虚拟桌面,
// 再换算会二次偏移。须先释放 busy 再返回。
if (hasWindowFrame && mcp.IsScreenCtrlTargeted(devId, sessionId)) {
mcp.EndScreenCtrlAction(devId, sessionId);
return BuildError(id, -32602,
"window_hwnd is redundant for a window/region-targeted session: "
"x/y are already 0..1 relative to the streamed frame");
}
// 目标窗口可能在会话期间被拖动/缩放:客户端会原地重建并按新尺寸重发 TOKEN_BITMAPINFO,
// 用服务端刚收到的最新帧尺寸覆盖 open 时的快照,避免坐标继续按旧比例换算。
if (mcp.IsScreenCtrlTargeted(devId, sessionId)) {
int latestW = 0, latestH = 0;
if (WebService().GetScreenSize(devId, latestW, latestH)) {
screenW = latestW;
screenH = latestH;
}
}
// 窗口与虚拟桌面的交集:get_screenshot mode=window 的源矩形也是这个交集,
// window_hwnd 比例点按同一交集换算,截图被裁掉的部分不会让点击整体偏移。
int clipL = 0, clipT = 0, clipR = 0, clipB = 0;
@@ -10462,7 +10701,8 @@ bool CMcpServer::BeginScreenCtrlOpen(uint64_t device_id, const std::string& sess
}
bool CMcpServer::MarkScreenCtrlReady(uint64_t device_id, const std::string& sessionId,
context* subCtx, int screenW, int screenH) {
context* subCtx, int screenW, int screenH,
bool targeted) {
std::lock_guard<std::mutex> lk(m_ScreenCtrlMutex);
auto it = m_ScreenCtrlSessions.find(device_id);
if (it == m_ScreenCtrlSessions.end() || it->second.sessionId != sessionId) return false;
@@ -10471,11 +10711,19 @@ bool CMcpServer::MarkScreenCtrlReady(uint64_t device_id, const std::string& sess
s.started = true;
s.screenW = screenW;
s.screenH = screenH;
s.targeted = targeted;
s.lastActiveAt = time(nullptr);
m_ScreenCtrlContextToDevice[subCtx] = device_id;
return true;
}
bool CMcpServer::IsScreenCtrlTargeted(uint64_t device_id, const std::string& sessionId) {
std::lock_guard<std::mutex> lk(m_ScreenCtrlMutex);
auto it = m_ScreenCtrlSessions.find(device_id);
if (it == m_ScreenCtrlSessions.end() || it->second.sessionId != sessionId) return false;
return it->second.targeted;
}
int CMcpServer::CloseScreenCtrlSession(uint64_t device_id, const std::string& sessionId) {
context* unblockCtx = nullptr;
int rc = 1;
+10 -2
View File
@@ -293,9 +293,15 @@ public:
bool BeginScreenCtrlOpen(uint64_t device_id, const std::string& sessionId);
// 子连接就绪(HasActiveSession && 分辨率到达)后调用:填 subCtx/分辨率并置 started。
// targeted=true 表示 remote_open 指定了 window_hwnd/region(帧不再是整屏)。
// false = 会话已被并发关闭(调用方应放弃本次 open)。
bool MarkScreenCtrlReady(uint64_t device_id, const std::string& sessionId,
context* subCtx, int screenW, int screenH);
context* subCtx, int screenW, int screenH,
bool targeted = false);
// 会话是否只推窗口/区域:此时归一化坐标已经相对目标帧,remote_mouse 的 window_hwnd
// 基准(相对整虚拟桌面)不再适用。须在 BeginScreenCtrlAction 之后调用。
bool IsScreenCtrlTargeted(uint64_t device_id, const std::string& sessionId);
// 注入前登记(校验 sessionId/started/!busy/!closed)。输出 subCtx/screenW/H。
// 注入期间 busy=true,保证 close/sweep/断线不与注入并发擦会话(镜像终端 busy 模式,
@@ -840,8 +846,10 @@ private:
bool closed = false; // 注入期间屏幕子连接已断(由注入线程收尾)
time_t lastActiveAt = 0; // idle 回收用(秒)
std::chrono::steady_clock::time_point startedAt = std::chrono::steady_clock::now(); // P11
int screenW = 0; // 物理捕获分辨率(来自 TOKEN_BITMAPINFO)
int screenW = 0; // 抓屏帧宽度(TOKEN_BITMAPINFO;目标窗口/区域时为裁剪后尺寸)
int screenH = 0;
// remote_open 指定了 window_hwnd/region:帧是窗口/区域而非整屏,归一化坐标已相对该帧。
bool targeted = false;
// P10-C 键鼠锁定:inputBlocked 是服务端认为的锁定状态(唯一真相,用于强制解锁);
// blockUntil 是自动解锁期限;blockAutoReleased 待下一次 remote_block_input 上报。
bool inputBlocked = false;
+19 -7
View File
@@ -2475,7 +2475,7 @@ void CWebService::NotifyClipboardText(uint64_t device_id, const std::string& tex
}
}
bool CWebService::StartRemoteDesktop(uint64_t device_id, bool forceVirtualDesktop) {
bool CWebService::StartRemoteDesktop(uint64_t device_id, bool forceVirtualDesktop, uint32_t windowHwnd) {
if (!m_pParentDlg) return false;
context* ctx = m_pParentDlg->FindHost(device_id);
@@ -2510,13 +2510,17 @@ bool CWebService::StartRemoteDesktop(uint64_t device_id, bool forceVirtualDeskto
// This creates a new hidden Web dialog while MFC dialog remains visible
// Cold start: drop any stale IDR cached from a previous capture session, it
// may have a different resolution / encoder instance.
// may have a different resolution / encoder instance. Also invalidate the
// cached resolution so remote_open cannot mistake the previous session's
// size for this one's (window/region captures change it).
{
std::lock_guard<std::mutex> lock(m_DeviceCacheMutex);
auto it = m_DeviceCache.find(device_id);
if (it != m_DeviceCache.end()) {
std::lock_guard<std::mutex> cache_lock(it->second->cache_mutex);
it->second->keyframe_cache.clear();
it->second->screen_width = 0;
it->second->screen_height = 0;
}
}
@@ -2525,11 +2529,19 @@ bool CWebService::StartRemoteDesktop(uint64_t device_id, bool forceVirtualDeskto
bToken[1] = 0; // DXGI mode: 0=GDI
bToken[2] = ALGORITHM_H264; // H264 algorithm
bToken[3] = 1; // Multi-screen: true
// 参数 buffer[11](wire 索引 12):强制抓整个虚拟桌面。客户端把 token 剥掉命令字节后
// 按 buffer[i]=bToken[i+1] 索引,且 buffer[3..10](wire [4..11])是 HWND,
// 不能占用。老客户端会忽略该字节,服务端只在客户端声明
// CLIENT_CAP_VIRTUAL_DESKTOP 时置位。
bToken[12] = forceVirtualDesktop ? 1 : 0;
if (windowHwnd) {
// 只推目标窗口(MCP remote_open window_hwnd):客户端按 wire [4..11] 的 HWND
// 进入窗口捕获,用 DWM 可见边框作为帧尺寸、窗口原点作为注入坐标原点;窗口
// 捕获强制 GDI,且与屏索引/虚拟桌面无关,所以不再置 forceVirtual([12])。
uint64_t hwnd64 = windowHwnd;
memcpy(bToken + 4, &hwnd64, sizeof(uint64_t));
} else {
// 参数 buffer[11](wire 索引 12):强制抓整个虚拟桌面。客户端把 token 剥掉命令字节后
// 按 buffer[i]=bToken[i+1] 索引,且 buffer[3..10](wire [4..11])是 HWND,
// 不能占用。老客户端会忽略该字节,服务端只在客户端声明
// CLIENT_CAP_VIRTUAL_DESKTOP 时置位。
bToken[12] = forceVirtualDesktop ? 1 : 0;
}
return ctx->Send2Client(bToken, sizeof(bToken)) != FALSE;
}
+4 -1
View File
@@ -195,7 +195,10 @@ public:
// Start remote desktop session for web viewing.
// forceVirtualDesktop=true 时要求客户端抓整个虚拟桌面(MCP 远程控制):
// 多显示器下截图与鼠标注入必须共用同一坐标系,Web 观看仍保持原有轮转行为。
bool StartRemoteDesktop(uint64_t device_id, bool forceVirtualDesktop = false);
// windowHwnd != 0 时只推该窗口(MCP remote_open window_hwnd):客户端用 DWM 可见
// 边框作为帧尺寸、窗口原点作为注入坐标原点,此时忽略 forceVirtualDesktop。
bool StartRemoteDesktop(uint64_t device_id, bool forceVirtualDesktop = false,
uint32_t windowHwnd = 0);
// Stop remote desktop session
void StopRemoteDesktop(uint64_t device_id);