前言¶
在 DeepSeek Harness 里做「电脑使用」类工作流时，常见做法是依赖 xdotool、uinput 或 X11 路径去点按、截图。纯 Wayland 会话里，这些手段往往只影响 XWayland 区域，或每一步都要重新拉起会话，延迟和可靠性都不理想。下面介绍维护者 Ganglith 发布的 dsh-wayland-use：分类为工作流，通过 Mutter 的 RemoteDesktop 与 ScreenCast 两条 D-Bus 会话读写桌面，在 GNOME/Mutter 环境下做截图、带坐标的 OCR、按文字点击和批量动作。
这是什么¶
dsh-wayland-use 是 DeepSeek Harness 的 Wayland 原生桌面控制插件（版本 0.1.0，MIT 许可证）。不走 xdotool / uinput / X11，后端为常驻 Python 进程，Mutter 会话与 GStreamer 管道只建立一次（约 300ms），后续单步操作多在毫秒级。对外坐标统一为逻辑像素，与 OCR、wayland_windows 列出的矩形同一套，可直接互用。
核心功能¶
插件通过 Cordis patch 暴露一组工具，概要如下。
| 工具 | 作用 |
|---|---|
wayland_screenshot |
截图；支持 region、scale、maxWidth |
wayland_read |
OCR 读出屏幕文字并带坐标；可用 contains 过滤 |
wayland_windows |
列窗口标题、矩形与焦点（AT-SPI） |
wayland_act |
一次调用执行多步动作，只返回一张最终截图 |
wayland_click_text |
按文字查找并点击 |
wayland_key |
组合键，如 ctrl+a、super+Return |
wayland_launch |
启动程序 |
wayland_status |
自检；reset: true 可重建会话 |
wayland_act 的 step 支持：click、clickText、type、key、move、scroll、wait、waitText、launch、sleep，每步可带 settleMs。README 建议能用批量就不要逐步调用，以减少往返。
相对「每步重建会话」的实现，README 给出了一组参考耗时：wayland_status 约 0.1ms；首次 wayland_screenshot 约 230ms，之后取缓存帧约 2ms；wayland_key 约 1–2ms；含 OCR 的 wayland_click_text 约 170–190ms；wayland_act 三步加截图约 600ms。静止画面时 PipeWire 不出新帧，插件用动作时间戳与缓存帧配合，避免不必要的重抓。
OCR 默认并行 eng 与 chi_sim（可通过环境变量调整），找不到文字时会从 1 倍放大自动升到 2 倍。
安装与启用¶
官方安装命令如下。
dsh plugin add https://github.com/Ganglith/dsh-wayland-use
也可手动装进 profile（~/.dsh/profiles/<profile>/）：
- 将包放入
node_modules/dsh-wayland-use（或符号链接以便改源码立即生效） - 在
package.json的dependencies增加"dsh-wayland-use"，并在dsh.profile.bundles增加对应条目 - 在
cordis.patch.yml增加- id: wayland-use与name: dsh-wayland-use
DSH 的 HMR 会热载新 patch，一般无需重启。例外：lib/daemon.py 为子进程，修改后需执行 pkill -f "daemon[.]py"，下次调用时会自动重新拉起。
系统依赖包括：python3-gi（Gio/GLib/Gst/PIL）、gstreamer1.0-plugins-{base,good}、tesseract-ocr 与 tesseract-ocr-chi-sim（OCR 可选）。无 Node 侧依赖。
常用环境变量（节选）：
| 变量 | 默认 | 说明 |
|---|---|---|
DSH_WAYLAND_PYTHON |
/usr/bin/python3 |
需带 gi |
DSH_WAYLAND_JPEG_QUALITY |
75 |
截图 JPEG 质量 |
DSH_WAYLAND_OCR_LANGS |
eng,chi_sim |
OCR 并行语言 |
DSH_WAYLAND_OCR_BANDS |
8 |
OCR 横切条数 |
DSH_WAYLAND_OCR_UPSCALE |
1 |
默认放大；找不到会自动升到 2 |
后端 stderr 中带 ERROR/Traceback 的行会写入 $TMPDIR/dsh-wayland-<uid>/daemon.log。
典型用法思路¶
- 用
wayland_status确认会话与后端正常；异常时可reset: true重建。 - 需要 Agent 理解界面时，先
wayland_read或wayland_screenshot；OCR 框左上角文字 @x,y可直接作为wayland_act里click的逻辑坐标。 - 已知按钮文字时，可用
wayland_click_text或wayland_act里的clickText，避免手猜坐标。 - 多步操作（输入、按键、等待）尽量收成一次
wayland_act，减少截图往返。
README 还记录了实现层面的约束（如 ibus 下文本宜走剪贴板 + Ctrl+V、RemoteDesktop 与 ScreenCast 启动顺序等），集成复杂工作流前建议在仓库 README「几个坑」一节通读一遍。
适用场景与注意¶
适合在 GNOME/Mutter 纯 Wayland 环境下，为 DSH 智能体提供截图、读屏、点击与批量桌面动作；与依赖 X11 或每步冷启动后端的方案相比，README 强调常驻后端与批量 wayland_act 的延迟优势。
插件以当前 dsh 进程的用户权限运行，能访问的桌面与 D-Bus 能力与此一致。安装前请自行审阅 GitHub 源码 与 MIT 许可证；DSH 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
