dsh-qq-screenshot

给 DeepSeek Harness Web UI 加一个和 QQ / 微信截图一样的截图工具：按快捷键 → 框选区域 → 标注 → 复制到剪贴板（或存成 PNG）。

QQ-style screenshot for the DeepSeek Harness Web UI: press Ctrl+Alt+A, drag a region, annotate it, and copy the result to the clipboard — ready to paste into the chat.

特性

• Ctrl+Alt+A 全局唤起，输入框左侧也有截图按钮；不打断正在输入的内容。
• 框选 + 精调：8 个控制点缩放、拖动内部移动、方向键 1px 微调（Shift = 10px），角标实时显示物理像素尺寸。
• 六种标注：矩形、椭圆、箭头、画笔、文字、马赛克，5 种颜色；超出选区的笔画自动裁掉。
• 一键进对话：Enter 复制到剪贴板，回输入框 Ctrl+V 即可粘贴图片；也可另存 PNG。
• 截图瞬间隐藏 Harness 自己（Windows）：窗口藏起来再抓屏，画面里不会有 Harness 窗口；藏失败会自动改抓一张不带遮罩的图并提示。
• 截的是整个桌面：QQ、浏览器、别的软件都能截，和 QQ 截图的手感一致。

安装

需要 DeepSeek Harness Desktop（已在 0.2.1-rc.4 上验证）。

插件市场：打开「插件市场」→ 搜索 dsh-qq-screenshot → 安装。

DSH CLI：

dsh plugin --profile desktop add dsh-qq-screenshot

手动：在 profile 的 package.json 里加依赖并在 dsh.profile.bundles 里选中：

{
  "dsh": { "profile": { "bundles": ["dsh-qq-screenshot"] } },
  "dependencies": { "dsh-qq-screenshot": "^1.2.0" }
}

安装或升级后刷新页面（或重启 DSH）一次：这个插件有客户端半边，页面启动时才会加载。

用法

操作	说明
Ctrl + Alt + A	开始截图（全局，输入框有焦点时也可以）
输入框左侧的截图图标	同上，鼠标点也行
拖动鼠标	框选区域；松手后出现工具栏
拖动选框内部 / 8 个控制点	移动或改变选区（「移动 / 缩放选框」工具）
方向键（Shift = 10px）	微调选区位置
工具：矩形 / 椭圆 / 箭头 / 画笔 / 文字 / 马赛克	在选区内标注，超出选区的笔画会被裁掉
5 个颜色圆点	换标注颜色
Enter、双击 ✓、Ctrl + C	复制图片到剪贴板，随后在输入框 Ctrl + V 粘贴
Ctrl + S、保存按钮	另存为 PNG（有系统「另存为」对话框时优先用它）
Ctrl + Z	撤销上一步标注
Esc、右键、✕	退出截图
工具栏「眼睛」/ 设置 → 通用 →「截图时隐藏当前窗口」	开关「截图瞬间隐藏本窗口」，下次生效

截图时隐藏当前窗口（QQ 同款）

默认开启。开启后按 Ctrl+Alt+A：

1. 页面先铺一层深色遮罩（「正在抓取屏幕…」）——这层遮罩不会进入截图，因为它出现时窗口已经藏起来了；
2. Host 半边用 Win32 ShowWindow(SW_HIDE) 把本窗口藏起来，等桌面重绘（260ms + DwmFlush），再 CopyFromScreen 抓屏；
3. 抓完立刻 ShowWindow(SW_SHOW) + SetForegroundWindow 把窗口还回来，然后才编码 PNG、回给页面；
4. 页面拿到图，遮罩换成冻结的桌面画面，进入框选。

窗口是怎么找准的：从 PowerShell 进程往上遍历父进程（最多 8 层），从近到远逐层找「该进程里面积最大的可见顶层窗口」，找到就停——所以永远不会走到 explorer.exe。同时按窗口类排除 Progman / WorkerW / Shell_TrayWnd / Shell_SecondaryTrayWnd，避免把桌面或任务栏当成目标（桌面窗口比最大化窗口还大一点点，这是早期版本藏错窗口的原因）。

藏失败怎么办：Host 用 IsWindowVisible 复核，并通过响应头 x-dsh-window-hidden 告诉页面。没藏成功时页面先撤掉遮罩、等重绘，再重新抓一次（这次不藏窗口），最坏情况是「一张包含 Harness 窗口的普通截图」，而不是「黑屏 + 正在抓取屏幕」；底部会常驻一条红色提示。

• 隐藏窗口仅 Windows 生效（macOS / Linux 忽略该开关，仍直接抓屏）；
• 开启后一次抓屏约 1.6–2.2 秒；关闭时 0.5–1.2 秒；藏失败的补救路径约 2.5–3 秒；
• 抓屏过程抛异常时，Host 会额外跑一次「只恢复窗口」的看门狗，避免窗口留在隐藏状态。

实现原理

浏览器页面本身没有权限抓桌面，所以拆成两半：

1. Host 半边（index.js）在 http://127.0.0.1:<port>/plugins/dsh-qq-screenshot/capture.png 注册一个只有本机能访问的 HTTP 路由（精确路径优先于 /plugins 前缀路由），并用系统自带工具抓一次全屏：
   • Windows：powershell.exe + System.Drawing.CopyFromScreen（先做 Per-Monitor DPI 感知，多屏/缩放屏都按物理像素抓）；
   • macOS：screencapture -x -t png；
   • Linux：依次尝试 gnome-screenshot / spectacle / grim / import。
2. 浏览器半边（client.js）在 shell.overlay 里冻结这一帧，框选、标注，最后用 Canvas 按原始分辨率合成 PNG，写进剪贴板。

因为截的是整个桌面，所以别的软件都能截；抓屏时页面本身还没有画出内容（遮罩要等窗口藏起来后才出现），所以画面里不会出现工具自己。

兼容性与限制

• 宿主：DeepSeek Harness Desktop 0.2.1-rc.4（@deepseek-ai/dsh-* 0.2.1-rc.4），Node ^22.19 || >=24。
• 抓屏依赖本机桌面会话：若 Harness 跑在无桌面的服务器上，会报「截屏失败」并显示系统返回的原因。
• 剪贴板写图片需要页面处于聚焦状态；被拒绝时会提示原因，可改用「保存为 PNG」。
• 快捷键固定 Ctrl+Alt+A；如与其他软件冲突，可改 client.js 里的 onKeyDown。
• Host 半边会调用系统截屏工具（Windows 上是 PowerShell），这是抓桌面所必需的；除此之外不访问网络、不写其他文件。

开发与测试

node --check index.js          # Host half
node --check client.js         # Client half
npm test                       # 两个冒烟测试

• tests/client-smoke.mjs：用 stub loader + stub React 真实执行 factory 与 apply()，断言两个 slot 注册、样式/快捷键/locale effect 登记，并渲染覆盖层首帧（遮罩、正在抓取屏幕…、canvas、设置开关）。
• tests/host-smoke.mjs：挂载 Host 半边、真实调用注册的路由：?hide=1 时校验返回的是合法 PNG 且 x-dsh-window-hidden: 1，POST 返回 405，并可用 hide <png> 参数落盘肉眼确认。

License

MIT © 2026 SKY_3635