Huawei Training Camp MCP

把你的华为运动健康数据接入 AI——让 Claude、Cherry Studio 等 AI 客户端 直接查询并分析你的训练记录、睡眠、心率、跑力，像和一个懂训练的教练聊天一样。

安全边界：本项目不实现任何绕过华为权限、破解认证、窃取 Cookie、 绕过访问控制的功能。认证信息只由用户本人通过环境变量显式提供 （来自用户自己已登录的浏览器会话），不写入代码 / 配置 / Git。

目录

• 这是什么？能干嘛？

• 开始之前：你需要准备什么

• 五步上手教程

  • 第 1 步：安装 Python

  • 第 2 步：下载本项目并安装依赖

  • 第 3 步：获取华为凭证（关键步骤）

  • 第 4 步：连通性自检

  • 第 5 步：接入你的 AI 客户端

• 怎么用：可以问 AI 的问题

• 功能一览（14 个 MCP 工具）

• 排障：401 / 认证过期

• 常见问题 FAQ

• 开发

• 已验证的真实 API 契约（摘要）

• 许可证与免责声明

这是什么？能干嘛？

你戴着华为手表 / 手环运动，数据都同步在华为运动健康里，但想分析时只能在 App 里一屏屏翻。本项目把这些数据变成 AI 能直接调用的工具（MCP， Model Context Protocol——一个让 AI 安全使用外部数据的标准协议）。

接入后，你可以直接对 AI 说：

• "我最近 4 周跑量 trend 怎么样？和上个月比呢？" → AI 调用周趋势 + 环比工具

• "分析一下我昨天那次间歇跑的心率曲线" → AI 调用训练详情 + 统计摘要

• "我最近睡眠质量如何？静息心率有没有异常？" → AI 调用睡眠 / 静息心率工具

• "我现在跑力多少？预测我半马能跑多少？" → AI 调用运动能力评估工具

数据永远只在你自己的电脑 ↔ 华为服务器之间流动，AI 客户端通过本项目的 本地服务读数，不经过任何第三方服务器。

开始之前：你需要准备什么

不需要会编程——下面每一步都是复制粘贴级别的内容。 需要的只是按顺序做完五步。

五步上手教程

第 1 步：安装 Python

1. 打开 python.org/downloads，下载 Python 3.12 或更高版本的安装包（Windows 点黄色大按钮即可）；

2. 运行安装包，务必勾选最底部的 Add Python to PATH（不勾后面会报 "'python' 不是内部或外部命令"），然后点 Install Now；

3. 验证：按 Win + R，输入 powershell 回车，在蓝底窗口输入：

   python --version

   显示 Python 3.12.x（或更高）即成功。

第 2 步：下载本项目并安装依赖

1. 在本仓库页面点绿色的 Code → Download ZIP，解压到任意目录 （本文以 C:\huawei-health-mcp 为例；会 Git 的同学直接 git clone 更好， 方便以后更新）；

2. 打开 PowerShell（Win + R → 输入 powershell 回车），逐行粘贴执行：

   cd C:\huawei-health-mcp                 # 进入项目目录（按你的实际解压路径改）
   python -m venv .venv                    # 创建独立的运行环境（约 30 秒）
   .\.venv\Scripts\pip install -r requirements.txt   # 安装依赖（约 1~2 分钟）

3. 装完先跑一遍自带测试（不需要任何凭证，验证环境没问题）：

   .\.venv\Scripts\python.exe -m pytest -q

   最后显示 315 passed 即环境就绪。

第 3 步：获取华为凭证（关键步骤）

本项目通过你自己浏览器里的登录凭证访问你的数据（就像你本人打开网页版 一样）。凭证 = 两个字符串，从浏览器里复制出来：

1. 用电脑浏览器登录华为运动健康网页端，确认能看到自己的训练数据；

2. 按 F12 打开开发者工具 → 切到 Network（网络） 标签；

3. 按 F5 刷新页面，Network 列表里会出现一堆请求；

4. 在过滤框输入 activityRecord，找到其中一条状态码 200 的请求， 点它；

5. 右侧切到 Headers（标头） → 往下翻到 Request Headers（请求标头）， 找到并复制这两个值（复制时从行首选到行尾，别多别少）：

   • Authorization：一长串以 Bearer 开头 → 对应 HTC_AUTHORIZATION

   • x-client-id：一串字母数字 → 对应 HTC_CLIENT_ID

6. 回到 PowerShell，粘贴设置（引号要保留）：

   $env:HTC_AUTHORIZATION = "粘贴 Authorization 的完整值"
   $env:HTC_CLIENT_ID     = "粘贴 x-client-id 的值"

安全须知：

• 这两个值等同于你的登录态，只粘贴到环境变量里，不要发给别人、 不要截图发群里、不要写进任何文件；

