企业官网建设流程全解析

如何为Pebrel贡献代码：从本地构建到一致性测试套件的开发者完全指南

【免费下载链接】pebrelAI-native, GPU-accelerated terminal emulator for Windows with SSH, persistent sessions, split panes, and first-class AI CLI workflows.项目地址: https://gitcode.com/gh_mirrors/neb0ula57/pebrel

Pebrel 是一款 AI 原生的 GPU 加速终端模拟器（Windows 为主，同时支持 macOS 与 Linux），内置 SSH 工作区、持久会话、分屏面板和 AI CLI 工作流。本文为第一次参与 Pebrel 开源贡献的开发者提供了完整路径：环境准备、本地构建、架构检查、Runtime API 一致性测试套件，直到提交 PR 的全流程。

📌 贡献 Pebrel 的 6 个阶段

在深入细节前，先给出整体路线图，帮助你建立全局认知：

1. 读规则— 贡献指南、架构图与工程约束三份文档
2. 备环境— 固定 Rust 工具链 + Python 3.11+
3. 本地构建— 一条 cargo 命令出真机产品
4. 跑本地门禁— 架构检查器、行数预算、i18n 契约
5. 跑一致性测试套件— 用公开 Runtime API 验证可见行为
6. 提交 PR— 小步提交，等待五平台原生矩阵

Pebrel 的模块边界清晰：应用与 UI 在 nebula_app/，终端核心与 PTY 在 nebula_terminal/，设置与语言注册在 nebula_settings/。贡献前务必先读目标路径最近的 AGENTS.md，规则按目录分层生效。

🛠️ 环境准备：安装固定工具链

Pebrel 在 rust-toolchain.toml 中固定了 Rust 版本，克隆仓库后 rustup 会自动切换到正确工具链：

git clone https://gitcode.com/gh_mirrors/neb0ula57/pebrel cd pebrel

各平台依赖要点（详见 INSTALL.md）：

另外，本地快速检查器要求Python 3.11+，且不需要任何第三方 Python 包。

⚡ 第一次本地构建：一条命令出产品

不要构建被替换的旧版可执行文件，始终构建真正的 GPUI 产品：

cargo build --locked -p nebula --bin pebrel --features gpui-shell

构建成功后你会得到带分屏、SSH 标签页和 AI 会话支持的原生终端。开发迭代时可以用更快的检查模式：

cargo check -p nebula --bin pebrel --features gpui-shell --tests --locked

✅ 本地门禁清单：PR 合并前的快速验证

Pebrel 用"工程合同"代替口头约定：行数预算与依赖方向由 architecture/ 目录声明，检查脚本统一读取同一来源。提交 PR 前，运行以下命令（Windows 上如python是你的解释器，请替换python3）：

python3 scripts/check_architecture.py --base <PR-base-commit> python3 -m unittest scripts.tests.test_architecture_budgets scripts.tests.test_architecture_dependencies scripts.tests.test_architecture_governance cargo test --manifest-path tools/i18n-contract/Cargo.toml --locked cargo test -p nebula-settings cargo test -p nebula --test file_line_budget cargo fmt --all -- --check

几条容易踩坑的规则（来自 CONTRIBUTING.md 与 docs/project-constraints.md）：

• 2000 行是硬上限，800 行只是"建议拆分"的提示线；既有超限文件按实测值冻结，不给增长空间
• 禁止靠抬高预算、删测试、压缩格式或机械分片让门禁通过
• 规则本身有缺陷时，提交窄范围政策修订 + 正反测试，而不是--skip绕过
• 一个 PR 只做一件事：改动超过1500 行源码（文档、lockfile、资源不计），pr-size检查会失败，请拆分而不是申请豁免

🧪 一致性测试套件：用 Runtime API 验证可见行为

这是 Pebrel 最有特色的部分：scripts/conformance/ 提供了一个仅用标准库的测试套件，它不碰内部 API，而是通过公开 Runtime API 验证用户可见行为——启动一个隔离应用进程（私有配置目录），通过回环 TCP JSONL 端点驱动它，结束后只清理自己拉起的进程。

套件按固定顺序运行 10 个用例：boot（启动与 API 发现）、echo（跨 shell 命令输入）、resize（分屏比例传播）、split（嵌套布局）、scrollback（600 行滚动历史）、session（自动保存与冷恢复）、paste（多行 bracketed-paste）、cjk_roundtrip（UTF-8/CJK 回环）、close（5 秒内关窗，放在最后因为它会终止应用）。

跨平台黄金基线对比

每次运行都会校验 golden/common.json 通用不变量；如果某平台已有评审过的黄金基线，会自动比对。首次在新平台跑通后可用--update-golden生成基线（有失败用例时该命令会拒绝写入）：

python3 scripts/conformance/run.py \ --app target/release/pebrel \ --platform linux-x86_64 \ --output dist/conformance/linux-report.json

多平台报告可直接横向对比，只有 golden/whitelist.json 中声明的字段允许差异——这让"Windows 上能跑"和"三平台行为一致"成为可验证的事实，而不是口头承诺。

🌐 理解 CI 矩阵：你的 PR 会跑哪些测试

PR 触发哪些原生测试，由权威选择器 scripts/ci_plan.py 统一规划，覆盖五类 runner：ubuntu、windows-x64、macos、windows-arm64、macos-intel。策略是"按路径分级"：

必需检查包括architecture-contracts、lint、pr-size、五个Tests (<os>)任务和两个Release workspace (<os>)任务，外加 Code Owner 审批。PR 只跑测试与编译检查，不构建发行包；首次 fork 贡献者需维护者审批 workflow 后才能开跑。

📝 提交 PR：像维护者一样思考

最后，让 PR 一次通过评审的几个关键点：

• 先说用户问题，再谈实现；跨层依赖、持久化格式、线程模型变更要先讨论
• 补上"针对缺陷会失败的回归测试"，并说明你实际跑了什么、没跑什么
• 非平凡决策记录到 architecture/notes/ 下对应路径；普通小修复不用写
• 涉及 UI 文案时遵循 docs/internationalization.md 的语言注册合同
• 不要附带构建产物、含密钥的截图或无关生成文件

总结

为 Pebrel 贡献代码的核心是小步、可验证、有证据：一条命令本地构建，一套门禁脚本本地验证，一致性测试套件保证跨平台行为一致，五平台原生矩阵把关最后关。从阅读 CONTRIBUTING.md 和 docs/architecture.md 开始，提交你的第一个 PR 吧！🚀

官方贡献入口：CONTRIBUTING.md ｜ 架构地图：docs/architecture.md ｜ 工程约束：docs/project-constraints.md ｜ 一致性套件：scripts/conformance/README.md

【免费下载链接】pebrelAI-native, GPU-accelerated terminal emulator for Windows with SSH, persistent sessions, split panes, and first-class AI CLI workflows.项目地址: https://gitcode.com/gh_mirrors/neb0ula57/pebrel