agentic-device

agentic-device

npm 包 · 命令行工具 · 库 · 安全性 · 限制

agentic-device 是一个 TypeScript 库、命令行工具和 MCP 服务，用于操控你自己拥有的手机——通过 WebDriverAgent 操控 iPhone，或通过 ESP32 HID 桥接器操控手机——让 Agent 执行以设置为导向的 UI 操作，并将可审计的手机发帖任务加入队列。 这是一个以用户同意为先的设备工具包：操作默认以模拟运行方式执行；任何需要人工参与的步骤（密码、CAPTCHA、验证码）都会以 needs-human 状态停止，而不会伪造进度。

安装

npm install agentic-device

需要 Node.js 和已发布的 dist/ 构建版本。运行时有两个依赖：MCP SDK 和 zod。

发布你的第一个任务

agentic-device device register --udid MY_PHONE_UDID --label "My iPhone" --connection simulator
agentic-device device action --udid MY_PHONE_UDID --action '{"type":"home"}'
agentic-device device post-task --udid MY_PHONE_UDID --platform instagram --text "Ship day"
agentic-device device queue

device action 和 post-task 默认以模拟运行方式执行，只有传入 --execute 才会实际运行；即使如此，device action 仍会保留审核关卡：运行结果会报告驱动程序执行的操作，或遇到的 VendorError。

命令行工具

agentic-device device register --udid <id> --label <label> --connection <wda|esp32-hid|simulator>
agentic-device device list
agentic-device device action --udid <id> --action <json> [--execute]
agentic-device device post-task --udid <id> --platform <name> --text <text> [--media <path>]
agentic-device device queue [--claim|--complete|--fail <task-id>]
agentic-device costs
agentic-device mcp

库

import { DeviceRegistry, SimulatorDriver, runAction } from "agentic-device";

const registry = new DeviceRegistry();
const phone = registry.register({ udid: "mine", label: "My iPhone", connectionType: "simulator" });
await runAction(phone, new SimulatorDriver(), { type: "home" }); // dry run

MCP 服务

agentic-device mcp（或 npx agentic-device-mcp）会通过 stdio 将同一套注册表、队列、驱动程序和成本报告作为工具提供，因此 Claude Code 或 Cursor 等宿主可以注册设备、预览操作并读取任务队列。

使用场景

• 支持 Agent 为你桌上的设备添加产品公告帖子，并由你批准执行。
• QA Agent 操控自己的模拟器完成应用引导流程并截取屏幕截图。
• 发帖流水线将每项设备任务记录为可审计的队列条目，而不是无法追踪的脚本。

替代方案和相关工具

• Appium 是通用的移动自动化框架；WebDriverAgent 是其 iOS 驱动程序，而 agentic-device 使用相同协议处理发帖任务子集。
• ESP32-BLE-Keyboard 是蓝牙 HID 路径的参考固件。
• 完整的设备农场产品（BrowserStack App Automate、Firebase Test Lab）可让你大规模租用设备；此工具包面向你自己桌上的手机。

安全性

• 仅按 UDID 注册你自己的手机。
• device action 默认以模拟运行方式执行；审核后才传入 --execute。
• 对于密码、CAPTCHA 和验证码步骤，humanCheckpoint 始终返回 needs-human——此工具包绝不会绕过平台检查。
• 驱动程序会将故障作为 VendorError 显示；绝不会将失败的硬件或网络操作报告为成功。

限制

• 绝不绕过密码、CAPTCHA、双重验证或 App Store 审核。
• WebDriverAgent 路径需要可访问的 WDA 端点来连接实体设备；simulator 是无需硬件的选项。
• 发帖队列默认在进程内运行；生产环境运行时，请将任务持久化到你自己的存储中。

上游基础项目

WDA 驱动程序遵循 appium/WebDriverAgent 提供的协议。ESP32 HID 路径围绕 ESP32-BLE-Keyboard 设计。这些集成仅供设备所有者操作自己的设备。

许可证

MIT