HealthKit同步命令行工具

通过本地网络，使用mTLS安全地将Apple HealthKit数据从iPhone同步到Mac。

何时使用此技能

• 用户询问从iPhone同步健康数据
• 用户提及healthsyncCLI命令
• 用户想要获取步数、心率、睡眠或锻炼数据
• 用户需要将Mac与iOS设备配对
• 用户询问iOS健康同步项目架构
• 用户提及证书锁定或mTLS模式

CLI快速参考

配对流程（首次使用）

# 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

获取健康数据

# 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

可用的健康数据类型

活动：步数、步行跑步距离、骑行距离、活动消耗能量、基础代谢能量、锻炼时间、站立小时、爬楼层数、锻炼记录

心脏：心率、静息心率、平均步行心率、心率变异性

生命体征血压收缩压，血压舒张压，血氧，呼吸频率，体温，最大摄氧量

睡眠：睡眠分析，在床时间，入睡时间，清醒时间，快速眼动睡眠，核心睡眠，深度睡眠

身体：体重，身高，身体质量指数，体脂率，去脂体重

配置

配置存储于~/.healthsync/config.json（权限：0600）：

{
  "host": "192.168.1.x",
  "port": 8443,
  "fingerprint": "sha256-certificate-fingerprint"
}

令牌存储在 macOS 钥匙串中，服务名称为org.mvneves.healthsync.cli。

安全架构

证书锁定

命令行界面通过 SHA256 指纹验证服务器证书（TOFU 模型）：

1. 首次配对时从二维码存储指纹
2. 后续连接验证指纹是否匹配
3. 不匹配 = 连接被拒绝（防止中间人攻击）

仅限本地网络

主机验证将连接限制为：

• localhost,*.local域名
• 私有IPv4地址：192.168.*,10.*,172.16-31.*
• IPv6回环地址：::1，链路本地地址：fe80::

钥匙串存储

令牌从不存储在配置文件中——始终使用以下保护类别存储在钥匙串中：

• kSecAttrAccessibleWhenUnlocked保护类别
• 服务：org.mvneves.healthsync.cli
• 账户：token-{主机}

项目结构

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

故障排除

“未找到设备”：

• 确保 iOS 应用已开启共享功能并正在运行
• 两台设备必须连接至同一 Wi-Fi 网络
• 检查防火墙是否未阻止 mDNS（端口 5353）

"配对码已过期"：

• 在 iOS 应用中生成新的二维码（二维码有效期为 5 分钟）

"证书不匹配"：

• 删除~/.healthsync/config.json并重新配对
• 服务器证书可能已被重新生成

"连接被拒绝"：

• iOS 应用服务器可能未运行
• 运行healthsync status --dry-run以便在不连接的情况下进行测试

另请参阅

• CLI 参考- 详细的命令文档
• 安全模式- mTLS 和证书固定模式
• 架构- iOS应用架构详解