feat: add Android and iOS tester skills

2026-10-11 17:29:04 +08:00
parent cf78d0cab2
commit 1100eec884
13 changed files with 557 additions and 0 deletions
@@ -0,0 +1,34 @@
+# Android 真机路径
+
+## 环境检查
+
+按顺序执行并记录：
+
+```bash
+adb start-server
+adb devices -l
+adb -s <serial> shell getprop ro.product.model
+adb -s <serial> shell getprop ro.build.version.sdk
+adb -s <serial> shell getprop sys.boot_completed
+```
+
+规则：
+
+- 没有设备：`environment-fail`。
+- `unauthorized`：提示用户在手机上授权，不自动绕过。
+- `offline`：停止，不把它当作产品失败。
+- 有多台设备但没有 `ANDROID_SERIAL`：停止，不猜设备。
+- `sys.boot_completed` 不是 `1`：等待有限时间，超时记 `environment-fail`。
+
+## 执行
+
+- 复用用户指定序列号，整轮测试不切换设备。
+- 只执行选中的 `driver: mobile` 用例。
+- 不自动安装 APK；安装必须有 APK、包名和明确的 mutating 授权。
+- 测试失败时收集目标设备的 logcat 尾部和当前屏幕截图。
+
+## 收尾
+
+- 不关机、不重启、不清除应用数据。
+- 停止由本轮启动的 ADB server 之前要确认没有其他测试会话依赖它。
+- 设备保留原状态，并在结果中记录。
@@ -0,0 +1,33 @@
+# Android 模拟器路径
+
+## 环境检查
+
+执行：
+
+```bash
+emulator -accel-check
+emulator -list-avds
+```
+
+必须同时满足：
+
+- KVM 可用。
+- 指定 AVD 存在。
+- AVD 的 system image 与 x86_64 主机匹配。
+- 没有被 VirtualBox、VMware 或 Docker 等外层虚拟化阻断。
+
+## 启动与等待
+
+- 如果目标 AVD 已运行，检查序列号和 AVD 名称后复用。
+- 如果没有运行，启动用户指定的 AVD，不创建替代 AVD。
+- 使用 ADB 等待设备出现，并等待 `sys.boot_completed=1`。
+- 启动失败、启动超时或 KVM 失效都记为 `environment-fail`。
+- 无桌面服务器时可使用 `-no-window -no-audio`，但必须先确认测试不需要可视化交互。
+
+## 执行与收尾
+
+- 一轮测试只绑定一个 AVD。
+- 需要安装 APK 或清数据时按 mutating 规则处理。
+- 测试失败时保存 logcat、模拟器信息和截图。
+- 只关闭本轮由 skill 启动且配置为临时会话的模拟器。
+- 不删除 AVD、不修改系统镜像、不覆盖用户已有配置。
@@ -0,0 +1,45 @@
+# Android 通用环境检查
+
+本文件只读检查，不安装软件、不修改设备。
+
+## 项目检查
+
+1. 确认项目根目录。
+2. 确认 `.pouch/tester/catalog.yaml` 存在且 `validate` 通过。
+3. 只选择 `driver: mobile` 的用例。
+4. 读取 `.pouch/tester/local.yaml`；缺少 Android 目标配置时停止，不猜目标。
+
+推荐的本地配置字段：
+
+```yaml
+ANDROID_TARGET_MODE: device
+ANDROID_SERIAL: ""
+ANDROID_AVD: ""
+ANDROID_PACKAGE: ""
+ANDROID_APK: ""
+ANDROID_ACTIVITY: ""
+```
+
+## 主机检查
+
+- `uname -m` 必须是 `x86_64`。
+- `adb` 必须可执行。
+- 模拟器路径还必须有 `emulator`、`sdkmanager` 和 KVM。
+- 记录 Android SDK 根目录、工具版本和当前用户。
+
+未安装工具属于 `environment-fail`。不要在普通测试运行中顺手安装；安装只能进入
+明确的 Debian 安装模式。
+
+## 运行前报告
+
+先报告：
+
+```text
+目标: 真机 | 模拟器
+项目测试目录: 已找到 | 缺失
+ADB: 通过 | 缺失
+模拟器工具链: 通过 | 缺失 | 不适用
+KVM: 通过 | 缺失 | 不适用
+目标设备: 已解析 | 未解析
+结论: 可执行 | environment-fail
+```
@@ -0,0 +1,95 @@
+# Debian 安装 Android 模拟器
+
+只支持 Debian amd64/x86_64。不要在 Ubuntu、其他发行版、ARM 主机或嵌套虚拟机中执行
+本流程。Android 官方 Linux 模拟器依赖 KVM；Android SDK Command-line Tools 提供
+`sdkmanager`，Emulator 和 Platform-Tools 作为 SDK 包安装。
+
+## 1. 检查并确认变更
+
+读取 `/etc/os-release`，必须满足：
+
+```bash
+test "$(. /etc/os-release && printf '%s' "$ID")" = debian
+test "$(dpkg --print-architecture)" = amd64
+```
+
+安装前向用户展示：
+
+- 将通过 apt 安装的 Debian 包。
+- Android SDK 目录，默认 `~/Android/Sdk`。
+- 要下载的 Emulator、Platform-Tools、Command-line Tools 和 system image。
+- 会把当前用户加入 `kvm`、`libvirt` 组，通常需要重新登录。
+- 是否创建 AVD，以及 AVD 名称、API、镜像和设备 profile。
+
+没有明确安装请求或用户未确认这些变更时，只输出检查结果，不执行 sudo、apt 或下载。
+
+## 2. 安装 Debian 主机依赖
+
+在用户确认后安装：
+
+```bash
+sudo apt update
+sudo apt install cpu-checker qemu-kvm libvirt-daemon-system \
+  libvirt-clients bridge-utils curl ca-certificates unzip
+sudo usermod -aG kvm,libvirt "$USER"
+```
+
+检查：
+
+```bash
+kvm-ok
+ls -l /dev/kvm
+```
+
+若没有硬件虚拟化或 `/dev/kvm`，停止并报告安装失败。不要降级为极慢的软件模拟。
+
+## 3. 安装 Android SDK 工具
+
+优先使用 Android 官方 Linux Command-line Tools。若机器已有 `sdkmanager`，复用现有
+SDK 根目录；否则从 Android 官方下载页获取 Linux Command-line Tools，解压为：
+
+```text
+~/Android/Sdk/cmdline-tools/latest/
+```
+
+安装并接受 SDK 许可后，执行：
+
+```bash
+sdkmanager --install \
+  "platform-tools" \
+  "emulator" \
+  "cmdline-tools;latest"
+```
+
+系统镜像由项目的 compile/target SDK 和用户明确选择的 API 决定。安装前先用
+`sdkmanager --list` 查找可用的 `google_apis;x86_64` 镜像，不猜一个不可用的版本。
+
+## 4. 创建 AVD
+
+只有用户明确要求创建 AVD 时执行。优先使用当前 SDK 提供的 Android CLI；兼容环境可
+使用 `avdmanager` 创建一个明确命名、明确 API 和明确 x86_64 镜像的 AVD。创建后运行：
+
+```bash
+emulator -list-avds
+emulator -accel-check
+emulator @<已确认的AVD名称>
+```
+
+`<已确认的AVD名称>` 只表示用户已经选择的实际名称，不允许由 skill 静默猜测。
+
+## 5. 安装完成报告
+
+报告必须包含：
+
+- Debian 版本和架构。
+- apt 安装包及结果。
+- SDK 根目录和工具版本。
+- 已安装的 system image。
+- AVD 名称和配置。
+- KVM 检查结果。
+- 是否需要重新登录。
+- 下一步是运行模拟器检查，还是直接执行测试。
+
+安装 Android Studio 不是本模式的必要条件；该流程安装的是可由命令行运行的 Emulator
+工具链。参考：[Android 安装文档](https://developer.android.com/studio/install)、
+[KVM 加速文档](https://developer.android.com/studio/run/emulator-acceleration)。
@@ -0,0 +1,29 @@
+# Android 结果报告
+
+每轮运行都生成 `.pouch/tester/runs/<run-id>.yaml` 和同名 `.csv`。附加证据放在同名
+目录中，不覆盖已有 run。
+
+对话报告格式：
+
+```text
+## android-tester 运行：完成 | 部分完成 | 阻塞
+
+路径: 真机 | 模拟器
+目标: 序列号/型号/API 或 AVD/API
+环境: 通过项；阻塞项
+计数: pass=N fail=N environment-fail=N skipped=N not-run=N
+失败: 用例 id + 一句证据
+跳过: 用例 id + 原因
+证据: logcat / 截图目录
+快照: .pouch/tester/runs/<run-id>.yaml
+成绩单: .pouch/tester/runs/<run-id>.csv
+下一步: 一句话
+```
+
+判定规则：
+
+- 工具缺失、设备不可用、启动超时：`environment-fail`。
+- 产品断言不满足：`fail`。
+- 风险未授权、用例主动不跑：`skipped`。
+- 失败即停后没有轮到的用例：`not-run`。
+- 不能把 ADB 命令退出码为 0 直接当成产品通过，必须对照用例的 `expected`。