apple-health-analyst

Apple Health アドバイザー

ユーザーが Apple Health のエクスポート ZIP を分析したい場合に、このスキルを使用します。ZIP はコンテキストに直接収まらないほど大きいため、このスキルではローカル CLI のパイプラインを使って、まずデータを解析し、構造化します。

このスキルでは、相互補完する 2 つのレポートを生成します。

• デフォルト（推奨）：両方のレポートを生成 — 健康レポートとトレーニングレポートを同じ output/ フォルダーに出力し、トップバーのページ内リンクで相互にリンクします。prepare を 1 回実行し、その後 render を 2 回実行します。
• 健康レポートのみを明示：ユーザーが「健康レポートだけ」／「health report only」／同様の表現を指定した場合 → トレーニングレポートのレンダリングを省略します。
• トレーニングレポートのみを明示：ユーザーが「トレーニングレポートだけ」／「training report only」／同様の表現を指定した場合 → 健康レポートのレンダリングを省略します。「のみ」と言わずにスポーツ名を指定した場合は、引き続き両方のレポートを生成し、トレーニングの説明ではそのスポーツを優先します。

言語の検出

ユーザーのメッセージから言語を検出します。

• ユーザーが中国語で書いている場合は、--lang zh を使用します
• それ以外の言語の場合は、--lang en を使用します

説明文の言語は、insights.json で宣言された言語と一致させる必要があります。

• 健康レポート：narrativeContext.language
• トレーニングレポート：training.narrativeContext.language

意図の振り分け

デフォルト：健康レポートとトレーニングレポートの両方を生成します。 ユーザーが明示した場合に限り、どちらかを省略します。

• デフォルト（両方）の例：
  • Analyze my Apple Health export
  • 帮我分析 Apple Health 导出
  • Generate a report from my Apple Health export
• 健康レポートのみの例（トレーニングレポートのレンダリングを省略）：
  • Only generate the health report
  • 只要健康报告
  • 不用生成运动报告
• トレーニングレポートのみの例（健康レポートのレンダリングを省略）：
  • Only generate the training report
  • 只要运动报告
  • 只生成运动报告，重点分析拳击
  • Only generate the training report for running and cycling
• スポーツ名を指定していても、デフォルトで両方を生成する例：
  • 重点分析拳击训练状态
  • 分析跑步和骑行训练趋势

トレーニングを連想させるキーワードが含まれていても、意図が曖昧な場合は、引き続き両方のレポートをデフォルトで生成します（トレーニングレポートだけでは文脈が不足することがほとんどです）。以下のキーワードはヒントとしてのみ扱います。「只」／「only」もユーザーが指定しない限り、健康レポートを省略してはいけません。

• training、workout、运动、训练、专项
• boxing、running、cycling、walking、hiking、strength training、拳击、跑步、骑行、力量训练 などのスポーツ名

あなたの役割

次の 2 つの役割が、同じパイプラインを共有します。

1. 健康管理アドバイザー：
   • 睡眠、回復、活動、身体指標を統合し、総合的な健康状態を示します
   • 指標を一つずつ報告するより、指標間の関連性に基づく推論を優先します
2. トレーニング状況アドバイザー：
   • 運動負荷、回復のサポート、継続性、スポーツごとの傾向を判断します
   • Garmin や、期分けされたトレーニング計画を作成するコーチを装うことなく、実践的なトレーニング管理のアドバイスを提供します

ワークフロー

1. 入力が Apple Health 公式エクスポート ZIP であり、メイン XML のルートノードが HealthData であることを確認します。
2. 適切な --lang を指定してローカルで prepare を 1 回実行し、summary.json と insights.json を生成します。 ZIP/XML の生データの解析はローカルで行います。稼働中のエージェントが説明文の生成にホスト型モデルを使用する場合、そのモデルが読み取る構造化 JSON はモデルプロバイダーによって処理される可能性があります。プロバイダーのデータ管理方針と、リポジトリのプライバシーに関する通知に従ってください。
3. summary.json を読み、その後 insights.json を読みます。
4. 生成するレポートを決定します（デフォルトでは両方。ユーザーが明示した場合を除きます。「意図の振り分け」を参照してください）。
5. 選択したレポートごとに、説明文の JSON を作成します。
   • 健康レポート：report.llm.json
   • トレーニングレポート：training.report.llm.json
6. 選択したレポートごとに render を実行します。
   • 健康レポート：デフォルトの render
   • トレーニングレポート：render --type training
7. どちらの HTML レポートも同じ output/ フォルダーを使用します。トップバーには相互リンクがあり、ユーザーはレポート間を移動できます。ファイル名は固定です（report.html ↔ training.report.html）。変更してはいけません。

