从源码构建

环境要求

• macOS 26 或更高版本
• Xcode 26
• Swift 6.2 或更高版本
• Git

长时间构建前先确认当前 Developer Directory 与版本：

sw_vers -productVersion
xcode-select -p
swift --version

xcode-select -p 应指向 /Applications/Xcode.app 内部。

克隆并构建

Release

git clone https://github.com/AstroQore/vibe-bar.git
cd vibe-bar
swift test
./Scripts/build_app.sh release
open ".build/Vibe Bar.app"

Debug

git clone https://github.com/AstroQore/vibe-bar.git
cd vibe-bar
swift test
./Scripts/build_app.sh debug
open ".build/Vibe Bar.app"

Swift Package 包含：

• VibeBar：应用可执行 Target；
• VibeBarCore：可测试的解析器、存储、隐私、Adapter 与用量逻辑。

打包脚本会组装 .build/Vibe Bar.app，复制资源与 Sparkle Framework，并对 Bundle 做 ad-hoc 签名供本地使用。

更具体地说，它会构建所选 Swift Configuration，创建 App Bundle 骨架，复制 Executable 与 SwiftPM Resource Bundle，保留 Sparkle 版本化 Framework 链接， 安装 Info.plist 与图标，从内到外签名嵌套 Helper，并验证最终 Bundle。

验证 Bundle

分发本地构建前，运行仓库规定的完整检查：

swift build
swift test
./Scripts/build_app.sh release
codesign --verify --deep --strict ".build/Vibe Bar.app"
codesign -d --entitlements - ".build/Vibe Bar.app"

因为 Vibe Bar 有意不启用沙箱，Entitlement 输出不应包含 com.apple.security.app-sandbox。

Smoke Test

open ".build/Vibe Bar.app"

确认：

• 菜单栏状态项出现；
• Overview 可打开，Settings Window 可进入；
• 至少一个可用核心 Provider 能刷新；
• 应用正常向 ~/.vibebar/ 写入派生状态；
• ~/Library/Containers/com.astroqore.VibeBar/ 下没有新建沙箱 Container。

完成 Smoke Test 并决定替换已安装版本前，不要把 Bundle 移进 /Applications。

常见失败

• xcode-select 指向 CommandLineTools 时，切换到完整 Xcode。
• Gatekeeper 报 Bundle 损坏时，使用右键 → 打开，或对本地 Bundle 移除 Quarantine。
• macOS 版本过旧时无法启动；Deployment Target 是 macOS 26。
• 旧构建中所有 Provider 都显示未登录时，检查 故障排查中的 Legacy Sandbox Container。

修改集成前

仓库中的 AGENTS.md 包含完整的架构、隐私、Adapter 与验证规则。修改 Provider 或本地数据行为前， 请先阅读对应章节。

不要把真实 Token、Cookie、邮箱、Organization ID、机器 Hostname 或个人 Home 路径放进源码、Fixture、示例或日志。