Health by Dr Brad

Brad 博士的健康指南

免费的健康路线图。输入您的测量数据和血液检测结果，即可查看哪些筛查检测该做了，并获取基于证据的建议及其引用来源。访问 https://drstanfield.com/pages/roadmap 即可使用，无需账户。通过连接器 URL https://mcp.drstanfield.com/mcp 将其连接到 Claude 或 ChatGPT。您的记录是一个文件 health-roadmap.json，存储在您自己的 Dropbox、Google Drive 或浏览器中；我们的服务器绝不会保留该文件。

健康指标跟踪与个性化建议，以 Shopify 店面主题扩展和可自托管页面的形式提供。

本地优先。 用户的健康数据存储在其自己的云端（Google Drive、Dropbox、GitHub、WebDAV）或 localStorage 中，作为单个 health-roadmap.json 文件。网站和本地工具绝不会将该文件发送到我们的服务器；位于 mcp.drstanfield.com 的托管连接器会在单次请求期间将其保存在服务器内存中，不会存储任何数据。“已登录”意味着已连接云服务提供商。Fly 后端仅提供少量功能：聊天机器人、化验结果导入提取、A/B 和产品事件、电子邮件提醒、Klaviyo 信息收集，以及托管 MCP 服务。Supabase 仅保存运营数据行，绝不保存健康数值。电子邮件提醒是唯一会让筛查项目名称传到我们这里的场景：该行保存已注册的电子邮件地址、筛查项目标签及其到期日期，不包含其他内容（app/lib/reminder-v2.server.ts）。

三种 Agent 入口

同一个文件，同一条写入路径，三种入口。

1. Widget：店面或可自托管页面中的 React 应用。 通过 RoadmapStore 读取和写入。
2. CLI 和 stdio MCP：tools/get-plan.ts、tools/edit-record.ts 和 tools/mcp-server.ts，在用户自己的机器上针对其自己的文件运行。请参阅 docs/guides/getting-started.md （“一份可连接到任意 AI 的开源健康记录”，中心指南）、 docs/guides/command-line.md 和 docs/guides/connect-claude-desktop.md。
3. 托管 MCP：https://mcp.drstanfield.com/mcp，自 2026-09-02 起运行于 Fly 应用 health-tool-edu 上，通过 Dropbox 和 Google Drive 提供服务。截至 2026-09-07，共有 9 个工具：仅限托管版的 import_documents（US-35）会从 Dropbox 应用文件夹读取实验室文件（Drive 的 drive.file 权限范围无法查看 用户放入的文件）；file_results（US-36）则接收助手从聊天中用户放入的 文件读取的行，因此文件不会到达我们的服务器。在 Dropbox 上，读取操作还会 列出记录中尚未包含的文件夹文件（US-37）。

要响应一次托管调用，服务器会解封助手持有的云凭据，用它打开用户的文件夹， 并在该请求处理期间将记录保存在服务器内存中。服务器不会存储任何数据。（有 一种例外：对于虚构账户，在 OpenAI 或 Anthropic 应用审核通过之前，服务器 会持有审核账户本身的 Dropbox 凭据；US-32 AC38。）不希望如此的用户可以改用 入口 2：tools/mcp-server.ts 在同一文件上运行相同的工具层，完全不经过我们 的服务器 （docs/guides/getting-started.md，中心 指南，以及 docs/guides/connect-claude-desktop.md）。

所有非浏览器写入操作都会经过同一个 SyncManager （packages/health-core/src/sync-manager.ts），它会在发生冲突时合并，并在 写入后验证。CLI 和 stdio MCP 通过 file-adapter.ts 运行它，该适配器会创建 锁文件并保留备份。托管 MCP 则通过 REST 适配器（dropbox-rest.ts、 drive-rest.ts）运行它，由服务提供商自身的条件写入机制完成相同的工作。 请参阅 packages/health-core/README.md。

不会直接修改任何行。更正时会追加一行新记录，并将旧记录标记为 entered-in-error。

两种构建，一份源码

构建	命令	部署位置
Shopify 店面	npm run build:shopify-prod	两个店铺，主题扩展
自托管	npm run build:pages	GitHub Pages，几乎没有后端，使用你自己的密钥

标志：所有 v2 行为由 VITE_LOCAL_FIRST 控制，需要我们服务器的功能由 VITE_SHOPIFY_SURFACE 控制。

“几乎没有后端”是 Pages 构建的准确说法。在那里，记录和聊天都不会经过我们的服务器：记录会直接写入用户自己的云端，聊天则使用用户自己的密钥。只有在用户主动操作时，才会有两个可选请求发送到我们这里。使用 Google 登录会将 OAuth 代码发送到 /api/google-token，该接口会将代码转发给 Google，且不会存储任何内容（widget-src/standalone/google-config.ts）。订阅邮件提醒会将邮箱地址和到期日期发送到 /api/reminders-v2（widget-src/standalone/reminders.ts）。此构建也会进行 Sentry 错误报告（widget-src/standalone/app.tsx 会调用 initSentry），并且在任何内容离开浏览器之前，由 widget-src/src/lib/sentry.ts 清理敏感信息：在 drbradstanfield.github.io 上，Sentry 已启用，环境名称为 standalone，因此页面确实会与 sentry.io 通信。清理方式与店面构建相同：对事件的每个自由文本字段应用共享的 scrubEventText，因此 Pages 错误也会遵循与其他错误相同的规则进行报告。