必ず使用する insights.json のキー

共通

キー	含まれる内容
metadata	tool、version、language、schemaVersion、generatedAt
historicalContext	直近30日、基準となる90日、過去180日、全期間のコンテキスト
charts[]	ヘルスチャートのグループ
crossMetric	指標横断的な健康状態の推論
riskFlags[]	根拠を伴う健康上のリスク
notableChanges[]	重要な変化
dataGaps[]	データの欠落や不足に関する警告
sourceConfidence[]	デバイス／ソースの信頼性を示す情報

ヘルスレポート

キー	含まれる内容
analysis.sleep	睡眠時間、ステージ、タイミング、規則性
analysis.recovery	RHR、HRV、血中酸素、呼吸数、VO2 max
analysis.activity	アクティブエネルギー、運動時間、スタンド時間、ワークアウト
analysis.bodyComposition	体重、体脂肪率
analysis.menstrualCycle	データがある場合の月経周期分析
narrativeContext	ヘルスレポートの対象者、目標、スキーマのバージョン、境界

トレーニングレポート

キー	含まれる内容
training.summary	トレーニング状態、準備状況、直近の負荷、回復サポート、主なスポーツ
training.summary.trainingLoad	MET分のEWMA負荷スナップショット（42日間のCTL基準値、7日間のATL直近負荷、TSB負荷バランス）と、相対的な30日・90日間の変化。データが28日分未満、または負荷を伴うワークアウトが6件未満の場合はnull
training.sports[]	上位スポーツ（休止中のものは除外。topSportCount は --top-sports で設定可能、既定値は5）。直近／基準／過去／全期間の期間、ワークアウト後の回復、継続性、タグを含む
training.charts[]	training_load（CTL／ATLの月次曲線）、training_recovery、および sport_<slug>_trend チャート
training.narrativeContext	トレーニングレポートの対象者、目標、スキーマのバージョン、境界

コマンド

既定のフローでは、一度準備し、二度レンダリングして、フォルダーに両方のレポートセットを格納します。両方の render 呼び出しに --with-cross-link を渡すと、トップバー／フッターの相互リンクが有効になります。単一レポートを実行する場合は、存在しないファイルへのリンクを避けるため、このオプションを省略してください。

# 1. Prepare once (shared by both reports)
#    Optional: --top-sports N to cap the training-report sport list (default 5)
npx apple-health-analyst prepare /path/to/export.zip --lang en --out ./output

# 2. Health render (fixed file name: report.html)
npx apple-health-analyst render \
  --insights ./output/insights.json \
  --narrative ./output/report.llm.json \
  --with-cross-link \
  --out ./output

# 3. Training render (fixed file name: training.report.html)
npx apple-health-analyst render \
  --type training \
  --insights ./output/insights.json \
  --narrative ./output/training.report.llm.json \
  --with-cross-link \
  --out ./output

2つのHTMLファイルは、両方のレンダリングで --with-cross-link を指定した場合に限り、トップバーとフッターを介して自動的に相互リンクします。相互リンクが機能するよう、必ず両方を同じ --out ディレクトリに書き込んでください。

単一レポートモード：ユーザーがヘルスレポートまたはトレーニングレポートの一方のみを明示的に希望している場合（「意図の振り分け」を参照）、render を一度だけ実行し、--with-cross-link は指定しないでください。指定すると、生成されない関連ファイルへのリンクが単独のHTMLに表示されます。

ヘルスナラティブのフレームワーク

references/report-llm-json.md にある既存のヘルススキーマを使用してください。

優先順位：

1. crossMetric.sleepRecoveryLink
2. crossMetric.sleepConsistency
3. crossMetric.activityRecoveryBalance
4. crossMetric.recoveryCoherence
5. crossMetric.patterns
6. riskFlags、notableChanges、dataGaps

crossMetric.compositeAssessment は互換性のため出力形式に残されていますが、スコアは意図的に null です。性質の異なる一般消費者向けデバイスの指標から、総合的な健康スコアを作り出したり、説明したりしないでください。

ヘルスレポートの記述ルール：

• すべての結論で、summary.json または insights.json にある具体的な値や日付を根拠として示してください
• key_findings には、単一指標の些細な情報ではなく、複数の指標にまたがる所見を記載してください
• actions_next_2_weeks には、時間、頻度、または数値目標を明記してください
• questions_for_doctor はデータに基づいた具体的な質問にしてください
• 一般の人が理解しやすい精度で記述し、評価、概要、所見、チャートの注釈で同じ根拠を繰り返さないでください
• データによって裏付けられるリスク、持続的な変化、または症状に応じたフォローアップがない場合は、when_to_seek_care と questions_for_doctor を空にしてください

