health-os

health-os

以本地数据为先的个人健康记录，通过 MCP 提供服务。 您的化验结果、诊断、药物、可穿戴设备数据和饮食记录都存储在您自己的 Postgres 中；任何 MCP 客户端——无论运行本地模型还是云端助手——都可以通过受保护的工具读取和更新这些数据。危急值、用药安全规则和筛查 计划均由确定性代码处理，而非由大模型判断。

医疗免责声明。 这不是医疗器械，也不提供医疗建议。 危急值提醒和筛查提醒仅用于提示您联系医生—— 绝非诊断，也绝不能成为延误就医的理由。使用风险由您自行承担。

功能

• 化验结果 — 将 PDF 或照片传给您的 MCP 客户端；模型会提取数值， health-os 会规范化名称（uk/ru/en/拉丁语同义词）和单位，并将检查项目暂存为 待审核。只有经您批准后，数据才会被视为事实。
• 代码实现的安全保障 — 危急值会立即触发提醒（日志、macOS 通知、 可选的 Telegram）；叙述性报告中的危急发现会被标记；对于药物相互作用 问题，会拒绝回答并建议咨询医生／药剂师（只运行确定性检查： 各种产品中的每日对乙酰氨基酚总量、化验前的生物素）；危机工具会返回 固定回复和热线信息，不受模型影响。
• 趋势和分析 — Mann-Kendall 趋势、个人基线和异常、 按年龄限制使用的风险计算器、筛查日历、每周报告、就诊摘要。
• 饮食记录 — 每餐包含 41 种营养素档案、%RDA、缺乏／过量标记和餐食模板。
• 设备 — 导入 Apple Health 导出数据和 Garmin 数据。
• 36 个 MCP 工具 + 服务端说明 — 每次连接时都会向所有客户端发送安全规则； 详见 mcp_server/README.md。

一条命令即可试用

只需 Docker。启动一个临时数据库，其中包含虚构患者的数据——两年的化验结果 （LDL 缓慢上升）、血压、药物、饮食记录，以及一份等待批准的化验项目：

git clone https://github.com/andronaft/health-os && cd health-os
make demo                             # or: cd demo && docker compose up -d --build

将 MCP 客户端指向该服务：

{
  "mcpServers": {
    "health-os-demo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "health-os-demo",
               "-e", "DATABASE_URL=postgresql+psycopg://health:demo@db:5432/health_os",
               "-e", "READONLY_DATABASE_URL=postgresql+psycopg://health_readonly:demo_ro@db:5432/health_os",
               "health-os:local"]
    }
  }
}

询问 “显示我的健康摘要”、“我的 LDL 是否呈上升趋势？”、“有哪些内容待审核？”、 “我在营养方面缺少什么？”。运行 make demo-down 即可全部移除。

安装并使用自己的数据

需要 Docker 和 Python 3.12+。

git clone https://github.com/andronaft/health-os && cd health-os
cp .env.example .env                  # set the passwords
docker compose up -d db               # Postgres 16 + pgvector
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/alembic upgrade head        # schema
.venv/bin/python -m seed.load         # marker catalog, synonyms, units, nutrients
.venv/bin/python -m seed.demo         # optional: a fictional demo patient to play with

然后连接 MCP 客户端——LM Studio、Open WebUI、Ollama CLI 和 Claude 的配置见 mcp_server/README.md。可以试试：“显示我的健康摘要”、 “LDL 趋势”、“本周我在营养方面缺少什么？”。

本地模型： 服务端通过 stdio 使用标准 MCP，因此任何能运行本地模型的 MCP 客户端都可以使用它。迄今已验证：服务端本身搭配官方 MCP Python 客户端 （CI + Docker 演示）。尚未完成与本地模型的端到端验证——详见 #9；欢迎反馈测试结果。

工作原理

### 一项化验结果：从报告到事实

分阶段面板中的每一行最终都会变为 pending — 未经明确批准，任何内容都不会成为事实。目录无法归类的行会被保留，而不是丢弃：

未映射和待处理的行会显示在 list_pending_reviews 和健康摘要的“等待审核”区块中；名称学习完成后，下一次面板导入时会自动映射。

目录	内容
core/	配置、数据库、规范化、服务、去重、健康摘要
mcp_server/	MCP 服务、读写工具
safety/	确定性安全规则和警报发送
analytics/	趋势、基线、计算器、筛查、营养、报告
ingestion/	提取架构、置信度评分、设备导入器、嵌入
migrations/	Alembic 架构
seed/	参考目录 + 演示患者
evals/	红队场景（注入、隐藏的危急值、单位技巧）
scripts/	备份/恢复（restic；install_launchd.sh 会在 macOS 上安排这些任务）、只读角色设置、导入器

隐私 / 本地优先

• 你的数据保留在自己的数据库中。 Postgres 在本地 Docker 中运行；data/ 和 .env 位于 git 之外。health-os 本身不会向任何地方发送数据。
• 哪些数据会离开设备，取决于你连接的 MCP 客户端。 使用本地模型 （LM Studio、Open WebUI + Ollama 等）时，不会有数据离开设备。使用云端助手时，工具 返回的任何内容都会发送给相应服务提供商 — 请选用条款适合医疗数据的服务（不使用你的 数据进行训练，且保留期限为零或较短）。
• 目标是完全本地运行： 使用本地模型进行聊天和提取，使用本地嵌入进行搜索 （已通过 fastembed 支持）。云端客户端仍为可选项。
• 可选的警报渠道（Telegram）只会发送“检查你的健康系统”这类通用文本，不会发送具体数值。
• 加密磁盘（FileVault / LUKS / BitLocker）— 数据库文件静态存储时未加密。
• 切勿在问题、PR 或测试中使用真实医疗数据 — 只能使用合成数据。

测试

make test              # everything (needs Postgres for the integration part)
make test-unit         # pure unit tests — no database needed
make test-integration  # only tests marked `integration`

集成测试绝不会接触正在使用的数据库：每次运行时，tests/conftest.py 都会在同一服务器上删除并重新创建 <POSTGRES_DB>_test（迁移 + 种子数据）。可通过 TEST_DATABASE_URL 覆盖（名称必须以 _test 结尾）。本地没有 Postgres 时会 跳过集成测试；CI 会设置 REQUIRE_DB=1，因此缺少数据库时测试会失败。

开发历程：PROGRESS.md。

许可证

AGPL-3.0-or-later。你可以使用、修改和分叉 health-os；如果分发该软件，或将修改后的版本 作为网络服务运行，则必须根据相同许可证发布源代码。

想在闭源或商业产品中使用它，同时不承担这些义务？作者提供单独的商业许可证 — 可通过 GitHub 联系（@andronaft）。

欢迎贡献 — 参见 CONTRIBUTING.md（其中包含一份简短的 CLA）。