Long Run Hybrid Coach

繁體中文 · English · 简体中文

Long Run Hybrid Coach — это неофициальный, Intervals-first, device-agnostic персональный гибридный тренер (hybrid training coach). Он ведёт единый 28-дневный план направления и расписание на текущую неделю (бег + силовые), читает достоверные фактические evidence для постоянного разбора, и после вашего подтверждения может отправлять расписание в календарь Intervals.icu.

Garmin не является обязательным условием. Garmin — это первый downstream-путь к устройству, прошедший реальное dogfood-тестирование на железе; Apple Watch, COROS, Polar, Suunto, Wahoo, другие приложения/часы и даже отсутствие часов — всё это работает с тем же Coach. Разница лишь в том, сколько достоверных evidence попадает в тренировочный цикл и проверен ли путь синхронизации устройств за Intervals.

Обычным пользователям рекомендуется Hosted MCP: https://mcp.paceandstaystrong.com/mcp. Вам нужен аккаунт Intervals.icu, но не нужно самостоятельно создавать Intervals OAuth App или поддерживать собственный gateway.

Quick Start: Hosted MCP

Что нужно перед началом?

1. Аккаунт Intervals.icu.

2. AI-клиент, который умеет подключаться к remote MCP и предоставлять действия, необходимые этому продукту.

3. Опционально: часы или тренировочное приложение, которые уже умеют синхронизировать активности в Intervals.icu.

Можно пользоваться и без Garmin. Если автоматических recovery evidence нет, Coach считает отсутствующие данные unknown, а не 0.

1. Подключение к Hosted Coach

MCP endpoint:

https://mcp.paceandstaystrong.com/mcp

• claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → вставьте endpoint. Этот путь прошёл полную проверку production OAuth, coaching turn и доставки в Intervals.

• ChatGPT: полный MCP (включая write/modify actions) в настоящее время, согласно официальной документации OpenAI, доступен в веб-версии beta для ChatGPT Business, Enterprise и Edu; custom MCP в Pro сейчас поддерживает только read/fetch и не может выполнить полный цикл plan write/delivery этого Coach. Если ваш workspace поддерживает полный MCP, создайте custom app в Apps/developer mode и укажите указанный выше remote endpoint. Актуальные ограничения планов см. в официальной документации OpenAI.

• OpenClaw: используйте openclaw mcp add, указав тот же endpoint, и добавьте --auth oauth; если instance используется несколькими людьми, OAuth identity нужно настроить как per-requester, иначе все будут подключены к одному аккаунту Intervals. Настройка — в entrypoints/openclaw/.

• Другие MCP-клиенты: укажите тот же URL как remote Streamable HTTP MCP server; возможность выполнить полный цикл зависит от того, поддерживает ли клиент необходимое этому продукту поведение MCP/OAuth.

Статус «полностью проверено на реальном железе» или «упаковано, ожидает реального подключения» для каждого entrypoint — см. entrypoints/.

2. Авторизация Intervals.icu

При первом подключении браузер откроет страницу согласия Intervals.icu. Войдите в свой собственный аккаунт Intervals.icu и авторизуйте возможности, необходимые Coach:

• ACTIVITY:READ: чтение выполненных тренировок.

• WELLNESS:READ: чтение wellness evidence, доступных в Intervals.

• CALENDAR:WRITE: чтение/запись тренировочного календаря, чтобы подтверждённые планы можно было доставлять и проверять read-back.

• SETTINGS:WRITE: чтение настроек; только если подтверждённому процессу доставки действительно нужно, добавляется недостающая настройка running threshold, подкреплённая evidence.

Страница согласия Intervals разделяет разрешения. Если не отметить одно из них, функции, зависящие от этого разрешения, будут явно завершаться ошибкой; достаточно переподключиться и добавить разрешение. Не вставляйте пароль Intervals, API key или token в диалог.

3. Просто задавайте обычные тренерские вопросы

Никаких предварительных анкет, например:

讀我最近的訓練，告訴我這週該怎麼練。

Или:

我想提升 VO2max，又不想掉力量，幫我排第一個 28 天方向。

Coach сначала прочитает уже существующие evidence, а затем спросит только о тех пробелах, которые действительно изменят решение, например о доступных для тренировок днях на этой неделе, оборудовании или силовом baseline, который provider знать не может.

4. Сначала 28-дневный preview, затем подтверждение плана

При первом создании плана вы увидите:

• Текущая неделя: точные, выполнимые, доставляемые сессии.

• Следующие три недели: направленный outlook, без притворства, что все детали известны уже сейчас.

План записывается только после того, как вы подтвердите этот preview. Каждое последующее еженедельное изменение — тот же опыт:

before / after preview → одно подтверждение → apply.

5. Подтверждение delivery только при отправке в календарь

Доставка — это отдельное независимое подтверждение:

delivery preview → одно подтверждение → запись в Intervals.icu → read-back проверка.

