dsh-metaphysics 0.18.4 → 0.20.0

package/engine/almanac.js

@@ -7,6 +7,7 @@
 // 彭祖百忌、胎神等全量黄历数据未收录——输出里如实标注「未收录」，不臆造。
 // 宜忌只按「建除十二神」通行简表给出（传统择日的第一层判据），不是逐日全量黄历。
 import { solarToLunar } from './lunar.js';
+import { nayinOf } from './nayin.js';
 import {
   toJDN, fromJDN, dayGanzhiIndex, ganzhiName, termWindow, termInstantJd, partsToJd, STEMS, BRANCHES, TERM_NAMES,
 } from './calendar.js';
@@ -89,6 +90,89 @@ export function lunarMonthText(month, isLeap = false) {
   return `${isLeap ? '闰' : ''}${MONTH_TEXT[month - 1] || month}月`;
 }
 
+/** 黄道/黑道十二神（青龙、明堂…勾陈），值日与时家共用。 */
+export const TIAN_SHEN = ['青龙', '明堂', '天刑', '朱雀', '金匮', '天德', '白虎', '玉堂', '天牢', '玄武', '司命', '勾陈'];
+/** 六黄道（吉）/ 六黑道（凶）。 */
+export const TIAN_SHEN_TYPE = {
+  青龙: '黄道', 明堂: '黄道', 金匮: '黄道', 天德: '黄道', 玉堂: '黄道', 司命: '黄道',
+  天刑: '黑道', 朱雀: '黑道', 白虎: '黑道', 天牢: '黑道', 玄武: '黑道', 勾陈: '黑道',
+};
+/** 十二神起例：以月支（日家）或日支（时家）为锚的偏移。 */
+const TIAN_SHEN_OFFSET = { 子: 4, 丑: 2, 寅: 0, 卯: 10, 辰: 8, 巳: 6, 午: 4, 未: 2, 申: 0, 酉: 10, 戌: 8, 亥: 6 };
+
+/** 日家十二神：日支 + 月支偏移；时家十二神：时支 + 日支偏移。 */
+export function tianShenOf(branch, anchorBranch) {
+  const b = BRANCHES.indexOf(branch);
+  const off = TIAN_SHEN_OFFSET[anchorBranch];
+  if (b < 0 || off == null) return null;
+  const name = TIAN_SHEN[(b + off) % 12];
+  const type = TIAN_SHEN_TYPE[name];
+  return { name, type, luck: type === '黄道' ? '吉' : '凶' };
+}
+
+/** 二十八宿：值日宿按「日支 + 星期」轮转（四组各七宿）。 */
+export const MANSIONS = {
+  角: { luck: '吉', zheng: '木', animal: '蛟', gong: '东' }, 亢: { luck: '凶', zheng: '金', animal: '龙', gong: '东' },
+  氐: { luck: '凶', zheng: '土', animal: '貉', gong: '东' }, 房: { luck: '吉', zheng: '日', animal: '兔', gong: '东' },
+  心: { luck: '凶', zheng: '月', animal: '狐', gong: '东' }, 尾: { luck: '吉', zheng: '火', animal: '虎', gong: '东' },
+  箕: { luck: '吉', zheng: '水', animal: '豹', gong: '东' }, 斗: { luck: '吉', zheng: '木', animal: '獬', gong: '北' },
+  牛: { luck: '凶', zheng: '金', animal: '牛', gong: '北' }, 女: { luck: '凶', zheng: '土', animal: '蝠', gong: '北' },
+  虚: { luck: '凶', zheng: '日', animal: '鼠', gong: '北' }, 危: { luck: '凶', zheng: '月', animal: '燕', gong: '北' },
+  室: { luck: '吉', zheng: '火', animal: '猪', gong: '北' }, 壁: { luck: '吉', zheng: '水', animal: '獝', gong: '北' },
+  奎: { luck: '凶', zheng: '木', animal: '狼', gong: '西' }, 娄: { luck: '吉', zheng: '金', animal: '狗', gong: '西' },
+  胃: { luck: '吉', zheng: '土', animal: '彘', gong: '西' }, 昴: { luck: '凶', zheng: '日', animal: '鸡', gong: '西' },
+  毕: { luck: '吉', zheng: '月', animal: '乌', gong: '西' }, 觜: { luck: '凶', zheng: '火', animal: '猴', gong: '西' },
+  参: { luck: '吉', zheng: '水', animal: '猿', gong: '西' }, 井: { luck: '吉', zheng: '木', animal: '犴', gong: '南' },
+  鬼: { luck: '凶', zheng: '金', animal: '羊', gong: '南' }, 柳: { luck: '凶', zheng: '土', animal: '獐', gong: '南' },
+  星: { luck: '凶', zheng: '日', animal: '马', gong: '南' }, 张: { luck: '吉', zheng: '月', animal: '鹿', gong: '南' },
+  翼: { luck: '凶', zheng: '火', animal: '蛇', gong: '南' }, 轸: { luck: '吉', zheng: '水', animal: '蚓', gong: '南' },
+};
+const XIU_GROUPS = {
+  A: ['虚', '毕', '翼', '箕', '奎', '鬼', '氐'],
+  B: ['房', '危', '觜', '轸', '斗', '娄', '柳'],
+  C: ['星', '心', '室', '参', '角', '牛', '胃'],
+  D: ['昴', '张', '尾', '壁', '井', '亢', '女'],
+};
+const XIU_GROUP_OF = { 子: 'A', 辰: 'A', 申: 'A', 丑: 'B', 巳: 'B', 酉: 'B', 寅: 'C', 午: 'C', 戌: 'C', 卯: 'D', 未: 'D', 亥: 'D' };
+
+/** 值日宿：weekday 0=周日。 */
+export function xiuOf(dayBranch, weekdayIndex) {
+  const g = XIU_GROUP_OF[dayBranch];
+  if (!g) return null;
+  const name = XIU_GROUPS[g][weekdayIndex];
+  const info = MANSIONS[name];
+  return info ? { name, ...info } : null;
+}
+
+/** 吉神方位（按日干；福神取通行一变，另一变注明差异）。 */
+const DIR_OF = { 坎: '正北', 艮: '东北', 震: '正东', 巽: '东南', 离: '正南', 坤: '西南', 兑: '正西', 乾: '西北' };
+const POS_XI = { 甲: '艮', 乙: '乾', 丙: '坤', 丁: '离', 戊: '巽', 己: '艮', 庚: '乾', 辛: '坤', 壬: '离', 癸: '巽' };
+const POS_CAI = { 甲: '艮', 乙: '艮', 丙: '坤', 丁: '坤', 戊: '坎', 己: '坎', 庚: '震', 辛: '震', 壬: '离', 癸: '离' };
+const POS_FU = { 甲: '坎', 乙: '坤', 丙: '乾', 丁: '巽', 戊: '艮', 己: '坎', 庚: '坤', 辛: '乾', 壬: '巽', 癸: '艮' };
+const POS_YANG_GUI = { 甲: '坤', 乙: '坤', 丙: '兑', 丁: '乾', 戊: '艮', 己: '坎', 庚: '离', 辛: '艮', 壬: '震', 癸: '巽' };
+const POS_YIN_GUI = { 甲: '艮', 乙: '坎', 丙: '乾', 丁: '兑', 戊: '坤', 己: '坤', 庚: '艮', 辛: '离', 壬: '巽', 癸: '震' };
+const posOf = (map, stem) => (map[stem] ? { gua: map[stem], dir: DIR_OF[map[stem]] } : null);
+
+/** 胎神（逐日干支，通行表）。 */
+const TAI_SHEN = {
+  甲子: '占门碓 外东南', 乙丑: '碓磨厕 外东南', 丙寅: '厨灶炉 外正南', 丁卯: '仓库门 外正南', 戊辰: '房床栖 外正南',
+  己巳: '占门床 外正南', 庚午: '占碓磨 外正南', 辛未: '厨灶厕 外西南', 壬申: '仓库炉 外西南', 癸酉: '房床门 外西南',
+  甲戌: '占门栖 外西南', 乙亥: '碓磨床 外西南', 丙子: '厨灶碓 外西南', 丁丑: '仓库厕 外正西', 戊寅: '房床炉 外正西',
+  己卯: '占大门 外正西', 庚辰: '碓磨栖 外正西', 辛巳: '厨灶床 外正西', 壬午: '仓库碓 外西北', 癸未: '房床厕 外西北',
+  甲申: '占门炉 外西北', 乙酉: '碓磨门 外西北', 丙戌: '厨灶栖 外西北', 丁亥: '仓库床 外西北', 戊子: '房床碓 外正北',
+  己丑: '占门厕 外正北', 庚寅: '碓磨炉 外正北', 辛卯: '厨灶门 外正北', 壬辰: '仓库栖 外正北', 癸巳: '占房床 房内北',
+  甲午: '占门碓 房内北', 乙未: '碓磨厕 房内北', 丙申: '厨灶炉 房内北', 丁酉: '仓库门 房内北', 戊戌: '房床栖 房内中',
+  己亥: '占门床 房内中', 庚子: '占碓磨 房内南', 辛丑: '厨灶厕 房内南', 壬寅: '仓库炉 房内南', 癸卯: '房床门 房内西',
+  甲辰: '占门栖 房内东', 乙巳: '碓磨床 房内东', 丙午: '厨灶碓 房内东', 丁未: '仓库厕 房内东', 戊申: '房床炉 房内中',
+  己酉: '占大门 外东北', 庚戌: '碓磨栖 外东北', 辛亥: '厨灶床 外东北', 壬子: '仓库碓 外东北', 癸丑: '房床厕 外东北',
+  甲寅: '占门炉 外东北', 乙卯: '碓磨门 外正东', 丙辰: '厨灶栖 外正东', 丁巳: '仓库床 外正东', 戊午: '房床碓 外正东',
+  己未: '占门厕 外正东', 庚申: '碓磨炉 外东南', 辛酉: '厨灶门 外东南', 壬戌: '仓库栖 外东南', 癸亥: '占房床 外东南',
+};
+
+/** 六合 / 三合（对日支取吉配生肖）。 */
+const LIUHE = { 子: '丑', 丑: '子', 寅: '亥', 亥: '寅', 卯: '戌', 戌: '卯', 辰: '酉', 酉: '辰', 巳: '申', 申: '巳', 午: '未', 未: '午' };
+const SANHE = { 申: '申子辰', 子: '申子辰', 辰: '申子辰', 亥: '亥卯未', 卯: '亥卯未', 未: '亥卯未', 寅: '寅午戌', 午: '寅午戌', 戌: '寅午戌', 巳: '巳酉丑', 酉: '巳酉丑', 丑: '巳酉丑' };
+
 /** 每日一卦：日期哈希确定性映射到通行本 64 卦（同日同卦）。 */
 export function dailyHexagram(year, month, day) {
   const names = Object.keys(HEX64);
@@ -153,7 +237,42 @@ export function buildAlmanac(input) {
     return `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`;
   };
 
-  const weekday = ['日', '一', '二', '三', '四', '五', '六'][(jdn + 1) % 7];
+  const weekdayIdx = (jdn + 1) % 7;
+  const weekday = ['日', '一', '二', '三', '四', '五', '六'][weekdayIdx];
+  // 值日十二神（黄道/黑道）、二十八宿、胎神、纳音、吉神方位、时辰吉凶
+  const dayGod = tianShenOf(dayBranch, BRANCHES[monthBranchIdx]);
+  const xiu = xiuOf(dayBranch, weekdayIdx);
+  const taiShen = TAI_SHEN[dayGz.name] || null;
+  const hourBase = (STEMS.indexOf(dayGz.stem) % 5) * 2;
+  const hours = BRANCHES.map((zhi, i) => {
+    const gan = STEMS[(hourBase + i) % 10];
+    const gz = ganzhiName(hourComposite((hourBase + i) % 10, i));
+    const shen = tianShenOf(zhi, dayBranch);
+    return {
+      zhi,
+      name: `${zhi}时`,
+      ganZhi: gz.name,
+      gan,
+      shen: shen ? shen.name : null,
+      type: shen ? shen.type : null,
+      luck: shen ? shen.luck : null,
+    };
+  });
+  const sanheGroup = SANHE[dayBranch] || '';
+  const liuheBranch = LIUHE[dayBranch] || null;
+  const lucky = {
+    liuhe: liuheBranch ? SHENGXIAO[BRANCHES.indexOf(liuheBranch)] : null,
+    sanhe: [...sanheGroup].filter((b) => b !== dayBranch).map((b) => SHENGXIAO[BRANCHES.indexOf(b)]),
+  };
+  const positions = {
+    caiShen: CAI_SHEN[dayGz.stem] || null,
+    xiShen: XI_SHEN[dayGz.stem] || null,
+    fuShen: posOf(POS_FU, dayGz.stem),
+    yangGui: posOf(POS_YANG_GUI, dayGz.stem),
+    yinGui: posOf(POS_YIN_GUI, dayGz.stem),
+    xiShenFull: posOf(POS_XI, dayGz.stem),
+    caiShenFull: posOf(POS_CAI, dayGz.stem),
+  };
   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)]}，两种都对，取用场合不同`
@@ -165,7 +284,7 @@ export function buildAlmanac(input) {
       date: `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`,
       weekday: `星期${weekday}`,
       ...(boundaryNote ? { boundaryNote } : {}),
-      scope: '通行简表口径：宜忌只按建除十二神；逐日神煞/二十八宿/彭祖百忌/胎神等全量黄历数据未收录',
+      scope: '通行口径：宜忌按建除十二神简表；已收录值日十二神（黄道/黑道）、时辰吉凶、二十八宿、胎神、吉神方位、纳音、六合三合吉配；逐日全量吉神凶煞与彭祖百忌未收录',
     },
     lunar: {
       year: springYear,
@@ -186,7 +305,13 @@ export function buildAlmanac(input) {
       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 },
+    positions,
+    dayGod,
+    xiu,
+    taiShen,
+    nayin: { day: nayinOf(dayGanzhiIndex(jdn)) },
+    lucky,
+    hours,
     zhiXing,
     yi: ZHIXING_YI[zhiXing].slice(),
     ji: ZHIXING_JI[zhiXing].slice(),
@@ -199,6 +324,7 @@ export function buildAlmanac(input) {
     sources: [
       '农历与节气：本地天文历法（定朔 + 节气黄经）',
       '建除十二神与冲煞：传统通行口径',
+      '值日/时家十二神（青龙…勾陈）、二十八宿、胎神、吉神方位：通行表',
       '宜忌：建除十二神通行简表（非逐日全量黄历）',
       '每日一卦：按公历日期确定性取卦（同日同卦）',
     ],
@@ -213,3 +339,11 @@ function monthComposite(stemIdx, branchIdx) {
   }
   return 0;
 }
+
+/** 由时干序与时支序求六十甲子序。 */
+function hourComposite(stemIdx, branchIdx) {
+  for (let i = 0; i < 60; i++) {
+    if (i % 10 === stemIdx && i % 12 === branchIdx) return i;
+  }
+  return 0;
+}

package/engine/bazi.js

@@ -506,7 +506,8 @@ export function buildBazi(input) {
       list: dayun,
     },
     strength,
-    frame,
+    frame,
+    climate: frame.yongshen.climate || frame.yongshen.tiaohou || null,
     liunian,
     liunianFrom: thisYear,
   };

package/engine/convert.js

@@ -0,0 +1,137 @@
+// 公农历互转（本地确定性，不依赖外部历法库）
+//
+// 两种方向：
+//   · 公历 → 农历：直接查本地定朔历（engine/lunar.js），给出农历年月日、闰月标记、干支、生肖。
+//   · 农历 → 公历：按目标农历年的「月首」序列反查（每月 29/30 天，闰月单独一轮），
+//     逐月定位后再加日偏移；不做「节气月」换算，农历就是朔望月口径。
+//
+// 诚实边界：只处理 1900–2100 的本地历法覆盖范围（与 lunar.js 一致）；闰月必须显式给出，
+// 不猜「第一个同名月」；农历日期越界（如小月三十）如实报错，不静默回退。
+import { solarToLunar } from './lunar.js';
+import { fromJDN, toJDN } from './calendar.js';
+import { buildAlmanac } from './almanac.js';
+import { assertCivil, daysInMonth } from './validate.js';
+
+const WEEK = ['日', '一', '二', '三', '四', '五', '六'];
+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]}`;
+}
+
+function lunarText(year, month, day, isLeap) {
+  return `农历${year}年${isLeap ? '闰' : ''}${MONTH_TEXT[month - 1] || month}月${dayText(day)}`;
+}
+
+/** 找某个农历年的正月初一（公历 1/20–2/25 之间）。 */
+function lunarNewYearJdn(lunarYear) {
+  const from = toJDN(lunarYear, 1, 20);
+  const to = toJDN(lunarYear, 2, 25);
+  for (let jdn = from; jdn <= to; jdn++) {
+    const p = fromJDN(jdn);
+    const l = solarToLunar(p.year, p.month, p.day);
+    if (l.lunarYear === lunarYear && l.month === 1 && l.day === 1) return jdn;
+  }
+  return null;
+}
+
+/** 某农历年的月首序列（含闰月）。 */
+function lunarMonths(lunarYear) {
+  const first = lunarNewYearJdn(lunarYear);
+  if (first == null) return [];
+  const out = [];
+  let cur = first;
+  for (let i = 0; i < 14; i++) {
+    const p = fromJDN(cur);
+    const l = solarToLunar(p.year, p.month, p.day);
+    if (i > 0 && l.month === 1 && !l.isLeap) break;
+    let next = null;
+    for (let k = 29; k <= 31; k++) {
+      const d = fromJDN(cur + k);
+      const l2 = solarToLunar(d.year, d.month, d.day);
+      if (l2.day === 1) { next = cur + k; break; }
+    }
+    if (next == null) break;
+    out.push({ month: l.month, isLeap: l.isLeap, startJdn: cur, length: next - cur });
+    cur = next;
+  }
+  return out;
+}
+
+/**
+ * 公农历互转。
+ * @param {{mode?:'solar2lunar'|'lunar2solar', year?:number, month?:number, day?:number,
+ *   lunarYear?:number, lunarMonth?:number, lunarDay?:number, isLeapMonth?:boolean}} input
+ */
+export function buildConvert(input) {
+  const mode = input.mode === 'lunar2solar' ? 'lunar2solar' : 'solar2lunar';
+  let solar;
+  let lunar;
+  let note = null;
+  if (mode === 'solar2lunar') {
+    solar = { year: input.year, month: input.month, day: input.day };
+    assertCivil(solar, '公农历转换');
+    if (solar.day > daysInMonth(solar.year, solar.month)) {
+      throw new Error(`非法日期：${solar.year} 年 ${solar.month} 月没有 ${solar.day} 日`);
+    }
+    lunar = solarToLunar(solar.year, solar.month, solar.day);
+  } else {
+    const y = Number(input.lunarYear);
+    const m = Number(input.lunarMonth);
+    const d = Number(input.lunarDay);
+    if (![y, m, d].every(Number.isInteger)) throw new Error('农历转换需要 lunarYear / lunarMonth / lunarDay');
+    if (m < 1 || m > 12) throw new Error('农历月份须在 1–12');
+    const months = lunarMonths(y);
+    if (!months.length) throw new Error(`农历 ${y} 年超出本地历法覆盖范围（1900–2100）`);
+    const isLeap = input.isLeapMonth === true;
+    const hit = months.find((x) => x.month === m && x.isLeap === isLeap);
+    if (!hit) {
+      const leapMonths = months.filter((x) => x.isLeap).map((x) => `闰${MONTH_TEXT[x.month - 1]}月`);
+      throw new Error(`农历 ${y} 年没有${leapMonths.length ? `该月（该年闰月为 ${leapMonths.join('、')}）` : '闰月'}：${isLeap ? '请确认闰月标记' : '请确认月份'}`);
+    }
+    if (d < 1 || d > hit.length) throw new Error(`农历 ${y} 年${isLeap ? '闰' : ''}${MONTH_TEXT[m - 1]}月只有 ${hit.length} 天，没有 ${d} 日`);
+    const p = fromJDN(hit.startJdn + d - 1);
+    solar = { year: p.year, month: p.month, day: p.day };
+    const check = solarToLunar(p.year, p.month, p.day);
+    if (check.month !== m || check.day !== d || check.isLeap !== isLeap) {
+      note = '反查结果与目标农历日不完全一致，已按本地历法实际月首回推';
+    }
+    lunar = check;
+  }
+
+  const a = buildAlmanac(solar);
+  const jdn = toJDN(solar.year, solar.month, solar.day);
+  const solarText = `${solar.year}-${String(solar.month).padStart(2, '0')}-${String(solar.day).padStart(2, '0')}`;
+  return {
+    system: 'convert',
+    meta: {
+      mode,
+      solarDate: solarText,
+      weekday: `星期${WEEK[(jdn + 1) % 7]}`,
+      ...(note ? { note } : {}),
+      scope: '公农历互转按本地定朔历（1900–2100）；农历闰月须显式指定，不自动猜同名月',
+    },
+    solar: { year: solar.year, month: solar.month, day: solar.day, text: solarText },
+    lunar: {
+      year: lunar.lunarYear,
+      month: lunar.month,
+      day: lunar.day,
+      isLeap: lunar.isLeap,
+      text: lunarText(lunar.lunarYear, lunar.month, lunar.day, lunar.isLeap),
+    },
+    ganzhi: {
+      year: a.ganzhi.year,
+      month: a.ganzhi.month,
+      day: a.ganzhi.day,
+      shengXiao: a.ganzhi.shengXiao,
+      springYear: a.ganzhi.springYear,
+    },
+    sources: ['农历：本地定朔 + 节气黄经历法（engine/lunar.js）', '干支与生肖：与黄历同口径（年按立春界，另列春节界）'],
+    disclaimer: '历法换算为确定性计算；民俗历法各版本在极少数日期（交节当日、闰月边界）存在日界差异，已注明口径。',
+  };
+}

