Horizon开发者指南:从源码构建、测试矩阵到为这个Rust工作区贡献代码
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 都是
#; - 文件大小:约 600 行就该考虑拆分,CI 护栏对
horizon-core/horizon-ui下超过 1000 行的非测试文件直接失败; - 性能:渲染热路径(每帧代码)尽量少分配;UI 的布局数学、状态转换下沉到
horizon-core,别在 UI 层重复实现。
开 PR 前的硬性约定(AGENTS.md):
- 一个 PR 只交付一个可独立验证的结果;超过 10 个源文件或 1500 行改动就先拆分,不要问;
- commit 用简洁祈使句并按需加范围:
feat(board):、fix(render):、ci:;一律 squash-merge; - UI 变更的 PR 必须在正文顶部放 GIF——从任务专属的隔离桌面录制、双遍 ffmpeg 调色板、约 6 fps、宽 1000px、小于 10 MB,只出现合成数据,绝不提交进仓库;无 UI 变更则写明
No visible change:及原因; - 用 scripts/check-pr-readiness.py 预检:
python3 scripts/check-pr-readiness.py --title "<标题>" --body <body文件>,它会核对规模阈值、测试规程、双份技能副本等规则; - 每个新功能都要有 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 工作区的标准了。