名称： garmer
描述： 从 Garmin Connect 提取健康和健身数据，包括活动、睡眠、心率、压力、步数和身体成分。当用户询问其 Garmin 数据、健身指标、睡眠分析或健康洞察时使用。
许可证： MIT
compatibility: 需要 Python 3.10+，使用 pip/uv 安装。需要 Garmin Connect 账户凭证进行身份验证。
元数据：
author: MoltBot Team
version: "0.1.0"
moltbot:
emoji: "⌚"
primaryEnv: "GARMER_TOKEN_DIR"
requires:
bins:
- garmer
install:
- id: uv
kind: uv
package: garmer
bins:
- garmer
label: 安装 garmer (uv)
- id: pip
kind: pip
package: garmer
bins:
- garmer
label: 安装 garmer (pip)

Garmer - Garmin 数据提取技能

此技能用于从 Garmin Connect 提取健康和健身数据，以便进行分析和获取洞察。

前提条件

1. 拥有包含健康数据的 Garmin Connect 账户。
2. 已安装 garmer CLI 工具（安装选项见元数据部分）。

身份验证（一次性设置）

在使用 garmer 之前，需要先登录 Garmin Connect：

garmer login

此命令将提示您输入 Garmin Connect 的邮箱和密码。令牌将保存至 ~/.garmer/garmin_tokens 以供后续使用。

检查身份验证状态：

garmer status

可用命令

每日摘要

获取今日健康摘要（步数、卡路里、心率、压力）：

garmer summary
# 指定日期：
garmer summary --date 2025-01-15
# 包含昨晚的睡眠数据：
garmer summary --with-sleep
garmer summary -s
# 以 JSON 格式输出，便于程序化处理：
garmer summary --json
# 组合使用标志：
garmer summary --date 2025-01-15 --with-sleep --json

睡眠数据

获取睡眠分析（时长、阶段、分数、HRV）：

garmer sleep
# 指定日期：
garmer sleep --date 2025-01-15

活动

列出最近的健身活动：

garmer activities
# 限制结果数量：
garmer activities --limit 5
# 按特定日期筛选：
garmer activities --date 2025-01-15
# 以 JSON 格式输出：
garmer activities --json

活动详情

获取单个活动的详细信息：

# 最新活动：
garmer activity
# 按 ID 指定活动：
garmer activity 12345678
# 包含分段数据：
garmer activity --laps
# 包含心率区间数据：
garmer activity --zones
# 以 JSON 格式输出：
garmer activity --json
# 组合使用标志：
garmer activity 12345678 --laps --zones --json

健康快照

获取某一天的综合健康数据：

garmer snapshot
# 指定日期：
garmer snapshot --date 2025-01-15
# 以 JSON 格式输出：
garmer snapshot --json

导出数据

将多日数据导出为 JSON：

# 最近 7 天（默认）
garmer export

# 自定义日期范围
garmer export --start-date 2025-01-01 --end-date 2025-01-31 --output my_data.json

# 最近 N 天
garmer export --days 14

实用命令

# 更新 garmer 到最新版本（git pull）：
garmer update

# 显示版本信息：
garmer version

Python API 使用

对于更复杂的数据处理，可以使用 Python API：

from garmer import GarminClient
from datetime import date, timedelta

# 使用已保存的令牌
client = GarminClient.from_saved_tokens()

# 或使用凭证登录
client = GarminClient.from_credentials(email="user@example.com", password="pass")

用户资料

# 获取用户资料
profile = client.get_user_profile()
print(f"用户：{profile.display_name}")

# 获取已注册设备
devices = client.get_user_devices()

每日摘要

# 获取每日摘要（默认为今天）
summary = client.get_daily_summary()
print(f"步数：{summary.total_steps}")

# 获取指定日期摘要
summary = client.get_daily_summary(date(2025, 1, 15))

# 获取每周摘要
weekly = client.get_weekly_summary()

睡眠数据

# 获取睡眠数据（默认为今天）
sleep = client.get_sleep()
print(f"睡眠：{sleep.total_sleep_hours:.1f} 小时")

# 获取昨晚睡眠数据
sleep = client.get_last_night_sleep()

# 获取日期范围内的睡眠数据
sleep_data = client.get_sleep_range(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 1, 7)
)

活动

# 获取最近的活动
activities = client.get_recent_activities(limit=5)
for activity in activities:
    print(f"{activity.activity_name}: {activity.distance_km:.1f} km")

# 使用筛选器获取活动
activities = client.get_activities(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 1, 31),
    activity_type="running",
    limit=20
)

# 按 ID 获取单个活动
activity = client.get_activity(12345678)

心率

# 获取某天的心率数据
hr = client.get_heart_rate()
print(f"静息心率：{hr.resting_heart_rate} bpm")

# 仅获取静息心率
resting_hr = client.get_resting_heart_rate(date(2025, 1, 15))

压力与身体电量

# 获取压力数据
stress = client.get_stress()
print(f"平均压力：{stress.avg_stress_level}")

# 获取身体电量数据
battery = client.get_body_battery()

步数

# 获取详细的步数数据
steps = client.get_steps()
print(f"总计：{steps.total_steps}，目标：{steps.step_goal}")

# 仅获取总步数
total = client.get_total_steps(date(2025, 1, 15))

身体成分

# 获取最新体重
weight = client.get_latest_weight()
print(f"体重：{weight.weight_kg} kg")

# 获取指定日期体重
weight = client.get_weight(date(2025, 1, 15))

# 获取完整的身体成分数据
body = client.get_body_composition()

补水与呼吸

# 获取补水数据
hydration = client.get_hydration()
print(f"摄入量：{hydration.total_intake_ml} ml")

# 获取呼吸数据
resp = client.get_respiration()
print(f"平均呼吸：{resp.avg_waking_respiration} 次/分钟")

综合报告

# 获取健康快照（某天所有指标）
snapshot = client.get_health_snapshot()
# 返回：daily_summary, sleep, heart_rate, stress, steps, hydration, respiration

# 获取包含趋势的每周健康报告
report = client.get_weekly_health_report()
# 返回：activities summary, sleep stats, steps stats, HR trends, stress trends

# 导出日期范围内的数据
data = client.export_data(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 1, 31),
    include_activities=True,
    include_sleep=True,
    include_daily=True
)

常见工作流

健康检查查询

当用户询问“我睡得怎么样？”或“我的健康摘要是什么？”时：

garmer snapshot --json

活动分析

当用户询问锻炼或运动情况时：

garmer activities --limit 10

趋势分析

分析一段时间内的健康趋势时：

garmer export --days 30 --output health_data.json

然后使用 Python 处理 JSON 文件进行分析。

可用数据类型

• 活动：跑步、骑行、游泳、力量训练等。
• 睡眠：时长、阶段（深睡、浅睡、REM）、分数、HRV。
• 心率：静息心率、样本、区间。
• 压力：压力水平、身体电量。
• 步数：总步数、距离、楼层。
• 身体成分：体重、体脂率、肌肉量。
• 补水：饮水量追踪。
• 呼吸：呼吸频率数据。

错误处理

如果未通过身份验证：

未登录。请先使用 'garmer login'。

如果会话过期，请重新验证：

garmer login

环境变量

• GARMER_TOKEN_DIR：自定义令牌存储目录。
• GARMER_LOG_LEVEL：设置日志级别（DEBUG, INFO, WARNING, ERROR）。
• GARMER_CACHE_ENABLED：启用/禁用数据缓存（true/false）。

参考

详细的 API 文档和 MoltBot 集成示例，请参阅 references/REFERENCE.md。