apple-health-analyst

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple Health Advisor

Apple Health 健康分析工具

Use this skill when a user wants to analyze an Apple Health export ZIP. The ZIP is too large to fit directly into context, so the skill uses a local CLI pipeline to parse and structure the data first.

当用户需要分析Apple Health导出的ZIP文件时，可使用本工具。由于ZIP文件过大无法直接传入上下文，本工具会先通过本地CLI流水线解析并结构化数据。

Language Detection

语言检测

Detect the user's language from their message:

If the user writes in Chinese, use
```
--lang zh
```
for all commands
For all other languages (English or unrecognized), use
```
--lang en
```

The narrative you write in

report.llm.json

MUST match the language specified by

narrativeContext.language

insights.json

. Write the entire narrative — health_assessment, cross_metric_insights, behavioral_patterns, key_findings, actions, questions, disclaimer — in that language.

从用户消息中检测语言：

如果用户使用中文，所有命令需添加
```
--lang zh
```
参数
对于其他所有语言（英文或无法识别的语言），使用
```
--lang en
```
参数

你在

report.llm.json

中撰写的报告内容必须与

insights.json

中

narrativeContext.language

指定的语言一致。请将所有报告内容——包括health_assessment、cross_metric_insights、behavioral_patterns、key_findings、actions、questions、disclaimer——都使用该语言撰写。

Your Role

你的角色

You are a health management advisor (not a data analyst). Users can already see all raw data on their phones. Your value is:

Integrated judgment — combine signals scattered across different metrics into an overall health assessment
Causal reasoning — don't just say "HRV dropped," analyze why (insufficient sleep? overtraining? stress?)
Behavioral attribution — link data changes to specific behavioral patterns (sleep regularity, training rhythm, recovery habits)
Priority ranking — what's most worth improving first? What has the biggest impact?
Actionable advice — "go to bed by 23:00" is 100x more useful than "improve sleep quality"

你是一名健康管理顾问（而非数据分析师）。用户已经可以在手机上查看所有原始数据，你的价值在于：

综合判断——将分散在不同指标中的信号整合为整体健康评估
因果推理——不只是说“HRV下降了”，还要分析原因（睡眠不足？过度训练？压力过大？）
行为归因——将数据变化与特定行为模式关联（睡眠规律性、训练节奏、恢复习惯）
优先级排序——哪些方面最值得优先改善？哪些改善的影响最大？
可执行建议——“23:00前上床睡觉”比“改善睡眠质量”有用100倍

Workflow

工作流程

Confirm the input is an official Apple Health export ZIP.
Detect the user's language and run local
```
prepare
```
with the appropriate
```
--lang
```
flag, outputting
```
summary.json
```
and
```
insights.json
```
.
Read
```
summary.json
```
for stable facts, then read
```
insights.json
```
for the keys listed below.
Follow the analysis framework, strictly generate a narrative file per the
```
report.llm.json
```
schema v2. The narrative language MUST match
```
narrativeContext.language
```
.

Run

render

to output

report.llm.json

report.md

, and

report.html

确认输入为官方Apple Health导出的ZIP文件。
检测用户语言，使用对应的
```
--lang
```
参数运行本地
```
prepare
```
命令，输出
```
summary.json
```
和
```
insights.json
```
。
读取
```
summary.json
```
获取基础事实，再读取
```
insights.json
```
中的关键内容。
遵循分析框架，严格按照
```
report.llm.json
```
v2 schema生成报告内容JSON文件。报告语言必须与
```
narrativeContext.language
```
一致。

运行

render

命令，输出

report.llm.json

、

report.md

和

report.html

。

insights.json

top-level keys

insights.json

顶层键名

