axiom-energy-diag

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Energy Diagnostics

电量诊断

Symptom-based troubleshooting for energy issues. Start with your symptom, follow the decision tree, get the fix.
Related skills:
axiom-energy
(patterns, checklists),
axiom-energy-ref
(API reference)

基于症状的电量问题故障排查。从你的症状入手,遵循决策树操作,即可找到修复方案。
相关技能
axiom-energy
(模式、检查清单),
axiom-energy-ref
(API参考)

Symptom 1: App at Top of Battery Settings

症状1:应用在电池设置中排名靠前

Users or you notice your app consuming significant battery.
用户或你发现应用消耗大量电量。

Diagnosis Decision Tree

诊断决策树

App at top of Battery Settings?
├─ Step 1: Run Power Profiler (15 min)
│  ├─ CPU Power Impact high?
│  │  ├─ Continuous? → Timer leak or polling loop
│  │  │  └─ Fix: Check timers, add tolerance, convert to push
│  │  └─ Spikes during actions? → Eager loading or repeated parsing
│  │     └─ Fix: Use LazyVStack, cache parsed data
│  │
│  ├─ Network Power Impact high?
│  │  ├─ Many small requests? → Batching issue
│  │  │  └─ Fix: Batch requests, use discretionary URLSession
│  │  └─ Regular intervals? → Polling pattern
│  │     └─ Fix: Convert to push notifications
│  │
│  ├─ GPU Power Impact high?
│  │  ├─ Animations? → Running when not visible
│  │  │  └─ Fix: Stop in viewWillDisappear
│  │  └─ Blur effects? → Over dynamic content
│  │     └─ Fix: Remove or use static backgrounds
│  │
│  └─ Display Power Impact high?
│     └─ Light backgrounds on OLED?
│        └─ Fix: Implement Dark Mode (up to 70% savings)
└─ Step 2: Check background section in Battery Settings
   ├─ High background time?
   │  ├─ Location icon visible? → Continuous location
   │  │  └─ Fix: Switch to significant-change monitoring
   │  ├─ Audio active? → Session not deactivated
   │  │  └─ Fix: Deactivate audio session when not playing
   │  └─ BGTasks running long? → Not completing promptly
   │     └─ Fix: Call setTaskCompleted sooner
   └─ Background time appropriate?
      └─ Issue is in foreground usage → Focus on CPU/GPU fixes above
应用在电池设置中排名靠前?
├─ 步骤1:运行Power Profiler(15分钟)
│  ├─ CPU电量影响高?
│  │  ├─ 持续高? → 计时器泄漏或轮询循环
│  │  │  └─ 修复方案:检查计时器,添加容差,转换为推送机制
│  │  └─ 操作期间出现峰值? → 预加载或重复解析
│  │     └─ 修复方案:使用LazyVStack,缓存解析后的数据
│  │
│  ├─ 网络电量影响高?
│  │  ├─ 大量小请求? → 批处理问题
│  │  │  └─ 修复方案:批量处理请求,使用discretionary URLSession
│  │  └─ 定期请求? → 轮询模式
│  │     └─ 修复方案:转换为推送通知
│  │
│  ├─ GPU电量影响高?
│  │  ├─ 动画问题? → 在不可见时仍在运行
│  │  │  └─ 修复方案:在viewWillDisappear中停止动画
│  │  └─ 模糊效果问题? → 应用于动态内容之上
│  │     └─ 修复方案:移除模糊效果或使用静态背景
│  │
│  └─ 显示电量影响高?
│     └─ OLED屏幕使用浅色背景?
│        └─ 修复方案:实现深色模式(最高可节省70%电量)
└─ 步骤2:检查电池设置中的后台部分
   ├─ 后台运行时间过长?
   │  ├─ 定位图标可见? → 持续定位
   │  │  └─ 修复方案:切换到重大变化监测模式
   │  ├─ 音频处于活跃状态? → 会话未停用
   │  │  └─ 修复方案:不播放时停用音频会话
   │  └─ BGTasks运行时间过长? → 未及时完成
   │     └─ 修复方案:尽早调用setTaskCompleted
   └─ 后台运行时间合理?
      └─ 问题出在前台使用 → 重点关注上述CPU/GPU修复方案

