macli battery 字段详解与诊断手册

macli battery 读取 macOS IOKit 的 AppleSmartBattery 服务，把电池、充电器、电源遥测等数据整理成可直接用 jq 处理的 JSON。它是 ioreg -n AppleSmartBattery -r 的严格超集：除了 IO 元数据，几乎所有标量、数组、嵌套对象都被保留，并且增加了单位换算、派生指标和二进制 blob 解码。

当前版本输出的是 完整/详细模式；以后会增加 --detail 开关，默认输出精简子集，但字段名和结构保持不变。

30 秒上手

# 核心状态
macli battery | jq '{status, stateOfCharge, healthPercent, cycleCount, temperature}'

# 功率流（电池输出功率、系统功耗、输入功率、瞬时功率）
macli battery | jq '{instantPowerWatts, batteryPower, systemPower, inputPower}'

# 电芯平衡（delta > 0.05 V 要留意）
macli battery | jq '{cellVoltages, cellVoltageDelta}'

# 解码后的每电芯内阻表
macli battery | jq '.raTableRaw'

# 导出 TSV 给 Excel / Numbers / R
macli battery --tsv > battery.tsv

为什么用 macli battery 而不是 ioreg？

ioreg -n AppleSmartBattery -r -l 已经把几乎所有原始数据展示出来了，但它有几点不便：

所以：ioreg 能看原始数据，macli battery 帮你把数据变成可编程、可对比、可监控的格式。两者不是替代关系，而是分层：底层探查用 ioreg，脚本/监控/告警用 macli。

与 system_profiler SPPowerDataType 的对比

system_profiler 只给出人类可读的摘要（循环次数、状态、最大容量百分比）。macli battery 则提供原始遥测：每个电芯电压、充电器状态、PD 适配器档位、电量计内部标志、生命周期数据等。

serialNumber 与 batterySerial 为什么会不同？

来源

为什么会不一样？

这两个序列号来自不同层级：

1. 根级 Serial 是 macOS 的 AppleSmartBattery 驱动从 SMC/PMU 侧读取或维护的标识，常用于 system_profiler SPPowerDataType 和系统设置。
2. BatteryData.Serial 来自电池包内部的电量计芯片（gas gauge）数据闪存，是电池制造商写入的。

在大多数原装机器上，Apple 会把同一个序列号同步到两个位置，所以它们看起来一样。但在以下场景可能不同：

• 第三方替换电池：厂商可能只写了 gas gauge 序列号，没同步到根级 Serial。
• 不同固件版本：较新的 Apple Silicon 机器上，根级序列号的编码规则发生变化，导致基于它的“从序列号解析生产日期”方法失效（见 munkireport/power#26）。
• 售后维修/翻新电池：电池包和主板记录的序列号可能不一致。
• 假冒/篡改电池：常见特征是根级序列号为空或随机，而 BatteryData.Serial 与 Apple 正品格式不符（见 iTech4Mac: How to Spot a Fake Battery）。

论据

• munkireport/power#26 指出：旧方法“从根级 Serial 提取 YWWD 生产日期”在新设备上已不可靠，必须改用 BatteryData.ManufactureDate。
• 多篇用户报告和电池检测脚本（如 少数派、anotherdayu）都同时引用 BatteryData.Serial 作为电池身份标识。
• ioreg 本身同时暴露两个 Serial 键，说明 Apple 认为它们是两个独立字段。

怎么用

# 判断两者是否一致
macli battery | jq '{serialNumber, batterySerial, same: (.serialNumber == .batterySerial)}'

# 怀疑假电池时，优先检查 BatteryData 序列号格式
macli battery | jq '.batterySerial'

适配器电压：adapter.voltage 与 adapter.adapterVoltage

IOKit 在不同机型/固件里用了两个键表示适配器电压：

macli 两个都读，所以你的输出里至少有一个存在。如果两个都有，它们应该是同一个值。

macli battery | jq '.adapter | {voltage, adapterVoltage}'

诊断脚本手册

下面这些脚本可以直接复制使用。它们展示了 macli battery 如何超越“查看信息”，变成真正的诊断工具。

1. 健康度与寿命

# 健康度低于 80% 时报警
macli battery | jq -e '.healthPercent < 80' && echo "考虑更换电池"

# 循环次数 + 设计寿命，算剩余寿命比例
macli battery | jq '{cycleCount, designCycleCount, lifeUsedPercent: (.cycleCount / .designCycleCount * 100)}'