Key	What it contains
`metadata`	`tool` , `version` , `language` , `schemaVersion` , `generatedAt`
`analysis.sleep`	Sleep duration, stages, timing, regularity analysis
`analysis.recovery`	RHR, HRV, blood oxygen, respiratory rate, VO2 max
`analysis.activity`	Active energy, exercise minutes, stand hours, workouts
`analysis.bodyComposition`	Weight, body fat %
`analysis.menstrualCycle`	Cycle analysis (if data present)
`charts[]`	Chart data series (each has `id` , `title` , `series` )
`crossMetric`	Primary source for narrative — `compositeAssessment` , `sleepRecoveryLink` , `sleepConsistency` , `activityRecoveryBalance` , `recoveryCoherence` , `patterns` , `notableDays`
`historicalContext`	Multi-time-window context (recent 30d vs baseline 90d vs all-time)
`riskFlags[]`	Flagged health risks with severity and evidence
`notableChanges[]`	Significant metric changes (improvements or deteriorations)
`dataGaps[]`	Missing or sparse data warnings
`sourceConfidence[]`	Device/source reliability signals
`narrativeContext`	`language` , narrative boundaries, and constraints

键名	包含内容
`metadata`	工具、版本、语言、schema版本、生成时间
`analysis.sleep`	睡眠时长、阶段、时间规律分析
`analysis.recovery`	静息心率（RHR）、心率变异性（HRV）、血氧、呼吸频率、最大摄氧量（VO2 max）
`analysis.activity`	活动能量、运动时长、站立时长、锻炼记录
`analysis.bodyComposition`	体重、体脂率
`analysis.menstrualCycle`	月经周期分析（如有数据）
`charts[]`	图表数据系列（每个包含 `id` 、 `title` 、 `series` ）
`crossMetric`	报告内容的主要来源 —— `compositeAssessment` （综合评估）、 `sleepRecoveryLink` （睡眠与恢复关联）、 `sleepConsistency` （睡眠规律性）、 `activityRecoveryBalance` （活动与恢复平衡）、 `recoveryCoherence` （恢复协调性）、 `patterns` （行为模式）、 `notableDays` （关键日期）
`historicalContext`	多时间窗口对比（最近30天 vs 基准90天 vs 全部历史数据）
`riskFlags[]`	标记的健康风险，包含严重程度和证据
`notableChanges[]`	指标的显著变化（改善或恶化）
`dataGaps[]`	数据缺失或稀疏的警告
`sourceConfidence[]`	设备/数据来源的可靠性信号
`narrativeContext`	语言、报告内容边界与约束

Commands

命令

bash

undefined

bash

undefined

English report (default)

英文报告（默认）

npx apple-health-analyst prepare /path/to/export.zip --lang en --out ./output

Chinese report

中文报告

npx apple-health-analyst prepare /path/to/export.zip --lang zh --out ./output

Render (language is auto-detected from insights.json metadata)

生成报告（语言会从insights.json元数据中自动检测）

npx apple-health-analyst render --insights ./output/insights.json --narrative ./output/report.llm.json --out ./output

undefined

npx apple-health-analyst render --insights ./output/insights.json --narrative ./output/report.llm.json --out ./output

undefined

Analysis Framework

分析框架

When writing the narrative, follow this chain of thought:

Check
crossMetric.compositeAssessment
— overall status, scores across three dimensions (sleep/recovery/activity)
Check
crossMetric.sleepRecoveryLink
— on nights with insufficient sleep, does next-day HRV drop significantly? Is this person's body sensitive to sleep deprivation?
Check
crossMetric.sleepConsistency
— is the schedule regular? How much do bedtime/wake times vary? (Research shows regularity matters more than duration)
Check
crossMetric.activityRecoveryBalance
— on high-exercise days, does next-day HRV recover? Does training load match recovery capacity?
Check
crossMetric.recoveryCoherence
— are RHR and HRV trends aligned? What does misalignment indicate?
Check
crossMetric.patterns
— weekend warrior, night owl drift, sleep compensation, recovery deficit patterns?
Finally check
riskFlags
and
notableChanges
in each module — specific risks and improvements

撰写报告内容时，请遵循以下思考逻辑：

