OpenLogi IPC 线缆协议剖析：tarpc + bincode 的位置化、只追加线缆格式与版本管理-育师

OpenLogi IPC 线缆协议剖析：tarpc + bincode 的位置化、只追加线缆格式与版本管理

【免费下载链接】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

OpenLogi 的桌面 GUI 与后台 agent 是两个独立进程，它们通过一个本地 socket 上的 tarpc + bincode 线缆协议对话。本文以crates/openlogi-ipc为核心，完整解读这份 "append-only（只追加）" 线缆格式的设计约束：为什么方法顺序与枚举变体索引就是线缆格式本身、为什么protocol_version必须永远是方法 0、黄金字节测试如何钉死每一处线缆布局，以及 debug 构建的 agent 为什么永远不会夺走正在运行的 release agent。读完本文，你将掌握 OpenLogi IPC 的架构骨架、各 RPC 方法语义、版本升级规范，以及如何在修改线缆类型时正确地跑通验证流程。

一、架构总览：GUI 与 agent 如何对话

1.1 传输层：interprocess 本地 socket

OpenLogi 的 agent（服务端）与 GUI（客户端）通过 tarpc 在interprocess本地 socket 上进行 RPC 通信，线缆定义位于 crates/openlogi-ipc/src/ipc.rs：

Unix：文件系统 Unix-domain socket，位于openlogi_core::paths::agent_socket_path()，生产构建默认~/.config/openlogi/agent.sock；macOS 本地-devbundle 使用兄弟的openlogi-dev配置目录，避免开发 agent 占用已安装应用的端点。
Windows：OS 命名空间下的命名管道\\.\pipe\openlogi-agent.sock。

interprocess在 Unix 与 Windows 上暴露同一套 API，因此 agent（bind）与 GUI（connect）共用一条代码路径，两端都通过wrap()用 "长度前缀 + bincode" 的同一帧格式包裹连接。bind()的try_overwrite(true)会清理非干净退出（SIGKILL / panic=abort / 掉电）残留的 Unix socket 文件，否则监听器Drop未执行时，残留 socket 会一直导致AddrInUse。相关实现见 crates/openlogi-ipc/src/transport.rs。

1.2 为什么是位置化线缆格式

线缆格式是位置化（positional）的，原因有两层：

bincode 编码枚举的"变体索引"（variant index），而非#[repr(u8)]判别值——这两者可能不一致；
tarpc 编码的是 trait 方法的"方法顺序"（method order），tarpc 会从 trait 生成一个请求枚举，bincode 编码该枚举的变体索引。

因此，Agenttrait 的方法声明顺序、serde 枚举的变体声明顺序，都直接构成了线缆字节的一部分。这是该 crate 最核心的纪律：任何穿过 IPC 边界的类型都是只追加的（append-only），永远不允许重排或删除。

1.3 线缆边界比本 crate 更宽

线缆表面（wire surface）不只是本 crate 内的类型。来自openlogi-core的 serde 类型（设备模型、DeviceKind、动作、配置）与openlogi-hid的写错误（WriteError）会骑在 RPC 负载里穿越边界，因此同样的只追加规则同样约束它们。也就是说，改openlogi-core或openlogi-hid中任何跨边界 serde 类型，与改本 crate 的线缆类型一样敏感。

二、协议版本：`protocol_version`必须永远是方法 0

2.1 严格相等，无兼容协商

PROTOCOL_VERSION当前为 29（见 crates/openlogi-ipc/src/ipc.rs），它独立于 crate 版本号，仅在线缆类型发生破坏性变更时递增。GUI 在连接时通过Agent::protocol_version检查该值，严格相等（strict-equal）时才继续驱动；不匹配则直接拒绝（transient only：GUI 与 agent 打包在同一个.app中并原子更新）。

线缆注释中明确说明：没有小版本 / 兼容协商。因为 GUI 与 agent 在同一 bundle 中发布，agent 二进制被替换时会 re-exec 自己，所以"严格相等 + 干净拒绝"就是完整契约。方法顺序是线缆格式的一部分：若protocol_version不再是第一个方法，握手本身在版本偏移时就会解码失败，此时连"检测并报告不匹配"都做不到了。

