WireHand · 接手

被控设备无需安装任何控制软件：只要能输出视频信号、接受键盘鼠标输入，就能通过相应的视频与键鼠接口接入控制，可远程操控与录制操作脚本，提供MCP服务器。

WireHand 从视频输出观察设备界面，通过模拟键盘鼠标发送操作。控制对象不限于电脑，也包括具备相应接口的其他电子设备；网页服务、视觉识别和脚本执行都运行在外部控制端，被控设备只需输出画面并接收键鼠输入。

当前硬件适配使用 ROCK 5B+ 的 HDMI 输入与 USB HID 键盘鼠标，接入具有兼容视频输出和标准 USB 键鼠输入的设备。接好线后，即可通过网页手动操作、使用 Python 编写自动化，或交给支持 MCP 的 AI agent 控制。

录制时，鼠标按下会提取点击附近的图像作为目标；重放时重新定位目标。键盘、鼠标移动和滚轮保留输入、位置与时间间隔。脚本、目标图片和桌面数据均保存在自己的服务器上，视觉处理使用本地 OpenCV。

工作原理

箭头表示画面和操作的传递方向：被控设备向 KVM 输出画面，KVM 将远程操作转换成标准键鼠输入。人通过网页接管，agent 通过 MCP 调用工具；视觉识别、录制和脚本执行都在 KVM 控制端完成。

图中展示实体设备的远程接入方式；同机 MCP 客户端可直接使用 stdio。Docker 桌面提供虚拟屏幕与键鼠后端，用于无板卡体验和开发。

Related MCP server: winagent

基于画面的视觉定位

把设备画面变成 agent 可以选择、脚本可以重新定位的操作目标。 WireHand 自动检测视觉候选并标号，agent 只需选择编号，坐标映射由程序完成。无需访问被控应用的 DOM 或无障碍接口，这套定位方式也能直接用于 HDMI 采集画面。

• 按编号点击：inspect_screen 返回标记图，click_target 根据目标 ID 校验画面并执行操作。

• 密集区域分图查看：先看总览，再看放大的局部图，每图最多 18 个候选；分页与细分共用同一帧。

• 录制后重新找目标：鼠标按下时自动保存附近的图像，脚本重放时等待匹配稳定，再定位到目标的新位置。

上图使用采集的真实 1920×1080 屏幕：266 个候选先分成九个区域，右下角 C09 的 24 个候选再分成两张图，分别有 14、10 个标记。关闭按钮在局部图中标为 T234。标记由实际算法生成，示例在保存的截图上离线运行。

inspect_screen()                                  → 获取快照 S 和区域总览
inspect_region(snapshot_id=S, region_id="C09")     → 查看右下角的局部编号
click_target(snapshot_id=S, target_id="T234")      → 按编号选择关闭按钮

视觉定位详细说明

适合哪些场景

控制实体设备从 ROCK 5B+ 接线与部署 开始；想先体验网页、录制与脚本功能，可以使用下面的 Docker 桌面。

快速开始：Docker 桌面

需要 Linux、Docker Engine、Docker Compose 插件和 Python 3。下载或克隆本仓库后，在仓库根目录执行：

./deploy/docker-desktop/desktopctl init
./deploy/docker-desktop/desktopctl up
./deploy/docker-desktop/desktopctl status

首次启动会构建镜像并安装桌面环境。打开 http://127.0.0.1:18810/，使用 deploy/docker-desktop/.env 中自动生成的 KVM_TOKEN 登录。

容器内预装 Xfce、Firefox ESR、终端和文件管理器。默认只监听本机回环地址；部署在远端服务器时，在自己的电脑上建立 SSH 隧道：

ssh -N -L 18810:127.0.0.1:18810 user@server

随后仍访问 http://127.0.0.1:18810/。桌面主目录、/workspace 和脚本库分别保存在 Docker 命名卷中，重建容器后保留。

常用管理命令：

./deploy/docker-desktop/desktopctl logs       # 查看日志
./deploy/docker-desktop/desktopctl restart    # 重启当前版本
./deploy/docker-desktop/desktopctl up         # 构建并启用更新后的代码
./deploy/docker-desktop/desktopctl down       # 停止服务，保留数据卷

分辨率、局域网访问、备份与恢复见 Docker 桌面指南。

网页录制与脚本执行

1. 点击 接管控制，使用画面中的鼠标和键盘操作设备。

2. 输入脚本名称，点击 开始录制，完成希望重复执行的操作。

3. 点击 停止并生成脚本，脚本和目标图片自动保存到服务器的脚本库。

4. 点击 结束接管，设置重复次数或无限重复，再点击脚本的 运行。

5. 在运行面板查看进度和日志；点击 停止执行，或重新接管设备，即可停止任务。