Time-Cost Analysis

时间成本分析

ApproachTimeAccuracy
Run Power Profiler, identify subsystem15-20 minHigh
Guess and optimize random areas4+ hoursLow
Read all code looking for issues2+ hoursMedium
Recommendation: Always use Power Profiler first. It costs 15 minutes but guarantees you optimize the right subsystem.

方法耗时准确率
运行Power Profiler,识别子系统15-20分钟
随机猜测并优化4小时以上
通读所有代码查找问题2小时以上
建议:始终优先使用Power Profiler。仅需15分钟,就能确保你优化正确的子系统。

Symptom 2: Device Gets Hot

症状2:设备发热

Device temperature increases noticeably during app use.
使用应用期间设备温度明显升高。

Diagnosis Decision Tree

诊断决策树

Device gets hot during app use?
├─ Hot during specific action?
│  │
│  ├─ During video/camera use?
│  │  ├─ Video encoding? → Expected, but check efficiency
│  │  │  └─ Fix: Use hardware encoding, reduce resolution if possible
│  │  └─ Camera active unnecessarily? → Not releasing session
│  │     └─ Fix: Call stopRunning() when done
│  │
│  ├─ During scroll/animation?
│  │  ├─ GPU-intensive effects? → Blur, shadows, many layers
│  │  │  └─ Fix: Reduce effects, cache rendered content
│  │  └─ High frame rate? → Unnecessary 120fps
│  │     └─ Fix: Use CADisplayLink preferredFrameRateRange
│  │
│  └─ During data processing?
│     ├─ JSON parsing? → Repeated or large payloads
│     │  └─ Fix: Cache parsed results, paginate
│     └─ Image processing? → Synchronous on main thread
│        └─ Fix: Move to background, cache results
├─ Hot during normal use (no specific action)?
│  │
│  ├─ Run Power Profiler to identify:
│  │  ├─ CPU high continuously → Timer, polling, tight loop
│  │  ├─ GPU high continuously → Animation leak
│  │  └─ Network high continuously → Polling pattern
│  │
│  └─ Check for infinite loops or runaway recursion
│     └─ Use Time Profiler in Instruments
└─ Hot only in background?
   ├─ Location updates continuous? → High accuracy or no stop
   │  └─ Fix: Reduce accuracy, stop when done
   ├─ Audio session active? → Hardware kept powered
   │  └─ Fix: Deactivate when not playing
   └─ BGTask running too long? → System may throttle
      └─ Fix: Complete tasks faster, use requiresExternalPower
使用应用期间设备发热?
├─ 执行特定操作时发热?
│  │
│  ├─ 视频/相机使用期间?
│  │  ├─ 视频编码? → 属于正常现象,但需检查效率
│  │  │  └─ 修复方案:使用硬件编码,必要时降低分辨率
│  │  └─ 相机未必要保持活跃? → 未释放会话
│  │     └─ 修复方案:使用完毕后调用stopRunning()
│  │
│  ├─ 滚动/动画期间?
│  │  ├─ GPU密集型效果? → 模糊、阴影、多层视图
│  │  │  └─ 修复方案:减少效果,缓存渲染内容
│  │  └─ 高帧率? → 不必要的120fps
│  │     └─ 修复方案:使用CADisplayLink preferredFrameRateRange
│  │
│  └─ 数据处理期间?
│     ├─ JSON解析? → 重复解析或大负载
│     │  └─ 修复方案:缓存解析结果,分页处理
│     └─ 图片处理? → 在主线程同步执行
│        └─ 修复方案:移至后台处理,缓存结果
├─ 正常使用时发热(无特定操作)?
│  │
│  ├─ 运行Power Profiler识别原因:
│  │  ├─ CPU持续高负载 → 计时器、轮询、死循环
│  │  ├─ GPU持续高负载 → 动画泄漏
│  │  └─ 网络持续高负载 → 轮询模式
│  │
│  └─ 检查是否存在无限循环或失控递归
│     └─ 使用Instruments中的Time Profiler
└─ 仅在后台时发热?
   ├─ 持续更新定位? → 高精度或未停止
