前言¶
在 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 / 幻方無官方從屬關係。
