前言¶

做智能体或桌面助手时，健康与训练数据往往散在 Garmin Connect 网页或手机 App 里，对话里临时查睡眠、负荷、最近骑行也不方便。通用 MCP 可以接设备数据，但要自己拼面板、鉴权与展示。佳明助手（Garmin Assistant）是 DeepSeek Harness（DSH）桌面版的 Cordis 插件：把 Garmin 官方 Personal API（及可选的账号登录进阶能力）收进一个常驻面板，并叠上 AI 教练、路书与多日行程等能力。下面按定位、功能、安装与注意点说明用法。

这是什么¶

• 名称与维护：开源项目 zeelinkCN/dsh-garmin-assistant，维护者 zeelinkCN；MIT 许可证；当前资料中的版本为 1.5.1。
• 分类：DSH 生态目录中归类为「客户端」插件；社区目录见 SkillHub 插件页。
• 定位：DeepSeek Harness 桌面版插件（非通用 MCP 服务，非 Garmin 官方应用）。数据默认经 Garmin 官方 Personal API（只读、免费、无需账号密码）；训练负荷、训练准备度等未在 Personal API 开放的指标，可在面板内一键进入「账号登录」进阶模式（后台自动准备组件，无需开终端）。
• 平台：依赖 Harness 桌面 0.2.x（Cordis 插件体系、ctx.webServer、浏览器模块加载）；macOS 已实机验证；Windows 安装器有平台分支但资料标明尚未实机验证；Linux 未测试。DSH Web/CLI 及其他 AI 客户端不在验证范围内。

数据从哪来¶

默认：Personal API（推荐）¶

1. 在 Garmin Connect 网页版「设置 → Personal API」创建 Key，粘贴到面板。
2. Key 存本地 ~/.garmin-personal-key（权限 600），24 小时令牌自动续期。
3. 覆盖范围包括：睡眠（评分/分期/HRV/静息心率）、Body Battery、压力、呼吸、血氧、水分、步数/卡路里/楼层、心率区间、活动列表与详情、原始 FIT 下载、体重、营养、体能年龄等。

进阶：Garmin 账号登录（可选）¶

官方 Personal API 不提供：训练负荷（CTL/ATL/ACWR）、训练准备度、VO₂max 趋势、比赛预测、装备、训练计划等。在面板点「解锁进阶数据」后，用 Garmin 账号（含两步验证）登录；不点击则不会下载进阶相关组件。

核心功能¶

面板把「今天能不能练、睡得如何、负荷高低、最近骑了哪」集中到一处，主要能力如下（均摘自项目 README，未实机逐项核对的不在此夸大）。

• 今日与身体：训练准备度（进阶）、睡眠评分、Body Battery、静息心率、本周强度分钟；步数环、卡路里、压力、心率、呼吸、血氧、水分、楼层。
• 恢复与睡眠：准备度六因子、HRV 周均、恢复倒计时（进阶）；近 7 晚深/浅/REM/清醒堆叠与评分折线。
• 趋势与细节：7 天 / 30 天健康趋势（静息心率、HRV、睡眠、步数等十类指标）；心率区间、睡眠规律性、身体成分、HRV 基线、Body Battery 日内曲线。
• 活动：最近活动详情（进阶下可有分段、区间、天气、装备、离线轨迹与海拔剖面）；FIT 曲线与进阶分析（功率曲线 PDC、爬坡 VAM、心率漂移等）。
• 训练计划（进阶，只读）：本周课表、Garmin Coach、目标进度；编辑与排课跳转 Garmin Connect。
• AI：教练（今日结论、训练/恢复建议、风险提醒、明日安排）；健康管家（睡眠、HRV、压力、生活习惯）；营养建议（按训练量/体重/睡眠给出热量与宏量，Garmin 营养会员能力不由 API 提供时用 AI 生成）。
• 地图与路书：活动轨迹与路书预览使用高德静态底图（WGS84→GCJ-02）；可配置高德 Web 服务 Key、行者应用 ID+Secret。路书工坊支持导入/导出；自然语言生成 2–3 条候选路书；多日行程（2–15 天）可 AI 拆天并用高德逐日算路。
• 交互：顶栏可回看最近 30 天；个性化里区块与卡片（共 23 张）可拖拽排序、隐藏；首次打开有三步新手引导；插件设计为只读（改名、排课、删活动等写操作建议在对话里交给 agent）。

安装与启用¶

前置：已安装 DeepSeek Harness 桌面版 0.2.x。

资料中的安装步骤为：先取得插件目录，再用 desktop profile 添加本地路径。README 原文如下：

git clone https://github.com/zeelinkCN/dsh-garmin-assistant.git
dsh plugin --profile desktop add ./dsh-garmin-assistant

首次打开面板进入向导：在 Garmin 官网创建 Personal API Key → 粘贴并验证 → 即可使用；向导里也提供账号密码登录（进阶模式）入口。

插件以当前 DSH 进程权限运行；安装前建议阅读仓库源码与 MIT 许可证，自行判断是否信任维护者与网络行为（资料写明：默认模式无密码上传、无遥测；Garmin 请求由本机直连 Garmin）。

典型用法¶

1. 零门槛看盘：完成 Personal API Key 配置后，看今日状态、睡眠近 7 晚、健康趋势与最近活动，无需开启进阶模式。
2. 看负荷与课表：在面板解锁进阶并登录 Garmin 账号后，查看 ATL/CTL/ACWR、训练计划与 FIT 深度分析。
3. 路书与行程：在路书工坊导入 GPX 或行者编号；或用一句话描述路线，从候选里保存；多日行程选天数后生成整程或按日路书（联网参考经典路线为可选项）。
4. 可选地图 Key：新手引导第 3 步或「账号设置」中填写高德 Web 服务 Key / 行者 ID+Secret；不填则基础功能仍可用，地图失败时回退 SVG。
5. 维护数据授权：右上角「账号设置」可重验 Key、重新登录、刷新数据；授权过期时顶部有提示条。

适用场景与注意¶

适合谁：已在用 Harness 桌面 0.2.x、且有 Garmin 账号（国际版或中国区）的开发者或运动用户，希望在同一桌面环境里看 Connect 数据并辅以 AI 建议，而不是单独再开一堆网页。

限制（README 已知项）：

• Host 侧改动需重启 Harness；Client 侧约 500ms 内热更新。
• 官方 API 部分区间端点有 28/31 天上限。
• 官方模式下活动详情无分段/区间/天气，轨迹依赖进阶模式（后续计划改为本地解析 FIT）。
• 一个面板对应一个 Garmin 账号。

AI 建议仅供参考，不构成医疗建议；Garmin、Garmin Connect 为 Garmin Ltd. 商标，本项目为第三方开源，与 Garmin 无关联。

结尾¶

佳明助手把 Garmin Connect 的只读 API 与可选进阶登录收成 Harness 里的可视化面板，并扩展 AI 教练、路书工坊与多日行程，适合想把训练与健康数据留在桌面工作流里的用户。更多说明与截图见 GitHub README；插件收录页：SkillHub · dsh-garmin-assistant，源码：github.com/zeelinkCN/dsh-garmin-assistant。