用途
HealthKit Sync 是一套用于将 iPhone 上的 Apple HealthKit 数据安全同步到 Mac 的命令行工具与模式（healthsync CLI）。它面向需要在 Mac 侧以编程方式获取 Apple 健康数据的用户，例如查询步数、心率、睡眠或锻炼数据，或在本地网络中对 Mac 与 iOS 设备进行配对。
主要能力
- 通过本地网络以双向 TLS（mTLS）安全同步 Apple HealthKit 数据。
- 配对流程：先在本地网络中发现设备，再由 iOS 应用生成二维码，最后从剪贴板（通用剪贴板）或图片文件扫描二维码完成配对。
- 提供命令行操作：检查连接状态、列出已启用的数据类型、抓取数据。
- 抓取数据支持 CSV（默认）与 JSON 格式，可一次指定多个数据类型，并可通过管道输出到文件。
- 支持多种健康数据类型，涵盖活动、心脏、生命体征、睡眠与身体指标。
使用方式
配对（首次）：
- 发现本地网络中的设备：
healthsync discover - 在 iOS 应用中点击 “Share” 生成二维码，然后点击 “Copy”
- 从剪贴板扫描二维码：
healthsync scan或从图片文件扫描：healthsync scan --file ~/Desktop/qr.png
抓取健康数据：
- 检查连接状态：
healthsync status - 列出已启用的数据类型：
healthsync types - 以 CSV（默认）抓取数据：
healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps - 以 JSON 抓取多个类型：
healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps,heartRate,sleepAnalysis --format json | jq - 输出到文件：
healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps > steps.csv
可用健康数据类型：
- 活动：steps、distanceWalkingRunning、distanceCycling、activeEnergyBurned、basalEnergyBurned、exerciseTime、standHours、flightsClimbed、workouts
- 心脏：heartRate、restingHeartRate、walkingHeartRateAverage、heartRateVariability
- 生命体征：bloodPressureSystolic、bloodPressureDiastolic、bloodOxygen、respiratoryRate、bodyTemperature、vo2Max
- 睡眠：sleepAnalysis、sleepInBed、sleepAsleep、sleepAwake、sleepREM、sleepCore、sleepDeep
- 身体：weight、height、bodyMassIndex、bodyFatPercentage、leanBodyMass
配置与安全
- 配置存放于
~/.healthsync/config.json（权限 0600），字段包括 host、port 与证书指纹 fingerprint。 - 令牌存储在 macOS 钥匙串中，服务名为
org.mvneves.healthsync.cli。 - 证书固定：CLI 通过 SHA256 指纹校验服务器证书（TOFU 模型）；首次配对从二维码存储指纹，后续连接验证指纹一致，不匹配则拒绝连接（防中间人攻击）。
- 仅限本地网络：主机校验限制为 localhost、.local 域、私有 IPv4（192.168.、10.、172.16-31.）以及 IPv6 回环 ::1 与链路本地 fe80::。
- 令牌不存于配置文件，始终存于 Keychain，使用 kSecAttrAccessibleWhenUnlocked 保护级别，服务为 org.mvneves.healthsync.cli，账户为 token-{host}。
项目结构
ai-health-sync-ios-clawdbot/
├── iOS Health Sync App/ # Swift 6 iOS app
│ ├── Services/Security/ # CertificateService, KeychainStore, PairingService
│ ├── Services/HealthKit/ # HealthKitService, HealthSampleMapper
│ ├── Services/Network/ # NetworkServer (TLS), HTTPTypes
│ └── Services/Audit/ # AuditService (SwiftData)
└── macOS/HealthSyncCLI/ # Swift Package CLI
故障排查
- “No devices found”：确保 iOS 应用正在运行且共享已开启；两台设备须在同一 Wi-Fi 网络；检查防火墙未阻止 mDNS（端口 5353）。
- “Pairing code expired”：在 iOS 应用中重新生成二维码（验证码 5 分钟过期）。
- “Certificate mismatch”：删除
~/.healthsync/config.json并重新配对；服务器证书可能已重新生成。 - “Connection refused”：iOS 应用服务器可能未运行；可运行
healthsync status --dry-run在不连接的情况下测试。
适用场景与限制
适用于在 Mac 上通过命令行获取和处理 Apple 健康数据的场景，尤其是需要在本地网络内安全传输与自动化处理的场合。工具仅支持本地网络连接，配对二维码有时效限制，证书变更需重新配对。其他平台兼容性、收费与价格信息暂未提供。