Deskhand

Deskhand — 让 AI Agent 安全地使用你的 KDE 桌面

Türkçe: README.tr.md

Deskhand 让 AI Agent（Claude Code 和其他 MCP 客户端）安全地使用你的 KDE Plasma 桌面 ——可以在你的屏幕上操作，也可以在你看电影时使用不可见的第二桌面。

Agent 可以读取窗口、点击屏幕上可见的文字、输入内容并打开应用。每次输入都会根据当时屏幕上的实际内容进行检查。购买／付款按钮和付款页面会等待你的回答，回答通过 Agent 无法访问的对话框提交。只要你触碰鼠标，它就会立即停止；点击一次STOP即可停止所有操作。你忙碌时，任务会转到隐藏桌面上继续进行，并可复用你已登录的部分会话，因此不会打断你看电影或玩游戏。

这是为善意的 Agent 提供的安全防护层，而非沙箱（见威胁模型）。

_{截图使用示例数据生成。目前面板界面为土耳其语；计划推出英文界面。}

功能

安全防护层

这些规则由工具本身强制执行，适用于两个桌面，不受 Agent 或其权限模式的影响：

• 禁止操作的窗口。 标题或类名与 ~/.config/deskhand/yasak-pencereler.txt 中某个模式匹配的窗口永远不会接收输入，其应用也永远不会启动（例如规则禁止自动化操作的在线游戏，或密码管理器）。 通过 MCP 操作时，这些窗口也会在截图中被遮挡，并从 OCR 结果中排除。
• 敏感按钮和付款页面需要人工确认。 对购买、付款、下单、授权、允许、删除账户（包括土耳其语和英语措辞）的操作，以及在标题看起来像结账／付款页面上的任何点击或 Enter 操作，都会触发 Deskhand 面板中的审批对话框： Allow once 或 Deny，并附有目标的小图。只有面板可以提交回答；对话框本身属于禁止操作的窗口，因此 Agent 无法点击它。没有回答、超时或面板未运行，均视为拒绝。
• 窗口／标签页标题锁定。 使用 -b PATTERN（CLI）或窗口模式（MCP）时，每次输入前都会重新检查标题。如果浏览器切换了标签页，输入会在单词中途停止。
• 人工优先。 如果你正在使用鼠标或键盘（通过 Wayland 空闲通知，无需额外权限），Deskhand 会等待 1.5 s 的空闲时间，最多等待 8 s，然后放弃操作。你一触碰任何设备，它按住的键就会立即释放。
• STOP 开关。 可通过面板按钮、托盘菜单或可选的全局快捷键启用。启用后，不会发送任何输入，并会释放所有按住的键。Agent 可以自行启用 STOP，但无法解除你启用的 STOP；只有面板可以解除。
• 活动日志。 每次输入都会记录在 ~/.local/state/deskhand 中（保留 7 天），并实时显示在面板中。

后台桌面

deskhand desktop start 会启动一个不可见的桌面：Xvfb + openbox，默认分辨率为 1920×1080，并与你的会话隔离。

• 不会有任何内容传到你这里。 输入不会发送到你的屏幕（后台后端只能与自己的 X 显示屏交互）。其中的应用使用私有 D-Bus，因此通知会被捕获到日志中，而不会弹出；音频则会发送到静音接收端。Wayland 变量会被移除，避免应用将内容显示到你的屏幕上。
• 轻量。 采用低 CPU/IO 优先级和内存上限（systemd 作用域，默认 4 GB）。启动约需 0.2 s；空桌面约占用 30 MiB。
• 按应用执行会话策略。 某些应用可在后台以已登录状态打开：
  • Firefox： 对你的配置文件进行一致的、单向快照复制（Cookie、登录信息、任务相关网站的站点存储）。任何内容都不会写回。不会复制同步身份信息；银行、支付、政府网站（包括土耳其银行和 e-Devlet）以及中央登录页面（Google、Microsoft）的 Cookie 和已保存密码都不会复制，因此后台不会登录 Google/YouTube。摄像头、麦克风、位置和通知权限会从副本中移除。
  • 不使用密钥环的 Flatpak 应用（例如 Discord、Spotify）：快照复制。
  • 需要密钥环的应用（Chromium 系列、VS Code）以及会写入真实文件的应用（Obsidian 知识库）只会在你的屏幕上运行。
  • 与两个客户端同时运行会出问题的应用（Telegram、Signal、WhatsApp 封装应用、Element、Steam、Thunderbird 等）绝不会被克隆，也绝不会在后台启动：Agent 会收到等待你的指示。邮件/同步守护进程（KMail/Akonadi、Nextcloud）也绝不会启动。
  • 策略会针对解析后的应用进行匹配（桌面条目、可执行文件、Flatpak ID），因此无法通过更改名称或路径绕过；匹配多条规则时采用最严格的一条。密码管理器绝不会启动。
  • 只有在确定你没有运行某个未知应用时，才会正常启动它（否则其单实例锁可能会让窗口出现在你的屏幕上）；如果无法确定，Agent 会等待。策略文件：~/.config/deskhand/oturum.toml。
