MyFinder Device Battery
Windows 上的多品牌无线鼠标、耳机与键盘电量卡片,支持 MyDockFinder / MyFinder,也可独立作为系统托盘应用使用。
当前源码版本 1.3.11-beta.20(测试版),适用于 Windows 10/11 x64。原生界面使用系统 .NET Framework,发行包内置设备读取组件,无需用户安装Python、厂商驱动或填写VID/PID。公开可下载版本以 Releases 页面为准,旧版本保留在历史Release中。
1.3.11-beta.20 新增狼蛛 AULA F99 MAX 的 2.4G 电量候选。共享 05AC:024F 接收器只有在产品串、集合、报告长度与自报固件身份均符合时才会读取。一次只发送两包固定设备信息请求,不使用配置、灯光、配对或固件命令。电量有官方驱动与键盘屏显 68% 的一次对照,充电状态、睡眠唤醒及驱动共存仍待本版实机确认。
1.3.11-beta.19 新增 VGN F1 MOBA 有线接口(3554:F506)的只读电量候选。程序仍要求运行时确认 FF02:0002 和目标输出恰为17字节后才查询;目前只有官方 VGN HUB 的静态协议依据,没有该接口的实机回复或厂商界面对照,充电状态也未实机确认,DPI 不在此适配范围。
1.3.11-beta.18 新增迈从 G3 V2 原版鼠标的 2.4G 电量及充电候选,按 M HUB 的 10% 档位显示。改进迈从 A7 V3 Pro 指定 2.4G 接收器的电量读取,补充 V9 PRO 原款耳机的满电显示和缺少接口诊断。ROG 夜魔原版支持指定的 2.4G 接收器;夜魔原版和魔导士 RX LP 还可通过 OMNI 读取电量和充电状态。五款待本版实机确认。
1.3.11-beta.17 新增维咖 NUT75 和 Veekos Shine 60 两款键盘的指定 2.4G 接收器电量候选,以及 ROG 棱镜 2 耳机的 2.4G 电量和充电候选。前行者 X23 Pro 鼠标仅监听 2.4G 接收器上报的电量。前行者 X87 原版键盘通过只读身份页核对接收器型号后显示电量。五款均待本版实机反馈。
1.3.11-beta.16 新增雷蛇毒蝰 V4 Pro、迈从 K99 V3 键盘、V9 Pro 2 耳机的 2.4G 接收器,以及狼蛛 V9 Pro+ 和 F87 Pro V2 D 版接收器的电量候选。五款已做离线验证,待本版实机反馈。
1.3.11-beta.15 新增索尼 INZONE H5、H9 II 和 Buds 使用原装 USB 接收器时的电量读取。Buds 分别显示左耳、右耳和充电盒的读数。已用公开设备报文验证,等待用户在测试版中与 INZONE Hub 对照。
1.3.11-beta.14 加入 VGN 共享 2.4G 接收器(3554:FB3E)的电量候选。蜻蜓 F2 Pro Max 与 Y2 Pro 的用户提供了电量回复,待本版实机复测,充电状态未知。
1.3.11-beta.13 加入达尔优 CM610 Pro(260D:1074)的分离接口电量候选,待实机复测。检查更新时遇到临时网络故障,程序会在 15 分钟后自动补查一次。旧版内置更新失败时可从 Releases 下载完整 ZIP。
1.3.11-beta.12 新增 VGN 蜻蜓 3 Pro Max(391D:1A04)和多彩 M900 Ultra / GH8K(3554:FB26)的 2.4G 接收器电量候选。程序核实目标集合和报告长度后查询。两款均有贡献者实机数据。本版还按 VGN HUB 的设备表加入 Y2 V2 Pro Max、蜻蜓 3 Ultra、F1 V2 Pro Max、F1 V5 Ultra 和 F2 V2 Ultra 的五款 2.4G 接收器候选。各候选均为 C 级,待实机复测。
1.3.11-beta.11 新增 ROG 龙鳞 2 Ace 使用 SPEEDNOVA 8K 接收器(0B05:1AD0)时的只读鼠标电量与充电候选。程序会核对 USB 父设备、鼠标集合以及输入和输出报告,验证通过后才发出查询。已有上游 Windows 11 回复样本,本项目完成离线回放,仍为 C 级,待使用 MyFinder 实机核对。
1.3.11-beta.10 改善同一进程内相同输入的文字重绘稳定性:复用首次生成的透明文字位图,保留实时底图、裁剪和文字更新,字体、字号与布局不变。缓存最多 256 项、总估算约 8 MiB,淘汰时释放位图。不同进程首次绘制、缓存重建及不适用缓存的绘制路径仍可能出现细微字形差异;Windows 内部触发原因和长期内存行为尚未确认。本版不新增硬件或 DPI 功能。
此前测试版已包含以下功能:
1.3.11-beta.9 仅新增迈从 MCHOSE A5 V2 Ultra(3837:100C)的只读电量候选:精确产品名、USB 父设备、唯一目标集合及 Feature 报告长度均通过运行时证明后,才使用已核实的电量查询;连续两次有效回复稳定一致才显示,失败清除该候选旧值。不新增 DPI 功能,不扩展到其他迈从或共享 100C 的产品。仍为 C 级,尚无该型号实机验收;实际描述符、电量与充电、休眠重连、官方软件共存和采样新鲜度待验证,稳定双读不保证设备产生了新采样。
1.3.11-beta.8 新增 VGN F1 Moba 2.4G 接收器(3554:F503,#592)的只读电量候选,沿用现有 CompX 查询;仅在运行时确认 FF02:0002 集合、输出报告恰好 17 字节后查询,门禁未通过时不发送,不扩展到所有 F1 或其他共享 3554 的型号,不新增 DPI 功能。#592 提供了 95%、未充电的完整回复,本项目仅做离线回放,并非维护者实测;仍为 C 级,充电转换、冷启动、深睡唤醒及厂商软件共存待确认。
1.3.11-beta.7 将更新检查与附件下载的等待分开,缺少可靠服务端提示时从 5 分钟逐步延长、最多 1 小时;有效服务端期限与旧记录的保守等待仍保留。界面准确显示缓存版本、等待到期和检查完成状态;签名及安装保护不变,本版不新增设备协议,真实限流与自动安装效果仍待验证。
1.3.11-beta.6 将默认主面板切换为环形布局(B),并保留电量条(A)与网格(C)可选;三种布局分别支持海蓝、原生、琥珀、青雾配色、浅/深色和标准/较大字号。网格设备方块可直接进入详情,快捷控制仅在空间不足时内部滚动;布局选择页新增缩略图,主面板打开时播放 240ms 填充动画,支持减弱动效。本版不新增设备协议,也不改变 DPI 或音频控制行为。
1.3.11-beta.5 为英菲克 IN10 接收器(1D57:FA65,#264 #356 #470)补上严格原始 HID 报告描述符回退和更具体的脱敏诊断。读取仍仅限已有的网页/旧款接口集合及接收器版本标识,只接收主动上报;尚未取得真实 FA65 描述符,C 级,待实机验证。
1.3.11-beta.4 为迈从 A7 V3 Ultra+ 接收器(3837:1018,#535 #536)在 Windows 上增加一条精确的描述符恢复路径:只有产品全名、接口和唯一 FF01:0001 集合符合条件,且系统 HID 接口在内存确认输入、输出报告 4D 均为 64 字节时,才沿用原有的只读 0900 电量查询。其他型号不经过这条恢复路径,3837:1014 的行为不变,歧义或证明不完整时不扩展;充电、休眠和冷启动仍待确认,C 级,待实机验证。
1.3.11-beta.3 修正竹林鸟 ZG4(3654:5055,#459)对真实设备在线状态帧前缀的解析,使原有的严格只读电量候选能继续走两阶段读取。仍仅限产品全名 ZhuAudio ZG4、MI04 / FF05:0001、同一物理 parent 下唯一 FF05,以及描述符逐报告证明输入 CE、输出 CD 都是固定 Usage 字节数组且各 64 字节;不支持其他型号和两个 FF02 集合。C 级,待实机验证。
1.3.11-beta.2 为 ROG OMNI 接收器(鼠标)(0B05:1ACE)新增严格只读电量候选,并补充固定脱敏诊断。该版支持 OMNI 鼠标,夜魔键盘的读取自 beta.18 加入。冷启动、休眠和未配对场景仍待确认;C 级,待实机验证。
1.3.11-beta.1 新增狼蛛 SC650(1D57:FA60)另一种 5 字节无编号上报帧的只接收电量读取(待实机验证),不向设备发送任何命令。
1.3.10 正式版汇总了 1.3.10-beta.1 至 beta.9:前行者 S9 PRO 8K、迈从 41E4:2001 键盘、水月雨 GM01 Pro 已有用户实测读通;新增 CHERRY、凌豹 M1 Pro、竹林鸟 ZG4、英菲克 IN10 旧款等(待实机验证);停用 3554:FA09 非迈从键盘的错误 100% 读数。
1.3.10-beta.9 补齐 ATK / VXE NANO 接收器(373B:1216)读不到电量时的固定脱敏诊断,可区分报告证明、通信和无有效回复等阶段。读取协议、安全校验和读写次数保持原有规则;A9 3.0 NK 的实际读取问题仍待新版诊断与实机对照确认。
1.3.10-beta.8 新增竹林鸟 ZG4(3654:5055)和凌豹 M1 Pro(088D:052F)的严格电量读取候选,补充狼蛛 SC650 已报告的被动电量前缀;均为 C 级、待维护者实机验证。凌豹充电时的 100% 占位不作为新读数。边界见 ZG4 说明 和 凌豹说明。
本版也改进雷蛇持续收到不匹配回复时的有界恢复,并为迈从 3837:1018 增加严格证明后的 FF0B:C4 备用集合选择;保留原有有效接口优先及全部回复校验,不猜测 41 字节新协议。实际设备效果、休眠恢复和官方软件共存仍待用户对照验证。
1.3.10-beta.7 新增 CHERRY MX 2.0S WL Pro 的精确 USB / 2.4G 电量适配(046A:01E0 / 01DE),依据贡献者 #482 的多档电量与插拔充电对照,仍为 C 级、待本项目维护者实机验证;蓝牙沿用系统电量路径。范围和未验收项见 CHERRY 说明。
本版停用 3554:FA09 上不随实际电量变化的 Feature 06 备用读数;保留独立证明的 BY 电量通道,并为精确 FF02 接口补充严格描述符证明。旧缓存仅按原逻辑保留历史,不再由错误字段刷新。
1.3.10-beta.6 为迈从 41E4:2001 键盘接收器的报告描述符证明和迈从 V3、GLW/QHW 读取器补充诊断;不改变现有读写协议,相关设备仍待用户实机验证。
1.3.10-beta.5 新增符合旧版英菲克驱动定义的 IN10 / FA65 接收器被动电量读取,只接收主动上报,并补充 FA6x 读取诊断;充电状态未知,待实机验证。
1.3.10-beta.4 补齐 ATK N9 V2 ULTRA / ULTIMATE 读不到电量时的诊断原因,不改变读取协议;实际 2.4G 电量读取仍待用户验证。
1.3.10-beta.3 补齐迈从 V3 和 Pulsar 读取不到电量时的诊断原因,并修正同接收器 ID 的迈从鼠标名称显示;实际电量读取仍待对应用户验证。
1.3.10-beta.2 修复水月雨 GM01 Pro 读不到电量(待实机验证)。
1.3.10-beta.1 修复前行者 S9 PRO 8K 读不到电量,并按迈从官方驱动改进迈从键盘接收器的读取(待实机验证)。
1.3.9 正式版汇总了 1.3.9-beta.1 至 beta.10:新增 VGN V98 Pro V3、雷柏 VT3 系列、HyperX 03F0:0FCC、迈从 A7 V3 Ultra+(均有用户实测),以及前行者 S9 PRO、达尔优 EM901、Pulsar Link 8K、ATK 耳机与 NANO 接收器、英菲克 FA60/FA65 等(待实机验证);正式版也可收到测试版提醒,更新检查改为每 6 小时。
1.3.9-beta.10 将 3554:FA09 键盘的 Feature 06 读数标为“待确认”。
1.3.9-beta.9 改进读不到电量时的诊断信息。
1.3.9-beta.8 新增迈从 A7 V3 Ultra+,并改进前行者 S9 PRO 的读取。
1.3.9-beta.7 修复部分雷柏鼠标和水月雨 GM01 Pro 因报告长度无法确认而读不到电量(待实机验证)。
1.3.9-beta.6 自动检查更新改为每 6 小时一次,托盘更新小圆点保留到安装或跳过为止。
1.3.9-beta.5 新增 HyperX Cloud III Wireless 03F0:0FCC,雷柏读取诊断写明原因。
1.3.9-beta.4 新增 ATK/VXE NANO 接收器和 1D57:FA60/FA65 接收器(英菲克等,只接收上报;均待实机验证)。
1.3.9-beta.3 新增狼蛛 FA09 键盘、ATK 海王星 N9 V2 耳机、水月雨 GM01 Pro 耳机(均待实机验证)。
1.3.9-beta.2 修复雷柏读不到电量并新增 VT3S 等雷柏型号,新增前行者 S9 PRO 8K、达尔优 EM901(均待实机验证)。
1.3.9-beta.1 新增 VGN V98 Pro V3 / V87 V2 / N75 V2 / V108 键盘接收器、迈从 41E4:2001 键盘接收器、Pulsar Link 8K,3554:FA09 上的狼蛛等键盘也会尝试读取(均待实机验证);修复低分辨率下文字发虚并新增“较大字号”。
1.3.8 正式版汇总了 1.3.8-beta.1 至 beta.7:新增迈从 FA09 接收器键盘、雷柏 VT3 系列、VGN 2.4G 键盘接收器、蓝牙和 Xbox 手柄等设备,ATK F1 V3 等 CompX 鼠标的 DPI 档位切换;修复雷柏几乎读不到电量和“我的反馈”窗口卡死。设置里新增“提醒测试版更新”(默认打开),正式版用户也能在程序内收到测试版。
1.3.7 正式版汇总了 1.3.6-beta.1 至 beta.4 的改动,并新增“我的反馈”:在程序里提交的反馈可以查看维护者回复、追加补充资料,不需要 GitHub 账号。新增设备包括迈从 A7 V3 Pro、V9 PRO、V9 Turbo+,VGN 蜻蜓 F2 Master+ 等;支持型号数据包。
1.3.6-beta.4 新增迈从 V9 Turbo+ 耳机的电量读取;修复任务栏自动隐藏时面板底部被遮挡。
1.3.6-beta.3 新增 VGN 蜻蜓 F2 Master+、VXE R1 SE 接收器的电量读取(待实机验证);雷蛇读不到电量时,诊断信息会写明失败在哪一步。
1.3.6-beta.2 新增迈从 A7 V3 Pro、G3M PRO 鼠标、前行者 S9、飞智 APEX5 手柄的电量读取(均待实机验证);有新版本时托盘图标右上角显示一个小圆点。
1.3.6-beta.1 新增赛洛斯 8K 接收器、迈从 V9 PRO 耳机、迈从 G98 V3 和 G87 V2 键盘的电量读取(均待实机验证);支持“型号数据包”,以后同协议的新型号不用更新程序即可生效;反馈报告不再列出虚拟设备和灯控设备。
1.3.5 正式版汇总了 1.3.5-beta.1 至 beta.9 的改动:多品牌协议族识别与重复连接合并、托盘跟随当前使用的设备、托盘分组(最多 4 个托盘图标)与设备图标样式、四套配色、程序内反馈(不需要 GitHub 账号)、带签名校验的程序内一键更新,以及统一的弹窗样式。1.3.4 及更早版本没有更新功能,需要手动安装一次 1.3.5。
1.3.5-beta.9 修复 beta.8 弹窗在真实桌面上的黑角、残影和叠字;更新后自动打开的面板贴在托盘图标旁;更新窗口缩小,不再默认全选说明;悬停高亮改为淡底色。
1.3.5-beta.8 更新、反馈、改名和提示窗口改用主面板的卡片、按钮和配色;修复从 PowerShell 7 等环境启动时一键更新失败、且失败后程序没有重新启动的问题。
1.3.5-beta.7 修复无线耳机关机后,接收器的音频端点被误当成有线耳机、显示“耳机”卡片的问题。
1.3.5-beta.6 新增程序内反馈(不需要 GitHub 账号)和托盘分组:最多 4 个托盘图标,可选设备图标样式;修正诊断里的 Windows 版本。分组和多图标尚未实机验证。
1.3.5-beta.5 精简菜单,新增“设备没显示?”页和四套配色(海蓝、原生、琥珀、青雾),合并托盘显示规则,加大电量数字并突出低电量。界面改动只用假数据渲染检查过,尚未实机验证。
1.3.5-beta.4 修复发行包无法一键更新的问题;1.3.5-beta.2、beta.3 的包只能手动安装,但已装的 beta.2、beta.3 可以一键更新到本版本。完整更新流程尚待用户实测。
1.3.5-beta.3 修复100%电量显示为省略号和切到耳机后回不了扬声器的问题,收起的音量栏改为只有点三角才展开。
1.3.5-beta.2 隐藏同一设备的重复连接,增加一键反馈、托盘跟随当前使用的鼠标、可收起音量栏、有线耳机快捷音频,开放G Pro Wireless的DPI切换,并加入带签名校验的自动更新。2026-11-03 收到单个用户反馈:重复卡片已消失,G Pro Wireless 有线和无线都能切换DPI,托盘跟随和耳机卡片正常。
1.3.5-beta.1 试验按协议族读取未列明的ATK设备,诊断摘要可列出未取得电量的设备,并改用AGPL-3.0-only许可。2026-11-02 收到单个用户反馈:ATK A9 Air 电量正确;仅为该用户的只读电量证据,等级仍为 C,不代表整个协议族已验证,也不开放 DPI。
1.3.4 修复轮询预算不足造成的失败误报,并缓存稳定路径集合下的完整HID描述符;路径变化或定向刷新时重读动态产品字符串。这两项尚未用真实Audeze或慢速读取器实测。
1.3.3 优化蓝牙查询频率与轮询顺序:连续成功查询仍无带电量设备时降低查询频率,优先完成HID读取;面板打开时蓝牙结果可在下次轮询显示,面板关闭时同步等待。
1.3.2 加固原生 ATK 的接收器身份与旧请求隔离,修复快照写入竞态,增加可见的诊断写入健康与实例标识。同步时间按真实读数显示,不增加常驻轮询,也不扩大设备协议范围。
1.3.1 使用新的冰川蓝双卡应用图标,统一 EXE、开始菜单与启动快捷方式的显示;小尺寸采用简化轮廓。顶栏仍实时显示设备电量,独立于静态应用图标。
1.3.0 加入USB鼠标活动后的定向补读:读数过期或状态未确认时,移动对应鼠标会触发一次检查,读到新数据后及时更新卡片和顶栏。重复活动合并处理,保留后台定时同步。
正式版包含多品牌电量卡片、ATK与GPW独立DPI控制、系统音量、设备隐藏/排序及耳机音频绑定。PRO X Wireless(C547接收器)的快捷DPI只改变当前灵敏度,不改写板载档位、固件或配对;所有控制均核对目标并读回确认。此前测试版的读取隔离、安装回滚、托盘开关和视觉修复一并保留。
升级后,旧版仅按型号记录的通用设备缓存和别名不会自动套到新的物理设备标识;原配置保留,必要时可在设备详情重新命名。历史读数只有设备标识、类型和读取器都相符时才复用。
自动识别范围见 兼容清单。目前包含26个通用读取器和原有专用适配:
- ATK HUB 识别为 A9 Air+ 的2.4 GHz鼠标,已验证接收器 VID/PID
373B:1278、FF02:0002、17字节报告。其他接收器或同名变体不保证兼容。 - HyperX Cloud Alpha Wireless,已验证
03F0:098D、FF43:0202、31字节报告。 - 音源切换和 Windows 麦克风静音支持用户主动绑定其他活动音频端点;这不会让其他耳机自动获得电量支持。
- 通用读取支持Logitech HID++鼠标/键盘/耳机、Razer无线鼠标和部分2.4G键盘,以及SteelSeries、HyperX、Corsair、ASUS ROG、Audeze、JBL、Pulsar、WLmouse、MCHOSE、Lofree等已列明型号。
- 蓝牙使用Windows已经提供的电量;标准HID设备只有明确声明电量字段时才读取。私有协议设备按内置型号表识别,不向未知接收器试发厂商命令。
- 自动按设备类型生成鼠标、耳机、键盘卡片;设备更多时可用滚轮或页码按钮浏览。通用设备只显示已有可靠能力,DPI写入限原生ATK、PRO X Wireless / C547及下述精确名称的G Pro Wireless Gaming Mouse。
- 支持设备插上接收器或完成系统蓝牙连接后即可读取。未支持或未返回数据的设备保持未知,不显示编造百分比;同品牌全系列与“市面所有设备”不作保证。
| 布局 | 浅色(海蓝) | 深色(海蓝) |
| --- | --- | --- |
| 环形(默认) |
|
|
| 电量条 |
|
|
| 网格 |
|
|
以上截图均由程序实际 C# 绘制代码配合模拟状态生成,用于展示布局和操作反馈,非实时硬件图。
使用和安装
从 Releases 下载正式版Windows x64 ZIP并完整解压。保留engine目录与outputs目录;只复制exe会丢失通用读取能力。
- 临时使用:运行
启动.bat,或outputs/AtkMouseBattery.exe --show。 - 稳定安装及自启:运行
一键安装自启.bat。程序复制到%LOCALAPPDATA%\Programs\MyFinderDeviceBattery,再创建当前用户的启动文件夹和开始菜单快捷方式,无需管理员权限。 - 以后更新会复用已记录的安装目录。稳定安装后可以移动或删除原解压包;直接运行的绿色模式需保留原目录。
- 更新前先从托盘右键退出程序,或运行新版
outputs/AtkMouseBattery.exe --exit请求已支持该入口的版本退出;更早版本仍从托盘退出。安装器按整个发行包检查变化,即使exe未变、只有设备读取组件更新,也会先检查已安装主程序和便携读取进程是否退出。完整候选包先校验并暂存,再复制;复制和注册失败会恢复本次涉及的程序、读取组件、安装记录和快捷方式。用户设置不在安装事务中改写。
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Startup.ps1 -InstallDirectory D:\Tools\MyFinderDeviceBattery
运行 一键卸载自启.bat 只关闭自启,保留程序、开始菜单入口和设置。若要同时移除开始菜单入口:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\Uninstall-Startup.ps1 -RemoveStartMenu
移除程序使用 -RemoveProgram,同时清除个人设置再加 -RemoveData。两项都不会递归清空目录:程序清理只移除安装收据中哈希仍一致的自有文件,个人设置清理只移除本程序已知文件,未知或手动修改的文件会保留。完整卸载前请退出程序;默认不加参数仍只关闭自启。
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\Uninstall-Startup.ps1 -RemoveProgram -RemoveData
完整包包含 release.json、package-manifest.json 与第三方许可证。安装前校验文件长度和SHA256,并记录版本、配置schema及自有文件清单;缺少运行库、文件被修改或路径不安全时拒绝安装。应用自启诊断区分可用、被Windows禁用、入口缺失、目标异常和无法确认,不自行修改Windows的启动禁用决定。
安装器兼容 Windows PowerShell 5.1 和 PowerShell 7,并识别本程序旧版的乱码快捷方式。Windows“启动应用”中已禁用的项目需先手动启用。自启直接运行 GUI exe,没有 PowerShell窗口、计划任务、服务或 watchdog。
面板和操作
- “显示与提醒 → 托盘图标”可添加分组,最多同时显示 4 个电量图标。第 1 组包含未分到其他组的设备;其他组可命名、选择成员,并按当前使用的鼠标、最低电量或固定设备显示。每台设备只属于一个组,删除分组后成员回到第 1 组;空组保留灰色图标。Windows 可能把新图标收进隐藏区,可在“设置 → 个性化 → 任务栏 → 其他系统托盘图标”中打开。
- 所有托盘图标可统一选择“数字”或“设备图标”样式。设备图标用鼠标、键盘、耳机或通用设备图形配底部电量条,保留电量等级色、充电标记及历史读数的灰色提示;每个图标都打开同一个面板和右键菜单。
- 默认「环形」将设备行和系统音量放在同一面板中;「电量条」使用独立卡片;「网格」提供两列设备方块和固定快捷控制区。点击设备行或方块直接进入详情。仅当网格快捷控制组溢出时,组内可独立滚动,系统音量和底部状态行保持固定。标准/较大字号面板宽度分别为260/300px,更多设备可分页浏览。
- 打开主面板时,电量条和圆环以240ms缓出动画增长到当前读数,数字始终显示真实值;刷新读数直接更新。开启「减弱动效」后直接显示最终状态。
- 左键逐次点击托盘图标展开或收起,点击其他窗口动画收起;
Esc先返回上一级,再收起主面板。返回保留逻辑焦点,蓝色焦点描边只在键盘或无障碍操作时显示;鼠标导航及时收起旧提示气泡。 - 开始菜单、
启动.bat或scripts/Start.ps1会唤出已运行实例的面板,保留单实例。启动脚本不是开机自启入口;开机仍安静运行。 - ATK鼠标卡片显示真实 DPI 档位,点击选择现有档位。已适配GPW卡片显示“快捷DPI”,提供当前值和常用灵敏度;快捷值不代表设备保存的板载档位。切换中显示待确认目标,核验后再改变选中状态;ATK连续选择串行保留最后意图。刚确认的当前值重复点击会跳过写入,断连、读数过期或结果未知时停用控制并先重新读取。
- 原生耳机电量卡片在无线连接确认后显示,音频接收器存在不代表无线已连接。没有原生卡片时,活动的已绑定耳机输出,或Windows报告的耳机类输出端点,可显示一张“耳机”快捷音频卡片,提供扬声器、耳机和麦克风按钮;这张卡片不显示电量,不声明无线连接,副标题显示端点名称。多个候选且未绑定时停用耳机按钮并提示绑定。通用无线耳机同样可用这张音频卡片;原生卡片显示时不会重复,设备管理可隐藏它。
- 点击立即反馈,设备或Windows核验后立即更新选中项;只有等待超过约280ms才显示待确认提示,不为动效增加延迟。连续点击合并到最后目标,失败保留已确认状态。
- 电量按设备上报能力显示。整数百分比使用1%显示单位;档位或电压估算明确显示“≈/约”,托盘以
~标记,不假装精确到1%。鼠标、耳机、键盘和托盘共用绿/黄/红,未知或缓存为灰色。电量环保持角度稳定,不旋转充当加载动画。 - 主弹窗有一条共用的系统音量滑块,显示当前输出名称和百分比,支持拖动、键盘和无障碍调整。右上角可立即收起为图标与百分比窄条,点击窄条或聚焦后按空格/回车展开;收起后没有滑块命中区域,状态保存到
VolumeCollapsed,重启保留,默认展开。拖动释放后提交;收起会取消未释放的拖动预览,已提交的音量队列仍照常核验。外部音量或音源变化会同步,无默认输出或状态未确认时停用音量调整。设备详情仍可进入音频页做更完整的操作。 - 音源和静音操作失败时显示短提示。输出切换保留通讯默认输出和默认录音设备。操作提交时固定端点与绑定快照,改绑或切换设备页面会取消旧待办并核对新状态。
Tab/Shift+Tab或左右方向键移动焦点,Enter/ 空格执行聚焦操作。- 面板按所在显示器 DPI 缩放,绘图与命中坐标共用同一比例。100/125/150/175/200%五档比例有离线渲染与坐标检查;实际跨屏表现仍需具体设备验证。
设置
点击公共底栏右侧的“更多”,或托盘右键的“设置…”;设置与详情都在同一浮层内打开:
- 分别选择扬声器、耳机、麦克风按钮绑定的 Windows 设备。
- 绑定默认保留 Realtek 扬声器和 HyperX 音频端点识别;没有匹配的HyperX输出时,可识别唯一的Windows耳机类活动输出(
Headphones=3、Headset=5,见Windows枚举)。自定义绑定按设备ID精确选择;设备断开后按钮不可用,不静默切换到其他设备。 - 快捷音频卡片按Windows现有音频事件更新插拔,不新增轮询;候选只来自
DEVICE_STATE_ACTIVE端点。3.5mm插孔取决于驱动,可能拔出后仍报告活动,或将耳机报告成扬声器;可在现有音频设置中绑定端点,但无法补足驱动未报告的插拔状态。识别、插拔和保存绑定本身不会切换默认设备,只有点击输出按钮才切换。 - 在“音源与麦克风 → 更换按钮绑定”中选择精确端点。“自动识别”与当前绑定均可见;设备断开后保留原绑定。保存配置本身不切换音源或改变静音。
- 通用耳机的详情页可单独绑定 Windows 扬声器、耳机和麦克风端点;未绑定的角色显示不可用,不套用其他耳机的自动识别结果。离开该设备音频页后恢复全局控制,主弹窗音量始终面向当前系统输出。
- “设备管理”保留隐藏设备入口;在设备详情中可隐藏/恢复、置顶或上下移动。隐藏只影响本程序的显示和默认托盘候选,不禁用系统设备或停止读取。隐藏的固定设备暂时回退到其他可用设备,恢复显示后可继续使用原固定设置。
- 无配置文件的新安装默认“当前使用的设备”(
active),仅依据现有USB鼠标活动,按物理连接匹配电量卡片;不判断键盘、音频或蓝牙活动。切换后至少3秒才接受另一只鼠标,锁屏时不跟随;无活动、设备消失或没有电量时使用原有自动选择规则。已有配置保留原值,旧文件缺省项仍按原来的鼠标优先处理。可改选自动、鼠标优先、耳机优先、键盘优先或最低电量;自动模式保持当前有效来源。设备详情中“固定为托盘主设备”优先级最高,固定设备暂时无有效读数时按原规则回退,恢复后再选回;卡片置顶只改变排列。 - 降级前请将托盘来源改为“自动”并保存:旧版本会拒绝含
active的配置,暂时使用整份默认设置(包括音频绑定等),而非仅回退托盘选项。原文件保留,旧版再次保存时现有机制先尝试备份为audio-settings.json.unread.bak。 - 低电量提醒默认关闭,可选择10%、15%或20%(默认20%);每台设备每轮放电只提醒一次,充电或回升至30%后重新计数。缓存不触发提醒;全屏、演示或系统不允许通知时延后。
- 外观默认跟随系统,支持浅色/深色与减弱动效。偏好选项提供统一的选择页并自动保存;详情中的设备别名只影响本程序,不改系统或USB名称。
- 同一设备的有线/接收器旧连接满足严格条件时暂时隐藏;两张都是当前读数、同一接收器不同槽位均保留。诊断摘要可查看“已隐藏的重复连接”,恢复读数后重新显示。两只同名鼠标电量接近且其中一只休眠时也可能暂时隐藏,详见兼容边界。
- “状态与诊断”显示自启与读取状态,可主动复制本机诊断摘要。“状态与诊断”和“设备没显示?”中的“反馈问题”打开反馈窗口,可选择类型、填写描述、选择是否附带诊断,并查看完整诊断。反馈使用独立报告,仅包含程序/Windows 版本、卡片设备原始名称、类型、读取器、电量与当前读数标志、明确匹配的 VID:PID、隐藏连接、未取得电量设备及异常读取器状态;不含别名、音频端点、进程/实例身份、路径、序列号或 physicalId。隐藏连接和未取得电量设备列表不写入
status.json。请不要在描述中填写个人信息。 - 反馈可在程序内提交,不需要 GitHub 账号。中转服务不可用时,可点击“改用浏览器提交”,复制类型、描述和所选诊断,并用默认浏览器打开预填的 issue 表单,需要 GitHub 账号。提交前可检查内容,预填失败时可粘贴剪贴板报告;URL 上限 6000 字符,超长先去掉健康项,再从末尾去掉未取得电量设备,仍超长才裁减隐藏连接和卡片列表,必要时截断链接中的描述,并注明“已截断;完整内容已复制”。剪贴板保留完整描述和所选诊断。
- “我的反馈”可查看本机提交的反馈、维护者回复和自动初筛,并追加公开的补充资料。最多保留 50 条本地记录,记录与补充凭证使用当前 Windows 用户的 DPAPI 加密保存在
%LocalAppData%\MyFinderDeviceBattery\feedback-v1.dat;删除本地记录不会删除 GitHub issue,但会丢失本机的补充凭证。旧中转服务创建的记录只能在网页查看。补充超时后请重试原内容,程序会复用原请求编号确认结果。 - 默认约每 6 小时自动检查回复,长期无新动态时降低频率或停止;仅维护者的新回复会合并提醒,最多每 6 小时一次。“显示与提醒”中的“自动检查反馈回复”可关闭后台请求,关闭后仍可在“我的反馈”手动刷新。
- 接收器插拔、系统恢复会合并触发一次检查,仍保留原有定时兜底。耳机开机未必产生 Windows 设备事件。
刷新、缓存和安全
打开面板立即读取;面板内鼠标 DPI 每2秒调度,成功读取电量后至少30秒再读。耳机正常约6秒检查,失败后退避。面板关闭后默认每分钟检查,可选2分钟/5分钟;较慢间隔会延后耳机开机发现。没有新增常驻高频轮询。
电量的新鲜状态受90秒时效限制,还取决于读数来源和连接证据;这个窗口不会随后台间隔延长。选择120秒或300秒后台同步后,两次查询之间的电量可能先变灰并标为历史读数,保留原确认时间;这表示测量已过期,不据此判定设备断开。Windows蓝牙系统属性仍单独标明“系统提供”和最近查询时间,不冒充设备刚上报。
通用管理进程随本程序启动和退出,通过本地管道通信,最多使用两个按需读取槽,所有子树归本程序管理。没有网络监听、服务、计划任务或额外watchdog。通用读取展开时最多每8秒触发;Windows蓝牙快照默认至少间隔一分钟,连续三次成功查询均无带电量的设备后改为至少五分钟,查到带电量的设备或HID接口路径集合变化后恢复一分钟;标准HID字段至少30秒,打开面板和主动同步可立即请求。较慢间隔下,新连接的蓝牙设备可能要等到打开面板或下一次查询才出现。结果分批返回;面板打开时,蓝牙结果可能在下一次轮询才出现;面板关闭时在本轮预算允许时同步等待蓝牙结果。预算不足的查询延后并在下一轮优先,不记作读取失败。同一物理接收器的查询串行,失败独立退避;慢调用到达预算后终止隔离进程,保留上次证据。厂商GUI、配对、RGB、键位和固件操作不在读取组件内。
面板关闭、完整轮询确认没有通用设备状态且读取器均正常无设备或不支持时,释放空闲读取槽;管理进程继续按原间隔工作。有设备、历史状态待确认或读取故障时保留对应上下文。展开面板时保留读取槽以减少反复启动。
USB/2.4G鼠标恢复活动时,如果该设备读数已过期或连接未确认,会按可靠的USB物理来源补读。活动通知按来源合并,初次唤醒尚未应答时仅进行有限补读;读数新鲜时不因持续移动重复查询。未知设备保留原有型号与描述符校验,无法可靠映射的来源继续使用定时同步。移动本身不更新电量时间、不冒充设备在线,取得真实读数后才恢复电量颜色。打开面板、手动刷新、设备事件和后台定时器也会触发检查。
未知值显示 --。读数失败保留上次成功数据并标明时间,超过新鲜度阈值会改变显示和提示;跨日缓存包含日期。电量和充电标记分别检查时效。
可跨重启保留最近7天的电量和原确认时间,启动时明确视为缓存,不保存充电状态,也不以历史数据判断耳机已开机。无线读取短暂失败时暂保留卡片与缓存,确认断开/接收器移除或超过保留期限后收起。
ATK界面请求固定到用户点击时的接收器、目标DPI值和连接代次;写前复核接收器、型号、档位表和校验值,写后读回确认。接收器或档位表变化时取消旧请求,旧回读不能更新新实例;多个同型号原生接收器仍拒绝歧义。GPW使用独立的当前DPI命令,写前复核接收器、槽位、单元、支持范围与当前值,不改写板载预设;结果未知时不重试,重新确认前停用控制。鼠标补读与控制按所属队列串行处理。耳机只使用已验证的查询命令,不写固件、配对或设备设置。
精确设备名G Pro Wireless Gaming Mouse的DPI控制已开放,待用户实测:接收器仅限C539/C53A/C53D/C53F/C541/C545/C547/C54D;插线使用槽位0xFF,必须有现有HID++长集合写入路径和可靠的非零单元ID,缺失时不开放。PRO X Wireless / C547原有行为保留,其他型号或近似名称不开放。两种连接均只发送0x2201易失写入,先复核身份和当前值,只接受设备报告的支持值,写后读回,不重试、不写板载配置;尚无本次用户设备的接收器PID、插线身份及实际操作结果。
音源和麦克风操作在隐藏受控进程中独立排队,写入后核验并在失败时尝试恢复。超时表示结果未确认,安全回收并读回之前暂停新的控制;绑定、操作目标和配置代次随请求固定,过期回读不覆盖新页面。成功读取到“无默认输出”的空状态会替换旧状态,避免继续操作已移除设备。端点、音量和静音变化优先接收Windows通知,保留轮询兜底。麦克风按钮控制Windows端点静音,不宣称已同步耳机物理静音开关。不读取账号、浏览器或密码管理器数据;联网仅用于下述更新检查和用户确认后的更新下载。
软件更新
“显示与提醒”中的 AutoCheckUpdates(自动检查更新)默认开启,可关闭;关闭后不自动发出更新请求,托盘右键或“状态与诊断”的“检查更新”仍可手动使用。自动检查在启动至少两分钟后进行,之后每6小时最多一次;失败只记录诊断,不弹窗、不立即重试。HTTP 403/429 优先遵守有效的服务端期限,没有可靠提示时采用 5/10/20/40/60 分钟的本地等待;手动检查可绕过普通自动周期,不能绕过尚未到期的等待。更新检查与附件下载分别计时,升级前来源不明的旧等待仍同时约束两者。
程序以 HTTPS / TLS 1.2 请求本仓库的 GitHub Releases API,只附加普通的 User-Agent: MyFinderDeviceBattery/<版本>,不上传设备信息、诊断、设置、账号或设备/实例标识符。GitHub 仍会像普通网络请求一样看到来源 IP。正式版只检查正式发布,测试版同时检查正式版和 -beta.N,忽略草稿和无法解析的版本;只接受高于当前版本的更新。
只有用户在反馈或补充资料窗口点击提交时,程序才会把所填内容和(可选的)诊断发送到反馈中转服务 https://myfinder-feedback-relay.wushuai0802.deno.net(服务源码)。创建反馈还会发送随机生成的补充凭证,追加补充时携带该凭证;凭证不显示在界面或诊断报告中。自动检查及手动刷新回复只发送反馈编号,不发送凭证和诊断。中转服务不持久保存反馈内容,反馈和补充会公开显示在 GitHub;服务不可用时可改用上述浏览器提交流程。程序不内置 GitHub token,更新检查也不会上传反馈内容。
发现新版本后,托盘最多提醒一次,“更多选项”和“状态与诊断”显示“有新版本”。可在版本对话框中“跳过此版本”,之后不再提示它;更高版本恢复提示。发布说明按有长度上限的纯文本显示,不执行脚本、不解析或自动打开说明中的链接。
只有点击“更新并重启”才会下载安装。稳定安装须同时满足:现有安装器 Read-DeviceBatteryReceipt 读取的数据目录 install.json 指向当前程序目录,并通过 .myfinder-device-battery-install.json 目录归属检查。绿色解压模式只提供发布页面和稳定安装说明,不下载覆盖原解压目录。
更新依次校验内置 RSA 公钥对 SHA256SUMS.txt 原始字节的 RSA-SHA256 / PKCS#1 v1.5 签名、其中精确文件名对应的 ZIP SHA256,再拒绝 ZIP 路径穿越、绝对路径、盘符、备用数据流及链接,核对 release.json 的应用身份/版本和 package-manifest.json 的文件长度/SHA256。缺失签名、任何不符或降级都会中止;HTTPS 和 SHA256 不能代替签名。下载仅接受本仓库发布信息中的三个精确附件,HTTPS 重定向主机限定 github.com、objects.githubusercontent.com、release-assets.githubusercontent.com,不接受其他主机或 HTTP;单文件上限100 MB,有连接/读取和总耗时限制。
下载暂存于 %LOCALAPPDATA%\MyFinderDeviceBattery\updates\<版本>\,开始前检查暂存盘、安装盘及安装器临时盘空间,同盘需求合并计算。隐藏的系统 PowerShell 辅助进程等待现有 --exit 正常退出流程结束(最多60秒),不会强杀读取进程;随后再次独立验签并解压,调用校验包内的 scripts\Install-Startup.ps1 / Install-DeviceBattery 完成原有暂存、校验和事务回滚。成功后重启新版本,失败后核对并启动已回滚的旧版本,下次启动显示失败原因。用户设置保留,不要求管理员权限。成功、失败、取消后清理本次暂存;异常断电留下的暂存超过一天后在下次启动清理。
已发布的 1.3.4 及之前版本、1.3.5-beta.1 没有更新功能,须先手动安装一次后续带更新功能的版本。若签名私钥丢失,不能通过本更新通道换公钥,用户只能手动下载新版本完成公钥更换。
本地数据
目录:%LOCALAPPDATA%\MyFinderDeviceBattery。
| 文件 | 用途 |
| --- | --- |
| audio-settings.json | 音源绑定、主题、别名、托盘、提醒及同步偏好;自动兼容旧格式 |
| readings-cache.json | 电量与原确认时间,不包含设备ID;关闭保留读数后不使用、不更新 |
| wireless-cache.json | 通用设备电量与原确认时间,标识为散列值;不会用历史记录声明设备在线 |
| install.json | 稳定安装目录、版本、配置schema和自有文件哈希清单 |
| update-state.json | 上次检查时间、限流期限、跳过和已提示的版本 |
| update-result.json、update.log | 更新结果及失败原因,供下次启动提示;不上传 |
| updates\<版本>\ | 按次隔离的更新下载、校验与辅助脚本暂存 |
| status.json | 运行诊断,包含进程/实例身份、独立生成时间与写盘健康;不参与自动刷新控制 |
| low-battery-state.txt | 启用提醒后的去重记录 |
| active-ui-render.png、visual-status.json | 满足条件时生成的本机绘图诊断 |
运行状态文件不再由 Git 跟踪;卸载自启保留用户设置。更换驱动后 Windows 可能分配新的设备ID,需要重新绑定。
状态与诊断页显示诊断写入健康。文件中 snapshotGeneratedAtUtc 是本次快照生成时间,persistence.lastSuccessfulStatusWriteUtc 是生成该快照前最近一次已完成的状态文件写入,不是本次写入的完成回执。读取文件时还应核对 PID、启动时间、文件修改时间;旧文件不能证明当前设备在线。写入失败最多即时重试两次,后续正常状态更新可再次尝试,不创建后台守护。
构建和验证
源码仓库不包含预编译程序,请从 Releases 下载完整发行包;从源码运行需在源码根目录依次完成两步:先不带参数运行 scripts\Build.ps1(默认输出到 outputs\),再运行 scripts\Build-Backend.ps1 -OutputDirectory .\engine\runtime 准备通用设备读取组件。
从源码仓库运行:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\Build.ps1 -OutputDirectory .\tmp\build
使用系统自带的 x64 .NET Framework 编译器,不下载依赖。构建会运行协议、设置、端点匹配、菜单、控制队列、缓存、低电量策略、DPI坐标和安装回滚检查。测试用模拟硬件和隔离文件夹,安装器检查分别覆盖 PowerShell 5.1、可用时的 PowerShell 7,不改真实自启项或音源。测试截图保存在指定输出目录下。
release.json是版本唯一来源;构建时生成程序集版本信息。scripts/Package.ps1 -OutputDirectory <目录> 生成完整ZIP、包内文件清单及 SHA256SUMS.txt。使用已经验证的构建可传 -SkipBuild -BuildDirectory <构建目录>;源码、版本或构建文件在验证后改变会拒绝打包。
发布维护步骤:等待准确提交的 CI 全部通过,下载该次 CI 的完整发行 ZIP 和 SHA256SUMS.txt,核对 ZIP 哈希后,在本机对校验和文件签名:
.\scripts\Sign-Release.ps1 -ReleaseDirectory <CI产物目录> -PrivateKeyPath <仓库外的私钥XML路径>
签名工具只从参数指定路径读取私钥,在内存中签名并立即用程序内置公钥复验;验证成功才写出二进制 SHA256SUMS.txt.sig。私钥不得进入仓库、CI、发布附件或日志。将原样的 ZIP、SHA256SUMS.txt 和 SHA256SUMS.txt.sig 三个附件一起上传发布;签名后不能改动校验和文件的换行或任何字节。
更新回归使用临时生成的测试密钥和假 HTTP 层;可注入公钥的下载测试入口仅以 UPDATE_TESTS 编译,生产下载只使用内置常量。独立校验入口为 AtkMouseBattery.exe --verify-update-package (生产公钥,不启动界面/读取器)。CI 的 PackageSmoke 另用只校验目录的 --validate-update-directory <目录> <版本> 检查尚未签名的包,不需要私钥,该入口不安装、不等于已通过发布验签。
GitHub Actions 在main推送及PR上构建、运行协议与安装回归,然后将同一份构建打包为最终ZIP,隔离解压安装后启动真实应用和便携读取器进行无硬件检查,验证正常退出与父进程异常退出的子进程回收,最后上传该ZIP和SHA256。安装器小型模拟exe测试不代替完整包检查。离线检查不代替每种硬件、游戏和显示器组合的实测。
验证边界、交互性能与八小时资源采样方法见 验证范围与复验方法。
通用版打包会按engine/dependencies.lock.json固定URL与SHA256准备官方便携运行库,复用已通过校验的下载缓存并校验官方Python签名。维护端可运行Build-Backend.ps1,再用engine/runtime/python.exe -I -B -m unittest discover -s tests -p 'test_*.py'及-m unittest discover -s engine/tests检查协议与桥接。最终用户无需执行这些步骤。
自有代码采用 AGPL-3.0-only,按现状提供,不提供任何担保。1.3.4 及更早版本按 MIT 发布,下一版本起为 AGPL-3.0-only。改编自 HaloBattery 的部分保留其 MIT 声明,第三方许可见 THIRD_PARTY_NOTICES.md;源码地址为 https://github.com/wushuai0802/myfinder-device-battery 。许可证、无担保说明与源码地址也可在“状态与诊断”页查看。
AtkBatteryProbe.exe --help、--self-test 不访问 HID。--enumerate 读描述符;--power、--diagnostic 查询设备;--dpi-read 读取 PAW3955 档位表;--select-stage N 会实际选择一个已有的一基档位。