• 它们会在几小时到几天后过期（华为控制），过期后按 401 排障 重新抓一次即可；

• 关闭这个 PowerShell 窗口后变量即消失，下次使用重新设置 （这是特性不是 bug——凭证不落盘）。

第 4 步：连通性自检

还在同一个 PowerShell 窗口（凭证设好的那个），执行：

.\.venv\Scripts\python.exe scripts\test_real_htc.py

看到 HTC API request: SUCCESS 和你的训练列表 → 链路全通，继续下一步。

更多自检模式（可选）：

.\.venv\Scripts\python.exe scripts\test_real_htc.py sleep 7         # 最近 7 晚睡眠
.\.venv\Scripts\python.exe scripts\test_real_htc.py resting-hr 28   # 28 天静息心率
.\.venv\Scripts\python.exe scripts\test_real_htc.py hrv 28          # 28 天 HRV
.\.venv\Scripts\python.exe scripts\test_real_htc.py performance     # 跑力与预测成绩
.\.venv\Scripts\python.exe scripts\test_real_htc.py pb              # 个人纪录
.\.venv\Scripts\python.exe scripts\test_real_htc.py trend 8         # 8 周训练趋势

第 5 步：接入你的 AI 客户端

以 Cherry Studio 为例（Claude Desktop 等同理，都在 MCP / 工具设置里）：

1. 打开 设置 → MCP 服务 → 添加（或"+"新建）；

2. 类型选 stdio，按下表填写：

JSON 配置（部分客户端直接编辑配置文件，等价于上面）：

{
  "mcpServers": {
    "huawei-training-camp": {
      "command": "C:\\huawei-health-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.huawei_health_mcp.server"],
      "cwd": "C:\\huawei-health-mcp",
      "env": {
        "HTC_AUTHORIZATION": "<你的 Authorization 值>",
        "HTC_CLIENT_ID": "<你的 x-client-id 值>"
      }
    }
  }
}

重要：env 里的凭证写在你本机的客户端配置里（该文件只在你电脑上， 不在 Git 仓库里）。凭证过期后改这里的新值并重启客户端。

3. 保存并启用该服务，客户端里应该能看到 14 个工具（health_check、 get_recent_activities 等）；

4. 开个对话直接问："帮我看看最近两周的训练情况"——AI 会自己调用工具。

怎么用：可以问 AI 的问题

• 训练回顾："我最近 7 天练了多少？和上一个 7 天比呢？"

• 单次分析："分析我昨天那次跑步的心率和配速。"

• 长期趋势："最近 8 周跑量趋势如何？哪周练得最猛？"

• 恢复状态："我最近睡眠怎么样？静息心率正常吗？HRV 呢？"

• 能力评估："我现在的跑力是多少？预测全马成绩？我的 5 公里 PB 是什么时候跑的？"

提示：不需要记工具名——直接用自然语言说需求，AI 自己选工具。

功能一览（14 个 MCP 工具）

参数说明：

• lookback_days：查询窗口天数，默认 30，范围 1~730；查更早的训练时调大。

• days：恢复状态类窗口天数（睡眠默认 14，心率 / HRV 默认 28）。

• weeks（周趋势）：周窗口数，默认 4，范围 1~104；滚动 7 天连续窗口 （非自然周），单次列表请求整个跨度后本地归窗。

• window_days（周期对比）：单窗口天数，默认 7，范围 1~365。

• activity_id 来自 get_recent_activities 返回；HTC API 不支持按 id 直查详情，详情查询内部先在列表中定位该活动再拉取高频数据。

排障：401 / 认证过期

症状：任一 tool 报 HTC HTTP 请求失败：status=401（或脚本输出 HTC API request: FAILED + 401）。通常昨天还能用、今天全体 tool 一起失败—— 这是会话凭证过期的典型形态，不是本项目代码问题。

原因：HTC_AUTHORIZATION / HTC_COOKIE 来自浏览器会话，有效期由华为 服务端控制（数小时到数天不等），过期后所有请求统一 401。

修复步骤：

1. 浏览器重新登录华为运动健康网页端，确认页面能正常看到训练数据；

2. 开发者工具 → Network → 刷新页面 → 找到对 activityRecord:query 的 **成功（200）**请求 → 重新复制 Authorization 与 x-client-id；

3. 按使用方式刷新凭证：

   • 终端脚本：在同一个终端重新 $env:HTC_AUTHORIZATION = "<新值>" 等即可，下次运行生效；

   • MCP 客户端常驻服务：服务进程的环境在启动那一刻固定——需在 MCP 客户端的启动配置（env 段）里替换新值，然后重启 MCP 服务 / 客户端；

4. 验证：.\.venv\Scripts\python.exe scripts\test_real_htc.py 输出 SUCCESS 即恢复。

相邻情况区分：

安全提醒：排障过程中复制粘贴的凭证只进环境变量，不要截图 / 粘贴到 issue / 写入任何文件。

