截图提问 yuyu297/dsh-screenshot

dsh-screenshot

一个截图提问插件，用于 DeepSeek Harness（DSH）。

在输入框点一下就能截屏，屏幕定格后出现一个选框，你可以拖动它，再微调，裁好的图会作为普通图片附件落进消息里——正好配上你准备输入的问题。

多数截图工具做不到的一点：画面不含 Harness 窗口本身，所以你可以直接指向它背后的任何东西。

为什么做这个

想就屏幕上的某个东西提问，通常得这么干：用系统工具截图，找到文件，拖进聊天框，再打字。四步，还得绕一趟文件系统。这个插件把它压成一次点击。

遮罩层是页面内的界面，不是系统窗口，所以不会留下任何东西：没有托盘图标，没有悬浮窗，也没有文件要清理。

功能

- 一键完成，不弹对话框——相机按钮就在输入框的工具行里。
- 选区可调——第一次拖完选框会留着，带八个手柄（四角、四边），内部也能拖动。挪到满意为止；确认之前不会裁剪。
- 按钮或按键确认——按 Enter 或点确认按钮；按 Esc、右键或点取消按钮则丢弃整次截图。
- 实时尺寸读数，单位是真实像素，不是屏幕像素。
- 排除 Harness 窗口——定格时把应用自己的窗口最小化，随后立刻恢复，所以画面里只有其他应用。
- 快——常驻的截图助手保持一个热进程，窗口列表有缓存，定格耗时约 45 ms 而不是 320 ms，整次截图大约 130–180 ms。详见性能。
- 顺滑——选区是单个元素，用 box-shadow 做暗化，指针移动合并为每个动画帧提交一次，所以选框按显示刷新率跟随光标，而不是每个事件都刷新 DOM。
- 无需清理——裁剪结果直接作为浏览器附件进入草稿；没有截图目录，也没有孤儿文件。

环境要求

- Windows——截图助手使用 PowerShell 5.1，配合 WinForms 和 GDI+。
- DSH，带 Web GUI（dsh web 或桌面应用）。插件需要 webServer Host 服务和 Conversation Client 服务，标准 web 配置档里两者都有。
- 想让模型看到裁剪结果，需要一个接受图片的模型。

安装

dsh plugin --profile <profile> add github:<your-account>/dsh-screenshot

然后重启 DSH，让 Host 那一半注册路由并启动助手。

本地开发时，改为安装目录：

dsh plugin --profile <profile> add ./dsh-screenshot

用法

1. 点输入框工具行左侧的相机按钮。
2. 屏幕定格。拖动，框出你想提问的区域。
3. 松开。选框留着——拖它的边、角或内部来调整。
4. 按 Enter 或点击 Confirm。按 Esc、右键单击或点击 Cancel 则放弃。
5. 裁剪结果会作为图片附件出现在草稿中。输入你的问题并发送。

工作原理

两部分，一条流程。

宿主部分（index.js）持有一个常驻 PowerShell 辅助进程（scripts/capture.ps1），以及两条精确匹配的同源 HTTP 路由： /api/dsh-screenshot/capture 和 /api/dsh-screenshot/crop。辅助进程从 stdin 读取按换行分隔的帧：

| 传入帧 | 含义 |
| <id>\|ping | 健康检查 |
| <id>\|shot\|<hideApp>\|<hideDelayMs> | 截取一帧 |
| <id>\|crop\|<srcPath>\|<l>,<t>,<w>,<h>\|<dstPath> | 从一帧中裁出一个矩形 |

并返回 OK\|<id>\|<w>\|<h>\|<bytes>\|<path>\|<sx>\|<sy>\|<sw>\|<sh> 或 ERR\|<id>\|<reason>。

冻结画面之前，辅助进程会最小化本应用拥有的每个可见顶层窗口，等待画面稳定，截取虚拟桌面，然后把每个窗口恢复到之前的状态和前台。这两条路由要求带上应用自己的鉴权 cookie，所以机器上无关的页面无法通过它们读取屏幕。截取返回原始 PNG 字节，外加 x-shot-width、x-shot-height 和 x-shot-id 响应头；裁剪返回该矩形的原始 PNG 字节，外加 x-crop-width 和 x-crop-height。

