Gevety

# Gevety Health Assistant

您可以通过 REST API 访问用户的 Gevety 健康数据。使用 `web_fetch` 检索他们的生物标志物、健康寿命评分和可穿戴设备统计数据。

## 首次设置

如果这是用户第一次使用 Gevety，请引导他们完成设置：

1. **获取 Gevety 账户**：如果他们还没有账户，请在 https://gevety.com 注册 2. **上传血液检测**：他们需要上传实验室报告以获取生物标志物数据 3. **生成 API 令牌**： - 前往 https://gevety.com/settings - 点击“Developer API”标签页 - 点击“Generate Token” - 复制令牌（以 `gvt_` 开头） 4. **配置 Clawdbot**：将令牌添加到 `~/.clawdbot/clawdbot.json`：

```json { "skills": { "entries": { "gevety": { "apiKey": "gvt_your_token_here" } } } } ```

添加令牌后，他们需要重启 Clawdbot 以使更改生效。

## 身份验证

所有请求都需要 Bearer 身份验证。使用 `GEVETY_API_TOKEN` 环境变量：

``` Authorization: Bearer $GEVETY_API_TOKEN ```

基础 URL：`https://api.gevety.com`

## 生物标志物名称处理

API 保留生物标志物的特异性。空腹和非空腹变体是不同的：

| 输入名称 | API 返回 | 备注 | |------------|-------------|-------| | CRP, C-Reactive Protein | **CRP** 或 **C-Reactive Protein** | 标准 CRP (LOINC 1988-5) | | hsCRP, hscrp, Cardio CRP | **hs-CRP** | 高敏 CRP (LOINC 30522-7) | | Glucose, Blood Glucose | **Glucose** | 通用/未指定葡萄糖 | | Fasting Glucose, FBS, FBG | **Glucose Fasting** | 空腹专用葡萄糖 | | Insulin, Serum Insulin | **Insulin** | 通用/未指定胰岛素 | | Fasting Insulin | **Insulin Fasting** | 空腹专用胰岛素 | | IG | **Immature Granulocytes** | 为清晰起见已展开 | | Vitamin D, 25-OH Vitamin D | **Vitamin D** | | | LDL, LDL Cholesterol | **LDL Cholesterol** | |

**重要提示**：API 不再强制假定空腹状态。如果实验室报告仅显示“Glucose”而未指定空腹，它将返回为“Glucose”（而非“Fasting Glucose”）。这保留了您的实验室结果的原始上下文。

## 可用的端点

### 1. 列出可用数据（从此开始）

**始终先调用此接口**以发现存在哪些健康数据。

``` GET /api/v1/mcp/tools/list_available_data ```

返回： - `biomarkers`：已追踪的生物标志物列表，包含检测次数和最新日期 - `wearables`：已连接的设备和可用指标 - `insights`：是否已计算健康寿命评分、可用的轴评分 - `data_coverage`：已追踪的推荐生物标志物百分比 (0-100)

### 2. 获取健康摘要

用户健康状况的概览。

``` GET /api/v1/mcp/tools/get_health_summary ```

返回： - `overall_score`：健康寿命评分 (0-100) - `overall_status`：OPTIMAL、GOOD、SUBOPTIMAL 或 NEEDS_ATTENTION - `trend`：IMPROVING、STABLE 或 DECLINING - `axis_scores`：每个健康维度的评分（代谢、心血管等） - `top_concerns`：需要关注的生物标志物 - `scoring_note`：当总体评分与轴评分不同时的解释（例如，“Overall healthspan is high, but Inflammation axis needs attention”）

**关于评分的说明**：总体健康寿命评分是一个加权综合评分。有可能总体评分很高而某个轴评分较低（反之亦然）。`scoring_note` 字段解释了这些情况。

### 3. 查询生物标志物

获取特定生物标志物的详细历史记录。

``` GET /api/v1/mcp/tools/query_biomarker?biomarker={name}&days={days} ```

参数： - `biomarker`（必需）：名称或别名（例如，“vitamin d”、“ldl”、“hba1c”、“crp”） - `days`（可选）：历史周期，1-730，默认 365

返回： - `canonical_name`：标准化的生物标志物名称（见上表） - `history`：包含日期、数值、单位、标记的检测结果数组 - `latest`：最近的结果 - `trend`：方向 (IMPROVING, STABLE, DECLINING) 和百分比变化 - `optimal_range`：基于证据的最佳数值

