AIm Workout Journal

AIm 训练日志

一款由 AI 助手记录的训练追踪器。AIm 是一个 MCP 服务，加上一款移动版 Web 应用（PWA）：你可以用自己的话在 Claude 或 ChatGPT 中描述一次训练，助手通过 MCP 记录下来，应用会展示训练计划、历史记录、个人纪录、估算的 1RM 和各肌群负荷。服务会将你的目标、伤病情况和已记录的重量作为数据提供给助手，让它根据你的训练情况制定计划，而不是给出泛泛的建议。

访问 aim-journal.com。免费使用，并且在你已经付费订阅的 AI 服务中运行，无需再订阅另一个服务。指南： 通过 MCP 连接训练追踪器， AI 私人教练， 1RM 计算器。

工作原理

有两种接入方式，使用同一主机，且都会解析为相同的 user_id：

https://<app>/mcp                OAuth 2.1 — add as a connector, approve in the browser
https://<app>/{token}            mobile web app / installable PWA
https://<app>/{token}/mcp        the original connector address, still supported
https://<app>/{token}/api/*      read only JSON the UI consumes

OAuth 是连接器目前使用的方式。服务是一个 OAuth 2.1 资源服务器：未经身份验证的调用会收到一个携带 RFC 9728 受保护资源元数据的 401 响应；客户端会从中发现授权服务器，动态注册自身，而用户则在此应用提供的同意页面上批准授权。Supabase Auth 是授权服务器，因此这里不会存储授权码或访问令牌；访问令牌的 sub 会通过 users.supabase_user_id 映射到账户。无需手动粘贴任何秘密信息。

URL 令牌出现得更早，但仍然可用，因此 OAuth 上线后，用户收件箱中已有的链接仍能正常使用。令牌解析中间件会将路径开头的片段映射到用户，并按 user_id 限定每个查询的范围；OAuth 路径则会从经过验证的令牌中设置相同的上下文变量。两种入口，一套范围限定规则。

MCP 服务提供的功能

通过无状态可流式传输的 HTTP（FastMCP）提供 20 个工具：

• 记录：log_session、update_session、update_set、delete_session、import_document（粘贴其他追踪器的导出内容，或笔记本页面的照片）。
• 读取：get_sessions、get_session、get_stats（训练量、进展、通过 Epley 公式估算的 1RM）、get_program、get_goals、get_body_metrics。
• 目录：search_exercise_pool（包含插图的精选全局训练动作库）、list_exercises、upsert_exercise。
• 训练指导：get_coaching_context 是其中重要的工具。它仅返回数据：针对当前任务（下一次训练、新训练计划、每周回顾），提供该用户的目标、经验、器材、伤病情况（以及会对其造成负荷的动作模式）、近期工作重量、符合目标的计划范围和信息收集状态，让助手依据数据制定计划，而非凭空猜测。助手如何使用这些数据，记录在服务的 MCP 指令中。review_program_draft、update_coach_profile、upsert_goal、log_coach_event、log_body_metric 用于保持这些上下文信息为最新状态。

仓库结构

api/index.py      Vercel entrypoint (must stay at repo root, see below). Imports backend/src.
requirements.txt  Vercel's Python build reads this (must also stay at repo root).
backend/          Python package, tests, scripts, DB migrations.
web/              Vite + React SPA (own package.json, own dev server) and the static guide pages.

api/index.py 和 requirements.txt 不可移动：Vercel 的零配置 Python 构建器只会自动检测根目录下 api/ 中的函数，并且只会为这些函数安装根目录下的 requirements.txt。backend/ 中的其他所有内容（pyproject.toml、uv.lock、tests、scripts、supabase/）都会通过 .vercelignore 从 Vercel 构建中排除，因此 Vercel 会将该仓库视为一个静态 SPA 加一个 Python 函数。

开始阅读前，有一点需要了解：部分代码注释会按路径引用内部规划文档，例如 docs/COACHING_PLAN.md、docs/TEST_CASES.md 或 docs/DEPLOYMENT.md。这些是未在此处发布的产品和研究笔记，因此这些路径无法访问。代码并不依赖这些文档；它们只是决策依据的出处，而非依赖项。构建、测试和运行本仓库内容所需的一切都在此 README 中。

技术栈

• 后端（backend/）：Python 3.12、FastMCP（无状态 HTTP）、psycopg3、Supabase Postgres （事务池化器）。MCP 和读取 API 位于 backend/src/workout_storage/，由 api/index.py 提供服务。
• 前端（web/）：Vite、React、Tailwind v4、shadcn/ui、recharts、React Query、 vite-plugin-pwa。数据层位于 web/src/app/lib/（令牌到 API，再到适配器和钩子）。web/guides/ 下的指南页面会在构建时生成为静态 HTML，不会打包。
• 托管：一个 Vercel 项目。vercel.json 将 mcp、api 和 cron 路由到函数，其他所有内容都路由到 SPA。

前端开发

cd web
npm install
echo 'VITE_API_ORIGIN=https://workout-storage.vercel.app' > .env.local  # dev against prod API
npm run dev              # http://localhost:5173/{token}
npm run test             # vitest: pure function + component tests
npx playwright install chromium   # one time, before the first test:e2e run
npm run test:e2e         # Playwright, against /demo (no backend needed)

后端开发

cd backend
uv sync --extra dev           # install deps
cp ../.env.example ../.env     # fill DATABASE_URL etc. (kept at repo root, shared by all tooling)
uv run pytest                  # unit + integration + e2e
uv run ruff check . && uv run mypy .

创建用户（打印可在浏览器中打开并粘贴到助手中的令牌）：

cd backend
uv run python scripts/create_user.py --name "Alex"

自行运行

这里包含所需的一切，但这是托管服务的源码，而非开箱即用的自托管套件：你需要提供一个 Supabase 项目（迁移文件位于 backend/supabase/migrations/）、一个 Vercel 项目，以及 .env.example 中列出的环境变量。分析、电子邮件和备份集成均为可选项，没有相应密钥时不会启用。

署名

练习插图为第三方作品，采用 CC BY-SA 许可，每项作品的署名信息见 web/ATTRIBUTIONS.md。无论本仓库采用何种许可，这些作品均保留其各自的许可。

许可证

MIT，详见 LICENSE。练习插图是唯一例外，见上文“署名”。