dsh-metaphysics 0.17.1 → 0.18.0

package/engine/almanac.js

@@ -0,0 +1,215 @@
+// 每日黄历（本地确定性 · 通行简表口径）
+//
+// 提供：农历日期、年/月/日干支（年按立春界，另列春节界生肖）、节气、建除十二神、
+// 冲煞（冲什么生肖 / 煞在何方）、财神与喜神方位、建除简表宜忌、每日一卦。
+//
+// 诚实边界：本插件不依赖 lunar-javascript，逐日神煞（吉神凶煞）、二十八宿值日、
+// 彭祖百忌、胎神等全量黄历数据未收录——输出里如实标注「未收录」，不臆造。
+// 宜忌只按「建除十二神」通行简表给出（传统择日的第一层判据），不是逐日全量黄历。
+import { solarToLunar } from './lunar.js';
+import {
+  toJDN, fromJDN, dayGanzhiIndex, ganzhiName, termWindow, termInstantJd, partsToJd, STEMS, BRANCHES, TERM_NAMES,
+} from './calendar.js';
+import { HEX64 } from './interpret-data.js';
+import { assertCivil, daysInMonth } from './validate.js';
+
+/** 建除十二神（按日支相对月支顺数）。 */
+export const ZHIXING = ['建', '除', '满', '平', '定', '执', '破', '危', '成', '收', '开', '闭'];
+
+/** 建除十二神宜忌（通行简表；传统黄历在此基础上再叠神煞与宿值）。 */
+export const ZHIXING_YI = {
+  建: ['出行', '上任', '会友', '上书', '见工'],
+  除: ['除服', '疗病', '扫舍', '出行'],
+  满: ['祈福', '祭祀', '结亲', '开市', '交易'],
+  平: ['修饰垣墙', '平治道涂'],
+  定: ['嫁娶', '订盟', '纳采', '祭祀', '祈福'],
+  执: ['祭祀', '祈福', '捕捉', '纳畜'],
+  破: ['破屋', '坏垣', '求医'],
+  危: ['祭祀', '祈福', '安床'],
+  成: ['嫁娶', '开市', '入学', '上任', '修造'],
+  收: ['纳财', '收账', '进人口'],
+  开: ['开市', '交易', '嫁娶', '入学', '动土'],
+  闭: ['筑堤', '埋穴', '补垣'],
+};
+
+export const ZHIXING_JI = {
+  建: ['动土', '开仓', '出货财', '安葬'],
+  除: ['求财', '赴任', '嫁娶'],
+  满: ['服药', '栽种', '安葬'],
+  平: ['祈福', '求嗣'],
+  定: ['诉讼', '出行'],
+  执: ['开市', '求财', '出行'],
+  破: ['嫁娶', '开市', '动土'],
+  危: ['登高', '行船', '出行'],
+  成: ['诉讼'],
+  收: ['开市', '出行', '安葬'],
+  开: ['安葬'],
+  闭: ['开市', '出行', '求医'],
+};
+
+/** 财神方位歌（按日干）。 */
+const CAI_SHEN = { 甲: '东北', 乙: '东北', 丙: '西南', 丁: '西南', 戊: '正北', 己: '正北', 庚: '正东', 辛: '正东', 壬: '正南', 癸: '正南' };
+
+/** 喜神方位（通行口诀，按日干）。 */
+const XI_SHEN = { 甲: '东北', 乙: '西北', 丙: '西南', 丁: '正南', 戊: '东南', 己: '东北', 庚: '西北', 辛: '西南', 壬: '正南', 癸: '东南' };
+
+/** 日支 → 冲的生肖 + 煞方（传统：申子辰煞南、寅午戌煞北、巳酉丑煞东、亥卯未煞西）。 */
+export const SHENGXIAO = ['鼠', '牛', '虎', '兔', '龙', '蛇', '马', '羊', '猴', '鸡', '狗', '猪'];
+const SHA_BY_GROUP = { 申子辰: '南', 寅午戌: '北', 巳酉丑: '东', 亥卯未: '西' };
+function shaOf(branch) {
+  for (const [g, v] of Object.entries(SHA_BY_GROUP)) if (g.includes(branch)) return v;
+  return null;
+}
+
+/** 24 小时制 → 时辰地支。 */
+export function hourToBranch(hour, minute = 0) {
+  const h = Number.isInteger(hour) ? ((hour % 24) + 24) % 24 : 12;
+  // 子时 23:00–00:59；分钟不改变时辰（真太阳时已在调用方处理）
+  return BRANCHES[Math.floor(((h + 1) % 24) / 2)];
+}
+
+/** 由日支与月支推建除十二神。 */
+export function zhixingOf(dayBranch, monthBranch) {
+  const d = BRANCHES.indexOf(dayBranch);
+  const m = BRANCHES.indexOf(monthBranch);
+  return ZHIXING[((d - m) % 12 + 12) % 12];
+}
+
+/** 农历月/日中文。 */
+const MONTH_TEXT = ['正', '二', '三', '四', '五', '六', '七', '八', '九', '十', '冬', '腊'];
+const DAY_TENS = ['初', '十', '廿'];
+const DAY_UNITS = ['十', '一', '二', '三', '四', '五', '六', '七', '八', '九'];
+function dayText(day) {
+  if (day === 10) return '初十';
+  if (day === 20) return '二十';
+  if (day === 30) return '三十';
+  return `${DAY_TENS[Math.floor(day / 10)]}${DAY_UNITS[day % 10]}`;
+}
+export function lunarMonthText(month, isLeap = false) {
+  return `${isLeap ? '闰' : ''}${MONTH_TEXT[month - 1] || month}月`;
+}
+
+/** 每日一卦：日期哈希确定性映射到通行本 64 卦（同日同卦）。 */
+export function dailyHexagram(year, month, day) {
+  const names = Object.keys(HEX64);
+  if (!names.length) return null;
+  const seed = (((year * 10007) ^ (month * 911) ^ (day * 97)) >>> 0) % names.length;
+  const name = names[seed];
+  return { name, ...HEX64[name] };
+}
+
+/** 节气名（TERM_NAMES 与 termWindow 的 index 一一对应）。 */
+const termName = (t) => (t && (t.name || TERM_NAMES[t.index])) || '';
+
+/**
+ * 黄历主函数。
+ * @param {{year:number, month:number, day:number}} input 公历日期（必须真实存在）
+ */
+export function buildAlmanac(input) {
+  assertCivil(input, '黄历');
+  const { year, month, day } = input;
+  if (day > daysInMonth(year, month)) {
+    throw new Error(`非法日期：${year} 年 ${month} 月没有 ${day} 日`);
+  }
+  const jdNoon = partsToJd({ year, month, day, hour: 12, minute: 0 });
+  const lunar = solarToLunar(year, month, day);
+  const jdn = toJDN(year, month, day);
+
+  // 年柱：立春界；同时给出春节界口径
+  const lichunJd = termInstantJd(year, 2);
+  const ganzhiYear = jdNoon < lichunJd ? year - 1 : year;
+  const yearIdx = (((ganzhiYear - 4) % 60) + 60) % 60;
+  const yearGz = ganzhiName(yearIdx);
+  const springYear = lunar.lunarYear;
+  const springGz = ganzhiName((((springYear - 4) % 60) + 60) % 60);
+
+  // 月柱：以「节」为界
+  const jieTerms = termWindow(year, { jieOnly: true });
+  let prevJie = null;
+  let nextJie = null;
+  for (const t of jieTerms) {
+    if (t.jd <= jdNoon) prevJie = t; else { if (!nextJie) nextJie = t; }
+  }
+  const monthBranchIdx = ((2 + (prevJie.index - 2) / 2) % 12 + 12) % 12;
+  const yinMonthStem = ((STEMS.indexOf(yearGz.stem) % 5) * 2 + 2) % 10;
+  const monthStemIdx = (yinMonthStem + ((monthBranchIdx - 2 + 12) % 12)) % 10;
+  // 月柱干支按「天干地支同旬」组合：用 sexagenary 序推
+  const monthGz = ganzhiName(monthComposite(monthStemIdx, monthBranchIdx));
+
+  const dayGz = ganzhiName(dayGanzhiIndex(jdn));
+  const dayBranch = dayGz.branch;
+  const zhiXing = zhixingOf(dayBranch, BRANCHES[monthBranchIdx]);
+  const chongIdx = (BRANCHES.indexOf(dayBranch) + 6) % 12;
+  const chongShengXiao = SHENGXIAO[chongIdx];
+
+  const allTerms = termWindow(year);
+  let prevTerm = null;
+  let nextTerm = null;
+  for (const t of allTerms) {
+    if (t.jd <= jdNoon) prevTerm = t; else { if (!nextTerm) nextTerm = t; }
+  }
+  const fmtJdDate = (jd) => {
+    const p = fromJDN(Math.floor(jd + 0.5));
+    return `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`;
+  };
+
+  const weekday = ['日', '一', '二', '三', '四', '五', '六'][(jdn + 1) % 7];
+  const lunarText = `农历${springGz.name}年${lunarMonthText(lunar.month, lunar.isLeap)}${dayText(lunar.day)}`;
+  const boundaryNote = yearGz.name !== springGz.name
+    ? `年界：本条按立春界作${yearGz.name}年·属${SHENGXIAO[BRANCHES.indexOf(yearGz.branch)]}（命理排盘用）；春节界为${springGz.name}年·属${SHENGXIAO[BRANCHES.indexOf(springGz.branch)]}，两种都对，取用场合不同`
+    : null;
+
+  return {
+    system: 'almanac',
+    meta: {
+      date: `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`,
+      weekday: `星期${weekday}`,
+      ...(boundaryNote ? { boundaryNote } : {}),
+      scope: '通行简表口径：宜忌只按建除十二神；逐日神煞/二十八宿/彭祖百忌/胎神等全量黄历数据未收录',
+    },
+    lunar: {
+      year: springYear,
+      month: lunar.month,
+      day: lunar.day,
+      isLeap: lunar.isLeap,
+      text: lunarText,
+    },
+    ganzhi: {
+      year: yearGz.name,
+      month: monthGz.name,
+      day: dayGz.name,
+      shengXiao: SHENGXIAO[BRANCHES.indexOf(yearGz.branch)],
+      springYear: springGz.name,
+      springShengXiao: SHENGXIAO[BRANCHES.indexOf(springGz.branch)],
+    },
+    jieQi: {
+      prev: prevTerm ? { name: termName(prevTerm), date: fmtJdDate(prevTerm.jd) } : null,
+      next: nextTerm ? { name: termName(nextTerm), date: fmtJdDate(nextTerm.jd) } : null,
+    },
+    positions: { caiShen: CAI_SHEN[dayGz.stem] || null, xiShen: XI_SHEN[dayGz.stem] || null },
+    zhiXing,
+    yi: ZHIXING_YI[zhiXing].slice(),
+    ji: ZHIXING_JI[zhiXing].slice(),
+    chong: {
+      shengXiao: chongShengXiao,
+      text: `冲${chongShengXiao}`,
+      sha: shaOf(dayBranch) ? `煞${shaOf(dayBranch)}` : null,
+    },
+    dailyHexagram: dailyHexagram(year, month, day),
+    sources: [
+      '农历与节气：本地天文历法（定朔 + 节气黄经）',
+      '建除十二神与冲煞：传统通行口径',
+      '宜忌：建除十二神通行简表（非逐日全量黄历）',
+      '每日一卦：按公历日期确定性取卦（同日同卦）',
+    ],
+    disclaimer: '黄历为传统民俗口径的本地确定性计算；宜忌仅按建除简表，属娱乐参考，不构成择日结论。',
+  };
+}
+
+/** 由月干序与月支序求六十甲子序（同旬组合必然存在）。 */
+function monthComposite(stemIdx, branchIdx) {
+  for (let i = 0; i < 60; i++) {
+    if (i % 10 === stemIdx && i % 12 === branchIdx) return i;
+  }
+  return 0;
+}

