太卜开源架构剖析:Next.js 16 + Supabase + Capacitor 多端命理应用是如何构建的

原创2026-11-01 16:02:371,961 阅读

太卜开源架构剖析: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 适配刘海屏。

太卜AI算命应用Android启动页:Capacitor将一套Web代码封装为iOS与Android客户端

上图为 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 的边界约定,都值得逐层读一读。

登录后查看全文
taibu