dsh-garmin-coach

Garmin Coach（DSH Garmin 运动 AI 教练）

Garmin Connect 同步 + AI 教练分析 + 训练计划生成 — DeepSeek Harness 插件。

把你的 Garmin 账号连到 DSH，自动同步活动/健康/HRV 数据，AI 基于真实数据给出专业训练建议。

⚠️ 免责声明

本插件通过逆向分析调用 Garmin Connect 的内部接口，使用非佳明官方公开的 client_id 模拟客户端登录。佳明不为第三方使用背书，账号可能因异常登录被限流或封禁。

本插件仅供学习与个人研究使用，请勿用于批量同步他人账号或任何违反佳明《Terms of Service》或所在地区法规的场景。

本插件按 「现状」（AS IS） 提供，作者不承担因以下原因造成的任何损失：

• 佳明账号被封禁、限流或任何处置
• 同步数据丢失、错乱、延迟
• 训练建议 / 训练计划不当造成的健康问题
• 佳明接口改版导致插件不可用
• 您违反佳明 ToS 或所在地法规而产生的法律后果

使用即表示您已理解并接受上述风险。

✨ 功能

📦 安装

前置条件

• 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

首次配置

1. 打开 DSH 设置 → Garmin Coach
2. 选择账号区域（CN 或 国际）
3. 输入邮箱 + 密码
4. 登录后如需要 MFA，输入短信验证码
5. 点击保存配置
6. 等待几秒，token 会自动保存（加密）
7. 点击立即同步 → 按设置中的"回看天数"拉取（默认 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 自动调用工具：

训练计划工作流

对话："帮我制定 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 里启用文件写权限）：

插件已自带保护：写文件前会探测权限，权限不足时会返回明确错误（包含路径 + 修复方法），而不是静默失败。

🔧 AI 工具列表（17 个）

基础查询（6，src/tools/register.ts）

• garmin_whoami / garmin_daily / garmin_sleep / garmin_hrv
• garmin_activities / garmin_summary

统计与计划（11，src/tools/stats-tools.ts）

• garmin_sync / garmin_recent_activities / garmin_best_pace
• garmin_report / garmin_training_plan / garmin_save_training_plan
• garmin_toggle_task / garmin_plan_progress / garmin_restore_plan
• garmin_log_diary / garmin_diary

🔐 安全

Garmin 账号安全（铁律）

1. 不自动重试登录 — 任何重试必须先经您同意（避免封号）
2. token 自动 refresh — ~28h access token，过期前自动换新
3. 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。