pp-strava

Strava — Printing Press 命令行工具

前置条件：安装命令行工具

此技能使用 strava-pp-cli 二进制文件。调用此技能中的任何命令前，必须确认命令行工具已安装。 如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install strava --cli-only
   

2. 验证：strava-pp-cli --version
3. 确保报告的安装目录位于调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/productivity/strava/cmd/strava-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。在验证成功之前，不要运行技能命令。

何时使用此命令行工具

当 Agent 需要查询运动员的历史训练数据、计算 Strava 网页界面不提供的体能指标、批量管理活动，或构建训练分析流水线时，请使用 strava-pp-cli。如果问题涉及汇总超过 5 项活动、涉及数据流级别的数据（心率、功率、GPS），或需要离线访问 Strava 数据，那么它就是合适的选择。

独特功能

这些功能无法通过此 API 的其他工具实现。

可累积的本地状态

• segments progress — 查看你在某个赛段上的完整成绩历史，包括日期、时间、平均功率、平均心率以及与个人纪录的差距，从而追踪自己是否确实在进步。

  当 Agent 需要评估运动员在一个赛季中是否在目标训练赛段上取得进步时使用。

  strava-pp-cli segments progress 229781 --json --select start_date,elapsed,avg_watts,delta_pr_seconds
  

• training load — 以迷你图形式查看慢性训练负荷、急性训练负荷和训练压力平衡，从而在比赛前发现过度训练或减量不足。

  当 Agent 需要评估运动员的体能/疲劳状态以及备战即将到来的赛事的准备情况时使用。

  strava-pp-cli training load --weeks 12 --ftp 285 --agent
  

• training zones — 查看每周在各个心率区间或功率区间实际训练的分钟数，从而判断训练分配是否符合计划。

  用于评估某个训练阶段是否按计划执行（极化、甜点区、基础训练）。

  strava-pp-cli training zones --weeks 8 --type Run --zone-type heartrate --agent
  

• athlete power-curve — 查看各个标准时长（1s 至 60min）的最佳平均功率，从而确定不同赛季间的优势、弱项和体能变化。

  当 Agent 需要描述骑行者的生理特征，或比较不同训练阶段的峰值功率时使用。

  strava-pp-cli athlete power-curve --since 2025-01-01 --weight 75 --agent
  

• activities drift — 测量一项活动中的有氧解耦，即后半段心率上升与配速下降的比率，无需实验室测试即可评估有氧体能。

  当 Agent 需要找出哪些长距离跑步或骑行活动出现了有氧解耦，表明运动员的强度已超过有氧阈值时使用。

  strava-pp-cli activities drift --min-duration 45m --since 2025-01-01 --threshold 5 --agent
  

• segments kom-gap — 查看你在每个已加星标赛段上距离 KOM 还差多少，并按最有可能缩小差距的目标排序。

  当 Agent 需要为训练计划或骑行前的目标设定找出最容易实现的 KOM 目标时使用。

  strava-pp-cli segments kom-gap --top 10 --agent
  

原生 Agent 工作流支持

• activities bulk-update — 一次性更新数百项活动的装备、名称模板或描述，并提供提交前预览作为安全保障。

  当 Agent 需要在更换装备后批量迁移装备分配，或追溯整理某个训练阶段的活动时使用。

  strava-pp-cli activities bulk-update --type Ride --after 2024-01-01 --set-gear b12345678 --dry-run
  

• gear status — 查看每双跑鞋和每辆自行车的总里程、你设置的更换阈值，以及根据近期使用频率估算的退役日期。

  当 Agent 需要在重要比赛前检查是否有装备即将退役时使用。

  strava-pp-cli gear status --threshold shoes=500mi --agent
  

命令参考

activities — 管理活动

• strava-pp-cli activities create-activity — 为运动员创建一项手动活动，需要 activity:write 范围。
• strava-pp-cli activities get-activity-by-id — 返回经身份验证的运动员拥有的指定活动。
• strava-pp-cli activities update-activity-by-id — 更新经身份验证的运动员拥有的指定活动。需要 activity:write。

athlete — 管理运动员

• strava-pp-cli athlete get-logged-in — 返回当前经过身份验证的运动员。
• strava-pp-cli athlete get-logged-in-activities — 返回指定标识符对应运动员的活动。需要 activity:read。
• strava-pp-cli athlete get-logged-in-clubs — 返回成员包括经身份验证的运动员的俱乐部列表。
• strava-pp-cli athlete get-logged-in-zones — 返回经身份验证的运动员的心率区间和功率区间。需要 profile:read_all。
• strava-pp-cli athlete update-logged-in — 更新当前经过身份验证的运动员。需要 profile:write 范围。

athletes — 管理运动员

clubs — 管理俱乐部

• strava-pp-cli clubs <id> — 使用标识符返回指定俱乐部。

gear — 管理装备

• strava-pp-cli gear <id> — 使用标识符返回指定装备。

routes — 管理路线

• strava-pp-cli routes <id> — 使用标识符返回指定路线。访问私人路线需要 read_all 范围。

segment-efforts — 管理路段成绩

