架构 – OpenLogi Docs

OpenLogi 各组成部分总览——GUI、代理、CLI、HID++ crate 与资源托管。

OpenLogi 由后台代理加按需 GUI 组成。代理独占所有设备通道与系统输入钩子；GUI 只是纯粹的 IPC 客户端，代理未运行时会将其拉起；CLI 则直接与硬件通信，用于清单与诊断。

组成部分

OpenLogi 代理（openlogi-agent）—— 后台进程：HID++ 设备 I/O、输入钩子、捕获会话、前台应用监视、菜单栏 / 托盘项、配对，以及 Actions Ring 浮层辅助进程。
OpenLogi GUI（openlogi-gui）—— GPUI 桌面应用：设备轮播、鼠标示意图、键盘模型、动作选择器与设置窗口。它本身不持有任何设备状态。
OpenLogi CLI（openlogi）—— 无界面清单、资源同步、补光灯与摄像头控制，以及设备端 HID++ 诊断。
assets.openlogi.org —— 静态托管，按设备 modelId 提供渲染图与可点击热点元数据；另有 Cloudflare 与 Fastly 镜像作为后备。

Crate	职责
`openlogi-core`	类型、TOML 配置、路径，以及按键 / 动作目录——不含 HID，也不含 async
`openlogi-hidpp`	内置的 HID++ 协议 crate（库名 `hidpp`）：通道、特性、接收器
`openlogi-hid`	设备发现、HID++ 读写、控件捕获、原始 HID 补光灯
`openlogi-hook`	系统输入钩子：macOS CGEventTap、Linux evdev/uinput、Windows `WH_MOUSE_LL`
`openlogi-inject`	系统事件合成：CGEvent、uinput / MPRIS、`SendInput`
`openlogi-camera`	UVC 摄像头发现、采集与图像控制
`openlogi-assets`	设备渲染图注册表结构与带缓存的镜像抓取
`openlogi-agent-core`	共享编排逻辑，以及代理 ↔ GUI 的 IPC 契约
`openlogi-agent` / `openlogi-gui` / `openlogi-cli`	三个二进制

控件被捕获——要么由系统钩子（中键 / 后退 / 前进）接管，要么通过 HID++ 0x1b04 接管（手势键、触感面板、模式切换键、键盘 F 区），由代理在绑定变化时重建的每设备捕获会话负责。
代理解析绑定：先看前台应用的叠加，再回落到设备的全局映射。
执行动作——经 openlogi-inject 合成为系统输入、通过 HID++ 写入设备（DPI、SmartShift），或由代理自己处理（Actions Ring）。

配置是一个纯 TOML 文件，启动时读取、变更时原子性重写——无云端、无账号。存放在设备易失性内存中的取值（DPI、SmartShift、Fn-lock、滚轮分辨率）由代理在每次重连时重新下发。

openlogi-agent-mock 用脚本化的内存清单提供与真实代理一致的 IPC 契约，因此没有罗技设备也能开发 GUI。参见 DEVELOPMENT.md。