前言¶
在 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 說明。
