健康数据助手免费版

面向个人用户的健康数据查询助手,通过自然语言与 Apple Health 数据交互，可产出提升工作效率. 适用于需要apple health tool相关能力的开发场景,提供结构化的工作流程和配置指引. 该工具经过深度差异化处理,针对用户反馈和使用痛点进行了优化改进,提升了实用性和可操作性.

概述

本工具帮助个人用户通过自然语言与 Apple Health 数据进行交互。无需复杂配置,只需配合 Transition 同步服务即可在聊天中查询运动记录、心率趋势、活动圆环进度等核心健康数据,让 AI 教练为你解读数据背后的健康信号. 免费版聚焦个人用户的日常查询场景,适合运动爱好者、健身新手以及希望系统了解自身健康指标的人群.

核心能力

能力模块	描述	免费版支持
AI 教练对话	通过自然语言询问健康数据	每日 3 次
运动记录查询	按日期范围检索历史运动	每日 100 次
每日运动推荐 (WOD)	生成结构化训练方案	无需认证
活动圆环进度	查询当日活动达成情况	支持
心率趋势分析	静息心率、运动心率变化	支持
性能指标	VO2 Max、心率区间	基础查询
表现管理图 (PMC)	CTL/ATL/TSB 计算	不支持 (升级 PRO)
多用户聚合分析	团队健康数据对比	不支持 (升级 PRO)

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：个人用户与、Apple、健康数据对话查询、支持运动、活动圆环等基础问、面向个人用户的健、康数据查询助手、通过自然语言与、Health、数据交互、核心能力、教练问答、适用场景、个人健身追踪、日常健康自检、运动习惯养成、差异化、免费版聚焦核心查、询能力、适合单用户日常使、配置简单开箱即用、适用关键词、fitness、workout等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一: 日常运动自检

用户询问最近一周运动情况,助手汇总并给出建议.

bash

# 通过 AI 教练查询
curl -X POST -H "X-API-ref: $TRANSITION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "这周我做了几次运动?平均心率多少?"}' \
  "https://api.transition.fun/api/v1/coach/chat"

场景二: 训练计划生成

无需认证即可获取当日推荐训练.

bash

# 获取 45 分钟跑步训练
curl "https://api.transition.fun/api/v1/wod?sport=run&duration=45"

支持的 sport 参数: run(跑步)、bike(骑行)、swim(游泳)、strength(力量).

场景三: 心率趋势回顾

查询最近一个月的静息心率变化.

bash

curl -X POST -H "X-API-ref: $TRANSITION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "过去一个月静息心率变化趋势如何?"}' \
  "https://api.transition.fun/api/v1/coach/chat"

不适用场景

以下场景健康数据助手免费版不适合处理：

• 实时流数据处理
• 小规模数据手动分析
• 非结构化文本情感分析

触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求.

快速开始

依赖详情

在 iPhone 上下载 Transition 应用,授予 Apple Health 数据访问权限.

Step 2: 生成 API Key

打开应用,进入 Settings > API Keys,点击 Generate New Key 生成密钥.

Step 3: 配置环境变量

bash

export TRANSITION_API_KEY="your_api_key_here"

可将此行加入 ~/.bashrc 或 ~/.zshrc 持久化配置.

Step 4: 验证连通性

bash

# 测试无认证接口
curl -s "https://api.transition.fun/api/v1/wod?sport=run&duration=20"
# ...
# 测试认证接口
curl -s -H "X-API-ref: $TRANSITION_API_KEY" \
  "https://api.transition.fun/api/v1/profile"

示例

基础配置文件

yaml

# ~/.apple-health-tool-free.yaml
api:
  base_url: https://api.transition.fun
  timeout: 30
  retry: 2
# ...
user:
  timezone: Asia/Shanghai
  language: zh-CN
# ...
limits:
  daily_read: 100
  daily_ai_chat: 3

运动查询示例

python

import os
import requests
# ...
API_BASE = "https://api.transition.fun"
API_KEY = os.environ.get("TRANSITION_API_KEY")
# ...
def get_workouts(start_date, end_date):
    """查询指定日期范围内的运动记录"""
    headers = {"X-API-Key": API_KEY}
    params = {"start": start_date, "end": end_date}
    resp = requests.get(
        f"{API_BASE}/api/v1/workouts",
        headers=headers,
        params=params,
        timeout=30,
    )
    return resp.json()