• strava-pp-cli segment-efforts get-by-id — 返回经身份验证的运动员拥有的活动中的路段成绩。需要订阅。
• strava-pp-cli segment-efforts get-efforts-by-segment-id — 返回经身份验证的运动员在指定路段的成绩集。需要订阅。

segments — 管理路段

• strava-pp-cli segments explore — 返回符合指定查询条件的前 10 个路段。
• strava-pp-cli segments get-by-id — 返回指定路段。
• strava-pp-cli segments get-logged-in-athlete-starred — 经身份验证的运动员收藏的路段列表。

uploads — 管理上传

• strava-pp-cli uploads create — 上传新的数据文件以创建活动。需要 activity:write 范围。
• strava-pp-cli uploads get-by-id — 返回指定标识符对应的上传记录。需要 activity:write 范围。

查找合适的命令

知道要做什么，但不知道该用哪个命令时，可以直接询问 CLI：

strava-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一项匹配；退出代码 2 表示没有可信的匹配结果，此时可改用 --help 或使用更具体的查询。

使用示例

在比赛前检查训练准备情况

strava-pp-cli training load --weeks 8 --ftp 285 --agent --select ctl,atl,tsb,label

显示过去 8 周每周的 TSB（新鲜度）；TSB 为负表示疲劳，为正表示状态良好。比赛周的理想目标是 TSB > 10。

找出今年的最佳功率成绩

strava-pp-cli athlete power-curve --since 2025-01-01 --weight 72 --agent --select duration,watts,wkg

返回按标准时间窗口计算的最佳平均功率，并归一化为 W/kg——可分享给教练，用于生理状况评估。

找出有氧解耦的长跑

strava-pp-cli activities drift --type Run --min-duration 60m --threshold 8 --agent --select id,name,start_date,drift_pct

列出所有后半程心率相对于配速的漂移超过 8% 的跑步活动——这些训练日说明你的强度过高。

查看本赛季的路段进步情况

strava-pp-cli segments progress 229781 --since 2025-01-01 --agent --select start_date,elapsed,avg_watts,delta_pr_seconds

按日期显示路段 229781 上的每次成绩，并列出与个人纪录的差值，便于清晰了解趋势。

在马拉松前检查装备退役状态

strava-pp-cli gear status --threshold run_shoes=400 --agent --select gear_name,total_distance_mi,pct_threshold,est_retirement_date

显示所有跑步装备的里程数和预计退役日期；使用 --select 缩小范围，仅保留比赛日检查清单所需的字段。

身份验证设置

Strava 使用 OAuth2。运行 strava-pp-cli auth login 打开浏览器授权页面——CLI 会自动处理本地回调、令牌交换和存储。运行前请设置 STRAVA_CLIENT_ID 和 STRAVA_CLIENT_SECRET。若要重新进行身份验证，再次运行 auth login。

运行 strava-pp-cli doctor 验证设置。

Agent 模式

为任意命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐个遍历元素。对于内容冗长的 API，这对控制上下文大小至关重要：

  strava-pp-cli activities create-activity --name example-resource --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不发送

• 适合离线使用 — 在本地 SQLite 存储可用时，同步和搜索命令可以使用它

• 非交互式 — 不会提示输入，所有输入都通过标志提供

• 显式重试 — 只有在已存在的创建结果也应视为成功时，才使用 --idempotent

响应封套

从本地存储或 API 读取数据的命令会将输出封装在来源信息封套中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 以判断数据来自实时 API 还是本地存储。只有当 stdout 是终端且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会向 stderr 输出便于阅读的 N results (live) 摘要——管道或 Agent 使用者以及指定格式的运行只会在 stdout 上收到纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

strava-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
strava-pp-cli feedback --stdin < notes.txt
strava-pp-cli feedback list --json --limit 10

条目会存储在本地的 ~/.strava-pp-cli/feedback.jsonl。除非设置了 STRAVA_FEEDBACK_ENDPOINT，并且传入了 --send 或 STRAVA_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认情况下，反馈仅保存在本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体，写成一行：这部分会不断累积价值。

输出传递

每个命令都接受 --deliver <sink>。除了输出到 stdout（或取代 stdout 输出）之外，结果还会发送到指定的接收目标，这样 Agent 无需手动通过管道即可路由命令结果。支持三种接收目标：

接收目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

未知方案会被拒绝，并返回包含支持方案列表的结构化错误。Webhook 请求失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。当定时运行的 Agent 每次都以相同配置调用同一命令时，可以使用它——这是 HeyGen 的“Beacon”模式。

strava-pp-cli profile save briefing --json
strava-pp-cli --profile briefing activities create-activity --name example-resource
strava-pp-cli profile list --json
strava-pp-cli profile show briefing
strava-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，方便进行自省的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	达到速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 strava-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并附加 --agent）

MCP 服务安装

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册它：

claude mcp add strava-pp-mcp -- strava-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which strava-pp-cli 如果未找到，则提供安装选项（请参阅本技能开头的先决条件）。
2. 根据上文的独特功能和命令参考，为用户查询匹配最佳命令。
3. 使用 --agent 标志执行：

   strava-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：strava-pp-cli <command> --help。