feiyu-memory 0.0.0-stage → 0.3.6

package/src/core/privacy.mjs

@@ -0,0 +1,252 @@
+/**
+ * 隐私层：落盘前的最后一道闸。
+ *
+ * 分三类，处理方式完全不同：
+ *
+ *  1. format —— 强确定性的可识别格式（手机号/证件/卡号/邮箱）
+ *     只要开了第三方泛化就一律处理。误伤概率极低。
+ *
+ *  2. secret —— 密钥。**硬阻断**，永远处理，没有开关。
+ *     命中即替换，绝不入档、绝不进日志。
+ *
+ *  3. name / amount —— 弱信号。**只认高置信标记**。
+ *     人名只认称谓（王总/李老师）、小X/老X、"叫X"三种明确写法；
+ *     金额只处理超过门槛的数（保住"3 块钱的包子"这种生活细节）。
+ *
+ * 设计原则：**宁可少泛化，不要过度泛化**。
+ * 糊成一团"某人和某人在某地发生了某事"的日记，既没有隐私价值也没有记忆价值，
+ * 用户会直接关掉这个功能 —— 那就等于没有隐私保护。
+ */
+
+/** 永远处理：密钥。命中的文本块直接丢弃。 */
+const SECRET_RULES = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '私钥'],
+  [/\bsk-[A-Za-z0-9_-]{16,}\b/g, 'API Key'],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, 'GitHub Token'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, 'GitHub Token'],
+  [/\bAKIA[0-9A-Z]{16}\b/g, 'AWS Key'],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/g, 'Google Key'],
+  [/\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g, 'Slack Token'],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, 'JWT'],
+  [/\bBearer\s+[A-Za-z0-9._~+/-]{20,}=*/g, 'Bearer Token'],
+  [
+    /\b(?:pass(?:wo?r?d)?|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key)\b\s*(?::|=|\bis\b|是|为)\s*["']?[^\s"',;]{6,}["']?/gi,
+    '凭据',
+  ],
+  // ── 中文键名 ──
+  //
+  // 审计报告（F2，P2）：上面那条只认英文键名，而这是个中文插件 ——
+  // README 承诺"密码……被替换成 [已拦截]"，可是这些写法全都放行：
+  //
+  //   服务器 root 密码是 Zx9!kq2#Lm7$Pw
+  //   WiFi 密码：hunter2pass2026
+  //   数据库口令 Hunter2pass
+  //   阿里云 AccessKey Secret 是 wJalrXUtn...
+  //   my password is Hunter2pass
+  //
+  // 中文没有 \b 词边界，所以单独一条规则，分隔符接受 : ： = 是 为 is。
+  [/(?:密码|口令|密钥|秘钥|验证码)\s*(?::|：|=|是|为|\bis\b)?\s*["']?[^\s"',;，。]{6,}["']?/g, '凭据'],
+  // 只写冒号、没有连接词的那种（"密码：xxx" 上面已覆盖，这条兜 Union 场景）
+  [/(?:密码|口令|密钥|秘钥)\s*[:：]\s*\S{6,}/g, '凭据'],
+  // ── URL 里内嵌的凭据 ──
+  //
+  // postgres://admin:Hunter2pass@db.internal:5432/app
+  //
+  // 原来这条"碰巧"被邮箱规则吃掉了（Hunter2pass@db.internal 像个邮箱），
+  // 换个 scheme 或者密码里没 @ 就漏。单独成规则才稳。
+  [/\/\/[^\/\s:@]+:[^@\s/]{4,}@/g, '凭据'],
+  // ── 长数字 ──
+  //
+  // 社区报告（2026-10-24）：一串 13 位数字 `123456789012` 原样进了
+  // relationship.json 的 evidence 字段。手机号规则只认 11 位大陆号，
+  // 11 位以上的一律放行。
+  //
+  // **门槛是 12 位，不是 11** —— 11 位是手机号，那个由上面 `RULES` 里的手机号
+  // 而且用户明确表示过"露着吧"。11 位以上基本只有电话号码和身份证号。
+  [/\b\d{12,}\b/g, '长数字'],
+];
+
+const SECRET_PLACEHOLDER = '[已拦截]';
+
+/**
+ * @typedef {'format'|'name'|'amount'} RuleGroup
+ * @typedef {object} Rule
+ * @property {RegExp} re
+ * @property {string | ((...m: string[]) => string)} replace
+ * @property {string} label
+ * @property {RuleGroup} group
+ */
+
+/** @type {Rule[]} */
+const RULES = [
+  { group: 'format', label: '手机号', re: /(?<!\d)1[3-9]\d{9}(?!\d)/g, replace: '[手机号]' },
+  { group: 'format', label: '证件号', re: /(?<!\d)\d{17}[\dXx](?!\d)/g, replace: '[证件号]' },
+  { group: 'format', label: '卡号', re: /(?<!\d)\d{16,19}(?!\d)/g, replace: '[卡号]' },
+  {
+    group: 'format',
+    label: '邮箱',
+    re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    replace: '[邮箱]',
+  },
+
+  // 称谓式人名：姓氏表 + 称谓。高置信，误伤极小。
+  {
+    group: 'name',
+    label: '称谓式人名',
+    re: /[\u5f20\u738b\u674e\u8d75\u5218\u9648\u6768\u9ec4\u5468\u5434\u5f90\u5b59\u9a6c\u6731\u80e1\u6797\u90ed\u4f55\u9ad8\u7f57\u90d1\u6881\u8c22\u5b8b\u5510\u8bb8\u97e9\u51af\u9093\u66f9\u5f6d\u66fe\u8096\u7530\u8463\u6f58\u8881\u8521\u848b\u4f59\u4e8e\u675c\u53f6\u7a0b\u82cf\u9b4f\u5415\u4e01\u4efb\u6c88\u59da\u5362\u59dc\u5d14\u949f\u8c2d\u9646\u6c6a\u8303\u91d1\u77f3\u5ed6\u8d3e\u590f\u97e6\u4ed8\u65b9\u767d\u90b9\u5b5f\u718a\u79e6\u90b1\u6c5f\u5c39\u859b\u95eb\u6bb5\u96f7\u4faf\u9f99\u53f2\u9676\u9ece\u8d3a\u987e\u6bdb\u90dd\u9f9a\u90b5\u4e07\u94b1\u4e25\u8983\u6b66\u6234\u83ab\u5b54\u5411\u6c64][\u603b\u8001\u5e08\u533b\u751f\u7ecf\u7406\u4e3b\u4efb\u54e5\u59d0\u53d4\u59e8\u5de5]/g,
+    replace: '[某人]',
+  },
+  // 小X / 老X
+  {
+    group: 'name',
+    label: '小X/老X',
+    re: /[\u5c0f\u8001][\u5f20\u738b\u674e\u8d75\u5218\u9648\u6768\u9ec4\u5468\u5434\u5f90\u5b59\u9a6c\u6731\u80e1\u6797\u90ed\u4f55\u9ad8\u7f57\u90d1\u6881\u8c22\u5b8b\u5510\u8bb8\u97e9\u51af\u9093\u66f9]/g,
+    replace: '[某人]',
+  },
+  // 明确引入的名字："叫X" / "名叫X" / "名字是X"
+  {
+    group: 'name',
+    label: '明确指名的名字',
+    re: /(叫|名叫|名字是)([\u4e00-\u9fa5]{2,4})(?=[\s\uff0c\u3002\uff01\uff1f,]|$)/g,
+    replace: (_m, lead) => `${lead}[某人]`,
+  },
+];
+
+/** 金额门槛：低于此值的金额不动 */
+export const DEFAULT_AMOUNT_THRESHOLD = 100;
+
+/** 带单位的金额（元/块/万/亿…），要读数字，所以单独处理 */
+const AMOUNT_UNIT_RE = /(?<![\d.])(\d[\d,]*(?:\.\d+)?)\s*(万元|万块|亿元|万|亿|元|块钱|块)(?![\d])/g;
+/** 带币种符号的金额 */
+const AMOUNT_SYMBOL_RE = /(?:¥|￥|\$)\s?(\d[\d,]*(?:\.\d+)?)/g;
+
+/**
+ * @typedef {object} PrivacyOptions
+ * @property {boolean} [thirdParty]      总开关：泛化第三方信息（默认 true）
+ * @property {boolean} [redactNames]     处理人名的弱信号规则（默认随 thirdParty）
+ * @property {boolean} [amounts]         泛化大额金额（默认随 thirdParty）
+ * @property {number}  [amountThreshold] 金额门槛（默认 100）
+ */
+
+/**
+ * 清洗一段文本。幂等 —— 占位符不会再次命中规则，重复调用结果稳定。
+ *
+ * @param {string} text
+ * @param {PrivacyOptions} [options]
+ * @returns {{text: string, hits: Array<{kind: string, label: string, count: number}>, blocked: boolean}}
+ */
+export function scrub(text, options = {}) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { text: typeof text === 'string' ? text : '', hits: [], blocked: false };
+  }
+
+  const thirdParty = options.thirdParty !== false;
+  const redactNames = options.redactNames !== false && thirdParty;
+  const doAmounts = options.amounts !== false && thirdParty;
+  const threshold = Number.isFinite(options.amountThreshold)
+    ? options.amountThreshold
+    : DEFAULT_AMOUNT_THRESHOLD;
+
+  const tally = new Map();
+  const bump = (kind, label, n = 1) => {
+    const key = `${kind}\u0000${label}`;
+    const cur = tally.get(key) ?? { kind, label, count: 0 };
+    cur.count += n;
+    tally.set(key, cur);
+  };
+
+  let out = text;
+
+  // 1) 密钥先做，且无条件做。后面任何一步出错，密钥都已经没了。
+  let blocked = false;
+  for (const [re, label] of SECRET_RULES) {
+    if (!re.test(out)) continue;
+    re.lastIndex = 0;
+    out = out.replace(re, () => {
+      blocked = true;
+      bump('secret', label);
+      return SECRET_PLACEHOLDER;
+    });
+  }
+
+  // 2) 格式类 / 人名类
+  if (thirdParty) {
+    for (const rule of RULES) {
+      if (rule.group === 'name' && !redactNames) continue;
+      out = out.replace(rule.re, (...args) => {
+        bump('thirdParty', rule.label);
+        return typeof rule.replace === 'function' ? rule.replace(...args) : rule.replace;
+      });
+    }
+  }
+
+  // 3) 金额（带门槛）
+  if (doAmounts) {
+    const overThreshold = (digits) => {
+      const v = Number(String(digits).replace(/,/g, ''));
+      return Number.isFinite(v) && v >= threshold;
+    };
+    out = out.replace(AMOUNT_UNIT_RE, (match, digits) => {
+      if (!overThreshold(digits)) return match;
+      bump('thirdParty', '金额');
+      return '一笔钱';
+    });
+    out = out.replace(AMOUNT_SYMBOL_RE, (match, digits) => {
+      if (!overThreshold(digits)) return match;
+      bump('thirdParty', '金额');
+      return '一笔钱';
+    });
+  }
+
+  return { text: out, hits: [...tally.values()], blocked };
+}
+
+/**
+ * 批量清洗，合并命中统计。
+ * @param {string[]} texts
+ * @param {PrivacyOptions} [options]
+ */
+export function scrubAll(texts, options = {}) {
+  const merged = new Map();
+  let blocked = false;
+  const out = texts.map((t) => {
+    const r = scrub(t, options);
+    blocked ||= r.blocked;
+    for (const h of r.hits) {
+      const key = `${h.kind}\u0000${h.label}`;
+      const cur = merged.get(key) ?? { kind: h.kind, label: h.label, count: 0 };
+      cur.count += h.count;
+      merged.set(key, cur);
+    }
+    return r.text;
+  });
+  return { texts: out, hits: [...merged.values()], blocked };
+}
+
+/**
+ * 给用户看的一句提示。刻意短，不弹窗、不说教 —— 像鱼，不像系统。
+ * @param {Array<{kind: string, label: string, count: number}>} hits
+ * @returns {string} 无命中时返回空串
+ */
+export function noticeFor(hits) {
+  if (!hits || hits.length === 0) return '';
+  const sum = (kind) =>
+    hits.filter((h) => (kind === 'secret' ? h.kind === 'secret' : h.kind !== 'secret'))
+      .reduce((s, h) => s + h.count, 0);
+  const parts = [];
+  const secrets = sum('secret');
+  const others = sum('other');
+  if (secrets > 0) parts.push(`拦下 ${secrets} 处密钥`);
+  if (others > 0) parts.push(`模糊了 ${others} 处别人家的信息`);
+  return parts.length > 0 ? parts.join('，') + '。' : '';
+}
+
+/**
+ * 预设：给"我就想让它记住我女朋友名字"的用户。
+ * 注意密钥与格式类仍然生效 —— 那两类没有关闭的理由。
+ */
+export const PRESET_REMEMBER_NAMES = Object.freeze({
+  thirdParty: true,
+  redactNames: false,
+  amounts: false,
+});