下载文件名与脚本名称对应，例如 每日整理.zip。解压后可以修改 replay.py、添加辅助模块，再上传同名 ZIP；网页会提示是否替换，实际运行的是修改后的 Python 文件。

网页只有接管和非接管两种模式。接管时由当前浏览器独占输入；脚本运行时由该任务独占自动输入。关闭浏览器会结束手动接管，已经启动的服务器脚本任务继续运行。

完整流程、压缩包格式与存储目录见 网页控制台指南。

Python SDK

SDK 提供截图、点击、键盘、滚轮、拖动、视觉等待和录制接口。它与网页共用同一套设备适配器与输入控制规则。

在 Docker 桌面中，先进入容器：

./deploy/docker-desktop/desktopctl shell

然后运行：

from wirehand import connect

with connect() as computer:
    print(computer.size())
    computer.screenshot().save('/workspace/screen.png')
    # 确认屏幕坐标后，可以发送操作：
    # computer.click(320, 240)
    # computer.hotkey('ctrl', 'a')
    # computer.write('hello')

容器已配置后端和运行目录。SDK 在设备后端所在环境执行：Docker 脚本在容器中运行，ROCK 脚本在板子上运行。宿主机上的 connect(backend='docker-desktop') 不会自动连接容器。

录制文件中的图像目标也可以用于手写脚本：

from pathlib import Path
from wirehand import connect
from wirehand.automation import Recording

flow = Recording.load(Path('/workspace/my-flow'))  # 解压后的录制目录
with connect(timeout=15) as computer:
    computer.click(target=flow.target('target_0001'))
    computer.write('hello')

目标 ID 取自 recording.json。像素坐标、图像匹配和取消行为见 SDK 与录制说明。网页右上角的 SDK 文档 从当前接口自动生成，也可以在源码环境导出：

uv sync --frozen
uv run wirehand-docs --output artifacts/sdk-docs

MCP 接入

支持 stdio 的 MCP 客户端可以使用以下配置，把路径替换为本机仓库的绝对路径；Docker 桌面需先启动：

{
  "mcpServers": {
    "desktop": {
      "command": "/absolute/path/to/wirehand/deploy/docker-desktop/desktopctl",
      "args": ["mcp"]
    }
  }
}

工具提供截图、按键、文本输入、鼠标操作，以及 inspect_screen / inspect_region / click_target。agent 可以选择图像中的编号来点击；密集画面先分区，再返回放大的局部标记图。

浏览器接管或服务器脚本执行期间，MCP 工具返回占用错误。结束接管或任务后可继续调用。连接方式、工具参数与排查方法见 MCP 接入指南。

控制电子设备：ROCK 5B+

ROCK 5B+ 是 Radxa 推出的 单板计算机（SBC）。它集成 HDMI 输入、USB OTG 和网络接口，适合同时承担画面采集、键鼠模拟及自动化程序运行。在 WireHand 中，板子就是连接被控设备与远程操作端的 KVM 控制器。

将被控设备的 HDMI OUT 接到 ROCK 5B+ 的 HDMI IN，再用板子的 USB-C 数据口连接被控设备的 USB 主机口。板子独立供电，被控设备通过 HDMI 输出画面、通过 USB 接收标准 HID 键鼠事件，无需安装控制软件。

完成板端驱动、USB gadget 和 EDID 配置后，在板子的仓库目录运行：

uv sync --frozen
uv run wirehand-web --backend rock5b-plus

启动前需配置 KVM_TOKEN 等环境变量。接线、系统依赖、服务安装和 SSH MCP 配置见 ROCK 5B+ 部署指南；跨网络观看见 SSH / HTTPS 与视频传输。

当前支持范围

• 运行环境：服务端使用 Linux/POSIX 输入锁；Docker 桌面已在 ARM64 Linux 上验证。

• 画面：Docker 桌面提供最高 5fps 的 JPEG 预览；ROCK 后端支持硬件视频路径，网页可使用 H.264 WebSocket、MSE、WebRTC 或 JPEG，取决于驱动和浏览器能力。

• 录制：捕获经过网页或 SDK 的操作。鼠标按下时生成局部 target；键盘、移动和滚轮不生成 target。直接接在目标电脑上的物理键鼠不进入该录制通道。

• 重放：点击目标会重新匹配；目标消失或匹配不唯一时停止。键盘焦点、菜单布局和输入法状态仍需与流程一致。

• 输入与权限：文本输入采用 US 布局 ASCII 约定；音频和剪贴板通道尚未提供。上传的 Python 脚本以服务器服务用户身份执行。

文档与开发

• 文档导航：按任务选择指南。

• 配置参考：后端、端口、访问密码与运行目录。

• 贡献与本地开发：安装源码、无硬件演示、测试和构建。

• 架构与扩展：一个安装包，按硬件、视觉、自动化和应用职责分目录。

• 视觉定位：候选检测、分区、分页和按编号点击。

许可证

本项目采用 MIT License。