strava-api

Strava API

直接集成 Strava API v3，用于健身数据管理。

安全模型

重要：所有密钥都存储在系统钥匙串中（macOS Keychain / Linux Secret Service）。

• AI Agent 无法从钥匙串读取密钥
• 只有 Python 脚本可以在运行时访问凭据
• 非密钥元数据（运动员姓名、令牌过期时间）存储在 ~/.strava/metadata.json

此设计确保你的 API 凭据绝不会暴露给 AI Agent。

---

首次设置工作流

当用户首次请求 Strava 数据时：

步骤 1：检查是否已配置

python3 scripts/strava_api.py athlete

如果出现错误 "Strava not configured" → 继续执行步骤 2。 如果成功 → 跳到“使用 API”部分。

步骤 2：创建 Strava 应用

引导用户创建 API 应用：

1. 打开 https://www.strava.com/settings/api
2. 填写应用表单：
   • Application Name：任意名称（例如 "My Fitness App"）
   • Category：任选一项
   • Website：http://localhost
   • Authorization Callback Domain：localhost
3. 记录 Client ID 和 Client Secret（将在设置中输入）

步骤 3：运行交互式设置

python3 scripts/setup_oauth.py

脚本将：

1. 询问 Client ID 和 Client Secret（密钥输入隐藏）
2. 打开浏览器进行 Strava 授权
3. 引导用户复制重定向 URL
4. 自动用授权码交换令牌
5. 将密钥存储在系统钥匙串中（安全）
6. 将元数据存储在 ~/.strava/metadata.json
7. 验证连接

步骤 4：验证设置

python3 scripts/strava_api.py athlete

应显示运动员资料 JSON。

---

使用 API

命令行命令

# Get athlete profile
python3 scripts/strava_api.py athlete

# Get athlete stats
python3 scripts/strava_api.py stats

# List recent activities
python3 scripts/strava_api.py activities --limit 20

# Get specific activity
python3 scripts/strava_api.py activity 12345678

# Explore segments in area
python3 scripts/strava_api.py segments "37.7,-122.5,37.8,-122.4" --type running

# Raw API request
python3 scripts/strava_api.py raw GET /athlete/zones
python3 scripts/strava_api.py raw POST /activities --data '{"name":"Test","sport_type":"Run","start_date_local":"2024-01-15T10:00:00Z","elapsed_time":1800}'

Python 导入

from scripts.strava_api import StravaClient

client = StravaClient()  # Auto-loads from keychain, refreshes token if needed

# Get athlete
athlete = client.get_athlete()

# List activities
activities = client.list_activities(per_page=50)

# Create activity
new_activity = client.create_activity(
    name="Morning Run",
    sport_type="Run",
    start_date_local="2024-01-15T07:30:00Z",
    elapsed_time=1800,
    distance=5000
)

令牌管理

令牌会自动刷新。检查状态：

# Check token status
python3 scripts/refresh_token.py --status

# Force refresh
python3 scripts/refresh_token.py --force

---

决策树

User Request
├── First time / "setup strava" → Run setup_oauth.py
├── "Get my profile/stats" → strava_api.py athlete/stats
├── "List my activities" → strava_api.py activities
├── "Get activity details" → strava_api.py activity {id}
├── "Create/log activity" → client.create_activity()
├── "Update activity" → client.update_activity()
├── "Get training data/streams" → client.get_activity_streams()
├── "Find segments nearby" → strava_api.py segments {bounds}
├── "Export route" → raw GET /routes/{id}/export_gpx
└── "Token expired" → Auto-handled by client

---

快速参考

项目	值
密钥存储	系统钥匙串（安全）
元数据位置	~/.strava/metadata.json
Base URL	https://www.strava.com/api/v3
速率限制	100 请求/15 分钟，1000 请求/天
令牌有效期	6 小时（自动刷新）

参考：

• 完整 API 文档：references/api_reference.md
• 手动设置：references/setup_guide.md

运动类型

• 跑步：Run、TrailRun、VirtualRun
• 骑行：Ride、MountainBikeRide、GravelRide、EBikeRide
• 其他：Swim、Walk、Hike、Workout、WeightTraining、Yoga

错误处理

状态	含义	操作
401	令牌过期	由客户端自动处理
403	权限范围不足	重新运行 setup_oauth.py
404	找不到资源	检查 ID
429	速率限制	等待 15 分钟