Devicely

---

快速开始

macOS 或 Linux，Node.js 20.9+。 暂不支持 Windows。

npm install -g devicely
devicely doctor      # checks Node, adb, Xcode and iOS tools; prints the install command for anything missing
devicely start       # starts Devicely and opens the Command Center

无法全局安装？ 如果你使用的是受限的工作机器（没有管理员权限、禁止全局安装，或关闭了安装脚本），可以改用 npx 运行 Devicely。不会进行全局安装，所有命令的用法都相同：

npx devicely@latest doctor
npx devicely@latest start

首次运行会下载约 185 MB；之后的运行会使用 npm 缓存启动。团队可以固定版本（npx [email protected] start），确保所有人运行相同版本。如果公司通过私有注册表（Artifactory、Nexus、Verdaccio）转发 npm，请联系 IT 部门允许使用 devicely 包；npx 和 npm install 都会使用该注册表。

Command Center 会在 devicely-ai.vercel.app 打开，并连接到你机器上的服务。如果没有连接设备，它会显示 添加你的首台设备，引导你通过 USB 或 Wi-Fi 设置 Android、iPhone 或模拟器。

手边没有手机？ 启动服务器时，同时启动 Android 模拟器或 iOS 模拟器：

devicely emulators list            # shows installed AVDs and simulators
devicely start --launch <name>     # starts Devicely and boots that virtual device

要求： macOS 或 Linux 上的 Node.js 20.9+。Android 需要在你的 PATH 中配置 adb（platform-tools）。iOS 和 iPadOS 设备需要安装 Xcode 的 Mac——请参阅 iOS 设置。

正在使用 AI Agent？ devicely mcp install <client> 可为 Claude Code、Cursor、VS Code 等进行设置——请参阅面向 AI Agent。

---

几分钟内连接首台设备

1. devicely doctor 会按平台分组显示每项检查的 ✓ / ! / ✗，并列出修复每个 ✗ 的命令。如果没有安装任何可用组件，它会以代码 1 退出（脚本可使用 --json）。
2. devicely start 会打印本地服务 URL，并打开 Command Center。
3. 在浏览器中按照“添加首台设备”的说明操作。连接设备、点击 允许 或 信任 后，清单会实时更新，设备随后便会联机。

你拥有的设备	预计耗时	所需条件
Android 手机或平板电脑	约 2 分钟	已安装 adb，并开启“开发者选项”和“USB 调试”。Wi-Fi 配对需要 Android 11 或更高版本。Android 指南
iPhone 或 iPad	首次约 15 分钟	一台安装了 Xcode 的 Mac、一个 Apple ID（免费账户即可），以及在 Xcode 中签名过一次的 WebDriverAgent。iOS 指南
没有设备	安装 Xcode 或 Android Studio 后只需几分钟	iOS 模拟器（Xcode + WebDriverAgent，无需签名）或 Android 模拟器（由 Android Studio 创建的 AVD）

故障排除

问题	解决方法
Android 显示正在等待授权（unauthorized）	解锁手机，并在是否允许 USB 调试？提示中点击允许（勾选始终允许）。没有提示？在“开发者选项”中撤销 USB 调试授权，然后重新插拔设备。了解更多
找不到设备	使用数据线，而不是仅支持充电的数据线，并检查 adb devices / idevice_id -l。运行 devicely doctor 检查是否缺少工具。在 Linux 上，no permissions 表示缺少 udev 规则：修复方法
浏览器无法访问本地服务	确认 devicely start 仍在运行，并打开它打印的确切链接。如果页面显示Devicely 正在运行，但此页面无法与其通信，说明浏览器阻止了 HTTPS 网站调用 http://127.0.0.1：在 Chrome 或 Edge 的网站设置中允许 devicely-ai.vercel.app 访问本地网络；在 Brave 中降低该网站的 Shields 防护级别；在 Safari 上则使用 Chrome、Edge 或 Firefox。如果没有浏览器连接，devicely start 也会在 30 秒后打印提示。
npm install -g 因 EACCES 或权限被拒绝而失败，或在工作场所遭到阻止	使用 npx devicely@latest start（以及 npx devicely@latest doctor）；无需全局安装或管理员权限。如果使用私有注册表，请联系 IT 部门允许安装 devicely 包。不要使用 sudo npm install -g。
端口已被占用	使用 devicely start -p 3002。使用非默认端口时，devicely start 会打印要打开的完整链接，例如 https://devicely-ai.vercel.app/?api=http://127.0.0.1:3002。
iPhone：WebDriverAgent 签名失败	Devicely 会指出原因（无签名团队、配置描述文件、开发者模式关闭、开发者不受信任、设备已锁定、超时），并链接到 iOS 指南中的解决方法。
Wi-Fi 配对失败	访客、酒店和企业 Wi-Fi 通常会阻止设备间通信和 mDNS，VPN 也可能改变流量路由。请使用家庭网络或热点，或者先通过 USB 配对。了解更多

