前言¶
在 DSH 裏讓 Agent 操作帶界面的程序時，常見做法是直接在用戶 KDE / GNOME 桌面上啓動窗口。Wayland 會話下，非焦點窗口難以注入輸入、抓屏受限，自動化還會搶焦點、佔滿屏幕。若改用嵌在用戶桌面裏的可見窗口（例如 Xephyr），程序雖隔離，但用戶仍會看到額外窗口。
下面介紹維護者 jingyingruodi 的工作流插件 dsh-headless-display（GitHub：jingyingruodi/dsh-headless-display，社區目錄：SkillHub 插件頁）。它在獨立的虛擬 X display 裏運行並操作 GUI：默認桌面上零窗口、零干擾；需要時用 Web 面板或工具按需彈出真實窗口查看與操作。插件爲 Agent 提供 10 個工具（含環境自檢），並暴露 HTTP API（9 條 /gui-isolation/* 路由）與 Web 側邊欄實時畫面面板。當前 package 版本爲 1.4.0，許可證 MIT。
這是什麼¶
dsh-headless-display 是 DeepSeek Harness 的本地 bundle 插件，分類爲工作流。核心思路是另起一個與用戶會話無關的 X server（或 headless sway + Xwayland），自動化、抓屏、鍵鼠注入都在該 display 內完成；用戶主桌面默認不受影響。
名稱曾隨開發迭代多次變更（@local/isolated-display → @local/gui-isolation → dsh-isolated-x11 → dsh-headless-display），與 DSH 宿主按包名做進程級緩存、開發期需換包名才能加載新 JS 有關；GitHub 倉庫改名後舊鏈接會重定向。
靜默保證與後端選擇¶
桌面爲何不會多出窗口¶
插件文檔強調「靜默」由具體機制保證，而非口號：
- display 編號不再依賴易失效的 XAUTHORITY 探活，而按進程歸屬判定（例如 sway 後端只認與 sway 進程組關聯的 Xwayland），並拒絕等於用戶桌面 display 的編號；寫操作還要求存在本插件狀態文件（
allowForeignDisplays: true可放開外部 display）。 - Wayland 客戶端誤連桌面：僅刪除
WAYLAND_DISPLAY不夠，GTK 等仍可能連用戶合成器；iso_display_run默認把子進程釘到 X11（GDK_BACKEND=x11、QT_QPA_PLATFORM=xcb等，並清理 Wayland 相關變量）。若需 Wayland 原生客戶端，可配置exposeWaylandClients: true或爲env傳入隔離會話內 Wayland socket 的絕對路徑，代價是 xdotool 等 X11 注入對這類窗口無效。 - 音頻：隔離 display 不自動隔離聲卡；默認會爲每個 display 創建 PulseAudio/PipeWire null sink 並注入
PULSE_SINK，程序側音頻初始化正常且揚聲器無聲。創建虛擬 sink 可能短暫影響用戶默認輸出靜音，插件會嘗試恢復；配置audio: 'inherit'可恢復聲音外放。直接走 ALSA 的程序不會被 null sink 攔住。
三種後端¶
| 後端 | 用戶桌面是否有插件窗口 | DRI3 / GPU | 典型用途 |
|---|---|---|---|
sway（backend: auto 下若探測到 sway 則首選） |
否 | 有，Vulkan/GL 可走 GPU | Proton、DX12、3D 遊戲及 2D |
xvfb |
否 | 無（Vulkan 多退到 lavapipe） | 輕量 2D / 純 X11 |
xephyr |
是（可見窗口，會打擾用戶） | 無 | 需在桌面上直接看到嵌套窗口時 |
默認 backend: auto：有 sway 用 sway，否則退回 xvfb。3D 遊戲文檔建議必須用 sway：Xvfb/Xephyr 無 DRI3，部分 UE/Unity 遊戲在 Xvfb 下會直接異常。
想看畫面或親手操作時，不必換後端：面板 「打開真實窗口」 或工具 iso_display_popout 在本機迴環起 VNC（sway 用 wayvnc，xvfb/xephyr 用 x11vnc），查看器默認 gvncviewer，可通過 viewerPath 改爲 TigerVNC 的 vncviewer。
核心功能¶
- 10 個 Agent 工具：環境自檢（
iso_display_doctor）、啓停隔離 display、在 display 內執行命令、抓屏、列窗口、注入鍵鼠、彈出/收起真實窗口等（README「Agent 工具」章節有完整列表）。 - Web 側邊欄面板：實時畫面、點擊、文本/按鍵注入、窗口列表、真實窗口開關。
- HTTP API：9 條
/gui-isolation/*路由，供面板與外部腳本調用。 - 跨發行版：
iso_display_doctor按 Debian / Fedora / Arch 給出缺失依賴的安裝命令；路徑自動探測。 - 實現：純 JavaScript，無 npm 依賴與構建步驟。
安裝與啓用¶
插件以當前 DSH 進程的用戶與權限運行；安裝前請自行審閱倉庫源碼與 MIT 許可證。社區目錄頁星標數爲 0，不代表功能完備性，僅作公開指標參考。
系統依賴（Linux）¶
文檔建議裝好後先跑 iso_display_doctor，按輸出粘貼本機包管理器命令。Debian 系示例：
# sway 後端（auto 首選；3D / Proton 需要）
sudo apt install sway grim x11-utils xdotool imagemagick
# xvfb 退路 / 純 2D
sudo apt install xvfb
# 按需「打開真實窗口」
sudo apt install x11vnc wayvnc gvncviewer
# 可選：可見後端 xephyr
sudo apt install xserver-xephyr
command -v sway grim Xvfb Xwayland xdpyinfo xdotool import identify x11vnc wayvnc gvncviewer
使用 sway 且 GPU 不可用時，需確認用戶在 render 組並可訪問 /dev/dri/renderD*。
安裝插件 bundle¶
將倉庫目錄放到本機任意路徑後，在 DSH 中安裝該目錄 bundle（不要用未在文檔出現的 dsh plugin add github:... 拼接命令）：
plugin_manager(action: "install_bundle", target: "<本目錄的絕對路徑>")
確認已加載：
plugin_manager(action: "list_bundles")
列表中應出現 dsh-headless-display，rows 含 gui-isolation。
典型用法¶
- 環境自檢：調用
iso_display_doctor，按提示安裝缺失包；關注 audio 模式與 pactl 告警（缺 pactl 時隔離 display 內聲音可能仍從揚聲器輸出）。 - 啓動隔離 display：通過 Agent 工具或 HTTP API 啓動（具體參數見 README「配置」與「Agent 工具」）；默認 auto 後端在用戶桌面無窗口。
- 在 display 內跑 GUI：
iso_display_run執行命令；子進程默認走 X11 與 null sink，避免窗口與聲音泄漏到用戶會話。 - 觀察與干預：Web 面板看實時畫面並點擊/輸入；或
iso_display_popout彈出 VNC 真實窗口，關閉後程序無需重啓。 - 停止：
iso_display_stop卸載對應音頻 module 並釋放 display。
Proton / 遊戲場景可參考倉庫內 scripts/run-proton.sh 與 README 中 sway + DRI3 說明。
配置要點（節選）¶
完整字段以 README「配置」爲準。已文檔化的項包括：
backend：auto|sway|xvfb|xephyrallowForeignDisplays：是否允許對外部 display 寫操作exposeWaylandClients：是否在隔離環境暴露 Wayland 給原生 Wayland 客戶端audio：默認 null sink 靜默；'inherit'繼承用戶聲卡viewerPath：VNC 查看器路徑（如vncviewer）vncPortBase：與 GTK-VNC 地址localhost:<display號>計算有關
適用場景與限制¶
適合：需要在 Agent 工作流中穩定跑 X11/GTK/Qt/Electron 等 GUI、自動化點擊與抓屏，且不希望干擾用戶桌面；跑 Proton/3D 時可優先 sway 後端；需要時在面板里人工接管。
注意：
- 插件邏輯與宿主 DSH 同權限，僅隔離顯示與默認音頻路由，不替代安全審計。
- KDE Wayland 下 XWayland 彈出的 VNC 查看器可能無法自動置頂，需從任務欄切換。
- 純 Wayland 客戶端、直連 ALSA 的音頻路徑有文檔標明的盲點。
- 已知限制、故障排查、部署到其他設備見 GitHub README 對應章節。
結尾¶
dsh-headless-display 把 GUI 自動化放進隔離 headless display：默認零桌面窗口，面板與 VNC 按需可見可操作，並配套 10 個 Agent 工具與 HTTP API。DeepSeek Harness 生態強調「一切皆插件」；SkillHub 目錄 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
- 目錄頁：https://www.skillhub.cn/plugins/jingyingruodi/dsh-headless-display
- 源碼與文檔：https://github.com/jingyingruodi/dsh-headless-display
