前言¶

做智能體或桌面助手時，健康與訓練數據往往散在 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。