G502 X PLUS：G HUB 功能与交互基准

2026-10-23，通过用户截图和本机已安装 G HUB 的页面资源、中文文案、设备定义核对。先通过本机资源核对，再通过 UI Automation 导航和 PrintWindow 取得设备分配、灵敏度、LIGHTSYNC、宏命名/类型/序列编辑、设备设置页。用户新增后台验收偏好后，不再还原或操作 G HUB 窗口；后续使用已有参考图与新应用自身后台渲染。

产品目标

沿用现有 WinUI 3、MVVM、导航、设置和日志架构。设备配置流程与 G HUB 对齐，在此基础上新增直接板载写入。协议参数、十六进制数值和脚本文本不能成为普通设置的必经步骤。

已核对的来源

C:\Program Files\LGHUB\resources\app.asar：当前安装版的页面组件与状态结构。
C:\ProgramData\LGHUB\depots\876190\core\data\strings\common\zh-CN.yaml：功能分类、宏类型、宏序列分段、录制、标准延迟、DPI、LIGHTSYNC、板载设置的文案。
设备资源 8807090d-3e9c-4dfe-a6a6-a863d7b688d4 与 97b085d9-0fde-406b-8bcd-b244746387e7 的 manifest.json、metadata.json、defaults_override.json、light_map.json：G502 X PLUS 视图、按键位置、默认设置、X/Y DPI、8 个灯区。
用户提供的“按键分配 / 宏”截图。

页面 JS/CSS 仅在被忽略的 artifacts/ghub-reference 中供核对，没有复制为应用实现。设备图和字体已用于用户要求的本地还原，详见 ASSET-PROVENANCE.md。

功能与交互

区域	G HUB 行为	本项目对应要求
设备页	型号、配置选择、设备设置入口	保留设备中心；板载槽作为配置目的地
按键分配	命令、按键、操作、宏、系统五个分类；搜索；拖至鼠标点位	分类和鼠标点选为主要操作，隐藏底层编码
设备视图	正面、侧面；点位与功能标签相连	两个视图共用同一组真实绑定
G-Shift	默认层与 G-Shift 层切换	独立编辑和保存，不能清空另一层
鼠标操作	左右中键、前后退、横滚、DPI、配置循环等	可选的人类可读命令，不能要求手输枚举
系统	媒体、编辑、鼠标、软件控制、启动应用	区分固件可执行动作和需要主机的动作
宏	不重复、按住时重复、触发、序列	四种模式；序列为点击、按住、松开三个片段
宏编辑	录制、开始/停止、标准延迟、按下/释放、插入延迟、文本、系统/程序动作	可视化步骤编辑，文本脚本仅作高级入口
灵敏度	预设、五档 DPI、活动/默认/Shift、X/Y 分离、有线/无线回报率	保留这些概念，逐项映射到设备能力
LIGHTSYNC	预设、自由、动画；颜色、速度、亮度；8 个灯区	支持区分设备端效果、软件动态效果和动画
设备设置	板载模式、配置槽、固件、电量、电源管理、灯光设置	板载模式仍可编辑，增加备份、恢复和写入校验

需要纠正的初版设计

普通用户不应通过 special 参数、HID 键码或脚本给鼠标分配常用操作。
配置页不能用一组协议表单替代 G HUB 的设备点位、分类库和宏编辑流程。
主机模式和板载模式需要共用用户可理解的配置模型；不能把软件模式的所有能力直接当作固件能力。
“序列宏”和启动应用、软件集成、屏幕取色、音频响应等依赖主机的功能，必须有相应的软件执行实现；不能将它们显示为已支持的板载功能。
未经该型号实测的写入不能标注为完整适配或已验证。

已读取的实际设备

G502 X PLUS 经 LIGHTSPEED 接收器 046D:C547，HID++ 地址 01，描述字节为 01 0A 01 05 02 0B 10 00 FF 0A 04。

配置格式 10、宏格式 1、5 个配置槽、11 个物理按键、16 × 255 字节。
普通按键表从 0x20 起，G-Shift 表从 0x60 起，名称区从 0xA0 起。
当前用户配置 CRC 校验通过；读取时为主机模式，活动板载地址为 0。
旧格式中的回报间隔字节为 FF，不能解释成 255 ms 或自动显示为 1000 Hz。
0x56..0x5F 出现第二组 DPI 数据，应保留，不能当作普通按键记录覆盖。
已执行基础单次连点宏和固件预设灯效的实机写入/读回；G5 物理触发 5 次点击，平均间隔 101.997ms；已恢复原始 19 扇区及模式/活动配置。断电保持、按住/触发循环、完整序列仍未完成物理实测。

本轮交互核对与实测边界

继续只读分析本机已提取的页面组件、样式、中文文案与动画数据，没有使用电脑技能，也没有重新激活 G HUB。下列 G HUB 操作逻辑来自本机资源；新软件的控件路径使用程序调用 WinUI 控件和状态转换验证，不能将其等同于对当前 G HUB 的完整运行交互测试。

宏：名称输入并按 Enter → 选择四种类型 → 编辑事件 → 保存；取消创建移除临时条目，取消编辑恢复原内容。实际保存按钮通过自动化控件接口调用，并读回独立宏库文件。
动画：内置动画编辑生成副本；选帧、单灯区着色、过渡曲线、帧时长、插入/复制/删除/重排、预览/定位、缩放、方向与默认速度；保存写入动画库，取消恢复进入前的快照。指针拖放没有被全局输入模拟，重排验证使用与拖放处理器相同的方法。
HERO：介绍 → 源鼠标/DPI → 同时移动约 10 英寸 → 传感器完成/失败 → 详情/命名。G HUB 在板载模式禁用该入口。本机 0x2202 能力为 0x0D：板载模式函数 8 返回 0x05，切到实际软件模式后正常读到宽 60、长 125、400×400 DPI。现已按模式控制入口，并在切换配置后刷新能力；此前将该错误归为固件故障的判断已纠正。双鼠标成功测量/保存尚未物理实测。
LIGHTFORCE：0x8090 状态位 0，混合/仅光学为设备级设置，按四字节掩码更新并保留其他位。已切换两种值并读回、恢复。
启动效果：0x8071 非易失配置，保留六个不透明参数；已开/关切换并读回、恢复。
板载配置：选择板载槽即启用自动保存；有效编辑合并 200ms 手势后写入，备份、串行、读回一致后显示已保存。切换配置前等待未完成事务；不将软件草稿覆盖到同编号的板载槽。

对应证据在 work/visual/advanced-build/。HERO 成功测量与保存、自定义动画 EEPROM 播放、G HUB 云端/游戏集成以及真实指针拖放和录制全流程仍不能标记为全部验证。

视觉核验

最终验收需求冻结于 work/visual/requirements.json。应用以原尺寸导出 RenderTargetBitmap 与可见控件布局；使用 background-visual-check 的原图、原比例分块、局部放大、OCR、同尺寸并排和差异图核对，并逐项记录 pass/fail/uncertain。测试通过不等于全部视觉达标。