cairn

# 凯恩 <p align="center"> <img src="media/cairn-hero.gif" alt="凯恩 — 简要信息读取你的日常，一个标记的实验室在多个领域传播，进展和教练聊天" width="300"> <br> _{简要信息 → 全景分析 → 连接的大脑 → 进展 → 食谱 → 教练聊天 &middot; 使用虚构的演示数据制作} </p> <p align="center"> <a href="https://codespaces.new/zilet/cairn"><img src="https://github.com/codespaces/badge.svg" height="30" alt="在 GitHub Codespaces 中打开"></a> </p> > **只想看看它 - 不需要安装，不需要终端？** 点击上面的按钮。单击即可在浏览器中运行一个真正的凯恩（预加载虚构的演示数据）- 无需设置，无需在您的机器上安装。探索简报、计划和连接的大脑，然后关闭标签页。当您准备在手机上实际使用时，**自行托管**（如下所示）- 它属于您，您的数据保留在您身边。更多的云端一键式选项（Daytona，devcontainer 主机）位于 [`docs/SANDBOX.md`](docs/SANDBOX.md)。 一个自我托管、连接的、**阅读日常的健康操作系统**，用于 **训练、营养和长寿**，带有智能教练循环和随时间增长的记忆。它打开一个宁静的 **简报**，读取您的全景并 *建议* 今天应该是什么样（建议，而不是门槛），将标记的实验室发现传播到它影响的每个领域，运行自适应的营养以实现您的实际目标 - **减重、维持或增重** - 了解您是谁，并将每次教练通话建立在它之上，轻松捕获（餐盘照片、时间-日期频繁、语音或 Apple Health），并在一次显示一个安静的跨领域洞察。它指导您训练的内容 - **举重、跑步或两者的混合** - 逐渐增加保守的坡道 + 逐渐减少到有日期的 **比赛** 或维持无日期的 **待命** 准备目标，并根据您实际跑步的里程数调整下一周。其力量计划 **演变** 随着您的进步（赚取超负荷、减负荷），整个应用程序在您的 **设备本地时钟** 上运行，因此晚上的日志在家里 *和* 出行时都会在正确的一天。 该产品北极星位于 [`docs/VISION.md`](docs/VISION.md)。一个 Node 服务提供： - **PWA** (`/`) - 一个手机优先的应用（带有响应式两列桌面布局）和六个标签页： **今日**（日常阅读 **简报** - 一个宁静的休息/轻松/训练建议，带有覆盖芯片和“为我生成一个会话”启动器，**日类型感知**，因此它读取 *今日 · 跑步*，*今日 · 举重 + 跑步*，或举重日，带有预订的跑步，已经同步翻转为宁静的完成卡和未来一周的展望；通过一键频繁食物、语音输入和可选的早晨签到实现无缝捕获；一个安静的洞察卡；会话后一键自动调节反馈；以及每周统计条、体重快速添加、日期选取器以记录任何过去的一天、设定-设定日志记录，带有预填充 + `N / M` 进展、休息计时器、PR 检测、“+ 添加锻炼”、完成锻炼总结、表单指南 + 智能“如何做”）， **计划**（手动计划编辑器 - 添加/删除/重新排序天和锻炼，每个锻炼的注释和热身组；一个 **耐力** 比赛教练子选项卡，带有比赛倒计时/待命目标横幅、当前阶段（基础 → 建设 → 锐化 → 逐渐减少），以及本周的跑步塑形；以及教练草案/提案/膳食计划流程，带有接受/拒绝 UI，每周的跑步到达可应用的处方）， **进展**（估计 1RM 趋势、体重图表与目标、会话历史、肌肉体积、日历热图、一个 **耐力** 视图，带有每周里程、时间-区域、配速趋势、耐力 PR 和“N of M km 本周”合规线，以及一个 **能量平衡** 视图，带有自适应营养检查）， **聊天**（与您的教练聊天：它立即记录安全的事情并分阶段计划更改为草案）， **我**（个人资料/记忆/健康/生活/ **家庭** 子导航：个人资料，带有自由文本 **关于我**，目标可行性检查和体重、活动和食物笔记记录；一个 **记忆** 视图，以策划教练记住的内容；**健康** - 上传血液检查/ DEXA/其他作为 PDF 或照片进行标记提取，以及一个 **大脑** 视图，带有恢复、最佳区域优先级标记和从您的实验室传播的跨领域指令。处理那些指令的完成/关闭成为反馈记忆：处理的建议保持安静以获得相同的结果，拒绝的建议不会重复，除非标记物发生实质性变化；**生活** - 一个时间线，记录您计划的旅行、伤害和生活事件； **家庭** - 教练计划所围绕的 roster），和 **设置**（代理轮换 + 每周自动教练，**智能富集** 切换，**Apple Health** 通过 iOS 快捷方式连接，数据导出/备份，首次运行注册）。 - **REST API** (`/api/*`)。 - **MCP 服务器** (`/mcp`, 流式 HTTP) - Claude / Codex / Antigravity / Grok 读取和写入所有内容：计划、日志、个人资料、目标、活动、记忆、膳食计划、食物笔记、健康记录和生活背景事件（旅行/伤害）。 - **代理运行器 + 调度器** - 从您的草案中起草训练目标和膳食计划提案。 存储使用 Node 内置的 `node:sqlite`。**需要 Node 24**（其中 `node:sqlite` 未标记）。Docker 镜像捆绑了 Node 24，因此用户无需在主机上安装 Node。 > [!IMPORTANT] > **安全性和运行位置。** 凯恩默认情况下 **没有身份验证** - 它是一个单用户应用，适用于您已经信任的网络，**不是公共互联网**。在您自己的机器、家庭服务器或小型虚拟机上运行它。最简单的设置既私密又可从手机访问： 将主机放在 [Tailscale](https://tailscale.com) （或类似）网络上，并通过其 **MagicDNS** 名称打开它 - 不需要转发端口，不需要管理证书。**永远不要将 `8787` 端口暴露在开放的互联网上。** 如果任何不受信任的设备可以访问它，请设置 `CAIRN_AUTH_TOKEN` 以要求共享令牌，并通过 HTTPS 提供它（Tailscale Serve / 私有反向代理），以便 PWA 可以离线安装。参见 [`SECURITY.md`](SECURITY.md) 和下面的部署方式。 ## 屏幕 <table> <tr> <td width="33%" valign="top"><img src="media/screens/01-brief-viewport.png" alt="简报"><br>_{<b>简报。</b> 已经读取您的恢复和负载 - 一个宁静的休息/轻松/训练 <i>建议</i>，带有单键覆盖。}</td> <td width="33%" valign="top"><img src="media/screens/15-analysis.png" alt="全景健康分析"><br>_{<b>分析。</b> 智能大脑的全景读取 - 什么进展顺利，本周的重点是什么，有什么问题。}</td> <td width="33%" valign="top"><img src="media/screens/04-brain-directives.png" alt="跨领域指令"><br>_{<b>传播。</b> 标记的实验室变成具体的营养/训练/观察指令 - 每个都有其纯语言的解释和引用。}</td> </tr> <tr> <td valign="top"><img src="media/screens/03-brain.png" alt="连接的大脑"><br>_{<b>连接的大脑。</b> 用纯语言显示恢复（无分数）和值得关注的标记，置于 <i>最佳</i> 范围内。}</td> <td valign="top"><img src="media/screens/06-marker-chart.png" alt="最佳区域标记趋势"><br>_{<b>最佳区域趋势。</b> 每个标记都绘制在长寿带上 - 不仅仅是实验室的参考范围，还有趋势的文字描述。}</td> <td valign="top"><img src="media/screens/16-exercise-detail.png" alt="锻炼详情"><br>_{<b>每个锻炼，都有图解。</b> 点击任何举重动作，查看其估计 1RM 趋势、动作提示和历史记录 - 带有生成的演播室插图。}</td> </tr> <tr> <td valign="top"><img src="media/screens/07-progress-1rm.png" alt="力量进展"><br>_{<b>力量。</b> 每个举重的估计 1RM 趋势，以及历史记录、肌肉体积和日历热图。}</td> <td valign="top"><img src="media/screens/08-energy-balance.png" alt="自适应营养"><br>_{<b>自适应营养。</b> 根据您的体重趋势得出支出 - 安全的精瘦、中立的遵守、不责备。}</td> <td valign="top"><img src="media/screens/10-meals.png" alt="目标感知的膳食计划"><br>_{<b>目标感知的膳食。</b> 以蛋白质为锚点的每周计划，由相同的标记实验室塑造（油性鱼和可溶性纤维用于 ApoB，长跑日铁）。}</td> </tr> <tr> <td valign="top"><img src="media/screens/17-recipe.png" alt="食谱详情"><br>_{<b>随需提供的食谱。</b> 任何计划的餐食都会扩展成完整的食谱 - 食材、步骤和提示 - 为该确切的菜肴而写。}</td> <td valign="top"><img src="media/screens/11-chat.png" alt="教练聊天"><br>_{<b>教练聊天。</b> 立即记录简单的事情并分阶段计划更改为草案，您批准后生效。}</td> <td valign="top"><img src="media/screens/13-life.png" alt="生活时间线"><br>_{<b>生活和家庭。</b> 您计划的旅行、伤害和人 - 教练会相应地放松。}</td> </tr> </table> <p align="center"> <img src="media/today.gif" alt="滚动浏览简报和当天的捕获" width="270"> &nbsp;&nbsp; <img src="media/brain.gif" alt="滚动浏览连接的大脑 - 恢复、标记、指令" width="270"> <br> _{简报（左）和连接的大脑（右），从上到下。} </p> _{每个截图都使用一个 <b>虚构</b> 的演示人物 - 没有真实的健康数据。您可以使用 <code>npm&nbsp;run&nbsp;seed:demo</code> 自己填充相同的演示。} ## 快速开始（30 秒） **想运行它吗？** 您不需要源码。镜像已发布到 GHCR（多架构，amd64 + arm64）- 一个命令，无需克隆，无需 Node： ```bash docker run -d --name cairn -p 127.0.0.1:8787:8787 \ -v cairn-data:/data -v cairn-home:/home/app \ --restart unless-stopped ghcr.io/zilet/cairn:latest ``` 打开 **http://localhost:8787** - 您立即会看到简报。两个命名卷保存您的数据（`cairn-data`）和 CLI 登录（`cairn-home`），以便在更新时保留；要更新，请执行 `docker pull ghcr.io/zilet/cairn:latest` 并重新运行命令。添加 `-e TZ=Europe/Belgrade` 以设置您的时区。仅当在私有网络上并且设置了 `CAIRN_AUTH_TOKEN` 时，才将绑定扩展到您的 LAN（例如 `-p 8787:8787`）。 更喜欢 docker-compose 文件（环境变量、环回安全默认值）？ `curl -LO https://github.com/zilet/cairn/releases/latest/download/docker-compose.yml && docker compose up -d`。 **想要源码** - 在本地构建、开发或在 Node 上运行，而不是 Docker？ ```bash git clone https://github.com/zilet/cairn.git cd cairn ./quickstart.sh ``` 脚本检测 Docker（首选，无需在主机上安装 Node）或回落到本地 Node 24，启动凯恩，等待健康并打印 URL。打开 **http://localhost:8787** - 您立即会看到简报。 **首次绘制是真实的**，无需代理即可使用。对于聊天、教练草案和膳食计划，请登录到 **一个** 代理 - CLI 捆绑在镜像中，因此无需安装。最简单的路径：打开 **设置 → 代理** 并点击 **连接** - 一个终端在浏览器中打开并引导您完成该提供者的注册，无需 `docker exec`。 ```bash docker exec -u app -it cairn claude auth login # 或：codex login · agy · grok login （选择一个；-u app 是必需的） ``` 内置的 `stub` 代理会返回一个罐装的演示提案，以离线探索 propose→apply 循环（它不是教练）。完整的详细信息（Grok API 密钥，本地 Node 登录）： [连接您的第一个代理](docs/QUICKSTART.md#connect-your-first-agent). ### 出厂盒 vs. 需要教练代理的内容 凯恩 **启动后立即完全可用**，无需代理和 API 密钥。教练代理添加了基于会话的生成层 - 而应用程序在您设置完毕后仍然有用。 | 出厂盒（无代理） | 需要登录的教练代理 | |---|---| | 简报 - 宁静的休息/轻松/训练建议 | 代理 **聊天** | | 设定-设定日志记录、历史记录、PR、估计 1RM | 教练 **聊天** | | 计划编辑器（添加/删除/重新排序天） | 计划和膳食 **草案** （提出 → 审查 → 应用）| | 体重图表，目标可行性检查 | 健康审查 **叙述** | | 标记提取视图和最佳区域趋势 | 安静的跨领域 **洞察** / 每周阅读 | | 恢复视图，确定性 TDEE / 支出 | 食谱生成，单餐交换 | | 活动、食物笔记、记忆、家庭、生活背景 | 日常日志的背景丰富 | | 耐力统计数据，跑步合规性，比赛倒计时，PR | 每周跑步 **处方** （草案，然后手术应用） | **教练代理** 意味着支持的 CLI 之一 - **Claude Code**、**Codex**、**Antigravity** 或 **Grok** - 安装在主机 **并登录** 您的帐户。没有共享密钥或内置模型：每个提供者都需要其自己的 CLI 和登录（Docker 镜像内置 CLI；您只需登录一次）。内置的 `stub` 代理在没有密钥的情况下练习相同的建议/应用循环，因此您可以探索代理流程后再连接一个真实的代理。 ### 选择运行目标 | 如果您... | 从这里开始 | |---|---| | 只需在您的笔记本电脑上运行（无需克隆） | `docker run … ghcr.io/zilet/cairn:latest` 上述命令 | | 从源码开发 | `./quickstart.sh` | | 保持在家始终在线 | `./scripts/quickstart-rpi.sh` 在树莓派或小型主机盒上 | | 运行在廉价的虚拟机上 | Docker + Tailscale；参见 [`docs/QUICKSTART.md#small-vm-private-online-box`](docs/QUICKSTART.md#small-vm-private-online-box) | | 在云上试用按需持久存储 | [`docs/SANDBOX.md`](docs/SANDBOX.md) | 对于树莓派：`./scripts/quickstart-rpi.sh` 处理 Docker 安装、arm64 检查和低内存注释。要将 Cairn 放在您的手机上，运行 **`./scripts/setup-phone.sh`** - 它检测您的确切私有 `https://…ts.net` URL via Tailscale Serve（仅限 tailnet）并打印 Add-to-Home-Screen 步骤以安装可安装的离线 PWA。 对于临时 **云沙盒**（Daytona / GitHub Codespaces）带有持久存储 - 在需求时启动，空闲时关闭以降低成本 - 见 [`docs/SANDBOX.md`](docs/SANDBOX.md)。`.devcontainer/` 包含，因此“打开云端”开箱即用。 ## 快速链接 | 文档 | 它涵盖的内容 | |---|---| | [`docs/QUICKSTART.md`](docs/QUICKSTART.md) | 30 秒启动、树莓派、虚拟机、Docker、Node、代理设置 | | [`docs/SANDBOX.md`](docs/SANDBOX.md) | 在 Daytona / Codespaces 上运行（按需，持久） | | [`docs/DEPLOYMENT.md`](docs/`docs/DEPLOYMENT.md) | Tailscale，HTTPS PWA，Pi/VM，备份 | | [`docs/OPERATIONS.md`](docs/OPERATIONS.md) | 更新，迁移，恢复 | | [`docs/APPLE_HEALTH.md`](docs/APPLE_HEALTH.md) | iOS 快捷方式 → `/api/health-metrics`（Apple Health / Oura / Whoop） | | [`docs/API.md`](docs/API.md) · [`docs/MCP-TOOLS.md`](docs/MCP-TOOLS.md) | 生成的 REST + MCP 参考（`npm run docs:index`） | | [`docs/VISION.md`](docs/VISION.md) | 产品宪法 | | [`docs/WHY-CAIRN.md`](docs/WHY-CAIRN.md) | 凯恩与其他产品比较（vs MacroFactor，Oura/Garmin，ChatGPT） | | [`CHANGELOG.md`](CHANGELOG.md) | 发布历史 | 凯恩需要代理。对于 **Claude Code**、**Codex** 和 **Antigravity**，这意味着在主机上安装并登录 **的提供者 CLI** - 他们使用他们的订阅 OAuth 登录目录，而不是环境 API 密钥（`claude -p` 和 `codex exec` 忽略 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` 以实现此流程）。只有 **Grok headless** 可靠地使用 API 密钥（`XAI_API_KEY`）。`GEMINI_API_KEY` 用于可选生成的 **艺术作品** - 它不是一条教练路径（凯恩甚至将其从代理子进程环境中剥离）。或选择内置的 **`stub`** 代理在 Settings 中，以离线方式使用无密钥的建议/应用循环。没有代理，草案/教练操作将静默失败。 ## 使用 Docker 运行 Cairn 设计为可以在您已经拥有个人服务的任何地方运行：笔记本电脑、小型家庭服务器、虚拟机、Raspberry Pi 或私人 Tailscale/WireGuard 网络。相同的容器可以在您需要时启动，也可以长时间运行。 **预构建镜像（无需克隆）。** 多架构镜像（amd64 + arm64）会随着每个标记版本发布到 GHCR，因此您可以完全跳过构建过程。最快捷的方式是使用一个 `docker run` 命令，无需源代码，也无需 compose 文件： ```bash docker run -d --name cairn -p 127.0.0.1:8787:8787 \ -v cairn-data:/data -v cairn-home:/home/app \ --restart unless-stopped ghcr.io/zilet/cairn:latest ``` 这会将 Cairn 绑定到环回地址。仅在私有网络上，并且设置了 `CAIRN_AUTH_TOKEN` 时，才将其扩展到您的局域网（例如 `-p 8787:8787`）。 或者，对于一个已经配置了环境变量和环回安全默认值的 compose 文件： ```bash mkdir cairn cd cairn curl -LO https://github.com/zilet/cairn/releases/latest/download/docker-compose.yml docker compose up -d ``` 无论哪种方式，请打开 `http://localhost:8787`。在以后更新时，使用 `docker pull ghcr.io/zilet/cairn:latest` 并重新运行。 **从源代码构建。** 只有当您想要开发或更改代码时才需要此操作 - 它会在本地构建镜像，而不是从远程拉取： ```bash git clone https://github.com/zilet/cairn.git cd cairn docker compose up -d --build ``` 第一次构建会将 coaching CLIs 编入镜像中，需要约 3-6 分钟；后续重建速度很快（BuildKit 会缓存层）。 参见 [`docs/SHARING.md`](docs/SHARING.md) 以了解 GHCR 发布流程和维护人员发布检查清单。 - `cairn-data` 卷 = SQLite 数据库；`cairn-home` 卷 = 所有 CLI 登录。重建永远不会触及两者。 - **默认情况下没有内置身份验证** - 将 Cairn 保留在 localhost 后面、局域网后面、Tailscale/VPN 或另一个受信任的私有网络后面，并且永远不要将端口暴露给公共互联网。如果端口可从环回地址以外的范围访问，请设置 **`CAIRN_AUTH_TOKEN`** （环境变量 / `.env`）以要求在 `/api` 和 `/mcp` 上共享令牌；PWA 会提示一次并存储它。参见 [`SECURITY.md`](SECURITY.md)。 - 容器以非 root 用户运行其主进程。要运行必须在 home 卷中保留登录的单次命令，请传递 `-u app` （参见下面的登录命令）。 - 对于可安装的/离线的 PWA，请在您的私有网络上通过 HTTPS 提供它。纯 HTTP 适用于基本使用，但浏览器只会在安全来源注册服务工作器。 - 参见下面的“Coaching agents”以获取每个提供商的一次登录。 ### 常见的部署方式 - **偶尔使用的本地应用：** 在您的笔记本电脑上运行 `docker compose up -d`，使用 `http://localhost:8787`，然后在完成后停止。 - **始终在线的盒子或虚拟机：** 在任何 Docker 主机上运行发布版的 compose。保持主机私有；如果另一个设备可以访问该端口，请设置 `CAIRN_AUTH_TOKEN`。 - **Tailscale / MagicDNS：** 在加入您 tailnet 的家庭服务器、虚拟机或 Pi 上运行 Cairn，然后使用 tailnet 主机名从您的手机或笔记本电脑打开它。对于可安装的 PWA/离线支持，请在 Tailscale Serve、Caddy、nginx 或另一个私有网络反向代理前面添加 HTTPS。 - **公共云虚拟机：** 不要将 `8787` 直接暴露给公共互联网。将它绑定到 localhost 或私有接口，然后通过 VPN、tailnet、SSH 隧道或身份验证的反向代理访问。 ## Cairn 跟踪的内容 - **您的主要学科：** Cairn 根据您的训练方式进行调整 - 力量/举重、跑步/耐力或两者的混合 - 因此 Brief、计划和教练阅读内容都是针对您实际的目标进行的。在此基础上，可以选择一个可选的 **耐力目标**：一个有日期的 **比赛**（Cairn 为此提供保守的坡道和减量训练）或一个没有日期的 **固定** 准备度目标（“保持 10k 准备度 - 维持，不要达到峰值”）。 - **举重**（精确）：5 天计划，包含每个锻炼的目标、记录的组、估计的 1RM 趋势。这是会被积极优化的部分。 - **跑步和耐力：** 教练为一周的跑步（简单/节奏/间隔/长跑，每个都有距离、持续时间和目标区域）提供处方，您可以批准；然后同步的 Garmin 跑步会与处方进行协调，因此 Today 显示“本周 M 公里中的 N 公里”，采用纯文本和下一个星期根据您实际跑步的里程进行保守调整（如果里程不足 → 保持不变，绝不弥补错过的里程）。每周里程、时间区间、配速趋势和耐力 PR 都记录在 Progress → Endurance 中；VO2max、静息心率和 HRV 作为连接的大脑中的最佳区间标记。 - **个人资料和目标：** 一个中立的示例个人资料随出货 - 请在 Me 标签中用您自己的替换（或首次运行 onboarding）。选择一个 **目标模式** - **减肥/维持/增重** - 数学就会遵循它：维持锚定到您的实际 TDEE（无强制赤字），增重是一个保守的精益盈余，减重测试可行性反对精益安全的速度（<=1 %/周）。**目标检查** 计算 TDEE（Mifflin-St Jeor x 活动因子），标记激进目标，并推荐现实的摄入量/时间表 - 例如，目标是 10 周内减重 20 磅（~2 磅/周），会被标记，推荐的节奏约为 ~1.35 磅/周，持续约 15 周，匹配的摄入量和蛋白质底线。 - **活动**（纯文本）：用自然语言记录跑步或骑行 - “跑了 50 分钟 @ 5:30/km” 或“骑行穿过山丘 2 小时”。Cairn 即时解析类型/持续时间/距离/配速 **（离线）**，然后 - 如果启用了丰富功能 - 后台代理会完善记录并将任何值得注意的持久事实提炼成记忆。教练在训练进展中会考虑心血管负荷。 - **记忆：** 持久的笔记（偏好、约束、见解），每个教练提示都会读取，以便规划不断改进。笔记来自聊天、手动输入或日志的后台丰富；您可以在 **Me → Memory** 视图中管理它们（或通过 `update_memory` / `delete_memory` MCP 工具）。 - **膳食计划：** 目标感知的每周草案，使用精益安全的目标和蛋白质底线（从不 crash 赤字），尊重记忆中的食物偏好。 - **食物笔记**（可选，无需每日记录）：参见下方。 - **健康记录：** 在 Me → Health 中上传血液检查/DEXA/其他文档（PDF 或照片）；后台代理会读取文件，提取结构化标记 + 纯文本摘要，并将值得注意的标志提炼成记忆。不同的实验室对同一分析物的命名方式不同，会自动合并到一个系列中。标记会通过反馈感知指令为教练提供参考（例如，低铁蛋白 → 谨慎增加耐力训练量）。 Done 表示已处理该结果，Dismiss 抑制该建议系列，直到标记发生实质性变化。从 Health → Share，**“打开医生报告”** 打印一份自成体系的临床报告（发现讨论的要点、具有最佳目标和完整日期历史的面板、“Copy for MyChart” twin）。信息性，而不是医疗建议。 - **生活背景：** Trip、injuries 和生活事件（Me → Life）及其日期，教练会**围绕**这些事件进行规划 - 旅行友好的减量周、减量受伤区域、在艰难时期减少训练量。活跃/即将发生的事件会在 Today 显示。 - **Garmin 源数据**（实验性）：将 Garmin Connect 活动和每日恢复指标同步到规范的源表中。Garmin 仍然是一个输入信号 - 手动 Cairn 举重日志仍然是力量进展的真实来源。参见 **[`docs/GARMIN.md`](docs/GARMIN.md)** 以获取本地连接器设置和官方 Garmin API 请求措辞。 ## 聊天驱动的部分（食物照片、自由文本） 容器中的无头 CLIs 处理调度的/触发的 **文本** 优化。需要视觉或宽松的自然语言的输入最好从 **Claude 客户端** （具有视觉 + 记忆）与 Cairn 的 MCP 服务器通信： - 拍一张盘子的照片 -> 在 Claude 中：*“这是午餐，估计一下”* -> Claude 估计并调用 `log_food_note`。无需每日记录；只需偶尔的快照来调整膳食建议。 - *“记录我的骑行：2 小时在山里，感觉很好”* -> `log_activity`。 - *“我减重到 176 了，将目标日期推迟两周”* -> `set_profile`。 ## 教练代理（每个提供商登录一次，然后运行） 没有跨提供商的单一登录。您每个提供商登录一次；`cairn-home` 卷会在重启时保留每个登录。 | 代理 | CLI | 订阅 | 无头 | 聊天流 | 认证目录 | | --- | --- | --- | --- | --- | --- | | `claude` | Claude Code | Anthropic Pro/Max | `claude -p` | ✅ token deltas | `~/.claude` | | `codex` | Codex | ChatGPT | `codex exec` | one-shot | `~/.codex` | | `antigravity` | Antigravity (`agy`) | Google plan | `agy -p` | one-shot | `~/.gemini` | | `grok` | Grok Build | SuperGrok/X Premium+ | `grok -p` | ✅ token deltas | xAI（headless 可能需要 `XAI_API_KEY`） | | `stub` | built-in | none | - | - | offline test agent | > **Google 教练路径：** Google 正在将 **Gemini CLI → Antigravity CLI**；Cairn 使用 `agy`（`~/.gemini` 下认证）。无头流式传输暂不可用 - 聊天会退回到 Codex 和 Antigravity 的一次性流式传输。 CLIs 被编译到发布的镜像中（以及通过 `INSTALL_CLAUDE/CODEX/ANTIGRAVITY/GROK` 构建参数到源代码构建中）。 **登录一次** 到 **一个** 提供商 - 有两种方式： **在应用中（无终端）：** **设置 → 代理 → 连接** 打开浏览器中的实时终端并为您运行该 CLI 的登录（通过服务器生成的 PTY 渲染，因此令牌位于其读取的位置 - 没有 `-u app` 陷阱）。卡片翻转到 **✓ 已连接**，未连接的代理自动从轮换中排除，而不是失败请求。它还显示 CLI 版本 + 当前模型（以及 grok/agy，其模型目录）。 **从终端：** 容器命名为 `cairn`（无论您使用 `docker run` 或 compose）： ```bash docker exec -u app -it cairn claude auth login # Claude Code - 登录（URL + 代码） docker exec -u app -it cairn codex login # Codex - ChatGPT 登录 docker exec -u app -it cairn agy # Antigravity（Google）- 快速粘贴代码，~30s docker exec -u app -it cairn grok login # Grok - 设备登录（或设置 XAI_API_KEY） ``` Grok 无头可以使用 API 密钥而不是登录 - 在 `docker run` 上传递 `-e XAI_API_KEY=…`（重新创建容器以应用）或在 compose 路径中为 `.env` 设置它。然后在 **设置 → 代理** 中启用代理。注意：`claude -p` 在订阅中从单独的 Agent SDK 信用池中扣除，从 2026-06-15 开始；`agy`/`grok` 是 beta 安装程序 - 在您的目标架构上验证它们。 Cairn **不** 代理共享的 API 密钥或共享订阅。容器仅提供运行程序二进制文件；每个用户都使用自己的 Claude / ChatGPT / Google / xAI 帐户登录，并且 `cairn-home` Docker 卷在重启和镜像更新时保留这些身份验证目录。 ### 更新 CLI 工具 镜像在构建时安装最新的启用 CLI。对于长期运行的安装，请从 **设置 → 代理 → 更新 CLI 工具** 或从 shell 更新它们： ```bash docker exec -u app cairn cairn-update-agent-clis ``` 要强制在镜像重建期间安装新的 CLI： ```bash AGENT_CLI_CACHE_BUST=$(date +%s) docker compose build cairn docker compose up -d ``` 自动运行时更新是可选的： ```bash AGENT_CLI_AUTO_UPDATE=1 AGENT_CLI_AUTO_UPDATE_INTERVAL_HOURS=168 docker compose up -d ``` 请在受信任的本地主机或 tailnet 上启用此功能。更新 CLI 会在容器内运行供应商安装脚本；不应为暴露于互联网的部署启用此功能。 ### 代理轮换和设置 打开 **设置** 选项卡（或通过 MCP 使用 `get_settings`/`set_settings`）选择 Cairn 在您未指定代理时的选择方式：**round-robin**（跨订阅均匀轮换），**random**（掷骰子），或 **priority**（按列表顶部优先）。切换各个代理的开启/关闭并重新排序它们 - 禁用未登录的提供商，其他提供商继续工作。任何“自动”草案都会尝试选择的顺序，并在失败时 **fallback**，因此死登录永远不会阻止提案。在 Coach 选项卡中，选择 **⟳ Auto** 使用此轮换，或选择特定的代理。 ### 让它运行 在 **设置 → 每周自动教练** 中启用它并设置日期/时间。每周，它会草拟一个训练提案（通过轮换）并在 Coach 选项卡中等待。永远不会自动应用；您审查并点击 Apply。（如果设置了 `.env` 中的 `COACH_AGENT`/`COACH_DAY`/`COACH_HOUR`，则首次启动时会从中获取这些信息。） ### 将 MCP 连接到 Claude Code ```bash claude mcp add --transport http cairn http://localhost:8787/mcp ``` Cairn 注册了 162 个 MCP 工具，涵盖整个应用程序 - 计划和会话、锻炼、进度和容量、提案/应用循环、个人资料和目标、体重和活动、记忆、膳食计划和配方、食物笔记、健康记录和标记、连接的大脑指令和见解、每日阅读和按需会话建议、恢复和自适应营养、检查和每日指标、家庭聊天、Garmin 同步和生活事件设置。代表性切片： `get_plan`、`log_set`、`get_day_read`、`suggest_session`、`draft_plan_update`、`apply_proposal`、`draft_meal_plan`、`swap_meal_plan`、`get_recovery`、`get_priority_markers`、`list_directives`、`generate_insight`、`log_activity`、`log_food_note`、`set_profile`、`sync_garmin`。使用您的 MCP 客户端的工具列表获取完整、当前的集合（定义在 `src/mcp.ts` 中）。 还有一个 Claude Code 技能包位于 `.claude/skills/cairn/`，它将日常短语（“记录我的骑行”、“更新我的计划”、“我怎么样了”）映射到这些工具。 ## 更新和迁移 ```bash git pull && docker compose up -d --build` ``` schema 迁移在每次启动时自动运行（`runMigrations()` 在 `src/migrate.ts` 中跟踪，通过 `PRAGMA user_version` 跟踪）。没有手动步骤。参见 [docs/OPERATIONS.md](docs/OPERATIONS.md) 以获取完整的更新/备份/恢复/回滚操作手册以及如何添加新的迁移。 ## API 所有应用逻辑都可以通过 `/api` REST 接口访问 - **72 个类别下的 195 个路由**。完整的、始终最新的引用直接来自源代码：[`docs/API.md`](docs/API.md）（运行 `npm run docs:index` 刷新；永远不会手动编辑，因此它不会漂移）。代表性切片：``` Brief & today GET /today-read GET /today-agenda POST /session-suggest GET /learned-timeline Training & plan GET /plan PUT /plan/:day/target POST /sets GET /progress/:exercise GET /program/balance GET /program/progression POST /program/evolve Nutrition & meals GET /nutrition/expenditure GET /nutrition/day POST /coach/mealplan POST /meal-plans/:id/swap POST /meal-plans/:id/recipe Connected brain GET|POST /health-docs GET /markers/priority GET /directives GET /guidelines GET /health/focus GET /health/synthesis GET /health-report Coach & chat GET /proposals POST /proposals/:id/apply POST /chat GET /chat/turns/:id/stream Recovery & life GET /recovery GET|POST /checkins GET|POST /context-events GET|POST /family Ops GET /settings GET /export GET /health ``` 参见 [`docs/API.md`](docs/API.md) 以获取权威的分类列表和 [`docs/MCP-TOOLS.md`](docs/MCP-TOOLS.md) 以获取平行的 MCP 接口（162 个工具）。 ## 笔记 - 辅助举重：负重。体重：null。预估 1RM = Epley 根据最佳组/天。 - 目标数学仅为指导，而不是医疗建议；它故意远离 crash 赤字。 - 默认情况下没有内置身份验证 - 将其保留在受信任的私有网络上（并且 `cairn-home` 保存实时 OAuth 令牌）。如果端口可从环回地址以外的范围访问，请设置 `CAIRN_AUTH_TOKEN` 以控制 `/api` 和 `/mcp`。参见 [`SECURITY.md`](SECURITY.md)。 ## 贡献和许可 欢迎贡献 - 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)（Node 24、thin-adapter 规则、迁移 + service-worker 约定）和 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。在 [MIT](LICENSE) 下许可。 ## 技术栈 Node 24 + TypeScript - Express - node:sqlite - @modelcontextprotocol/sdk - vanilla PWA - Docker。