Orca macOS 权限与签名：entitlements 验证与发布签名完整指南

Orca macOS 权限与签名：entitlements 验证与发布签名完整指南

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca

Orca 是一个用于并行运行多 Agent 的 ADE（Agent 开发环境），支持桌面端、移动端和 VPS 部署。本文带你完整看懂 Orca 在 macOS 上的权限声明（entitlements）与发布签名机制：从权限清单到 hardened runtime、公证（Notarization），再到自动化校验脚本，帮助你快速理解它的构建与发布安全体系。

为什么 macOS 权限与签名这么重要

macOS 对第三方应用有三道"关卡"，任何一道没过，用户要么无法打开应用，要么权限反复失效：

1. 权限声明（Entitlements）：应用要使用麦克风、摄像头、蓝牙等能力，必须先在清单里"报备"，系统弹窗才可能合法弹出；
2. 代码签名（Code Signing）：发布版必须使用 Developer ID 证书签名并开启 Hardened Runtime，否则系统直接拒跑；
3. 公证（Notarization）：Apple 公证票据让权限授权（TCC）与"应用身份"稳定绑定——换一次构建，用户之前授予的文件夹访问权限不会莫名失效。

Orca 恰好把这三件事都做成了可验证的工程化流程。

两个 entitlements 文件：主应用与辅助应用

Orca 在resources/build/目录下维护了两份 macOS 权限清单：

主清单中声明了 9 项能力，每一项都对应一个具体的产品功能：

• com.apple.security.automation.apple-events：允许终端启动的开发者工具自动化本地应用；
• com.apple.security.device.audio-input：桌面语音捕获（语音输入）；
• com.apple.security.device.bluetooth/camera/usb：连接开发设备与模拟器；
• com.apple.security.personal-information.location：位置信息；
• com.apple.security.cs.allow-jit、allow-unsigned-executable-memory：Electron / Chromium 运行所需；
• com.apple.security.cs.allow-dyld-environment-variables：打包后二进制加载所需。

配套的用户可见说明（比如"为什么 Orca 要访问麦克风"）写在打包配置的extendInfo里，见 config/electron-builder.config.cjs 中的NSMicrophoneUsageDescription等字段——用户看到弹窗时，文案来自这里。

自动化校验：为什么重复的权限键名是个坑

一个隐蔽的坑：plist 里出现重复的 key，plutil -lint能通过，但发布签名时codesign会直接拒绝。

为此 Orca 编写了专门的校验脚本 verify-macos-entitlements.mjs，它逐行扫描 XML，按<dict>层级检查 key 是否重复，并报告"首次出现行号 / 重复行号"：

pnpm verify:macos-entitlements

该命令已在 package.json 中注册。脚本只校验、不修改文件——一旦发现重复键就报错退出，确保问题在进入签名阶段前被拦下。

发布签名：三道硬性开关

打包行为集中在 config/electron-builder.config.cjs 中，由环境变量ORCA_MAC_RELEASE=1等开关控制（见 第22-43行）。正式发布时同时打开三个开关：

对应的关键配置位于 macos 打包段：

• entitlements与entitlementsInherit都指向 entitlements.mac.plist，保证主应用和所有子进程继承同一份权限；
• 注释中特别解释了为什么开发渠道构建也要公证：TCC 把授权锚定在"标识符 + 团队"上，与代码哈希无关；没有公证票据，每 24 小时一次的构建都会让用户已授予的 Documents/Desktop/Downloads 访问权限静默失效。

签名前必须先签"内嵌应用"

Orca 的 macOS 包里还嵌套了几个独立可执行体（Orca Computer Use.app、orca-notification-status、orca-keyboard-layout）。构建脚本在打包前先用codesign --force --deep --sign <identity> --options runtime --timestamp为它们签名并立即--verify --strict校验，再让外层 Orca.app 封存。相关实现见 signMacComputerUseHelper 与 codesignArgs。

签名身份的选择逻辑见 findInstalledMacSigningIdentity：发布构建只接受Developer ID Application或Apple Distribution；本地开发才允许Apple Development，且回退到 ad-hoc（-）签名。

一键发布构建与所需凭据

发布入口是一条命令（见 package.json）：

pnpm build:mac:release

它会先运行 verify-macos-release-env.mjs 做"凭据守门"——缺少任何一项都立即失败，避免 CI 日志看起来成功、实际产物却是未签名应用。所需环境变量：

本地调试则使用pnpm build:mac做 ad-hoc 构建，无需任何 Apple 凭据即可在开发机上启动验证。

快速上手：验证你的构建

在你自己的 Orca 工作副本中，按顺序执行以下检查，即可复现发布流水线的核心验证：

pnpm verify:macos-entitlements # 1. 检查 entitlements 无重复键 pnpm build:mac # 2. 本地 ad-hoc 构建 codesign --verify --deep --strict \ --verbose=2 dist/Orca.app # 3. 手动校验产物签名

如果你想进一步理解权限如何映射到产品功能，建议阅读以下资料：

• 权限清单：resources/build/entitlements.mac.plist
• 打包与签名配置：config/electron-builder.config.cjs
• entitlements 校验脚本：config/scripts/verify-macos-entitlements.mjs
• 发布环境守门脚本：config/scripts/verify-macos-release-env.mjs

常见问题（FAQ）

Q1：本地构建不签名能打开吗？可以。本地构建走 ad-hoc 路径，不启用 hardened runtime 和公证，适合快速验证。

Q2：为什么更新后文件夹权限有时会"失效"？macOS 的 TCC 授权绑定应用身份。Orca 通过公证票据让身份在版本间保持稳定（见 配置注释），这是它连开发渠道构建也坚持公证的原因。

Q3：发布构建为何"宁败勿降级"？forceCodeSigning保证签名不可用时构建直接报错，而不是生成一个"看起来能发"的 ad-hoc 产物混入发布日志。

总结

Orca 的 macOS 发布体系可以用三句话概括：权限清单集中管理并用自动化脚本拦截重复键错误；内嵌辅助应用先签后封、签后必验；发布构建强制 Developer ID 签名 + Hardened Runtime + 公证，缺一即失败。这套机制既保证了用户权限授权跨版本稳定，也让每一次发布都有可验证的安全底线。

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca