Cadence 是一个本地优先（local-first）的健康上下文引擎，旨在把 WHOOP 和 Apple Health 的数据汇集到一个本地存储中，并通过 MCP 和命令让 Claude 获得关于用户当前睡眠、恢复、压力（strain）和锻炼等真实状态的可用知识，而不是在无信息的情况下工作。
用途与核心定位 Cadence 的核心用途是成为个人健康数据的本地上下文层。它从 WHOOP 和 Apple Health 两个来源拉取数据，统一存入本地 SQLite 文件，并暴露给 Claude 查询。它的目标不是做通用健康仪表盘，而是让 AI 助手在会话开始时就知道用户当前的身体状态，并在此基础上做更贴合实际的建议和关联分析。
数据来源与隐私说明 WHOOP 数据来自 WHOOP 自身的云 API（通过 OAuth），这是无法绕开的。但一旦拉取完成，健康数据只存在于本机：一个位于 ~/.cadence/cadence.db 的本地 SQLite 文件，权限为 0600（仅所有者可访问）。OAuth 令牌存放在 macOS Keychain 中，不会以明文写入磁盘，也不会进入仓库。Cadence 不会将任何数据重新上传或分享给第三方。Apple Health 数据则完全不离开本机——它通过本地文件导入，不涉及网络调用。Claude 通过 MCP 在本地读取数据，同样不会造成数据传输。
Apple Health 与 WHOOP 的接入方式 Apple Health 无需额外设置，完全本地：从 iPhone 的健康 App 导出全部健康数据后导入即可。WHOOP 需要一次性 OAuth 设置：在 developer.whoop.com 注册个人应用，填写隐私政策链接、重定向 URL，并勾选六个数据范围（read:recovery、read:cycles、read:sleep、read:workout、read:profile、read:body_measurement）。Webhooks 留空，因为 Cadence 采用拉取模式（cadence sync）。开发者状态下的应用最多可供 10 个 WHOOP 账号立即使用，个人使用无需审批。之后导出客户端 ID 和密钥（仅显示一次），运行 cadence auth 完成授权，令牌会存入 Keychain。此后 cadence sync 即可自动工作，并会自动处理 refresh token 轮换。
MCP 服务 Cadence 提供 MCP 服务，使 Claude 可以实时查询本地数据，而不仅仅是读取简报。通过 claude mcp add cadence -- cadence mcp 或等价的 stdio-server 配置，即可将 Claude 客户端指向该服务。
健康感知的 AI 会话（v0.2.0） cadence hook 会输出 Claude Code 的 SessionStart hook 载荷，使每天第一次 Claude 会话在开启时就已经知道用户的生理状态——昨晚的睡眠、今天的恢复、近期压力——并在数值需要提醒时附带一行自适应提示（例如恢复低时建议轻量工作而非马拉松式构建）。每天第二次会话默认静默，避免不必要的噪音。Hook 不会阻塞会话，不进行网络调用，只读取本地 SQLite，任何失败路径都选择静默而不是中断会话启动。
个人基线与异常检测（v0.3.0） 所有阈值都是个人化的，而非人群常模。Cadence 会为每个指标（恢复分数、HRV、静息心率、呼吸频率、睡眠时长/效率）建立真实的 30 天滚动均值/标准差，只有当今日数值相对于个人正常水平出现真实统计偏差（|z| >= 1.5）时才会标记。一个重要护栏是：某个指标在积累 14 天以上真实历史之前会被静默省略，而不是用误导性的小样本量展示。异常会通过三种方式呈现：简报/会话 hook 内联显示；若当天首次会话之后出现新的严重偏差（|z| >= 2.5），hook 会再次触发提醒；无人值守同步任务会对严重级别发送 macOS 通知。周报由 cadence digest 生成到可配置目录，并可选择性提交到笔记/日志仓库，邮件发送有意未接入。
身体、代码与 AI 使用量的镜像（v0.4.0） 这是 Cadence 较为独特的部分：它是第一个把 git 提交历史、Claude 使用量和生理数据放在同一个本地关联层中的工具。所有关联都是基于用户自身历史的简单两组均值比较，不做回归或显著性检验包装。少于 14 天真实重叠数据的组别，Cadence 拒绝报告任何结果，并明确标注为“观察性，非因果”。MCP 工具包括 get_developer_rhythm() 和 get_body_code_correlations()。
端上叙述（v0.5.0） cadence digest --narrate 可将结构化周报转成 2-3 段口语化文字，完全在设备端通过 langchain-apple-foundation-models 生成，零云服务、零费用。该功能为可选安装（pip install cadence[narrate]），Cadence 本身不依赖 Apple Intelligence 也能工作。文档如实记录了首次生成时出现的幻觉（模型声称数据不足，而输入中基线其实已充分），并说明修复方式是将叙述置于确定性结构化周报之上，而非替代它。
数据处理与工程细节 两个来源会被规范化为统一的本地 SQLite schema（sleep、recovery、workouts、daily_metrics），每行标注来源。当两个来源覆盖同一事件时，Cadence 不会静默合并成虚假的“规范”记录，而是明确选择并说明：睡眠分期由 WHOOP 优先，恢复/压力仅 WHOOP 提供；步数和其他日常活动由 Apple Health 提供。Apple Health 导出文件可能达 200MB-1GB 以上 XML，代码使用 iterparse 流式处理并主动驱逐已处理元素以控制内存。睡眠记录会被按连续时间段归并为真实会话。WHOOP 刷新令牌每次使用都会轮换，代码会在返回前立即持久化新令牌。文档还记录了若干真实 bug（趋势计算中的边界重叠、测试隔离问题、部分日偏置、WHOOP 日期参数只接受完整 ISO8601 等）及其修复。
适用场景与限制 Cadence 适合希望让 Claude 等 AI 助手在本地、隐私可控的前提下获得个人健康上下文的用户，尤其适合关注恢复、睡眠与工作/编码节奏关联的人。它当前依赖 WHOOP 云 API 获取 WHOOP 数据，Apple Health 需要手动导出导入，令牌存储依赖 macOS Keychain。叙述功能需要 Apple Intelligence，且属于可选。关联分析在数据量不足时会明确不输出结果。
