读取桌面无障碍元素树（结构化文本），这是感知屏幕的首选方式，不要默认用 screenshot。返回紧凑文本树，每个可操作元素带 [ref] 编号，后续用 click(ref)/type_text(ref) 精确操作，无需估算坐标。scope=active_window 最省 token（默认）；找特定应用用 scope=app+app=名字关键词；整桌面用 scope=desktop（大，慎用）。interactive_only=true 只列可操作元素，进一步省 token。

按文本/角色/应用搜索可交互元素，返回候选列表（每个含 [ref]）。用 ref 配合 click/type_text 精确操作，避免坐标估算。text 为名字子串（如『保存』『是』），role 为角色子串（如 'push button'；注意 GTK 输入框的 role 是 'text' 而非 'entry'），app 限定应用名关键词。至少提供 text 或 role 之一。强烈建议带 app 或 text 限定：全桌面裸搜很慢，且遍历大型应用（浏览器/Electron）时有节点数熔断，结果可能不全。

按 ref 查看单个元素的详情：角色、名字、值、状态、屏幕矩形、可用 actions。在 click/type 前用它确认元素是否正确、有哪些可执行动作。

点击一个元素。优先传 ref（来自 get_ui_tree/find_element/get_screen_text）；也可传 text(+app) 现场匹配第一个元素。执行采用三级降级：①元素级 do_action（零坐标，首选）→ ②校准坐标点击（兜底）→ ③都失败则提示改用 screenshot。返回结果会标明实际生效的层级。坐标级点击会回报「落点证据」（落在哪扇窗、底下什么字、点后活动窗口）、一张点击前抓的准星小图（红十字 = 你刚才点的那个像素，未缩放、图上 1 像素 = 屏幕 1 像素），以及程序算好的偏差数值：最近文字块离落点多远；若你传了 expect（如 expect="保存"），还会直接给出「未命中，偏差 (+17,-42) 共45px，建议改点其中心 (517,258)」——按建议坐标重试即可，不必再截图估算。另有「点后界面变化」百分比作为命中参考（无变化 = 大概率点空）。preview=false 可关掉这套画面反馈（更省 token，代价是失去位置依据）。灰区应用（无元素树，如 SWT/自绘控件）可传裸坐标 x+y（屏幕绝对坐标，可先用 get_screen_text 读出坐标）直接坐标级点击，无需再借道 shell。

输入文本。若给 ref（文本框/输入区），优先用元素级 set_value（最稳，不受焦点影响）；否则/失败时降级为键盘注入（xdotool type）。clear_first=true 先全选删除原内容再输入。建议：先 click(ref) 聚焦目标输入框，再 type_text。键盘注入会回报输入后的活动窗口标题——焦点被别的应用抢走时一眼可见，不必再截图核对。

发送快捷键（全局键盘注入）。combo 形如 'ctrl+s'、'alt+F4'、'Return'、'Tab'、'ctrl+shift+t'。修饰键用 ctrl/alt/shift/super；常见别名（PageDown/Enter/Esc/方向键等）会自动归一为 xdotool keysym；键名不识别会明确报错而非静默无操作。会回报按键后的活动窗口标题（快捷键生效与否取决于焦点在谁身上）。

回看最近一次坐标点击的准星小图与结论（index=-1 最近，-2 上上次）。⭐ 什么时候用它：坐标点击之后界面没有预期反应（没弹窗、没跳转、没变化）时，先用它看清「刚才到底点在哪、程序算的偏差是多少、建议改点哪个坐标」，再据此修正重试；不要盲目重复点击（实测那是最容易把界面点花的做法），也不必重新截图重新估算。返回里含：落点坐标、当时程序算出的偏差与建议坐标、点后界面变化百分比。记录只保留本会话内最近 8 次坐标点击；元素级点击零坐标、不产生记录。

