健身决策代理
一位个人人工智能教练，每天查看你的身体数据，告诉你训练的难度。
______________________________________________________________________
问题
持续的训练很容易。训练 *智能地* 很难。
大多数人：
- 当他们的身体没有恢复时，训练太用力（导致受伤、进度停滞）
- 当他们真正准备好推动时，训练太容易了（把收获留在桌子上）
问题是，要知道你所处的情况，需要合成很多嘈杂的信号——你昨晚的睡眠、心率变异性、你本周训练了多少、你过去一个月的力量趋势是什么。每天手工正确地做到这一点是不现实的。
这就是这个项目所自动化的。
______________________________________________________________________
它的作用
每天早上，代理人都会：
- 提取您的身体数据 来自Whoop和Oura（心率变异性、睡眠评分、恢复评分、静息心率）
- 计算您的准备情况 --一个单一的分数，将所有信号结合起来，真实地反映出你的恢复情况
- 检查您的训练历史记录 --这周你训练有多努力？这个月？你有受伤的趋势吗？
- 规定今天的锻炼 --具体的组数、重复次数、重量和用力程度（表示为“后备重复次数”）
- 解释每一个决定 --你总是知道的 *为什么* 它规定了它所做的事情
- 随着时间的推移而学习 --当你记录会话和结果时，系统会更好地预测什么有效 *你的* 身体具体
______________________________________________________________________
输出示例
TODAY'S PRESCRIPTION — Lower (Squat focus)
───────────────────────────────────────────
4 × 5 @ 102.5kg
Stop 2 reps before failure (RIR 2)
Why: Recovery is 74/100. HRV is slightly above your baseline (+0.4σ).
Training load this week is healthy (AC ratio: 0.91). This is a solid
moderate day — good time for consistent work, not a PR attempt.
───────────────────────────────────────────如果你的恢复很差：
TODAY'S PRESCRIPTION — Rest
───────────────────────────────────────────
Take the day off.
Why: Recovery 31/100. HRV is 2 standard deviations below your baseline.
You've trained hard 5 days in a row (AC ratio: 1.7 — above injury
threshold). Your body needs recovery, not more stress.
───────────────────────────────────────────______________________________________________________________________
技术核心
这个项目解决了三个有趣的问题：
1.信号噪声 没有上下文，原始HRV数字毫无意义。55ms的读数没有任何意义，除非你知道你的基线是65ms，那么这意味着你比正常值低1.5个标准差，这是很重要的。该系统将每个信号与您的个人历史进行标准化，因此比较是有意义的。
2.延迟反馈 直到明天（你是如何恢复的？）甚至下个月（你的力量是否呈上升趋势？），你才知道今天的锻炼是否正确。这使得它成为一个强化学习问题——系统必须从迟到的结果中学习，而不是立即学习。
3.安全约束 与大多数机器学习系统不同，这里的糟糕输出会产生真正的物理后果。某些规则——当你的急慢性负荷比超过1.5时不要训练，不要在48小时内训练同一肌肉群——是硬编码的，无论数据如何，都不能被模型覆盖。
______________________________________________________________________
它是如何建造的
Your Wearables (Whoop, Oura)
↓
Data Ingestion pulls and normalizes your daily signals
↓
State Model computes readiness score + injury risk metrics
↓
Policy Engine decides today's training prescription
↓
Guardrail Layer safety checks that always run last
↓
Prescription what to do today, with explanation
↓
[You train]
↓
Feedback Logger you log what actually happened
↓
Reward Model scores how good the prescription was (delayed)
↓
RL Pipeline uses that feedback to improve future prescriptions该策略最初是一个简单的基于规则的系统（高恢复率→ 训练强度大，恢复率低→ 后退）。随着时间的推移，当你积累记录的会话时，它会被一个基于你自己的数据训练的机器学习模型所取代——一个学习你个人反应模式的模型，而不是依赖于通用的总体平均值。
______________________________________________________________________
关键概念（术语表）
心率变异性 --心跳之间的时间变化。更高通常更好，表明你的神经系统已经恢复。这是最具信息量的恢复信号。
HRV z评分 --你今天的HRV与你的个人平均值有多远，以标准差衡量。比原始数字更有用，因为它与 *你的* 基线，而不是人口规范。
交流比率（急性：慢性负载比率） --你本周的训练负荷除以过去4周的平均训练负荷。高于1.5=受伤风险增加。2.0以上=受伤风险高。这是一个在运动科学中使用的经过临床验证的指标。
RIR（储备代表） --在失败之前，你还能做多少次重复。RIR 0=你遭遇了失败。RIR 3=你还有3次重复。这就是系统如何表达训练强度，而不需要知道你的确切1RM。
e1RM（预计最多1个代表） --使用Epley公式从您的工作集计算出的单个重复的估计最大值。用于跟踪随时间推移的强度趋势。
离线RL --一种强化学习，模型从历史数据而不是现场实验中学习。我们使用这个是因为用糟糕的锻炼处方进行“实验”会产生真正的身体后果——我们负担不起现场探索。
MCP（模型上下文协议） --我们用于将代理连接到外部数据源（Whoop、Oura、您的培训日志）的标准。每个数据源都封装在MCP服务器中。代理通过MCP调用工具，而不是直接访问API，这使事情保持模块化。
______________________________________________________________________
糖原代理算法
该系统使用两条不同的路径计算糖原状态评分，从0（耗尽）到1（满载）：
路径1（跟踪数据）： 如果你记录碳水化合物摄入量，系统会使用过去24小时内相对于个人阈值（根据你的体重和训练量校准）消耗的实际克数。摄入越多=糖原状态越高。
路径2（从代理推断）： 如果碳水化合物没有被追踪，系统会通过积累证据来估计消耗量：
- 最近的训练量明显高于基线，增加了消耗
- 连续多日的艰苦训练增加了体力消耗
- 长时间训练而没有减载会增加消耗
- 持续的热量不足（尤其是超过300千卡）会导致严重的消耗
代理方法从100%假设的糖原开始，并根据存在的消耗信号数量进行减法。每个信号都会产生分数惩罚。
为什么这适用于RL：
当你在跟踪的数据上训练模型时，它会在同一个跟踪中看到直接碳水化合物数字和所有代理特征。它了解到：“当碳水化合物含量低时，表现会下降”，但“当碳水化合物摄入量低时，这些其他模式通常也会出现。”
后来，当有人不跟踪碳水化合物时，模型会看到缺失的碳水化合物数据，但会识别出它从你的痕迹中学到的代理模式。它了解糖原作用的形状，并可以间接应用。
融入准备状态：
糖原状态在总体准备评分计算中占10%的权重。恢复信号为30%，HRV为25%，睡眠为20%，负荷管理为15%，糖原为10%。这使得它有意义，但并不占主导地位——糖原完全耗尽的分数（0）会使准备状态下降10分，这足以将处方从重度转变为中度，但不足以迫使自己休息。
______________________________________________________________________
项目结构
fitness-agent/
├── data/
│ ├── ingestion/ # Whoop + Oura API connectors
│ ├── state/ # Converts raw data into AthleteState
│ └── store/ # Persistent storage (SQLite)
│
├── mcp_servers/ # One MCP server per data source
│ ├── wearable_server.py
│ ├── nutrition_server.py
│ ├── calendar_server.py
│ └── performance_server.py
│
├── policy/ # The brain — maps state → prescription
│ ├── rule_based.py # v0 baseline (start here)
│ ├── policy_network.py # v1 ML policy (after enough data)
│ └── guardrails.py # Hard safety constraints
│
├── reward/ # Scores past prescriptions, trains ML policy
├── agent/ # Orchestrates everything end-to-end
├── evals/ # Test suite — 15 scenarios covering edge cases
└── notebooks/ # Training runs, analysis, backtest results技术栈
这个项目主要是用Python构建的，重点是干净的数据建模、可重复的评估，以及从基于规则的策略到学习策略的安全路径。
核心语言
- python
日志记录
- Python日志记录-在整个系统中使用，因此每个决策都是可追溯的（基于错误的日志记录）
Supabase事件记录——用于存储结构化历史（状态快照、处方、护栏触发器和结果）
数据建模
派丹蒂克 -可穿戴信号 -培训课程 -计算运动员状态 -处方和解释
数据库
速贝 -每日可穿戴指标（Whoop+Oura） -训练历史和会话日志 -计算状态快照
数值计算
- NumPy（滚动基线、归一化、准备评分、趋势特征（疲劳+性能））
机器学习
- PyTorch（用于在存在足够多的日志会话时训练模型）
- scikit-learn（用于快速基线、评估指标和完全进入PyTorch之前的早期实验）
测试
- Pytest
代理
- 克劳德-用于：
- 生成清晰的自然语言解释 - 总结随时间变化的趋势 - 自我反思/改进循环
违反护栏
当前状态
| 里程碑 | 状态 |
|---|---|
| M1：数据摄取+状态模型 | 🔲 未启动 |
| M2：基于规则的政策+护栏 | 🔲 未启动 |
| M3:MCP服务器 | 🔲 未启动 |
| M4：奖励模式+离线RL训练 | 🔲 未启动 |
| M5：自反射环 | 🔲 未启动 |
| M6：评估仪表板 | 🔲 未启动 |
| M7：活Whoop/Oura连接器 | 🔲 未启动 |
我们故意按照这个顺序建造。基于规则的策略（M2）必须在ML策略（M4）之前存在——这是我们试图击败的基线，如果ML模型倒退，这是安全的回退。
______________________________________________________________________
入门指南
git clone https://github.com/your-username/fitness-agent
cd fitness-agent
pip install -r requirements.txt
cp .env.example .env # fill in your API keys
python -m data.store.migrations.init您需要：
- 具有开发者API访问权限的Whoop帐户（在开发者网站免费）
- 一个带有个人访问令牌的Oura帐户（在cloud.oraring.com上免费）
- 人类API密钥
______________________________________________________________________
问题
有关完整的技术规范——架构图、实现细节、代码示例和设计决策原理——请参阅 SPEC.md.