name: easytouch description: 跨平台系统自动化操作工具，支持 Windows、Linux、macOS。提供 CLI 命令行和 MCP 服务器两种使用方式，支持鼠标键盘控制、屏幕截图、窗口管理、系统信息查询等功能。

EasyTouch Skill

环境要求

使用 npm 安装时：Node.js >= 18（npm 安装场景）

直接从 Github Release 下载文件后添加环境变量。

安装方式

npm 安装

# 推荐：自动匹配当前平台
npm install -g @whuanle/easytouch

# Windows
npm install -g easytouch-windows

# Linux
npm install -g easytouch-linux

# macOS
npm install -g easytouch-macos

安装后命令入口：

et help

CLI 命令

核心命令

# 显示命令总览与参数格式
et help

# 显示当前运行时状态与主机平台信息
et status

# 列出各平台实现状态与能力模块
et platforms

# 显示 CLI/MCP 接口与能力映射概览
et interfaces

# 显示能力接入和运行时要求清单
et requirements

# 启动 MCP stdio 服务
et mcp-stdio

# 输出 MCP manifest（工具清单）JSON
et mcp-stdio --output json

自动化命令

默认命令执行输出结果内容为 json，如需直接输出文本可使用 -output text 指定。

系统信息

平台说明：

• Windows：全部可用。
• Linux：整体可用，system network-info 依赖 ip 命令。
• macOS：整体可用，信息主要来自 sysctl、vm_stat、ifconfig 等系统命令。

鼠标操作

平台说明：

• Windows：全部可用。
• Linux：依赖 xdotool，并要求运行在 X11 或 XWayland 会话中；Wayland 原生会话下可能被桌面环境限制。
• macOS：依赖系统 Accessibility 权限；未授权时鼠标读取和注入会失败。

参数说明：

• --x / --y：目标坐标（整数）
• --duration-ms：总移动时长（毫秒），默认 280
• --jitter-px：轨迹抖动幅度（像素），默认 3
• --step-delay-ms：每一步移动间隔（毫秒），默认 8
• --button：按键类型，left、right、middle
• --count：点击次数，默认 1
• --delta：滚动量，正负值分别代表不同方向

窗口与应用

平台说明：

• Windows：全部可用。
• Linux：window list、window foreground、window activate、window close 可用；window show、window minimize 依赖 xdotool，window maximize、window restore、window move 依赖 wmctrl 和兼容 EWMH 的窗口管理器。
• Linux：整体要求 X11 或 XWayland 会话，Wayland 原生会话下窗口句柄和控制能力可能受限。
• macOS：窗口控制依赖 Accessibility 和 Automation 权限；window show、window minimize、window maximize、window restore、window move、window close 通过 System Events 操作，若同一进程里有多个同名窗口，系统会按首个匹配窗口执行。

参数说明：

• --title：窗口标题关键字
• --match：匹配模式，contains 或 exact
• --include-hidden：包含隐藏窗口
• --pid：按进程 ID 过滤
• --handle：窗口句柄（非负整数）
• --x / --y：窗口目标位置
• --width / --height：窗口目标尺寸（可选，不传则保持原尺寸）
• --target：可执行路径、文件路径或 URI

剪贴板

平台说明：

• Windows：全部可用。
• Linux：依赖 wl-copy / wl-paste 或 xclip / xsel；缺少这些工具时，对应文本、文件、图片剪贴板能力不可用。
• macOS：文本剪贴板通过 pbcopy / pbpaste；文件和图片剪贴板通过 osascript / JXA 写入，若宿主进程缺少 Automation 权限可能失败。

参数说明：

• --text：要写入的文本内容
• --paths：多个文件路径，使用分号 ; 分隔
• --path：单个图片文件路径

键盘操作

平台说明：

• Windows：全部可用。
• Linux：依赖 xdotool，并要求运行在 X11 或 XWayland 会话中；Wayland 原生会话下键盘注入通常不稳定或被系统阻止。
• macOS：依赖 Accessibility 权限；keyboard ime-switch 的策略会映射到系统快捷键，是否真正切换输入法取决于系统当前输入源绑定。
• macOS：keyboard caps-lock 目前仅稳定支持 toggle，on / off 仍不保证可用。

参数说明：

