Garminskill

核心用法

Garmin Connect Skill 通过命令行工具将 Garmin 穿戴设备的健康数据自动同步到本地 Markdown 文件。用户首次需运行 --setup 完成邮箱认证，获取缓存的 OAuth Token（有效期约一年），后续无需重复输入密码。支持同步今日数据、指定日期或过去 N 天的历史记录，文件按 YYYY-MM-DD.md 格式存储于 {baseDir}/health/ 目录。

运行依赖 uv（Astral 出品的 Python 包管理器），自动处理 garminconnect 和 cloudscraper 等依赖，无需手动配置 Python 环境。

显著优点

1. 数据本地化：原始健康数据以可读 Markdown 格式存储，便于长期归档、搜索和备份
2. 隐私优先：密码通过 getpass 交互输入，不进入命令历史；Token 本地缓存，无需云端托管凭证
3. 自动化友好：支持 cron 定时任务，每日自动同步，零人工干预
4. 多维度指标：覆盖睡眠、活动量、心率、压力、Body Battery、HRV、血氧、体重等完整健康图谱

潜在局限

• 认证机制受限：Garmin 未开放官方 OAuth API，依赖非官方逆向库，存在服务协议灰色地带
• Token 有效期限制：约一年需重新认证，中断后需人工介入
• 网络依赖：cloudscraper 需应对 Garmin 的反爬策略，可能偶发同步失败
• 平台锁定：仅支持 Garmin 生态，无法聚合 Apple Health、Fitbit 等竞品数据

适合人群

• Garmin 手表/码表深度用户，希望本地化备份健康数据
• 量化自我（Quantified Self）爱好者，需结构化数据用于分析或自动化工作流
• 隐私敏感型用户，拒绝将完整健康数据托管于云端第三方服务
• 开发者或高级用户，习惯命令行工具链和 cron 自动化

常规风险

| 风险类型 | 说明 |

|---------|------|

| 凭证安全 | 首次认证时密码虽经 `getpass` 保护，但仍存在被键盘记录器截获的本地风险 |

| API 稳定性 | 非官方库依赖 Garmin 网页端接口，官方变更可能导致功能失效 |

| 数据完整性 | 同步失败时 Markdown 文件可能缺失，需人工校验或重试 |

| 权限范围 | Token 权限等同于完整账户访问，泄露后可读取全部历史健康数据 |

核心用法

Garmin Connect Skill 通过 Python 脚本将 Garmin 账户中的每日健康数据同步到本地 Markdown 文件。用户首次需运行 --setup 完成邮箱+密码认证（密码通过 getpass 安全输入，不回显、不存历史），获取的 OAuth Token 缓存至 ~/.garminconnect/ 约一年有效。此后支持三种同步模式：当日数据（无参数）、指定日期（--date）、最近 N 天（--days）。数据文件按 YYYY-MM-DD.md 存储于 health/ 目录，可直接读取用于问答分析。

显著优点

1. 隐私优先设计：所有健康数据本地存储，不上传至第三方服务器；凭证处理采用标准安全实践。
2. 零配置依赖管理：使用 uv 工具自动解析 PEP 723 内联元数据，无需手动 pip 安装。
3. Token 长效缓存：一次认证，全年免密，兼顾便利与安全。
4. 格式友好：Markdown 输出便于版本控制、搜索和 AI 分析。

潜在缺点与局限性

• 无官方 API：依赖逆向/非官方 garminconnect 库，存在服务变更导致失效的风险。
• 单平台锁定：仅支持 Garmin Connect，无法与其他健康平台（Apple Health、Fitbit 等）互通。
• Token 过期需重认证：一年期 Token 过期后需重新输入密码，无自动化续期机制。
• 无实时同步：基于定时任务（cron），非推送式更新。

适合人群

• Garmin 手表/设备用户，希望本地化备份健康数据
• 注重数据隐私、不愿将敏感健康信息托管于云服务的用户
• 需要通过 Markdown 进行长期健康趋势分析的技术爱好者

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| 第三方库依赖 | `garminconnect`/`cloudscraper` 非 Garmin 官方维护 | 定期审查依赖更新，关注社区 Issue |

| 凭证泄露 | 虽然 `getpass` 安全，但 Token 文件权限若设置不当可能被其他程序读取 | 确保 `~/.garminconnect/` 目录权限为 700 |

| 服务中断 | Garmin 接口变更可能导致同步失败 | 关注 Skill 更新，保留原始 Garmin 应用作为备份 |

| 数据丢失 | 本地存储无自动备份 | 定期备份 `health/` 和 Token 目录至加密存储 |