bazi-core

一个可解释、可追溯的 TypeScript 八字计算与规则分析引擎。

bazi-core 负责把中国标准时间的公历输入转换为四柱，并提供季节环境、藏干十神、根气、干支关系、旺衰、大运、流年等结构化结果。重要结果会公开实际采用的规则、推导过程和能力边界。

它不会用伪精确的五行百分比包装结论，也不会把合、冲、刑、害直接解释成吉凶或具体人生事件。

设计原则

• 计算与解释分离：历法、四柱和时间线属于计算层；十神、根气和干支关系属于事实层；旺衰或未来的流派判断属于解释层。
• 规则显式可追溯：重要结果保留 model、appliedRules、trace 和 warnings。
• 旧模型保持稳定：新增规则通过新的模型版本演进，不静默修改已有 *-v1、*-v2 的含义。

安装

npm install bazi-core

包内同时包含 ESM、CommonJS、TypeScript 类型声明和完整 src/ 源码，具体规则可以直接审查。

应该使用哪个 API

| 需求 | API | 主要结果 | | --- | --- | --- | | 出生时间排完整八字 | calculateBazi | 四柱、藏干、十神、季节、关系、根气、旺衰 | | 计算起运和十年大运 | calculateLuckCycles | 顺逆、起运年龄、交运时间、大运时间线 | | 分析大运与原局关系 | analyzeLuckCycles | 每步大运的十神、根气、十二长生、合克刑冲害事实 | | 生成流年时间线 | calculateAnnualCycles | 按立春分段的流年干支及精确起止时间 | | 已知四柱，直接分析 | calculateFromPillars | 标准化命盘、关系、根气、旺衰 v1/v2 | | 已知四柱，只算旺衰 | analyzePillars / analyzePillarsV2 | 指定版本的旺衰分析结果 |

detectPillarRelations、detectPillarRoots、getTenGod、getTwelveGrowthStage 等底层函数也可以独立使用。

快速开始：完整排盘

import { calculateBazi } from 'bazi-core';

const birthInput = {
  civilTime: {
    year: 1995,
    month: 1,
    day: 21,
    hour: 11,
    minute: 30,
  },
};

const result = calculateBazi(birthInput);

console.log(
  Object.values(result.pillars).map((pillar) => pillar.ganZhi),
);
// ['甲戌', '丁丑', '壬子', '丙午']

console.log(result.dayMaster);               // 日主
console.log(result.pillars);                 // 完整四柱、五行、十神和藏干
console.log(result.seasonContext);           // 节气、十二长生、旺相休囚死
console.log(result.relations);               // 原局天干合克、地支刑冲合害
console.log(result.roots);                   // 根气位置和本中余气层级
console.log(result.analysis);                // ziping-strength-v1
console.log(result.analysisV2);              // ziping-strength-v2
console.log(result.appliedRules);            // 本次采用的规则
console.log(result.trace);                   // 从时间到结果的推导链
console.log(result.warnings);                // 当前模型边界

输入是中国标准时间 UTC+08:00 的公历民用时间组件，不接收容易产生时区歧义的 JavaScript Date。

选择换日规则

const result = calculateBazi(
  {
    civilTime: {
      year: 2024,
      month: 2,
      day: 10,
      hour: 23,
      minute: 30,
    },
  },
  {
    // 默认 midnight，即 00:00 换日；zi-hour 表示 23:00 换日
    dayBoundary: 'zi-hour',
  },
);

起运与十年大运

import { calculateLuckCycles } from 'bazi-core';

const luckCycles = calculateLuckCycles(birthInput, {
  // 只用于所选传统顺逆规则，不改变出生四柱
  sexForRule: 'male',
  cycleCount: 8,
});

console.log(luckCycles.sourcePillars);       // 原局四柱的简洁干支形式
console.log(luckCycles.direction);           // forward
console.log(luckCycles.directionReason);     // 为什么顺排
console.log(luckCycles.boundaryTerm);        // 起运采用的节令和距离
console.log(luckCycles.startAge);            // 起运年龄
console.log(luckCycles.startsAt);            // 精确交运时间
console.log(luckCycles.cycles[0]);           // 第一步十年大运

不使用年干阴阳与性别定顺逆的传统规则时，可以直接指定方向：

const luckCycles = calculateLuckCycles(birthInput, {
  direction: 'reverse',
});

luck-cycle-v1 只计算时间和干支，不判断某一步是不是好运。完整规则见 docs/luck-cycle.md。

大运与原局关系事实

import { analyzeLuckCycles } from 'bazi-core';

const luckAnalysis = analyzeLuckCycles(birthInput, {
  sexForRule: 'male',
  cycleCount: 8,
});

console.log(luckAnalysis.sourcePillars);
// { year: '甲戌', month: '丁丑', day: '壬子', hour: '丙午' }

console.log(luckAnalysis.dayMaster);
// { stem: '壬', element: 'water', yinYang: 'yang' }

const first = luckAnalysis.cycles[0];
console.log(first.cycle);                    // 戊寅大运的年龄与时间区间
console.log(first.stem.tenGod);              // 七杀
console.log(first.branch.hiddenStems);       // 寅支藏干及其十神
console.log(first.branch.twelveGrowth);      // 壬在寅的十二长生
console.log(first.branch.root);              // 寅支是否给壬水增加同五行根气
console.log(first.relations.stems);          // 大运干与原局四干的合克
console.log(first.relations.branches);       // 大运支参与的合冲刑害

