OpenLogi 架构总览GUI、Agent、Overlay 三进程分离设计的完整图解【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogiOpenLogi 是一款用 Rust 编写的本地优先local-first罗技设备管理工具可替代 Logitech Options支持按键重映射、DPI 调节和 SmartShift 滚轮设置无需账号、不收集遥测数据。它的核心架构是「三进程分离」设计GUI界面、Agent后台守护进程、Overlay动作环浮层各自独立运行通过本地 IPC 通信协作——这套设计也是它能做到轻量、稳定、可脚本化的根本原因。为什么采用三进程分离架构传统设备管理软件往往把「界面渲染」和「硬件通信」塞进同一个进程界面卡顿时按键重映射也跟着卡界面崩溃时设备功能全部失效。OpenLogi 的答案是把职责彻底拆开进程职责生命周期GUI纯展示 发送指令不碰任何设备 I/O按需启动关窗即退出Agent独占输入钩子与全部 HID 设备 I/O常驻后台开机自启Overlay渲染以光标为中心的 Actions Ring 浮层触发时拉起超时自动关闭这样带来三个直接好处职责单一界面可以随便关掉Agent 继续在后台完成按键重映射和 DPI 切换故障隔离Overlay 作为独立「兄弟进程」而非 GUI 的一部分渲染浮层时的任何异常不会影响主界面与设备控制权限收敛macOS 上需要输入监控、辅助功能等敏感权限的只有 Agent 一个二进制用户授权的目标清晰明确。这一分工在入口文件中写得非常直白Agent 的 crates/openlogi-agent/src/main.rs 自述为「headless, always-on无头、常驻」GUI 的 crates/openlogi-desktop/src/main.rs 则注明「GUI 是客户端观察设备清单与状态通过 IPC 转发设备指令」。GUI一个「纯 IPC 客户端」桌面端 GUI 基于 GPUI 框架构建源码位于 crates/openlogi-desktop/。它的启动流程很克制初始化日志 → 单实例锁 → 加载 TOML 配置 → 解析界面语言 → 建立到 Agent 的 IPC 客户端然后才进入 GPUI 事件循环见 crates/openlogi-desktop/src/main.rs。几个值得新手注意的设计细节关窗即退出GUI 是「按需型」进程最后一个窗口关闭时进程直接退出因为常驻工作全部由 Agent 承担无需让界面进程「 lingering 」配置只读不独占GUI 可以加载config.toml做展示和编辑但所有真正写硬件的动作都要经 IPC 交给 Agent 执行共享展示层GUI 与 Overlay 共用的图标、环几何、本地化资源被抽到独立的 crates/openlogi-ui/任何加进这个 crate 的依赖会同时进入两个进程——这是刻意维持的对称约束。Agent唯一「碰硬件」的进程Agent 是整个架构的心脏源码位于 crates/openlogi-agent/。它一个人包办了️输入钩子CGEventTapmacOS/ evdevuinputLinux/ WH_MOUSE_LLWindows捕获鼠标与按键事件HID 设备 I/O设备枚举、DPI 写入、SmartShift 配置、配对会话全部在此完成IPC 服务端在本地 socket 上监听服务 GUI 与 Overlay 两个客户端️系统托盘菜单栏图标、开机自启launchd / systemd / 注册表的协调维护。从 crates/openlogi-agent/src/main.rs 可以看到它的运行骨架先抢单实例锁因为它是唯一允许存在的设备 I/O 进程第二个 Agent 启动会直接退出或替换过期实例再构建 tokio 运行时最后进入一个tokio::select!主循环同时监听设备清单变化、相机状态、前台应用切换、辅助功能授权、关闭信号等事件流。值得注意的是 Agent 内部还有一层共享编排代码 crates/openlogi-agent-core/钩子运行时、DPI 循环、Actions Ring 会话状态它与 IPC 契约一起构成「三进程下方的公共地基」。OverlayActions Ring 为什么必须独立成进程Actions Ring 是 OpenLogi 的招牌功能之一按一下按钮以光标为圆心弹出 8 格环形菜单悬停即选、超时自动消失。它被实现为独立二进制openlogi-overlaycrates/openlogi-overlay/src/main.rs文件头注释开宗明义「本进程是纯 IPC 客户端。Agent 拥有 HID、会话校验、触觉输出与动作执行Overlay 只负责渲染 Agent 快照下来的动作并回报悬停 / 激活 / 取消。」分离的原因很实际环形菜单要求毫秒级弹出、像素级跟随光标如果把它画在 GUI 主窗口里就要承受主界面渲染管线的全部延迟独立进程可以「无窗口启动 → 弹环 → 自动关闭」整个会话生命周期由DISPLAY_LIFETIME超时控制见 crates/openlogi-overlay/src/main.rs。Overlay 与 Agent 的交互协议还有一套精巧的细节悬停是「尽力而为」而激活/取消这类终结性命令会重试到会话截止期新命令还会取代卡住的旧命令而不排队——这是浮层在 Agent 短暂繁忙时依然跟手的关键实现在 crates/openlogi-overlay/src/agent.rs。IPC 层连接三根「电话线」的契约三个进程之间的对话全部走tarpc bincode 本地 socketUnix 域套接字或 Windows 命名管道契约定义在 crates/openlogi-ipc/src/ipc.rs有版本号的线协议当前PROTOCOL_VERSION 28ipc.rs#L62规则是「只追加、不修改」客户端连接时会校验版本不匹配就拒绝工作并自动让位给新版进程没有服务端推送tarpc 是严格请求/响应模型Agent 想「告诉」客户端状态变化时用的是客户端常开的一个observe请求——状态一变立刻应答且应答携带全量状态客户端无需订阅与重放即可收敛ipc.rs#L4-L10单一传输路径interprocess在 Unix/Windows 上提供同一 APIAgent 端bind监听、GUI/Overlay 端connect两端用同一种长度分隔 bincode 帧格式见 crates/openlogi-ipc/src/transport.rs。也就是说GUI 和 Overlay 是平级的「兄弟客户端」谁都不直接持有设备句柄——这是理解 OpenLogi 架构最重要的一句话。一图看懂 Crate 与进程的对应关系OpenLogi 用 20 余个 crate 支撑这套架构理解「哪个进程链哪个库」比记住每个库更重要分层Crate说明进程入口openlogi-desktop / openlogi-agent / openlogi-overlay三个二进制IPC 契约openlogi-ipc线格式 本地 socket 传输agent 与 GUI 共享共享编排openlogi-agent-core钩子运行时、HID 写入、DPI 循环、Ring 会话纯类型层openlogi-coreTOML 配置、设备模型、动作目录——无 I/O、无 async硬件协议openlogi-hidpp / openlogi-device / openlogi-hidHID 协议、设备层、主机接线输入捕获/注入openlogi-hook / openlogi-inject平台事件钩子与合成输入共享展示openlogi-uiGUI 与 Overlay 共用的图标、几何、20 种语言本地化平台差异全部通过#[cfg(target_os …)]按 crate 门控如 Agent 的 macOS 托盘在 crates/openlogi-agent/src/tray.rs、Windows 托盘在 crates/openlogi-agent/src/tray_windows.rs保证同一份核心逻辑在三大平台复用。小结这套分离设计给普通用户意味着什么✅关掉主窗口重映射照常工作——设备功能不依附于界面进程✅弹窗菜单快而稳——Actions Ring 独立渲染不拖累主界面✅权限清晰——只有 Agent 一个进程申请系统权限隐私可控✅纯文本配置 CLI——全部设置收敛在一个 TOML 文件可参考 docs/CONFIGURATION.mdGUI 只是它的一个「遥控器」。如果你想深入开发建议的阅读顺序是docs/DEVELOPMENT.md 了解构建流程 → crates/openlogi-ipc/src/ipc.rs 读懂线协议 → 再按进程逐个读三个main.rs。三进程分离不是炫技而是「界面、硬件、浮层」三种节奏完全不同的工作各自的正确归属。【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenLogi 架构总览：GUI、Agent、Overlay 三进程分离设计的完整图解
OpenLogi 架构总览GUI、Agent、Overlay 三进程分离设计的完整图解【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogiOpenLogi 是一款用 Rust 编写的本地优先local-first罗技设备管理工具可替代 Logitech Options支持按键重映射、DPI 调节和 SmartShift 滚轮设置无需账号、不收集遥测数据。它的核心架构是「三进程分离」设计GUI界面、Agent后台守护进程、Overlay动作环浮层各自独立运行通过本地 IPC 通信协作——这套设计也是它能做到轻量、稳定、可脚本化的根本原因。为什么采用三进程分离架构传统设备管理软件往往把「界面渲染」和「硬件通信」塞进同一个进程界面卡顿时按键重映射也跟着卡界面崩溃时设备功能全部失效。OpenLogi 的答案是把职责彻底拆开进程职责生命周期GUI纯展示 发送指令不碰任何设备 I/O按需启动关窗即退出Agent独占输入钩子与全部 HID 设备 I/O常驻后台开机自启Overlay渲染以光标为中心的 Actions Ring 浮层触发时拉起超时自动关闭这样带来三个直接好处职责单一界面可以随便关掉Agent 继续在后台完成按键重映射和 DPI 切换故障隔离Overlay 作为独立「兄弟进程」而非 GUI 的一部分渲染浮层时的任何异常不会影响主界面与设备控制权限收敛macOS 上需要输入监控、辅助功能等敏感权限的只有 Agent 一个二进制用户授权的目标清晰明确。这一分工在入口文件中写得非常直白Agent 的 crates/openlogi-agent/src/main.rs 自述为「headless, always-on无头、常驻」GUI 的 crates/openlogi-desktop/src/main.rs 则注明「GUI 是客户端观察设备清单与状态通过 IPC 转发设备指令」。GUI一个「纯 IPC 客户端」桌面端 GUI 基于 GPUI 框架构建源码位于 crates/openlogi-desktop/。它的启动流程很克制初始化日志 → 单实例锁 → 加载 TOML 配置 → 解析界面语言 → 建立到 Agent 的 IPC 客户端然后才进入 GPUI 事件循环见 crates/openlogi-desktop/src/main.rs。几个值得新手注意的设计细节关窗即退出GUI 是「按需型」进程最后一个窗口关闭时进程直接退出因为常驻工作全部由 Agent 承担无需让界面进程「 lingering 」配置只读不独占GUI 可以加载config.toml做展示和编辑但所有真正写硬件的动作都要经 IPC 交给 Agent 执行共享展示层GUI 与 Overlay 共用的图标、环几何、本地化资源被抽到独立的 crates/openlogi-ui/任何加进这个 crate 的依赖会同时进入两个进程——这是刻意维持的对称约束。Agent唯一「碰硬件」的进程Agent 是整个架构的心脏源码位于 crates/openlogi-agent/。它一个人包办了️输入钩子CGEventTapmacOS/ evdevuinputLinux/ WH_MOUSE_LLWindows捕获鼠标与按键事件HID 设备 I/O设备枚举、DPI 写入、SmartShift 配置、配对会话全部在此完成IPC 服务端在本地 socket 上监听服务 GUI 与 Overlay 两个客户端️系统托盘菜单栏图标、开机自启launchd / systemd / 注册表的协调维护。从 crates/openlogi-agent/src/main.rs 可以看到它的运行骨架先抢单实例锁因为它是唯一允许存在的设备 I/O 进程第二个 Agent 启动会直接退出或替换过期实例再构建 tokio 运行时最后进入一个tokio::select!主循环同时监听设备清单变化、相机状态、前台应用切换、辅助功能授权、关闭信号等事件流。值得注意的是 Agent 内部还有一层共享编排代码 crates/openlogi-agent-core/钩子运行时、DPI 循环、Actions Ring 会话状态它与 IPC 契约一起构成「三进程下方的公共地基」。OverlayActions Ring 为什么必须独立成进程Actions Ring 是 OpenLogi 的招牌功能之一按一下按钮以光标为圆心弹出 8 格环形菜单悬停即选、超时自动消失。它被实现为独立二进制openlogi-overlaycrates/openlogi-overlay/src/main.rs文件头注释开宗明义「本进程是纯 IPC 客户端。Agent 拥有 HID、会话校验、触觉输出与动作执行Overlay 只负责渲染 Agent 快照下来的动作并回报悬停 / 激活 / 取消。」分离的原因很实际环形菜单要求毫秒级弹出、像素级跟随光标如果把它画在 GUI 主窗口里就要承受主界面渲染管线的全部延迟独立进程可以「无窗口启动 → 弹环 → 自动关闭」整个会话生命周期由DISPLAY_LIFETIME超时控制见 crates/openlogi-overlay/src/main.rs。Overlay 与 Agent 的交互协议还有一套精巧的细节悬停是「尽力而为」而激活/取消这类终结性命令会重试到会话截止期新命令还会取代卡住的旧命令而不排队——这是浮层在 Agent 短暂繁忙时依然跟手的关键实现在 crates/openlogi-overlay/src/agent.rs。IPC 层连接三根「电话线」的契约三个进程之间的对话全部走tarpc bincode 本地 socketUnix 域套接字或 Windows 命名管道契约定义在 crates/openlogi-ipc/src/ipc.rs有版本号的线协议当前PROTOCOL_VERSION 28ipc.rs#L62规则是「只追加、不修改」客户端连接时会校验版本不匹配就拒绝工作并自动让位给新版进程没有服务端推送tarpc 是严格请求/响应模型Agent 想「告诉」客户端状态变化时用的是客户端常开的一个observe请求——状态一变立刻应答且应答携带全量状态客户端无需订阅与重放即可收敛ipc.rs#L4-L10单一传输路径interprocess在 Unix/Windows 上提供同一 APIAgent 端bind监听、GUI/Overlay 端connect两端用同一种长度分隔 bincode 帧格式见 crates/openlogi-ipc/src/transport.rs。也就是说GUI 和 Overlay 是平级的「兄弟客户端」谁都不直接持有设备句柄——这是理解 OpenLogi 架构最重要的一句话。一图看懂 Crate 与进程的对应关系OpenLogi 用 20 余个 crate 支撑这套架构理解「哪个进程链哪个库」比记住每个库更重要分层Crate说明进程入口openlogi-desktop / openlogi-agent / openlogi-overlay三个二进制IPC 契约openlogi-ipc线格式 本地 socket 传输agent 与 GUI 共享共享编排openlogi-agent-core钩子运行时、HID 写入、DPI 循环、Ring 会话纯类型层openlogi-coreTOML 配置、设备模型、动作目录——无 I/O、无 async硬件协议openlogi-hidpp / openlogi-device / openlogi-hidHID 协议、设备层、主机接线输入捕获/注入openlogi-hook / openlogi-inject平台事件钩子与合成输入共享展示openlogi-uiGUI 与 Overlay 共用的图标、几何、20 种语言本地化平台差异全部通过#[cfg(target_os …)]按 crate 门控如 Agent 的 macOS 托盘在 crates/openlogi-agent/src/tray.rs、Windows 托盘在 crates/openlogi-agent/src/tray_windows.rs保证同一份核心逻辑在三大平台复用。小结这套分离设计给普通用户意味着什么✅关掉主窗口重映射照常工作——设备功能不依附于界面进程✅弹窗菜单快而稳——Actions Ring 独立渲染不拖累主界面✅权限清晰——只有 Agent 一个进程申请系统权限隐私可控✅纯文本配置 CLI——全部设置收敛在一个 TOML 文件可参考 docs/CONFIGURATION.mdGUI 只是它的一个「遥控器」。如果你想深入开发建议的阅读顺序是docs/DEVELOPMENT.md 了解构建流程 → crates/openlogi-ipc/src/ipc.rs 读懂线协议 → 再按进程逐个读三个main.rs。三进程分离不是炫技而是「界面、硬件、浮层」三种节奏完全不同的工作各自的正确归属。【免费下载链接】OpenLogi⚡️A native, local-first alternative to Logitech Options, written in Rust — remap buttons, DPI, and SmartShift over HID. No account, no telemetry.项目地址: https://gitcode.com/GitHub_Trending/op/OpenLogi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考