type FiveElement = 'wood' | 'fire' | 'earth' | 'metal' | 'water'; type YinYang = 'yang' | 'yin'; type HeavenlyStemName = '甲' | '乙' | '丙' | '丁' | '戊' | '己' | '庚' | '辛' | '壬' | '癸'; type EarthlyBranchName = '子' | '丑' | '寅' | '卯' | '辰' | '巳' | '午' | '未' | '申' | '酉' | '戌' | '亥'; type TenGod = '比肩' | '劫财' | '食神' | '伤官' | '偏财' | '正财' | '七杀' | '正官' | '偏印' | '正印'; type Relation = 'companion' | 'resource' | 'output' | 'wealth' | 'officer'; interface CivilTime { year: number; month: number; day: number; hour?: number; minute?: number; second?: number; } type DayBoundary = 'midnight' | 'zi-hour'; interface CalculateBaziOptions { /** * midnight: 00:00 换日;zi-hour: 23:00 换日。 * 默认 midnight。 */ dayBoundary?: DayBoundary; } interface BaziInput { /** 中国标准时间(UTC+08:00)的当地民用时间,不接受 JavaScript Date。 */ civilTime: CivilTime; } interface HeavenlyStem { name: HeavenlyStemName; element: FiveElement; yinYang: YinYang; tenGod: TenGod | '日主'; } type HiddenStemOrder = 'main' | 'middle' | 'residual'; interface HiddenStem extends HeavenlyStem { order: HiddenStemOrder; } interface EarthlyBranch { name: EarthlyBranchName; element: FiveElement; hiddenStems: HiddenStem[]; } type PillarKey = 'year' | 'month' | 'day' | 'hour'; interface Pillar { key: PillarKey; ganZhi: string; stem: HeavenlyStem; branch: EarthlyBranch; } interface FourPillarsInput { year: string; month: string; day: string; hour: string; } interface DayMaster { stem: HeavenlyStemName; element: FiveElement; yinYang: YinYang; } interface StemRelationMember { pillar: PillarKey; position: 'stem'; value: HeavenlyStemName; } interface BranchRelationMember { pillar: PillarKey; position: 'branch'; value: EarthlyBranchName; } interface StemCombinationRelation { id: string; type: 'stem-combination'; subtype: 'five-combination'; members: [StemRelationMember, StemRelationMember]; candidateElement: FiveElement; description: string; } interface StemControlRelation { id: string; type: 'stem-control'; members: [StemRelationMember, StemRelationMember]; controller: StemRelationMember; controlled: StemRelationMember; description: string; } type StemChartRelation = StemCombinationRelation | StemControlRelation; interface BranchSixCombinationRelation { id: string; type: 'branch-six-combination'; members: [BranchRelationMember, BranchRelationMember]; candidateElement: FiveElement; description: string; } interface BranchThreeCombinationRelation { id: string; type: 'branch-three-combination'; members: [BranchRelationMember, BranchRelationMember, BranchRelationMember]; candidateElement: FiveElement; description: string; } interface BranchClashRelation { id: string; type: 'branch-clash'; members: [BranchRelationMember, BranchRelationMember]; description: string; } interface BranchHarmRelation { id: string; type: 'branch-harm'; members: [BranchRelationMember, BranchRelationMember]; description: string; } interface BranchPunishmentRelation { id: string; type: 'branch-punishment'; subtype: 'mutual' | 'triple' | 'self'; pattern: 'zi-mao' | 'yin-si-shen' | 'chou-xu-wei' | 'self'; members: BranchRelationMember[]; description: string; } type BranchChartRelation = BranchSixCombinationRelation | BranchThreeCombinationRelation | BranchClashRelation | BranchHarmRelation | BranchPunishmentRelation; interface ChartRelations { model: 'relations-v1'; stems: StemChartRelation[]; branches: BranchChartRelation[]; } interface RootPosition { pillar: PillarKey; branch: EarthlyBranchName; hiddenStem: HeavenlyStemName; order: HiddenStemOrder; source: string; } interface RootsContext { model: 'roots-v1'; dayMaster: DayMaster; hasRoot: boolean; roots: RootPosition[]; } type SolarTermKind = 'jie' | 'qi'; interface SolarTermDistance { name: string; kind: SolarTermKind; at: string; direction: 'previous' | 'next'; distanceSeconds: number; } interface SolarTermContext { /** 前后相邻的二十四节气。 */ previous: SolarTermDistance; next: SolarTermDistance; /** 前后相邻的十二节;八字月柱以此为边界。 */ previousMonthBoundary: SolarTermDistance; nextMonthBoundary: SolarTermDistance; } type TwelveGrowthStage = 'changsheng' | 'muyu' | 'guandai' | 'linguan' | 'diwang' | 'shuai' | 'bing' | 'si' | 'mu' | 'jue' | 'tai' | 'yang'; type TwelveGrowthLabel = '长生' | '沐浴' | '冠带' | '临官' | '帝旺' | '衰' | '病' | '死' | '墓' | '绝' | '胎' | '养'; interface TwelveGrowthPosition { pillar: PillarKey; branch: EarthlyBranchName; stage: TwelveGrowthStage; stageLabel: TwelveGrowthLabel; } interface TwelveGrowthContext { subject: DayMaster; direction: 'forward' | 'reverse'; byPillar: Record; } type FourSeason = 'spring' | 'summer' | 'autumn' | 'winter'; type SeasonalState = 'wang' | 'xiang' | 'xiu' | 'qiu' | 'si'; type SeasonalStateLabel = '旺' | '相' | '休' | '囚' | '死'; interface ElementSeasonalState { state: SeasonalState; stateLabel: SeasonalStateLabel; } interface SeasonalStatesContext { basis: 'month-branch-four-season'; monthBranch: EarthlyBranchName; season: FourSeason; seasonLabel: '春' | '夏' | '秋' | '冬'; byElement: Record; } interface SeasonContextRules { solarTermProvider: 'lunar-typescript'; solarTermPrecision: 'second'; monthBoundaryTerms: 'jie'; twelveGrowth: 'ten-stem-yang-forward-yin-reverse'; seasonalStates: 'four-season-wang-xiang-xiu-qiu-si'; earthTransition: 'not-modeled'; } interface SeasonContext { model: 'season-context-v1'; solarTerms: SolarTermContext; twelveGrowth: TwelveGrowthContext; seasonalStates: SeasonalStatesContext; appliedRules: SeasonContextRules; warnings: string[]; } type EvidenceCategory = 'season' | 'root' | 'support' | 'pressure'; type EvidenceSide = 'supporting' | 'opposing'; type EvidenceImpact = 'major' | 'moderate' | 'minor'; interface StrengthEvidence { id: string; category: EvidenceCategory; relation: Relation; side: EvidenceSide; impact: EvidenceImpact; /** 仅用于公开、确定性的分档决策,不表示五行百分比。 */ decisionUnits: 1 | 2 | 3; source: string; description: string; } type StrengthState = 'extremely-weak' | 'weak' | 'balanced' | 'strong' | 'extremely-strong'; type Confidence = 'low' | 'medium' | 'high'; interface DecisionBalance { supporting: number; opposing: number; delta: number; thresholds: { extremelyStrong: number; strong: number; weak: number; extremelyWeak: number; }; } interface SpecialPatternReview { status: 'not-indicated' | 'review-required'; candidate: 'following-strong' | 'following-weak' | null; reason: string; } interface StrengthAnalysis { status: 'completed' | 'needs-special-pattern-review'; strength: StrengthState; strengthLabel: '极弱' | '偏弱' | '相对中和' | '偏强' | '极强'; confidence: Confidence; dayMaster: DayMaster; supportingElements: FiveElement[]; opposingElements: FiveElement[]; evidence: StrengthEvidence[]; decisionBalance: DecisionBalance; specialPattern: SpecialPatternReview; } type StrengthV2SourceModel = 'chart' | 'season-context-v1' | 'relations-v1' | 'roots-v1'; type StrengthV2EvidenceCategory = 'seasonal-state' | 'twelve-growth' | 'solar-term-distance' | 'visible-stem' | 'hidden-stem' | 'root' | 'stem-control' | 'root-clash' | 'relation-observation'; interface StrengthV2Evidence { id: string; ruleId: string; category: StrengthV2EvidenceCategory; sourceModels: StrengthV2SourceModel[]; sources: string[]; side: EvidenceSide | 'neutral'; applied: boolean; /** 仅用于公开、确定性的 v2 分档决策,不表示五行百分比。 */ decisionUnits: number; description: string; } interface StrengthV2Analysis { model: 'ziping-strength-v2'; status: 'completed' | 'needs-special-pattern-review'; strength: StrengthState; strengthLabel: StrengthAnalysis['strengthLabel']; confidence: Confidence; dayMaster: DayMaster; supportingElements: FiveElement[]; opposingElements: FiveElement[]; evidence: StrengthV2Evidence[]; decisionBalance: DecisionBalance; specialPattern: SpecialPatternReview; warnings: string[]; } interface StrengthV2Facts { seasonContext?: SeasonContext; relations?: ChartRelations; roots?: RootsContext; } type LuckCycleDirection = 'forward' | 'reverse'; type LuckCycleSexForRule = 'male' | 'female'; type LuckCycleDirectionRule = 'explicit' | 'year-stem-and-sex'; type LuckCycleBoundaryRule = 'jie'; type LuckCycleStartAgeRule = 'three-days-one-year'; interface CalculateLuckCyclesOptions { /** 与原局排盘一致,默认 00:00 换日。 */ dayBoundary?: DayBoundary; /** 直接指定顺排或逆排;提供后优先于 sexForRule。 */ direction?: LuckCycleDirection; /** 仅用于 year-stem-and-sex 传统顺逆规则,不改变出生四柱。 */ sexForRule?: LuckCycleSexForRule; /** 首版只支持以年干阴阳和 sexForRule 定顺逆。 */ directionRule?: 'year-stem-and-sex'; /** 首版只使用十二“节”作为起运边界。 */ boundaryRule?: LuckCycleBoundaryRule; /** 首版只支持“三天一岁”的起运换算。 */ startAgeRule?: LuckCycleStartAgeRule; /** 返回多少步十年大运,默认 10。 */ cycleCount?: number; } interface LuckCycleAgeOffset { years: number; months: number; days: number; hours: number; minutes: number; } interface LuckCyclePeriod { index: number; ganZhi: string; startsAt: string; endsAt: string; startAge: LuckCycleAgeOffset; endAge: LuckCycleAgeOffset; } interface BeforeFirstLuckCycle { label: '起运前'; startsAt: string; endsAt: string; } interface LuckCycleAppliedRules { calendar: 'solar'; timeStandard: 'china-standard-time'; dayBoundary: DayBoundary; directionRule: LuckCycleDirectionRule; boundaryRule: LuckCycleBoundaryRule; startAgeRule: LuckCycleStartAgeRule; cycleLengthYears: 10; cycleInterval: 'start-inclusive-end-exclusive'; solarTermProvider: 'lunar-typescript'; solarTermPrecision: 'second'; } interface LuckCycleResult { model: 'luck-cycle-v1'; input: { civilTime: Required; sexForRule?: LuckCycleSexForRule; }; sourcePillars: FourPillarsInput; direction: LuckCycleDirection; directionReason: string; boundaryTerm: SolarTermDistance; startAge: LuckCycleAgeOffset; startsAt: string; beforeStart: BeforeFirstLuckCycle; cycles: LuckCyclePeriod[]; appliedRules: LuckCycleAppliedRules; trace: TraceStep[]; warnings: string[]; } type LuckAnalysisPillarKey = PillarKey | 'luck'; interface LuckAnalysisStemMember { source: 'natal' | 'luck'; pillar: LuckAnalysisPillarKey; position: 'stem'; value: HeavenlyStemName; } interface LuckAnalysisBranchMember { source: 'natal' | 'luck'; pillar: LuckAnalysisPillarKey; position: 'branch'; value: EarthlyBranchName; } interface LuckAnalysisStemCombinationRelation { id: string; type: 'stem-combination'; subtype: 'five-combination'; members: [LuckAnalysisStemMember, LuckAnalysisStemMember]; candidateElement: FiveElement; transformationStatus: 'candidate-only'; description: string; } interface LuckAnalysisStemControlRelation { id: string; type: 'stem-control'; members: [LuckAnalysisStemMember, LuckAnalysisStemMember]; controller: LuckAnalysisStemMember; controlled: LuckAnalysisStemMember; description: string; } type LuckAnalysisStemRelation = LuckAnalysisStemCombinationRelation | LuckAnalysisStemControlRelation; interface LuckAnalysisBranchSixCombinationRelation { id: string; type: 'branch-six-combination'; members: [LuckAnalysisBranchMember, LuckAnalysisBranchMember]; candidateElement: FiveElement; transformationStatus: 'candidate-only'; description: string; } interface LuckAnalysisBranchThreeCombinationRelation { id: string; type: 'branch-three-combination'; members: [ LuckAnalysisBranchMember, LuckAnalysisBranchMember, LuckAnalysisBranchMember ]; candidateElement: FiveElement; transformationStatus: 'candidate-only'; description: string; } interface LuckAnalysisBranchClashRelation { id: string; type: 'branch-clash'; members: [LuckAnalysisBranchMember, LuckAnalysisBranchMember]; description: string; } interface LuckAnalysisBranchHarmRelation { id: string; type: 'branch-harm'; members: [LuckAnalysisBranchMember, LuckAnalysisBranchMember]; description: string; } interface LuckAnalysisBranchPunishmentRelation { id: string; type: 'branch-punishment'; subtype: 'mutual' | 'triple' | 'self'; pattern: 'zi-mao' | 'yin-si-shen' | 'chou-xu-wei' | 'self'; members: LuckAnalysisBranchMember[]; description: string; } type LuckAnalysisBranchRelation = LuckAnalysisBranchSixCombinationRelation | LuckAnalysisBranchThreeCombinationRelation | LuckAnalysisBranchClashRelation | LuckAnalysisBranchHarmRelation | LuckAnalysisBranchPunishmentRelation; interface LuckAnalysisStem { name: HeavenlyStemName; element: FiveElement; yinYang: YinYang; tenGod: TenGod; } interface LuckAnalysisHiddenStem extends LuckAnalysisStem { order: HiddenStemOrder; } interface LuckAnalysisRootFact { hiddenStem: HeavenlyStemName; order: HiddenStemOrder; source: string; } interface LuckAnalysisBranch { name: EarthlyBranchName; element: FiveElement; hiddenStems: LuckAnalysisHiddenStem[]; twelveGrowth: { stage: TwelveGrowthStage; stageLabel: TwelveGrowthLabel; }; root: { hasRoot: boolean; roots: LuckAnalysisRootFact[]; }; } interface LuckAnalysisPeriod { cycle: LuckCyclePeriod; stem: LuckAnalysisStem; branch: LuckAnalysisBranch; relations: { stems: LuckAnalysisStemRelation[]; branches: LuckAnalysisBranchRelation[]; }; } interface LuckAnalysisAppliedRules { luckCycleModel: 'luck-cycle-v1'; relationsModel: 'luck-to-natal-relations-v1'; tenGod: 'day-master-relative'; twelveGrowth: 'ten-stem-yang-forward-yin-reverse'; root: 'same-element-hidden-stem'; tripleRelations: 'complete-only'; transformations: 'candidate-only'; interpretation: 'none'; } interface LuckAnalysisResult { model: 'luck-analysis-v1'; input: LuckCycleResult['input']; sourcePillars: FourPillarsInput; dayMaster: DayMaster; direction: LuckCycleDirection; directionReason: string; startsAt: string; cycles: LuckAnalysisPeriod[]; appliedRules: LuckAnalysisAppliedRules; trace: TraceStep[]; warnings: string[]; } interface CalculateAnnualCyclesInput { /** 按公历年编号选择起始流年,包含该年。 */ fromYear: number; /** 按公历年编号选择结束流年,包含该年。 */ toYear: number; } interface AnnualCyclePeriod { index: number; /** 该流年立春所在的公历年。 */ anchorYear: number; ganZhi: string; startsAt: string; endsAt: string; } interface AnnualCycleAppliedRules { calendarInput: 'gregorian-year-range'; timeStandard: 'china-standard-time'; yearBoundary: 'beginning-of-spring'; cycleInterval: 'start-inclusive-end-exclusive'; solarTermProvider: 'lunar-typescript'; solarTermPrecision: 'second'; } interface AnnualCycleResult { model: 'annual-cycle-v1'; input: CalculateAnnualCyclesInput; cycles: AnnualCyclePeriod[]; appliedRules: AnnualCycleAppliedRules; trace: TraceStep[]; warnings: string[]; } interface AppliedRules { calendar: 'solar'; timeStandard: 'china-standard-time'; yearBoundary: 'beginning-of-spring'; monthBoundary: 'major-solar-terms'; dayBoundary: DayBoundary; seasonContextModel: 'season-context-v1'; relationsModel: 'relations-v1'; rootsModel: 'roots-v1'; strengthModel: 'ziping-strength-v1'; strengthV2Model: 'ziping-strength-v2'; specialPatterns: 'flag-only'; } interface TraceStep { ruleId: string; description: string; input: Record; output: Record; } interface BaziChart { pillars: { year: Pillar; month: Pillar; day: Pillar; hour: Pillar; }; dayMaster: DayMaster; } interface BaziResult extends BaziChart { input: { civilTime: Required; }; seasonContext: SeasonContext; relations: ChartRelations; roots: RootsContext; analysis: StrengthAnalysis; analysisV2: StrengthV2Analysis; appliedRules: AppliedRules; trace: TraceStep[]; warnings: string[]; } declare function createChart(pillars: FourPillarsInput): BaziChart; declare function analyzeChart(chart: BaziChart): StrengthAnalysis; declare function analyzePillars(pillars: FourPillarsInput): StrengthAnalysis; declare function analyzeChartV2(chart: BaziChart, facts?: StrengthV2Facts): StrengthV2Analysis; declare function analyzePillarsV2(pillars: FourPillarsInput): StrengthV2Analysis; declare function calculateAnnualCycles(input: CalculateAnnualCyclesInput): AnnualCycleResult; declare function detectRelations(chart: BaziChart): ChartRelations; declare function detectPillarRelations(pillars: FourPillarsInput): ChartRelations; declare function detectRoots(chart: BaziChart): RootsContext; declare function detectPillarRoots(pillars: FourPillarsInput): RootsContext; declare function analyzeLuckCycles(input: BaziInput, options: CalculateLuckCyclesOptions): LuckAnalysisResult; declare function convertThreeDaysToOneYear(distanceSeconds: number): LuckCycleAgeOffset; declare function calculateLuckCycles(input: BaziInput, options: CalculateLuckCyclesOptions): LuckCycleResult; declare function getElementRelation(dayMaster: FiveElement, other: FiveElement): Relation; declare function isSupportingRelation(relation: Relation): boolean; declare function getTenGod(dayStem: HeavenlyStemName, otherStem: HeavenlyStemName): TenGod; declare function getTwelveGrowthStage(stem: HeavenlyStemName, branch: EarthlyBranchName): { stage: TwelveGrowthStage; stageLabel: TwelveGrowthLabel; }; declare function getSeasonalStates(monthBranch: EarthlyBranchName): SeasonalStatesContext; declare function calculateSeasonContext(civilTime: Required, chart: BaziChart): SeasonContext; declare const BAZI_CORE_VERSION = "0.8.0"; declare function calculateBazi(input: BaziInput, options?: CalculateBaziOptions): BaziResult; declare function calculateFromPillars(pillars: FourPillarsInput): { chart: ReturnType; relations: ChartRelations; roots: RootsContext; analysis: StrengthAnalysis; analysisV2: StrengthV2Analysis; }; export { type AnnualCycleAppliedRules, type AnnualCyclePeriod, type AnnualCycleResult, type AppliedRules, BAZI_CORE_VERSION, type BaziChart, type BaziInput, type BaziResult, type BeforeFirstLuckCycle, type BranchChartRelation, type BranchClashRelation, type BranchHarmRelation, type BranchPunishmentRelation, type BranchRelationMember, type BranchSixCombinationRelation, type BranchThreeCombinationRelation, type CalculateAnnualCyclesInput, type CalculateBaziOptions, type CalculateLuckCyclesOptions, type ChartRelations, type CivilTime, type Confidence, type DayBoundary, type DayMaster, type DecisionBalance, type EarthlyBranch, type EarthlyBranchName, type ElementSeasonalState, type EvidenceCategory, type EvidenceImpact, type EvidenceSide, type FiveElement, type FourPillarsInput, type FourSeason, type HeavenlyStem, type HeavenlyStemName, type HiddenStem, type HiddenStemOrder, type LuckAnalysisAppliedRules, type LuckAnalysisBranch, type LuckAnalysisBranchClashRelation, type LuckAnalysisBranchHarmRelation, type LuckAnalysisBranchMember, type LuckAnalysisBranchPunishmentRelation, type LuckAnalysisBranchRelation, type LuckAnalysisBranchSixCombinationRelation, type LuckAnalysisBranchThreeCombinationRelation, type LuckAnalysisHiddenStem, type LuckAnalysisPeriod, type LuckAnalysisPillarKey, type LuckAnalysisResult, type LuckAnalysisRootFact, type LuckAnalysisStem, type LuckAnalysisStemCombinationRelation, type LuckAnalysisStemControlRelation, type LuckAnalysisStemMember, type LuckAnalysisStemRelation, type LuckCycleAgeOffset, type LuckCycleAppliedRules, type LuckCycleBoundaryRule, type LuckCycleDirection, type LuckCycleDirectionRule, type LuckCyclePeriod, type LuckCycleResult, type LuckCycleSexForRule, type LuckCycleStartAgeRule, type Pillar, type PillarKey, type Relation, type RootPosition, type RootsContext, type SeasonContext, type SeasonContextRules, type SeasonalState, type SeasonalStateLabel, type SeasonalStatesContext, type SolarTermContext, type SolarTermDistance, type SolarTermKind, type SpecialPatternReview, type StemChartRelation, type StemCombinationRelation, type StemControlRelation, type StemRelationMember, type StrengthAnalysis, type StrengthEvidence, type StrengthState, type StrengthV2Analysis, type StrengthV2Evidence, type StrengthV2EvidenceCategory, type StrengthV2Facts, type StrengthV2SourceModel, type TenGod, type TraceStep, type TwelveGrowthContext, type TwelveGrowthLabel, type TwelveGrowthPosition, type TwelveGrowthStage, type YinYang, analyzeChart, analyzeChartV2, analyzeLuckCycles, analyzePillars, analyzePillarsV2, calculateAnnualCycles, calculateBazi, calculateFromPillars, calculateLuckCycles, calculateSeasonContext, convertThreeDaysToOneYear, createChart, detectPillarRelations, detectPillarRoots, detectRelations, detectRoots, getElementRelation, getSeasonalStates, getTenGod, getTwelveGrowthStage, isSupportingRelation };