LifeOS

在线体验 · 贡献指南 · 安全策略 · MIT License

LifeOS 是一个把 PARA、GTD、OKR、复盘、个人资产与游戏化成长结合起来的个人操作系统。仓库包含两个独立部署的 Next.js 应用，以及一个供 ChatGPT/Agent 使用的 OAuth MCP 服务。

本项目采用 MIT License 开源，欢迎提交 Issue 和 Pull Request。package.json 中保留 "private": true 仅用于防止误发布到 npm，不代表 GitHub 仓库是私有软件。

正式环境（唯一准确信息源）

固定端点：

• 网站：https://lifeos-topaz-chi.vercel.app
• 登录：https://lifeos-topaz-chi.vercel.app/login
• API 健康检查：https://lifeos-api-nine.vercel.app/health
• MCP：https://lifeos-api-nine.vercel.app/mcp
• MCP Protected Resource Metadata：https://lifeos-api-nine.vercel.app/.well-known/oauth-protected-resource
• OAuth Authorization Server Metadata：https://lifeos-topaz-chi.vercel.app/.well-known/oauth-authorization-server
• Google OAuth 回调（Google Cloud 必须逐字一致）：https://lifeos-topaz-chi.vercel.app/api/auth/callback/google

不要再使用旧的猜测地址 lifeos-kunkun1234-1s-projects.vercel.app。Google 的 redirect_uri_mismatch 表示 Google Cloud 中登记的 Authorized redirect URI 与上面的正式回调不完全一致（协议、域名、路径、尾部斜杠都必须一致）。

架构

ChatGPT / MCP client
        │  OAuth 2.1 + PKCE
        ▼
Web（根目录，端口 3000） ── 登录、授权、令牌签发
        │
        ▼
API（apps/api，端口 4000） ── /mcp + 全部业务 Route Handlers
        │
        ▼
PostgreSQL / Prisma

• Web：页面、Auth.js Google 登录、MCP OAuth 授权服务器。
• API：全部业务 API、93 个 MCP 工具、鉴权、审计和幂等执行。
• packages/contracts：任务、目标等共享请求契约。
• packages/domain：可复用领域逻辑。
• prisma：PostgreSQL schema、迁移和种子数据。
• 进一步资料：后端迁移说明、数据库设计。

完整 MCP

MCP 是 tool-only 服务，不需要额外 Widget。Agent 登录 LifeOS 后只能访问当前用户自己的数据。工具层使用明确的白名单调用现有业务 API，不提供任意 URL、任意 SQL 或任意数据库工具。

当前共 93 个工具，覆盖网页已有功能：

• 查询：Dashboard、Analytics、Areas、Tasks、Habits、Routines、Goals/KR、Projects、Notes/Tree、Principles、Decisions、Reviews、Reward Store、Inventory、Achievements、Events、Battle Pass、Gacha、Wallet/Transactions、Equipment、Titles、Commissions、Profile、Resin、Freeze。
• 计划与执行：创建、修改、完成、归档或删除任务、习惯、例行事项、目标、关键结果和项目。
• 知识与复盘：创建、修改、移动或删除笔记；维护原则、决策记录与周期复盘。
• 资产与奖励：钱包初始化和设置，收入/支出/转账、修改、退款、删除、月结；奖励商品、兑换和库存处理。
• 游戏化：成就、活动、通行证、每日委托、称号、装备、冻结道具和祈愿。
• AI：决策教练、日程教练、周/月/季度教练；服务端会执行限流和树脂扣除/失败退款。
• 媒体：上传图片或音频到 Vercel Blob（未配置 Blob 时仅本地磁盘回退）。

核心实现位于：

• MCP endpoint：apps/api/src/app/mcp/route.ts
• 工具目录：apps/api/src/mcp/tools.ts
• 内部 API 白名单桥：apps/api/src/mcp/api-client.ts
• OAuth token 验证：apps/api/src/mcp/auth.ts
• 审计与幂等：apps/api/src/mcp/audit.ts
• OAuth server：src/lib/mcp-auth.ts

MCP 权限

所有非只读工具都要求 idempotencyKey，执行记录写入 AgentAction。同一个 key 重试同一操作会返回上次结果；同 key 换参数会被拒绝。删除、消费、祈愿、月结、AI 消耗等工具还带有 destructive/open-world 标注，供客户端显示确认。

在 ChatGPT 中连接

1. 确认下面的生产环境变量均已配置并重新部署两个项目。
2. 在 ChatGPT 开启 Developer mode，创建远程 MCP app/connector。
3. MCP Server URL 填写 https://lifeos-api-nine.vercel.app/mcp。
4. ChatGPT 会自动读取 Protected Resource Metadata，跳转到 LifeOS Web 登录并显示权限同意页。
5. 如果之前连接过 7 工具旧版 MCP，断开后重新连接一次，以授予新增 scope 并刷新到 93 个工具。

