HermesEnabler 贡献指南:如何为新的 watchOS 构建添加 MobileGestalt 偏移表与沙箱策略
HermesEnabler 贡献指南:如何为新的 watchOS 构建添加 MobileGestalt 偏移表与沙箱策略
HermesEnabler 是一个让任意 Apple Watch 解锁 Hermès 独占表盘的开源项目。本文是一份面向新手的贡献指南:教你如何为新出现的 watchOS 构建完成物理 OTA 验证、填写 MobileGestalt 偏移表(MGOffsets.plist)与沙箱策略检查,让你的 PR 一次通过。
一枚运行 HermesEnabler 后解锁 Hermès 表盘的 Apple Watch。你的贡献,就是让下一个 watchOS 版本的用户也能看到这一幕 ⌚
为什么每个 watchOS 构建都要有独立的偏移表
HermesEnabler2 的工作原理,是修改手表上 MobileGestalt 缓存(系统用来回答"我的设备支持什么"的缓存文件)。这个缓存包含三个关键字段:
| 字段 | 作用 |
|---|---|
CacheData |
二进制数据块,每个键的值存放在随构建变化的固定字节偏移处 |
CacheExtra |
字典形式的覆盖项,使用不透明的"加密键"标识 |
CacheUUID |
布局指纹,应用用它判断缓存是否属于预期构建 |
关键点:同一个营销版本号(如 27.2)对应的内部构建号(如 24S132)才是布局的真正索引。研究文档中 24R359 的条目就是从相邻构建 24R364 复制的假设值——它的 RecoveryVerified 标记为 false,因为缺少独立的物理 OTA 验证。这正是本文要帮你避免的坑。
完整原理见 Research/MobileGestalt/README.md,"Adding a build" 一节明确写道:不要仅因营销版本号相近或缓存长度相同就复制偏移量。
准备工作:克隆仓库并熟悉核心文件
git clone https://gitcode.com/GitHub_Trending/he/HermesEnabler
先通读以下 4 个文件,它们构成你的"贡献地图" 🗺️:
| 文件 | 作用 |
|---|---|
| MGOffsets.plist | ⭐ 偏移表:每个构建的缓存布局与描述符索引 |
| MGDefaults.plist | 每个构建的激活值与验证边界 |
| BQCore.m | 沙箱逃逸与 MobileGestalt 读写核心实现 |
| Research/OTA/README.md | 可复现的物理 OTA 分析工作流 |
以已验证的 24R364 条目为模板(见 MGOffsets.plist 第 45-111 行),一个完整条目包含:
CacheUUID/CacheDataLength:缓存指纹与总长度DeviceBrandOffset/ScreenClassOffset:两个数值键的字节偏移(Hermès 与 Ultra 表盘分别依赖它们)PresenceBase:布尔能力"存在位"的起始偏移,第index个能力的存在位位于PresenceBase + indexIndexes:8 个布尔能力(AOD、Action Button、Double Tap 等)的描述符索引AdditionalIndexes:13 个附加能力索引(如心率、罗盘)RecoveryVerified:只有当恢复路径的证据也成立时才设为true
第一步:锁定物理构建并下载对应 OTA
- 确定目标 watchOS 构建号(如
24T123)与具体机型(如Watch8,1)。营销版本号只是外观,构建号才是布局索引。 - 从 Apple 更新服务获取该机型 + 构建的全量物理 OTA(full OTA),单独保存其来源与预期 SHA-256。
- 校验下载完整性——这一步只能证明"文件没下错",不是对二进制语义的证明:
shasum -a 256 "$OTA_PATH"
完整数据集说明见 Research/OTA/README.md。
第二步:提取并分析 libMobileGestalt.dylib
使用社区工具 ipsw 提取 dyld 共享缓存中的目标动态库:
ipsw ota extract "$OTA_PATH" --key-db "$KEY_DB_PATH" --dyld --confirm --output "$OUTPUT_DIR"
ipsw dyld extract "$DYLD_CACHE_PATH" libMobileGestalt.dylib --slide --output "$OUTPUT_DIR/mg"
然后对提取出的 libMobileGestalt.dylib 做静态分析,记录:
- 选中架构(arm64e)与描述符索引
DeviceBrand、main-screen-class的索引 → 换算出 8 字节值槽偏移与存在位偏移- 8 个主布尔键 + 13 个附加键的索引
- 回调函数的输入来源(设备树属性?其他 MG 答案?机型检查?)
⚠️ 注意:main-screen-class 的回调会经由全局路径读取 MainScreenStaticInfo,分析时务必追踪其依赖链。
第三步:填写偏移表与默认值条目
将分析结果填入两个 plist:
MGOffsets.plist —— 按上文"核心文件"一节列出的字段逐项填写。若某个描述符在你的二进制中不存在(如 24R5315i 缺少两个附加描述符),省略它,不要臆造。
MGDefaults.plist —— 填写:
| 键 | 含义 |
|---|---|
MaxDeviceBrand |
DeviceBrand 的验证上限(如 2),是校验边界,不是写入值 |
HermesEnabledDeviceBrand |
Hermès 激活覆盖值,通常为 1 |
UltraEnabledScreenClass / UltraScreenClassOptions |
Ultra 表盘的屏幕类别,29 必选;38 仅在你的构建完成了 ClockKit 静态分析后才提供 |
38 这个备选值的门槛很高:需要验证 ClockKit 中 -<a href="https://link.gitcode.com/i/7dcb4748443cd4848ac4b2b3619111b6" target="_blank">CLKDevice _loadDeviceInfo] 的屏幕类别映射(29 → size 6,38 → size 9,且 isUltra 谓词接受对应类别)。参考 [Research/WatchFaces/README.md。
第四步:核对沙箱策略
HermesEnabler2 运行在严格的 App 沙箱内,要写入位于沙箱外的 MobileGestalt 缓存,必须借助 BQCore.h 定义的"沙箱逃逸租约":通过 MCM(containermanager)查询获取沙箱扩展 token,临时获得对目标容器的访问权,用完立即释放。
新增构建时需要关注的策略差异:
- App Groups 权限:应用依赖 HermesEnabler2.entitlements 中的
application-groups权限。它决定了逃逸的 class-1 路径是否可用。 - class-2 父目录回退:BQCore.m 中注释说明,部分构建允许重命名应用自身的
Library目录,部分构建会被 sandbox 直接杀掉进程,因此该回退默认关闭,且带崩溃保护标志。 - 子路径符号链接策略:在
Library/Caches内放置临时符号链接再请求 MCM 解析,是最温和的尝试路径。
如果你手头有实机设备,验证新构建上的实际行为并记录结果:逃逸策略是否全部失效、哪条路径成功、bqtool.log 的关键行。这是你 PR 中最有说服力的证据。
第五步:跑测试与构建
提交前,两条命令缺一不可:
clang -std=c11 -Wall -Wextra -Werror tests/BQRecoveryValidationTests.c -o /tmp/hermes-recovery-tests
/tmp/hermes-recovery-tests
单元测试覆盖了缓存槽位比对、DeviceBrand 解析、按钮列表解析等核心逻辑(见 tests/BQRecoveryValidationTests.c)。接着执行 watchOS 构建:
xcodebuild -project HermesEnabler2.xcodeproj -scheme HermesEnabler2 -configuration Debug -sdk watchos -destination 'generic/platform=watchOS' CODE_SIGNING_ALLOWED=NO build
记住:这些检查不能验证私有 API 访问、缓存写入或真机恢复行为——如有实机测试结果,请在 PR 中单独说明。
提交前自检清单 ✅
- [ ] 偏移来自本构建自己的物理 OTA 提取,而非相邻构建复制
- [ ]
CacheUUID、长度、8 个主索引、13 个附加索引逐一比对过 - [ ] 记录了实际检查的架构与机型(
24S132中Watch7,11与Watch8,1提取出的库哈希就不同) - [ ]
RecoveryVerified按证据诚实设置,而非顺手写true - [ ] 沙箱策略行为(若实测)已记录
- [ ] 隐私红线:绝不把设备的 MobileGestalt 备份、序列号、地区数据发布到研究材料中 🚫
写在最后
HermesEnabler 的研究文档反复强调一个原则:"模板、编译成功、UUID 相同"都不等于功能可用。每一条偏移背后都是一次可复现的静态分析;每一份 PR 的证据标签(代码 / 静态分析 / 运行时观测)都应清晰可查。保持这种严谨,你的构建条目就会像 24R364 那样,成为后来者可以放心引用的基准。
相关文档:Research 总览 · 恢复与备份研究 · 中文 README
