如何给Muxy开源项目贡献代码：SPM + Swift 6本地开发、测试与Lint完整指南

【免费下载链接】muxyLightweight and Memory efficient terminal for Mac built with SwiftUI and libghostty项目地址: https://gitcode.com/gh_mirrors/muxy1/muxy

Muxy 是一款用 SwiftUI 和 libghostty 构建的轻量级 macOS 终端，本文带你完整走通 Muxy 开源项目的代码贡献全流程：从 SPM（Swift Package Manager）工程初始化、Swift 6 本地开发，到自动化测试与 SwiftLint 静态检查，零基础也能快速上手。

一、贡献前准备：环境要求清单

Muxy 是一个纯 SPM 工程，无需 Xcode 工程文件，也不依赖外部依赖管理器。开始前请确认：

⚠️ 工具版本已被锁定在 .tool-versions 文件中，检查脚本启动时会校验版本，版本不符会明确提示你期望的版本号。

官方贡献指南见 CONTRIBUTING.md，完整的项目约定可参考 AGENTS.md。

二、一键克隆与初始化开发环境

克隆仓库后只需三条命令即可完成初始化：

git clone https://gitcode.com/gh_mirrors/muxy1/muxy cd muxy scripts/setup.sh # 自动下载 GhosttyKit.xcframework 及运行时资源 swift build # 验证全部代码可编译

初始化脚本 scripts/setup.sh 会从上游 fork 的 Ghostty 仓库拉取最新发布的GhosttyKit.xcframework，并把 shell 集成资源、terminfo 文件同步到Muxy/Resources/下，已存在时会自动跳过，重复执行安全无副作用。

三、读懂 SPM 工程结构

Package.swift 声明了swift-tools-version: 6.0，整个工程由多个 Target 组成：

• Muxy（主应用）：依赖 GhosttyKit、MuxyServer、Sparkle、Yams、Sentry
• MuxyShared：跨进程共享的协议与 DTO
• muxy-hook / muxy-session：两个独立可执行目标，用于 AI 代理 Hook 桥接与持久会话守护
• MuxyTests：测试 Target，源码位于 Tests/MuxyTests，覆盖 Git 解析、远程服务、模型、视图等 200+ 个测试文件

理解 Target 依赖关系后，你在改代码时就能快速定位改动会波及哪些模块。

四、本地构建与运行

swift build --product Muxy # Debug 构建 swift run Muxy # 直接启动应用

日常开发推荐用 scripts/run-dev.sh，它会自动检测源码是否比上次构建更新，按需增量编译Muxy、muxy-hook、muxy-session三个产物后再启动，省去手动判断重建的步骤：

scripts/run-dev.sh --hooks # 启用 AI hooks 调试模式

五、本地测试与覆盖率门槛

测试通过 scripts/run-tests-isolated.sh 以隔离的 Application Support 存储运行，避免污染真实用户数据：

swift test --quiet # 标准测试 scripts/checks.sh --coverage # 额外运行覆盖率门槛

覆盖率脚本 scripts/coverage.sh 要求核心模块行覆盖率不低于90%，低于门槛会直接失败，这是 PR 合入的硬性标准之一。

六、Lint 与格式化：一条命令全搞定

提交前必须通过完整检查链，一条命令即可：

scripts/checks.sh # 格式检查 → 严格 Lint → 构建测试 → 运行测试 scripts/checks.sh --fix # 自动修复格式和 Lint 问题后再构建测试

检查链 scripts/checks.sh 按顺序执行、首个失败即停止，并输出每步耗时：

1. Formatting—swiftformat --lint .（规则见 .swiftformat）
2. Linting—swiftlint lint --strict --quiet（规则见 .swiftlint.yml）
3. Build tests—swift build --build-tests
4. Test— 隔离存储下运行swift test

七、代码规范与 PR 提交清单

📌代码规范（项目明确要求）：

• 代码库不允许任何注释，代码必须自解释、结构清晰
• 用提前返回代替深层嵌套条件判断
• 修复根因，而非打补丁
• 遵循现有模式，保持低内存、低 CPU 占用的设计取向

📌PR 提交清单：

1. 基于main创建分支，PR 聚焦单一改动
2. 标题和描述说清楚"为什么"，关联相关 Issue
3. 提交前本地跑通scripts/checks.sh --fix
4. 若使用 AI 辅助编码，必须在 PR 中注明所用 LLM 名称
5. 遵循 PR 模板 填写

⚠️ 特别注意：Muxy 实行"仅人类"沟通政策——Issue、PR 描述与评审评论中禁止 AI 生成的文本（可用 AI 辅助写代码，但发布文本必须是你自己写的），违反的 Issue/PR 会直接被关闭。

八、遇到 bug 怎么提 Issue

提 Issue 前先搜索是否已有相同问题，然后使用对应模板：

• Bug：.github/ISSUE_TEMPLATE/bug_report.yml
• 功能建议：.github/ISSUE_TEMPLATE/feature_request.yml

结语

从git clone到 PR 合入，Muxy 的贡献路径非常顺滑：SPM 免配置初始化、一条scripts/checks.sh --fix搞定格式化/Lint/构建/测试，规范清晰且可预期。熟悉本指南后，你就可以开始为这个轻量高效的 macOS 终端提交自己的第一个贡献了 🚀

【免费下载链接】muxyLightweight and Memory efficient terminal for Mac built with SwiftUI and libghostty项目地址: https://gitcode.com/gh_mirrors/muxy1/muxy