# 温度换算成华氏度
macli battery | jq '{celsius: .temperature, fahrenheit: (.temperature * 9 / 5 + 32)}'

2. 功率与充电

# 当前系统/电池/输入功率全景
macli battery | jq '{instantPowerWatts, batteryPower, systemPower, inputPower, chargerPower: .charger.powerWatts}'

# 判断是否在“慢充”或“不充电”
macli battery | jq '{externalConnected, isCharging, fullyCharged, notChargingReason: .charger.notChargingReason, slowChargingReason: .charger.slowChargingReason}'

# 估算从当前电量到满电需要多少 Wh
macli battery | jq '{remainingWh: (.estimatedFullChargeWh - .currentWh), estimatedFullChargeWh, currentWh}'

3. 电芯平衡与内阻

# 电芯电压差
macli battery | jq '{cellVoltages, cellVoltageDelta}'

# 电压差大于 0.05 V 时高亮
macli battery | jq -e '.cellVoltageDelta > 0.05' && echo "电芯不平衡，建议校准或检查"

# 查看加权内阻（mΩ）
macli battery | jq '{weightedRa, chemicalWeightedRa, resScale, rss, iss}'

# 把 raTableRaw 画成每个电芯的电阻表
macli battery | jq '.raTableRaw | to_entries[] | {cell: .key, table: .value}'

4. 适配器与 USB-C PD

# 当前适配器能力
macli battery | jq '.adapter | {watts, voltage, current, description, isWireless}'

# PDO 档位（适配器支持的电压/电流组合）
macli battery | jq '.adapter.usbHvcMenu'

# 每个 USB-C 口接了什么设备
macli battery | jq '.fedDetails | map({vendorID, productID, externalConnected, remainingCapacity})'

5. 时间序列与监控

# 每隔 5 秒记录一条 CSV
while true; do
  macli battery | jq -r '[now, .stateOfCharge, .temperature, .instantPowerWatts, .cellVoltageDelta] | @csv'
  sleep 5
done >> battery.csv

# 用 macli monitor 流式监控电池功率（每秒一个样本，共 60 个）
macli monitor --metric battery_power --interval 1 --count 60

# 计算过去 N 次采样的平均功耗
macli monitor --metric battery_power --interval 1 --count 60 | awk -F'\t' 'NR>1 {sum+=$2; n++} END {print "avg:", sum/n, "W"}'

6. 可疑电池 / 身份核对

# 两个序列号是否一致
macli battery | jq '{serialNumber, batterySerial, same: (.serialNumber == .batterySerial)}'

# 制造商数据里的 ASCII 片段
macli battery | jq '{mfgDataAscii, manufacturerDataAscii, deviceName, manufactureDate}'

# 一次性输出所有可用于判断电池是否原生的字段
macli battery | jq '{serialNumber, batterySerial, deviceName, manufactureDate, cycleCount, designCycleCount, mfgDataAscii}'

二进制字段解析说明

ioreg 里有些字段是 NSData blob，macli battery 对它们做了不同处理：

关于 BatteryState 和 ChargerStatus 的 bit 含义

SBS（Smart Battery System）规范定义了标准寄存器：

• BatteryStatus(0x16)：2 字节，包含 DISCHARGING、FULLY_CHARGED、TERMINATE_CHARGE_ALARM 等标志。
• ChargingStatus(0x55)：2 字节，包含 FCHG、PULSEOFF 等标志。

但 Apple 在 BatteryData.BatteryState 里放的是扩展状态 blob（常见 16~17 字节），ChargerData.ChargerStatus 新版本也是 NSData。前两个字节可能对应 SBS 标志，其余字节布局未公开。macli battery 只负责把它们以 hex/bytes 形式暴露出来，不推测未验证的 bit 语义。

关于 RaTableRaw

每个电芯的内阻表是 32 字节，按 big-endian uint16 解析成 16 个整数。这些值与 ra00–ra14 一起描述了电池在不同 SOC/温度点的内阻特征。跨机型、跨化学 ID 的具体映射由电量计算法决定，macli 只提供原始整数表，不发明物理含义。

字段速查表

状态

容量与能量

电压 / 电流

电量百分比

两者通常接近，差 1% 属于正常。

温度

时间估算

65535 表示无效/未知（常见于接 AC 未充电时）。

识别信息

电芯数据

电池数据诊断

适配器

充电器

系统电源遥测

USB-C PD 与端口诊断

生命周期数据

