garmin-pulse

Garmin Pulse 是一款专注于将 Garmin Connect 健康数据同步到本地 Markdown 文件的开源工具。该技能通过安全的 OAuth 认证机制，将用户的睡眠、活动、心率、压力、身体电量、HRV、SpO2 及体重等多维度健康数据离线存储，实现完全本地化的个人健康数据管理。

核心用法方面，用户首先需要通过命令行执行一次性设置，使用 getpass 安全输入密码获取 OAuth 令牌（缓存于 ~/.garminconnect/，有效期约一年）。随后可通过 uv run 命令同步今日、指定日期或过去 N 天的数据。同步后的数据以结构化的 Markdown 格式存储于 health/ 目录，便于阅读、搜索和版本控制。若需回答健康相关问题，Agent 将直接读取对应日期的 Markdown 文件。

显著优点包括：1）安全性设计周到，密码输入采用交互式 getpass 提示，避免明文显示于屏幕或记录于 Shell 历史；2）数据完全本地化，不涉及任何第三方服务器传输，仅与 Garmin 官方 API 通信；3）依赖管理现代化，使用 uv 工具自动处理 Python 依赖（garminconnect、cloudscraper），无需手动 pip 安装；4）支持自动化工作流，可配置 cron 定时任务实现每日早晨自动同步，保持数据实时更新。

潜在缺点与局限性方面，该技能要求用户禁用 Garmin 账户的双因素认证（2FA），这在安全敏感场景下可能不适用。此外，依赖的 garminconnect 和 cloudscraper 为社区维护库，非官方 SDK，存在长期维护不确定性。OAuth 令牌一年有效期后需重新认证，且云端的 Cloudflare 防护偶尔可能导致同步中断。

适合的目标群体主要为注重数据隐私的个人 Garmin 用户、希望离线查看健康数据的极客用户，以及需要将健康数据纳入本地知识库管理（如 Obsidian、Logseq）进行长期分析的用户。对于企业级安全要求、必须使用 2FA 或不信任第三方库的用户则不适用。

使用风险主要包括：依赖社区的第三方库可能存在潜在安全漏洞（尽管当前无已知 CVE）、令牌过期导致的服务中断需手动重新认证，以及需要手动配置和管理 cron 定时任务的运维负担。建议用户定期备份 health/ 目录中的个人健康数据，并关注依赖库的安全更新。

核心用法

Garmin Pulse 是一个命令行工具，用于将 Garmin Connect 的健康与运动数据同步到本地 Markdown 文件。用户需先执行一次性认证设置，使用 getpass 安全输入密码获取 OAuth Token，后续所有同步均依赖缓存的 Token，无需重复输入凭证。

主要功能：

• 同步当日、指定日期或过去 N 天的健康数据
• 生成结构化的每日 Markdown 文件，包含睡眠、活动、心率、压力、Body Battery、HRV、血氧及体重数据
• 支持通过 cron 定时任务实现自动化同步

显著优点：

• 凭证安全处理：密码通过 getpass 交互获取，不落屏幕、不存历史、不作为参数传递，符合安全最佳实践
• Token 长效缓存：OAuth Token 缓存约一年，避免频繁认证
• 数据本地化：所有健康数据以 Markdown 形式存储于用户指定目录，便于查阅与长期归档
• 依赖管理现代化：使用 uv 运行脚本，自动处理依赖隔离，无需手动 pip 安装
• 传输加密：所有与 Garmin 的通信均通过 TLS 加密

潜在缺点与局限性：

• 非官方 API：依赖第三方社区库 garminconnect 逆向 Garmin 私有 API，存在 API 变更导致失效的风险
• Token 存储安全：OAuth Token 以明文形式存储于 ~/.garminconnect/，虽建议权限 0700，但仍依赖系统文件权限保护
• 个人维护风险：维护者为个人开发者（T3 级别），长期维护更新及安全响应能力存疑
• 依赖供应链风险：cloudscraper 等第三方依赖需持续监控安全公告
• 平台局限：目前仅支持 Garmin Connect 生态，无法同步其他品牌设备数据

适合人群：

• 注重数据本地化的 Garmin 设备用户
• 希望建立个人健康数据档案的隐私敏感型用户
• 熟悉命令行操作、能够配置定时任务的进阶用户

常规风险：

• Token 泄露风险：若设备多用户共享或文件权限配置不当，缓存的 Token 可能被其他用户读取
• API 服务中断：Garmin 官方 API 策略变更可能导致同步功能失效
• 依赖漏洞：第三方库若出现安全漏洞，可能影响本地环境安全（建议定期更新）