INTRODUCTION

重新认识 GitHub：独立开发者的外脑与工厂

在过去，你仅仅把 Git 当作一个“进度保存工具”（类似于玩单机游戏时的存档），只会使用 add、commit 和 push。

但作为一名使用 Swift/Rust/Python 构建多平台应用、并重度依赖 AI 的极客，GitHub 实际上是你的**虚拟云端办公室**。在这里：

AI Agent 的工位

像你体验的 PR Review，GitHub 是 Codex 等高级 AI 介入你项目的标准化接口。不用 PR，AI 就无法做全局静态分析。

全自动流水线

写完代码推送到云端，自动化工具可以帮你跑 Rust 测试、编译 Swift 的 ipa 文件，甚至全自动分发到 TestFlight。

核心概念与极客规范

1. Branch (分支) —— 你的平行宇宙

不要在 main 里直接改代码。养成使用**语义化前缀**创建分支的习惯，这会让未来的你（以及 AI）一眼看出这个分支是干嘛的。

# 推荐的分支命名规范
git checkout -b feat/audio-engine # feat: 新功能开发
git checkout -b fix/grdb-crash # fix: 修复特定的 Bug
git checkout -b refactor/ui-components # refactor: 重构代码但不改功能

2. Commit (提交) —— 故事的断点

Commit message 是写给 AI 审查员看的“引导词”。如果你写 "update"，AI Review 时会找不到重点；如果你写 "fix: handle nil audio stream to prevent crash"，AI 就会重点审查空指针问题。

💡 效率建议：提交前，习惯性敲一下 git diff 看看自己到底改了啥，防止把测试用的 print("test") 或者是临时的硬编码 API Key 提交上去。

3. Pull Request (PR) —— AI 的质检台

即使没有人类队友，你也必须用 PR！**PR 的本质是把“新分支”合并到“主分支”的申请书。** 这张申请书是发给 AI 审核员（以及自动化脚本）看的。

独狼 + AI 的黄金工作流

每次开发新功能或修复 Bug，请严格执行以下 6 步闭环。这是最大化压榨 AI 算力、保护你不犯低级错误的最佳实践。

1

切出新分支 (本地)

git checkout main
git pull
git checkout -b feat/new-spider
2

疯狂编码 (结合 Cursor 等本地 AI)

使用本地工具生成代码并测试。这消耗你的本地算力或日常 Usage。

git add .
git commit -m "feat: init spider engine"
3

推送到云端

git push -u origin feat/new-spider
4

发起 PR 并提交“架构师总结”

在 GitHub 创建 PR 时，将 AI 生成的修复报告作为描述。例如：“此 PR 修复了 AudioFeatureExtractor.swift 中吞噬 I/O 错误的问题，并将 AVAudioPCMBuffer 封装在 Sendable 容器中。”

AI 深度审查 (Code Review)

AI 机器人会自动在代码行间留言。警惕： 如果 AI 发现逻辑漏洞（如静默失败），必须在本地修复并再次 push，GitHub 会自动更新 PR 状态为 Outdated，确保合入代码的绝对质量。

6

Merge (合并) 并清理

AI 审核通过后，点击 "Merge pull request"。回到本地电脑执行清理：

git checkout main
git pull
git branch -d feat/new-spider # 删掉本地已完成的分支

多语言栈管理与大文件 (LFS)

你同时使用 Swift, Rust, Python 和 R。管理这么多语言，核心原则是：**绝对不要把编译产物传到 Git，只传源码！**

关键防御：`.gitignore`

Swift / macOS

  • .DS_Store
  • build/
  • *.xcworkspace
  • xcuserdata/