Самое дальнее состояние, которое этот продукт может доказать, — intervals_accepted. Успех в Intervals не означает, что расписание уже на Garmin, Apple Watch или других часах. Синхронизация за Intervals — это внешний hop, который нужно проверять отдельно для каждого пути устройства.

Related MCP server: Transition MCP

Что делает Intervals.icu в этом продукте?

Intervals.icu — это текущий interoperability hub: он помогает Coach получать evidence активности и wellness с разных устройств/приложений, а также принимает подтверждённые календарные планы Coach. Он не является source of truth для PlanState Coach.

手錶 / 訓練 app
      │
      ▼
 Intervals.icu ───── 已完成活動 + wellness evidence ─────► Coach
      ▲                                                   │
      │                                                   │
      └────────── 確認後的 calendar workout ◄────────────┘
      │
      ▼
Garmin / Apple Watch bridge / 其他下游同步

Разделение ответственности:

• Intervals.icu: интеграция внешних тренировочных evidence и хранение provider calendar.

• Long Run Hybrid Coach: хранит единственный текущий PlanState, decision history, athlete-reported evidence, подтверждённые binding и coaching workflow.

• Ваши часы/приложение: могут приносить активности в Intervals и могут получать workout, отправляемые Intervals дальше; но успех последней мили — это отдельный compatibility evidence.

Обязательно ли, чтобы в Intervals уже были данные?

Обязателен только сам аккаунт. Если активности/wellness уже синхронизированы, автоматические evidence Coach будут полнее; отсутствующие поля остаются unknown, не превращаются в 0 и не блокируют обычный coaching из-за отсутствия одного опционального значения.

То, что устройство не измеряет или не синхронизирует, можно просто сообщить в диалоге, например:

• фактические подходы, веса и повторения в силовых;

• доступное время для тренировок и ограничения по оборудованию на этой неделе;

• вес/процент жира;

• активность без часов;

• субъективное состояние вроде «последнее время устал», «плохо сплю»;

• реальные показатели recovery, которые вы видите на часах/в приложении: sleep, HRV, resting HR, readiness и т.д.

Coach не превратит фразу «я устал» в поддельный readiness score.

Hosted MCP vs Local / Self-hosted MCP

Реальная разница, которую вы почувствуете, только одна: hosted можно использовать прямо с телефона; local работает только на том компьютере, где запущен gateway. Каждая остальная строка ниже — это цена этой разницы.

Кратчайший путь запуска Hosted MCP

1. В MCP-клиенте, поддерживающем все необходимые требования, добавьте remote MCP app/connector.

2. Вставьте URL https://mcp.paceandstaystrong.com/mcp.

3. Пройдите OAuth-процесс клиента.

4. В браузере подтвердите авторизацию в Intervals.icu.

5. Вернитесь в чат и задайте первый тренерский вопрос.

Hosted-сервис сам обрабатывает dynamic client registration, PKCE, gateway token и per-athlete owner mapping; обычным пользователям не нужны owner id, athlete id, API key, Intervals client secret или server environment variable.

Как запустить Local / Self-hosted MCP?

Репозиторий использует Python 3.11, сам продукт — stdlib-only, предварительная установка набора runtime Python-пакетов не требуется.

1. Клонируйте репозиторий.

2. Подайте заявку в Intervals.icu на создание OAuth application. Текущий публичный процесс Intervals — это не самостоятельное добавление приложения в Settings: согласно официальной документации OAuth, укажите app name, description, website, logo, privacy policy, redirect URI и ваш Intervals ID; приложение появится в Settings только после создания, а client_id/secret получаются из Manage App. Процесс см. в Intervals.icu OAuth support.

3. Зарегистрируйте callback gateway provider в приложении Intervals: <gateway-origin>/oauth/callback. Локальный клиент может использовать loopback; remote-клиенту нужен доступный HTTPS/secure tunnel.

4. Настройте необходимые переменные окружения gateway:

export GARMIN_COACH_LOOP_GATEWAY_STATE_ROOT="$HOME/.local/share/long-run-hybrid-coach-gateway"
export GARMIN_COACH_LOOP_TOKEN_HMAC_KEY="$(openssl rand -base64 32)"
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_ID="..."
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_SECRET="..."

5. Запустите:

python3 -m garmin_coach_loop.cli serve-gateway --host 127.0.0.1 --port 8422

6. Локальный MCP-клиент укажите на:

http://127.0.0.1:8422/mcp

Если вы собираетесь официально предоставлять доступ remote-клиентам, не используйте loopback-пример как production runbook. Persistent volume, TLS, trusted client origin, single replica, release identity и проверка развёртывания — в docs/deploy-gateway.md.

Local CLI не должен молча становиться вторым current plan

У одного athlete должен быть только один current writer. Когда локально задан GARMIN_COACH_LOOP_GATEWAY_URL, указывающий на hosted coach, запись в локальное хранилище по умолчанию блокируется; только явный --offline означает «я намеренно веду отдельный local plan».

