OpenLogi 本地复现 GitHub Actions CI：用 `cargo xtask ci` 把整条流水线搬到开发者机器上-北京尧图网络

OpenLogi 本地复现 GitHub Actions CI用cargo xtask ci把整条流水线搬到开发者机器上【免费下载链接】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原生、本地优先的 Logitech Options 替代品Rust 实现在 PR 阶段依赖 GitHub Actions 的ci.yml流水线做跨平台校验而本指南讲解的是它的本地映射方案如何用一条cargo xtask ci命令在当前开发机上复现ci.yml中每一个可复现的作业并诚实地区分跑过与跳过。读完本文你将掌握 OpenLogi 完整 CI 作业的本地等价命令、各平台陷阱MSRV、交叉 lint、wasm 可移植性、差异驱动的检查清单以及新增 CI 作业时需要同步维护的四份文件。双源真相为什么ci.yml是唯一事实来源.claude/rules/ci.md这份规则文件其生效路径由文件头 frontmatter 声明覆盖.github/workflows/**、xtask/src/commands/ci.rs、xtask/src/commands/ci/**、.cargo/deny.toml、.config/typos.toml、.editorconfig、rust-toolchain.toml、prek.toml开门见山地定下了一条铁律.github/workflows/ci.ymlis the source of truth for the PR test pipeline.ci.yml是 PR 测试流水线的唯一事实来源而cargo xtask ci是它的本地拷贝。两者必须保持严格同步如果在ci.yml里改了一个run:而不更新本文件和cargo xtask ci就会被当作一个 bug。为防止拷贝漂移xtask 内置了两条漂移检测测试见 xtask/src/commands/ci/jobs/tests.rsci_yml_runs_what_this_runner_runs把ci.yml中折行续接的run:命令还原成单行workflow_commands把\\\n替换为空格并压缩空白再逐一断言那些不依赖宿主机器的作业rustfmt、publish closure、clippy、rustdoc、tests linux、tests macos的每一步命令都出现在工作流文本里。typos、shell、msrv、cargo-deny、clippy (windows)、wasm这六个作业因按机器能力选择调用方式或决定是否可运行被显式排除在比较之外——它们被文档化为代理而非拷贝。every_ci_yml_job_name_resolves从ci.yml的jobs:层级缩进四格的name:提取所有作业名断言Job::resolve都能解析——即新加进工作流但本地 runner 叫不出名字的作业会直接让测试失败。但这两条测试都无法校验本规则文件.claude/rules/ci.md自身所以维护本文件的命令表仍然是人肉职责。两层本地检查完整档与按包收窄档仓库在预推送阶段提供了两层本地门禁gate完整档由 devenv 任务提供是宿主操作系统上的 pre-push 检查上限devenv tasks run openlogi:check这条任务在 devenv.nix 中定义为依次执行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并排除 GPUI 的四个 crate。它覆盖 fmt、clippy、测试、rustdoc 四个维度。按包收窄档定义在 AGENTS.md 的 Local gate 一节当本次 diff 只改动 Rust 代码时先计算受影响包集合——每个被改动的工作区包加上所有传递地依赖它的工作区包用cargo tree --workspace --target all --invert changed求并集。只有满足特定条件如无 rebase、无冲突解决等才允许只对该集合跑收窄检查否则回到完整档。规则文件特别强调了两点边界任何一层都不是流水线本身macOS 上 green 的 clippy 并不编译 Linux 的cfg它也不跑 typos、MSRV、cargo-deny、Windows clippy 或 shell 检查——这些必须回到cargo xtask ci对应的作业。不要声称跳过的作业通过了在 PR 的 Testing 段落里没跑过的作业必须如实标注 not run而不是写成 PASS。快速上手cargo xtask ci的四种用法在仓库根目录执行cargo xtask ci # 每个本机可复现的作业 cargo xtask ci --list # 作业 → 命令对照表 cargo xtask ci rustfmt docs # 指名作业CI 的 name: 或作业 id cargo xtask ci --dry-run # 只打印每个作业的命令不真正执行 direnv exec . cargo xtask ci # cargo 只在 devenv 里时 devenv tasks run openlogi:ci # 等价于上面那条命令命令行参数由 xtask/src/commands/ci.rs 中的Args结构定义--list打印对照表后直接退出--dry-run只打印每个作业将要执行的命令而不执行位置参数JOB接受 CI 的name:或作业 id缺省时运行当前宿主能复现的全部默认作业即ci.yml中所有in_default_run为真的作业按工作流顺序执行。值得一提的实现细节Host在 ci.rs 里是运行期枚举值而非cfg!(target_os …)这样哪个作业需要在哪台机器上跑变成测试可读取的数据而不是只存在于某台机器构建中的分支。--list表格也完全由每个作业的Spec行渲染而来见 xtask/src/commands/ci/list.rs因此新增作业无需单独维护表格代码。CI 环境语义RUSTFLAGS、CARGO_INCREMENTAL、sccacherunner 会设置 CI 的语义级编译器环境——RUSTFLAGS-D warnings这意味着本地 clippy 没暴露的 rustc 警告同样会让 CI 失败。CI 还设置CARGO_INCREMENTAL0并用 sccache 包装 rustc但这两项只改变编译产物的产生与复用方式不改变作业校验的内容。这些常量在源码中是硬编码的const CI_ENV: [(str, str); 3] [ (CARGO_TERM_COLOR, always), (CARGO_INCREMENTAL, 0), (RUSTFLAGS, -D warnings), ];cargo-den 作业则相反地清除sccache根因是 cargo-deny 的元数据探测只调 rustc 而不编译且该作业刻意跳过 sccache 初始化。缓存策略上rust-cache只存 Cargo 的 registry/git 输入cache-targets: false编译器输出完全交给 sccache 拥有PR 读取默认分支的 sccache 对象但不写入自己隔离的 merge-ref 缓存。另外流水线没有 Windows 测试作业——Windows 上只有clippy (windows)。流水线全图CI 作业逐一对照以下是ci.yml中每个作业与其本地等价命令的完整映射谁可以跑列表示该命令在哪些平台上成立CI 作业本地命令谁可以跑rustfmtcargo fmt --all -- --check任何平台typostypos --config .config/typos.toml .任何平台需要typosdevenv shell 已内置publish closurecargo xtask release check-publish任何平台shellgit ls-files -z \| xargs -0 shfmt -f管道进xargs shellcheck与xargs shfmt -d任何平台需要shellcheckshfmt均在 devenv shell 中clippycargo clippy --workspace --all-targets -- -D warningsLinux 才是 CI 作业macOS/Windows 上的宿主 clippy 编译的是不同的cfgMSRV (cargo check, os)RUSTUP_TOOLCHAINrust-version cargo check --workspace --all-targetsmacOS 与 Linuxrust-version取根 Cargo.toml 的rust-version当前为1.98rustdoc (non-GUI crates)RUSTDOCFLAGS-D warnings cargo doc --workspace --no-deps --document-private-items --exclude openlogi-ui --exclude openlogi-desktop --exclude openlogi-overlay --exclude openlogi-agent任何平台tests (linux)cargo test --workspace --exclude openlogi-desktopLinuxtests (macos, arch)cargo test --workspace --all-targetsmacOSCI 矩阵为 arm64macos-latest与 x86_64macos-15-intelcargo-denycargo deny --config .cargo/deny.toml --all-features --manifest-path crates/openlogi/Cargo.toml check任何平台需要cargo-denynix run nixpkgs#cargo-deny -- …同样可行clippy (windows)cargo clippy --workspace --all-targets -- -D warningsWindows其他平台用devenv tasks run openlogi:check-windowsring-free 子集非完整工作区wasm (portable crates)cargo check -p openlogi-hidpp -p openlogi-device --target wasm32-unknown-unknown再cargo check -p openlogi-core --no-default-features --target wasm32-unknown-unknown任何平台需要wasm32-unknown-unknownstddevenv 会安装各作业的源码级细节rustfmt / clippy / rustdoc 的参数在 xtask/src/commands/ci/jobs/steps.rs 中以CLIPPY_ARGS常量和RUSTDOC_EXCLUDES常量存在。rustdoc 作业按排除法而不是按列举法工作只要列出需要排除的 GPUI 四个 crateopenlogi-ui、openlogi-desktop、openlogi-overlay、openlogi-agent新 crate 默认就会被纳入文档检查文档化这些 crate 会拖入整个图形工具链。typos读取 .config/typos.toml它不忽略隐藏目录ignore-hidden false从而覆盖.github、.config排除了翻译语料crates/openlogi-ui/locales/*.toml但保留英文源en.toml、docs/README.*.md与 Crowdin 合并脚本并为协议/领域标识符如PNGs、SWCustomHighligt2、udid与常用技术词lod、mis、scap、unparseable配置了豁免。shell作业用shfmt -f按扩展名 shebang 双通道判定脚本枚举所有被 git 跟踪的脚本再对它们跑shellcheck和shfmt -d。shfmt不带任何打印参数——一旦传了-i、-ci之类的 flagshfmt 就会丢弃 .editorconfig 中的格式化选项。由于基于git ls-files.devenv/里生成的 shell 因未被跟踪而天然排除。publish closure的实质是crates.io 包的所有 normal/build 路径依赖都必须指向注册表版本或另一个可发布的工作区包Spec 的 caveat。cargo-deny以crates/openlogi/Cargo.toml为根--manifest-path正好对应发布到 crates.io 的那组 crate选择它而不是虚拟工作区根是为了避免把 git 锁定的 gpui 树拖进依赖图。本地若无cargo-deny二进制runner 会自动回退到nix run nixpkgs#cargo-deny -- …CARGO_DENY调用链见 steps.rs。两个聚焦套件focused suitesi18n与wire_format不是ci.yml中的独立作业而是测试作业的一部分cargo test -p openlogi-ui locale # 可移植的语料一致性 cargo test -p openlogi-desktop i18n # 桌面端到端按键解析 cargo test -p openlogi-ipc --test wire_format # bincode/tarpc 黄金线格式Linux CI 跑openlogi-ui的可移植语料一致性测试桌面端到端按键解析测试cargo test -p openlogi-desktop i18n只在 macOS CI 上运行。线格式测试对应 crates/openlogi-ipc/tests/wire_format.rs是 IPC 线协议tarpc/bincode的黄金快照。平台陷阱逐一拆解MSRV 陷阱rust-toolchain.toml的 channel 覆盖rust-toolchain.toml 固定了channel stable组件为 rustfmt 与 clippy。rustup优先遵循该文件而不是作业安装的工具链所以 MSRV 作业必须显式设置RUSTUP_TOOLCHAIN到下限版本否则它会在你不知情时静默地检查 stable——CI 里该变量硬编码为1.98见 .github/workflows/ci.yml。本地复现必须采用同样的方式。steps.rs 的msrv实现还处理了三种环境有 rustup 且能安装/解析该下限时给cargo check挂上RUSTUP_TOOLCHAINfloor没有 rustup如 Nix 工具链但当前 rustc 已经是1.98.x时直接跑并加 note两者都不满足时跳过并提示rustup toolchain install 1.98。在 macOS 上跑 Linux 的 clippy / testsmusl 交叉配方macOS 上的宿主 clippy不是CI 的clippy作业。要覆盖 Linux cfgcamera 之外文档给出了 musl 交叉检查配方cargo clippy --target aarch64-unknown-linux-musl \ -p openlogi-hook -p openlogi-inject -p openlogi-hid -p openlogi-hidpp \ -p openlogi-core -p openlogi-agent -p openlogi-agent-core -p openlogi-ipc \ -p openlogi-permissions --all-targets -- -D warnings注意openlogi-camera的 Linux 后端依赖内核头文件无法从 macOS 交叉编译细节见 .claude/rules/cross-platform.md。Windows clippy 的替身ring-free 交叉 lintCI 在windows-latest上原生 lint 整个工作区而在其他平台上cargo xtask ci的clippy (windows)作业变成代理对 8 个携带 Windows 代码的 crate 做x86_64-pc-windows-gnu目标的交叉 lintclippy --target是纯 check不需要链接器。这个列表WINDOWS_LINT_CRATES见 steps.rs刻意排除了 ring 系openlogi-{assets,cli}与根openlogi拉入 ureq → ring其curve25519.c在无 mingw 时无法交叉编译而它们又没有 Windows 专属代码剩余部分由 CI 原生覆盖。GUI crate 因 GPUI 没有 Windows 后端同样排除。实现上还处理了一个隐蔽问题runner 优先调用cargo-clippy clippy而非cargo clippy因为 cargo 会先从$CARGO_HOME/bin解析外部子命令——在有 rustup 的机器上cargo clippy会用 rustup 的 clippy 配合当前 shell 的 cargo这可能指向不同的编译器且在 rustup 工具链缺 windows-gnu std 时直接失败。wasm 可移植性检查无 OS 可依赖的事实声明wasm作业不是任何要发布的东西——它不产生 wasm 产物。选wasm32-unknown-unknown正是因为目标下面没有任何 OS一个悄悄长宿主依赖文件系统、随机源、线程的 crate 会在这里编译失败而在别处都不会暴露。源码注释明确指出std::thread::spawnhidpp 读循环与tokio::time这类运行时失败是它抓不到的——它只是 check。可移植 crate 用列举法声明WASM_PORTABLE_CRATES与 rustdoc 的排除法相反可移植性是需要赚取并保持的属性新 crate 默认不可移植。openlogi-core只有在关掉fsfeature 时才合格——该 feature 就是配置文件而配置文件需要文件系统——所以它用--no-default-features单独跑一轮。runner 会先探测 sysroot 里是否存在wasm32-unknown-unknownstd缺失则跳过并提示rustup target add wasm32-unknown-unknown。跳过不是通过Summary 的语义ci.rs 的Summary把结果分为三类passed、failed、skipped。一个作业在本机不可复现时输出SKIP 作业 — 原因最终汇总打印---- N passed, M failed, K skipped ----并列出 Skipped 名单末尾固定一行A skipped job is not a pass. Name it as not run in the PR Testing section.跳过不是通过请在 PR 测试段落中标注为未运行。这是整套工具的核心诚实性设计沉默不等于通过。此外一个作业的多个步骤即使某一步失败也会全部执行shell 作业要同时汇报 shellcheck 与 shfmt 的发现。改了什么就跑什么差异驱动的检查清单规则文件给出了一张diff → 检查的速查表PR 提交前按此选择本地验证改动跑什么任何 Rust 改动AGENTS.md 中选定的 local-gate 档pre-push 钩子总是跑全工作区 Clippy 与非 GUI rustdoccrate 发布标志、工作区路径依赖、release-plz.tomlpublish-closure任何*.sh、带 shell shebang 的文件、.editorconfigshellprek 钩子在提交时跑同样的两个工具#[cfg(target_os …)]、hook/inject/hid/camera 平台文件clippy-windows代理 linux-musl 配方做不到就明说crates/openlogi-hidpp/**、crates/openlogi-device/**、crates/openlogi-core/**或它们新增的依赖wasm——这些 crate 必须能在无 OS 环境下继续构建Cargo.lock/.cargo/deny.toml/ 新依赖cargo-denyrust-version或新稳定的 APIMSRVrustdoc / 移动的 trait impl / hidpp deriverustdoccrates/openlogi-ipc/**或线类型cargo test -p openlogi-ipc --test wire_formatcrates/openlogi-ui/locales/**cargo test -p openlogi-ui locale二进制接线或桌面解析有变时再跑cargo test -p openlogi-desktop i18ndevenv.nix/.envrc/devenv.lockdevenv CInix fmt -- --check devenv.nix和devenv --no-tui shell -- trueflake.nix/flake.lock/packaging/linux/**Nix CInix fmt -- --check flake.nix devenv.nix packaging/linux/package.nix packaging/linux/nixos-module.nix和nix flake check --all-systems --no-build --show-tracextask/**/packaging/**对应平台的 unsignedcargo xtask打包命令Build 工作流不属于cargo xtask ci三条不在ci.yml里的 PR 流水线以下工作流不是ci.yml的一部分也不在默认运行内Nix CI路径过滤先做求值格式化再在 x86_64-linux 与 aarch64-linux 上nix build包。本地等价命令见上表 Nix 行完整nix build匹配 Linux 上的构建作业。devenv CI路径过滤格式化devenv.nix并执行devenv --no-tui shell -- true。Build在每个 PR 上构建未签名安装包。只有当 diff 触及打包时才运行对应的cargo xtask打包命令。另外本地的 prek 钩子prek.toml与 CI 保持着同样的纪律cargo-fmt、cargo-clippypre-push 阶段因为它要编译整个工作区、cargo-rustdocsh -c包裹以传入RUSTDOCFLAGS同样排除 GPUI 四个 crate、shellcheckshfmt --write同样排除.envrc保持与 CI 检查集合一致以及 typos 钩子本地可带--write-changes自动修复。新增一个 CI 作业三步走与四份文件当你要在流水线里加作业时规则要求同步维护四处否则要么漂移测试失败、要么别人无法本地复现在 xtask/src/commands/ci/jobs.rs 加一个Job变体及其Spec行name、aliases、hosts、caveat在 xtask/src/commands/ci/jobs/steps.rs 加它的步骤并在本文档的命令表加一行。--list从Spec行自我渲染无需编辑every_ci_yml_job_name_resolves在Spec行没响应工作流的name:之前会一直失败。Spec行就是决定主机跳过的唯一依据——不要在作业步骤里用cfg!(target_os …)。若新作业的命令在所有平台一致把它加进ci_yml_runs_what_this_runner_runs这样任一份拷贝里的笔误都会让测试失败。如果它属于宿主 OS 的 pre-push 门禁同步更新 devenv.nix 的openlogi:check任务与 AGENTS.md 的 Local gate。跑一遍验证用cargo xtask ci --dry-run确认计划输出再实际执行一次确认通过。这套工作流即事实来源、runner 即拷贝、测试锁漂移的设计让 OpenLogi 在横跨 Linux/macOS/Windows 与 wasm 目标的 CI 矩阵下仍能保证每一位贡献者在自己机器上看到的检查与 CI 看到的完全一致——包括那些诚实的跳过。【免费下载链接】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 本地复现 GitHub Actions CI：用 `cargo xtask ci` 把整条流水线搬到开发者机器上

相关推荐

Graphite 如何用 node 宏创建一个带默认值、滑杆与类别的新节点？

FunASR llama.cpp/GGUF 运行时 vs whisper.cpp：中文语音识别 CPU 基准测试全解（数据、指标口径与内置 FSMN-VAD 实现）

Ruffle 浏览器扩展 ruffle-extension 深度指南：自动替换网页 Flash 内容、版本协商与 SWF 劫持机制

更多资讯

像老乡鸡那样做香辣鸡杂：炖菜标准化配方、鸡杂料与分步炖煮流程全解析

Transformer与MoE架构：大模型演进与核心技术解析

Zulip Delighted 集成指南：将客户满意度调查反馈实时同步到团队聊天

GoFr vs Fiber：性能导向的 fasthttp 框架与生产级全栈框架的选型对比

MaaAssistantArknights Issue Bot 使用指南：自动标签、手动触发命令与 issue-checker 配置解析

Wasp 社交内容技能深度解析：用六步逆向工程框架提取爆款内容模式

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？