EasyTouch Automation Skill

该技能用于指导 AI 助手通过 et 命令执行桌面自动化任务。
适用于 CLI 调用和 MCP 集成场景，重点是稳定的操作流程与可复现命令。

何时使用

• 需要控制鼠标、键盘执行桌面操作
• 需要截图、取色、识别前台窗口状态
• 需要查询系统信息、进程、剪贴板
• 需要浏览器自动化，且操作是多步骤任务（启动 -> 导航 -> 点击/输入 -> 截图）

前置条件

• 已安装 EasyTouch，可执行文件可通过 et 调用
• 如使用浏览器能力，确保本机可启动 Playwright 浏览器
• skills 仓库仅提供文档，不内置二进制；需先安装程序本体（例如 easytouch-windows）

快速自检

et --version
et mouse_position
et screen_list

常用命令域

• 鼠标：mouse_move mouse_click mouse_scroll mouse_position
• 键盘：key_press type_text
• 屏幕：screenshot pixel_color screen_list
• 窗口：window_list window_find window_activate window_foreground
• 系统：os_info cpu_info memory_info disk_list process_list
• 剪贴板：clipboard_get_text clipboard_set_text clipboard_get_files
• 浏览器：browser_*

浏览器自动化操作手册（重点）

1) 执行模型（先理解这个）

• 所有浏览器动作都依赖 browserId
• browser_launch 只负责创建会话，不会替你完成后续业务步骤
• 当前实现通过后台 daemon 持有会话，所以命令结束后会话仍可复用
• 你必须显式管理会话：创建、使用、关闭

支持浏览器：

• chromium
• firefox
• webkit
• edge（内部使用 msedge 通道）

注意：通过 npm 安装 EasyTouch 时已内置 Playwright 运行能力，本技能不包含手动安装步骤。

2) 标准操作逻辑（AI 必须遵守）

每个浏览器任务按固定顺序执行：

1. 创建会话：browser_launch
2. 确认会话：browser_list，提取目标 browserId
3. 打开目标页：browser_navigate
4. 等待页面可交互：browser_wait_for
5. 执行交互：browser_click / browser_fill / browser_select / browser_upload
6. 验证结果：browser_get_text / browser_assert_text / browser_page_info
7. 留证据：browser_screenshot
8. 结束任务：browser_close

如果中途失败，不要直接重启所有步骤，优先：

• 先 browser_page_info 看当前 URL/标题
• 再 browser_wait_for 重试关键元素
• 仍失败才考虑关闭旧会话并重新 browser_launch

3) CLI 流程模板

# 创建会话
et browser_launch --browser edge --headless false

# 读取 browserId（以下示例假设为 browser_1）
et browser_list

# 导航
et browser_navigate --browser-id browser_1 --url "https://example.com"

# 等待并操作
et browser_wait_for --browser-id browser_1 --selector "input[name='q']" --state visible --timeout 15000
et browser_fill --browser-id browser_1 --selector "input[name='q']" --value "EasyTouch"
et browser_click --browser-id browser_1 --selector "button[type='submit']"

# 验证与截图
et browser_get_text --browser-id browser_1 --selector "body"
et browser_screenshot --browser-id browser_1 --output "./result.png" --full-page true

# 收尾
et browser_close --browser-id browser_1

4) MCP 命令映射（AI 调用重点）

CLI 参数名与 MCP 参数名不同，常用映射如下：

MCP 调用范式：

{
  "jsonrpc": "2.0",
  "id": "browser-1",
  "method": "tools/call",
  "params": {
    "name": "browser_launch",
    "arguments": {
      "browserType": "edge",
      "headless": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "browser-2",
  "method": "tools/call",
  "params": {
    "name": "browser_navigate",
    "arguments": {
      "browserId": "browser_1",
      "url": "https://example.com",
      "waitUntil": "load",
      "timeout": 30000
    }
  }
}

4.1) 截图文件路径规范（必须遵守）

AI 调用 browser_screenshot 时，必须显式传 outputPath，不要依赖默认路径。

原因：

• 不传 outputPath 时，截图会落到系统临时目录（Path.GetTempPath()）
• AI 往往不会在后续步骤自动定位临时目录，导致“找不到截图文件”

执行规则：

1. 每次截图都传明确路径
2. 优先使用当前任务可访问目录（如仓库下 artifacts/screenshots）
3. 截图后始终读取返回值里的 imagePath，后续一律用这个实际路径
4. 不要自行猜测文件位置，不要硬编码与返回值不一致的路径

CLI 示例：

et browser_screenshot --browser-id browser_1 --full-page true --output "./artifacts/screenshots/search-result.png"

MCP 示例：

{
  "jsonrpc": "2.0",
  "id": "browser-3",
  "method": "tools/call",
  "params": {
    "name": "browser_screenshot",
    "arguments": {
      "browserId": "browser_1",
      "fullPage": true,
      "outputPath": "E:\\workspace\\EasyTouch\\artifacts\\screenshots\\search-result.png",
      "type": "png"
    }
  }
}

收到响应后：

• 记录 data.imagePath
• 后续如果要读取/上传/展示截图，使用 data.imagePath，不要改写成其他路径

5) 选择器策略（提高成功率）

优先级建议：

1. 稳定属性选择器：[data-testid='xxx']、[name='xxx']
2. 语义化 CSS：form button[type='submit']
3. 文本选择：selectorType=text（仅在文案稳定时使用）
4. XPath：仅在复杂结构时兜底

每次点击/输入前，都先 browser_wait_for：

• state=visible 用于可见元素操作
• state=attached 用于只要求在 DOM 中存在的元素

6) 常见任务模板

登录流程模板：

1. browser_navigate 打开登录页
2. browser_wait_for 等待用户名框
3. browser_fill 填用户名/密码
4. browser_click 提交按钮
5. browser_wait_for 等待登录后标志元素
6. browser_screenshot 存证

搜索流程模板：

1. browser_wait_for 搜索框
2. browser_fill 关键词
3. browser_click 搜索按钮
4. browser_wait_for 结果列表
5. browser_get_text 读取前几条结果摘要

7) 会话与异常恢复

browser_list 为空：

• 先查 et browser_daemon_status
• 若 daemon 不在，重新 browser_launch

browserId 无效：

• 会话可能已关闭或 daemon 重启
• 重新创建会话，替换为新 browserId

页面跳转后元素找不到：

• 增大 browser_wait_for --timeout
• 改用更稳定的选择器
• 用 browser_page_info 确认是否跳到了预期页面

执行完成必须收尾：

• 单任务结束：browser_close --browser-id ...
• 需要彻底结束后台持久化：browser_daemon_stop

MCP 使用建议

如需供 AI 客户端长期调用，使用 MCP 模式：

et --mcp

示例配置：

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

参考文档

• 项目说明：README.md
• 技能文档：skills/SKILLS.md