dsh-metaphysics 0.61.2 → 0.62.1

package/engine/liuyao.js

@@ -1,6 +1,8 @@
 // 六爻（纳甲）引擎：摇卦、装卦、六亲、六神、世应、变卦
 import { STEMS, BRANCHES, toJDN, ganzhiName, dayGanzhiIndex, sexagenaryIndex, xunKongOf } from './calendar.js';
 import { jingText } from './yijing-text.js';
+import { fail } from './fail.js';
+import { assertObject } from './validate.js';
 
 // 八卦三位（自下而上，1 = 阳）
 const TRIGRAM_BITS = {
@@ -117,6 +119,7 @@ function hexBranches(hex) {
 
 /** 单个卦的卦体属性：是否六冲卦 / 六合卦，及配对明细 */
 export function hexBody(hex) {
+  assertObject(hex, 'hexBody 的卦对象', '取 buildLiuyao 结果里的 ben / bian（含 name、upper、lower）');
   const { inner, outer, all } = hexBranches(hex);
   const chongPairs = pairThirds(all, ZHI_CHONG_PAIRS);
   const hePairs = pairThirds(all, ZHI_HE_PAIRS);
@@ -140,6 +143,8 @@ export function hexBody(hex) {
  * @param {number[]} [moving] 动爻位置（1~6）
  */
 export function bodyRelations(ben, bian = null, moving = []) {
+  assertObject(ben, 'bodyRelations 的本卦', 'hexagramFromBits / buildLiuyao 得到的卦对象（含 name、upper、lower）；静卦时 bian 传 null');
+  if (bian !== null && bian !== undefined) assertObject(bian, 'bodyRelations 的变卦', '卦对象或 null（静卦传 null）');
   const b = hexBody(ben);
   const out = {
     ben: { name: b.name, chong: b.chong, he: b.he, chongPairs: b.chongPairs, hePairs: b.hePairs, inner: b.inner, outer: b.outer },
@@ -262,6 +267,10 @@ export const HEXAGRAM_COUNT = HEXAGRAM_INDEX.size;
 
 /** 由六爻（自下而上，1 = 阳）求卦 */
 export function hexagramFromBits(bits) {
+  // 爻数不对以前静默返回 undefined（HEXAGRAM_INDEX.get 落空），调用方拿着 undefined 继续读 .name 才炸
+  if (!Array.isArray(bits) || bits.length !== 6 || bits.some((b) => b !== 0 && b !== 1)) {
+    throw fail('E_INPUT', `hexagramFromBits 需要 6 个爻位（自下而上，每项 0 或 1），收到 ${Array.isArray(bits) ? `${bits.length} 项` : String(bits) === 'null' ? 'null' : typeof bits}`);
+  }
   const upper = TRIGRAM_BY_VALUE[bitsValue(bits.slice(3))];
   const lower = TRIGRAM_BY_VALUE[bitsValue(bits.slice(0, 3))];
   return HEXAGRAM_INDEX.get(`${upper}|${lower}`);
@@ -326,6 +335,10 @@ const sideOf = (position) => (position <= 3 ? 'inner' : 'outer');
  * @param {{direction?:string, gender?:string}} [opts]
  */
 export function yongshenOf(result, opts = {}) {
+  // opts 允许省略或传 null（都按默认口径），但显式给了别的东西就必须是对象：
+  // 以前 yongshenOf(r, null) 会一路走到读 opts.direction，抛裸 TypeError
+  if (opts === null || opts === undefined) opts = {};
+  assertObject(opts, 'yongshenOf 的 opts', '{ direction?, gender? }；省略或 null 按默认口径');
   const r = result && typeof result === 'object' ? result : {};
   const ben = r.ben && typeof r.ben === 'object' ? r.ben : {};
   const lines = Array.isArray(ben.lines) ? ben.lines : [];
@@ -476,12 +489,22 @@ function isMoving(v) {
  * @param {object} input { lines?: number[] (自下而上, 6/7/8/9), dayGanZhi?: {stem, branch}, question?: string }
  */
 export function buildLiuyao(input = {}) {
-  const rawLines = Array.isArray(input.lines) && input.lines.length === 6
-    ? input.lines.slice()
-    : tossLines(input.random);
+  if (!input || typeof input !== 'object') throw fail('E_INPUT', '六爻起卦参数不能为空：至少给 lines 或 seed');
+  // lines 给了但不是数组（"7,8,9,6,7,8" / 789678 / {…}）以前等同于「没给」：
+  // 用户以为摇的是自己记下的那一卦，实际拿到一张随机盘，而且看不出来。
+  if (input.lines !== undefined && input.lines !== null && !Array.isArray(input.lines)) {
+    throw fail('E_LINES', `lines 必须是数组：自下而上 6 个爻值（6 老阴 / 7 少阳 / 8 少阴 / 9 老阳），收到 ${typeof input.lines}`);
+  }
+  const given = Array.isArray(input.lines) ? input.lines : null;
+  // 给了 lines 就按给定的装卦；长度不对是输入错误，不能悄悄改成随机摇卦
+  // 码一律用 E_LINES：爻值这一族错误对外只有一个口径，宿主层不必再按文案二次判
+  if (given && given.length !== 6) {
+    throw fail('E_LINES', `lines 必须是 6 个爻值（自下而上），收到 ${given.length} 个`);
+  }
+  const rawLines = given ? given.slice() : tossLines(input.random);
 
   const invalid = rawLines.filter((v) => ![6, 7, 8, 9].includes(v));
-  if (invalid.length) throw new Error(`爻值只能是 6/7/8/9，收到 ${JSON.stringify(rawLines)}`);
+  if (invalid.length) throw fail('E_LINES', `爻值只能是 6/7/8/9，收到 ${JSON.stringify(rawLines)}`);
 
   const bits = rawLines.map(lineToBit);
   const ben = hexagramFromBits(bits);

package/engine/lunar.js

@@ -120,7 +120,6 @@ export function solarToLunar(year, month, day) {
   let num = 11;
   // 农历年以正月初一为界：月序越过「正」之后，岁次进一位
   let wrapped = false;
-  let cursorStart = dayNumberOf(newMoonJd(k));
 
   for (let i = 1; i <= 15; i++) {
     const startDay = dayNumberOf(newMoonJd(k + i - 1));
@@ -149,17 +148,11 @@ export function solarToLunar(year, month, day) {
       num = (num % 12) + 1;
       if (num === 1) wrapped = true; // 已越过正月初一
     }
-    cursorStart = endDay;
   }
 
   throw new Error(`农历换算失败：${year}-${month}-${day}`);
 }
 
-/** 农历月首的儒略日（供内部校验） */
-export function monthStartJd(year, month, day) {
-  return toJDN(year, month, day);
-}
-
 export { SYNODIC };
 
 

package/engine/mbti.js

@@ -352,6 +352,7 @@ function strengthOf(pct, answered) {
  * 维度净分 > 0 取左字母，< 0 取右字母，= 0 按维度表的 tie 取（并标「临界」）。
  */
 export function buildMbti(input = {}) {
+  input = input && typeof input === 'object' ? input : {};
   const answers = normalizeAnswers(input.answers);
   const answeredAll = answers.filter((v) => v !== null).length;
   if (answeredAll < 12) {

package/engine/meihua.js

@@ -1,7 +1,9 @@
 // 梅花易数：时间/数字起卦、体用、互卦、变卦、错综卦
-import { BRANCHES } from './calendar.js';
+import { BRANCHES, fromJDN, toJDN } from './calendar.js';
 import { solarToLunar } from './lunar.js';
 import { fail } from './fail.js';
+import { parseDateTime } from './datetime.js';
+import { assertShifted } from './validate.js';
 import { hexagramFromBits } from './liuyao.js';
 import { jingText } from './yijing-text.js';
 
@@ -45,6 +47,7 @@ function relation(bodyEl, useEl) {
  *   upper/lower/changing: 数字（number 模式，可给两数由程序取余）
  */
 export function buildMeihua(input = {}) {
+  if (!input || typeof input !== 'object') throw fail('E_INPUT', '梅花起卦参数不能为空：时间起卦要 datetime，数字起卦要 upper / lower');
   const mode = input.mode === 'number' ? 'number' : 'time';
   let upperNum;
   let lowerNum;
@@ -57,13 +60,31 @@ export function buildMeihua(input = {}) {
     if (!Number.isFinite(a) || !Number.isFinite(b)) throw fail('E_INPUT', '数字起卦需要两个数字（upper / lower），例如 upper=3、lower=5');
     upperNum = mod8(a);
     lowerNum = mod8(b);
-    moving = Number.isFinite(Number(input.changing)) && Number(input.changing) > 0
-      ? mod6(Number(input.changing))
-      : mod6(a + b);
+    if (input.changing !== undefined && input.changing !== null && input.changing !== '') {
+      // 以前 99 会被 mod 6 折成 3：用户指定动爻却得到另一爻，结果里看不出来
+      const ch = Number(input.changing);
+      if (!Number.isInteger(ch) || ch < 1 || ch > 6) {
+        throw fail('E_INPUT', `动爻 changing 必须是 1–6 的整数，收到「${input.changing}」`);
+      }
+      moving = ch;
+    } else {
+      moving = mod6(a + b);
+    }
     source = `数字起卦：${a} / ${b}`;
   } else {
     const dt = parseDateTime(input.datetime);
-    const lunar = solarToLunar(dt.year, dt.month, dt.day);
+    // 晚子时换日与八字/六壬/奇门同口径：23:00–23:59 归次日，年月日电数才落在同一子时
+    const lateZi = input.lateZi !== false;
+    let sy = dt.year;
+    let sm = dt.month;
+    let sd = dt.day;
+    if (lateZi && dt.hour >= 23) {
+      const next = assertShifted(fromJDN(toJDN(sy, sm, sd) + 1), '梅花时间起卦');
+      sy = next.year;
+      sm = next.month;
+      sd = next.day;
+    }
+    const lunar = solarToLunar(sy, sm, sd);
     const yearBranch = ((lunar.lunarYear - 4) % 12 + 12) % 12;
     const hb = Math.floor(((dt.hour + 1) % 24) / 2);
     const sum1 = yearBranch + 1 + lunar.month + lunar.day;
@@ -71,7 +92,7 @@ export function buildMeihua(input = {}) {
     upperNum = mod8(sum1);
     lowerNum = mod8(sum2);
     moving = mod6(sum2);
-    source = `时间起卦：${BRANCHES[yearBranch]}年${lunar.month}月${lunar.day}日${BRANCHES[hb]}时`;
+    source = `时间起卦：${BRANCHES[yearBranch]}年${lunar.month}月${lunar.day}日${BRANCHES[hb]}时${lateZi && dt.hour >= 23 ? '（晚子时按次日）' : ''}`;
   }
 
   const ben = hexName(upperNum, lowerNum);
@@ -127,14 +148,4 @@ export function buildMeihua(input = {}) {
   };
 }
 
-function parseDateTime(text) {
-  if (typeof text !== 'string' || !text.trim()) throw fail('E_INPUT', '时间起卦需要 datetime，例如 2026-10-24T11:43');
-  const m = text.trim().match(/^(\d{4})-(\d{1,2})-(\d{1,2})(?:[T\s](\d{1,2}):(\d{1,2}))?$/);
-  if (!m) throw fail('E_INPUT', `无法解析 datetime：「${text}」，请用 2026-10-24T11:43 这种格式`);
-  return {
-    year: Number(m[1]), month: Number(m[2]), day: Number(m[3]),
-    hour: Number(m[4] ?? 0), minute: Number(m[5] ?? 0),
-  };
-}
-
 export { TRI_NAME, TRI_ELEMENT, TRI_BITS };

package/engine/name.js

@@ -4,7 +4,8 @@
 //       五格按康熙字典繁体笔画计（见 name-data.js 的口径说明），81 数理取通行本；
 //       音韵只做机械检查（同调、相邻同声母/同韵母、叠字），不做语义谐音判断。
 import { buildBazi } from './bazi.js';
-import { assertCivil } from './validate.js';
+import { assertCivil, assertObject } from './validate.js';
+import { fail } from './fail.js';
 import {
   READING, SURNAME_STROKES, SURNAME_READING, SURNAME_ALT_READING, DOUBLE_SURNAMES, SHULI_81,
 } from './name-data.js';
@@ -491,11 +492,12 @@ function charInfo(ch) {
 
 /** 评估一个名字（姓 + 名 1–2 字）。给了生辰才做喜用匹配。 */
 export function assessName(input) {
+  assertObject(input, 'assessName 的参数', '{ surname, givenName, year?, month?, day? }');
   const surname = String(input.surname || '').trim();
-  if (!surname) throw new Error('缺少姓氏：请给 surname（如「李」）');
+  if (!surname) throw fail('E_INPUT', '缺少姓氏：请给 surname（如「李」）');
   const given = String(input.givenName || '').trim();
-  if (!given) throw new Error('缺少名字：请给 givenName（1–2 个汉字，如「沐宸」）');
-  if ([...given].length > 2) throw new Error('名请给 1–2 个汉字；复姓请把复姓整体写在 surname，名只留 1–2 字');
+  if (!given) throw fail('E_INPUT', '缺少名字：请给 givenName（1–2 个汉字，如「沐宸」）');
+  if ([...given].length > 2) throw fail('E_INPUT', '名请给 1–2 个汉字；复姓请把复姓整体写在 surname，名只留 1–2 字');
 
   let favorable = { list: [], basis: '' };
   let strength = null;
@@ -595,10 +597,11 @@ export function assessName(input) {
  * limit 1–20；同一字不重复；候选按「合喜用数 → 简洁 → 字库序」确定性排序。
  */
 export function generateNames(input) {
+  assertObject(input, 'generateNames 的参数', '{ surname, year, month, day, limit? }');
   const surname = String(input.surname || '').trim();
-  if (!surname) throw new Error('缺少姓氏：请给 surname（如「李」）');
+  if (!surname) throw fail('E_INPUT', '缺少姓氏：请给 surname（如「李」）');
   if (!Number.isInteger(input.year) || !Number.isInteger(input.month) || !Number.isInteger(input.day)) {
-    throw new Error('生成候选名需要完整出生年月日（公历）：不给生辰无法判断喜用五行');
+    throw fail('E_INPUT', '生成候选名需要完整出生年月日（公历）：不给生辰无法判断喜用五行');
   }
   assertCivil(input, 'birth');
   const gender = input.gender === 'female' ? 'female' : 'male';
@@ -720,6 +723,12 @@ export function generateNames(input) {
 
 /** 主函数：action='assess'（默认）或 'generate'。 */
 export function buildName(input) {
+  if (!input || typeof input !== 'object') {
+    throw fail('E_INPUT', '起名参数不能为空：评名要 surname / givenName，起名要 surname 与性别/生日');
+  }
+  if (input.action != null && input.action !== 'assess' && input.action !== 'generate') {
+    throw fail('E_INPUT', `起名 action 只能是 assess / generate，收到「${String(input.action).slice(0, 24)}」`);
+  }
   if (input.action === 'generate') return generateNames(input);
   return assessName(input);
 }

package/engine/numerology.js

@@ -1,6 +1,7 @@
 // 生命数字（西方数字学）：生命路径数 / 生日数 / 态度数，11、22、33 主数保留。
 // 纯本地确定性；与八字/紫微是两套不可互证的体系，输出里明确提示。
-import { daysInMonth } from './validate.js';
+import { MAX_YEAR, MIN_YEAR, daysInMonth } from './validate.js';
+import { fail } from './fail.js';
 
 /** 1–9 与主数 11/22/33 的数义（白话提炼）。 */
 export const NUMBER_MEANING = {
@@ -37,8 +38,8 @@ const digitSum = (n) => String(Math.abs(Math.trunc(n))).split('').reduce((s, c)
 export function buildNumerology(input) {
   const { year, month, day } = input || {};
   if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)
-    || year < 1900 || year > 2100 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
-    throw new Error('生命数字需要真实存在的公历出生日期（year 1900–2100、month、day）——请向用户询问，勿猜');
+    || year < MIN_YEAR || year > MAX_YEAR || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
+    throw fail('E_INPUT', `生命数字需要真实存在的公历出生日期（year ${MIN_YEAR}–${MAX_YEAR}、month、day）——请向用户询问，勿猜`);
   }
   const lifePath = reduceNumber(digitSum(year) + digitSum(month) + digitSum(day));
   const birthday = reduceNumber(day);

package/engine/qimen-interpret.js

@@ -55,7 +55,16 @@ const REL_TEXT = {
   unknown: '五行缺失，关系未定',
 };
 
-const findPalace = (r, key) => r.palaces.find((p) => p.star === key || p.gate === key || p.god === key || p.palace === key) || null;
+// 天芮在中宫寄坤时被统一改名「禽芮」，表里仍按通行名写；不折叠就永远定位不到。
+// 驿马不在 palaces[].star 上，而是 r.ma.gong，单独走一条。
+const STAR_ALIAS = { 天芮: '禽芮' };
+const findPalace = (r, key) => {
+  if (key === '驿马') {
+    const gong = r.ma && r.ma.gong;
+    return gong ? (r.palaces.find((p) => p.palace === gong) || null) : null;
+  }
+  return r.palaces.find((p) => p.star === key || p.star === STAR_ALIAS[key] || p.gate === key || p.god === key || p.palace === key) || null;
+};
 const cell = (p) => `${p.palace}宫（${p.star}·${p.gate}·${p.god}）`;
 
 /** 按询问方向取用神及其落宫；解读与推导链共用这一张表，避免两处各写一份 */
@@ -111,7 +120,16 @@ export function interpretQimen(r, opts = {}) {
   // ③ 用神候选
   const yongList = ysInfo.rows.filter((x) => x.palace);
   if (!yongList.length) unresolved.push(`${ys.label}的用神未上盘`);
-  if (yongList.length > 1) unresolved.push(`用神有 ${yongList.length} 个候选（${yongList.map((x) => x.key).join('、')}）`);
+  else {
+    // 主用神缺位、只剩次级候选时不能装作没发生：原先主用神落空、死门仍能撑起 yongList，
+    // 「用神未上盘」的兜底永远不触发，健康解读就只剩一句「若以死门为用神」。
+    const missingPrimary = ys.primary.filter((k) => !ysInfo.rows.some((x) => x.key === k && x.palace));
+    if (missingPrimary.length) unresolved.push(`主用神${missingPrimary.join('、')}未上盘`);
+  }
+  // 「辅用神也在盘上」不算未决：YONG_SHEN 每个方向本就是「主用神 + 一两个辅用神」，
+  // 辅用神必然落宫，按候选数判未决等于 unresolved 恒非空，下面的倾向分支一次也没跑过
+  // （7 个方向全部退回「暂不给单一倾向」）。候选清单在 ④ 一节里逐条列出，不靠这里提醒。
+  const primaryYong = ysInfo.rows.find((x) => ys.primary.includes(x.key) && x.palace) || null;
   sections.push({
     key: 'yongshen',
     label: `用神候选（${ys.label}）`,
@@ -121,7 +139,7 @@ export function interpretQimen(r, opts = {}) {
   });
 
   // ④ 两宫关系（用神宫 × 值符宫）
-  const primary = yongList[0] || null;
+  const primary = primaryYong || yongList[0] || null;
   if (primary && zhiFuP) {
     if (primary.palace.palace === zhiFuP.palace) {
       sections.push({
@@ -201,6 +219,13 @@ export function interpretQimen(r, opts = {}) {
       label: '最终倾向',
       text: `暂不给单一倾向。未决项：${unresolved.join('；')}。先把用神定下来，再谈顺逆。`,
     });
+  } else if (!primary || !zhiFuP) {
+    // 顺逆要拿「用神宫 × 值符宫」对比，两处任一落不到具体单宫就没法给结论
+    sections.push({
+      key: 'tendency',
+      label: '最终倾向',
+      text: `暂不给单一倾向。${primary ? '值符落宫在本盘没有对应单宫，缺对照宫' : '本盘没有可用的用神落宫'}，顺逆判断需要一个明确的对照，缺它就不硬凑。`,
+    });
   } else {
     const rel = wuxingRelation(primary.palace.palaceElement, zhiFuP.palaceElement);
     const tone = rel === '被生' || rel === '生' ? '偏向顺' : rel === '被克' ? '偏向滞' : '中性';

package/engine/qimen-prompt.js

@@ -4,6 +4,8 @@
 // 模型拿到一屏数据后最省力的写法就是「开门临生门，吉」——这不是解读，是把符号念一遍。
 // 所以提示里把「取哪个符号、为什么取它、它落在哪、和谁什么关系、回到现实查什么」写成硬步骤，
 // 并要求先给人话结论，再给依据。文案与取法分开存，取法可测，文案可改。
+import { xunShouLiuYi } from './qimen.js';
+
 export const QIMEN_PROMPT_VERSION = 'qimen-1';
 
 /** 九宫序号 → 方位与领域（读「事情落在哪个领域」时用，不直接当吉凶） */
@@ -122,11 +124,6 @@ const HARD_RULES = [
   '不确定就写不确定，并说明缺哪条信息才能确定。',
 ];
 
-const stemOf = (siZhu, key) => {
-  const v = siZhu && siZhu[key];
-  return v ? String(v).charAt(0) : '';
-};
-
 /** 天盘某干落在哪一宫（日干/时干/月干定位都走这里） */
 function palaceOfStem(q, stem) {
   if (!stem) return null;
@@ -138,6 +135,24 @@ function palaceOfStem(q, stem) {
   return c && c.tianPan === stem ? c : null;
 }
 
+/** 某柱天干定宫：甲不上天盘，按本柱所在旬的旬首六仪代查，并在文案里标明寄仪 */
+function palaceOfPillarStem(q, siZhu, key, label) {
+  const gz = siZhu && siZhu[key] ? String(siZhu[key]) : '';
+  const stem = gz.charAt(0);
+  if (!stem) return { symbol: `${label}`, palace: null, missing: `四柱里没有${label}` };
+  if (stem !== '甲') {
+    const p = palaceOfStem(q, stem);
+    return { symbol: `${label} ${stem}`, palace: p, missing: p ? '' : `${label}${stem}未现于天盘` };
+  }
+  const yi = xunShouLiuYi(gz);
+  const p = palaceOfStem(q, yi);
+  return {
+    symbol: `${label} 甲（寄${yi}）`,
+    palace: p,
+    missing: p ? '' : `${label}甲寄${yi}，${yi}未现于天盘`,
+  };
+}
+
 function palaceOfGate(q, gate) {
   if (!gate) return null;
   return (q.palaces || []).find((p) => p.gate === gate) || null;
@@ -152,18 +167,9 @@ function palaceOfGod(q, god) {
 export function resolveSubject(q, sub) {
   const si = q.siZhu || {};
   const how = String(sub.how || '');
-  if (how === 'dayStem') {
-    const s = stemOf(si, 'day');
-    return { symbol: `日干 ${s}`, palace: palaceOfStem(q, s), missing: s ? '' : '四柱里没有日干' };
-  }
-  if (how === 'hourStem') {
-    const s = stemOf(si, 'time');
-    return { symbol: `时干 ${s}`, palace: palaceOfStem(q, s), missing: s ? '' : '四柱里没有时干' };
-  }
-  if (how === 'monthStem') {
-    const s = stemOf(si, 'month');
-    return { symbol: `月干 ${s}`, palace: palaceOfStem(q, s), missing: s ? '' : '四柱里没有月干' };
-  }
+  if (how === 'dayStem') return palaceOfPillarStem(q, si, 'day', '日干');
+  if (how === 'hourStem') return palaceOfPillarStem(q, si, 'time', '时干');
+  if (how === 'monthStem') return palaceOfPillarStem(q, si, 'month', '月干');
   if (how === 'zhiFu') {
     const g = q.zhiFu && q.zhiFu.gong;
     return { symbol: `值符（${(q.zhiFu && q.zhiFu.star) || ''}）`, palace: (q.palaces || []).find((p) => p.palace === String(g)) || null, missing: g ? '' : '没有值符落宫' };

package/engine/qimen.js

@@ -4,7 +4,8 @@
 // 只把历法层换成本插件自己的 calendar/lunar 模块——节气、干支、农历都走同一套已验证的源码。
 import { termInstantJd, termWindow, jdToParts, partsToJd, formatJd, ganzhiName, sexagenaryIndex, STEMS, BRANCHES } from './calendar.js';
 import { solarToLunar } from './lunar.js';
-import { assertCivil } from './validate.js';
+import { assertCivil, assertShifted } from './validate.js';
+import { fail } from './fail.js';
 import { ganyingOf, LIUYI_RU_MU } from './qimen-ganying.js';
 
 const TIAN_GAN = ['甲', '乙', '丙', '丁', '戊', '己', '庚', '辛', '壬', '癸'];
@@ -44,7 +45,11 @@ const indexOfGz = (gz) => {
 };
 
 /** 由公历时刻构建快照（本地民用时间轴） */
-export function buildSnapshot({ year, month, day, hour, minute, lateZiHourMode = 'same-day' }) {
+export function buildSnapshot(input) {
+  if (!input || typeof input !== 'object') {
+    throw fail('E_INPUT', '奇门排盘参数不能为空：至少给 year / month / day / hour');
+  }
+  const { year, month, day, hour, minute, lateZiHourMode = 'same-day' } = input;
   assertCivil({ year, month, day, hour, minute });
   const jd = partsToJd({ year, month, day, hour, minute });
 
@@ -52,11 +57,15 @@ export function buildSnapshot({ year, month, day, hour, minute, lateZiHourMode =
   const baseJdn = partsToJd({ year, month, day, hour: 12, minute: 0 });
   const jdn = Math.floor(baseJdn + 0.5);
   const isLateZi = hour >= 23;
+  // 晚子时归次日若跨出 1600–2400，直接拒绝：不能拿 2401 的日柱排盘
+  if (isLateZi && lateZiHourMode === 'next-day') assertShifted(jdToParts(jd + 1), '奇门');
   const dayJdn = isLateZi && lateZiHourMode === 'next-day' ? jdn + 1 : jdn;
   const dayGz = ganzhiName((((dayJdn + 49) % 60) + 60) % 60).name;
 
-  // 时干支（五鼠遁）：23:00 之后时柱一律按次日的日干起子时，
-  // 这样 same-day / next-day 两种口径只有日柱不同、时柱一致（与参照实现一致）。
+  // 时干支（五鼠遁）：23:00 之后时柱一律按「次日」日干起子时。
+  // 因此 same-day / next-day 两种口径只差日柱、时柱保持一致；代价是会出现
+  // 「甲子日 + 丙子时」这种按当日日干推不出的组合（晚子时固定口径，README 与测试已锁）。
+  // 奇门以时柱定值符值使与局，两个口径的差异从日柱进入，不能把日柱当成无关紧要的细节。
   const hourBranchIdx = Math.floor(((hour + 1) % 24) / 2);
   const hourStemBasisJdn = isLateZi ? jdn + 1 : jdn;
   const hourBasisGz = ganzhiName((((hourStemBasisJdn + 49) % 60) + 60) % 60).name;
@@ -204,7 +213,8 @@ export function stemPalaceRelation(stem, palace) {
 // ── 六仪击刑 / 三奇入墓 ─────────────────────────────────────
 // 两者都是「天盘干落到某个宫就成立」的硬条件，与门迫一样只作宫位条件，不下吉凶。
 // 六仪击刑按地支相刑推：子刑卯、戌刑未、申刑寅、午自刑、辰自刑、寅刑巳；
-// 三奇入墓按五行墓库推：乙木墓未（未在坤二宫）、丙丁火墓戌（戌在乾六宫）。
+// 三奇入墓按《玄机赋》阴干逆行取墓：乙阴木墓戌、丙阳火墓戌（同落乾六），丁阴火墓丑（艮八）。
+// 注意别再混入「阳木墓未」——那套口径会把乙判到坤二，与本插件引文相反。
 const JI_XING = {
   戊: { palace: '3', zhi: '卯', basis: '甲子戊，子刑卯' },
   己: { palace: '2', zhi: '未', basis: '甲戌己，戌刑未' },
@@ -214,9 +224,9 @@ const JI_XING = {
   癸: { palace: '4', zhi: '巳', basis: '甲寅癸，寅刑巳' },
 };
 const RU_MU = {
-  乙: { palace: '2', zhi: '未', basis: '乙木墓于未，未在坤二宫' },
+  乙: { palace: '6', zhi: '戌', basis: '乙阴木墓于戌（玄机赋），戌在乾六宫' },
   丙: { palace: '6', zhi: '戌', basis: '丙火墓于戌，戌在乾六宫' },
-  丁: { palace: '6', zhi: '戌', basis: '丁火墓于戌，戌在乾六宫' },
+  丁: { palace: '8', zhi: '丑', basis: '丁阴火墓于丑（玄机赋），丑在艮八宫' },
 };
 
 /** 天盘六仪落刑宫 → [{palace, stem, zhi, basis}] */
@@ -357,7 +367,7 @@ function distributeBaShen(zhiFuGong, type) {
   return baShen;
 }
 
-function xunShouLiuYi(gz) {
+export function xunShouLiuYi(gz) {
   const tg = TIAN_GAN.indexOf(gz[0]);
   const dz = DI_ZHI.indexOf(gz[1]);
   if (tg === -1 || dz === -1) return '戊';
@@ -401,13 +411,18 @@ function calcJuShu(snapshot, juMethod = 'chaibu') {
       termName = snapshot.fuTouTermName || termName;
       note = `置闰法：超神 ${lead} 天，但不在芒种/大雪窗口，按超神接气取${termName}`;
     } else {
-      note = `置闰法：符头距${snapshot.nextTermName} ${lead} 天，未达置闰条件，按拆补处理`;
+      note = lead == null
+        ? '置闰法：缺少符头距下一节气天数，按拆补处理'
+        : `置闰法：符头距${snapshot.nextTermName} ${lead} 天，未达置闰条件，按拆补处理`;
     }
   }
   const nums = JU_NUMBERS_MAP[termName] || '111';
-  const num = Number(nums.charAt(yuan));
+  // 局数与元名必须同源：置闰把元改到「下元」后，局数也得取 nums 的第三位，
+  // 否则会排出「阴遁九局（下元）」却用上元的局数
+  const effYuan = yuanOverride >= 0 ? yuanOverride : yuan;
+  const num = Number(nums.charAt(effYuan));
   const CN = { 1: '一', 2: '二', 3: '三', 4: '四', 5: '五', 6: '六', 7: '七', 8: '八', 9: '九' };
-  const yuanName = ['上元', '中元', '下元'][yuanOverride >= 0 ? yuanOverride : yuan];
+  const yuanName = ['上元', '中元', '下元'][effYuan];
   return {
     jieQiName: termName,
     juMethod,
@@ -440,6 +455,9 @@ const findGong = (obj, val) =>
 
 /** 排盘主函数 */
 export function buildQimen(input) {
+  if (!input || typeof input !== 'object') {
+    throw fail('E_INPUT', '奇门排盘参数不能为空：至少给 year / month / day / hour');
+  }
   // snapshot 是内部快照路径（已由 buildSnapshot 校验过），不必重复校验
   if (!input.snapshot) assertCivil(input);
   const snapshot = input.snapshot || buildSnapshot(input);
@@ -468,7 +486,8 @@ export function buildQimen(input) {
   });
   tianPan['5'] = diPan['5'] || ''; // 中五宫天盘取本宫地盘干
 
-  const kongZhi = KONG_WANG[snapshot.dayXun === xunOf(hourGz) ? xunOf(hourGz) : xunOf(hourGz)] || [];
+  // 时家奇门按时辰所在旬取空亡（如甲子旬空戌亥），不看日旬
+  const kongZhi = KONG_WANG[xunOf(hourGz)] || [];
   const kongGong = kongZhi.map((z) => ZHI_TO_GONG[z]).filter(Boolean);
   const maMap = { 申: '寅', 子: '寅', 辰: '寅', 寅: '申', 午: '申', 戌: '申', 亥: '巳', 卯: '巳', 未: '巳', 巳: '亥', 酉: '亥', 丑: '亥' };
   const maZhi = maMap[hourGz[1]] || '';
@@ -566,7 +585,7 @@ export function buildQimen(input) {
       '定局：以日干支符头定上中下元（子午卯酉上元、寅申巳亥中元、辰戌丑未下元），按节气取局数',
       '阴阳遁：冬至至夏至前用阳遁，夏至至冬至前用阴遁',
       '中五宫寄坤二宫；天盘随值符旋转，八神随值符落宫顺（阳）/逆（阴）布',
-      '本次未实现超神接气与置闰，采用拆补法',
+      '定局可选拆补法（默认）、超神接气法、置闰法：超神接气局随符头，置闰仅在芒种/大雪后符头超前 9 日以上时启用',
     ],
   };
 }

package/engine/rectify.js

@@ -11,6 +11,8 @@ const KINDS = ['career', 'wealth', 'love', 'move', 'health', 'other'];
 const HOURS = [0, 1, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 23];
 /** 事件条数上限：对账用不到几百条，超限是输入异常而不是需求 */
 const MAX_EVENTS = 200;
+/** 事件年份跨度上限：人活着的事件区间本来就窄，超宽只会把流年表撑爆 */
+const MAX_SPAN = 120;
 
 const TEN_GOD = (l) => l.stemTenGod || '';
 const has = (l, re) => re.test((l.relations || []).join(''));
@@ -81,7 +83,26 @@ export function rectifyBirth(opts) {
     e.code = 'E_INPUT';
     throw e;
   }
+  // 出生前的事件不参与对账：以前照样进窗口并计分，一个填错的年份就能把整体排序拉走，
+  // 而排序看起来仍是「算出来的」。报错而不是静默丢掉——静默会让调用方以为它在名单里。
+  const beforeBirth = clean.filter((x) => x.year < base.year);
+  if (beforeBirth.length) {
+    const e = new Error(`事件年份早于出生年 ${base.year}：${beforeBirth.map((x) => x.year).join('、')}——生时校正只对出生以后发生的事打分`);
+    e.code = 'E_INPUT';
+    throw e;
+  }
   const nowYear = clean.reduce((m, x) => (x.year < m ? x.year : m), clean[0].year);
+  // 流年表默认只有 10 条：事件比最早一条晚十年以上时永远查不到，被当成「没对上」，
+  // 对所有候选同样落空，只会白白拉低命中率。窗口要覆盖到最晚一条事件。
+  const lastYear = clean.reduce((m, x) => (x.year > m ? x.year : m), clean[0].year);
+  // 窗口按事件年份逐年排盘，跨度不设上限就等于「两个年份决定要排多少张盘」：
+  // [{year:1601},{year:2399}] 会让每个候选摊上 799 年流年，实测 1267ms（30 年跨度只有 9ms）。
+  if (lastYear - nowYear + 1 > MAX_SPAN) {
+    const e = new Error(`事件年份跨度太大：${nowYear}–${lastYear} 共 ${lastYear - nowYear + 1} 年，最多 ${MAX_SPAN} 年`
+      + '——只报真正相关的几十年，别用两个极端年份把窗口撑开');
+    e.code = 'E_INPUT';
+    throw e;
+  }
   // 候选时辰同样要限：一天只有 12 个时辰，给了 1000 个就是白排 1000 张盘
   const wanted = Array.isArray(opts.hours) && opts.hours.length
     ? [...new Set(opts.hours.filter((h) => Number.isInteger(h) && h >= 0 && h <= 23))]
@@ -106,6 +127,7 @@ export function rectifyBirth(opts) {
       longitude: typeof opts.longitude === 'number' ? opts.longitude : undefined,
       geo: opts.geo && typeof opts.geo === 'object' ? opts.geo : undefined,
       nowYear,
+      liunianTo: lastYear,
     });
     const matched = [];
     const missed = [];
@@ -126,23 +148,42 @@ export function rectifyBirth(opts) {
       missedYears: missed.map((x) => x.year),
     };
   });
-  candidates.sort((a, b) => b.score - a.score || a.hour - b.hour);
+  // 真太阳时校正后，不同整点可能落进同一时辰（如东经 114.5° 一带 0:00 与 1:00 都在子时），
+  // 排出来的盘完全一样。重复列 14 条会让用户以为有 14 种可能，这里按盘面合并。
+  const merged = [];
+  const seen = new Map();
+  for (const c of candidates) {
+    const key = `${c.dayGanzhi}|${c.hourGanzhi}`;
+    const hit = seen.get(key);
+    if (hit) {
+      hit.hours.push(c.hour);
+      hit.label = `${hit.hours.map((h) => `${String(h).padStart(2, '0')}:00`).join(' / ')} 起`;
+      continue;
+    }
+    const item = { ...c, hours: [c.hour], label: `${String(c.hour).padStart(2, '0')}:00 起` };
+    seen.set(key, item);
+    merged.push(item);
+  }
+  merged.sort((a, b) => b.score - a.score || a.hour - b.hour);
 
-  const days = [...new Set(candidates.map((c) => c.dayGanzhi))];
-  const best = candidates[0];
-  const second = candidates[1];
+  const days = [...new Set(merged.map((c) => c.dayGanzhi))];
+  const best = merged[0];
+  const second = merged[1];
   const tie = second && second.score === best.score;
+  const dropped = candidates.length - merged.length;
 
   return {
     system: 'bazi',
     base,
     events: clean,
     hours,
-    candidates,
+    candidates: merged,
     best: best || null,
     tie,
     dayChanged: days.length > 1,
-    note: `候选 ${candidates.length} 个：命中数最高 ${best ? best.hits : 0}/${clean.length}${tie ? `（有并列：${candidates.filter((c) => c.score === best.score).map((c) => c.hour).join('、')} 点）` : ''}。` +
+    note: `候选 ${merged.length} 组：命中数最高 ${best ? best.hits : 0}/${clean.length}${tie ? `（有并列：${merged.filter((c) => c.score === best.score).map((c) => c.hours.join('/')).join('、')} 点）` : ''}。` +
+      (dropped ? `输入 ${candidates.length} 个整点中有 ${dropped} 个与相邻整点落在同一时辰，已合并为同一组。` : '') +
+      `事件按 ${nowYear}–${lastYear} 年逐年对账（共 ${lastYear - nowYear + 1} 年）。` +
       (days.length > 1 ? `注意：跨 23:00 的候选会改变日柱（${days.join(' / ')}），这类差异比时柱更关键。` : '候选之间只差时柱（日柱未变）。') +
       ' 这是缩小范围的参考，不替代出生记录；命中数接近时不要硬选。',
   };

package/engine/star.js

@@ -1,6 +1,7 @@
 // 星座档案 + 当日娱乐向基调：纯本地确定性（同一天同一星座结果永远一致）。
 // 星座按太阳过宫的通行日期区间（公历）；当日基调由日期哈希生成，不是随机数。
-import { daysInMonth } from './validate.js';
+import { MAX_YEAR, MIN_YEAR, daysInMonth } from './validate.js';
+import { fail } from './fail.js';
 
 /** 12 星座（区间含起止日；摩羯跨年由两端分别匹配）。 */
 export const SIGNS = [
@@ -50,11 +51,11 @@ const TONE_TEXT = {
 export function buildStar(input) {
   const { year, month, day } = input || {};
   if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)
-    || year < 1900 || year > 2100 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
-    throw new Error('星座需要真实存在的公历日期（year 1900–2100、month、day）——请向用户询问');
+    || year < MIN_YEAR || year > MAX_YEAR || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
+    throw fail('E_INPUT', `星座需要真实存在的公历日期（year ${MIN_YEAR}–${MAX_YEAR}、month、day）——请向用户询问`);
   }
   const sign = signOfDate(month, day);
-  if (!sign) throw new Error(`无法识别星座：${year}-${month}-${day}`);
+  if (!sign) throw fail('E_INPUT', `无法识别星座：${year}-${month}-${day}`);
   const dims = ['事业', '感情', '财运', '健康'].map((k, i) => {
     const stars = (daySeed(year, month, day, i + 1) % 5) + 1;
     return { name: k, stars, text: TONE_TEXT[stars] };