介绍
# HealthKit Sync CLI
通过本地网络使用 mTLS 将 Apple HealthKit 数据安全地从 iPhone 同步到 Mac。
## 何时使用此技能
- 用户询问关于从 iPhone 同步健康数据 - 用户提及 `healthsync` CLI 命令 - 用户想要获取步数、心率、睡眠或锻炼数据 - 用户需要将 Mac 与 iOS 设备配对 - 用户询问 iOS Health Sync 项目架构 - 用户提及证书锁定或 mTLS 模式
## CLI 快速参考
### 配对流程（首次使用）
```bash # 1. Discover devices on local network healthsync discover
# 2. On iOS app: tap "Share" to generate QR code, then "Copy" # 3. Scan QR from clipboard (Universal Clipboard) healthsync scan
# Alternative: scan from image file healthsync scan --file ~/Desktop/qr.png ```
### 获取健康数据
```bash # Check connection status healthsync status
# List enabled data types healthsync types
# Fetch data as CSV (default) healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps
# Fetch multiple types as JSON healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \ --types steps,heartRate,sleepAnalysis --format json | jq
# Pipe to file healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \ --types steps > steps.csv ```
### 可用的健康数据类型
**Activity（活动）**：steps, distanceWalkingRunning, distanceCycling, activeEnergyBurned, basalEnergyBurned, exerciseTime, standHours, flightsClimbed, workouts
**Heart（心脏）**：heartRate, restingHeartRate, walkingHeartRateAverage, heartRateVariability
**Vitals（生命体征）**：bloodPressureSystolic, bloodPressureDiastolic, bloodOxygen, respiratoryRate, bodyTemperature, vo2Max
**Sleep（睡眠）**：sleepAnalysis, sleepInBed, sleepAsleep, sleepAwake, sleepREM, sleepCore, sleepDeep
**Body（身体）**：weight, height, bodyMassIndex, bodyFatPercentage, leanBodyMass
## 配置
配置文件存储于 `~/.healthsync/config.json`（权限：0600）： ```json { "host": "192.168.1.x", "port": 8443, "fingerprint": "sha256-certificate-fingerprint" } ```
令牌存储在 macOS 钥匙串 中，服务名称为 `org.mvneves.healthsync.cli`。
## 安全架构
### 证书锁定
CLI 通过 SHA256 指纹验证服务器证书（TOFU 模式）： 1. 首次配对时存储来自二维码的指纹 2. 后续连接验证指纹是否匹配 3. 不匹配 = 拒绝连接（MITM 防护）
### 仅限本地网络
主机验证将连接限制为： - `localhost`、`*.local` 域名 - 私有 IPv4：`192.168.*`、`10.*`、`172.16-31.*` - IPv6 回环：`::1`，链路本地：`fe80::`
### 钥匙串存储
令牌绝不存储在配置文件中 —— 始终存储在钥匙串中，并带有： - `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` 进行测试而不建立连接
## 另请参阅
- [CLI Reference](references/CLI-REFERENCE.md) - 详细的命令文档 - [Security Patterns](references/SECURITY.md) - mTLS 和证书锁定模式 - [Architecture](references/ARCHITECTURE.md) - iOS 应用架构详情