前言¶
在 DeepSeek Harness（DSH）里和智能体协作时，经常需要把当前界面、报错弹窗或 Trajectory 里的状态发给模型。常见做法是系统截图工具截屏，再切回浏览器粘贴或拖进附件区，步骤多，还容易截错窗口。DSH 社区插件 dsh-quick-screenshot 把「截屏 → 进草稿」收成一次操作：由 Host 侧调用各平台截图能力生成 PNG，Client 侧把图片放进已挂载的 composer 草稿，或在没有输入框时写入剪贴板。
这是什么¶
dsh-quick-screenshot 是维护者 JackEngineer 发布的客户端类 DSH 插件（bundle id：screenshot）。它是一个自包含的 DSH bundle：Host 半部通过平台自带工具截取 DSH 窗口（或指定窗口、整屏），经一条带认证的 Fetch 路由提供 PNG；Client 半部以包内 ./client bundle 形式注入界面。
插件在 SkillHub 插件目录 可查；源码与说明见 GitHub 仓库。社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
界面入口与手势¶
插件在两个席位注册同一套相机控件：
| 席位 | 效果 |
|---|---|
shell.overlay |
全窗口悬浮相机按钮，任意页面可用（不限于已挂载 composer 的页面）；可拖动，锚点保存在 localStorage |
conversation.input.left |
composer 左侧工具行，紧邻 + |
捕获目标由手势区分：
| 手势 | 捕获目标 |
|---|---|
| 单击 | 标题包含 DeepSeek Harness 的最大可见窗口；找不到则用当前前台窗口 |
| Shift+单击 | 整块桌面（多显示器） |
| Alt+单击 | 当前前台窗口 |
Ctrl+Shift+S |
与单击相同，页面任意处可用 |
点击使用 mousedown 并阻止默认行为，不会抢走键盘焦点，光标位置不变。捕获过程中控件显示加载状态；成功且放入草稿时会短暂显示「已放入输入框」及像素尺寸；失败则显示 Host 返回的拒绝说明。完整手势与最近一次结果在 tooltip 中。
图片去向¶
已挂载 composer 时，Client 走与粘贴、拖放相同的路径：
POST /api/quick-screenshot返回 PNG 及元数据头。ctx.conversation.createDrafts(sessionId, [file])注册浏览器文件并得到 draft id。- 通过
inputActions的addAttachments(ids)写入附件轨；发送时随消息序列化。
未挂载 composer 时（插件页、Trajectory、设置等），同一次捕获写入系统剪贴板，结果气泡会说明；读者进入对话后再粘贴。若剪贴板写入失败，气泡会给出暂存在磁盘上的 PNG 路径。
当上述服务不可用，Client 会对 [data-composer-input="true"] 派发携带文件的合成 paste 事件，行为与手动粘贴一致。
Host 接口与捕获后端¶
GET /api/quick-screenshot 描述当前 Host 能力（supported、platform、tool、modes、directory 等）。POST /api/quick-screenshot 接受可选 JSON 体并返回 PNG：
{ "mode": "window", "titlePattern": "DeepSeek Harness", "maxDimension": 0 }
| 字段 | 含义 |
|---|---|
mode |
window（默认）、active 或 screen |
titlePattern |
window 模式下的窗口标题匹配，默认 DeepSeek Harness |
maxDimension |
最长边上限；0 表示保持原生尺寸 |
响应为 image/png，Cache-Control: no-store，并通过 X-Screenshot 头携带 percent-encoded 的 JSON 元数据（mode、method、window、width、height、bytes、path 等）。失败时返回 JSON，含稳定 code（如 CAPTURE_UNSUPPORTED、CAPTURE_TIMEOUT、CAPTURE_FAILED、METHOD_NOT_ALLOWED）及面向用户的 message。路由经 ctx.connection.fetch 注册，共享 /api 桥的 Host/Origin 校验与浏览器 cookie 认证。
各平台捕获工具（摘自 README）：
| 平台 | 工具 | 说明 |
|---|---|---|
| Windows | powershell.exe + System.Drawing |
优先 PrintWindow(PW_RENDERFULLCONTENT)；平坦结果时抬窗后从屏幕矩形回退；Per-monitor-v2 DPI |
| macOS | screencapture -x -o |
显示器级捕获；window/active 均解析为当前活动显示器 |
| Linux | gnome-screenshot、spectacle、grim、import、scrot 中首个可用 |
显示器级捕获 |
Windows 可用环境变量 DSH_SCREENSHOT_POWERSHELL 覆盖默认 shell（例如仅安装 PowerShell 7 时）。文件暂存于 <tmpdir>/dsh-screenshot/，目录仅保留最新 24 个文件；并发点击会排队，不会竞态。
安装与启用¶
从 GitHub 安装无需构建步骤。在 DSH Plugin Manager 中对本目录执行 install_bundle（本地路径），或用 pnpm 安装后写入 profile 的 dsh.profile.bundles 亦可。常用命令如下：
dsh plugin --profile web add github:JackEngineer/dsh-quick-screenshot
修改 Host 半部 lib/index.js 后需重启 DSH Host（Loader 会缓存 Node 模块）；lib/client.js 在 bundle 行切换时会按 mtime/ctime/size 从磁盘重读。
典型用法¶
- 安装并启用 bundle 后，在对话页使用 composer 左侧相机按钮，或拖动悬浮相机到顺手位置。
- 需要把当前 DSH 主窗口发给模型时：单击相机（或按
Ctrl+Shift+S），等待「已放入输入框」，直接发送或补充文字。 - 需要整屏或多显示器内容时：Shift+单击。
- 需要前台其他窗口时：Alt+单击。
- 在设置页等无 composer 的页面截图后，切换到对话页 粘贴 到输入框。
本地验证（离线，无需浏览器）：
node scripts/selftest.mjs # Host 路由与真实捕获
node scripts/client-smoke.mjs # Client bundle、控件与附件流
无桌面环境的 CI 可通过 DSH_SCREENSHOT_SKIP_CAPTURE=1 跳过真实捕获（仓库 .github/workflows/test.yml 采用此方式）。
适用场景与注意¶
适合经常在 DSH 内截主窗口、整屏或前台窗口，并立刻作为消息附件或剪贴板内容的开发者。Windows 上对被遮挡窗口的窗口模式相对友好；macOS / Linux 文档标明为显示器级捕获，与 Windows 窗口语义不完全一致。
README 列出的已知限制包括：窗口捕获不包含独立 popup 上的上下文菜单；PrintWindow 平坦回退到屏幕矩形时需要目标窗口置于前台。安装前请阅读源码与 MIT 许可证；插件以当前 DSH 进程权限调用系统截图工具，应自行评估环境与信任边界。
结尾¶
dsh-quick-screenshot 把 DSH 窗口（或屏幕、前台窗口）截图与 composer 草稿打通，减少切出浏览器的次数。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库。