一次调用批量执行一串动作——省往返的关键工具。⭐ 使用判据：凡是下一步不依赖上一步结果的连续动作，一律一次提交；每多一次单独调用，就多一个「模型思考 + 读结果」的来回（实测每轮 30~70 秒，而工具本身只要零点几秒）。只有需要看结果做分支判断时才拆成多次调用。steps 每项含 op 字段：click{ref?,text?,role?,app?,button?,x?,y?} / type{text,ref?,clear_first?} / key{combo} / wait{title_contains?,window_id?,timeout?} / sleep{seconds} / list_windows{} / screenshot{region?,max_side?}。把 screenshot 放在最后一步，可以在同一次调用里拿到「这一串做完之后长什么样」，省掉单独截图的整个来回（确认类截图占实测截图的三分之二）。stop_on_error=true 时某步失败即停止后续。返回每步 ok/message 的 JSON；点击类步骤的 message 里带落点证据（落在哪扇窗、底下什么字、点后活动窗口），据此判断有没有点偏，不必再截图确认。

获取显示器布局：各屏幕名称、分辨率、在虚拟桌面中的偏移(x,y)、是否主屏，以及虚拟桌面总尺寸。多屏/坐标问题排查时先调它理解几何环境。返回 JSON 文本。

截图（灰区兜底，默认不要主动用）。仅当目标无元素树（自绘控件/游戏/视频/远程桌面）或 get_ui_tree/find_element 无法定位时才使用——它费 token。可传 region=[x,y,w,h] 裁剪感兴趣区域；max_side 控制降采样长边（默认1280，省 token）。inline=false 时不返回图像、只落盘并返回文件路径（更省 token/更快），适合只需存档或后续自行读取的场景。此时可用 save_path 指定落盘位置——已存在的文件不会被覆盖（会直接报错），需要改路径或留空让本工具自动存到临时目录（自动路径只保留最近 5 张、旧的会被回收，要长期留存必须显式传 save_path）。优先用 get_ui_tree + click(ref) 完成任务。

读取屏幕上的文字及其坐标，返回紧凑文本列表（每行 [ref] 文字 @ (x,y) 宽x高）。灰区应用（无元素树：SWT/Java、自绘控件、游戏、远程桌面）首选感知方式——它比 screenshot 省得多：你读文字就能定位，不需要看图、也不需要从图像里估算像素位置再换算回屏幕坐标（那正是灰区操作慢和点偏的主因）。拿到结果后可直接 click(x=..,y=..)，或 click(ref=N) 由服务端代点（避免抄错坐标）。scope='window'（默认）只识别当前活动窗口那块区域，23 秒；scope='screen' 整屏，文字密集时要 810 秒，非必要别用。也可传 region=[x,y,w,h] 自己指定区域。注意：坐标是快照，界面变化（切窗/弹新对话框）后请重新调用，不要复用旧 ref。⚠️ 已知限制：文字紧邻深色图标时那一行会识别失败（实测「确认删除该文件吗？」挨着问号图标时被认成乱码）。若发现某行文字明显不对，把 region 收窄到只含该文字的小块再调一次即可（可先用本次返回的该块 bbox 定位）。

一次列出当前可见窗口：[{id,title,pid,x,y,w,h,area}]，按面积降序（面积最大者通常是主窗口；未映射的孤儿窗/隐藏辅助窗已被过滤）。用于甄别同名窗、定位目标窗口 id，替代多次 shell 查询。返回 JSON 文本。

等待窗口标题满足条件（server 内部轮询，单次调用完成）。title_contains 忽略大小写；window_id 指定则只盯该窗口，否则盯活动窗口；超时返回超时提示。用于等页面加载/应用启动，替代外部反复轮询。

在目标 display 启动应用：isolated 模式即放进 Xephyr 沙箱（把应用放上虚拟屏的唯一正路，宿主桌面不受影响）；real 模式即普通启动。command 用 shlex 解析（如 'zenity --entry --title=T'、'gedit'），返回 {pid,command,display} 的 JSON。启动后配合 wait_window 等窗口出现，再 get_ui_tree/click 操作。