火三天然后呢:桌面小工具项目的常见死法

原创2026-11-18 05:01:131,605 阅读
文章标签:桌面应用系统编程

火三天然后呢:桌面小工具项目的常见死法

一个 350 KB 的 exe,2 MB 内存,没有服务、没有驱动、没有运行时,装在任务栏上显示无线鼠标和耳机的电量。这种东西在社交媒体上通常只有三天的命:第一天有人转发“终于有人做了”,第二天被搬进各类“自制工具分享”合集,第三天沉底。

Wireless-Device-Battery-Monitor 是个适合拿来解剖的样本,因为它把这三天之后的事情全都写进了代码:一份 30 行的兼容表格、24 个驱动实现、一套“只读、精确匹配、必须超时”的驱动规矩,以及一份明确列出“不支持什么”的清单。本文不谈它有多好,只谈这类项目为什么会死,以及这个仓库用什么工程手段往后拖时间。

先看清“火三天”到底有多长

社区情报里这个赛道的注意力分布很能说明问题。一篇介绍同类工具 VigilWatt 的文章,1318 阅读、2 收藏;一篇讲 LGSTray Battery 的文章,491 阅读、4 收藏;而同一批搜索结果里 15 条有 12 条是 QtScrcpy 的投屏教程,阅读量从 410 到 1172 不等。

这不是“竞品太强”,而是流量被同质内容摊平了。桌面小工具没有版本发布会、没有 benchmark、没有融资新闻,它能消费的注意力只有“我发现了一个痛点”这一条。等这句话被说了一百遍,第一百零一遍就没人点了。热度不是被谁抢走的,是自己蒸发的。