│  └─ 修复方案:降低精度,使用完毕后停止
   ├─ 音频会话处于活跃状态? → 硬件保持供电
│  └─ 修复方案:不播放时停用
   └─ BGTask运行时间过长? → 系统可能会限制
      └─ 修复方案:加快任务完成速度,使用requiresExternalPower

Time-Cost Analysis

时间成本分析

ApproachTimeOutcome
Power Profiler + Time Profiler20-30 minIdentifies exact cause
Check code for obvious issues1-2 hoursMay miss non-obvious causes
Wait for user complaintsN/AReputation damage

方法耗时结果
Power Profiler + Time Profiler20-30分钟准确定位根本原因
检查代码中的明显问题1-2小时可能遗漏非明显原因
等待用户反馈损害声誉

Symptom 3: Background Battery Drain

症状3:后台电池耗电

App drains battery even when user isn't actively using it.
即使用户未主动使用,应用仍在消耗电池电量。

Diagnosis Decision Tree

诊断决策树

High background battery usage?
├─ Step 1: Check Info.plist background modes
│  │
│  ├─ "location" enabled?
│  │  ├─ Actually need background location?
│  │  │  ├─ YES → Use significant-change, lowest accuracy
│  │  │  └─ NO → Remove background mode, use when-in-use only
│  │  └─ Check: Is stopUpdatingLocation called?
│  │
│  ├─ "audio" enabled?
│  │  ├─ Audio playing? → Expected
│  │  ├─ Audio NOT playing? → Session still active
│  │  │  └─ Fix: Deactivate session, use autoShutdownEnabled
│  │  └─ Playing silent audio? → Anti-pattern for keeping app alive
│  │     └─ Fix: Use proper background API (BGTask)
│  │
│  ├─ "fetch" enabled?
│  │  └─ Check: Is earliestBeginDate reasonable? (not too frequent)
│  │
│  └─ "remote-notification" enabled?
│     └─ Expected for push updates, check didReceiveRemoteNotification efficiency
├─ Step 2: Check BGTaskScheduler usage
│  │
│  ├─ BGAppRefreshTask scheduled too frequently?
│  │  └─ Fix: Increase earliestBeginDate interval
│  │
│  ├─ BGProcessingTask not using requiresExternalPower?
│  │  └─ Fix: Add requiresExternalPower = true for non-urgent work
│  │
│  └─ Tasks not completing? (setTaskCompleted not called)
│     └─ Fix: Always call setTaskCompleted, implement expirationHandler
└─ Step 3: Check beginBackgroundTask usage
   ├─ endBackgroundTask called promptly?
   │  └─ Fix: Call immediately after work completes, not at expiration
   └─ Multiple overlapping background tasks?
      └─ Fix: Track task IDs, ensure each is ended
后台电池高耗电?
├─ 步骤1:检查Info.plist中的后台模式
│  │
│  ├─ 已启用"location"?
│  │  ├─ 是否真的需要后台定位?
│  │  │  ├─ 是 → 使用重大变化监测模式,最低精度
│  │  │  └─ 否 → 移除后台模式,仅使用使用时定位
│  │  └─ 检查:是否调用了stopUpdatingLocation?
│  │
│  ├─ 已启用"audio"?
│  │  ├─ 正在播放音频? → 正常现象
│  │  ├─ 未播放音频? → 会话仍处于活跃状态
│  │  │  └─ 修复方案:停用会话,启用autoShutdownEnabled
│  │  └─ 播放无声音频? → 为保持应用活跃的反模式
│  │     └─ 修复方案:使用正规后台API(BGTask)
│  │
│  ├─ 已启用"fetch"?
│  │  └─ 检查:earliestBeginDate是否合理?(不要过于频繁)
│  │
│  └─ 已启用"remote-notification"?
│     └─ 推送更新所需,检查didReceiveRemoteNotification的效率
├─ 步骤2:检查BGTaskScheduler的使用
│  │
│  ├─ BGAppRefreshTask调度过于频繁?
│  │  └─ 修复方案:增加earliestBeginDate的间隔
│  │
│  ├─ BGProcessingTask未使用requiresExternalPower?
│  │  └─ 修复方案:为非紧急任务设置requiresExternalPower = true
│  │
│  └─ 任务未完成?(未调用setTaskCompleted)
│     └─ 修复方案:务必调用setTaskCompleted,实现expirationHandler
└─ 步骤3:检查beginBackgroundTask的使用
   ├─ 是否及时调用endBackgroundTask?
   │  └─ 修复方案:任务完成后立即调用,不要等到过期
   └─ 是否存在多个重叠的后台任务?
      └─ 修复方案:跟踪任务ID,确保每个任务都已结束

