health-sleep-analysis

name: health-sleep-analysis description: Analyze sleep health data from Apple HealthKit, including sleep stages (Deep/REM/Core/Awake), blood oxygen saturation (SpO2) during sleep, sleep duration trends, bedtime patterns, resting heart rate, and HRV. Use this skill whenever the user asks about sleep quality, sleep analysis, blood oxygen during sleep, sleep stages breakdown, sleep trends over time, heart rate, HRV, or any health data analysis involving sleep or cardiac health. Triggers on: "sleep analysis", "blood oxygen", "sleep quality", "deep sleep", "REM sleep", "resting heart rate", "HRV", "心脏健康", "睡眠分析", "睡眠质量", "血氧", "深睡眠", "静息心率", "心率变异" and similar in any language.

Sleep Health Analysis Skill

Fetch sleep, SpO2, heart rate, and HRV data from Apple HealthKit, analyze it, and produce visual reports.

Language Rules (IMPORTANT)

Detect the language of the user's message and apply it consistently throughout the entire response:

• Written analysis, conclusions, health advice → user's language
• Chart/image text labels, titles, axes, legend, insight cards, footer → user's language
• Code, script internals, variable names → English (always)
• When rendering SVG charts: pass a --lang argument to the rendering scripts; the scripts will localize all on-chart text automatically

Supported --lang values: zh (Chinese, default), en (English), ja (Japanese)
If the user writes in another language, fall back to en for chart text and reply in their language.

Pre-built Scripts (call directly, no rewriting needed)

Quick Start

Step 1 — Install dependencies

apk add rsvg-convert font-noto-cjk -q
python3 -c "import matplotlib, numpy" 2>/dev/null || apk add py3-matplotlib py3-numpy -q

Step 2 — Fetch data (write to /tmp to avoid workspace sync delay)

# 7-day weekly report
apple-healthkit sleep --days 8 --compact -q > /tmp/sleep_raw.json
apple-healthkit blood-oxygen --days 8 --limit 2000 --compact -q > /tmp/spo2_raw.json

# 30-day monthly trend
apple-healthkit sleep --days 31 --compact -q > /tmp/sleep_raw.json
apple-healthkit blood-oxygen --days 31 --limit 5000 --compact -q > /tmp/spo2_raw.json

Important: Always write raw data to /tmp/ first (not /var/minis/workspace/). The workspace directory has an iSH ↔ iOS sync delay that causes stale reads. Copy to workspace only after scripts finish.

Step 3 — Run the appropriate script

# ── 7-day weekly report card ──────────────────────────────────
python3 /var/minis/skills/health-sleep-analysis/sleep_report_data.py \
    --sleep /tmp/sleep_raw.json --spo2 /tmp/spo2_raw.json \
    --out /tmp/sleep_report_7d.json

python3 /var/minis/skills/health-sleep-analysis/sleep_report_librsvg.py \
    --data /tmp/sleep_report_7d.json \
    --out-prefix /tmp/sleep_report_7d \
    --lang zh                          # zh | en | ja

# ── 30-day monthly trend ──────────────────────────────────────
python3 /var/minis/skills/health-sleep-analysis/sleep_month_trend_librsvg.py \
    --days 30 \
    --sleep /tmp/sleep_raw.json --spo2 /tmp/spo2_raw.json \
    --out-prefix /tmp/sleep_month_trend \
    --lang zh                          # zh | en | ja

# ── Half-year trend (26 weeks, weekly aggregation) ────────────
apple-healthkit sleep --days 186 --compact -q > /tmp/sleep_raw.json
apple-healthkit blood-oxygen --days 186 --limit 10000 --compact -q > /tmp/spo2_raw.json
python3 /var/minis/skills/health-sleep-analysis/sleep_longterm_librsvg.py \
    --period halfyear \
    --sleep /tmp/sleep_raw.json --spo2 /tmp/spo2_raw.json \
    --out-prefix /tmp/sleep_halfyear \
    --lang zh                          # zh | en | ja

# ── Full-year trend (12 months, monthly aggregation) ──────────
apple-healthkit sleep --days 366 --compact -q > /tmp/sleep_raw.json
apple-healthkit blood-oxygen --days 366 --limit 10000 --compact -q > /tmp/spo2_raw.json
python3 /var/minis/skills/health-sleep-analysis/sleep_longterm_librsvg.py \
    --period year \
    --sleep /tmp/sleep_raw.json --spo2 /tmp/spo2_raw.json \
    --out-prefix /tmp/sleep_year \
    --lang zh

