dsh-metaphysics 0.62.0 → 0.62.2

package/engine/liuyao.js

@@ -3,6 +3,7 @@ import { STEMS, BRANCHES, toJDN, ganzhiName, dayGanzhiIndex, sexagenaryIndex, xu
 import { jingText } from './yijing-text.js';
 import { fail } from './fail.js';
 import { assertObject } from './validate.js';
+import { randomOf, isSeed } from './random.js';
 
 // 八卦三位（自下而上，1 = 阳）
 const TRIGRAM_BITS = {
@@ -335,10 +336,8 @@ const sideOf = (position) => (position <= 3 ? 'inner' : 'outer');
  * @param {{direction?:string, gender?:string}} [opts]
  */
 export function yongshenOf(result, opts = {}) {
-  // opts 允许省略或传 null（都按默认口径），但显式给了别的东西就必须是对象：
+  opts = liuyaoOpts(opts, 'yongshenOf 的 opts', '{ direction?, gender? }');
   // 以前 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 : [];
@@ -490,6 +489,14 @@ function isMoving(v) {
  */
 export function buildLiuyao(input = {}) {
   if (!input || typeof input !== 'object') throw fail('E_INPUT', '六爻起卦参数不能为空：至少给 lines 或 seed');
+  // seed 以前只写在文档里：直接 buildLiuyao({ seed }) 仍走 Math.random，
+  // 同一个 seed 摇不出同一卦，句柄却按 seed 算了身份。这里与工具层同一把尺。
+  if (input.seed !== undefined && input.seed !== null && input.seed !== '' && !isSeed(input.seed)) {
+    throw fail('E_INPUT', `seed 必须是数字，收到「${String(input.seed).slice(0, 24)}」`);
+  }
+  if (input.random !== undefined && input.random !== null && typeof input.random !== 'function') {
+    throw fail('E_INPUT', `random 必须是函数，收到 ${typeof input.random}`);
+  }
   // lines 给了但不是数组（"7,8,9,6,7,8" / 789678 / {…}）以前等同于「没给」：
   // 用户以为摇的是自己记下的那一卦，实际拿到一张随机盘，而且看不出来。
   if (input.lines !== undefined && input.lines !== null && !Array.isArray(input.lines)) {
@@ -501,7 +508,8 @@ export function buildLiuyao(input = {}) {
   if (given && given.length !== 6) {
     throw fail('E_LINES', `lines 必须是 6 个爻值（自下而上），收到 ${given.length} 个`);
   }
-  const rawLines = given ? given.slice() : tossLines(input.random);
+  const rand = typeof input.random === 'function' ? input.random : randomOf(input.seed);
+  const rawLines = given ? given.slice() : tossLines(rand);
 
   const invalid = rawLines.filter((v) => ![6, 7, 8, 9].includes(v));
   if (invalid.length) throw fail('E_LINES', `爻值只能是 6/7/8/9，收到 ${JSON.stringify(rawLines)}`);
@@ -513,7 +521,7 @@ export function buildLiuyao(input = {}) {
   const bian = bianBits ? hexagramFromBits(bianBits) : null;
 
   const dayGanZhi = input.dayGanZhi ?? (() => {
-    const now = new Date();
+    const now = new Date(); // allow-clock: 未传日辰时按起卦当天取日干起六神；asOf 可钉死
     const jdn = toJDN(now.getFullYear(), now.getMonth() + 1, now.getDate());
     const g = ganzhiName(dayGanzhiIndex(jdn));
     return { stem: g.stem, branch: g.branch, name: g.name };
@@ -662,6 +670,12 @@ export function dayRelationOf(element, dayElement) {
   return 'unknown';
 }
 
+/** opts 省略或传 null 都按默认口径；显式给了别的类型则当场报 E_INPUT。 */
+function liuyaoOpts(opts, who, shape) {
+  if (opts === null || opts === undefined) return {};
+  return assertObject(opts, who, `${shape}；省略或 null 按默认口径`);
+}
+
 /**
  * 用神旺衰：把月建、日辰两股外部力量落到用神那几爻上。
  * 月建按月支、日辰按日支，各出自己的五行，再与本爻五行论生克；
@@ -671,6 +685,7 @@ export function dayRelationOf(element, dayElement) {
  * @param {{monthBranch?: string, dayBranch?: string}} opts
  */
 export function yongshenStrength(result, useGod, opts = {}) {
+  opts = liuyaoOpts(opts, 'yongshenStrength 的 opts', '{ monthBranch?, dayBranch? }');
   if (!useGod || !Array.isArray(useGod.found) || !useGod.found.length) return null;
   const monthBranch = opts.monthBranch || null;
   const dayBranch = opts.dayBranch || (result && result.dayGanZhi ? result.dayGanZhi.branch : null);
@@ -747,6 +762,7 @@ export const FUSHEN_VERDICTS = ['可出', '有助有压', '受压难出', '未
  * @param {{monthBranch?: string, dayBranch?: string}} opts
  */
 export function fushenAccess(result, useGod, opts = {}) {
+  opts = liuyaoOpts(opts, 'fushenAccess 的 opts', '{ monthBranch?, dayBranch? }');
   if (!useGod || !Array.isArray(useGod.fushen) || !useGod.fushen.length) return null;
   const monthBranch = opts.monthBranch || null;
   const dayBranch = opts.dayBranch || (result && result.dayGanZhi ? result.dayGanZhi.branch : null);
@@ -822,6 +838,7 @@ export function fushenAccess(result, useGod, opts = {}) {
 // 与用神旺衰同一套判定（月令五态、日辰五关系、三种冲法），区别只在不挑用神：
 // 六爻每一爻都给一次，世应、动爻、旬空另标，看得出整张卦的气压在哪一头。
 export function hexagramStrength(result, opts = {}) {
+  opts = liuyaoOpts(opts, 'hexagramStrength 的 opts', '{ monthBranch?, dayBranch? }');
   const rows = (result && result.ben && Array.isArray(result.ben.lines))
     ? result.ben.lines
     : (result && Array.isArray(result.lines) ? result.lines : []);
@@ -910,6 +927,7 @@ const TUI_VERDICT = { 旺: '退得缓', 相: '退得缓', 休: '退得实', 囚:
  * @param {{monthBranch?: string, dayBranch?: string}} opts
  */
 export function jinTuiPower(result, opts = {}) {
+  opts = liuyaoOpts(opts, 'jinTuiPower 的 opts', '{ monthBranch?, dayBranch? }');
   const items = result && result.body && Array.isArray(result.body.jinTui) ? result.body.jinTui : [];
   if (!items.length) return null;
   const rows = result && result.ben && Array.isArray(result.ben.lines) ? result.ben.lines : [];
@@ -983,6 +1001,7 @@ const TRIGGER_ORDER = ['逢值', '逢冲', '逢合', '出空填实', '冲空'];
  * @param {{monthBranch?: string}} opts
  */
 export function yingqiWindow(result, useGod, opts = {}) {
+  opts = liuyaoOpts(opts, 'yingqiWindow 的 opts', '{ monthBranch? }');
   if (!useGod || !useGod.liuqin) return null;
   const found = Array.isArray(useGod.found) ? useGod.found : [];
   const fushen = Array.isArray(useGod.fushen) ? useGod.fushen : [];

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) {
@@ -384,8 +385,11 @@ export function buildMbti(input = {}) {
       picked,
       strength: strengthOf(pct, answered),
       tie: sum === 0,
+      unanswered: answered === 0,
     };
   });
+  // 整维未答时 letter 只是 tie 占位；把它单独列出来，摘要与面板才不会当成「测出来了」
+  const unanswered = dims.filter((d) => d.unanswered).map((d) => d.key);
   const type = dims.map((d) => d.picked).join('');
   const profile = TYPES[type];
   if (!profile) throw fail('E_SYSTEM', `内部错误：类型 ${type} 没有对应文案`);
@@ -412,6 +416,8 @@ export function buildMbti(input = {}) {
     answered: answeredAll,
     skipped: QUESTIONS.length - answeredAll,
     total: QUESTIONS.length,
-    note: '四维各 6 题、李克特 1–5 计分，按维度净分取字母（平手时取 I / N / F / P 一侧并标「临界」）。这是 MBTI 风格的问卷测算，不是官方量表；类型只作自我参照，不是能力评价，也不用它给人下结论。',
+    unanswered,
+    note: '四维各 6 题、李克特 1–5 计分，按维度净分取字母（平手时取 I / N / F / P 一侧并标「临界」）。这是 MBTI 风格的问卷测算，不是官方量表；类型只作自我参照，不是能力评价，也不用它给人下结论。'
+      + (unanswered.length ? ` 本轮 ${unanswered.join('、')} 维度一题未答，该维按平手取字母，只作占位，参考价值有限。` : ''),
   };
 }

package/engine/meihua.js

@@ -2,6 +2,7 @@
 import { BRANCHES, fromJDN, toJDN } from './calendar.js';
 import { solarToLunar } from './lunar.js';
 import { fail } from './fail.js';
+import { bool } from './bool.js';
 import { parseDateTime } from './datetime.js';
 import { assertShifted } from './validate.js';
 import { hexagramFromBits } from './liuyao.js';
@@ -55,16 +56,29 @@ export function buildMeihua(input = {}) {
   let source;
 
   if (mode === 'number') {
-    const a = Number(input.upper);
-    const b = Number(input.lower);
-    if (!Number.isFinite(a) || !Number.isFinite(b)) throw fail('E_INPUT', '数字起卦需要两个数字（upper / lower），例如 upper=3、lower=5');
+    // 只认真正的数字：Number(null) / Number(false) / Number([]) 都是 0，
+    // 以前缺参或传错类型会静默起成「坤为地」，盘面看着正常却完全不是用户给的字数。
+    const a = input.upper;
+    const b = input.lower;
+    // 小数以前只过 Number.isFinite，mod8(3.5) 得到 4.5，bitsOf 查不到卦再在深处抛
+    // 「bitsOf is not a function」——参数错却报成内部错误。数字起卦只认整数。
+    if (typeof a !== 'number' || typeof b !== 'number' || !Number.isInteger(a) || !Number.isInteger(b)) {
+      throw fail('E_INPUT', '数字起卦需要两个整数（upper / lower），例如 upper=3、lower=5');
+    }
     upperNum = mod8(a);
     lowerNum = mod8(b);
     if (input.changing !== undefined && input.changing !== null && input.changing !== '') {
-      // 以前 99 会被 mod 6 折成 3：用户指定动爻却得到另一爻，结果里看不出来
-      const ch = Number(input.changing);
+      // 以前 99 会被 mod 6 折成 3：用户指定动爻却得到另一爻，结果里看不出来。
+      // Number(true)=1、Number([3])=3 也会静默通过，故只收数字或十进制数字串。
+      const raw = input.changing;
+      const ch = typeof raw === 'number'
+        ? raw
+        : typeof raw === 'string' && /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(raw.trim())
+          ? Number(raw.trim())
+          : NaN;
       if (!Number.isInteger(ch) || ch < 1 || ch > 6) {
-        throw fail('E_INPUT', `动爻 changing 必须是 1–6 的整数，收到「${input.changing}」`);
+        const shown = typeof raw === 'string' ? raw : JSON.stringify(raw);
+        throw fail('E_INPUT', `动爻 changing 必须是 1–6 的整数，收到「${shown}」`);
       }
       moving = ch;
     } else {
@@ -74,7 +88,7 @@ export function buildMeihua(input = {}) {
   } else {
     const dt = parseDateTime(input.datetime);
     // 晚子时换日与八字/六壬/奇门同口径：23:00–23:59 归次日，年月日电数才落在同一子时
-    const lateZi = input.lateZi !== false;
+    const lateZi = bool(input.lateZi, true);
     let sy = dt.year;
     let sm = dt.month;
     let sd = dt.day;

package/engine/name.js

@@ -4,6 +4,7 @@
 //       五格按康熙字典繁体笔画计（见 name-data.js 的口径说明），81 数理取通行本；
 //       音韵只做机械检查（同调、相邻同声母/同韵母、叠字），不做语义谐音判断。
 import { buildBazi } from './bazi.js';
+import { bool } from './bool.js';
 import { assertCivil, assertObject } from './validate.js';
 import { fail } from './fail.js';
 import {
@@ -267,19 +268,23 @@ const WX_REL = (a, b) => (a === b ? '同' : SHENG[a] === b ? '生' : KE[a] === b
 
 /** 数理超过 81 按传统「减 80 循环」取（如 104 → 24）。 */
 export function shuliOf(n) {
-  let x = n;
-  while (x > 81) x -= 80;
+  // 用取模代替 while 递减：strokeOverrides 允许用户给任意正整数，
+  // 以前给 1e12 会在这里空转一百多亿次，整次排盘卡死。
+  const x = n > 81 ? ((n - 1) % 80) + 1 : n;
   if (!(x >= 1)) return null;
   const row = SHULI_81[x];
   return row ? { num: x, level: row[0], name: row[1] } : null;
 }
 
-/** 合并两处笔画覆盖：surnameStrokes（按姓给的）+ strokeOverrides（逐字覆盖），后者优先。 */
+/** 合并两处笔画覆盖：surnameStrokes（按姓给的）+ strokeOverrides（逐字覆盖），后者优先。
+ *  笔画值允许数字串（`{"秋":"9"}`）：模型经 JSON 传参时常见，只在入口归一还不够——
+ *  这里再兜一层，免得「用户给了笔画却被静默按字库算」这种错法又冒出来。 */
 function overridesOf(input) {
   const out = {};
   for (const src of [input && input.surnameStrokes, input && input.strokeOverrides]) {
     if (!src || typeof src !== 'object') continue;
-    for (const [k, v] of Object.entries(src)) {
+    for (const [k, raw] of Object.entries(src)) {
+      const v = typeof raw === 'string' ? Number(raw.trim()) : raw;
       if (Number.isInteger(v) && v > 0) out[k] = v;
     }
   }
@@ -507,12 +512,14 @@ export function assessName(input) {
     assertCivil(input, 'birth');
     const r = buildBazi({
       year: input.year, month: input.month, day: input.day,
-      hour: Number.isInteger(input.hour) ? input.hour : 12,
+      // 只给日期时与 datetime:'YYYY-MM-DD' 同一口径（00:00 占位）；引擎摘要会标明缺时刻，
+      // 以前这里悄悄补 12:00，同一个生日走 datetime 和 year/month/day 会得到两档旺衰。
+      hour: Number.isInteger(input.hour) ? input.hour : 0,
       minute: Number.isInteger(input.minute) ? input.minute : 0,
       gender: input.gender || 'male',
-      lateZi: input.lateZi !== false,
-      trueSolar: input.trueSolar !== false,
-      dst: input.dst !== false,
+      lateZi: bool(input.lateZi, true),
+      trueSolar: bool(input.trueSolar, true),
+      dst: bool(input.dst, true),
       longitude: input.longitude, address: input.address, geo: input.geo,
     });
     strength = { level: r.strength.level, score: r.strength.score, dayElement: r.pillars.day.stemElement };
@@ -608,12 +615,13 @@ export function generateNames(input) {
   const limit = Math.max(1, Math.min(20, Number.isInteger(input.limit) ? input.limit : 10));
   const r = buildBazi({
     year: input.year, month: input.month, day: input.day,
-    hour: Number.isInteger(input.hour) ? input.hour : 12,
+    // 与 assessName 同一口径：缺时刻按 00:00 占位，由引擎摘要统一提示
+    hour: Number.isInteger(input.hour) ? input.hour : 0,
     minute: Number.isInteger(input.minute) ? input.minute : 0,
     gender,
-    lateZi: input.lateZi !== false,
-    trueSolar: input.trueSolar !== false,
-    dst: input.dst !== false,
+    lateZi: bool(input.lateZi, true),
+    trueSolar: bool(input.trueSolar, true),
+    dst: bool(input.dst, true),
     longitude: input.longitude, address: input.address, geo: input.geo,
   });
   const strength = { level: r.strength.level, score: r.strength.score, dayElement: r.pillars.day.stemElement };
@@ -726,6 +734,9 @@ 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,6 @@
 // 生命数字（西方数字学）：生命路径数 / 生日数 / 态度数，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 的数义（白话提炼）。 */
@@ -38,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 fail('E_INPUT', '生命数字需要真实存在的公历出生日期（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.js

@@ -5,6 +5,7 @@
 import { termInstantJd, termWindow, jdToParts, partsToJd, formatJd, ganzhiName, sexagenaryIndex, STEMS, BRANCHES } from './calendar.js';
 import { solarToLunar } from './lunar.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 });
 
@@ -450,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);

package/engine/random.js

@@ -22,20 +22,34 @@ export function mulberry32(seed) {
   };
 }
 
+// 与宿主 / bool.js 同一把尺：只认十进制（可带指数、尾点）。Number() 会把
+// "0x10"、false、[] 也变成有效数字，于是直接调引擎能排出盘、走工具层却被拒——
+// 同一份输入两种命运，正是句柄与复现最容易分叉的地方。
+const NUMERIC_TEXT = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+
+const seedNumber = (seed) => {
+  if (typeof seed === 'number') return Number.isFinite(seed) ? seed : NaN;
+  if (typeof seed === 'string') {
+    const s = seed.trim();
+    if (s !== '' && NUMERIC_TEXT.test(s)) return Number(s);
+  }
+  return NaN;
+};
+
 /**
  * 从参数里取随机源：
  * - 没给 seed：沿用 Math.random（保持"真随机"的手感）
- * - 给了数字或数字字符串：mulberry32(seed)，可复现
+ * - 给了数字或十进制数字串：mulberry32(seed)，可复现
  * - 给了别的东西：调用方应当先报错，这里兜底回 Math.random
  */
 export function randomOf(seed) {
   if (seed === undefined || seed === null || seed === '') return Math.random;
-  const n = Number(seed);
+  const n = seedNumber(seed);
   return Number.isFinite(n) ? mulberry32(n) : Math.random;
 }
 
 /** 是否是一个可以接受的 seed */
 export function isSeed(v) {
   if (v === undefined || v === null || v === '') return true;
-  return Number.isFinite(Number(v));
+  return Number.isFinite(seedNumber(v));
 }

package/engine/rectify.js

@@ -6,6 +6,7 @@
 //   2. 只有时柱（以及跨 23:00 时的日柱）会变，年/月柱通常不变，所以候选之间的差异集中在晚运、子女、事业后半段；
 //   3. 打分规则是显式、固定的（见 matchEvent），不是拟合；换一套规则排序可能变。
 import { buildBazi } from './bazi.js';
+import { bool } from './bool.js';
 
 const KINDS = ['career', 'wealth', 'love', 'move', 'health', 'other'];
 const HOURS = [0, 1, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 23];
@@ -120,9 +121,9 @@ export function rectifyBirth(opts) {
       hour,
       minute: 0,
       gender,
-      lateZi: opts.lateZi !== false,
-      trueSolar: opts.trueSolar !== false,
-      dst: opts.dst !== false,
+      lateZi: bool(opts.lateZi, true),
+      trueSolar: bool(opts.trueSolar, true),
+      dst: bool(opts.dst, true),
       address: typeof opts.address === 'string' ? opts.address : undefined,
       longitude: typeof opts.longitude === 'number' ? opts.longitude : undefined,
       geo: opts.geo && typeof opts.geo === 'object' ? opts.geo : undefined,

package/engine/star.js

@@ -1,6 +1,6 @@
 // 星座档案 + 当日娱乐向基调：纯本地确定性（同一天同一星座结果永远一致）。
 // 星座按太阳过宫的通行日期区间（公历）；当日基调由日期哈希生成，不是随机数。
-import { daysInMonth } from './validate.js';
+import { MAX_YEAR, MIN_YEAR, daysInMonth } from './validate.js';
 import { fail } from './fail.js';
 
 /** 12 星座（区间含起止日；摩羯跨年由两端分别匹配）。 */
@@ -51,8 +51,8 @@ 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 fail('E_INPUT', '星座需要真实存在的公历日期（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 fail('E_INPUT', `无法识别星座：${year}-${month}-${day}`);

package/engine/tarot.js

@@ -277,12 +277,17 @@ export function tarotDeck() {
 // 名称 → 牌面数据（解读时按名字回查，保证确定性、且不依赖调用方是否带全字段）
 const BY_NAME = new Map(tarotDeck().map((c) => [c.name, c]));
 
+// 外部手输/旧数据常见的另一种译名。只做显式别名，不做模糊匹配：
+// 拼错的牌名不能被猜成另一张，否则解读会披着别的牌义，错得看不出来。
+const CARD_ALIASES = { 愚人: '愚者' };
+const cardMeta = (name) => BY_NAME.get(CARD_ALIASES[name] || name) || null;
+
 const splitKeywords = (s) => String(s || '').split(/\s+/).filter(Boolean);
 
 /** 抽牌时刻（只做记录，不影响牌面） */
 function stamp(at) {
   if (typeof at === 'string' && at.trim()) return at.trim().replace('T', ' ').slice(0, 16);
-  const d = new Date();
+  const d = new Date(); // allow-clock: 未传 asOf 时记录抽牌时刻；牌面由 seed 固定
   const p = (x) => String(x).padStart(2, '0');
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 }
@@ -306,12 +311,17 @@ export function tarotReading(input = {}) {
   if (!n) return ['没有抽到牌面，无法解读。'];
 
   const names = list.map((c) => c.name).join(' / ');
+  // 牌库外的牌名不能悄悄读成「空牌义」：开场点名是哪几张，逐张处退回正/逆位泛义。
+  const unknown = list.map((c) => c.name).filter((name) => !cardMeta(name));
+  const unknownNote = unknown.length
+    ? `其中「${unknown.join('」「')}」不在韦特 78 张牌库里，这几张只按你给的位置与正逆位泛读，不补牌面、元素与占星对应。`
+    : '';
   const paras = [];
 
   // ① 开场：所问 + 象征系统声明
   paras.push(q
-    ? `你问的是「${q}」，抽到的是 ${n} 张牌阵（${names}）。塔罗是一套象征系统而不是判决：不同流派对牌义、编号与逆位的取舍略有差异，这里按 RWS（韦特）牌名与黄金黎明的元素对应来读，请把下面的话当作镜子，对照自己的处境取用。`
-    : `这次没有具体提问，那就先看牌面本身在说什么。牌阵 ${n} 张（${names}）。塔罗是象征系统，牌义随流派略有差异，这里按 RWS（韦特）与黄金黎明的常见对应来读，读到合用的部分就好。`);
+    ? `你问的是「${q}」，抽到的是 ${n} 张牌阵（${names}）。塔罗是一套象征系统而不是判决：不同流派对牌义、编号与逆位的取舍略有差异，这里按 RWS（韦特）牌名与黄金黎明的元素对应来读，请把下面的话当作镜子，对照自己的处境取用。${unknownNote}`
+    : `这次没有具体提问，那就先看牌面本身在说什么。牌阵 ${n} 张（${names}）。塔罗是象征系统，牌义随流派略有差异，这里按 RWS（韦特）与黄金黎明的常见对应来读，读到合用的部分就好。${unknownNote}`);
 
   // ② 逐张：位义 + 牌名/正逆 + 关键词 + 一句与位义结合的解读
   //    1-3 张时每张一段；4 张以上按前后两段分组（前段取 ceil(n/2) 张），
@@ -321,8 +331,10 @@ export function tarotReading(input = {}) {
   for (const group of groups) {
     const lines = group.map((i) => {
       const c = list[i];
-      const meta = BY_NAME.get(c.name) || {};
-      const kws = (c.keywords && c.keywords.length ? c.keywords : splitKeywords(c.upright ? meta.up : meta.down)).join('、');
+      const meta = cardMeta(c.name) || {};
+      // 牌库外又没有关键词时，退回正/逆位的泛义，别留下「正位：。」的空句
+      const kws = (c.keywords && c.keywords.length ? c.keywords : splitKeywords(c.upright ? meta.up : meta.down)).join('、')
+        || (c.upright === false ? '逆位泛义（阻滞、内转或用力过头）' : '正位泛义（推进、显化、顺势）');
       const ori = c.upright === false ? '逆位' : '正位';
       const oriNote = c.upright === false
         ? '逆位并不等于凶，更像这股力量还没顺过来，或用力过了头'
@@ -347,7 +359,7 @@ export function tarotReading(input = {}) {
   const upCount = n - revCount;
   const elementCount = {};
   for (const c of list) {
-    const e = (BY_NAME.get(c.name) || {}).element || c.element;
+    const e = (cardMeta(c.name) || {}).element || c.element;
     if (e) elementCount[e] = (elementCount[e] || 0) + 1;
   }
   const present = ELEMENT_ORDER.filter((e) => elementCount[e]);
@@ -376,7 +388,7 @@ export function tarotReading(input = {}) {
   const majorCard = list.find((c) => c.arcana === '大阿卡纳');
   const revCard = list.find((c) => c.upright === false);
   const key = majorCard || revCard || list[0];
-  const keyMeta = BY_NAME.get(key.name) || {};
+  const keyMeta = cardMeta(key.name) || {};
   const keyReason = majorCard
     ? '它出现的地方，往往就是这件事真正被牵动的层级'
     : revCard
@@ -449,7 +461,9 @@ export function drawTarot(input = {}) {
       keywords: splitKeywords(upright ? c.up : c.down),
     };
   });
-  const q = (question || '').trim();
+  // 直接调引擎时 question 可能是数字（工具层 schema 的 string 不做强转），
+  // 以前 (123 || '').trim() 会抛裸 TypeError，整张牌只剩一句内部错误。
+  const q = String(question == null ? '' : question).trim();
   return {
     system: 'tarot',
     question: q || null,

package/engine/trace.js

@@ -9,6 +9,7 @@ import { PATTERN_TONE } from './ziwei.js';
 import { yongshenOf, yongshenStrength, fushenAccess } from './liuyao.js';
 import { qimenYongshen } from './qimen-interpret.js';
 import { GAN_JI_GONG } from './daliuren.js';
+import { bool } from './bool.js';
 
 const SYSTEM_LABEL = { liuyao: '六爻', bazi: '八字', ziwei: '紫微', qimen: '奇门', daliuren: '大六壬' };
 
@@ -429,7 +430,7 @@ export function buildTrace(result, opts = {}) {
   if (result.system === 'liuyao') {
     let view = result;
     // 面板改了「询问方向」但不想重摇一卦：只按新方向重算用神相关三层
-    if (opts.refresh === true) {
+    if (bool(opts.refresh)) {
       try {
         const ug = yongshenOf(result, { direction: opts.direction, gender: opts.gender });
         const monthBranch = (result.hexStrength && result.hexStrength.month && result.hexStrength.month.branch)

package/engine/trend.js

@@ -4,6 +4,7 @@
 // 口径：这是一套**简化启发式**——十神计分表固定、正负号随日主旺衰方向翻转，
 // 只用于看形态与相对起伏；分高不等于真实吉凶，旺衰落在换档边界时连排序都不给。
 import { buildBazi, HIDDEN_STEMS, tenGod } from './bazi.js';
+import { bool } from './bool.js';
 import { ganzhiName, sexagenaryIndex, STEMS, BRANCHES } from './calendar.js';
 import { fail } from './fail.js';
 
@@ -85,6 +86,9 @@ function buildSegments(list, direction, birthYear, toAge) {
  *          address?:string,longitude?:number,geo?:object}} input
  */
 export function buildTrend(input) {
+  if (!input || typeof input !== 'object') {
+    throw fail('E_INPUT', '人生 K 线需要参数对象：至少给 datetime 与 gender（大运顺逆由性别决定）');
+  }
   const gender = input.gender;
   if (gender !== 'male' && gender !== 'female') {
     throw fail('E_INPUT', '人生 K 线需要性别：大运顺逆由性别决定，不可缺省');
@@ -104,10 +108,13 @@ export function buildTrend(input) {
     day: input.day,
     hour: Number.isInteger(input.hour) ? input.hour : 12,
     minute: Number.isInteger(input.minute) ? input.minute : 0,
+    // 时辰未知必须一路传到 buildBazi：它在内部统一按正午占位并收回时柱。
+    // 少了这一个键，摘要写着「按正午暂算」，旺衰却按 00:00 算成了另一档。
+    hourUnknown: bool(input.hourUnknown),
     gender,
-    lateZi: input.lateZi !== false,
-    trueSolar: input.trueSolar !== false,
-    dst: input.dst !== false,
+    lateZi: bool(input.lateZi, true),
+    trueSolar: bool(input.trueSolar, true),
+    dst: bool(input.dst, true),
     address: typeof input.address === 'string' ? input.address : undefined,
     longitude: typeof input.longitude === 'number' ? input.longitude : undefined,
     geo: input.geo && typeof input.geo === 'object' ? input.geo : undefined,

package/engine/xiaoliuren.js

@@ -1,6 +1,7 @@
 // 小六壬（诸葛马前课）：月/日/时（或报三个数）掐指落宫，六宫循环。
 // 口径：通行掌诀；断语为白话提炼（非原文照录）。轻量快占，属民俗参考。
 import { solarToLunar } from './lunar.js';
+import { bool } from './bool.js';
 import { hourToBranch } from './almanac.js';
 import { BRANCHES, fromJDN, toJDN } from './calendar.js';
 import { parseYmd } from './datetime.js';
@@ -49,7 +50,7 @@ export function buildXiaoliuren(input) {
     let y = mt.year;
     let mo = mt.month;
     let dy = mt.day;
-    const lateZi = input.lateZi !== false;
+    const lateZi = bool(input.lateZi, true);
     if (lateZi && input.hour >= 23) {
       const next = assertShifted(fromJDN(toJDN(y, mo, dy) + 1), '小六壬时间起课');
       y = next.year;

package/engine/ziwei.js

@@ -8,6 +8,7 @@ import { nayinOf } from './nayin.js';
 import { resolveAddress } from './geo.js';
 import { placeZuoyao, zuoyaoVerseBlock, ZUOYAO_SKIPPED } from './ziwei-zuoyao.js';
 import { SHA_STAR } from './ziwei-words.js';
+import { bool } from './bool.js';
 
 const fix = (i) => ((i % 12) + 12) % 12;
 
@@ -397,7 +398,7 @@ export function buildZiwei(input) {
   assertCivil(input);
   const schools = ziweiSchoolsOf(input);
   const { year: cy, month: cm, day: cd, hour: ch = 0, minute: cmin = 0, gender = 'male' } = input;
-  const useTrueSolar = input.trueSolar !== false;
+  const useTrueSolar = bool(input.trueSolar, true);
   const geo = input.geo || (input.address ? resolveAddress(input.address) : null);
   const longitude = typeof input.longitude === 'number'
     ? input.longitude
@@ -671,7 +672,7 @@ export function buildZiwei(input) {
   // 直接读挂钟的话，同一组参数（同一个句柄）跨年会排出不同的流年表，
   // 「同参数同盘」的承诺就只在当年成立。
   const asOfForLiunian = asOfParts(input.asOf);
-  const thisYear = (asOfForLiunian && asOfForLiunian.year) || new Date().getFullYear();
+  const thisYear = (asOfForLiunian && asOfForLiunian.year) || new Date().getFullYear(); // allow-clock: 未传 asOf 时按本机年份起流年；工具层 asOf 可钉死
   const liunian = [];
   for (let y = thisYear; y < thisYear + 12; y++) {
     const gz = ganzhiName((((y - 4) % 60) + 60) % 60);
@@ -1323,7 +1324,7 @@ export function asOfParts(v) {
 }
 
 export function flowOf(chart, asOf) {
-  const now = new Date();
+  const now = new Date(); // allow-clock: 流日/流时按调用时刻；显式 asOf 会覆盖
   const a = asOfParts(asOf) || {};
   const Y = a.year || now.getFullYear();
   const M = a.month || now.getMonth() + 1;