Те, у кого уже есть локальное состояние, могут перенести его на hosted; полный процесс — в docs/ops/migrate-local-store-to-hosted.md.

Что можно делать сейчас?

Текущие возможности продукта:

• Ведение 28-дневного направления: точные сессии на текущую неделю + outlook на следующие три недели.

• Чтение Intervals activity/wellness/calendar evidence и автоматическая достоверная reconciliation planned → actual обратно в current plan.

• Одновременная работа с бегом и силовыми в одном недельном плане.

• Запись athlete-reported profile, availability, long-term goal, training preference, фактических силовых, веса/процента жира, активностей, не записанных устройством, и субъективного состояния.

• startCoachSession принимает recovery readings для текущего запроса; Hosted не читает и не будет читать вашу локальную базу данных здоровья.

• Импорт поддерживаемых исторических evidence, включая CSV поддерживаемых форматов, содержимое Apple Health XML и FIT payload через binary import path; детерминированная дедупликация одинаковых файлов и активностей, при невозможности определить — вопрос пользователю.

• Сессия может содержать coach_note, чтобы ключевые комментарии тренера попадали в событие Intervals, а не порождали вторую грамматику workout.

• Еженедельный разбор «что реально тренировал, есть ли evidence прогресса, что дальше», а не автоматическое «расписание выполнено = fitness вырос».

• Изменения плана сначала preview, затем подтверждение, затем apply.

• Доставка в календарь сначала preview, затем подтверждение; поддержка безопасного retry, replace и withdraw product-owned event.

• Экспорт прямо в диалоге или двухэтапное необратимое удаление owner data, хранящихся в этом продукте.

Важные границы

• startCoachSession выполняет детерминированную reconciliation и может записать новую версию PlanState; если нужен полностью side-effect-free доступ к stored state, используйте getCoachState — это read-only путь.

• athlete-reported activity — это evidence, но она не будет молча повышена до provider-backed actual completion.

• Recovery-числа принимаются только как реальные наблюдения; модель не может сама угадать число из текста.

• Этот продукт не занимается медицинской диагностикой.

• Delivery evidence ограничивается read-back в Intervals и не заявляет о доставке на часы.

Данные, экспорт и удаление

Hosted-сторона хранит состояние продукта, необходимое для ведения одного owner-плана: цепочку версий PlanState, decision/receipt, athlete-reported evidence, identity mapping и незавершённый delivery bookkeeping.

При экспорте намеренно не включаются: keyed fingerprint OAuth credential, provider raw payload/GPS track и внутренний owner id. Fingerprint — это односторонний bookkeeping; raw GPS/файлы активностей должен предоставлять provider; owner id — внутренний storage locator.

Удаление данных продукта также имеет три чёткие границы; эти три вещи не входят в область удаления этого продукта:

• workout, уже записанные в календарь Intervals.icu;

• авторизация provider, выданная вами в Intervals.icu Settings;

• минимализированные платформенные операционные логи, не содержащие plan, health или identity контента.

Полный жизненный цикл — в docs/account-lifecycle.md, публичная политика конфиденциальности — на paceandstaystrong.com/privacy.html.

Текущие ограничения

• Coach не входит напрямую в Apple Health, Garmin Connect или другие аккаунты устройств; основной путь автоматических evidence в настоящее время — Intervals.icu.

• Hosted не хранит постоянно raw recovery upload из каждого запроса; при следующей необходимости передавайте текущие evidence заново.

• Этот продукт не наблюдает каждый hop синхронизации устройств после Intervals, поэтому не называет intervals_accepted «уже на часах».

• Local self-hosting — путь для operator/developer; обычным пользователям следует предпочесть Hosted MCP.

• Совместимость устройств — это evidence по каждому пути; проверка Garmin не означает, что другие устройства ведут себя так же.

Поверхность продукта и техническая документация

Текущий релиз предоставляет 22 MCP tool, 2 prompt, 30 CLI-команд, 3 JSON Schema contract, 5 identity-таблиц. Эти числа выводятся тестами из реального кода, чтобы README не расходился с действительностью.

• Стабильные пользовательские истории: docs/user-story.md

• Источники данных и границы полей: docs/data-sources.md

• Entrypoints и настройка платформ: entrypoints/

• MCP protocol, OAuth и поведение tool: entrypoints/mcp/README.md

• Развёртывание Hosted gateway: docs/deploy-gateway.md

• Жизненный цикл аккаунта: docs/account-lifecycle.md

• Публичные материалы для публикации/reviewer: docs/distribution/

• Release inventory: docs/release-inventory.md

• Repository invariants и проверка: AGENTS.md

Long Run Hybrid Coach — независимый проект, не имеющий отношения принадлежности, одобрения или спонсорства с Garmin, Intervals.icu, Apple или другими поставщиками устройств/платформ. Код выпущен под MIT License.