使用示例

# 只看最关心的状态
macli battery | jq '{status, stateOfCharge, currentCapacity, maxCapacity, healthPercent, cycleCount, temperature}'

# 判断健康度是否低于 80%
macli battery | jq -e '.healthPercent < 80' && echo "consider replacement"

# 计算真实充电功率（如果正在充电）
macli battery | jq '{watts: (.charger.voltage * .charger.current / 1000000)}'

# 检查两个序列号是否一致
macli battery | jq '{serialNumber, batterySerial, same: (.serialNumber == .batterySerial)}'

# 查看每个 USB-C 口接了什么
macli battery | jq '.fedDetails'

# 查看 PDO 供电档位
macli battery | jq '.adapter.usbHvcMenu'

# 导出为 TSV 在表格里打开
macli battery --tsv > battery.tsv

补充字段（进一步覆盖 ioreg）

以下字段是为了让 macli battery 成为 ioreg 的超集而补充的：

故意不重复输出的字段

以下字段在 ioreg 里同时出现在根级和 BatteryData 里，macli 已经在根级输出，所以不再在 BatteryData 下重复：

跳过的字段

以下字段是 IO 元数据或大块二进制 blob，macli 故意不输出：

• IOGeneralInterest、IOObjectClass、IORegistryEntryID 等 IO 元数据
• LifetimeData.Raw、LifetimeData.TimeAtHighSoc 等二进制时间序列（Apple 电量计私有格式）
• PortControllerInfo 里的 PortControllerEvtBuffer 等大块原始 buffer（USB-PD 控制器私有格式）

其余二进制字段（BatteryState、ChargerStatus、MfgData、ManufacturerData、RaTableRaw、iMaxAndSocSmoothTable）已以 hex 或结构化形式输出。

控制充电：macli battery 只读，控制请用这些工具

macli battery 是观测/诊断工具，它只读取 IOKit 数据，不修改电池或充电行为。如果你需要限制充电、暂停充电或做自动校准，请使用以下方案。

1. 官方原生方式（最稳）

macOS 官方提供图形界面的充电控制，注意区分“学习型延迟充电”和“硬上限”：

重要：Optimized Battery Charging 最终还是会充满到 100%，只是延迟最后 20% 的充电时间。如果你希望长期插电时电池停在 80% 或更低，必须开 80% Limit / Charging Limit，而不是 Optimized Battery Charging。

Charging Limit（80%–100% 可调）是 macOS 26.4 及更高版本新增的原生功能（据 charlie0129/batt 项目公告），无需第三方工具。

Optimized Battery Charging 的学习机制与决策

它是怎么学习的？

1. macOS 会记录你每天的插电和拔电时间、使用时长。
2. 当它发现你有规律（比如每晚 23:00 插电，早上 8:30 拔掉），它会：
   • 先快速充到 80%；
   • 在 80% 处“暂停”；
   • 在你预计拔掉电源前不久（比如早上 7:30）再把最后 20% 充满。
3. 这样既减少了电池在高电压下停留的时间，又能保证你拔电时电池是满的。

它的局限：

• 作息不规律时基本无效。如果你每天插电/拔电时间都不一样，系统学不出模式，就会直接充满到 100%。
• 学习需要几天甚至几周。新机器或刚升级系统后，可能要一段时间才开始生效。
• 最终还是会到 100%。它不是硬上限，只是“延迟充满”。

决策建议：

临时需要充满时，可以点击电池菜单或系统通知里的 “Charge to Full Now”（立即充满），让系统跳过学习策略一次。

优点：Apple 官方支持，无需额外软件，系统升级不会失效。
缺点：依然没有 CLI；如果需要低于 80% 的限制，仍需第三方工具。

为什么有时要设到 60% 甚至更低？

80% 是大多数人的甜点，但不是所有人的最优解。

锂电池在高 SOC（高电压）下老化更快。80% 已经比 100% 好很多；如果你几乎 24 小时插电（比如 Mac 长期接显示器当台式机用），把上限进一步降到 60%–70% 可以减少化学应力、延缓容量衰减。代价是断电时的可用续航变少。

macOS 原生只支持 80%–100% 的可调范围，所以想要 60%–70% 必须用 batt（Apple Silicon）或 AlDente 等第三方工具。

2. pmset — 原生命令，但只能看不能控

pmset 是 macOS 自带的电源管理工具，可以查看电池和电源状态：

