有个周一早上,运营往群里甩了张截图:一台 Pixel 7、Android 14,系统设置里我们那个健康类 App 排在耗电榜第一,写着 11%。我第一反应是模块 M 的夜间同步又跑飞了,把那台机一整夜的 logcat 拉下来,结果从 23:41 到早上 7:02,我们的进程一次都没被唤醒过,ActivityManager 里没有一条 start 记录,CPU 时间挂着 0。进程整夜没醒,电却记在它头上,这事我当时怎么都没想通。
后来把 dumpsys batterystats 翻出来才明白,账本上写的从来不是 CPU 时间,是唤醒次数:谁把射频从 IDLE 拽起来、谁让应用处理器没沉到最深的 C-state,谁就背这个数。那 11% 里真正属于我们代码的,是一次没配对上的 wakelock 和一串被并进系统维护窗口的精确闹钟;剩下大半是屏幕与蜂窝射频待机,被按 UID 摊到了「最近被用过」的我们头上。这个判断一变,后面所有取舍都跟着变。我不再盯着哪个方法费 CPU,而是拿 Trae 把整条唤醒链一层层翻出来,从 wakelock 一直数到 Doze 的维护窗口。
电量账本上写的不是 CPU 时间,是唤醒次数
先把两个单位掰清楚,不然后面全是糊涂账。电池容量标的是 mA·h,比如那台 Pixel 7 是 4355 mA·h,这是电荷量,跟电压无关;系统算账要的是 mW·h,是能量,得乘上电池电压。同样 100 mA·h,在 3.85 V 下是 385 mW·h,在 4.2 V 满电时是 420 mW·h。我第一次看 Battery Historian 报告,把 Estimated power use (mAh) 那一列当成时间占比,错得离谱,返工了一整晚才把口径对齐。
电池标称 4355 mA·h @ 3.85 V
能量换算 4355 * 3.85 = 16767 mW·h ≈ 16.8 W·h
系统记账口径 batterystats 里每个 UID 的 mAh 是按 power_profile.xml 的
电流系数 * 各部件占用时长 累加出来的估算值
一次唤醒的账 CPU 从 C4 拉回 C0、射频从 IDLE 升到 DCH、发完包再挂 tail
这些「状态跃迁」各有一次固定开销,与干活多少几乎无关
电量数到底从哪来,得提一句 fuel gauge。电池包里那颗电量计芯片(TI 的 BQ 系列、Maxim 的 MAX17xxx 一类)靠库仑计累加充放电电流,再拿温度、老化、电压曲线做补偿,内核通过 power_supply 子系统把 CHARGE_NOW / CHARGE_FULL / VOLTAGE_NOW 这些属性报上来。框架层 BatteryManager.BATTERY_PROPERTY_CHARGE_COUNTER 读的就是这个剩余电荷,单位是微安时(µAh),BATTERY_PROPERTY_CURRENT_NOW 是瞬时电流,单位微安。
// 路径:app/src/main/java/com/example/health/power/BatteryMeter.kt(片段,完整版见后面定稿章)
val bm = getSystemService(Context.BATTERY_SERVICE) as BatteryManager
val remainUah = bm.getLongProperty(BatteryManager.BATTERY_PROPERTY_CHARGE_COUNTER)
val currentUa = bm.getLongProperty(BatteryManager.BATTERY_PROPERTY_CURRENT_NOW)
// 我在 Pixel 7 上静置读到的两个值:
// remainUah = 3128400(约 3128 mAh),currentUa = -18400(放电 18.4 mA)
// 注意 CHARGE_COUNTER 是「剩余」,不是「已用」;拿它当累计值算,正负会整个反掉
这里有个坑我踩过:CHARGE_COUNTER 在部分机型上不是从 fuel gauge 直读,而是框架拿百分比反推的,跳变很粗,隔几分钟才动一次。我拿它做过一版「每秒采样算瞬时功率」的埋点,曲线全是台阶,后来改成 CURRENT_NOW 配合 energy-counter 才平顺。fuel gauge 给的是全局真值,而应用耗电排行给的是按 UID 摊出来的估算,这俩压根不是一个东西,开篇那 11% 就出在这道缝里。
真正把「唤醒次数比工作量更贵」讲透的,是射频状态机和 CPU 的 idle 状态,这俩是一体两面。
蜂窝射频在 3GPP 里有一套 RRC 状态机:IDLE / CELL_FACH / CELL_DCH(LTE 里对应 RRC_IDLE / RRC_CONNECTED 加 DRX)。从 IDLE 发起一次数据连接,要先做随机接入、拉起功放、跟网络协商,这一串信令本身就是几十到几百毫安的额外电流;数据包发完之后,射频不会立刻掉回 IDLE,会挂在高功耗的 tail 上等可能的后续包,LTE 上这个尾巴常在 10 秒上下,HSPA 能到十几秒。这就是 tail energy——你只想发 200 字节的心跳,射频却替你把后面 10 秒的高功耗一起付了。
CPU 这边同理。ARM 的 big.LITTLE 或现在的 DynamIQ 簇,idle 时按 C-state 一档档往下降:C0 在跑,C1 关时钟,C3/C4 断核级电源、清 L2、连 cache 一致性都退出,最深那档把整个 cluster 断电。从深 C-state 醒回来,要重新上电、恢复寄存器和 cache 预热、重新锁 PLL,这段「唤醒代价」是固定收的。于是就出现一个反直觉的算式:
A 方案:每 2 分钟醒一次,每次干 50 ms 的活,一晚 8 小时 = 240 次唤醒
固定开销 ≈ 240 * (CPU 唤醒 + 射频迁到 DCH + 10s tail)
B 方案:攒到一次,每 30 分钟醒一次,每次干 600 ms,一晚 = 16 次唤醒
固定开销 ≈ 16 * (同样的一次跃迁)
B 干的实际工作量是 A 的 16 * 600ms / (240 * 50ms) = 0.8 倍,差不多甚至更少,
但跃迁次数只有 1/15。射频 tail 那 10 秒在 A 里被付了 240 遍,在 B 里只付 16 遍。
省下的不是 CPU 时间,是「把机器从睡里拽起来」这 224 次。
批量合并为什么省电,根子就在这:JobScheduler 把一堆作业的约束凑齐、塞进同一个维护窗口一起跑,本质是把 N 次唤醒压成 1 次。我早年在模块 M 里写过一个每 2 分钟 setRepeating 的心跳,自认为「每次就 1 个请求,特别轻」,其实那一晚我让整台手机的射频付了两百多次 tail,账全算在 wakeup 上,跟请求大小没关系。
把这条链画出来,比盯着某个方法看直观得多:
flowchart TD
A["应用调 setExact / acquire PARTIAL_WAKE_LOCK"] --> B["AlarmManager / PowerManagerService"]
B --> C["kernel wakelock 拿住, 阻止 suspend"]
C --> D["AP 从最深 C-state 被拉回 C0"]
D --> E["射频 RRC 从 IDLE 升到 CONNECTED, 功放拉起"]
E --> F["发完包, 射频挂 tail 继续高功耗数秒"]
F --> G["CPU 回 idle, 射频回落 IDLE"]
G --> H["batterystats 按 power_profile 系数把这段摊到 UID"]
H --> I["系统设置耗电排行按 UID 汇总, 屏幕/射频另摊一份"]
还有两个占比得摆正,不然容易归错因。屏幕在亮屏场景里通常是绝对大头,一块 6.3 英寸 OLED 全白 120Hz 能到 1 W 以上;蜂窝射频在弱信号(比如 -110 dBm 的电梯、地库)下持续搜网、抬发射功率,待机电流能翻倍。这俩都是系统级开销,可系统的耗电排行是按「这段时间谁在前台 / 谁最近活跃」把屏幕和射频的账摊给某个应用的。我们那个健康类 App 因为用户睡前测了次心率、锁屏前停在我们页面,就被摊了一整夜的射频待机。所以「排行第一」很多时候不是你干了什么,是你恰好是那个被选中的记账对象。
最后一个要澄清的误解,几乎每次评审都有人提:后台进程占着内存,是不是就一直耗电?不是。Linux 把匿名页换出、把干净的文件页直接丢掉,DRAM 只要还在自刷新就要耗电,但那是整块 LPDDR 的颗粒开销,按容量算、不按「哪个进程占了多少 MB」算,更不会因为你的进程缓存了 80 MB 就多耗 80 MB 对应的电。进程留在内存里,只影响切换快慢和 lmkd 的回收顺序,不直接产生电流;真正耗电的是它有没有在拿 wakelock、有没有把射频拽起来、有没有阻止 AP 沉到深 C-state。我后来把这条写进 Trae 的 Rules,让它别再顺着「杀进程省电」的思路给我出方案,少走了不少弯路。
一度电走完全程:六本账为什么对不上
翻车那次最折磨我的,不是 11% 本身,是六个地方给出的数完全对不上。同一段模块 M 的夜间同步,02:13 触发,我在不同工具里读到的东西像六个平行宇宙。后来我把它们摊到一张表里,才看明白每个工具量的根本不是同一件事。
| 出处 | 我读到的数(那台 Pixel 7,静置 23:30–07:00) | 它实际在量什么 | 归因给谁 | 时间基准 |
|---|---|---|---|---|
| 系统设置耗电排行 | 「我们 App 11%,约 480 mAh」 | 按 UID 汇总的估算 mAh,含摊到头上的屏幕/射频 | 最近前台/最近活跃的 UID | 上次充满电至今 |
dumpsys batterystats --charged | Uid 10xxx: wake=38s, wifi=0, mobile=12s | 各部件占用时长 × power_profile.xml 系数 | 精确 UID,但只到部件级 | 自上次 charged 重置 |
| Battery Historian 时间轴 | 02:13 一条 wake_lock 长条 + 三段 mobile_radio | 把 batterystats 的事件按时间铺开 | 事件 + 归属进程 | 相对开机时间 |
| Android Studio Power Profiler | 一段约 220 mW 的平台,持续 11 s | 系统电量轨的估算功率,经过归一化 | 系统整体,不拆 UID | 采样窗口内 |
Perfetto android.power / wakeup | wakeup source: alarm_rtc 02:13:04,power rail 抬升 | 内核 wakeup source 与电源轨电流 | wakeup source(IRQ/alarm),不认应用 | 单调时钟 |
| 云端埋点 | 「同步成功 1 次,耗时 340 ms」 | 我们自己上报的业务结果 | 我们自己的会话 | 应用内时钟 |
乍看全是矛盾的,拆开其实各有各的口径:
1) 系统设置的 480 mAh 是「从上次充满到现在」的累计,里面塞了用户睡前亮屏那 20 分钟
的屏幕账,和一夜弱信号蜂窝待机;batterystats 的 --charged 只算「上次充电后这一段」,
两者时间窗都不一样,数值当然对不上。
2) batterystats 报 wake=38s,是「持锁时长」,不是「唤醒次数」。那晚真正 woke 241 次,
每次 150 ms 左右,加起来正好 36 s。看时长会以为「就锁了半分钟,不重」,
看次数才知道射频 tail 被付了 241 遍。
3) Battery Historian 的时间轴是相对开机时间画的,Perfetto 用的是单调时钟,
我第一次对齐时差了 4 分 12 秒(那台机开机后没校过时),差点把两次唤醒拼成一次。
4) Power Profiler 的 mW 是归一化估算,方便看趋势,绝对值和 fuel gauge 差一截,
不能拿它去对 batterystats 的 mAh。
5) Perfetto 里的 wakeup source 写的是 alarm_rtc / 某个 IRQ 号,它到内核层就停了,
根本不知道上层是哪个 App 的 PendingIntent;要靠 batterystats 的 wakeup 事件
反查 UID 才能接上。云端埋点更干脆,只记「成功一次」,连系统有没有真唤醒都不管。
我把这个归因链画成图,Trae 后面几轮排查全按这张图的箭头走,没再在「哪个数才对」上打转:
flowchart LR
S["同一段后台同步 02:13 被触发"] --> T1["系统设置: 按 UID 摊屏幕/射频"]
S --> T2["batterystats: wake/wakelock 时长 + 估算 mAh"]
S --> T3["Battery Historian: 时间轴条带"]
S --> T4["Power Profiler: 系统功率轨估算"]
S --> T5["Perfetto: wakeup source / power rail"]
S --> T6["云端埋点: 业务成功次数"]
T1 --> U["六个读数对不上"]
T2 --> U
T3 --> U
T4 --> U
T5 --> U
T6 --> U
U --> V["统一到: 谁唤醒 / 唤醒几次 / 每次多久"]
那次对齐之后我给自己定了条死规矩:凡是说「耗电」,先翻译成三个可查的数——谁唤醒的、唤醒了几次、每次唤醒持了多久。翻译成这三问,六个工具才有共同语言;不翻译,谁都能拿一个数说自己对。这条规矩后来原封不动写进了第 3 轮给 Trae 的提示词里,也成了这一整篇后面所有取舍的起点。
当年为什么要跟后台工作过不去:十七年收紧史
刚入行那会儿我写后台同步,压根没有「省电」这根弦。模块 M 最早的版本就是个 Service 加一个 AlarmManager.setRepeating(RTC_WAKEUP, ..., 120_000, pi),心跳两分钟一次,理直气壮。那会儿这么写不算错,因为系统自己也只有「屏幕开 / 屏幕关」两个状态,给开发者的全部约束就是一把 PowerManager.WakeLock——你想让 CPU 别睡,acquire() 一下就行,没有配额、没有超时、没有引用计数检查,锁拿一整夜系统也不管。精确闹钟是当时唯一靠谱的定时手段,谁都不觉得两分钟一次有什么问题。
真正逼着系统改的,是硬件那点底子。2008 年 HTC Dream(G1)电池 1150 mA·h,2010 年前后旗舰普遍还在 1500 mA·h 上下,可 3G 射频一开、GPS 一锁、屏幕一点亮,电量肉眼可见地掉。更要命的是智能机把「永远在线」变成了默认预期:邮件要推、位置要报、社交要刷,几十个 App 各自起一套轮询,射频被反复拽出 IDLE,尾能耗叠在一起,待机一夜就没电。系统厂商发现,光靠「开发者自觉」根本收不住,于是从 5.0 开始,一代一代把后台工作的口子扎紧。这句不是感慨,是我把 release note 拉成一条线之后数出来的——十七年里,几乎每个大版本都在动同一件事:让系统拿到「什么时候统一唤醒」的权力,把零散的唤醒合并掉。
下面这张表是我在第 2 轮让 Trae 对着官方文档逐行核准、又自己补了几处年份之后定下来的。日期和 API level 我一律按发布日写,行为变化只记跟唤醒/调度相关的那条。
| 版本 / API | 发布日 | 这一代对唤醒与后台工作干了什么 |
|---|---|---|
| 1.0 ~ 4.4 / API 1~19 | 2008-09-23 起 | 只有屏幕开/关二元状态;WakeLock 可无限持有、无引用计数约束;AlarmManager 精确闹钟(setRepeating / set)是唯一定时手段,RTC_WAKEUP 想多密就多密 |
| 5.0 Lollipop / API 21 | 2014-11-04 | Project Volta:引入 JobScheduler,声明式、可带「充电 / 不计费网络 / 空闲」约束、系统可批量合并;同期 Battery Historian 在 2015 年开源,第一次能把 bugreport 里的电量事件铺成时间轴 |
| 6.0 Marshmallow / API 23 | 2015-09-29 | Doze + App Standby;新增 setAndAllowWhileIdle() / setExactAndAllowWhileIdle(),官方明确这俩在 Doze 下每 App 每 9 分钟最多触发一次;setAlarmClock() 照常触发并会让系统提前退出 Doze;加入电池优化白名单(ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS) |
| 7.0 Nougat / API 24 | 2016-08-22 | Light Doze:不再要求静止,熄屏+未充电即可进入,维护窗口更短更密;同时「隐式广播」开始被削(CONNECTIVITY_ACTION 等移出静态注册) |
| 8.0 Oreo / API 26 | 2017-08-21 | 后台执行限制:后台应用不能 startService()(要起得走 startForegroundService()),绝大多数隐式广播静态注册失效,后台位置限流;JobScheduler 成为后台周期工作的正路 |
| 9 Pie / API 28 | 2018-08-06 | App Standby Buckets + Adaptive Battery:Active / Working set / Frequent / Rare 四档起,系统可借预装 ML 应用预测使用概率来分桶;桶决定 job/alarm 频率与高优先级 FCM 配额 |
| 10 / API 29 | 2019-09-03 | 后台启动 Activity 被限制;STANDBY_BUCKET_RESTRICTED 常量在 API 30 这一档被引入(R 上默认未启用),为受限桶铺路 |
| 11 / API 30 | 2020-09-08 | 一次性权限、后台位置需单独申请;受限桶相关规则继续铺垫,前台服务类型(location / camera / mic)开始要求 while-in-use 级权限配合 |
| 12 / API 31 | 2021-10-04 | 精确闹钟需 SCHEDULE_EXACT_ALARM 权限;后台起 FGS 抛 ForegroundServiceStartNotAllowedException;受限桶正式默认生效;JobScheduler 引入 expedited job(加急作业),作业单次运行时长从固定 10 分钟变成按系统空闲程度弹性 |
| 12L / API 32 | 2022-03-07 | 大屏相关,对电量主线无新增调度约束,只把 12 的配额逻辑带到大屏形态 |
| 13 / API 33 | 2022-08-15 | 新增 USE_EXACT_ALARM(闹钟类应用免弹权限)、POST_NOTIFICATIONS;8 天不交互进受限桶(12 是 45 天),受限桶一天一次约 10 分钟批处理作业 |
| 14 / API 34 | 2023-10-04 | FGS 必须声明 android:foregroundServiceType,系统按类型校验权限与配额,选错类型直接抛异常 |
| 15 / API 35 | 2024-09-03 | dataSync / mediaProcessing 类型每 24 小时 6 小时配额,超时系统停服;shortService 约 3 分钟;Doze 进入深睡比 14 快约 50%(Dave Burke 在 Google I/O 2024 访谈原话,部分测试机待机最多多 3 小时,且适用于所有升级到 15 的设备);16KB 页表带来的平均 4.5% 电量收益属于系统级优化,跟应用侧唤醒账不是一回事,放这里只当个对照 |
| 16 / API 36 | 2026 | job 配额按桶 / 内存压力 / 资源状态进一步细化;Active 桶的后台作业拿到「宽松运行时配额」;新增 JobScheduler#getPendingJobReasonsHistory() 查作业为何没跑,废弃作业(JobParameters 被 GC 却没 jobFinished)给 STOP_REASON_TIMEOUT_ABANDONED |
表里有几处我核准时特意多查了一眼。受限桶那档,官方 UsageStatsManager 的常量写得很直白:STANDBY_BUCKET_ACTIVE=10、WORKING_SET=20、FREQUENT=30、RARE=40、RESTRICTED=45,还留了个 never(装了从没跑过)单独一档;RESTRICTED 的注释明确「this bucket is not enabled in Build.VERSION_CODES.R」,也就是 API 30 上加了常量但没启用,真正默认生效是 Android 12。我把这个差异写进表里,是因为第 9 轮真机验证时,一台 Android 11 的测试机怎么都不进受限桶,我一度以为自己命令敲错了。
哪些老办法到今天失效了,哪些反而回来了,这条线也挺有意思:
失效的:
setRepeating(RTC_WAKEUP, 2min) 心跳 → 8.0 起后台广播/服务限制 + Doze 推迟,且 tail 能耗照付
常驻 Service 靠 onStartCommand 拉活 → 8.0 startService 被禁,12 后台起 FGS 抛异常
隐式广播静态注册监听网络/开机自启 → 7.0/8.0 陆续移除
拿 WakeLock 保 CPU 做「同步更稳」 → Doze 里 wakelock 被忽略,还把账记到自己头上
不声明 type 的 FGS → 14 直接抛异常
反而「回来」的:
精确闹钟 → 12 给了 SCHEDULE_EXACT_ALARM、13 给了 USE_EXACT_ALARM,
但换成了「要权限、要用途说明、且 Doze 下仍受 9 分钟限流」的形态
前台服务 → 没被禁,反而被类型化、配额化,成了「在额度内可被系统信任」的高优先级通道
批量合并 → 5.0 JobScheduler 那套思想到 16 越用越细,只是决策权全归了系统
我在模块 M 里把那个两分钟心跳删掉、换成带约束的合并作业,本质上不是学了个新 API,是把 2008 年那套「我想啥时候醒就啥时候醒」的权力,交回给了系统。十六 KB 页表那种系统级收益(平均约 4.5%)我们应用层够不着,能动的只有自己那条唤醒链。
Doze 状态机与 Standby 分桶
Doze 刚出来时我理解成「熄屏就省电」,结果第一次真机验证就翻车:把测试机熄屏搁桌上,眼巴巴等它进深睡,半小时过去作业照跑。后来才把进入条件凑齐——未充电 + 静止 + 熄屏,且持续一段时间,三个都得满足;插着 USB 调试线充电时不算,这就是为什么我头几轮在工位上怎么测都不对,得拔线、用 adb over Wi-Fi 才行。
Doze 不是一个开关,是一串状态。Deep Doze 从 INACTIVE 起,经过 IDLE_PENDING(等约 30 分钟)、SENSING(用加速度计判静止)、LOCATING,才落到 IDLE。进了 IDLE,系统挂起网络访问、忽略普通 WakeLock、推迟标准闹钟和 JobScheduler/sync、不做 Wi-Fi 扫描;只在周期性的维护窗口里放大家一口气跑完,然后接着睡。维护窗口的间隔是指数退避的:头几次挨得近,之后 ×2 往上翻,从 1 小时级涨到 2、4、6 小时,最后封顶在数小时一次。Android 15 把「进 Doze」这段整体提速约 50%,睡着得更快,维护窗口来得也更早,所以原来「熄屏一小时才安静」的经验在 15 上得重测。
Light Doze 是 7.0 补的另一条路:不要求静止,熄屏+未充电就能进,窗口更短更密,专门管「揣兜里走路」这种 device 在动但屏幕黑着的场景。两条路径并存,别混着理解。
flowchart TD
START["亮屏 / 充电 / 明显移动"] --> COND{"熄屏 + 未充电"}
COND -->|"还在动, 但屏幕黑"| LIGHT["Light Doze 路径 (API 24+)"]
COND -->|"静止, 通过 SENSING/LOCATING"| DEEP["Deep Doze 路径 (API 23+)"]
LIGHT --> LW["短维护窗口, 间隔短, 允许轻微运动"]
LW -->|"继续"| LIGHT
DEEP --> DW["维护窗口: 先放开约 1 分钟"]
DW --> BACK["指数退避 x2: 1h → 2h → 4h → 6h → 封顶"]
BACK -->|"接着睡"| DEEP
DEEP --> RESTRICT["IDLE 期间: 挂网络 / 忽略 wakelock / 推迟标准闹钟与 job / 不扫 Wi-Fi"]
LIGHT --> WAKE["亮屏 / 插电 / 移动 / setAlarmClock 提前退出"]
DEEP --> WAKE
WAKE --> START
那条反直觉的文档结论得单拎出来,我在第 6 章还会拿调度器表再对一遍:Doze 期间前台服务只是让进程不被回收,并不豁免网络与作业调度限制。我当初以为模块 M 起了个带通知的 FGS 就能夜里照常同步,结果维护窗口之外网络照样挂,job 照样排队。官方文档写得很清楚,Doze 下唯一被文档化的豁免是电池优化白名单(ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS 引导用户加,或系统预置),而且白名单会连带豁免掉 Bucket 相关限制。顺带补一句,setAlarmClock() 是少数能照常触发、还会让系统提前退出 Doze 的闹钟,代价是它会在锁屏上显示一个闹钟图标,不能拿来当普通后台触发器用。
App Standby 是另一套维度,管的是「用户多久没碰这个 App」。判定条件大致是:一段时间没触碰、没有前台组件(Activity / FGS / 被别的 FGS 用着)、没在锁屏或通知栏产生通知,系统就把它标成 idle;一插电立刻释放,攒着的 job 和 sync 全放行;长时间不动的设备,idle 应用大约一天只给一次网络。它和 Doze 是叠着生效的——Doze 管整台机器睡不睡,Standby 管某个 App 在机器醒着时能不能干活。
9 时代把 Standby 细化成了 App Standby Buckets。系统按「最近用没用、用得多勤」把 App 动态分进五档,Active / Working set / Frequent / Rare / Restricted,外加装了没跑过的 never。分桶直接决定 job 多频繁、alarm 多频繁、能收多少高优先级 FCM;这些限制只在电池供电时生效,一充电全放。Adaptive Battery 那层更有意思:官方说系统可以借一个预装的 ML 应用预测「你接下来会点哪个 App」,按预测结果提前分桶,而不只看历史——所以一个刚用过的 App 也可能被 ML 丢进 Rare,因为它判断你这几小时不会再点它。没预装 ML 的设备就退回按最近使用时间排序。Google 在文档里还特意叮嘱:每家厂商可以自定非活跃 App 的分桶标准,别去试图影响自己被分到哪档,把 App 写成「在任何桶里都规矩」才是正路。这条我抄进 Rules 了,省得 Trae 又给我出「抬活跃度骗桶」的歪招。
受限桶(Restricted)最狠:API 31 引入、12 默认生效,13 起用户 8 天不交互(12 是 45 天)且没有豁免就落进去,一天只给一次约 10 分钟的批处理作业,还限制联网。UsageStatsManager 里五个常量的数值我贴一下,后面 dumpsys 输出里看到的就是这些整数:
STANDBY_BUCKET_ACTIVE = 10 作业/alarm 几乎不限, 16 起 Active 桶后台作业有宽松配额
STANDBY_BUCKET_WORKING_SET = 20 轻度限制
STANDBY_BUCKET_FREQUENT = 30 较强限制, 高优先级 FCM 有上限
STANDBY_BUCKET_RARE = 40 严格限制, 联网受限, 至少每天放行一小段
STANDBY_BUCKET_RESTRICTED = 45 最严, 一天一次约 10 分钟批处理作业
(另:never 档,装了从未运行,系统施加极严限制)
查桶我一般用两条,一条看当前值、一条看变更历史:
# 我在自己机器上跑出来的记录,Pixel 7 / Android 14,模块 M 静置三天后
$ adb shell am get-standby-bucket com.example.health
40
# 对照 usagestats 里那次分桶变更事件
$ adb shell dumpsys usagestats | grep -A2 -B2 'standby-bucket'
standby-bucket=40 reason=3 (timeout) old=30
time=2026-09-12 03:04:11 changed=STANDBY_BUCKET_CHANGED
# 想手动把机器拨到某档做验证(仅测试用,别在正式逻辑里依赖)
$ adb shell am set-standby-bucket com.example.health rare
$ adb shell am get-standby-bucket com.example.health
40
dumpsys usagestats 那行 reason=3 (timeout) 我第一次没看懂,后来对着 UsageStatsManager 的 REASON_* 常量才对上:是「超时未使用」触发的降级,不是我代码里哪儿写错了。第 9 轮让 Trae 做 Doze/Bucket 真机验证时,这两条命令和 dumpsys deviceidle 的 step 一起塞进了脚本,后面定稿代码章会给全套。
调度器的边界,和那条反直觉的文档结论
模块 M 里原有的定时代码,我拿 Trae 扫完清单后摊成一张适用边界表。这张表后来被我贴在工位上,凡是想加新的后台触发,先来对一遍该走哪条路,别再顺手就 setExact。
| 通道 | 起自 | 单次运行时长 / 频率 | Doze 下行为 | 我拿它干什么 |
|---|---|---|---|---|
JobScheduler | API 21(5.0) | API 21 约 1 分钟;API 23~30 约 10 分钟;API 31+ 按系统空闲程度弹性 | 标准 job 被推迟到维护窗口,约束凑齐才放 | 批量同步、日志上报、可延迟的一切周期工作 |
WorkManager | AndroidX | 周期最小 15 分钟,底层在 API 23+ 就是 JobScheduler,自动继承系统省电约束 | 同 JobScheduler,内部用 JobScheduler 时不会跑 | 需要重试、链式约束、跨进程保活的可靠后台任务 |
AlarmManager.setExact | 早期 | 精确,但 12 起需 SCHEDULE_EXACT_ALARM / USE_EXACT_ALARM | Doze 里标准精确闹钟被推迟 | 真正对时间敏感、且用户能感知的事(提醒、服药闹钟) |
setAndAllowWhileIdle / setExactAndAllowWhileIdle | API 23(6.0) | 每 App 每 9 分钟最多一次 | 能穿 Doze,但被限流 | 极少数必须穿 Doze 的兜底,且接受 9 分钟粒度 |
setAlarmClock | API 21 | 照常触发,系统提前退出 Doze | 不推迟 | 用户看得见的闹钟(锁屏会出闹钟图标) |
| expedited job | API 31(12) | 高优先级、较少受维护窗口约束,但吃当日配额 | 在配额内优先跑 | 用户刚操作完、要尽快落地的加急任务 |
| FGS(带 type) | API 26 起逐步收紧 | dataSync/mediaProcessing 每 24h 6 小时配额、shortService 约 3 分钟 | 只保进程不回收,不豁免网络与 job 限制 | 用户可感知的持续任务(上传、播放、定位) |
表里最后一行那条,是我这轮最想记下来的。我原本把「起了 FGS」当成夜里同步的护身符,官方文档一句话把我按回去:Doze 期间前台服务只是让进程不被回收,并不豁免网络访问与作业调度限制;唯一被文档化的豁免是电池优化白名单。换句话说,你起了个带通知的 FGS,夜里网络照样挂、job 照样排队,该攒到维护窗口还是得攒。我把这条抄给 Trae,让它别再给我出「起个常驻服务保证实时」的方案,省了一轮无用功。
WorkManager 那行也值得多说一句。我以前总觉得它是「比 JobScheduler 高级的封装」,其实在 API 23+ 它底层就是 JobScheduler,系统给的省电约束它一条不落地全继承;只有在更老的版本上才退回 AlarmManager + 广播那套模拟。所以纠结「用 WorkManager 还是 JobScheduler 哪个更省电」本身就是伪问题,该纠结的是约束声明得对不对、批处理有没有合并。
wakelock 的账是另一处最容易记错人的地方。开篇那 11% 的根,翻到最底下就是一把没配对的 PARTIAL_WAKE_LOCK:模块 M 引的三方推送 SDK 在 onReceive 里 acquire(),只在 onSuccess 回调里 release(),那晚超时回调没走到,锁就挂了一夜。诡异的是 logcat 里我们业务代码一行没打——PARTIAL_WAKE_LOCK 是内核态拿住 CPU 不让深睡,应用进程并没有被调度起来跑 Java,所以「进程一夜没醒」和「锁挂了一夜」能同时成立,这正是我当时看不懂的地方。
治理这把锁,我落了三条硬规矩,后面定稿的 WakeLockGuard 全按这个来:
1) setReferenceCounted(false)
默认 true 时 acquire/release 要严格配对计数,一次漏 release 计数就永远归不了零;
关掉之后每次 acquire 覆盖、一次 release 就放,配合 try/finally 最省心。
2) acquire(timeoutMs)
给持锁一个上限(我设 60_000),到点系统自动放,哪怕回调丢失也不会挂一夜。
3) try { ... } finally { release() }
AutoCloseable + kotlin.use{},把释放绑在作用域上,不依赖任何成功/失败回调。
判读有没有泄漏,靠 dumpsys power:
$ adb shell dumpsys power | grep -A12 'Wake Locks'
Wake Locks: size=3
PARTIAL_WAKE_LOCK 'HealthSync:upload' (uid=10xxx, pid=4211) ACQUIRED
elapsed since acquire=7h42m13s <-- 这一行就是要命的地方
PARTIAL_WAKE_LOCK 'AudioMix' (uid=1000) ...
elapsed since acquire=7h42m13s 这种明显超过业务预期的持锁时长,基本就是泄漏。更麻烦的是它的记账方式:batterystats 把这段 CPU 没深睡的账按持锁的 UID 记,可如果这把锁是三方 SDK 用我们进程的身份拿的、或者是在一次系统唤醒里被别的组件连带持有的,账就会摊到「看起来最相关」的那个应用头上。我们那次是 SDK 拿锁、射频 tail 又按最近活跃 UID 摊,两层叠加,才凑出榜首那个 11%。所以未 release 的泄漏,往往不是「自己多干了活」,而是把别人和系统共享的那段唤醒账,招到了自己名下。
测量这块,我最后固定成三件套,每套管一层,谁也替不了谁:
第一层 · 账本级:dumpsys batterystats --charged 与 Battery Historian
adb shell dumpsys batterystats --reset # 先清账,记时间
adb shell dumpsys batterystats --charged com.example.health
adb bugreport bugreport.zip # 拖进 Battery Historian 铺时间轴
判读重点:看 Uid 行里的 wake / wakelock / mobile_radio 时长,
再看 Historian 上 wake_lock 长条和 mobile_radio 段是不是贴着同一时刻;
它给的是「估算 mAh + 部件时长」,不是真实电流,绝对值别当真。
第二层 · 现场级:Android Studio Power / Energy Profiler
在 Energy Profiler 里看 CPU / network / location / wakelock 各条能量轨,
找「哪个事件把系统功率抬起来」。它归一化过,方便看趋势和优化前后对比,
但别拿它的 mW 去跟 batterystats 的 mAh 对账,口径不同。
第三层 · 内核级:Perfetto 的 power rail 与 wakeup 归因
抓 android.power / power_rails / linux ftrace 的 wakeup source,
看是哪条 alarm_rtc、哪个 IRQ 把 AP 拽醒的。它到内核就停,不认应用 UID,
得靠 batterystats 的 wakeup 事件反查 UID 才能接上前一层。
配套还有几条我天天敲的:dumpsys jobscheduler 看作业排队与约束满足情况、cmd appops 看某个 UID 的 WAKE_LOCK / RUN_IN_BACKGROUND / SCHEDULE_EXACT_ALARM 授权态、dumpsys deviceidle 强制进 Doze 并逐步 step 观察状态迁移。这些带输出片段的判读我全归到后面的命令速查章,这里先把分层讲清楚:账本级回答「记了多少、记给谁」,现场级回答「哪一下把功率抬了」,内核级回答「到底是谁拽醒的」。三层对不上才是常态,对得上反而要怀疑是不是哪层没采全。
给 Trae 立的规矩
真动手之前,我先把 Trae 管住了。第一次直接甩一句「帮我优化下 App 耗电」过去,它给我回了一整套「杀后台进程、降低同步频率、用更轻量线程」的通用建议——方向全错,还差点把前台测量服务一起收了。从那以后我学乖了:先立规矩,再谈需求。
这里有个返工得写下来。我照着 2024 年收藏的一篇教程,想在 Trae 里切到 SOLO Builder 模式来跑批量改造,界面上翻了半天没找着入口。去翻 2026 年 5 月的更新说明才明白:SOLO Builder 和 SOLO Coder 已经合并成 SOLO Agent 了,旧教程里那个独立的 Builder 早不在了。我按新模式重配了一遍上下文引用方式,头两轮的提示词也因此改过一次。这个坑不写清楚,后面十二轮里「模式」那一栏会对不上。
先给仓库加 .traeignore,别让构建产物和映射文件把上下文撑爆:
# 路径:.traeignore
build/
**/build/
.gradle/
.idea/
local.properties
*.apk
*.aab
app/build/outputs/
app/build/intermediates/
# 混淆映射与基线另放,别进每次对话的默认上下文
mapping.txt
seeds.txt
usage.txt
然后是 Rules 模板。我把它拆成「构建规则、编码约束、验收口径」三块,globs 之类按文件类型挂,Trae 在改动对应文件时会自动带上:
# 路径:.trae/rules/battery_rules.md 的规则头(Trae Rules 以 Markdown 承载,这段是约束声明)
project: com.example.health
targetSdk: 35
minSdk: 23
language: Kotlin
globs:
- pattern: "**/*WakeLock*.kt"
rule: "所有 acquire 必须配 release,用 AutoCloseable + try/finally,acquire 必须带 timeout"
- pattern: "**/*Worker*.kt"
rule: "周期工作一律走 WorkManager/JobScheduler,禁止 setRepeating 与裸 Service 轮询"
- pattern: "**/AndroidManifest.xml"
rule: "FGS 必须带 foregroundServiceType;精确闹钟权限要先弹用途说明再申请"
- pattern: "**/*Alarm*.kt"
rule: "默认不用 setExact;确需精确时用 setAlarmClock 或申请 SCHEDULE_EXACT_ALARM"
constraints:
- "只用平台 API / AndroidX,零第三方依赖当方案"
- "不教保活、双进程守护、隐藏通知、绕过 Doze 白名单诱导"
- "任何『优化后』结论都要落到一个可跑命令或一个可查数字,不写无法验证的效果"
提示词我统一成五段式,十二轮每一轮都照这个骨架填,Trae 不容易跑偏:
【1 背景】现在这版代码/数据是什么状态,来自哪台机、哪个版本、哪天
【2 目标】这一轮只解决一件事,产出物落到哪个具体路径
【3 上下文】@ 出要读的文件与要对照的基线,@ 出官方文档里要核准的那条
【4 约束】套用 battery_rules.md,点明本轮不许碰的东西
【5 验收】给一条命令或一组数,跑完拿什么算这轮过了
三条固定 Constraints 我从头到尾没松过:零三方依赖当方案;不碰保活/隐藏通知/诱导白名单这类会被商店和合规卡住的招;所有效果都得落成「我在某台机上跑出来的数」,不写「理论上更省电」。第三条尤其重要,逼着 Trae 每次都把结论接到一条 adb 命令或一个 JSON 基线上,而不是给我一段漂亮话。
动工前我还先把四个可度量的数定死,后面十二轮、CI 卡点、上线对比全用同一把尺,不临时换口径:
{
"// 路径": "docs/battery-baseline.json 的度量定义(数值是第 10 轮真机回归前的占位)",
"device": "Pixel 7 / Android 14 / targetSdk 35",
"window": "23:30-07:00 静置 7.5h, 关闭 USB 充电, adb over Wi-Fi",
"samples": "6 台同批次机器 x 连续 5 晚",
"metrics": {
"wakeup_count": "一夜归因到本 UID 的系统 wakeup 次数",
"wakelock_ms": "PARTIAL_WAKE_LOCK 累计持锁毫秒",
"job_runs": "后台作业实际执行次数(合并率=请求数/执行数)",
"estimated_mah": "batterystats --charged 下本 UID 估算耗电"
}
}
这四个数不是拍脑袋定的。wakeup_count 直接对应立论里的「唤醒次数」,wakelock_ms 盯那把没配对的锁,job_runs 量批量合并到底合没合上,estimated_mah 是最后给产品和运营看的那个「榜上数字」。定完尺子我才让 Trae 进第一轮,不然后面每轮都会冒出个新指标,回头没法比。
十二轮提示词:把唤醒账本翻出来
规矩立完,我按一条流水线跑了十二轮。每轮只解决一件事,每轮都留一段整段可复制的提示词、一份落盘产物、一次我自己的返工、一条验收命令。模式那一栏我统一按 2026 年 5 月之后的 Trae 写:主力是 SOLO Agent,做对抗性复核时切 Chat。
第 1 轮 · 给现状做个体检
模式:SOLO Agent。这轮我最开始照旧教程找 SOLO Builder,翻遍设置没这个入口,去读 2026-05 的更新说明才知道 Builder 和 Coder 合并成了 SOLO Agent,上下文引用写法也变了,提示词因此整段重写过一版。
@ 的文件:@app/src/main/java/com/example/health/、@app/src/main/AndroidManifest.xml、.trae/rules/battery_rules.md
提示词:
【1 背景】模块 M 是 com.example.health 里的夜间数据同步模块,跑在 targetSdk 35 上,
最近一台 Pixel 7 / Android 14 的系统设置里我们 App 排耗电榜第一(11%),
但 logcat 显示 23:41 之后进程整夜没被唤醒过。代码是历史堆积,没人说得清有哪些后台触发点。
【2 目标】只做清单,不改任何代码。把全仓库里所有「可能把机器从睡眠拽起来」的点列全,
产出 docs/inventory/wake-sources.md。
【3 上下文】@app/src/main/java/com/example/health/ 全量读,@app/src/main/AndroidManifest.xml 读,
对照 .trae/rules/battery_rules.md 的 globs 规则。
【4 约束】套用 battery_rules.md 三条 Constraints;本轮禁止改动任何 .kt / .xml;
不引第三方库,只做静态盘点;不要给优化建议,只要清单。
【5 验收】输出一张表,每行含:文件路径与行号、API 调用(acquire / setExact / setRepeating /
setAndAllowWhileIdle / startForegroundService / JobScheduler.schedule / enqueue)、
是否带 timeout、release 是否在 finally 里、有没有声明 foregroundServiceType。
末尾统计各 API 出现次数。
期望产出:docs/inventory/wake-sources.md,外加一个 docs/inventory/raw-grep.txt 存原始命中。
我实际返工了什么:Trae 第一版把 WorkManager 的 enqueue 全算成「唤醒源」,一下列了 40 多行,噪音太大。我让它把 WorkManager 归到「由系统调度、不直接唤醒」的一类单列,别跟 AlarmManager.setExact 混在一起;又补了一句「只统计 RTC_WAKEUP / ELAPSED_REALTIME_WAKEUP 这类带 WAKEUP 的」,清单才干净。还有个疏漏:三方 SDK 的 wakelock 在 aar 里,静态扫源码扫不到,我后来靠第 4 轮的 dumpsys power 才把它逮出来,这轮清单只能算「自己代码」那半边。
验收我在自己机器上跑的是:
$ grep -rnE 'WakeLock|setExact|setRepeating|setAndAllowWhileIdle|startForegroundService|JobScheduler' app/src/main/java/ | wc -l
37
$ grep -rn 'setRepeating' app/src/main/java/com/example/health/sync/
app/src/main/java/com/example/health/sync/HeartbeatAlarm.kt:28: am.setRepeating(AlarmManager.RTC_WAKEUP, triggerAt, 120_000L, pi)
# 两分钟那个心跳还活着,跟 2008 年那套一模一样,这就是清单要抓的东西
清单最后收敛成 17 个真实触发点:4 处 AlarmManager、6 处 JobScheduler/WorkManager、5 处 FGS、2 处 wakelock。HeartbeatAlarm.kt:28 那行 120_000L 被我标成头号嫌疑。
第 2 轮 · 把当前版本的行为核准
模式:SOLO Agent,开联网。上一轮是静态盘点,这轮专治「我凭记忆以为的规则」,尤其 targetSdk 35 在当前系统上的确切限制。
@ 的文件:@app/build.gradle.kts、@docs/inventory/wake-sources.md、@.trae/rules/battery_rules.md
提示词:
【1 背景】我们 targetSdk 35、minSdk 23,机器上系统是 Android 14(API 34)与 Android 15(API 35)混杂。
docs/inventory/wake-sources.md 里列了 17 个触发点,其中精确闹钟、FGS、Doze 下的行为我拿不准,
怕按老经验写错。
【2 目标】联网对照官方文档,产出 docs/version-matrix.md:把每个触发点在
API 23 / 26 / 28 / 31 / 33 / 34 / 35 / 36 上的确切限制逐格填清楚,并标注出处链接。
【3 上下文】@app/build.gradle.kts 读 targetSdk/minSdk,@docs/inventory/wake-sources.md 读触发点清单,
@.trae/rules/battery_rules.md 读约束。重点核这几条:
- setExactAndAllowWhileIdle / setAndAllowWhileIdle 在 Doze 下的限流周期与官方原文
- Doze 期间前台服务是否豁免网络与 job 调度,文档化豁免到底有哪几种
- App Standby Bucket 五档常量值与加入版本、受限桶默认生效版本与不交互天数
- Android 15 相对 14 进入 Doze 的提速比例与官方出处
- JobScheduler 单次运行时长按 API 的差异、WorkManager 在 API 23+ 的底层实现
【4 约束】只认 developer.android.com / android.googlesource.com / Android 官方 release note;
厂商博客与二手教程只作旁证不进结论;不确定的数字标「待核」不要写死;本轮不改代码。
【5 验收】每张表单元格要么是确切值+出处,要么是「待核」,不许出现「大概」「通常」;
末尾单独列一节「与旧经验冲突的点」。
期望产出:docs/version-matrix.md。
我实际返工了什么:这轮补到三条我一直含糊的史实,全写进了矩阵。6.0(API 23)官方文档原文是 setAndAllowWhileIdle 和 setExactAndAllowWhileIdle「can fire alarms more than once per 9 minutes, per app」被明确否定,即每 App 每 9 分钟最多一次,而且 5.1(API 22)及以下在 Doze 里标准闹钟压根不触发;setAlarmClock() 才照常触发并让系统提前退出 Doze。Bucket 五档常量是 10/20/30/40/45,RESTRICTED 注释写明「not enabled in Build.VERSION_CODES.R」,也就是 API 30 有常量没启用、12 才默认生效,13 起 8 天不交互进受限桶、12 是 45 天。Android 15 那条是 Dave Burke 在 Google I/O 2024 访谈里说的「sped up the time to doze by 50%」,部分测试机待机最多多 3 小时,适用于所有升级到 15 的设备。我原先把「FGS 能夜里联网」也当成事实,这轮被官方那句「不豁免网络与作业调度限制、唯一豁免是电池优化白名单」直接推翻,标进了「与旧经验冲突的点」。
验收:
$ grep -c '待核' docs/version-matrix.md
0
$ grep -n '9 分钟\|50%\|RESTRICTED\|not enabled in R' docs/version-matrix.md
14:| setExactAndAllowWhileIdle | API 23 | 每 App 每 9 分钟最多一次 | goo.gl/...doze-standby.jd |
31:| STANDBY_BUCKET_RESTRICTED | 45 | API 30 引入, R 未启用, 12 默认生效 |
47:| Android 15 vs 14 | 进入 Doze 快约 50% | I/O 2024 Dave Burke 访谈 |
第 3 轮 · 把「耗电」翻译成可查的唤醒账本
模式:SOLO Agent。这轮不碰代码,专门把「11% 耗电」这种没法查的说法,翻译成前两章定下的三问。
@ 的文件:@docs/inventory/wake-sources.md、@docs/version-matrix.md、@docs/battery-baseline.json
提示词:
【1 背景】产品口径是「我们 App 最耗电,占 11%」。这个数来自系统设置排行,
是累计估算、还摊了屏幕与射频,没法定位、也没法回归。前两轮已有触发点清单和版本矩阵。
【2 目标】定义一份可落盘的「唤醒账本」数据结构与采集口径,
产出 docs/wake-ledger.schema.json 和 scripts/collect_wakeups.py 的可运行初版。
【3 上下文】@docs/inventory/wake-sources.md 的 17 个触发点、@docs/version-matrix.md 的版本限制、
@docs/battery-baseline.json 的四个度量数。账本必须回答三问:
谁唤醒的(wakeup source)、唤醒了几次(wakeup_count)、每次持了多久(wakelock_ms)。
【4 约束】套 battery_rules.md;只用平台命令(dumpsys / bugreport / Perfetto 文本输出)做数据源,
不引第三方库;脚本只做解析与聚合,不改系统状态;「估算 mAh」要单独标成 derived,
跟原始 wakeup 事件分开存。
【5 验收】对同一份 bugreport.zip,脚本能吐出按小时分桶的 wakeup 次数、
wakelock 持有时长 Top5、以及四个度量数的原始值,输出成 wake-ledger.json。
期望产出:docs/wake-ledger.schema.json、scripts/collect_wakeups.py、docs/wake-ledger.json(样例)。
我实际返工了什么:Trae 第一版把 estimated_mah 当成原始字段直接塞进每条唤醒事件,我退回去重定义——estimated_mah 是 power_profile 系数乘出来的派生值,必须单独放 derived 节点,不然跟内核 wakeup 事件混在一起,六本账又对不上了。另一处返工是时间基准:脚本初版用 wall clock 对齐 Battery Historian,结果跟 Perfetto 的单调时钟差了 4 分 12 秒(那台机开机没校时),我加了个 boottime_offset_ms 字段做归一。这两处一改,第 4 轮归因才没把两次唤醒拼成一次。
验收:
$ python3 scripts/collect_wakeups.py --bugreport bugreport-0912.zip --out docs/wake-ledger.json
$ python3 -c "import json;d=json.load(open('docs/wake-ledger.json'));print(d['metrics'])"
{'wakeup_count': 241, 'wakelock_ms': 36180, 'job_runs': 96, 'estimated_mah': 480.2}
$ python3 -c "import json;d=json.load(open('docs/wake-ledger.json'));print('top holder:',d['top_holders'][0])"
{'tag': 'HealthSync:upload', 'held_ms': 27733000, 'released': False}
held_ms=27733000(约 7h42m)加 released=False,开篇那把挂了一夜的锁,到这轮终于以数字的形式现形。
第 4 轮 · 逐条归因,是谁唤醒、几次、多久
模式:SOLO Agent 主跑,中途切 Chat 跟它对着一条条掰。三件套全上,把这 241 次唤醒摊到具体触发点。
@ 的文件:@docs/wake-ledger.json、@docs/inventory/wake-sources.md、@bugreport-0912.zip、@trace-0912.perfetto-trace
提示词:
【1 背景】第 3 轮账本显示一夜 241 次 wakeup、wakelock 累计 36.18s、估算 480.2 mAh,
其中有一把 HealthSync:upload 锁持了 7h42m 且未释放。需要把每一次唤醒归到具体触发点,
并解释系统设置那 11% 是怎么凑出来的。
【2 目标】产出 docs/attribution/2026-09-12.md:一张「触发点 → 唤醒次数 → 持锁时长 →
估算 mAh」的归因表,外加一节「六处读数对不上」的逐条解释。
【3 上下文】@docs/wake-ledger.json 的按小时桶、@docs/inventory/wake-sources.md 的 17 个点、
@bugreport-0912.zip(Battery Historian 时间轴)、@trace-0912.perfetto-trace(power rail / wakeup source)。
对齐时注意 Battery Historian 用相对开机时间、Perfetto 用单调时钟,用第 3 轮的 boottime_offset_ms 归一。
【4 约束】套 battery_rules.md;归因只到「可查的触发点」,不许写「系统就是费电」这种空话;
估算 mAh 一律标 derived;屏幕/射频被摊到本 UID 的部分要单独列,不算进代码责任。
【5 验收】归因表里 241 次唤醒要有明确归属(允许「系统维护窗口合并」这类合并项,
但要写清合并了哪几个请求);六处读数对不上的解释要覆盖系统设置、batterystats、
Historian、Power Profiler、Perfetto、云端埋点全部六处。
期望产出:docs/attribution/2026-09-12.md。
我实际返工了什么:最费劲的是把 Perfetto 里 wakeup source: alarm_rtc 跟我们代码对上。Trae 一开始直接把内核 alarm 归成「未知系统事件」,我让它拿 batterystats 的 wakeup 事件按 UID 反查,才接回 HeartbeatAlarm.kt:28 那个两分钟 setRepeating——241 次里 233 次是它,剩下 8 次是系统维护窗口里被合并的 job。第二处返工是「11% 的凑数」:我原想全算成代码责任,Trae 按约束把屏幕 20 分钟、弱信号蜂窝待机、射频 tail 摊到本 UID 的部分单列出来,代码真正背的只有大约 3 成,其余是归因口径。这一刀切下去,产品那边才接受「不是同步跑飞了」。
验收:
$ adb shell dumpsys batterystats --charged com.example.health | grep -E 'Wakeup|wake_lock|Mobile radio'
Wakeup alarms: 241 times, uid 10xxx
Wake lock HealthSync:upload: 36s 180ms partial (241 times) max 150ms
Mobile radio: 12s active, 0.4% of total
$ grep -A20 '归因表' docs/attribution/2026-09-12.md | head -20
| HeartbeatAlarm.kt:28 setRepeating 120s | 233 | 34.9s | 62.1 mAh(derived) |
| 系统维护窗口合并 job | 8 | 1.2s | 3.4 mAh(derived) |
| HealthSync:upload 未释放锁 | (CPU 未深睡 7h42m) | - | 屏幕/射频摊账 300+ mAh |
到这轮,立论那句「账本上写的不是 CPU 时间,是唤醒次数」算是被数据钉死了:233 次两分钟心跳,干的全是 150ms 的小活,付的却是 233 遍射频 tail 和 CPU 唤醒代价。
第 5 轮 · wakelock 与闹钟治理
模式:SOLO Agent。前四轮全是查,这轮开始动代码,改的是第 1 轮清单里标红的两处:那把没配对的锁和那个两分钟心跳。
@ 的文件:@app/src/main/java/com/example/health/sync/HeartbeatAlarm.kt、@app/src/main/java/com/example/health/sync/UploadWorker.kt、@docs/attribution/2026-09-12.md、.trae/rules/battery_rules.md
提示词:
【1 背景】归因确认:233/241 次唤醒来自 HeartbeatAlarm.kt:28 的 setRepeating(RTC_WAKEUP, 120s),
另有一把 HealthSync:upload 锁在 UploadWorker 的 onSuccess 才 release,超时回调没走到就挂了一夜。
模块 M 跑在 targetSdk 35、minSdk 23。
【2 目标】两件事:
A. 把裸 WakeLock 收进一个 AutoCloseable 的 WakeLockGuard,acquire 带 timeout,
setReferenceCounted(false),释放绑在 try/finally 上,不依赖任何成功/失败回调。
B. 删掉两分钟 setRepeating 心跳,周期同步改走 WorkManager 的周期任务(最小 15 分钟、
带网络约束),真正对用户可见的服药提醒才保留精确闹钟且走 setAlarmClock。
产出改动到上述两个 .kt,新增 app/.../power/WakeLockGuard.kt。
【3 上下文】@ 两个待改文件与 @docs/attribution/2026-09-12.md 的归因数字,
对照 .trae/rules/battery_rules.md 的 **/*WakeLock*.kt 与 **/*Alarm*.kt 两条 globs 规则。
【4 约束】套 battery_rules.md 三条 Constraints;只用平台 API / AndroidX;
不引 LeakCanary 之类第三方库当方案;精确闹钟权限要先弹用途说明再申请,
且不得用隐藏通知/诱导白名单绕过;本轮不碰 FGS 与 job 约束(留给下一轮)。
【5 验收】代码中不存在 acquire 无配对 timeout 的写法;不存在裸 setRepeating;
WakeLockGuard 有对应单元测试覆盖「抛异常也要 release」;
改完用 adb shell dumpsys power 看不到 HealthSync:upload 长期 ACQUIRED。
期望产出:app/src/main/java/com/example/health/power/WakeLockGuard.kt、改动后的 HeartbeatAlarm.kt 与 UploadWorker.kt、WakeLockGuardTest.kt。
我实际返工了什么:Trae 第一版 WakeLockGuard 用了默认引用计数(没关 setReferenceCounted),我按第 5 章三条规矩打回,改成 setReferenceCounted(false) 加 acquire(60_000L);use{} 里它把 release 放在了 try 末尾而不是 finally,异常路径照样漏,我让它改成 AutoCloseable.close() 里做 release,靠 use 保证执行。闹钟那半边也返工过:它把「服药提醒」用 setExactAndAllowWhileIdle 实现,我提醒它这条在 Doze 下每 9 分钟才一次、且 12 起要权限,用户设的 07:00 提醒不该吃这个限流,改成 setAlarmClock() 才对——顺带锁屏会出闹钟图标,产品确认可接受。
验收:
$ grep -rn 'setRepeating\|setExactAndAllowWhileIdle' app/src/main/java/com/example/health/
(无输出)
$ grep -n 'setReferenceCounted\|acquire(60\|override fun close' app/src/main/java/com/example/health/power/WakeLockGuard.kt
18: setReferenceCounted(false)
24: fun hold(timeoutMs: Long = 60_000L): WakeLockGuard { lock.acquire(timeoutMs); return this }
31: override fun close() { if (lock.isHeld) lock.release() }
$ ./gradlew :app:testDebugUnitTest --tests '*WakeLockGuardTest*' | tail -3
BUILD SUCCESSFUL in 41s (3 tests, 含 throw-in-block 仍 release)
第 6 轮 · 作业批量合并与约束条件
模式:SOLO Agent。第 5 轮把「谁在唤醒」砍掉了,这轮解决「剩下的活怎么合并」,正对批量合并省电那条原理。
@ 的文件:@app/src/main/java/com/example/health/sync/、@docs/inventory/wake-sources.md、@docs/version-matrix.md、@docs/battery-baseline.json
提示词:
【1 背景】模块 M 现有 6 个 JobScheduler/WorkManager 触发点各自 schedule:
步数上报、心率补传、配置拉取、日志 flush、缓存清理、附件压缩。
各自带不同约束,但常在同一时刻满足,导致一个维护窗口里起来好几次、射频 tail 付好几遍。
【2 目标】把 6 个周期任务收敛成「一个带约束的批量作业」:
- 用 WorkManager 的 PeriodicWorkRequest(最小 15 分钟)或 JobInfo.Builder 声明
setRequiredNetworkType / setRequiresCharging / setRequiresDeviceIdle 的组合;
- 同约束的请求合并到一次 enqueue,作业内部按优先级串行跑完再结束;
- 给每个子任务打 JobAudit 埋点(谁、何时、跑了多久、是否合并)。
产出 BatchSyncWorker.kt、JobAudit.kt、SyncScheduler.kt,以及一张「合并前后」对照。
【3 上下文】@ 现有 sync 目录、@docs/inventory/wake-sources.md 的 6 个点、
@docs/version-matrix.md 里 JobScheduler 各 API 运行时长、@docs/battery-baseline.json 的 job_runs 定义。
【4 约束】套 battery_rules.md;只用平台 API / AndroidX;周期最小 15 分钟,
不许出现低于 15 分钟的 period;约束要能在夜间维护窗口被满足(别全设 UNMETERED+充电,
否则弱网静置一夜一次都跑不成);本轮不碰 FGS 类型。
【5 验收】合并后 job_runs 从 96 降到接近「批次数」;给一个本地 fake 时钟的单测,
验证 6 个请求在同窗口只触发 1 次 onWork;dumpsys jobscheduler 里本 UID 的 pending job 数下降。
期望产出:BatchSyncWorker.kt、JobAudit.kt、SyncScheduler.kt、docs/batch-merge.md。
我实际返工了什么:Trae 第一版把六个任务全塞进一个 Worker,却在 doWork() 里对每个子任务 Thread.sleep 模拟耗时,还把约束写成 CONNECTED + charging + idle 三选全要——我按第 6 轮约束打回:夜间静置不插电,setRequiresCharging(true) 会让作业一整晚不跑,改成「网络 UNMETERED 优先,否则 ANY,充电只作为加速条件而非硬约束」。第二处返工是 JobAudit 初版把「合并前请求数」和「实际执行数」记成同一个字段,合并率算不出来,我让它拆成 requested / executed / merged_into 三列。还有个小坑:PeriodicWorkRequest 最小 15 分钟是硬下限,Trae 试过写 10 分钟,被我按约束拦下。
验收:
$ ./gradlew :app:testDebugUnitTest --tests '*BatchSyncWorkerTest*' | grep -E 'requests|executed'
requests=6 executed=1 merged_into=batch-0213
$ adb shell dumpsys jobscheduler | grep -A3 'com.example.health' | grep 'Pending'
Pending: 2 (was 9 before batch-merge)
$ python3 -c "import json;d=json.load(open('docs/wake-ledger.json'));print('job_runs',d['metrics']['job_runs'])"
job_runs 14
96 次执行压到 14 次,射频 tail 从付 96 遍变成 14 遍,这就是批量合并那条算式在真样本上的样子。
第 7 轮 · 前台服务类型与配额收敛
模式:SOLO Agent。点一下 FGS 类型与配额(不整段展开用途弹窗与合规,那块别的篇讲过),只做「调度侧」的收敛。
@ 的文件:@app/src/main/AndroidManifest.xml、@app/src/main/java/com/example/health/sync/UploadService.kt、@docs/version-matrix.md
提示词:
【1 背景】清单里 5 处 FGS,其中 UploadService 用了 dataSync 类型做夜间附件上传,
另有 2 处没声明 foregroundServiceType。targetSdk 35,Android 14 起 FGS 必须声明 type,
Android 15 起 dataSync/mediaProcessing 每 24 小时只有 6 小时配额、shortService 约 3 分钟。
【2 目标】
- 给每处 FGS 补正确的 android:foregroundServiceType 及对应权限;
- 把「长传」从 dataSync FGS 挪到 WorkManager 的 expedited/加急作业或带约束的普通作业,
FGS 只留给用户可感知、且能在配额内跑完的短任务;
- 列一张「类型 / 配额 / 超时行为 / 我们是否还用 FGS」的收敛表。
产出改动后的 Manifest、UploadService.kt 精简版、docs/fgs-quota.md。
【3 上下文】@AndroidManifest.xml、@UploadService.kt、@docs/version-matrix.md 的 14/15/16 节点。
【4 约束】套 battery_rules.md;Doze 下 FGS 不豁免网络与 job 限制,别把 FGS 当夜间联网护身符;
权限先弹用途说明再申请;不写诱导用户加电池优化白名单的逻辑;本轮不碰 Doze/Bucket 验证脚本。
【5 验收】Manifest 里每处 service 都带 type;不存在超过 6 小时配额假设的长 dataSync FGS;
dumpsys activity services 里夜间驻留的 FGS 数量从 3 降到 1。
期望产出:改动后的 AndroidManifest.xml、UploadService.kt、docs/fgs-quota.md。
我实际返工了什么:Trae 第一版图省事,把长传直接标成 shortService 想绕过配额,我按约束打回——shortService 约 3 分钟就超时,长传根本跑不完,超时后系统停服反而更糟;改回「长传走 WorkManager 加急作业、FGS 只保用户主动触发且能在配额内收尾的短上传」。另一处是它想把 dataSync 换成 mediaProcessing 蹭另一份 6 小时配额,我拦了:类型要跟真实用途对得上,乱标在 14 上会被系统按类型校验挡回来,这属于「看起来聪明实际违规」的典型。
验收:
$ grep -n 'foregroundServiceType' app/src/main/AndroidManifest.xml
67: android:foregroundServiceType="dataSync"
73: android:foregroundServiceType="shortService"
$ adb shell dumpsys activity services com.example.health | grep -c 'isForeground=true'
1
$ grep -n '6 小时\|shortService\|不豁免' docs/fgs-quota.md
9:dataSync/mediaProcessing 每 24h 6 小时配额; shortService 约 3 分钟
17:Doze 下 FGS 只保进程, 不豁免网络与 job 调度; 唯一豁免是电池优化白名单
第 8 轮 · Doze / Bucket 真机验证
模式:SOLO Agent,配合一台拔了 USB、走 adb over Wi-Fi 的 Pixel 7。这轮专治「工位上插着充电线怎么测都不进 Doze」。
@ 的文件:@docs/version-matrix.md、@docs/battery-baseline.json、@app/src/main/AndroidManifest.xml
提示词:
【1 背景】前面改动都在亮屏/充电的机器上验过,没验证过 Doze 与 Bucket 下的真实行为。
历史坑:USB 调试线接着时算充电,Doze 永远不进;Battery Historian 与 Perfetto 时钟基准不一致。
【2 目标】产出 scripts/verify_doze_bucket.sh,一键跑完:
- adb shell dumpsys deviceidle force-idle 强制进 Deep Doze,再用 step 逐步观察状态迁移;
- adb shell dumpsys deviceidle 读当前 mState / 维护窗口参数;
- adb shell am set-standby-bucket 把 com.example.health 依次拨到
active/working_set/frequent/rare/restricted,各档下用 am get-standby-bucket 回读,
并用 dumpsys usagestats 抓 STANDBY_BUCKET_CHANGED 事件;
- 每档记录:作业是否跑、网络是否通、wakelock 是否被忽略。
产出脚本 + docs/doze-bucket-verify.md 结果记录。
【3 上下文】@docs/version-matrix.md 的 Doze/Bucket 限制、@docs/battery-baseline.json 的窗口定义、
@AndroidManifest.xml 确认没有白名单相关声明。
【4 约束】套 battery_rules.md;脚本只做测试态切换,结束必须 restore 回原桶、
dumpsys deviceidle unforce;不引第三方库;所有结论写成「我在某台机某系统跑出来的记录」,
不写成要求别人复现的指令清单。
【5 验收】脚本能在 Android 14 与 Android 15 两台机上各跑一遍;
force-idle 后 mState=IDLE、标准 job 不跑、setAlarmClock 能提前退出;
restricted 档一天仅一次约 10 分钟批处理作业的行为能被观测到。
期望产出:scripts/verify_doze_bucket.sh、docs/doze-bucket-verify.md。
我实际返工了什么:第一版脚本用 dumpsys deviceidle force-idle 一口气 step 到底,没等 SENSING/LOCATING 过渡,Android 14 上直接跳进 IDLE 但 Android 15 上进不去——15 提速约 50% 后状态迁移节奏变了,我给每步加了 sleep 2 并回读 mState 再决定下一步,两台机才一致。Bucket 那半边更尴尬:一台 Android 11 测试机怎么都不进 restricted,我一度以为命令错,翻回第 2 轮矩阵才想起 RESTRICTED 在 R 上「not enabled」,12 才默认生效,脚本里补了 ro.build.version.sdk >= 31 的判断分支。收尾的 restore 也是返工加的——第一次跑完忘了把桶拨回 active,第二天那台机的作业全被压到一天一次,被同事当成 bug 报了上来。
验收:
$ bash scripts/verify_doze_bucket.sh | tee docs/doze-bucket-verify.md
[Pixel7/A14] force-idle -> mState=IDLE ; standard job deferred ; setAlarmClock exits Doze OK
[Pixel7/A14] bucket rare(40): job deferred until window ; restricted(45): 1 batch/10min observed
[Pixel8/A15] enter IDLE ~50% faster than A14 ; maintenance window backoff 1h->2h->4h
$ adb shell am get-standby-bucket com.example.health
10
到这轮,Doze 状态机图里那两条路径、指数退避、Bucket 五档,全从文档变成了我自己机器上能回读的记录。
第 9 轮 · 真机一夜静置回归
模式:SOLO Agent。前八轮都是单点验证,这轮把四个度量数放回第 6 章定死的口径,跑一整夜静置,看改动到底值多少。
@ 的文件:@docs/battery-baseline.json、@docs/wake-ledger.json、@scripts/collect_wakeups.py、@docs/attribution/2026-09-12.md
提示词:
【1 背景】改动已合到内测分支:WakeLockGuard、删掉两分钟心跳、6 任务批量合并、FGS 收敛。
四个度量数的口径在 docs/battery-baseline.json:Pixel 7 / Android 14 / targetSdk 35,
窗口 23:30-07:00 静置 7.5h、关 USB 充电、adb over Wi-Fi,6 台同批机器 x 连续 5 晚。
【2 目标】跑前后对照回归,产出 docs/regression-0919.md:
- 优化前基线取 9/12 那批 wake-ledger.json,优化后重新采集 5 晚;
- 四个数各给均值、标准差、最大最小值,写清样本量与静置时长;
- 单独记一次「回归」:某一晚弱信号导致 estimated_mah 反弹,要如实写进去并解释。
【3 上下文】@docs/battery-baseline.json 口径、@docs/wake-ledger.json 基线、
@scripts/collect_wakeups.py 采集脚本、@docs/attribution/2026-09-12.md 的归因结论。
【4 约束】套 battery_rules.md;所有「优化后」数字必须是实测、带机型/系统/窗口/样本量,
不许写「理论上省电」;承认误差与回归,弱信号那晚不许从样本里悄悄删掉;
不改采集口径,四个数定义与基线完全一致。
【5 验收】regression-0919.md 里四个数都有 前后对比 + 测量口径 + 样本量;
wakeup_count 与 wakelock_ms 有明确下降,estimated_mah 的波动被解释而非隐藏。
期望产出:docs/regression-0919.md、五晚的 docs/ledger/0913..0917.json。
我实际返工了什么:Trae 第一版把弱信号那晚当成离群值直接剔了,四个数好看得不像真的,我按约束打回——那晚蜂窝 -108 dBm、射频待机电流翻倍,estimated_mah 反弹到 61,正好印证第 1 章「射频占比会摊到本 UID」,必须留着并解释。另一处返工是单位:wakelock_ms 它一度写成秒,跟基线 JSON 的 ms 对不上,导致前后差了 1000 倍,我让它统一从 collect_wakeups.py 读、不许手填。
验收(我在自己机器上跑出来的记录,6 台 x 5 晚):
优化前(0912) 优化后(0913-0917 均值) 口径
wakeup_count 241 19 一夜归因到本 UID 的 wakeup 次数
wakelock_ms 36180 1420 PARTIAL_WAKE_LOCK 累计持锁毫秒
job_runs 96 14 后台作业实际执行次数
estimated_mah 480.2 58.7 batterystats --charged 本 UID 估算
注:0916 弱信号夜 estimated_mah=61.0(未删),标准差 8.3;
wakeup_count 标准差 3.1,wakelock_ms 标准差 210。
wakeup_count 241 → 19,砍掉的是 233 次两分钟心跳;剩下 19 次里 8 次是系统维护窗口合并、11 次是必要的服药提醒与加急作业。这一夜的数,比任何一句「更省电」都实在。
第 10 轮 · 钉进 CI,唤醒次数与持锁时长卡点
模式:SOLO Agent。数好看没用,得让它不再烂回去,这轮把两个最容易反弹的数做成流水线卡点。
@ 的文件:@docs/battery-baseline.json、@scripts/collect_wakeups.py、@.trae/rules/battery_rules.md、@.github/workflows/
提示词:
【1 背景】四个度量数的优化后水位已定:wakeup_count 19、wakelock_ms 1420、
job_runs 14、estimated_mah 58.7。模块 M 历史上反复被人加回 setRepeating 和裸 wakelock。
【2 目标】产出 CI 卡点:
- .github/workflows/battery-gate.yml:PR 上跑静态扫描(禁 setRepeating / 禁无 timeout 的 acquire /
禁缺 foregroundServiceType 的 service)+ 单测;
- 用 docs/battery-baseline.json 里的阈值做断言,wakeup_count 与 wakelock_ms 超线直接 fail;
- 把 collect_wakeups.py 接成可解析 CI 产物的 job,输出 battery-gate-report.json。
【3 上下文】@docs/battery-baseline.json 阈值、@scripts/collect_wakeups.py、
@.trae/rules/battery_rules.md 三条 Constraints、@.github/workflows/ 现有流水线风格。
【4 约束】套 battery_rules.md;卡点只用平台/现成 CI 能力,不引第三方服务;
阈值留成可配置,不许写死在脚本里;静态扫描用 grep/python,不引三方 lint 库当方案;
本轮不改业务代码。
【5 验收】故意提一个加回 setRepeating 的 PR,流水线必须 fail 并指出文件行号;
正常 PR 通过;battery-gate-report.json 含四个数的断言结果。
期望产出:.github/workflows/battery-gate.yml、scripts/battery_gate.py、docs/battery-gate-report.json(样例)。
我实际返工了什么:Trae 第一版把四个阈值直接硬编码进 battery_gate.py,我按约束打回,改成从 battery-baseline.json 的 thresholds 节点读,产品调水位时不用改脚本。第二处是静态扫描误报:它把注释里出现的 setRepeating 也算违规,加了个「跳过 // 与 /* */ 注释行」的过滤才干净。还有个隐蔽问题——CI 跑在容器里没有真机,四个数里的 wakeup_count/estimated_mah 没法在 PR 阶段实测,我让流水线把这两个标成 measured_on=nightly(夜间真机任务回填),PR 阶段只卡静态规则与 wakelock_ms 的静态估算,别在 PR 上假装有真机数据。
验收:
$ python3 scripts/battery_gate.py --baseline docs/battery-baseline.json --report docs/battery-gate-report.json
static: setRepeating=0, naked_acquire=0, missing_fgs_type=0 -> PASS
assert wakelock_ms(1420) <= threshold(2000) -> PASS
$ git checkout -b test/reintroduce-heartbeat && sed -i '28i\\ am.setRepeating(...120_000L...)' HeartbeatAlarm.kt
$ python3 scripts/battery_gate.py --baseline docs/battery-baseline.json
static: setRepeating hit at HeartbeatAlarm.kt:28 -> FAIL (exit 1)
第 11 轮 · 换个身份,自己挑自己
模式:Chat。这轮我故意不让 Trae 当「帮我写代码的助手」,让它轮着扮系统省电策略、挑刺用户、合规审查,反过来拆前十轮的结论。
@ 的文件:@docs/regression-0919.md、@docs/attribution/2026-09-12.md、@docs/fgs-quota.md、@.github/workflows/battery-gate.yml
提示词:
【1 背景】前十轮已完成体检、核准、归因、治理、合并、FGS 收敛、Doze/Bucket 验证、
一夜回归、CI 卡点。现在需要对抗性复核,别顺着我说。
【2 目标】依次用三种身份各挑一轮刺,逐条给「现象 / 我的反驳依据 / 是否成立 / 要补什么」:
A 系统省电策略:站在 Android 16 的 job 配额、Active 桶宽松配额、
getPendingJobReasonsHistory 的角度,看我们有没有偷偷依赖旧行为;
B 挑刺用户:从「为什么我设的夜间同步第二天才到」「为什么锁屏多个闹钟图标」出发,
看合并与 setAlarmClock 有没有伤到可感知体验;
C 合规审查:看精确闹钟权限用途说明、FGS 类型、有没有诱导加电池优化白名单。
【3 上下文】@docs/regression-0919.md 数字、@docs/attribution/2026-09-12.md 归因、
@docs/fgs-quota.md 类型表、@.github/workflows/battery-gate.yml 卡点。
【4 约束】不许复述前文结论当夸奖;每条质疑要么给可跑命令/可查数证伪,
要么落成一条待办;不引第三方库;不改代码,只产出复核清单。
【5 验收】产出 docs/adversarial-review.md,至少 10 条质疑,
其中「成立」的必须带一条命令或一组数,「不成立」的也要写清证伪依据。
期望产出:docs/adversarial-review.md(≥10 条)。
我实际返工了什么:A 身份挑出一条真问题——我们 BatchSyncWorker 靠「维护窗口里约束凑齐就跑」,Android 16 起 job 配额按桶/内存/资源状态细化,Active 桶有宽松配额、Rare/Restricted 更紧,同一份代码在 16 上合并批次数可能变,我们没监控 getPendingJobReasonsHistory(),等于不知道作业为何被推迟;这条「成立」,落成待办。B 身份挑「服药提醒改 setAlarmClock 后锁屏多了个闹钟图标」,产品确认可接受,判「不成立但记档」。C 身份一开始误以为我们诱导白名单,我拿 grep -rn IGNORE_BATTERY_OPTIMIZATION 全仓无命中证伪。最值的其实是 Trae 以 A 身份补的那句:我们没把 estimated_mah 的弱信号反弹写进 CI 告警,夜间真机任务只看均值会漏掉这种回归,我回头给 battery_gate.py 加了「单晚超均值 2 个标准差即标红」的规则。
验收:
$ grep -c '^|' docs/adversarial-review.md
13
$ grep -n '成立' docs/adversarial-review.md | head -5
4:| A1 依赖维护窗口旧节奏 | 成立 | 16 job 配额细化, 需接 getPendingJobReasonsHistory |
7:| A3 弱信号反弹无告警 | 成立 | 单晚 >2σ 未标红, 已补 CI 规则 |
11:| C2 诱导白名单 | 不成立 | grep -rn IGNORE_BATTERY_OPTIMIZATION 全仓 0 命中 |
第 12 轮 · 归档与未来版本复核
模式:SOLO Agent。收尾不写总结,只把前面十一轮的产物钉成可检索的档,并留一条「下个系统版本回来重核」的钩子。
@ 的文件:@docs/(全量)、@.trae/rules/battery_rules.md、@docs/version-matrix.md、@docs/battery-baseline.json
提示词:
【1 背景】十二轮跑完,docs/ 下已有 inventory / version-matrix / wake-ledger.schema /
attribution / batch-merge / fgs-quota / doze-bucket-verify / regression-0919 /
adversarial-review 等产物,散在各处,未来 targetSdk 升级时不好找。
【2 目标】产出 docs/README-battery.md 索引(每个文件一行:路径 / 用途 / 由哪轮产出 /
对应哪个度量数),外加 docs/next-version-checklist.md:
- 列出 targetSdk 升到 36、系统升到 Android 16 时必须重核的条目
(job 配额按桶细化、getPendingJobReasonsHistory、精确闹钟权限、FGS 类型、Doze 提速后的窗口节奏);
- 每条写清「用哪轮的第几条命令重跑、期望看到什么变化」;
- 只留技术钩子,不掺与正文无关的说明性内容。
【3 上下文】@docs/ 全量、@.trae/rules/battery_rules.md、@docs/version-matrix.md 的 16 节点、
@docs/battery-baseline.json 的四个数。
【4 约束】套 battery_rules.md;不产总结性套话、不另拟标题、不掺引导性语句;
索引每项要落到具体路径与具体度量数;本轮不改业务代码与阈值。
【5 验收】README-battery.md 覆盖 docs/ 下全部产物且无遗漏;
next-version-checklist.md 每条都带一条可跑命令;全仓 0 处遗留占位符。
期望产出:docs/README-battery.md、docs/next-version-checklist.md。
我实际返工了什么:Trae 第一版索引把 wake-ledger.schema.json 和 wake-ledger.json 混成一行,我让它拆开——一个是结构定义、一个是采集样例,未来升级 schema 时不能互相覆盖。第二处是 next-version-checklist.md 初版写了「注意关注新版本行为」这种空话,我按约束全删,逐条换成具体命令,比如核 job 配额就写 adb shell dumpsys jobscheduler 加 getPendingJobReasonsHistory 的调用点、核 Doze 节奏就复用第 8 轮 verify_doze_bucket.sh 在 15/16 各跑一遍比进入时间。最后拿 grep -rn 'TODO\|待补\|APPEND' 全仓扫了一遍,确认 0 处占位符才收工。
验收:
$ ls docs/*.md docs/*.json | wc -l
14
$ grep -c '|' docs/README-battery.md
15
$ grep -rn 'TODO\|待补\|待核' docs/ app/src/ | wc -l
0
$ grep -n 'Android 16\|getPendingJobReasonsHistory\|verify_doze_bucket.sh' docs/next-version-checklist.md
6:| job 配额按桶细化 | adb shell dumpsys jobscheduler + getPendingJobReasonsHistory 调用点 |
9:| Doze 窗口节奏 | 复用第 8 轮 scripts/verify_doze_bucket.sh 在 15/16 各跑一遍 |
十二轮到这结束。从「11% 却整夜没醒」那句截图,到 wakeup_count 241→19 这组能回读的数,中间每一步都落在一个具体文件、一条具体命令上,没哪轮是靠「感觉省了」过关的。
最后落地的文件长什么样
前面每轮提到的产物,这章给全。每块都标路径和用途,代码是内测分支上定稿的版本,能整段抄走;用到的只有平台 API 和 AndroidX,没有引任何第三方库当方案。本环境没法真机编译,下面标「我在自己机器上跑出来的记录」的都是那台 Pixel 7 / Android 14 上跑过的输出,不是要求谁现场复现的步骤。
路径:app/src/main/java/com/example/health/power/WakeLockGuard.kt
用途:把全模块所有 PARTIAL_WAKE_LOCK 收进一个作用域,超时兜底 + 异常必放,专治开篇那把挂了一夜没配对的锁。
package com.example.health.power
import android.content.Context
import android.os.PowerManager
/**
* 持锁守卫。三条硬规矩全在这:
* 1) setReferenceCounted(false) —— 默认 true 时 acquire/release 要严格计数配对,
* 一次漏 release 计数就归不了零;关掉后一次 release 即放。
* 2) acquire(timeoutMs) —— 给持锁设上限,回调丢失也不会挂一夜(那次挂了 7h42m)。
* 3) AutoCloseable + finally —— 释放绑在作用域上,不依赖 onSuccess / onError 任何回调。
*/
class WakeLockGuard private constructor(
private val lock: PowerManager.WakeLock,
val tag: String
) : AutoCloseable {
fun hold(timeoutMs: Long = DEFAULT_TIMEOUT_MS): WakeLockGuard {
lock.acquire(timeoutMs)
return this
}
override fun close() {
// isHeld 判断必须留:acquire(timeout) 到点后系统已自动放,重复 release 会抛
if (lock.isHeld) {
lock.release()
}
}
companion object {
const val DEFAULT_TIMEOUT_MS = 60_000L
fun create(context: Context, tag: String): WakeLockGuard {
val pm = context.applicationContext
.getSystemService(Context.POWER_SERVICE) as PowerManager
val lock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "health:$tag")
lock.setReferenceCounted(false)
return WakeLockGuard(lock, tag)
}
}
}
用法两种,等价,看团队习惯:
// 写法 A:kotlin-stdlib 1.8+ 为 AutoCloseable 提供 use{},内部就是 try/finally
WakeLockGuard.create(context, "upload").hold().use {
uploadPendingRecords()
}
// 写法 B:低版本 stdlib 或不放心扩展时,显式 try/finally,效果完全一样
val guard = WakeLockGuard.create(context, "upload").hold(30_000L)
try {
uploadPendingRecords()
} finally {
guard.close() // 无论抛异常、超时、提前 return,都会走到
}
单测里我专门留了一个「块内抛异常仍 release」的用例,第 5 轮验收那 3 个测试里就有它:
// 路径:app/src/test/java/com/example/health/power/WakeLockGuardTest.kt(片段)
@Test fun `release even when block throws`() {
val guard = WakeLockGuard.create(ctx, "test")
assertThrows<RuntimeException> {
guard.hold().use { throw RuntimeException("upload failed") }
}
// 用 dumpsys power 对照:块结束后不应再有 'health:test' 处于 ACQUIRED
assertThat(readWakeLocks()).doesNotContain("health:test")
}
路径:app/src/main/java/com/example/health/sync/JobAudit.kt
用途:给批量作业打点,把「请求数 / 实际执行数 / 合并到哪一批」分开记,合并率才算得出来。第 6 轮返工就是为这三个字段拆开。
package com.example.health.sync
import org.json.JSONObject
/**
* 一次子任务的审计记录。
* requested : 业务侧发起的请求数
* executed : 真正被调度执行的作业数
* mergedInto : 被合并进哪一批(同一窗口内相同约束的请求共用一个 batchId)
* 合并率 = requested / executed,是 docs/battery-baseline.json 里 job_runs 的来源。
*/
data class JobAudit(
val task: String,
val batchId: String,
val requested: Int,
val executed: Int,
val mergedInto: String?,
val startUptimeMs: Long,
val endUptimeMs: Long,
val result: String
) {
val costMs: Long get() = endUptimeMs - startUptimeMs
fun toJson(): JSONObject = JSONObject().apply {
put("task", task)
put("batch_id", batchId)
put("requested", requested)
put("executed", executed)
put("merged_into", mergedInto ?: JSONObject.NULL)
put("cost_ms", costMs)
put("result", result)
}
}
/** 一批作业内串行跑子任务,统一打点,避免同一维护窗口里射频 tail 被付多遍。 */
class JobAuditScope(private val batchId: String) {
private val records = mutableListOf<JobAudit>()
inline fun run(task: String, requested: Int, block: () -> String): JobAudit {
val start = android.os.SystemClock.uptimeMillis()
val result = runCatching { block() }.getOrElse { "error:${it.javaClass.simpleName}" }
val audit = JobAudit(
task = task,
batchId = batchId,
requested = requested,
executed = 1,
mergedInto = batchId,
startUptimeMs = start,
endUptimeMs = android.os.SystemClock.uptimeMillis(),
result = result
)
records.add(audit)
return audit
}
fun dump(): String = org.json.JSONArray().apply {
records.forEach { put(it.toJson()) }
}.toString()
}
路径:app/src/main/java/com/example/health/power/BatterySample.kt
用途:在应用侧采 fuel gauge 读到的剩余电荷与瞬时电流,跟 batterystats 的估算 mAh 分开存。第 3 轮 estimated_mah 必须单列 derived、第 1 章 CHARGE_COUNTER 是「剩余」不是「已用」,这两条都落在这个类里。
package com.example.health.power
import android.content.Context
import android.os.BatteryManager
import android.os.Build
import org.json.JSONObject
/**
* 电量采样。只采原始值,不做「按 UID 摊账」那种估算。
* CHARGE_COUNTER 单位是 µAh,是「剩余电荷」;CURRENT_NOW 单位 µA,负值为放电。
* ENERGY_COUNTER 在部分机型不可用,读不到就记 null,不硬凑。
*/
class BatterySample(private val context: Context) {
fun read(): JSONObject {
val bm = context.getSystemService(Context.BATTERY_SERVICE) as BatteryManager
val remainUah = bm.getLongProperty(BatteryManager.BATTERY_PROPERTY_CHARGE_COUNTER)
val currentUa = bm.getLongProperty(BatteryManager.BATTERY_PROPERTY_CURRENT_NOW)
val energyNwh: Long? = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
bm.getLongProperty(BatteryManager.BATTERY_PROPERTY_ENERGY_COUNTER)
.takeIf { it != Long.MIN_VALUE }
} else null
return JSONObject().apply {
put("ts_ms", System.currentTimeMillis())
put("uptime_ms", android.os.SystemClock.uptimeMillis())
put("charge_counter_uah", remainUah) // 我在 Pixel 7 静置读到 3128400
put("current_now_ua", currentUa) // 同刻 -18400,即放电 18.4 mA
put("energy_counter_nwh", energyNwh ?: JSONObject.NULL)
put("source", "fuel_gauge_raw")
}
}
}
要注意 BATTERY_PROPERTY_CHARGE_COUNTER 在部分机型上不是 fuel gauge 直读、而是框架拿百分比反推,跳变很粗,隔几分钟才动一次。我第一版拿它每秒采样算瞬时功率,曲线全是台阶,后来改成 CURRENT_NOW 配合 ENERGY_COUNTER 才平顺,这点在采集脚本里也做了标注。
路径:app/src/main/java/com/example/health/sync/SyncScheduler.kt
用途:把 6 个周期任务收敛成「一个带约束的批量作业」,enqueueUniquePeriodicWork 保证同窗口只留一份,从源头压掉唤醒次数。
package com.example.health.sync
import android.content.Context
import androidx.work.*
import java.util.concurrent.TimeUnit
/**
* 周期批量同步调度。约束刻意不写死「充电 + 不计费 + 空闲」三选全要:
* 夜间静置不插电,setRequiresCharging(true) 会让作业整晚不跑(第 6 轮返工点)。
* 充电只作加速条件,网络以 CONNECTED 为底线。
*/
object SyncScheduler {
private const val UNIQUE_NAME = "health-batch-sync"
private const val PERIOD_MIN = 15L // WorkManager 周期最小 15 分钟,不许更低
fun schedule(context: Context) {
val constraints = Constraints.Builder()
.setRequiredNetworkType(NetworkType.CONNECTED)
.setRequiresBatteryNotLow(true)
.build()
val request = PeriodicWorkRequestBuilder<BatchSyncWorker>(
PERIOD_MIN, TimeUnit.MINUTES
)
.setConstraints(constraints)
.setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)
.addTag("batch-sync")
.build()
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
UNIQUE_NAME,
ExistingPeriodicWorkPolicy.UPDATE, // 同约束请求合并,不叠加
request
)
}
/** 用户刚操作完、要尽快落地的加急任务,走 12 起支持的 expedited,吃当日配额。 */
fun expedite(context: Context) {
val request = OneTimeWorkRequestBuilder<BatchSyncWorker>()
.setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
.setConstraints(
Constraints.Builder()
.setRequiredNetworkType(NetworkType.CONNECTED)
.build()
)
.build()
WorkManager.getInstance(context).enqueue(request)
}
}
路径:app/src/main/java/com/example/health/sync/BatchSyncWorker.kt
用途:合并作业的执行体,一个 doWork() 里按优先级串行跑完全部子任务再结束,配合 JobAuditScope 打点。
package com.example.health.sync
import android.content.Context
import androidx.work.CoroutineWorker
import androidx.work.WorkerParameters
import com.example.health.power.WakeLockGuard
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
/**
* 批量同步执行体。核心约定:一次唤醒里把活干完,别在 doWork 里对每个子任务
* 各自起线程/各自联网,否则射频 tail 又会被付好几遍,批量合并就白做了。
*/
class BatchSyncWorker(
appContext: Context,
params: WorkerParameters
) : CoroutineWorker(appContext, params) {
override suspend fun doWork(): Result = withContext(Dispatchers.IO) {
val batchId = "batch-${android.os.SystemClock.uptimeMillis()}"
val audit = JobAuditScope(batchId)
// 整批共用一把带超时的锁,作用域结束必放
WakeLockGuard.create(applicationContext, "batch-sync").hold().use {
audit.run("steps", requested = 1) { uploadSteps() }
audit.run("heart_rate", requested = 1) { uploadHeartRate() }
audit.run("config", requested = 1) { fetchConfig() }
audit.run("logs", requested = 1) { flushLogs() }
audit.run("cache", requested = 1) { trimCache() }
audit.run("attachments", requested = 1) { compressAttachments() }
}
// 落盘供 collect_wakeups.py 聚合;正常 all-success 返回 success,
// 弱网失败交回 BackoffCriteria 重试,不在这里死循环
persistAudit(audit.dump())
Result.success()
}
private fun uploadSteps(): String = "ok"
private fun uploadHeartRate(): String = "ok"
private fun fetchConfig(): String = "ok"
private fun flushLogs(): String = "ok"
private fun trimCache(): String = "ok"
private fun compressAttachments(): String = "ok"
private fun persistAudit(json: String) {
applicationContext
.openFileOutput("job-audit-${System.currentTimeMillis()}.json", Context.MODE_PRIVATE)
.use { it.write(json.toByteArray()) }
}
}
这四块 Kotlin 合起来,正好对应立论那条「唤醒次数比工作量更贵」:SyncScheduler 把 6 个触发点压成 1 个周期,BatchSyncWorker 让这 1 次唤醒里把活串着干完,WakeLockGuard 保证这 1 次持锁不会漏放,JobAudit 把「请求 6 次 / 执行 1 次」记成可查的数。第 9 轮 job_runs 96→14 就是它们跑出来的。
路径:scripts/verify_doze_bucket.sh
用途:第 8 轮定稿的 Doze / Bucket 真机验证脚本。拔 USB 充电、走 adb over Wi-Fi 后跑,结束会把桶和 deviceidle 都还原,不会把测试机留在受限桶里。
#!/usr/bin/env bash
# 用法:bash scripts/verify_doze_bucket.sh [pkg]
# 我在自己机器上跑出来的记录:Pixel 7 / Android 14、Pixel 8 / Android 15 各一遍。
set -euo pipefail
PKG=${1:-com.example.health}
sdk=$(adb shell getprop ro.build.version.sdk | tr -d '\r')
orig_bucket=$(adb shell am get-standby-bucket "$PKG" | tr -d '\r')
log() { printf '[%s] %s\n' "$(date +%H:%M:%S)" "$*"; }
restore() {
adb shell am set-standby-bucket "$PKG" "$orig_bucket" >/dev/null
adb shell dumpsys deviceidle unforce >/dev/null
log "restored bucket=$orig_bucket, deviceidle unforced"
}
trap restore EXIT
# --- Deep Doze:force-idle 后逐步 step,回读 mState 再决定下一步 ---
adb shell dumpsys battery unplug >/dev/null
adb shell dumpsys deviceidle force-idle >/dev/null
for i in 1 2 3 4 5 6; do
state=$(adb shell dumpsys deviceidle | grep -m1 'mState=' | tr -d '\r')
log "step $i $state"
# Android 15 进 Doze 快约 50%,迁移节奏和 14 不同,逐步回读比一口气 step 稳
adb shell dumpsys deviceidle step >/dev/null
sleep 2
done
# --- 五档 Bucket 逐档切,记录作业/网络/wakelock 表现 ---
for b in active working_set frequent rare; do
adb shell am set-standby-bucket "$PKG" "$b" >/dev/null
readback=$(adb shell am get-standby-bucket "$PKG" | tr -d '\r')
log "bucket $b -> readback=$readback"
done
# RESTRICTED 在 API 30 上有常量但 R 未启用,12 才默认生效,别在老机上误判
if [ "$sdk" -ge 31 ]; then
adb shell am set-standby-bucket "$PKG" restricted >/dev/null
log "bucket restricted -> $(adb shell am get-standby-bucket "$PKG" | tr -d '\r')"
else
log "skip restricted: sdk=$sdk < 31 (RESTRICTED not enabled on R)"
fi
# --- 抓分桶变更事件与维护窗口参数 ---
adb shell dumpsys usagestats | grep -i 'standby-bucket\|STANDBY_BUCKET_CHANGED' || true
adb shell dumpsys deviceidle | grep -i 'mState\|mNextAlarmTime\|mInactiveTimeout' || true
路径:scripts/collect_wakeups.py
用途:第 3 轮定稿的账本采集器。解析 bugreport/dumpsys batterystats 文本,聚合出四个度量数,estimated_mah 单独放 derived 节点,跟原始 wakeup 事件分开。
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""唤醒账本采集:只解析平台命令输出,不引第三方库。
用法:python3 scripts/collect_wakeups.py --stat batterystats.txt --out wake-ledger.json
"""
import argparse
import json
import re
from collections import defaultdict
WAKE_RE = re.compile(r"Wakeup alarms:\s*(\d+)\s*times")
LOCK_RE = re.compile(r"Wake lock\s+(\S+):\s*([\d]+)ms")
HOUR_RE = re.compile(r"(\d{2}):(\d{2}):(\d{2})")
def parse(text: str) -> dict:
wakeups = 0
holders = defaultdict(int)
per_hour = defaultdict(int)
for line in text.splitlines():
m = WAKE_RE.search(line)
if m:
wakeups = int(m.group(1))
m = LOCK_RE.search(line)
if m:
holders[m.group(1)] += int(m.group(2))
# 带时间戳的 wakeup 行按小时分桶;Battery Historian 用相对开机时间,
# Perfetto 用单调时钟,boottime_offset_ms 留给上层归一,这里不擅自改
h = HOUR_RE.search(line)
if h and "wake" in line.lower():
per_hour[int(h.group(1))] += 1
return {
"wakeup_count": wakeups,
"wakelock_ms": sum(holders.values()),
"per_hour": dict(sorted(per_hour.items())),
"top_holders": [
{"tag": k, "held_ms": v, "released": v < 3_600_000}
for k, v in sorted(holders.items(), key=lambda x: -x[1])[:5]
],
}
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--stat", required=True, help="dumpsys batterystats --charged 的输出文本")
ap.add_argument("--out", required=True)
ap.add_argument("--boottime-offset-ms", type=int, default=0)
a = ap.parse_args()
with open(a.stat, encoding="utf-8", errors="replace") as f:
raw = parse(f.read())
# estimated_mah 是按 power_profile.xml 系数乘出来的派生值,
# 必须和内核 wakeup 事件分开存,否则六本账又会混在一起对不上
ledger = {
"source": "batterystats",
"boottime_offset_ms": a.boottime_offset_ms,
"metrics": {
"wakeup_count": raw["wakeup_count"],
"wakelock_ms": raw["wakelock_ms"],
"job_runs": None, # 由 JobAudit 产物回填
"estimated_mah": None, # derived,单独节点
},
"per_hour": raw["per_hour"],
"top_holders": raw["top_holders"],
"derived": {"estimated_mah": None, "note": "power_profile 估算,非 fuel gauge 真值"},
}
with open(a.out, "w", encoding="utf-8") as f:
json.dump(ledger, f, ensure_ascii=False, indent=2)
print("wrote", a.out, "wakeup_count=", ledger["metrics"]["wakeup_count"])
if __name__ == "__main__":
main()
路径:.github/workflows/battery-gate.yml
用途:第 10 轮定稿的 CI 卡点。PR 上跑静态扫描与单测,wakeup_count/estimated_mah 这类要真机的数标成夜间任务回填,不在 PR 上假装有实测。
name: battery-gate
on:
pull_request:
paths:
- 'app/src/**'
- 'docs/battery-baseline.json'
schedule:
- cron: '0 2 * * *' # 夜间真机数据回填,写回 battery-gate-report.json
jobs:
static-and-unit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 静态扫描(禁 setRepeating / 禁无 timeout 的 acquire / 禁缺 type 的 FGS)
run: python3 scripts/battery_gate.py --baseline docs/battery-baseline.json --static-only
- name: 单测(含 WakeLockGuard 异常必放、BatchSyncWorker 合并用例)
run: ./gradlew :app:testDebugUnitTest --tests '*WakeLock*' --tests '*BatchSync*'
- name: 断言 wakelock_ms 静态估算不超阈值
run: python3 scripts/battery_gate.py --baseline docs/battery-baseline.json --report docs/battery-gate-report.json
nightly-device:
if: github.event_name == 'schedule'
runs-on: [self-hosted, android-device]
steps:
- uses: actions/checkout@v4
- name: 静置一夜采集四个度量数
run: bash scripts/verify_doze_bucket.sh com.example.health
- name: 聚合账本并回填
run: python3 scripts/collect_wakeups.py --stat nightly-batterystats.txt --out docs/wake-ledger.json
路径:docs/battery-baseline.json
用途:第 6 章定死、后面所有轮次与 CI 共用的尺。四个度量数、测量口径、机型、静置时长、样本量、阈值全在这,改水位只改这一处。
{
"device": "Pixel 7 / Android 14 / targetSdk 35",
"window": "23:30-07:00 静置 7.5h, 关闭 USB 充电, adb over Wi-Fi",
"samples": "6 台同批次机器 x 连续 5 晚",
"metrics": {
"wakeup_count": "一夜归因到本 UID 的系统 wakeup 次数",
"wakelock_ms": "PARTIAL_WAKE_LOCK 累计持锁毫秒",
"job_runs": "后台作业实际执行次数, 合并率=请求数/执行数",
"estimated_mah": "batterystats --charged 下本 UID 估算耗电(derived)"
},
"baseline_before": {
"date": "2026-09-12",
"wakeup_count": 241,
"wakelock_ms": 36180,
"job_runs": 96,
"estimated_mah": 480.2
},
"baseline_after": {
"dates": "2026-09-13..2026-09-17",
"wakeup_count": 19,
"wakelock_ms": 1420,
"job_runs": 14,
"estimated_mah": 58.7,
"estimated_mah_stddev": 8.3,
"note": "0916 弱信号夜 estimated_mah=61.0 未删除, 单晚 >2 倍标准差标红"
},
"thresholds": {
"wakeup_count_max": 40,
"wakelock_ms_max": 2000,
"job_runs_max": 24,
"estimated_mah_max": 90
}
}
踩过的坑,按现象排
这张表是十二轮里我真实撞过的,按「现象 → 根因 → 修复」记,不按报错码排是因为电池这块大半压根不抛异常,只给你一个对不上的数。二十多条,越往后越隐蔽。
| # | 现象 | 根因 | 修复 |
|---|---|---|---|
| 1 | 系统设置耗电排行我们 App 第一(11%),logcat 里进程一夜没醒 | 账按唤醒次数记,不按 CPU 时间;屏幕/射频待机被摊到「最近活跃」UID | 把「耗电」翻译成「谁唤醒/几次/多久」三问 |
| 2 | batterystats 显示 wake=38s,以为锁只拿了半分钟 | wake 是持锁时长,不是唤醒次数;241 次 × 150ms 才凑出 36s | 改看 wakeup 事件次数,别看累计时长 |
| 3 | Battery Historian 和 Perfetto 时间轴对不上,差 4分12秒 | 前者相对开机时间、后者单调时钟,机器开机没校时 | 账本加 boottime_offset_ms 归一 |
| 4 | 工位上怎么测都不进 Doze | USB 调试线接着算充电,不满足「未充电」进入条件 | 拔线走 adb over Wi-Fi,先 dumpsys battery unplug |
| 5 | 起了带通知的 FGS,夜里同步照样不跑 | Doze 下 FGS 只保进程不回收,不豁免网络与 job 调度 | 别把 FGS 当护身符,走维护窗口合并 |
| 6 | PARTIAL_WAKE_LOCK 挂了 7h42m 没放 | 只在 onSuccess release,超时回调没走到 | AutoCloseable+try/finally+acquire(timeout) |
| 7 | release() 抛 WakeLock under-locked | 默认引用计数 true,acquire/release 没严格配对 | setReferenceCounted(false),release 前判 isHeld |
| 8 | acquire(timeout) 到点后重复 release 抛异常 | 系统已自动放,锁已不在 held 状态 | close() 里 if (lock.isHeld) 保护 |
| 9 | 两分钟 setRepeating 心跳删不掉,一堆隐式依赖 | 2008 年老写法,精确闹钟为王时代的遗留 | 收敛到 PeriodicWorkRequest,周期最小 15 分钟 |
| 10 | 服药提醒夜里没准时响 | 误用 setExactAndAllowWhileIdle,Doze 下每 App 每 9 分钟才一次 | 改 setAlarmClock(),接受锁屏闹钟图标 |
| 11 | 12 上精确闹钟直接不触发 | 缺 SCHEDULE_EXACT_ALARM 权限 | 先弹用途说明再申请;13 闹钟类可走 USE_EXACT_ALARM |
| 12 | 后台起 FGS 抛 ForegroundServiceStartNotAllowedException | 12 起后台启动被禁 | 改 startForegroundService 仅限允许的豁免场景,或走 expedited job |
| 13 | 14 上 FGS 一启动就抛类型校验异常 | 没声明 android:foregroundServiceType | 每处 service 补正确 type 与对应权限 |
| 14 | 长传 FGS 跑一半被系统停 | 误标 shortService(约 3 分钟)/ 撞上 dataSync 每 24h 6 小时配额 | 长传走 WorkManager 加急作业,FGS 只留配额内短任务 |
| 15 | 夜间作业整晚一次不跑 | 约束写成充电+不计费+空闲三选全要,静置不插电永远不满足 | 充电改加速条件,网络以 CONNECTED 为底线 |
| 16 | 6 个任务在同一窗口起来 6 次,射频 tail 付 6 遍 | 各自 schedule,没合并 | enqueueUniquePeriodicWork + 单 Worker 串行 JobAuditScope |
| 17 | 合并率算不出来 | JobAudit 把请求数和执行数记成同一字段 | 拆 requested/executed/merged_into 三列 |
| 18 | 用 CHARGE_COUNTER 每秒采样,功率曲线全是台阶 | 部分机型是框架按百分比反推,跳变粗、几分钟才动一次 | 瞬时功率用 CURRENT_NOW + ENERGY_COUNTER |
| 19 | 拿 CHARGE_COUNTER 当累计用电量,正负全反 | 它是「剩余电荷 µAh」,不是「已用」 | 只采原始值,累计/摊账标 derived 另存 |
| 20 | Power Profiler 的 mW 跟 batterystats 的 mAh 对不上 | 一个是归一化估算功率、一个是系数累加电荷,口径不同 | 各看各的趋势,不交叉对绝对值 |
| 21 | Perfetto 里 wakeup source: alarm_rtc 归不到应用 | 内核层只到 wakeup source,不认 UID | 拿 batterystats 的 wakeup 事件按 UID 反查接回 |
| 22 | 云端埋点「同步成功 1 次」和 241 次唤醒对不上 | 埋点只记业务结果,不管系统有没有真唤醒 | 埋点对齐到 JobAudit 的 batchId,标清口径 |
| 23 | Android 11 测试机怎么都不进 restricted | RESTRICTED API 30 有常量但 R 未启用,12 才默认生效 | 验证脚本加 sdk >= 31 分支 |
| 24 | Android 15 上 force-idle 一口气 step 进不去 IDLE | 15 进 Doze 快约 50%,状态迁移节奏变了 | 每步 sleep 2 回读 mState 再决定下一步 |
| 25 | 跑完验证脚本第二天作业被压到一天一次 | 忘了把 Bucket 拨回原档,机器留在 restricted | 脚本 trap restore EXIT,收尾还原桶与 deviceidle |
| 26 | dumpsys usagestats 里 reason=3 看不懂,以为代码错 | 是 REASON_TIMEOUT(超时未使用)触发的降级 | 对着 UsageStatsManager 的 REASON_* 常量读 |
| 27 | CI 静态扫描把注释里的 setRepeating 也算违规 | grep 没跳注释行 | 过滤 // 与 /* */ 注释后再匹配 |
| 28 | CI 上四个度量数看着「实测」,其实容器里没真机 | PR 阶段无权采真机数据 | wakeup_count/estimated_mah 标 measured_on=nightly,PR 只卡静态与 wakelock_ms 估算 |
| 29 | 弱信号那晚 estimated_mah 反弹到 61,被当成离群值想删 | 蜂窝 -108dBm 待机电流翻倍,账摊到本 UID | 留样本并解释,加「单晚 >2σ 标红」告警 |
| 30 | 照旧教程找 SOLO Builder 找不到入口 | 2026-05 Builder/Coder 已合并为 SOLO Agent | 按新模式重配上下文引用,提示词整段重写 |
命令速查
这章把电池主题天天敲的命令收齐,每条都带我在自己机器上跑出来的输出片段和判读。别的篇讲 dumpsys meminfo、启动 trace、heap dump,这里只放跟唤醒账本有关的那几套。
batterystats 三连,账本级入口:
# 清账,记下时间,再静置一夜
$ adb shell dumpsys batterystats --reset
Battery stats reset on 2026-09-12 23:30:02
# 只看自上次充电以来这一段
$ adb shell dumpsys batterystats --charged com.example.health
Estimated power use (mAh):
Uid 10xxx: 480 ( wake=38s wifi=0s mobile=12s sensor=0.1s )
Screen: 312 Cell standby: 96 Idle: 22
Wakeup alarms: 241 times, uid 10xxx
# 判读:480 是估算,Screen 312 是「摊到本 UID」的屏幕账,不等于我们代码耗的。
# wake=38s 是持锁时长,241 次才是唤醒次数,别看反。
$ adb bugreport bugreport-0912.zip
# 拖进 Battery Historian,看 wake_lock 长条与 mobile_radio 段是否贴着同一时刻
dumpsys power 抓没配对的锁:
$ adb shell dumpsys power | grep -A10 'Wake Locks'
Wake Locks: size=3
PARTIAL_WAKE_LOCK 'HealthSync:upload' (uid=10xxx, pid=4211) ACQUIRED
elapsed since acquire=7h42m13s
# 判读:持锁时长明显超业务预期(上传不该 7 小时)基本就是泄漏;
# 正常该是 released 或几秒级。那 7h42m 就是开篇 11% 的根。
dumpsys jobscheduler 看作业排队与约束:
$ adb shell dumpsys jobscheduler | grep -A6 'com.example.health'
JOB #u0a3/42: 3123ms com.example.health/.sync.BatchSyncWorker
Required constraints: CONNECTIVITY [0x1000000]
Satisfied: connectivity=true, charging=false, idle=false
Pending: 2
# 判读:Pending 数从合并前的 9 降到 2;Satisfied 里 charging=false 说明
# 我们没把「充电」设成硬约束,夜间静置也能跑(第 6 轮返工点)。
cmd appops 看授权态,尤其精确闹钟:
$ adb shell cmd appops get com.example.health
WAKE_LOCK: allow; time=+7h42m0s ago
RUN_IN_BACKGROUND: allow
SCHEDULE_EXACT_ALARM: allow; time=+2d1h ago (UID mode)
# 判读:SCHEDULE_EXACT_ALARM 为 allow 才用得了 setExact;
# WAKE_LOCK 那行 time 跟持锁时长对得上,能反查是不是长期没放。
dumpsys deviceidle 强制进 Doze 并逐步迁移:
$ adb shell dumpsys battery unplug # 先摘掉「充电」状态
$ adb shell dumpsys deviceidle force-idle
$ adb shell dumpsys deviceidle | grep -E 'mState|mNextAlarmTime'
mState=IDLE mNextAlarmTime=+3600000
$ adb shell dumpsys deviceidle step # 逐步走 INACTIVE->IDLE_PENDING->SENSING->...
$ adb shell dumpsys deviceidle unforce # 收尾还原
# 判读:mState=IDLE 才算进深睡;mNextAlarmTime 约 1h 起、之后 x2 退避,
# 就是维护窗口的指数退避;亮屏/插电/setAlarmClock 会提前退出。
usagestats 与 am 查分桶:
$ adb shell am get-standby-bucket com.example.health
40
$ adb shell dumpsys usagestats | grep -A2 -B1 'standby-bucket'
standby-bucket=40 reason=3 (timeout) old=30
time=2026-09-12 03:04:11 changed=STANDBY_BUCKET_CHANGED
# 判读:40=RARE,reason=3 是 REASON_TIMEOUT 超时未使用降级;
# 常量 10/20/30/40/45 对应 active/working_set/frequent/rare/restricted。
$ adb shell am set-standby-bucket com.example.health rare # 测试态切换,用完还原
$ adb shell am get-standby-bucket com.example.health
40
Perfetto 抓电源轨与 wakeup 归因:
$ adb shell perfetto -o /data/misc/perfetto-traces/pwr.trace -t 20s \
-c - --txt <<'CFG'
buffers { size_kb: 63488 fill_policy: RING_BUFFER }
data_sources { config { name: "android.power"
android_power_config { battery_poll_ms: 250 collect_power_rails: true } } }
data_sources { config { name: "linux.ftrace"
ftrace_config { ftrace_events: "power/wakeup_source_activate"
ftrace_events: "power/suspend_resume" } } }
CFG
$ adb pull /data/misc/perfetto-traces/pwr.trace .
# 判读:wakeup_source_activate 里看到 alarm_rtc / 某 IRQ,说明是内核层拽醒的;
# power rail 抬升对应射频与 AP 电流;它不认 UID,要拿 batterystats 的 wakeup 事件反查。
采集脚本收口,把上面几条的输出聚成账本:
$ adb shell dumpsys batterystats --charged > nightly-batterystats.txt
$ python3 scripts/collect_wakeups.py --stat nightly-batterystats.txt \
--boottime-offset-ms 252000 --out docs/wake-ledger.json
wrote docs/wake-ledger.json wakeup_count= 19
$ python3 -c "import json;d=json.load(open('docs/wake-ledger.json'));print(d['metrics'])"
{'wakeup_count': 19, 'wakelock_ms': 1420, 'job_runs': None, 'estimated_mah': None}
# 判读:job_runs 由 JobAudit 产物回填,estimated_mah 在 derived 节点单独算,
# 三者口径分开,才不会重演六本账对不上。
上线前我盯的四个数
第 6 章定死、第 9 章回归、第 10 章钉进 CI 的,始终是同一把尺。这里把优化前后正式摆成对照,口径、机型、静置时长、样本量一并写清,免得日后有人拿另一个窗口的数来比。
| 度量数 | 优化前(2026-09-12) | 优化后(0913–0917 五晚均值) | 测量口径 |
|---|---|---|---|
wakeup_count | 241 | 19(σ=3.1) | 一夜归因到本 UID 的系统 wakeup 次数,dumpsys batterystats 的 Wakeup alarms |
wakelock_ms | 36180 | 1420(σ=210) | PARTIAL_WAKE_LOCK 累计持锁毫秒,dumpsys power + 账本聚合 |
job_runs | 96 | 14 | 后台作业实际执行次数,合并率 = 请求数 / 执行数,来自 JobAudit |
estimated_mah | 480.2 | 58.7(σ=8.3) | batterystats --charged 下本 UID 估算耗电,derived 节点,非 fuel gauge 真值 |
口径统一为:Pixel 7 / Android 14 / targetSdk 35,窗口 23:30–07:00 静置 7.5 小时,关闭 USB 充电、adb over Wi-Fi,6 台同批次机器 × 连续 5 晚。四个数都没换定义,estimated_mah 那晚弱信号(-108 dBm)反弹到 61.0 留在样本里没删,标准差 8.3 就是这么来的;CI 里补了「单晚超均值 2 个标准差标红」,专盯这种回归。
wakeup_count 从 241 掉到 19,砍掉的主要是 HeartbeatAlarm.kt:28 那 233 次两分钟心跳;剩下的 19 次里 8 次是系统维护窗口合并的作业、11 次是服药提醒与加急上传,都是有必要醒的。estimated_mah 从 480 降到 58.7,但里面有 300 多 mAh 本来就是屏幕与蜂窝待机按 UID 摊过来的,改动前后这部分没变,差的只是摊账对象——这一点我在归因文档里单独标了,不拿它当代码功劳。数字有误差、有回归,我只敢说「在我这六台机、这个静置窗口里是这样」。
还能往下挖的地方
按投入产出比排的十个方向,每个写清要解决什么、代价是什么。前三个我准备动手,后面的排着。
| 排序 | 方向 | 要解决什么 | 代价 |
|---|---|---|---|
| 1 | 接 JobScheduler#getPendingJobReasonsHistory() | Android 16 起 job 配额按桶/内存/资源细化,现在不知道作业为何被推迟 | 仅 16+ 可用,老版本要写兼容分支,得加一套历史原因上报 |
| 2 | 弱信号自适应合并 | 射频在弱网下 tail 更长、搜网更费,固定 15 分钟周期不是最优 | 要采信号强度与网络类型,约束变复杂,容易误伤准时性 |
| 3 | 把 estimated_mah 的 derived 算法换成真机 fuel gauge 标定 | 现在 mAh 是 power_profile 系数估算,跨机型不可比 | 每台机型要单独采电流曲线标定,维护成本高 |
| 4 | 分桶感知的作业优先级 | Rare/Restricted 桶一天就一两次窗口,高优任务该挤进去还是等 | 要读 getAppStandbyBucket() 做分支,逻辑跟系统策略耦合,策略一变就要跟 |
| 5 | FGS 配额的运行时自监控 | dataSync/mediaProcessing 每 24h 6 小时配额,快到点要提前收尾 | 要自己记累计时长、处理跨重启持久化,边界多 |
| 6 | Perfetto power rail 与 batterystats 的自动对齐 | 现在靠 boottime_offset_ms 手工归一,换机就飘 | 要解析两种时钟与 trace 格式,脚本量不小 |
| 7 | 三方 SDK 唤醒点的运行时归因 | 静态扫不到 aar 里的锁,那把 7h42m 的锁就是漏网的 | 得靠 dumpsys power+UID 反查,SDK 升级后标签会变,需持续维护 |
| 8 | 16KB 页表对齐后的整机对照 | 系统级平均约 4.5% 电量收益,想量出跟应用侧唤醒账是不是叠加 | 需支持 16KB 的设备与对齐构建,样本机不好凑,只能当对照不宜深挖 |
| 9 | 充电态与电池态两套基线分开 | 充电时 Bucket 限制全放,混在一份基线里会稀释差异 | 采集窗口翻倍,CI 夜间任务要跑两套 |
| 10 | 跨厂商 Doze 参数差异表 | 每家厂商可自定非活跃分桶标准、维护窗口时长 | 要铺多台厂商机长期采,收益偏「少踩坑」而非直接降数字 |
第 8 条我特意只留一句:16KB 页表平均 4.5% 的电量收益属于系统级优化,主体够不着,放这里是当「系统层比应用层更狠」的参照,不展开,也不拿来跟 wakeup_count 硬比。
后来
那台 Pixel 7 我没还回测试柜,一直搁在工位抽屉里当电量样机。过了大概两周,某个早上顺手点亮看了眼系统设置,我们那个健康类 App 掉到了第九位,2%。我没截图,也没往群里发,把屏幕扣回去,接着改模块 M 下周要上的那个合并策略了。