用户说我们 App 最耗电,可进程一夜没醒:我用 Trae 把 Android 电量账本翻了出来

2 阅读46分钟

有个周一早上,运营往群里甩了张截图:一台 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 --chargedUid 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 / wakeupwakeup 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~192008-09-23 起只有屏幕开/关二元状态;WakeLock 可无限持有、无引用计数约束;AlarmManager 精确闹钟(setRepeating / set)是唯一定时手段,RTC_WAKEUP 想多密就多密
5.0 Lollipop / API 212014-11-04Project Volta:引入 JobScheduler,声明式、可带「充电 / 不计费网络 / 空闲」约束、系统可批量合并;同期 Battery Historian 在 2015 年开源,第一次能把 bugreport 里的电量事件铺成时间轴
6.0 Marshmallow / API 232015-09-29Doze + App Standby;新增 setAndAllowWhileIdle() / setExactAndAllowWhileIdle(),官方明确这俩在 Doze 下每 App 每 9 分钟最多触发一次;setAlarmClock() 照常触发并会让系统提前退出 Doze;加入电池优化白名单(ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS)
7.0 Nougat / API 242016-08-22Light Doze:不再要求静止,熄屏+未充电即可进入,维护窗口更短更密;同时「隐式广播」开始被削(CONNECTIVITY_ACTION 等移出静态注册)
8.0 Oreo / API 262017-08-21后台执行限制:后台应用不能 startService()(要起得走 startForegroundService()),绝大多数隐式广播静态注册失效,后台位置限流;JobScheduler 成为后台周期工作的正路
9 Pie / API 282018-08-06App Standby Buckets + Adaptive Battery:Active / Working set / Frequent / Rare 四档起,系统可借预装 ML 应用预测使用概率来分桶;桶决定 job/alarm 频率与高优先级 FCM 配额
10 / API 292019-09-03后台启动 Activity 被限制;STANDBY_BUCKET_RESTRICTED 常量在 API 30 这一档被引入(R 上默认未启用),为受限桶铺路
11 / API 302020-09-08一次性权限、后台位置需单独申请;受限桶相关规则继续铺垫,前台服务类型(location / camera / mic)开始要求 while-in-use 级权限配合
12 / API 312021-10-04精确闹钟需 SCHEDULE_EXACT_ALARM 权限;后台起 FGS 抛 ForegroundServiceStartNotAllowedException;受限桶正式默认生效;JobScheduler 引入 expedited job(加急作业),作业单次运行时长从固定 10 分钟变成按系统空闲程度弹性
12L / API 322022-03-07大屏相关,对电量主线无新增调度约束,只把 12 的配额逻辑带到大屏形态
13 / API 332022-08-15新增 USE_EXACT_ALARM(闹钟类应用免弹权限)、POST_NOTIFICATIONS;8 天不交互进受限桶(12 是 45 天),受限桶一天一次约 10 分钟批处理作业
14 / API 342023-10-04FGS 必须声明 android:foregroundServiceType,系统按类型校验权限与配额,选错类型直接抛异常
15 / API 352024-09-03dataSync / mediaProcessing 类型每 24 小时 6 小时配额,超时系统停服;shortService 约 3 分钟;Doze 进入深睡比 14 快约 50%(Dave Burke 在 Google I/O 2024 访谈原话,部分测试机待机最多多 3 小时,且适用于所有升级到 15 的设备);16KB 页表带来的平均 4.5% 电量收益属于系统级优化,跟应用侧唤醒账不是一回事,放这里只当个对照
16 / API 362026job 配额按桶 / 内存压力 / 资源状态进一步细化;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 下行为我拿它干什么
JobSchedulerAPI 21(5.0)API 21 约 1 分钟;API 23~30 约 10 分钟;API 31+ 按系统空闲程度弹性标准 job 被推迟到维护窗口,约束凑齐才放批量同步、日志上报、可延迟的一切周期工作
WorkManagerAndroidX周期最小 15 分钟,底层在 API 23+ 就是 JobScheduler,自动继承系统省电约束同 JobScheduler,内部用 JobScheduler 时不会跑需要重试、链式约束、跨进程保活的可靠后台任务
AlarmManager.setExact早期精确,但 12 起需 SCHEDULE_EXACT_ALARM / USE_EXACT_ALARMDoze 里标准精确闹钟被推迟真正对时间敏感、且用户能感知的事(提醒、服药闹钟)
setAndAllowWhileIdle / setExactAndAllowWhileIdleAPI 23(6.0)每 App 每 9 分钟最多一次能穿 Doze,但被限流极少数必须穿 Doze 的兜底,且接受 9 分钟粒度
setAlarmClockAPI 21照常触发,系统提前退出 Doze不推迟用户看得见的闹钟(锁屏会出闹钟图标)
expedited jobAPI 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把「耗电」翻译成「谁唤醒/几次/多久」三问
2batterystats 显示 wake=38s,以为锁只拿了半分钟wake 是持锁时长,不是唤醒次数;241 次 × 150ms 才凑出 36s改看 wakeup 事件次数,别看累计时长
3Battery Historian 和 Perfetto 时间轴对不上,差 4分12秒前者相对开机时间、后者单调时钟,机器开机没校时账本加 boottime_offset_ms 归一
4工位上怎么测都不进 DozeUSB 调试线接着算充电,不满足「未充电」进入条件拔线走 adb over Wi-Fi,先 dumpsys battery unplug
5起了带通知的 FGS,夜里同步照样不跑Doze 下 FGS 只保进程不回收,不豁免网络与 job 调度别把 FGS 当护身符,走维护窗口合并
6PARTIAL_WAKE_LOCK 挂了 7h42m 没放只在 onSuccess release,超时回调没走到AutoCloseable+try/finally+acquire(timeout)
7release() 抛 WakeLock under-locked默认引用计数 true,acquire/release 没严格配对setReferenceCounted(false),release 前判 isHeld
8acquire(timeout) 到点后重复 release 抛异常系统已自动放,锁已不在 held 状态close() 里 if (lock.isHeld) 保护
9两分钟 setRepeating 心跳删不掉,一堆隐式依赖2008 年老写法,精确闹钟为王时代的遗留收敛到 PeriodicWorkRequest,周期最小 15 分钟
10服药提醒夜里没准时响误用 setExactAndAllowWhileIdle,Doze 下每 App 每 9 分钟才一次改 setAlarmClock(),接受锁屏闹钟图标
1112 上精确闹钟直接不触发缺 SCHEDULE_EXACT_ALARM 权限先弹用途说明再申请;13 闹钟类可走 USE_EXACT_ALARM
12后台起 FGS 抛 ForegroundServiceStartNotAllowedException12 起后台启动被禁改 startForegroundService 仅限允许的豁免场景,或走 expedited job
1314 上 FGS 一启动就抛类型校验异常没声明 android:foregroundServiceType每处 service 补正确 type 与对应权限
14长传 FGS 跑一半被系统停误标 shortService(约 3 分钟)/ 撞上 dataSync 每 24h 6 小时配额长传走 WorkManager 加急作业,FGS 只留配额内短任务
15夜间作业整晚一次不跑约束写成充电+不计费+空闲三选全要,静置不插电永远不满足充电改加速条件,网络以 CONNECTED 为底线
166 个任务在同一窗口起来 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 另存
20Power Profiler 的 mW 跟 batterystats 的 mAh 对不上一个是归一化估算功率、一个是系数累加电荷,口径不同各看各的趋势,不交叉对绝对值
21Perfetto 里 wakeup source: alarm_rtc 归不到应用内核层只到 wakeup source,不认 UID拿 batterystats 的 wakeup 事件按 UID 反查接回
22云端埋点「同步成功 1 次」和 241 次唤醒对不上埋点只记业务结果,不管系统有没有真唤醒埋点对齐到 JobAudit 的 batchId,标清口径
23Android 11 测试机怎么都不进 restrictedRESTRICTED API 30 有常量但 R 未启用,12 才默认生效验证脚本加 sdk >= 31 分支
24Android 15 上 force-idle 一口气 step 进不去 IDLE15 进 Doze 快约 50%,状态迁移节奏变了每步 sleep 2 回读 mState 再决定下一步
25跑完验证脚本第二天作业被压到一天一次忘了把 Bucket 拨回原档,机器留在 restricted脚本 trap restore EXIT,收尾还原桶与 deviceidle
26dumpsys usagestats 里 reason=3 看不懂,以为代码错是 REASON_TIMEOUT(超时未使用)触发的降级对着 UsageStatsManager 的 REASON_* 常量读
27CI 静态扫描把注释里的 setRepeating 也算违规grep 没跳注释行过滤 // 与 /* */ 注释后再匹配
28CI 上四个度量数看着「实测」,其实容器里没真机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_count24119(σ=3.1)一夜归因到本 UID 的系统 wakeup 次数,dumpsys batterystats 的 Wakeup alarms
wakelock_ms361801420(σ=210)PARTIAL_WAKE_LOCK 累计持锁毫秒,dumpsys power + 账本聚合
job_runs9614后台作业实际执行次数,合并率 = 请求数 / 执行数,来自 JobAudit
estimated_mah480.258.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() 做分支,逻辑跟系统策略耦合,策略一变就要跟
5FGS 配额的运行时自监控dataSync/mediaProcessing 每 24h 6 小时配额,快到点要提前收尾要自己记累计时长、处理跨重启持久化,边界多
6Perfetto power rail 与 batterystats 的自动对齐现在靠 boottime_offset_ms 手工归一,换机就飘要解析两种时钟与 trace 格式,脚本量不小
7三方 SDK 唤醒点的运行时归因静态扫不到 aar 里的锁,那把 7h42m 的锁就是漏网的得靠 dumpsys power+UID 反查,SDK 升级后标签会变,需持续维护
816KB 页表对齐后的整机对照系统级平均约 4.5% 电量收益,想量出跟应用侧唤醒账是不是叠加需支持 16KB 的设备与对齐构建,样本机不好凑,只能当对照不宜深挖
9充电态与电池态两套基线分开充电时 Bucket 限制全放,混在一份基线里会稀释差异采集窗口翻倍,CI 夜间任务要跑两套
10跨厂商 Doze 参数差异表每家厂商可自定非活跃分桶标准、维护窗口时长要铺多台厂商机长期采,收益偏「少踩坑」而非直接降数字

第 8 条我特意只留一句:16KB 页表平均 4.5% 的电量收益属于系统级优化,主体够不着,放这里是当「系统层比应用层更狠」的参照,不展开,也不拿来跟 wakeup_count 硬比。

后来

那台 Pixel 7 我没还回测试柜,一直搁在工位抽屉里当电量样机。过了大概两周,某个早上顺手点亮看了眼系统设置,我们那个健康类 App 掉到了第九位,2%。我没截图,也没往群里发,把屏幕扣回去,接着改模块 M 下周要上的那个合并策略了。