mi-fitness 0.2.0

小米运动健康亲友数据 SDK

Mi Fitness

小米运动健康 SDK， 通过亲友列表获取其他账号的的心率、睡眠、步数等健康数据。

⚠️ 仅供学习与测试使用。 API 端点可能随版本更新而变化。

安装

pip install mi-fitness
# 或使用 uv
uv add mi-fitness

从源码安装：

git clone https://github.com/MistEO/MiSDK.git && cd MiSDK
uv sync

快速开始

登录（二维码扫码）

使用小米账号二维码扫码方式登录：

import asyncio
from mi_fitness import XiaomiAuth

async def login():
    async with XiaomiAuth() as auth:
        await auth.login_qr()
        auth.save_token("token.json")
        print(f"登录成功！user_id = {auth.token.user_id}")

asyncio.run(login())

自定义二维码展示回调：

async def login_with_callback():
    async def on_qr(qr_image_url: str, login_url: str) -> None:
        # qr_image_url 是二维码图片 URL
        print(f"请扫描: {qr_image_url}")

    async with XiaomiAuth() as auth:
        await auth.login_qr(qr_callback=on_qr)
        auth.save_token("token.json")

CLI 一行命令登录：

uv run python -m mi_fitness.cli qr-login

查询数据

import asyncio
from mi_fitness import MiHealthClient

async def main():
    async with MiHealthClient.from_token("token.json") as client:
        # 亲友列表
        relatives = await client.get_relatives()
        for r in relatives:
            print(f"[{r.relative_uid}] {r.relative_note}")

        uid = relatives[0].relative_uid

        # 最新快照（强类型）
        latest = await client.get_latest_data(uid)
        print(latest.available_keys)
        print(latest.heart_rate)  # LatestHeartRate(bpm=84, ...)
        print(latest.steps)       # StepData(steps=3716, ...)

        # 最近同步日摘要（心率+睡眠+步数并发获取）
        summary = await client.get_latest_daily_summary(uid)
        print(f"步数: {summary.steps}, 睡眠: {summary.sleep}, 心率: {summary.heart_rate}")

asyncio.run(main())

亲友管理

async def manage():
    async with MiHealthClient.from_token("token.json") as client:
        # 验证用户
        info = await client.verify_user(小米ID)
        print(f"找到: {info.nickname} (UID: {info.user_id})")

        # 发送邀请（默认共享全部数据类型）
        await client.invite_relative(info.user_id)

        # 删除亲友
        await client.delete_relative(亲友UID)

异常处理

from mi_fitness import MiHealthClient, TokenExpiredError, APIError

async def safe_query():
    try:
        async with MiHealthClient.from_token("token.json") as client:
            relatives = await client.get_relatives()
    except TokenExpiredError:
        print("Token 已过期，请重新登录")
    except APIError as e:
        print(f"API 错误: {e} (HTTP {e.status_code})")

API 一览

数据查询

方法	返回类型	说明
get_heart_rate(uid, date)	list[HeartRateData]	日均/静息/最大/最小心率、最新采样
get_sleep(uid, date)	list[SleepData]	时长/评分/深睡/浅睡/REM/片段详情
get_steps(uid, date)	list[StepData]	步数/距离/卡路里
get_calories_history(uid, date, days=1)	list[CaloriesData]	按天/按周获取活动卡路里
get_valid_stand_history(uid, date, days=1)	list[ValidStandData]	按天/按周获取有效站立次数
get_intensity_history(uid, date, days=1)	list[IntensityData]	按天/按周获取中高强度活动时长
get_spo2_history(uid, date, days=1)	list[Spo2SummaryData]	按天/按周获取血氧摘要
get_weight_history(uid, date, days=1)	list[WeightData]	获取时间窗口内的体重测量记录
get_blood_pressure_history(uid, date, days=1)	list[BloodPressureData]	获取时间窗口内的血压测量记录
get_weight(uid)	WeightData | None	体重/BMI
get_goal(uid)	GoalData | None	最新活力目标集合，支持 steps_goal / calories_goal / intensity_goal 便捷访问；不提供历史目标值
get_blood_pressure(uid)	BloodPressureData | None	最新血压
get_calories(uid)	CaloriesData | None	最新活动卡路里
get_valid_stand(uid)	ValidStandData | None	最新有效站立次数
get_intensity(uid)	IntensityData | None	最新中高强度活动时长
get_spo2(uid)	Spo2Data | None	最新血氧
get_latest_data(uid)	LatestDataSnapshot	强类型最新快照（goal/heart_rate/sleep/steps/weight/...）
get_latest_items(uid)	list[LatestDataItem]	原始 data_list，适合调试
get_daily_summary(uid, date)	DailySummary	心率+睡眠+步数并发获取
get_latest_daily_summary(uid)	DailySummary	自动使用最近一次同步日，减少空结果
get_aggregated_data(uid, key, start, end)	AggregatedDataResponse	自定义时间范围和数据类型
get_fitness_data(uid, key, start, end)	AggregatedDataResponse	原始测量/事件数据（如体重、血压、异常心率）

亲友管理

方法	说明
get_relatives()	获取所有已绑定亲友
find_relative(keyword)	按备注名或 UID 查找
verify_user(xiaomi_id)	添加亲友前验证用户信息
invite_relative(uid)	邀请用户成为亲友
delete_relative(uid)	解除亲友关系
accept_invite(msg) / reject_invite(msg)	接受/拒绝邀请
has_new_invite()	是否有新邀请
get_invite_link_id()	获取二维码邀请链接 ID
get_shared_data_types(uid)	查看对方共享了哪些数据类型
get_family_members()	家庭组成员列表

异常体系

异常	说明
MiSDKError	基础异常
AuthError	认证相关（登录失败等）
TokenExpiredError	Token 过期且自动刷新失败
DataNotSharedError	亲友未共享当前请求的数据类型
DataOutOfSharedTimeScopeError	查询日期超出亲友允许共享的时间范围
APIError	API 非预期响应（含 status_code 和 response_body）
DeviceUntrustedError	新设备需要短信验证
CaptchaRequiredError	触发图形验证码风控
FamilyMemberNotFoundError	找不到指定亲友