名称： healthkit-sync
描述： iOS HealthKit 数据同步 CLI 命令与模式。适用于使用 healthsync CLI、获取 Apple 健康数据（步数、心率、睡眠、锻炼）、通过本地网络配对 iOS 设备，或了解 iOS 健康同步项目架构（包括 mTLS 证书固定、钥匙串存储和审计日志）。
许可证： Apache-2.0
compatibility: 需安装 healthsync CLI 的 macOS 系统（配置文件位于 ~/.healthsync/config.json）
元数据：
category: development
platforms: ios,macos
author: mneves

HealthKit 同步 CLI

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

使用场景

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

CLI 快速参考

配对流程（首次使用）

# 1. 在本地网络中发现设备
healthsync discover

# 2. 在 iOS 应用中：点击"分享"生成二维码，然后点击"复制"
# 3. 从剪贴板扫描二维码（通用剪贴板）
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

可用的健康数据类型

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

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

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

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

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

配置

配置文件位于 ~/.healthsync/config.json（权限：0600）：

{
  "host": "192.168.1.x",
  "port": 8443,
  "fingerprint": "sha256-证书指纹"
}

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

安全架构

证书固定

CLI 通过 SHA256 指纹验证服务器证书（TOFU 模型）：
1. 首次配对时，从二维码中存储指纹
2. 后续连接验证指纹是否匹配
3. 不匹配则拒绝连接（防止中间人攻击）

仅限本地网络

主机验证限制连接至以下范围：
- 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 应用
│   ├── 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 应用架构详情