健康数据助手 (专业版)

概述

专业版面向健身工作室、运动队、企业健康关怀项目等组织场景,在免费版核心查询能力之上,扩展多用户聚合分析、PMC 疲劳模型深度计算、团队报告生成、批量数据导出等企业级能力。支持多租户数据隔离,可同时管理数百名成员的健康数据,并提供优先技术支持与 SLA 保障。

专业版与免费版数据格式完全兼容,个人用户从免费版升级后历史数据无缝衔接。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 按照skill规范执行核心功能执行操作,遵循单一意图原则。 输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

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

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。 输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

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

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。 输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：企业级健康数据分、析平台、支持多用户聚合、团队报告与批量导、面向企业、健身工作室与专业、运动队的健康数据、分析平台、核心能力、团队健康报告、批量数据导出、适用场景、健身工作室会员管、运动队训练监控、企业员工健康关怀、保险精算数据采集、差异化、专业版支持多租户、批量操作、与免费版数据格式、完全兼容、适用关键词、健康数据分析、运动队管理、健身工作室等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一: 健身工作室会员管理

为工作室所有会员建立健康档案,自动跟踪训练进展并生成月度报告。

import os
import requests
from datetime import datetime, timedelta

API_BASE = "https://api.transition.fun"
ADMIN_KEY = os.environ["TRANSITION_ADMIN_KEY"]

class StudioManager:
    def __init__(self, admin_key):
        self.headers = {"X-API-Key": admin_key, "X-Admin-Scope": "all"}

    def list_members(self):
        """列出全部会员"""
        resp = requests.get(
            f"{API_BASE}/api/v1/admin/members",
            headers=self.headers,
            timeout=30,
        )
        return resp.json().get("members", [])

    def batch_pmc(self, member_ids):
        """批量获取 PMC 疲劳指标"""
        results = []
        for mid in member_ids:
            resp = requests.get(
                f"{API_BASE}/api/v1/performance/pmc",
                headers={**self.headers, "X-Member-Id": mid},
                timeout=30,
            )
            results.append({"member_id": mid, "pmc": resp.json()})
        return results

    def flag_fatigued(self, threshold=-20):
        """识别疲劳会员 (TSB 低于阈值)"""
        members = self.list_members()
        pmc_data = self.batch_pmc([m["id"] for m in members])
        return [
            {"member": m, "tsb": p["pmc"].get("tsb")}
            for m, p in zip(members, pmc_data)
            if p["pmc"].get("tsb", 0) < threshold
        ]

manager = StudioManager(ADMIN_KEY)
fatigued = manager.flag_fatigued()
for f in fatigued:
    print(f"提醒: {f['member']['name']} TSB={f['tsb']}, 建议安排恢复训练")

场景二: 运动队训练监控

教练实时监控全队训练负荷,避免过度训练导致伤病。

def team_training_load(team_id, date_range):
    """获取队伍训练负荷"""
    resp = requests.get(
        f"{API_BASE}/api/v1/admin/teams/{team_id}/load",
        headers=manager.headers,
        params={"start": date_range[0], "end": date_range[1]},
        timeout=60,
    )
    return resp.json()

# 示例
# {
#   "team_id": "t_001",
#   "period": "2026-07-01 to 2026-07-15",
#   "avg_ctl": 65.2,
#   "avg_atl": 78.4,
#   "avg_tsb": -13.2,
#   "athletes_at_risk": 3,
#   "recommendation": "降低下周训练强度 15%"
# }

场景三: 企业员工健康关怀

为 HR 部门生成脱敏的团队健康报告,关注整体趋势而非个体数据。

def generate_hr_report(department, quarter):
    """生成部门季度健康报告"""
    payload = {
        "department": department,
        "quarter": quarter,
        "anonymize": True,
        "metrics": ["avg_steps", "avg_sleep_hours", "activity_ring_completion"],
        "format": "pdf",
        "template": "corporate_wellness_q",
    }
    resp = requests.post(
        f"{API_BASE}/api/v1/admin/reports",
        headers=manager.headers,
        json=payload,
        timeout=120,
    )
    return resp.json()

# 报告包含:
# - 部门整体活动圆环完成率趋势
# - 平均步数、睡眠时长对比
# - 高风险人群预警 (匿名)
# - 健康促进活动建议

