dsh-metaphysics 0.57.0 → 0.58.0

package/engine/index.js

@@ -5,13 +5,14 @@ import { buildZiwei, BRIGHTNESS, flowOf, asOfParts, ZIWEI_SCHOOL_DEFAULTS } from
 import { drawTarot } from './tarot.js';
 import { buildMeihua } from './meihua.js';
 import { buildDaliuren } from './daliuren.js';
-import { buildHepan } from './hepan.js';
+import { buildHepan, tripleOf } from './hepan.js';
 import { buildZiweiHepan } from './ziwei-hepan.js';
 import { buildQimen, buildSnapshot } from './qimen.js';
 import { geocodeAddress, resolveAddress } from './geo.js';
 import { toJDN, ganzhiName, dayGanzhiIndex } from './calendar.js';
 import { randomOf, isSeed } from './random.js';
 import { encodeHandle, decodeHandle, resolveHandle } from './handle.js';
+import { askLink, parseAskLink, formOf, restNote, askPackages } from './bridge.js';
 import { parseRevision, displayValue } from './revise.js';
 import { interpret, DIRECTIONS, DIRECTION_DEFAULT } from './interpret.js';
 import { followup, askPrompt } from './followup.js';
@@ -27,7 +28,7 @@ import { buildNumerology } from './numerology.js';
 import { buildMbti, mbtiPaper } from './mbti.js';
 import { buildConvert } from './convert.js';
 import { classicsFor, classicsText, suiyunClassicOf, classicOf, CLASSIC_BOOKS } from './classics.js';
-import { diffObjects, summarize, sortDiffs, labelOf, rootOf, categoryOf, formatValue, CALIBER_SWITCHES } from './diff.js';
+import { diffObjects, summarize, sortDiffs, labelOf, rootOf, categoryOf, formatValue, CALIBER_SWITCHES, viewRows } from './diff.js';
 import { canonicalJson, fingerprintOf } from './fingerprint.js';
 import { buildTrend } from './trend.js';
 import { buildFengshui } from './fengshui.js';
@@ -297,6 +298,26 @@ function qimenText(r) {
   ].join('\n');
 }
 
+function tripleText(t) {
+  if (!t || !Array.isArray(t.pairs) || !t.pairs.length) return [];
+  const lines = [
+    '【三方合盘】三对两两并列，不合成「三人总分」',
+    ...t.pairs.map((p) => `· ${p.a}–${p.b}：${p.level || '—'}（${p.total == null ? '—' : `${p.total}/100`}）`),
+  ];
+  if (t.best) {
+    // 差 1–2 分时点名「最顺/最需磨合」是假精确：三对分数接近就直说接近，不排名
+    if (t.spread >= 3) {
+      lines.push(`　最顺：${t.best.a}–${t.best.b}（${t.best.total}/100）`
+        + (t.hardest ? `；最需磨合：${t.hardest.a}–${t.hardest.b}（${t.hardest.total}/100）` : ''));
+    } else {
+      lines.push(`　三对分数接近（最高与最低相差 ${t.spread} 分），不排名`);
+    }
+  }
+  if (t.focus && t.focus.spread >= 3) lines.push(`　差异最大的一维：${t.focus.label}（三对相差 ${t.focus.spread} 分）`);
+  if (t.note) lines.push(`※ ${t.note}`);
+  return lines;
+}
+
 function hepanText(r) {
   if (r.chart === 'ziwei') {
     const d = (x) => `${x.label}：${x.score >= 0 ? '+' : ''}${x.score}　${x.text}`;
@@ -306,6 +327,7 @@ function hepanText(r) {
       `对方 命宫 ${r.b.soul.branch}（${r.b.soulStars.join('、') || '无主星'}）　夫妻 ${r.b.spouseStars.join('、') || '无主星'}　${r.b.bureau}`,
       ...r.dimensions.map(d),
       ...r.interactions.map((h) => `　· ${h.text}`),
+      ...tripleText(r.triple),
       ...r.notes.map((n) => `※ ${n}`),
     ].join('\n');
   }
@@ -329,6 +351,7 @@ function hepanText(r) {
       `年命纳音：${r.detail.nayin.a} / ${r.detail.nayin.b}（${r.detail.nayin.label}）——${r.detail.nayin.text}`,
       `吉凶象：吉 ${r.detail.tally.good} / 凶 ${r.detail.tally.bad}（${r.detail.tally.lean}；分档只数象，总分以上面三维度为准）`,
     ] : []),
+    ...tripleText(r.triple),
     ...r.notes.map((n) => `※ ${n}`),
   ].join('\n');
 }
@@ -559,11 +582,14 @@ function shadowParams(args, result) {
     };
   }
   if (system === 'hepan') {
-    return {
+    const params = {
       chart: args.chart === 'ziwei' ? 'ziwei' : 'bazi',
       a: shadowPerson({ ...args, datetime: args.datetime }),
       b: shadowPerson(args.partner || {}),
     };
+    // 第三方进指纹：同一对加上不同的第三人，是另一组盘
+    if (args.partner2) params.c = shadowPerson(args.partner2);
+    return params;
   }
 
   // 其余体系：只剔除解析/附加模块参数，其余原样归一化
@@ -720,6 +746,11 @@ export function compute(input = {}) {
       ignored: rev.ignored,
     };
   }