package/src/core/recall.mjs

@@ -0,0 +1,280 @@
+/**
+ * 记忆召回 —— 完全本地、零模型 token。
+ *
+ * 为什么不用 SQLite / 向量库：
+ *  - 向量库要下载模型 + 占几百 MB，还得开 GPU 之外的线程池，与"轻到不像插件"背道而驰
+ *  - SQLite 要么引原生依赖（插件装不上），要么赌运行时有 `node:sqlite`
+ *  - 倒排索引对我们这个量级（十年日记 ≈ 几千条）是**毫秒级**的，
+ *    而且索引是纯派生的 —— 每次加载重建，不需要存盘，文件坏了也不影响档案本体
+ *
+ * 打分 = a·文本相似度 + b·salience + c·新鲜度 − d·最近刚提过的惩罚
+ *
+ * 分流刻意保留随机性：人本来就是"联想到什么说什么"，
+ * 每次都精准翻出最相关的那条，是数据库，不是鱼。
+ */
+
+import { tokenize } from './keywords.mjs';
+
+/** IDF 平滑，避免 df=0 时除零 */
+const IDF_SMOOTH = 1;
+
+/**
+ * 建倒排索引。纯派生数据，随用随建。
+ *
+ * @param {Array<{id: string, keywords?: string[], text?: string}>} entries
+ * @returns {{postings: Map<string, Map<string, number>>, df: Map<string, number>, lengths: Map<string, number>, N: number}}
+ */
+export function buildIndex(entries) {
+  const postings = new Map();
+  const df = new Map();
+  const lengths = new Map();
+  const list = Array.isArray(entries) ? entries : [];
+
+  for (const entry of list) {
+    // 以正文为主索引；已存的关键词额外加权（重复计入），因为它们是刻意提炼过的
+    const tokens = tokenize(entry.text ?? '');
+    if (Array.isArray(entry.keywords)) {
+      for (const k of entry.keywords) {
+        const kt = tokenize(k);
+        tokens.push(...kt, ...kt);
+      }
+    }
+    if (tokens.length === 0) continue;
+
+    const tf = new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+
+    for (const [t, n] of tf) {
+      let bucket = postings.get(t);
+      if (bucket === undefined) {
+        bucket = new Map();
+        postings.set(t, bucket);
+      }
+      bucket.set(entry.id, n);
+      df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    lengths.set(entry.id, tokens.length);
+  }
+
+  return { postings, df, lengths, N: lengths.size };
+}
+
+/**
+ * BM25-lite 检索，分数映射到 0~1（便于设阈值）。
+ *
+ * 归一化方式经过一次返工：最初用"命中证据 / 查询全部 token 的 idf 之和"，
+ * 结果**永远匹配不上** —— 中文 bigram 会产生大量噪声 token（"序算""法还"），
+ * 它们把分母顶得很大，一条明显相关的日记只能拿到 0.10 分。
+ *
+ * 现在改用**饱和函数**：只看命中了多少有区分度的证据，与查询长度解耦。
+ *
+ *     sim = 1 − exp(−Σgain / saturation)
+ *
+ * 好处：分数含义稳定 —— 命中 1 个实词约 0.4，命中 2 个约 0.67，完全无关是 0。
+ * 阈值因此可以说人话，也不会因为用户多打几个字就掉到阈值以下。
+ *
+ * @param {ReturnType<typeof buildIndex>} index
+ * @param {string} query
+ * @param {{limit?: number, saturation?: number}} [options]
+ * @returns {Map<string, number>} id → 相似度 0~1（未命中的条目不会出现在 map 里）
+ */
+export function searchScores(index, query, options = {}) {
+  const limit = options.limit ?? 50;
+  const saturation = Number.isFinite(options.saturation) && options.saturation > 0
+    ? options.saturation
+    : 2;
+  const scores = new Map();
+  if (index.N === 0) return scores;
+
+  // 查询侧去重：bigram 噪声里重复 token 不该重复计分
+  const qTokens = [...new Set(tokenize(query))];
+  if (qTokens.length === 0) return scores;
+
+  const idf = (t) => Math.log(1 + (index.N + IDF_SMOOTH) / ((index.df.get(t) ?? 0) + IDF_SMOOTH));
+
+  const k1 = 1.2;
+  const b = 0.75;
+  const avgLen =
+    [...index.lengths.values()].reduce((s, n) => s + n, 0) / Math.max(1, index.lengths.size);
+
+  const raw = new Map();
+  for (const t of qTokens) {
+    const bucket = index.postings.get(t);
+    if (bucket === undefined) continue;
+    const w = idf(t);
+    for (const [id, tf] of bucket) {
+      const len = index.lengths.get(id) ?? avgLen;
+      const norm = 1 - b + (b * len) / Math.max(1, avgLen);
+      const gain = (w * (tf * (k1 + 1))) / (tf + k1 * norm);
+      raw.set(id, (raw.get(id) ?? 0) + gain);
+    }
+  }
+
+  for (const [id, r] of raw) scores.set(id, Math.min(1, 1 - Math.exp(-r / saturation)));
+
+  if (scores.size > limit) {
+    const kept = [...scores.entries()].sort((a, b2) => b2[1] - a[1]).slice(0, limit);
+    return new Map(kept);
+  }
+  return scores;
+}
+
+/** 新鲜度：指数衰减 */
+function recencyFactor(createdAt, now, halfLifeDays) {
+  if (!Number.isFinite(createdAt)) return 0.5;
+  const ageDays = Math.max(0, (now - createdAt) / 86400000);
+  return Math.pow(0.5, ageDays / Math.max(0.5, halfLifeDays));
+}
+
+/**
+ * @typedef {object} RecallOptions
+ * @property {number} [highSim]        高相似必触发（默认 0.5 ≈ 共享 2 个以上实词）
+ * @property {number} [midSim]         中相似进随机池（默认 0.25 ≈ 共享 1 个实词）
+ * @property {number} [minSalience]    进入随机池的最低 salience（默认 0.5）
+ * @property {number} [saturation]     相似度饱和尺度（默认 2）
+ * @property {number} [a]              相似度权重（默认 1）
+ * @property {number} [b]              salience 权重（默认 0.45）
+ * @property {number} [c]              新鲜度权重（默认 0.2）
+ * @property {number} [d]              最近刚提过的惩罚（默认 0.8）
+ * @property {number} [temperature]    softmax 温度（默认 0.15）
+ * @property {number} [cooldownTurns]  同一条的冷却轮数（默认 20）
+ * @property {number} [maxShow]        每轮最多露几条（默认 1）
+ * @property {number} [wanderChance]   没有强匹配时"走神"随机想起一条的概率（默认 0.08）
+ * @property {number} [halfLifeDays]   新鲜度半衰期（默认 45）
+ * @property {number} [now]            当前时间戳
+ * @property {() => number} [rng]      注入随机源（测试用）
+ */
+
+export const DEFAULT_RECALL_OPTIONS = Object.freeze({
+  highSim: 0.5,
+  midSim: 0.25,
+  minSalience: 0.5,
+  saturation: 2,
+  a: 1,
+  b: 0.45,
+  c: 0.2,
+  d: 0.8,
+  temperature: 0.15,
+  cooldownTurns: 20,
+  maxShow: 1,
+  wanderChance: 0.08,
+  halfLifeDays: 45,
+});
+
+/**
+ * @typedef {object} RecallState
+ * @property {Map<string, number>} [lastShownTurn]  条目 → 上次露出的轮次
+ */
+
+/**
+ * 挑出这一轮要提起的记忆。
+ *
+ * @param {Array<object>} entries 全部日记条目
+ * @param {ReturnType<typeof buildIndex>} index
+ * @param {string} query 本轮用户消息
+ * @param {RecallState} state
+ * @param {number} turn 当前轮次
+ * @param {RecallOptions} [options]
+ * @returns {{chosen: Array<{entry: object, score: number, sim: number, why: string}>, considered: number}}
+ */
+export function selectMemories(entries, index, query, state, turn, options = {}) {
+  const opts = { ...DEFAULT_RECALL_OPTIONS, ...options };
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const rng = typeof opts.rng === 'function' ? opts.rng : Math.random;
+  const lastShownTurn = state?.lastShownTurn ?? new Map();
+
+  const sims = searchScores(index, query, { saturation: opts.saturation });
+  /** @type {Array<{entry: object, score: number, sim: number, why: string}>} */
+  const scored = [];
+
+  for (const entry of entries) {
+    const sim = sims.get(entry.id) ?? 0;
+    const salience = Number.isFinite(entry.salience) ? entry.salience : 0.5;
+
+    // 冷却：刚提过就别再提
+    const last = lastShownTurn.get(entry.id);
+    if (Number.isFinite(last) && turn - last < opts.cooldownTurns) continue;
+
+    const fresh = recencyFactor(entry.created_at, now, opts.halfLifeDays);
+    const score =
+      opts.a * sim + opts.b * salience + opts.c * fresh - (Number.isFinite(last) ? opts.d : 0);
+
+    if (sim < opts.midSim && salience < opts.minSalience) continue;
+    scored.push({ entry, score, sim, why: '' });
+  }
+
+  // 未解决的失败记忆：稍微加权，因为它们最该被主动提起
+  const addWhy = (c, reason) => {
+    c.why = c.why ? `${c.why} + ${reason}` : reason;
+  };
+  for (const c of scored) {
+    if (c.entry.kind === 'failure' && c.entry.resolved !== true) {
+      c.score += 0.15;
+      addWhy(c, '未解决');
+    }
+  }
+
+  scored.sort((x, y) => y.score - x.score);
+
+  const strong = scored.filter((c) => c.sim >= opts.highSim);
+  const chosen = [];
+
+  // 1) 强匹配：必触发
+  for (const c of strong.slice(0, opts.maxShow)) {
+    addWhy(c, '强匹配');
+    chosen.push(c);
+  }
+
+  // 2) 还不够，且允许走神：从中等候选里按 softmax 随机抽
+  if (chosen.length < opts.maxShow) {
+    const pool = scored.filter(
+      (c) => !chosen.includes(c) && c.sim >= opts.midSim && (c.entry.salience ?? 0) >= opts.minSalience,
+    );
+    if (pool.length > 0) {
+      const picked = softmaxPick(pool, opts.temperature, rng);
+      if (picked !== undefined) {
+        addWhy(picked, '想起来一点');
+        chosen.push(picked);
+      }
+    }
+  }
+
+  // 3) 走神：完全没匹配上时，小概率随机想起一条旧事。这条纯粹为了像人。
+  if (chosen.length === 0 && rng() < opts.wanderChance) {
+    const pool = scored.filter((c) => (c.entry.salience ?? 0) >= opts.minSalience);
+    if (pool.length > 0) {
+      const picked = pool[Math.floor(rng() * pool.length)];
+      addWhy(picked, '走神想起来的');
+      chosen.push(picked);
+    }
+  }
+
+  // 记下露出时间，供冷却使用
+  for (const c of chosen) lastShownTurn.set(c.entry.id, turn);
+
+  return { chosen, considered: scored.length };
+}
+
+/**
+ * 按 softmax 概率抽一个。温度越低越接近"取最高分"。
+ * @template T
+ * @param {T[]} items 必须已按 score 降序，且每项有 .score
+ * @param {number} temperature
+ * @param {() => number} rng
+ * @returns {T | undefined}
+ */
+export function softmaxPick(items, temperature, rng) {
+  if (items.length === 0) return undefined;
+  if (items.length === 1) return items[0];
+  const t = Math.max(1e-6, temperature);
+  const max = items[0].score;
+  const exps = items.map((it) => Math.exp((it.score - max) / t));
+  const sum = exps.reduce((s, e) => s + e, 0);
+  if (!(sum > 0)) return items[0];
+  let r = rng() * sum;
+  for (let i = 0; i < items.length; i++) {
+    r -= exps[i];
+    if (r <= 0) return items[i];
+  }
+  return items[items.length - 1];
+}