屏幕窗口截图 machine202502/dsh-screenshoot

dsh-screenshoot

DSH 插件，用来截取屏幕和窗口。跨平台：Windows、macOS、Linux（X11）。

和普通「屏幕截图」最大的区别：窗口是按自己的像素截取的，所以即使窗口被别的窗口挡住、缩在后台、或者没有焦点，也能截到。前台在放电影、智能体应用在后面，都不影响。

工具

| 工具 | 做什么 |
| screen_monitors | 列出显示器：位置、尺寸、缩放、是否主屏 |
| screen_windows | 列出可见窗口：id、pid、标题、进程、位置、尺寸 |
| screen_capture_monitor | 截取整个显示器 |
| screen_capture_region | 截取矩形区域 |
| screen_capture_window | 按 pid、title 或 id（十进制或 0x…）截取窗口 |

区域会按虚拟桌面的边界裁剪：超出屏幕时，只截交集部分，并在说明里标上 clamped；完全没有交集时，返回明确的错误，并附上桌面尺寸。

三个截图工具都有 delayMs，用来在拍摄前等待（最多 30 秒）。打开菜单、播放动画、窗口还没重绘完的时候，这个参数很有用。

所有截图都存成 PNG，结果里返回路径。你可以用 read_image 工具打开它，看看图片。

截取窗口的一部分

窗口可以不截整块，而是按窗口左上角为原点裁出一个矩形：

screen_capture_window { pid: 11184, crop: { x: 40, y: 60, width: 420, height: 240 } }
→ window 420×240 … · crop 420×240 at 40,60

坐标从窗口的角算起（内容区的左上角），不是从屏幕算起。矩形超出截图范围时，返回错误并附上图片尺寸——不会悄悄按边缘裁掉。

裁剪在所有平台都能用：先用平台方式截图，再用内置解码器（src/png.js）裁 PNG，不需要 ImageMagick，也没有外部依赖。

聊天里的截图

和 Browser 一样：截图之后，工具那一行会出现缩略图。宿主在 127.0.0.1:49231 起一个本地帧服务器，工具返回标记 [shot:<id>]，客户端据此画出 。内存里保留最近 24 帧，文件留在磁盘上。

点缩略图会在新标签页打开 PNG。

各平台的实现方式

Windows —— PowerShell + Win32：

- EnumWindows + DwmGetWindowAttribute —— 窗口列表和精确边界；
- PrintWindow(PW_RENDERFULLCONTENT) —— 把窗口渲染到 bitmap，而不是复制屏幕；正因如此，被遮挡的窗口也能截到；
- Graphics.CopyFromScreen —— 显示器和区域；
- per-monitor DPI awareness —— 坐标和尺寸都用物理像素（200% 缩放下很重要）。
- 窗口标题以 base64 传递，stdout 强制 UTF-8——否则西里尔字母会乱码。

macOS —— screencapture + JavaScript for Automation：

- NSScreen —— 显示器；
- CGWindowListCopyWindowInfo —— 窗口及其边界；
- screencapture -l <window id> —— 截取窗口，即使窗口被遮挡也行；-R —— 截取区域；-D —— 截取显示器。

需要 Screen Recording 权限（系统设置 → 隐私与安全性）。没有这个权限，macOS 只会返回壁纸。

Linux（X11） —— xrandr、wmctrl、ImageMagick import：

- xrandr --query —— 列出显示器；
- wmctrl -lGpx —— 列出窗口、pid 和几何信息；
- import -window <id> —— 从窗口自己的缓冲区截取窗口；-window root -crop —— 截取区域。

在 Wayland 下，X11 工具看不到窗口：插件会如实说明缺少什么，而不是返回一张黑图。Wayland 需要 portal/grim 方案。

安装

npx --yes github:machine202502/dsh-screenshoot

或手动安装：在 ~/.dsh/profiles/desktop/package.json 中添加

{
"dependencies": { "dsh-screenshoot": "github:machine202502/dsh-screenshoot" },
"dsh": { "profile": { "bundles": ["…", "dsh-screenshoot"] } }
}

然后重启 DSH。插件不引入 npm 依赖 —— 只用平台自带的系统工具。

示例

screen_monitors
→ 0* 3200x2000 at 0,0

screen_windows { title: "Brave" }
→ 132518 pid 9800 3200x1904 at 0,0 machine202502/dsh-browser – Brave

screen_capture_window { title: "Brave" }
→ PNG 路径 3200x1904（窗口当时在 DSH 后面）

screen_capture_region { x: 100, y: 100, width: 800, height: 500 }
screen_capture_monitor { monitor: 0 }

要求

| 平台 | 需要什么 |
| Windows | PowerShell 5.1+（默认自带）、.NET Framework |
| macOS | Screen Recording 权限 |
| Linux X11 | xrandr、wmctrl、ImageMagick（import） |
| Linux Wayland | grim、wlr-randr（仅显示器/区域） |

验证

node tests/probe.mjs # 直接测试平台后端
node tests/smoke.mjs # 通过 index.js 测试工具