+  // partner2: null 视同未传：先归一化再排盘，否则同一对盘会因为显式 null 多出一个句柄
+  if (args.partner2 === null) {
+    args = { ...args };
+    delete args.partner2;
+  }
   const r = jsonSafe(computeRaw(args));
   if (revision) r.revision = revision;
   if (r && r.system === 'bazi') {
@@ -901,11 +932,12 @@ export function caliberCompare(args = {}, opts = {}) {
     const alt = sw.alt(current);
     let diffs = [];
     let error = '';
+    let cur = null;
+    let altRes = null;
     try {
-      diffs = diffObjects(
-        compute({ ...base, [sw.key]: current }),
-        compute({ ...base, [sw.key]: alt }),
-      );
+      cur = compute({ ...base, [sw.key]: current });
+      altRes = compute({ ...base, [sw.key]: alt });
+      diffs = diffObjects(cur, altRes);
     } catch (e) {
       error = (e && e.message) || String(e);
     }
@@ -933,6 +965,7 @@ export function caliberCompare(args = {}, opts = {}) {
       altLabel: sw.label(alt),
       total: diffs.length,
       summary: error ? '' : summarize(diffs),
+      views: error ? [] : viewRows(system, cur, altRes),
       roots,
       categories,
       error,
@@ -1045,31 +1078,42 @@ function computeRaw(args = {}) {
     if (!partner.datetime) {
       throw fail('E_PARTNER', '缺少 partner.datetime（对方的公历出生时间），例如 partner: {"datetime":"1992-03-03T10:00","gender":"female"}');
     }
-    const pa = parseDateTime(args.datetime);
-    const pb = parseDateTime(partner.datetime);
+    const partner2 = args.partner2;
+    if (partner2 !== undefined && partner2 !== null) {
+      if (typeof partner2 !== 'object' || Array.isArray(partner2)) {
+        throw fail('E_PARTNER', 'partner2 需要 { datetime, gender, address? }；不想看三方就整段省略（null 视同未传）');
+      }
+      if (!partner2.datetime) {
+        throw fail('E_PARTNER', '缺少 partner2.datetime（第三方的公历出生时间），例如 partner2: {"datetime":"1988-09-09T08:00","gender":"male"}');
+      }
+    }
     const chart = args.chart === 'ziwei' ? 'ziwei' : 'bazi';
     // 性别决定双方大运/大限顺逆，两边都不能用默认值
-    const sideA = {
-      ...pa,
-      gender: requireGender(args.gender, '你（主方）'),
-      trueSolar: args.trueSolar,
-      lateZi: args.lateZi,
-      dst: args.dst !== false,
-      address: typeof args.address === 'string' ? args.address : undefined,
-      longitude: typeof args.longitude === 'number' ? args.longitude : undefined,
-      geo: args.geo && typeof args.geo === 'object' ? args.geo : undefined,
-    };
-    const sideB = {
-      ...pb,
-      gender: requireGender(partner.gender, '对方'),
-      trueSolar: partner.trueSolar,
-      lateZi: partner.lateZi,
-      dst: partner.dst !== false,
-      address: typeof partner.address === 'string' ? partner.address : undefined,
-      longitude: typeof partner.longitude === 'number' ? partner.longitude : undefined,
-      geo: partner.geo && typeof partner.geo === 'object' ? partner.geo : undefined,
+    const sideOf = (src, who) => {
+      const dt = parseDateTime(src.datetime);
+      return {
+        ...dt,
+        gender: requireGender(src.gender, who),
+        trueSolar: src.trueSolar,
+        lateZi: src.lateZi,
+        dst: src.dst !== false,
+        address: typeof src.address === 'string' ? src.address : undefined,
+        longitude: typeof src.longitude === 'number' ? src.longitude : undefined,
+        geo: src.geo && typeof src.geo === 'object' ? src.geo : undefined,
+      };
     };
-    const result = chart === 'ziwei' ? buildZiweiHepan({ a: sideA, b: sideB }) : buildHepan({ a: sideA, b: sideB });
+    const sideA = sideOf(args, '你（主方）');
+    const sideB = sideOf(partner, '对方');
+    const build = (x, y) => (chart === 'ziwei' ? buildZiweiHepan({ a: x, b: y }) : buildHepan({ a: x, b: y }));
+    const result = build(sideA, sideB);
+    if (partner2) {
+      const sideC = sideOf(partner2, '第三方');
+      result.triple = tripleOf([
+        { key: 'a-b', a: '你', b: '对方', result },
+        { key: 'a-c', a: '你', b: '第三方', result: build(sideA, sideC) },
+        { key: 'b-c', a: '对方', b: '第三方', result: build(sideB, sideC) },
+      ]);
+    }
     return { ...result, summary: hepanText(result) };
   }
   if (system === 'meihua') {
@@ -1156,16 +1200,23 @@ function computeRaw(args = {}) {
     return { ...result, summary: almanacText(result) };
   }
   if (system === 'zeri') {
-    // startDate 必须显式：择日要「从哪天起看」，缺了不能拿本机今天静默代填
-    if (typeof args.startDate !== 'string' || !args.startDate.trim()) {
-      throw fail('E_INPUT', '择日需要 startDate（公历 YYYY-MM-DD，起算日）；可另给 days（1–60，默认 30）与 shengXiao（当事人属相）');
+    const candMode = args.candidates !== undefined && args.candidates !== null;
+    // startDate 必须显式：择日要「从哪天起看」，缺了不能拿本机今天静默代填；候选日模式改用 candidates
+    if (!candMode && (typeof args.startDate !== 'string' || !args.startDate.trim())) {
+      throw fail('E_INPUT', '择日需要 startDate（公历 YYYY-MM-DD，起算日）；可另给 days（1–60，默认 30）与 shengXiao（当事人属相）。只想比几天，改给 candidates: ["2026-12-01","2026-12-08"]');
+    }
+    let result;
+    try {
+      result = buildZeri({
+        task: args.task,
+        startDate: args.startDate,
+        days: args.days,
+        shengXiao: args.shengXiao,
+        candidates: args.candidates,
+      });
+    } catch (e) {
+      throw fail('E_INPUT', (e && e.message) || String(e));
     }
-    const result = buildZeri({
-      task: args.task,
-      startDate: args.startDate,
-      days: args.days,
-      shengXiao: args.shengXiao,
-    });
     return { ...result, summary: zeriText(result) };
   }
   if (system === 'chenggu') {
@@ -1355,16 +1406,27 @@ function almanacText(r) {
 
 /** 择日文本 */
 function zeriText(r) {
-  const head = `【择日·${r.meta.task}】${r.meta.startDate} 起 ${r.meta.days} 天${r.meta.shengXiao ? `　当事人属${r.meta.shengXiao}` : '（未给属相，未做冲煞排除）'}`;
-  const top = r.days.slice().sort((a, b) => b.score - a.score).slice(0, 5)
+  const cand = r.compare && r.compare.mode === 'candidates';
+  const head = cand
+    ? `【择日·${r.meta.task}】候选 ${r.meta.days} 天：${r.meta.candidates.join('、')}${r.meta.shengXiao ? `　当事人属${r.meta.shengXiao}` : '（未给属相，未做冲煞排除）'}`
+    : `【择日·${r.meta.task}】${r.meta.startDate} 起 ${r.meta.days} 天${r.meta.shengXiao ? `　当事人属${r.meta.shengXiao}` : '（未给属相，未做冲煞排除）'}`;
+  const top = r.days.slice().sort((a, b) => b.score - a.score).slice(0, cand ? 12 : 5)
     .map((d) => `· ${d.date} ${d.weekday}　${d.verdict}（${d.score}分）　宜${d.yi.slice(0, 3).join('/')}　${d.reasons.join('；') || '无特别加减分'}`);
+  const bestLine = cand
+    ? (r.compare.best
+      ? `这一组里最优：${r.compare.best.date}（${r.compare.best.score}分，${r.compare.best.verdict}）`
+        + (r.compare.best.ties.length > 1 ? `；同分：${r.compare.best.ties.filter((d) => d !== r.compare.best.date).join('、')}` : '')
+      : '这一组都因冲属相被排除，没有可用的日子')
+    : `推荐日：${r.best.length ? r.best.join('、') : '本期无（都不够推荐分）'}`;
   return [
     head,
-    `推荐日：${r.best.length ? r.best.join('、') : '本期无（都不够推荐分）'}`,
+    bestLine,
+    `推荐日：${r.best.length ? r.best.join('、') : '无'}`,
     `可用日：${r.usable.length ? r.usable.join('、') : '无'}`,
     `回避日：${r.avoid.length ? r.avoid.slice(0, 6).join('、') : '无'}`,
-    '逐日排序：',
+    cand ? '候选日逐日：' : '逐日排序：',
     ...top,
+    ...(cand ? [`比较口径：${r.compare.note}`] : []),
     `口径：${r.meta.scope}`,
   ].join('\n');
 }
@@ -1614,7 +1676,11 @@ export function renderText(result) {
       + c.switches.map((s) => {
         if (s.error) return `· ${s.title}：未能对照（${s.error}）`;
         if (!s.total) return `· ${s.title}：${s.currentLabel} → ${s.altLabel}，本盘无变化`;
-        return `· ${s.title}：${s.currentLabel} → ${s.altLabel}\n　${s.summary}`;
+        const changed = (Array.isArray(s.views) ? s.views : []).filter((v) => v.changed);
+        const side = changed.length
+          ? `\n　并排：${changed.map((v) => `${v.label} ${v.current} → ${v.alt}`).join('；')}`
+          : '';
+        return `· ${s.title}：${s.currentLabel} → ${s.altLabel}\n　${s.summary}${side}`;
       }).join('\n'));
   }
   if (result.followup) {
@@ -1648,6 +1714,8 @@ export { buildAlmanac, buildZeri, buildChenggu, buildXiaoliuren, buildStar, buil
 export { buildTrend, buildFengshui, buildName };
 export { buildTrace, traceMarkdown };
 export { encodeHandle, decodeHandle, resolveHandle };
+// C3 对话桥替代：深链编解码、表单还原、三档复制包（面板与独立页共用一份）
+export { askLink, parseAskLink, formOf, restNote, askPackages };
 
 
 

package/engine/interpret-knowledge.js

@@ -25,7 +25,8 @@ export const KNOWLEDGE = [
     system: 'bazi', dims: ['overall', 'career'],
     gist: '天干是露在外面的样子，地支是藏在地下的根。',
     detail: '同一个五行，透在天干叫「显」，扎在地支叫「有根」。只有天干没有地支，是看着有、使不上劲；只有地支不通天干，是有实力、不显眼。判断一个人能不能扛事，看的就是根有多深。',
-    source: '《滴天髓》「天干得一比肩，不如得支中一墓库」一路的取象',
+    source: '《滴天髓·干支总论》「天全一气，不可使地德莫之载；地全三物，不可使天道莫之容」',
+    note: '常被署给《滴天髓》的「地支所藏之干，本静以待用，透出干头，则显其用矣。故干以通根为美，支以透出为贵」，出自《子平真诠》卷一论十干十二支的注文——滴天髓底本与沈孝瞻原文里都查不到这句，注文自己引的才是上面那句滴天髓。所以本卡引可核的原文，注文只作说明。',
     status: 'settled',
   },
   {
@@ -372,7 +373,7 @@ export const KNOWLEDGE = [
     detail: '进神退神本身只说明这一爻的向外趋势：用神化进为得力，忌神化进则为患加剧；用神化退是力衰，忌神化退反而是解脱。传统还要看它在本月令衰旺、有没有日辰生扶，空亡或受克时进者未必能进。本插件把进退与爻位标出来，再按月建五态给一档力重——得令则进得动、退得慢，失令则进得虚、退得实，月破压过一切；只给档位，不折成加权分数，吉凶仍落在用神与忌神那一层判。',
     source: '《增删卜易》进神退神章、用神章',
     status: 'variant',
-    note: '土之进退次序各家说法不完全一致，有以丑→辰→未→戌为进、也有只取辰戌丑未相对者；本插件按丑辰未戌成环处理，并用《增删卜易》卦例中「未土化戌土为进」「戌土化未土为退」对拍。',
+    note: '土之进退次序各家说法不完全一致，有以丑→辰→未→戌为进、也有只取辰戌丑未相对者；本插件按丑辰未戌成环处理，并用《增删卜易》卦例中「未土化戌土为进」「戌土化未土为退」对拍。喜忌分档的出处是《增删卜易》卷二·進神退神章第二十九：「所喜者宜於化進，所忌者宜化退神」；把「喜／忌」具体落到用神／忌神两档，是本插件的引申。',
   },
 
   // ── 梅花 / 六壬 / 奇门 / 塔罗 ───────────────────────────

package/engine/trace.js

@@ -56,7 +56,7 @@ function liuyaoTrace(r, opts = {}) {
       ['变卦', bian ? `${text(bian.name)}（上${text(bian.upper)}·下${text(bian.lower)}）` : '无'],
     ],
     lines.map((l) => `${l.position}爻 ${text(l.ganzhi)}${text(l.element)}`).join('｜'),
-    '京房纳甲诀；engine/liuyao.js · NAJIA',
+    '京房纳甲（八宫纳甲表）；实现：engine/liuyao.js · NAJIA（规则表，本仓未录入古籍章页）',
   );
 
   const liuqin = step(
@@ -69,7 +69,7 @@ function liuyaoTrace(r, opts = {}) {
       ['日干起六神', `${text(r.dayGanZhi && r.dayGanZhi.stem)}日`],
     ],
     lines.map((l) => `${l.position}爻 ${text(l.liuqin)}（${text(l.element)}）`).join('｜'),
-    '五行生克；engine/liuyao.js · liuqin()',
+    '五行生克定六亲；取用可对读《增删卜易》卷一·用神章第八；实现：engine/liuyao.js · liuqin()',
   );
 
   const shiying = step(
@@ -83,7 +83,7 @@ function liuyaoTrace(r, opts = {}) {
     ],
     `${text(ben.shi)}爻${shi ? ` ${text(shi.liuqin)}·${text(shi.ganzhi)}${text(shi.element)}` : ''}为世，`
       + `${text(ben.ying)}爻${ying ? ` ${text(ying.liuqin)}·${text(ying.ganzhi)}${text(ying.element)}` : ''}为应`,
-    '八宫世应诀；engine/liuyao.js · SHI_POSITION',
+    '八宫世应诀（世爻序与应爻隔三位）；实现：engine/liuyao.js · SHI_POSITION（通行动诀，本仓未录入古籍章页）',
   );
 
   let fushen;
@@ -97,7 +97,7 @@ function liuyaoTrace(r, opts = {}) {
       '用神不上卦时，回本宫首卦的同位取伏神；飞伏之间只判生克与助压。',
       [['用神', ug && ug.ask ? ug.ask : '未取']],
       `${why}；本层不适用。`,
-      'engine/liuyao.js · yongshenOf()',
+      '取伏之法参《增删卜易》卷二·飛伏神章第二十八；实现：engine/liuyao.js · yongshenOf()',
     );
   } else if (ug.missing) {
     const hidden = (ug.fushen || []).map((f) => {
@@ -117,7 +117,7 @@ function liuyaoTrace(r, opts = {}) {
         ['月建 / 日辰', `${text(month && month.branch)} / ${text(day && day.branch)}`],
       ],
       `${hidden || '本卦无此六亲，首卦同位也未取到伏神'}${access ? `；出伏：${access}` : ''}`,
-      '本宫首卦取伏；engine/liuyao.js · fushenAccess()',
+      '《增删卜易》卷二·飛伏神章第二十八（用神不現，尋得伏神而遇生扶有用）；实现：engine/liuyao.js · fushenAccess()',
     );
   } else {
     fushen = step(
@@ -129,7 +129,7 @@ function liuyaoTrace(r, opts = {}) {
         ['在位', list((ug.found || []).map((l) => `${l.position}爻`))],
       ],
       `用神 ${ug.liuqin} 已在 ${list((ug.found || []).map((l) => `${l.position}爻`))}，无需伏神。`,
-      'engine/liuyao.js · yongshenOf()',
+      '取伏之法参《增删卜易》卷二·飛伏神章第二十八；实现：engine/liuyao.js · yongshenOf()',
     );
   }
 
@@ -150,7 +150,7 @@ function liuyaoTrace(r, opts = {}) {
       useStrength ? `用神：${useStrength}${us.labels && us.labels.length ? `（${us.labels.join('、')}）` : ''}` : '用神：未取，只看全卦',
       hs && hs.labels && hs.labels.length ? `全卦：${hs.labels.join('、')}` : '',
     ].filter(Boolean).join('；'),
-    '月建主旺衰、日辰司生克；engine/liuyao.js · yongshenStrength / hexagramStrength',
+    '《增删卜易》卷一·月將章第十六、日辰章第十七；实现：engine/liuyao.js · yongshenStrength / hexagramStrength',
   );
 
   return [najia, liuqin, shiying, fushen, wangsheng];
@@ -179,7 +179,7 @@ function baziTrace(r) {
       ['虚透', list(parts.virtualHelpers, '无')],
     ],
     `${text(s.level)}（${text(s.score)} 分）：${text(s.detail)}`,
-    'engine/bazi.js · 旺衰量化（月令权重 + 藏干通根，三会/三合/六合折根 + 天干虚透减半）',
+    '本仓量化规则（月令权重 3/2/1/0.5/0、藏干通根、三会/三合/六合折根、虚透减半；非古籍定数）；实现：engine/bazi.js · 旺衰量化',
   );
 
   const primaryName = text(frame.primaryName || (primary && primary.name), '未取格局');
@@ -211,7 +211,7 @@ function baziTrace(r) {
       ['调候', tiaohou && tiaohou.kind ? `${text(tiaohou.kind)}${need && need.element ? ` → ${text(need.element)}` : ''}` : '—'],
     ],
     `${resultParts}`,
-    '子平真诠 · 月令取格；engine/geju.js · yongshenOf()',
+    '《子平真诠》八、论用神（专求月令）；调候参《穷通宝鉴》五行总论；实现：engine/geju.js · yongshenOf()',
   );
 
   const p = r.palaces && typeof r.palaces === 'object' ? r.palaces : {};
@@ -228,7 +228,7 @@ function baziTrace(r) {
       ['命宫 / 身宫', `${text(p.minggong && p.minggong.ganzhi)} / ${text(p.shengong && p.shengong.ganzhi)}`],
     ],
     `胎元 ${text(p.taiyuan.ganzhi)}；${p.taixi ? `胎息 ${text(p.taixi.ganzhi)}；` : ''}命宫 ${text(p.minggong && p.minggong.ganzhi)}；身宫 ${text(p.shengong && p.shengong.ganzhi)}。四宫是辅助坐标，不单独折吉凶。`,
-    'Tyme 四宫口径；engine/bazi.js · palaces',
+    'Tyme 1.5.4 四宫口径（与 ziwei.pub 704 组日期对拍）；本仓未直接照录古籍章页；实现：engine/bazi.js · palaces',
   ) : null;
 
   return [strength, geju, ...(palaces ? [palaces] : [])];
@@ -251,7 +251,7 @@ function ziweiTrace(r) {
       ['命中数', `${patterns.length} / ${total}`],
     ],
     patterns.length ? `命中 ${patterns.length} 条：${hit}` : '未命中已收录的格局条件（不表示命盘无结构，只是不在已收录清单内）。',
-    '紫微斗数全书 · 格局条件；engine/ziwei.js · detectPatterns()',
+    '《紫微斗数全书》卷三·论人命入格、谈星要论；实现：engine/ziwei.js · detectPatterns()',
   )];
 }
 
@@ -277,7 +277,7 @@ function qimenTrace(r, opts = {}) {
       ['空亡 / 驿马', `${list(r.kongWang)} / ${text(ma.zhi)}${ma.gong ? `（${ma.gong}宫）` : ''}`],
     ],
     palaces.map((p) => `${p.palace}宫 天${text(p.tianPan)}·${text(p.star)}·${text(p.gate)}·${text(p.god)}`).join('｜') || '无九宫数据',
-    'engine/qimen.js · buildQimen()',
+    '《奇门遁甲统宗》卷一·奇门秘诀总赋（阴阳二遁、五日换元、超神接气）；实现：engine/qimen.js · buildQimen()',
   );
 
   const ys = qimenYongshen(r, opts.direction);
@@ -298,7 +298,7 @@ function qimenTrace(r, opts = {}) {
       ? `${ys.note}；${found.map((x) => `${x.key} 落 ${x.palace.palace}宫（${text(x.palace.star)}·${text(x.palace.gate)}·${text(x.palace.god)}）`).join('，')}`
         + (missing.length ? `；${missing.join('、')} 未上盘` : '')
       : `${ys.label}的用神均未上盘，属未决项；先按值符落宫参照。`,
-    '奇门用神取象；engine/qimen-interpret.js · qimenYongshen()',
+    '本仓用神表（按所问之事取用，非古籍原文）；实现：engine/qimen-interpret.js · qimenYongshen()',
   );
 
   const order = ['旺', '相', '休', '囚', '死'];
@@ -315,7 +315,7 @@ function qimenTrace(r, opts = {}) {
       ['天盘干', stateLine(states.stem)],
     ],
     `门：${stateLine(states.gate)}；星：${stateLine(states.star)}；天盘干：${stateLine(states.stem)}`,
-    '月令五行五态；engine/qimen.js · groupByState()',
+    '《奇门遁甲统宗》卷三（旺相休囚）；实现：engine/qimen.js · groupByState()',
   );
 
   const forced = [];
