OpenLogi 代理开发指南从架构地图到发布管线的 Rust 工程实践【免费下载链接】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 仓库根目录的 AGENTS.md即 CLAUDE.md 通过AGENTS.md导入的代理契约文档为骨架结合工作区源码、Cargo 清单、CI 工作流与发布配置系统讲解这个 Rust 版 Logitech Options 替代品的架构设计、构建验证流程、代码规范与发布管线。读完你将掌握 OpenLogi 的 crate 边界划分、三进程通信模型、分级质量门禁以及从提交到发布的完整工程纪律。OpenLogi 是一个用 Rust 编写的、本地优先的 Logitech Options 替代品支持按钮重映射、DPI、SmartShift 与按应用配置文件覆盖 Logitech HID 设备Bolt/Unifying 接收器、蓝牙直连、有线连接无账号、无遥测、纯 TOML 配置。macOS 与 Linux 是一等公民Windows 是较新但已可交付的移植。代码采用 MIT/Apache-2.0 双许可证design/目录下的品牌资产为专有。文档定位CLAUDE.md 与 AGENTS.md仓库根目录的 CLAUDE.md 全文只有一行AGENTS.md——这是 Claude Code 的内容导入指令指向开发者手册 docs/DEVELOPMENT.md 之外的代理契约文件AGENTS.md。该文件是代理Agent与项目协作的全局工作流契约包含四大部分架构地图19 个工作区 crate 的角色与进程边界证据纪律问题必须回溯到根因并验证构建、运行、验证从快速迭代到推送前全量门禁的分级检查策略工程规范Rust 标准、Git/GitHub 流程、发布管线与子系统规则索引。文件结尾明确所有子系统专属规则都放在.claude/rules/下的路径作用域规则文件中AGENTS.md只承载全局工作流改到对应区域前必须阅读匹配的规则文件。架构地图三进程模型与 crate 边界OpenLogi 的运行时架构核心是一个长期运行的agent进程独占输入钩子与 HID I/OGUI与overlay是纯粹的 IPC 客户端CLI 是诊断例外openlogi list优先使用兼容的 agent 快照无可用时回退到直接枚举硬件诊断子命令则直接访问设备。仓库 Cargo.toml 定义了 20 个 workspace 成员各 crate 的角色如下Crate角色crates/openlogiCLI 二进制——对openlogi-cli的薄封装crates/openlogi-core纯类型TOML 配置、设备模型、动作目录、locale 协商。无 I/O、无 async按 feature 门控的主机读取fs、localecrates/openlogi-device-registry纯硬件身份注册表接收器协议与独立设备驱动元数据crates/openlogi-hidpphidpp协议 crate 的硬分叉库名为hidpp0BSD 许可crates/openlogi-hidpp-derive为openlogi-hidppfeature 样板代码服务的私有 derive 宏crates/openlogi-deviceHID 设备层枚举、探测、写入、会话、配对。不感知宿主针对HidBackend表达crates/openlogi-hid将设备层接到本机async-hid传输、macOS Input Monitoring、磁盘探测缓存crates/openlogi-camera跨平台 Logitech UVC 枚举、采集、控制与相机权限 APIcrates/openlogi-assets设备渲染注册表 OpenLogi 资产镜像的缓存拉取crates/openlogi-cliCLI 分发可用时走 agent 库存另加直接硬件诊断crates/openlogi-hookOS 输入捕获CGEventTap / evdevuinput / WH_MOUSE_LLcrates/openlogi-injectOS 输入合成CGEvent / uinputMPRIS / SendInputcrates/openlogi-agent-core共享 agent 编排钩子运行时、HID 写入、DPI 循环、Actions Ring 会话状态crates/openlogi-ipctarpc IPC 契约src/ipc.rs 本地 socket 传输agent 与其客户端共用crates/openlogi-agentopenlogi-agent二进制——运行时 HID/输入服务端crates/openlogi-permissions隐私权限状态 系统设置深链macOS TCC 读取、Linux 设备文件探测。只读从不主动弹窗crates/openlogi-ui两个 GPUI 进程共享的表现层圆环几何/图标、GPUI 资产源、共享 locale 目录。依赖gpui但不依赖gpui-componentcrates/openlogi-desktopGPUI gpui-component 桌面应用——轮询 agent不做 HID/输入 I/Ocrates/openlogi-overlayopenlogi-overlay二进制——光标居中 Actions Ring纯 IPC 客户端xtaskcargo xtask维护任务打包、发布清单三个关键架构约束值得展开1. 版本化且只追加append-only的 IPC 线格式。IPC 客户端与 agent 通过interprocess本地 socket 上承载的 tarpc/bincode 通信。根据 crates/openlogi-ipc/AGENTS.mdbincode 编码枚举的变体索引、tarpc 编码方法顺序因此线格式是位置化的——服务方法只能追加protocol_version必须永远是方法 0接管握手要跨版本探测它。任何线格式变更都要提升 ipc.rs 中的PROTOCOL_VERSION当前为 29连接时严格相等校验并重新生成 tests/wire_format.rs 中的黄金测试。注意 serde 编码的是声明索引而非#[repr(u8)]判别值两者可能不一致线格式表面比该 crate 更宽——openlogi-core的设备模型、动作、配置与openlogi-hid的写入错误类型都搭载在 RPC 载荷内同样受此约束。2. overlay 是 GUI 的兄弟进程。三个进程随 bundle 一起发布但 overlay 链接的是openlogi-ui从不链接openlogi-desktop。两者都需要的东西必须进openlogi-ui而每次向openlogi-ui添加依赖也会进入 overlay——这正是openlogi-ui不依赖gpui-component的原因见 crates/openlogi-desktop/AGENTS.md。3. 平台代码按 cfg 门控。每个 crate 通过[target.cfg(target_os …).dependencies]做平台区分.claude/rules/cross-platform.md是 cfg 门控平台代码的契约.claude/rules/objc-ffi.md维护 macOS 原生 FFI 的权威文件清单。从源码看CLI 是唯一可发布到 crates.io 的例外路径openlogi-ipc因 CLI 依赖其契约而进入发布依赖闭包见 release-plz.toml 注释。证据纪律与根因修复AGENTS.md 对问题处理提出明确要求把每个 issue、用户报告、评审意见都当作声明claim在接受其诊断前必须对照当前 head 与最直接的可用证据验证。修复必须落在根因所属模块及其生命周期边界上——不允许用 shim、回退或一次性抽象去掩盖一个损坏的 owner 或生命周期。这一纪律也体现在单例锁等工程细节上desktop 应用二次启动会因单例锁退出开发时必须先退出旧实例再重新run不能把改动没生效误判为 UI 渲染问题。构建、运行、验证分级的质量门禁工具链与 devenvNix/devenv 是可选项——rustup rust-toolchain.tomlstable channel含 rustfmt 与 clippy 组件即可。若安装了 devenvdirenv 会加载它否则.envrc仅打印提示、不动 PATH系统cargo照常工作。devenv 激活时 cargo 可能只在 shell 内可用需在仓库根运行命令或direnv exec . …git 同样如此钩子需要 cargocargo check -p openlogi-core # cargo 仅在 devenv 内时 direnv exec . cargo check -p openlogi-core direnv exec . git commit …工作区根 Cargo.toml 使用 resolver 3、edition 2024rust-version为 1.98跟随当前 stable。default-members只保留crates/openlogi避免裸cargo build拖入 GPUI 的 Metal shader 工具链。迭代期快速路径先定义一个证明文档明确反对每次编辑后跑全工作区 Clippy/测试/rustdoc——宽泛检查是最终门禁而非内层开发循环。正确顺序是先定义单一证明选择能证明预期结果的聚焦测试、编译目标或运行时行为内层循环只跑该证明行为用cargo test -p crate test-filterAPI/类型反馈用cargo check -p crate一行或纯文档改动不触发 Clippy代码稳定后对实际改动的 crate 各跑一次格式化检查、相关测试与cargo clippy -p crate --all-targets -- -D warnings共享公共 API 用cargo check验证受影响消费者仅在 push 前根据最终 diff 选择受影响包门禁或全量门禁。本地门禁push 前的硬性关卡受影响包层级——仅当同时满足以下条件时才允许使用自上次全量门禁以来没有 rebase 过 Rust 提交、没有解决过冲突diff 不涉及任何工作区级构建/校验输入任何Cargo.toml、build.rs、Cargo.lock、rust-toolchain.toml、.cargo/**、lint/格式/钩子配置、devenv 配置、CI 工作流。此时对整个受影响包集合改动包 传递依赖它们的包用cargo tree --workspace --target all --invert changed推导运行export RUSTFLAGS-D warnings cargo fmt --all -- --check cargo clippy -p affected… --all-targets -- -D warnings cargo test -p affected…全量层级——在 Rust 相关 rebase/冲突解决后、任何工作区级输入变更时、受影响集合无法可靠推导时或子系统规则明确要求时export RUSTFLAGS-D warnings # CI 全局设置此值clippy 的 -D warnings 与之不同 cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace RUSTDOCFLAGS-D warnings cargo doc --workspace --no-deps \ --document-private-items --exclude openlogi-ui --exclude openlogi-desktop \ --exclude openlogi-overlay --exclude openlogi-agent # 或devenv tasks run openlogi:check # 本机可复现的每个 CI jobcargo xtask cirustdoc 步骤镜像 CI 的rustdoc (non-GUI crates)任务能捕获其他三步发现不了的故障失效的 intra-doc 链接既不是编译错误也不是 clippy lint。GPUI crate 被排除是因为文档化它们会拖入整个图形工具链其余 crate 通过排除而非列举覆盖新 crate 默认即被文档化。本地复现每个 CI job本地门禁只是宿主 OS 子集完整流水线见 .github/workflows/ci.ymlLinux clippy、macOSLinux MSRV、rustdoc、排除 desktop 的 Linux 测试、macOS--all-targets测试、typos、cargo-deny、Windows clippy、wasm 可移植性、shell lint。macOS 绿灯不等于矩阵全绿用cargo xtask复现本机可跑的所有 jobcargo xtask ci cargo xtask ci --list # job → 命令对照表 cargo xtask ci rustfmt clippy # 单 job名称与 CI 一致 # 或devenv tasks run openlogi:ci跳过某个 jobOS 不对、缺cargo-deny、无 MSRV 工具链不算通过——必须在 PR Testing 部分如实声明未运行。完整映射见 .claude/rules/ci.md。prek 钩子兜底而非替代prek.toml 配置了 Git 钩子管理器commit 阶段运行内置的 trailing-whitespace、end-of-file-fixer、check-yaml、check-toml、check-merge-conflict 与 check-added-large-files^design/排除——1024² 的图标主文件合法超过 500 KB 默认阈值外加 typospre-push 阶段运行cargo fmt --all --、全工作区 Clippycargo clippy --workspace --all-targets -- -D warnings与 rustdoc排除 GPUI 四 crate。钩子是兜底rebased 之后仍需自己跑门禁。Push 清单代理专用rebase/合并冲突完全解决——无残留、无半移植 API最终树上适用层级门禁绿灯非 Rust diff 走非 Rust 检查无全量触发条件走受影响包层级否则全量diff 要求的额外流水线 job 按名运行cargo xtask ci job…跳过的 job 如实声明未运行cfg 门控文件有变更任何 crate 中任何#[cfg(target_os …)]块时交叉 lint 或对照 master 手工审计——macOS 绿灯在此毫无证明力见 .claude/rules/cross-platform.md线类型变更提升PROTOCOL_VERSION并保证cargo test -p openlogi-ipc --test wire_format绿灯见 crates/openlogi-ipc/AGENTS.mdlocale 变更每个crates/openlogi-ui/locales/*.toml与en.toml键一致新键同位置跑cargo test -p openlogi-ui locale校验目录对齐、cargo test -p openlogi-desktop i18n校验目录接线与桌面解析见 .claude/rules/i18n.md之后才git push/force-push 到 PR 分支。运行应用与开发环境开发运行cargo run -p openlogi-desktop——cargo runner 会把构建包进target/dev/OpenLogi.app与打包用的身份、helper、plist 表一致。macOS GUI 构建需要完整 XcodeGPUI 的 Metal shaderdevenv 存在时会设置环境shader 编译失败就direnv reloadcargo build不会刷新该 bundle二次实例会因单例锁退出先退出旧实例再重新run每次 dev run 会先停掉上次遗留的 agent 与 overlay它们由 LaunchServices 启动、有自己的 TCC 身份存活 agent 约 20 秒后自我重启再启动刚构建的 agent 并等待其 socket保证 GUI 首次 IPC 连接成功。OPENLOGI_DEV_AGENT0可完全关闭此行为无硬件cargo run -p openlogi-agent --bin openlogi-agent-mock通过 dev IPC socket 提供脚本化库存实现在 mock_agent.rsGUI 无需修改即可运行、生产应用保持不动。机制、dev 档案与 mock 边界详见 docs/DEVELOPMENT.md。Rust 标准edition 2024、MSRV 与共享 lint 表Edition 2024MSRV 当前 stable1.98共享工作区 lint 表集中在根 Cargo.toml 的[workspace.lints]unsafe_code全工作区 deny但非 forbidFFI crate 可局部#[expect(unsafe_code, reason …)]显式豁免clippy pedantic 组为 warn另有unwrap_used、expect_used、allow_attributes、allow_attributes_without_reason、cast_*、ptr_as_ptr、exit、tests_outside_test_module、undocumented_unsafe_blocks等显式 lint。完整标准lint 表逐日含义、类型化不变式风格、重构/依赖/模块布局规则在 .claude/rules/rust.md。Git 与 GitHub 工作流提交与分支Conventional Commitstype(scope): imperative lowercase description。类型有feat fix refactor chore docs ci perf style build testscope 为 crate 短名gui agent hidpp hid core hook ipc cli assets xtask或横切关注点release ci i18n windows linux macos tray infra。i18n是 scope 而非 type分支自master拉出type/kebab-description。重大或高风险工作在 worktree 中进行琐碎修复可直接上 master提交小而聚焦不相关关注点拆分提交任何 rebase 前必须先git fetch upstream master或 origin——基于刷新后的 tip而非过期的本地 master。PR 合并与正文合并默认squash手写主题行type(scope): description (#N)release-plz 要解析它合并提交已禁用仅当分支上每个提交都达到可发布质量时才 rebase-merge。合并前等 Greptile 评审检查与 CI评审发现要修复、回复、解决不能无视。PR 正文结构## Summary、## Changes逐 crate 要点、## Testing列出实际运行的确切命令 硬件验证状态——确为未在硬件上运行时测试要如实写出真实硬件验证是维护者的职责因此每个修复 PR 都要说明如何测试结尾Fixes #N。UI 变更附截图。所有 GitHub 产物PR 标题/正文、提交、issue、评审、评论一律英文绝不给提交/PR/issue 加 AI 署名Generated with …、AI 合著尾注包括采用贡献者作品时不代维护者对外发帖或公开回复——草拟文本待批准公开草稿要简短、随意、聚焦问题。贡献者 PR 采用收养而非拒绝检查maintainerCanModify在 worktree 中 rebase 到新鲜master修复评审发现在 rebase 后的 tip 上跑适用本地门禁Rust 相关 rebase 走全量层级再推到 fork 分支保留作者身份重新安置作品时加Co-authored-by。分支落后过多时 squash-then-rebase 亦可。CI / Actions 注意事项CI 并发按分支隔离ci-${{ workflow }}-${{ ref }}且cancel-in-progress: true。批准或重跑分支上旧 SHA的工作流会取消当前 head 的运行——只批准/重跑head_sha等于 PR 当前 head 的工作流。force-push 后等新运行不要重新批准更早提交遗留的action_required任务。首次 fork 的 PR 可能停在action_required直到维护者批准工作流运行——这正常本地门禁绿灯前仍不 push。发布管线release-plz 驱动统一版本发布由 release-plz 驱动统一工作区版本、一个根 CHANGELOG.md绝无逐 crate changelog、只有一个v{version}标签且只由 release-plz 创建——绝不手工建 tag。已发布的 GitHub Release 不可变绝不在已有 tag 上重跑失败的发布任务或重新分发。release-plz.toml 是版本契约不可删减。配置要点与源码注释吻合pr_branch_prefix release-plz/semver_check false应用型项目不需要 API 破坏分析噪音git_tag_enable false统一由根 crate 出 taggit_release_enable falseGitHub Release 由 .github/workflows/release.yml 的 softprops 以草稿创建、上传 DMG 与校验和、最后发布——release-plz 直接发布会因资产未附而不可变changelog_update false根 changelog 由 git-cliff 经.config/cliff.toml编写release_always false仅 release PR 合并时发布。全部发布 crate 通过version_group openlogi锁定步调最高下一版本胜出app cratedesktop/ui/overlay/agent 等标记release false; publish false。子系统规则与任务技能索引AGENTS.md末尾提供了一张改什么、读什么的索引表是所有代理改动前的强制阅读清单区域规则文件本地复现 CI jobci.yml 每个 job → 命令.claude/rules/ci.md任何*.rs/Cargo.toml工作区 Rust 标准.claude/rules/rust.mdcrates/openlogi-desktop/**、crates/openlogi-ui/**、crates/openlogi-overlay/**GPUI.claude/rules/gui.mdcrates/openlogi-desktop/**该 crate 自身契约与地图crates/openlogi-desktop/AGENTS.mdlocale 目录/协商与各二进制的rust_i18n::i18n!接线.claude/rules/i18n.mdcrates/openlogi-ipc/**及所有 serde 类型上线的 crateopenlogi-agent-core、openlogi-agent、openlogi-core、openlogi-hidcrates/openlogi-ipc/AGENTS.mdcfg 门控平台代码hook/inject/hid、camera、agent autostart/resume.claude/rules/cross-platform.mdcrates/openlogi-hidpp/**hidpp硬分叉crates/openlogi-hidpp/AGENTS.mdcrates/openlogi-device/**、crates/openlogi-hid/**HID 层接缝crates/openlogi-device/AGENTS.mdcrates/openlogi-hook/**事件 tapcrates/openlogi-hook/AGENTS.mdxtask/**、packaging/**、.github/scripts/**xtask/AGENTS.md另见 xtask/README.mdmacOS 原生 FFI该规则携带权威路径清单.claude/rules/objc-ffi.md除路径规则外还有按任务而非路径触发的技能处理 macOS 上无设备 / Failed to open device / 该授哪个权限的报告、以及任何权限、helper 启动或 bundle 签名代码的改动应阅读 .claude/skills/openlogi-macos-permissions/SKILL.md其diagnose.sh脚本可协助诊断权限问题。.claude/skills/下其余内容是对.agents/skills/的逐开发者符号链接不属于项目本体。结语作为工程模板的代理契约OpenLogi 的这份代理指南展示了AI 协作时代大型 Rust 桌面项目如何把架构知识沉淀为机器可执行的契约crate 表让代理在任何改动前先理解进程边界与依赖方向分级门禁快速路径 → 受影响包 → 全量 → CI 复现在保证质量的同时维持迭代速度append-only 的 IPC 线格式从协议层面杜绝破坏性变更release-plz 的统一版本策略让发布成为确定性流程。对想要深入了解 HID 设备层、GPUI 前端或三进程 IPC 架构的开发者而言AGENTS.md 与其指向的.claude/rules/文件构成了一个可循迹、可验证的工程导航系统。【免费下载链接】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 代理开发指南：从架构地图到发布管线的 Rust 工程实践
OpenLogi 代理开发指南从架构地图到发布管线的 Rust 工程实践【免费下载链接】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 仓库根目录的 AGENTS.md即 CLAUDE.md 通过AGENTS.md导入的代理契约文档为骨架结合工作区源码、Cargo 清单、CI 工作流与发布配置系统讲解这个 Rust 版 Logitech Options 替代品的架构设计、构建验证流程、代码规范与发布管线。读完你将掌握 OpenLogi 的 crate 边界划分、三进程通信模型、分级质量门禁以及从提交到发布的完整工程纪律。OpenLogi 是一个用 Rust 编写的、本地优先的 Logitech Options 替代品支持按钮重映射、DPI、SmartShift 与按应用配置文件覆盖 Logitech HID 设备Bolt/Unifying 接收器、蓝牙直连、有线连接无账号、无遥测、纯 TOML 配置。macOS 与 Linux 是一等公民Windows 是较新但已可交付的移植。代码采用 MIT/Apache-2.0 双许可证design/目录下的品牌资产为专有。文档定位CLAUDE.md 与 AGENTS.md仓库根目录的 CLAUDE.md 全文只有一行AGENTS.md——这是 Claude Code 的内容导入指令指向开发者手册 docs/DEVELOPMENT.md 之外的代理契约文件AGENTS.md。该文件是代理Agent与项目协作的全局工作流契约包含四大部分架构地图19 个工作区 crate 的角色与进程边界证据纪律问题必须回溯到根因并验证构建、运行、验证从快速迭代到推送前全量门禁的分级检查策略工程规范Rust 标准、Git/GitHub 流程、发布管线与子系统规则索引。文件结尾明确所有子系统专属规则都放在.claude/rules/下的路径作用域规则文件中AGENTS.md只承载全局工作流改到对应区域前必须阅读匹配的规则文件。架构地图三进程模型与 crate 边界OpenLogi 的运行时架构核心是一个长期运行的agent进程独占输入钩子与 HID I/OGUI与overlay是纯粹的 IPC 客户端CLI 是诊断例外openlogi list优先使用兼容的 agent 快照无可用时回退到直接枚举硬件诊断子命令则直接访问设备。仓库 Cargo.toml 定义了 20 个 workspace 成员各 crate 的角色如下Crate角色crates/openlogiCLI 二进制——对openlogi-cli的薄封装crates/openlogi-core纯类型TOML 配置、设备模型、动作目录、locale 协商。无 I/O、无 async按 feature 门控的主机读取fs、localecrates/openlogi-device-registry纯硬件身份注册表接收器协议与独立设备驱动元数据crates/openlogi-hidpphidpp协议 crate 的硬分叉库名为hidpp0BSD 许可crates/openlogi-hidpp-derive为openlogi-hidppfeature 样板代码服务的私有 derive 宏crates/openlogi-deviceHID 设备层枚举、探测、写入、会话、配对。不感知宿主针对HidBackend表达crates/openlogi-hid将设备层接到本机async-hid传输、macOS Input Monitoring、磁盘探测缓存crates/openlogi-camera跨平台 Logitech UVC 枚举、采集、控制与相机权限 APIcrates/openlogi-assets设备渲染注册表 OpenLogi 资产镜像的缓存拉取crates/openlogi-cliCLI 分发可用时走 agent 库存另加直接硬件诊断crates/openlogi-hookOS 输入捕获CGEventTap / evdevuinput / WH_MOUSE_LLcrates/openlogi-injectOS 输入合成CGEvent / uinputMPRIS / SendInputcrates/openlogi-agent-core共享 agent 编排钩子运行时、HID 写入、DPI 循环、Actions Ring 会话状态crates/openlogi-ipctarpc IPC 契约src/ipc.rs 本地 socket 传输agent 与其客户端共用crates/openlogi-agentopenlogi-agent二进制——运行时 HID/输入服务端crates/openlogi-permissions隐私权限状态 系统设置深链macOS TCC 读取、Linux 设备文件探测。只读从不主动弹窗crates/openlogi-ui两个 GPUI 进程共享的表现层圆环几何/图标、GPUI 资产源、共享 locale 目录。依赖gpui但不依赖gpui-componentcrates/openlogi-desktopGPUI gpui-component 桌面应用——轮询 agent不做 HID/输入 I/Ocrates/openlogi-overlayopenlogi-overlay二进制——光标居中 Actions Ring纯 IPC 客户端xtaskcargo xtask维护任务打包、发布清单三个关键架构约束值得展开1. 版本化且只追加append-only的 IPC 线格式。IPC 客户端与 agent 通过interprocess本地 socket 上承载的 tarpc/bincode 通信。根据 crates/openlogi-ipc/AGENTS.mdbincode 编码枚举的变体索引、tarpc 编码方法顺序因此线格式是位置化的——服务方法只能追加protocol_version必须永远是方法 0接管握手要跨版本探测它。任何线格式变更都要提升 ipc.rs 中的PROTOCOL_VERSION当前为 29连接时严格相等校验并重新生成 tests/wire_format.rs 中的黄金测试。注意 serde 编码的是声明索引而非#[repr(u8)]判别值两者可能不一致线格式表面比该 crate 更宽——openlogi-core的设备模型、动作、配置与openlogi-hid的写入错误类型都搭载在 RPC 载荷内同样受此约束。2. overlay 是 GUI 的兄弟进程。三个进程随 bundle 一起发布但 overlay 链接的是openlogi-ui从不链接openlogi-desktop。两者都需要的东西必须进openlogi-ui而每次向openlogi-ui添加依赖也会进入 overlay——这正是openlogi-ui不依赖gpui-component的原因见 crates/openlogi-desktop/AGENTS.md。3. 平台代码按 cfg 门控。每个 crate 通过[target.cfg(target_os …).dependencies]做平台区分.claude/rules/cross-platform.md是 cfg 门控平台代码的契约.claude/rules/objc-ffi.md维护 macOS 原生 FFI 的权威文件清单。从源码看CLI 是唯一可发布到 crates.io 的例外路径openlogi-ipc因 CLI 依赖其契约而进入发布依赖闭包见 release-plz.toml 注释。证据纪律与根因修复AGENTS.md 对问题处理提出明确要求把每个 issue、用户报告、评审意见都当作声明claim在接受其诊断前必须对照当前 head 与最直接的可用证据验证。修复必须落在根因所属模块及其生命周期边界上——不允许用 shim、回退或一次性抽象去掩盖一个损坏的 owner 或生命周期。这一纪律也体现在单例锁等工程细节上desktop 应用二次启动会因单例锁退出开发时必须先退出旧实例再重新run不能把改动没生效误判为 UI 渲染问题。构建、运行、验证分级的质量门禁工具链与 devenvNix/devenv 是可选项——rustup rust-toolchain.tomlstable channel含 rustfmt 与 clippy 组件即可。若安装了 devenvdirenv 会加载它否则.envrc仅打印提示、不动 PATH系统cargo照常工作。devenv 激活时 cargo 可能只在 shell 内可用需在仓库根运行命令或direnv exec . …git 同样如此钩子需要 cargocargo check -p openlogi-core # cargo 仅在 devenv 内时 direnv exec . cargo check -p openlogi-core direnv exec . git commit …工作区根 Cargo.toml 使用 resolver 3、edition 2024rust-version为 1.98跟随当前 stable。default-members只保留crates/openlogi避免裸cargo build拖入 GPUI 的 Metal shader 工具链。迭代期快速路径先定义一个证明文档明确反对每次编辑后跑全工作区 Clippy/测试/rustdoc——宽泛检查是最终门禁而非内层开发循环。正确顺序是先定义单一证明选择能证明预期结果的聚焦测试、编译目标或运行时行为内层循环只跑该证明行为用cargo test -p crate test-filterAPI/类型反馈用cargo check -p crate一行或纯文档改动不触发 Clippy代码稳定后对实际改动的 crate 各跑一次格式化检查、相关测试与cargo clippy -p crate --all-targets -- -D warnings共享公共 API 用cargo check验证受影响消费者仅在 push 前根据最终 diff 选择受影响包门禁或全量门禁。本地门禁push 前的硬性关卡受影响包层级——仅当同时满足以下条件时才允许使用自上次全量门禁以来没有 rebase 过 Rust 提交、没有解决过冲突diff 不涉及任何工作区级构建/校验输入任何Cargo.toml、build.rs、Cargo.lock、rust-toolchain.toml、.cargo/**、lint/格式/钩子配置、devenv 配置、CI 工作流。此时对整个受影响包集合改动包 传递依赖它们的包用cargo tree --workspace --target all --invert changed推导运行export RUSTFLAGS-D warnings cargo fmt --all -- --check cargo clippy -p affected… --all-targets -- -D warnings cargo test -p affected…全量层级——在 Rust 相关 rebase/冲突解决后、任何工作区级输入变更时、受影响集合无法可靠推导时或子系统规则明确要求时export RUSTFLAGS-D warnings # CI 全局设置此值clippy 的 -D warnings 与之不同 cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace RUSTDOCFLAGS-D warnings cargo doc --workspace --no-deps \ --document-private-items --exclude openlogi-ui --exclude openlogi-desktop \ --exclude openlogi-overlay --exclude openlogi-agent # 或devenv tasks run openlogi:check # 本机可复现的每个 CI jobcargo xtask cirustdoc 步骤镜像 CI 的rustdoc (non-GUI crates)任务能捕获其他三步发现不了的故障失效的 intra-doc 链接既不是编译错误也不是 clippy lint。GPUI crate 被排除是因为文档化它们会拖入整个图形工具链其余 crate 通过排除而非列举覆盖新 crate 默认即被文档化。本地复现每个 CI job本地门禁只是宿主 OS 子集完整流水线见 .github/workflows/ci.ymlLinux clippy、macOSLinux MSRV、rustdoc、排除 desktop 的 Linux 测试、macOS--all-targets测试、typos、cargo-deny、Windows clippy、wasm 可移植性、shell lint。macOS 绿灯不等于矩阵全绿用cargo xtask复现本机可跑的所有 jobcargo xtask ci cargo xtask ci --list # job → 命令对照表 cargo xtask ci rustfmt clippy # 单 job名称与 CI 一致 # 或devenv tasks run openlogi:ci跳过某个 jobOS 不对、缺cargo-deny、无 MSRV 工具链不算通过——必须在 PR Testing 部分如实声明未运行。完整映射见 .claude/rules/ci.md。prek 钩子兜底而非替代prek.toml 配置了 Git 钩子管理器commit 阶段运行内置的 trailing-whitespace、end-of-file-fixer、check-yaml、check-toml、check-merge-conflict 与 check-added-large-files^design/排除——1024² 的图标主文件合法超过 500 KB 默认阈值外加 typospre-push 阶段运行cargo fmt --all --、全工作区 Clippycargo clippy --workspace --all-targets -- -D warnings与 rustdoc排除 GPUI 四 crate。钩子是兜底rebased 之后仍需自己跑门禁。Push 清单代理专用rebase/合并冲突完全解决——无残留、无半移植 API最终树上适用层级门禁绿灯非 Rust diff 走非 Rust 检查无全量触发条件走受影响包层级否则全量diff 要求的额外流水线 job 按名运行cargo xtask ci job…跳过的 job 如实声明未运行cfg 门控文件有变更任何 crate 中任何#[cfg(target_os …)]块时交叉 lint 或对照 master 手工审计——macOS 绿灯在此毫无证明力见 .claude/rules/cross-platform.md线类型变更提升PROTOCOL_VERSION并保证cargo test -p openlogi-ipc --test wire_format绿灯见 crates/openlogi-ipc/AGENTS.mdlocale 变更每个crates/openlogi-ui/locales/*.toml与en.toml键一致新键同位置跑cargo test -p openlogi-ui locale校验目录对齐、cargo test -p openlogi-desktop i18n校验目录接线与桌面解析见 .claude/rules/i18n.md之后才git push/force-push 到 PR 分支。运行应用与开发环境开发运行cargo run -p openlogi-desktop——cargo runner 会把构建包进target/dev/OpenLogi.app与打包用的身份、helper、plist 表一致。macOS GUI 构建需要完整 XcodeGPUI 的 Metal shaderdevenv 存在时会设置环境shader 编译失败就direnv reloadcargo build不会刷新该 bundle二次实例会因单例锁退出先退出旧实例再重新run每次 dev run 会先停掉上次遗留的 agent 与 overlay它们由 LaunchServices 启动、有自己的 TCC 身份存活 agent 约 20 秒后自我重启再启动刚构建的 agent 并等待其 socket保证 GUI 首次 IPC 连接成功。OPENLOGI_DEV_AGENT0可完全关闭此行为无硬件cargo run -p openlogi-agent --bin openlogi-agent-mock通过 dev IPC socket 提供脚本化库存实现在 mock_agent.rsGUI 无需修改即可运行、生产应用保持不动。机制、dev 档案与 mock 边界详见 docs/DEVELOPMENT.md。Rust 标准edition 2024、MSRV 与共享 lint 表Edition 2024MSRV 当前 stable1.98共享工作区 lint 表集中在根 Cargo.toml 的[workspace.lints]unsafe_code全工作区 deny但非 forbidFFI crate 可局部#[expect(unsafe_code, reason …)]显式豁免clippy pedantic 组为 warn另有unwrap_used、expect_used、allow_attributes、allow_attributes_without_reason、cast_*、ptr_as_ptr、exit、tests_outside_test_module、undocumented_unsafe_blocks等显式 lint。完整标准lint 表逐日含义、类型化不变式风格、重构/依赖/模块布局规则在 .claude/rules/rust.md。Git 与 GitHub 工作流提交与分支Conventional Commitstype(scope): imperative lowercase description。类型有feat fix refactor chore docs ci perf style build testscope 为 crate 短名gui agent hidpp hid core hook ipc cli assets xtask或横切关注点release ci i18n windows linux macos tray infra。i18n是 scope 而非 type分支自master拉出type/kebab-description。重大或高风险工作在 worktree 中进行琐碎修复可直接上 master提交小而聚焦不相关关注点拆分提交任何 rebase 前必须先git fetch upstream master或 origin——基于刷新后的 tip而非过期的本地 master。PR 合并与正文合并默认squash手写主题行type(scope): description (#N)release-plz 要解析它合并提交已禁用仅当分支上每个提交都达到可发布质量时才 rebase-merge。合并前等 Greptile 评审检查与 CI评审发现要修复、回复、解决不能无视。PR 正文结构## Summary、## Changes逐 crate 要点、## Testing列出实际运行的确切命令 硬件验证状态——确为未在硬件上运行时测试要如实写出真实硬件验证是维护者的职责因此每个修复 PR 都要说明如何测试结尾Fixes #N。UI 变更附截图。所有 GitHub 产物PR 标题/正文、提交、issue、评审、评论一律英文绝不给提交/PR/issue 加 AI 署名Generated with …、AI 合著尾注包括采用贡献者作品时不代维护者对外发帖或公开回复——草拟文本待批准公开草稿要简短、随意、聚焦问题。贡献者 PR 采用收养而非拒绝检查maintainerCanModify在 worktree 中 rebase 到新鲜master修复评审发现在 rebase 后的 tip 上跑适用本地门禁Rust 相关 rebase 走全量层级再推到 fork 分支保留作者身份重新安置作品时加Co-authored-by。分支落后过多时 squash-then-rebase 亦可。CI / Actions 注意事项CI 并发按分支隔离ci-${{ workflow }}-${{ ref }}且cancel-in-progress: true。批准或重跑分支上旧 SHA的工作流会取消当前 head 的运行——只批准/重跑head_sha等于 PR 当前 head 的工作流。force-push 后等新运行不要重新批准更早提交遗留的action_required任务。首次 fork 的 PR 可能停在action_required直到维护者批准工作流运行——这正常本地门禁绿灯前仍不 push。发布管线release-plz 驱动统一版本发布由 release-plz 驱动统一工作区版本、一个根 CHANGELOG.md绝无逐 crate changelog、只有一个v{version}标签且只由 release-plz 创建——绝不手工建 tag。已发布的 GitHub Release 不可变绝不在已有 tag 上重跑失败的发布任务或重新分发。release-plz.toml 是版本契约不可删减。配置要点与源码注释吻合pr_branch_prefix release-plz/semver_check false应用型项目不需要 API 破坏分析噪音git_tag_enable false统一由根 crate 出 taggit_release_enable falseGitHub Release 由 .github/workflows/release.yml 的 softprops 以草稿创建、上传 DMG 与校验和、最后发布——release-plz 直接发布会因资产未附而不可变changelog_update false根 changelog 由 git-cliff 经.config/cliff.toml编写release_always false仅 release PR 合并时发布。全部发布 crate 通过version_group openlogi锁定步调最高下一版本胜出app cratedesktop/ui/overlay/agent 等标记release false; publish false。子系统规则与任务技能索引AGENTS.md末尾提供了一张改什么、读什么的索引表是所有代理改动前的强制阅读清单区域规则文件本地复现 CI jobci.yml 每个 job → 命令.claude/rules/ci.md任何*.rs/Cargo.toml工作区 Rust 标准.claude/rules/rust.mdcrates/openlogi-desktop/**、crates/openlogi-ui/**、crates/openlogi-overlay/**GPUI.claude/rules/gui.mdcrates/openlogi-desktop/**该 crate 自身契约与地图crates/openlogi-desktop/AGENTS.mdlocale 目录/协商与各二进制的rust_i18n::i18n!接线.claude/rules/i18n.mdcrates/openlogi-ipc/**及所有 serde 类型上线的 crateopenlogi-agent-core、openlogi-agent、openlogi-core、openlogi-hidcrates/openlogi-ipc/AGENTS.mdcfg 门控平台代码hook/inject/hid、camera、agent autostart/resume.claude/rules/cross-platform.mdcrates/openlogi-hidpp/**hidpp硬分叉crates/openlogi-hidpp/AGENTS.mdcrates/openlogi-device/**、crates/openlogi-hid/**HID 层接缝crates/openlogi-device/AGENTS.mdcrates/openlogi-hook/**事件 tapcrates/openlogi-hook/AGENTS.mdxtask/**、packaging/**、.github/scripts/**xtask/AGENTS.md另见 xtask/README.mdmacOS 原生 FFI该规则携带权威路径清单.claude/rules/objc-ffi.md除路径规则外还有按任务而非路径触发的技能处理 macOS 上无设备 / Failed to open device / 该授哪个权限的报告、以及任何权限、helper 启动或 bundle 签名代码的改动应阅读 .claude/skills/openlogi-macos-permissions/SKILL.md其diagnose.sh脚本可协助诊断权限问题。.claude/skills/下其余内容是对.agents/skills/的逐开发者符号链接不属于项目本体。结语作为工程模板的代理契约OpenLogi 的这份代理指南展示了AI 协作时代大型 Rust 桌面项目如何把架构知识沉淀为机器可执行的契约crate 表让代理在任何改动前先理解进程边界与依赖方向分级门禁快速路径 → 受影响包 → 全量 → CI 复现在保证质量的同时维持迭代速度append-only 的 IPC 线格式从协议层面杜绝破坏性变更release-plz 的统一版本策略让发布成为确定性流程。对想要深入了解 HID 设备层、GPUI 前端或三进程 IPC 架构的开发者而言AGENTS.md 与其指向的.claude/rules/文件构成了一个可循迹、可验证的工程导航系统。【免费下载链接】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），仅供参考