仍然无法解决？devicely doctor --bundle 会在本地磁盘写入一份已脱敏的支持信息包（不会上传任何内容），你可以将其附加到问题报告中。另请参阅故障排除。

---

为什么选择 Devicely

在十台设备上测试一个流程，通常意味着手动重复十次、按分钟租用云设备，或维护针对每台设备的脚本。Devicely 采用不同的方式：你操作一台设备，设备群中的其他设备就会在同一时刻执行相同操作。

	Devicely	云设备实验室	脚本框架（Appium、Maestro、Detox）	屏幕镜像（scrcpy、Vysor）
实时一对多手势（一点按 → 所有设备）	✅	❌	❌	❌
在同一实时会话中混用 iOS 和 Android	✅	❌	❌	❌
使用自己的设备，并在自己的机器上运行	✅	❌	✅	✅
无需编写代码（UI、语音、纯英文）	✅	部分支持	❌	✅（单台设备）
录制一次并保存为 Flow，在每台设备上重放	✅	部分支持	❌（需要编写代码）	❌
内置面向 AI Agent 的 MCP 服务	✅	因平台而异	因平台而异	❌
将 Flow 和定位器导出为测试代码	✅	—	✅	❌

Devicely 不会取代你的测试框架，而是缩短周边的耗时环节：探索、在多台设备上复现错误、对构建进行冒烟测试，以及查找要用于测试的定位器。

---

面向 QA 团队

Commander 模式 — 一对多控制

• 实时镜像显示主控设备，并排显示每台跟随设备。
• 广播每个手势：点按、长按、滑动（保留速度）和输入的文本都会同时发送到所有跟随设备。
• 识别界面元素，而非盲目依赖像素。 跟随设备会根据无障碍 ID、标签、类型和 UI 树中的位置，找到主控设备上被触碰的元素——因此，在 iPhone 上点按的按钮，在 iPad 或 Pixel 上也会被点按，即使布局不同也不例外。
• 通过镜像画面上的下拉菜单切换主控设备，无需重启会话。
• 一键包含或排除单台跟随设备。
• 通过 WebDriverAgent MJPEG 实现快速 iOS 镜像：每帧约 170 KB，相比之下，轮询截图约为 5.8 MB。每台 iOS 设备都有自己的 WDA 端口，因此多台 iPhone 不会发生冲突。
• 真实设备般的体验：仅在主控设备上显示指尖光标和触碰位置的涟漪效果。
• 操作栏中的滑动控件会同时作用于所有目标设备。
• 沉浸式全屏，底部叠加命令栏，无需离开镜像画面。

Flows — 无代码自动化

手动操作一次，Devicely 就会将其保存为 Flow，可在单台设备或整个设备群上重放，并可在准备就绪后导出为测试代码。

