health-data

用途

health-data 是一个用于查询和分析 Apple Health 本地 SQLite 数据库的技能。该数据库包含 630 万条以上记录，覆盖 43 种健康指标，数据时间范围为 2015-10-13 至今，包含 1,435 次锻炼会话、40,514 条睡眠记录和 1,875 天活动摘要。数据库位置为 ~/data/health.db。

主要能力

该技能支持查询生命体征、活动、睡眠和锻炼数据，并提供多种预置查询：

每日健康摘要：返回步数、卡路里、心率（平均/最低/最高）、锻炼分钟数、距离和活动圆环状态。
每周趋势：对比周与周的表现，返回平均每日步数、静息心率、锻炼分钟数和每周锻炼次数。
睡眠分析：返回每晚时长、睡眠阶段（Core、Deep、REM）和平均睡眠小时数。
最新生命体征：返回心率、HRV、静息心率、血氧、呼吸频率及时间戳。
活动圆环：返回每日圆环数值/目标、完成百分比和完美天数。
锻炼历史：返回锻炼类型、时长、距离、卡路里及按类型汇总。

数据库包含 43 种健康指标类型，涵盖：生命体征（心率、HRV、静息心率、血氧、呼吸频率、血压）、活动（步数、距离、活动卡路里、基础卡路里、爬楼层数、锻炼时间、站立时间）、移动能力（步行速度、步长、步行不对称性、爬楼速度、步行稳定性）、身体（体重、BMI、体脂率）、音频（环境噪音、耳机暴露）以及其他（VO2 Max、日光时间、紫外线暴露）。

使用方式

Python 脚本（推荐用于常见查询）

使用 scripts/health_query.py 进行预置查询并自动格式化：

# 每日摘要
python ~/.claude/skills/health-data/scripts/health_query.py --format markdown daily --date 2025-11-29

# 每周趋势
python ~/.claude/skills/health-data/scripts/health_query.py --format json weekly --weeks 4

# 睡眠分析
python ~/.claude/skills/health-data/scripts/health_query.py --format fhir sleep --days 7

# 最新生命体征
python ~/.claude/skills/health-data/scripts/health_query.py vitals

# 活动圆环
python ~/.claude/skills/health-data/scripts/health_query.py --format json activity --days 30

# 锻炼历史
python ~/.claude/skills/health-data/scripts/health_query.py workouts --days 30 --type Running

# 自定义 SQL
python ~/.claude/skills/health-data/scripts/health_query.py --format json query "SELECT * FROM workouts LIMIT 5"

输出格式包括：markdown、json、fhir、ascii。

直接 SQL（用于自定义/临时查询）

可直接对数据库运行 SQL。表结构和查询模板参见 references/schema.md。

sqlite3 ~/data/health.db "SELECT AVG(value) FROM health_records WHERE record_type LIKE '%HeartRate%' AND start_date LIKE '2025-11%'"

输出格式

Markdown（默认）：人类可读的表格和列表，适合报告和摘要。
JSON：结构化数据，供程序化使用。
FHIR R4：医疗互操作格式，输出为包含 Observation 资源的 FHIR Bundle，使用 LOINC 编码，编码映射参见 references/fhir_mappings.md。
ASCII：终端友好输出，带条形图和统计信息。

常见 SQL 模式

心率按小时（昼夜节律模式）：

SELECT strftime('%H', start_date) as hour, ROUND(AVG(value), 1) as avg_hr
FROM health_records
WHERE record_type = 'HKQuantityTypeIdentifierHeartRate'
AND value BETWEEN 40 AND 200
GROUP BY hour ORDER BY hour;

本月每日步数：

SELECT DATE(start_date) as day, SUM(value) as steps
FROM health_records
WHERE record_type = 'HKQuantityTypeIdentifierStepCount'
AND start_date >= DATE('now', 'start of month')
GROUP BY day ORDER BY day;

睡眠质量（深睡 + REM 小时）：

SELECT DATE(start_date) as night,
       ROUND(SUM(duration_minutes)/60.0, 1) as quality_hours
FROM sleep_sessions
WHERE sleep_stage IN ('Deep', 'REM')
GROUP BY night ORDER BY night DESC LIMIT 14;

锻炼汇总：

SELECT REPLACE(workout_type, 'HKWorkoutActivityType', '') as type,
       COUNT(*) as count, ROUND(SUM(duration_minutes)) as total_min
FROM workouts
WHERE start_date >= DATE('now', '-30 days')
GROUP BY type ORDER BY count DESC;

适用场景

适用于个人健康数据回顾、周与周趋势对比、睡眠模式分析、锻炼统计、生命体征追踪，以及需要将健康数据导出为 FHIR R4 格式用于医疗互操作的场景。

限制与故障排查

数据库未找到：确保 ~/data/health.db 存在。可从 /Users/server/apple_health_export/ 运行导入脚本：python import_health.py --status。
日期范围无数据：检查可用日期范围：SELECT MIN(start_date), MAX(start_date) FROM health_records;。
异常值：过滤生理有效范围（如心率 40-200 bpm）：WHERE value BETWEEN 40 AND 200。

资源

scripts/health_query.py：主查询工具，支持 Markdown/JSON/FHIR 输出。
references/schema.md：数据库模式、记录类型映射、SQL 查询模板。
references/fhir_mappings.md：LOINC 编码和 FHIR R4 模板。