package/engine/geju.js

@@ -2,10 +2,12 @@
 //
 // 定位：在 bazi.js 算出四柱、五行、旺衰之后，给出
 //   1) 格局（月令格 + 特殊格 + 常见组合）；
-//   2) 用神 / 喜忌（扶抑为主，调候作简化提示）；
-//   3) 大运、流年的吉凶倾向评分。
+//   2) 用神 / 喜忌（调候优先 + 扶抑校验；气候平和时仍以扶抑为主）；
+//   3) 大运、流年的吉凶倾向评分（含调候修正项）。
 // 取舍：格局派别差异极大，这里只给「规则可复核」的判定，evidence 写明依据；
-// 调候未做穷通宝鉴 120 条全表，只按寒暖燥湿给方向，并在 detail 里注明。
+// 调候由 tiaohou.js 独立判定，与扶抑冲突时显式裁决并写明理由，不静默取用。
+
+import { judgeClimate, arbitrate } from './tiaohou.js';
 
 const STEMS = ['甲', '乙', '丙', '丁', '戊', '己', '庚', '辛', '壬', '癸'];
 const BRANCHES = ['子', '丑', '寅', '卯', '辰', '巳', '午', '未', '申', '酉', '戌', '亥'];
@@ -197,38 +199,37 @@ function specialPatterns(pillars, dayStem, monthBranch, strength, wuxing, gods)
 
 // ── 用神 / 喜忌 ──────────────────────────────────────────────
 