pmset -g batt        # 当前电池状态
pmset -g ps         # 电源源状态
pmset -g rawlog     # 原始电池状态日志
pmset -g log        # 电源事件日志

但它没有充电限制功能。它管理的是睡眠、唤醒、显示器关闭、低电量模式等系统电源策略，不是电池充电阈值。

3. 第三方 CLI 控制工具（功能强，但非官方）

# batt（Apple Silicon）设置 80% 上限
brew install batt
sudo batt limit 80

# bclm（Intel）设置 80% 上限
brew tap zackelia/formulae
brew install bclm
sudo bclm write 80

⚠️ 这些工具都依赖未公开的接口或私有 API。macOS 大版本更新后可能需要等待工具更新，且不在 Apple 官方支持范围内。

4. 和 macli battery 的配合

推荐组合：

1. 日常充电策略用 System Settings（最稳）。
2. 用 macli battery 做遥测，验证策略是否生效：

   macli battery | jq '{stateOfCharge, isCharging, externalConnected, chargerPower: .charger.powerWatts}'
   

3. 如果系统版本低于 macOS 26.4，或需要把上限设到 80% 以下，再考虑 batt / bclm，并接受它们是私有/非官方方案。

macli battery 与 batt / bclm 的关系

一句话：不是替代关系，是互补关系。

为什么 batt 不能替代 macli battery？

batt 的定位非常聚焦：把充电上限这件事做透。它的 batt status 只会输出控制充电所需的最小信息（当前电量、是否在充电、限制值等），不会给你：

• 每个电芯的电压和内阻；
• USB-C PD 适配器的 PDO 档位和接了什么设备；
• 电池/充电器的原始状态字节；
• 生命周期温度、最大放电电流等诊断数据。

反过来说，macli battery 永远也不会去控制充电——这是两个不同的问题域。

推荐搭配

# 1. 用 macli battery 做全面体检
macli battery | jq '{healthPercent, cycleCount, cellVoltageDelta, temperature}'

# 2. 如果需要，再用 batt 设置充电上限（Apple Silicon）
sudo batt limit 80

# 3. 用 macli battery 验证 batt 是否生效
macli battery | jq '{stateOfCharge, isCharging, externalConnected, chargerPower: .charger.powerWatts}'

电池保养、常见误区与决策参考

macli battery 给了一堆数字，但数字背后的决策更重要。下面是一些实用的电池知识，帮你判断该怎么用、该怎么设。

循环次数 vs 健康度

• 循环次数（cycleCount）只是老化指标之一，不是全部。
• 健康度（healthPercent）反映的是当前最大容量相对于设计容量的比例，是化学老化的综合结果。
• 一个循环次数很低但长期在 100% 满电、高温环境下使用的电池，健康度可能掉得很快；反过来，循环次数高但使用温和的电池，健康度可能保持得更好。

# 同时看循环次数和健康度
macli battery | jq '{cycleCount, designCycleCount, healthPercent, temperature}'

温度比循环次数更伤电池

锂电池最怕的是高温，其次是长期高电量。

• 理想工作温度：约 10°C–35°C。
• 长期高于 35°C 会加速电解液分解和容量衰减。
• 常见的高温场景：被子/沙发上堵住散热口、夏天阳光直射、边充电边跑高强度编译/游戏。

# 看看你的电池现在热不热
macli battery | jq '.temperature'

充电习惯：浅充浅放更好

• 不需要等到 0% 再充。锂电池没有记忆效应，浅充浅放反而更友好。
• 长期在 20%–80% 之间循环，化学应力最小。
• 长期插电建议开启 80% Limit；如果几乎不移动，可考虑 60%–70%。

长期存放

如果你要几周或几个月不用 Mac：

1. 把电量充到 50% 左右。
2. 关机（不要只睡眠）。
3. 放在阴凉、干燥的地方。

长期满电存放和长期亏电存放都会损伤电池。

需要手动校准电池吗？

现代 Mac 的电量计（gas gauge）会自动校准，大多数时候不需要你手动做完整充放电循环。

只在出现以下现象时考虑校准：

• 电量百分比突然跳变（比如从 30% 直接跳到 5%）；
• 显示 100% 后很快掉电；
• healthPercent 在不同次采样间大幅波动。

校准方法：用到接近自动关机，然后一次性充满到 100%，中间不要中断。

什么时候该考虑换电池

MagSafe 指示灯含义

如果你开了 80% Limit，MagSafe 灯在 80% 时就会变绿，这是正常的。

