核心功能与定位
gccli 是 Garmin Connect 的非官方命令行工具，由社区开发者 bpauli 维护，提供对 Garmin 生态系统的完整数据访问能力。其核心能力覆盖四大维度：
1. 活动与训练数据管理
- 活动列表查询、搜索、详细数据获取（心率区间、功率区间、分段数据、天气信息）
- 多格式下载支持：FIT（默认）、GPX、TCX、KML、CSV
- 活动上传、手动创建、编辑重命名、删除
- 训练计划（Workout）的创建、下载、上传、排程管理
2. 健康指标全景监控
- 基础体征：步数、心率、静息心率、睡眠、血氧、呼吸频率
- 进阶指标：HRV、压力指数、身体电量、训练准备度、训练状态、最大摄氧量
- 运动表现：乳酸阈值、骑行FTP、耐力评分、爬坡评分、强度分钟数、赛事预测
3. 身体成分与设备管理
- 体重、体脂、肌肉量记录与历史查询
- 血压数据管理
- 设备列表、设置、闹钟、太阳能充电数据
- 装备（Gear）追踪与活动关联
4. 账户与数据安全
- Garmin SSO 认证（支持浏览器交互和 headless 模式+MFA）
- Token 安全存储于系统密钥环（macOS Keychain/Linux Secret Service）
- 自动刷新、指数退避重试机制
显著优势
- 数据主权：突破 Garmin Connect 网页/APP 的限制，实现本地批量导出和备份
- 自动化友好：
--json/--plain输出、日期快捷语法、环境变量配置，完美适配脚本和 CI/CD - 训练编排：支持复杂结构化训练创建（配速/心率/功率目标区间）
- 多账户支持：通过
GCCLI_ACCOUNT快速切换，支持 Garmin 中国区域域名配置
局限性与风险
- 非官方工具：依赖逆向工程或私有 API，存在 Garmin 服务变更导致失效的风险
- 认证依赖：需存储长期有效的访问令牌，虽有密钥环保护但仍需关注令牌泄露
- 功能边界：部分高级功能（如实时同步、Connect IQ 应用管理）未覆盖
- 平台限制：仅支持 macOS 和 Linux，无 Windows 原生支持
适用人群
- 运动数据分析师、量化自我（Quantified Self）爱好者
- 需要定期备份 Garmin 数据的用户
- 开发自定义训练工具或仪表板的开发者
- 多平台数据整合需求（同步至 Strava、TrainingPeaks 等第三方服务）
常规风险提示
- 建议定期检查 GitHub 仓库更新，应对 Garmin API 变更
- 敏感操作（删除活动/训练计划）默认需确认，生产环境建议加
--force前充分验证 - 中国用户需显式设置
GCCLI_DOMAIN=garmin.cn以确保数据路由正确