White Whale Bazi & Liuyao Engine
<div align="center">
# 白鲸测 · 确定性八字与命卜合参引擎
**四柱八字与六爻的学习者,不该迷失在 AI 的概率幻觉与免责套话里**
[](https://github.com/personalxz000001-debug/white-whale-bazi/actions/workflows/ci.yml)
[](#)
[](./LICENSE)
[](#四快速开始-cli--mcp--skill)
[](#九协议与隐私铁律)
中文 · [English](./README_EN.md)
</div>
---
**一、项目理念**:命理与六爻推演是中国古典决策学的精粹,先人们将其总结在各部经典中。我们希望通过现代技术,让这些经典走出时间的迷雾,辅助自身趋吉避凶。
我们开源底层的全球经纬度真太阳时天文历法、MCP / Skill 接入层与反和稀泥结构化协议,是因为我们认为:**国学流派是各家的大成,不应该成为阻拦后人继续学习的障碍**。价值非凡的调候病药,应当指导人们更好地生活与决策;借现代算法与开源共创,让一万人的实战思考交汇融合、持续进化。
**二、引擎基线**:白鲸测采用「确定性天文与四脉规则链 + 实时交叉推演」架构——**823 项真题校准的代码级八字与决策系统 × 四脉古籍同参**:
| 演进阶段 | 古典命局原型 | 实盘与真题靶场 | 发版门禁断言 | 单次实时交付规格 |
| :--- | :--- | :--- | :--- | :--- |
| **v2.0 四脉合参引擎**(当前线上) | **46 类原型** | **22 道大赛真题 + 140 盲测** | **823 项(100% 必过)** | **约 1.2 万字 + 15 页 PDF** |
| v1.0 初版探索底座 | 36 类原型 | 基础实盘抽样校验 | 310 项 | 单模态纯文本简析 |
| 迭代跨度 | +28% 格局覆盖 | 引入 10 条防过拟合铁律 | **+165% 断言密度** | 双模零术语 + 铜钱合参 |
在线完整体验:[baijingce.com](https://www.baijingce.com/?ch=github) —— 真太阳时免费排盘、四脉合参详批、铜钱×八字动态起课全部开放。
> **注:关于「同盘异命」与定量边界**
> 传统四柱推演若脱离时代与地域坐标,极易沦为机械宿命论。我们在 140+ 真人盲测与标杆对照盘(如 `BENCH-37` 同八字跨城对照)中严格验证:现实成就由 **「原局做功结构 40% + 大运应期 30% + 城市与平台杠杆 30%」** 共同锚定。同一命盘在一线高杠杆赛道与三四线稳态环境中会呈现显著区间弹性;因此,在线完整版摒弃绝对化宿命断语,统一输出「稳态保底底盘 vs 主升浪冲刺上限」双轨资产坐标。
---
## 目录
| 序号 | 章节 | 一句话 |
| :---: | :--- | :--- |
| 一 | [一、本轮更新](#一本轮更新) | 《穷通》《真诠》日干×月令真神校准、823 项断言全绿、零术语双模编译器上线 |
| 二 | [二、为什么推倒重做](#二为什么推倒重做) | 正面解决通用 AI 算八字的 6 个底层死结与“同卦不同命”合参原理 |
| 三 | [三、四大核心工程](#三四大核心工程) | 四脉同参靶场、A 级资产坐标、铜钱×八字动态合参、一盘双译盲态隐私 |
| 四 | [四、快速开始 (CLI / MCP / Skill)](#四快速开始-cli--mcp--skill) | 30 秒克隆跑起来,一键接入 Claude Code / Cursor / Antigravity |
| 五 | [五、真太阳时排盘内核](#五真太阳时排盘内核) | 能做到什么、经纬度均时差与节气边界怎么算、文件怎么分 |
| 六 | [六、界面是一份轻量 Demo](#六界面是一份轻量-demo) | 不是 `baijingce.com` 线上完整双模系统,差距明牌写清 |
| 七 | [七、开源边界](#七开源边界) | 什么永久开源、什么锁在线上闭源母库 |
| 八 | [八、维护节奏与贡献](#八维护节奏与贡献) | 底座同步节奏、实盘挑刺与 Issue / PR 口径 |
| 九 | [九、协议与隐私铁律](#九协议与隐私铁律) | 代码 MIT / 古籍公版 / 线上零浏览器本地存储与一键物理焚毁 |
| 十 | [十、关于与联系](#十关于与联系) | 项目理念、双层技术栈、备案官网与交流入口 |
---
## 一、本轮更新
v2.0 线上引擎与本仓 `v0.2.0` 开源历法底座已完成三项关键对齐:
1. **日干 × 月令调候真神全量校准**:线上母库完成《穷通宝鉴》寒暖燥湿与《子平真诠》月令相神冲突裁决回归,823 项真题与盲测断言 100% 通过;本仓同步开源公版《滴天髓》十天干体象与《穷通宝鉴》十干 × 十二月令(全 120 组)自动检索器。
2. **真太阳时纠偏对比现场化**:纯 Python 标准库手写 VSOP87D 太阳地心视黄经求解器(节气交接精度对齐紫金山天文台至秒级)与 Jean Meeus 均时差方程,内置 400 座中外城市离线坐标与 1986–1991 中国历史夏令时自动回拨,新增 `compare-solar` 命令直观复现裸连大模型排错日柱、时柱的翻车现场。
3. **零依赖 MCP Server 与双模协议定型**:线上零术语「白话 / 专业」双模编译器与 15 页 PDF 报告正式投产;本仓同步提供零第三方运行时依赖的标准 `stdio` MCP 服务、Agent Skill 规范及反免责和稀泥 JSON Schema。
## 二、为什么推倒重做
我们推倒了市面上常见的“套壳提示词聊天框”,经 140+ 真人实盘盲测,用确定性代码重搭了整套八字与决策系统,正面解决 AI 算八字的 **6 个底层死结**:
1. **历法幻觉**:算不准城市经纬度真太阳时与节气分钟边界,源头就排错干支;
2. **机械数五行**:只会数金木水火土个数,无视月令寒暖调候病药;
3. **单流派死套与过拟合**:被迫单选格局或调候,拿死口诀硬套活人——见印多就盲夸高学历、见伤官就铁断二婚,无视原局破格与大运救应,一遇复杂盘立刻翻车;
4. **免责和稀泥**:“既宜求稳、又可创业”两头讨好,反问一句就顺杆改口打补丁;
5. **时间谜语与大厂周报腔**:满屏“赋能、预期收益”的公文套话,读完依然不知道哪个月该冲、哪件事该避;
6. **千人同签(如何实现“同卦不同解”)**:普通工具两人同一分钟摇出同一卦,给的签文一字不差;我们将六爻「世应关系与动爻五行」直接咬合本人的「八字喜用神及事业/婚姻宫位」交叉运算——同样摇出旺火动爻,八字喜火者断乘势翻身,忌火者断盲动引火烧身,真正做到同卦不同命。
## 三、四大核心工程
* **四脉古籍同参 × 头部实战拆盘蒸馏 × 823 项真题门禁**
手搓全球经纬度真太阳时天文底座,将《滴天髓》病药、《穷通宝鉴》调候、《子平真诠》格局成破与正统盲派做功四脉合参,并蒸馏了十余位实战派博主「直抓第一病灶 → 辨破格救应 → 落现代赛道」的拆盘链。内置 46 类古典原型 + 22 道大赛标杆真题(823 项断言),正确率 100% 后方可发版。
* **拒绝量化模糊:A 级资产坐标 × 现代职场三层狙击**
淘汰古代行业套话与江湖恐吓:直接算清终身财富区间精确至小数位(如 A7.2 ~ A7.7),拍板考公、大厂还是单干及能不能跟熟人合伙,所有干支流月全部自动换算为公历月份与实岁年龄。
* **拒绝静态题库:铜钱起课 × 个人八字底盘实时合参**
预制文本库只能给同一卦发同一张死签文。本引擎在起课瞬间调取你的八字底盘动态推演——本卦看表面僵局、互卦扒对方心底潜台词、变卦定最终走向,一屏直出成事把握百分比、六维运势评分与 4 句刀锋决断,彻底终结两人同卦却拿同一套话术的行业通病。
* **一盘双译编译器 × 开发者盲态隐私架构**
一键秒切「白话 / 专业」双视图:【白话】100% 零术语直出准话、8 维同频生活参数与 15 页雷达曲线精排 PDF;【专业】保留全量古籍生克推导;全站零浏览器本地存储、全链路加密,连开发者本人亦无法查看任何用户数据,支持一键物理焚毁。
## 四、快速开始 (CLI / MCP / Skill)
本仓库运行时 **零第三方依赖**(100% Python 3.10+ 标准库),无需编译任何 C 扩展,克隆后 30 秒即可跑出完整排盘与古籍索引。
### 1. 安装与终端实跑 (`pip` / `uv`)
```bash
git clone https://github.com/personalxz000001-debug/white-whale-bazi.git
cd white-whale-bazi
# 方式 A:使用 uv(推荐)
uv tool install --editable .
# 方式 B:使用标准 pip
pip install -e .
```
**实测一:抓出通用大模型排错日柱与时柱的现场 (`ww-bazi compare-solar`)**
```bash
ww-bazi compare-solar --date 1988-07-15 --time 00:30 --city 乌鲁木齐 --gender female
```
```text
══════════════════════════════════════════════════════════════════════════════
白鲸测 · 平太阳时钟表直排 vs 真太阳时天文校准 干支差异现场对比
══════════════════════════════════════════════════════════════════════════════
输入钟表时间:1988-07-15 00:30:00 | 城市:乌鲁木齐 (87.6168°, 43.8256°)
[Step 1] 夏令时校准:-01h 00m 00s (1988年中国历史夏令时生效窗口,已自动回拨 1 小时)
[Step 2] 经度平太阳:-02h 09m 32s (相对 120.0° 标准子午线)
[Step 3] 天文均时差:-05m 52s (Meeus 轨道偏心率与黄赤交角修正)
=> 最终真太阳时:1988-07-14 21:14:36 (累计纠偏 -03h 15m 24s)
┌─────────────────────────────┬──────┬──────┬────────────────┬────────────────┐
│ 对比维度 │ 年柱 │ 月柱 │ 日柱 │ 时柱 │
├─────────────────────────────┼──────┼──────┼────────────────┼────────────────┤
│ 未校准钟表直排 (裸LLM常见) │ 戊辰 │ 己未 │ 辛未 │ 戊子 │
│ 真太阳时校准后 (确定性真值) │ 戊辰 │ 己未 │ 庚午 │ 丁亥 │
│ 偏差诊断 │ 一致 │ 一致 │ !! 发生翻转 !! │ !! 发生翻转 !! │
└─────────────────────────────┴──────┴──────┴────────────────┴────────────────┘
结论:检测到 日柱/时柱 发生实质翻转(钟表直排:戊辰 己未 辛未 戊子 -> 真太阳时校准:戊辰 己未 庚午 丁亥,甚至连日主都从「辛金」变成了「庚金」)。
```
**实测二:输出完整四柱矩阵、十步大运与 120 组《穷通》《滴天髓》原典 (`ww-bazi chart`)**
```bash
ww-bazi chart --date 1988-07-15 --time 00:30 --city 乌鲁木齐 --gender female
```
```text
┌────────┬──────────────────────────┬──────────────────────────┬─────────────────┬─────────────────┐
│ 排盘项 │ 年柱 │ 月柱 │ 日柱 │ 时柱 │
├────────┼──────────────────────────┼──────────────────────────┼─────────────────┼─────────────────┤
│ 主星 │ 偏印 │ 正印 │ 元女 │ 正官 │
│ 天干 │ 戊(土) │ 己(土) │ 庚(金) │ 丁(火) │
│ 地支 │ 辰(土) │ 未(土) │ 午(火) │ 亥(水) │
│ 藏干 │ 戊偏印 / 乙正财 / 癸伤官 │ 己正印 / 丁正官 / 乙正财 │ 丁正官 / 己正印 │ 壬食神 / 甲偏财 │
│ 星运 │ 养 │ 冠带 │ 沐浴 │ 病 │
│ 空亡 │ 戌亥 │ 子丑 │ 戌亥 │ 午未 │
│ 纳音 │ 大林木 │ 天上火 │ 路旁土 │ 屋上土 │
│ 神煞 │ — │ 天乙贵人 │ — │ 文昌 │
└────────┴──────────────────────────┴──────────────────────────┴─────────────────┴─────────────────┘
【公版古籍原典自动检索】
1. 《滴天髓·天干体象》[庚金 · 百炼剑戟]
原文:「庚金带煞,刚健为最。得水而清,得火而锐。土润则生,土干则脆。能赢甲兄,输于乙妹。」
2. 《穷通宝鉴·庚日未月》[季夏冠带]
提纲调候参考字:丁、甲
原文:「六月庚金,三伏生寒,顽钝极矣,先用丁火煅炼,次取甲木引丁。」
原局字面核对:天干透出 [丁] | 地支藏根 [丁、甲]
```
**实测三:三枚铜钱六爻起课与京房纳甲全盘 (`ww-bazi liuyao`)**
```bash
ww-bazi liuyao --date 2026-11-15 --time 14:20 --city 北京 --lines 7,8,9,7,6,8 --question "核心重构上线推进节奏"
```
### 2. 一键挂载 MCP Server(Claude Desktop / Claude Code / Cursor / Antigravity)
将以下配置写入宿主的 `mcpServers` 配置文件(把路径替换为你本地克隆的绝对路径):
```json
{
"mcpServers": {
"white-whale-bazi": {
"command": "python3",
"args": ["-m", "white_whale_bazi.mcp_server"],
"env": {
"PYTHONPATH": "/absolute/path/to/white-whale-bazi/src"
}
}
}
}
```
若已执行 `uv tool install --editable .` 或 `pip install -e .`,可直接简化为:
```json
{
"mcpServers": {
"white-whale-bazi": {
"command": "ww-bazi-mcp"
}
}
}
```
挂载后,AI 会自动获得两个确定性工具:
* `calculate_true_solar_bazi`:一次返回真太阳时秒级校准、四柱十神藏干神煞十步大运、平/真太阳时差异警告、《滴天髓》《穷通宝鉴》命中条文与反和稀泥输出约束。
* `cast_liuyao_hexagram`:返回三枚铜钱京房纳甲全盘(本卦、互卦、变卦、世应、六亲、六神、伏神、日辰旬空月破)及 64 卦公版《周易》卦辞象辞。
### 3. 挂载 Agent Skill 与 Python API 调用
复制 `skills/white-whale-bazi/SKILL.md` 到项目的 `.claude/skills/white-whale-bazi/SKILL.md` 或 `.agents/skills/white-whale-bazi/SKILL.md`,即可强制智能体先查历法真值、再用唯一肯定句作答。
```python
from white_whale_bazi import compare_solar_bazi, match_classical_canon, cast_liuyao
comp = compare_solar_bazi("1988-07-15", "00:30", city="乌鲁木齐", gender="female")
canon = match_classical_canon(comp.calibrated_chart)
plate = cast_liuyao(lines=[7, 8, 9, 7, 6, 8], cast_date="2026-11-15", cast_time="14:20")
```
## 五、真太阳时排盘内核
很多排盘脚本把“节气交接”和“真太阳时”混为一谈,导致西部与海外城市在立春、惊蛰交界日算错月柱甚至年柱。本内核在球面天文学上严格区分两条物理轨道:
1. **公转黄经定年柱、月柱与起运(全球瞬时天象)**:
二十四节气本质是地球公转令太阳地心视黄经到达 `15°` 整数倍的物理瞬间(如立春严格对应视黄经 `315.0000°`)。`solar_terms.py` 采用截断 VSOP87D 行星摄动级数,叠加 NASA `ΔT = TT - UT1` 多项式、IAU 章动与周年光行差修正,通过牛顿迭代求根将 1900–2100 年节气交接误差压缩在 `±5 秒` 内,直接以扣除夏令时后的绝对世界时 `UTC` 判定年月交界与起运交脱岁数。
2. **自转时角定日柱与时柱(当地子午线太阳仰角)**:
日干支更替与十二时辰取决于太阳相对出生地子午线的真实时角。`true_solar_time.py` 按三步精确还原:
* **历史夏令时回拨**:自动识别中国大陆 1986–1991 六个夏令时生效窗口并回拨 `-3600s`,港澳台地区单独标记不误扣,海外 35 座城市通过 `zoneinfo` 自动剥离当地夏令时;
* **经度时差修正**:相对标准时区子午线(东八区为 `120.0°E`)按 `1° = 240 秒` 换算平太阳时;
* **天文均时差(Equation of Time)**:基于地球轨道偏心率 `e` 与黄赤交角 `ε` 计算日晷真太阳与平太阳的逐日快慢差(全年波动达 `-14m14s` 至 `+16m29s`),并支持 `23:00` 交子换日与 `00:00` 零点换日(早晚子时)切换。
### 仓库文件划分
```text
white-whale-bazi/
├── demo/index.html # 离线零依赖、零浏览器存储交互式排盘与六爻起课页
├── skills/white-whale-bazi/SKILL.md # 即插即用 Agent Skill 反幻觉协议
├── src/white_whale_bazi/
│ ├── cities_data.py # 400 座中国地级/主要城市及全球核心城市离线坐标库
│ ├── solar_terms.py # VSOP87D 太阳视黄经与二十四节气秒级求解器
│ ├── true_solar_time.py # 夏令时回拨 + 经度时差 + Meeus 均时差引擎
│ ├── bazi_chart.py # 四柱、藏干、十神、神煞、五行权重与十步大运
│ ├── classical_canon.py # 《滴天髓》十干 + 《穷通宝鉴》120 组公版原典匹配器
│ ├── liuyao_cast.py # 三枚铜钱六爻起课、京房八宫纳甲、伏神与 64 卦周易经传
│ ├── cli.py # ww-bazi 终端对齐渲染入口
│ ├── mcp_server.py # 标准 MCP (stdio) 零依赖服务端
│ └── protocol/ # 反免责和稀泥 JSON Schema 与现代十神职能词表
└── tests/ # 覆盖跨城纠偏、夏令时、立春边界、120组古籍与 MCP 的单测套件
```
## 六、界面是一份轻量 Demo
仓库内的 [`demo/index.html`](./demo/index.html) 是一份无需启动后端、无需联网、双击即可在浏览器离线运行的单文件验证台。它采用「85% 冷白刀锋 × 15% 曜石黑金」排印体系,内置与 Python 内核 1:1 同步的前端历法与纳甲脚本,支持:
* 一键切换乌鲁木齐夏令时跨日、拉萨立春分钟级换年、哈尔滨夜子换日、台北无大陆夏令时四大实测算例;
* 同屏直观对比「未校准平太阳时钟表直排」与「真太阳时校准后」的四柱翻转;
* 实时检索 120 组《穷通宝鉴》与《滴天髓》公版原典,以及模拟三枚铜钱六次摇卦装盘。
**明牌说明差距**:这份静态页仅展示本地开源内核的**客观历法排盘与公版古籍原文检索**,不包含线上生产系统的四脉病药冲突裁决、破格救应推理、资产定量模型、双模白话编译与 15 页典藏 PDF 排版。想体验完整推演深度,请直接访问 [baijingce.com](https://www.baijingce.com/?ch=github)。
## 七、开源边界
我们坚持把地基彻底敞开接受检验,同时清晰划定开源底座与线上商业引擎的边界:
| 能力模块 | 本仓本地开源版 (`MIT`) | `baijingce.com` 在线完整引擎 |
| :--- | :--- | :--- |
| **全球真太阳时与历史夏令时校准** | **100% 开源**(400 城离线库 + 自定义经纬度) | 在线同步(扩展支持全球数万城市检索) |
| **分钟级节气四柱、十神、神煞与十步大运** | **100% 开源**(纯标准库确定性计算) | 在线同步(含流年流月应期联动) |
| **传统京房纳甲六爻全盘与 64 卦《周易》** | **100% 开源**(本/互/变、世应、六亲、伏神) | 在线升级为 **个人八字喜忌 × 铜钱动爻实时合参** |
| **古籍依据层** | **公版原典检索**(《滴天髓》10 组 + 《穷通》120 组) | **闭源母库**(四脉冲突裁决链 + 46 类原型破格救应) |
| **真题靶场与定量体系** | 开源反和稀泥协议 Schema 与基础十神职能词表 | **闭源母库**(22 道真题 823 项门禁 + A 级双轨资产定量) |
| **交付形态** | 终端 CLI / 标准 MCP Server / 离线单页 HTML | **白话/专业一键双译 + 1.2 万字详批 + 15 页精排 PDF** |
## 八、维护节奏与贡献
* **底座同步节奏**:每当线上引擎在盲测或用户反馈中发现历法边界个案(如特殊历史时区、海外夏令时切换、古籍条文校勘),脱敏后的纯历法与公版校勘补丁会定期合入本仓库。
* **欢迎提交的 PR 与 Issue**:
1. 扩充更多县级城市或海外城市的精确经纬度与历史时区测试算例;
2. 二十四节气天文算法在极端历史年份的精度对比与性能优化;
3. 公版《滴天髓》《穷通宝鉴》《周易》原典字句的错别字校勘;
4. 新增更多主流 AI IDE / Agent 框架的 MCP 与 Skill 适配示例。
* **不接受的提交范围**:请勿提交任何包含真实他人姓名与隐私身份的命盘数据,亦不合并带有玄学恐吓话术或未经确定性验证的概率提示词模板。详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 九、协议与隐私铁律
* **开源许可**:本仓库全部源代码、JSON Schema 协议与离线 Demo 均采用 [MIT License](./LICENSE) 宽松开源协议,允许自由商用、修改与二次分发;内置《周易》《滴天髓》《穷通宝鉴》引文均取自公版古籍。
* **零浏览器本地存储铁律**:本仓 [`demo/index.html`](./demo/index.html) 与线上 [baijingce.com](https://www.baijingce.com/?ch=github) 均严格执行零浏览器本地存储标准,不在客户端驻留任何出生时间或卦象缓存。
* **线上盲态加密与物理焚毁**:在线完整版对用户档案与报告实施全链路高强度密文保护,服务端日志严禁打印任何出生时辰与报告明文,支持用户随时一键物理焚毁名下档案。
## 十、关于与联系
### 项目理念
见本页开头。想自己搭排盘底座或接 AI 插件?代码都在这里,MIT 协议直接拿去用。嫌配环境麻烦、想直接看四脉病药深推与 15 页精排报告?来 [baijingce.com](https://www.baijingce.com/?ch=github) 直接用。
### 技术栈
* **开源历法内核(本仓)**:Python 3.10+(零重型依赖天文均时差、历史夏令时与二十四节气历法实现 + 公版《穷通》《滴天髓》120 组索引)+ 标准 MCP (`stdio`) + Agent Skill
* **线上完整系统(`baijingce.com`)**:Next.js (App Router) + TypeScript + Python / Django + PostgreSQL + WeasyPrint(典藏 A4 PDF 排版引擎)+ GSAP / Lenis 动效系统
### 联系与交流
* **线上平台**:[baijingce.com](https://www.baijingce.com/?ch=github)(已完成 ICP 备案:浙ICP备2026049940号-1)
* **提问题、提历法修复**:见 [CONTRIBUTING.md](./CONTRIBUTING.md) 或提交 [Issues](https://github.com/personalxz000001-debug/white-whale-bazi/issues)(公开探讨盘面请隐去真实姓名保护隐私);使用交流请到仓库 **[Discussions(讨论区)](https://github.com/personalxz000001-debug/white-whale-bazi/discussions)** 或官网顶部 **Q&A 站长留言箱**
* **全网动态**:小红书 / 抖音 / 微信视频号 搜索关注 **白鲸测**,第一时间看实盘拆解与引擎更新动态🐳
TDQS
Scored across 2 tools
The two tools target entirely different divination systems: one produces a Bazi (Four Pillars) chart, the other casts a Liuyao hexagram. Their names and descriptions make the boundary unmistakable, so an agent cannot reasonably confuse them.
Both names follow a strict snake_case verb_noun pattern (calculate_true_solar_bazi, cast_liuyao_hexagram), using domain-appropriate verbs. There is no mixing of conventions or casing styles.
Two tools map cleanly onto the server's two advertised engines, each consolidating a large deterministic calculation into one call. The surface is thin, but that reflects the deliberate scope rather than missing structure.
Both tools expose rich, self-contained outputs (pillars, canons, calibrated diff; primary/nuclear/changed hexagrams, six relatives, hidden spirits, Zhouyi texts), covering the core lifecycle of each engine. Minor gaps exist, such as luck-pillar/liunian cycles for Bazi or hexagram lookup/auxiliary reference tools.