EasyTouch (et)

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

目前：

• Windows
• Linux
• MAC（目前缺少设备验证功能）

大家平时使用各类 AI 编程工具，写页面是不是经常碰到 AI 写的页面怎么也不满意，写出来跟设计稿差异很大，这是因为 AI 只能通过读写代码来改进代码，它看不到界面，不像人类有感官。

所以 EasyTouch 是给 AI 装上手和眼睛。

功能概览

提示：在 Linux 里，由于桌面环境差异很大，有些功能在某些桌面系统下可能不可用，详见 Linux 环境说明。

安装

# Windows
npm i easytouch-windows

# Linux
npm i easytouch-linux

# macOS
npm i easytouch-mac

或者从https://github.com/whuanle/EasyTouch/releases下载对应平台的可执行文件，并添加环境变量。

执行 et --help 命令测试是否正常工作：

PS E:\workspace\EasyTouch> et --help
EasyTouch Windows Automation Tool

Usage: et <command> [options]

Commands:
  mouse_move --x <n> --y <n> [--relative] [--duration <ms>]
  mouse_click [--button left|right|middle] [--double]
  mouse_position
  key_press --key <key>
  type_text --text <text> [--interval <ms>] [--human]
  screenshot [--output <path>] [--x <n>] [--y <n>] [--width <n>] [--height <n>]
  pixel_color --x <n> --y <n>
  window_list [--visible-only] [--filter <text>]
  window_find [--title <text>] [--class <name>] [--pid <n>]
  window_activate --title <text> | --handle <n>
  window_foreground
  os_info, cpu_info, memory_info, disk_list
  process_list [--filter <text>]
  clipboard_get_text, clipboard_set_text --text <text>

  help       Show this help
  version    Show version
{"success":true}

浏览器操作支持

支持浏览器：chromium / firefox / webkit / edge（edge 走 Chromium 通道 msedge）。

浏览器操作建议按会话流程执行：先启动，再获取 browserId，后续所有命令都使用该 browserId。

et browser_launch --browser edge --headless false
et browser_list
# 使用 browserId 执行后续命令
et browser_navigate --browser-id browser_1 --url "https://example.com"

作为 Skills 给 AI 使用

只需要执行命令安装 skills 即可。

npx skills add https://github.com/whuanle/EasyTouch

注：skills 里面不带脚本，需提前使用 npm i easytouch-windows 安装工具。

作为 MCP 工具使用

如果只是给 AI 工具使用，建议使用 skills 即可，配置 MCP 可能会麻烦一些。

在 Claude、Cursor 等工具中，配置 MCP 的方式都是大同小异，通过 npm/bun 等方式安装的 EasyTouch，程序文件在 $basedir/node_modules/easytouch-windows 下面，。

在配置文件中添加：

Windows

{
  "mcpServers": {
    "easytouch": {
      "command": "C:\\path\\to\\et.exe",
      "args": ["--mcp"]
    }
  }
}

NPM 安装方式

{
  "mcpServers": {
    "easytouch": {
      "command": "npx",
      "args": ["-y", "easytouch-windows", "--mcp"]
    }
  }
}

Linux / macOS

{
  "mcpServers": {
    "easytouch": {
      "command": "/path/to/et",
      "args": ["--mcp"]
    }
  }
}

CLI 命令参考

鼠标控制

# 移动鼠标（绝对坐标）
et mouse_move --x 100 --y 200

# 相对移动
t mouse_move --x 50 --y -30 --relative

# 平滑移动（500ms 动画）
et mouse_move --x 100 --y 200 --duration 500

# 左键单击（默认）
et mouse_click

# 右键双击
t mouse_click --button right --double

# 向上滚动3格
t mouse_scroll --amount 3

# 水平滚动
t mouse_scroll --amount 3 --horizontal

# 获取当前位置
t mouse_position

键盘控制

# 按下单个键
t key_press --key "enter"

# 组合键
t key_press --key "ctrl+c"
t key_press --key "alt+tab"
t key_press --key "win+d"

# 输入文本
t type_text --text "Hello World"

# 模拟人工打字（带随机间隔）
t type_text --text "Hello World" --human --interval 50