package/engine/bazi.js

@@ -7,6 +7,7 @@ import {
 import { resolveAddress } from './geo.js';
 import { computeBaziShensha } from './shensha.js';
 import { assertCivil } from './validate.js';
+import { applyDst } from './dst.js';
 import { nayinOf } from './nayin.js';
 import { SANHE } from './sanhe.js';
 import { analyzeBaziFrame, scoreLuck } from './geju.js';
@@ -209,9 +210,15 @@ export function applyTrueSolar(jd, longitude) {
  */
 export function buildBazi(input) {
   assertCivil(input);
-  const { year, month, day, hour = 0, minute = 0, gender = 'male' } = input;
+  let { year, month, day, hour = 0, minute = 0, gender = 'male' } = input;
   const lateZi = input.lateZi !== false;
   const useTrueSolar = input.trueSolar !== false;
+  // 1986–1991 中国夏令时：出生证钟面时间普遍是「拨快 1 小时」的钟面时间，
+  // 不校正会让时柱（乃至跨 23:00 的日柱）整档偏；显式传 dst:false 可关闭。
+  const dst = input.dst === false ? { applied: false, note: null } : applyDst({ year, month, day, hour, minute });
+  if (dst.applied) {
+    year = dst.year; month = dst.month; day = dst.day; hour = dst.hour; minute = dst.minute;
+  }
 
   const civilJd = partsToJd({ year, month, day, hour, minute });
   // 地址 -> 经度：手填的 longitude 优先，其次按地址查表
@@ -470,12 +477,13 @@ export function buildBazi(input) {
       geo,
       lateZi,
       trueSolar: useTrueSolar,
+      dst: { applied: !!dst.applied, note: dst.note || null },
     },
     solarTime: {
       civilText: `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')} ${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`,
       trueSolarText: formatJd(jd),
       offsetMinutes: solar.offsetMinutes,
-      note: solar.note,
+      note: dst.applied ? `${dst.note}；${solar.note}` : solar.note,
       lunarYearForPillar: solarYear,
     },
     jieqi: {

package/engine/chenggu.js

@@ -0,0 +1,126 @@
+// 袁天罡称骨：按农历年/月/日/时辰四柱骨重求和，给分档白话批语。
+// 骨重表为通行本口径；批语是白话自撰（不冒充原版称骨歌诀原文）。
+import { solarToLunar } from './lunar.js';
+import { ganzhiName, toJDN, dayGanzhiIndex } from './calendar.js';
+import { assertCivil } from './validate.js';
+import { hourToBranch } from './almanac.js';
+
+/** 六十甲子年骨重（单位：钱；索引 = (农历年 - 4) mod 60，0 = 甲子）。 */
+export const YEAR_WEIGHT = [
+  12, 9, 6, 7, 12, 5, 9, 8, 7, 8,
+  15, 9, 16, 8, 8, 19, 12, 6, 8, 7,
+  5, 15, 6, 16, 15, 7, 9, 12, 10, 7,
+  15, 6, 5, 14, 14, 9, 7, 7, 9, 12,
+  8, 7, 13, 5, 14, 5, 9, 17, 5, 7,
+  12, 8, 8, 6, 19, 6, 8, 16, 10, 7,
+];
+
+/** 农历月骨重（正月…腊月）。 */
+export const MONTH_WEIGHT = [6, 7, 18, 9, 5, 16, 9, 15, 18, 8, 9, 5];
+
+/** 农历日骨重（初一…三十）。 */
+export const DAY_WEIGHT = [
+  5, 10, 8, 15, 16, 15, 8, 16, 8, 16,
+  9, 17, 8, 17, 10, 8, 9, 18, 5, 15,
+  10, 9, 8, 9, 15, 18, 7, 8, 16, 6,
+];
+
+/** 时辰骨重（按地支）。 */
+export const HOUR_WEIGHT = { 子: 16, 丑: 6, 寅: 7, 卯: 10, 辰: 9, 巳: 16, 午: 10, 未: 8, 申: 8, 酉: 9, 戌: 6, 亥: 6 };
+
+const LIANG = ['一', '二', '三', '四', '五', '六', '七'];
+const QIAN = ['一', '二', '三', '四', '五', '六', '七', '八', '九'];
+const MONTH_TEXT = ['正', '二', '三', '四', '五', '六', '七', '八', '九', '十', '冬', '腊'];
+const DAY_TENS = ['初', '十', '廿'];
+const DAY_UNITS = ['十', '一', '二', '三', '四', '五', '六', '七', '八', '九'];
+
+/** 钱 → 「X两Y钱」（不足一两只写钱数）。 */
+export function formatWeight(qian) {
+  const liang = Math.floor(qian / 10);
+  const rem = qian % 10;
+  const liangPart = liang > 0 ? `${LIANG[liang - 1]}两` : '';
+  const remPart = rem > 0 ? `${QIAN[rem - 1]}钱` : liang > 0 ? '整' : '零';
+  return `${liangPart}${remPart}`;
+}
+
+/** 农历日序中文：初一…三十。 */
+export function lunarDayText(day) {
+  if (day === 10) return '初十';
+  if (day === 20) return '二十';
+  if (day === 30) return '三十';
+  const ten = Math.floor(day / 10);
+  const unit = day % 10;
+  return `${DAY_TENS[ten]}${DAY_UNITS[unit]}`;
+}
+
+/** 农历月序中文。 */
+export function lunarMonthText(month, isLeap = false) {
+  return `${isLeap ? '闰' : ''}${MONTH_TEXT[month - 1] || month}月`;
+}
+
+/** 骨重分档（白话自撰）。 */
+function bandVerdict(qian) {
+  if (qian >= 55) return { band: '上上', text: '骨重沉实，根基深厚，一生多逢贵人，谋事易成；守正持重，福泽可久。' };
+  if (qian >= 45) return { band: '上', text: '骨重充实，中年前后渐入佳境，事业家宅两旺；忌骄忌躁，善守即善成。' };
+  if (qian >= 35) return { band: '中上', text: '骨重适中，先劳后逸，凭本事立身；中年转运之象，稳扎稳打自见分晓。' };
+  if (qian >= 25) return { band: '中', text: '骨重平平，成败多靠自身经营；宜有一技傍身、广结善缘，勤则补拙。' };
+  return { band: '中下', text: '骨重较轻，早年多磨，凡事宜稳不宜急；积跬步以至千里，晚景反可安宁。' };
+}
+
+/**
+ * 称骨主函数。
+ * @param {{ year:number, month:number, day:number, hour:number, minute?:number }} input
+ *   一律按公历给生日（农历换算由引擎完成）；时辰必填——称骨四柱缺时辰不可算。
+ */
+export function buildChenggu(input) {
+  assertCivil(input, '称骨');
+  const { year, month, day, hour } = input;
+  const minute = input.minute || 0;
+  if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+    throw new Error('称骨必须给时辰：hour 为 0–23 的整数（缺时辰四柱不齐，骨重无法求和）');
+  }
+  const lunar = solarToLunar(year, month, day);
+  const lunarYear = lunar.lunarYear;
+  const lunarMonth = lunar.month;
+  const lunarDay = lunar.day;
+  const yearGz = ganzhiName((((lunarYear - 4) % 60) + 60) % 60);
+  const hourBranch = hourToBranch(hour, minute);
+
+  const wYear = YEAR_WEIGHT[((lunarYear - 4) % 60 + 60) % 60];
+  const wMonth = MONTH_WEIGHT[lunarMonth - 1];
+  const wDay = DAY_WEIGHT[lunarDay - 1];
+  const wHour = HOUR_WEIGHT[hourBranch];
+  if ([wYear, wMonth, wDay, wHour].some((x) => typeof x !== 'number')) {
+    throw new Error(`称骨表缺项：年${wYear} 月${wMonth} 日${wDay} 时${wHour}`);
+  }
+  const total = wYear + wMonth + wDay + wHour;
+  const verdict = bandVerdict(total);
+  const jdn = toJDN(year, month, day);
+
+  return {
+    system: 'chenggu',
+    input: { solar: `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`, hour, minute },
+    lunar: {
+      text: `农历${yearGz.name}年${lunarMonthText(lunarMonth, lunar.isLeap)}${lunarDayText(lunarDay)} ${hourBranch}时`,
+      year: lunarYear,
+      month: lunarMonth,
+      day: lunarDay,
+      isLeap: lunar.isLeap,
+      hourBranch,
+    },
+    ganzhi: { year: yearGz.name, day: ganzhiName(dayGanzhiIndex(jdn)).name },
+    weights: {
+      year: { qian: wYear, label: `${yearGz.name}年 ${formatWeight(wYear)}` },
+      month: { qian: wMonth, label: `农历${lunarMonthText(lunarMonth, lunar.isLeap)} ${formatWeight(wMonth)}` },
+      day: { qian: wDay, label: `农历${lunarDayText(lunarDay)} ${formatWeight(wDay)}` },
+      hour: { qian: wHour, label: `${hourBranch}时 ${formatWeight(wHour)}` },
+    },
+    total: { qian: total, label: formatWeight(total) },
+    verdict,
+    sources: [
+      '骨重表：通行本袁天罡称骨（六十甲子年 / 十二月 / 三十日 / 十二时辰）',
+      '批语：白话自撰，非原版称骨歌诀原文，可自行对照',
+    ],
+    disclaimer: '骨重为通行表口径；批语为白话解读，属民俗娱乐参考，不构成命运断言。',
+  };
+}

package/engine/dst.js

@@ -0,0 +1,68 @@
+// 中国夏令时（1986–1991）校正：纯本地确定性。
+//
+// 这六年春夏钟表拨快 1 小时：出生证上的时间多数是「夏令时钟面时间」，
+// 不校正则时辰（乃至日柱）整体错一档。区间为通行口径（春季 02:00 起，秋季 02:00 止，含头不含尾）。
+// 依据：国务院 1986–1991 年夏令时通告；与公开万年历对拍一致。
+import { daysInMonth } from './validate.js';
+
+/** 历年夏令时区间：[起始日, 结束日]（本地钟面时间）。 */
+export const DST_SPANS = {
+  1986: ['1986-05-04', '1986-09-14'],
+  1987: ['1987-04-12', '1987-09-13'],
+  1988: ['1988-04-10', '1988-09-11'],
+  1989: ['1989-04-16', '1989-09-17'],
+  1990: ['1990-04-15', '1990-09-16'],
+  1991: ['1991-04-14', '1991-09-15'],
+};
+
+const ORD = (y, m, d) => y * 10000 + m * 100 + d;
+
+/**
+ * 给定钟面时刻是否落在夏令时区间内。
+ * @param {{year:number,month:number,day:number,hour:number,minute?:number}} t
+ */
+export function inDstSpan(t) {
+  const span = DST_SPANS[t.year];
+  if (!span) return false;
+  const [sy, sm, sd] = span[0].split('-').map(Number);
+  const [ey, em, ed] = span[1].split('-').map(Number);
+  const n = ORD(t.year, t.month, t.day);
+  if (n < ORD(sy, sm, sd) || n > ORD(ey, em, ed)) return false;
+  const minutes = t.hour * 60 + (t.minute || 0);
+  if (n === ORD(sy, sm, sd) && minutes < 120) return false; // 起始日 02:00 起
+  if (n === ORD(ey, em, ed) && minutes >= 120) return false; // 结束日 02:00 止
+  return true;
+}
+
+/**
+ * 夏令时校正：钟面时间减 1 小时（跨日正确回退）。
+ * @param {{year:number,month:number,day:number,hour:number,minute?:number}} t
+ * @returns {{year,month,day,hour,minute,applied:boolean,note:string|null}}
+ */
+export function applyDst(t) {
+  const minute = t.minute || 0;
+  if (!inDstSpan(t)) return { year: t.year, month: t.month, day: t.day, hour: t.hour, minute, applied: false, note: null };
+  let { year, month, day, hour } = t;
+  hour -= 1;
+  if (hour < 0) {
+    hour += 24;
+    day -= 1;
+    if (day < 1) {
+      month -= 1;
+      if (month < 1) { month = 12; year -= 1; }
+      day = daysInMonth(year, month);
+    }
+  }
+  return {
+    year, month, day, hour, minute,
+    applied: true,
+    note: `检出自 ${DST_SPANS[t.year][0]} 至 ${DST_SPANS[t.year][1]} 的中国夏令时：出生钟面时间已减 1 小时校正`,
+  };
+}
+
+/** 把夏令时说明折进 notes 数组（不改动其它口径）。 */
+export function withDstNote(notes, dst) {
+  const out = Array.isArray(notes) ? notes.slice() : [];
+  if (dst && dst.applied && dst.note) out.push(dst.note);
+  return out;
+}