USB 功率监控 1.11.1（build 15）
整理日期：2026-10-23，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% 时，会变黄并通知一次；正常上限等待不报警。
主菜单只显示功率、电量、电气参数和必要状态，不再显示“电量暂时稳定”等趋势文字；菜单栏悬停提示也移除趋势文字。内部电量趋势判断仍用于图标颜色及原有掉电通知，不新增日志。时间戳、采样频率仅在显式开启的诊断记录中出现，普通运行不写日志。
默认仅小图标模式的菜单栏占位宽度为 14 点，较 1.11 缩窄 2 点；14×16 点的图标图像保持原尺寸。带功率数字的显示模式仍按内容适配宽度。

安装与组件
程序包包含 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 连接”只在用户针对设备确认后执行，会中断数据连接，集线器还影响下游设备。不保证重新协商供电，不作为自动修复。

本次验证（1.11.1，2026-10-23）
构建与内置状态、趋势、菜单周期及采样组件签名/限频检查通过；浅色、深色原生菜单预览已检查，趋势行及对应留白已移除。刷新、连接监听、电量查询节流和状态判定逻辑未修改。
已更新 /Applications 的正式应用及原有采样组件，二者与 build/ 逐字节匹配，应用正常启动且无诊断参数。主动采样返回成功（1），iPad、iPhone 功率和电量可读，通知权限仍为已授权（2）。
界面自动连接超时；用户实际展开菜单确认“正常，文字已消失且图标完整”，并确认能正常点击。此次未重复执行插拔或睡眠唤醒测试；以下为 1.11 的历史验证。

历史验证（1.11，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 或设备均支持全部读数。
本次清理保留当前源码、构建、使用方法与必要验证摘要，旧版本回退包、逐轮诊断原始记录、示例预览和编译缓存不再保留。
