ai-running-coach

KO | EN

gitlite — search

#javascript #python #golang #machine-learning #deep-learning #linux #docker #java #awesome #kubernetes #vue #pytorch #security #ios

ai-running-coach

(★ 21)

基于高驰数据 × 丹尼尔斯训练理论的 AI 跑步教练 | AI Running Coach powered by COROS + Daniels Running Formula

ai-running-coach Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AI Running Coach

> An AI running coach built on classic training science — reads your COROS watch data, estimates your fitness, and generates marathon plans that adapt week by week. Runs as a skill on Claude (or any capable LLM in manual mode).
>
> 基于 Claude + 高驰 MCP 的智能跑步训练系统，理论驱动 · 数据实时 · 课表动态调整（[中文文档见下半部分](#ai-running-coach-中文)）

---

## What is this?

This repo is the **open methodology layer** behind [Pacer](https://pacer.xiaolou.space/en), a hosted AI running coach. Everything the coach "believes" about training lives here in auditable form: the workflow rules, the pace/load math conventions, and a structured knowledge-card library covering injury rehab, strength work, and race nutrition.

You can run it yourself as a **Claude skill**: it reads your training history from a COROS watch via COROS's official MCP server (read-only), estimates your VDOT from real runs (no time-trial needed), and generates a race training plan built on three classic methodologies — then re-scores and adjusts it every week based on what you actually ran.

**Core ideas:**

- ⌚ **No file uploads** — activity and physiological data come straight from the watch via MCP. No watch? `parse_fit.py` turns exported FIT files into a CSV you can paste in.
- 🧠 **Structured knowledge cards** — injury triage (Level 0–2 grading), a 15-exercise strength library with per-exercise form guides, and race nutrition are routed from in-repo cards, not hallucinated.
- 🏃 **VDOT from history** — fitness is estimated from your real runs; no all-out test required. Out-of-range inputs raise an error instead of silently snapping to a wrong pace table.
- 📅 **One-line weekly update** — one prompt scores last week's execution, checks fatigue, and adjusts next week.
- 🩺 **Readiness, not guesswork** — HRV drop, resting-HR spike and sleep score each raise a flag; two flags and today becomes a recovery day. Missing signals are skipped rather than assumed fine.
- 🌡️ **Heat-aware by session type** — on a muggy day a key interval session gets moved to a cooler hour (or a treadmill) to protect the stimulus; a long run keeps its duration and just slows down; an easy run slows freely.
- 🔢 **The LLM never does arithmetic** — VDOT, readiness and all hydration/fueling numbers come from pure functions in this repo (`vdot_calculator.py`, `readiness_calc.py`, `nutrition_calc.py`). The coach only reports what they return.
- 🛡️ **Safety over compliance** — the 10% mileage rule, consecutive-hard-day limits and injury de-escalation are enforced, not suggested.
- 🌍 **Fully redistributable** — no copyrighted source material included; clone it and run your own coach.

## Quick start (English)

1. **Model**: use a strong model for plan generation (Claude Opus/Sonnet class). Weaker models are fine for day-to-day analysis.
2. **Install the COROS MCP** (~3 min) — in Claude Code / Claude Desktop, add the MCP server `https://mcpcn.coros.com/mcp`, then confirm `coros` shows up under `/mcp`. No COROS watch? Manual mode works: paste your training data instead.
3. **Generate your plan** — send:

```
Initialize the AI running coach. Read my last 6 weeks of COROS training data and build my plan.

About me:
- Goal race: [half marathon / marathon]
- Target time: [e.g. 1:45:00]
- Training days per week: [e.g. 4]
- Race date: [e.g. 2026-11-15]
```

4. **Each week** — just say: `Update this week's training data`.

## Training theory

| Theory | Source | What it contributes |
|--------|--------|---------------------|
| VDOT system | Jack Daniels, *Daniels' Running Formula* (2013) | Precise five-zone pace prescription |
| Cumulative fatigue | Luke Humphrey, *Hansons Marathon Method* (2012) | Sane long-run ceilings |
| 80/20 intensity split | Matt Fitzgerald, *80/20 Running* (2014) | Keeps you out of the gray zone |
| 10% progression rule | Hal Higdon, *Marathon* (2011) | Safe ramp-up and taper |

## This repo vs. Pacer (the hosted app)

The training logic is the same in both. The difference is who keeps it running.

- **This repo** = the full methodology, as a self-hostable skill. Every rule, threshold and knowledge card is here in plain text for you to read, audit and change. Bring your own LLM; your data stays in your own Claude/COROS accounts. You drive it — you say "update this week" and it runs.
- **[Pacer](https://pacer.xiaolou.space/en)** = the same logic, productized so it runs *without you asking*: one-tap COROS sign-in (official OAuth, read-only), automatic sync and weekly review on a schedule, daily pre-run advice in your inbox, memory that accumulates across months, and a mobile UI. Free while early.

In short: **this repo tells you how to train; Pacer keeps it going on its own.**

> **Language note**: the detailed docs below are currently in Chinese (an English pass is in progress). The skill itself works fine in English conversations — the coach replies in whatever language you use.

---

# AI Running Coach（中文）

## 这是什么

AI Running Coach 是一个运行在 Claude 上的跑步训练 Skill。它通过高驰（COROS）MCP 实时读取你的手表数据，结合丹尼尔斯、汉森、80/20 三大经典训练理论，**并通过独创的分层知识卡片库涵盖了伤病康复、力量体能和运动营养**，为你生成和动态调整专属训练计划。

**核心特点：**
- ⌚ **无需上传文件**——直接通过 MCP 从手表读取实时运动记录和生理数据。没有高驰手表也能用：`parse_fit.py` 把导出的 FIT 文件解析成 CSV 走手动模式。
- 🧠 **内置专业知识卡片**——伤病分级诊断、**15 个力量动作库（含分步要领、常见错误、跑者专项 cue、呼吸）**、赛事营养，全部结构化路由调用。无需外挂向量数据库。
- 🏃 **免去繁琐测试**——AI 从运动历史自动推算 VDOT，无需单独安排全力测试跑。成绩填错、超出对照表范围时会直接报错，而不是悄悄给你一套错配速。
- 📅 **每周一句话更新**——`更新本周训练数据` 即可完成课表执行度打分、疲劳判断和下周计划自动调整。
- 🩺 **身体准备度多信号判定**——HRV 跌幅、静息心率升幅、睡眠分各记一面红旗，两面即换恢复日。**某项没测到就跳过、不当作正常**，也不会因为少一项数据就误报警。
- 🌡️ **按课型的湿热调整**——桑拿天里，关键间歇课优先挪到凉爽时段或跑步机以保住训练刺激；长跑保时长只放慢；轻松跑随便慢。不是一热就砍量。
- 🔢 **确定性算术不交给 AI**——VDOT、准备度、补水补给的全部数字由仓库内纯函数算出（`vdot_calculator.py` / `readiness_calc.py` / `nutrition_calc.py`），教练只负责复述，**不做心算**。
- 🛡️ **伤病与疲劳保护**——10% 递增法则、连续高强度限制、伤病降级（含"改了距离必须同步改文案"）均为强制执行而非建议。
- 📊 **一键生成周打卡图**——`生成本周打卡图` 输出 1080×1440 分享图，含课表实录、AI 复盘、下周预览，支持导出 PNG。
- 🌍 **全量合规开源**——不含任何版权原文材料，任何人都可以克隆并运行自己的专属教练。

---

## 推荐运行环境与模型

> AI 会在生成课表前自动检查模型能力。**如果当前模型不足以生成完整训练计划，AI 会直接告知并给出替代建议，不降低课表质量。**

### 环境支持（MCP 自动同步）

MCP 是手表数据自动同步的关键协议，目前支持范围如下：

| 运行环境 | MCP 自动拉取 | 推荐度 |
|---------|------------|------|
| **Claude Code 桌面版 / CLI** | ✅ 完整支持 | ⭐⭐⭐ 首选 |
| **Claude 桌面应用（Desktop App）** | ✅ 完整支持 | ⭐⭐⭐ 首选 |
| **Claude 网页版（claude.ai）** | ⚠️ 需手动配置 | ⭐⭐ |
| **Cursor / Windsurf 等 IDE** | ✅ 支持 MCP 插件 | ⭐⭐ 适合开发者 |
| **Gemini / DeepSeek / Kimi 等** | ❌ 暂不支持 MCP | ⭐ 手动模式可用（或配合 parse_fit.py） |

> **无 MCP 时**：手动粘贴训练数据或使用 `parse_fit.py` 解析 FIT 文件，AI 仍可完整分析和生成课表。

### 模型能力档位划分

| 能力档位 | 要求与特点 | 推荐用途 |
|---|---|---|
| **旗舰推理档** | 支持长文本结构化输出（≥ 32k tokens）与深度逻辑推理 | 生成 15 周全程课表、赛前深度分析 |
| **均衡档** | 具备良好的表格渲染能力与较快响应速度 | 周例行更新、日常单次/周复盘 |
| **轻量档** | 基础对话能力 | 仅限快速查询，不建议生成全程课表 |

> *注：最后核对日期：2026-07。模型迭代迅速，请以各厂商当前旗舰模型为准。*

---

## 支持设备

| 设备 | 状态 | 说明 |
|------|------|------|
| 高驰（COROS）全系列 | ✅ 正式支持 | 通过官方 MCP 实时拉取数据 |
| 佳明（Garmin）| 🚧 占位未实现 | 适配规划中 |
| 苹果 Watch | 🔮 规划中 | 待评估 |

---

## 快速开始

### 第一步：确认模型

生成完整课表前，请确认当前模型属于**旗舰推理档**（具备长文本结构化表格输出能力）。

### 第二步：安装高驰 MCP（约 3 分钟）

在 Claude Code 中输入：

```
帮我安装高驰 COROS MCP，地址是 https://mcpcn.coros.com/mcp
```

重启后输入 `/mcp` 确认 `coros` 出现在列表中。

### 第三步：生成你的训练计划

复制以下内容，填写你的信息后发给 Claude：

```
请帮我初始化 AI 跑步教练系统，读取我高驰手表最近6周的训练数据，为我生成专属课表。

我的信息：
- 目标比赛：[半程马拉松 / 全程马拉松]
- 目标完赛时间：[例如 1小时30分]
- 每周可训练天数：[例如 4天]
- 目标比赛日期：[例如 2026年11月15日]
```

### 第四步：每周更新

每周训练结束后，对 Claude 说：

```
更新本周训练数据
```

---

## 文件结构

```
ai-running-coach/
├── README.md             # 本文件：项目介绍与快速开始
├── USER_GUIDE.md         # 用户操作手册（所有用户必读）
├── 快捷指令.md            # 四大场景快捷模板（复制即用）
├── SKILL.md              # AI 教练核心规范（AI 自动读取）
├── CHANGELOG.md          # 版本更新日志
├── THEORY_LIBRARY.md     # 训练理论知识库大纲
├── knowledge_cards/      # 分层知识卡片库（AI 按需路由调用）
│   ├── 伤病/             # 6 张：分级诊断 + 康复动作 + 课表降级
│   ├── 力量/             # 动作库(15动作) + 动作指引 + 分期方案
│   └── 营养/             # 4 张：日常/赛前装载/赛中补给/赛后恢复
├── vdot_calculator.py    # VDOT 查表与五区配速（越界报错，不静默钳制）
├── readiness_calc.py     # 身体准备度多信号红旗判定
├── nutrition_calc.py     # 出汗率/补液/补钠/碳水/能量胶算术
├── parse_fit.py          # 本地 FIT 文件解析工具（手动模式入口）
├── ADAPTERS.md           # 设备适配器配置（22 个 COROS MCP 工具映射）
├── CONTRIBUTING.md       # 贡献指南（开发者）
├── 赘肉.md               # 归档内容（AI 不读取）
├── schedules/
│   ├── example_schedule.md        # 示例课表（了解格式）
│   └── [你的昵称]_schedule.md    # 你的专属课表（AI 自动生成）
└── 训练数据/              # 本地 .fit 文件（MCP 优先，此为备用）
```

---

## 训练理论依据

| 理论 | 出处 | 核心贡献 |
|------|------|---------|
| VDOT 体系 | Jack Daniels, *Daniels' Running Formula* (2013) | 五区配速精确划定 |
| 累积疲劳原则 | Luke Humphrey, *Hansons Marathon Method* (2012) | 消除超长跑迷信 |
| 80/20 强度分配 | Matt Fitzgerald, *80/20 Running* (2014) | 避免"灰色地带"训练 |
| 10% 递增法则 | Hal Higdon, *Marathon* (2011) | 安全增量与赛前减量 |

---

## 分享给朋友

把整个 `ai-running-coach` 文件夹分享给朋友，让他们按照 USER_GUIDE.md 连接自己的高驰账号即可——课表数据各自独立生成，不会互相影响。

---

## 贡献

欢迎为本项目贡献：
- 新设备适配器（参考 ADAPTERS.md 格式）
- 训练理论补充（THEORY_LIBRARY.md 第四章）
- 用户反馈与建议

详见 [CONTRIBUTING.md](CONTRIBUTING.md)

---

*AI Running Coach v3.0.0 · 基于 Claude Skill 协议构建*

ai-running-coach

ai-running-coach Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ai-running-coach

ai-running-coach Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README