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,51 @@
 # android-tester
 在 Android 真机或 Debian Linux Android 模拟器上执行测试；每次先检查环境，最后生成可追溯的测试结果。
 ## 什么时候使用
 - 「检查 Android 真机测试环境」
 - 「检查 Debian Android 模拟器环境」
 - 「用真机跑 Android smoke」
 - 「用 AVD 跑 Android full」
 - 「安装 Debian 上的 Android 模拟器」
 - 「查看本次 Android 测试结果」
 ## 使用前准备
 - 项目已有 `.pouch/tester/` 和测试用例。
 - 真机：开启 USB 调试并在设备上授权当前电脑。
 - 模拟器：准备支持虚拟化的 Debian amd64 主机；首次使用可让 skill 安装 KVM、SDK
  Command-line Tools、Platform-Tools、Emulator 和指定系统镜像。
 - 需要安装或启动应用时，提供 APK、包名和启动组件，或提供项目自己的测试命令。
 - 安装模式会使用 sudo、apt 和用户组变更；运行前会先展示变更范围。
 ## 使用示例
 ```text
 检查 Android 真机环境，然后跑 smoke 测试
 ```
 ```text
 在 Debian 上安装 Android 模拟器，使用项目需要的 Android API 创建 AVD
 ```
 ```text
 用 Pixel_API_35 模拟器跑 Android full，失败时保留 logcat 和截图
 ```
 ## Agent 会做什么
 1. 明确选择真机或模拟器，不在两者之间自动切换。
 2. 先检查 ADB、KVM、AVD、设备授权、启动状态和项目测试配置。
 3. 模拟器路径可在 Debian amd64 上安装主机依赖和 Android SDK 模拟器组件。
 4. 执行 `.pouch/tester/` 中命中的 Android 用例。
 5. 生成 YAML 运行快照、CSV 成绩单，失败时附带 logcat 和截图。
 安装、安装 APK、清数据和修改设备设置都属于有副作用的操作，必须得到明确授权。
 ## 如何判断完成
 - 环境检查有明确的通过项和阻塞项。
 - 每条用例都有 `pass`、`fail`、`environment-fail`、`skipped` 或 `not-run` 结果。
 - 运行记录位于 `.pouch/tester/runs/`，且 YAML 与 CSV 的 run id 一致。
@@ -0,0 +1,56 @@
 ---
 name: android-tester
 description: >-
  检查并运行 Android 真机或模拟器测试；支持 Debian amd64 上安装
  Android Emulator、KVM 依赖、SDK 工具和 AVD。触发词：Android 测试、安卓测试、
  真机测试、Android 模拟器、AVD、ADB、安装安卓模拟器、检查 Android 环境。
 ---
 # Android Tester
 项目根是 `git rev-parse --show-toplevel`。本 skill 复用项目已有的
 `.pouch/tester/` 用例和运行记录，不创建第二套测试目录。
 ## 模式路由
 - 用户要求安装或配置 Android 模拟器：先读 `references/install-debian.md`。
 - 用户要求检查环境：先读 `references/environment.md`，再按目标读 `device.md` 或
  `emulator.md`。
 - 用户要求用真机测试：目标固定为 `device`，读 `device.md`。
 - 用户要求用模拟器测试：目标固定为 `emulator`，读 `emulator.md`。
 - 用户要求报告结果或复盘失败：读 `references/reporting.md`。
 ## 全局硬规则
 - 每次运行测试前必须重新检查环境；检查失败记为 `environment-fail`，不伪装成产品失败。
 - 真机与模拟器必须由用户明确选择，禁止自动 fallback。
 - 运行范围和结果语义遵循 `tester`：默认 smoke、默认 readonly，使用
  `pass/fail/environment-fail/skipped/not-run`。
 - 不自动构建 APK；只使用项目提供的测试命令或已有 APK。
 - 安装 APK、清除数据、授予权限、修改设备设置属于 mutating，必须有明确授权。
 - 不自动清空真机、重启真机、创建或删除未知 AVD。
 - Debian 安装模式只接受 `ID=debian` 且 `amd64/x86_64`；Ubuntu、其他发行版、ARM
  主机必须停止并说明不在第一版范围内。
 - 没有 `.pouch/tester/catalog.yaml` 时，不静默初始化，提示用户先初始化 `tester`。
 ## 运行顺序
 1. 解析测试范围和目标模式。
 2. 检查 `.pouch/tester/`、本地配置和工具链。
 3. 检查真机或模拟器目标是否可用。
 4. 必要时只启动本轮自己创建的模拟器会话。
 5. 按 tester 用例顺序执行测试。
 6. 失败时采集 logcat 和截图，生成 YAML/CSV 运行记录。
 7. 按 `references/reporting.md` 输出结果，并执行目标会话的安全收尾。
 ## 安装安全边界
 安装模式会运行 `apt`、修改用户组、下载 Android SDK 文件并可能创建 AVD。只有用户
 明确要求安装时才执行；执行前先列出包、下载目录、SDK 镜像和需要重新登录的事项。
 不要把 sudo 密码、账号或第三方 token 写入文件或输出。
 ## 验证
 - `pouch check android-tester` 通过。
 - Debian 安装后 `kvm-ok` 和 `emulator -accel-check` 通过。
 - 真机和模拟器各完成一条 readonly smoke 用例，并分别生成运行快照和成绩单。