• 步骤会记录为定位器（accessibilityId、resourceId、文本、类型、边界），而不是原始坐标。
• 自动等待：重放时，每个步骤最多等待 10 s，直到元素出现，因此动画和缓慢的网络不会导致运行失败。
• 坐标回退：如果找不到元素，Devicely 会改为点按其缩放后的位置，并将该步骤标记为 fallback，方便你查看出现偏移的位置。
• 可在单台设备或整个设备群上并行重放。
• 将 Flow 导出为 Maestro、Appium（Python 或 Java）或 WebdriverIO，无需 AI 参与，即可用于 CI。
• 通过列表或网格视图管理 Flows，并使用搜索和标签筛选。详情抽屉会显示每个步骤的定位器、耗时和结果；编辑器可用于添加、编辑、重新排序和删除步骤。

自然语言和语音

输入或说出 “打开设置，向下滚动，打开相机”。Devicely 会将其转换为适用于各个平台的操作，例如 iOS 上的 com.apple.Preferences 和 Android 上的 com.android.settings，并同时在所有选定设备上执行。语音输入会等待 2 秒停顿后再执行，让你可以自然地说话。

• 以真实屏幕内容为依据。 规划前，AI 会读取设备上的内容，因此它点击的是实际存在的按钮，而不是靠猜测。
• 执行前先审核。 计划会显示为一张卡片，你可以检查、编辑或取消。确认操作可靠后，可通过命令面板（⌘K）关闭审核。
• 默认安全。 AI 计划遇到第一个失败步骤时就会停止，并等待元素出现，而不是依赖固定延迟。

在 Settings → AI Config 中选择 AI 提供商，并使用 Test connection 通过实际请求检查密钥和模型：

提供商	说明
Ollama	在本地运行。无需 API 密钥，提示词不会离开你的设备。
Google Gemini、Groq	提供免费套餐，是最简单的入门方式。
OpenAI、Anthropic Claude	使用你自己的 API 密钥。
GitHub Copilot	使用你的 Copilot 订阅。

每个提供商都会在设置屏幕中列出当前模型。Devicely 只使用你选择的提供商；绝不会在你不知情的情况下切换到其他提供商。

快捷操作、检查器和代码导出

• 命令面板（⌘K）：输入几个字母，即可运行任意操作、选择目标设备、切换控制器或跳转到任意位置。
• 快捷操作面板：发送文本、按名称或 x,y 点击元素，以及通过自动补全启动应用。按方向键可循环查看之前输入的内容。
• UI 检查器：将鼠标悬停在任意元素上，即可查看其无障碍 ID、资源 ID、XPath 和边界。
• 一键导出选择器为 Devicely 命令、WebdriverIO、Appium Python 或 Appium Java 代码。

让设备保持连接

• 无线配对（Android 11+）：从 Command Center 扫描二维码或输入 6 位配对码，无需输入 IP 地址。如果配对失败，Devicely 会检查网络是否阻止了设备发现（mDNS），并告知你。从终端运行：devicely wifi pair <ip:port> <code>，然后运行 devicely wifi connect <ip:port>。
• 清晰的设备状态：等待你点击 Allow 的 Android 设备会显示为等待授权，而不会消失。
• 健康监控会在数秒内发现线缆断开、设备重启或驱动故障，并清理会话。
• 自动重新连接会在设备重新通过 USB 或 Wi-Fi 出现时立即恢复连接。此功能默认开启；设置 DEVICELY_AUTO_RECONNECT=0 即可关闭。
• 虚拟设备：可通过 UI 或 CLI 启动和停止 Android 模拟器及 iOS 模拟器，并与实体设备并列显示。

---

面向 AI Agent（MCP 服务）

Devicely 内置了 Model Context Protocol 服务，让编码 Agent 能够查看和控制真实设备。

你的 Agent 是大脑；Devicely 是双手。 通过 MCP，Devicely 不会调用自己的 AI：你的 Agent 会读取屏幕、做出决策、执行操作并检查结果。无需第二个模型、额外的 API 密钥，也无需配置 Devicely 的 AI 设置。

devicely mcp install claude-code      # prints the `claude mcp add` command to run
devicely mcp install cursor           # also: vscode, windsurf, gemini, claude-desktop
devicely mcp doctor                   # checks the backend, token and transports

或者在 Claude Code 内安装 Claude Code 插件：

/plugin marketplace add sureshkumarm8/Devicely
/plugin install devicely@devicely

