device-interaction

设备交互

在以下情况触发：用户要求验证／测试／检查应用在设备上是否正常运行；实现影响 UI、需要在设备上验证的功能后；用户询问“能用吗”“测试一下”“在设备上检查”；用户报告 UI 未按预期工作；需要调试触控／交互问题。 在以下情况不要触发：用户只询问单元测试；仅要求构建而不涉及设备测试；仅进行代码审查而不涉及设备测试；询问模拟器配置；更改不会影响 UI（例如注释、重构、非 UI 逻辑）。

---

致主 Agent

这是一个子 Agent 技能。 需要进行设备验证时，通过 Agent 工具调用此技能。

Agent tool:
- subagent_type: "general-purpose"
- description: "Verify login feature works"
- prompt: "Using the device-interaction skill, verify that the login feature works correctly on session <device-interaction-session>. Launch the app, capture screenshot and UI hierarchy, check that the login button is visible and tappable, and report if the implementation is working correctly."

实现影响 UI 的功能后，调用此技能，在设备上验证实现是否正常工作。

会话生命周期

DeviceInteractionStartSession (do this early, runs in the background)
  → DeviceInteractionInstallAndRun (after each code change; includes building)
    → DeviceEventSynthesize (interact + observe, repeatable)
  → DeviceInteractionEndSession (when done — keeping sessions open is resource-heavy)

DeviceInteractionStartSession 工具

设备发现

开启新的设备交互会话时，传入设备标识符以选择设备；也可以省略，以使用当前目标。传入任意不匹配的值，即可获取可用目标列表。

DeviceInteractionInstallAndRun 工具

可选参数

• commandLineArguments — 启动应用时传入的参数。使用 $(inherited) 作为令牌，以保留方案中已有的参数（例如，使用 ["$(inherited)", "--reset-state"] 在末尾添加额外参数）。
• environmentVariables — 启动应用时设置的环境变量键值对。使用 "$(inherited)" 作为键，以保留方案中已有的环境变量（例如，{"$(inherited)": "", "DEBUG_MODE": "1"}）。

省略这两个参数，即可保持方案的参数和环境不变。

优先使用这些参数，而不是直接编辑方案。 它们只对本次运行生效，不会改变用户的配置。

---

致子 Agent

务必报告可能由代码导致的 UI 问题：文本重叠或难以辨认、图像／文本意外裁切、颜色错误等。

DeviceEventSynthesize 工具

此工具可执行交互操作并观察设备状态。

读取层级文件

层级文件包含每个元素计算得出的位置：

UIView {{100, 200}, {50, 30}}, center: {125.0, 215.0}
  UIButton "Login" {{110, 205}, {30, 20}}, center: {125.0, 215.0}

• {100, 200} - 原点位置
• {50, 30} - 宽度和高度
• center: {125.0, 215.0} - 计算得出的中心点（最适合点击）

触控事件始终优先使用中心坐标。

交互命令语法

interactionCommand 参数接受以下命令语法：

命令	描述
t <x> <y> [duration]	点击指定坐标，可选设置按住时长
d <x> <y>	双击
t <x1> <y1> f <x2> <y2> [duration]	从 (x1,y1) 滑动到 (x2,y2)
b h/p/u/d [duration]	硬件按钮：h=主屏幕，p=电源，u=音量增大，d=音量减小
sender keyboard kbd <text>	输入文本；必须是命令链中的最后一条命令——kbd 之后的所有内容都会按原样处理（包括保留多个空格）。输入特殊字符时，使用 \u{XXXX} Unicode 转义序列：\u{000A}（回车／换行）、\u{0009}（制表符）
w duration	等待指定时长，不执行任何操作
orientation faceDown/faceUp/landscapeLeft/landscapeRight/portrait/portraitUpsideDown	设置设备方向

示例：

• "t 100 200" - 点击 (100, 200)
• "d 200 300" - 双击 (200, 300)
• "t 200 600 f 200 200 0.3" - 向上滑动（滚动以查看下方内容）
• "t 200 200 f 200 600 0.3" - 向下滑动（滚动以查看上方内容）
• "b h" - 按下主屏幕按钮
• "b h b h" - 连按两次主屏幕按钮，进入应用切换器
• "b h w 0 b h" - 唤醒并解锁设备（仅适用于无需密码的设备）
• "sender keyboard kbd hello world" - 输入带空格的文本
• "sender keyboard kbd hello world" - 输入文本并保留多个空格
• "sender keyboard kbd submit\u{000A}" - 输入文本，然后按回车／提交
• "w 0.3" - 等待 0.3 秒
• "orientation landscapeLeft" - 将设备旋转为横向

标准子 Agent 工作流

每次交互前，务必捕获并读取层级结构（以及截图）。每次交互后，再次捕获并验证结果。对于复杂组件（如切换开关），请查看嵌套元素（如 Switch 或 Slider）——附近的元素可能才是实际控件。完成后，将发现报告给主 Agent。

• 若要在不进行交互的情况下捕获，请使用 DeviceEventSynthesize，并将 interactionCommand 留空。
• 切勿仅凭截图猜测位置——始终使用层级结构中的中心坐标。
• 如果无法确定，或缩略图分辨率不足，请分析全尺寸截图。

计时与重试

• 应用启动：启动会话后，应用可能需要几秒钟才能加载。请捕获层级结构，并检查其中是否包含有意义的 UI 元素，再进行交互。如果层级结构几乎为空，或显示启动画面，请再次捕获后再继续。
• 交互后：如果点击或滑动未产生预期变化，请重新捕获层级结构，并重试一次（元素可能在动画过程中移动）。如果重试一次后仍然失败，请报告问题，不要无限重试。
• 加载状态：如果层级结构显示了微调器或加载指示器，请稍作等待后再次捕获。不要与仍在加载的元素交互。

判断成功与失败

验证时，请区分以下类别：

• 功能缺陷（始终报告）：元素无法响应点击、导航到错误的屏幕、崩溃、未显示数据、缺少预期的 UI 元素。
• 视觉/布局缺陷（始终报告）：文本重叠、标签截断、元素渲染在屏幕外、颜色错误、对齐异常。
• 瞬时状态（不要报告为缺陷）：加载微调器、短暂动画、键盘弹出/收起。请等待过渡完成后再次捕获。
• 意外退出（始终报告）：崩溃、应用退出。请跟踪进程 ID，并捕获进程的标准输出以进行识别。
• 预期行为（不要报告为缺陷）：带有占位文本的空状态、表单未完成时禁用的按钮、权限对话框。

错误处理

• 如果应用不可见，请重试一次，因为这可能是设备运行缓慢所致。
• 如果点击目标不明确，请重新读取层级结构数据，以获取正确的中心坐标。
• 你可以检查运行时日志以排查问题。如果怀疑存在计时问题，可建议主 Agent 暂时在相关代码中添加 print 语句，以帮助诊断问题。
• 向主 Agent 报告问题，并附上详细信息和建议。