不适用场景

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

• 需要100%确定性的关键决策
• 医疗诊断
• 法律判决

触发条件

需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于非本工具能力范围的需求。

快速开始

Step 1: 申请专业版账户

联系销售团队开通专业版账户,获取管理员 API Key 与租户 ID。

Step 2: 配置管理员凭证

export TRANSITION_ADMIN_KEY="sk_live_admin_xxx"
export TRANSITION_ORG_ID="org_your_id"
export TRANSITION_EDITION="pro"

Step 3: 导入会员数据

# 批量导入会员 (CSV 格式)
curl -X POST -H "X-API-Key: $TRANSITION_ADMIN_KEY" 
  -H "Content-Type: multipart/form-data" 
  -F "file=@members.csv" 
  "https://api.transition.fun/api/v1/admin/members/import"

CSV 文件格式:

member_id,name,email,join_date,plan
m001,张三,zhangsan@example.com,2026-01-15,premium
m002,李四,lisi@example.com,2026-02-01,basic

Step 4: 验证多租户隔离

# 切换不同租户上下文
curl -H "X-API-Key: $TRANSITION_ADMIN_KEY" 
  -H "X-Org-Id: studio_a" 
  "https://api.transition.fun/api/v1/admin/members"

curl -H "X-API-Key: $TRANSITION_ADMIN_KEY" 
  -H "X-Org-Id: studio_b" 
  "https://api.transition.fun/api/v1/admin/members"

命令参数说明

• -API-Key: 命令参数,用于指定操作选项
• -Member-Id: 命令参数,用于指定操作选项
• -Admin-Scope: 命令参数,用于指定操作选项
• -F: 命令参数,用于指定操作选项
• -X: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项
• -Type: 命令参数,用于指定操作选项

配置示例

企业级配置

# /etc/apple-health-tool/pro.yaml
edition: pro
api:
  base_url: https://api.transition.fun
  admin_key: ${TRANSITION_ADMIN_KEY}
  org_id: ${TRANSITION_ORG_ID}
  timeout: 60
  retry: 5
  rate_limit:
    requests_per_minute: 200
    burst: 50

multi_org:
  enabled: true
  isolation: strict
  audit_log: true
  audit_path: /var/log/apple-health-audit/

reports:
  templates_dir: /etc/apple-health-tool/templates/
  output_dir: /var/log/apple-health-reports/
  formats: [pdf, csv, xlsx]
  schedule:
    weekly_summary: "0 8 * * 1"
    monthly_report: "0 9 1 * *"

notifications:
  fatigued_member:
    enabled: true
    tsb_threshold: -20
    channel: webhook
    webhook_url: ${SLACK_WEBHOOK_URL}

自定义报告模板

from jinja2 import Template

TEMPLATE = Template("""
# {{ team_name }} 周度训练报告

## 概览
- 报告周期: {{ period }}
- 参与人数: {{ member_count }}
- 平均 CTL: {{ avg_ctl }}
- 平均 TSB: {{ avg_tsb }}

## 风险预警
{% for m in at_risk_members %}
- {{ m.name }}: TSB={{ m.tsb }} ({{ m.risk_level }})
{% endfor %}

## 建议
{{ recommendation }}
""")

def render_report(data):
    return TEMPLATE.render(**data)

最佳实践

1. 多租户数据隔离

为不同业务线、工作室或部门配置独立租户,确保数据互不干扰。

def with_org(org_id, func):
    """租户上下文装饰器"""
    def wrapper(*args, **kwargs):
        prev_value = os.environ.get("TRANSITION_ORG_ID")
        os.environ["TRANSITION_ORG_ID"] = org_id
        try:
            return func(*args, **kwargs)
        finally:
            if prev_value:
                os.environ["TRANSITION_ORG_ID"] = prev_value
            else:
                os.environ.pop("TRANSITION_ORG_ID", None)
    return wrapper

2. 批量操作幂等性

批量导入、更新操作使用幂等键,避免重试导致数据重复。

import uuid

