herdr-gpui 贡献指南：justfile 工作流、CI 约定与严格的 1000 行文件限制如何执行-平芜编程栈

【免费下载链接】herdr-gpui

Native client for Herdr on macOS, Linux, and Windows, built with Rust and GPUI. View terminal sessions, workspaces, Git worktrees, and agent activity through your local Herdr daemon.

项目地址：https://gitcode.com/gh_mirrors/he/herdr-gpui

点击查看免费下载

herdr-gpui 是基于 Rust 和 GPUI 构建的 Herdr 原生桌面客户端，覆盖 macOS 与 Linux，让你通过本地 daemon 查看终端会话、工作区、Git worktree 与 Agent 活动。这份herdr-gpui 贡献指南拆解它的三大工程机制：justfile 工作流如何一键完成构建与验证、CI 约定在各平台检查了什么，以及严格的1000 行文件限制是如何被强制执行、不留例外的。

🚀 开始之前：两个前置条件

安装 Herdr daemon：本仓库只是 daemon 的原生客户端，不安装、不停止、不升级 daemon；daemon 本身的 bug 应反馈给上游。
平台现状：macOS 为完整支持，Linux（x86_64 / ARM64）已纳入 CI 与发布构建，Windows 为实验性，无发布构建。

克隆仓库并搭建环境：

git clone https://gitcode.com/gh_mirrors/he/herdr-gpui cd herdr-gpui bash scripts/install-linux-deps.sh # 仅 Ubuntu 24.04 需要

工具链被 rust-toolchain.toml 固定为 Rust 1.96.1，mise.toml 镜像同一版本——请勿顺手升级。之后：

just run # 优化构建并启动（日常交互用这个） just run-debug # 未优化构建，终端密集时明显更慢

🛠️ justfile 工作流：核心命令速查

整个开发循环围绕 justfile 组织，just无参数时直接列出全部命令。最常打交道的几个：

命令	作用
`just format`	`cargo fmt --all`，全工作区格式化
`just ci`	与 CI 完全等价的本地门禁（见下节）
`just lint`	clippy 全 target 全 feature + 无默认 feature 各一遍，`-D warnings`
`just test`	默认 feature 与全 feature 两轮测试
`just check-file-size`	检查是否有源码文件超过 1000 行
`just hooks`	每个 clone 执行一次，安装`commit-msg`钩子
`just check-commits`	手动按 CI 规则检查提交信息
`just changelog-unreleased`	预览未发布的变更日志
`just test-live /path/to/herdr`	实时集成测试（自起隔离 daemon）
`just test-gui /path/to/herdr`	打开真实原生窗口的 GUI 测试
`just test-sidebar`	原生字体/字形回归测试
`just test-perf`	release 模式场景性能预算

开 PR 前只需两步，见 CONTRIBUTING.md：

just format just ci

⚙️ CI 约定：`just ci`到底检查了什么

ci是一条责任链（justfile）：format-check → check-file-size → lint → test → test-mockup-wait。

远端 CI 定义在 .github/workflows/ci.yml，按 job 依次为：

zizmor：审计 workflow 文件本身，防注入、防过度权限、防未固定版本的 action；
commits：检查 PR 中每一笔提交的主题是否符合约定（下节详述），并用 scripts/ci-changes.sh 判断本次改动是否涉及代码——纯文档 PR 会跳过原生构建检查，但提交信息门禁始终运行；
checks（矩阵：macos-14 / macos-15 / ubuntu-24.04 / ubuntu-24.04-arm）：先跑发布脚本的 mock 测试，然后cargo fmt --check、bash scripts/check-file-size.sh、两轮 clippy、两轮测试；
windows：在 Windows 上重复格式、lint、测试；
checks-passed：把以上全部聚合成一个分支保护门禁；
build：仅在main上为 Apple Silicon、Intel macOS、Ubuntu x86_64/ARM64 构建 release 二进制并验证其 CLI。

一个值得借鉴的细节：CI 用ci-changes.sh做变更检测，文档-only 的 PR 不必跑昂贵的原生构建，但必需的门禁永远不会被跳过。