页面加载的其他内容都来自页面自身。widget-src/standalone/index.html 包含一个模块脚本，页面加载时不会加载第三方脚本；Sentry 已打包其中，hero 图片也随构建一起发布（widget-src/standalone/hero-dr-brad.webp，26 KB），而不是从 cdn.shopify.com 获取，因此加载页面不会让 Shopify 知道任何信息。连接 Google Drive 时，会从 accounts.google.com 加载 Google 登录脚本。云凭据和可选的 Anthropic 密钥会存储在该源的 localStorage 中（hr_anthropic_key、health_roadmap_dropbox_tokens、health_roadmap_gdrive 和 health_roadmap_gdrive_tokens、health_roadmap_github，以及保存 WebDAV 用户名和密码的 health_roadmap_selfhost），该源上运行的任何脚本都可以读取这些信息。/roadmap/ 和 /roadmap/dev/ 属于同一源，因此预览环境会与线上页面共享这些存储内容。

开始使用

git clone <repo-url>
cd roadmap
npm install
cp .env.example .env   # fill in what you need
npm run test:all

需要 Node 22 或更高版本。切勿运行 shopify app dev：开发预览会覆盖生产环境。

测试

npm test          # symlink guard + health-core + server
npm run test:all  # everything, and what CI runs
npx vitest run <path>

部署

CI 是部署途径：.github/workflows/deploy.yml，从 Actions → Deploy → Run workflow 触发。所有凭据都存储在 GitHub 的 production 环境中。手动操作和紧急处理步骤，以及两个应用的 Fly 拆分方式，请参阅 docs/deploy-runbook.md。

自行验证

你不必只听代码怎么说。打开网站，启用 DevTools 网络选项卡的录制功能，然后使用该工具。

