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：
- 页面先铺一层深色遮罩（「正在抓取屏幕…」）——这层遮罩不会进入截图，因为它出现时窗口已经藏起来了；
- Host 半边用 Win32
ShowWindow(SW_HIDE) 把本窗口藏起来，等桌面重绘（260ms + DwmFlush），再 CopyFromScreen 抓屏；
- 抓完立刻
ShowWindow(SW_SHOW) + SetForegroundWindow 把窗口还回来，然后才编码 PNG、回给页面；
- 页面拿到图，遮罩换成冻结的桌面画面，进入框选。
窗口是怎么找准的：从 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 会额外跑一次「只恢复窗口」的看门狗，避免窗口留在隐藏状态。
实现原理
浏览器页面本身没有权限抓桌面，所以拆成两半：
- 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。
- 浏览器半边（
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