Common Background Drain Patterns

常见后台耗电模式

PatternPower Profiler SignatureFix
Continuous locationCPU lane + location iconsignificant-change
Audio session leakCPU lane steadysetActive(false)
Timer not invalidatedCPU spikes at intervalsinvalidate in background
Polling from backgroundNetwork lane at intervalsPush notifications
BGTask too longCPU sustainedFaster completion
模式Power Profiler特征修复方案
持续定位CPU通道 + 定位图标重大变化监测模式
音频会话泄漏CPU通道稳定高负载调用setActive(false)
计时器未失效CPU定期出现峰值在后台时失效计时器
后台轮询网络通道定期活跃推送通知
BGTask运行时间过长CPU持续高负载加快任务完成速度

Time-Cost Analysis

时间成本分析

ApproachTimeOutcome
Check Info.plist + BGTask code30 minFinds common issues
On-device Power Profiler trace1-2 hours (real usage)Captures real behavior
User-collected traceVariableBest for unreproducible issues

方法耗时结果
检查Info.plist + BGTask代码30分钟发现常见问题
设备端Power Profiler追踪1-2小时(实际使用场景)捕获真实行为
用户收集的追踪数据可变最适合无法复现的问题

Symptom 4: High Energy Only on Cellular

症状4:仅蜂窝网络下高耗电

Battery drains faster on cellular than WiFi.
蜂窝网络下的电池耗电速度比WiFi快。

Diagnosis Decision Tree

诊断决策树

High battery drain on cellular only?
├─ Expected: Cellular radio uses more power than WiFi
│  └─ But: Excessive drain indicates optimization opportunity
├─ Check URLSession configuration
│  │
│  ├─ allowsExpensiveNetworkAccess = true (default)?
│  │  └─ Fix: Set to false for non-urgent requests
│  │
│  ├─ isDiscretionary = false (default)?
│  │  └─ Fix: Set to true for background downloads
│  │
│  └─ waitsForConnectivity = false (default)?
│     └─ Fix: Set to true to avoid failed connection retries
├─ Check request patterns
│  │
│  ├─ Many small requests? → High connection overhead
│  │  └─ Fix: Batch into fewer larger requests
│  │
│  ├─ Polling? → Radio stays active
│  │  └─ Fix: Push notifications
│  │
│  └─ Large downloads in foreground? → Could wait for WiFi
│     └─ Fix: Use background URLSession with discretionary
└─ Check Low Data Mode handling
   ├─ Respecting allowsConstrainedNetworkAccess?
   │  └─ Fix: Set to false for non-essential requests
   └─ Checking ProcessInfo.processInfo.isLowDataModeEnabled?
      └─ Fix: Reduce payload sizes, defer non-essential transfers
仅蜂窝网络下电池高耗电?
├─ 正常情况:蜂窝网络无线电比WiFi更耗电
│  └─ 但:过度耗电意味着有优化空间
├─ 检查URLSession配置
│  │
│  ├─ allowsExpensiveNetworkAccess = true(默认)?
│  │  └─ 修复方案:非紧急请求设置为false
│  │
│  ├─ isDiscretionary = false(默认)?
│  │  └─ 修复方案:后台下载设置为true
│  │
│  └─ waitsForConnectivity = false(默认)?
│     └─ 修复方案:设置为true以避免失败连接重试
├─ 检查请求模式
│  │
│  ├─ 大量小请求? → 连接开销高
│  │  └─ 修复方案:合并为少量大请求
│  │
│  ├─ 轮询? → 无线电保持活跃
│  │  └─ 修复方案:推送通知
│  │
│  └─ 前台大文件下载? → 可等待WiFi
│     └─ 修复方案:使用后台URLSession并设置discretionary
└─ 检查低数据模式处理
   ├─ 是否遵循allowsConstrainedNetworkAccess?
   │  └─ 修复方案:非必要请求设置为false
   └─ 是否检查ProcessInfo.processInfo.isLowDataModeEnabled?
      └─ 修复方案:减小负载大小,推迟非必要传输