# ── Long-term trend (matplotlib, 30+ days) ───────────────────
DAYS=185
cd /var/minis/workspace
apple-healthkit sleep --days $((DAYS+1)) --compact -q > sleep_raw.json
apple-healthkit blood-oxygen --days $((DAYS+1)) --limit 10000 --compact -q > spo2_raw.json
python3 /var/minis/skills/health-sleep-analysis/sleep_halfyear.py
# 输出: sleep_halfyear.png（当前目录）

# ── Cardiac health ────────────────────────────────────────────
apple-healthkit heart-rate --days 30 --limit 5000 --compact -q > /tmp/hr_raw.json
apple-healthkit hrv --days 30 --limit 500 --compact -q > /tmp/hrv_raw.json
python3 /var/minis/skills/health-sleep-analysis/cardiac_analysis.py

Step 4 — Copy output and display

cp /tmp/sleep_report_7d.png /var/minis/workspace/sleep_report_7d.png
cp /tmp/sleep_month_trend.png /var/minis/workspace/sleep_month_trend.png

Display in chat with Markdown inline images. Follow up with a written analysis in the user's language.

Localization Reference

When rendering SVG charts, scripts accept --lang <code>. The following strings must be translated per language:

Script Argument Reference

sleep_report_data.py

--sleep   path to sleep_raw.json   (default: /var/minis/workspace/sleep_raw.json)
--spo2    path to spo2_raw.json    (default: /var/minis/workspace/spo2_raw.json)
--out     output JSON path         (default: /var/minis/workspace/sleep_report_7d.json)

sleep_report_librsvg.py

--data        input JSON from sleep_report_data.py
--out-prefix  SVG/PNG output prefix   (default: /var/minis/workspace/sleep_report_7d_librsvg)
--lang        zh | en | ja            (default: zh)
--width       canvas width px         (default: 1280)
--height      canvas height px        (default: 1760)

sleep_month_trend_librsvg.py

--days        number of nights to include  (default: 30)
--sleep       path to sleep_raw.json
--spo2        path to spo2_raw.json
--out-prefix  SVG/PNG output prefix        (default: /var/minis/workspace/sleep_month_trend)
--lang        zh | en | ja                 (default: zh)

Data Processing

Night attribution rule

Records between 00:00–13:59 belong to the previous calendar day (same sleep session):

def sleep_date(dt):
    return (dt - timedelta(days=1)).date() if dt.hour < 14 else dt.date()

Sleep stage mapping

HealthKit JSON field names

Raw samples use start / end (not startDate / endDate). Always check both:

ss = s.get('startDate') or s.get('start')
ee = s.get('endDate')   or s.get('end')

Workspace sync delay

Writing large files directly to /var/minis/workspace/ can result in iSH reading a stale cached version. Always:

1. Write data and outputs to /tmp/
2. Run scripts with /tmp/ paths
3. cp final PNGs to /var/minis/workspace/ for display

Health Standards

Sleep duration

Sleep stages

SpO2

Frequent drops below 95% (>20% of readings) or any reading below 90% warrants evaluation for obstructive sleep apnea (OSA), especially with snoring, daytime sleepiness, or morning headaches.

Resting Heart Rate (RHR)

Estimate RHR from raw heart rate data (lowest 25% of daily readings):

vals = sorted(by_day[date])
rhr = mean(vals[:max(1, len(vals)//4)])

HRV (SDNN)

Common Issues

Q: Only a few SpO2 readings?
A: Add --limit, use 2000 for short-term, 10000 for long-term.

Q: Chinese/Japanese characters show as boxes?
A: Run apk add font-noto-cjk first.

Q: Missing data for some nights?
A: Apple Watch likely not worn; nights with < 1h total are auto-filtered.

Q: Chart still shows stale data after re-running?
A: Write outputs to /tmp/ and use --sleep /tmp/... --spo2 /tmp/... arguments. Copy PNG to workspace only for display.

Q: 30-day chart shows only 6–7 bars?
A: The workspace JSON is stale. Fetch fresh data to /tmp/ and pass /tmp/ paths explicitly to the script.