hevy

Hevy 训练计划创建器

快速入门

<skill-dir>/bin/hevy auth <key>           # Authenticate (get key from hevy.com/settings)
<skill-dir>/bin/hevy exercises search "squat"
<skill-dir>/bin/hevy routines template > routine.json
# Edit routine.json
<skill-dir>/bin/hevy routines create routine.json

所有命令均可使用：<skill-dir>/bin/hevy --help

工作流

1. 解析训练计划 - 提取训练动作、组数、次数、重量和休息时间
2. 查找训练动作 ID - hevy exercises search <name>
3. 构建训练计划 JSON - 从 hevy routines template 开始
4. 创建训练计划 - hevy routines create file.json

关键规则

• 绝对不要在备注中使用 @（会导致无提示的 400 错误）
• 始终使用包装结构：{"routine": {...}}，不要使用裸对象
• 始终让组属性与训练动作类型匹配：
  • weight_reps → weight_kg、reps
  • reps_only → 仅 reps（不要包含 weight！）
  • duration → duration_seconds
  • distance_duration → distance_meters、duration_seconds
  • short_distance_weight → distance_meters、weight_kg（农夫行走、雪橇推/拉）
• 绝不要猜测 ID，始终使用 hevy exercises search

判断训练动作类型

用户描述……	训练动作类型	组属性
重量 + 次数（“3x10 @ 135lb”）	weight_reps	weight_kg、reps
仅次数（“3x12 引体向上”）	reps_only	仅 reps
静态保持时长（“平板支撑 60s”）	duration	duration_seconds
距离 + 时间（“划船 500m”）	distance_duration	distance_meters、duration_seconds
距离 + 重量（“农夫行走 50m @ 80kg”）	short_distance_weight	distance_meters、weight_kg

不确定时：hevy exercises get <id> 会显示训练动作类型。

解读训练计划

超级组：

• “A1/A2”、“超级组”或“成对训练” → 使用相同的 superset_id（整数：0、1、2……）
• “循环训练”或“EMOM” → 所有训练动作共用一个 superset_id
• 独立训练动作 → superset_id: null

**休息：**仅设置在超级组的最后一个训练动作上

**AMRAP/最大努力：**使用 "reps": null

超级组结构示例：

{
  "exercise_template_id": "79D0BB3A",
  "superset_id": 0,
  "rest_seconds": null,
  "sets": [{"type": "normal", "weight_kg": 80, "reps": 10}]
},
{
  "exercise_template_id": "1B2B1E7C",
  "superset_id": 0,
  "rest_seconds": 90,
  "sets": [{"type": "normal", "reps": 8}]
}

常见训练动作 ID

使用 hevy exercises search 获取当前 ID。以下为参考示例：

训练动作	ID	类型
深蹲（杠铃）	D04AC939	weight_reps
硬拉（杠铃）	C6272009	weight_reps
卧推（杠铃）	79D0BB3A	weight_reps
过顶推举（杠铃）	AE23FF09	weight_reps
引体向上	1B2B1E7C	reps_only
俯卧撑	392887AA	reps_only
划船机	0222DB42	distance_duration
拉伸	527DA061	duration
农夫行走	49742539	short_distance_weight

创建自定义训练动作前

1. 搜索部分名称（搜索“row”，而非“cable row”）
2. 检查器械变体（杠铃、哑铃、拉索、器械）
3. 尝试其他名称（“Skull Crushers” = “Lying Tricep Extension”）

单位换算

用户提供磅数（lbs）时，换算为千克：weight_kg = lbs / 2.205

为便于实际装载，四舍五入到最接近的 0.5 kg。

处理搜索结果

情况	操作
完全匹配	使用该 ID
有多个相似结果（例如，“Squat”返回杠铃、哑铃、史密斯机版本）	选择与用户上下文匹配的器械变体
没有结果	尝试更短的词（搜索“tricep”，而非“tricep pushdown cable”）
仍无结果	最后才创建自定义训练动作

批量导入策略

对于包含 10 个以上训练计划的训练项目：

1. 先构建所有 JSON 文件
2. 创建一个训练计划，并在应用中确认显示正确
3. 每次调用间隔 2 秒，创建其余训练计划
4. 如果出现 429 错误：等待 60 秒，从失败的训练计划开始继续

故障排查

问题	原因	解决方法
HTML 响应	备注中包含 @	替换为“at”
找不到训练动作	拼写错误	搜索部分名称
401 未授权	API 密钥错误	hevy auth test
429 请求频率受限	请求过多	等待 60 秒后重试
400 错误请求	组属性与训练动作类型不匹配	使用 hevy exercises get <id> 检查训练动作类型
不允许的字段	更新中包含只读字段	移除 id、created_at、updated_at 字段
组被拒绝	在 reps_only 训练动作中使用了 weight_kg	移除重量，仅使用 reps

CLI 与本文档

需求	使用
精确的命令语法和所有标志	hevy <command> --help
工作流、注意事项和解读规则	本文档
探索所有功能	hevy --help