def batch_update(members):
    """幂等批量更新"""
    batch_id = str(uuid.uuid4())
    payload = {
        "batch_id": batch_id,
        "members": members,
    }
    resp = requests.post(
        f"{API_BASE}/api/v1/admin/members/batch",
        headers=manager.headers,
        json=payload,
        timeout=120,
    )
    return resp.json()

3. 异步报告生成

大型报告生成采用异步任务,避免阻塞主流程。

import time

def submit_report_job(template, params):
    """提交异步报告任务"""
    resp = requests.post(
        f"{API_BASE}/api/v1/admin/reports/async",
        headers=manager.headers,
        json={"template": template, "params": params},
        timeout=30,
    )
    return resp.json()["job_id"]

def poll_job(job_id, interval=10, max_wait=600):
    """轮询任务状态"""
    elapsed = 0
    while elapsed < max_wait:
        resp = requests.get(
            f"{API_BASE}/api/v1/admin/jobs/{job_id}",
            headers=manager.headers,
            timeout=30,
        )
        status = resp.json().get("status")
        if status == "completed":
            return resp.json()
        elif status == "failed":
            raise RuntimeError(resp.json().get("error"))
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f"Job {job_id} timeout")

4. 审计日志留存

启用审计日志,记录所有敏感操作,满足合规要求。

# 查询审计日志
curl -H "X-API-Key: $TRANSITION_ADMIN_KEY" 
  "https://api.transition.fun/api/v1/admin/audit?start=2026-07-01&end=2026-07-31"

常见问题

Q1: 专业版与免费版数据是否互通?

是的,专业版完全兼容免费版的数据格式与 API 响应结构。个人用户从免费版升级后,历史数据无缝衔接,无需迁移。

Q2: 多租户隔离如何实现?

通过 X-Org-Id 请求头区分租户上下文,服务端在数据访问层强制过滤,确保租户间数据物理隔离。审计日志记录每次跨租户访问。

Q3: 团队报告支持哪些格式?

支持 PDF (用于汇报)、CSV (用于数据分析)、XLSX (用于 Excel 二次加工)、JSON (用于程序对接)。支持自定义模板。

Q4: SLA 如何保障?

专业版承诺 99.5% 月度可用性。如未达成,按服务等级协议进行费用补偿。提供 7x24 优先工单支持。

已知限制

单次批量操作最多 500 个对象,超出请分批提交。异步任务无数量上限,但单个任务最长执行 30 分钟。

Q6: 数据合规性如何保证?

支持数据加密传输 (TLS 1.3)、加密存储 (AES-256)。可配置数据保留期、自动清理策略,满足 GDPR、个人信息保护法等合规要求。

依赖说明

运行环境

• Agent 平台: 支持 SKILL.md 规范的任意 AI Agent (Claude Code、Cursor、Codex、Gemini CLI 等)
• 操作系统: Windows / macOS / Linux (生产环境推荐 Linux)
• 网络: 需稳定访问 api.transition.fun,建议配置出口 IP 白名单
• 数据源: 需 iPhone 设备 + Transition 应用同步 Apple Health 数据
• Python: 3.9+ (用于脚本化批量操作)

依赖详情

API Key 配置

# 专业版环境变量配置
export TRANSITION_ADMIN_KEY="sk_live_admin_xxx"
export TRANSITION_ORG_ID="org_your_id"
export TRANSITION_EDITION="pro"

# 可选: Webhook 通知
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/xxx"

# 可选: 数据库审计日志存储 (使用兼容数据库)
export AUDIT_DB_URL="db://user:pass@host:5432/audit"

可用性分类

• 分类: MD+EXEC (Markdown 指令 + 命令行执行)
• 说明: 本 Skill 面向企业与组织用户,通过自然语言指令驱动 Agent 调用 Transition Pro API,完成多用户健康数据聚合分析、团队报告生成、批量数据操作
• 专业版特性: 多租户隔离、PMC 深度计算、批量导出、自定义模板、优先技术支持、SLA 保障
• 兼容性: 与免费版数据格式完全兼容,支持平滑升级

错误处理

示例

基本用法

输入：用户提供操作指令和必要参数

输出：返回执行结果,包含操作状态和输出数据

用户: 执行核心功能
Skill: 正在执行核心功能...
Skill: 执行完成,结果如下: 操作成功