luck-analysis-v1 只输出当前大运参与的结构化关系：

• 天干五合与有方向的相克；
• 地支六合、完整三合、六冲、六害、子卯刑、自刑和完整三刑；
• 合化只标记 candidate-only，不表示已经化成目标五行；
• 不删除原局干支，不修改原局旺衰，不生成吉凶或事件断语。

完整规则见 docs/luck-analysis.md。

pillars 与 sourcePillars 的区别

calculateBazi().pillars 是完整结构，每一柱都包含天干、地支、五行、阴阳、十神和藏干。

calculateLuckCycles().sourcePillars 和 analyzeLuckCycles().sourcePillars 是大运计算所依据的原局四柱，使用简洁的干支字符串：

{
  "year": "甲戌",
  "month": "丁丑",
  "day": "壬子",
  "hour": "丙午"
}

如果一个业务页面同时需要完整命盘和大运关系，可以分别调用：

const chart = calculateBazi(birthInput);
const luck = analyzeLuckCycles(birthInput, {
  sexForRule: 'male',
  cycleCount: 8,
});

两个 API 使用相同的四柱历法核心，大运结果中的 sourcePillars 可用于核对原局来源。

流年时间线

import { calculateAnnualCycles } from 'bazi-core';

const annualCycles = calculateAnnualCycles({
  fromYear: 2024,
  toYear: 2026,
});

console.log(annualCycles.cycles.map((cycle) => cycle.ganZhi));
// ['甲辰', '乙巳', '丙午']

console.log(annualCycles.cycles[0]);
// {
//   index: 1,
//   anchorYear: 2024,
//   ganZhi: '甲辰',
//   startsAt: '2024-02-04T16:27:07+08:00',
//   endsAt: '2025-02-03T22:10:28+08:00'
// }

每个流年采用 [本年立春, 次年立春) 区间，不以公历元旦或农历正月初一换年。annual-cycle-v1 不判断流年吉凶，完整规则见 docs/annual-cycle.md。

已知四柱时直接分析

import {
  analyzePillars,
  analyzePillarsV2,
  calculateFromPillars,
} from 'bazi-core';

const pillars = {
  year: '庚午',
  month: '辛巳',
  day: '壬午',
  hour: '丁未',
};

const analysisV1 = analyzePillars(pillars);
const analysisV2 = analyzePillarsV2(pillars);

const result = calculateFromPillars(pillars);
console.log(result.chart);
console.log(result.relations);
console.log(result.roots);
console.log(result.analysis);
console.log(result.analysisV2);

纯四柱输入没有出生时刻，因此不能还原节气的精确秒级距离，但仍可根据月支计算季节状态和核心十二长生事实。

当前模型

| 模型 | 作用 | 详细规则 | | --- | --- | --- | | relations-v1 | 原局天干合克、地支刑冲合害事实 | docs/relations.md | | season-context-v1 | 节气距离、十二长生、旺相休囚死 | docs/season-context.md | | roots-v1 | 日主同五行藏干及根气位置 | docs/roots.md | | ziping-strength-v1 | 保留的首版旺衰模型 | docs/algorithm.md | | ziping-strength-v2 | 显式组合季节、根气和关系事实 | docs/algorithm-v2.md | | luck-cycle-v1 | 起运与十年大运时间线 | docs/luck-cycle.md | | luck-analysis-v1 | 大运与原局关系事实 | docs/luck-analysis.md | | annual-cycle-v1 | 按立春分段的流年时间线 | docs/annual-cycle.md |

可追溯结果的常见字段

• model：本次结果采用的版本化模型；
• appliedRules：实际启用的历法或分析口径；
• trace：机器可读的输入、规则与输出推导链；
• warnings：未建模、存在流派差异或不应过度解释的边界；
• candidateElement：传统合局中的候选化行，不表示合化成功；
• 时间区间统一使用前闭后开 [startsAt, endsAt)。

当前边界

• 只接受中国标准时间的公历民用时间；
• 不计算经度修正、真太阳时和夏令时；
• 年柱以立春换年，月柱以十二“节”换月；
• 不自动判断从格、专旺、化气、假从、调候和用神；
• 不把合、冲、刑、害自动换算成吉凶；
• 不生成性格、婚恋、财运、健康或具体事件断语；
• 旺衰只是公开规则模型的结果，不是科学预测，也不应代替现实决策。

历法边界回归向量覆盖立春换年、节换月、两种子时换日、闰日和年末场景，维护规则见 docs/testing.md。

开发

npm install
npm run check

npm run check 会依次执行严格类型检查、完整 Vitest 测试，并构建 ESM、CommonJS 和 .d.ts 类型声明。

发布前检查

1. 检查 package.json 中的版本、作者、许可和发布配置；
2. 执行 npm whoami 确认当前 npm 账号；
3. 执行 npm run check；
4. 执行 npm pack --dry-run，检查压缩包内容；
5. 在临时项目中分别验证 ESM、CommonJS 和类型声明；
6. 确认目标版本未发布后，执行 npm publish --access public。

许可

本项目使用 MIT License。历法部分依赖同为 MIT 许可的 lunar-typescript，详见 THIRD_PARTY_NOTICES.md。

版本变更见 CHANGELOG.md。