2.2 连接握手：client.rs 的统一机制

所有客户端——设置应用与 overlay 助手——都必须走同一条路径：连接、包裹流、spawn tarpc client、在发起任何真实 RPC 之前读取 agent 的协议版本。不同的只是不匹配时的策略（应用告知用户哪一侧过期；overlay 让出自己的角色），因此机制集中在 crates/openlogi-ipc/src/client.rs：

pub async fn connect() -> Result<Connection, ConnectError> { let stream = transport::connect().await?; let client = AgentClient::new(client::Config::default(), transport::wrap(stream)).spawn(); let version = client.protocol_version(context::current()).await?; Ok(Connection { client, version }) }

版本故意不在本函数内校验——调用方对比PROTOCOL_VERSION后按方向决策：更老的 agent 等着被替换，更新的 agent 说明本进程才是过期方。ConnectError区分两种截然不同的失败：Endpoint（socket 不可达：agent 未运行、未监听、端点名无法解析）与Handshake（socket 接受了连接但 agent 从未应答握手——挂起或垂死的 agent，而非缺席）。

2.3 实践中如何使用：CLI 的优雅降级

openlogi-cli 的 list 命令展示了版本策略的落地：先以 2 秒超时尝试client::connect()；若版本不匹配，打印提示note: the agent speaks protocol v{}, this CLI expects v{PROTOCOL_VERSION} — reading hardware directly，随后绕过 agent 直接读硬件。若连接成功，则以ClientKind::Cli声明身份（见下文第 4.5 节），使休眠 agent 无需武装整套输入栈即可服务一次查询。

三、黄金字节测试：钉死线缆格式

3.1 测试文件与运行方式

线缆格式的每一处布局都由 golden test 钉死，位于 crates/openlogi-ipc/tests/wire_format.rs。运行方式：

cargo test -p openlogi-ipc --test wire_format

规则是：任何触碰线缆类型的提交在 push 之前都必须跑这个测试。失败信息会打印新编码的字节（left是新编码）。

3.2 序列化选项：DefaultOptions，不是自由函数

线缆使用 tokio-serde 的Bincode::default()，即 bincode 1.3 的DefaultOptions（varint 整数、little-endian、拒绝尾部多余字节）。而自由的bincode::serialize/deserialize函数使用fixint编码，不会产生匹配的字节。测试辅助函数因此显式走bincode::DefaultOptions::new().serialize(...)，而不是自由函数。

3.3 黄金测试的验证范围

每个assert_wire都做双向验证：序列化字节与黄金值严格相等，再反序列化回原值并重新序列化，确认往返一致。黄金测试覆盖了：

请求变体顺序（方法顺序即线缆）：ProtocolVersion {}=00、SetDpi=04、NextPairing=0d、Snapshot=0e、PollEventMonitor=0f、Identity=16、Observe=17、ObserveActionRing=18、DeclareClient=19等；
protocol_version_is_pinned：assert_eq!(PROTOCOL_VERSION, 29)，任何黄金值重生成都必须伴随版本号提升，同一 diff 中可见；
agent 身份冻结：Identity两半都是裸u64，黄金0712永不变化——新旧任何构建都能解码，helper 才能读懂"让它离开"的指令；
各类 DTO：AgentStatus、AgentSnapshot、ForegroundApps、配对阶段、事件监视器事件、Actions Ring 类型、设备库存、设备设置负载、独立灯光设备等。

测试文件中特别钉死了几个"看似无辜的修复"陷阱：例如 serde 编码SmartShiftMode的变体索引（Free=0, Ratchet=1），而非#[repr(u8)]固件判别值（1/2）；FeatureUnsupported变体索引对 GUI 停止重复探测是承重（load-bearing）的，不仅关乎可解码性。

四、RPC 服务契约：Agent trait 逐方法解读

#[tarpc::service] pub trait Agent定义了完整的方法面。以下是按声明顺序的关键方法及其语义（全部见 crates/openlogi-ipc/src/ipc.rs）：