常见误区

• ❌ “必须把电用完再充” — 锂电池没有记忆效应，深度放电反而有害。
• ❌ “快充伤电池” — 充电速度由 BMS 控制，真正伤电池的是快充时产生的高温。
• ❌ “一直插电会充坏电池” — 现代 BMS 会停充并转由市电供电，但长期停在 100% 会加速化学老化；开 80% Limit 可缓解。
• ❌ “循环次数低就一定健康” — 高温、满电存放、电芯不平衡同样会拉低健康度。

数据布局说明

macli battery 的输出布局遵循以下原则：

1. 兼容优先：所有已有的顶层字段（designCapacity、maxCapacity、healthPercent 等）位置和名字不变。
2. 一个 IOKit key 尽量对应一个 JSON key：新增字段不合并、不重新分组。
3. 只有多实例或结构复杂的数据才嵌套：
   • adapter 是对象，因为适配器信息包含多个子字段。
   • rawAdapterDetails、fedDetails、portControllerInfo 是数组，因为 macOS 按 USB-C 口提供多份数据。
   • lifetimeData、carrierMode、deadBatteryBootData 是对象，因为它们在 IOKit 里本身就是嵌套字典。
4. 命名风格：
   • 顶层历史字段和新增标量字段使用 camelCase。
   • 嵌套对象/数组内部保留 IOKit 原始 PascalCase 键名，避免 invent mapping。

优点：jq '.healthPercent' 直接取值，不破坏旧脚本。
代价：顶层键很多（约 150 个），第一眼会比较 overwhelm。后续 --detail 开关会把默认输出精简到 15~20 个常用字段。

如何用 ioreg 查看 macli 未输出的字段

macli 为了兼容、体积和可读性，跳过了 IO 元数据和大块二进制 blob。如果你需要这些原始字段，直接用 ioreg：

# 1. 查看完整原始快照
ioreg -n AppleSmartBattery -r -l

# 2. 保存为 plist 并用 plutil 查看（更结构化）
ioreg -n AppleSmartBattery -r -a -l > /tmp/battery.plist
plutil -p /tmp/battery.plist

# 3. 只看被 macli 跳过的二进制/大块字段
ioreg -n AppleSmartBattery -r -l | \
  grep -E -A2 'RaTableRaw|iMaxAndSocSmoothTable|"BatteryState"|"ChargerStatus"|TimeAtHighSoc|"Raw"|PortControllerEvtBuffer'

# 4. 查看 BatteryData 里被 macli 故意去重的字段
#    （它们已在根级输出为 designCapacity / maxCapacityPercent / voltage / gaugeCycleCount）
ioreg -n AppleSmartBattery -r -l | \
  grep -A40 '"BatteryData"' | \
  grep -E 'DesignCapacity|MaxCapacity|Voltage|CycleCount'

# 5. 查看所有 IO 元数据（IOObjectClass、IORegistryEntryID 等）
ioreg -n AppleSmartBattery -r -l | grep -E 'IO(Object|Registry|Report|Service)'

说明：

• RaTableRaw、iMaxAndSocSmoothTable 是电池算法内部表格，对人类可读性极低。
• BatteryState、ChargerStatus、MfgData、ManufacturerData macli 已输出 hex 字符串版本。
• LifetimeData.Raw、TimeAtHighSoc 是时间序列二进制数据。
• PortControllerEvtBuffer 是每个 USB-C 口的原始事件 buffer，通常 512 字节左右。

常见问题

Q：输出字段这么多，是不是 bug？ A：不是。当前是完整模式，所有 IOKit 里有价值的数据都flatten/保留了出来。后续 --detail 开关会让默认输出变精简。

Q：nominalChargeCapacity 为什么比 designCapacity 大？ A：它是 gas gauge 的标称校准值，会漂移，略大于设计值是正常的。

Q：timeRemaining 为什么是 65535？ A：接电源且未充电时无法估算，Apple 用 65535 表示无效。

Q：batterySerial 和 serialNumber 一样代表没问题吗？ A：在原装机器上通常一样。如果你怀疑电池被更换或篡改，重点看 batterySerial 格式是否符合 Apple 正品规律，以及 manufactureDate 是否与机器年龄匹配。

Q：为什么 ioreg 就够了还要用 macli？ A：ioreg 是原始探查工具；macli battery 把它变成结构化的 JSON、做了单位换算、加了派生指标，并且能被脚本和 macli monitor 复用。