Garmin Coach（DSH Garmin 运动 AI 教练）
Garmin Connect 同步 + AI 教练分析 + 训练计划生成 — DeepSeek Harness 插件。
把你的 Garmin 账号连到 DSH，自动同步活动/健康/HRV 数据，AI 基于真实数据给出专业训练建议。
⚠️ 免责声明
本插件通过逆向分析调用 Garmin Connect 的内部接口，使用非佳明官方公开的 client_id 模拟客户端登录。佳明不为第三方使用背书，账号可能因异常登录被限流或封禁。
本插件仅供学习与个人研究使用，请勿用于批量同步他人账号或任何违反佳明《Terms of Service》或所在地区法规的场景。
本插件按 「现状」（AS IS） 提供，作者不承担因以下原因造成的任何损失：
- 佳明账号被封禁、限流或任何处置
- 同步数据丢失、错乱、延迟
- 训练建议 / 训练计划不当造成的健康问题
- 佳明接口改版导致插件不可用
- 您违反佳明 ToS 或所在地法规而产生的法律后果
使用即表示您已理解并接受上述风险。
✨ 功能
| 模块 | 内容 |
|---|
| 🔐 认证 | CN 账号 + 短信 MFA + DI OAuth2（access token ~1h 自动 refresh） |
| 📊 数据同步 | 增量同步（不重复拉全量），手动触发（防 Garmin 行为指纹检测） |
| 📈 运动看板 | 30+ 分析（距离/配速/心率/HR-Pace/步频/TRIMP/时段/一致性等） |
| 🤖 AI 训练建议 | 规则生成洞察（PB 变化、跑量趋势、步频建议等） |
| 📋 训练计划 | AI 生成结构化计划 + 打卡勾选 + 历史版本/恢复 |
| 📓 训练日记 | 训练后记感受/评分 + 时间线查看 |
| 🔄 AI 工具 | 17 个工具，AI 对话中可直接调用（如"月报"/"训练计划"） |
| 💾 持久化 | 数据存 ~/data/（garmin.json + training-plan.json + training-diary.json） |
📦 安装
前置条件
- DSH (DeepSeek Harness) 已安装并运行
- Garmin 账号（支持 CN/国际）
- Node.js 18+
- pnpm（推荐）或 npm
💡 为什么需要手动加 bundles？
DSH 启动时只显式加载 dsh.profile.bundles 列表里的包，不自动扫 node_modules/ 加载所有 dsh-* 包（这是设计：稳定性、隔离性、性能）。所以 pnpm add dsh-garmin-coach 装包后，必须手动加到 bundles——这是 DSH 的工作方式，不是 bug。
DSH 官方推荐用 dshmarket（应用市场）装包——它会自动加 bundles。dsh-garmin-coach 目前还在审核中，临时手动加即可。
一键安装（推荐）
cd ~/.dsh/profiles/web
pnpm add dsh-garmin-coach
装完后还需要把 dsh-garmin-coach 加到 bundles（DSH 启动时只显式加载 bundles 里的包）：
方法 1：手动改 package.json
编辑 ~/.dsh/profiles/web/package.json，在 dsh.profile.bundles 列表末尾加：
"dsh": {
"profile": {
"bundles": [
...其他包,
"dsh-garmin-coach" ← 加这行
]
}
}
方法 2：命令行追加
cd ~/.dsh/profiles/web
node -e "
const fs = require('fs');
const p = JSON.parse(fs.readFileSync('package.json', 'utf8'));
if (!p.dsh.profile.bundles.includes('dsh-garmin-coach')) {
p.dsh.profile.bundles.push('dsh-garmin-coach');
fs.writeFileSync('package.json', JSON.stringify(p, null, 2) + '\n');
}
"
加完后重启 DSH（您自己执行）：
ddsh restart
打开 DSH → 设置 → 应该看到 Garmin Coach 卡片。
手动注册（旧方式，不推荐）
在 ~/.dsh/profiles/web/cordis.patch.yml 手动添加（如果不想用 bundles）：
- insert:
- id: garmin-coach
name: dsh-garmin-coach
首次配置
- 打开 DSH 设置 → Garmin Coach
- 选择账号区域（CN 或 国际）
- 输入邮箱 + 密码
- 登录后如需要 MFA，输入短信验证码
- 点击保存配置
- 等待几秒，token 会自动保存（加密）
- 点击立即同步 → 按设置中的"回看天数"拉取（默认 30 天，可在 Garmin Coach 设置页修改）
⚠️ 首次同步后，数据存到 ~/data/garmin.json（macOS/Linux 用户 Home 目录）。Windows 用户在 DSH 启动目录下的 data\garmin.json。
🚀 使用
运动看板
点击侧栏 Garmin Coach → 打开运动看板。
默认显示：
- 运动总览（总距离/次数/时长/配速/最长）
- 健康数据（步数/心率/压力/Body Battery）
- AI 训练建议（💡⚠️🔴）
- 训练计划（折叠）+打卡
- 各项分析 section
最近活动表支持：
- 筛选（按运动类型：跑步/骑行/登山等）
- 排序（按日期/距离/配速/心率）
- + 按钮展开心率区间（Z1恢复/Z2有氧/Z3节奏/Z4阈值/Z5无氧）和运动时间（10:00-11:30）
AI 对话
直接用自然语言提问，AI 自动调用工具：
| 自然语言 | AI 调用 |
|---|
| "六月份报告" | garmin_report(month) |
| "我十公里最好成绩" | garmin_best_pace(10000) |
| "本周跑量" | garmin_distance_stats(week) |
| "帮我制定半马破2计划" | garmin_training_plan + garmin_save_training_plan |
| "记录今天的训练：跑了 6km，4星" | garmin_log_diary |
| "我的训练进度" | garmin_plan_progress |
训练计划工作流
对话："帮我制定 10km 进 5:30 的计划"
→ AI 调 garmin_training_plan（基于您的基线数据）
→ AI 生成 4 周计划 + 16 个训练任务
→ AI 调 garmin_save_training_plan 保存
打开看板 → 看到训练计划（默认折叠）→ 点 ▶ 展开 → 勾选完成的任务
误操作：AI 误覆盖 → 对话："找回之前的计划" → AI 调 garmin_plan_history + garmin_restore_plan
⚙️ 配置
账号区域
- CN：
sso.garmin.cn（中国账号）
- 国际：
sso.garmin.com（其他地区）
数据存储位置
所有数据存到 DSH 用户的 data/ 目录（macOS/Linux 是 Home 目录，Windows 是 DSH 启动目录）：
~/data/ # macOS/Linux
%USERPROFILE%\data\ 或 <DSH_cwd>\data\ # Windows
├── garmin.json # meta + daily（同步数据，约 100 KB）
├── garmin-activities.json # activities（约 1.75 MB，单独文件）
├── training-plan.json # 当前训练计划 + 打卡状态
├── training-diary.json # 训练日记
└── training-plan-history/ # 计划历史（自动备份）
同步策略
- 手动同步（推荐）：点击卡片"立即同步"按钮或对话"同步数据"
- 增量：每次只拉上次同步后的新数据（从 lastSyncAt 前一天到今天），但若距上次同步已超过"回看天数"配置，则至少回看该配置值（默认 14 天）
- 防行为指纹：无定时同步（避免被 Garmin 检测为自动化）
⚠️ 重要：文件写入权限
本插件需要把同步数据、训练计划、训练日记写入 ~/data/（macOS/Linux）或 C:\Users\<you>\.dsh\data\（Windows）。
DSH 在沙箱里运行，默认没 full access 权限——会导致：
- 同步数据看起来成功但实际写错地方（或失败丢失）
- 训练计划看板看不到刚保存的内容
- 打卡后重启数据丢失
修复方法（在 DSH 里启用文件写权限）：
| 平台 | 步骤 |
|---|
| macOS | 第一次写文件时会弹"权限"请求 → 允许"完整文件访问" |
| Windows | DSH 设置 → 沙箱/安全 → 开启「完整文件访问」(full file access) → 重启 DSH |
| Linux | 通常默认有权限；如有问题检查 ~/data/ 目录权限 chmod 755 ~/data |
插件已自带保护：写文件前会探测权限，权限不足时会返回明确错误（包含路径 + 修复方法），而不是静默失败。
🔧 AI 工具列表（17 个）
基础查询（6，src/tools/register.ts）
garmin_whoami / garmin_daily / garmin_sleep / garmin_hrvgarmin_activities / garmin_summary
统计与计划（11，src/tools/stats-tools.ts）
garmin_sync / garmin_recent_activities / garmin_best_pacegarmin_report / garmin_training_plan / garmin_save_training_plangarmin_toggle_task / garmin_plan_progress / garmin_restore_plangarmin_log_diary / garmin_diary
🔐 安全
Garmin 账号安全（铁律）
- 不自动重试登录 — 任何重试必须先经您同意（避免封号）
- token 自动 refresh — ~28h access token，过期前自动换新
- refresh 也失效 → 提示重新连接 — 自动清除失效 token
数据隐私
- 所有数据存本地（
~/data/），不上传任何服务器
- 密码/email 不持久化到 settings——只在登录时通过 HTTP body 传给后端（DSH 默认监听 127.0.0.1，外部网络拿不到）
- 仅与 Garmin API 通信（直接 HTTPS，无中间服务）
🛠️ 开发
构建
npm install
npm run build # tsc → lib/
npm run typecheck # 类型检查
数据目录
- 开发时 cwd 是插件目录 → 数据存
data/
- DSH 进程 cwd 是用户主目录 → 数据存
~/data/
- 代码自动用
process.env.HOME/data（统一路径）
项目结构
src/
├── index.ts # 插件主入口（apply/register/工具注册）
├── storage.ts # GarminStoreFile（数据存储 + 3 文件 IO + 计划缓存）
├── sync.ts # 同步逻辑（增量 + 4 端点并行 + 空 daily 过滤）
├── stats.ts # 运动分析 + 报告聚合 + dailyRecent 推送
├── settings-web.ts # settings route（/garmin-settings）
├── boundary.ts # 错误边界（withBoundary 容错）
├── logger.ts # 日志（落盘到 plugin 日志文件）
├── tools/
│ ├── register.ts # 基础工具（6）
│ └── stats-tools.ts # 统计工具（11）
├── auth/
│ ├── client.ts # DI OAuth2 + token refresh
│ ├── file-store.ts # 持久化 token/mfa state
│ ├── cookie-jar.ts # Set-Cookie 解析
│ ├── token-store.ts # TokenStore 接口
│ ├── types.ts # 类型定义
│ └── constants.ts # CN/国际端点
└── api/
└── queries.ts # 5 端点查询方法（daily/sleep/hrv/readiness/training/activities/summary/whoami）
lib/ # 编译产物
├── *.js + *.d.ts
└── client.js # 看板前端（手写 React IIFE）
cordis.patch.yml # 注册入口
package.json
tsconfig.json
📝 更新日志
见 CHANGELOG.md。
🤝 贡献
欢迎提 issue / PR。建议先开 issue 讨论再改。
📄 License
MIT — 详见 LICENSE。
