企业官网建设流程全解析

• AI 技能
• AI 插件

在 Agentic Awesome Skills 仓库中，android_ui_verification是一个面向 React Native 与原生 Android 应用的端到端 UI 自动化验证技能，它不依赖任何测试框架，仅通过 ADB 命令即可驱动模拟器完成"查看界面 → 计算坐标 → 模拟交互 → 截图与日志验证"的完整闭环。本文将以该技能文档为核心，结合仓库内配套的自动化脚本与其在项目目录、变更日志中的元数据记录，为你讲解这套方法的每一步命令、底层原理与最佳实践，读完即可在本地模拟器上复现 Agent 自主执行 UI 验证的完整工作流。

技能定位与适用场景

android_ui_verification的核心思路是：把 Android 模拟器当作一个可以被命令行完全操控的黑盒，用adb这一 Android 官方调试桥完成"观察状态、执行操作、确认结果"的循环。其 frontmatter 元数据表明该技能为source: community（社区贡献）、risk: safe（安全风险等级为安全），并记录于 CHANGELOG.md，由社区成员 @alexmvie 贡献。

根据 SKILL.md 的定义，该技能适合在以下场景中使用：

• 验证 React Native 或原生 Android 应用的 UI 变更；
• 对布局问题或交互类 Bug 进行自主调试；
• 在人工测试成本过高时，快速确认功能是否正常；
• 为 PR 文档自动捕获界面截图。

它尤其适合需要"无人值守回归"的 Agent 场景——Agent 可以自行启动模拟器、执行命令、保存证据，并把结果整理进 PR 说明。

前置条件

技能运行前需要满足三项基础条件，缺一不可：

1. Android 模拟器正在运行——所有命令都作用在已启动的设备上；
2. adb已安装并加入 PATH——adb是 Android SDK Platform-Tools 的核心命令；
3. 应用以 debug 模式构建——只有 debug 包才会输出ReactNativeJS相关的 JS 控制台日志到logcat，后续的"分析验证"步骤依赖这一点。

提示：可在执行任何操作前先运行adb devices确认设备在线且无unauthorized状态，避免后续命令全部落空。

完整工作流：四步闭环验证

技能文档将整个验证过程划分为四个阶段，从校准设备开始，到输出可归档的证据结束。

1. 设备校准（Device Calibration）

模拟器界面通常会做逻辑分辨率缩放，直接猜测坐标很容易点错位置。因此第一步永远是校准屏幕尺寸：

adb shell wm size

命令会返回类似Physical size: 1080x2400的输出。文档特别强调：布局往往是经过缩放的，必须以此处返回的物理尺寸作为坐标计算基准，而不是想当然地使用 App 内部 DP 单位。

2. UI 检查（State Discovery）

通过uiautomator工具导出当前界面的控件层级，即可拿到所有 UI 元素的精确位置：

adb shell uiautomator dump /sdcard/view.xml && adb pull /sdcard/view.xml ./artifacts/view.xml

uiautomator dump会在设备端生成当前窗口的视图层级 XML（默认也可输出到/sdcard/window_dump.xml），adb pull将其拉取到宿主机的./artifacts/目录归档。随后在view.xml中检索text（文本内容）、content-desc（无障碍描述）或resource-id（资源 ID）来定位目标元素，其中最关键的属性是bounds——它形如[x1,y1][x2,y2]，直接定义了该元素的可点击区域矩形。

这是整个流程的"眼睛"：只有拿到准确的 bounds，后续的点击才能命中。

3. 交互命令（Interaction Commands）

拿到坐标后，用adb shell input系列命令模拟用户操作：

常见 keyevent 码还包括：4（返回键）、3（Home 键）、67（删除/退格）、61（Tab 切换焦点）。这些编码是 Android 框架层KeyEvent.KEYCODE_*常量在input keyevent命令中的十进制表示。

4. 验证与报告（Verification & Reporting）

交互完成后，技能提供"视觉 + 分析"双通道验证，并规定产物统一归档：

视觉验证（截图对比）

