Horizon开发者指南:从源码构建、测试矩阵到为这个Rust工作区贡献代码

原创2026-11-01 11:02:051,933 阅读

Horizon开发者指南:从源码构建、测试矩阵到为这个Rust工作区贡献代码

Horizon 是一款用 Rust 编写的 GPU 加速终端面板(terminal board),把终端、AI Agent、浏览器和 VNC 桌面全部铺在一块无限画布上。本 Horizon 开发者指南带你走完全流程:如何从源码构建 Horizon、读懂它的测试矩阵,并规范地向上游 Rust 工作区贡献代码。

1️⃣ 先读懂工作区布局:25 个 crate 各司其职

Horizon 是一个 Cargo 工作区,成员清单在根 Cargo.toml 的 members 数组里。版本统一由 <a href="https://link.gitcode.com/i/1bef98df59e5168cf8cf667bb840bf0e" target="_blank">workspace.package] 管理(当前 0.2.7,Rust edition 2024,最低 Rust 1.95,见 [rust-toolchain.toml)。

crate 职责
horizon-core 核心:终端仿真、PTY、Board 与面板管理、配置
horizon-ui 可执行二进制:eframe/egui 应用、画布渲染、输入处理
horizon-browser 等 7 个 browser-* 浏览器面板引擎、MCP 服务、CLI 与协议层
horizon-cloud 等 3 个 cloud-* 云工作区(RunPod、Hetzner 等)与 worker 协议
horizon-cast / horizon-vnc / horizon-device Apple TV 投屏、VNC 查看器与 Device 面板

贡献前建议通读 AGENTS.md——它是所有贡献者(和 AI 代理)的"唯一事实来源",涵盖开发环境、架构说明、代码规范与 CI 要求;README.md 的 Contributing 一节则是最短的入口摘要。

2️⃣ 环境准备清单:Rust 1.95+ 与 Git LFS 是硬门槛

依赖 说明
Rust stable ≥ 1.95 edition 2024,AGENTS.md 有完整的 Prerequisites 清单
Git LFS 仓库内嵌字体等资产走 LFS;若字体仍是 LFS 指针,构建会直接中止
Linux 系统头文件 eframe/wgpu 需要 libxkbcommon、libwayland-dev、libvulkan-dev 等 -dev 包(Debian/Fedora/Arch 命令见 AGENTS.md)
macOS 只需 Xcode Command Line Tools(xcode-select --install)
NASM ≥ 2.15 仅 x86_64 的 AV1 录制需要(rav1e 汇编内核),ARM64 可跳过
CMake + C++ 编译器 仅当你要启用 --features speech(本地语音输入)时

💡 Linux 上最常见的构建失败原因就是缺系统头文件——看到 pkg-config 或链接器报错时,对照安装对应 -dev 包即可。

3️⃣ 三行命令完成源码构建并运行

按 README.md 的 Build from source 流程,最快路径如下:

git clone https://gitcode.com/gh_mirrors/horizon40/horizon
cd horizon
git lfs install
git lfs pull
cargo run --release
  • 想快速迭代就用 target/debug/horizon(debug 构建),官方建议冒烟测试优先用它(AGENTS.md)。
  • 语音输入是编译期选项:cargo speech 等价于 cargo run --release --features speech,需要 CMake 与 C++ 编译器,Linux 还需 ALSA 头文件。
  • 构建失败时先读报错:缺字体 → 补 git lfs pull;缺头文件 → 装系统包;再重试。

4️⃣ 本地测试矩阵:提交前必须跑通的命令

开发中"按改动跑测试",候选版本(candidate)上要完整跑一遍矩阵。核心命令(摘自 AGENTS.md 的 Full local matrix):

cargo fmt --all -- --check
RUSTFLAGS="-D warnings" cargo test --workspace
RUSTFLAGS="-D warnings" cargo test -p horizon-ui --features speech
cargo clippy --all-targets --features speech,trace-profiling -- -D warnings

Clippy 分三层(AGENTS.md):

层级 关键参数 地位
Blocking --all-targets --features speech,trace-profiling 必须通过
Strict 额外 -D clippy::unwrap_used -D clippy::expect_used 必须通过
Pedantic -W clippy::pedantic 仅建议(未来会升级为强制)

两个效率神器:

  • scripts/test-focus.py:根据你改动的文件路径自动推导出"一个 crate + 一个模块"的聚焦测试命令,避免整工作区分钟级的全量编译;
  • cargo-nextest + .config/nextest.toml:比 libtest 快约 3 倍,并把每个超过 20 秒的测试点名暴露出来——慢测试是作者要修的问题,不是机器的属性。

5️⃣ GitHub Actions CI 是怎么切分测试矩阵的

CI 定义在 .github/workflows/ci.yml,主要任务一目了然:

任务 平台 内容
repo-checks / changes Ubuntu fmt、可维护性检查、版本号同步;检测改动输入,纯文档 PR 可跳过编译类任务
clippy Ubuntu 跑上表三层 Clippy
rust-test(Linux x64) Ubuntu 拆成 ui / libs / speech 三个分片并行,共享一份缓存
rust-test(macOS arm64) macOS libs / speech 两个分片,各自独立缓存键;speech 分片还会交叉编译 iOS 目标(horizon-media、horizon-chromecast)
browser-engine / device / browser-harness-tests Ubuntu 浏览器与 Device 子系统的专项测试
snap-build / rust-artifacts Ubuntu Snap 打包与发布产物构建

分片的具体命令在 scripts/ci-cargo-test-shard.sh,其中还包含 Linux 专属的 trusted-tcp-producer、trusted-exposure-gate 两个 feature 通道,以及 examples/cloud-worker 下的 Python 契约测试。

想在本地复刻 CI?官方推荐 localci:它会按你的操作系统挑选 .github/workflows/ci.yml 中匹配的任务在本地执行(localci list 查看任务、localci run repo-checks 跑单项),详见 AGENTS.md。注意:本地通过不等于 CI 通过,最终信号以 GitHub 上精确 head commit 的检查为准。

6️⃣ 第一次贡献:代码规范与 PR 规则

Horizon 的代码质量门槛写得很死(AGENTS.md),新手最容易踩的几条:

  • 类型化错误:用 thiserror 定义错误枚举,库代码禁止 Box<dyn Error> 与 .unwrap();
  • 安全:所有 crate 都是 #![forbid(unsafe_code)](仅 wayland pinch 桥一处受控例外);
  • 文件大小:约 600 行就该考虑拆分,CI 护栏对 horizon-core/horizon-ui 下超过 1000 行的非测试文件直接失败;
  • 性能:渲染热路径(每帧代码)尽量少分配;UI 的布局数学、状态转换下沉到 horizon-core,别在 UI 层重复实现。

开 PR 前的硬性约定(AGENTS.md):

  1. 一个 PR 只交付一个可独立验证的结果;超过 10 个源文件或 1500 行改动就先拆分,不要问;
  2. commit 用简洁祈使句并按需加范围:feat(board):、fix(render):、ci:;一律 squash-merge;
  3. UI 变更的 PR 必须在正文顶部放 GIF——从任务专属的隔离桌面录制、双遍 ffmpeg 调色板、约 6 fps、宽 1000px、小于 10 MB,只出现合成数据,绝不提交进仓库;无 UI 变更则写明 No visible change: 及原因;
  4. 用 scripts/check-pr-readiness.py 预检:python3 scripts/check-pr-readiness.py --title "<标题>" --body <body文件>,它会核对规模阈值、测试规程、双份技能副本等规则;
  5. 每个新功能都要有 STE 简式技术英语的测试规程,放在 docs/testing/procedures/(模板在该目录),保证"另一个代理无需额外上下文也能执行";

跨机冒烟测试通过 PR 评论的 SMOKE-TEST REQUEST/REPORT 协议异步接力(AGENTS.md),等待方轮询 SMOKE-TEST: DONE 标记。

7️⃣ 实用脚本与文档索引

资源 用途
scripts/test-focus.py 按改动路径推导聚焦测试(--print 只打印不执行)
scripts/check-pr-readiness.py PR 标题/正文规则预检
scripts/check-maintainability.sh 本地可维护性护栏
scripts/profile.sh 性能剖析(cargo build --profile profiling --features trace-profiling)
docs/testing/reports/ 历次测试报告存档
docs/release-flow.md tag 驱动的发布流程(scripts/next-version.sh 建议下一版本号)
docs/architecture/maintainability.md 模块边界与护栏说明

小结:git lfs pull + cargo run --release 让你跑起来;fmt/test/三层 Clippy 让你改得放心;读懂 ci.yml 的分片与 localci 让你本地即 CI;守住"一个结果一个 PR、UI 必带 GIF、规程先于功能"三条线,你的第一个贡献就符合这个 Rust 工作区的标准了。

登录后查看全文
horizon