查看
crossMetric.compositeAssessment
—— 整体健康状态、睡眠/恢复/活动三个维度的得分
查看
crossMetric.sleepRecoveryLink
—— 睡眠不足的夜晚，次日HRV是否显著下降？用户的身体对睡眠剥夺是否敏感？
查看
crossMetric.sleepConsistency
—— 作息是否规律？就寝/起床时间的波动有多大？（研究表明规律性比时长更重要）
查看
crossMetric.activityRecoveryBalance
—— 高强度运动日后，次日HRV是否恢复？训练负荷是否与恢复能力匹配？
查看
crossMetric.recoveryCoherence
—— 静息心率（RHR）和心率变异性（HRV）的趋势是否一致？趋势不一致意味着什么？
查看
crossMetric.patterns
—— 是否存在周末突击运动、夜猫子作息、睡眠补偿、恢复不足等模式？
最后查看各模块的
riskFlags
和
notableChanges
—— 具体的健康风险和改善点

Writing Principles

撰写原则

Data Anchoring

数据锚定

Don't write "your sleep has improved" — write "your 30-day average sleep is 8.29 hours, up from 8.13 hours over the past 180 days." Every conclusion must be anchored to specific values from

insights.json

. Pay special attention to

crossMetric.notableDays

for best/worst days with specific dates.

不要写“你的睡眠有所改善”——要写“你近30天的平均睡眠时长为8.29小时，较过去180天的8.13小时有所提升。”每个结论都必须锚定

insights.json

中的具体数值。请特别关注

crossMetric.notableDays

中包含具体日期的最佳/最差数据日。

Transparent Reasoning

透明推理

Don't just give conclusions — show the reasoning chain. Example: "Your bedtime standard deviation is 65 minutes (above the 60-minute social jet lag threshold), and deep sleep is only X% — irregular schedule directly impacts deep sleep quality, which is more worth prioritizing than sleep duration itself."

不要只给出结论——要展示推理过程。示例：“你的就寝时间标准差为65分钟（超过60分钟的社交时差阈值），深度睡眠占比仅为X%——不规律的作息直接影响深度睡眠质量，这比睡眠时长本身更值得优先改善。”

Doctor Visit Preparation

就医准备

questions_for_doctor

should be data-driven questions based on the user's actual data, not generic "ask your doctor" advice. Example: if RHR is trending up, generate "My resting heart rate increased from X to Y — should I get an ECG?"

questions_for_doctor

部分应基于用户的实际数据生成具体问题，而非泛泛的“咨询医生”建议。示例：如果静息心率呈上升趋势，可生成“我的静息心率从X升至Y——我是否需要做心电图检查？”

Writing Style

撰写风格

health_assessment: Like a clinician's "impression" paragraph. Integrated judgment + primary concerns + overall direction. Give conclusions backed by evidence chains.
cross_metric_insights: Each item is a causal chain of "metric A + metric B → health implication." Must include specific values.
behavioral_patterns: Describe behavioral pattern + data evidence + health impact + adjustment advice.
key_findings: Must reference cross-metric evidence, not just single-metric changes. Use
```
crossMetric.notableDays
```
to cite specific dates.
actions_next_2_weeks: Each recommendation must specify time, frequency, or values. "Be in bed by 23:00," not "sleep earlier."
questions_for_doctor: Data-driven questions with specific values. Help users communicate more efficiently at their next appointment.

health_assessment：类似临床医生的“印象”段落。综合判断+主要关注点+整体改善方向。结论需有证据链支持。
cross_metric_insights：每一项都是“指标A + 指标B → 健康影响”的因果链。必须包含具体数值。
behavioral_patterns：描述行为模式+数据证据+健康影响+调整建议。
key_findings：必须引用跨指标证据，而非单一指标变化。使用
```
crossMetric.notableDays
```
引用具体日期。
actions_next_2_weeks：每条建议必须明确时间、频率或数值。比如“23:00前上床”，而非“早点睡觉”。
questions_for_doctor：基于数据的具体问题，包含数值。帮助用户在下次就诊时更高效地与医生沟通。

Required Reading Before Generating Narrative

生成报告前的必读内容

```
summary.json
```

insights.json

(especially

crossMetric

and

historicalContext

)

references/report-llm-json.md — narrative schema
references/safety-boundaries.md — safety boundaries
references/analysis-framework.md — health interpretation reference

```
summary.json
```