Time-Cost Analysis

时间成本分析

ApproachTimeOutcome
Review URLSession configs15 minQuick wins
Add discretionary flags30 minSignificant savings
Convert poll to push2-4 hoursLargest impact

方法耗时结果
检查URLSession配置15分钟快速优化见效
添加discretionary标记30分钟显著节省电量
轮询转推送2-4小时影响最大

Symptom 5: Energy Spike During Specific Action

症状5:特定操作时电量骤增

Noticeable battery drain or heat when performing particular operation.
执行特定操作时出现明显的电池耗电或发热。

Diagnosis Decision Tree

诊断决策树

Energy spike during specific action?
├─ Step 1: Record Power Profiler during action
│  └─ Note which subsystem spikes (CPU/GPU/Network/Display)
├─ CPU spike?
│  │
│  ├─ Is it parsing data?
│  │  ├─ Same data parsed repeatedly?
│  │  │  └─ Fix: Cache parsed results (lazy var)
│  │  └─ Large JSON/XML payload?
│  │     └─ Fix: Paginate, stream parse, or use binary format
│  │
│  ├─ Is it creating views?
│  │  ├─ Many views at once?
│  │  │  └─ Fix: Use LazyVStack/LazyHStack
│  │  └─ Complex view hierarchies?
│  │     └─ Fix: Simplify, use drawingGroup()
│  │
│  └─ Is it image processing?
│     ├─ On main thread?
│     │  └─ Fix: Move to background queue
│     └─ No caching?
│        └─ Fix: Cache processed images
├─ GPU spike?
│  │
│  ├─ Starting animation?
│  │  └─ Fix: Ensure frame rate appropriate
│  │
│  ├─ Showing blur effect?
│  │  └─ Fix: Use solid color or pre-rendered blur
│  │
│  └─ Complex render? (shadows, masks, many layers)
│     └─ Fix: Simplify, use shouldRasterize, cache
├─ Network spike?
│  │
│  ├─ Large download started?
│  │  └─ Fix: Use background URLSession, show progress
│  │
│  ├─ Many parallel requests?
│  │  └─ Fix: Limit concurrency, batch
│  │
│  └─ Retrying failed requests?
│     └─ Fix: Exponential backoff, waitsForConnectivity
└─ Display spike?
   └─ Unusual unless changing brightness programmatically
      └─ Fix: Don't modify brightness, let system control
特定操作时电量骤增?
├─ 步骤1:操作期间录制Power Profiler
│  └─ 记录哪个子系统出现峰值(CPU/GPU/网络/显示)
├─ CPU峰值?
│  │
│  ├─ 是否在解析数据?
│  │  ├─ 重复解析相同数据?
│  │  │  └─ 修复方案:缓存解析结果(使用lazy var)
│  │  └─ 大JSON/XML负载?
│  │     └─ 修复方案:分页、流式解析或使用二进制格式
│  │
│  ├─ 是否在创建视图?
│  │  ├─ 一次性创建大量视图?
│  │  │  └─ 修复方案:使用LazyVStack/LazyHStack
│  │  └─ 复杂视图层级?
│  │     └─ 修复方案:简化层级,使用drawingGroup()
│  │
│  └─ 是否在处理图片?
│     ├─ 在主线程执行?
│     │  └─ 修复方案:移至后台队列
│     └─ 未缓存?
│        └─ 修复方案:缓存处理后的图片
├─ GPU峰值?
│  │
│  ├─ 启动动画?
│  │  └─ 修复方案:确保帧率合适
│  │
│  ├─ 显示模糊效果?
│  │  └─ 修复方案:使用纯色或预渲染模糊效果
│  │
│  └─ 复杂渲染?(阴影、遮罩、多层视图)
│     └─ 修复方案:简化效果,使用shouldRasterize,缓存
├─ 网络峰值?
│  │
│  ├─ 启动大文件下载?
│  │  └─ 修复方案:使用后台URLSession,显示进度
│  │
│  ├─ 大量并行请求?
│  │  └─ 修复方案:限制并发数,批量处理
│  │
│  └─ 重试失败请求?
│     └─ 修复方案:指数退避,使用waitsForConnectivity
└─ 显示峰值?
   └─ 除非通过代码修改亮度,否则不常见
      └─ 修复方案:不要修改亮度,交由系统控制

