Run Skill

运行分析技能

一个全面的跑步性能分析工具，可以解析训练文件，将数据存储在DuckDB中，并使用既定的训练科学原理（Jack Daniels VDOT、Pfitzinger HR区域）生成见解。

特性

• 锻炼解析：FIT和GPX文件支持，具有完整的遥测功能
• 云同步：MotherDuck集成，支持多设备访问
• 培训计划：创建和跟踪定期培训计划
• 性能分析：基于VDOT的配速建议和比赛预测
• 历史跟踪：VO2最大趋势、PR和进度监控
• 培训科学：Jack Daniels和Pfitzinger方法论的循证见解

快速开始

适用于Claude桌面用户

此技能通过MotherDuck MCP服务器与Claude Desktop集成，使Claude可以访问您的运行数据。

1. 获取MotherDuck代币：注册地址： motherduck.com 并从以下地址获取您的令牌 设置
2. 添加到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"]
       }
     }
   }

1. 重新启动克劳德桌面 -克劳德现在可以分析你的跑步了！

有关详细的设置和迁移说明，请参阅 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的云同步以实现多设备访问：

设置

1. 注册MotherDuck：https://motherduck.com（免费版：10GB）
2. 获取您的令牌：https://app.motherduck.com/settings/tokens
3. 配置：

# 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.py

Claude桌面集成

此技能与使用MotherDuck MCP服务器的Claude Desktop无缝协作。

安装说明

1. 安装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

1. 重新启动克劳德桌面

现在克劳德可以：

• 使用完整的历史背景分析您的跑步记录
• 制定并跟踪培训计划
• 通过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 -设置、生理、PR
• training_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标准
• 默认情况下为私有
• 可选择与教练/朋友分享

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

鸣谢

培训科学：

• 杰克·丹尼尔斯跑步方程式（VDOT系统）
• Pete Pfitzinger的高级马拉松（人力资源区）

内置：

• DuckDB-嵌入式分析数据库
• MotherDuck-云原生DuckDB
• fitparse-FIT文件解析
• pandas/numpy-数据分析

支持

• 文件：见 技能.md
• 问题：GitHub问题
• 讨论：GitHub讨论

______________________________________________________________________

专为跑步者打造，由跑步者打造。 🏃‍♂️💨