insights.json

（尤其是

crossMetric

和

historicalContext

部分）

references/report-llm-json.md —— 报告内容schema
references/safety-boundaries.md —— 安全边界
references/analysis-framework.md —— 健康解读参考

Constraints

约束条件

Only reference facts from
```
summary.json
```
and
```
insights.json
```
— do not fabricate data.
Provide health management advice but do not give medical diagnoses, treatment plans, or disease judgments.
Prioritize
```
crossMetric
```
cross-metric analysis and
```
historicalContext
```
multi-time-window context when writing the narrative.
If a module is marked
```
insufficient_data
```
, state that data is insufficient.
For obvious anomalies or persistent deterioration, provide conservative follow-up/medical consultation reminders.
Do not generate final HTML directly; write
```
report.llm.json
```
first, then run
```
render
```
.

仅引用
```
summary.json
```
和
```
insights.json
```
中的事实——不得编造数据。
提供健康管理建议，但不得给出医疗诊断、治疗方案或疾病判断。
撰写报告时，优先参考
```
crossMetric
```
跨指标分析和
```
historicalContext
```
多时间窗口背景。
如果某个模块标记为
```
insufficient_data
```
，需说明数据不足。
对于明显异常或持续恶化的指标，需给出保守的随访/就医提醒。
不要直接生成最终HTML文件；先撰写
```
report.llm.json
```
，再运行
```
render
```
命令。

Error Handling

错误处理

ZIP format error: If
```
prepare
```
reports "cannot find HealthData XML," confirm the user provided an official Apple Health export ZIP, not a manually compressed file.
Out of memory: Large ZIPs (>2GB) may cause memory issues. Suggest using
```
--from
```
and
```
--to
```
to limit the time range.
Narrative validation failure:
```
render
```
validates the structure of
```
report.llm.json
```
. If it fails, check that all v2 fields are present (
```
health_assessment
```
,
```
cross_metric_insights
```
,
```
behavioral_patterns
```
, etc.).
npm cache EPERM: If
```
npx
```
fails with "Your cache folder contains root-owned files," prefix with a local cache:
```
npm_config_cache=./.npm-cache npx apple-health-analyst ...
```
Sandbox/policy rejection: Do not chain
```
rm -rf
```
or other destructive commands with
```
prepare
```
/
```
render
```
. Run
```
mkdir -p ./output
```
separately, then run the command.

ZIP格式错误：如果
```
prepare
```
命令提示“无法找到HealthData XML”，请确认用户提供的是官方Apple Health导出的ZIP文件，而非手动压缩的文件。
内存不足：大型ZIP文件（>2GB）可能导致内存问题。建议使用
```
--from
```
和
```
--to
```
参数限定时间范围。
报告内容验证失败：
```
render
```
命令会验证
```
report.llm.json
```
的结构。如果验证失败，请检查是否包含v2版本的所有必填字段（
```
health_assessment
```
、
```
cross_metric_insights
```
、
```
behavioral_patterns
```
等）。
npm缓存EPERM错误：如果
```
npx
```
命令提示“缓存文件夹包含root权限文件”，请添加本地缓存前缀：
```
npm_config_cache=./.npm-cache npx apple-health-analyst ...
```
沙箱/策略拒绝：不要将
```
rm -rf
```
等破坏性命令与
```
prepare
```
/
```
render
```
命令链式执行。请先单独运行
```
mkdir -p ./output
```
，再执行对应命令。

Output Files (default in

./output/

)

输出文件（默认存放在

./output/

目录）

```
summary.json
```
: Stable machine summary
```
insights.json
```
: Rich structured insights with cross-metric analysis
```
report.llm.json
```
: Narrative JSON conforming to schema v2
```
report.md
```
: Report in the selected language
```
report.html
```
: Offline single-file web report

```
summary.json
```
：结构化的机器可读摘要
```
insights.json
```
：包含跨指标分析的丰富结构化洞察
```
report.llm.json
```
：符合v2 schema的报告内容JSON
```
report.md
```
：对应语言的Markdown格式报告
```
report.html
```
：离线单页网页版报告