shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析需要 API Key

佳明数据同步

支持佳明运动数据的同步，包含账号认证、数据获取、CSV格式化输出

person作者: user_61f6dd3ahubcommunity
download下载资源包

佳明运动数据调取分析

任务目标

  • 本 Skill 用于：从 Garmin Connect 同步运动数据到本地 CSV 文件
  • 能力包含：账号认证、数据获取、数据解析、CSV 格式化输出
  • 触发条件：用户需要同步佳明训练数据、备份运动记录或进行数据分析时

前置准备

步骤 1：环境检查

运行以下命令检查 Python 环境：

# 检查 Python 版本（需要 >= 3.7）
python3 --version

# 检查当前使用的 Python 解释器路径
which python3

注意：如果系统中有多个 Python 环境（如 python 和 python3），请确保在后续步骤中 consistently 使用同一个解释器。

步骤 2：依赖安装（必需）

本 Skill 必须预先安装以下依赖包才能运行：

安装核心依赖

# 使用 pip3 安装（推荐）
pip3 install garminconnect>=0.2.0

# 或者使用 pip
pip install garminconnect>=0.2.0

# 如果遇到权限问题，使用 --user 参数
pip3 install --user garminconnect>=0.2.0

验证安装

# 验证 garminconnect 是否正确安装
python3 -c "import garminconnect; print('✓ garminconnect 安装成功'); print(f'  版本: {garminconnect.__version__}')"

如果看到 ✓ garminconnect 安装成功，说明依赖安装正确。如果看到 ModuleNotFoundError，请重新执行安装命令。

可选：安装数据分析依赖

如果需要使用数据分析功能（生成统计报告），请额外安装 pandas：

pip3 install pandas

常见安装问题

问题 1：pip 命令不存在

# Ubuntu/Debian 系统
sudo apt-get update && sudo apt-get install python3-pip

# CentOS/RHEL 系统
sudo yum install python3-pip

问题 2：权限错误

# 使用 --user 参数安装到用户目录
pip3 install --user garminconnect>=0.2.0

# 或使用虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate
pip install garminconnect>=0.2.0

问题 3：网络问题

# 使用国内镜像源加速
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple garminconnect>=0.2.0

步骤 3：输出目录准备

执行数据同步前，需创建输出目录：

mkdir -p outputs/训练系统

步骤 4：网络连接验证

确保您的环境可以访问 Garmin 服务器：

# 测试网络连接
python3 -c "import requests; r = requests.get('https://connect.garmin.com', timeout=10); print(f'✓ Garmin Connect 访问正常 (状态码: {r.status_code}')"

如果测试失败，请检查：

  • 网络连接是否正常
  • 是否需要配置代理
  • 防火墙是否阻止了 HTTPS 连接

代理配置（如需要）：

# 设置 HTTP 代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

操作步骤

步骤 1：输入账号密码

引导用户提供佳明 Connect 账号和密码：

  • 账号格式：邮箱地址（如 your_email@example.com）
  • 密码：Garmin Connect 登录密码

步骤 2：执行数据同步

调用 scripts/garmin_sync_v2.py 进行数据同步：

python scripts/garmin_sync_v2.py \
  --username <邮箱> \
  --password <密码> \
  --days <天数> \
  --output outputs/训练系统/佳明同步数据.csv

参数说明：

  • --username：佳明账号邮箱（必需）
  • --password：登录密码（必需）
  • --days：同步最近N天的数据（默认30天）
  • --start-date：开始日期（YYYY-MM-DD格式，与--days二选一）
  • --end-date：结束日期（YYYY-MM-DD格式，与--days二选一）
  • --output：输出文件路径（默认：outputs/训练系统/佳明同步数据.csv）
  • --debug：开启调试模式

步骤 3：容错处理

脚本内置以下容错机制：

  • 网络超时：自动重试 3 次，每次间隔 5 秒
  • 认证失败：提示用户检查账号密码
  • 数据格式异常：跳过异常记录，记录错误日志

步骤 4：数据分析和统计（可选）

同步完成后，可以查看数据统计报告：

# 安装pandas（如未安装）
pip install pandas

# 分析数据
python scripts/analyze_data.py

统计报告包含：

  • 活动总数和类型分布
  • 距离统计（总距离、平均距离、最长距离）
  • 时长统计（总时长、平均时长、最长时长）
  • 心率统计（平均心率、最高心率）
  • 卡路里消耗统计
  • 爬升统计
  • 速度统计

步骤 5：输出文件验证

检查生成的 CSV 文件：

head -20 outputs/训练系统/佳明同步数据.csv

确认数据格式符合预期，包含以下字段：

  • 日期、活动类型、距离、时长、平均心率、最大心率、卡路里等

资源索引

必要脚本

  • scripts/garmin_sync_v2.py（核心同步脚本）：基于garminconnect库实现佳明数据同步
  • scripts/check_environment.py（环境检查脚本）：自动检测Python环境、依赖包和网络连接
  • scripts/test_garminconnect.py（测试脚本）：测试Garmin Connect登录是否成功
  • scripts/analyze_data.py（数据分析脚本）：生成运动数据统计报告

领域参考

  • references/output_format.md（输出格式说明）：详细描述 CSV 输出的字段定义、数据类型、格式规范
  • references/troubleshooting.md（故障排查指南）：常见问题诊断、认证问题解决方案

输出资产

  • assets/case_study.md（使用案例）：真实用户场景展示，包含个人用户、教练团队、数据备份等典型应用

注意事项

认证说明

  • 脚本使用garminconnect库，该库已处理Garmin Connect的认证机制
  • 支持国际服和国服账号，会自动识别
  • 账号密码仅在内存中暂存，同步后自动清理

API 使用限制

  • 遵守Garmin Connect API的请求频率限制
  • 大量数据同步时，建议分批获取
  • 如果遇到2FA（两步验证）问题，请使用浏览器完成首次登录

输出目录

  • CSV 文件固定输出到 outputs/训练系统/佳明同步数据.csv
  • 每次同步会覆盖旧文件，如需备份请手动重命名

使用示例

示例 1：同步最近 30 天数据

python scripts/garmin_sync_v2.py \
  --username your_email@example.com \
  --password your_password \
  --days 30 \
  --output outputs/训练系统/佳明同步数据.csv

示例 2：同步指定日期范围

python scripts/garmin_sync_v2.py \
  --username your_email@example.com \
  --password your_password \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --output outputs/训练系统/佳明同步数据.csv

示例 3：调试模式

python scripts/garmin_sync_v2.py \
  --username your_email@example.com \
  --password your_password \
  --days 7 \
  --debug

示例 4：智能体辅助触发

用户请求："帮我同步佳明最近一个月的运动数据"

智能体执行流程：

  1. 提示输入账号密码
  2. 调用同步脚本
  3. 返回同步结果和数据摘要

使用案例

本 Skill 已在多种场景下验证，详见 assets/case_study.md：

  1. 跑者月度分析

    • 一键同步30天数据，自动生成统计报告
    • 分析距离、心率、配速趋势
    • 效率提升240倍

  2. 教练团队管理

    • 批量同步20位学员数据
    • 自动生成周报和月报
    • 节省4小时/周

  3. 数据备份与恢复

    • 全量备份1000+历史记录
    • 数据安全保障
    • 支持跨平台迁移