# ...
# 示例: 查询本周运动
workouts = get_workouts("2026-07-13", "2026-07-19")
for w in workouts.get("data", []):
    print(f"{w.get('date')} - {w.get('sport')} - {w.get('duration')}min")

优秀实践

1. 善用自然语言教练

AI 教练掌握你的全部健康数据上下文,直接用自然语言提问比拼装 API 参数更高效.

text

推荐问题示例:
- "我最近的睡眠质量怎么样?"
- "对比上个月和这个月的跑步配速"
- "根据近期训练强度,我需要休息一天吗?"
- "我的 VO2 Max 趋势如何?"

2. 关注疲劳指标

在安排高强度训练前,先检查疲劳状态.

bash

curl -H "X-API-ref: $TRANSITION_API_KEY" \
  "https://api.transition.fun/api/v1/performance/pmc"

当 TSB 低于 -20 时,说明身体处于疲劳状态,建议安排恢复训练.

3. 日期格式统一

所有日期参数使用 YYYY-MM-DD 格式,避免歧义。查询区间最大跨度为 90 天.

已知限制

免费版每日读取接口 100 次、AI 教练 3 次。建议将常用查询结果缓存到本地.

python

import json
from pathlib import Path
from datetime import datetime
# ...
CACHE_FILE = Path.home() / ".apple_health_cache.json"
# ...
def cache_response(key, data):
    cache = json.loads(CACHE_FILE.read_text()) if CACHE_FILE.exists() else {}
    cache[key] = {"data": data, "ts": datetime.now().isoformat()}
    CACHE_FILE.write_text(json.dumps(cache, ensure_ascii=False, indent=2))

常见问题

Q1: API Key 在哪里获取?

在 iPhone 的 Transition 应用中,Settings > API Keys > Generate New Key 生成。Key 只显示一次,请妥善保存.

常见问题(补充)

每日 0 点 UTC 重置。如需更多次数,可升级至 PRO 版本,每日 AI 教练额度提升至 100 次.

Q3: 必须是 iPhone 用户才能用吗?

是的,Apple Health 数据来源于 iOS 设备。Android 用户请考虑其他健康数据源.

Q4: 数据会保存多久?

Transition 会持续同步 Apple Health 数据,免费版保留最近 90 天完整数据,更早的数据仅保留聚合指标.

Q5: 支持哪些运动类型?

跑步、骑行、游泳、力量训练、瑜伽、徒步等 Apple Health 支持的全部运动类型.

依赖说明

运行环境

• Agent 平台: 支持 SKILL.md 规范的任意 AI Agent (Claude Code、Cursor、Codex、Gemini CLI 等)
• 操作系统: Windows / macOS / Linux
• 网络: 需访问 api.transition.fun 域名
• 数据源: 需 iPhone 设备 + Transition 应用同步 Apple Health 数据

第三方依赖

依赖项	类型	是否必需	获取方式
Transition API	在线 API	必需	下载 Transition 应用后生成 API Key
LLM API	推理服务	必需	由 Agent 内置 LLM 提供
curl	命令行工具	可选	系统自带或包管理器安装
Python 3.8+	运行时	可选	python.org 下载,用于脚本化调用
requests 库	Python 库	可选	pip install requests

API Key 配置

bash

# 方式一: 环境变量 (推荐)
export TRANSITION_API_KEY="sk_your_key_here"
# ...
# 方式二: 配置文件
cat > ~/.apple-health.env << 'EOF'
TRANSITION_API_KEY=sk_your_key_here
EOF
# ...
source ~/.apple-health.env

安全提示: 切勿将 API Key 提交到代码仓库,建议加入 .gitignore.

可用性分类

• 分类: MD+exec方法(Markdown 指令 + 命令行执行)
• 说明: 本 Skill 通过自然语言指令驱动 Agent 调用 Transition API,完成 Apple Health 数据查询与分析
• 免费版限制: AI 教练每日 3 次,读取接口每日 100 次,仅支持单用户使用

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

json

{
  "success": true,
  "data": {
    "result": "健康数据助手免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "apple health"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}