• 查看并接管。 面板会显示实时预览。接管会将你的鼠标和键盘输入发送到后台桌面，同时让 Agent 等待。

忙碌检测：“后台 / 我的屏幕 / 稍后”

deskhand busy 会以只读方式检查你是否正忙：是否有全屏窗口、正在播放的媒体播放器（MPRIS）、近期键盘/鼠标输入、游戏或禁止操作的窗口，以及屏幕是否锁定。

deskhand decide "task summary" 会据此作出决定。如果你不忙，结果为我的屏幕。如果你正忙，默认会弹出通知，询问你选择后台 / 我的屏幕 / 稍后（45 s 内未作答 = 后台）。如果你正在全屏观看电影或玩游戏，它不会打扰你，而是直接转到后台。以上设置均可在面板中配置。

按文本点击（优先使用 OCR）

Agent 会点击它能读到的内容，而不是猜测坐标：click-text <window> "Save"。Tesseract 可识别土耳其语和英语。如果有显卡，第二个识别器（GPU 上的 EasyOCR）也会自动加入：它能找到彩色网页按钮，以及 Tesseract 会漏掉的浅色或小号文本（实测：测试短语识别数为 55/55，而不是 49/55；每次识别约需 0.15 s）。它只会额外添加识别行；Tesseract 的识别结果会保留。你玩游戏或全屏观看内容时，它绝不会启动；空闲 5 分钟后会释放显存。土耳其语字母会进行宽松匹配（ş/s、ı/i 等），遇到匹配不明确时会停止，而不是猜测。还可使用：无障碍树（AT-SPI，按按钮名称点击）、已保存的图标模板、颜色区域，以及用于重复任务的屏幕识别流程。

MCP 服务（12 个工具）

deskhand mcp 是一个 stdio MCP 服务：get_status、choose_desktop、manage_desktop、 screenshot、read_text、find、click、type_text、press_key、scroll、open_app、 run_flow。截图会缩放至长边 1280 px。坐标会与 shot_id 核对，因此会拒绝在过期截图上执行点击。MCP 界面没有“已批准”标记：敏感操作始终通过面板进行。

监控面板和托盘

活动（实时日志、筛选）、后台桌面（预览、停止、接管）、审批（待处理 + 历史记录）、设置（忙碌时的行为、禁止的窗口、STOP 快捷键）、已保存的图标，以及所有依赖项的健康检查。托盘图标会显示空闲 / 正在你的屏幕上 / 在后台 / STOP；有审批等待时会显示徽标。

对比

这个领域有不少优秀项目；选择适合你的即可。

• agent-sh/agent-workspace-linux 是最接近的项目：支持六种后端的隐藏桌面（包括原生 KWin Wayland 虚拟合成器）、密钥环和 Chrome 配置文件导入、应用允许列表、实时查看器，以及 82 个工具。它的功能范围比 Deskhand 更广，也更具可移植性。
• ahmetadakli/kde-desktop-mcp 在 KDE 上采用了最接近的安全模型：带级别的应用允许列表、确认列表、密码字段保护、用户接管时暂停、停止快捷键。它通过辅助功能树运行。
• agent-sh/computer-use-linux（以 GNOME 为主，支持许多后端）、Samthesurf/kwin-mcp（KDE Wayland）、alex-oleshkevich/wayland-mcp（niri/wlroots、嵌套沙箱、本地 OCR）是其他可选方案。

Deskhand 将以下功能组合在一起，而我们尚未见到其他项目具备同样的组合：

1. 依据屏幕内容进行检查，而不只是依据应用：禁止的窗口、敏感按钮、支付页面检测、标题 / 类锁定。
2. 忙碌状态检测以及 后台 / 我的屏幕 / 稍后 循环。
3. 后台桌面的逐应用会话策略（复制 / 等待 / 从不），包括不得重复运行的应用。
4. 通过可见文本点击，支持土耳其语 OCR，即使没有辅助功能树也能使用。
5. Plasma 面板：托盘、STOP、实时预览、接管、仅由人工进行的审批。