方法	语义
`protocol_version() -> u32`	握手用，方法 0，跨所有版本线缆稳定
`status() -> AgentStatus`	Accessibility / hook / 自启动状态，供 GUI 门禁与设置页
`inventory() -> Vec<DeviceInventory>`	最新设备库存快照（GUI 在窗口打开时按定时器轮询）
`reload_config() -> Result<(), ConfigReloadError>`	重读`config.toml`并重建绑定/DPI 映射；GUI 保存配置后调用
`set_dpi`/`read_dpi`	立即应用 / 读取 DPI 值（滑动条预览与提交）
`set_lighting`/`set_smartshift`/`read_smartshift`	立即应用灯光与完整 SmartShift 配置
`request_accessibility_prompt()`	由 agent 发起 Accessibility 弹窗，使系统对话框指向真正被信任的 agent 二进制
`start_pairing`/`pair_device`/`cancel_pairing`	配对会话的三种命令；agent 独占设备 I/O
`next_pairing() -> Option<PairingUpdate>`	长轮询下一步配对事件（已被状态化`PairingPhase`取代，方法保留只因方法顺序即线缆）
`snapshot() -> AgentSnapshot`	原子获取状态 + 最新库存（v4 追加）
`poll_event_monitor() -> Vec<MonitorEvent>`	排空 hook 观察到的事件（v9 追加）
`set_light`/`set_light_manual_power`	独立灯光命令与相机联动灯的手动功率覆盖
`next_action_ring() -> Option<ActionRingInvocation>`	长轮询下一次 Actions Ring 调用（已被状态化取代，方法保留）
`action_ring_hover`/`action_ring_activate`/`action_ring_cancel`	环交互三命令，带`ActionRingCommandError`
`identity() -> Identity`	本 agent运行实例的身份；冻结，位置永不变
`observe(since: Generation) -> Observation`	阻塞到可观察状态与`since`不同，然后整体返回
`observe_action_ring(since: Generation) -> RingObservation`	环的独立状态通道，契约同`observe`
`declare_client(kind: ClientKind)`	声明连接类型；对休眠 agent 是承重信息（v29 追加）

4.1 observe：边沿驱动的时间、全量状态的内容

tarpc 是严格的请求/响应，没有服务端推送。因此 agent 需要"告诉"客户端的事，被塑造成客户端保持打开、agent 一直持有直到有话说或持有窗口耗尽的请求。Agent::observe就是这条状态通道：

时间上是边沿驱动：agent 的任一 watcher 改变状态时立即应答；
内容上永远是完整当前状态，绝不是增量：客户端从任意起点（新窗口、重连、agent 重启）都能收敛——用最后一次见过的 generation（或0）问一次即可。这让协议免除了订阅、回放与缺口检测，两侧都不需要记忆任何历史。
持有窗口OBSERVE_HOLD= 20 秒：无可报告时 agent 在窗口耗尽后以不变状态应答，这同时充当存活心跳——挂起（而非死亡）的 agent 停止应答，死亡的 agent 则掉落 socket。该常量在 crates/openlogi-ipc/src/ipc.rs 导出，客户端设置请求 deadline 必须高于它，因为 tarpc 会取消 deadline 过期的 handler。

Generation单调递增，仅在状态真正变化时递增。0是客户端"I 什么都没见过"的哨兵；agent 的 cell 从 1 开始，因此第一次observe(0)立即应答，而不是等 20 秒的持有期去等一个已经发生的变化。

4.2 服务端实现：ObservableState

agent 侧的状态 cell 在 crates/openlogi-agent-core/src/observable.rs：内部是tokio::sync::watch通道，update()通过send_if_modified只在真正有差异时递增 generation 并通知——"一个不改变任何东西的写入不通知任何人"，这正是读者可以阻塞在该 cell 上而非定时重采样的原因。该 cell 有多个写者（orchestrator 写设备与配置事实、agent 二进制写 hook 事实），因此以Arc共享，每个 setter 都取&self。