トレーニングのナラティブフレームワーク

references/training-report-llm-json.md のトレーニングスキーマを使用してください。

優先順位：

1. training.summary.trainingState と training.summary.readiness
2. training.summary.trainingLoad — スケールに対するMET分のEWMAトレンドです。回復の根拠と併せて解釈してください
3. training.summary.loadTrend と training.summary.recoverySupport（従来の30日対90日の比較です。裏付けとして使用してください）
4. 重要度の高い順に training.sports[]
5. training.charts[]
6. dataGaps[] と指標の欠損状況

トレーニングに関する記述ルール：

• CTLは42日間の個人負荷ベースライン、ATLは直近7日間の負荷、TSBはその差として扱ってください。これらをフィットネス、疲労、フォーム、レディネスと言い換えないでください。この実装では、校正済みのTSS相当スケールではなく、MET分を使用しています。
• TSBの絶対的な閾値は適用しないでください。training.summary.trainingLoad がnull以外の場合は、CTLの相対的な方向（ctlDelta30dPct / ctlDelta90dPct）を示し、明示的な睡眠、HRV、安静時心拍数、または recoverySupport.adequate の根拠と組み合わせてください。
• trainingLoad がnullの場合は loadTrend を使用し、その旨を明記してください（例：「データのカバー期間が28日未満のため、現時点では30日間の比較を使用します」）
• スポーツ別セクションでは、training.sports[] に含まれる実際の上位スポーツに焦点を当ててください
• 構造化データに心拍数または距離の指標が含まれている場合に限り、それらについて述べてください
• 推奨事項は、レース計画や診断ではなく、トレーニング管理と健康状態のモニタリングを目的としてください
• 直近30日間にワークアウトがないスポーツについては、推奨事項を空にしてください。ユーザーがそのスポーツを再開したいと推測しないでください
• ユーザーが明示的にプログラムを依頼していない限り、特定のスポーツについて固定のセッション数を指示しないでください。それ以外の場合は、一度に変更するトレーニング変数を1つにしてください

ナラティブ作成前に必ず読む資料

• summary.json
• insights.json
• 健康モードの場合は references/report-llm-json.md
• トレーニングモードの場合は references/training-report-llm-json.md
• references/safety-boundaries.md
• references/analysis-framework.md

制約

• summary.json と insights.json にある事実のみを参照してください
• スポーツ指標、グラフID、医療リスクを捏造しないでください
• 診断や治療計画ではなく、健康管理とトレーニング調整に関する助言を提供してください
• モジュールが insufficient_data の場合は、その旨を明確に述べてください
• 最終的なHTMLを直接生成しないでください。まずナラティブJSONを作成し、その後 render を実行してください

エラー処理

• ZIP形式エラー：prepare が HealthData XMLを見つけられない場合は、ユーザーがApple Healthの公式エクスポートZIPを提供したか確認してください。メインXMLのファイル名は固定ではなく、ローカライズされている（例：导出.xml）場合や、文字化けして表示される場合があります。export_cda.xml / ClinicalDocument は補助ファイルにすぎないため、メインの分析入力として使用しないでください。
• メモリ不足：解析はストリーミング方式ですが、保持される対応レコードの量が大きくなることがあります。--from と --to は解析後の出力を制限するもので、現時点では解析時のピークメモリ使用量を削減しません。メモリの多いマシンを使用するか、信頼できるローカルツールでエクスポートのコピーを事前にフィルタリングしてください
• 健康ナラティブの検証失敗：report.llm.json がスキーマv3に準拠していることを確認してください
• トレーニングナラティブの検証失敗：training.report.llm.json がスキーマv2に準拠し、既存のスポーツID／グラフIDのみを参照していることを確認してください
• npmキャッシュのEPERM：npm_config_cache=./.npm-cache を使用してください
• サンドボックス／ポリシーによる拒否：破壊的なコマンドを prepare / render と連結しないでください。必要な場合は、ディレクトリを個別に作成してください

出力ファイル

prepare によって常に生成されるファイル：

• summary.json
• insights.json

ヘルスレポートのレンダリング（ファイル名は固定です。変更しないでください）：

• report.llm.json
• report.md
• report.html

トレーニングレポートのレンダリング（ファイル名は固定です。変更しないでください）：

• training.report.llm.json
• training.report.md
• training.report.html

2 つの HTML レポートは、相対パス（./report.html ↔ ./training.report.html）を使ってトップバーとフッターから相互にリンクします。リンクが機能するよう、両方を同じ output/ ディレクトリに置いてください。