apple-health-ai-bridge

<div align="center"> <img src="assets/brand/health-bridge-lockup.png" alt="健康桥" width="520"> <p><strong>您的 Apple 健康数据，持续可用于您自己的 AI 代理。</strong></p> <p> <a href="https://healthbridge.chanhyo.dev/install/">安装 iPhone 应用</a> · <a href="docs/setup.md">设置您的桥</a> · <a href="docs/supported-health-data.md">支持的健康数据</a> · <a href="https://healthbridge.chanhyo.dev/">网站</a> </p> </div> --- Apple 健康 AI 桥为您提供从 Apple 健康到您选择的 AI 工具的直接、自托管路径 - 无需通过托管的中间人。iPhone 伴侣持续将您允许的 HealthKit 数据发送到您控制的接收器，接收器通过只读 CLI 和 MCP 接口使数据可用于兼容的代理。 您的健康数据保持在您的控制之下：接收器和数据库运行在您的基础设施上，AI 访问权限仅为只读，不需要托管的继电器或第三方模型。 ## 设置桥 您需要： - 运行 iOS 18 或更高版本的 iPhone； - 一台 macOS 或 Linux 计算机，用于运行接收器和存储私有数据库；原生 Windows 目前不受支持； - 为了持续同步，需要一个稳定的私有 HTTPS 路由，iPhone 可以在离开本地网络时访问；对于明确的仅本地评估，需要一个相同的 LAN 路由，但有以下限制； - 接收器机器上的 MCP 客户端，或用于直接 CLI 访问的终端； - [`uv`](https://docs.astral.sh/uv/) 用于接收器包。 ### 1. 安装 iPhone 应用 在您的 iPhone 上打开 [官方 TestFlight 安装页面](https://healthbridge.chanhyo.dev/install/)，并点击验证的公共邀请。 ### 2. 准备接收器路由 该项目不提供接收器 URL。URL 是 iPhone 访问接收器计算机的私有地址，必须在核心设置创建配对材料之前存在。 - **已经使用 Tailscale：** 使用 [设置指南](docs/setup.md#route-a-already-use-tailscale) 中记录的私有 Tailscale Serve HTTPS 路径。Tailscale 是现有用户的选项，而不是产品要求。 - **代理辅助的私有 HTTPS 进入：** 使用设置指南的代理辅助路径。设置代理必须先检查，然后显示每个提出的 DNS、隧道、代理、防火墙和服务更改，并在应用更改之前等待批准。 - **仅限本地网络：** 作为故意仅限本地的备用方案支持，但当 iPhone 离开该网络时，自动同步停止。 不要复制示例主机名，直接将接收器端口 `8765` 暴露给公共互联网，或发布配对页面。请按照完整的 [接收器设置指南](docs/setup.md) 来生成和验证实际路由。 ### 3. 安装和运行设置 安装当前的签名接收器版本： ```bash uv tool install "git+https://github.com/roian6/apple-health-ai-bridge.git@v1.0.1" ``` 路由特定的指南将 `HEALTH_BRIDGE_RECEIVER_URL` 设置为确切配置的 `/v1/batches` URL。然后运行： ```bash health-bridge setup --receiver-url "$HEALTH_BRIDGE_RECEIVER_URL" ``` 对于故意仅限本地网络的备用方案，请使用相同的实际 LAN URL 和所需的非环回绑定： ```bash health-bridge setup \ --receiver-url "$HEALTH_BRIDGE_RECEIVER_URL" \ --receiver-host 0.0.0.0 \ --receiver-port 8765 ``` `health-bridge setup` 创建私有 SQLite 数据库和一次性配对页面，准备接收器命令，发出规范的同主机 stdio MCP 描述符，验证本地健康桥 MCP 进程，并检测客户端适配器而不修改它们。 成功的本地 MCP 检查并不证明接收器已准备就绪或手机可达性。请将打印的接收器命令放在主机的批准服务管理器下，启动它，从打印的本地 `/health` URL 获取 `{"status":"ok"}`，然后从物理 iPhone 上的确切面向手机的 `/health` URL 获取相同的响应。路由 A 和 B 使用 HTTPS；路由 C 仅在同一受信任的 LAN 上使用 HTTP。 添加客户端会创建另一个可以读取私有健康数据库的进程，因此设置不会自动执行。在选择客户端后，请使用明确的 `--configure-client <name>`。 ### 4. 配对和同步 1. 只有在监督接收器、本地健康检查和物理 iPhone 健康检查都通过后才继续。 2. 在接收器计算机上，在受信任的屏幕上打开生成的配对 HTML。对于无头接收器，请安全地复制该文件到受信任的本地屏幕；请勿发布它或将其放在 Web 服务器上。 3. 使用 iPhone 相机扫描二维码，打开设置链接，并连接伴侣应用。 4. 点击 **允许健康访问** 并查看 Apple 的原生授权表。 5. 启用 **自动同步**。 6. 等待第一次成功的接收器上传，然后询问您的代理有关您的数据。 示例提示： - “显示昨天的锻炼和唤醒日期的睡眠。” - “哪些 Apple 健康指标最近同步了？” - “总结我过去七天的活动，并标记任何源或同步间隙。” ## 支持内容 伴侣请求每个 HealthKit 类型，这些类型都由应用程序实现并且在当前的 iOS 运行时可用。不支持或不可用的类型保持缺失，而不是被伪造。 请参阅版本化的 [支持的健康数据参考](docs/supported-health-data.md)。 ## 代理接口 MCP 服务器是只读的，并暴露了有界、源基工具： - 桥和同步状态； - 支持和当前同步的指标目录； - 时间序列观测； - 锻炼； - 睡眠摘要； - 每日摘要； - 源出处。 它不暴露原始 SQL、令牌材料、光标值或临床建议。 ## 隐私和安全 - HealthKit 访问权限仅为只读。 - 接收器和 SQLite 数据库归用户所有。 - 该项目没有托管的健康数据后端。 - 配对邀请是临时且单次使用的。 - 设备凭证存储在 iOS 密钥链中，并在接收器中以哈希形式存储。 - 日志和代理状态默认省略健康值和凭证。 - 接收器设计用于单个受信任用户，而不是相互不受信任的租户。 请勿将接收器的环回端口或配对页面暴露给公共互联网。对于远离家里的持续同步，请使用现有的私有网络 HTTPS 路由，例如 Tailscale Serve 或代理辅助的私有 HTTPS 进入，经审查的接收器路径。仅限本地访问是一种有限的备用方案。 通过 GitHub 的私有漏洞报告流程，在 [SECURITY.md](SECURITY.md) 中描述的报告漏洞。 公共政策和帮助：[隐私](https://healthbridge.chanhyo.dev/privacy) · [支持](https://healthbridge.chanhyo.dev/support) ### 删除本地桥数据 停止接收器，然后使用默认的干运行检查确切的删除范围： ```bash health-bridge receiver purge --db ~/.local/share/health-bridge/health.sqlite ``` 请在查看列出的数据库和 SQLite 边车后，再使用 `--confirm` 运行相同的命令。确认在接收器仍在使用数据库时被拒绝。这会删除本地桥副本，不会删除 Apple 健康数据。空的私有 `.lifecycle.lock` 和 `.access.lock` 协调文件以及包含零字节墓文件的私有 `.purge-*` 目录可能会保留；它们不包含健康记录。 如果命令返回 `recovery-required`，请不要重启接收器。请查看结构化源、隔离区和截断路径列表；命令故意保留私有隔离区，而不是在不可逆的部分清除后声明回滚。 ## 版本 用户安装被固定到签名的版本标签，而不是移动的 `main` 分支。每个 GitHub 版本都发布确切的标签轮和源存档，以及 SHA-256 校验和、构建出处和将 Python 包、iOS 版本/构建、Git 树和批次模式绑在一起的元数据。当前的接收器版本是 `v1.0.1`，与不变的 iOS 伴侣 `1.0.0 (15)` 兼容。第一个协调的公共版本是 `v1.0.0`。 ## 从源代码构建 TestFlight 是正常的 iPhone 安装路径。贡献者和高级用户可以使用 Xcode 16 或更高版本，通过遵循 [docs/self-build.md](docs/self-build.md) 来构建。 ## 文档 - [设置](docs/setup.md) - [支持的健康数据](docs/supported-health-data.md) - [架构和信任边界](docs/architecture.md) - [品牌指南](docs/brand.md) - [批次合约](docs/reference/batch-v1.md) - [SQLite 模式](docs/reference/sqlite-v1.md) - [构建 iOS 应用](docs/self-build.md) - [贡献想法](docs/contribution-ideas.md) - [支持路由](SUPPORT.md) - [维护者工作流程](docs/maintainer-guide.md) ## 开发 ```bash uv sync --all-extras --dev --locked uv run pytest -q uv run ruff check . uv run basedpyright ``` 合成夹具和烟雾命令是贡献者工具，不是用户入职的一部分。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 Apple 健康 AI 桥是一个独立的开源项目，与 Apple Inc. 无关，也不受其认可或赞助。 ## 许可证 Apache-2.0。请参阅 [LICENSE](LICENSE)。