USB 功率监控 1.11（build 14）
整理日期：2026-10-17，Asia/Tokyo

用途与运行环境
查看 Mac 向 USB-C 设备输出的实际功率、电量与充电状态，重点提示 iPad 接电却持续掉电的情况。
主应用支持 Apple Silicon、macOS 12+；“及时更新功率”辅助组件需要 macOS 13+。应用为本地 ad-hoc 签名，未经过 Apple 公证。系统限制安装时，请按设备的安装规则处理，不绕过安全提示。
共享入口：https://blanc-testarossa.tail07b69f.ts.net/apps/usb-power-monitor/ （同一 Tailscale 网络内访问）

当前行为
没有可枚举的 USB-C 设备时隐藏菜单栏图标；插入设备后立即恢复，拔掉最后一台后立即隐藏。图标显示独立于较慢的功率、电量读取。
启用“及时更新功率”后，菜单展开约每 2 秒请求新功率，收起后每 30 秒更新功率、电量和 iPad 图标。系统更新事件继续及时生效。新设备接入及“立即刷新”会请求新读数；首次未知时保留最长两分钟的快速读取兜底。
每台设备使用统一闪电卡片：功率达到分界为绿色、低于分界为黄色、未知为灰色；默认分界 10 W，可在偏好设置调整。菜单栏图标表示 iPad 综合状态。
iPad 达到 80% 且暂停充电时为绿色；同一连接已观察到上限后，76–79% 正常等待补充仍为绿色。恢复充电或降至 75% 后重新按功率判断。至少观察 5 分钟、下降 2 个百分点且正在充电或已低于 75% 时，会变黄并通知一次；正常上限等待不报警。
主菜单只显示功率、电量、电气参数和必要状态。时间戳、采样频率仅在显式开启的诊断记录中出现，普通运行不写日志。

安装与组件
程序包包含 USB功率监控.app、PowerRefreshHelper、启动配置、维护脚本、签名清单和本说明。
先退出旧应用，把 USB功率监控.app 放到 /Applications/USB功率监控.app，再从该位置打开。固定应用身份为 local.usb-power-monitor；更新时沿用此路径。
主动采样组件只接受绑定应用签名与本机用户。预编译包绑定 UID 501，适用于本次构建用户以及同 UID 的账户。可用 id -u 查看；其他 UID 请使用源码包在本机重新构建后安装。缺少或关闭组件时仍可读取系统已有数据，但不保证每两秒产生新功率。
选择启用主动采样时，在已解压程序包的根目录执行：
  sudo /bin/bash -p PowerRefreshMaintenance.sh install "$PWD"
源码构建后的安装命令为：
  sudo /bin/bash -p PowerRefreshMaintenance.sh install "$PWD/build"
该步骤需管理员授权。主应用始终以普通用户运行；组件只请求系统新电源数据，不修改充电策略、不重置 USB，按需启动、空闲约 10 秒后退出。偏好设置可关闭此功能。
移除组件：sudo /bin/bash -p PowerRefreshMaintenance.sh remove
它不删除应用、偏好或登录启动配置。应用关闭后不再发起采样请求。新机器的登录启动可使用系统登录项或提供的 local.usb-power-monitor.autostart.plist 模板；本机原登录启动保持原状。

源码与重建
源码包保留七份 Swift 文件、Info.plist、两个启动模板、build.py、PowerRefreshMaintenance.sh 和本说明，无第三方运行依赖。需要 macOS Command Line Tools 与 Python 3。
在源码根目录以普通用户执行：
  python3 build.py
生成 build/USB功率监控.app、build/PowerRefreshHelper、组件启动配置、应用签名策略和校验清单，并运行内置检查。此命令不安装应用、不注册系统组件、不操作 USB 重置。
主应用每次重建或重新签名后，必须同步重建并更新辅助组件；不能只更新主应用。发布用原生应用与源码分别打包，校验值及逐文件 MANIFEST 随下载提供。

维护与诊断
build/ 保留当前正式构建和配套配置；编译缓存可删除，下次构建会重新生成。正式运行只使用 /Applications 的应用，以及 /Library/PrivilegedHelperTools 和 /Library/LaunchDaemons 下已安装的采样组件。
--check-indicator：内置状态、颜色、连接会话、菜单周期、电量节流和趋势检查。
--snapshot：一次只读快照。工具沙箱可能影响私有框架及通知查询，不能把受限环境的结果直接当作正式应用状态。
--trace-sampling 路径.jsonl：临时记录采样与实际绘制。先退出已有实例再运行，完成后正常重启以关闭记录。readAt 表示本地读取完成，systemUpdatedAt 是系统更新时间标记；后者不是逐接口硬件采样时间。
正式程序已避免重叠电量会话，电量读取在后台串行执行、等待最多 4 秒，旧电量超过 75 秒不参与判断，并核对 USB 会话防止重插后串用旧数据。
“重置 USB 连接”只在用户针对设备确认后执行，会中断数据连接，集线器还影响下游设备。不保证重新协商供电，不作为自动修复。

已完成验证（2026-10-17）
正式安装字节与工作区构建一致，应用及组件签名通过；内置状态/趋势/菜单周期/限频及签名匹配检查通过。本机两次新接 iPhone，约 1–2 秒出现功率。
无应用诊断日志时观察约 164 秒，连续五个后台间隔均为 30 秒。主应用 CPU 约单核 0.46%，RSS 约 83.3–83.5 MiB；组件约 8 MiB，按需启动后正常退出。属短时观察，不代表长期能耗或无内存泄漏。
真实合盖唤醒后，首次读取约 0.125 秒；收起时三个完整间隔为 30.002、30.019、30.003 秒。展开时九次请求均成功，间隔中位 2.011 秒；再次收起恢复约 30 秒，未遗留两秒循环。用户确认绿色 iPad 图标及功率更新正常。
合盖到唤醒通知窗口约 65 秒，期间可能有系统后台活动，不代表同样时长的持续深度睡眠。更长睡眠、长期运行、其他设备组合及实际颜色转换不据此保证。

限制
接口功率包含设备运行耗电和充电损耗，不能单独证明电池未放电；供电档位是上限，不是实时取电。依赖 USB 数据枚举，纯供电而不枚举的设备不按此规则显示。
系统私有电量与主动采样接口、机型提供的数据可能变化；不自动配对陌生设备，不保证所有 Mac 或设备均支持全部读数。
本次清理保留当前源码、构建、使用方法与必要验证摘要，旧版本回退包、逐轮诊断原始记录、示例预览和编译缓存不再保留。