@@ -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`。
@@ -0,0 +1,46 @@
 # ios-tester
 检查并执行 iOS 真机或 Xcode Simulator 测试；在 Linux 上明确报告官方 Simulator 不可本地运行，并支持远程 Mac/云设备入口。
 ## 什么时候使用
 - 「检查 iOS 测试环境」
 - 「用 iPhone 真机跑测试」
 - 「用 iOS Simulator 跑 smoke」
 - 「在远程 Mac 上跑 iOS 测试」
 - 「报告本次 iOS 测试结果」
 ## 使用前准备
 - 本地 Simulator 或真机测试需要 macOS、Xcode 和对应平台组件。
 - 真机还需要设备配对、Developer Mode、签名和 Provisioning Profile。
 - Linux 上不能安装 Apple 官方 Simulator；需要提供远程 Mac、macOS CI 或云真机入口。
 - 项目需要提供 Xcode scheme、workspace/project、destination 和测试命令。
 ## 使用示例
 ```text
 检查当前机器是否可以跑 iOS Simulator
 ```
 ```text
 用 iPhone 15 真机跑 iOS smoke，并保留 xcodebuild 日志
 ```
 ```text
 在远程 Mac 上运行 iOS 测试，最后给出 pass/fail/environment-fail 结果
 ```
 ## Agent 会做什么
 1. 先判断当前是 macOS、本地 Linux、远程 Mac 还是云设备路径。
 2. 检查 Xcode、Simulator runtime、设备配对、签名和测试命令。
 3. 环境完整后执行测试；环境不完整时停止，不将阻塞误报为产品失败。
 4. 采集测试日志、失败诊断和可用的截图或测试产物。
 5. 生成包含目标、环境、用例结果和证据路径的运行报告。
 ## 如何判断完成
 - 有明确的目标路径和环境检查结论。
 - 每条测试都有标准结果状态。
 - macOS/远程执行有日志和产物；Linux 本地不可行时有清晰的修复建议。
@@ -0,0 +1,45 @@
 ---
 name: ios-tester
 description: >-
  检查并运行 iOS 真机或 Xcode Simulator 测试，生成可追溯结果；支持 Linux 上识别
  不可本地运行 Simulator 的边界，并通过 macOS 或远程 Mac 执行。触发词：iOS 测试、
  苹果测试、iPhone 真机、iOS Simulator、Xcode 测试、远程 Mac 测试。
 ---
 # iOS Tester
 本 skill 负责 iOS 测试环境判定、测试执行编排和结果报告，不伪造 Linux 上不存在的
 iOS Simulator。项目根是 `git rev-parse --show-toplevel`。
 ## 模式路由
 - 用户要求检查环境：先读 `references/environment.md`。
 - 用户要求真机测试：读 `references/device.md`。
 - 用户要求 Simulator 测试：读 `references/simulator.md`。
 - 用户要求远程 Mac 或云设备：先读取对应目标配置，再按同一环境/执行/报告闭环。
 - 用户要求结果或失败复盘：读 `references/reporting.md`。
 ## 全局硬规则
 - 每次执行前必须检查环境；环境不完整记 `environment-fail`。
 - 真机、Simulator、远程 Mac 必须由用户明确选择，禁止自动 fallback。
 - Linux 本机不能安装或运行 Apple 官方 iOS Simulator；不能把 Android 模拟器或浏览器
  结果冒充 iOS 结果。
 - macOS/Xcode 是本地 iOS Simulator 和完整 iOS 真机开发测试的官方工具链。
 - 不自动申请 Apple Developer 账号、签名证书、Provisioning Profile 或设备授权。
 - 不清除真机数据、不重启真机、不修改 Apple 账号或钥匙串。
 - 结果使用 `pass/fail/environment-fail/skipped/not-run`，并区分环境阻塞与产品失败。
 ## 运行顺序
 1. 明确目标：local-device、local-simulator、remote-mac 或 cloud-device。
 2. 检查 Xcode、Simulator runtime、设备配对/签名和项目测试配置。
 3. 只有环境通过后才构建、安装或运行测试。
 4. 采集 xcodebuild、设备/Simulator 日志和失败证据。
 5. 生成运行快照、成绩单和结果总结。
 ## 验证
 - `pouch check ios-tester` 通过。
 - macOS Simulator 和物理设备各完成一条 readonly 测试，或在 Linux 上明确得到
  Simulator 不可用的 `environment-fail` 报告。
@@ -0,0 +1,28 @@
 # iOS 真机路径
 ## 环境检查
 在 macOS 上确认：
 - 设备通过 USB 或网络连接。
 - 设备已在 Xcode/Device Hub 中配对。
 - Developer Mode 已开启。
 - Xcode 能看到设备并将其作为 run destination。
 - 项目签名、Team、Provisioning Profile 和设备支持版本完整。
 Linux 上的 `libimobiledevice` 之类工具最多用于有限的设备识别或文件操作，不能替代
 Xcode 的完整构建、签名、安装和 XCTest 链路。没有远程 Mac 时，不把有限识别结果报告为
 完整 iOS 测试环境通过。
 ## 执行
 - 使用项目明确提供的 `xcodebuild test` 或等价测试命令。
 - destination 必须绑定已检查的设备，不在多台设备中猜目标。
 - 安装、签名、修改设备设置属于有副作用的操作，必须明确授权。
 - 测试失败时保留 xcodebuild 日志、测试报告和设备诊断信息。
 ## 收尾
 - 不重启、抹掉或清除真机数据。
 - 不移除配对、不修改钥匙串和签名配置。
 - 报告设备型号、系统版本、destination 和签名状态。
@@ -0,0 +1,34 @@
 # iOS 通用环境检查
 ## 目标判定
 先明确以下之一：
 - `local-device`：当前 macOS 连接的 iPhone/iPad。
 - `local-simulator`：当前 macOS 的 Xcode Simulator。
 - `remote-mac`：用户提供的远程 Mac 执行命令或 CI 入口。
 - `cloud-device`：用户提供的云设备执行入口。
 Linux 本机不是有效的 `local-simulator`。若用户要求在 Linux 本机跑 Simulator，应停止
 并记为 `environment-fail`，同时说明需要 Mac 或远程 Mac。
 ## macOS 检查
 ```bash
 xcode-select -p
 xcodebuild -version
 xcrun simctl list devices available
 ```
 还要确认：
 - Xcode 版本与项目部署目标兼容。
 - 对应 iOS Simulator runtime 已安装。
 - workspace/project、scheme 和 destination 存在。
 - 测试所需的签名和开发团队配置存在。
 ## Linux 检查
 Linux 只能作为测试编排端或远程执行端。不要安装所谓的“Linux iOS Simulator”，也不
 使用 Android Emulator 代替。若使用远程 Mac，检查用户提供的连接/执行入口，不在 skill
 中保存 SSH 密码、Apple 账号或云平台 token。
@@ -0,0 +1,28 @@
 # iOS 结果报告
 每次运行生成项目约定的运行快照和成绩单；如果项目已接入 `.pouch/tester/`，复用其
 `runs/<run-id>.yaml` 与 `.csv`，否则使用项目指定的报告目录，不覆盖已有结果。
 对话报告格式：
 ```text
 ## ios-tester 运行：完成 | 部分完成 | 阻塞
 路径: local-device | local-simulator | remote-mac | cloud-device
 目标: 型号/系统版本/destination
 环境: 通过项；阻塞项
 计数: pass=N fail=N environment-fail=N skipped=N not-run=N
 失败: 用例或测试名称 + 一句证据
 产物: xcodebuild 日志、测试报告、截图或诊断包
 快照: <运行快照路径>
 成绩单: <成绩单路径>
 下一步: 一句话
 ```
 判定规则：
 - 没有 Xcode、runtime、设备配对、签名或远程执行入口：`environment-fail`。
 - 产品断言或 XCTest 失败：`fail`。
 - 未授权的安装、签名或数据修改：`skipped`。
 - 失败即停后未执行的测试：`not-run`。
 - Linux 本地要求 Simulator 时，明确写出“官方 Simulator 不支持 Linux 本机运行”。
@@ -0,0 +1,33 @@
 # iOS Simulator 路径
 ## 硬边界
 Apple 官方 Simulator 随 Xcode 提供并运行在 Mac 上。Linux/Debian 不能本地安装官方
 iOS Simulator，因此 Linux 本机只能转发到远程 Mac、macOS CI 或云设备。
 ## macOS 环境检查
 ```bash
 xcode-select -p
 xcodebuild -version
 xcrun simctl list runtimes
 xcrun simctl list devices available
 ```
 必须存在：
 - Xcode。
 - 与项目兼容的 iOS Simulator runtime。
 - 用户指定的设备类型和系统版本。
 - 可用的 workspace/project、scheme 和 destination。
 若 runtime 缺失，可在用户明确要求安装时使用 Xcode 的 Components 设置或
 `xcodebuild -downloadPlatform iOS` 下载。该安装只能发生在 macOS，不属于 Debian 安装
 能力。
 ## 执行与收尾
 - 启动并等待指定 Simulator 完成 boot。
 - 只执行目标 scheme 的测试，不将 Simulator 结果外推为真实设备硬件结论。
 - 失败时保留 xcodebuild 输出、Simulator 日志和截图/测试产物。
 - 只关闭本轮由 skill 启动且配置为临时会话的 Simulator。