-const TIAOHOU = {
-  亥: ['火', '冬月寒水当令，最喜火暖局'],
-  子: ['火', '仲冬水旺，最喜火暖局'],
-  丑: ['火', '季冬湿寒，喜火解冻'],
-  巳: ['水', '初夏火旺，喜水制衡'],
-  午: ['水', '仲夏火炎，最喜水调候'],
-  未: ['水', '季夏燥土，喜水润局'],
-  寅: ['火', '初春尚寒，得火而发'],
-  卯: ['火', '仲春木旺，喜火吐秀'],
-  辰: ['金', '季春湿土，喜金水疏泄'],
-  申: ['火', '初秋金旺，喜火炼金'],
-  酉: ['火', '仲秋金锐，喜火制'],
-  戌: ['水', '季秋燥土，喜水润泽'],
-};
 
-function yongshenOf(dayStem, monthBranch, strength, wuxing) {
+function yongshenOf(dayStem, monthBranch, strength, wuxing, branches = []) {
   const roles = elementRoles(dayStem);
   const me = roles.me;
   const weak = strength.level === '身弱' || strength.level === '偏弱';
   const strong = strength.level === '身强' || strength.level === '偏强';
 
-  const favor = weak ? [roles.inMe, me] : strong ? [roles.shi, roles.cai, roles.guan] : [roles.inMe, me, roles.shi];
-  const avoid = weak ? [roles.shi, roles.cai, roles.guan] : strong ? [me, roles.inMe] : [roles.guan, roles.cai];
-  const favorableTenGods = weak ? ['正印', '偏印', '比肩', '劫财'] : strong
-    ? ['食神', '伤官', '正财', '偏财', '正官', '七杀']
-    : ['正印', '偏印', '食神', '伤官'];
-
-  const th = TIAOHOU[monthBranch];
-  const tiaohou = th ? { element: th[0], note: th[1] } : null;
+  const baseFavor = weak ? [roles.inMe, me] : strong ? [roles.shi, roles.cai, roles.guan] : [roles.inMe, me, roles.shi];
+  const baseAvoid = weak ? [roles.shi, roles.cai, roles.guan] : strong ? [me, roles.inMe] : [roles.guan, roles.cai];
+  let favor = baseFavor.slice();
+  let avoid = baseAvoid.slice();
+
+  // 先判气候，再决定要不要让调候压过扶抑
+  const climate = judgeClimate({ monthBranch, dayStem, wuxing, branches });
+  const arb = arbitrate(climate, baseFavor, baseAvoid);
+  if (climate.need && climate.priority === '调候优先') {
+    const needEl = climate.need.element;
+    if (!favor.includes(needEl)) favor.unshift(needEl);
+    avoid = avoid.filter((e) => e !== needEl);
+    if (climate.avoidElement && !avoid.includes(climate.avoidElement)) avoid.unshift(climate.avoidElement);
+  }
 
   const roleName = (el) => (el === me ? '比劫' : el === roles.inMe ? '印'
     : el === roles.shi ? '食伤' : el === roles.cai ? '财' : '官杀');
+  const expand = {
+    比劫: ['比肩', '劫财'], 印: ['正印', '偏印'], 食伤: ['食神', '伤官'],
+    财: ['正财', '偏财'], 官杀: ['正官', '七杀'],
+  };
+  const favorTenGods = Array.from(new Set(favor.flatMap((el) => expand[roleName(el)] || [])));
+  const avoidTenGods = Array.from(new Set(avoid.flatMap((el) => expand[roleName(el)] || [])));
+
   const detail = [
     `日主${dayStem}${me}，${strength.level}（${strength.score} 分）：`,
     weak
@@ -236,24 +237,22 @@ function yongshenOf(dayStem, monthBranch, strength, wuxing) {
       : strong
         ? `喜${roles.shi}（食伤）泄秀、${roles.cai}（财）耗、${roles.guan}（官杀）制；忌${me}（比劫）与${roles.inMe}（印）再助。`
         : '身中和，先取调候与通关，喜忌随大运流年动态变化。',
-    tiaohou ? `调候（简化）：${tiaohou.note}，宜${tiaohou.element}。` : '',
-    '扶抑法为主；调候未用穷通宝鉴全表，各派取用不同，仅作方向提示。',
+    `调候：${climate.label}（${(climate.evidence || []).join('、')}）${climate.need ? `，取${climate.need.stem}${climate.need.element}，忌${climate.avoidElement}` : '，气候平和'}。`,
+    arb.text,
+    arb.clash ? '取舍：本盘按「调候优先、扶抑次之」取用；若你更认同扶抑派，可把调候当环境偏好，强弱判断不受影响。' : '',
   ].filter(Boolean).join('');
 
   return {
-    method: '扶抑为主 + 调候简化提示',
+    method: climate.priority === '调候优先' ? '调候优先 + 扶抑校验' : '扶抑为主 + 调候校验',
     level: strength.level,
     favor,
     avoid,
     favorRoles: favor.map(roleName),
     avoidRoles: avoid.map(roleName),
-    favorTenGods: favorableTenGods,
-    avoidTenGods: weak
-      ? ['食神', '伤官', '正财', '偏财', '正官', '七杀']
-      : strong
-        ? ['比肩', '劫财', '正印', '偏印']
-        : ['正官', '七杀', '正财', '偏财'],
-    tiaohou,
+    favorTenGods,
+    avoidTenGods,
+    tiaohou: { ...climate, ...arb, element: climate.need ? climate.need.element : null },
+    climate,
     detail,
   };
 }
@@ -274,33 +273,55 @@ export function scoreLuck(ganzhi, frame) {
   const branch = ganzhi[1];
   const stemEl = STEM_ELEMENT[stem];
   const branchEl = BRANCH_ELEMENT[branch];
+  const th = ys.tiaohou || ys.climate || null;
   const scoreEl = (el) => {
     let s = 0;
     if (ys.favor.includes(el)) s += 1;
     if (ys.avoid.includes(el)) s -= 1;
-    if (ys.tiaohou && el === ys.tiaohou.element) s += 0.4;
     return s;
   };
   let score = scoreEl(stemEl) * 1.0 + scoreEl(branchEl) * 0.8;
   for (const h of (HIDDEN[branch] || []).slice(1)) {
     score += scoreEl(STEM_ELEMENT[h]) * 0.2;
   }
-  score = Math.round(score * 10) / 10;
-
-  const godStem = tenGod(frame.dayStem, stem);
-  const bonus = ys.favorTenGods.includes(godStem) ? 0.3 : 0;
-  const total = Math.round((score + bonus) * 10) / 10;
 
-  const tier = TIERS.find(([min]) => total >= min)[1];
   const reasons = [];
   if (ys.favor.includes(stemEl)) reasons.push(`天干${stem}${stemEl}为用神`);
   else if (ys.avoid.includes(stemEl)) reasons.push(`天干${stem}${stemEl}为忌神`);
   else reasons.push(`天干${stem}${stemEl}不喜不忌`);
   if (ys.favor.includes(branchEl)) reasons.push(`地支${branch}${branchEl}助用`);
   else if (ys.avoid.includes(branchEl)) reasons.push(`地支${branch}${branchEl}助忌`);
-  if (ys.tiaohou && (stemEl === ys.tiaohou.element || branchEl === ys.tiaohou.element)) {
-    reasons.push(`合调候（${ys.tiaohou.element}）`);
+
+  // 调候修正：不是"有没有这个五行"，而是"这一年是给命局添了一把火，还是泼了一盆水"
+  if (th && th.need && th.priority === '调候优先') {
+    const needEl = th.need.element;
+    const oppEl = th.avoidElement;
+    const cold = String(th.kind).includes('寒');
+    if (stemEl === needEl) {
+      score += 1.1;
+      reasons.push(`${th.label}之局得${stem}${stemEl}，${cold ? '解冻' : '得润'}`);
+    } else if (stemEl === oppEl) {
+      score -= 0.9;
+      reasons.push(`${th.label}之局再逢${stem}${stemEl}，${cold ? '冻木难生' : '燥上加燥'}`);
+    }
+    if (branchEl === needEl) {
+      score += 0.9;
+      reasons.push(`地支${branch}${branchEl}合调候`);
+    } else if (branchEl === oppEl) {
+      score -= 1.0;
+      reasons.push(`地支${branch}${branchEl}加重${th.label}`);
+    }
+    if (cold && (stemEl === '水' || branchEl === '水')) score -= 0.3;
+  } else if (th && th.need && (stemEl === th.need.element || branchEl === th.need.element)) {
+    reasons.push(`合调候（${th.need.element}）`);
   }
+
+  const godStem = tenGod(frame.dayStem, stem);
+  const bonus = ys.favorTenGods.includes(godStem) ? 0.3 : 0;
+  let total = Math.round((score + bonus) * 10) / 10;
+  total = Math.max(-4, Math.min(4, total));
+
+  const tier = TIERS.find(([min]) => total >= min)[1];
   return { ganzhi, score: total, tier, stemTenGod: godStem, reasons, note: `${godStem}运，${tier}（${total}）` };
 }
 
@@ -319,7 +340,7 @@ export function analyzeBaziFrame({ pillars, dayStem, monthBranch, strength, wuxi
   const month = monthPattern(pillars, dayStem, monthBranch);
   const special = specialPatterns(pillars, dayStem, monthBranch, strength, wuxing, gods);
   const geju = [month, ...special];
-  const yongshen = yongshenOf(dayStem, monthBranch, strength, wuxing);
+  const yongshen = yongshenOf(dayStem, monthBranch, strength, wuxing, Object.values(pillars).map((p) => p.branch));
   return {
     geju,
     primary: month,

package/engine/geo.js

@@ -143,7 +143,7 @@ const DETAIL = /(区|县|镇|乡|村|小区|街道|路|号|巷|弄|组|队)/;
 
 /** OpenStreetMap Nominatim：免密钥、支持中文。失败返回 null。
  *  UA 按 OSM 使用政策要求写明应用与联系方式（改版本时同步这里）。 */
-const USER_AGENT = 'dsh-metaphysics/0.18.4 (+https://github.com/xuanfu-web/dsh-metaphysics)';
+const USER_AGENT = 'dsh-metaphysics/0.20.0 (+https://github.com/xuanfu-web/dsh-metaphysics)';
 
 async function onlineLookup(text, { timeoutMs = 2500 } = {}) {
   if (typeof fetch !== 'function') return null;

package/engine/index.js

@@ -21,7 +21,8 @@ import { buildZeri } from './zeri.js';
 import { buildChenggu } from './chenggu.js';
 import { buildXiaoliuren } from './xiaoliuren.js';
 import { buildStar } from './star.js';
-import { buildNumerology } from './numerology.js';
+import { buildNumerology } from './numerology.js';
+import { buildConvert } from './convert.js';
 import { buildTrend } from './trend.js';
 import { buildFengshui } from './fengshui.js';
 import { buildName } from './name.js';
@@ -109,6 +110,7 @@ function baziText(r) {
     `　　　${r.frame.geju.map((g) => `${g.name}[${g.kind}]`).join('　')}`,
     `用神：喜${r.frame.yongshen.favor.join('')}（${r.frame.yongshen.favorTenGods.join('、')}）　忌${r.frame.yongshen.avoid.join('')}（${r.frame.yongshen.avoidTenGods.join('、')}）　${r.frame.yongshen.method}`,
     `　　　${r.frame.yongshen.detail}`,
+    `寒暖：${r.climate ? `${r.climate.label}（${(r.climate.evidence || []).join('、')}）${r.climate.need ? `　调候取${r.climate.need.stem}${r.climate.need.element}　忌${r.climate.avoidElement}` : ''}` : '—'}`,
     `十神权重：${Object.entries(r.frame.godStats.groups).map(([k, v]) => `${k}${v}`).join(' ')}`,
   ] : [];
   return [
@@ -617,6 +619,26 @@ function computeRaw(args = {}) {
     const result = buildChenggu({ year: dt.year, month: dt.month, day: dt.day, hour, minute: hasTime ? dt.minute : 0 });
     return { ...result, summary: chengguText(result) };
   }
+  if (system === 'convert') {
+    const mode = args.mode === 'lunar2solar' ? 'lunar2solar' : 'solar2lunar';
+    let result;
+    if (mode === 'lunar2solar') {
+      if (args.lunarYear == null || args.lunarMonth == null || args.lunarDay == null) {
+        throw fail('E_INPUT', '农历转公历需要 lunarYear / lunarMonth / lunarDay（闰月另加 isLeapMonth: true）');
+      }
+      result = buildConvert({
+        mode,
+        lunarYear: Number(args.lunarYear),
+        lunarMonth: Number(args.lunarMonth),
+        lunarDay: Number(args.lunarDay),
+        isLeapMonth: args.isLeapMonth === true,
+      });
+    } else {
+      const dt = parseDateTime(args.datetime);
+      result = buildConvert({ mode, year: dt.year, month: dt.month, day: dt.day });
+    }
+    return { ...result, summary: convertText(result) };
+  }
   if (system === 'xiaoliuren') {
     const dt = args.datetime ? parseDateTime(args.datetime) : null;
     const result = buildXiaoliuren({
@@ -700,22 +722,35 @@ function computeRaw(args = {}) {
     return { ...result, summary: nameText(result) };
   }
   if (!system) {
-    throw fail('E_INPUT', '缺少 system，可选：bazi（四柱八字）、ziwei（紫微斗数）、liuyao（六爻）、meihua（梅花易数）、daliuren（大六壬）、qimen（奇门遁甲）、hepan（合盘）、tarot（塔罗）、almanac（黄历）、zeri（择日）、chenggu（称骨）、xiaoliuren（小六壬）、star（星座）、numerology（生命数字）、trend（人生 K 线）、fengshui（风水）、name（起名）。');
+    throw fail('E_INPUT', '缺少 system，可选：bazi（四柱八字）、ziwei（紫微斗数）、liuyao（六爻）、meihua（梅花易数）、daliuren（大六壬）、qimen（奇门遁甲）、hepan（合盘）、tarot（塔罗）、almanac（黄历）、zeri（择日）、chenggu（称骨）、xiaoliuren（小六壬）、star（星座）、numerology（生命数字）、trend（人生 K 线）、fengshui（风水）、name（起名）、convert（公农历互转）。');
   }
-  throw fail('E_SYSTEM', `未知体系「${system}」，可选：bazi（四柱八字）、ziwei（紫微斗数）、liuyao（六爻）、meihua（梅花易数）、daliuren（大六壬）、qimen（奇门遁甲）、hepan（合盘）、tarot（塔罗）、almanac（黄历）、zeri（择日）、chenggu（称骨）、xiaoliuren（小六壬）、star（星座）、numerology（生命数字）、trend（人生 K 线）、fengshui（风水）、name（起名）。`);
+  throw fail('E_SYSTEM', `未知体系「${system}」，可选：bazi（四柱八字）、ziwei（紫微斗数）、liuyao（六爻）、meihua（梅花易数）、daliuren（大六壬）、qimen（奇门遁甲）、hepan（合盘）、tarot（塔罗）、almanac（黄历）、zeri（择日）、chenggu（称骨）、xiaoliuren（小六壬）、star（星座）、numerology（生命数字）、trend（人生 K 线）、fengshui（风水）、name（起名）、convert（公农历互转）。`);
 }
 
 /** 黄历文本 */
 function almanacText(r) {
   const g = r.ganzhi;
   const jq = r.jieQi && r.jieQi.next ? `　下一节：${r.jieQi.next.name} ${r.jieQi.next.date}` : '';
+  const god = r.dayGod ? `值日：${r.dayGod.name}（${r.dayGod.type}·${r.dayGod.luck}）` : '';
+  const xiu = r.xiu ? `二十八宿：${r.xiu.name}宿（${r.xiu.luck}·${r.xiu.zheng}·${r.xiu.animal}）` : '';
+  const tai = r.taiShen ? `胎神：${r.taiShen}` : '';
+  const pos = r.positions
+    ? `吉神方位：喜神${r.positions.xiShen || '—'}　财神${r.positions.caiShen || '—'}　福神${r.positions.fuShen ? r.positions.fuShen.dir : '—'}　阳贵${r.positions.yangGui ? r.positions.yangGui.dir : '—'}　阴贵${r.positions.yinGui ? r.positions.yinGui.dir : '—'}`
+    : '';
+  const lucky = r.lucky ? `吉配生肖：六合${r.lucky.liuhe || '—'}　三合${(r.lucky.sanhe || []).join('、') || '—'}` : '';
+  const nayin = r.nayin && r.nayin.day ? `日柱纳音：${r.nayin.day.name}` : '';
+  const hours = (r.hours || []).map((h) => `${h.zhi}${h.ganZhi.slice(0, 1)}·${h.shen}${h.luck === '吉' ? '吉' : '凶'}`).join(' ');
   return [
     `【黄历】${r.meta.date} ${r.meta.weekday}　${r.lunar.text}`,
     `干支：${g.year}年　${g.month}月　${g.day}日　属${g.shengXiao}`,
     ...(r.meta.boundaryNote ? [`　${r.meta.boundaryNote}`] : []),
-    `建除：${r.zhiXing}日　冲：${r.chong.text}${r.chong.sha ? `（${r.chong.sha}）` : ''}　财神：${r.positions.caiShen || '—'}　喜神：${r.positions.xiShen || '—'}`,
+    `建除：${r.zhiXing}日　冲：${r.chong.text}${r.chong.sha ? `（${r.chong.sha}）` : ''}　${god}`,
+    [xiu, nayin, tai].filter(Boolean).join('　'),
     `宜：${r.yi.join('、')}`,
     `忌：${r.ji.join('、')}`,
+    pos,
+    lucky,
+    hours ? `时辰吉凶：${hours}` : '',
     `节气：上一节 ${r.jieQi.prev ? `${r.jieQi.prev.name} ${r.jieQi.prev.date}` : '—'}${jq}`,
     r.dailyHexagram ? `每日一卦：${r.dailyHexagram.name}　${r.dailyHexagram.meaning || ''}` : '',
     `口径：${r.meta.scope}`,
@@ -775,6 +810,18 @@ function starText(r) {
   ].join('\n');
 }
 
+/** 公农历互转文本 */
+function convertText(r) {
+  const g = r.ganzhi;
+  const dir = r.meta.mode === 'lunar2solar' ? '农历 → 公历' : '公历 → 农历';
+  return [
+    `【公农历转换·${dir}】${r.lunar.text} ⇄ ${r.solar.text} ${r.meta.weekday}`,
+    `干支：${g.year}年　${g.month}月　${g.day}日　属${g.shengXiao}${g.springYear && g.springYear !== g.year ? `（春节界为${g.springYear}年）` : ''}`,
+    ...(r.meta.note ? [`注：${r.meta.note}`] : []),
+    `口径：${r.meta.scope}`,
+  ].join('\n');
+}
+
 /** 生命数字文本 */
 function numerologyText(r) {
   return [
@@ -883,7 +930,7 @@ export { buildBazi, buildLiuyao, tossLines };
 export { followup };
 export { pastSignals, verifyFit, rectifyBirth };
 export { crossCheck, crossText };
-export { buildAlmanac, buildZeri, buildChenggu, buildXiaoliuren, buildStar, buildNumerology };
+export { buildAlmanac, buildZeri, buildChenggu, buildXiaoliuren, buildStar, buildNumerology, buildConvert };
 export { buildTrend, buildFengshui, buildName };