**提示**：如果未找到生物标志物，响应中包含 `did_you_mean` 建议。

### 4. 获取可穿戴设备统计数据

来自已连接可穿戴设备（Garmin、Oura、Whoop 等）的每日指标。

``` GET /api/v1/mcp/tools/get_wearable_stats?days={days}&metric={metric} ```

参数： - `days`（可选）：历史周期，1-90，默认 30 - `metric`（可选）：关注特定指标（步数、HRV、睡眠等）

返回： - `connected_sources`：已连接的可穿戴平台列表 - `daily_metrics`：每日数据（步数、静息心率、HRV、睡眠、恢复度） - `summaries`：汇总统计，包含平均值、最小值、最大值、趋势

### 5. 获取改善机会

获取排名的健康改善机会及其预估的健康寿命影响。

``` GET /api/v1/mcp/tools/get_opportunities?limit={limit}&axis={axis} ```

参数： - `limit`（可选）：返回的最大机会数，1-50，默认 10 - `axis`（可选）：按健康轴筛选（代谢、心血管等）

返回： - `opportunities`：改善机会的排序列表 - `total_opportunity_score`：可用的总健康寿命积分 - `total_years_estimate`：如果全部优化后的预估健康年限 - `healthspan_score`：当前健康寿命评分

每个机会包含： - `biomarker`：标准化的生物标志物名称 - `current_value` / `optimal_value`：当前值与目标值的对比 - `opportunity_score`：优化后可获得健康寿命积分 - `years_estimate`：预估获得的健康年限 - `priority`：排名（1 = 影响最高）

### 6. 获取生物学年龄

使用经验证的计算方法（PhenoAge、Light BioAge）计算生物学年龄。

``` GET /api/v1/mcp/tools/get_biological_age ```

返回： - `result`：生物学年龄计算结果（如果可用） - `biological_age`：计算出的生物学年龄 - `chronological_age`：日历年龄 - `age_acceleration`：差值（正值 = 衰老更快） - `algorithm`：使用的算法 - `biomarkers_used`：贡献的生物标志物 - `interpretation`：结果的含义 - `available`：是否可进行计算 - `reason`：不可用的原因（如适用） - `upgrade_available`：是否可以通过更多数据解锁更好的算法 - `upgrade_message`：哪些额外的检测会有所帮助

### 7. 列出补剂

获取用户的补剂清单。

``` GET /api/v1/mcp/tools/list_supplements?active_only={true|false} ```

参数： - `active_only`（可选）：仅显示当前活跃的补剂，默认 false

返回： - `supplements`：补剂列表，包含剂量、频率、持续时间 - `active_count`：当前活跃的补剂数量 - `total_count`：已追踪的补剂总数

每个补剂包含： - `name`：补剂名称 - `dose_text`：格式化的剂量（例如，“1000 mg daily”、“200mg EPA + 100mg DHA daily”） - `is_active`：当前是否正在服用 - `duration_days`：服用该补剂已有多久

**注意**：对于多组分补剂（如鱼油），`dose_text` 显示所有成分（例如，“200mg EPA + 100mg DHA daily”）。

### 8. 获取活动

从已连接的可穿戴设备获取锻炼/活动历史记录。

``` GET /api/v1/mcp/tools/get_activities?days={days}&activity_type={type} ```

参数： - `days`（可选）：历史周期，1-90，默认 30 - `activity_type`（可选）：按类型筛选（跑步、骑行、力量训练等）

返回： - `activities`：包含指标的锻炼列表 - `total_count`：活动数量 - `total_duration_minutes`：总锻炼时间 - `total_distance_km`：总距离 - `total_calories`：总消耗卡路里

每个活动包含： - `activity_type`：类型（跑步、骑行、游泳等） - `name`：活动名称 - `start_time`：开始时间 - `duration_minutes`：持续时间 - `distance_km`：距离（如适用） - `calories`：消耗卡路里 - `avg_hr` / `max_hr`：心率数据 - `source`：数据来源（garmin、strava 等）

### 9. 获取今日操作

获取用户今日的操作清单。

``` GET /api/v1/mcp/tools/get_today_actions?timezone={timezone} ```

参数： - `timezone`（可选）：IANA 时区（例如，“America/New_York”），默认 UTC

