如果你希望在 macOS 上顺利分发 Universal DMG 安装包，Apple 公证（Notarization）与 Stapler 绑定是必不可少的环节。简单来说，整个过程的核心目标就是：让搭载任意芯片的 Mac 用户双击即可安装，不弹出安全警告、无需手动输入命令，安装完成后环境变量自动配置就绪。

首先需要明确一个关键前提：如果跳过公证步骤，那么在 macOS Sonoma 及更新版本上，系统会直接拒绝运行该应用——即使已经完成代码签名也无济于事。

验证 DMG 包的签名与公证状态

打开终端，执行命令：xattr -l /path/to/HermesAgent-universal.dmg。输出结果中如果包含 com.apple.security.code-signature 字段，说明已成功签名；若同时存在 com.apple.quarantine，则表明系统将该文件识别为从网络下载。内部测试阶段可通过 xattr -d com.apple.quarantine /path/to/HermesAgent-universal.dmg 清除隔离标记，但正式发布版本必须走完 Apple Notarization 认证流程。

公证是强制要求。 未经过公证的 DMG 在 Sonoma 及后续版本中默认禁止运行，即使签名完整也会弹出“无法验证开发者”的警告。正确的操作方式是：使用 altool --notarize-app 提交给 Apple 服务器，等待返回 success 状态后，再执行 xcrun stapler staple HermesAgent-universal.dmg 完成票证绑定。

构建 Universal DMG 的核心文件结构

DMG 安装包中必须包含以下三类文件，缺一不可：

根目录下放置 HermesAgent.app（已签名、公证并绑定 stapler 的通用二进制应用）；
根目录下放置 postinstall.sh（以 #!/bin/zsh 开头、赋予可执行权限 chmod +x，内部包含 hermes postinstall --no-interactive 调用）；
根目录下放置 .background/background.png（尺寸 640×480，透明背景）。

使用 hdiutil create -fs HFS+ -volname "HermesAgent" -srcfolder ./dist/ HermesAgent-universal.dmg 命令打包，避免使用拖拽压缩方式——那样会丢失可执行权限与资源分支数据。

自动化安装引导流程设计

用户挂载 DMG 后，应实现“拖拽即部署”的体验：

第一步：在 .DS_Store 中预设窗口布局，使 HermesAgent.app 与 postinstall.sh 并列显示；
第二步：在 HermesAgent.app/Contents/Info.plist 中添加 LSEnvironment 字典，设置 PATH 值为 /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin；
第三步：postinstall.sh 脚本通过 echo $SHELL 检测当前 shell 类型。若为 zsh，则向 ~/.zshrc 追加 export PATH="$HOME/.local/bin:$PATH" 并执行 source ~/.zshrc；若为 bash，则修改 ~/.bash_profile；
第四步：脚本末尾调用 open -a "HermesAgent.app" 启动应用，触发首次初始化向导——该向导已内置 Kimi API Key 输入界面与端口自检功能。