Time-Cost Analysis

时间成本分析

ApproachTimeOutcome
Power Profiler during action5-10 minIdentifies subsystem
Time Profiler for CPU details10-15 minIdentifies function
Code review without profiling1+ hoursMay miss actual cause

方法耗时结果
操作期间运行Power Profiler5-10分钟识别子系统
Time Profiler分析CPU细节10-15分钟识别具体函数
无分析的代码审查1小时以上可能遗漏实际原因

Quick Diagnostic Checklist

快速诊断检查清单

Use this when you need fast answers:
需要快速解答时使用:

30-Second Check

30秒检查

  • Device plugged in? (Power metrics show 0)
  • Debug build? (Less optimized than release)
  • Low Power Mode on? (May affect measurements)
  • 设备是否已充电?(电量指标显示0)
  • 是否为Debug构建?(比Release构建优化程度低)
  • 是否开启低电量模式?(可能影响测量结果)

5-Minute Check (Power Profiler)

5分钟检查(Power Profiler)

  • Which subsystem is dominant? (CPU/GPU/Network/Display)
  • Sustained or spiky?
  • Foreground or background?
  • 哪个子系统占主导?(CPU/GPU/网络/显示)
  • 持续高负载还是峰值型?
  • 前台还是后台?

15-Minute Investigation

15分钟调查

  • If CPU: Run Time Profiler to identify function
  • If Network: Check request frequency and size
  • If GPU: Check animation frame rates
  • If Background: Check Info.plist modes
  • 如果是CPU:运行Time Profiler识别具体函数
  • 如果是网络:检查请求频率和大小
  • 如果是GPU:检查动画帧率
  • 如果是后台:检查Info.plist中的模式

Common Quick Fixes

常见快速修复方案

FindingQuick FixTime
Timer without toleranceAdd
.tolerance = 0.1
1 min
VStack with large ForEachChange to LazyVStack1 min
allowsExpensiveNetworkAccess = trueSet to false1 min
Missing stopUpdatingLocationAdd stop call2 min
No Dark ModeAdd asset variants30 min
Audio session always activeAdd setActive(false)5 min

发现快速修复耗时
计时器无容差添加
.tolerance = 0.1
1分钟
包含大型ForEach的VStack改为LazyVStack1分钟
allowsExpensiveNetworkAccess = true设置为false1分钟
未调用stopUpdatingLocation添加停止调用2分钟
未实现深色模式添加资源变体30分钟
音频会话始终活跃添加setActive(false)5分钟

When to Escalate

何时升级处理

Use
axiom-energy
skill when

当你需要以下支持时使用
axiom-energy
技能

  • Need full audit checklist
  • Want comprehensive patterns with code
  • Planning proactive optimization
  • 需要完整的审计检查清单
  • 需要带代码示例的全面模式
  • 规划主动优化

Use
axiom-energy-ref
skill when

当你需要以下支持时使用
axiom-energy-ref
技能

  • Need specific API details
  • Want complete code examples
  • Implementing from scratch
  • 需要特定API细节
  • 需要完整的代码示例
  • 从零开始实现

Use
energy-auditor
agent when

当你需要以下支持时使用
energy-auditor
代理

  • Want automated codebase scan
  • Looking for anti-patterns at scale
  • Pre-release energy audit
Run:
/axiom:audit energy

Last Updated: 2025-12-26 Platforms: iOS 26+, iPadOS 26+
  • 想要自动化代码库扫描
  • 大规模查找反模式
  • 发布前电量审计
运行:
/axiom:audit energy

最后更新:2025-12-26 平台:iOS 26+, iPadOS 26+