dsh-metaphysics 0.56.0 → 0.58.0

package/engine/geju.js

@@ -303,6 +303,8 @@ function specialPatterns(pillars, dayStem, monthBranch, strength, wuxing, gods)
 // 用神与忌神两行在局中都真有分量、且相克时，五行里恰有一行能接上——克方所生、且能生被克方。
 // 只报这一行在局中的分量，不判「关通了就吉」。
 const TONGGUAN_MIN = 1.5;
+/** 忌神在全局不足这个分量时，展示层降为「中性偏忌」（仍留在 avoid 里参与行运评分） */
+const NEUTRAL_MAX = 0.5;
 export function tongguanOf(favor = [], avoid = [], wuxing = {}) {
   const w = (el) => Math.round((Number(wuxing[el]) || 0) * 10) / 10;
   for (const use of favor) {
@@ -378,6 +380,14 @@ function yongshenOf(dayStem, monthBranch, strength, wuxing, branches = []) {
   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 disputedTenGods = Array.from(new Set(disputed.flatMap((d) => expand[roleName(d.element)] || [])));
+  // 中性偏忌：忌神里全局分量极轻（不足 NEUTRAL_MAX 分）的那些。
+  // 不从 avoid 里删——行运评分要让「这一行走运到位」仍按忌计分：局中没有，不等于运里不来。
+  // 只在展示层把它们从「实忌」降为「中性偏忌」，避免把一张几乎无该行的盘说成三行皆忌。
+  const weightOf = (el) => Math.round((Number(wuxing[el]) || 0) * 10) / 10;
+  const neutral = avoid
+    .filter((el) => weightOf(el) < NEUTRAL_MAX)
+    .map((el) => ({ element: el, role: roleName(el), verb: ROLE_VERB[roleName(el)], weight: weightOf(el) }));
+  const neutralTenGods = Array.from(new Set(neutral.flatMap((n) => expand[n.role] || [])));
   const tongguan = tongguanOf(favor, avoid, wuxing);
 
   const describe = (el) => `${el}（${roleName(el)}·${ROLE_VERB[roleName(el)]}）`;
@@ -387,6 +397,9 @@ function yongshenOf(dayStem, monthBranch, strength, wuxing, branches = []) {
   const detail = [
     `日主${dayStem}${me}，${strength.level}（${strength.score} 分）：`,
     `喜${favor.map(describe).join('、') || '—'}；忌${avoid.map(describe).join('、') || '—'}。`,
+    neutral.length
+      ? `中性偏忌：${neutral.map((n) => `${n.element}（局中 ${n.weight} 分）`).join('、')}——分量近零，不作实忌论，但不从此盘喜忌中删除（行运遇之仍按忌计）。`
+      : '',
     disputed.length ? `有争议：${disputedText}。` : '',
     !weak && !strong ? '身中和，先取调候与通关，喜忌随大运流年动态变化。' : '',
     `调候：${climate.label}（${(climate.evidence || []).join('、')}）${climate.need ? `，取${climate.need.stem}${climate.need.element}，忌${climate.avoidElement}${disputed.some((d) => d.element === climate.avoidElement) ? '（有争议）' : ''}` : '，气候平和'}。`,
@@ -410,11 +423,14 @@ function yongshenOf(dayStem, monthBranch, strength, wuxing, branches = []) {
     favor,
     avoid,
     disputed,
+    neutral,
     favorRoles: favor.map(roleName),
     avoidRoles: avoid.map(roleName),
+    neutralRoles: neutral.map((n) => n.role),
     favorTenGods,
     avoidTenGods,
     disputedTenGods,
+    neutralTenGods,
     tiaohou: { ...climate, ...arb, element: climate.need ? climate.need.element : null },
     climate,
     qt,

package/engine/handle.js

@@ -0,0 +1,192 @@
+// C1 排盘句柄：把「排这张盘用的参数」压成一段自包含的短字符串。
+//
+// 为什么要自包含而不用内存缓存：工具每次调用可能落在不同进程里（宿主一次工具调用
+// 一个进程），内存里的句柄拿到下一次就失效。这里把参数本身编码进句柄，
+// 任何进程、任何会话都能还原——代价是句柄里带着输入，所以它是编码，不是加密。
+//
+// 用法：
+//   const r = compute({ system: 'bazi', datetime: '1996-01-19T07:31', gender: 'male', address: '安徽池州' });
+//   r.handle                       // 'mc1.eyJ... .a1b2c3d4'
+//   compute({ handle: r.handle, asOf: 2030 })   // 只传增量，参数自动并回去
+//
+// 约定：
+//   * 只收「影响盘面」的参数；trace / shadow / withInterpret / ask 这类输出开关不进句柄，
+//     所以同一张盘无论要不要解析、要不要推导链，句柄都一样；
+//   * 带校验位：句柄被截断或改了字符会报 E_HANDLE，而不是静默排成另一张盘；
+//   * 键序固定，参数写法不同（例如先 system 后 datetime）也得到同一个句柄。
+import { fail } from './fail.js';
+
+const PREFIX = 'mc1.';
+
+/**
+ * 不进句柄的参数：它们只改输出形态或只对某一次追问有效，不影响盘面。
+ * 反过来，seed / asOf / direction / 各流派开关都必须留下——少了它们就复现不出同一张盘。
+ */
+const SKIP = new Set([
+  'handle', 'trace', 'shadow', 'shadowVersion', 'diff', 'withInterpret', 'cross',
+  'verifyPast', 'rectify', 'events', 'ask', 'followup', 'question', 'geocode', 'caliber',
+  // 一句话改参是把原话翻成补丁：补丁已经落在其余参数里，原话本身不进句柄，
+  // 否则同一张盘换个说法就换一个句柄，回放时还会再套一遍补丁。
+  'revise',
+]);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** 稳定序列化：对象键排序，数组按原序；只收 JSON 能表达的值 */
+function stable(v) {
+  if (Array.isArray(v)) return `[${v.map((x) => stable(x === undefined ? null : x)).join(',')}]`;
+  if (isObject(v)) {
+    const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stable(v[k])}`).join(',')}}`;
+  }
+  const s = JSON.stringify(v === undefined ? null : v);
+  return s === undefined ? 'null' : s;
+}
+
+/** FNV-1a 32 位：足够挡手误改字与截断，不承担抗篡改 */
+function checksum(text) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+// base64url 与 UTF-8 都自己实现：引擎要同时在 Node、浏览器与 vm 沙箱里跑，
+// 不能依赖 Buffer，也不能假设宿主有 btoa / TextEncoder。
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+function utf8Bytes(str) {
+  const out = [];
+  for (const ch of String(str)) {
+    let cp = ch.codePointAt(0);
+    if (cp < 0x80) out.push(cp);
+    else if (cp < 0x800) out.push(0xc0 | (cp >> 6), 0x80 | (cp & 63));
+    else if (cp < 0x10000) out.push(0xe0 | (cp >> 12), 0x80 | ((cp >> 6) & 63), 0x80 | (cp & 63));
+    else out.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 63), 0x80 | ((cp >> 6) & 63), 0x80 | (cp & 63));
+  }
+  return out;
+}
+
+function utf8String(bytes) {
+  let out = '';
+  for (let i = 0; i < bytes.length;) {
+    const b = bytes[i];
+    let cp;
+    let n;
+    if (b < 0x80) { cp = b; n = 1; }
+    else if (b < 0xe0) { cp = b & 31; n = 2; }
+    else if (b < 0xf0) { cp = b & 15; n = 3; }
+    else { cp = b & 7; n = 4; }
+    for (let k = 1; k < n; k++) cp = (cp << 6) | (bytes[i + k] & 63);
+    i += n;
+    out += String.fromCodePoint(cp);
+  }
+  return out;
+}
+
+function b64url(str) {
+  const bytes = utf8Bytes(str);
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+    out += B64[a >> 2];
+    out += B64[((a & 3) << 4) | ((b === undefined ? 0 : b) >> 4)];
+    if (b === undefined) break;
+    out += B64[((b & 15) << 2) | ((c === undefined ? 0 : c) >> 6)];
+    if (c === undefined) break;
+    out += B64[c & 63];
+  }
+  return out;
+}
+
+function unb64url(s) {
+  const bytes = [];
+  let buf = 0;
+  let bits = 0;
+  for (const ch of s) {
+    const v = B64.indexOf(ch);
+    if (v < 0) throw new Error(`不是 base64url 字符：${ch}`);
+    buf = (buf << 6) | v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buf >> bits) & 0xff);
+    }
+  }
+  return utf8String(bytes);
+}
+
+/** 从参数里挑出要进句柄的那部分 */
+export function handlePayload(args = {}) {
+  const out = {};
+  for (const [k, v] of Object.entries(args || {})) {
+    if (SKIP.has(k) || v === undefined) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * 参数 → 句柄。参数里没有可编码内容时返回 ''（例如只传了 { trace: true }）。
+ * @returns {string}
+ */
+export function encodeHandle(args = {}) {
+  const payload = handlePayload(args);
+  if (!Object.keys(payload).length) return '';
+  const body = b64url(stable(payload));
+  return `${PREFIX}${body}.${checksum(body)}`;
+}
+
+/**
+ * 句柄 → 参数。任何不合法都抛 E_HANDLE，并在文案里说清是哪一步不对。
+ * @returns {object}
+ */
+export function decodeHandle(handle) {
+  if (typeof handle !== 'string' || !handle.trim()) {
+    throw fail('E_HANDLE', 'handle 必须是非空字符串；没拿到句柄时照常传 system + datetime 等原始参数即可');
+  }
+  const s = handle.trim();
+  if (!s.startsWith(PREFIX)) {
+    throw fail('E_HANDLE', `handle 前缀不对（应以 ${PREFIX} 开头）：句柄来自旧版本或复制不全，重新排一次盘取新的 handle`);
+  }
+  const rest = s.slice(PREFIX.length);
+  const dot = rest.lastIndexOf('.');
+  if (dot <= 0) throw fail('E_HANDLE', 'handle 缺少校验位：复制时可能被截断，重新取一次');
+  const body = rest.slice(0, dot);
+  const sum = rest.slice(dot + 1);
+  if (checksum(body) !== sum) {
+    throw fail('E_HANDLE', 'handle 校验不通过：内容被改动或截断，重新排一次盘取新的 handle');
+  }
+  let payload;
+  try {
+    payload = JSON.parse(unb64url(body));
+  } catch (e) {
+    throw fail('E_HANDLE', 'handle 内容无法解析（不是本插件生成的句柄），重新排一次盘取新的 handle');
+  }
+  if (!isObject(payload)) throw fail('E_HANDLE', 'handle 内容不是参数对象，重新排一次盘取新的 handle');
+  return payload;
+}
+
+/**
+ * 把 handle 与增量参数并起来。没有 handle 时原样返回（深一层的浅拷贝，避免改调用方对象）。
+ * 增量优先：{ handle, asOf: 2030 } 只覆盖 asOf，其余沿用原参数。
+ */
+export function resolveHandle(args = {}) {
+  if (!isObject(args)) return args;
+  const { handle, ...rest } = args;
+  if (handle === undefined || handle === null || handle === '') return { ...rest };
+  const base = decodeHandle(handle);
+  // 显式的 undefined 当作「没传」：否则 { handle, datetime: undefined } 会把句柄里的日期抹掉
+  const out = { ...base };
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+export const HANDLE_PREFIX = PREFIX;
+export const handleChecksum = checksum;

package/engine/hepan.js

@@ -61,6 +61,49 @@ function yearBranchRelation(a, b) {
   return { name: '无直接关系', score: 0, text: '属相之间没有合冲刑害，表层影响小，以日柱为主' };
 }
 
+/**
+ * 三方合盘：把三对两两结果并列，不合成「三人总分」。
+ * 任何两两关系都独立成立，合成一个数会把「和谁相处」混为一谈；
+ * 这里只做三件事：列出每对的分数与三维度、指出最顺/最需磨合的一对、找出差异最大的一维。
+ * @param {{key:string,a:string,b:string,result:object}[]} pairs 三对结果（顺序固定为 a-b、a-c、b-c）
+ */
+export function tripleOf(pairs) {
+  const brief = (r) => {
+    const s = (r && r.score) || {};
+    return {
+      total: typeof s.total === 'number' ? s.total : null,
+      level: s.level || '',
+      dimensions: (Array.isArray(r && r.dimensions) ? r.dimensions : [])
+        .map((d) => ({ key: d.key, label: d.label, score: typeof d.score === 'number' ? d.score : 0 })),
+    };
+  };
+  const rows = pairs.map((p) => ({ key: p.key, a: p.a, b: p.b, ...brief(p.result) }));
+  const sorted = rows.filter((x) => typeof x.total === 'number').sort((x, y) => y.total - x.total);
+  const best = sorted[0] || null;
+  const hardest = sorted[sorted.length - 1] || null;
+  // 同一维度在三对里差得最多的一维：三方之间最敏感的地方
+  let focus = null;
+  const keys = rows[0] ? rows[0].dimensions.map((d) => d.key) : [];
+  for (const key of keys) {
+    const vals = rows.map((r) => (r.dimensions.find((d) => d.key === key) || {}));
+    const scores = vals.map((d) => (typeof d.score === 'number' ? d.score : 0));
+    const spread = Math.max(...scores) - Math.min(...scores);
+    if (!focus || spread > focus.spread) {
+      focus = { key, label: (vals[0] && vals[0].label) || key, spread };
+    }
+  }
+  return {
+    pairs: rows,
+    best: best ? { key: best.key, a: best.a, b: best.b, total: best.total, level: best.level } : null,
+    hardest: hardest && hardest !== best
+      ? { key: hardest.key, a: hardest.a, b: hardest.b, total: hardest.total, level: hardest.level }
+      : null,
+    spread: best && hardest ? best.total - hardest.total : 0,
+    focus,
+    note: '三方只把三对两两关系并列，不合成「三人总分」：和不同的人相处是不同的事，合成一个数会把差异抹平。',
+  };
+}
+
 /** 合盘主函数 */
 export function buildHepan(input) {
   assertCivil(input && input.a, 'a');