前言¶

在 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 仓库改名后旧链接会重定向。

静默保证与后端选择¶

桌面为何不会多出窗口¶

插件文档强调「静默」由具体机制保证，而非口号：

1. display 编号不再依赖易失效的 XAUTHORITY 探活，而按进程归属判定（例如 sway 后端只认与 sway 进程组关联的 Xwayland），并拒绝等于用户桌面 display 的编号；写操作还要求存在本插件状态文件（allowForeignDisplays: true 可放开外部 display）。
2. Wayland 客户端误连桌面：仅删除 WAYLAND_DISPLAY 不够，GTK 等仍可能连用户合成器；iso_display_run 默认把子进程钉到 X11（GDK_BACKEND=x11、QT_QPA_PLATFORM=xcb 等，并清理 Wayland 相关变量）。若需 Wayland 原生客户端，可配置 exposeWaylandClients: true 或为 env 传入隔离会话内 Wayland socket 的绝对路径，代价是 xdotool 等 X11 注入对这类窗口无效。
3. 音频：隔离 display 不自动隔离声卡；默认会为每个 display 创建 PulseAudio/PipeWire null sink 并注入 PULSE_SINK，程序侧音频初始化正常且扬声器无声。创建虚拟 sink 可能短暂影响用户默认输出静音，插件会尝试恢复；配置 audio: 'inherit' 可恢复声音外放。直接走 ALSA 的程序不会被 null sink 拦住。

三种后端¶

默认 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。

典型用法¶

1. 环境自检：调用 iso_display_doctor，按提示安装缺失包；关注 audio 模式与 pactl 告警（缺 pactl 时隔离 display 内声音可能仍从扬声器输出）。
2. 启动隔离 display：通过 Agent 工具或 HTTP API 启动（具体参数见 README「配置」与「Agent 工具」）；默认 auto 后端在用户桌面无窗口。
3. 在 display 内跑 GUI：iso_display_run 执行命令；子进程默认走 X11 与 null sink，避免窗口与声音泄漏到用户会话。
4. 观察与干预：Web 面板看实时画面并点击/输入；或 iso_display_popout 弹出 VNC 真实窗口，关闭后程序无需重启。
5. 停止：iso_display_stop 卸载对应音频 module 并释放 display。

Proton / 游戏场景可参考仓库内 scripts/run-proton.sh 与 README 中 sway + DRI3 说明。

配置要点（节选）¶

完整字段以 README「配置」为准。已文档化的项包括：

• backend：auto | sway | xvfb | xephyr
• allowForeignDisplays：是否允许对外部 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