或者手动将其添加到 Claude Code：

claude mcp add devicely -- npx -y devicely mcp

有两种传输方式：stdio（devicely mcp，会在后端未运行时启动后端）和 Streamable HTTP，并由 Bearer 令牌保护。运行 devicely mcp doctor 查看 HTTP 端点。

30 个工具

分组	工具
观察	devicely_snapshot、devicely_find_elements、devicely_wait_for、devicely_get_device_logs、devicely_get_action_log
操作	devicely_tap、devicely_long_press、devicely_swipe、devicely_type_text、devicely_press_key、devicely_open_url
应用	devicely_launch_app、devicely_close_app、devicely_list_apps、devicely_install_app、devicely_uninstall_app
设备	devicely_list_devices、devicely_connect_device、devicely_disconnect_device、devicely_restart_device、devicely_set_passcode、devicely_doctor
设备群与流程	devicely_commander、devicely_run_commands、devicely_export_test
虚拟设备	devicely_launch_virtual_device、devicely_stop_virtual_device
流程	devicely_save_recording、devicely_list_recordings、devicely_replay_recording

适用于常见任务的提示词：smoke_test、reproduce_bug 和 write_test。 包含实时上下文的资源：devicely://devices、devicely://apps、devicely://docs/command-language 和 devicely://docs/agent-guide。

安全控制

在设置 → AI Agents中配置（保存于 ~/.devicely/mcp.json）：

• 破坏性工具默认关闭：install_app、uninstall_app、restart_device 和 stop_virtual_device。启用后，还可以要求确认。默认允许使用 set_passcode；如需禁用，请将其添加到 ~/.devicely/mcp.json 中的 disabledTools。
• 将 Agent 限定为特定设备（allowedDevices）、关闭单个工具，并从输出中屏蔽敏感值。
• 每个 Agent 操作都会记录到审计追踪中。

REST API

通过 /api/v1 的 HTTP 接口也可使用相同功能，并使用相同的 Bearer token，适用于 CI 流水线和自定义测试框架。使用 devicely mcp token [--rotate] 查看或轮换 token；token 保存在 ~/.devicely/mcp-token 中。

示例

“截取 Pixel 的屏幕快照，检查 Login 按钮是否可见，点击该按钮，并确认欢迎界面是否出现。”

Agent 会调用 devicely_snapshot 和 devicely_find_elements，使用 devicely_tap 点击，并通过 devicely_wait_for 检查结果。

---

CLI 参考

命令	功能
devicely start	启动服务（绑定到回环地址 127.0.0.1）并打开 Command Center
devicely start --host <addr>	绑定到指定接口（例如使用 --host 0.0.0.0 进行局域网访问）
devicely start -p <port>	使用其他端口（例如，端口 3001 已被占用时）。输出包含该端口 ?api= 的完整 Command Center 链接
devicely start --no-browser	不打开浏览器（适用于 CI、无头计算机）；请自行打开输出的链接
devicely start --usb-only / --wifi-only	仅检测通过 USB 连接的设备，或仅检测通过 Wi-Fi 连接的设备
devicely start --launch <name>	启动服务时启动虚拟设备
devicely start --debug	开启调试日志
devicely start --https --ssl-key <key.pem> --ssl-cert <cert.pem>	通过 HTTPS/WSS 提供服务（或设置 DEVICELY_HTTPS=true、DEVICELY_SSL_KEY、DEVICELY_SSL_CERT）。如果无法加载证书，则拒绝启动。请使用本地受信任的证书（例如 mkcert localhost 127.0.0.1）；浏览器会静默阻止自签名证书
devicely list [--verbose]	列出已连接的 iOS 和 Android 设备
devicely exec "<command>" [-d <name>]	在所有设备上运行命令，或使用 -d 在一台设备上运行
devicely doctor	检查 Node、adb、Xcode 和 iOS 工具，并为每项故障提供修复命令。如果没有安装任何可用工具，则以状态码 1 退出
devicely doctor --json	以 JSON 格式执行相同检查，供脚本和 CI 使用
devicely doctor --bundle	将已脱敏的支持信息包写入磁盘（不会上传任何内容）
devicely wifi pair <ip:port> <code>	使用 Android 11+ 设备上的 Wireless debugging › Pair device with pairing code 中的代码进行配对
devicely wifi connect <ip:port>	通过 Wi-Fi 连接已配对的 Android 设备（地址显示在 Wireless debugging 下方）
devicely telemetry status|enable|disable	查看或更改是否选择加入设置诊断的选项（详情）
devicely emulators list	列出 Android 模拟器和 iOS 模拟器（别名：devicely virtual）
devicely emulators start <name> [--headless]	启动虚拟设备
devicely emulators stop <name>	关闭虚拟设备
devicely mcp [--url <url>] [--no-autostart]	运行 MCP stdio 服务
devicely mcp doctor	检查 MCP 是否就绪
devicely mcp token [--rotate]	查看或轮换 Agent 令牌
devicely mcp install <client>	配置 claude-code、claude-desktop、cursor、vscode、windsurf 或 gemini