adb shell screencap -p /sdcard/screen.png && adb pull /sdcard/screen.png ./artifacts/test_result.png

-p参数指定输出 PNG 格式。截图可被用于人工复核或作为 PR 文档中的界面证据；配合交互前截图，还能进行像素级的视觉回归比对。

分析验证（日志审查）

adb logcat -d | grep "ReactNativeJS" | tail -n 20

实时抓取 JS 控制台输出：-d表示 dump 当前缓冲区后退出而非持续跟踪，grep "ReactNativeJS"过滤 React Native 运行时的日志标签，tail -n 20只保留最近 20 行，用于快速确认操作成功或定位抛错。

清理与归档

所有生成文件（view.xml、截图、日志）必须存放在artifacts/目录，以满足项目的组织规范，也便于 Agent 后续把证据附到提交或 PR 中。

配套脚本：verify_ui.sh 的自动化封装

仓库为该技能提供了可直接调用的辅助脚本 scripts/verify_ui.sh，它将上述手动命令封装成一个原子操作，一次调用即可产出全套验证产物：

# 用法：./verify_ui.sh [截图文件名] ./verify_ui.sh my_test_screen

脚本执行逻辑（与 SKILL.md 文档流程一一对应）：

1. 自动创建./artifacts目录（若不存在）；
2. 执行adb shell wm size完成屏幕校准并打印分辨率；
3. 执行uiautomator dump导出 UI 层级并adb pull到artifacts/view.xml；
4. 执行screencap -p截图并保存为artifacts/<截图名>.png（默认名latest_screen.png）；
5. 抓取最近 20 行ReactNativeJS日志写入artifacts/js_logs.txt。

整个脚本把"校准 → 检查 → 截图 → 日志"串成一行命令，非常适合在 CI 前置脚本或 Agent 工作流中作为"验证前快照采集器"调用，且与文档约定保持完全一致。

最佳实践：让自动化验证更可靠

技能文档总结了四条经过实践检验的经验，直接决定了验证的稳定性与可调试性：

• 等待动画结束：交互与验证之间务必加入 1～2 秒的sleep，避免在页面转场或动画播放中途截图，导致断言误判；
• 点击取中心点：对[x1,y1][x2,y2]计算算术平均值((x1+x2)/2, (y1+y2)/2)作为点击坐标，这是最可靠的目标命中策略；
• 埋设日志标记：在业务代码中使用特征明显的日志（如✅ Action Successful），让grep验证变得一目了然——这也与上文的logcat | grep "ReactNativeJS"一脉相承；
• 快速失败（Fail Fast）：若uiautomator dump失败或找不到预期文本，应立即停下排查（如检查界面是否在异常页面、元素是否被遮挡），而不是盲目盲点。盲目点击会把单点失败扩散成难以定位的连锁问题。

局限性与使用边界

技能文档同样明确了它的边界，使用时应保持清醒：

• 该技能只在任务范围与上述描述明确匹配时使用，不要随意扩大到不相关的场景；
• 自动化产物不能替代面向具体环境的验证、正式测试或专家评审——模拟器通过不代表真机、灰度或生产环境行为一致；
• 当所需输入、权限、安全边界或成功标准缺失时，应停下来向用户确认，而不是擅自猜测继续执行。

此外，从技能元数据（risk: safe）与分类（category: test-automation，见 apps/web-app/public/skills.json.backup）可以看到，它在项目中被归类为安全的测试自动化技能，支持 codex 与 claude 两类 Agent 目标平台。

延伸阅读

• 技能主文档：plugins/agentic-awesome-skills-claude/skills/android_ui_verification/SKILL.md
• 同内容镜像副本：plugins/agentic-awesome-skills/skills/android_ui_verification/SKILL.md
• 配套自动化脚本：plugins/agentic-awesome-skills-claude/skills/android_ui_verification/scripts/verify_ui.sh
• 技能发布记录：CHANGELOG.md
• 全量技能目录索引：CATALOG.md

• AI 技能
• AI 插件