Health Tracker

固定寫入目標

除非使用者明確指定檔名或要求整理 legacy 文件，health-tracker 的 routine output 只能落在以下 canonical targets：

• raw capture：notes/claw/health/raw/YYYY/MM/DD/<timestamp>-<record-type>-<source>.md
• daily log：notes/claw/health/daily/YYYY-MM-DD.md
• monthly report：notes/claw/health/reports/monthly/YYYY-MM.md
• quarterly report：notes/claw/health/reports/quarterly/YYYY-QN.md
• yearly report：notes/claw/health/reports/yearly/YYYY.md

不要為一般記錄任務新增 notes/claw/health/*.md top-level 檔案，也不要把 routine data 寫到 diet.md、sleep.md、training.md、body_composition.md、DESIGN.md 這類 legacy 檔案。這些 legacy 檔案只能當參考來源，不能當新的日常寫入目標。

何時使用這個 skill

當任務符合以下情況時，使用 health-tracker：

• 要記錄餐盤照片、重訓截圖、用藥筆記、檢驗報告、睡眠資料或身體組成更新
• 要做每日健康追蹤或狀態檢視
• 要看熱量預算、剩餘熱量、蛋白質目標進度或營養缺口
• 要產生月報、季報或年報
• 需要把健康相關 artifacts 寫入 notes/claw/health

不要用在這些情況

• 緊急症狀或急性風險判斷
• 診斷、治療決策或調藥建議
• 在沒有證據時編造數據
• 假裝目前環境已經有不存在的健康 API

資料來源規則

• 若 GarminDB runtime 可用，優先使用 health-tracker-garmin sync-and-ingest --latest 或 ingest-garmin 將 Garmin Connect 資料匯入 canonical raw/、daily/，並刷新受影響的 reports/
• Garmin secrets 一律留在 repo 外的 ~/.GarminDb/GarminConnectConfig.json，並使用 credentials.password_file
• 若目前環境可用，優先使用 gws-compatible health connector
• 不要捏造像 gws fit、gws health、gws sleep 這種不存在的指令
• 若 connector 不可用，依序退回：
  • Telegram 文字
  • Telegram 照片或截圖
  • 匯出的 CSV / JSON / PDF / text
  • 使用者手動輸入
  • notes/claw/health 內既有檔案
• 每一筆資料都要保留來源追溯資訊

語言規則

• 日誌、報表、欄位標題、摘要與缺資料說明預設使用 zh-TW
• 藥名、保健品名稱、檢驗項目、原始表格欄名可保留原文，再補上 zh-TW 說明
• 若來源內容是英文或 OCR 文字，raw record 保留原文，daily 與 report 用 zh-TW 整理
• 檔名可維持英文與日期格式，但檔案內容預設為 zh-TW

角色分工

PicoClaw

• 辨識任務類型與日期範圍
• 收集可用輸入
• 讀取截圖、餐盤照片、文字筆記或報告
• 呼叫可用工具或 connector
• 將檔案寫入 notes/claw/health
• 回覆精簡摘要，並說明信心與缺資料情況

health-tracker

• 將混合來源健康資料正規化為單一日紀錄
• 保守估算餐點內容
• 追蹤活動、睡眠、訓練、用藥、檢驗與身體組成
• 產生日報、月報、季報、年報
• 明確標示不確定性、缺值與待補資料

內部分工

health-intake-normalizer

• 將每筆輸入分類為 activity、sleep、meal、training、medication、lab、body-composition 或 general
• 將時間轉成在地日期
• 保留來源類型與原始文字
• 分析前先存 raw capture

meal-estimator

• 估算份量、熱量、三大營養素與可能的微量營養覆蓋
• 盡量依照食物外觀、份量線索與可見標示
• 將信心標記為 high、medium 或 low

activity-sleep-analyzer

• 整理步數、距離、活動時間、運動與睡眠
• 若資料足夠，與近期 baseline 比較
• 對未知欄位保持明確，不補幻想值

medication-lab-recorder

• 轉錄藥名、劑量、時間、檢驗值、單位、參考區間與身體組成指標
• 若畫面沒寫清楚，不可自行推定藥名、劑量或檢驗值
• 對不完整或模糊資訊加註

report-builder

• 產生日報、月報、季報、年報
• 與前一期比較
• 標出缺資料、低信心估值與趨勢變化
• 報表更新後，若 runtime 已設定 Telegram 通知，發送本次更新摘要

必要流程

1. 先決定日期範圍

   • 若使用者有明確日期，就用該日期
   • 若是即時餐點或運動紀錄，預設使用這次 capture 的在地日期；若原始資料已帶時間戳，先用原始時間戳換算 local_date，不要每次重新猜日期
   • 若日期不明，摘要中要直接說明

2. 先檢查模板

   • 若目標日誌或報表不存在，優先從對應模板建立
   • 優先使用 live templates root
   • 若 live templates 不存在，再依 repo templates root 的欄位結構建立

3. 先保存 raw 證據

   • 在做彙總前，先在 raw/ 寫一筆原始紀錄
   • 保留原始文字、OCR 結果或 connector 輸出
   • 記錄來源、時間與信心
   • captured_at 只生成或採信一次，格式固定為 ISO 8601 with offset，例如 2026-04-02T11:35:19+08:00
   • raw 檔名中的 <timestamp> 必須由同一個 captured_at 正規化為 YYYYMMDDTHHMMSSZZ，例如 20260402T113519+0800

4. 更新 daily record

   • 將該輸入合併到對應日期的 daily 檔
   • 只更新相關區塊
   • 不要用較弱的猜測覆蓋較強的證據
   • 若 daily 檔已存在，只更新相關區塊與 原始紀錄索引，不要整份重寫
   • 不要因為摘要方式改變就改寫既有欄位標題、區塊順序或檔名格式

5. 只估算能支撐的內容

   • 有標示、表格或明確數字時，用精確值
   • 沒有精確值時，才使用 heuristic
   • 所有估值都要附信心

6. 只在有需要時產生週期報表

   • daily: 當日追蹤
   • monthly: 月度趨勢與遵循情況
   • quarterly: 較廣的趨勢與一致性
   • yearly: 高層級長期變化

7. 報表更新後送出通知

   • 若 runtime notification 已設定 Telegram，發送精簡摘要
   • 只在報表實際變更時通知，避免重複打擾
   • 摘要需說明更新了哪些報表與最重要的變化

8. 回覆要精簡

   • 說明這次寫入了什麼
   • 列出最重要的計算值
   • 說明缺資料或低信心項目
   • 需要時附上檔案路徑

穩定性規則

• daily 檔名固定使用 YYYY-MM-DD.md；不要使用 YYYYMMDD.md、today.md、latest.md 或其他變體
• monthly 檔名固定使用 YYYY-MM.md，月份必須補零
• quarterly 檔名固定使用 YYYY-QN.md，N 只能是 1、2、3、4
• yearly 檔名固定使用 YYYY.md
• local_date 與 date 一律使用 YYYY-MM-DD
• weekday 一律使用 週一、週二、週三、週四、週五、週六、週日
• 同一筆事件先寫一次 raw capture，再把事實合併到對應 daily；不要因為補充整理就另外生出第二份 daily
• 同一天的後續補充只更新既有 daily 檔；除非使用者明確要求，不要另開 summary、memo、scratch 或 top-level health 檔案
• 若遇到 legacy 檔案與 canonical 檔案並存，新的事實一律寫入 canonical 檔案，legacy 檔案只保留為參考

模板檔案

若要新建檔案，優先使用以下模板：

• canonical live template root：/home/haman/.picoclaw/workspace/notes/claw/health/templates
• skill-local template mirror：/home/haman/.picoclaw/workspace/skills/health-tracker/templates
• raw record template: /home/haman/.picoclaw/workspace/notes/claw/health/templates/raw-record-template.md
• daily log template: /home/haman/.picoclaw/workspace/notes/claw/health/templates/daily-log-template.md
• monthly report template: /home/haman/.picoclaw/workspace/notes/claw/health/templates/reports/monthly-report-template.md
• quarterly report template: /home/haman/.picoclaw/workspace/notes/claw/health/templates/reports/quarterly-report-template.md
• yearly report template: /home/haman/.picoclaw/workspace/notes/claw/health/templates/reports/yearly-report-template.md

若 live template 尚未同步，可參考 repo 版本：

• /home/haman/custom-claw-tools/health-tracker/templates/raw-record-template.md
• /home/haman/custom-claw-tools/health-tracker/templates/daily-log-template.md
• /home/haman/custom-claw-tools/health-tracker/templates/reports/monthly-report-template.md
• /home/haman/custom-claw-tools/health-tracker/templates/reports/quarterly-report-template.md
• /home/haman/custom-claw-tools/health-tracker/templates/reports/yearly-report-template.md

Raw record 規格

每筆 raw record 至少保留：

• captured_at
• local_date
• source_type (connector, telegram-photo, telegram-text, manual, lab-report, body-composition, import)
• source_ref
• record_type
• raw_text
• structured_fields
• confidence
• notes

建議檔名格式：

• raw/YYYY/MM/DD/<timestamp>-<record-type>-<source>.md
• <timestamp> 一律使用由 captured_at 正規化後的 YYYYMMDDTHHMMSSZZ

Daily record 規格

每份 daily 檔案應在有資料時包含以下區塊：

• date
• activity
  • steps
  • distance
  • active_minutes
  • exercise_sessions
  • estimated_calories_burned
• sleep
  • duration
  • bedtime
  • wake_time
  • awakenings
  • sleep_score_or_quality
• meals
  • meal_time
  • estimated_portion
  • estimated_calories
  • protein_g
  • carbs_g
  • fat_g
  • fiber_g
  • likely_micronutrient_notes
• training
  • exercise_name
  • sets
  • reps
  • load
  • tonnage_if_known
• medication
  • medication_name
  • dose
  • timing
  • adherence_note
• labs
  • test_name
  • value
  • unit
  • reference_range
  • flag_if_visible
• body_composition
  • weight
  • body_fat_percent
  • skeletal_muscle
  • bmi_if_given
• energy_budget
  • intake_kcal
  • target_kcal
  • remaining_kcal
  • protein_target_progress
• data_quality
  • missing_inputs
  • low_confidence_items
  • follow_up_needed

建議檔名格式：

• daily/YYYY-MM-DD.md
• date 欄位與檔名必須一致，不可一個用 2026-04-02、另一個用 20260402

報表規格

Monthly report

應包含：

• 平均步數
• 平均睡眠時數
• 訓練頻率
• 若資料足夠，平均熱量攝取
• 若資料足夠，平均蛋白質攝取
• 體重與體脂趨勢
• 遵循情況摘要
• 缺資料摘要
• 與前一月比較

建議檔名格式：

• reports/monthly/YYYY-MM.md
• MM 必須補零，例如 2026-04.md

Quarterly report

應包含：

• 每月趨勢表
• 活動量趨勢
• 睡眠趨勢
• 訓練一致性
• 體重 / 身體組成趨勢
• 熱量收支趨勢
• 飲食模式摘要
• 主要優點、缺口與注意事項
• 與前一季比較

建議檔名格式：

• reports/quarterly/YYYY-QN.md
• Q1=01-03、Q2=04-06、Q3=07-09、Q4=10-12

Yearly report

應包含：

• 年度總覽
• 主要趨勢變化
• 最穩定與最不穩定的面向
• 身體組成變化
• 訓練量模式
• 睡眠與活動模式
• 飲食模式摘要
• 資料完整度摘要
• 與前一年比較

建議檔名格式：

• reports/yearly/YYYY.md

餐點估算規則

使用以下信任順序：

1. 明確標示或已知營養表
2. 使用者明確提供重量或份量
3. 清晰照片且食物可辨識
4. 粗略 plate heuristic
5. unknown

Portion heuristics

當沒有精確重量時，使用簡單視覺規則：

• 1 個手掌大小瘦蛋白 ~= 20-30 g 蛋白質
• 1 個拳頭大小熟澱粉 ~= 25-40 g 碳水
• 1 個拇指大小額外脂肪 ~= 7-12 g 脂肪
• 1 杯非澱粉類蔬菜通常熱量較低，除非明顯有大量油或醬

Plate heuristic

若是一般餐盤照片且細節不足：

• 半盤蔬菜
• 四分之一盤蛋白質
• 四分之一盤澱粉

只有在畫面明顯不同時才調整。

Mixed dishes

對湯品、咖哩、炒飯、便當、麵類、燴飯等混合料理：

• 採保守估算
• 明確註記隱藏油脂、醬料、糖分或裹粉不確定性
• 若食材不明，不要宣稱精確 macro

熱量與營養規則

• 蛋白質使用 4 kcal/g
• 碳水使用 4 kcal/g
• 脂肪使用 9 kcal/g
• 若總熱量由 macro 推回，需與上述係數一致
• remaining_kcal = target_kcal - intake_kcal
• 若目標熱量已含一般活動量，不要再重複扣抵活動消耗
• 若有額外運動消耗數值，要說明如何使用
• 若使用者沒有明確蛋白質目標，可用保守 heuristic 追蹤，但要明講這是 heuristic，不是處方
• 微量營養素盡量使用質性描述，除非來源很強：
  • likely covered
  • possibly low
  • insufficient evidence

建議追蹤的營養重點：

• protein
• fiber
• calcium
• iron
• magnesium
• potassium
• vitamin D
• vitamin C
• omega-3

睡眠規則

• 優先使用可信來源提供的明確睡眠時數或分數
• 若沒有分數，就用可得訊號摘要：
  • 總睡眠時數
  • 入睡時間一致性
  • 起床時間一致性
  • 若已知，夜間醒來次數
• 不要編造睡眠分期或 recovery score

訓練規則

• 畫面可見時，記錄確切的 sets、reps 與 load
• 若只有完成組數截圖，就只記錄畫面可見內容
• 只有在 sets、reps、load 都明確時才計算 tonnage
• 若動作名稱不清楚，保留原始標籤並註記模糊

信心規則

使用以下標記：

• high
  • 明確標示、明確份量、精確 connector 輸出，或清楚結構化報告
• medium
  • 清晰照片且食物可辨識，或運動數據可讀
• low
  • 部分畫面、隱藏食材、模糊截圖，或不完整報告

Guardrails

• 不做疾病診斷
• 不建議調藥
• 不取代醫師、藥師或營養師
• 不捏造測量值、檢驗值或 connector 輸出
• 只要是估值，就要明講是估值
• 缺資料就要明講缺資料
• 保留絕對日期與單位
• 保留來源追溯資訊
• 若檢驗報告或用藥紀錄不完整，只記錄可見事實
• 若使用者提到急性危險症狀，要提醒盡快尋求專業協助

輸出風格

回覆時：

• 先講主要結果
• 顯示最重要數值
• 說明信心
• 列出缺資料
• 說明更新或建立了哪個檔案

保持簡短、結構化、誠實，並預設使用 zh-TW。