agent-device by callstackincubator/agent-device
npx skills add https://github.com/callstackincubator/agent-device --skill agent-device探索时使用快照引用。确定性回放时使用选择器。结构化探索性 QA 缺陷排查和报告时,请使用 ../dogfood/SKILL.md。
将此技能用作路由器,而非完整手册。
devices -> 选择目标 -> open。open -> snapshot -i -> press/fill -> diff snapshot -i -> close广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
open <app> -> logs clear --restart -> 复现问题 -> network dump -> logs path -> 针对性 grepreplay -u <path> -> 验证更新后的选择器agent-device open Settings --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device close
agent-device open MyApp --platform ios
agent-device logs clear --restart
agent-device network dump 25
agent-device logs path
默认情况下日志记录是关闭的。仅在调试窗口期间启用。logs clear --restart 需要一个活跃的应用会话(先执行 open <app>)。
agent-device replay -u ./session.ad
# 客户端直接指向远程守护进程 HTTP 基础 URL。
export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>
# 分配租约
curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"runId":"run-123","tenantId":"acme","ttlMs":60000}}'
# 在租户隔离的命令执行中使用租约
agent-device \
--tenant acme \
--session-isolation tenant \
--run-id run-123 \
--lease-id <lease-id> \
session list --json
# 心跳和释放
curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
注意事项:
AGENT_DEVICE_DAEMON_BASE_URL 使 CLI 跳过本地守护进程发现/启动,直接调用远程 HTTP 守护进程。AGENT_DEVICE_DAEMON_AUTH_TOKEN 会同时发送在 JSON-RPC 请求令牌和 HTTP 认证头中。--debug 不会跟踪本地的 daemon.log;请检查远程主机上的日志。agent-device devices
agent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulators
agent-device devices --platform android --android-device-allowlist emulator-5554,device-1234
agent-device ensure-simulator --device "iPhone 16" --ios-simulator-device-set /tmp/tenant-a/simulators
agent-device ensure-simulator --device "iPhone 16" --runtime com.apple.CoreSimulator.SimRuntime.iOS-18-4 --ios-simulator-device-set /tmp/tenant-a/simulators --boot
agent-device open [app|url] [url]
agent-device open [app] --relaunch
agent-device close [app]
agent-device install <app> <path-to-binary>
agent-device reinstall <app> <path-to-binary>
agent-device session list
仅当 open 无法找到/连接到就绪的目标时,才将 boot 作为后备方案使用。对于按 AVD 名称指定的 Android 模拟器,使用 boot --platform android --device <avd-name>。对于无 GUI 的 Android 模拟器,添加 --headless。使用 --target mobile|tv 与 --platform(必需)来选择手机/平板与电视目标(AndroidTV/tvOS)。
隔离范围快速参考:
--ios-simulator-device-set <path> 将 iOS 模拟器发现 + 命令执行范围限定在一个模拟器集内。--android-device-allowlist <serials> 将 Android 发现/选择范围限定在以逗号/空格分隔的序列号内。--device、--udid、--serial)之前应用;超出范围的选择器会失败并提示 DEVICE_NOT_FOUND。模拟器配置快速参考:
ensure-simulator 在启动会话前,在设备集内创建或重用指定名称的 iOS 模拟器。--device <name> 是必需的(例如 "iPhone 16 Pro")。--runtime <id> 固定运行时;省略则使用最新的兼容版本。--boot 立即启动它。返回 udid、device、runtime、ios_simulator_device_set、created、booted。电视快速参考:
open/apps 自动使用电视启动器发现。snapshot、wait、press、fill、get、scroll、back、home、app-switcher、record 及相关选择器流程)。back/home/app-switcher 映射到运行器中的 Siri Remote 操作(menu、home、double-home)。pinch、settings 和 push 等辅助命令。agent-device snapshot -i
agent-device diff snapshot -i
agent-device find "Sign In" click
agent-device press @e1
agent-device fill @e2 "text"
agent-device is visible 'id="anchor"'
press 是规范的点击命令;click 是其别名。
agent-device appstate
agent-device clipboard read
agent-device clipboard write "token"
agent-device keyboard status
agent-device keyboard dismiss
agent-device perf --json
agent-device network dump [limit] [summary|headers|body|all]
agent-device push <bundle|package> <payload.json|inline-json>
agent-device trigger-app-event screenshot_taken '{"source":"qa"}'
agent-device get text @e1
agent-device screenshot out.png
agent-device settings permission grant notifications
agent-device settings permission reset camera
agent-device trace start
agent-device trace stop ./trace.log
agent-device batch --steps-file /tmp/batch-steps.json --json
open 之后使用 agent-device perf --json(或 metrics --json)。snapshot -i;仅在需要时指定范围/深度。find "<query>" click --json 返回 { ref, locator, query, x, y } — 所有这些都源自匹配的快照节点。不要依赖原始 press/click 响应中的这些字段进行可观测性分析;请改用 find。fill 实现清除后输入的语义;使用 type 实现聚焦追加输入的语义。install 进行原地应用升级(在平台允许时保留应用数据),使用 reinstall 进行确定性的全新状态运行。install/reinstall 支持的应用二进制格式:Android .apk/.aab,iOS .app/.ipa。.aab 要求 PATH 中有 bundletool,或者设置 AGENT_DEVICE_BUNDLETOOL_JAR=<path-to-bundletool-all.jar> 且 PATH 中有 java。.aab 可选:设置 AGENT_DEVICE_ANDROID_BUNDLETOOL_MODE=<mode> 以控制 bundletool 的 build-apks --mode(默认值:universal)。.ipa:从 Payload/*.app 中提取/安装;当存在多个应用包时,<app> 用作包 ID/名称提示。appstate 是会话范围的;Android 的 appstate 是实时前台状态。iOS 响应包含 device_udid 和 ios_simulator_device_set 用于隔离验证。open 响应包含 device_udid 和 ios_simulator_device_set 以确认哪个模拟器处理了该会话。clipboard read / clipboard write <text> 在 Android 和 iOS 模拟器上受支持;iOS 物理设备尚不支持。keyboard status|get|dismiss 报告键盘可见性/类型,并在可见时通过 keyevent 关闭键盘。network dump 是尽力而为的,并从会话应用日志文件中解析 HTTP(s) 条目。settings faceid|touchid <match|nonmatch|enroll|unenroll>;Android 在运行时工具可用时支持 settings fingerprint <match|nonmatch>。--target 与 --platform(ios、android 或 apple 别名)配对使用;仅使用目标选择是无效的。push 模拟通知传递:
trigger-app-event 需要应用定义的深度链接钩子和 URL 模板配置(AGENT_DEVICE_APP_EVENT_URL_TEMPLATE 或平台特定的变体)。trigger-app-event 需要一个活跃的会话或明确的选择器(--platform、--device、--udid、--serial);在 iOS 物理设备上,自定义方案触发需要活跃的应用上下文。website/docs/docs/commands.md 的 应用事件触发器 部分下。settings permission <grant|deny|reset> <camera|microphone|photos|contacts|notifications> [full|limited]alert wait 然后 alert accept/dismiss — accept/dismiss 内部会重试最多 2 秒,因此您不需要手动休眠。请参阅 references/permissions.md。full|limited 模式仅适用于 iOS 的 photos;其他目标会拒绝此模式。fill/type 在某些系统映像上可能需要 ADB 键盘 IME;仅从可信来源安装 IME APK 并验证校验和/签名。--save-script,请优先使用显式路径语法(--save-script=flow.ad 或 ./flow.ad)。--tenant、--session-isolation tenant、--run-id 和 --lease-id。AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET(兼容 IOS_SIMULATOR_DEVICE_SET)和 AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST(兼容 ANDROID_DEVICE_ALLOWLIST)。AGENT_DEVICE_DAEMON_BASE_URL / --daemon-base-url,而不是依赖本地守护进程元数据或仅限环回的端口。agent-device 二进制文件,而不是按需执行包。npx --yes agent-device@<exact-version> --help)。~/.agent-device 目录下;回放脚本写入您提供的显式路径。AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual 加上客户端的 AGENT_DEVICE_DAEMON_BASE_URL,并根据需要配合 AGENT_DEVICE_HTTP_AUTH_HOOK 和租户范围的租约准入。--activity 结合使用(不支持的组合)。boot 视为默认的第一步,而不是后备方案。每周安装量
1.1K
代码仓库
GitHub 星标数
1.0K
首次出现
2026年2月3日
安全审计
安装于
codex1.0K
opencode982
gemini-cli973
github-copilot941
amp866
kimi-cli860
For exploration, use snapshot refs. For deterministic replay, use selectors. For structured exploratory QA bug hunts and reporting, use ../dogfood/SKILL.md.
Use this skill as a router, not a full manual.
devices -> pick target -> open.open -> snapshot -i -> press/fill -> diff snapshot -i -> closeopen <app> -> logs clear --restart -> reproduce -> network dump -> logs path -> targeted grepreplay -u <path> -> verify updated selectorsagent-device open Settings --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device close
agent-device open MyApp --platform ios
agent-device logs clear --restart
agent-device network dump 25
agent-device logs path
Logging is off by default. Enable only for debugging windows. logs clear --restart requires an active app session (open <app> first).
agent-device replay -u ./session.ad
# Client points directly at the remote daemon HTTP base URL.
export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>
# Allocate lease
curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"runId":"run-123","tenantId":"acme","ttlMs":60000}}'
# Use lease in tenant-isolated command execution
agent-device \
--tenant acme \
--session-isolation tenant \
--run-id run-123 \
--lease-id <lease-id> \
session list --json
# Heartbeat and release
curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
-H "content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
Notes:
AGENT_DEVICE_DAEMON_BASE_URL makes the CLI skip local daemon discovery/startup and call the remote HTTP daemon directly.AGENT_DEVICE_DAEMON_AUTH_TOKEN is sent in both the JSON-RPC request token and HTTP auth headers.--debug does not tail a local daemon.log; inspect logs on the remote host instead.agent-device devices
agent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulators
agent-device devices --platform android --android-device-allowlist emulator-5554,device-1234
agent-device ensure-simulator --device "iPhone 16" --ios-simulator-device-set /tmp/tenant-a/simulators
agent-device ensure-simulator --device "iPhone 16" --runtime com.apple.CoreSimulator.SimRuntime.iOS-18-4 --ios-simulator-device-set /tmp/tenant-a/simulators --boot
agent-device open [app|url] [url]
agent-device open [app] --relaunch
agent-device close [app]
agent-device install <app> <path-to-binary>
agent-device reinstall <app> <path-to-binary>
agent-device session list
Use boot only as fallback when open cannot find/connect to a ready target. For Android emulators by AVD name, use boot --platform android --device <avd-name>. For Android emulators without GUI, add --headless. Use --target mobile|tv with --platform (required) to pick phone/tablet vs TV targets (AndroidTV/tvOS).
Isolation scoping quick reference:
--ios-simulator-device-set <path> scopes iOS simulator discovery + command execution to one simulator set.--android-device-allowlist <serials> scopes Android discovery/selection to comma/space separated serials.--device, --udid, --serial); out-of-scope selectors fail with DEVICE_NOT_FOUND.Simulator provisioning quick reference:
ensure-simulator to create or reuse a named iOS simulator inside a device set before starting a session.--device <name> is required (e.g. "iPhone 16 Pro"). --runtime <id> pins the runtime; omit to use the newest compatible one.--boot boots it immediately. Returns udid, device, runtime, ios_simulator_device_set, created, booted.TV quick reference:
open/apps use TV launcher discovery automatically.snapshot, wait, press, fill, get, scroll, back, home, app-switcher, and related selector flows).agent-device snapshot -i
agent-device diff snapshot -i
agent-device find "Sign In" click
agent-device press @e1
agent-device fill @e2 "text"
agent-device is visible 'id="anchor"'
press is canonical tap command; click is an alias.
agent-device appstate
agent-device clipboard read
agent-device clipboard write "token"
agent-device keyboard status
agent-device keyboard dismiss
agent-device perf --json
agent-device network dump [limit] [summary|headers|body|all]
agent-device push <bundle|package> <payload.json|inline-json>
agent-device trigger-app-event screenshot_taken '{"source":"qa"}'
agent-device get text @e1
agent-device screenshot out.png
agent-device settings permission grant notifications
agent-device settings permission reset camera
agent-device trace start
agent-device trace stop ./trace.log
agent-device batch --steps-file /tmp/batch-steps.json --json
agent-device perf --json (or metrics --json) after open.snapshot -i; scope/depth only when needed.find "<query>" click --json returns { ref, locator, query, x, y } — all derived from the matched snapshot node. Do not rely on these fields from raw press/click responses for observability; use find instead.fill for clear-then-type semantics; use type for focused append typing.install for in-place app upgrades (keep app data when platform permits), and for deterministic fresh-state runs.agent-device binary over on-demand package execution.npx --yes agent-device@<exact-version> --help).~/.agent-device; replay scripts write to explicit paths you provide.AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual on the host plus client-side AGENT_DEVICE_DAEMON_BASE_URL, with AGENT_DEVICE_HTTP_AUTH_HOOK and tenant-scoped lease admission where needed.--activity (unsupported combination).boot as default first step instead of fallback.Weekly Installs
1.1K
Repository
GitHub Stars
1.0K
First Seen
Feb 3, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex1.0K
opencode982
gemini-cli973
github-copilot941
amp866
kimi-cli860
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装
recordback/home/app-switcher map to Siri Remote actions (menu, home, double-home) in the runner.pinch, settings, and push.reinstallinstall/reinstall: Android .apk/.aab, iOS .app/.ipa..aab requires bundletool in PATH, or AGENT_DEVICE_BUNDLETOOL_JAR=<path-to-bundletool-all.jar> with java in PATH..aab optional: set AGENT_DEVICE_ANDROID_BUNDLETOOL_MODE=<mode> to control bundletool build-apks --mode (default: universal)..ipa: extract/install from Payload/*.app; when multiple app bundles are present, <app> is used as a bundle id/name hint.appstate is session-scoped; Android appstate is live foreground state. iOS responses include device_udid and ios_simulator_device_set for isolation verification.open responses include device_udid and ios_simulator_device_set to confirm which simulator handled the session.clipboard read / clipboard write <text> are supported on Android and iOS simulators; iOS physical devices are not supported yet.keyboard status|get|dismiss report keyboard visibility/type and dismiss via keyevent when visible.network dump is best-effort and parses HTTP(s) entries from the session app log file.settings faceid|touchid <match|nonmatch|enroll|unenroll>; Android supports settings fingerprint <match|nonmatch> where runtime tooling is available.--target with --platform (ios, android, or apple alias); target-only selection is invalid.push simulates notification delivery:
trigger-app-event requires app-defined deep-link hooks and URL template configuration (AGENT_DEVICE_APP_EVENT_URL_TEMPLATE or platform-specific variants).trigger-app-event requires an active session or explicit selectors (--platform, --device, --udid, --serial); on iOS physical devices, custom-scheme triggers require active app context.website/docs/docs/commands.md under App event triggers.settings permission <grant|deny|reset> <camera|microphone|photos|contacts|notifications> [full|limited]alert wait then alert accept/dismiss — accept/dismiss retry internally for up to 2 s so you do not need manual sleeps. See references/permissions.md.full|limited mode applies only to iOS photos; other targets reject mode.fill/type may require an ADB keyboard IME on some system images; only install IME APKs from trusted sources and verify checksum/signature.--save-script, prefer explicit path syntax (--save-script=flow.ad or ./flow.ad).--tenant, --session-isolation tenant, --run-id, and --lease-id together.AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET (compat IOS_SIMULATOR_DEVICE_SET) and AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST (compat ANDROID_DEVICE_ALLOWLIST).AGENT_DEVICE_DAEMON_BASE_URL / --daemon-base-url instead of relying on local daemon metadata or loopback-only ports.