batterygate

name	batterygate
description	面向中文用户的 MacBook 电池助手 skill：查询电池健康度、循环次数、当前电量等状态；一键配置"加速循环"充放电模式（默认充到 95% 停止、低于 10% 恢复），并在调整上下限时给出如何更快增加循环次数的推荐建议；同时覆盖 BatteryGate 的安装、卸载、暂停/恢复充电和故障排查。用户提到 BatteryGate、电池健康度、循环次数、加速循环、充放电阈值、停充/续充设置时使用。

BatteryGate

概述

BatteryGate 是一个 macOS 菜单栏充电控制器（开源，MIT 协议，仓库 github.com/marsggbo/BatteryGate）：电量充到你设的上限就自动停止充电，掉到你设的下限再开始充电。同时显示电池遥测数据（健康度、循环次数、温度、电压、容量）。

三种后端（面板可选，设置存于 defaults）：

• 0 只读演示（Dry Run）—— 不实际控制充电
• 1 内置助手（Built-in Helper）—— 默认；root 守护进程通过 SMC 控制充电
• 2 外部命令（External Command）—— 用用户自定义脚本控制充电

快速开始

# 一步查询：电量、是否充电、温度、循环次数、健康度
~/.zcode/skills/batterygate/scripts/batterygate.sh status

# 读取当前阈值配置
defaults read com.marsggbo.BatteryGate

查询电池状态

用 batterygate.sh status 或直接读面板。解读时注意：

字段	说明
健康度	system_profiler SPPowerDataType 的 Maximum Capacity，苹果官方口径（%）
循环次数	IOKit CycleCount，电池终身累计
当前电量	百分比 + 是否在充电 + 是否插电
温度 / 电压	老化过程的参考信号

查询类需求直接报数据 + 一句话解释即可，不触发任何开关。

一键配置：加速循环模式（核心功能）

用户想"更快增加电池循环次数 / 加快电池消耗"时：

# 一键设为加速循环配置（默认：充到 95% 停，低于 10% 恢复）
~/.zcode/skills/batterygate/scripts/batterygate.sh cycle

# 自定义上下限（上限 下限）
batterygate.sh cycle 100 10

给用户的调整建议（每次调整上下限时都附上，按更快循环排序）

1. 上限越高越好：95% → 100%。上限越高，每轮充放的电量越多。
2. 下限建议 5–10%，但实际最低 30%：App 状态机有 30% 保护线，实际恢复充电 = max(下限, 30%)。设 10% 实际是 30% 就恢复，App 层面无法突破（机器保护）。
3. 区间决定单轮循环量：100% ↔ 30% ≈ 每轮 0.7 次循环；95% ↔ 30% ≈ 0.65 次。想要循环数涨得快：上限拉高 + 保持插电即可（电量一到下限自动开始补电）。
4. 保持插电：恢复充电需要电源接入；不插电只会放电不自动充。

必须如实告知的注意事项

• 深放、满电高压是锂电池老化最快的方式——加速循环 = 加速健康度下降，寿命缩短，这是它的本来代价。
• 循环次数按苹果统计口径累计；保修/换电池条款请用户自己核对，AI 不替用户判断"薅保修"行为是否可取。
• 设置后 30–60 秒内应看到状态变化（App 每 15 秒刷新一次）；面板若报 SMC 错误 → 该机型不支持，切换外部命令后端。

安装 / 卸载

• GUI 优先（推荐）：从 GitHub Release 下载 .app → 拖入 /Applications → 打开 → 选内置助手时点 Install Helper… → 系统弹一次密码框，全程不需要终端。
• 命令行等价：源码目录 make install-helper（装同样的 root 助手 + plist + socket）。
• 卸载：App 内 Remove Helper 按钮，或 make uninstall-helper；再删 /Applications/BatteryGate.app 与 ~/Library/LaunchAgents/com.marsggbo.BatteryGate.plist。

配置细节

面板与 defaults write com.marsggbo.BatteryGate 等价（App 运行中下次刷新即生效）：

upper  = 50–100（停充上限）
lower  = 5–95，其中实际生效 ≥30（恢复下限）
enabled= 开关
backend= 0/1/2（演示/内置助手/外部命令）
pauseCommand / resumeCommand（backend=2 时使用）

暂停 / 恢复控制

echo pause | nc -U /var/run/batterygate-helper.sock   # 需要内置助手在运行
scripts/batterygate.sh pause
scripts/batterygate.sh resume

直接运行 BatteryGateHelper pause 报 SMC write ... e00002c1 属预期（SMC 写需要 root），走 socket 或 sudo。

故障排查（中文用户场景）

• "健康度/循环是多少" → 跑 status 直接报告数字。
• "设了没生效 / 没停充" → 查 helper 是否运行（sudo launchctl print system/com.marsggbo.BatteryGateHelper）、socket 是否存在、面板是否报错；若报 SMC 写入失败 → 机型不支持，切外部命令后端。
• "菜单栏没显示电量" → 该机型读不到电池信息（虚拟机/无电池设备最常见）。
• "想放到 10% 以下再充" → 如实说明 30% 保护线是 App 层最大底线，无法通过设置突破。

安全纪律

• 不接受 force discharge（adapter disable）类行为——helper 端直接拒绝，不手写 SMC。
• 所有涉及 sudo 的安装动作，先给用户看命令、获得同意再执行。
• 退出 App 会自动恢复充电；依赖"长时间保持停充"的场景，提醒用户这是设计的兜底行为。

资源

• scripts/batterygate.sh — status/ thresholds / cycle（一键加速循环）/ pause / resume / socket 一站式。
• references/helper-socket.md — socket 协议 + SMC 键表（调试 helper 或写外部命令脚本时再看）。