squeak

在 Linux 上配置 Keychron 鼠标 —— DPI、回报率、传感器、按键、宏， 以及配置文件 —— 通过原生 raw HID 实现，复刻了网页版 Launcher 的功能。每一次写入都会被读取 并进行校验。 两个前端共享同一个经过验证的核心（`squeak-core`）： | | | |---|---| | **[`squeak`](crates/squeak-tui/README.md)** (终端 UI) | ratatui，支持 SSH，体积小巧，无需 GUI | | **[`squeak-desktop`](crates/squeak-desktop/README.md)** (桌面应用) | Tauri + WebKit，图形化窗口 | 首要适配目标：**Keychron M6 8K / Ultra-Link 8K 接收器**（`8k_nordic`， VID `0x3434`），已通过有线 + 2.4 GHz 连接进行实时验证。插拔状态会被自动检测 （基于 netlink uevents —— 无需设备轮询）。 桌面应用： 终端 UI： ## 安装 一键从源码构建并安装 udev 规则（需要 `cargo`；桌面 版本还需要 `webkit2gtk-4.1`）： ``` curl -fsSL https://raw.githubusercontent.com/Stoica-Mihai/squeak/main/install.sh | bash # desktop app 替代（或配合） TUI： curl -fsSL https://raw.githubusercontent.com/Stoica-Mihai/squeak/main/install.sh | SQUEAK_TARGET=desktop bash # SQUEAK_TARGET = tui (default) | desktop | both ``` 或者手动进行安装 —— 请参阅下方各个前端的 README。 卸载： ``` curl -fsSL https://raw.githubusercontent.com/Stoica-Mihai/squeak/main/uninstall.sh | bash # 保留 udev rule：... | KEEP_UDEV=1 bash ``` ## 目录结构 ``` crates/ squeak-core/ proto · hid · worker — shared, frontend-agnostic squeak-tui/ ratatui terminal UI → crates/squeak-tui/README.md squeak-desktop/ Tauri desktop app → crates/squeak-desktop/README.md ``` 选择一个前端的 README 以了解安装与使用方法。下方的其余内容为通用信息。 ## 权限 hidraw 需要访问权限（浏览器版 Launcher 同样需要此权限）。仓库中自带了 位于 [`packaging/99-keychron.rules`](packaging/99-keychron.rules) 的规则文件： ``` sudo curl -o /etc/udev/rules.d/99-keychron.rules \ https://raw.githubusercontent.com/Stoica-Mihai/squeak/main/packaging/99-keychron.rules sudo udevadm control --reload-rules && sudo udevadm trigger --action=add # 重新插入设备 ``` 该规则针对 M6 的产品 ID 进行了限制，并为它们添加了 `uaccess` 标签，从而自动为 当前活动的桌面登录用户授权： ``` SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3434", ATTRS{idProduct}=="d028", MODE="0660", GROUP="input", TAG+="uaccess" SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3434", ATTRS{idProduct}=="d049", MODE="0660", GROUP="input", TAG+="uaccess" ``` 在普通的桌面会话中，这就足够了。无头环境/SSH（即 `uaccess` 不生效的场景）下，会退回到 `input` 用户组 —— 执行 `sudo usermod -aG input $USER` 并重新登录即可。 ## 功能 DPI 预设 + **当前阶段切换** · 回报率 · 传感器（LOD、滚轮方向、 运动同步、可设置角度的角度平滑、波纹效应、采样模式） · 消抖 · 休眠 · 按键重映射（鼠标 / 多媒体 / 禁用 / 默认）并带有 **左键锁定** 功能 · 宏（点击序列 + 文本，通过 `0x71` 自动分块） · 配置文件切换 · 恢复出厂设置。 稳定性：每一次写入都会经过读取校验；遇到传输 错误时会重连并重试；当接收器和有线连接同时接入时，会自动探测当前活跃的连接方式；支持热插拔 自动刷新。 M6 不支持手势 / 长按 / 组合键（其能力标志位中 并未提供这些支持）。 ## 协议与参考 HID 协议是通过逆向工程 Keychron Launcher (WebHID) 以及 usbmon 抓包数据得出的。针对各设备的映射表位于 [`docs/`](docs/) — [`docs/8k-nordic.md`](docs/8k-nordic.md) 是经过验证的设备。 [`FINDINGS.md`](FINDINGS.md) 是逆向工程日志；[`capture.py`](capture.py) 是 usbmon 解码器（`RAW=1` 会记录所有的 report id）；归档的 Launcher JS bundle 位于 [`docs/launcher/`](docs/launcher/)。[`PLAN.md`](PLAN.md) 是开发计划。 ## 状态 8k_nordic 已经过实时验证（DPI、回报率、传感器、按键、宏、配置文件 切换 —— 所有操作均通过读取确认无误），支持有线和 Ultra-Link 8K 接收器两种连接方式。其他 Keychron 变体（1k / 4k / 8k）虽已根据 Launcher 的 JS 文件进行了文档化，但尚未经过验证。

标签：HID, Rust, Tauri, TUI, 可视化界面, 网络流量审计, 通知系统, 鼠标配置工具