佳明性能分析系统
⚠️ 非官方工具这是一个社区开发的个人使用项目，与Garmin有限公司无关。
一个与Garmin Connect集成的综合跑步表现分析系统，能够提供结合环境因素的详细分段分析。
特点/特性
- Garmin MCP（多功能控制面板）集成直接连接到Garmin Connect以检索数据
- DuckDB 后端性能数据的高效存储与查询
- 多智能体分析针对不同分析类型的专用代理
- 日本报告所有分析报告均以日语生成
- 环境融合天气、地形和身体状况分析
- 性能跟踪历史趋势分析与锻炼对比
建筑学
数据流
Garmin API → Raw Data → Performance Analysis → DuckDB → Analysis Reports核心组件
- 数据摄入 （
tools/ingest/): 收集并处理Garmin数据 - 数据库层 （
tools/database/): DuckDB 集成以实现高效查询 - 分析代理 （在...中配置
.claude/): 专门的分析工作流程 - MCP服务器 (
servers/): 用于数据访问的自定义MCP服务器 - 报告 (
tools/reporting/): 基于模板的报告生成
安装
# Install dependencies
uv sync
# Install with development tools
uv sync --extra dev使用
个体活动分析
# Analyze a specific activity
/analyze-activity 批处理分析
# Run batch analysis for date range
uv run python tools/batch/batch_planner.py批量获取活动详情
获取所有缺失活动的详细活动数据（最大图表数=2000） activity_details.json：
# Show what would be fetched (dry run)
uv run python tools/bulk_fetch_activity_details.py --dry-run
# Fetch missing activity_details.json files
uv run python tools/bulk_fetch_activity_details.py
# Force re-fetch even if files exist
uv run python tools/bulk_fetch_activity_details.py --force
# Adjust API rate limit delay (default: 1.0 seconds)
uv run python tools/bulk_fetch_activity_details.py --delay 2.0发展
代码质量
# Format code
uv run black .
# Lint
uv run ruff check .
# Type check
uv run mypy .
# Run tests
uv run pytest预提交钩子（或：提交前钩子）
# Install hooks
pre-commit install
# Run manually
pre-commit run --all-files数据结构
data/raw/不可变的Garmin API响应data/performance/预处理后的性能指标data/database/DuckDB数据库文件result/最终分析报告
可配置的数据路径
隐私保护通过配置自定义数据目录，将您的个人健康数据与代码库分开存储。
设置
- 复制示例配置：
cp .env.example .env- 编辑
.env按照您偏好的路径:
# Use absolute paths for safety
GARMIN_DATA_DIR=/home/user/garmin_data/data
GARMIN_RESULT_DIR=/home/user/garmin_data/results- 运行应用程序:
系统会自动使用已配置的路径。无需修改代码！
- （可选）设置 direnv 以自动加载环境变量：
# Install direnv if not already installed
# Ubuntu/Debian: sudo apt install direnv
# Or: curl -sfL https://direnv.net/install.sh | bash
# Add direnv hook to your shell (~/.bashrc or ~/.zshrc)
eval "$(direnv hook bash)" # For bash
# eval "$(direnv hook zsh)" # For zsh
# Allow direnv to load .envrc
direnv allow配置好direnv后，当你（进入某个目录或执行某个命令时），环境变量会自动加载 cd 进入项目目录。
默认行为
如果 .env 未配置时，系统使用默认目录：
- 数据：
./data - 结果：
./result
好处
- 隐私存储在Git仓库外部的个人健康数据
- 灵活存储使用外部驱动器或NAS（网络附加存储）处理大型数据集
- 环境分离不同的开发/生产路径
如需更多详情，请参阅 docs/GITHUB_PUBLISHING_CHECKLIST.md。
MCP服务器
这个项目使用了以下MCP服务器（配置在 .mcp.json):
- Garmin 数据库基于DuckDB的性能数据查询和区间分析存储
- 塞雷娜符号感知的代码导航和编辑操作
配置
看 CLAUDE.md 以获取详细的配置和使用指南。
免责声明
这是一款非官方的、由社区开发的工具，与Garmin有限公司或其子公司无关，未得到其认可或支持。
- 这个项目使用了第三方Python库
garminconnect(麻省理工学院许可证) 以访问个人Garmin Connect数据 - 这个工具旨在用于 仅供个人使用 分析你自己的健身数据
- 用户有责任遵守Garmin的服务条款
- 自行承担风险使用——作者对因使用本软件而产生的任何问题不承担任何责任
隐私说明： 这个工具会在本地处理您的个人健康数据。请确保您保留好您的数据目录（通过 .env) 安全起见，切勿将个人数据提交到版本控制系统中。
许可证
这个项目遵循MIT许可证授权——详见 许可证 文件中详述。
该项目使用了以下第三方库：
garminconnect- MIT 许可证- 其他依赖项列在
pyproject.toml各自持有相应的许可证