评估工具¶
Status: Current
Last verified: 2026-07-01
Code anchors:tools/collect/collect-*.sh,tools/generate/generate_synthetic_android_trace.py,crates/aios-cli/tests/*_dataset_test.rs
这篇文档回答什么:如何运行 DiPECS 的评估工具,生成资源、UX、稳定性数据集以及合成 trace。
tools/ 下的脚本都是手动测量工具,产出结构化 JSON 数据集;CI 再通过 crates/aios-cli/tests/*_dataset_test.rs 校验这些数据集是否满足阈值。合成 trace 工具则不需要真机。
| 工具 | 需要什么 | 输出 |
|---|---|---|
tools/collect/collect-resource-overhead.sh | Android 模拟器/真机 | 资源开销数据集 |
tools/collect/collect-ux-metrics.sh | Android 模拟器/真机 | UX 数据集 |
tools/collect/collect-stability.sh | Android 模拟器/真机 | 稳定性数据集 |
tools/generate/generate_synthetic_android_trace.py | 仅 Python | 合成脱敏 JSONL trace |
前置条件¶
- Android 模拟器已启动,或真机已通过 adb 连接。
- 已安装目标包
com.dipecs.collector。 adb在 PATH 中(脚本会自动检测 Windows 下的adb.exe)。- Python 3 已安装(用于合成 trace 和 action sender)。
通用环境变量:
| 变量 | 默认值 | 说明 |
|---|---|---|
ADB | adb | adb 路径 |
PACKAGE | com.dipecs.collector | 目标包名 |
OUT_DIR | data/evaluation | 输出目录 |
TOKEN | dipecs-dev-emulator-shared-token-00000000 | action socket HMAC token |
PORT | 46321 | bridge 端口 |
ACTION_HOST | 127.0.0.1 | bridge 主机 |
资源开销:collect-resource-overhead.sh¶
测量三种模式下的 RSS、PSS、jank,并记录粗粒度 CPU 预算烟测与电池/温度估算:
baseline_idle:app 被 force-stopdipecs_observe_only:仅采集dipecs_action_loop:采集 + 动作回路
运行¶
可调环境变量¶
| 变量 | 默认值 | 说明 |
|---|---|---|
SAMPLES_PER_MODE | 10 | 每种模式采样次数 |
SAMPLE_INTERVAL_SECS | 10 | 采样间隔 |
输出¶
data/evaluation/resource-overhead-emulator-<ts>.jsondata/evaluation/resource-overhead-emulator-<ts>.md
对应 CI 测试¶
crates/aios-cli/tests/resource_overhead_dataset_test.rs
阈值:
- CPU delta ≤ 8 个百分点(仅预算烟测;近 0 或负 delta 不作精确 CPU 结论)
- PSS delta ≤ 80 MB
UX 指标:collect-ux-metrics.sh¶
测量 PreWarmProcess 启动加速和 ReleaseMemory 对 jank / 内存的影响。
采集模式:
no_dipecs_baselinecold_startupprewarm_startupbaseline_jankpost_release_jank
运行¶
输出¶
data/evaluation/ux-metrics-emulator-<ts>.jsondata/evaluation/ux-metrics-emulator-<ts>.md
Startup summary 同时报告 avg_startup_total_time_ms 和 p95_startup_total_time_ms;committed regression fixture 至少覆盖 cold/prewarm 启动样本合计 n=20。
对应 CI 测试¶
crates/aios-cli/tests/ux_metrics_dataset_test.rs
阈值:
- PreWarm 加速 ≥ 20% 且 ≥ 100 ms
- ReleaseMemory jank 增加 ≤ 20 个百分点
- startup p95 必须能从 raw samples 重算,避免均值掩盖尾部退化
稳定性:collect-stability.sh¶
长时间采样 RSS/PSS/CPU,用线性回归判断内存泄漏。
运行¶
# 默认 10 分钟
./tools/collect/collect-stability.sh
# 标准长运行
DURATION_MINUTES=60 SAMPLE_INTERVAL_SECS=30 ./tools/collect/collect-stability.sh
可调环境变量¶
| 变量 | 默认值 | 说明 |
|---|---|---|
DURATION_MINUTES | 10 | 总时长 |
SAMPLE_INTERVAL_SECS | 30 | 采样间隔 |
输出¶
data/evaluation/stability-emulator-<ts>.jsonl(原始样本)data/evaluation/stability-emulator-<ts>.json(汇总数据集)
对应 CI 测试¶
crates/aios-cli/tests/stability_dataset_test.rs
阈值:
- RSS 增长 ≤ 50 MB/h
- PSS 增长 ≤ 20 MB/h
- 平均 CPU ≤ 10%
合成 Trace:generate_synthetic_android_trace.py¶
不需要真机,生成确定性、已脱敏的 Android JSONL trace,用于 replay、策略测试和文档示例。
运行¶
python3 tools/generate/generate_synthetic_android_trace.py \
--rows 2400 \
--output data/traces/android_synthetic_large.redacted.jsonl \
--summary data/traces/android_synthetic_large.redacted.summary.json \
--seed 20260628
参数¶
| 参数 | 默认值 | 说明 |
|---|---|---|
--rows | 2400 | JSONL 行数 |
--output | data/traces/... | 输出 JSONL |
--summary | data/traces/... | 输出统计摘要 |
--seed | 20260628 | 随机种子,保证可复现 |
输出¶
- JSONL trace,事件类型包括
app_transition、notification_posted、notification_interaction、context_heartbeat、accessibility 事件、screen_state等。 - Summary JSON,含
eventTypeCounts、sourceCounts、rawEventKindCounts。
注意:输出明确标记为 synthetic 和 redacted,不能作为真实设备证据。
Trace Dashboard¶
tools/view/trace-dashboard/index.html 是一个静态 HTML 页面,可在浏览器中浏览 JSON/JSONL/NDJSON trace 文件。
用法:
# 用任意静态服务器打开
python3 -m http.server 8080 --directory tools/view/trace-dashboard
# 然后访问 http://localhost:8080
与 CI 的关系¶
| 工具 | CI 是否直接运行 | CI 如何验证 |
|---|---|---|
collect-resource-overhead.sh | 否 | dataset test 读取已提交的 fixture |
collect-ux-metrics.sh | 否 | dataset test 读取已提交的 fixture |
collect-stability.sh | 否 | dataset test 读取已提交的 fixture |
generate_synthetic_android_trace.py | 否 | replay/golden/noop 测试使用 fixture |
因此:工具产出的 fixture 必须提交到 git,CI 才能做回归验证。
常见问题¶
脚本提示找不到 action-forensic-sender.py¶
确保 tests/scenarios/lib/action-forensic-sender.py 存在;该 sender 用于向 action socket 注入动作。
资源开销/UX 脚本在 Windows 上找不到 Python¶
脚本会尝试检测 Windows Python 3.13;可通过 PYTHON / SEND_PYTHON 环境变量显式指定。
新 fixture 加入后 CI 失败¶
dataset tests 会从原始样本重新计算 summary。如果新 fixture 内部不一致或超出阈值,测试会失败。此时应检查数据采集过程,而不是简单修改测试阈值。