easytouch-macos 1.0.11

package/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,161 @@
+# EasyTouch
+
+跨平台系统自动化操作工具，支持 Windows、Linux、macOS。提供 CLI 命令行和 MCP 服务器两种使用方式，支持鼠标键盘控制、屏幕截图、窗口管理、系统信息查询等功能。
+
+目前：
+
+- [x] Windows
+
+- [x] Linux
+- [ ] MAC（目前缺少设备验证功能）
+
+大家平时使用各类 AI 编程工具，写页面是不是经常碰到 AI 写的页面怎么也不满意，写出来跟设计稿差异很大，这是因为 AI 只能通过读写代码来改进代码，它看不到界面，不像人类有感官。
+
+所以 EasyTouch 是给 AI 装上手和眼睛。
+
+
+
+**你能用它做什么？**
+
+- 系统信息：系统、CPU、内存、磁盘、进程
+- 屏幕能力：显示器枚举、像素取色、截图
+- 窗口控制：枚举、查找、激活、关闭、前台窗口读取
+- 输入控制：鼠标移动/点击/滚轮，键盘按键/组合键/输入/粘贴
+- 剪贴板：读文本、写文本、读文件列表
+- 等待器：等待窗口、焦点、像素、剪贴板、进程状态
+- 应用启动：按路径或 URI 启动目标
+
+
+
+### 安装
+
+按照操作系统安装，安装命令：
+
+```
+# Windows
+npm i  -g easytouch-windows
+
+# Linux
+npm i  -g easytouch-linux
+
+# macOS
+npm i -g easytouch-mac
+```
+
+
+
+### 使用示例
+
+
+
+
+
+### 作为 Skills 给 AI 使用
+
+只需要执行命令安装 skills 即可。
+
+```bash
+npx skills add https://github.com/whuanle/EasyTouch
+```
+
+
+
+注：skills 里面不带脚本，需提前使用 `npm i easytouch-windows` 安装工具。
+
+![image-20260224090411080](images/image-20260224090411080.png)
+
+
+
+### 作为 MCP 工具使用
+
+如果只是给 AI 工具使用，建议使用 skills 即可，配置 MCP 可能会麻烦一些。
+
+在 Claude、Cursor 等工具中，配置 MCP 的方式都是大同小异，通过 npm/bun 等方式安装的 EasyTouch，程序文件在 `$basedir/node_modules/easytouch-windows` 下面，。
+
+
+
+在配置文件中添加：
+
+**Windows**
+
+```json
+{
+  "mcpServers": {
+    "easytouch": {
+      "command": "C:\\path\\to\\et.exe",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+**NPM 安装方式**
+
+```json
+{
+  "mcpServers": {
+    "easytouch": {
+      "command": "npx",
+      "args": ["-y", "easytouch-windows", "--mcp"]
+    }
+  }
+}
+```
+
+**Linux / macOS**
+
+```json
+{
+  "mcpServers": {
+    "easytouch": {
+      "command": "/path/to/et",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+
+
+
+
+### 平台说明
+
+Windows
+
+- 完全支持所有功能
+- 部分功能可能需要管理员权限
+
+Linux
+
+- 官方验证环境：Ubuntu Desktop（22.04 / 24.04）
+- 其他发行版和桌面环境为 best-effort，建议先用测试脚本验证
+- 建议在图形界面环境中使用（优先 X11 会话）
+- 有些功能可能需要 sudo 管理员权限
+
+Linux 依赖可手动安装（Ubuntu）：
+
+```bash
+# 基础依赖（推荐）
+sudo apt install xdotool xclip xsel imagemagick gnome-screenshot
+
+# Wayland 补充依赖（按需）
+sudo apt install ydotool wl-clipboard grim
+```
+
+安装后可执行脚本测试兼容性：
+
+```bash
+node scripts/test-easytouch.js --cli-only --verbose
+```
+
+macOS
+
+- 需要授予辅助功能权限（系统设置 → 隐私与安全性 → 辅助功能）
+- 截图功能需要屏幕录制权限
+
+
+
+## 许可证
+
+MIT License

package/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: easytouch
+description: EasyTouch Skill 接入文档（CLI + MCP）。
+---
+
+# EasyTouch Skill
+
+## 环境要求
+
+使用 npm 安装时：Node.js >= 18（npm 安装场景）
+
+>  直接从 Github Release 下载文件后添加环境变量。
+
+
+
+## 安装方式
+
+### npm 安装
+
+```bash
+npm install easytouch
+```
+
+安装后命令入口：
+
+```bash
+et help
+```
+
+
+
+## CLI 命令
+
+### 核心命令
+
+```bash
+# 显示命令总览与参数格式
+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` 指定。
+
+
+
+#### 系统信息
+
+| 命令 | 用途 |
+| --- | --- |
+| `system os-info` | 读取操作系统版本、架构、主机名等信息 |
+| `system cpu-info` | 读取 CPU 架构与核心信息 |
+| `system memory-info` | 读取内存总量、可用量与占用情况 |
+| `system disk-list` | 列出磁盘与容量信息 |
+| `system process-list` | 列出当前进程列表 |
+| `system hardware-info` | 读取硬件概览（架构、核心、页大小、物理内存、虚拟内存、机器名） |
+| `system network-info` | 读取网络适配器信息（IPv4、MAC、网卡类型、DHCP 状态） |
+
+平台说明：
+
+- Windows：全部可用。
+- Linux：整体可用，`system network-info` 依赖 `ip` 命令。
+- macOS：整体可用，信息主要来自 `sysctl`、`vm_stat`、`ifconfig` 等系统命令。
+
+
+
+#### 鼠标操作
+
+| 命令 | 用途 |
+| --- | --- |
+| `mouse position` | 读取当前鼠标坐标 |
+| `mouse move --x <x> --y <y> [--duration-ms <ms>] [--jitter-px <px>] [--step-delay-ms <ms>]` | 以渐进轨迹移动鼠标，支持抖动与延迟，更接近人类操作 |
+| `mouse click [--button <left\|right\|middle>] [--count <n>]` | 执行鼠标点击 |
+| `mouse scroll --delta <amount>` | 执行鼠标滚轮滚动 |
+
+平台说明：
+
+- 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`：滚动量，正负值分别代表不同方向
+
+
+
+#### 窗口与应用
+
+| 命令 | 用途 |
+| --- | --- |
+| `window list [--include-hidden] [--pid <pid>]` | 列出窗口，可按可见性和进程过滤 |
+| `window foreground` | 读取当前前台窗口信息 |
+| `window find --title <text> [--match <contains\|exact>] [--include-hidden] [--pid <pid>]` | 按标题查找窗口 |
+| `window activate --handle <handle>` | 按句柄激活窗口 |
+| `window show --handle <handle>` | 显示窗口并请求激活 |
+| `window minimize --handle <handle>` | 最小化窗口 |
+| `window maximize --handle <handle>` | 最大化窗口 |
+| `window restore --handle <handle>` | 恢复窗口（从最小化/最大化） |
+| `window move --handle <handle> --x <x> --y <y> [--width <n>] [--height <n>]` | 拖曳/移动窗口到指定坐标，可选调整尺寸 |
+| `window close --handle <handle>` | 按句柄请求关闭窗口 |
+| `app launch --target <path-or-uri>` | 启动应用、打开文件或 URI |
+
+平台说明：
+
+- 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
+
+
+
+#### 剪贴板
+
+| 命令 | 用途 |
+| --- | --- |
+| `clipboard get-text` | 读取剪贴板文本 |
+| `clipboard set-text --text <value>` | 写入剪贴板文本 |
+| `clipboard get-files` | 读取剪贴板中的文件列表 |
+| `clipboard set-files --paths <path1;path2;...>` | 写入剪贴板文件列表（用于后续粘贴文件） |
+| `clipboard set-image --path <image-file>` | 写入剪贴板图片（用于后续粘贴图片） |
+
+平台说明：
+
+- Windows：全部可用。
+- Linux：依赖 `wl-copy` / `wl-paste` 或 `xclip` / `xsel`；缺少这些工具时，对应文本、文件、图片剪贴板能力不可用。
+- macOS：文本剪贴板通过 `pbcopy` / `pbpaste`；文件和图片剪贴板通过 `osascript` / JXA 写入，若宿主进程缺少 Automation 权限可能失败。
+
+参数说明：
+- `--text`：要写入的文本内容
+- `--paths`：多个文件路径，使用分号 `;` 分隔
+- `--path`：单个图片文件路径
+
+
+
+#### 键盘操作
+
+| 命令 | 用途 |
+| --- | --- |
+| `keyboard key --key <name>` | 发送单个按键 |
+| `keyboard hotkey --keys <combo>` | 发送组合键 |
+| `keyboard type --text <value>` | 直接注入文本内容（直输模式） |
+| `keyboard type-keys --text <value> [--key-delay-ms <ms>]` | 按键位逐字输入（模拟人类打字模式） |
+| `keyboard ime-switch [--strategy <win-space\|alt-shift\|ctrl-shift>]` | 切换输入法 |
+| `keyboard caps-lock [--state <toggle\|on\|off>]` | 控制大小写状态 |
+| `keyboard paste [--expect-title <text>] [--match <contains\|exact>]` | 发送粘贴动作，可加窗口标题保护 |
+
+平台说明：
+
+- 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`
+
+
+
+#### 屏幕与截图
+
+| 命令 | 用途 |
+| --- | --- |
+| `screen displays` | 列出显示器与分辨率信息 |
+| `screen pixel-color --x <x> --y <y>` | 读取指定像素颜色 |
+| `screen capture [--path <file>] [--display-id <id>] [--window-handle <handle>]` | 默认截取所有屏幕，或按屏幕/窗口定向截图 |
+
+平台说明：
+
+- 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`）
+
+```bash
+# 默认：截取所有屏幕
+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
+```
+
+
+
+#### 等待器
+
+等待器用于“动作后确认状态”，避免脚本只执行动作却不验证结果。
+典型用法：点击/输入/窗口切换之后，先等待目标条件成立，再继续下一步。
+这样可以降低因为界面刷新延迟、窗口抢焦点、颜色尚未变化导致的误操作。
+
+| 命令 | 用途 |
+| --- | --- |
+| `wait window --title <text> [--timeout-ms <ms>] [--match <contains\|exact>] [--foreground-only]` | 等待目标窗口出现或满足前台条件 |
+| `wait focus --title <text> [--timeout-ms <ms>] [--match <contains\|exact>]` | 等待焦点窗口标题匹配 |
+| `wait activate --handle <handle> [--expect-active <true\|false>] [--timeout-ms <ms>]` | 监听指定窗口句柄是否成为前台激活窗口（或等待其失去激活） |
+| `wait pixel --x <x> --y <y> --hex <RRGGBB> [--timeout-ms <ms>]` | 等待指定像素达到目标颜色 |
+| `wait clipboard [--expect-text <value>] [--timeout-ms <ms>] [--match <contains\|exact>]` | 等待剪贴板变化或匹配目标文本 |
+| `wait process [--name <text>\|--pid <pid>] [--expect-running <true\|false>] [--timeout-ms <ms>] [--match <contains\|exact>]` | 等待进程进入期望状态 |
+
+平台说明：
+
+- 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` 表示等待退出
+
+
+
+复杂参数组合示例：
+
+```bash
+# 标题精确匹配 + 只接受前台窗口
+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 服务
+
+```bash
+et mcp-stdio
+```
+
+
+
+### 导出工具清单（manifest）
+
+```bash
+et mcp-stdio --output json
+```
+
+
+
+
+### 配置示例
+
+```json
+{
+  "mcpServers": {
+    "easytouch": {
+      "command": "et",
+      "args": ["mcp-stdio"]
+    }
+  }
+}
+```
+
+

package/package.json

@@ -0,0 +1,18 @@
+{
+    "name":  "easytouch-macos",
+    "version":  "1.0.11",
+    "description":  "macOS binary distribution for EasyTouch.",
+    "license":  "SEE LICENSE IN LICENSE.txt",
+    "os":  [
+               "darwin"
+           ],
+    "cpu":  [
+                "x64"
+            ],
+    "files":  [
+                  "bin/**",
+                  "LICENSE.txt",
+                  "README.md",
+                  "SKILL.md"
+              ]
+}