vitals

<p align="center"> <img src="assets/VitalsIcon.icon/Assets/vitals-trazos-1000.png" alt="Vitals logo" width="150"> </p> # Vitals 自主托管的健康数据管理平台 [](https://github.com/DocStream-Oficial/vitals/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/) [](#tests) **您的数据。您的服务器。您的人工智能。** Vitals 是一个个人恢复/压力/睡眠/身体年龄仪表盘，类似您会为之付费的 WHOOP 或 Google Health，但它运行在您自己的硬件上，读取您已有的可穿戴设备（Google Fit、Oura、WHOOP、Apple HealthKit），并且从不将您的健康数据发送到第三方云。 <p align="center"> <img src="assets/demo/vitals-today-desktop.png" alt="Vitals — 今日选项卡（桌面）" width="68%"> <img src="assets/demo/vitals-today-mobile.png" alt="Vitals — 今日选项卡（移动 PWA）" width="26%"> </p> <p align="center"> <img src="assets/demo/vitals-sleep-mobile.png" alt="睡眠 — 催眠图，阶段，效率" width="31%"> <img src="assets/demo/vitals-trends-mobile.png" alt="趋势 — 周 vs 周，健康跨度节奏" width="31%"> <img src="assets/demo/vitals-coach-mobile.png" alt="AI 助手 — 对话式，在您的硬件上运行" width="31%"> </p> <p align="center">_{睡眠阶段和催眠图 · 周到周的趋势和健康跨度节奏 · 对话式 AI 助手。<br>所有截图均来自演示模式（<code>VITALS_DEMO=1</code>）— 100% 合成数据，无真实用户参与。}</p> --- ## 为什么选择 Vitals 可穿戴设备仪表盘（WHOOP、Oura、Fitbit Premium）是订阅产品：您的恢复、睡眠和 HRV 历史记录存放在别人的服务器上，需要每月付费，并且评分逻辑是一个黑盒。 Vitals 则采取相反的策略： - **自主托管，始终** — Docker Compose 或普通的 Python 虚拟环境，在您控制的设备上（备用 Mac mini、家庭服务器、5 美元的 VPS）。无需订阅。 - **自带 OAuth** — 您创建自己的 Google/Oura/WHOOP 开发人员凭证；Vitals 绝不会通过共享的后端代理您的数据。 - **透明评分** — 恢复、压力、睡眠表现和身体年龄都是您可以阅读的普通 Python 代码。有关确切的公式、权重和 — 同样重要的是 — 它们的诚实限制，请参见 [`docs/ALGORITHMS.md`](docs/ALGORITHMS.md)。 - **AI 原生，通过 MCP** — `vitals_mcp.py` 将您的健康数据公开为 9 个 MCP 工具，以便本地 AI 代理（[OpenClaw](https://openclaw.io)、[Hermes](https://hermes-agent.nousresearch.com)、Claude 或任何支持 MCP 的代理）可以在不离开您的网络的情况下，推理您的恢复趋势、标记早期疾病信号或回答“今天我应该进行高强度训练吗？”无需任何数据离开您的网络。甚至有一个[复制粘贴提示](#零努力设置-只需询问您的代理)，您的代理可以运行它来自我配置。 - **多源，源无关** — 连接 Google Health、Oura、WHOOP 或 Apple HealthKit（或同时连接多个）；评分引擎将所有数据归一化为一个内部模式。 如果您曾经希望您的量化自我数据真正属于**您** — 可检查、可导出并在您控制的基础设施上运行 — 那么这就是它。 --- ## 功能 | 领域 | 功能描述 | |---|---| | **今日** | 恢复环（HRV/RHR/睡眠复合指标）、压力、睡眠分解、HRV/RHR 与滚动基线 | | **趋势** | 7 天/30 天滚动视图的恢复、HRV、睡眠、训练负荷（ACWR） | | **助手** | 对话式 AI 助手（多对话、ChatGPT/Claude 风格）通过您本地的 `claude` CLI — 如果您已经运行 OpenClaw，则无需 API 密钥 | | **日记 + 行为影响** | 每日习惯跟踪器（~33 个习惯：补充剂、酒精、冥想、睡前屏幕时间等）+ 统计引擎，查找哪些习惯**实际上**影响您的恢复/HRV/睡眠 — Spearman 相关性与 Benjamini-Hochberg 校正，而不是凭直觉 | | **叙事报告** | 每周/每月关于发生了什么以及为什么的普通语言摘要 | | **实验室** | 手动血液检测跟踪（~20 个常见生物标志物）带有参考范围和超出范围的标志 | | **身体年龄和健康跨度** | 基于 VO2max 的健身年龄（NTNU/Nes 2011 公式）以及每月的身体年龄与实际年龄趋势 | | **家庭/多个人资料** | 从一个实例跟踪多个个人（家庭、伴侣），每个个人资料数据隔离 | | **推送通知** | ntfy/Telegram 警报用于恢复下降、疾病风险信号、睡眠债务 | | **离线可用 PWA** | 添加到 iOS/Android 的主屏幕；服务工作者缓存外壳 | | **原生 iOS 应用（自带开发账户）** | Capacitor 外壳与原生 HealthKit 插件：Apple Watch HRV、睡眠阶段、VO₂max、心电图 — 由您构建和签名，通过 TestFlight 分发 | | **AI 代理集成（MCP）** | 9 个只读 MCP 工具，用于 OpenClaw / Hermes / Claude — 早晨简报、睡前提醒、来自您自己的代理的主动警报 | | **女性健康模块** | 可选的周期跟踪（阶段、生育窗口、延迟检测、绝经/围绝经信号）— 除非明确启用，否则数据不会暴露 | | **心电图查看器** | 用于从 iOS 配套应用推送的 Apple Watch 心电图波形的隔离查看器 | | **数据导出** | 完整 JSON 或扁平 CSV 导出您自己的历史记录，任何时候 | --- ## 支持的数据源 | 源 | 认证方式 | 备注 | |---|---|---| | **Google Fit / Health Connect** | OAuth 2.0（自带客户端） | Fitbit、Pixel Watch、Garmin 以及同步到 Google Health Connect 的任何设备 | | **Oura** | OAuth 2.0（自带客户端） | Oura Ring v2 API | | **WHOOP** | OAuth 2.0（自带客户端） | WHOOP v2 API — 需要 `offline` 范围以获取刷新令牌 | | **Apple HealthKit** | 推送令牌（`INGEST_TOKEN`） | 配套 iOS 应用在设备上读取 HealthKit 并将数据推送到 `/api/ingest` — 无需云端往返 | 您可以同时连接多个源；同步引擎将它们合并为每个指标的单个每日记录。 --- ## 快速开始 ### Docker（推荐） 无需 Python 设置，无需虚拟环境 — 只有 Docker。 ```bash git clone https://github.com/DocStream-Oficial/vitals.git cd vitals cp .env.example .env # 填写您的凭证（参见下文），或跳过演示模式 docker compose up -d # 打开 http://localhost:8700 ``` 想在连接任何真实凭证之前试用？在**演示模式**下运行它 — 确定性合成数据集（150 天的现实恢复/睡眠/HRV/压力，加上样本日记条目和实验室结果），无需 OAuth，无需 `.env`，无需可穿戴设备： ```bash docker compose run --rm -e VITALS_DEMO=1 -p 8700:8700 vitals # 打开 http://localhost:8700 — 完全填充的仪表盘，无需登录 ``` 在演示模式下，每个写入端点（同步、OAuth 登录、源连接/断开、HealthKit 摄入）都以 `200 {"status": "demo"}` 响应，而不触及真实凭证或 `data/`。您在演示模式下添加的日记/实验室条目将转到一个临时目录，该目录在进程退出时会丢弃 — 您在演示模式下执行的操作不会影响与之一起运行的真实安装。 ### 无 Docker — 单个命令（`install.py`） 更喜欢纯 Python 虚拟环境而非 Docker？`install.py` 是一个跨平台的单个脚本（Windows/Mac/Linux，标准库），它创建虚拟环境、安装依赖项、生成 `.env` 并启动应用 — 无需手动步骤。 ```bash git clone https://github.com/DocStream-Oficial/vitals.git cd vitals python install.py # 打开 http://localhost:8700 ``` 它具有幂等性 — 随时重新运行；它重用现有的 `.venv` 并且从不覆盖现有的 `.env`。以相同的方式尝试演示模式，无需凭证： ```bash python install.py --demo ``` #### 标志 | 标志 | 功能描述 | |---|---| | *(无)* | 交互式向导（所有字段可选，Enter = 默认值/跳过），然后启动应用 | | `--demo` | 设置 `VITALS_DEMO=1`，跳过所有凭证提示，直接进入演示数据集 | | `--no-launch` | 仅执行设置（虚拟环境 + 依赖项 + `.env`）；打印如何手动启动应用，不启动应用 | | `-y`， `--yes` | 非交互式：直接复制 `.env.example`，无提示 — 用于 CI/脚本 | | `--port N` | uvicorn 的端口（默认 `8700`） | | `--help` | 完整用法 | `install.py` 需要 Python 3.9+（与项目其余部分相同的最低版本），并使用您调用它的解释器（`python`、`python3` 或 `py -3` 在 Windows 上）创建虚拟环境 — 无需猜测适用于您平台的正确命令。 ### 手动设置（虚拟环境，无安装程序） 如果您更愿意自己执行步骤： ```bash git clone https://github.com/DocStream-Oficial/vitals.git cd vitals python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp .env.example .env # 填写您的凭证（参见下文） uvicorn main:app --host 127.0.0.1 --port 8700 --reload # 打开 http://localhost:8700 ``` ### Windows 服务（NSSM） 有关持久后台服务的说明，请参阅 `deploy_windows.ps1` 以获取一步一步的 PowerShell 脚本。 需要 Python 3.9+、NSSM 和 Tailscale（用于远程 HTTPS 访问）。 --- ## 设置 Google OAuth（自带凭证） Vitals 使用 Google 的 OAuth 2.0 读取您的健康数据。**每个人都创建自己的 OAuth 客户端** — 没有共享的客户端 ID。 1. 前往 [Google Cloud Console](https://console.cloud.google.com/) → **APIs & Services → Credentials**。 2. 创建一个项目（或使用现有的项目）。 3. 启用 **Fitness API** 和/或 **Health Connect API**。 4. 创建一个 **OAuth 2.0 客户端 ID**（类型：*Web 应用程序*）。 5. 将 `http://localhost:8700/auth/callback` 添加为授权重定向 URI。 - 对于远程访问，请添加 `https://your-box.your-tailnet.ts.net/auth/callback`。 6. 将 `CLIENT_ID` 和 `CLIENT_SECRET` 复制到您的 `.env` 中。 > **测试模式：** 在您的 OAuth 应用处于*测试*状态时，令牌每 7 天过期。仪表盘在发生这种情况时显示一个“重新连接”横幅 — 点击它以一键重新身份验证。发布应用（Google 验证对于个人使用是可选的）以获取永久刷新令牌。 Oura 和 WHOOP 的工作方式类似 — 在它们各自的门户上创建一个开发者应用，并将客户端 ID/密钥放入 `.env`（参见 `.env.example` 获取确切的密钥）。Apple HealthKit 不使用 OAuth；请参见 `docs/IOS-HEALTHKIT.md`。 --- ## 配置（`.env`） ```bash cp .env.example .env ``` 在 `.env.example` 中查看完整的变量列表，包含内联注释（每个源的 OAuth 凭证、配置文件默认值、`INGEST_TOKEN`、通知设置、Claude CLI 路径和 `VITALS_DEMO`）。 ### 使用本地 LLM（Ollama、LM Studio、llama.cpp）进行教练 默认情况下，教练（聊天、标题和叙事报告）会调用您的本地 `claude` CLI — 如果您已经运行 [OpenClaw](https://openclaw.io)，则无需 API 密钥。如果您想在自托管模型上完全离线运行所有内容，请在 `.env` 中设置 `COACH_BACKEND=openai_compat`，并指向任何与 OpenAI 兼容的 `/chat/completions` 端点： ```bash # .env COACH_BACKEND=openai_compat COACH_API_BASE=http://localhost:11434/v1 # Ollama 默认值 COACH_MODEL=llama3.1 # 必须已经拉取/加载 COACH_API_KEY= # 留空用于本地服务器 ``` 这适用于 [Ollama](https://ollama.com)（先运行 `ollama pull llama3.1`）、[LM Studio](https://lmstudio.ai) 的本地服务器或任何使用 OpenAI 完成聊天格式的 `llama.cpp` 服务器。请求是一个标准的 `urllib` POST（无需新的 pip 依赖，无 SDK）— 与 CLI 具有相同的尽力而为的语义：缓慢/无法访问的服务器超时并优雅地回退，它从不阻塞请求或崩溃应用。`COACH_BACKEND` 未设置（或任何未识别的值）保持默认的 `claude_cli` 行为 — 如果您不触摸此设置，则没有任何更改。 ### 仪表盘登录（`DASHBOARD_TOKEN`） 默认情况下，可以访问应用端口的任何人都可以查看您的仪表盘 — 无需登录屏幕。在 `.env` 中设置 `DASHBOARD_TOKEN` 以要求身份验证： ```bash # .env DASHBOARD_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") ``` 然后在 `/login` 处登录一次（设置一个长期有效的 cookie），或在每个请求上发送 `Authorization: Bearer <DASHBOARD_TOKEN>`（适用于 `curl` 或 Grafana）。`/api/ingest` + `/api/ecg`（iOS 应用自己的推送端点）和 `/api/v1/*`（公共只读 API）保留其自己的独立身份验证 — 这仅控制仪表盘本身。完整的详细信息，包括 CSRF 副作用，在 `SECURITY.md` 中。 --- ## 架构/技术栈 - **后端**：FastAPI（Python 3.9+），普通 JS 前端（无构建步骤），作为单个进程提供 — `uvicorn main:app`。 - **持久性**：`data/` 下的平面 JSON 文件（无数据库）。原子写入（`.tmp` + `os.replace`）无处不在；每个域（配置文件、日记、实验室、周期、教练历史）都有自己的文件。多人/多配置文件模式在 `data/users/<uid>/` 下命名空间这些文件。有关原始按源有效载荷如何归一化为每日模式的信息，请参见 [`docs/ALGORITHMS.md`](docs/ALGORITHMS.md)。 - **调度器**：用于每日同步的 APScheduler 后台作业（`.env` 中的 `SYNC_HOUR`），以及在启动时的尽力而为的同步。有关在每次同步（恢复、压力、睡眠性能、身体年龄）运行的评分管道的详细信息，请参见 [`docs/ALGORITHMS.md`](docs/ALGORITHMS.md)。 - **AI 助手**：调用您的本地 `claude` CLI（无需 API 密钥，如果您已经运行 [OpenClaw](https://openclaw.io)）；如果 CLI 无法使用，则会降级为确定性回退叙事。如果 API 密钥可用，[OpenClaw](https://openclaw.io) 会自动使用。 - **MCP 服务器**：`vitals_mcp.py`（单独进程，Python 3.10+`mcp` SDK）将您的数据公开为 MCP 工具，供任何支持 MCP 的代理使用。 - **移动端**：用于原生 HealthKit/ECG 访问的 Capacitor 封装 iOS 应用（`ios/`），通过 `/api/ingest` 与同一 FastAPI 后端通信。 - **交互式 API 文档**：FastAPI 自动在服务器运行时在 [`/docs`](http://localhost:8700/docs) 处生成 OpenAPI 文档 — 每个端点、请求/响应模式和“试用”控制台，均免费。 ## 端点 运行后在 `/docs` 处可获得完整的交互式参考。所有路由的完整列表在 `main.py` 中，以及它们的身份验证模型： - **无** — 没有自己的身份验证；设计为开放（登录页面，静态 PWA 资源）或故意公开。 - **仪表盘** — 通过 `DASHBOARD_TOKEN` 保护，当你设置一个（cookie 或 `Authorization: Bearer`）；如果留空（默认），则完全开放。参见 `SECURITY.md`。 - **摄入令牌** — 需要 `X-Vitals-Token` 头部（`INGEST_TOKEN`），独立于 `DASHBOARD_TOKEN`。 - **API 密钥** — 需要 `Authorization: Bearer vk_...`（你在“更多”→“API”下生成的密钥），独立于 `DASHBOARD_TOKEN`。 | 方法 | 路径 | 描述 | 身份验证 | |--------|------|--------------|------| | GET | `/` | 仪表盘 HTML | 仪表盘 | | GET | `/manifest.webmanifest` | PWA 清单 | 无 | | GET | `/service-worker.js` | PWA 服务工作者 | 无 | | GET | `/api/ingest-token` | 显示当前 `INGEST_TOKEN`（用于配对） | 仪表盘 | | GET | `/api/qr` | 用于配对的 SVG 二维码（在 URL 中嵌入令牌） | 仪表盘 | | GET | `/login` | 仪表盘登录表单 | 无 | | POST | `/login` | 验证 `DASHBOARD_TOKEN`，设置会话 cookie | 无 | | GET | `/api/insights` | 基于规则的洞察卡片 | 仪表盘 | | GET | `/api/coach/suggestions` | 建议的教练问题 | 仪表盘 | | GET | `/api/drivers` | 恢复的统计驱动因素 | 仪表盘 | | GET | `/api/report` | 每周/每月叙述报告 | 仪表盘 | | GET | `/api/data` | 您的健康数据 JSON | 仪表盘 | | GET | `/api/export` | 导出完整数据集（`?fmt=json\|csv`） | 仪表盘 | | POST | `/api/sync` | 触发手动同步（演示模式下为 no-op） | 仪表盘 | | POST | `/api/ingest` | HealthKit 推送摄入（iOS 应用） | 摄入令牌 | | POST | `/api/ecg` | ECG 读取推送摄入（iOS 应用） | 摄入令牌 | | GET | `/api/ecg` | 列出 ECG 读取（无电压） | 仪表盘 | | GET | `/api/ecg/{uuid}` | 完整的 ECG 读取，包括电压 | 仪表盘 | | GET | `/auth/login` | 启动 OAuth 流程（演示模式下禁用） | 仪表盘 | | GET | `/api/profile` | 读取配置文件 | 仪表盘 | | PUT | `/api/profile` | 更新配置文件 | 仪表盘 | | POST | `/api/sources/{name}` | 连接数据源 | 仪表盘 | | DELETE | `/api/sources/{name}` | 断开数据源连接 | 仪表盘 | | GET | `/api/sources` | 列出连接的数据源 | 仪表盘 | | GET | `/api/cycle` | 跟踪周期状态 | 仪表盘 | | POST | `/api/cycle/period` | 记录一个周期 | 仪表盘 | | DELETE | `/api/cycle/period/{start}` | 删除记录的周期 | 仪表盘 | | POST | `/api/cycle/symptom` | 记录一个周期症状 | 仪表盘 | | GET | `/api/journal` | 习惯日记条目 | 仪表盘 | | PUT | `/api/journal/{date}` | 更新日记条目 | 仪表盘 | | POST | `/api/journal/custom` | 添加自定义日记习惯 | 仪表盘 | | GET | `/api/journal/impact` | 行为影响引擎发现 | 仪表盘 | | GET | `/api/journal/dose-response` | 习惯的剂量反应曲线 | 仪表盘 | | GET | `/api/sleep-coach` | 睡眠教练卡片 | 仪表盘 | | GET | `/api/programs` | 教练程序 | 仪表盘 | | GET | `/api/plan` | 活动计划卡片 | 仪表盘 | | POST | `/api/plan` | 启动/更新计划 | 仪表盘 | | DELETE | `/api/plan` | 清除活动计划 | 仪表盘 | | POST | `/api/plan/check` | 标记计划步骤 | 仪表盘 | | GET | `/api/labs` | 血液检查条目 | 仪表盘 | | POST | `/api/labs` | 添加血液检查条目 | 仪表盘 | | POST | `/api/labs/import` | 从 CSV 导入血液检查 | 仪表盘 | | DELETE | `/api/labs/{entry_id}` | 删除血液检查条目 | 仪表盘 | | GET | `/api/healthspan` | 身体年龄与时间趋势 | 仪表盘 | | GET | `/api/coach/conversations` | 列出教练对话 | 仪表盘 | | POST | `/api/coach/conversations` | 启动新的教练对话 | 仪表盘 | | GET | `/api/coach/conversations/{cid}` | 读取教练对话 | 仪表盘 | | DELETE | `/api/coach/conversations/{cid}` | 删除教练对话 | 仪表盘 | | POST | `/api/coach` | 询问教练（聊天） | 仪表盘 | | GET | `/api/coach/history` | 旧版教练历史 | 仪表盘 | | DELETE | `/api/coach/history` | 清除旧版教练历史 | 仪表盘 | | GET | `/api/users` | 列出家庭用户 | 仪表盘 | | POST | `/api/users` | 创建家庭用户 | 仪表盘 | | DELETE | `/api/users/{uid}` | 删除家庭用户 | 仪表盘 | | POST | `/api/keys` | 创建公共只读 API 密钥 | 仪表盘 | | GET | `/api/keys` | 列出您的 API 密钥（仅元数据） | 仪表盘 | | DELETE | `/api/keys/{key_id}` | 撤销 API 密钥 | 仪表盘 | | GET | `/api/v1/data` | 公共只读 API：完整数据集 | API 密钥 | | GET | `/api/v1/insights` | 公共只读 API：洞察卡片 | API 密钥 | | GET | `/auth/callback` | OAuth 回调 — 保存您的令牌 | 仪表盘 | --- ## 公共只读 API 在此基础上构建您自己的数据（与 [wger](https://wger.de)/Open Wearables 相同的模式），无需向第三方集成公开 `INGEST_TOKEN`（HealthKit/ECG 写密钥）。从 **更多 → API**，生成一个 `vk_...` 密钥 — 它只显示 **一次**；保存它，之后无法恢复。 ```bash curl -H "Authorization: Bearer vk_..." https://your-instance.example/api/v1/data curl -H "Authorization: Bearer vk_..." https://your-instance.example/api/v1/insights ``` - 按用户、 可撤销、**只读** 密钥 — 在 `/api/v1/*` 下没有写入端点。 - 仅存储密钥的 SHA-256 哈希值；原始密钥从不存储，创建后无法恢复。 - 缺失、无效或已撤销的密钥 → `401`（从不 `500`）。 - 每个用户最多 10 个活动密钥；从同一部分撤销它们。 --- ## 入门和配置文件 首次启动时，Vitals 会引导您完成一个简短的入门流程，您可以在其中设置语言、单位（公制/英制）和配置文件。您可以在 **更多** 选项卡 → 配置文件中更新这些设置。 --- ## 原生 iOS 应用（Apple Watch / HealthKit）— 自带开发账户 存储库附带一个完整的原生 iOS 同伴应用（`ios/`，Capacitor + WKWebView）：一个薄壳，加载 **您的** 自托管实例，并添加 PWA 无法提供的功能 — **原生 HealthKit 访问**： - 读取约 13 个 HealthKit 指标，包括 Apple Watch 数据：HRV、静息心率、呼吸率、SpO₂、手腕温度、VO₂max、睡眠阶段、锻炼、步数、主动能量。 - 将它们推送到您的实例（`POST /api/ingest`，通过 `X-Vitals-Token` 身份验证）并在应用程序进入前台时自动同步。 - Apple Watch **ECG 波形** 也会推送 — 在仪表盘的 ECG 查看器中可见。 您可以使用自己的 Apple 账户自行构建 — 不分发二进制文件，不通过 App Store 中间人处理您的健康数据： - **免费 Apple ID** → 在您自己的 iPhone 上运行（7 天签名）。 - **付费 Apple 开发者账户**（99 美元/年）→ 通过 **TestFlight** 分发给您自己和家人（约 30 分钟设置）。 逐步指南： [docs/IOS-BETA.md](docs/IOS-BETA.md)（构建 + TestFlight）和 [docs/IOS-HEALTHKIT.md](docs/IOS-HEALTHKIT.md)（Xcode 中的 HealthKit 连接）。 --- ## PWA — 添加到主屏幕 在 Safari 或 Chrome 中打开 `http://localhost:8700`（或您的 HTTPS URL）。点击 **分享 → 添加到主屏幕**（iOS）或安装提示（Android/Chrome）。Vitals 作为全屏、离线功能的应用程序运行，无需浏览器边框。 --- ## 连接您的 AI 代理（OpenClaw / Hermes / 任意 MCP 客户端） 这是 Vitals 停止作为仪表盘并成为基础设施的地方：如果您运行 [OpenClaw](https://openclaw.io)，[Hermes Agent](https://hermes-agent.nousresearch.com)，Claude 或其他任何 MCP 客户端，`vitals_mcp.py` 将您的健康数据转换为 **9 个只读工具**，您的代理可以调用 — 本地运行，无需向第三方发送任何数据。您的代理可以回答 *“今天我应该训练吗？”* 根据您的实际 HRV，早上通过 WhatsApp/Telegram 给您简报，或在您感觉到之前标记一个疾病风险信号。 ```bash # 安装额外依赖（Python 3.10+ 需要 mcp SDK） pip install -r requirements-mcp.txt # 运行 MCP 服务器（stdio 传输 — 您的代理将启动它） python3 vitals_mcp.py ``` 可用工具：`vitals_today`、`vitals_trends`、`vitals_insights`、`vitals_bodyage`、`vitals_morning_brief`、`vitals_bedtime_brief`、`vitals_drivers`、`vitals_cycle_summary`、`vitals_ask_coach`。 ### 零努力设置：只需询问您的代理 复制并粘贴此内容到您的代理（OpenClaw、Hermes、Claude Code — 任何可以运行命令和编辑其自己的 MCP 配置的内容）中，它将自动配置所有内容： ```text 我运行一个自托管的 Vitals 实例（https://github.com/DocStream-Oficial/vitals）。 存储库克隆在 <PATH-TO-REPO> 处，应用程序运行在 <MY-VITALS-URL>。 使用以下命令设置其 MCP 服务器，以便您可以读取我的健康数据： 1. 安装 MCP 额外依赖项：pip install -r <PATH-TO-REPO>/requirements-mcp.txt （需要 Python 3.10+）。 2. 在您的 MCP 配置文件中注册 <PATH-TO-REPO>/vitals_mcp.py 作为一个_stdio MCP 服务器，命名为“vitals”， 然后重新加载您的 MCP 连接。 3. 验证 9 个 vitals_* 工具可用，调用 vitals_today，并给我今天的恢复、睡眠和压力状态。 4. 从现在开始：在我的早晨例行程序中包含 vitals_morning_brief，在晚上发送 vitals_bedtime_brief， 并在我恢复率低于 40% 或 vitals_insights 中出现疾病风险信号时主动提醒我。 ``` 最后一步是有趣的部分 — 一个带有这些工具的计划代理 = 一个主动的健康副驾驶，您的费用为 0 美元/月订阅。 --- ## 测试 ```bash source .venv/bin/activate pip install -r requirements-dev.txt pytest -q ``` 1,600+ 个测试，全部针对 **合成夹具** — 不需要或在存储库中提供实际的健康数据。CI 在每次推送/拉取请求时在 Python 3.9 和 3.12 上运行完整的测试套件（参见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)）。 ```bash python scripts/i18n_audit.py # 验证所有 4 个语言环境（ES/EN/FR/PT）是否同步 ``` --- ## 安全性和发布您自己的分叉 参见 [`SECURITY.md`](SECURITY.md) 以了解如何报告漏洞，以及 [`CONTRIBUTING.md`](CONTRIBUTING.md#before-you-publish) 以了解发布前检查清单（永远不要提交 `.env` 或 `data/`，在公开分叉之前旋转凭证等）。`scripts/preflight_publish.sh` 会自动执行此检查。 --- ## 许可证 MIT © 2026 DocStream. 参见 [LICENSE](LICENSE)。