Long Run Hybrid Coach

繁體中文 · English · 简体中文

Long Run Hybrid Coach は、非公式・Intervals-first・device-agnostic のパーソナライズされた hybrid training coach です。同じ 28 日間の方向性と今週のランニング＋筋力トレーニングの計画を維持し、信頼できる実際の完了 evidence を読み取って継続的に振り返り、あなたの確認後に計画を Intervals.icu カレンダーに送信できます。

Garmin は使用前提ではありません。 Garmin は現在、実機で 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. remote MCP に接続でき、本製品が必要とするアクションを提供できる AI client。

3. オプション：すでにアクティビティを Intervals.icu に同期できる時計またはトレーニングアプリ。

Garmin がなくても使用できます。自動 recovery evidence がない場合、Coach は欠落したデータを 0 ではなく unknown として扱います。

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 delivery について完全に検証済みです。

• ChatGPT：完全な MCP（write／modify actions を含む）は、現在 OpenAI 公式の説明に従い、ChatGPT Business、Enterprise、Edu のウェブ版 beta に提供されています。Pro の custom MCP は現在 read/fetch のみで、本 Coach の plan write／delivery の全フローを完了できません。ワークスペースが完全な MCP をサポートしている場合、Apps／developer mode で custom app を作成し、上記の remote endpoint を指定してください。最新のプラン制限は OpenAI 公式説明 に従ってください。

• OpenClaw：openclaw mcp add で同じ endpoint を指定し、--auth oauth を追加します。1 つの instance を複数人で使う場合は、OAuth identity を per-requester に設定してください。そうしないと全員が同じ Intervals アカウントに接続されます。設定は entrypoints/openclaw/ を参照してください。

• その他の MCP client：同じ URL を remote Streamable HTTP MCP server として設定します。実際に全フローを実行できるかは、その client が本製品に必要な MCP/OAuth 動作をサポートしているかどうかに依存します。

各エントリーポイントの「実機で完全検証済み」または「パッケージ化済み・実接続検証待ち」の状態は、entrypoints/ を基準とします。

2. Intervals.icu を認可する

初回接続時、ブラウザで Intervals.icu の同意ページが開きます。自分自身の Intervals.icu アカウントにログインし、Coach が必要とする権限を認可します：

• ACTIVITY:READ：完了したトレーニングを読み取ります。

• WELLNESS:READ：Intervals が提供できる wellness evidence を読み取ります。

• CALENDAR:WRITE：トレーニングカレンダーを読み／書きし、確認済みの計画を配信して read-back 検証できるようにします。

• SETTINGS:WRITE：設定を読み取ります。確認済みの delivery フローで本当に必要な場合にのみ、欠落していて evidence に裏付けられた running threshold setting を補います。

Intervals の同意ページでは権限が分かれています。1 つでもチェックを外すと、その権限に依存する機能は明確に失敗します。再接続して権限を補えば問題ありません。Intervals のパスワード、API key、token を会話に貼り付けないでください。

3. 普通のコーチ質問をそのままする

事前にアンケートを記入する必要はありません。例：

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

または：

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

Coach はまず既存の evidence を読み、その上で本当に意思決定を変えるギャップだけを質問します。例えば、今週のトレーニング可能日、器材、provider が知り得ない筋力トレーニングの baseline などです。

4. 28 日間の preview を確認してから計画を確定する

初めて計画を作成するときは、まず以下が表示されます：

• 今週：正確で、実行可能で、配信可能な session。

• 以降 3 週間：方向性を示す outlook。今の時点で全ての詳細が分かっているかのように装いません。

その preview を確認した後、計画が書き込まれます。以降の毎週の変更も同じ体験です：

before / after preview → 一度確認 → apply。

5. カレンダーに送信するときは delivery 確認を行う

配信はもう 1 つの独立した確認です：

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 です。異なるデバイス／アプリからのアクティビティと wellness evidence を Coach が受け取れるようにし、Coach が確認したカレンダー計画も受け取ります。Coach の PlanState source of truth ではありません。

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

役割分担：

• Intervals.icu：外部トレーニング evidence を統合し、provider calendar を保持します。

