LogiBoardToolBox
沿用 .NET 10、WinUI 3、CommunityToolkit.Mvvm 与 XFEExtension 架构的罗技鼠标配置工具。现已加入 GPW、PRO X SUPERLIGHT、G304/G305、G502 HERO/LIGHTSPEED、G403/G703/G903 等 14 个型号的识别、G HUB 宏槽位和设备图适配。板载布局与可用功能以连接设备实际返回的能力为准；实机写入与宏输出目前在 G502 X PLUS / 046D:C547 上验证。具体型号与验证范围见 多型号支持。
设备界面依据用户截图和本机 G HUB 页面、资源与交互逻辑重做，新增板载自动读写。基础板载宏已通过物理按键实测；目前仍未达到 G HUB 全功能、全界面完全一致，断电保持尚未实测。
当前实现
- 使用鼠标自身的 USB/WPID 型号信息识别设备，不把通用接收器 PID 当作鼠标型号。按型号更新分配项、G HUB 槽位前缀和设备图；切换设备前完成旧设备的自动保存，并隔离草稿。
- 标准板载格式 1–5 共用格式 1 宏写入与恢复流程；格式 10 继续限定已识别的几何布局。G HUB 导入保留每个录制延迟；拒绝超出真实按键数量或不存在的 G-Shift 层。
- LIGHTSYNC 根据实际接口使用旧版 0x8070 灯区或 0x8071/0x8081；编辑器、屏幕采样和动画帧支持可变灯区数量。SUPERLIGHT、G304/G305 隐藏 RGB 入口，G502 X PLUS 的八区映射保持不变。
- 黑色设备画布、真实 G502 X PLUS 正面/侧面图、按键连线、视图切换、默认/G-SHIFT 两层。
- 命令、按键、操作、宏、系统五类分配，搜索、点位菜单、拖放分配；点击宏进入编辑器。
- 宏的命名 → 四种类型 → 编辑 → 保存流程。点击、按住、松开三条时间线支持录制、编辑、插入、删除与拖动步骤。
- 软件宏执行器支持不重复、按住重复、触发、完整序列；取消、断连、关闭时释放所持按键。键盘、鼠标、媒体、滚轮和位移均有输入实现。
- LIGHTSYNC 预设、自定义八灯区；独立动画编辑器包含本机 G HUB 的三款鼠标预设、十种过渡曲线、循环/反向循环/弹跳/随机、帧时长、复制/插入/删除/排序、预览/定位/缩放和本地保存/取消。
- 屏幕分区采样与 WASAPI 系统输出音频响应；软件灯效使用 RAM 帧，不冒充已存入板载。
- 五档 DPI、独立 X/Y、默认/DPI Shift、灵敏度预设、本地自定义预设、有线/无线回报率；当前设备读到 100–44000 DPI、125/250/500/1000 Hz。
- 真实电量与固件读取、五个板载储存位、完整备份/恢复、写前检查、写后读回和失败恢复。
- LIGHTFORCE 混合/仅光学模式与启动效果开关，已实际切换、读回并恢复。HERO 校准包含介绍、源鼠标/DPI、物理测量、结果/错误和重试流程；已确认板载模式需先切换软件配置，软件模式实际读到 400×400 DPI 校准基准。完整双鼠标测量与成功保存尚未实测。
- 格式 10 的已识别字段可实验性写入；选择板载配置后启用自动保存，未知字节保持原样。相同宏复用已有偶数入口；早期版本产生的奇数入口在重新导入时迁移到新宏空间，旧扇区保留。
使用
打开设备后自动扫描并读取。多只鼠标可在设备设置中的“设备诊断与软件配置”选择；切换前完成旧设备自动保存，再读取新设备。右上角选择“桌面: 默认”编辑软件配置，选择实际提供的“板载配置”后直接编辑相应板载槽。DPI X/Y、闲置秒数、配置名称和颜色文本在输入时仅保留草稿，按 Enter 或离开输入框后才校验并提交；Esc 撤销草稿。无效数值保留上次有效设置，不进入保存队列。已确认的有效修改在约 200ms 内合并后自动保存，无需再点写入；事务串行执行，每次自动备份、检查旧数据并逐扇区读回。正在执行的闪存事务不会被后续手势取消。失败会显示错误并保留编辑内容；仍有保存失败时不会直接关闭窗口。
宏库、软件配置、自定义灵敏度预设和自动备份位于 %LOCALAPPDATA%\LogiBoardToolBox\Onboard。项目、程序集及可执行文件统一更名为 LogiBoardToolBox；首次使用更名版本时会复制旧 LogiBordToolBox\Onboard 数据目录，保留原目录且不覆盖已有新宏库，即使配置框架已提前创建新产品目录也能迁移。旧版本生成的板载备份仍可读取和恢复。软件宏需从宏编辑器的“板载与执行”启动；LIGHTSYNC 页面用户进入时可接管软件灯效，停止或关闭会恢复控制。
完整独立按住循环序列、自由灯区及动画的 EEPROM 播放布局尚未验证；这些功能不会被静默转换成其他板载效果。屏幕、音频联动仍需要电脑。HERO 成功校准、触发循环及其他高级宏的物理执行、应用自动切换、G HUB 集成/社区仍有未完成或未确认项，不能视为 G HUB 全功能替代。
构建与验证
更名后的 Release x64 版本构建无警告、无错误，93 项测试全部通过，包含旧数据目录迁移、框架预创建目录和旧备份格式的兼容性检查。发布可执行文件：
dotnet publish LogiBoardToolBox/LogiBoardToolBox -c Release -p:Platform=x64 -o artifacts/LogiBoardToolBox
.\artifacts\LogiBoardToolBox\LogiBoardToolBox.exe
2026-10-25 多型号验证：Release x64 构建及诊断工具构建均无警告、无错误，90 项测试、40 项 WinUI 检查通过。分场景视觉验收汇总在 work/visual/multi-device/acceptance-summary.json；新型号硬件输出和本轮未覆盖的 G502 侧视图仍单列为尚未确认。离线 WinUI 验收使用 --catalog-verify，截图包含 14 个型号与 GPW 的宏、DPI、灯效和两区动画；截图中的设备快照为模拟数据，不代表新型号已经实机验证。当前 G502 X PLUS 的只读核对仍与取消刀成功后的 19 个板载扇区完全一致。逐项证据见 work/visual/multi-device。
dotnet build LogiBoardToolBox.slnx -c Release -p:Platform=x64
dotnet run --project LogiBoardToolBox/LogiBoardToolBox.Test -c Release -- --language zh --artifacts work/visual/tests
dotnet run --project tools/LogiBoardToolBox.Diagnostics -- --backup work/visual/device-backup.json
默认诊断只读；单元测试使用内存设备，不访问物理鼠标。WinUI 的 --ui-verify <目录> 使用应用自身 RenderTargetBitmap 取图、导出可见控件文字与位置，并以独立设置目录调用真实控件校验保存/取消流程；测试窗口不激活，不模拟全局输入。显式加 --write-verify 才执行自动板载保存实测并恢复原始快照。
2026-10-23 本机校验：Release x64 构建 0 警告、0 错误，83 项测试通过。后台流程校验覆盖宏的命名/类型/实际保存/取消、动画的编辑/保存/重载、HERO 的实际软件模式能力、屏幕采样、音频回环和板载即时写入。完整交互、视觉差异与尚未确认项分别记录，截图成功不等于整体视觉达标。
真实板载连点：临时绑定记录 5（G HUB 的 G6，前进侧键），按一次输出 5 次左键点击；接收器 Raw Input 捕获 5 次按下和 5 次抬起，按下间隔平均 101.997ms，原生钩子也捕获到相应事件，注入事件为 0；测试进程没有软件宏引擎。结束后 19 个扇区、模式、活动配置均与备份一致。自动保存验证另行修改双轴 DPI、双连接回报率、名称、灯效、宏绑定并独立读回，随后完整恢复。没有据此声称已验证断电保持或所有循环模式。
G HUB 导入的侧键映射已纠正：G5 → 记录 4（重塑取消刀），G6 → 记录 5（左键连点），界面编号和侧视图标记采用相同顺序。实机只交换两条绑定和 CRC，保留 10800 DPI、灯效及全部宏字节；取消刀的 59/198/25/10ms 录制延迟原样保留。按住左键连点的实测捕获到接收器的 56 次按下和 56 次抬起，软件注入事件为 0。
2026-10-24：取消刀已恢复，并通过实体按键实测。 用户明确同意拔插对照后，程序被动观察同一配置：拔插接收器前没有收到键盘事件；重新插入后捕获 C547 键盘集合的 16 个事件，组成 4 组完整的反斜杠按下/松开、数字 1 按下/松开，用户确认“已完成，取消刀正确”。本轮没有软件输入注入、输入拦截、板载写入或模式切换；数字 1 校准钩子仅观察并透传。19 个扇区、模式和活动槽均与对照前一致，双轴仍为 10800 DPI，有线/无线仍为 1000 Hz。取消刀的 59/198/25/10ms 录制延迟字节完全保留，实际采集的各段延迟均在录制值 ±5ms 内。证据在 恢复验收记录 和 resume-20261024/replug-comparison。
此次故障定位在 Windows 接收器键盘读取路径：恢复前，匹配微软驱动符号的 HIDCLASS 跟踪显示，17 字节键盘报告已经到达集合 1，但完成读取 IRP 数为 0，键盘集合持续 NumPendingReads=0；同接口的媒体集合正常完成读取。重新连接使设备重新枚举，随后原生键盘输出恢复。最初导致读取循环停止的触发原因仍未确定，没有证据认定某个其他程序导致故障。work/ghub-binding-fix/driver-read-path-summary.json 保留恢复前的历史跟踪，keyboard-output-failure-summary.json 汇总当前恢复结果与历史对照。
此前已经修复的协议与存储差异继续保留：板载切换/保存及软件会话最后退出前关闭 0x8110/2 按键监听；Shift 使用 G HUB 原生 43 02 E1 / 44 02 E1；宏分配遵循终止符后的两字节对齐。取消刀位于扇区 8 偏移 0，左键连点位于同扇区偏移 26，G5/G6 绑定顺序正确。单独应用这些修正时，用户仍反馈取消刀无效，因此没有把这些修正当作此次恢复的直接原因。原始宏扇区保留，所有临时对照均已恢复。历史证据在 native-reference-audit.json、aligned-entry-repair、receiver-keyboard-path 等目录中。
--audit-receiver <目录> 只读导出设备功能表、固件和接收器寄存器，不设置通知标志、不配对、不切模式、不生成输入；本机读到接收器 4.2.9，检查前后扇区、模式和活动槽一致。
--reload-onboard-runtime <目录> 是仅针对上述已核对设备的一次性恢复命令：先备份，最多等待 60 秒，连续输入空闲至少 5 秒且鼠标常规按键均松开才允许重载；输入恢复或配置变化则跳过。它仅短暂重建主机/板载运行状态，强制返回原板载槽，核对闪存和性能，不调用宏执行函数、不写入闪存。不得把运行状态恢复成功当作宏执行成功。
--replug-keyboard-comparison <目录> 是需用户明确配合的 90 秒拔插对照：释放 HID++ 句柄后，仅观察目标接收器 Raw Input、设备到达/移除及透传的数字 1 校准，结束后重新读取配置验证一致性。命令不会写入、触发宏、切换前台或拦截输入。
管理员诊断工具 Receiver-RepairHost.ps1 使用进程和本地任务队列；曾验证同一进程内的请求复用和子任务错误隔离，但该进程在 2026-10-24 恢复工作前已经退出，未实现跨轮持续可用，不能把启动元数据当作当前存活证据。此次恢复没有再次申请 UAC。此前单个键盘子设备重启返回 Windows 3010（需要重启系统），没有执行系统重启；键盘/媒体 USB 接口恢复脚本始终仅做预检，未执行接口重启。
本地验收产物（不随源码分发）：动画编辑器、功能运行记录、连点物理事件、自动保存读回、逐项验收结果。参考与本软件包含不同的宏库、活动档位和灯效状态，差异图没有据此计算“还原百分比”。整体尚未通过“与 G HUB 完全一致”。
资料与素材
应用内的设备图和字体来自本机已安装 G HUB，仅用于用户要求的本地界面还原；它们不属于本项目自行创作或开源许可的资产。发布或重新分发前需要单独核实对应使用权。