• --key：按键名（如 enter、esc、f5）
• --keys：组合键（如 ctrl+c、ctrl+shift+s）
• --text：输入文本
• --key-delay-ms：模拟键位输入时每个按键之间的延迟
• --strategy：输入法切换快捷键策略
• --state：大小写状态，toggle、on、off
• --expect-title：执行粘贴前要求前台窗口标题匹配
• --match：标题匹配模式，contains 或 exact

屏幕与截图

平台说明：

• Windows：全部可用。
• Linux：screen displays 依赖 xrandr，screen capture 依赖 grim、gnome-screenshot、scrot 或 import 之一。
• Linux：screen capture --display-id 和 screen capture --window-handle 仍未实现，当前只保证整桌面截图。
• Linux：Wayland 原生会话下，截图和像素读取可能受桌面权限或会话类型限制。
• macOS：screen capture 依赖系统 screencapture 命令；若系统未授予屏幕录制权限，截图或像素读取会失败。
• macOS：支持 --display-id 与 --window-handle 定向截图，但前提是目标窗口仍存在于当前 CoreGraphics 快照中。

参数说明：

• --x / --y：像素坐标
• --path：截图输出路径，不传则使用默认路径
• --display-id：指定屏幕 ID（来自 screen displays）
• --window-handle：指定窗口句柄（来自 window list / window foreground）

# 默认：截取所有屏幕
screen capture --path ./captures/all.png

# 截取指定屏幕
screen capture --display-id 1 --path ./captures/display-1.png

# 截取指定窗口
screen capture --window-handle 0x001A09F2 --path ./captures/window.png

等待器

等待器用于“动作后确认状态”，避免脚本只执行动作却不验证结果。 典型用法：点击/输入/窗口切换之后，先等待目标条件成立，再继续下一步。 这样可以降低因为界面刷新延迟、窗口抢焦点、颜色尚未变化导致的误操作。

平台说明：

• Windows：全部可用。
• Linux：等待器本身可用，但会继承底层能力依赖；例如 wait activate 依赖 X11/XWayland 窗口焦点能力，wait clipboard 依赖剪贴板后端工具，wait pixel 依赖图形会话可读。
• macOS：等待器整体可用，但 wait activate、wait clipboard、wait pixel 等同样受系统权限和图形会话状态影响。

参数说明：

• --timeout-ms：最长等待时间（毫秒），超时会返回失败
• --match：文本匹配模式，contains 或 exact
• --foreground-only：仅匹配当前前台窗口（仅 wait window）
• --handle：目标窗口句柄（用于 wait activate）
• --expect-active：true 等待激活，false 等待失去激活
• --expect-text：剪贴板期望文本，不传则等待任意变化
• --name / --pid：进程名称或进程 ID
• --expect-running：期望进程是否存在，true 表示等待启动，false 表示等待退出

复杂参数组合示例：

# 标题精确匹配 + 只接受前台窗口
wait window --title "记事本" --match exact --foreground-only --timeout-ms 5000

# 监听窗口激活（句柄来自 window list）
wait activate --handle 0x001A09F2 --expect-active true --timeout-ms 5000

# 颜色等待（十六进制）
wait pixel --x 100 --y 200 --hex FFCC00 --timeout-ms 3000

# 进程退出等待
wait process --name "chrome" --expect-running false --match contains --timeout-ms 10000

注意事项

功能按照 Windows 设计，以上所有功能在 Windows 下均可用，Linux 和 macOS 已补齐大部分常用能力，但仍有平台依赖和少量限制，使用前需要先确认桌面会话、系统权限和命令行工具是否满足。

Linux：

• 鼠标、键盘、窗口控制依赖 xdotool，并要求运行在 X11 或 XWayland 会话里。
• window maximize、window restore、window move 依赖 wmctrl 和兼容 EWMH 的窗口管理器。
• 剪贴板文本/文件/图片依赖 wl-copy / wl-paste 或 xclip / xsel。
• screen displays 依赖 xrandr，screen capture 依赖 grim、gnome-screenshot、scrot 或 import 之一。
• system network-info 依赖 ip 命令。
• screen capture --display-id 和 screen capture --window-handle 在 Linux 仍未实现，当前只保证整桌面截图。
• Wayland 原生会话下，部分窗口句柄、键鼠注入、像素读取和窗口控制可能被桌面环境限制；X11/XWayland 兼容性更好。

