跳转至

Android 设备与 UI

只读诊断

inspect_android_environment 返回系统/API/ABI、命令可用性、内存和 /data 容量，不安装软件。inspect_android_app 查询指定或前台应用的 Activity、进程、内存、版本和位置。android_dumpsys、android_logcat、android_settings、android_content_query 接受受限参数，不提供写设置、service call 或 ContentProvider 写入。

还提供通知、Crash/ANR、温控/功耗、流量、存储、Wi-Fi/以太网、Doze、权限与连接性聚合。android_background_work 要求精确包名，同时返回有界的 JobScheduler、AlarmManager、应用待机分组和 DeviceIdle 证据，用于排查后台任务延迟或未唤醒；结果不证明任务必然执行，也可能看不到 OEM 省电策略。默认有界定向查询；超时后先缩小范围。android_connectivity 的 ping 成功不代表 HTTPS 下载成功。

只读诊断使用当前进程身份，以非交互捕获模式运行，即使 Shell 配置了 root 模式。android_dumpsys 只接受经过审核的查询形式；android_logcat 接受标签/优先级过滤规则，不接受命令选项。原始 Shell 中未知或修改性的 dumpsys/logcat 选项要求强确认。独立诊断可并发执行，取消时等待子进程回收。

界面闭环

先 android.screen_dump 获取有界节点，再按真实包名、文字、资源 ID 或 bounds 选择动作；android.tap_text / android.tap_node 在确认后重新核对身份。部分树不能证明语义目标唯一，会拒绝点击。

android.launch_app 解析包内 MAIN/LAUNCHER 组件后启动；android.stop_app、android.tap、android.swipe、android.scroll、导航和输入属于需确认的操作。android.scroll 可省略坐标并默认向下，direction: "up" 向上。操作后重新读取界面并检查 success，不要从点击命令退出码推断业务完成。

无 companion 时 android.input_text 只接受可打印 ASCII；Unicode 和实时 Accessibility 树见 Android Bridge。完整 UI 能力要求 shell/root，普通 Termux UID 不支持。

inspect_android_ui / inject_android_input 提供原有 bounds 校验入口；输入准备前和执行前重新读取树，坐标必须仍在匹配且可用节点内。

电视焦点导航

优先使用 inspect_android_ui 的默认紧凑模式（full: false）。结果在节点列表前提供 navigation：当前焦点节点、该节点及其 XML 子孙的文字/描述（每个焦点最多 16 条）、可见标签（最多 40 条）和各自截断标记。节点增加 focusable、selected、enabled、scrollable；未上报的属性为 null。焦点容器可能没有自身文字；多条子孙标签不代表唯一可点击目标，不能从相邻节点或屏幕坐标猜标签。空树即使命令退出码为零也报告失败；摘要 complete 只表示当前树读完整，不证明页面目标不存在或业务完成。

按实际可见标签优先选择 android.tap_text / android.tap_node；必须遥控导航时，每次方向键后重新观察焦点，再决定下一步。不要把猜测的多次方向键和确认键合并执行，进入、确认前先核对包名和焦点文字。仅查找信息时不要激活恢复默认、清除、出厂重置或升级。原始 Shell 的 input 与 cmd input 都按 Dangerous 强确认，包括方向键、Enter/OK、点击和文本注入；只读包查询不受此规则影响。

用户指定信息来源或操作路径时，按该要求查证并注明实际来源；没有证据时，不把不同来源的同名字段视为等价。回答保持在用户请求的范围内。

截图与视觉

android.screenshot / android.read_screen 无路径时用私有临时目录返回图片附件；指定持久路径需确认。capture_android_screen 确认后写指定 PNG。view_screenshot 支持 PNG/JPEG/WebP，必要时缩放并转 JPEG，附件不保存进会话。需要支持视觉的模型；MediaStore 的时间/尺寸不是画面证据。

例子：“查看最近的 ANR 并列出日志证据，不重启应用”；“读当前界面，解释搜索框位置，等待我确认后再输入”。所有参数见 目录。

Bridge 协议 v2 使用单一 base64url JSON payload，带协议版本与请求 ID；支持旧伴侣的逐方法调用。 v2 动作失败或回复 ID 不匹配时不会回退重放。原有审批、目标身份复核与 shell/root 边界继续生效。

系统性能 Trace

按 start_system_trace → stop_system_trace → analyze_system_trace 使用。开始和停止都需要修改确认，分析只读；不安装 Perfetto、不自动提权。采集要求设备 /system/bin/perfetto 和服务中的 linux.ftrace 可用，通常需要 Android shell/root；API 26+ 可运行 nl2sh 不代表设备一定提供 Perfetto。普通 Termux 应用 UID 不提供采集入口。

Agent 内调用 start_system_trace 成功后，运行时会登记绑定当前任务的后台分析，释放等待期间的 Android UI 租约，并在自动结束截止时间（包含 5 秒收尾余量）到达后通过正常工具准备与安全链调用 analyze_system_trace，随后请求模型给出结论。TUI/Web 显示“等待后台任务，完成后自动继续”；后台等待计入任务时限，续跑工具计入工具预算，模型步骤预算不重置。取消、预算耗尽或进程退出会撤销续跑；已启动的 Perfetto 采集继续按自身时限/文件上限停止，Trace 文件保留。运行时不会因取消自动批准停止操作，也不会在重启后重放旧任务。直接工具调用没有 Agent 续跑所有者，返回 background_analysis_scheduled: false，必须显式调用分析。若到期检查仍在采集或分析失败，结果会明确反馈给模型，不宣称已完成分析。