两次调用之间，帧留在磁盘上（最多六个，最旧的被淘汰），所以裁剪不必让像素在浏览器里往返一趟。每帧只被一次裁剪消费，消费后即删除。

客户端部分（client.js）注册两个插槽：

- conversation.input.left —— 相机按钮。
- shell.overlay —— 冻结帧的选择界面，只在有待处理的截取时挂载。

确认时，选区通过显示时所用的同一套 object-fit: contain 黑边计算，映射回截图自身的像素，宿主再从已持有的帧中裁出该矩形。结果作为 File 交给输入框，走 Conversation 服务的草稿附件。它的行为与粘贴的图片完全一致。

性能

我们对一次截取逐步做了性能分析，因为「感觉慢」其实是四项独立的开销，而不是一项。在 150% DPI 的 2560×1600 桌面上测得：

| 步骤 | 初版 | 现在 |
| Get-Process 窗口归属扫描 | 79 ms | 0（已缓存，20 s TTL） |
| EnumWindows | 25 ms | 0（已缓存，用 IsWindow 校验） |
| 等待最小化动画 | 320 ms | 45 ms |
| CopyFromScreen 2560×1600 | 45 ms | 45 ms |
| PNG 编码 | 45 ms | 45 ms（复用缓冲区） |
| 恢复后的稳定等待 | 80 ms | 0（恢复是异步的） |
| 总计 | ≈520–600 ms | ≈130–180 ms |

另一半在客户端：

- 这条路由以前返回的 PNG 是 base64 编码后塞进 JSON 的，所以浏览器得先解析一个几兆字节的字符串，再对 data: URL 做 base64 解码，第一个像素才能出现。现在它返回 image/png，客户端 URL.createObjectURL 直接交给 ，销毁时再撤销。

- 遮罩层以前只在 requestFullscreen() 完成后才挂载，Chromium 的全屏动画会挡在用户面前。现在先显示冻结画面，窗口在它背后展开（fullscreenchange 时重新执行 measure()）。
- 暗色区域以前是四个分别定位的半透明矩形，每次指针移动都重绘。现在改成在选区框自身上展开一个 box-shadow: 0 0 0 100vmax，八个手柄作为 CSS 定位的子元素，于是每帧的全部开销就是单个元素的几何变化。
- 以前每次指针移动都调用 getBoundingClientRect()（强制布局）。遮罩层是 position: fixed; inset: 0，视口坐标本来就是图层坐标。

还有一项开销只在确认之后才显现，表现为图片出现在输入框之前的延迟：

- 裁剪以前在浏览器里跑——把四百万像素的画面 drawImage 进 canvas，再 canvas.toBlob('image/png')——两件事都在渲染器主线程上，和输入框重绘、窗口退出全屏挤在一起。像素本来就在磁盘上，于是裁剪挪到了那里：常驻助手用 GDI+ 切出矩形，再把 PNG 流式传回。附加从来不是慢的那一环；输入框只创建一个对象 URL，把字节推迟到发送时再取。

配置

无需配置。插件不注册 Config schema，也不读取工作区之外的文件。

目录结构

dsh-screenshot/
├── index.js # Host half: helper lifecycle + capture route
├── client.js # Client half: camera button + selection overlay
├── scripts/capture.ps1 # Resident PowerShell helper (WinForms + GDI+)
├── cordis.patch.yml # Bundle patch declaring the plugin row
├── locale/{en,zh}.json # Plugin manager title/description
├── icon.svg # Plugin artwork
├── package.json # dsh.bundle + dsh.client manifest
└── LICENSE

说明与限制

- 仅限 Windows。 Host 部分没有 macOS 或 Linux 的截图后端，所以在这些平台上路由会返回错误。
- 单屏，整个桌面。 多显示器环境按一个虚拟桌面截图；选区框横跨所有屏幕。
- 独立的 PowerShell 控制台即使隐藏，也可能仍出现在画面里，取决于其宿主如何渲染。
- 隐藏应用窗口会短暂改变焦点；截图结束后立即恢复之前的前台窗口。

安全

- 截图路由要求应用的身份验证 cookie，且只做精确匹配。
- 截图在内存中处理，作为附件交给输入框；助手的临时 PNG 一读完就删除。
- 不发起网络请求，不内置密钥，不依赖外部服务。

许可证

MIT