• 保存一项指标不会向我们的服务器发送请求。记录文件只由 widget-src/src/storage/ 中的适配器（dropbox.ts、drive.ts、github.ts、webdav.ts、local-storage-adapter.ts）写入，因此数据会写入你自己的 Dropbox、Google Drive、GitHub、WebDAV 服务或 localStorage。我们的服务器上没有任何端点会接收记录并存储。托管连接器是记录会到达我们服务器的唯一途径，而且只有在你连接之后才会发生：它会在服务器内存中读取文件，仅持续一次请求的时间，不会存储其中任何内容。
• 有两种请求会携带健康信息，而且都是由你触发的。上传实验室文档时，会将文档页面内容通过 POST 发送到 /api/lab-import-v2，该端点会将其发送至 Anthropic 的 API 进行提取，返回提取的值，但不会存储这些值。从店铺小组件发送聊天消息时，会通过 POST 将消息、该对话之前的轮次，以及回答所需的健康信息上下文发送到 /api/chat。在这个界面上，服务器会为每个问题存储一行记录：你输入文本的前 500 个字符（其中可能包含你写入的健康详情）、匹配到的文章、分类结果、路由器的原始输出及任何路由器错误、界面名称，以及假名化的会话 ID 和对话 ID。之前的聊天轮次和回复不会存储。记录满 30 天后，每日任务会清空问题文本、路由器的原始输出和错误文本；匹配记录会保留：文章、分类结果和 ID。访客会话记录中保存的是经过哈希处理的地址，而非 IP。
• 博客页面上的聊天气泡和聊天机器人嵌入功能发送的内容少于小组件聊天，但保留的内容更多。两者都会从 localStorage 中读取小组件保存的记录副本，并在每条消息中将其作为聊天上下文发送（widget-src/src/lib/storage.ts 中的 loadGuestInputs()，由 widget-src/src/site-chat.tsx 和 widget-src/src/chatbot-embed.tsx 调用）。该上下文包含你保存的个人资料（性别、身高、出生年份和月份、单位制）；每项测量的最新保存值及其日期；记录在案的药物及其名称和剂量；以及记录在案的每项筛查回答：方法、结果、日期和后续跟进、吸烟史和包年数、PSA 值、关于讨论前列腺癌和子宫内膜癌筛查的回答，以及关于异常出血的回答。你输入但未保存的内容不会包含在内。小组件自身的聊天还会发送以上所有内容、每项测量最多 24 条带日期的数值，以及页面上已输入但尚未保存的内容。这两类数据都未设置 VITE_LOCAL_FIRST，因此服务器会将其作为存储型界面的数据处理：会把你的问题和回复写入 chat_messages，而回复可能会引用一并发送的数值。这些缓存值仍会作为上下文发送；Brad 于 2026-09-10 决定保留这一做法，因为缺少这些信息会降低回答质量。现在，聊天记录也加入相同的 30 天清理流程（app/lib/chat-purge-cron.server.ts）：记录满 30 天后，任务会清空消息文本和对话标题（即问题开头的几个词）。保留下来的是对话的结构，而不是文字：行 ID、角色、时间戳、模型、令牌数量和回退标记。清空内容的轮次读取时会显示为 [removed after 30 days]。Discord 机器人的聊天记录也按相同周期清空，这是于 2026-09-10 决定的：在机器人中输入的问题，与在聊天气泡中输入的问题享有同等隐私保护。YouTube 聊天记录会保留，因为这些轮次属于视频下的公开评论，适用各自的保留政策。
• 两台设备各自编辑时，无需沟通也能合并。如果两台设备在离线时为同一天记录了同一项测量，较新的条目会成为当天的值；另一条则会保留在历史记录中，并标记为输入错误。任何内容都不会被删除。记录文件是信任根：任何能够写入该文件的对象都已能够将其彻底删除，而带有较晚删除记录的文件会在每台设备上胜出。恢复数据依靠的是你的服务提供商提供的版本历史。
• 遥测事件采用封闭的允许列表，事件名称定义在 packages/health-core/src/product-events.ts 中。一个事件包含名称和匿名访客 UUID，服务器会拒绝任何不在列表中的名称。
• 我们调用的其他接口都不会携带任何数值。/api/google-token 会将 OAuth 代码或刷新令牌转发给 Google，不会存储任何内容。/api/reminders-v2 会发送你的提醒计划，其中包括类似 “Colonoscopy” 的标签和到期日期。在店铺中，你无需主动注册：连接云服务提供商就会为你注册，因为该连接即表示同意（widget-src/standalone/reminders.ts 中的 autoEnrolReminders，这是 2026-08-11 确定的默认启用行为）。连接时，你的云账户邮箱地址、标签和日期都会发送给我们。随后发送的计划就绪邮件会告知提醒即将启用，并附带一键关闭开关，此后的每条提醒邮件也都会附带该开关。在 GitHub Pages 版本中，不会自动为你注册：autoEnrolReminders 在 Shopify 界面之外会立即返回，只有需要你提供邮箱地址的开关可以为你注册。无论哪种情况，我们保存的都只有该地址、提醒计划和用于关闭提醒的令牌：没有健康数值、账户或其他信息。可选的计划邮件会发送你输入的地址和同一份提醒计划。
• 你在小组件反馈框中输入的反馈会被存储并通过邮件发送。该路由会接收你的邮箱地址和最多 2000 个字符的自由文本；如果你已登录，还会添加你的 Shopify 客户 ID；随后将记录写入 feedback_submissions，并通过 Resend 将相同内容发送给 Brad（app/routes/api.feedback.ts、app/lib/product-events.server.ts 中的 recordFeedbackSubmission）。没有任何程序会清理这些文本，也没有任何程序会删除该记录，因此你写入其中的健康详情会一直保留。
• 错误会发送至 Sentry，并在离开浏览器之前进行清理（widget-src/src/lib/sentry.ts）：控制台面包屑文本会被替换，fetch 面包屑 URL 会截断为来源地址，记录操作错误会简化为固定消息和封闭的标签集合。sendDefaultPii 从未设置。请了解文本清理的实际范围（packages/health-core/src/sentry-scrub.ts）：它会删除邮箱地址、带单位的数字，以及在约 30 个指标和实验室相关词汇 20 个字符以内的数字；在服务器端，还会丢弃任何超过 200 个字符的额外字段。它无法识别以文字叙述的诊断或姓名，也没有电话号码规则（该防护措施位于连接器的 report_feedback 工具中）。真正起作用的防护在上游：代码会使用固定消息抛出错误，而不是回显所读取的文本。实验室文档提取的解析流程于 2026-09-10 也做了相同调整，因为 JSON 或架构错误会原样引用文档内容。
• 健康文件不会被打包进服务器映像。.gitignore 中的每种健康数据模式也都会在 .dockerignore 中排除，并且有测试确保两者保持一致（tests/dockerignore.test.ts），因此如果添加忽略规则时没有添加相应的排除项，测试套件就会失败。
• 两种版本的计划页脚都会链接到隐私声明（widget-src/src/components/ResultsPanel.tsx），因此只需点击一下，就能从计划页面了解我们如何处理你的数据，而不必在同意页面中费力查找。

后续阅读

• CLAUDE.md：本仓库的工作约定。
• docs/architecture-v2.md：可视化系统图，也是最佳入门指南。
• docs/reference.md：文件清单、数据模型、端点及常见问题档案。
• docs/user-stories.md：每项行为变更都从这里的一则用户故事开始。
• docs/agent-access.md 和 docs/mcp-architecture.md：Agent 约定和 MCP 图。
• docs/guides/：面向用户的指南，首先阅读 getting-started.md：“可连接到任意 AI 的开源健康记录”。
• docs/privacy-connector-addendum.md： AI 连接器的隐私声明草案。