屏幕操作

# 全屏截图
t screenshot --output screenshot.png

# 区域截图
t screenshot --x 100 --y 100 --width 800 --height 600 --output region.png

# 获取像素颜色
t pixel_color --x 100 --y 200

# 列出显示器
t screen_list

窗口管理

# 列出可见窗口
t window_list

# 按标题过滤
t window_list --filter "Chrome"

# 查找窗口
t window_find --title "记事本"

# 激活窗口
t window_activate --title "记事本"

# 获取前台窗口
t window_foreground

系统信息

# 操作系统信息
et os_info

# CPU 信息
et cpu_info

# 内存信息
et memory_info

# 磁盘列表
et disk_list

# 进程列表
et process_list --filter "chrome"

# 锁定屏幕
et lock_screen

剪贴板

# 获取文本
et clipboard_get_text

# 设置文本
et clipboard_set_text --text "Hello World"

# 清空
et clipboard_clear

# 获取文件列表
et clipboard_get_files

浏览器控制

使用 et browser_launch --browser 命令启动浏览器后（匿名模式），使用 et browser_list 获取浏览器实例列表，之后可以使用不同的命令控制浏览器，最后可以自行关闭或使用 et browser_close 关闭浏览器。

# 列出浏览器实例
et browser_list

# 启动 Chromium（无头模式）
et browser_launch --browser chromium --headless

# 启动 Edge（有界面）
et browser_launch --browser edge --headless false

# 打开页面
et browser_navigate --browser-id <id> --url "https://example.com"

# 导航控制
et browser_go_back --browser-id <id>
et browser_go_forward --browser-id <id>
et browser_reload --browser-id <id>

# 点击元素
et browser_click --browser-id <id> --selector "#submit"

# 输入内容
et browser_fill --browser-id <id> --selector "input[name='q']" --value "EasyTouch"

# 滚动页面（按像素）
et browser_scroll --browser-id <id> --x 0 --y 800 --behavior smooth

# 下拉选择
et browser_select --browser-id <id> --selector "#city" --values "beijing"

# 文件上传（多个文件用逗号分隔）
et browser_upload --browser-id <id> --selector "input[type='file']" --files "a.txt,b.txt"

# 页面截图
et browser_screenshot --browser-id <id> --output page.png --full-page true

# 执行脚本
et browser_evaluate --browser-id <id> --script "document.title"

# 读取页面信息
et browser_page_info --browser-id <id>

# Cookie 管理
et browser_get_cookies --browser-id <id>
et browser_set_cookie --browser-id <id> --name token --value abc --domain example.com --path / --http-only true --secure true --same-site lax
et browser_clear_cookies --browser-id <id>

# 执行本地 JS/TS Playwright 测试脚本
et browser_run_script --script-path "./tests/example.spec.ts" --browser edge --headless true

# 透传 Playwright CLI 参数（CSV）
et browser_run_script --script-path "./tests/login.spec.ts" --browser chromium --extra-args "--reporter=list,--workers=1"

# 文本断言（自动化测试）
et browser_assert_text --browser-id <id> --selector "h1" --expected-text "Example Domain" --exact-match true

# 关闭浏览器
et browser_close --browser-id <id>

MCP Tools

更多 MCP 使用文档见 skills/SKILLS.md

平台说明

Windows

• 完全支持所有功能
• 部分功能可能需要管理员权限

Linux

• 官方验证环境：Ubuntu Desktop（22.04 / 24.04）
• 其他发行版和桌面环境为 best-effort，建议先用测试脚本验证
• 建议在图形界面环境中使用（优先 X11 会话）
• 有些功能可能需要 sudo 管理员权限

Linux 依赖可手动安装（Ubuntu）：

# 基础依赖（推荐）
sudo apt install xdotool xclip xsel imagemagick gnome-screenshot

# Wayland 补充依赖（按需）
sudo apt install ydotool wl-clipboard grim

安装后可执行脚本测试兼容性：

node scripts/test-easytouch.js --cli-only --verbose

macOS

• 需要授予辅助功能权限（系统设置 → 隐私与安全性 → 辅助功能）
• 截图功能需要屏幕录制权限

许可证

MIT License