架构 – OpenLogi Docs

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

组成部分

OpenLogi 代理（openlogi-agent）—— 后台进程：HID++ 设备 I/O、输入钩子、捕获会话、前台应用监视、菜单栏 / 托盘项、配对、动作分发，以及浮层辅助进程的监督。
OpenLogi 桌面（openlogi-desktop）—— GPUI 设置应用。本地状态用于展示与编辑，HID++ 读写都经过代理；摄像头预览与 UVC 控制仍由桌面直接操作。
Actions Ring 浮层（openlogi-overlay）—— 独立、常驻待命的 GPUI 进程。接收仅供呈现的轮盘快照，返回悬停、激活和取消事件；动作由代理保管和执行。
OpenLogi CLI（openlogi）—— 无界面清单、资源同步、补光灯与摄像头控制、fixture 采集与验证，以及 HID++ 诊断。设备清单可使用代理 IPC，硬件诊断仍直接访问设备。
assets.openlogi.org —— 静态托管，按设备 modelId 提供渲染图与可点击热点元数据；版本化的 Cloudflare Pages 源与 jsDelivr npm 分片参与镜像竞速。

组件关系

进程与本地状态

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

openlogi-desktop ── snapshots + commands ──┐
openlogi-overlay ── ring interactions ─────┼── openlogi-ipc ── openlogi-agent
openlogi list ───── inventory snapshot ────┘                        │
                                                                  ├── 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、Windows `WH_MOUSE_LL`
`openlogi-inject`	系统事件合成：CGEvent、uinput / MPRIS、`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 区），由代理在绑定变化时重建的每设备捕获会话负责。
代理解析绑定：先看前台应用的叠加，再回落到设备的全局映射。
执行动作：主机动作经 openlogi-inject 合成为系统输入，设备动作使用代理持有的 openlogi-hid 通道。
ShowActionsRing 由代理为浮层生成展示快照，接受悬停 / 激活 / 取消 RPC，验证会话与槽位后，再由代理执行选中的动作。

配置是纯 TOML 文件，无云端、无账号。桌面加载并原子写入后请求 reload_config。代理在启动时独立加载，重载时再次验证后才替换运行状态。存放在设备易失性内存中的取值（DPI、SmartShift、Fn-lock、滚轮分辨率）在重连与系统唤醒后重新下发。

无硬件开发

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