规范命令集（DSL）

Devicely 可在 iOS 和 Android 上执行确定性的多行或以分号分隔的命令 DSL：

动词	语法	平台	说明
launch	launch <app|package>	iOS, Android	按预设名称或 bundle/package ID 启动应用
kill	kill <app|package>	iOS, Android	强制停止/终止应用
click	click <text|x,y>	iOS, Android	按文本、无障碍 ID 或坐标点击元素
longpress	longpress <text|x,y>	iOS, Android	长按元素或坐标
swipe	swipe <up|down|left|right>	iOS, Android	模拟手指手势（注意：向下滚动对应向上滑动）
type	type <text>	iOS, Android	在当前聚焦的输入框中输入文本
enter	enter	Android	按下 Enter / 提交键（在 iOS 上，type 会为你按下 Return）
home	home	iOS, Android	返回主屏幕
back	back	iOS, Android	返回上一页
screenshot	screenshot	iOS, Android	截取设备屏幕
lock / unlock	lock, unlock	iOS, Android	锁定或唤醒/解锁设备屏幕
url	url <https://...>	iOS, Android	在默认浏览器中打开 URL
WAIT	WAIT <ms>	iOS, Android	暂停执行指定的毫秒数
notifications	notifications	iOS, Android	打开通知中心 / 通知栏
quicksettings	quicksettings	iOS, Android	打开控制中心 / 快速设置
recent	recent	iOS, Android	打开应用切换器
rotate	rotate	iOS	旋转屏幕
volume	volume <up|down>	Android	调节音量
getLocators	getLocators	Android	导出当前屏幕的 UI 无障碍树
install / clear	install <apk>, clear <package>	Android	安装 APK，或清除应用数据
uninstall	uninstall <app|package>	iOS, Android	移除应用
restart / shutdown	restart, shutdown	iOS, Android	重启或关闭设备

exec 的示例命令：

devicely exec "launch settings"
devicely exec "launch settings; swipe up; launch camera"
devicely exec "url https://github.com" -d "Pixel 8"

---

支持的平台

	支持情况
主机	macOS 和 Linux，Node.js 20.9+。暂不支持 Windows。
Android	通过 ADB 和 UIAutomator2 支持手机、平板和模拟器。无线调试需要 Android 11+。
iOS / iPadOS	通过 WebDriverAgent 支持运行 iOS/iPadOS 17 或更高版本的 iPhone、iPad 和模拟器。需要配备 Xcode 的 Mac。实体设备需要开启开发者模式。

iOS 设置

通过 WebDriverAgent（WDA）控制 iPhone、iPad 和模拟器。WDA 是 Appium 的开源测试运行器。可在 添加你的第一台设备 中一键获取，也可以自行将其克隆到 Devicely 数据文件夹：

git clone https://github.com/appium/WebDriverAgent ~/.devicely/WebDriverAgent

（如果设置了 DEVICELY_DATA_DIR，则路径为 $DEVICELY_DATA_DIR/WebDriverAgent；WDA_PATH 可将 Devicely 指向其他位置的检出目录。）模拟器无需额外配置。

