紫微斗数开源排盘引擎：用代码复原千年命理智慧

想象一个场景：一位对命理学感兴趣的年轻人，想用紫微斗数给自己算一卦，但翻遍市面 App 不是要付费订阅，就是算法语焉不详、解读如同模板填充——直到他发现了一个 GitHub 项目，只需要输入出生时间地点，一张完整的命盘就出现在眼前，连大限流年、古籍原文都能随时查阅。Renhuai123/ziwei-doushu 正是这样一个项目。

背景：紫微斗数为何需要开源

紫微斗数是中国传统命理学的核心体系之一，与八字并列为命理两大柱，但因传承封闭、算法复杂，数字化程度远低于八字。倪海厦在《天纪》中系统整理了正统的紫微斗数体系，成为这个项目知识库的核心来源。

作者（GitHub ID: Renhuai123）在 2026 年 5 月 1 日创建了这个仓库，并在 6 月初发布 v3.0 版本时同步开源了 51.8 万条命盘样本数据集（5.5 GB），在开源社区引发关注。这种规模的数据集在命理类 AI 应用中极为罕见。

核心功能：从排盘到解读的完整链路

排盘引擎（lib/ziwei/）

项目的核心是纯 TypeScript 实现的排盘算法，覆盖紫微斗数完整流程：

• 算法流程（algorithm.ts）：安命宫 → 定五行局 → 安十四主星 → 安辅星 → 排大限流年
• 四化飞星（sihua.ts）：禄权科忌四化系统，含各天干四化对照表
• 格局知识库（patterns.ts）：1100+ 行代码，覆盖紫府同宫、日月并明、七杀朝斗等经典格局判定
• 合盘方法（heming-knowledge.ts）：倪师体系下双人命盘比对逻辑
• 城市经纬度（cities.ts）：中国城市经纬度用于真太阳时校正

这些算法的独特之处在于：作者明确标注基于倪海厦《天纪》体系，使得解读口径与主流付费平台有明显差异——例如格局判定逻辑、女命妇科保养细节、健康子午流注等细分领域。

知识库与古籍

项目不只做算法，还内置了完整古籍原文数据库：

• 骨髓赋（gusuifu.ts）：紫微斗数核心歌诀
• 紫微斗数全集（quanji.ts）：清代古本
• 紫微斗数全书（quanshu.ts）：陈希夷传本

这些古籍均标注为 Public Domain，可自由商用。配合倪海厦《天纪》三篇（天纪、人纪、地纪）知识体系，项目构建了一套从算法到解读的完整知识图谱。

51.8 万样本数据集

v3.0 版本开源的最大亮点，覆盖年60 × 月12 × 日30 × 时12 × 性别2 的全部组合。每条样本包含完整命盘 JSON + 13 主题解读（命格总览、财运、事业、感情、健康等）。作者声称数据与线上平台口径完全一致，并提供了完整的 SHA256 校验文件。

典型用途：

• LLM 微调语料（51.8 万 input-output 配对）
• RAG 检索系统的知识源
• 紫微斗数算法 A/B 对比基准
• 命理学学术研究

许可极为宽松：商用无需付费、无需申请，唯一要求是保留数据来源标注（attribution）。

Web 前端（Next.js 14）

完整的前端界面，包含：

• 排盘工作台（app/chart/page.tsx）：命盘方格、宫位详情、星曜面板
• 合盘分析页（app/heming/）：双人命盘比对
• 古籍阅读器（app/library/）：全文搜索
• 命理百科（app/knowledge/）：14 主星 × 12 宫位知识页
• 亮色/暗色主题切换、移动端适配

前端依赖的外部库中，iztro 和 lunar-javascript 是两个关键库——前者提供排盘数据基础，后者处理农历历法换算。项目在此基础上封装了大量自定义逻辑。

技术架构

层次	技术选型
框架	Next.js 14（App Router）
语言	TypeScript（严格类型）
样式	Tailwind CSS + CSS Variables
动画	Framer Motion
命理计算	iztro + lunar-javascript
AI 对接	Anthropic Claude API（@anthropic-ai/sdk）
数据库	PostgreSQL（pg + ioredis）
部署	Vercel / Cloudflare Pages

架构上采用前后端分离：开源版本仅包含前端 UI 和纯算法层，AI 解读后端（/api/interpret、/api/heming）属于平台运营层不开源。这意味着如果你想获得 AI 解读能力，需要自行实现接口并接入 LLM。

代码结构清晰，模块划分合理：

• lib/ziwei/：核心算法，所有逻辑均有 TypeScript 类型定义
• lib/classics/：古籍原文模块化
• lib/seo/：SEO 知识图谱数据
• lib/nihai/：倪海厦人纪系列知识
• components/：React 组件，按功能域拆分

整体代码质量较高，体现在：完整的 TypeScript 类型系统、lint-staged + husky 预提交检查、设计系统级 CSS Variables 规范。

部署体验

本地部署（推荐）：

git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install
cp .env.example .env.local  # 填入 AI API Key（可选）
npm run dev

硬件需求极低（1GB RAM），无需 GPU。项目支持直接部署到 Vercel（npm run build）或 Cloudflare Pages（npm run build:cf），作者在 README 中提供了明确的部署指引。

注意：开源版不含 AI 解读后端，不填 API Key 时可以正常访问排盘界面（算法和 UI 独立运行），但无法获得 AI 命盘解读。

局限与争议

1. AI 解读能力需自行实现：开源代码不含 /api/interpret 等路由，需要自行对接 LLM 才能获得解读功能；
2. 平台运营能力不开源：用户系统、支付、签名校验、防刷等后台逻辑均不开放；
3. 文化争议：命理学本身存在科学争议，项目定位是「知识整理与算法实现」，解读结论的准确性高度依赖知识库质量；
4. 无 Docker 支持：项目未提供 Dockerfile，对习惯容器化部署的开发者有一定门槛。

行业意义

这个项目代表了传统命理文化数字化的一条新路径：通过开源算法和数据，让原本封闭在付费 App 后的知识体系变得可验证、可复现。51.8 万条样本数据集的开源，对于想要训练命理领域 LLM 或构建 RAG 系统的开发者而言，是目前已知质量最高的开源数据集。

同时，作者通过「算法开源 × 数据集开源 × 平台付费」的商业模式，展示了传统文化 + AI 的一种可持续路径：开源部分足够有价值（算法 + 数据），盈利靠平台运营和 AI 解读服务。

从 GitHub 趋势看，项目自 2026 年 5 月创建以来保持稳定增长，配合 ICP 备案的正式上线，正在成为一个兼具工具属性和文化属性的垂直 AI 应用入口。