Feature: Add native region, window and monitor capture to get_screenshot
New Windows clients advertise CLIENT_CAP_SCREEN_REGION and accept a 24-byte ScreenPreviewReqEx appended to the existing 8-byte preview request, so get_screenshot can capture a region, a window or a single monitor at 1:1 resolution instead of only the scaled virtual desktop. Successful v2 responses append an optional ScreenCaptureMeta block reporting the source rect and scale, letting callers map coordinates back for remote input. Old clients and old servers keep the v1 byte stream unchanged. The 8192 px per-side bound only applies to native (1:1) capture, where it guards bitmap memory; scaled captures are unaffected so ultra-wide virtual desktops (for example triple 4K) still produce thumbnails and previews. max_width is clamped to [64,1920] as before instead of rejected, matching the documented schema. Co-Authored-By: deepseek-flash
This commit is contained in:
1 parent
b2c0d81396
commit
235a8a622c
11 files changed
+668
-97
No files matched your search
@@ -1063,3 +1063,75 @@ GUI 自动化的失败大多不是「事件没发出去」,而是「事件进
|
||||
列表不完整;`expect_hwnd` 查不到时 `-32009` 的文案区分「窗口可能还在、只是没返回」
|
||||
与「隐藏/已关闭」;`activate` 复核时目标不在返回的这一批里则记 `state=unknown`、
|
||||
`reason=list_truncated`,而不是 `missing`。任何情况下都不要据截断的列表断定窗口已销毁。
|
||||
|
||||
|
||||
## 21. 增补(2026-11-10:区域/窗口/显示器原生分辨率截图)
|
||||
|
||||
### 21.1 问题
|
||||
|
||||
旧的 `get_screenshot` 只有「整个虚拟桌面 + `max_width` 缩放」一种形态。GUI 自动化真正
|
||||
需要的往往是某个窗口或某块 ROI 的原始像素:整屏缩到 1024 后聊天正文、按钮小字都糊了,
|
||||
OCR 与视觉定位同时退化;把 `max_width` 抬到 1920 对 4K 屏仍不够,而且传的依旧是全屏。
|
||||
|
||||
### 21.2 协议
|
||||
|
||||
新增能力位 `CLIENT_CAP_SCREEN_REGION=0x0200`(Windows 客户端 `DefaultCaps()` 置位;
|
||||
Linux 客户端只有 v1 处理分支,不声明)。请求在原有 8 字节 `ScreenPreviewReq` 之后追加
|
||||
24 字节 `ScreenPreviewReqEx`(共 32 字节):
|
||||
|
||||
```
|
||||
u8 mode ScreenCaptureMode: VDESKTOP=0 / REGION=1 / WINDOW=2 / MONITOR=3
|
||||
u8 flags SCREEN_CAPTURE_F_NATIVE=0x01(按源矩形 1:1,忽略 maxWidth)
|
||||
u16 monitor mode=MONITOR 的序号
|
||||
i32 x, y, w, h mode=REGION 的矩形(虚拟桌面坐标)
|
||||
u32 hwnd mode=WINDOW 的窗口句柄
|
||||
```
|
||||
|
||||
响应仍是 `ScreenPreviewRspHeader`(16) + JPEG;v2 成功时客户端在 JPEG 之后追加 24 字节
|
||||
`ScreenCaptureMeta`(magic `'SCM2'`=0x324D4353,`x/y/w/h` + `scale` + `mode`),如实回报
|
||||
实际抓取的源矩形与缩放百分比。老服务端只按 `header.bytes` 取图,会忽略尾块;老客户端
|
||||
忽略请求尾巴、按 v1 抓整屏。服务端只对声明能力位的主机发 v2,两个方向都不需要版本协商。
|
||||
|
||||
### 21.3 抓取语义
|
||||
|
||||
| mode | 参数 | 源矩形 | 默认尺寸 |
|
||||
|---|---|---|---|
|
||||
| `screen` | — | 虚拟桌面 `SM_*VIRTUALSCREEN` | 沿用 RTT 自适应(≤1024),可传 `max_width` |
|
||||
| `region` | `x/y/width/height` | 与虚拟桌面求交后裁剪(`x/y` 可为负) | 1:1 原生分辨率 |
|
||||
| `window` | `hwnd` | `GetWindowRect` 后与虚拟桌面求交;`IsWindow` 且非 `IsIconic` | 1:1 原生分辨率 |
|
||||
| `monitor` | `monitor` | 0=主显示器(`MonitorFromPoint`);1..N 按 `EnumDisplayMonitors` 顺序跳过主屏 | 1:1 原生分辨率 |
|
||||
|
||||
- `region/window/monitor` 只有显式传 `max_width`(钳制到 64..1920) 才等比缩小;缺省即原生分辨率,
|
||||
1:1 抓取单边硬上限 8192 像素(覆盖 8K 显示器,同时拦住异常区域打爆内存)。缩放路径不受此限,
|
||||
整屏同样适用——三屏 4K 这类超宽虚拟桌面仍能正常抓缩略图。
|
||||
- 需要缩放时目标宽高做偶数对齐(JPEG 更省),1:1 时不改尺寸。
|
||||
- 抓屏与注入共用虚拟桌面坐标系(多显示器时原点可为负),`structuredContent.capture`
|
||||
回报的就是实际源矩形,可直接用于换算点击坐标。
|
||||
- 窗口抓取是 GDI 抓屏语义:被其他窗口遮挡的部分截到的是遮挡物,不是 `PrintWindow`
|
||||
式的重绘;需要无遮挡内容时先 `activate` 目标窗口。矩形含非客户区。
|
||||
|
||||
### 21.4 工具参数与返回
|
||||
|
||||
`get_screenshot` 的 `inputSchema` 新增 `mode`(枚举 `screen|region|window|monitor`,默认
|
||||
`screen`)与 `x/y/width/height/hwnd/monitor`;`max_width` 的描述按模式分叉。`hwnd` 直接
|
||||
取 `host_list_windows` / `get_foreground_window` 返回的句柄,同时接受整数与 `0x` 字符串。
|
||||
返回值在 `image` 之外新增 `structuredContent.capture = {mode,x,y,width,height,scale,native}`
|
||||
(老客户端不回尾块时只有 `mode`)。`screen` 模式对新客户端也走 v2,因此同样能拿到源矩形。
|
||||
|
||||
### 21.5 错误
|
||||
|
||||
| 场景 | code | 说明 |
|
||||
|---|---|---|
|
||||
| 客户端无 `CLIENT_CAP_SCREEN_REGION` 却要 region/window/monitor | `-32005` | 换 `mode=screen` 或升级客户端,改别的参数修不好 |
|
||||
| `window` 的 hwnd 不存在、已最小化、完全在虚拟桌面外或单边超过 8192 px | `-32009` | 先 `activate` / `restore`,或重新取 hwnd;超大窗口改用 `region` 分段截取 |
|
||||
| `monitor` 序号越界、`region` 裁剪后为空 | `-32602` | 参数问题 |
|
||||
| 抓屏/编码失败 | `-32000` | 主机侧失败(如无桌面会话) |
|
||||
| 超时 / 设备忙 | `-32001` / `-32003` | 同其他主连接工具 |
|
||||
|
||||
### 21.6 兼容与代价
|
||||
|
||||
- 全部挂在能力位后面:老客户端、老服务端的字节流逐字节不变;Linux 仍走 v1 全屏。
|
||||
- 客户端对抓屏请求保持单飞(同一时刻 1 个),并投递到工作线程编码,不阻塞接收线程;
|
||||
并发请求直接丢弃,表现为服务端超时。
|
||||
- 原生分辨率意味着更大的 JPEG 与 base64 体积:区域越大、越多窗口细节,单次响应越贵。
|
||||
只截需要的 ROI,比整屏 1920 更省也更快。
|
||||
@@ -280,9 +280,11 @@ MCP 现在能读、能传、能搜,**唯独不能删、不能改名、不能
|
||||
|
||||
### 4.2 窗口级截图
|
||||
|
||||
`COMMAND_SCREEN_WINDOW`(`client/ScreenManager.cpp:894`)接的是**屏幕流**(按窗口标题捕获,空串恢复全屏),不是一次性 JPEG。要做 `get_screenshot(window_title=...)` 需要服务端在屏幕子连接上收若干帧再截一张,本质上是「起一个临时屏幕会话」——比现有 `get_screenshot`(主连接一次 RPC)重得多。
|
||||
|
||||
**建议**:先做「AI 侧的替代方案」——`remote_open` 已能拿全屏,`list_windows` 能给窗口句柄与标题,模型可以据此用 `remote_mouse` 点击。等 `remote_*` 在真实任务里被证明「全屏截图不够用」再投入。
|
||||
**已完成**(2026-11-10,`CLIENT_CAP_SCREEN_REGION`):`get_screenshot` 新增 `mode=window`
|
||||
(按 hwnd 原生分辨率抓取)以及 `mode=region` / `mode=monitor`,走主连接 v2 RPC + 客户端
|
||||
`GetWindowRect` / `StretchBlt`,一次性返回 JPEG 并附源矩形元数据,不需要为单张截图起
|
||||
屏幕流子会话。`COMMAND_SCREEN_WINDOW` 仍适用于需要**持续**窗口视频流的场景,与一次性
|
||||
JPEG 不冲突;详见 `Mcp_Design.md §21`。
|
||||
|
||||
### 4.3 代理隧道(价值最高的「新维度」)
|
||||
|
||||
@@ -509,7 +511,7 @@ P10-C(`3d388f8`)加工具时索性去掉数字——避免每加一个工具
|
||||
| ~~`list_windows` 无 `pid` 过滤~~ | — | **已完成**(P10-A,`bb55f52`):`list_processes` / `list_windows` 都加了 `name` + `pid` |
|
||||
| `search_file` 无深度/大小上限参数 | `McpServer.cpp:8050` | 客户端固定深度 32 / 10000 条,服务端可加 `max_depth` 但需客户端支持;暂不做(P12) |
|
||||
| ~~`search_file` 的描述仍写着「会栈溢出」~~ | — | **已完成**(P10-A,`bb55f52`):描述改为「超过 260 字节的路径会被静默跳过(既不记录也不继续向下递归)」,`tools/mcp_smoke.ps1` 的两处注释改为「MAX_PATH 的条目会被客户端静默跳过(8f718d9 起不再栈溢出)」 |
|
||||
| `get_screenshot` 无区域裁剪 | `McpServer.cpp:2085` | 有 `max_width`;ROI 需客户端改动,收益有限,不做 |
|
||||
| ~~`get_screenshot` 无区域裁剪~~ | — | **已完成**(2026-11-10):新增 `mode=region/window/monitor`,默认原生分辨率并返回 `capture` 源矩形元数据;见 `Mcp_Design.md §21` |
|
||||
| 审计不含调用参数 | `Mcp_Design.md §10.8` | 有意设计(防泄漏),维持 |
|
||||
| `chat_wait` 会取走 inbox | `McpInternal.cpp:431` | 已正确标注非幂等,无需改 |
|
||||
|
||||
|
||||
Reference in new issue
Block a user