它的功能范围也更小：仅支持 KDE Plasma、一个后台桌面，且后台桌面不使用 GPU。

要求

• 前台（你自己的屏幕）需要 KDE Plasma 6 on Wayland。后台桌面是一个 X 服务器（Xvfb），因此可运行仍支持 X11 的应用（大多数应用都支持）。
• Python 3.11+
• 前台：kdotool、dotool、spectacle，以及对 /dev/uinput 的访问权限
• 前后台均需：带有土耳其语和英语数据的 tesseract
• 后台：Xvfb、openbox、python-xlib；建议安装 xdotool、pactl（静音音频接收端；没有它，后台应用将完全没有音频）和 systemd-run（内存限制）
• Python 模块：PyQt6、python-xlib、numpy、scipy、pillow、jeepney、mcp ≥ 2.3
• 要构建小型键盘活动辅助工具：C 编译器、make、pkg-config、wayland（没有它，人类优先级监测只会监测鼠标）
• 如果使用 AMD 或 NVIDIA 显卡，要在 GPU 上进行文本识别：需要适用于你显卡的 PyTorch、torchvision、OpenCV、scikit-image、shapely、pyclipper，以及装有其模型（约 100 MB）的小型 venv。没有 GPU 则无需安装额外内容。install.sh 会检查所有这些依赖并打印相应命令
• 要构建截图辅助工具（KWin 的截图接口，每次截图约 8 ms）：需要上述相同工具以及 libsystemd（systemd 的一部分）。install.sh 会构建该工具并注册其桌面条目

Arch / CachyOS：

sudo pacman -S --needed spectacle tesseract tesseract-data-tur tesseract-data-eng \
    xorg-server-xvfb openbox xdotool libpulse python-pyqt6 python-xlib python-numpy \
    python-scipy python-pillow python-jeepney python-mcp base-devel wayland
paru -S kdotool-bin dotool        # AUR (or yay, or by hand)

# with a graphics card (NVIDIA: python-pytorch-opt-cuda instead of -rocm)
sudo pacman -S --needed python-pytorch-opt-rocm python-torchvision python-opencv \
    python-scikit-image python-shapely python-pyclipper
python3 -m venv --system-site-packages ~/.local/share/deskhand/ocr-venv
~/.local/share/deskhand/ocr-venv/bin/python -m pip install --no-deps easyocr python-bidi
cd ~/.local/src/deskhand && ~/.local/share/deskhand/ocr-venv/bin/python -m deskhand.ocr_gpu indir   # models

dotool 需要向 /dev/uinput 写入数据。其软件包会为 input 组安装 udev 规则，因此：

sudo usermod -aG input "$USER"                        # then log out and back in
sudo modprobe uinput                                  # if /dev/uinput does not exist
echo uinput | sudo tee /etc/modules-load.d/uinput.conf   # load it at boot

在 CachyOS (Arch) + KDE Plasma 6 上开发并测试。其他发行版使用相应的软件包应该也能运行，但未经测试。

安装

在任意位置克隆仓库，然后以普通用户身份（不要使用 sudo）运行安装程序：

git clone https://github.com/sobelendimm/deskhand.git ~/.local/src/deskhand
cd ~/.local/src/deskhand
./install.sh --dry-run    # see what it will do
./install.sh              # install (safe to re-run)

安装程序不会安装软件包。它会列出缺少的依赖并打印相应命令，随后构建活动辅助工具并安装：

• 将 deskhand 命令安装到 ~/.local/bin（指向此文件夹；如果移动文件夹，请重新运行 ./install.sh），
• 菜单条目和图标，
• 登录时自动启动面板（仅系统托盘），因为审批需要面板正在运行（使用 ./install.sh --no-autostart 可跳过）。

不会进行系统级安装。更新：git pull && ./install.sh。卸载：./uninstall.sh（保留设置、已保存的图标和工作流）或 ./uninstall.sh --purge。

快速入门

deskhand panel                          # monitoring panel + tray
deskhand busy                           # are you busy? (read-only)
deskhand windows firefox                # find windows: id | title | geometry
deskhand read firefox                   # read the window's text with coordinates (OCR)
deskhand -b "Example" click-text firefox "Sign in"     # click visible text, title locked
deskhand --background open firefox --site github.com   # signed-in Firefox on the invisible desktop
deskhand stop                           # STOP: no input from now on
deskhand resume                         # lift a STOP set from the CLI

