axiom-energy-diag

能耗诊断

基于症状排查能耗问题。从症状入手，按照决策树操作，找到解决方案。

相关技能：axiom-energy（模式、检查清单），axiom-energy-ref（API 参考）

---

症状 1：应用出现在电池设置的顶部

用户或你注意到应用消耗了大量电量。

诊断决策树

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

时间成本分析

方法	时间	准确度
运行 Power Profiler，找出子系统	15-20 分钟	高
猜测并优化随机区域	4+ 小时	低
阅读所有代码以查找问题	2+ 小时	中

建议：始终先使用 Power Profiler。虽然需要 15 分钟，但能确保你优化的是正确的子系统。

---

症状 2：设备发热

使用应用期间，设备温度明显升高。

诊断决策树

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

时间成本分析

方法	时间	结果
Power Profiler + Time Profiler	20-30 分钟	找出确切原因
检查代码中的明显问题	1-2 小时	可能会遗漏不明显的原因
等待用户投诉	N/A	损害声誉

---

症状 3：后台耗电

即使用户没有主动使用应用，应用仍会耗电。

诊断决策树

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

常见后台耗电模式

模式	Power Profiler 特征	修复方法
持续定位	CPU 通道 + 定位图标	significant-change
音频会话泄漏	CPU 通道持续活动	setActive(false)
定时器未失效	CPU 周期性飙升	在后台调用 invalidate
在后台轮询	Network 通道周期性活动	推送通知
BGTask 持续时间过长	CPU 持续活动	更快完成任务

时间成本分析

方法	时间	结果
检查 Info.plist + BGTask 代码	30 分钟	找出常见问题
设备端 Power Profiler 跟踪	1-2 小时（实际使用）	捕获实际行为
用户收集的跟踪记录	不定	最适合无法复现的问题

---

症状 4：仅在蜂窝网络下能耗较高

使用蜂窝网络时，电量比使用 WiFi 时消耗更快。

诊断决策树

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

时间成本分析

方法	时间	结果
检查 URLSession 配置	15 分钟	快速见效
添加 discretionary 标志	30 分钟	显著节省能耗
将轮询改为推送	2-4 小时	影响最大

---

症状 5：执行特定操作时能耗飙升

执行特定操作时，电量消耗或设备发热明显。

诊断决策树

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

时间成本分析

方法	时间	结果
操作期间运行 Power Profiler	5-10 分钟	找出子系统
使用 Time Profiler 查看 CPU 详情	10-15 分钟	找出函数
不进行性能分析，直接审查代码	1+ 小时	可能会遗漏实际原因

---

快速诊断检查清单

需要快速获得答案时使用：

30 秒检查

• 设备已连接电源？（功耗指标显示为 0）
• 使用的是调试构建？（优化程度低于发布构建）
• 低电量模式已开启？（可能会影响测量结果）

5 分钟检查（Power Profiler）

• 哪个子系统占主导？（CPU/GPU/Network/Display）
• 持续活动还是间歇性峰值？
• 前台还是后台？

15 分钟调查

• 如果是 CPU：运行 Time Profiler 以找出函数
• 如果是 Network：检查请求频率和大小
• 如果是 GPU：检查动画帧率
• 如果是后台：检查 Info.plist 模式

常见快速修复

问题	快速修复	耗时
定时器未设置容差	添加 .tolerance = 0.1	1 分钟
VStack 中的 ForEach 项目较多	改为 LazyVStack	1 分钟
allowsExpensiveNetworkAccess = true	设为 false	1 分钟
缺少 stopUpdatingLocation	添加停止调用	2 分钟
不支持深色模式	添加资源变体	30 分钟
音频会话始终处于活动状态	添加 setActive(false)	5 分钟

---

何时升级处理

在以下情况下使用 axiom-energy 技能

• 需要完整的审计清单
• 想要包含代码的全面模式
• 计划主动优化

在以下情况下使用 axiom-energy-ref 技能

• 需要特定的 API 详情
• 想要完整的代码示例
• 从头开始实现

在以下情况下使用 energy-auditor Agent

• 想要自动扫描代码库
• 查找大规模反模式
• 发布前进行能耗审计

运行：/axiom:audit energy

---

最后更新：2025-12-26 平台：iOS 26+、iPadOS 26+