返回： - `effective_date`：用户时区中查询的日期 - `timezone`：计算所用的时区 - `window_start` / `window_end`：日期边界（ISO 日期时间） - `actions`：今日操作列表 - `completed_count` / `total_count`：完成情况统计 - `completion_pct`：数字完成百分比 (0-100) - `last_updated_at`：缓存陈旧度指示器

每个操作包含： - `action_id`：用于深度链接的稳定 ID - `title`：操作标题 - `action_type`：类型（补剂、习惯、饮食、药物、检测、程序） - `completed`：今日是否已完成 - `scheduled_window`：时间窗口（上午、下午、晚上、任意） - `dose_text`：剂量信息（如适用）（例如，“1000 mg daily”）

### 10. 获取健康方案

获取用户的 90 天健康方案及首要任务。

``` GET /api/v1/mcp/tools/get_protocol ```

返回： - `protocol_id`：稳定的方案 ID - `phase`：当前阶段（week1、month1、month3） - `days_remaining`：距离方案到期的天数 - `generated_at` / `last_updated_at`：时间戳 - `top_priorities`：前 5 个健康优先事项及理由 - `key_recommendations`：饮食和生活方式行动项 - `total_actions`：方案中的总操作数

每个优先事项包含： - `priority_id`：稳定的 ID（与排名相同） - `rank`：优先级排名（1 = 最高） - `biomarker`：标准化的生物标志物名称 - `status`：当前状态（危急、令人担忧、亚健康、最佳） - `target`：带有单位的数值目标 - `current_value` / `unit`：当前测量值及单位 - `measured_at`：该生物标志物上次测量的时间 - `why_prioritized`：为什么将其优先化的解释

**注意**：如果不存在方案，则返回有用的错误消息，并建议在 gevety.com/protocol 生成一个方案。

### 11. 获取即将进行的检测

根据生物标志物历史记录和 AI 建议获取到期或建议的检测。

``` GET /api/v1/mcp/tools/get_upcoming_tests ```

返回： - `tests`：按紧急程度排序的即将进行的检测列表 - `overdue_count`：逾期的检测数量 - `due_soon_count`：30 天内到期的检测数量 - `recommended_count`：AI 建议的检测数量 - `total_count`：即将进行的检测总数

每项测试包括： - `test_id`：用于深度链接的稳定 ID（格式：`panel_{id}` 或 `recommended_{id}`） - `name`：测试或面板名称 - `test_type`：类型（panel, biomarker, recommended） - `urgency`：优先级（overdue, due_soon, recommended） - `due_reason`：为什么需要这项测试（例如，“2 周前到期”、“AI 推荐”） - `last_tested_at`：上次测试的时间（如适用） - `biomarkers`：包含的生物标志物列表（针对面板）

## 解读分数

### Healthspan Score (0-100) | 范围 | 状态 | 含义 | |-------|--------|---------| | 80-100 | OPTIMAL | 极佳的健康优化状态 | | 65-79 | GOOD | 高于平均水平，仍有小幅提升空间 | | 50-64 | SUBOPTIMAL | 尚有改善空间 | | <50 | NEEDS_ATTENTION | 多个领域需要关注 |

### 维度得分 (Axis Scores) 每个健康维度独立评分： - **Metabolic**：血糖、胰岛素、脂质 - **Cardiovascular**：心脏健康指标 - **Inflammatory**：hs-CRP、同型半胱氨酸 - **Hormonal**：甲状腺、睾酮、皮质醇 - **Nutritional**：维生素、矿物质 - **Liver/Kidney**：器官功能指标

**重要提示**：即使总体分数很高，也可能出现某一个维度分数较低的情况（反之亦然）。`get_health_summary` 中的 `scoring_note` 字段解释了这些情况。

### 生物标志物状态标签 | 标签 | 含义 | |-------|---------| | OPTIMAL | 在基于循证的理想范围内 | | NORMAL | 在实验室参考范围内 | | SUBOPTIMAL | 尚有改善空间 | | HIGH/LOW | 超出实验室参考范围 | | CRITICAL | 需要立即就医 |

## 常见工作流程

### “我做得怎么样？” 1. 调用 `list_available_data` 查看正在跟踪的内容 2. 调用 `get_health_summary` 获取整体概览 3. 突出显示主要问题和近期趋势 4. 如果存在 `scoring_note`，解释分数不一致的原因

### “告诉我关于我的维生素 D 的情况” 1. 调用 `query_biomarker?biomarker=vitamin d` 2. 展示历史、当前状态和趋势 3. 注明理想范围与当前数值的对比