• Long Run Hybrid Coach：唯一の current PlanState、decision history、athlete-reported evidence、確認 binding、coaching workflow を保持します。

• あなたの時計／アプリ：アクティビティを Intervals に取り込めます。また、Intervals から送られる workout を受け取ることもできます。ただし、最後の 1 マイルが成功するかどうかは、独立した compatibility evidence です。

Intervals に事前にデータが必要ですか？

必要なのはアカウント自体だけです。アクティビティ／wellness がすでに同期されていれば、Coach の自動 evidence はより完全になります。ないフィールドは unknown のまま保持され、0 として扱われることはなく、オプションの数値が 1 つ欠けているだけで一般的な coaching がブロックされることもありません。

デバイスで計測できない、または同期されていないものは、会話で直接伝えることができます。例：

• 筋力トレーニングの実際のセット数、重量、回数；

• 今週のトレーニング可能時間と器材の制限；

• 体重／体脂肪率；

• 時計を着けずに行ったアクティビティ；

• 「最近とても疲れている」「睡眠が良くない」といった subjective state；

• 時計／アプリで実際に確認した sleep、HRV、resting HR、readiness などの recovery reading。

Coach は「疲れた」という一言を、こっそり偽の readiness score に変換したりしません。

Hosted MCP vs Local / Self-hosted MCP

実際に感じる違いは 1 つだけです：hosted はスマートフォンでそのまま使えます。local は gateway を実行しているコンピューター上でしか使えません。 以下の他のすべての行は、この違いのコストです。

Hosted MCP の最短セットアップ手順

1. 完全な要件をサポートする MCP client に remote MCP app／connector を追加します。

2. URL に https://mcp.paceandstaystrong.com/mcp を貼り付けます。

3. client の 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 はどうやって実行するのか？

Repo は Python 3.11 を使用し、製品自体は stdlib-only で、一連の runtime Python package を事前にインストールする必要はありません。

1. Repo を clone します。

2. Intervals.icu に OAuth application の作成を申請します。 Intervals の現在の公開フローは Settings でのセルフサービス app 追加ではありません。公式 OAuth の説明に従い、app name、description、website、logo、privacy policy、redirect URI、あなたの Intervals ID を提供します。app が作成されて初めて Settings に表示され、Manage App から client_id / secret を取得します。フローは Intervals.icu OAuth support を参照してください。

3. Intervals app に gateway provider callback を登録します：<gateway-origin>/oauth/callback。ローカル client は loopback を使用できます。remote client には到達可能な 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 client を指定します：

http://127.0.0.1:8422/mcp

remote client に正式に提供する場合、loopback の例を production runbook として扱わないでください。Persistent volume、TLS、trusted client origin、single replica、release identity、デプロイ検証については docs/deploy-gateway.md を参照してください。

Local CLI が黙って 2 つ目の current plan になるべきではない

1 人の athlete には current writer が 1 つだけであるべきです。ローカルで GARMIN_COACH_LOOP_GATEWAY_URL を hosted coach に向けて設定している場合、ローカル store への書き込みはデフォルトでブロックされます。明示的に --offline を付けた場合のみ、「意図的に別の local plan を作っている」ことを意味します。

すでにローカル state がある人は hosted に移行できます。完全なフローは docs/ops/migrate-local-store-to-hosted.md を参照してください。

現在できること

現在の製品機能は以下を含みます：

• 28 日間の方向性を維持：今週の正確な session ＋ 以降 3 週間の outlook。

• Intervals の activity／wellness／calendar evidence を読み取り、信頼できる planned → actual を current plan に自動 reconciliation します。

• 同じ週間計画の中でランニングと筋力トレーニングの両方を同時に処理します。

• athlete-reported profile、availability、long-term goal、training preference、実際の筋力トレーニング、体重／体脂肪率、デバイスが記録できなかったアクティビティ、subjective state を記録します。

• startCoachSession は今回の request の recovery readings を受け取ります。Hosted はあなたのローカル health database を読む必要もなく、読みもしません。

