android-performance-tool

通过本地网页调用 ADB 采集 Android 数据，或通过 HDC 与 SmartPerf 采集 HarmonyOS 应用 FPS、PSS 和后台内存。界面展示每条命令、结果摘要、耗时和原始返回，数据保存在本机。

运行

需要 Node.js 22 或更新版本、浏览器和 Android Platform Tools 的 ADB。HarmonyOS 设备还需要 DevEco Studio 提供的 HDC 和设备上的 SmartPerf daemon。手机开启调试并完成授权。仅使用 Node.js 内置模块，无需 npm install，不依赖 Python。

adb devices -l
npm start

也可以直接执行 node android-performance-tool.mjs。打开终端显示的地址，默认 http://127.0.0.1:4317；端口占用时顺延。服务仅监听本机。桌面浏览器和 Finder 打开目录在 macOS 验证过，Windows/Linux 尚未完成实机界面验证。

网页自动扫描设备、选中第一个在线设备并识别应用。环境数据每次读取完成后间隔 10 秒更新。选择场景、完成人工确认，依次执行“准备内存基线 → 开始本轮采集 → 结束本轮采集”；帧统计冻结后手动返回手机桌面，后台观察结束后保存并强停应用。

长会话滚动可使用测试控制区的专用流程：“开始采集滚动”自动完成基线与正式采集准备，然后持续向历史消息滚动；看到顶部后点“反向滚动”，看到底部后点“结束采集”。提示帧统计已冻结后返回桌面，继续完成后台观察。两个方向的帧指标分别写入本轮结果。

功能与计算

• 帧统计：使用系统 Janky frames / Total frames rendered 计算卡顿率，并以总帧数除正式采集时长计算平均帧率；逐帧记录作为诊断。
• 内存：对采样时刻可识别的同包进程及所选渲染进程分别查询 PSS 并求和，记录正式区间起止快照、采样峰值、相对基线增量及后台末段值；另保留各进程 PSS。跨包共享渲染进程的 PSS 不代表目标应用独占内存。
• 环境检查：电量、电池温度、系统热状态、开机时长、省电模式和非调试包。
• 结果：保存逐轮原始命令和指标，合格轮次按相同条件分组求平均；页面可打开当前测试结果目录查看文件。
• 应用管理：APK 备份、哈希校验后覆盖安装、单独执行并核验 speed 编译。
• HarmonyOS：HDC 设备发现、应用识别、电量与温度、SmartPerf FPS/PSS 和 CSV 保存。热状态、省电模式由测试人员确认；HarmonyOS 卡顿率、自动滚动及 HAP 安装/编译不由本工具处理。

详细步骤、命令、阈值和公式见 使用说明。温度默认上限 40°C、基线 30 秒和 10% 波动是本工具的测量规则，不是 Android 官方通用标准。当前热状态小于 2 的规则允许轻度热限频，若测试目标要求无热限频，需要另行统一测试规则。

数据与配置

默认数据位于 data/android-performance/；每次启动创建一个会话，APK 备份跨会话保存。关闭网页不会中断采集，退出 Node.js 会中断，先结束测试再退出。

环境变量	用途
ADB_PATH	ADB 可执行文件路径，默认 adb
HDC_PATH	HDC 可执行文件路径，默认使用 DevEco Studio 内置 HDC 或 PATH 中的 hdc
ANDROID_TOOL_PORT	本地端口，默认 4317
ANDROID_TOOL_DATA	数据根目录
ANDROID_TOOL_SESSION	恢复已有会话，填写数据根目录下 session- 开头的文件夹名称，需存在 summary.json

例如 macOS/Linux：

ADB_PATH=/path/to/adb node android-performance-tool.mjs
ANDROID_TOOL_SESSION=session-2026-10-20T08-51-16-228Z node android-performance-tool.mjs

Windows PowerShell 可先设置 $env:ADB_PATH = 'C:\path\to\adb.exe'，再执行启动命令。场景列表和最近使用排序保存在浏览器本地存储中，同一浏览器、同一服务地址下保留。

原始输出可能含设备标识、应用和本机路径，数据、APK 备份、报告及本地配置默认不纳入 Git 或发布包。分享时单独检查需要提供的文件。旧版报告和历史数据没有迁移成新版测量结果。

开发与验证

npm test

测试使用模拟 ADB，不需要连接手机，不会安装、编译或强停真实应用。测试覆盖命令解析、基线及时间窗口、错误处理、状态机、汇总、备份安装与编译核验。历史原始输出也做过重算，实机验证过识别、环境读取和网页交互。可控帧率、可控内存的 Android 测试应用校准尚未完成。

路径	内容
android-performance-tool.mjs	本地 HTTP 服务、接口、数据导出
web-tool/	页面、ADB 调用、采集、计算和应用管理
tests/	Node.js 自动测试
NODE_TOOL_GUIDE.md	使用与实现说明
docs/AI_APP_TEST_PROTOCOL.md	历史 AI 应用测试目标与报告约定
BENCHMARK_AUDIT.md、KNOWN_MEASUREMENT_ISSUES.md	旧版方法与问题归档，不是新版当前缺陷清单

许可证

项目许可证待维护者确认，当前不授予开源许可。Lucide 图标的第三方许可独立保留，见 第三方声明。