实体设备还需要在 Xcode 中使用你的 Apple ID 为 WDA 签名一次。免费 Apple ID 也可使用，但签名会在 7 天后过期。应用内指南会引导你信任电脑、开启开发者模式并完成签名；如果连接失败，还会说明原因（未设置签名团队、配置描述文件问题、开发者模式已关闭、开发者不受信任、设备已锁定、超时），并提供修复链接。完整指南：iOS 设备指南。Android 设备无需签名。

---

隐私与安全

• 在本地运行。 Devicely 服务在你的机器上运行，并直接与设备通信。你的应用、屏幕截图和测试数据不会上传到任何地方。
• 默认绑定到回环地址。 服务默认绑定到 127.0.0.1，避免主机意外暴露于本地网络。
• Origin 和 Host 防护。 REST API 和 WebSocket 端点会检查请求中的 Host 和 Origin 标头是否可信，防范 DNS 重绑定和跨源攻击。
• 可选择使用本地 AI。 使用 Ollama 可将提示词和屏幕数据保留在你的机器上。使用云端 AI 提供商时，你的命令会通过自己的 API 密钥发送给该提供商。
• API 密钥保存在你的机器上。 你在 Settings 中添加的 AI 密钥会保存在 ~/.devicely/.env（或 $DEVICELY_DATA_DIR/.env）中，且仅你可读取（0600）。这些密钥只会发送给你选择的 AI 提供商。
• Agent 需要令牌。 通过 HTTP 使用 MCP 和 REST API 均需要 32 字节的 Bearer 令牌。
• **分析数据：**本地服务不发送遥测数据。托管仪表板 devicely-ai.vercel.app 使用匿名的 Vercel 页面浏览分析数据，并连接到你的本地服务；设备数据不会发送给 Vercel。
• 设置诊断为可选加入。 Command Center 会询问一次是否分享匿名设置事件（例如“doctor 检查失败：缺少 adb”或“首次设备操作成功”）。事件仅使用固定代码：不包含序列号、IP 地址、设备或应用名称，也不包含文件路径。只有你同意后才会发送数据；设置 DO_NOT_TRACK=1 或 DEVICELY_TELEMETRY_DISABLED=1 可关闭此功能。使用 devicely telemetry status|enable|disable 查看或更改设置。每个事件及字段均列于 TELEMETRY.md。

详细信息：Devicely 可以和不可以查看的内容。发现漏洞？请发送邮件至 [email protected]，而不要创建公开问题。

---

2.4.0 版本更新

• **Flows：**录制内容现在称为 Flows — 录制一次，即可在每台设备上重放，并导出到 Maestro、Appium 或 WebdriverIO。
• **基于实际屏幕信息的 AI 命令：**AI 会先读取屏幕，再制定计划；计划会显示出来供你审核；遇到首个失败步骤时会停止，并等待界面元素出现，而不是使用固定延迟。
• **重新设计的 Command Center：**紧凑的命令栏、⌘K 命令面板、全设备滑动控制、沉浸式全屏和真实设备触控反馈。
• **简化 MCP：**Agent 会自行规划每一步；Devicely 不再通过 MCP 调用自身的 AI。
• **AI 提供商：**支持最新的 Gemini 和 Groq 模型，提供真实的连接测试，不再静默回退。已移除 Cohere 和 Mistral。
• **iOS 26 修复：**锁定和解锁功能恢复正常，并新增对较新版本的 iOS 隧道支持。
• **安全性：**已修复所有已知的依赖项漏洞。现在要求使用 Node.js 20.9 或更高版本。

---

许可证

**免费使用，闭源。**Devicely 可免费安装和使用，无论是个人使用还是在公司内部使用。本软件为专有软件：不得复制、修改、逆向工程或再分发，不得将其作为托管服务提供，也不得用于训练 AI 模型。请参阅 Devicely Free Use License。

• 问题和企业咨询：[email protected]
• 报告问题：github.com/sureshkumarm8/Devicely/issues