佳明运动教练 csustyang/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 或所在地法规而产生的法律后果

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

✨ 功能

| 模块 | 内容 |
| 🔐 认证 | 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

首次配置

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 自动调用工具：
| 自然语言 | 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_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。