dsh-metaphysics 0.14.2 → 0.15.0

package/engine/liuyao.js

@@ -1,227 +1,237 @@
-// 六爻（纳甲）引擎：摇卦、装卦、六亲、六神、世应、变卦
-import { STEMS, BRANCHES, toJDN, ganzhiName, dayGanzhiIndex } from './calendar.js';
-
-// 八卦三位（自下而上，1 = 阳）
-const TRIGRAM_BITS = {
-  乾: [1, 1, 1], 兑: [1, 1, 0], 离: [1, 0, 1], 震: [1, 0, 0],
-  巽: [0, 1, 1], 坎: [0, 1, 0], 艮: [0, 0, 1], 坤: [0, 0, 0],
-};
-// 位值 = b0 + 2b1 + 4b2
-const TRIGRAM_BY_VALUE = ['坤', '震', '坎', '兑', '艮', '离', '巽', '乾'];
-
-const bitsValue = (bits) => bits[0] + 2 * bits[1] + 4 * bits[2];
-
-// 京房八宫：每宫八卦次序 = 本宫、一世…五世、游魂、归魂
-const PALACE_NAMES = {
-  乾: ['乾为天', '天风姤', '天山遁', '天地否', '风地观', '山地剥', '火地晋', '火天大有'],
-  兑: ['兑为泽', '泽水困', '泽地萃', '泽山咸', '水山蹇', '地山谦', '雷山小过', '雷泽归妹'],
-  离: ['离为火', '火山旅', '火风鼎', '火水未济', '山水蒙', '风水涣', '天水讼', '天火同人'],
-  震: ['震为雷', '雷地豫', '雷水解', '雷风恒', '地风升', '水风井', '泽风大过', '泽雷随'],
-  巽: ['巽为风', '风天小畜', '风火家人', '风雷益', '天雷无妄', '火雷噬嗑', '山雷颐', '山风蛊'],
-  坎: ['坎为水', '水泽节', '水雷屯', '水火既济', '泽火革', '雷火丰', '地火明夷', '地水师'],
-  艮: ['艮为山', '山火贲', '山天大畜', '山泽损', '火泽睽', '天泽履', '风泽中孚', '风山渐'],
-  坤: ['坤为地', '地雷复', '地泽临', '地天泰', '雷天大壮', '泽天夬', '水天需', '水地比'],
-};
-
-const PALACE_ELEMENT = {
-  乾: '金', 兑: '金', 离: '火', 震: '木', 巽: '木', 坎: '水', 艮: '土', 坤: '土',
-};
-
-// 八宫卦序：世爻位置（1 = 初爻）
-const SHI_POSITION = [6, 1, 2, 3, 4, 5, 4, 3];
-
-// 京房纳甲：内卦 / 外卦 的天干与三爻地支
-const NAJIA = {
-  乾: { gan: ['甲', '壬'], inner: ['子', '寅', '辰'], outer: ['午', '申', '戌'] },
-  坤: { gan: ['乙', '癸'], inner: ['未', '巳', '卯'], outer: ['丑', '亥', '酉'] },
-  震: { gan: ['庚', '庚'], inner: ['子', '寅', '辰'], outer: ['午', '申', '戌'] },
-  巽: { gan: ['辛', '辛'], inner: ['丑', '亥', '酉'], outer: ['未', '巳', '卯'] },
-  坎: { gan: ['戊', '戊'], inner: ['寅', '辰', '午'], outer: ['申', '戌', '子'] },
-  离: { gan: ['己', '己'], inner: ['卯', '丑', '亥'], outer: ['酉', '未', '巳'] },
-  艮: { gan: ['丙', '丙'], inner: ['辰', '午', '申'], outer: ['戌', '子', '寅'] },
-  兑: { gan: ['丁', '丁'], inner: ['巳', '卯', '丑'], outer: ['亥', '酉', '未'] },
-};
-
-const BRANCH_ELEMENT = {
-  子: '水', 丑: '土', 寅: '木', 卯: '木', 辰: '土', 巳: '火',
-  午: '火', 未: '土', 申: '金', 酉: '金', 戌: '土', 亥: '水',
-};
-
-const GENERATES = { 木: '火', 火: '土', 土: '金', 金: '水', 水: '木' };
-const OVERCOMES = { 木: '土', 土: '水', 水: '火', 火: '金', 金: '木' };
-
-const LIUSHEN = ['青龙', '朱雀', '勾陈', '螣蛇', '白虎', '玄武'];
-// 日干 -> 初爻所起六神
-const LIUSHEN_START = { 甲: 0, 乙: 0, 丙: 1, 丁: 1, 戊: 2, 己: 3, 庚: 4, 辛: 4, 壬: 5, 癸: 5 };
-
-function liuqin(palaceElement, branchElement) {
-  if (palaceElement === branchElement) return '兄弟';
-  if (GENERATES[branchElement] === palaceElement) return '父母';
-  if (GENERATES[palaceElement] === branchElement) return '子孙';
-  if (OVERCOMES[branchElement] === palaceElement) return '官鬼';
-  if (OVERCOMES[palaceElement] === branchElement) return '妻财';
-  return '?';
-}
-
-// 构建 (上卦, 下卦) -> 卦 的索引
-const HEXAGRAM_INDEX = new Map();
-
-function flip(bits, positions) {
-  const out = bits.slice();
-  for (const p of positions) out[p] = out[p] ? 0 : 1;
-  return out;
-}
-
-for (const [palace, names] of Object.entries(PALACE_NAMES)) {
-  const t = TRIGRAM_BITS[palace];
-  const variants = [
-    { lower: t, upper: t },
-    { lower: flip(t, [0]), upper: t },
-    { lower: flip(t, [0, 1]), upper: t },
-    { lower: flip(t, [0, 1, 2]), upper: t },
-    { lower: flip(t, [0, 1, 2]), upper: flip(t, [0]) },
-    { lower: flip(t, [0, 1, 2]), upper: flip(t, [0, 1]) },
-    { lower: flip(t, [0, 1, 2]), upper: flip(t, [1]) },
-    { lower: t, upper: flip(t, [1]) },
-  ];
-  variants.forEach((v, order) => {
-    const upper = TRIGRAM_BY_VALUE[bitsValue(v.upper)];
-    const lower = TRIGRAM_BY_VALUE[bitsValue(v.lower)];
-    HEXAGRAM_INDEX.set(`${upper}|${lower}`, {
-      name: names[order],
-      palace,
-      palaceElement: PALACE_ELEMENT[palace],
-      order,
-      upper,
-      lower,
-      lines: [...v.lower, ...v.upper], // b0 初爻
-      shi: SHI_POSITION[order],
-      ying: SHI_POSITION[order] > 3 ? SHI_POSITION[order] - 3 : SHI_POSITION[order] + 3,
-    });
-  });
-}
-
-export const HEXAGRAM_COUNT = HEXAGRAM_INDEX.size;
-
-/** 由六爻（自下而上，1 = 阳）求卦 */
-export function hexagramFromBits(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}`);
-}
-
-/** 随机摇卦：三枚铜钱，背为阳（3），字为阴（2），合计 6/7/8/9 */
-export function tossLines(random = Math.random) {
-  const lines = [];
-  for (let i = 0; i < 6; i++) {
-    let sum = 0;
-    for (let c = 0; c < 3; c++) sum += random() < 0.5 ? 3 : 2;
-    lines.push(sum); // 6 老阴 7 少阳 8 少阴 9 老阳
-  }
-  return lines;
-}
-
-function lineToBit(v) {
-  return v === 7 || v === 9 ? 1 : 0;
-}
-
-function isMoving(v) {
-  return v === 6 || v === 9;
-}
-
-/**
- * 装卦
- * @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);
-
-  const invalid = rawLines.filter((v) => ![6, 7, 8, 9].includes(v));
-  if (invalid.length) throw new Error(`爻值只能是 6/7/8/9，收到 ${JSON.stringify(rawLines)}`);
-
-  const bits = rawLines.map(lineToBit);
-  const ben = hexagramFromBits(bits);
-  const moving = rawLines.map((v, i) => (isMoving(v) ? i : -1)).filter((i) => i >= 0);
-  const bianBits = moving.length ? flip(bits, moving) : null;
-  const bian = bianBits ? hexagramFromBits(bianBits) : null;
-
-  const dayGanZhi = input.dayGanZhi ?? (() => {
-    const now = new Date();
-    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 };
-  })();
-
-  const liushenStart = LIUSHEN_START[dayGanZhi.stem] ?? 0;
-
-  function decorate(hex, movingSet) {
-    const rows = [];
-    for (let i = 0; i < 6; i++) {
-      const isInner = i < 3;
-      const trigram = isInner ? hex.lower : hex.upper;
-      const nj = NAJIA[trigram];
-      const branch = isInner ? nj.inner[i] : nj.outer[i - 3];
-      const gan = isInner ? nj.gan[0] : nj.gan[1];
-      const element = BRANCH_ELEMENT[branch];
-      const value = rawLines[i];
-      rows.push({
-        position: i + 1,
-        name: ['初爻', '二爻', '三爻', '四爻', '五爻', '上爻'][i],
-        yinYang: bits[i] ? '阳' : '阴',
-        moving: movingSet ? movingSet.has(i) : isMoving(value),
-        symbol: bits[i] ? '━━━━━' : '━━ ━━',
-        ganzhi: gan + branch,
-        stem: gan,
-        branch,
-        element,
-        liuqin: liuqin(hex.palaceElement, element),
-        liushen: LIUSHEN[(liushenStart + i) % 6],
-      });
-    }
-    return rows;
-  }
-
-  const benRows = decorate(ben, new Set(moving));
-  const movingSet = new Set(moving);
-  const bianRows = bian ? decorate(bian, new Set()) : null;
-  if (bianRows) {
-    bianRows.forEach((r, i) => {
-      r.changedFrom = movingSet.has(i) ? benRows[i].symbol : null;
-    });
-  }
-
-  return {
-    system: 'liuyao',
-    question: input.question ?? null,
-    cast: {
-      lines: rawLines,
-      notation: rawLines.map((v) => ({ 6: '老阴 ✕', 7: '少阳', 8: '少阴', 9: '老阳 ○' }[v])),
-      movingPositions: moving.map((i) => i + 1),
-    },
-    dayGanZhi: { name: dayGanZhi.name, stem: dayGanZhi.stem, branch: dayGanZhi.branch },
-    ben: {
-      name: ben.name,
-      upper: ben.upper,
-      lower: ben.lower,
-      palace: `${ben.palace}宫`,
-      palaceElement: ben.palaceElement,
-      shi: ben.shi,
-      ying: ben.ying,
-      lines: benRows,
-    },
-    bian: bian
-      ? {
-        name: bian.name,
-        upper: bian.upper,
-        lower: bian.lower,
-        palace: `${bian.palace}宫`,
-        palaceElement: bian.palaceElement,
-        shi: bian.shi,
-        ying: bian.ying,
-        lines: bianRows,
-      }
-      : null,
-  };
-}
+// 六爻（纳甲）引擎：摇卦、装卦、六亲、六神、世应、变卦
+import { STEMS, BRANCHES, toJDN, ganzhiName, dayGanzhiIndex, sexagenaryIndex, xunKongOf } from './calendar.js';
+
+// 八卦三位（自下而上，1 = 阳）
+const TRIGRAM_BITS = {
+  乾: [1, 1, 1], 兑: [1, 1, 0], 离: [1, 0, 1], 震: [1, 0, 0],
+  巽: [0, 1, 1], 坎: [0, 1, 0], 艮: [0, 0, 1], 坤: [0, 0, 0],
+};
+// 位值 = b0 + 2b1 + 4b2
+const TRIGRAM_BY_VALUE = ['坤', '震', '坎', '兑', '艮', '离', '巽', '乾'];
+
+const bitsValue = (bits) => bits[0] + 2 * bits[1] + 4 * bits[2];
+
+// 京房八宫：每宫八卦次序 = 本宫、一世…五世、游魂、归魂
+const PALACE_NAMES = {
+  乾: ['乾为天', '天风姤', '天山遁', '天地否', '风地观', '山地剥', '火地晋', '火天大有'],
+  兑: ['兑为泽', '泽水困', '泽地萃', '泽山咸', '水山蹇', '地山谦', '雷山小过', '雷泽归妹'],
+  离: ['离为火', '火山旅', '火风鼎', '火水未济', '山水蒙', '风水涣', '天水讼', '天火同人'],
+  震: ['震为雷', '雷地豫', '雷水解', '雷风恒', '地风升', '水风井', '泽风大过', '泽雷随'],
+  巽: ['巽为风', '风天小畜', '风火家人', '风雷益', '天雷无妄', '火雷噬嗑', '山雷颐', '山风蛊'],
+  坎: ['坎为水', '水泽节', '水雷屯', '水火既济', '泽火革', '雷火丰', '地火明夷', '地水师'],
+  艮: ['艮为山', '山火贲', '山天大畜', '山泽损', '火泽睽', '天泽履', '风泽中孚', '风山渐'],
+  坤: ['坤为地', '地雷复', '地泽临', '地天泰', '雷天大壮', '泽天夬', '水天需', '水地比'],
+};
+
+const PALACE_ELEMENT = {
+  乾: '金', 兑: '金', 离: '火', 震: '木', 巽: '木', 坎: '水', 艮: '土', 坤: '土',
+};
+
+// 八宫卦序：世爻位置（1 = 初爻）
+const SHI_POSITION = [6, 1, 2, 3, 4, 5, 4, 3];
+
+// 京房纳甲：内卦 / 外卦 的天干与三爻地支
+const NAJIA = {
+  乾: { gan: ['甲', '壬'], inner: ['子', '寅', '辰'], outer: ['午', '申', '戌'] },
+  坤: { gan: ['乙', '癸'], inner: ['未', '巳', '卯'], outer: ['丑', '亥', '酉'] },
+  震: { gan: ['庚', '庚'], inner: ['子', '寅', '辰'], outer: ['午', '申', '戌'] },
+  巽: { gan: ['辛', '辛'], inner: ['丑', '亥', '酉'], outer: ['未', '巳', '卯'] },
+  坎: { gan: ['戊', '戊'], inner: ['寅', '辰', '午'], outer: ['申', '戌', '子'] },
+  离: { gan: ['己', '己'], inner: ['卯', '丑', '亥'], outer: ['酉', '未', '巳'] },
+  艮: { gan: ['丙', '丙'], inner: ['辰', '午', '申'], outer: ['戌', '子', '寅'] },
+  兑: { gan: ['丁', '丁'], inner: ['巳', '卯', '丑'], outer: ['亥', '酉', '未'] },
+};
+
+const BRANCH_ELEMENT = {
+  子: '水', 丑: '土', 寅: '木', 卯: '木', 辰: '土', 巳: '火',
+  午: '火', 未: '土', 申: '金', 酉: '金', 戌: '土', 亥: '水',
+};
+
+const GENERATES = { 木: '火', 火: '土', 土: '金', 金: '水', 水: '木' };
+const OVERCOMES = { 木: '土', 土: '水', 水: '火', 火: '金', 金: '木' };
+
+const LIUSHEN = ['青龙', '朱雀', '勾陈', '螣蛇', '白虎', '玄武'];
+// 日干 -> 初爻所起六神
+const LIUSHEN_START = { 甲: 0, 乙: 0, 丙: 1, 丁: 1, 戊: 2, 己: 3, 庚: 4, 辛: 4, 壬: 5, 癸: 5 };
+
+function liuqin(palaceElement, branchElement) {
+  if (palaceElement === branchElement) return '兄弟';
+  if (GENERATES[branchElement] === palaceElement) return '父母';
+  if (GENERATES[palaceElement] === branchElement) return '子孙';
+  if (OVERCOMES[branchElement] === palaceElement) return '官鬼';
+  if (OVERCOMES[palaceElement] === branchElement) return '妻财';
+  return '?';
+}
+
+// 构建 (上卦, 下卦) -> 卦 的索引
+const HEXAGRAM_INDEX = new Map();
+
+function flip(bits, positions) {
+  const out = bits.slice();
+  for (const p of positions) out[p] = out[p] ? 0 : 1;
+  return out;
+}
+
+for (const [palace, names] of Object.entries(PALACE_NAMES)) {
+  const t = TRIGRAM_BITS[palace];
+  const variants = [
+    { lower: t, upper: t },
+    { lower: flip(t, [0]), upper: t },
+    { lower: flip(t, [0, 1]), upper: t },
+    { lower: flip(t, [0, 1, 2]), upper: t },
+    { lower: flip(t, [0, 1, 2]), upper: flip(t, [0]) },
+    { lower: flip(t, [0, 1, 2]), upper: flip(t, [0, 1]) },
+    { lower: flip(t, [0, 1, 2]), upper: flip(t, [1]) },
+    { lower: t, upper: flip(t, [1]) },
+  ];
+  variants.forEach((v, order) => {
+    const upper = TRIGRAM_BY_VALUE[bitsValue(v.upper)];
+    const lower = TRIGRAM_BY_VALUE[bitsValue(v.lower)];
+    HEXAGRAM_INDEX.set(`${upper}|${lower}`, {
+      name: names[order],
+      palace,
+      palaceElement: PALACE_ELEMENT[palace],
+      order,
+      upper,
+      lower,
+      lines: [...v.lower, ...v.upper], // b0 初爻
+      shi: SHI_POSITION[order],
+      ying: SHI_POSITION[order] > 3 ? SHI_POSITION[order] - 3 : SHI_POSITION[order] + 3,
+    });
+  });
+}
+
+export const HEXAGRAM_COUNT = HEXAGRAM_INDEX.size;
+
+/** 由六爻（自下而上，1 = 阳）求卦 */
+export function hexagramFromBits(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}`);
+}
+
+/** 随机摇卦：三枚铜钱，背为阳（3），字为阴（2），合计 6/7/8/9 */
+export function tossLines(random = Math.random) {
+  const lines = [];
+  for (let i = 0; i < 6; i++) {
+    let sum = 0;
+    for (let c = 0; c < 3; c++) sum += random() < 0.5 ? 3 : 2;
+    lines.push(sum); // 6 老阴 7 少阳 8 少阴 9 老阳
+  }
+  return lines;
+}
+
+function lineToBit(v) {
+  return v === 7 || v === 9 ? 1 : 0;
+}
+
+function isMoving(v) {
+  return v === 6 || v === 9;
+}
+
+/**
+ * 装卦
+ * @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);
+
+  const invalid = rawLines.filter((v) => ![6, 7, 8, 9].includes(v));
+  if (invalid.length) throw new Error(`爻值只能是 6/7/8/9，收到 ${JSON.stringify(rawLines)}`);
+
+  const bits = rawLines.map(lineToBit);
+  const ben = hexagramFromBits(bits);
+  const moving = rawLines.map((v, i) => (isMoving(v) ? i : -1)).filter((i) => i >= 0);
+  const bianBits = moving.length ? flip(bits, moving) : null;
+  const bian = bianBits ? hexagramFromBits(bianBits) : null;
+
+  const dayGanZhi = input.dayGanZhi ?? (() => {
+    const now = new Date();
+    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 };
+  })();
+
+  const liushenStart = LIUSHEN_START[dayGanZhi.stem] ?? 0;
+
+  // 旬空：由日柱所在的旬推两位空亡（甲子旬→戌亥、甲戌旬→申酉、甲申旬→午未、
+  // 甲午旬→辰巳、甲辰旬→寅卯、甲寅旬→子丑）。六爻断卦离不开它，之前没有输出。
+  // 公式统一放在 calendar.xunKongOf，三体系共用一份，避免各自演化后互相漂移。
+  const dayIdx = sexagenaryIndex(STEMS.indexOf(dayGanZhi.stem), BRANCHES.indexOf(dayGanZhi.branch));
+  const xun = dayIdx >= 0 ? Math.floor(dayIdx / 10) : -1;
+  const xunKong = xunKongOf(`${dayGanZhi.stem}${dayGanZhi.branch}`);
+  const xunShou = xun >= 0 ? ganzhiName(xun * 10).name : '';
+
+  function decorate(hex, movingSet) {
+    const rows = [];
+    for (let i = 0; i < 6; i++) {
+      const isInner = i < 3;
+      const trigram = isInner ? hex.lower : hex.upper;
+      const nj = NAJIA[trigram];
+      const branch = isInner ? nj.inner[i] : nj.outer[i - 3];
+      const gan = isInner ? nj.gan[0] : nj.gan[1];
+      const element = BRANCH_ELEMENT[branch];
+      const value = rawLines[i];
+      rows.push({
+        position: i + 1,
+        name: ['初爻', '二爻', '三爻', '四爻', '五爻', '上爻'][i],
+        yinYang: bits[i] ? '阳' : '阴',
+        moving: movingSet ? movingSet.has(i) : isMoving(value),
+        symbol: bits[i] ? '━━━━━' : '━━ ━━',
+        ganzhi: gan + branch,
+        stem: gan,
+        branch,
+        element,
+        liuqin: liuqin(hex.palaceElement, element),
+        liushen: LIUSHEN[(liushenStart + i) % 6],
+      });
+    }
+    return rows;
+  }
+
+  const benRows = decorate(ben, new Set(moving));
+  const movingSet = new Set(moving);
+  const bianRows = bian ? decorate(bian, new Set()) : null;
+  if (bianRows) {
+    bianRows.forEach((r, i) => {
+      r.changedFrom = movingSet.has(i) ? benRows[i].symbol : null;
+    });
+  }
+
+  return {
+    system: 'liuyao',
+    question: input.question ?? null,
+    cast: {
+      lines: rawLines,
+      notation: rawLines.map((v) => ({ 6: '老阴 ✕', 7: '少阳', 8: '少阴', 9: '老阳 ○' }[v])),
+      movingPositions: moving.map((i) => i + 1),
+    },
+    dayGanZhi: { name: dayGanZhi.name, stem: dayGanZhi.stem, branch: dayGanZhi.branch },
+    xunShou,
+    xunKong,
+    ben: {
+      name: ben.name,
+      upper: ben.upper,
+      lower: ben.lower,
+      palace: `${ben.palace}宫`,
+      palaceElement: ben.palaceElement,
+      shi: ben.shi,
+      ying: ben.ying,
+      lines: benRows,
+    },
+    bian: bian
+      ? {
+        name: bian.name,
+        upper: bian.upper,
+        lower: bian.lower,
+        palace: `${bian.palace}宫`,
+        palaceElement: bian.palaceElement,
+        shi: bian.shi,
+        ying: bian.ying,
+        lines: bianRows,
+      }
+      : null,
+  };
+}

package/engine/lru.js

@@ -0,0 +1,69 @@
+// 统一 LRU 缓存：上限 + 可选 TTL + 命中率计数。
+//
+// 原先四处缓存各自为政（节气瞬时 4096 FIFO、单年 32、三年窗口 8、地址 200+TTL），
+// 淘汰策略与上限写法都不一样，也没法回答「到底有没有命中」。这里抽一个工厂，
+// 各处只保留自己的上限与 TTL 参数，行为等价，但结构统一、可观测。
+
+/**
+ * @param {{max?: number, ttlMs?: number, name?: string, now?: () => number}} [opts]
+ *   max   最多保留多少条（超出按最久未使用淘汰）
+ *   ttlMs >0 时，超过该毫秒数的条目视为未命中并删除
+ *   now   取时函数（测试可注入；默认 Date.now，避免引擎里散落时间源）
+ */
+export function createLru({ max = 64, ttlMs = 0, name = 'lru', now = () => Date.now() } = {}) {
+  const map = new Map(); // key -> { value, at }
+  const stats = { name, hits: 0, misses: 0, evictions: 0, expirations: 0 };
+
+  const expired = (entry) => ttlMs > 0 && now() - entry.at > ttlMs;
+
+  return {
+    name,
+    max,
+    ttlMs,
+    get(key) {
+      const entry = map.get(key);
+      if (!entry || expired(entry)) {
+        if (entry) { map.delete(key); stats.expirations += 1; }
+        stats.misses += 1;
+        return undefined;
+      }
+      // 命中后移到队尾，维持「最久未使用在队首」
+      map.delete(key);
+      map.set(key, entry);
+      stats.hits += 1;
+      return entry.value;
+    },
+    set(key, value) {
+      if (map.has(key)) map.delete(key);
+      map.set(key, { value, at: now() });
+      while (map.size > max) {
+        map.delete(map.keys().next().value);
+        stats.evictions += 1;
+      }
+      return value;
+    },
+    has(key) {
+      const entry = map.get(key);
+      if (!entry) return false;
+      if (expired(entry)) { map.delete(key); stats.expirations += 1; return false; }
+      return true;
+    },
+    delete(key) { return map.delete(key); },
+    clear() { map.clear(); },
+    get size() { return map.size; },
+    /** 快照：命中率在调用时按当前计数算，便于渲染一行指标 */
+    stats() {
+      const total = stats.hits + stats.misses;
+      return {
+        name,
+        size: map.size,
+        max,
+        hits: stats.hits,
+        misses: stats.misses,
+        evictions: stats.evictions,
+        expirations: stats.expirations,
+        hitRate: total ? stats.hits / total : 0,
+      };
+    },
+  };
+}