| 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，电池终身累计 |
| 当前电量 | 百分比 + 是否在充电 + 是否插电 |
| 温度 / 电压 | 老化过程的参考信号 |
查询类需求直接报数据 + 一句话解释即可，不触发任何开关。
一键配置：加速循环模式（核心功能）
用户想"更快增加电池循环次数 / 加快电池消耗"时：
~/.zcode/skills/batterygate/scripts/batterygate.sh cycle
batterygate.sh cycle 100 10
给用户的调整建议（每次调整上下限时都附上，按更快循环排序）
- 上限越高越好：95% → 100%。上限越高，每轮充放的电量越多。
- 下限建议 5–10%，但实际最低 30%：App 状态机有 30% 保护线，实际恢复充电 = max(下限, 30%)。设 10% 实际是 30% 就恢复，App 层面无法突破（机器保护）。
- 区间决定单轮循环量：100% ↔ 30% ≈ 每轮 0.7 次循环；95% ↔ 30% ≈ 0.65 次。想要循环数涨得快：上限拉高 + 保持插电即可（电量一到下限自动开始补电）。
- 保持插电：恢复充电需要电源接入；不插电只会放电不自动充。
必须如实告知的注意事项
- 深放、满电高压是锂电池老化最快的方式——加速循环 = 加速健康度下降，寿命缩短，这是它的本来代价。
- 循环次数按苹果统计口径累计；保修/换电池条款请用户自己核对，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 或写外部命令脚本时再看）。