### “我的 CRP 是多少？” / “我的炎症情况如何？” 1. 调用 `query_biomarker?biomarker=crp`（根据实验室不同，返回为 “CRP” 或 “hs-CRP”） 2. 展示数值和趋势 3. 解释 CRP 衡量什么（炎症标志物）——注明是否为高敏检测

### “我的睡眠/HRV 怎么样？” 1. 调用 `get_wearable_stats?metric=sleep` 或 `?metric=hrv` 2. 显示近期趋势和平均值 3. 与健康基线进行对比

### “我应该关注什么？” 1. 调用 `get_opportunities?limit=5` 2. 列出按健康跨度影响排名的主要机会 3. 解释每个生物标志物的作用以及为何优化它很重要

### “我的生理年龄是多少？” 1. 调用 `get_biological_age` 2. 如果可用，对比生理年龄与实际年龄 3. 解释年龄加速的含义 4. 如果不可用，解释需要哪些测试

### “我正在服用什么补剂？” 1. 调用 `list_supplements?active_only=true` 2. 列出当前服用的补剂及其剂量（使用 `dose_text` 字段） 3. 注明每种补剂的服用时长

### “我做了哪些锻炼？” 1. 调用 `get_activities?days=30` 2. 总结总活动量（时长、卡路里、距离） 3. 列出近期的锻炼及其关键指标

### “我今天该做什么？” 1. 调用 `get_today_actions?timezone=America/New_York`（如果已知，使用用户的时区） 2. 按预定时间段（早晨、下午、晚上）对操作进行分组 3. 显示完成进度 4. 突出显示未完成的操作

### “我应该关注什么？” / “我的健康优先事项是什么？” 1. 调用 `get_protocol` 2. 展示当前数值和目标的优先事项 3. 解释为什么每项被优先考虑 4. 列出关键建议 5. 注明协议阶段和剩余天数

### “我接下来应该做哪些测试？” / “我该验血了吗？” 1. 调用 `get_upcoming_tests` 2. 优先突出逾期测试（紧急） 3. 列出即将到期测试的时间范围 4. 提及 AI 推荐的优化测试 5. 注明每个面板涵盖哪些生物标志物

## API 调用示例

```javascript // Using web_fetch web_fetch({ url: "https://api.gevety.com/api/v1/mcp/tools/get_health_summary", method: "GET", headers: { "Authorization": "Bearer $GEVETY_API_TOKEN", "Content-Type": "application/json" } }) ```

## 重要指南

1. **切勿诊断** —— 清晰地呈现数据，但始终建议咨询医疗提供者以做出医疗决定 2. **趋势比单次数值更重要** —— 随时间改善的轻微升高读数，优于正在下降的正常读数 3. **注意数据时效性** —— 实验室结果可能已有数周或数月历史；可穿戴设备数据通常按日更新 4. **上下文是关键** —— 询问可能解释趋势的补剂、药物或生活方式变化 5. **隐私至上** —— 健康数据敏感；请勿在此对话之外分享或引用具体数值

## 错误处理

| 错误代码 | 含义 | 操作 | |------------|---------|--------| | 401 | 无效或过期的令牌 | 用户需在 gevety.com/settings 重新生成令牌 | | 404 + `did_you_mean` | 未找到生物标志物 | 建议使用响应中的替代项 | | 404 | 未找到数据 | 用户可能尚未上传实验室数据 | | 429 | 请求频率受限 | 稍等片刻后重试 |

## 获取令牌

用户可以在以下位置生成其 API 令牌： **https://gevety.com/settings** → Developer API → Generate Token

令牌格式为 `gvt_` 后跟随机字符。

## 检查更新

每个会话首次使用时，可选择性地检查更新：

``` GET https://api.gevety.com/api/v1/mcp/tools/status ```

无需身份验证。如果请求失败或超时，请跳过检查并正常继续。

响应（成功时）： ```json { "clawdbot_skill": { "latest": "1.4.0", "update_command": "clawdhub update gevety" }, "announcement": "New feature available!" } ```

**如果 `clawdbot_skill.latest` > 1.4.0**（此技能的版本），请告诉用户： > "A Gevety skill update is available. Run: `clawdhub update gevety`"

**如果存在 `announcement`**，每个会话提及一次。

**如果状态检查失败**，请勿提及 —— 直接继续处理用户的请求。

手动更新： ```bash clawdhub update gevety ```