Rust

  • target/
  • **/*.rs.bk
  • # Cargo.lock 必须上传！保证依赖一致

避坑指南：Git LFS (Large File Storage)

作为 AI / macOS 开发者，你肯定会遇到巨大的文件（如 .mlmodel 机器学习模型、超大音频测试文件、预渲染视频）。直接 Push 会被 GitHub 拒绝（单文件 > 100MB 限制）。
**解决方案：** 使用 Git LFS。它会把大文件存在云端，Git 记录里只保存一个轻量级指针。

git lfs install
git lfs track "*.mlmodel"
git lfs track "*.mp4"
git add .gitattributes
# 之后就可以像普通文件一样 add 和 commit 了

GitHub Actions：你的免费云端 Linux 服务器

对于 Python 爬虫、R 语言数据处理、Rust 服务端，**GitHub Actions** 是最完美的自动化工具。每当有代码 Push 或 PR 建立，它就会在微软的云端服务器里运行你指定的脚本。

示例：让 GitHub 自动跑 Rust 测试 .github/workflows/rust-test.yml：

name: Rust CI
on:
  pull_request: # 当有 PR 创建时自动触发
    branches: [ "main" ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Run Tests
      run: cargo test --verbose

⚠️ 注意：虽然 GitHub Actions 也能跑 macOS，但配置 Apple 开发者证书、Provisioning Profile 简直是一场噩梦。因此，涉及到 iOS/macOS 打包，请使用下面介绍的 Xcode Cloud。

Xcode Cloud：终极 macOS/iOS 自动化

对于独立开发者来说，每次开发完都要手动选择证书、Archive、导出 IPA、用 Transporter 传到 App Store Connect... 这个过程既枯燥又容易出错。

Xcode Cloud 是苹果官方的 CI/CD 工具，它直接与你的 GitHub 仓库和 App Store Connect 深度绑定。最大的优势是：它“免维护”证书和 Provisioning Profile！

如何接入你的 GitHub 工作流？

不需要写 YAML 配置文件，全图形化操作：

  1. 在 Xcode 顶部菜单选择 Product > Xcode Cloud > Create Workflow。
  2. 选择你需要打包的产品（比如 Sonodex_Multiplatform）。
  3. 关键点：授权 GitHub。 Xcode 会跳出网页让你授权 GitHub 仓库，允许 Xcode Cloud 监听你的 Push 和 PR 事件。
  4. 配置完成！由于你登录了 Apple ID，它会自动去 App Store Connect 拉取所有证书。

结合 AI 的完全体流水线

将我们在 第 3 章 讲的流程与 Xcode Cloud 结合，你的独立开发体验将变为“全自动工厂”：

1. 你在本地用 Cursor 写代码并推送到新分支
2. 你在 GitHub 发起 PR
3. Codex AI 自动介入 Review，帮你修掉 Bug
4. 你点击 Merge，合并到 main 分支
5. [自动化触发] Xcode Cloud 监听到 main 的变动
↳ 启动云端 Mac Studio
↳ 自动拉取最新的 Rust 库进行构建
↳ 自动编译、签名打包
↳ 自动分发到 TestFlight，通知你的内测用户！

*在 Xcode Cloud 中，你可以设置环境脚本（ci_pre_xcodebuild.sh）来提前安装 Rust 工具链：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

Sonodex 实战：从警告到自动化

解决“幽灵冲突” (.xcuserstate)

惨案：合并 PR 时提示 UserInterfaceState.xcuserstate 冲突，且 checkout main 时被拦截。
终极解药：这是 Xcode 自动生成的本地状态，不应被追踪。

# 1. 物理删除本地阻碍文件
rm "Sonodex_MacOS.xcodeproj/project.xcworkspace/xcuserdata/kircerta.xcuserdatad/UserInterfaceState.xcuserstate"
# 2. 从 Git 索引中彻底抹除并提交
git rm --cached [文件路径]
git commit -m "chore: stop tracking xcode user state"

权限拦截与依赖避坑 (HTTPS 替代 SSH)

问题：初次配置时，Xcode Cloud 试图请求 groue (GRDB 作者) 的 GitHub 组织权限导致流程卡死。
解决与好处：我们发现这是因为项目中使用了 SSH 链接拉取开源库。将依赖修改为公开的 HTTPS 链接 (https://github.com/groue/GRDB.swift.git) 后瞬间解决。明白底层逻辑，你就不会被云端 CI 的权限报错吓倒。

主分支保护与靶向修复 (Branching)

操作：面对海量的 Swift 6 严格并发检查警告 (如 AVAudioPCMBuffer 的 Sendable 报错)，我们没有在稳定的 main 分支直接动刀，而是立即切出了 fix/swift6-concurrency 分支。
好处：保证了 main 永远处于可运行、可打包的健康状态。你的任何试错都在“平行宇宙”中进行，彻底告别“改了一个 Bug 导致连项目都跑不起来”的噩梦。

算力卸载，让云端替你打工 (CI/CD Power)

操作：我们在本地小批量修复代码后，将其推送到 GitHub 并发起 Pull Request (PR)，直接触发了 Xcode Cloud 工作流。
好处：全量编译和多环境兼容性测试全部交由 Apple 的云端服务器并行完成。 你的本地 Mac 性能被完全释放，你可以立刻切换回主干分支开发新功能，或者直接去喝杯咖啡。这就是 10 倍开发效率的秘密。

独立开发者极客指令速查表

日常开发必用指令

git status查看当前改了哪些文件，什么在暂存区
git add .将所有改动放入暂存区
git commit -m "msg"打包成一个版本（必须写清楚干了啥）
git push -u origin 分支名推送到云端（第一次推新分支必须加 -u）

后悔药（写错代码时救命用）

git restore <file>丢弃某个文件的修改，恢复到原样
git reset --soft HEAD~1撤销上一次 commit，但保留代码修改（方便重新 commit）
git reset --hard HEAD~1撤销上一次 commit，代码也一起删掉（不可逆！慎用！）

切换分支受阻时的“地毯大法”

git stash 把本地所有乱糟糟的改动（包括那些烦人的 Xcode 状态更改）临时“藏起来”，瞬间让工作区变干净。
git fetch -p 修剪 (Prune) 掉那些本地还存在、但云端已经删掉的“幽灵分支”。

终极效率利器：GitHub CLI (`gh`)

如果连打开浏览器去提 PR 都嫌烦，可以在 Mac 终端输入 `brew install gh` 安装 GitHub 官方命令行工具。以后提交 PR 只需要敲一行：
gh pr create --title "feat: audio engine" --body "@codex review"