Home

PeriTray 项目 WIKI

本项目原名为 PeriphMonitor，现更名为 PeriTray。

面向开发者（本人/协作者）的完整知识库：架构设计、模块详解、踩坑复盘、架构纪律与验收方法论、工程化设施与开发指南。 用户视角的功能介绍见仓库根目录 README，开发约定见 AGENTS.md。

快速导航

页面	内容	适合场景
01-项目概览	定位、功能全景、技术栈选型理由、版本演进史、分支策略	新人了解项目全貌
02-架构总览	三层架构、启动流程时序、数据流、线程模型、全局状态	改动前建立整体认知
03-Rust后端模块	20 个模块逐一详解（职责/关键实现/互相关系）	后端开发
04-前端架构	双页体系、加载序约定、common.js 公共层、CSS 令牌体系	前端开发
05-命令与事件参考	全部 invoke 命令 + 后端广播事件的速查表	查参数/查语义
11-支持设备列表	「2.4G 设备电量」收录的雷蛇设备全清单（76 个 VID:PID，含形态与验证状态）	查兼容性 / 贡献驱动
F99-Pro-排障过程	单台 AULA F99 Pro 的电量读取排查流水（单机过程，非常设章节）	复现同类 2.4G 读数问题时参考
06-踩坑复盘·假死 ⭐	两类假死的完整定罪过程、看门狗自愈机制设计、三层防线	动窗口/事件循环/WebView 相关代码前必读
07-踩坑复盘·高频回归 ⭐	材质恒透明架构、托盘坐标缩放、弹窗 Z 序不变式、硬件固件对抗等 9 个反复修的问题域	新设备接入前 / 音频属性 / 响度均衡（未结，§12）
12-代码审查与整改复盘	2026-09 审查的结论归档：41 条发现的最终处置、批次与提交、15 条计划外发现、未决项决策、明确不做	想知道「某条为什么这么改 / 为什么没改」
15-任务栏内嵌与自绘 ⭐	设备状态窗嵌入任务栏内部：四路取舍结论、分层子窗口「可见四条件」、supportedOS、Z 序与命中测试、两条 DPI 口径、任务栏专属验收方法论、已退役的两代避让方案	动 taskbar_widget.rs 前必读
16-物理设备身份 ⭐	ContainerId 三级降级链、容器 GUID 版本位 = 派生方式、占位容器黑名单、BaseContainers 反向索引、hidapi 路径映射、CM_Get_Device_ID_ListW 的三种静默失败、2.4G 电量分域	动设备去重 / 2.4G 电量 / 身份键前必读
13-架构决策与纪律 ⭐	15 条架构纪律，每条 = 为什么 + 反例 + 判据（持锁区纯内存、锁序白名单、RAII 守卫、失败路径回滚、事件回调线程、配置写入语义…）	动锁 / 线程 / 事件 / 配置前必读
14-工程实践与验收方法论	可证伪判据、验证三分法、回归闸门≠验收闸门、注入式验证与确定性压力探针、五层判据、避坑清单 30 条	写验收 / 做修复类改动前必读
08-工程化与工具链	check.mjs 九类校验、pre-commit 闸门、clippy、CI/CD、发版流程	提交/发版
09-开发指南	本地运行、调试手段、常见任务 how-to、已否决路线	日常开发
Wiki-维护规范	职责边界、维护时机矩阵（何时必须更）、操作流程与模板	更新 WIKI 前必读

一分钟项目画像

PeriTray 是一款 Windows 系统托盘外设监控工具：WMI + WinRT 蓝牙 + PnP 枚举实时检测音频/USB/蓝牙/电池/显示器设备，提供音量控制（设备级/应用会话级/空间音效）、蓝牙连接管理、全局快捷键。界面为 WinUI 风格的 popup（弹出面板）+ settings（设置页）双页体系。

技术形态：

• Tauri v2（Rust 后端 ~10700 行，20 个模块）+ 纯 HTML/CSS/JS 前端（~7000 行，无构建流程，cargo build 时嵌入二进制）
• 大量 Win32/COM 直接互操作：DWM 材质、WebView2 生命周期、未公开的 Core Audio 策略接口
• 工程闸门：pre-commit 九类校验 + Rust fmt/check 零警告 + clippy（带一份存量基线，条数以 tools/check-clippy.mjs 为准）+ CI 复跑全套

三条最重要的历史教训（详见踩坑篇）

1. Tauri 主事件循环是单点——任何在事件线程上执行的同步重操作（Win32 调用、COM 销毁链）挂起都会导致全局假死。铁律：事件回调只做分发，重操作一律 spawn 移出。
2. 窗口透明能力在创建瞬间固化进 HWND——事后 SetDefaultBackgroundColor 无法补救，必须"恒透明出生"，观感差异由 CSS 承担。
3. 软件层无法稳定赢过硬件固件的状态同步——部分音频设备的 HID 代理会回写标量/静音状态，对抗方案必然失败，应引导用户使用显式的强制静音路径。