| name | perf-auto-test |
| description | 对 Android APK 做性能测试、跑 CPU/内存监控、压测期间抓取性能数据时使用。给定包名，连接安卓设备/模拟器后自动采集 CPU 和内存指标，超阈值自动 dump 现场，测试结束后输出性能总结并弹出网页图表报告。 |
| when_to_use | 用户说"帮我跑性能测试"、"测一下这个 APK 的内存"、"监控 CPU 使用率"、"压测期间跑 perf"、"跑 perf-auto-test"时触发。 |
| argument-hint | <package> [duration] [--device serial] [--config path] [--output dir] |
perf-auto-test
参数解析
从 args 或对话上下文中提取。只有 --package 是必填的，其余均有代码默认值。
| 参数 | 说明 | 默认值 |
|---|
--package | 目标 APK 包名（必填） | — |
--duration | 采集时长，如 30s、5m、1h | 5m |
--output | 报告输出目录（不填时自动生成） | ./reports/<包名末段>_<YYYYMMDD_HHMMSS> |
--device | ADB serial（多设备时必填） | 自动取唯一在线设备 |
--config | YAML 配置路径（覆盖阈值等） | — |
--cpu-threshold-percent | CPU% 报警阈值（单核归一化，4核全满=400%） | 80 |
--mem-threshold-pss-mb | 内存 PSS MB 报警阈值 | 500 |
采样间隔、cooldown、dump 上限、输出格式等进阶参数均在代码中有默认值，需要时可通过 --config YAML 覆盖，见 ${CLAUDE_SKILL_DIR}/scripts/config.example.yaml。
简写识别：/perf-auto-test com.example.app 5m → --package com.example.app --duration 5m
步骤 1：环境检查
python -m pat --help
若报 ModuleNotFoundError，安装依赖后重试：
pip install -e ${CLAUDE_SKILL_DIR}/scripts
若 adb devices 为空，提示用户连接设备或启动模拟器后再试。
步骤 2：确认参数
若 --package 缺失，询问用户目标包名。
若 --output 未指定，自动生成：./reports/<包名末段>_<YYYYMMDD_HHMMSS>
确认后告知用户：
开始对 <package> 进行 <duration> 性能采集，输出至 <output_dir>…
步骤 3：执行采集
在 perf_auto_test/scripts/ 目录下执行：
python -m pat \
--package <package> \
--output <output_dir> \
--duration <duration> \
[--device <serial>] \
[--config <config_path>] \
[其他可选参数]
在前台执行，实时显示日志。采集期间 <output_dir>/status.json 每 10 秒刷新一次心跳。
步骤 4：弹出报告 + 输出总结
采集命令结束后，先弹出网页报告，再输出文字总结。
4.1 弹出网页报告
open <output_dir>/report.html
4.2 读取数据
读取 <output_dir>/report.json，提取以下字段：
run：时长、退出原因、设备信息processes[*]：stats.cpu_pct（mean/p95/max）、stats.mem_pss_mb（mean/max）、alerts、restart_countincidents[]：触发时间、进程名、类型、observed vs thresholdlifecycle_events[]：new / gone / restart 事件
4.3 输出性能总结
总结要简短、有逻辑、有结论，格式如下：
性能测试总结 — <package>（<duration>）
整体状态：正常 / ⚠️ 有报警 / 🔴 异常（一句话说明）
进程概览
| 进程 | CPU均值 | CPU P95 | CPU峰值 | 内存均值 | 内存峰值 | 报警 | 重启 |
|---|
报警 & 异常事件（无则省略此节）
- 逐条列出：时间 — 进程 — 类型 — 观测值 vs 阈值
结论
一到两句话：是否存在性能问题、最需要关注的点是什么。
详细图表和 dump 文件见已弹出的 report.html
总结不要罗列所有字段，不需要重复网页报告里的完整数据——只给出判断和关键数字。
命令行直接调用参考
以下命令在 perf_auto_test/scripts/ 目录下执行。
python -m pat --package com.example.app --duration 5m --output ./reports/run01
python -m pat --config config.example.yaml --package com.example.app --output ./reports/r1
python -m pat --package com.android.settings --duration 30s --output ./reports/smoke
完整参数：python -m pat --help