还有一个更隐蔽的信号:本仓库的快照只有一个 squash 后的提交(Merge PR #20),没有任何可用于统计提交节奏的历史。对分析者来说这是个坏消息,但对作者来说未必——它说明项目的对外形态是“一次交付”,而不是“持续叙事”。而“持续叙事”恰恰是热度赖以续命的东西。

任务栏上的电量挂件

死法一:兼容列表永远追不上用户手上的硬件

README 的兼容表格有近 30 行厂商条目,从 Logitech、Razer、SteelSeries 一路排到 Attack Shark、AULA、Rapoo、G-Wolves。看起来是战果,其实是负债表。

同一份 README 往下两段就自己承认了:真机验证过的只有 5 台——Glorious Model O Wireless、HyperX Cloud III Wireless、Cooler Master MM712、Rapoo VT3 Max Gen 2、Redragon M916 Pro 1K。其余全部是“按协议文档和其他项目实现,尚未测试”。

这不是谦虚,这是这类项目的第一个死亡陷阱:用户拿来的硬件永远比你表格里的多,而且长得越来越像杂牌。

看看“杂牌长尾”有多长。Rongyuan 接收器一行写着“81 个型号:Attack Shark R3、X82 PRO HE、Ajazz 键盘、部分 MSI 及其他”;G-Wolves 一行从 Fenrir 排到 VUK 再加各种 8K dongle;Xenta 接收器一行又是另一批。每一个名字背后都是一次协议逆向。

单台设备的边际成本有多高,看 Rapoo 就够。docs/rapoo.md 有 129 行,src/drivers/rapoo.cpp 有 112 行,tests/rapoo_protocol_test.cpp 和 tests/rapoo_driver_test.cpp 加起来 233 行。也就是说为了多支持一只鼠标,仓库多了近 500 行代码和文档,而这还是“顺手”的情况——因为协议刚好是推送式的。

更麻烦的是命名与型号的混乱。文档里明确写着:官方 manifest 里 1417/4617 这对 ID 叫 VT3 MAX,用户自己认作 VT3 Max Gen 2,而“社区表格把这个 ID 分配给 VT9 Pro 的做法不能作为命名或识别的唯一依据”。兼容列表一旦开始依赖社区口口相传的 ID 表,它就从技术文档退化成谣言集散地。

兼容债最终会变成架构债。 这个仓库的应对方式是给“认领”建一套最小机制,见 src/drivers/drivers.h:

struct PollContext {
    std::vector<HidColl> colls;
    std::set<std::pair<USHORT, USHORT>> claimed;
    std::vector<DeviceStatus> out;

    bool IsClaimed(USHORT vid, USHORT pid) const { return claimed.count({ vid, pid }) != 0; }
    void Claim(USHORT vid, USHORT pid) { claimed.insert({ vid, pid }); }

驱动按顺序跑,谁认领了某个 VID/PID,后面的通用回退就不能再报一次。于是 src/devices.cpp 里出现了一串看起来很奇怪、但每一行都有原因的排序注释:

PollAula(ctx);       // before Kysona, which shares the 3554 vendor id and would probe it first
PollAtkSerial(ctx);  // before Kysona, which shares the ATK vendor id
...
PollRazerHeadsets(ctx);  // before the generic Razer driver, which shares the vendor id

这三行注释就是兼容长尾的真实代价:厂商 ID 撞车、协议复用、同一 VID 下不同产品线要用不同解析器。死亡方式往往不是“不支持”,而是“支持一半”——把别的设备点亮、把 87% 读成 8%、在用户鼠标上写进一条不该发的报文。所以 CONTRIBUTING.md 才把规矩写成铁律:只读、精确匹配、必须超时、协议来源必须写在文件头注释里。

死法二:系统更新一次,采集链路整体失效

桌面小工具的第二类死法更致命,因为它和功能多少无关。

这个项目的数据来源分三层:HID 报文、Windows 设备属性、WinRT/XInput。前两层还算稳定,第三层是别人的实现细节。真正脆弱的是界面层——它没有用任何公开 API 把文字放上任务栏,而是直接抓住 Explorer 的窗口树。见 src/widget.cpp:

g_taskbar = FindWindowW(L"Shell_TrayWnd", nullptr);
if (!g_taskbar || !FindWindowExW(g_taskbar, nullptr, L"TrayNotifyWnd", nullptr)) { g_taskbar = nullptr; return false; }

拿到 Shell_TrayWnd 后,创建一个 WS_EX_LAYERED 的子窗口,用 UpdateLayeredWindow 自绘图标和数字,然后每帧计算位置,插到通知区域左边。这中间有两个时代差异被显式处理:

  • Windows 11 的任务栏是 XAML island,探针是 Windows.UI.Composition.DesktopWindowContentBridge;
  • Windows 10 的任务按钮在 ReBarWindow32 里,必须主动 MoveWindow 把它压窄,否则按钮会滑到挂件底下,而且“Explorer 自己会在布局时把它重新展开”,所以要反复压。

再往下还有一层降级:竖排任务栏直接放弃挂件,改用托盘图标;Explorer 重启则靠 RegisterWindowMessageW(L"TaskbarCreated") 重来一遍;每秒钟 Reconcile() 一次,用 widget::Alive() 确认挂件是否已经被系统悄悄扔掉;连“没人有电量”这种状态都有专门的占位图标,保证用户总有点东西可点。

这套代码很聪明,也很脆弱。任何一次任务栏重写(Windows 10 到 11 已经来过一次)都会让 FindWindowExW 的返回值变成 nullptr。作者的应对不是“保证支持”,而是保证失败时体面:挂件创建失败就回退托盘图标,托盘图标不可用就退到占位符。这类项目能活多久,几乎等于它的降级路径有多少层。

采集侧的问题是同构的,只是更隐蔽。

Xbox 手柄走 Windows.Gaming.Input 能拿到真实毫瓦时,算出真实百分比;但 XInput 的 XINPUT_BATTERY_INFORMATION 只有 Empty / Low / Medium / Full 四档。见 src/drivers/xinput.cpp:

case BATTERY_LEVEL_EMPTY:  s.percent = 5;   s.levelText = L"Empty";  break;
case BATTERY_LEVEL_LOW:    s.percent = 25;  s.levelText = L"Low";    break;
case BATTERY_LEVEL_MEDIUM: s.percent = 60;  s.levelText = L"Medium"; break;
default:                   s.percent = 100; s.levelText = L"Full";   break;

这里的 5/25/60/100 是排序用的伪值,界面上优先显示 levelText(“Low”)而不是“25%”。这是个值得所有同类项目抄的细节:粗粒度数据不要伪装成精确数据。反过来做,用户第一次发现“显示 25% 但其实还有一半电”时,信任就没了,而小工具的信任只有一次。

蓝牙那一侧同样在跟不承诺稳定的实现打交道。src/drivers/generic.cpp 里硬编码了电池属性的 DEVPROPKEY,还得处理一个反直觉的现象:耳机跑 A2DP 音频时,承载电量的 Hands-Free 服务节点会被读成“未连接”,所以不能信服务节点自己的 connected 标志,必须用 ContainerId 归并到主设备节点再判断。注释写得很直白:“prefer a live node”。

系统大版本更新不会发通知告诉你有哪个私有属性改了语义。它只会让用户的电量变成灰色问号。

死法三:作者先退场,热度自然蒸发

第三类死法不需要技术原因。

看这个仓库的“维护姿态”,会发现它更像一份留给未来的说明书,而不是一个正在燃烧的项目:

  • .gitignore 里躺着 .claude/ 和 CLAUDE.md;
  • .github/workflows/pr-safety.yml 专门检查提交信息里有没有 Co-authored-by: Claude / Copilot / ChatGPT / Cursor ...,有就失败,理由是“合并后会把 AI 列成仓库贡献者”;
  • PR 模板的 checklist 逐条要求“只发送只读查询”“不新增 src/、docs/、README.md 之外的文件”“不含二进制”“AI 辅助的提交要去掉 co-author 行”。

这些痕迹说明两件事:维护工作量已经需要工具来分担;而作者很清楚自己随时可能不在。于是他把“不在”之后的规则写成了 CI。

这套护栏本身值得单独看,因为它恰好回答了“作者退场后项目靠什么不死”:

  • 工作流默认 permissions: contents: read,PR 的构建无权改仓库、无权发版本;
  • 所有 action 按 commit SHA 固定(注释写明“a moved tag cannot swap in different code”);
  • 发布任务单独拆出,只在维护者推 v* tag 时触发;
  • PR 安全检查用 pull_request_target 跑主分支上的脚本,只把 diff 当文本下载,从不 checkout、构建或运行 PR 代码;
  • scripts/pr-safety.sh 是一份“这个应用绝不该出现的东西”的清单:网络访问(WinHttp、WSAStartup、URL)、启动别的进程(CreateProcess、ShellExecute)、读键盘/剪贴板/屏幕(SetWindowsHookEx、GetAsyncKeyState、BitBlt)、注册表启动项、超长 base64 或大段字节数组(“possible hidden payload”)。

脚本开头自己承认:“This is a tripwire, not a guarantee.” 这句话很关键——它没打算替代人,只打算在人不在了的时候,让越界的那一行必须被解释。

活下来的少数共性

把上面三条死法反过来读,就是这个项目实际做对的事。它们不新鲜,但很难同时做到。

范围极小。 纯 C++17 + Win32,无第三方依赖,Makefile 只有 30 行,链接 hid、setupapi、cfgmgr32、ole32、comctl32、gdi32、runtimeobject。没有服务、没有驱动、没有运行时,安装不需要管理员权限。唯一的外部程序是可选捆绑的 headsetcontrol.exe,而且“没有它只是少支持一些耳机”。整个 src/ 加 tests/ 约 5100 行,这是一个人能读完全部代码的规模。

范围是按协议划的,不是按型号划的。 Logitech 驱动靠 HID++ 的 feature discovery 找 0x1004 / 0x1000 / 0x1001 / 0x1F20,所以不需要维护一张逐型号的表。Rapoo 驱动不靠型号白名单,而是靠 VID + 专用 collection + 报文长度 + 合法状态字节来判断,文档里的表述很克制:“这是共享协议的证据,不是 69 台硬件的验证”。这个区分非常重要:宣称协议覆盖,而不是宣称型号覆盖,才不会在下一批换壳产品出现时全线崩。

维护极轻,因为贡献路径被设计成一次性数据采集。 想加设备?先跑两条命令:

WirelessBattery.exe --dump    # 打印每个 HID collection 的用法页、报文长度
WirelessBattery.exe --list    # 打印当前识别到的设备和电量

--dump 的输出格式就是一张表(VID:PID IF UsagePg:Usage In Out Feat Product),用户填进 issue,作者对着表判断协议。再加上“厂商软件 + Wireshark + USBPcap 抓包”这条路,贡献漏斗从“你帮我写驱动”降到“你给我一段抓包”。这是小项目唯一可持续的扩张方式。

测试只覆盖最贵的那一块。 make test 只跑两个测试:一个可移植的 Rapoo 报文解码测试(里面直接放了真机抓到的 07 20 03 20 03 20 03 01 19 00 04 84 00 17 46 00 02 03 BC),一个带模拟 HID 响应的驱动测试,覆盖 0%、100%、充电、缺字段、截断帧、错误 VID、超时、键稳定性、有线/接收器去重。不去追求覆盖率,只保护“猜错就会发出错误报文”的地方。

承认不知道。 README 有一节叫 Limitations,逐条列出不支持的东西:MSI 无线鼠标键盘、Razer Kraken / Barracuda、HyperX Pulsefire、Xbox 无线耳机(走 Xbox adapter 时),理由是“电池协议没有公开文档”;Keychron 键盘只在蓝牙下报电量,2.4G 接收器固件不暴露。Rapoo 文档更狠,明确写出 CH584 的 08 报文不支持、办公 MT/M 系列不支持,并留下一句“Do not send guessed queries”。

用数据模型吸收厂商差异。 所有厂商最终都塌缩成一个 DeviceStatus(src/devices.h):percent 可以是 -1,levelText 承接粗粒度档位,charging、asleep、connected、millivolts 各自独立,graceSec 决定设备不应答后旧值还能撑多久。正因为有这个模型,Logitech 接收器把休眠设备踢出链路时,界面还能把最后读数压暗显示 30 分钟——用户看到的是“93%(睡着)”,而不是“设备消失”。

人群极明确。 目标用户就一句话:装了 G HUB、Synapse、iCUE 但又不想开着它们的人。所以产品边界是“只读”:不改灯光、不改 DPI、不升固件、不进设置。这条边界既是产品定位,也是安全模型——CONTRIBUTING.md 的驱动规矩第一条就是 read-only,PR 检查清单第一条也是 read-only。一个不写设备的小工具,永远不会有“把用户鼠标刷成砖”的事故,也就不会有那种一夜之间口碑归零的死法。

给下一个“三天项目”的五个问题

如果准备写一个类似的桌面小工具,在动手前先回答这五个问题,能提前看出自己会死在哪一条:

  1. 你的数据来源里,有多少是别人不承诺稳定的私有实现? 如果答案是“大部分”,那就先把降级路径设计出来:挂件失败用托盘,托盘失败用占位符,采集失败保留旧值并压暗。
  2. 新增一台硬件的边际成本是多少行? 如果是 500 行加一份逆向文档,那你的路线必须是“按协议收编”,而不是“按型号堆表”。
  3. 你能用几个字段描述所有厂商? 这个项目用了 8 个。字段越少,驱动越好写,界面越好维护。
  4. 你写下“不支持什么”了吗? 没有 Limitations 一节的兼容列表,等于承诺了无限责任。
  5. 如果作者明天消失,CI 还能拦住什么? 只读权限、按 SHA 固定的 action、独立发布任务、把 diff 当文本扫的安全检查——这些不是洁癖,是留给接手者的说明书。

桌面小工具的死法其实只有一种:把“能用”当成“能活下去”。三天的热度来自“终于有人做了”,之后的每一年都来自“它还没坏”。这个仓库给出的答案并不浪漫——24 个驱动、一堆按顺序排列的注释、一条“每秒确认挂件还活着”的定时器、一份写着“不支持”的清单——但它至少把三天之后的日子,认真地算过一遍。

登录后查看全文
Wireless-Device-Battery-Monitor