@@ -354,7 +354,7 @@ function qimenTrace(r, opts = {}) {
       ['空亡', kongCells.join('、') || '无'],
     ],
     `门迫 ${forced.length} 处、宫制门 ${controlled.length} 处；天盘干与宫：${stemLine}；击刑 ${jiXing.length} 处、三奇入墓 ${ruMu.length} 处、六仪入墓 ${liuYiRuMu.length} 处、落空 ${kongCells.length} 宫。十干克应：${ganying || '—'}。`,
-    '门迫/宫制门；engine/qimen.js · gatePalaceRelation() / stemPalaceRelation()；十干克应 engine/qimen-ganying.js',
+    '《奇门遁甲统宗》卷二（八门迫制）、卷十一·玄机赋（中）（六仪击刑、三奇入墓）；十干克应为本仓表；实现：engine/qimen.js · gatePalaceRelation() / stemPalaceRelation()、engine/qimen-ganying.js',
   );
 
   return [facts, yongshen, wangshuai, relations];
@@ -380,7 +380,7 @@ function daliurenTrace(r) {
       ['昼夜 / 贵人', `${text(r.dayNight)} / ${text(gr.zhi)}（${gr.reverse ? '逆布' : '顺布'}）`],
     ],
     pan.map((p) => `${p.di}→${p.tian}${p.jiang ? `（${text(p.jiang)}）` : ''}`).join('｜') || '无天地盘数据',