示例参数（开始后在设备上复现卡顿，再停止）：

{"package":"com.example.app","duration_secs":30,"buffer_mb":8}

开始返回 trace_id；后两步都用 {"trace_id":"返回的 ID"}，分析可加 package 或 pid（二选一），以及 threshold_ms: 50、frame_budget_ms: 16.667。刷新率为 120 Hz 时可把帧预算设为约 8.333 ms。也可只读分析已存在的外部原始 protobuf 文件：{"path":"/data/local/tmp/example.pftrace","pid":1234}。路径不接受符号链接，压缩 Trace 和通用 TrackEvent 不在支持范围内。

采集固定请求调度、唤醒、Binder 和 gfx/view atrace；探测到时才加入进程元数据与 android.surfaceflinger.frametimeline。使用二进制 Perfetto 配置并关闭 compact_sched，不接受模型提供的配置或命令。时长默认 10 秒、最多 120 秒，缓冲默认 8 MiB、最多 32 MiB，文件最多 64 MiB。Perfetto 服务持有会话并在到期或文件上限时自动结束，允许跨 nl2sh 进程停止；只停止本工具创建的随机会话，不向任意 PID 发信号。主动采集中不能用 trace_id 分析。私有元数据保存在配置对应状态目录的 system-traces/，protobuf 文件由 Perfetto 以 0600 创建在系统允许的 /data/misc/perfetto-traces/nl2sh-<trace_id>.pftrace（受 Android SELinux 约束，不能直接写入任意应用目录）。最多保留 16 次；旧证据及对应元数据需用户显式删除，不上传。包过滤只限制应用 atrace，系统调度/Binder 仍全局采集，可能包含敏感名称。

报告列出覆盖计数、目标 PID、阈值、各类异常计数与最多 50 条例证，以及最多 30 个线程的运行/等待/唤醒摘要：

  • 主线程：只计算 wakeup 或可运行抢占到下一次调度的长等待，排除正常睡眠；不是 ANR 诊断。
  • RenderThread：长可运行等待与长 atrace 切片；缺少线程身份时不会猜测。
  • 帧：Choreographer#doFrame 超帧预算仅是长回调证据；旧格式 FrameTimeline 的 late/drop/jank 标志单独报告，不把两者当成唯一掉帧数。
  • Binder：同 debug_id 的发送到接收延迟，不包括处理或同步回复往返。
  • CPU：长可运行等待与观测窗口内至少 100 次/秒的唤醒启发式，不等同功耗测量或已证明根因。

Rust 解析最多 64 MiB、10 万 packet、50 万事件、32768 个线程，单 packet 4 MiB；超限和损坏数据拒绝分析。跨 CPU 按时间排序；丢失标志清空配对状态，非 boot 时钟、压缩、compact_sched 和新版 TrackEvent FrameTimeline 标记为未支持/部分证据。未配对、边界未完成区间被排除；空结果或缺失数据源不能证明设备健康。完整参数见工具目录。

UI 操作后置条件

android.launch_app、android.stop_app、点击、输入、滑动、滚动及返回/Home/Enter 支持可选 verification。省略时保持原结果格式和调用行为；所有动作继续经过原审批与目标复核，验证只读且不重放动作。

{"text":"搜索","verification":{"verify_change":true,"expected_package":"com.example.app","text_present":"结果","text_absent":"加载中","timeout_ms":2000}}

字段可组合，至少指定一项检查：verify_change 比较审批后、动作执行前与执行后的完整 UI 树；expected_package 要求当前焦点窗口属于精确包名；text_present / text_absent 匹配精确文字或内容描述。超时默认 2000 ms，范围 100–10000 ms；基线读取与动作后观察分别使用该预算；较慢的 shell UI 读取可显式提高超时，基线不跨人工审批保存。验证期间轮询且不自动滚动。

结果包含 action_sent、原 action_result 和 verification 中的 ui_changed、expectation_met、逐项结果、observation_complete、passed。observation_complete 仅表示取得完整 UI 树；单独验证焦点包名时不读取树，该字段为 false。未请求或无法验证的布尔值为 null；全部请求的检查满足才报告工具成功。验证超时、条件不满足或部分/失败树会报告工具失败，但 action_sent: true 表示动作已发送一次，失败不撤销动作，重试前应重新观察。UI 变化不等于业务成功，文字缺失仅针对完整当前视口，不证明屏幕外或其他窗口不存在目标。

定向日志时间窗口

android_logcat 增加 since_secs（1–3600 秒）、package 或 pid（二选一），保留 lines（最多 500）和标签/优先级 filter。时间窗口使用设备时间与时区，不依赖控制端时钟，不清除缓冲区或修改设备。

{"package":"com.example.app","since_secs":120,"lines":200,"filter":"MyTag:D *:S"}

包名解析到当前唯一主进程 PID；不存在或不唯一时失败，不回退读取全局日志。子进程和已重启进程可能遗漏，需要明确 PID 或另行采集。时间窗口返回起点之后最多指定数量的匹配条目，达到限额会标记 limit_reached，不保证覆盖整个窗口。返回设备截断时间、实际 PID、范围及限额；默认对常见凭据赋值和 Authorization 等头部做尽力脱敏。没有匹配日志不能证明没有故障，脱敏也不保证识别所有敏感信息。