太卜开源架构剖析:Next.js 16 + Supabase + Capacitor 多端命理应用是如何构建的
太卜开源架构剖析:Next.js 16 + Supabase + Capacitor 多端命理应用是如何构建的
太卜(taibu)是一款开源的高精度 AI 算命工具,覆盖八字、紫微斗数、六爻、梅花易数、奇门遁甲、大六壬、小六壬、太乙神数、西方占星、塔罗、黄历与 MBTI 等 15 类命理体系。它基于 Next.js 16 + Supabase + Capacitor 构建,同一套代码可以同时以 Web 网站、iOS/Android 应用和 MCP 服务器三种形态运行。本文将从计算引擎、协议层、Web 前端、多端分发四个层面,完整拆解这套开源架构的构建方式。
一、Monorepo 布局:一个 pnpm workspace 承载四个"产品"
太卜采用 pnpm workspace 单仓管理,一个仓库里同时产出四个可独立交付的组件:
| 目录 | 角色 | 交付形态 |
|---|---|---|
packages/core/ |
taibu-core 命理计算引擎 | 可安装的 npm SDK |
packages/mcp/ |
taibu-mcp(stdio 协议) | 本地 AI 客户端工具 |
packages/mcp-server/ |
taibu-mcp-server(HTTP 协议) | 公共 MCP 在线服务 |
根目录 src/ |
Next.js 16 Web 应用 + Agent | 网站与 API 路由 |
android/、ios/ |
Capacitor 原生壳 | iOS / Android 应用 |
工作区定义见 pnpm-workspace.yaml。项目的官方架构说明在 docs/manual/Architecture.md 中明确了一点:选择模块化单体,而不是拆成微服务——浏览器只通过受控 HTTP 接口访问应用服务,Supabase、SQL、模型 SDK 等细节全部留在服务端适配层。
💡 许可方面采用混合模式:三个包为 MIT(可商用再分发),Web 与服务端代码为 AGPL-3.0-only,详见根目录 LICENSE。
二、taibu-core:可安装的命理计算引擎
整套命理算法沉淀在 packages/core/ 中,与账号、会员、数据库完全解耦,纯函数式实现:
- 16 个领域子包:packages/core/src/domains/ 下按 bazi、ziwei、liuyao、meihua、qimen、daliuren、xiaoliuren、taiyi、tarot、almanac、astrology 等分目录,紫微还拆出运限(ziwei-horoscope)与飞星(ziwei-flying-star)子包;
- 规范输出:每个领域导出统一格式函数(如
toBaziText()/toBaziJson()),保证 Web 展示、AI 提示词与 MCP 返回的是同一套结果,避免三处各写一份渲染逻辑; - 借力成熟算法库:依赖 lunar-javascript(干支历法)、iztro(紫微)、taobi(奇门)、liuren-ts-lib(大六壬)、astronomy-engine(占星),见 packages/core/package.json;
- 回归测试护航:packages/core/tests/ 包含 30+ 个测试文件,覆盖算法边界、时区回归、输出契约完整性(如 timezone-utils.test.mjs)。
算法规则与推导约定记录在 packages/core/ALGORITHM_RULES.md。开发者在自己的 Node.js 项目中执行 npm install taibu-core 即可直接调用排盘能力,无需任何 MCP 协议。
三、MCP 协议层:让 AI Agent 直接调用 15 个命理工具
MCP(Model Context Protocol)是太卜架构中很关键的一环——它把"算得准"升级为"随便哪个 AI 都能用":
| 包 | 传输方式 | 典型场景 |
|---|---|---|
| packages/mcp/ | stdio | 本地接入 Cursor、Claude Desktop 等客户端 |
| packages/mcp-server/ | HTTP(streamable-http) | 公共在线服务,POST /mcp 即可调用 |
HTTP 服务不要求 OAuth、API Key 或数据库,但内置了 Origin 白名单、IP 频率限制与订阅长连接容量保护,配置说明见 packages/mcp-server/README.md。
对外暴露的工具与 core 一一对应:bazi(八字排盘)、bazi_pillars_resolve(四柱反查)、bazi_dayun(大运)、ziwei / ziwei_horoscope / ziwei_flying_star(紫微三件套)、liuyao(六爻)、meihua(梅花)、tarot(塔罗)、almanac(黄历)、astrology(占星)、qimen(奇门)、taiyi(太乙)、daliuren / xiaoliuren(大小六壬)。使用手册见 docs/manual/MCP-Server-Manual.md。
四、Next.js 16 前端结构:App Router 页面如何组织
Web 应用的核心依赖锁定在 package.json:Next.js 16.1.1 + React 19 + TypeScript 5 + Tailwind CSS 4 + Vercel AI SDK v6(ai 与 @ai-sdk/openai)。
页面按命理体系一个目录一个体系组织在 src/app/ 下:bazi/、ziwei/、liuyao/、tarot/、qimen/、daliuren/、meihua/、xiaoliuren/、mbti/、face/(面相)、palm/(手相)、hepan/(合盘)……每个体系内部再细分 page.tsx(排盘输入)、result/(结果)、history/(历史)三级路由,结构高度一致,新人很容易找到入口。
几个值得注意的工程点:
- AI 多模型网关:基于 AI SDK 流式对话,支持多模型来源、BYOK(自带密钥)与后台 AI 模型管理面板(src/components/admin/ 下的 AIModelPanel、AIGatewayPanel);
- 服务端会话:
@supabase/ssr以 Cookie 维护 Supabase 会话,浏览器状态用 TanStack Query 管理; - 前后端边界:鉴权与受控客户端装配集中在 src/lib/api-utils.ts,排盘 → AI 分析 → 保存的完整管线见 src/lib/api/divination-pipeline.ts;
- 构建与安全:next.config.ts 开启
standalone输出(Docker 友好)、统一安全响应头,并对远程图片域名做了白名单。
五、Supabase 一站式后端:数据、认证、存储
太卜没有自建传统后端,而是把 Supabase 当作 PostgreSQL + Auth + PostgREST + Storage 的合体:
- 数据:共 49 张表(42 张业务表 + 7 张 Agent 运行表),知识库检索使用 pgvector 向量索引;schema 快照见 supabase/tabel_export_from_supabase.sql;
- 权限:全部用户数据走 RLS(行级安全),管理员操作仍要求
authenticated + is_admin_user(),不使用无限制 service_role; - 原子性:积分扣减、分析结果写入、历史绑定等关键路径封装为 SQL RPC 事务,避免"扣了分但没保存"之类的半成品状态;
- 文件:头像等资产走 Storage 公开 bucket,命名规则与大小限制见 supabase/selfhost/README.md。
六、Agent Worker:把长任务从浏览器搬到后台
AI 编排类任务(Agent 多步工具调用、后台执行、成果自动保存)不能挂在页面请求上。太卜的解法是一个独立的 worker 容器:
docker-compose.yml 中定义了三服务编排:
| 服务 | 说明 | 端口 |
|---|---|---|
web |
Next.js 主站 | 3000 |
worker |
.agent/worker.mjs,基于 Pi Durable 的后台任务执行器,自带 --health 健康检查 |
— |
mcp |
taibu-mcp-server | 3001 |
Web 端入口在 src/app/api/agent/ 与 src/lib/agent/,负责鉴权、任务提交与结果回写;worker 的数据库租约与原子结算细节见 docs/manual/Agent.md。
镜像构建则是一个标准的 Docker 多阶段流程:Dockerfile 依次经过依赖安装(pnpm 层缓存)、构建、运行三个阶段,最终容器以非 root 用户运行,并在构建期对 Sharp 图像处理与 worker 启动做了运行时自检,防止镜像里缺二进制文件。
七、Capacitor 多端方案:一套代码,三种端形态
移动端的实现思路非常"轻":Capacitor 只负责提供一个原生壳。
核心配置见 capacitor.config.ts:appId 为 com.hhs.taibu,appName 为"太卜"。关键点在于 server.url 直接指向线上 Web 站点——也就是说 iOS 和 Android 客户端加载的就是与浏览器完全相同的那套 Next.js 页面,配合白名单域名控制导航,再叠加 iOS 的 contentInset 适配刘海屏。
上图为 Android 横屏启动页。原生平台目录 android/(Gradle 工程)与 ios/(Xcode 工程 + SPM 包)只承担打包、签名与启动画面职责,业务逻辑零重复。这正是"多端体验,一套代码"的实现方式。
八、运行方式:本地开发、Docker 与自托管三条路线
本地开发(需要 Node.js 18+ 与 pnpm):
git clone https://gitcode.com/gh_mirrors/ta/taibu
cd taibu
pnpm install
cp .env.example .env # 填入必要的 API Keys
pnpm dev # 访问 http://localhost:3000
Docker 部署:docker compose up -d --build 一键拉起 Web + MCP 两个服务;也可以只用 docker-compose.web.yml 或 docker-compose.mcp.yml 单独部署其中一部分。
完全自托管(不依赖任何外部托管平台):
pnpm selfhost init --demo # 生成随机凭据与本地配置
pnpm selfhost up # 启动本地 PostgreSQL + Redis + Auth/PostgREST/Storage 栈
启动器 scripts/selfhost.mjs 会在本地拉起完整的 Supabase 兼容栈(含 GoTrue 认证、PostgREST、Storage 与向量扩展),--demo 模式使用标注清晰的本地确定性模型,不产生真实 AI 费用;数据库基线与迁移顺序见 supabase/selfhost/README.md 与 docs/manual/Self-Hosting.md。
九、质量防线:测试与架构守卫
一个能长期演进的开源项目,靠的是可重复验收的防线,太卜同样如此:
- 统一测试入口:
pnpm test会先自动构建三个包再执行全量测试,运行器为 scripts/test-runner.mjs; - 架构守卫:scripts/check-architecture-guards.mjs 用脚本检查模块边界(例如服务器实现不得流入浏览器包),防止架构随时间腐化;
- 端到端验收:
pnpm verify一次构建后跑完单元、路由、SQL 契约、真实 Auth/REST 栈与 Playwright 浏览器层断言; - 贡献规范:仓库内 AGENTS.md 给出了"项目最小地图"、常用命令与测试验收要求,是理解项目分工最快的入口。
小结
回看太卜的架构,可以用一句话概括:把"算法、协议、应用、分发"四层彻底解耦。taibu-core 保证算得准,MCP 层保证任何 AI 都能用,Next.js + Supabase 保证 Web 端体验与数据安全,Capacitor 则用最小的成本把同一套代码装进手机。对想学习"传统领域逻辑 + 现代全栈架构"如何结合的开发者来说,这个开源仓库本身就是一份结构清晰的参考实现——从 README.md 的 MCP 配置到 docs/manual/Architecture.md 的边界约定,都值得逐层读一读。