• サポートされている履歴 evidence をインポートします。サポートされている形式の CSV、Apple Health XML コンテンツ、binary import path を通じて処理される FIT payload を含みます。同じファイルと同じアクティビティは deterministic に重複排除され、判断できない場合のみユーザーに質問します。

• Session に coach_note を含めることができ、コーチの重要なテキストを Intervals event に一緒に含めます。こっそり 2 つ目の workout grammar を作り出すことはありません。

• 毎週「実際に何を練習したか、進歩の evidence があるか、次のステップは何か」を振り返ります。「計画をやり遂げた」ことをそのまま fitness の向上と見なすことはしません。

• 計画変更はまず preview、確認後に apply します。

• カレンダー配信はまず preview、確認後に実行します。安全な retry、replace、product-owned event の withdraw をサポートします。

• 会話内で直接エクスポート、または 2 段階で本製品が保持する owner data を完全削除できます。

重要な境界

• startCoachSession は deterministic reconciliation を行い、新しい PlanState version を書き込む可能性があります。完全に side effect のない stored state だけが必要な場合は、getCoachState を使用してください。これが read-only の経路です。

• athlete-reported activity は evidence ですが、provider-backed の actual completion にこっそり昇格されることはありません。

• recovery の数値は実際に観測された値のみを受け付けます。モデルがテキストから自分で数値を推測することはできません。

• 本製品は医療診断を行いません。

• Delivery の evidence は Intervals read-back までであり、時計に届いたと主張することはありません。

データ、エクスポート、削除

Hosted 側は、同じ owner 計画を維持するために必要な製品状態を保存します：PlanState version chain、decision／receipt、athlete-reported evidence、identity mapping、未収束の delivery bookkeeping です。

エクスポートには意図的に含めません：OAuth credential の keyed fingerprint、provider raw payload／GPS track、internal owner id。Fingerprint は一方向の bookkeeping です。raw GPS／アクティビティファイルは provider が提供するものです。owner id は内部の storage locator です。

製品データの削除にも 3 つの明確な境界があり、これら 3 つは本製品が削除できる範囲外です：

• Intervals.icu カレンダーにすでに書き込まれた workout；

• Intervals.icu Settings で付与した provider 認可；

• plan、健康、identity の内容を含まない最小化されたプラットフォーム運用ログ。

完全なライフサイクルは docs/account-lifecycle.md を参照してください。公開プライバシーポリシーは paceandstaystrong.com/privacy.html にあります。

現在の制限

• Coach は Apple Health、Garmin Connect、その他のデバイスアカウントに直接ログインしません。主要な自動 evidence 経路は現在も Intervals.icu です。

• Hosted は毎回の request で渡される raw recovery upload を永続保存しません。次に必要なときは、その時点の evidence を再度渡してください。

• 本製品は Intervals の先の各デバイス同期 hop を監視しないため、intervals_accepted を「すでに時計にある」とは言いません。

• Local self-hosting は operator／developer 向けの経路です。一般ユーザーは Hosted MCP を優先してください。

• デバイス互換性は経路ごとの evidence であり、Garmin が検証済みだからといって他のデバイスも必ず同じだと推論することはありません。

製品サーフェスと技術ドキュメント

現在の release は外部に 22 個の MCP tool、2 個の prompt、30 個の CLI コマンド、3 つの JSON Schema contract、5 つの identity テーブルを提供しています。これらの数はテストが実際のコードから導出しており、README が独自にずれることを防いでいます。

• 安定したユーザーストーリー：docs/user-story.md

• データソースとフィールドの境界：docs/data-sources.md

• エントリーポイントとプラットフォーム設定：entrypoints/

• MCP protocol、OAuth、tool の動作：entrypoints/mcp/README.md

• Hosted gateway のデプロイ：docs/deploy-gateway.md

• アカウントライフサイクル：docs/account-lifecycle.md

• 公開リリース／レビューアー向け資料：docs/distribution/

• Release inventory：docs/release-inventory.md

• Repository invariants と検証：AGENTS.md

Long Run Hybrid Coach は独立したプロジェクトであり、Garmin、Intervals.icu、Apple、その他のデバイス／プラットフォームベンダーとの所属、推薦、スポンサー関係はありません。コードは MIT License で公開されています。