前言¶
在 DeepSeek Harness（DSH）里做个人健康或跑步相关的智能体，常见做法是手写脚本拉 Garmin API，再把 JSON 塞进对话上下文。数据字段多、认证方式杂，代理也很难在「查睡眠」「对比最近跑步配速」「下载 FIT 原始文件」之间自动切换。
dsh-plugin-garmin-connect（GitHub 仓库 Likenttt/garmin-connect-plugin-for-dsh）把 Garmin Connect 注册成一组 AI 可调用工具：安装并配置凭据后，代理通过自然语言触发查询，不必每次手写 HTTP 请求。插件同时提供独立 MCP 入口，可在 Cursor、Codex、Claude Code 等客户端复用同一套工具，不强制依赖 DSH Web 界面。
这是什么¶
npm 包名 dsh-plugin-garmin-connect，当前版本 0.1.5，MIT 许可证，要求 Node.js ≥ 20。维护者为 Likenttt，在 SkillHub 社区目录归类为「联网工具」，GitHub 约 10 stars。
插件通过 @deepseek-ai/cordis 挂载到 DSH，底层使用 garmin-connect 库访问 Garmin Connect。一句话定位：把佳明账号里的活动、睡眠、步数、心率、体重、训练库等数据，以及有限的写操作（下载 FIT、创建训练），暴露为结构化工具供模型调用。
SkillHub（skillhub.cn）是 DSH 插件的独立社区目录，与 DeepSeek / 幻方无官方从属关系；安装与文档以仓库 README 和 npm 发布页为准。
核心功能¶
插件共注册 10 个工具。其中 8 个只读 Garmin 数据；download_garmin_activity_fit 会在 MCP/dsh 所在主机写入本地文件；create_garmin_workout 会修改用户的 Garmin 训练库。
| 工具名 | 用途 |
|---|---|
get_garmin_activities |
近期运动记录，支持 compact / full 详情 |
get_garmin_sleep |
睡眠评分、时长与阶段分布 |
get_garmin_steps |
步数；目标与步行距离仅在 Garmin 上游提供时出现 |
get_garmin_heart_rate |
静息、最高、最低心率 |
get_garmin_weight |
体重、BMI、体脂率、骨骼肌等身体成分 |
get_garmin_workouts |
训练库中的可复用模板（非日历排期） |
get_garmin_profile |
经字段白名单过滤的个人资料摘要 |
get_running_skill_advice |
讲解课型与训练理念，或在完成问询后给出个性化跑步建议 |
download_garmin_activity_fit |
下载活动归档并提取唯一 FIT 文件到配置的父目录 |
create_garmin_workout |
预览结构化训练；用户显式确认后才创建 |
create_garmin_workout 采用两次调用：首次返回预览和一次性 confirmationId（10 分钟有效）；用户确认未改动的预览后，再以 confirmed: true 和同 ID 二次调用。
get_running_skill_advice 区分两种模式：
mode: "explain"：只讲解课型或训练理念（汉森、丹尼尔斯、挪威阈值、极化训练等），不生成个人日程。mode: "personalized"：须先补齐六组问询（目标、当前成绩、训练背景、可用时间、健康约束、训练偏好）；缺项时只返回追问，不读 Garmin 活动、不猜计划。若hasWarningSymptoms为 true，工具会安全停止并建议就医评估，不返回课型素材。
安装与启用¶
环境需具备 Node.js ≥ 20，且 pnpm 在 PATH 中。下面先做依赖准备，再安装插件。
npm install -g pnpm
推荐从 npm registry 安装并激活 web profile（首次运行会自动初始化 profile）：
npx --legacy-peer-deps=false @deepseek-ai/dsh plugin --profile web add dsh-plugin-garmin-connect
--legacy-peer-deps=false 让 npm 正常解析 peer 依赖；若本机 npm 配置了 legacy-peer-deps=true，DSH 可能因缺少 @deepseek-ai/cordis-plugin-group 报 ERR_MODULE_NOT_FOUND。
不启动服务即可检查插件是否已写入配置：
npx --legacy-peer-deps=false @deepseek-ai/dsh --profile web --dump-config | grep -A 2 garmin-connect
若尚未安装 DSH CLI，可执行：
npx --legacy-peer-deps=false @deepseek-ai/dsh web
默认 Web 界面为 http://127.0.0.1:3080。在 设置 → 插件 → 插件列表 中，plugin-garmin-connect 显示为已挂载、已启用即表示加载成功。
配置凭据¶
插件不持久化账号密码。在运行 dsh 的工作区根目录新建 .env（registry 安装不会自动带出模板，可参考仓库 .env.example）。GARMIN_PASSWORD、GARMIN_SESSION_TOKEN、GARMIN_SESSION_TOKEN_FILE 三选一；有效 session 优先于密码登录。
GARMIN_USERNAME=your-email@example.com
GARMIN_PASSWORD=your-password
GARMIN_REGION=global
GARMIN_REGION 可选 global（国际，默认）或 cn（佳明中国）。使用 FIT 下载工具时须额外设置 GARMIN_FIT_DOWNLOAD_DIR 为绝对路径父目录。
0.1.5 重要限制： Garmin 两步验证尚未完成，不属于本次发布支持的能力。README 中的浏览器认证命令（garmin-connect-auth login --browser 或源码 npm run auth:setup）仅供本地开发调试，不能依赖其做生产访问或 session 恢复。MCP 侧只能读取已有的有效 session 文件，不会提示 MFA。
典型用法¶
配置完成后，在 DSH Web 对话中直接用自然语言提问，代理会选择对应工具：
- 「我昨晚睡得怎么样？」
- 「帮我看一下最近 5 次跑步的配速变化。」
- 「我今天走了多少步？」
工具层参数示例（供理解调用形态，一般由代理自动构造）：
{"limit": 5, "detail": "compact"}
{"startDate": "2023-10-01", "endDate": "2023-10-02"}
讲解训练理念时可指定中文：
{"mode": "explain", "query": "丹尼尔斯", "language": "zh-CN"}
不安装 DSH 时，npm 包还提供独立 MCP 服务器（lib/mcp.js，系统命令 garmin-connect-mcp）。在已配置 session 的前提下，可将同一套工具接入 Cursor、Codex、Claude Code 等客户端；配置方式见仓库 README「在其他 AI 编程助手中使用（MCP 协议）」章节。
适用场景与注意¶
适合谁： 已在 Garmin Connect 记录运动与健康数据、希望在 DSH 或其它 MCP 客户端里用自然语言查询或有限写入（创建训练、导出 FIT）的开发者与个人用户。
运行权限： 插件以当前 dsh 或 MCP 进程权限运行，可访问进程环境变量中的凭据，并在主机上写入 FIT 文件或调用 Garmin 写接口。安装前应阅读源码与 MIT 许可证，确认凭据存放与文件输出路径符合本机安全策略。
多账号与 session： 当前模型是「每账号每进程」——不同客户端或账号应使用独立初始化的 GARMIN_SESSION_TOKEN_FILE，不要并发共享同一 session 文件（refresh token 可能轮换）。多个进程可共享同一 GARMIN_FIT_DOWNLOAD_DIR 父目录，插件会按区域与规范化邮箱建子目录隔离。
数据与隐私： GARMIN_ACTIVITY_DETAIL=full 时活动数据可能包含精确路线与位置；session token 与密码同等敏感，不要粘贴进 AI 对话。download_garmin_activity_fit 只向模型返回 activityId、fileName、sizeBytes、sha256，不返回完整磁盘路径。
版本与生态： 依赖 @deepseek-ai/cordis ^4.0.1；DSH 生态理念是「一切皆插件」，本插件是社区维护的联网扩展，非 Garmin 或 DeepSeek 官方产品。
链接¶
- SkillHub 目录页：garmin-connect-plugin-for-dsh
- GitHub 仓库：Likenttt/garmin-connect-plugin-for-dsh
- npm 包：dsh-plugin-garmin-connect
把 Garmin 数据注册成标准工具后，健康与跑步类智能体可以少写一层 API 胶水，把精力放在对话逻辑与训练建议上；在 0.1.5 阶段，认证链路仍以密码或已有 session 为主，浏览器 MFA 流程仍属开发预览，部署前请对照 README 中的 WARNING 说明。