单元测试覆盖了关键语义：重复枚举不唤醒读者（a_repeated_enumeration_notifies_nobody）、权限撤销与 hook 退役在同一 generation 完成（a_revoke_retires_the_hook_in_the_same_generation）、持有期耗尽返回不变状态（nothing_to_report_answers_with_the_unchanged_state）、静默写入不终止持有期（a_silent_write_does_not_end_the_hold）。

4.3 PairingPhase：配对会话是状态，不是事件流

AgentSnapshot::pairing（v20 追加）把配对会话建模为状态而非步骤流：Searching/Found(Vec<FoundDevice>)/Pairing/Passkey(PasskeyMethod)/Paired { slot }/Failed(PairingFailure)。这让 agent 中途重启自愈：替代 agent 没有会话，因此停留在 "Searching…" 的窗口自行消解，无需为其合成终止事件。终态（Paired、Failed）一直保留到会话被取消或新会话开始，结果不会像事件那样落在两次观察之间。旧的next_pairing事件流仍被忠实服务，只因方法顺序是线缆格式。

PairingFailure是类型化错误（Hid、ReceiverNotFound、Register、Timeout、Device { code }、Cancelled、ReceiverBusy、WatcherUnavailable、AgentRestarted、ReceiverAccessUnavailable、AlreadyActive、UnknownDevice、NoActiveSession），跨 agent↔GUI 边界保持类型化，GUI 可以据此选择恢复 UI、遥测与本地化文案，而不必匹配人类可读字符串。PairingCommandError只覆盖"agent 无法接受命令本身"的失败，接受后的进度仍通过状态呈现。

4.4 RingObservation 与 Actions Ring 呈现

observe_action_ring在独立的 cell上运行，而不是AgentSnapshot的字段：overlay 是工作集完全不同的观察者，为了每次设备热插拔都唤醒它并塞给它完整设备库存，对一个只负责"按键按下的瞬间画出环"的 helper 是错误的。RingObservation携带 generation 与Option<ActionRingInvocation>——None即"没有环要显示"，关闭也因此到达，无需发明"closed"消息。

ActionRingInvocation只携带只读呈现快照：标签、literal标志（用户自写文案原样渲染，避免与本地化键碰撞，v16）、已解析图标与语言。可执行动作永不跨入 overlay helper，留在 agent 拥有的会话中。overlay 的完整实现见 crates/openlogi-overlay/src/agent.rs：连接、声明ClientKind::Overlay、读取identity并与succession的 allegiance 比对，superseded 则让位退出；终端命令（activate/cancel）会重试直到会话自身 deadline，而同一环的更新命令会取代（supersede）停滞命令而非排队，保证环的响应性。

4.5 declare_client：macOS 休眠门禁的承重信息

ClientKind有三个变体：Gui（桌面应用，唯一能武装休眠 agent 的类型）、Cli（读取快照，不武装）、Overlay（overlay helper，不武装——自行连接的是上一次运行的孤儿）。连接握手后立即声明。AgentServer把每次连接的声明转发到休眠门禁（dormancy gate）的 demand 通道，见 crates/openlogi-agent/src/server.rs。接管探测（takeover probe）从不声明——它只讲protocol_version——因此也永远不会武装休眠 agent。

五、接管（Takeover）：如何用只读握手替换旧 agent

5.1 背景：二进制 watcher 覆盖不到的旧 agent

二进制 watcher 只存在于带有它的二进制里，因此第一次协议版本提升仍会搁浅每个运行着更新前 agent 的用户：旧 agent 从不退出、launchd 只在退出时行动、它持有单例锁使每个新 spawn 的 agent 失败退出、新 GUI 又拒绝旧协议——用户被钉在连接界面直到下次登录。接管逻辑见 crates/openlogi-agent/src/takeover.rs。

5.2 接管流程

新 agent 失去单例锁后，以客户端身份连接 IPC socket，向锁持有者询问协议版本：

