# WristBeam：为 Mac 配套应用重建佳明手表协议

> 以原生 macOS 菜单栏应用实现佳明手表的配套客户端：通过蓝牙配对，接收实时健康通知和原始 FIT 文件，并可上传至 Garmin Connect。源码注释称，GFDI 分帧、握手、文件传输和状态字段依据对一个自备佳明 Android 安装包的分析实现，并与 Gadgetbridge 等社区实现相互核对。设备验证仅涵盖一款手表；可选启用的 MCP 与 HTTP 接口只提供本地缓存的数据。

- 类型：案例
- 目标：应用 · 协议
- 类别：独立重建案例
- 关联：独立重建项目
- 来源复核于：2026-10-19
- 收录于：2026-10-27
- 原始资源：<https://github.com/kongdayan/wristbeam>
- 一手来源：<https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/README.md>
- 目录页面：<https://awesomerea.org/zh/resources/wristbeam-garmin-watch-protocol-case/>
- 记录 JSON：<https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/record.json>
- 英文版：[English](https://awesomerea.org/resources/wristbeam-garmin-watch-protocol-case/index.md)

## 使用条件与局限

- 审阅版本为 VERSION 0.3.7 及未发布的改动。需要 macOS 13+、已关闭心率广播的佳明手表；使用云端功能时，还需通过佳明官方页面登录佳明中国或国际账号。本地模式会暂停所有佳明云端访问。不支持应用层加密、原生 MLR／CoreTransfer 和桌面小组件，Mac 休眠时无法同步。
- 协议源码注释称，GFDI 分帧（COBS、CRC-16）、多链路注册、设备信息、文件目录与传输、电池状态及账号身份字段均以 Swift 独立实现，并逐项对应自备佳明 Android 安装包中的具名类。Gadgetbridge、garmin-bridge 和 garmin-ble 被列为相互印证的线上协议观察资料，仅作参考而未移植。所审阅文件树不含 APK 或反编译清单；云端历史数据使用 Connect 客户端接口，开发者指南说明这些接口并非佳明公开的 API 约定。
- 构建需要 macOS 13+、Swift 5.9+ 和 Command Line Tools；原生 swift test 及 CodeQL 分析需要完整 Xcode，由 CI 提供。CONTRIBUTING 列出了代码检查、本地化、密钥扫描、发布流水线及核心回归脚本。发布包为临时（ad hoc）签名，未经 Apple 公证。
- 设备矩阵仅将 Instinct 2 Solar 于 2026-10-13 的配对、实时通知、原始 FIT 下载、中国区上传和每日图表标为已验证，且未记录固件版本。其他 Instinct、fēnix、epix、Forerunner、Venu 和 vívoactive 型号以及国际区的实际上传仍未验证。VERIFICATION.md 记录的回归数量通过 Command Line Tools 运行，而非完整 XCTest。
- MIT 覆盖项目本身，项目声明与佳明无关联；佳明服务、Android 安装包、手表固件和健康数据保留各自条款。MCP、HTTP／HTTPS API 和 Webhook 在启用前均为关闭状态。

## 一手来源

1. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/README.md>
2. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDISession.swift>
3. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDICodec.swift>
4. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDIFiles.swift>
5. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDIBattery.swift>
6. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Sources/GarminBar/Protocol/GFDICoreIdentity.swift>
7. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/DEVICES.md>
8. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/VERIFICATION.md>
9. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/developer/API.md>
10. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/docs/developer/WATCH-REQUESTS.md>
11. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/CONTRIBUTING.md>
12. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/Package.swift>
13. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/VERSION>
14. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/CHANGELOG.md>
15. <https://github.com/kongdayan/wristbeam/blob/712f577ac55b476ff91e0b44565934ac0d4cad4d/LICENSE>

## 同分区更多条目：应用

- [usque：Cloudflare WARP MASQUE 模式的开源再实现](https://awesomerea.org/zh/resources/usque-warp-masque-client-case/index.md) · 案例
- [Webamp：在浏览器中重新实现 Winamp 2](https://awesomerea.org/zh/resources/webamp-winamp-reimplementation-case/index.md) · 案例
- [NOOP：基于蓝牙协议研究构建的离线 WHOOP 手环客户端](https://awesomerea.org/zh/resources/noop-whoop-ble-client-case/index.md) · 案例
- [NiimBlue：NIIMBOT 标签打印机的独立网页客户端](https://awesomerea.org/zh/resources/niimblue-niimbot-printer-client-case/index.md) · 案例
- [open_oura：基于逆向 BLE 协议、无需云端的 Oura Ring 客户端](https://awesomerea.org/zh/resources/open-oura-ring-protocol-case/index.md) · 案例
- [Sony Headphones Client：Sony 耳机控制协议的桌面客户端](https://awesomerea.org/zh/resources/sony-headphones-client-case/index.md) · 案例

## 关于此条目

说明已依据一手来源复核。
原创说明采用 MIT 许可；外部项目、论文与素材保留各自的权利和许可。