速查表（运行 deskhand help 可查看所有内容）：

命令	含义
windows <pattern>	查找窗口
screenshot <window>	截图（指定窗口，或使用 ekran 截取整个屏幕）
read <window> [pattern]	读取文本和坐标（OCR）
click-text <window> <text>	点击可见文本
click <window> <x> <y>	点击窗口坐标
type <window> <text>	输入文本（--secret：不写入日志）
key <window> <keys>	按键或快捷键，例如 ctrl+s
scroll <window> [down|up]	滚动
wait <window> <text>	等待文本出现（--gone：等待其消失）
open <app> / open --command "CMD"	启动应用并等待其新窗口出现
tree / click-element	无障碍树 / 按名称点击元素
desktop start|stop|status	后台桌面
sessions status|policy|clear	后台桌面上已登录并打开的应用
busy · decide "<task>"	忙碌检查 · 决定在哪里工作
stop · resume · status	开启 STOP · 关闭 STOP · 显示状态
panel [--tepsi] · mcp	面板（仅系统托盘）· MCP 服务

常用选项：-b/--title PATTERN 锁定标题，-s/--class PATTERN 锁定类，--background 在不可见桌面上运行，--on-my-screen 即使正在玩游戏或看电影，也在你的屏幕上操作 （仅在你明确同意时）。原有的土耳其语命令名（bul、metin、metne-tikla，等等）和 ekran 命令仍可作为别名使用。

与 Claude Code（MCP）配合使用

在 user 范围内注册两个条目（切勿使用 project 范围：桌面控制不应随仓库一同迁移）。Claude Code 权限规则无法匹配工具参数，因此通过服务名称区分桌面：

claude mcp add --scope user --transport stdio deskhand    -- ~/.local/bin/deskhand mcp
claude mcp add --scope user --transport stdio deskhand-bg -- ~/.local/bin/deskhand mcp --desktop background
claude mcp get deskhand        # inside a session: /mcp

名称	可访问范围	建议权限
deskhand	你的屏幕和后台桌面（默认 desktop=auto）	ask
deskhand-bg	仅限后台桌面（会拒绝前台请求）	权限可以设置得宽松一些

~/.claude/settings.json 示例：

{
  "permissions": {
    "allow": ["mcp__deskhand__get_status", "mcp__deskhand__read_text", "mcp__deskhand__find",
              "mcp__deskhand-bg__get_status", "mcp__deskhand-bg__read_text", "mcp__deskhand-bg__screenshot"],
    "ask":   ["mcp__deskhand__screenshot", "mcp__deskhand__click", "mcp__deskhand__type_text",
              "mcp__deskhand__press_key", "mcp__deskhand__scroll", "mcp__deskhand__open_app",
              "mcp__deskhand__run_flow", "mcp__deskhand__manage_desktop"]
  }
}

权限提示是第二层防护；Deskhand 自身的检查会在每种权限模式下运行。 前台运行时，服务需要 WAYLAND_DISPLAY、DBUS_SESSION_BUS_ADDRESS 和 XDG_RUNTIME_DIR；如果客户端以空环境启动服务，请通过 --env 传入这些变量。

典型会话：get_status →（忙碌？）choose_desktop → manage_desktop start → open_app → read_text → click(text="Save", verify=true) → type_text → read_text 检查 → manage_desktop stop。

Agent 使用模式（CLI）

先询问，然后在选定的桌面上运行每条命令：

deskhand decide "Save the invoice as PDF"
case $? in
    0)  WHERE="" ;;          # my screen
    20) WHERE="--background" ;;    # background desktop
    21) exit 0 ;;            # later: tell the user, do nothing now
esac
deskhand $WHERE open --command "okular ~/invoice.pdf"

Agent 规则：遇到退出代码 10、12、13、15 和 16 时停止并告知用户；点击前先读取，点击后进行验证；只有当用户在聊天中批准了该确切步骤时，才传入 --approved。否则，Deskhand 会在面板中询问用户。

配置

路径	内容
~/.config/deskhand/yasak-pencereler.txt	禁止访问的窗口（每行一个正则表达式，匹配标题或类名）
~/.config/deskhand/ayarlar.toml	忙碌时的行为（[karar]：ask / background / wait、超时、全屏时询问）
~/.config/deskhand/oturum.toml	后台桌面的逐应用会话策略（与默认值合并）
~/.local/share/deskhand/	已保存的图标（simgeler/）、工作流（akislar/）
~/.local/state/deskhand/	输入日志（保留 7 天）、捕获的后台通知
~/.cache/deskhand/	截图、OCR 缓存（保留 5 天）
$XDG_RUNTIME_DIR/deskhand/	STOP 开关、审批请求、后台桌面状态、会话副本（tmpfs，0700）