-    '大六壬月将加时；engine/daliuren.js · tianDiPan()',
+    '《大六壬大全》卷二·神将释（月将为十二支神，登明为首逆布）；加时布盘属通行口诀，未标卷次；实现：engine/daliuren.js · tianDiPan()',
   );
 
   const sike = step(
@@ -393,7 +393,7 @@ function daliurenTrace(r) {
       ['四课', ke.map((k) => `${k.position}课 ${text(k.shang)}上${text(k.xia)}下`).join('；') || '—'],
     ],
     ke.map((k) => `${k.position}课 ${text(k.shang)}上${text(k.xia)}下${k.jiang ? `·${text(k.jiang)}` : ''}：${text(k.relation)}`).join('；') || '无四课数据',
-    'engine/daliuren.js · siKe()',
+    '《大六壬大全》卷一·起例（十干寄宫）；四课余下三课按通行口诀；实现：engine/daliuren.js · siKe()',
   );
 
   const chuanLine = (c) => (c
@@ -410,7 +410,7 @@ function daliurenTrace(r) {
       ['末传', chuanLine(sc.mo)],
     ],
     `${chuanLine(sc.chu)} → ${chuanLine(sc.zhong)} → ${chuanLine(sc.mo)}`,
-    'engine/daliuren.js · chuan()',
+    '《大六壬大全》卷一·起例（贼克法为首法，比用、涉害、遥克、昴星、八专、伏吟、返吟依次列后）；实现：engine/daliuren.js · chuan()',
   );
 
   return [tiandipan, sike, sanchuan];

