架构 – OpenLogi Docs

OpenLogi 由一个掌握运行时状态的后台代理和两个 GPUI 客户端组成。代理负责 HID++ 设备清单与通道、输入捕获、绑定解析、设备写入和动作执行。设置应用展示代理快照并发送命令。浮层负责绘制 Actions Ring 和屏幕提示，并把轮盘交互报告给代理。openlogi list 优先使用兼容代理的快照，不可用时才直接枚举。openlogi api 只通过代理 IPC 工作；硬件诊断命令直接打开设备。

组成部分

OpenLogi 代理（openlogi-agent）—— 后台进程：HID++ 设备 I/O、输入钩子、捕获会话、前台应用监视、菜单栏 / 托盘项、配对、动作分发、低电量与锁定键事件，以及浮层辅助进程的监督。
OpenLogi 桌面（openlogi-desktop）—— GPUI 设置应用。本地状态用于展示与编辑，HID++ 读写都经过代理；摄像头预览与 UVC 控制仍由桌面直接操作。应用更新检查也由桌面负责：macOS 上使用 Sparkle，Windows 上使用 MSI 更新器。
浮层（openlogi-overlay）—— 独立、常驻待命的 GPUI 进程。它根据仅供呈现的快照绘制 Actions Ring，并返回悬停、激活和取消事件；动作由代理保管和执行。它还绘制代理标记为当前的提示：低电量提示、锁定键指示和键盘背光亮度。参见屏幕提示。
OpenLogi CLI（openlogi）—— 无界面清单、资源同步、补光灯与摄像头控制、fixture 采集与验证，以及 HID++ 诊断。设备清单可使用代理 IPC；openlogi api 通过代理提供 JSON 输出与设备控制。硬件诊断仍直接访问设备。参见 CLI 指南。
assets.openlogi.org —— 静态托管，按设备 modelId 提供渲染图与可点击热点元数据；跟随资源版本线最新发布的 Cloudflare Pages 源与 jsDelivr npm 分片参与镜像竞速。

组件关系

进程与本地状态

openlogi-ipc 是共享契约与传输库，不是另一个进程。桌面和浮层连接同一端点，并使用共享的版本握手；不兼容的客户端不会交换运行时数据。

openlogi-desktop ── snapshots + commands ──┐
openlogi-overlay ── ring + notices ────────┼── openlogi-ipc ── openlogi-agent
openlogi list ───── inventory snapshot ────┤                        │
openlogi api ────── status + control ──────┘                        │
                                                                  ├── HID I/O
openlogi diagnostics ─────────────────────── direct HID I/O         └── OS input

代理监督独立浮层。桌面写入 config.toml 后请求经过验证的配置重载。开发 UI 时，可以在开发专用 socket 上用 openlogi-agent-mock 替代真实代理。

运行时与 I/O 边界

代理负责 HID++ 和系统输入捕获。桌面仅直接打开 UVC 摄像头；桌面和 CLI 都可以填充经过验证的资源缓存。

openlogi-device 面向 HidBackend 接口实现枚举、探测、会话、配对与设备写入，不自行打开主机设备。 openlogi-hid 提供真实的 async-hid 传输、权限集成与探测缓存。录制或回放后端可以复用同一设备层，而无需修改协议逻辑。原生输入捕获与合成分别由 openlogi-hook 和 openlogi-inject 负责。

Crate 一览

Crate	职责
`openlogi-core`	基础类型、TOML 配置、路径、设备模型、按键 / 动作目录与语言协商
`openlogi-hidpp-derive`	生成 HID++ 特性样板代码的私有过程宏
`openlogi-hidpp`	工作区维护的 HID++ 协议硬分叉（库名 `hidpp`）：通道、特性、接收器
`openlogi-device-registry`	纯接收器协议与独立设备身份元数据
`openlogi-fixture`	不依赖主机的 fixture 结构、合成身份与隐私 / 关联验证
`openlogi-device`	与后端无关的枚举、探测、会话、配对与设备写入
`openlogi-hid`	主机 HID 传输、权限集成与磁盘探测缓存
`openlogi-hook`	系统输入钩子与前台应用识别：macOS CGEventTap；Linux evdev/uinput，窗口识别支持 X11、wlroots 与 GNOME Shell；Windows `WH_MOUSE_LL` 与 `WH_KEYBOARD_LL`
`openlogi-inject`	系统事件合成：macOS CGEvent，签名的代理能创建虚拟 HID 键盘时，按键改由该键盘发出；Linux uinput、MPRIS、KWin 与 GNOME 的 D-Bus 调用，以及 Hyprland 调度；Windows `SendInput`
`openlogi-camera`	UVC 摄像头发现、采集与图像控制
`openlogi-permissions`	只读权限状态与系统设置跳转；摄像头权限 API 位于 `openlogi-camera`
`openlogi-assets`	设备渲染图注册表结构与带缓存的镜像抓取
`openlogi-ipc`	tarpc 服务契约与 Unix socket / Windows 命名管道上的 bincode 传输
`openlogi-agent-core`	无界面编排、捕获规划、硬件操作、动作分发与 Actions Ring 会话
`openlogi-ui`	共享 GPUI 动作图标、颜色与语言目录
`openlogi-cli` / `openlogi`	CLI 实现库及其薄二进制包装
`openlogi-agent`	真实代理与 `openlogi-agent-mock` 两个二进制目标
`openlogi-desktop`	GPUI 设置应用与代理 IPC 客户端
`openlogi-overlay`	独立 GPUI 渲染器，绘制 Actions Ring、屏幕提示与键盘指示；代理 IPC 客户端
`xtask`	CI、打包与发布工具

一次按键如何变成动作

控件被捕获：要么由系统钩子（中键 / 后退 / 前进）接管，要么通过 HID++ 0x1b04 接管（手势键、触感面板、模式切换键、键盘 F 区），由代理在绑定变化时重建的每设备捕获会话负责。同一会话还会通过 0x2121 接管主滚轮以实现平滑滚轮（Smooth wheel），并通过 0x1b04 读取原始滚轮输入以实现按住时水平滚动（Hold to scroll sideways）。
代理解析绑定：先看目标应用的叠加，再回落到设备的全局映射。鼠标配置默认跟随指针下的应用，也可以用 mouse_profile_target = "focused" 改为跟随焦点应用。键盘配置始终跟随焦点。参见按应用配置。
执行动作：主机动作经 openlogi-inject 合成为系统输入，设备动作使用代理持有的 openlogi-hid 通道。
对于 ShowActionsRing，代理选择焦点应用对应的完整布局，再为浮层生成展示快照。代理接受悬停 / 激活 / 取消 RPC，验证会话与槽位后执行选中的动作。

配置是纯 TOML 文件，无云端、无账号。桌面加载并原子写入后请求 reload_config。代理在启动时独立加载，重载时再次验证后才替换运行状态。

部分设置存放在设备的易失性内存中，设备重连后会丢失。代理会在重连或系统唤醒后重新写入这些设置：DPI、回报率、SmartShift、原生滚轮模式（分辨率与反转）、键盘灯光、Fn 锁定、保持系统布局（Keep OS layout）和 Litra 灯光设置。已停用的设备不会收到任何写入。

无硬件开发

openlogi-agent-mock 用脚本化内存清单提供真实 IPC 契约，不打开 HID 设备或安装输入钩子，因此没有罗技设备也能开发桌面与浮层。它可以加载录制的设备 profile 来替代内置清单。HID++ cassette 则通过回放后端测试独立的设备层，不是 UI mock 的实时输入流。参见参与贡献和 MOCK_DEVICE_TESTING.md。