@jjh32456/dsh-longlive 1.6.7 → 1.8.0

package/src/metrics/prestep-latency.mjs

@@ -0,0 +1,300 @@
+// src/metrics/prestep-latency.mjs — B3 时延责任归因（pre-step 编排器 observability）
+//
+// 目的：把「思考/回忆时间（t_question → t_evidence_ready）」拆成可归因的阶段：
+//   boot（开机卡）/ shared（共享活动流）/ working（工作帧）/ recall（召回编排）/
+//   inject（消息合并入 messages）/ budget（召回预算裁剪）
+// 另记 degradations[]：gate 跳过 / embedding 回退 / 零命中 / 预算裁剪 / 异常 fail-open。
+//
+// 契约：**纯计时、零行为变化**。所有入口都吞异常并返回 no-op 计时器；metrics 未启用时
+// 完全不写盘、不创建目录（registerMetrics 在入口调用 configurePrestepLatency）。
+// 落盘：<memoryRoot>/.longlive/metrics/prestep.jsonl，每轮一行（sessionId+turn 幂等）。
+// 面板/基准读取：readPrestepRows()；面板接线走 store.mjs#readPrestepSummary()。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PRESTEP_LATENCY_SCHEMA = 'prestep-latency/v1';
+export const PRESTEP_SUMMARY_SCHEMA = 'prestep-summary/v1';
+export const PRESTEP_FILE_NAME = 'prestep.jsonl';
+export const PRESTEP_PHASES = Object.freeze(['boot', 'shared', 'working', 'recall', 'inject', 'budget', 'guard']);
+export const PRESTEP_DEGRADES = Object.freeze([
+  'gate-skip', 'embedding-fallback', 'zero-hit', 'budget-trim', 'error', 'factory-unavailable', 'frame-skip',
+]);
+
+const state = {
+  enabled: false,
+  memoryRoot: '',
+  now: () => new Date(),
+  pending: new Map(), // key -> entry
+  finalized: new Map(), // key -> at (idempotency; bounded)
+};
+const MAX_ENTRIES = 2048;
+
+function roundMs(value) {
+  return Number.isFinite(value) ? Math.round(value * 1000) / 1000 : null;
+}
+function nowMs() {
+  if (typeof process.hrtime?.bigint === 'function') return process.hrtime.bigint();
+  return BigInt(Date.now()) * 1_000_000n;
+}
+function elapsedMs(start) {
+  if (start === null) return null;
+  try {
+    return Number(nowMs() - start) / 1e6;
+  } catch {
+    return null;
+  }
+}
+function safeSessionId(sessionId) {
+  return typeof sessionId === 'string' && sessionId.trim() !== '' ? sessionId.trim() : 'unknown';
+}
+function safeTurn(turn) {
+  return Number.isFinite(Number(turn)) ? Number(turn) : null;
+}
+function turnKey(sessionId, turn) {
+  return `${safeSessionId(sessionId)}:${safeTurn(turn) === null ? '?' : safeTurn(turn)}`;
+}
+function prestepFile(memoryRoot) {
+  const root = typeof memoryRoot === 'string' && memoryRoot.trim() !== '' ? path.resolve(memoryRoot.trim()) : '';
+  return root === '' ? '' : path.join(root, '.longlive', 'metrics', PRESTEP_FILE_NAME);
+}
+function trimMap(map) {
+  while (map.size > MAX_ENTRIES) {
+    const first = map.keys().next().value;
+    map.delete(first);
+  }
+}
+
+/**
+ * Called once by metrics registration. `enabled:false` makes every helper a no-op
+ * with zero disk IO; changing memoryRoot resets in-flight turn state.
+ */
+export function configurePrestepLatency(options = {}) {
+  const memoryRoot = typeof options.memoryRoot === 'string' ? options.memoryRoot.trim() : '';
+  if (memoryRoot !== state.memoryRoot) {
+    state.pending.clear();
+    state.finalized.clear();
+  }
+  state.enabled = options.enabled === true && memoryRoot !== '';
+  state.memoryRoot = memoryRoot;
+  state.now = typeof options.now === 'function' ? options.now : () => new Date();
+  return { enabled: state.enabled, memoryRoot: state.memoryRoot };
+}
+
+export function prestepLatencyEnabled() {
+  return state.enabled === true;
+}
+
+export function resetPrestepLatencyForTests() {
+  state.pending.clear();
+  state.finalized.clear();
+  state.enabled = false;
+  state.memoryRoot = '';
+}
+
+function getEntry(sessionId, turn) {
+  const key = turnKey(sessionId, turn);
+  let entry = state.pending.get(key);
+  if (!entry) {
+    entry = {
+      key,
+      sessionId: safeSessionId(sessionId),
+      turn: safeTurn(turn),
+      startedAt: state.now().toISOString(),
+      phases: Object.fromEntries(PRESTEP_PHASES.map((name) => [name, null])),
+      degrades: [],
+      meta: {},
+    };
+    state.pending.set(key, entry);
+    trimMap(state.pending);
+  }
+  return entry;
+}
+
+/** Open a phase timer; always safe to call. */
+export function startPrestepPhase(sessionId, turn, phase) {
+  if (!state.enabled || !PRESTEP_PHASES.includes(phase)) return { end() {} };
+  let start = null;
+  try {
+    const entry = getEntry(sessionId, turn);
+    start = nowMs();
+    return {
+      end(detail = null) {
+        if (start === null) return;
+        const ms = elapsedMs(start);
+        start = null;
+        if (!Number.isFinite(ms)) return;
+        try {
+          entry.phases[phase] = roundMs(ms);
+          if (detail !== null && typeof detail === 'object') {
+            for (const [name, value] of Object.entries(detail)) {
+              if (name === 'degrades' && Array.isArray(value)) continue;
+              entry.meta[name] = value;
+            }
+          }
+        } catch { /* timing must never break a turn */ }
+      },
+    };
+  } catch {
+    return { end() {} };
+  }
+}
+
+/** Record one degradation reason for this turn (unknown session/turn just creates the entry). */
+export function notePrestepDegrade(sessionId, turn, input = {}) {
+  if (!state.enabled) return false;
+  try {
+    const entry = getEntry(sessionId, turn);
+    const kind = typeof input.kind === 'string' && input.kind !== '' ? input.kind : 'error';
+    entry.degrades.push({
+      kind,
+      phase: typeof input.phase === 'string' && PRESTEP_PHASES.includes(input.phase) ? input.phase : null,
+      detail: input.detail === undefined ? null : String(input.detail),
+    });
+    if (entry.degrades.length > 32) entry.degrades.splice(0, entry.degrades.length - 32);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Merge metadata into this turn's row (e.g. budget tokens, injected paths). */
+export function setPrestepMeta(sessionId, turn, meta = {}) {
+  if (!state.enabled || meta === null || typeof meta !== 'object') return false;
+  try {
+    Object.assign(getEntry(sessionId, turn).meta, meta);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function dominantOf(phases) {
+  let name = null;
+  let ms = -1;
+  for (const key of PRESTEP_PHASES) {
+    const value = phases[key];
+    if (Number.isFinite(value) && value > ms) {
+      name = key;
+      ms = value;
+    }
+  }
+  return { dominant: name, dominantMs: ms >= 0 ? roundMs(ms) : null };
+}
+
+/**
+ * Write one row (idempotent per session:turn) and clear pending state.
+ * Safe to call from any pre-step handler / metrics turn-end fallback.
+ */
+export function finalizePrestepTurn(sessionId, turn, options = {}) {
+  if (!state.enabled) return null;
+  const key = turnKey(sessionId, turn);
+  if (state.finalized.has(key)) return null;
+  let entry = state.pending.get(key);
+  if (!entry) entry = getEntry(sessionId, turn);
+  state.pending.delete(key);
+  state.finalized.set(key, state.now().toISOString());
+  trimMap(state.finalized);
+
+  let ms = 0;
+  let counted = 0;
+  for (const name of PRESTEP_PHASES) {
+    if (Number.isFinite(entry.phases[name])) {
+      ms += entry.phases[name];
+      counted += 1;
+    }
+  }
+  const { dominant, dominantMs } = dominantOf(entry.phases);
+  const row = {
+    schema: PRESTEP_LATENCY_SCHEMA,
+    at: state.now().toISOString(),
+    sessionId: entry.sessionId,
+    turn: entry.turn,
+    phases: { ...entry.phases },
+    dominant,
+    dominantMs,
+    ms: counted === 0 ? null : roundMs(ms),
+    countedPhases: counted,
+    degrades: entry.degrades,
+    meta: entry.meta,
+  };
+  const file = prestepFile(typeof options.memoryRoot === 'string' && options.memoryRoot.trim() !== '' ? options.memoryRoot : state.memoryRoot);
+  if (file === '') return null;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(row)}\n`, 'utf8');
+  } catch {
+    return null;
+  }
+  return row;
+}
+
+/** Read raw rows, newest last. Corrupt lines skipped; never throws. */
+export function readPrestepRows(options = {}) {
+  const file = prestepFile(options.memoryRoot);
+  if (file === '') return { ok: false, code: 'E_MEMORY_ROOT_UNSET', path: '', rows: [], total: 0, skipped: 0 };
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { ok: true, path: file, rows: [], total: 0, skipped: 0, exists: false };
+    return { ok: false, code: 'E_PRESTEP_READ', path: file, rows: [], total: 0, skipped: 0, message: String(error?.message ?? error) };
+  }
+  const rows = [];
+  let skipped = 0;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    try {
+      const row = JSON.parse(trimmed);
+      if (row && typeof row === 'object' && row.schema === PRESTEP_LATENCY_SCHEMA) rows.push(row);
+      else skipped += 1;
+    } catch {
+      skipped += 1;
+    }
+  }
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 0;
+  const kept = limit > 0 ? rows.slice(-limit) : rows;
+  return { ok: true, path: file, exists: true, rows: kept, total: rows.length, skipped };
+}
+
+function avg(values) {
+  if (values.length === 0) return null;
+  return roundMs(values.reduce((sum, value) => sum + value, 0) / values.length);
+}
+function p50(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return roundMs(sorted[Math.floor((sorted.length - 1) / 2)]);
+}
+
+/** Deterministic summary for the panel (#9 write-health `prestep` field) / benchmarks. */
+export function summarizePrestepRows(rows = []) {
+  const phases = {};
+  for (const name of PRESTEP_PHASES) {
+    const values = [];
+    for (const row of rows) {
+      const value = row?.phases?.[name];
+      if (Number.isFinite(value)) values.push(value);
+    }
+    phases[name] = { count: values.length, avgMs: avg(values), p50Ms: p50(values), maxMs: values.length > 0 ? roundMs(Math.max(...values)) : null };
+  }
+  const dominantCounts = {};
+  const degradeCounts = {};
+  let lastAt = null;
+  for (const row of rows) {
+    if (typeof row.dominant === 'string' && row.dominant !== '') dominantCounts[row.dominant] = (dominantCounts[row.dominant] ?? 0) + 1;
+    for (const item of Array.isArray(row.degrades) ? row.degrades : []) {
+      if (typeof item?.kind === 'string') degradeCounts[item.kind] = (degradeCounts[item.kind] ?? 0) + 1;
+    }
+    if (typeof row.at === 'string' && (lastAt === null || row.at > lastAt)) lastAt = row.at;
+  }
+  return {
+    schema: PRESTEP_SUMMARY_SCHEMA,
+    count: rows.length,
+    lastAt,
+    phases,
+    dominantCounts,
+    degradeCounts,
+  };
+}

package/src/metrics/store.mjs

@@ -13,10 +13,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { summarizeRows, clampFactor, DEFAULT_FACTOR, DEFAULT_KEEP_TURNS } from './measure.mjs';
+import { PRESTEP_FILE_NAME, readPrestepRows, summarizePrestepRows } from './prestep-latency.mjs';
 
 export const METRICS_DIR_NAME = 'metrics';
 export const TURNS_FILE_NAME = 'turns.jsonl';
 export const STATE_FILE_NAME = 'state.json';
+export const PRESTEP_FILE = PRESTEP_FILE_NAME;
 export const LEDGER_VERSION = 1;
 
 export function metricsDir(memoryRoot) {
@@ -34,6 +36,29 @@ export function calibrationPath(memoryRoot) {
   return dir === '' ? '' : path.join(dir, STATE_FILE_NAME);
 }
 
+export function prestepLedgerPath(memoryRoot) {
+  const dir = metricsDir(memoryRoot);
+  return dir === '' ? '' : path.join(dir, PRESTEP_FILE_NAME);
+}
+
+/**
+ * B3: read the pre-step latency ledger (`.longlive/metrics/prestep.jsonl`).
+ * Best-effort, never throws; corrupt lines are counted in `skipped`.
+ */
+export function readPrestepLedger(options = {}) {
+  return readPrestepRows({ memoryRoot: options.memoryRoot, limit: options.limit });
+}
+
+/**
+ * B3: deterministic pre-step latency summary for the panel.
+ * Activity-writer A6 wiring: add `prestep: readPrestepSummary({ memoryRoot })` to the
+ * #9 write-health reader response (see B3 handoff), no new route id needed.
+ */
+export function readPrestepSummary(options = {}) {
+  const rows = readPrestepRows({ memoryRoot: options.memoryRoot, limit: options.limit }).rows;
+  return summarizePrestepRows(rows);
+}
+
 /** Append one row.  Never throws. */
 export function appendTurnRow(row, options = {}) {
   const memoryRoot = options.memoryRoot;

package/src/policy-profile.js

@@ -2,10 +2,11 @@
 // 这一层刻意放在 src/router 之外：判定层（route.js）可以 import 它，
 // 但产品代码（index.js）不需要 import 任何带 router 字样的模块。
 import { readFileSync } from 'node:fs';
+import { applyAdapterPolicy } from './adapters/registry.js';
 
 export const POLICY_PROFILE_DEFAULT = 'generic';
 export const POLICY_PROFILE_BASE = 'generic';
-export const POLICY_PROFILE_SOURCE = 'J8-RULINGS-2026-11-03';
+export const POLICY_PROFILE_SOURCE = 'example-policy';
 export const POLICY_PROFILE_DIR = new URL('./router/policies/', import.meta.url);
 
 export const E_ROUTE_PROFILE_UNKNOWN = 'E_ROUTE_PROFILE_UNKNOWN';
@@ -417,7 +418,14 @@ export function loadPolicyProfile(name = POLICY_PROFILE_DEFAULT, options = {}) {
   if (baseProblem) return baseProblem;
   const base = baseRead.value;
   if (name === POLICY_PROFILE_BASE) {
-    return { ok: true, name, policy: JSON.parse(JSON.stringify(base)), sources: [`${name}.json`] };
+    // M2-E：adapter 策略片段（第三方写作用域等）在核心 profile 校验后并入；失败仅降级。
+    const patched = applyAdapterPolicy(base);
+    if (patched.degraded) {
+      return { ok: true, name, policy: patched.policy, sources: [`${name}.json`], adapterDegraded: patched.errors };
+    }
+    const patchedProblem = validateBase(patched.policy, name);
+    if (patchedProblem) return patchedProblem;
+    return { ok: true, name, policy: patched.policy, sources: [`${name}.json`] };
   }
   const overlayRead = readProfile(name, dir);
   if (overlayRead.error) return overlayRead.error;
@@ -426,7 +434,14 @@ export function loadPolicyProfile(name = POLICY_PROFILE_DEFAULT, options = {}) {
   const policy = mergePolicyProfile(base, overlayRead.value);
   const mergedProblem = validateBase(policy, name);
   if (mergedProblem) return mergedProblem;
-  return { ok: true, name, policy, sources: [`${POLICY_PROFILE_BASE}.json`, `${name}.json`] };
+  // M2-E：adapter 策略片段并入（失败仅降级，不阻塞核心 profile）。
+  const patched = applyAdapterPolicy(policy);
+  if (patched.degraded) {
+    return { ok: true, name, policy: patched.policy, sources: [`${POLICY_PROFILE_BASE}.json`, `${name}.json`], adapterDegraded: patched.errors };
+  }
+  const patchedProblem = validateBase(patched.policy, name);
+  if (patchedProblem) return patchedProblem;
+  return { ok: true, name, policy: patched.policy, sources: [`${POLICY_PROFILE_BASE}.json`, `${name}.json`] };
 }
 
 export function configurePolicyProfile(name) {

package/src/recall/anaphora.mjs

@@ -0,0 +1,87 @@
+// src/recall/anaphora.mjs — B2：指代链解析（它/这个/那个/他/她/上面/刚才）
+//
+// 只用上下文（焦点实体 + 最近用户文本），无候选时 resolved=null（不猜）。
+// 输出可回填查询：把 resolved 实体追加进查询词，提升同实体卡片命中。
+
+export const ANAPHORA_SCHEMA = 'anaphora/v1';
+
+export const PRONOUN_PATTERNS = Object.freeze([
+  { pronoun: '它', regex: /它/gu },
+  { pronoun: '它们', regex: /它们/gu },
+  { pronoun: '这个', regex: /这个/gu },
+  { pronoun: '那个', regex: /那个/gu },
+  { pronoun: '这些', regex: /这些/gu },
+  { pronoun: '那些', regex: /那些/gu },
+  { pronoun: '上面', regex: /上面|上述|前面/u },
+  { pronoun: '刚才', regex: /刚才|刚刚/u },
+  { pronoun: '他', regex: /他(?![们])/gu },
+  { pronoun: '她', regex: /她(?![们])/gu },
+  { pronoun: '他们', regex: /他们/gu },
+  { pronoun: '她们', regex: /她们/gu },
+]);
+
+const STOPWORDS = new Set([
+  '这个', '那个', '这些', '那些', '什么', '怎么', '可以', '我们', '你们', '他们', '她们', '自己',
+  '一个', '一下', '现在', '然后', '因为', '所以', '但是', '如果', '已经', '还是', '不是', '没有',
+  '没有', '就是', '这样', '那样', '这里', '那里', '时候', '东西', '事情', '问题', '继续', '开始',
+]);
+
+function normalizeToken(token) {
+  return String(token ?? '').trim();
+}
+
+/** Extract plausible entity tokens from a text (CJK 2-12 chars / ASCII words), stopwords dropped. */
+export function extractEntityTokens(text, { max = 12 } = {}) {
+  const value = typeof text === 'string' ? text : '';
+  const tokens = [];
+  const seen = new Set();
+  const cjk = value.match(/[\u3400-\u9fff]{2,12}/gu) ?? [];
+  const ascii = value.match(/[A-Za-z][A-Za-z0-9_.-]{1,30}/gu) ?? [];
+  for (const token of [...cjk, ...ascii]) {
+    if (STOPWORDS.has(token)) continue;
+    if (seen.has(token)) continue;
+    seen.add(token);
+    tokens.push(token);
+    if (tokens.length >= max) break;
+  }
+  return tokens;
+}
+
+/**
+ * Resolve pronouns in `text` against focus entities first, then recent user texts.
+ * @returns {{schema,references:{pronoun,resolved,candidates}[],terms:string[],unresolved:string[]}}
+ */
+export function resolveAnaphora({ text = '', recentTexts = [], focusEntities = [] } = {}) {
+  const query = typeof text === 'string' ? text : '';
+  const focus = (Array.isArray(focusEntities) ? focusEntities : [])
+    .map(normalizeToken)
+    .filter((token) => token !== '' && !STOPWORDS.has(token));
+  const recentTokens = [];
+  for (const recent of Array.isArray(recentTexts) ? recentTexts.slice(-3) : []) {
+    for (const token of extractEntityTokens(recent)) {
+      if (!recentTokens.includes(token)) recentTokens.push(token);
+    }
+  }
+  const candidates = [...new Set([...focus, ...recentTokens])];
+  const references = [];
+  const terms = [];
+  const unresolved = [];
+  for (const { pronoun, regex } of PRONOUN_PATTERNS) {
+    regex.lastIndex = 0;
+    if (!regex.test(query)) continue;
+    // Prefer the most recent focus entity; never invent one when no candidate exists.
+    const resolved = candidates.length > 0 ? candidates[0] : null;
+    references.push({ pronoun, resolved, candidates: candidates.slice(0, 5) });
+    if (resolved !== null && !terms.includes(resolved)) terms.push(resolved);
+    if (resolved === null) unresolved.push(pronoun);
+  }
+  return { schema: ANAPHORA_SCHEMA, references, terms, unresolved };
+}
+
+/** Append resolved referents to the query (no-op when nothing resolved). */
+export function expandQueryWithAnaphora(queryText, resolution) {
+  const terms = Array.isArray(resolution?.terms) ? resolution.terms : [];
+  const base = String(queryText ?? '');
+  const fresh = terms.filter((term) => !base.includes(term));
+  return { text: fresh.length === 0 ? base : `${base} ${fresh.join(' ')}`, changed: fresh.length > 0, terms: fresh };
+}

package/src/recall/cards.mjs

@@ -138,6 +138,13 @@ export function parseCard(raw, relPath) {
     salience: typeof data.salience === 'number' ? data.salience : null,
     strength: typeof data.strength === 'number' ? data.strength : null,
     date: typeof data.date === 'string' ? data.date : null,
+    // A3 trust ranking hints (only when authored; absent => neutral weight)
+    ...(typeof data.source_tier === 'string' ? { sourceTier: data.source_tier } : {}),
+    ...(typeof data.sourceTier === 'string' ? { sourceTier: data.sourceTier } : {}),
+    ...(typeof data.trust_score === 'number' ? { trustScore: data.trust_score } : {}),
+    ...(typeof data.trustScore === 'number' ? { trustScore: data.trustScore } : {}),
+    ...(typeof data.verify_count === 'number' ? { verifyCount: data.verify_count } : {}),
+    ...(typeof data.last_used === 'string' ? { lastUsed: data.last_used } : {}),
     localOnly,
     hasFrontmatter,
     warnings,

package/src/recall/embedding.mjs

@@ -28,7 +28,7 @@ import path from 'node:path';
 export const EMBEDDING_VERSION = 1;
 
 export const EMBEDDING_DEFAULTS = Object.freeze({
-  enabled: false,
+  enabled: true,
   modelPath: '',
   maxSeqLen: 256,
   queryInstruction: '为这个句子生成表示以用于检索相关文章：',
@@ -67,7 +67,7 @@ function text(value) {
  */
 export function normalizeEmbeddingConfig(input, { memoryRoot = null } = {}) {
   const value = input && typeof input === 'object' ? input : {};
-  const enabled = bool(value.enabled);
+  const enabled = value.enabled !== false;
   const modelPath = text(value.modelPath);
   const cacheDirRaw = text(value.cacheDir);
   const cacheDir = cacheDirRaw
@@ -625,7 +625,7 @@ export async function buildVectorIndex({ cards, config, embedder, cachePath }) {
 export function createEmbeddingRuntime(input, { memoryRoot = null, warn = null } = {}) {
   const config = normalizeEmbeddingConfig(input, { memoryRoot });
   const cachePath = config.cacheDir ? path.join(config.cacheDir, 'index.json') : '';
-  let state = null; // {ok, embedder, vectors, stats} | {ok:false, code, message}
+  let state = null; // {ok, embedder, vectors, stats, signature} | {ok:false, code, message}
   let loading = null;
 
   const load = async (cards) => {
@@ -653,16 +653,16 @@ export function createEmbeddingRuntime(input, { memoryRoot = null, warn = null }
     get enabled() {
       return config.enabled;
     },
-    /** Build/refresh once; later calls reuse the in-memory index. */
-    async ensure(cards, { refresh = false } = {}) {
-      if (state?.ok && !refresh) return state;
+    /** Build/refresh once; a changed card signature rebuilds the in-memory index. */
+    async ensure(cards, { refresh = false, signature = undefined } = {}) {
+      if (state?.ok && !refresh && (signature === undefined || signature === state.signature)) return state;
       if (loading) return loading;
       loading = load(cards).then((value) => {
-        state = value;
+        state = { ...value, signature };
         if (!value.ok && typeof warn === 'function') {
           warn(`[embedding] ${value.code}: ${value.message} — 回退关键词召回`);
         }
-        return value;
+        return state;
       }).finally(() => {
         loading = null;
       });

package/src/recall/entities.mjs

@@ -0,0 +1,112 @@
+// src/recall/entities.mjs — B2：实体别名表（`.longlive/entities/entities.jsonl`）
+//
+// 字段：{schema:'entities/v1', canonical, aliases[], kind, at}
+// 只读路径给召回查询扩展用；写入口只允许宿主传入（本模块不做权限门，由调用方保证）。
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ENTITIES_SCHEMA = 'entities/v1';
+
+export function entitiesPathOf(memoryRoot) {
+  return path.join(path.resolve(String(memoryRoot ?? '')), '.longlive', 'entities', 'entities.jsonl');
+}
+
+function nowIso(now) {
+  const value = typeof now === 'function' ? now() : new Date();
+  return (value instanceof Date ? value : new Date(value)).toISOString();
+}
+
+/** Read alias registry (append-only; later rows add aliases). Missing file => empty map. */
+export function readEntityAliases({ memoryRoot }) {
+  const file = entitiesPathOf(memoryRoot);
+  const byCanonical = new Map();
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { present: false, file, aliases: {}, byCanonical: {}, badLines: 0 };
+  }
+  let bad = 0;
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      bad += 1;
+      continue;
+    }
+    const canonical = typeof row?.canonical === 'string' ? row.canonical.trim() : '';
+    if (canonical === '') continue;
+    const aliases = Array.isArray(row.aliases) ? row.aliases.map((a) => String(a).trim()).filter(Boolean) : [];
+    const prev = byCanonical.get(canonical) ?? { canonical, aliases: new Set([canonical]), kind: row.kind ?? null };
+    for (const alias of aliases) prev.aliases.add(alias);
+    byCanonical.set(canonical, prev);
+  }
+  const aliases = {};
+  for (const [canonical, entry] of byCanonical) aliases[canonical] = [...entry.aliases];
+  return { present: true, file, aliases, byCanonical, badLines: bad };
+}
+
+/** Append one entity alias row (host/panel write path). Idempotent per canonical+alias set. */
+export function appendEntityAlias({ memoryRoot, canonical, aliases = [], kind = null, now = () => new Date() }) {
+  const name = typeof canonical === 'string' ? canonical.trim() : '';
+  if (name === '') {
+    const error = new Error('E_ENTITY_CANONICAL_REQUIRED: canonical 不能为空');
+    error.code = 'E_ENTITY_CANONICAL_REQUIRED';
+    throw error;
+  }
+  const list = [...new Set([name, ...(Array.isArray(aliases) ? aliases : [])].map((a) => String(a).trim()).filter(Boolean))];
+  const file = entitiesPathOf(memoryRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const row = { schema: ENTITIES_SCHEMA, canonical: name, aliases: list, kind: kind ?? null, at: nowIso(now) };
+  fs.appendFileSync(file, `${JSON.stringify(row)}\n`, 'utf8');
+  return { ok: true, file, row };
+}
+
+/** Find canonical entities mentioned in `text` (longest alias first). */
+export function resolveEntityAliases(text, aliasMap, { max = 20 } = {}) {
+  const value = typeof text === 'string' ? text : '';
+  const matches = [];
+  const entries = [];
+  for (const [canonical, aliases] of Object.entries(aliasMap ?? {})) {
+    for (const alias of new Set([canonical, ...(Array.isArray(aliases) ? aliases : [])])) {
+      if (typeof alias !== 'string' || alias.trim() === '') continue;
+      entries.push({ canonical, alias });
+    }
+  }
+  entries.sort((a, b) => b.alias.length - a.alias.length || a.alias.localeCompare(b.alias));
+  const usedRanges = [];
+  for (const entry of entries) {
+    let from = 0;
+    while (matches.length < max) {
+      const index = value.indexOf(entry.alias, from);
+      if (index === -1) break;
+      from = index + entry.alias.length;
+      const end = index + entry.alias.length;
+      if (usedRanges.some((range) => index < range.end && end > range.start)) continue;
+      usedRanges.push({ start: index, end });
+      matches.push({ canonical: entry.canonical, alias: entry.alias, index });
+    }
+  }
+  matches.sort((a, b) => a.index - b.index);
+  return {
+    terms: [...new Set(matches.map((match) => match.canonical))],
+    matches,
+  };
+}
+
+/** Deterministic expansion text: canonical names appended once. */
+export function expandQueryWithEntities(queryText, resolution) {
+  const terms = Array.isArray(resolution?.terms) ? resolution.terms : [];
+  if (terms.length === 0) return { text: String(queryText ?? ''), changed: false, terms };
+  const base = String(queryText ?? '');
+  const tail = terms.filter((term) => !base.includes(term)).join(' ');
+  return { text: tail === '' ? base : `${base} ${tail}`, changed: tail !== '', terms };
+}
+
+export function entityAliasDigest(aliasMap) {
+  return crypto.createHash('sha1').update(JSON.stringify(aliasMap ?? {})).digest('hex').slice(0, 12);
+}