📏 严格的 1000 行文件限制：没有例外名单

这是本仓库最有辨识度的一条规则，由 scripts/check-file-size.sh 执行：

上限1000 行（MAX_LINES=1000）；
覆盖所有被 Git 跟踪的.rs、.py、.sh、.swift文件，测试文件同样计入（scripts/check-file-size.sh）；
没有任何豁免名单：超限就按职责拆分模块，而且要在同一个改动里完成拆分，而不是"先加个例外以后再说"。

执行路径是双重的：本地just ci会先跑check-file-size，远端 CI 的 checks job 也会再跑一遍（.github/workflows/ci.yml）。AGENTS.md 同时给出分寸感："行数限制是天花板，不是随意切割的理由"——按职责拆，而不是凑数字拆。

配套实践：测试体不放生产文件，新功能的测试放进模块tests/目录下的新主题文件（如keymap/tests/pane_keys.rs），并行 PR 各改各的文件，天然减少冲突。

✍️ 提交信息与 PR 约定：主题即发布说明

变更日志由git-cliff从 git 历史自动生成（cliff.toml），提交主题原文就是用户看到的发布页条目。规则由 scripts/release/check-commit-messages.py 定义并强制执行：

类型	去向
`feat`	Added
`fix`	Fixed
`perf`/`refactor`/`revert`	Changed
`docs`	Documentation
`chore`/`ci`/`build`/`style`/`test`	永远不面向用户

格式要求：type: description或type(scope): description，主题 ≤80 字符、描述 ≥8 字符、结尾不加句号、第 2 行必须留空；破坏性变更用type!:或BREAKING CHANGE:页脚，必然发布。

执行分三层：

每个 clone 跑一次just hooks，安装 .githooks/commit-msg，在提交产生之前就拒绝不合规主题；
CI 的 commits job 对 PR 内每一笔提交复查；
被拒后用git commit --amend修正，而不是--no-verify绕过。

PR 层面还有几条硬性要求：可视变更必须附真实原生窗口的前后截图（换主题附明暗两套，改布局附窄窗口）；PR 描述要列 QA checklist，只勾选实际跑过的检查，没跑的原生/手动检查要明说；提交与 PR 描述中禁止任何 AI 署名行。审查时你看到的就是应用内这样的 diff 视图：

🧪 可选的深度验证：live、GUI 与性能测试

以下测试因为需要 CI 不具备的资源而设为显式 opt-in：

just test-live /absolute/path/to/herdr # 实时集成测试 just test-gui /absolute/path/to/herdr # 需图形桌面 just test-sidebar # 原生字形回归 just test-perf # release 模式性能预算

关键纪律：绝不把 live 测试指向个人 daemon——它们会自建、自清理一个隔离 daemon。对视觉改动，请在真实原生窗口里检查窄布局、长标签、焦点与裁切；无头布局测试不能证明原生字形与输入的正确性。

📚 关键资料导航

资料	路径
贡献流程（入门）	CONTRIBUTING.md
工程规则（架构、Rust 约定、验证要求）	AGENTS.md
全部 just 命令	justfile
文件行数检查脚本	scripts/check-file-size.sh
提交信息检查脚本	scripts/release/check-commit-messages.py
CI 工作流定义	.github/workflows/ci.yml
变更检测逻辑	scripts/ci-changes.sh
发布工具说明	scripts/release/README.md

一句话总结：herdr-gpui 的贡献体验就是just format && just ci之后提交 PR——格式、行数、lint、测试、提交信息全部被脚本化地强制执行，你唯一需要"自觉"的，是把没跑过的检查如实写进 PR 描述。

【免费下载链接】herdr-gpui

Native client for Herdr on macOS, Linux, and Windows, built with Rust and GPUI. View terminal sessions, workspaces, Git worktrees, and agent activity through your local Herdr daemon.

项目地址：https://gitcode.com/gh_mirrors/he/herdr-gpui

点击查看免费下载