dsh-screenshot

给 DeepSeek Harness（DSH）的 Web 输入框加一个「截图」按钮：点一下 → 遮罩框选（或先隐藏 DSH 窗口再截）→ 确认后裁剪好的截图直接出现在输入框的附件栏里，回车就能发。

从 0.2 起，截图走 DSH 自己的草稿附件通道：图片会作为真正的图片附件随消息发送，模型直接看到图；不再往草稿里塞 截图：<路径>，也不再需要 vision MCP。对不支持图片的模型，可以在菜单里切到「以文件路径发送」。

界面示意（演示数据）：遮罩框选后点「确定」，截图会进入输入框的附件栏。

功能

• 三种截法：截取屏幕区域 / 隐藏 DSH 窗口后截图 / 截取全部屏幕（多显示器）
• 微信式框选：全屏遮罩、拖拽选区、实时显示物理像素尺寸，支持「全选 / 取消 / 确定」、Enter 确认、Esc 取消
• 服务端裁剪：Host 用 PowerShell 裁图，浏览器只上报显示坐标和画布尺寸；用 PNG 真实宽高换算物理像素，不受浏览器缩放、系统 DPI、CSS 影响
• 原生附件：裁剪结果交给 ctx.conversation.createDrafts + inputActions.addAttachments，由 DSH 渲染附件卡、发送图片字节
• 失败可见：截图失败、输入框正忙、附件过大都会 toast 提示，不再静默吞掉
• 崩溃自恢复：隐藏窗口模式在被强杀后会由 Host 依据 .hwnd 标记把窗口恢复回来
• 取消/发送后自动清理临时文件，超过 30 分钟的残留由后台清扫

安装

从 GitHub 安装

先确认你用的是哪个 profile：桌面端是 desktop，dsh web 命令行一般是 web。

# 桌面端
dsh plugin --profile desktop add github:XEsx630/dsh-screenshot

# 或 dsh web
dsh plugin --profile web add github:XEsx630/dsh-screenshot

# 指定版本
dsh plugin --profile desktop add "github:XEsx630/dsh-screenshot#v0.2.0"

dsh.bundle 清单会自动把插件挂进 profile。重启 DSH 并刷新页面。

本地开发安装

dsh plugin --profile desktop add link:E:/path/to/dsh-screenshot
# 然后在 ~/.dsh/profiles/desktop 里 pnpm install，重启

使用

1. 点输入框左侧的「📷 截图」，选一种截法
2. 等遮罩里的画面加载完，按住左键拖出一个区域
3. 点「确定」（或按 Enter）→ 截图进入输入框上方的附件栏
4. 继续打字或直接发送；不想发了就在附件卡上点 ×

菜单底部可以切换发送方式：

架构

┌─ 浏览器 ─────────────────────────────────────────────┐
│ 截图按钮 ──POST /capture──▶ 截图预览（GET /preview）   │
│    │                            │                    │
│    └── 遮罩拖拽（只算坐标）      │                    │
│         └──POST /crop {rect, stage}──▶ 裁剪好的 PNG    │
│                                        │             │
│ 取回 Blob ──▶ new File ──▶ createDrafts + addAttachments
└────────────────────────────────────────┼─────────────┘
                                         ▼
                              输入框附件栏（DSH 原生）

Host 侧：

1. screenshot.ps1 抓屏（可选先隐藏前台窗口，DPI 感知），写临时 PNG
2. 浏览器显示预览、拖拽选区
3. crop.ps1 按 PNG 真实尺寸换算后的物理像素裁剪
4. 裁剪结果通过 GET /file 交给浏览器，随后删除

设计取舍：

• 裁剪放服务端：浏览器只做显示和坐标换算，避免 canvas 解码时序、naturalWidth=0、CSS 缩放带来的 1×1 空图
• 坐标换算以 PNG 真实尺寸为准：物理 = 显示坐标 × (PNG 宽 / 画布宽)，浏览器缩放和 DPI 缩放都被吸收
• 图片字节走附件通道：不再依赖 $DSH_HOME/uploads 路径，也不需要把路径塞进 prompt
• 隐藏窗口有崩溃兜底：screenshot.ps1 隐藏前写 <png>.hwnd 标记，正常路径删除；进程被强杀时 Host 读标记调 restore.ps1 恢复

HTTP API（Host）

所有接口仅限本机回环地址，且要求同源。

安全

• 路由只接受回环 Host（127.0.0.0/8、localhost、::1），拒绝 sec-fetch-site: cross-site 和跨源 Origin
• id 必须是 UUID，文件名由 Host 生成，不接受外部路径
• 请求体上限 16 KB；响应 no-store、nosniff
• 截图和裁剪全部在本机 PowerShell 中完成，不上传任何数据
• 临时文件目录：$DSH_HOME/cache/dsh-screenshot（可用 DSH_SCREENSHOT_DIR 重定向），30 分钟 TTL

兼容性

• DSH ≥ 0.2（依赖 ctx.conversation.createDrafts / inputActions.addAttachments 与 fileUpload 服务）
• Windows：PowerShell 5.1 + .NET Framework 的 System.Drawing / System.Windows.Forms
• 客户端注入 @deepseek-ai/dsh-client-runtime、dsh-client-ui-conversation、dsh-client-file-upload

开发

node --test            # 单元测试 + PowerShell 裁剪测试
npm run check          # 语法检查

# 真实抓屏测试（会截当前屏幕）
$env:DSH_SCREENSHOT_LIVE=1; node --test test/powershell.test.js

测试覆盖：坐标换算/边界钳制、PNG 头解析、信任栅栏、路由校验与错误码、crop.ps1 的真实裁剪与越界拒绝。CI 在 windows-latest 上跑 Node 22/24。

故障排查

License

MIT