常见问题 FAQ

Q1：报错 "'python' 不是内部或外部命令" 安装 Python 时没勾 Add Python to PATH。最简单的解决：重新运行安装包， 勾上后再 Install；或改用 py 命令（py -m venv .venv）。

Q2：PowerShell 提示"在此系统上禁止运行脚本"（执行策略） 本教程的命令不涉及运行 .ps1 脚本，一般不会遇到。若确需放开，以管理员 开 PowerShell 执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned （输入 Y 确认）。

Q3：.\.venv\Scripts\pip 提示找不到路径 你不在项目目录里。先 cd 到项目根目录（有 requirements.txt 的那层）。

Q4：Network 里找不到 activityRecord 请求 确认已登录网页端且能看到数据；刷新页面后再看；过滤词换 activityRecord:query 或 things.dbankcloud 再试。

Q5：Mac / Linux 能用吗？ 可以。等价命令：python3 -m venv .venv、.venv/bin/pip install -r requirements.txt、.venv/bin/python -m src.huawei_health_mcp.server； 环境变量改用 export HTC_AUTHORIZATION="..." 写法。

Q6：我的数据会不会上传到第三方？ 不会。本服务只在你本机运行，请求只发往华为官方服务器。AI 客户端从本地 服务读数——你问 AI 时，AI 客户端会把要分析的数据发给你自己配置的模型 服务方（和你平时用它聊天是同一回事，介意的话选本地模型）。

Q7：凭证放环境变量安全吗？为什么不做自动登录？ 环境变量方式保证凭证不落盘、不进 Git。自动登录需要模拟华为认证流程， 属于绕过/逆向范畴，本项目不做（见安全边界）。

Q8：测试显示 315 passed 但我一条数据都没有？ 单元测试用合成数据，不需要凭证和网络。真实数据要看第 4 步的 test_real_htc.py 输出。

开发

# 运行全部测试（全部 Mock，不联网、不需要凭证）
.\.venv\Scripts\python.exe -m pytest -q      # 预期 315 passed

src/huawei_health_mcp/
├─ client.py             # HTCClient：HTTP 取数，返回原始 JSON（不解析）
├─ parser.py             # 训练原始 JSON → 标准模型（时间戳契约：记录 ms / 采样 ns）
├─ health_parser.py      # 恢复状态解析（睡眠记录 / 静息心率 / HRV 统计）
├─ performance_parser.py # 训练能力解析（运动能力评估 / PB 个人纪录）
├─ models.py             # Pydantic 模型（ActivityRecord / TrainingSummary / SleepRecord / AthleticPerformance 族）
├─ analysis.py           # 确定性统计分析（ActivityDetail → TrainingSummary）
├─ period_analysis.py    # 周期聚合（多 ActivityRecord → TrainingPeriodSummary）
├─ period_comparison.py  # 周期对比（两个 TrainingPeriodSummary → TrainingPeriodComparison）
├─ trend_analysis.py     # 滚动周趋势与相邻周环比（复用聚合层与对比层）
└─ server.py             # FastMCP 服务与工具接线
scripts/test_real_htc.py   # 人工真实请求脚本（十一模式，需要环境变量凭证）
scripts/test_mcp_client.py # 真实 MCP 客户端验收（14 个 tool 全调用）
tests/                     # 单元测试（synthetic fixture，无真实用户数据）
PROJECT_STATE.md           # 项目长期状态账本（新贡献者/Agent 从这里恢复上下文）

开发约定：认证只经环境变量；真实响应只存 data_temp/（git-ignored）； 测试全部使用 Mock / synthetic 数据；每个 Phase 完成后更新 PROJECT_STATE.md。

已验证的真实 API 契约（摘要）

• 列表 / 详情响应顶层均为 list

• 记录级与详情顶层时间为毫秒；采集器 / 采样点时间为纳秒

• 采样值 floatValue → float、integerValue → int

• 请求的数据类型不保证全部返回（details / samplePoints 可为空，属正常）

• 恢复状态端点：GET /healthRecords 时间戳为纳秒；healthRecords 统计的 startDay/endDay 为字符串、sampleSet 统计为数字（两端口径不混用）； 睡眠分段为分钟（light+deep+dream=all 自洽）

• 训练能力端点：GET /athleticPerformance/latest 直接收五项指数与 predictedTimes（秒）；GET /sportReports PB 的 startTime/endTime 为毫秒， value 单位由华为定义（时间为秒、距离为米）

许可证与免责声明

本项目以 MIT License 开源。

免责声明：本项目仅用于分析用户自己账号、自己授权的运动数据。 不实现任何绕过华为权限、破解认证、窃取 Cookie、绕过访问控制的功能。 使用本项目产生的任何后果（如账号因异常访问被服务方限制）由使用者自行承担。