运行分析技能
一个全面的跑步性能分析工具，可以解析训练文件，将数据存储在DuckDB中，并使用既定的训练科学原理（Jack Daniels VDOT、Pfitzinger HR区域）生成见解。
特性
- 锻炼解析：FIT和GPX文件支持，具有完整的遥测功能
- 云同步：MotherDuck集成，支持多设备访问
- 培训计划：创建和跟踪定期培训计划
- 性能分析：基于VDOT的配速建议和比赛预测
- 历史跟踪：VO2最大趋势、PR和进度监控
- 培训科学：Jack Daniels和Pfitzinger方法论的循证见解
快速开始
适用于Claude桌面用户
此技能通过MotherDuck MCP服务器与Claude Desktop集成，使Claude可以访问您的运行数据。
- 获取MotherDuck代币：注册地址： motherduck.com 并从以下地址获取您的令牌 设置
- 添加到Claude桌面配置 (
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"motherduck": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", "md:runs_db", "--motherduck-token", "YOUR_TOKEN_HERE"]
}
}
}- 重新启动克劳德桌面 -克劳德现在可以分析你的跑步了！
有关详细的设置和迁移说明，请参阅 Claude桌面集成 在......下面
面向开发者
安装
# Clone the repository
git clone https://github.com/mz462/run-skill.git
cd run-skill
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt基本用法
from scripts.parsers.gpx_parser import parse_gpx_file
from scripts.db_manager import RunDatabaseManager
from scripts.run_analyzer import RunAnalyzer
# Parse a workout file
run_data = parse_gpx_file("path/to/workout.gpx")
# Store in database
db = RunDatabaseManager()
run_id = db.insert_run(run_data)
# Analyze the run
analyzer = RunAnalyzer()
analysis = analyzer.analyze_run(run_id)
print(analysis)云同步（可选）
启用与MotherDuck的云同步以实现多设备访问：
设置
- 注册MotherDuck：https://motherduck.com（免费版：10GB）
- 获取您的令牌：https://app.motherduck.com/settings/tokens
- 配置：
# Option 1: Environment variable
export MOTHERDUCK_TOKEN="your_token_here"
# Option 2: Config file (recommended for Claude Desktop)
cp data/config.json.example data/config.json
# Edit data/config.json and add your token迁移
如果您有现有的本地数据，请将其迁移到云端：
source .venv/bin/activate
python3 scripts/migrate_to_motherduck.pyClaude桌面集成
此技能与使用MotherDuck MCP服务器的Claude Desktop无缝协作。
安装说明
- 安装MotherDuck MCP:
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:runs_db",
"--motherduck-token",
"YOUR_MOTHERDUCK_TOKEN_HERE"
]
}
}
}注： uvx 是的一部分 uv Python包管理器。安装方式：
# macOS/Linux
brew install uv
# OR
curl -LsSf https://astral.sh/uv/install.sh | sh- 重新启动克劳德桌面
现在克劳德可以：
- 使用完整的历史背景分析您的跑步记录
- 制定并跟踪培训计划
- 通过MCP直接查询您的MotherDuck数据库
- 在所有设备上生成见解
培训科学
VDOT系统（杰克·丹尼尔斯）
根据比赛表现计算训练速度：
from scripts.training_science import TrainingScience
# Calculate VDOT from race
vdot = TrainingScience.calculate_vdot(
distance_km=21.1, # Half marathon
time_sec=5460 # 1:31:00
)
# Get training paces
paces = TrainingScience.get_training_paces(vdot)
print(paces['easy']) # Easy run pace
print(paces['tempo']) # Threshold pace
print(paces['intervals']) # VO2 max pace心率区域（Pfitzinger）
hr_zones = TrainingScience.calculate_hr_zones_pfitzinger(
max_hr=185,
resting_hr=60
)培训计划
制定定期培训计划：
from scripts.training_plan_manager import TrainingPlanManager
manager = TrainingPlanManager()
plan = manager.create_plan(
name="Spring Marathon 2026",
goal_race="Boston Marathon",
goal_distance_km=42.2,
goal_date="2026-04-20",
goal_time="3:30:00"
)
# Add phases
manager.add_phase({
'name': 'base',
'start_date': '2025-12-01',
'end_date': '2026-01-31',
'weekly_volume_km': 65,
'long_run_km': 25,
'key_workouts': ['easy', 'long'],
'focus': 'Build aerobic base'
})数据库模式
该技能使用DuckDB和下表：
运行数据：
runs-核心训练指标splits-圈/公里分段hr_zones-心率分布vo2max_history-随时间变化的最大摄氧量
用户数据：
user_profile-设置、生理、PRtraining_plans-培训计划元数据training_plan_phases-相位配置
文件格式
GPX文件
- 来自Apple Health、Garmin Connect导出的GPS轨迹
- 包括：距离、速度、高度
- 缺失：心率、节奏
FIT文件
- Garmin、Wahoo等公司的完整遥测数据。
- 包括：人力资源、节奏、权力、高级指标
- 建议进行全面分析
发展
# Run tests
pytest tests/
# Check database
python3 scripts/db_manager.py
# Test analysis
python3 scripts/run_analyzer.py项目结构
run-skill/
├── scripts/
│ ├── db_manager.py # Database operations
│ ├── run_analyzer.py # Analysis engine
│ ├── training_science.py # VDOT, HR zones
│ ├── training_plan_manager.py # Plan management
│ ├── report_generator.py # Report formatting
│ ├── config_manager.py # Configuration
│ ├── migrate_to_motherduck.py # Cloud migration
│ ├── migrate_json_to_db.py # JSON to DB migration
│ └── parsers/
│ ├── gpx_parser.py # GPX file parsing
│ └── fit_parser.py # FIT file parsing
├── data/
│ ├── config.json.example # Config template
│ └── runs.duckdb # Local database (auto-created)
├── SKILL.md # Detailed documentation
└── README.md # This file隐私和安全
- 所有数据都存储在本地 默认情况下
- 可选云同步 需要明确的MotherDuck令牌
- 无跟踪或分析
- 您的数据属于您
使用MotherDuck时：
- 在传输和静止时加密的数据
- 符合GDPR/SOC2标准
- 默认情况下为私有
- 可选择与教练/朋友分享
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
鸣谢
培训科学：
- 杰克·丹尼尔斯跑步方程式（VDOT系统）
- Pete Pfitzinger的高级马拉松（人力资源区）
内置：
- DuckDB-嵌入式分析数据库
- MotherDuck-云原生DuckDB
- fitparse-FIT文件解析
- pandas/numpy-数据分析
支持
- 文件：见 技能.md
- 问题：GitHub问题
- 讨论：GitHub讨论
______________________________________________________________________
专为跑步者打造，由跑步者打造。 🏃♂️💨