Vercel 的 API Production Deployment Protection 必须允许 ChatGPT 公网访问，否则远程 MCP 无法读取 metadata 或连接 /mcp。

环境变量

先复制本地模板：

cp .env.example .env.local

机密值不要提交 Git。API_JWT_SECRET、MCP_OAUTH_SECRET 和 AUTH_SECRET 都应是至少 32 字符的随机值。两个 Vercel 项目中，共享 secret 必须保持相同。

Web 项目 lifeos

API 项目 lifeos-api

部署后用下面命令检查配置是否生效：

curl https://lifeos-api-nine.vercel.app/health
curl https://lifeos-api-nine.vercel.app/.well-known/oauth-protected-resource
curl https://lifeos-topaz-chi.vercel.app/.well-known/oauth-authorization-server

Protected Resource Metadata 中的 resource 必须是 https://lifeos-api-nine.vercel.app/mcp，不能是 127.0.0.1。
代码在未设置显式 MCP 变量时会依次回退到 NEXT_PUBLIC_API_URL 和 Vercel 的
VERCEL_PROJECT_PRODUCTION_URL，但生产环境仍建议显式填写上表的稳定地址，便于以后更换域名。

本地开发

要求 Node.js 20+、npm 和可访问的 PostgreSQL。

npm install
npm run db:generate
npm run db:deploy

分别启动两个进程：

npm run dev
npm run dev:api

• Web：http://localhost:3000
• API：http://127.0.0.1:4000
• MCP：http://127.0.0.1:4000/mcp

本地 MCP 环境值：

AUTH_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://127.0.0.1:4000
WEB_ORIGIN=http://localhost:3000,http://127.0.0.1:3000
MCP_AUTH_ISSUER=http://localhost:3000
MCP_RESOURCE_URL=http://127.0.0.1:4000/mcp

验证与测试

npm run lint
npm run typecheck
npm run typecheck:api
npm run build
npm run build:api
npm run smoke:api
npm run smoke:notes
npm run smoke:wallet
npm run smoke:mcp

smoke:mcp 会启动临时 Web/API 服务，实际验证 OAuth Dynamic Client Registration、Authorization Code + PKCE、refresh token rotation、93 个工具发现、鉴权读写和幂等重放。

参与贡献

提交代码前请阅读 CONTRIBUTING.md。发现安全问题时不要创建公开 Issue，请按照 SECURITY.md 中的方式私下报告。

数据库变更

修改 prisma/schema.prisma 后：

npm run db:migrate
npm run db:generate

生产部署前或部署阶段应用已提交的迁移：

npm run db:deploy

MCP 依赖 OAuthClient、OAuthAuthorizationCode、OAuthRefreshToken 和 AgentAction 数据表；首次部署 MCP 前必须先应用迁移。

Vercel 自动部署

两个 Vercel 项目都连接此 Git 仓库的 main 分支。向 main push 后会分别构建 Web 与 API，无需手动上传文件。

发布顺序：

1. 本地运行类型检查、构建和 smoke tests。
2. 有 Prisma 迁移时执行 npm run db:deploy。
3. commit 并 push main。
4. 等待 lifeos 与 lifeos-api 两个 Vercel Production Deployment 成功。
5. 检查 /health、两个 OAuth metadata 和 /login。
6. 重新连接 ChatGPT MCP，确认能发现 93 个工具。

常见故障

• Google Error 400: redirect_uri_mismatch：Google Cloud Authorized redirect URI 没有逐字配置为 https://lifeos-topaz-chi.vercel.app/api/auth/callback/google。
• Metadata 仍显示 http://127.0.0.1:4000/mcp：API 项目缺少 MCP_RESOURCE_URL 或环境变量修改后未重新部署。
• MCP 401：访问令牌过期、issuer/resource 不一致，或两个项目的 MCP_OAUTH_SECRET 不同。
• MCP 能读不能写：旧连接没有 lifeos:write / lifeos:economy / lifeos:ai，断开并重新授权。
• MCP 内部 API 401/503：两个项目的 API_JWT_SECRET 不同，或 secret 少于 32 字符。
• AI 工具 503：API 项目未配置 DEEPSEEK_API_KEY。
• 上传在 Vercel 失败：未连接 Vercel Blob 或缺少 BLOB_READ_WRITE_TOKEN。
• ChatGPT 无法发现 MCP：API Deployment Protection 阻止公网访问，或 MCP URL 不是精确的 HTTPS /mcp 地址。