每个目录都可以通过 DESKHAND_CONFIG_DIR、DESKHAND_STATE_DIR、 DESKHAND_CACHE_DIR、DESKHAND_DATA_DIR、DESKHAND_RUNTIME_DIR 移动。其他变量： DESKHAND_HEDEF=on|arka|oto（默认桌面）、DESKHAND_SANAL_BOYUT=1920x1080（后台桌面大小）、DESKHAND_SANAL_BELLEK=4G（内存上限，0 = 关闭）。

退出代码

代码	含义
0	完成
1	用法错误
2	坐标位于窗口/屏幕之外
3	窗口未激活 / 另一个窗口位于前台
4	标题或类名锁定条件不匹配
5	匹配项过多（请提供 --sira N）
6	未找到文本
7	超时
8	窗口已关闭或已移动
9	必需的工具未运行（dotool、tesseract、Xvfb…）
10	窗口被禁止访问，或未经批准执行敏感操作
11	工作流进入错误屏幕
12	你正在使用计算机（人类优先）
13	STOP 已启用
14	后台桌面不可用
15	你正在玩游戏或观看视频：不会操作你的屏幕
16	无法在后台桌面打开应用（请在你的屏幕上打开，或该应用仅支持密钥环）
20 / 21	decide：后台 / 稍后（0 = 你的屏幕）

通过 MCP 使用时，同样的代码会以 [code] name: detail 错误形式显示。

已知限制

• 后台桌面没有 GPU。 Xvfb 使用软件渲染：WebGL、游戏和视频解码在此环境中运行缓慢。
• 仅支持 Wayland 的应用无法在后台运行（后台桌面使用 X11）。
• 需要密钥环的应用只能在前台运行。 Chromium 系浏览器、VS Code，以及任何将机密信息存储在 KWallet/Secret Service 中的应用，都无法在后台桌面上以已登录状态打开。
• 同一时间只能有一个后台桌面。
• Xvfb 暂无身份验证 cookie。 它只监听本地套接字，但其他本地用户仍可能连接。计划添加 -auth cookie。
• OCR 可能会误读。 遇到不明确的匹配时会停止而非猜测；点击可以验证，但小字或对比度低的文本可能会被误读或无法识别。完整的 read 列表中可能缺少单独的网页按钮；搜索其文本（read <window> "<text>"、click-text）会进行额外读取并找到它。
• 审批需要面板处于运行状态。 如果面板已关闭，所有敏感操作都会被拒绝。
• 前台功能需要在 Wayland 上运行 Plasma 6（kdotool + KWin 脚本）。
• 活动日志以土耳其语写入（面板会显示翻译后的内容）；消息、帮助信息和面板会采用你的系统语言（土耳其语或英语），也可以使用“设置”中选择的语言。

威胁模型

Deskhand 会保护你免受 Agent 的误操作和提示词注入（网页或文档指示 Agent 购买商品或删除账户）：Agent 没有任何工具或命令可以批准自己的请求，也无法解除你的 STOP。它不是沙箱：能够以你的用户身份运行任意 shell 命令的 Agent，可以编辑文件、关闭面板，或在没有 Deskhand 的情况下操作桌面。请通过客户端的权限提示来限制 shell 访问。

开发

for t in tests/test_*.py; do python3 "$t" || break; done

test_mantik、test_ocr、test_ocr_gpu、test_onay、test_oturum、test_entegrasyon、test_mesgul、test_guvenlik、 test_i18n 和 test_gui（无屏幕 Qt）无需屏幕（如果已安装 test_ocr_gpu，且你当前不在游戏中，它也会运行真实的 GPU 读取器）。test_sanal 和 test_mcp 会启动各自的后台桌面；屏幕上不会显示任何内容。

测试会将所有 Deskhand 目录重定向到临时文件夹，不会触碰你的真实配置。tests/ekranli/ 中的测试套件会操作你的真实屏幕；仅当你没有使用电脑时才运行：tests/ekranli/hepsi.sh 会运行全部测试（约 15 分钟；它会使用临时配置文件打开自己的 Firefox，不会使用你的 Firefox；--insansiz 会跳过需要你在审批对话框中点击的两个步骤）。参见 CONTRIBUTING.md。

许可证

GPL-3.0-or-later © 2026 sobelendimm.