握手：protocol_version握手跨版本线缆稳定（方法 0，裸u32），所以对任何过去版本的 agent 都有效。等待窗口HANDSHAKE_TIMEOUT= 2 秒，答不上来的持有者视为无法推理的卡死状态，不动它。
版本比较：持有者版本更老→ 是更新前的遗留物，终止它并夺取锁；持有者版本相同或更新→ 我们才是重复（或过期）的那一个，照旧退出。
终止手段：SIGTERM 而非礼貌 RPC——过去版本的协议没有 quit 方法。太老而无法处理信号的持有者死于信号，在 launchd 下这是非成功退出，于是 launchd 以 bundle 路径（即新二进制）重生它，随后的锁竞争败者干净退出；新到能处理 SIGTERM 的持有者释放事件 tap 并以 0 退出，launchd 不干预，锁落到我们手中。无论哪条路，最终恰好一个最新 agent 存活。
锁重试：LOCK_RETRY= 20 × 200 ms 预算，覆盖慢速退出。

5.3 debug 构建永不接管：设计而非缺陷

try_replace_stale()在cfg!(debug_assertions)下直接返回None，日志记录 "debug build — leaving the running agent in place"。debug 构建的 agent 永远不会夺走正在运行的 release agent——这是有意的设计（开发 agent 不得挤掉用户的生产 agent），不是 bug。这是 AGENTS.md 明确强调的约束之一。Windows 侧没有历史包袱：从未发布（或自启动）过 agent，binary_watch在更新时退出、GUI 的 spawn 重试启动新二进制，因此replace_stale()直接返回None。

六、升级线缆类型的完整规程

综合 AGENTS.md 与源码，任何线缆变更必须遵循：

只追加：服务方法只在末尾追加，永不重排或删除；跨边界的 serde 枚举只追加变体，永不重排。若看起来需要"重排"，说明设计上应新增类型/方法而非修改旧布局。
提升版本：任何线缆变更都提升PROTOCOL_VERSION，并同步更新protocol_version_is_pinned测试中的断言（当前为 29）。
重新生成黄金值：更新 crates/openlogi-ipc/tests/wire_format.rs 中的 golden hex。若失败是有意为之，从断言消息（left是新编码）取实际十六进制替换黄金值。
跑测试：cargo test -p openlogi-ipc --test wire_format——任何触碰线缆类型的 push 之前都必须运行。
尊重冻结面：identity()方法的位置与Identity两半u64的类型是冻结的——新旧任何构建都要能解码；关于 agent 的新事实放新方法或AgentStatus，绝不放进 identity。
保持客户端 deadline：调用observe/observe_action_ring时把 RPC deadline 设在OBSERVE_HOLD（20 秒）之上，否则 tarpc 会在持有期结束前取消 handler。

七、设计与演进参考

docs/DECISIONS.md的架构决策记录把这条线缆称为项目的两条生产基础设施之一（另一条是succession的单进程-单角色生命周期模式），并记录了"agent 保持单进程；跨越边界的边获得一条线缆，而非事件层"的决策依据：任何候选切分点都穿过热路径（CGEventTap hook 与 HID++ 设备 I/O 是同一个输入循环的两端），GUI/agent 拆分之所以成立，正是因其跨越边是冷路径（配置保存、快照、长轮询）。其既定方针是：任何将来跨越进程边界的边，都应获得openlogi-ipc契约上的版本化方法（只追加、黄金测试、PROTOCOL_VERSION提升），外加一个succession角色管理新进程的生命周期——但第一动作永远是"一条线缆"，而不是一个抽象。

这套设计让 GUI、agent、CLI 与 overlay 四个进程共享同一个版本化契约：GUI 是纯 IPC 客户端（lib.rs 说明本 crate 是叶子 crate，只依赖openlogi-core，GUI 拉入线缆契约无需链接openlogi-hid/hidpp/async-hid），agent 侧回答这些 RPC 的运行时（hook 运行时、设备 I/O、Actions Ring 会话状态）留在openlogi-agent-core，反向依赖本 crate。理解这份线缆格式，就理解了 OpenLogi 多进程架构的全部边界约束。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenLogi IPC 线缆协议剖析：tarpc + bincode 的位置化、只追加线缆格式与版本管理