package/engine/zeri.js

@@ -81,23 +81,68 @@ const VERDICT = (score, ctx) => {
  * @param {{task:string, startDate:string, days?:number, shengXiao?:string}} input
  *   startDate 必填（公历 YYYY-MM-DD），避免引擎在无时钟环境下静默取「今天」。
  */
+/** 严格解析公历日期：2 月 30 日这类不存在的日子直接判非法，不滚到下个月 */
+function parseYmd(raw) {
+  const m = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(String(raw || '').trim());
+  if (!m) return null;
+  const year = Number(m[1]);
+  const month = Number(m[2]);
+  const day = Number(m[3]);
+  if (month < 1 || month > 12 || day < 1) return null;
+  const back = fromJDN(toJDN(year, month, day));
+  return back.year === year && back.month === month && back.day === day ? { year, month, day } : null;
+}
+
+const ymd = (p) => `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`;
+
+/**
+ * 择日主函数。
+ * @param {{task:string, startDate:string, days?:number, shengXiao?:string,
+ *   candidates?:string[]}} input
+ *   startDate 必填（公历 YYYY-MM-DD），避免引擎在无时钟环境下静默取「今天」。
+ *   candidates 给了就只比这几个候选日（2–12 个，去重、保持输入顺序），startDate 与 days 不参与。
+ */
 export function buildZeri(input) {
   const task = input.task;
   if (!TASKS[task]) throw new Error(`不支持的事项「${task}」。支持：${Object.keys(TASKS).join('、')}`);
-  const m = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(String(input.startDate || '').trim());
-  if (!m) throw new Error('择日需要 startDate（公历 YYYY-MM-DD）——请向用户询问起算日，不要代填');
-  const start = { year: Number(m[1]), month: Number(m[2]), day: Number(m[3]) };
-  const days = Math.max(1, Math.min(60, Number.isInteger(input.days) ? input.days : 30));
   const shengXiaoRaw = typeof input.shengXiao === 'string' ? input.shengXiao.trim() : '';
   const shengXiao = shengXiaoRaw || null;
   if (shengXiao && !SHENGXIAO.includes(shengXiao)) throw new Error(`shengXiao 须为生肖名：${SHENGXIAO.join('、')}`);
 
+  // 候选日模式：只比用户给的这几天，不再按区间扫
+  let candidates = null;
+  if (input.candidates !== undefined && input.candidates !== null) {
+    if (!Array.isArray(input.candidates)) {
+      throw new Error('candidates 须为日期数组，例如 ["2026-12-01","2026-12-08","2026-12-15"]');
+    }
+    if (input.candidates.length < 2) throw new Error('candidates 至少给 2 个候选日；只想看一天请用 startDate + days: 1');
+    if (input.candidates.length > 12) throw new Error('candidates 最多 12 个候选日；更多请用 startDate + days 扫区间');
+    const seen = new Set();
+    candidates = [];
+    for (const raw of input.candidates) {
+      const p = parseYmd(raw);
+      if (!p) throw new Error(`候选日不是真实存在的公历日期：「${raw}」，请用 2026-12-01 这种格式`);
+      const key = ymd(p);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      candidates.push(p);
+    }
+    if (candidates.length < 2) throw new Error('候选日去重后不足 2 天；至少要两个不同的日子才谈得上比较');
+  }
+
+  let start = null;
+  let days = 0;
+  if (!candidates) {
+    const m = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(String(input.startDate || '').trim());
+    if (!m) throw new Error('择日需要 startDate（公历 YYYY-MM-DD）——请向用户询问起算日，不要代填');
+    start = { year: Number(m[1]), month: Number(m[2]), day: Number(m[3]) };
+    days = Math.max(1, Math.min(60, Number.isInteger(input.days) ? input.days : 30));
+  }
+
   const spec = TASKS[task];
   const zhixingSet = ZHIXING_FAVOR[spec.category];
-  const startJdn = toJDN(start.year, start.month, start.day);
-  const list = [];
-  for (let i = 0; i < days; i++) {
-    const p = fromJDN(startJdn + i);
+
+  const makeRow = (p) => {
     const a = buildAlmanac(p);
     let score = 0;
     const reasons = [];
@@ -114,7 +159,7 @@ export function buildZeri(input) {
     if (a.zhiXing === '危' && spec.category !== 'travel' && spec.category !== 'worship') { score -= 1; reasons.push('危日（-1）'); }
 
     const v = VERDICT(score, { chongSelf, jiHit });
-    list.push({
+    return {
       date: a.meta.date,
       weekday: a.meta.weekday,
       lunar: a.lunar.text,
@@ -128,17 +173,47 @@ export function buildZeri(input) {
       verdict: v.verdict,
       verdictText: v.text,
       ...(v.excluded ? { excluded: true } : {}),
-    });
-  }
+    };
+  };
+
+  const list = candidates
+    ? candidates.map(makeRow)
+    : Array.from({ length: days }, (_, i) => makeRow(fromJDN(toJDN(start.year, start.month, start.day) + i)));
 
   const ranked = list.slice().sort((x, y) => y.score - x.score || (x.date < y.date ? -1 : 1));
+  const startDate = candidates
+    ? candidates.slice().sort((x, y) => (ymd(x) < ymd(y) ? -1 : 1)).map(ymd)[0]
+    : ymd(start);
+
+  // 候选日比较：只在这几天里比，给出最高分和同分者；不换算成「好多少」
+  let compare = null;
+  if (candidates) {
+    const pool = ranked.filter((d) => !d.excluded);
+    const top = pool[0] || null;
+    const scores = list.map((d) => d.score);
+    compare = {
+      mode: 'candidates',
+      count: list.length,
+      best: top ? {
+        date: top.date,
+        score: top.score,
+        verdict: top.verdict,
+        ties: pool.filter((d) => d.score === top.score).map((d) => d.date),
+      } : null,
+      spread: Math.max(...scores) - Math.min(...scores),
+      note: '候选日只在这几天里比：分数来自建除宜忌与冲煞，胜出只表示更合所问事项，不代表「好多少」。',
+    };
+  }
+
   return {
     system: 'zeri',
     meta: {
       task,
-      startDate: `${start.year}-${String(start.month).padStart(2, '0')}-${String(start.day).padStart(2, '0')}`,
-      days,
+      mode: candidates ? 'candidates' : 'range',
+      startDate,
+      days: list.length,
       shengXiao,
+      ...(candidates ? { candidates: candidates.map(ymd) } : {}),
       scope: shengXiao
         ? `宜忌按建除简表；已给当事人属相（${shengXiao}），凡当日冲该属相径直排除。评分仅用于排序引导。`
         : '宜忌按建除简表；未给当事人属相，未做冲属相排除。评分仅用于排序引导。',
@@ -147,6 +222,7 @@ export function buildZeri(input) {
     usable: ranked.filter((d) => d.verdict === '可用' && !d.excluded).slice(0, 5).map((d) => d.date),
     avoid: list.filter((d) => d.verdict === '回避').map((d) => `${d.date}（${d.reasons.join('；') || '综合减分'}）`),
     days: list,
+    ...(compare ? { compare } : {}),
     excludedCount: list.filter((d) => d.excluded).length,
     sources: ['宜忌：建除十二神通行简表', '建除适配与冲煞：传统通行口径', '排序：宜忌加减分 + 属相排除（确定性）'],
     disclaimer: '择日为传统黄历口径的本地计算，属民俗参考；评分只用于排序，不构成择日结论。',

package/index.js

@@ -230,11 +230,16 @@ export function apply(ctx) {
         },
         startDate: {
           type: 'string',
-          description: '仅 zeri 使用：起算日（公历 YYYY-MM-DD）。省略则由宿主补今天。',
+          description: '仅 zeri 使用：起算日（公历 YYYY-MM-DD）。省略则由宿主补今天；给了 candidates 时不需要。',
         },
         days: {
           type: 'number',
-          description: '仅 zeri 使用：往后考察天数，1–60，默认 30。',
+          description: '仅 zeri 使用：往后考察天数，1–60，默认 30；给了 candidates 时忽略。',
+        },
+        candidates: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '仅 zeri 使用：候选日比较（2–12 个真实公历日期，如 ["2026-12-01","2026-12-08"]）。给了就只比这几天，结果多一个 compare（这一组最优、同分者、分差）与逐日并排；不替代 startDate 扫区间。',
         },
         shengXiao: {
           type: 'string',
@@ -330,6 +335,17 @@ export function apply(ctx) {
           },
           required: ['datetime', 'gender'],
         },
+        partner2: {
+          type: 'object',
+          description: '三方合盘（可选）：第三个人的出生信息，字段与 partner 相同。给了就多回 triple——你×对方、你×第三方、对方×第三方三对分数并列，不合成「三人总分」。仅 hepan 使用；null 与省略等价，不要传 null。',
+          properties: {
+            datetime: { type: 'string', description: '第三方公历本地时间，如 1988-09-09T08:00' },
+            gender: { type: 'string', enum: ['male', 'female'], description: '第三方性别' },
+            address: { type: 'string', description: '第三方出生地（省/市即可）' },
+            trueSolar: { type: 'boolean', description: '第三方是否启用真太阳时' },
+          },
+          required: ['datetime', 'gender'],
+        },
         mode: {
           type: 'string',
           enum: ['time', 'number'],