macOS：

• 窗口控制、键盘输入、剪贴板文件/图片等自动化依赖系统的 Accessibility 和 Automation 授权；如果宿主进程没有权限，命令会失败。
• window show、window minimize、window maximize、window restore、window move、window close 通过 System Events 操作窗口；如果同一进程里有多个同名窗口，系统会按首个匹配窗口执行。
• keyboard ime-switch 在 macOS 下做了策略映射：win-space 对应 Command+Space，alt-shift 对应 Option+Space，ctrl-shift 对应 Control+Space。是否真正切换输入法，取决于系统当前输入源快捷键绑定。
• keyboard caps-lock 目前只支持 toggle；on / off 还不能稳定判断系统真实状态。

任务编排：

• 建议工作流：先观察，再动作，最后等待确认
  • 观察：window.find / window.foreground / screen.pixel-color
  • 动作：window.activate / keyboard.* / mouse.* / app.launch
  • 确认：wait.window / wait.focus / wait.pixel / wait.clipboard / wait.process
• 不要连续盲操作（点击、输入、窗口切换后应立即确认状态）
• 参数约定：
  • 匹配模式：contains|exact
  • handle：非负整数
  • x/y、delta：32 位有符号整数
  • wait 默认超时：timeout_ms=2000
  • wait_process：expect_running=true|false
• 高风险动作（鼠标/键盘/窗口激活/窗口关闭/剪贴板写）前后都应插入观察或等待
• Linux/macOS 的部分能力仍需以目标环境实测为准
• 失败时优先读取：failure.code / failure.message / failure.detail

MCP 接入

启动 MCP stdio 服务

et mcp-stdio

导出工具清单（manifest）

et mcp-stdio --output json

配置示例

优先在全局安装后执行 init，把真实原生 et 程序复制出来，再让 MCP 直接调用这个文件：

npm i -g @whuanle/easytouch
easytouch init

这一步会直接从包内复制当前主机对应的原生 et 文件。

生成后的默认路径：

• Windows：<npm root -g>/@whuanle/easytouch/et.exe
• Linux / macOS：<npm root -g>/@whuanle/easytouch/et

同时会刷新全局 et 命令。

也可以通过 --output 指定输出位置。

推荐配置：

{
  "mcpServers": {
    "easytouch": {
      "command": "et",
      "args": ["mcp-stdio"]
    }
  }
}

Windows 请把文件名写成 et.exe。Linux / macOS 写 et。

默认会把 et 生成到全局安装目录下的包目录里，并同步刷新全局 et 命令。也可以显式指定输出路径：

easytouch init --output <你想放置 et 的路径>

如果你直接安装的是平台包，初始化命令分别是 easytouch-windows init、easytouch-linux init、easytouch-macos init。

如果需要查看实际路径，可以执行 npm root -g 和 npm prefix -g。

如果宿主能正确处理 PATH，MCP 直接写 command: "et" 即可；否则改成 npm prefix -g 或 npm root -g 对应的实际路径。

如果 Windows 宿主报 LOCAL_PROCESS_ERROR，优先改用 init.js 生成的 et.exe；如果仍走 npm 命令，再检查这里是不是还写成了 npx。

语义元素树定位

当需要更稳定地点击控件时，可以先读取前台窗口的元素树，再按元素查找、等待、点击或 invoke：

et element tree --output json
et element find --name "确定" --control-type Button --output json
et wait element --name "保存" --control-type Button --timeout-ms 5000 --output json
et element click --element-id root/0/3 --output json
et element invoke --element-id root/0/3 --output json

element tree 返回 element_id、control_type、automation_id、class_name、framework_id、center、bounds、children 等字段，适合让模型先找元素再执行动作。

element find 支持按 element_id、name、automation_id、class_name、control_type、framework_id 查询元素。wait element 会轮询这些条件直到元素出现。element invoke 会走平台语义动作或中心点击回退。

平台要求：

• Windows：UI Automation + PowerShell。
• Linux：python3/python + pyatspi，点击回退还需要 xdotool。
• macOS：osascript + System Events，宿主需要 Accessibility / Automation 权限。