@ilaomianyang/dsh-memory-graph 0.10.3 → 0.11.0

package/src/extract.js

@@ -121,7 +121,13 @@ function extractJson(text) {
 
 export function parseCards(text) {
   const parsed = extractJson(text)
-  if (parsed === null) return { cards: [], skipped: 'model output was not JSON', raw: String(text ?? '').slice(0, 600) }
+  if (parsed === null) {
+    return {
+      cards: [],
+      skipped: '模型输出不是 JSON · model output was not JSON',
+      raw: String(text ?? '').slice(0, 600),
+    }
+  }
   const list = Array.isArray(parsed) ? parsed : Array.isArray(parsed.cards) ? parsed.cards : []
   const cards = []
   for (const raw of list) {
@@ -253,14 +259,16 @@ export function resolveRoute(cfg, selection) {
   if (!useCurrentModel) {
     if (!provider || !model) {
       throw new Error(
-        'extractor.useCurrentModel is off, so extractor.provider and extractor.model are both required.',
+        '关掉了 extractor.useCurrentModel，所以 extractor.provider 和 extractor.model 都必须填 · extractor.useCurrentModel is off, so extractor.provider and extractor.model are both required.',
       )
     }
     return { provider, model, effort: reasoningEffort, source: 'config extractor.provider/model' }
   }
   if (!selection?.provider || !selection?.model) {
     throw new Error(
-      'No model is selected in Settings → Models, so the extractor has no route to borrow. ' +
+      '设置 → 模型里没有选中任何模型，所以抽取器没有可借用的路由。' +
+        '在那里选一个模型，或者填好 extractor.provider 和 extractor.model 再把 extractor.useCurrentModel 关掉 · ' +
+        'No model is selected in Settings → Models, so the extractor has no route to borrow. ' +
         'Pick a model there, or set extractor.provider and extractor.model and turn extractor.useCurrentModel off.',
     )
   }
@@ -270,7 +278,7 @@ export function resolveRoute(cfg, selection) {
     // An explicit setting wins, so a big thinking budget can be reserved for
     // distillation without changing the model the conversation itself uses.
     effort: reasoningEffort || selectionEffort(selection),
-    source: 'Settings → Models selection',
+    source: '设置 → 模型里选中的路由 · Settings → Models selection',
   }
 }
 
@@ -293,7 +301,7 @@ function splitMessages(messages) {
 async function callHarnessModel(cfg, messages, { signal, llm, selection } = {}) {
   if (!llm || typeof llm.prepareCall !== 'function') {
     throw new Error(
-      'This harness build exposes no llm service to plugins, so set extractor.transport = "http" to post to an endpoint directly.',
+      '这个 harness 版本没有把 llm 服务暴露给插件，所以请把 extractor.transport 设成 "http"，直接向接口发请求 · This harness build exposes no llm service to plugins, so set extractor.transport = "http" to post to an endpoint directly.',
     )
   }
   const route = resolveRoute(cfg, selection)
@@ -339,26 +347,33 @@ async function callHarnessModel(cfg, messages, { signal, llm, selection } = {})
       if (controller.signal.aborted) {
         // Either the caller cancelled us or our own timer fired; say which,
         // because the fix is different (wait longer vs. run less work).
-        const why = signal?.aborted
+        const whyZh = signal?.aborted ? '在路由应答之前就被取消了' : `超时了 ${cfg.extractor.timeoutMs} ms`
+        const whyEn = signal?.aborted
           ? 'was cancelled before the route answered'
           : `timed out after ${cfg.extractor.timeoutMs} ms`
         throw new Error(
-          `Extractor call to ${route.provider}/${route.model} ${why}; raise extractor.timeoutMs or distill fewer episodes per run.`,
+          `抽取器调用 ${route.provider}/${route.model} 时${whyZh}；可以调大 extractor.timeoutMs，或者每次少蒸馏几条情节 · ` +
+            `Extractor call to ${route.provider}/${route.model} ${whyEn}; raise extractor.timeoutMs or distill fewer episodes per run.`,
         )
       }
       throw new Error(
-        `Extractor call failed on ${route.provider}/${route.model} (${failure.code ?? kind}): ${failure.message ?? 'the route ended the stream without a reason'}`,
+        `抽取器调用 ${route.provider}/${route.model} 失败（${failure.code ?? kind}）：${failure.message ?? '路由结束了流但没给原因'} · ` +
+          `Extractor call failed on ${route.provider}/${route.model} (${failure.code ?? kind}): ${failure.message ?? 'the route ended the stream without a reason'}`,
       )
     }
     if (kind === 'tool-calls') {
-      throw new Error('Extractor answered with a tool call instead of JSON. Try a different model for distillation.')
+      throw new Error(
+        '抽取器返回的是工具调用而不是 JSON，蒸馏时换一个模型试试 · Extractor answered with a tool call instead of JSON. Try a different model for distillation.',
+      )
     }
     if (kind === 'max-tokens') {
       throw truncated(
-        `Extractor output reached maxOutputTokens (${cfg.extractor.maxOutputTokens}); raise it or distill fewer episodes per run.`,
+        `抽取器输出撞到了 maxOutputTokens 上限（${cfg.extractor.maxOutputTokens}）；把它调大，或者每次少蒸馏几条情节 · Extractor output reached maxOutputTokens (${cfg.extractor.maxOutputTokens}); raise it or distill fewer episodes per run.`,
       )
     }
-    if (text.trim() === '') throw new Error('Extractor returned an empty completion.')
+    if (text.trim() === '') {
+      throw new Error('抽取器返回了空回复 · Extractor returned an empty completion.')
+    }
     return {
       content: text,
       usage,
@@ -377,7 +392,7 @@ export async function callHttpModel(cfg, messages, { signal } = {}) {
   if (key === '') {
     const where = looked.length > 0 ? looked.join(' or ') : 'config extractor.apiKey'
     throw new Error(
-      `No API key for the extractor. Looked in ${where}. Set the env var, add the name to the harness credential store, or set config extractor.apiKey.`,
+      `抽取器没有可用的 API key，找过这些地方：${where}。请设置该环境变量、把名字加进 harness 的凭据库，或者直接填 config extractor.apiKey · No API key for the extractor. Looked in ${where}. Set the env var, add the name to the harness credential store, or set config extractor.apiKey.`,
     )
   }
   const url = `${cfg.extractor.baseUrl}${cfg.extractor.path}`
@@ -406,13 +421,17 @@ export async function callHttpModel(cfg, messages, { signal } = {}) {
       text = await response.text()
     }
     if (!response.ok) {
-      throw new Error(`Extractor HTTP ${response.status} from ${url}: ${text.slice(0, 400)}`)
+      throw new Error(
+        `抽取器请求 ${url} 返回 HTTP ${response.status}：${text.slice(0, 400)} · Extractor HTTP ${response.status} from ${url}: ${text.slice(0, 400)}`,
+      )
     }
     let data
     try {
       data = JSON.parse(text)
     } catch {
-      throw new Error(`Extractor returned non-JSON response: ${text.slice(0, 300)}`)
+      throw new Error(
+        `抽取器返回的不是 JSON：${text.slice(0, 300)} · Extractor returned non-JSON response: ${text.slice(0, 300)}`,
+      )
     }
     const content =
       data?.choices?.[0]?.message?.content ?? data?.choices?.[0]?.text ?? data?.output_text ?? ''
@@ -420,11 +439,11 @@ export async function callHttpModel(cfg, messages, { signal } = {}) {
       // Same situation as the harness route's max-tokens finish: the answer is
       // cut off mid-JSON, so ask for less instead of blaming the parser.
       throw truncated(
-        `Extractor output reached maxOutputTokens (${cfg.extractor.maxOutputTokens}); raise it or distill fewer episodes per run.`,
+        `抽取器输出撞到了 maxOutputTokens 上限（${cfg.extractor.maxOutputTokens}）；把它调大，或者每次少蒸馏几条情节 · Extractor output reached maxOutputTokens (${cfg.extractor.maxOutputTokens}); raise it or distill fewer episodes per run.`,
       )
     }
     if (typeof content !== 'string' || content.trim() === '') {
-      throw new Error('Extractor returned an empty completion.')
+      throw new Error('抽取器返回了空回复 · Extractor returned an empty completion.')
     }
     return { content, usage: data?.usage ?? null, model: data?.model ?? cfg.extractor.model, keySource: source }
   } finally {
@@ -496,13 +515,18 @@ export async function distill({ cfg, vault, redactor, project, dryRun = false, s
     return {
       ok: false,
       reason:
-        'Extractor is disabled. Set config extractor.enabled = true; the default transport reuses the model selected in Settings → Models.',
+        '抽取器没有启用。请把 config extractor.enabled 设成 true；默认传输方式会复用「设置 → 模型」里选中的模型 · Extractor is disabled. Set config extractor.enabled = true; the default transport reuses the model selected in Settings → Models.',
     }
   }
 
   const entries = await vault.readUndistilled(cfg.extractor.maxEpisodesPerRun)
   if (entries.length === 0) {
-    return { ok: true, episodes: 0, written: 0, reason: 'Every episode has already been distilled.' }
+    return {
+      ok: true,
+      episodes: 0,
+      written: 0,
+      reason: '所有情节都已经蒸馏过了 · Every episode has already been distilled.',
+    }
   }
 
   const known = await vault.listCards({ includeRetracted: true })

package/src/graph.js

@@ -143,7 +143,7 @@ function buildModel({ cards, entities, projects }) {
       key: `c:${card.id}`,
       type: 'card',
       kind: String(card.kind ?? 'note'),
-      label: String(card.title ?? '(untitled)'),
+      label: String(card.title ?? '（无标题 untitled）'),
       id: card.id,
       project: card.project ?? 'shared',
       status: card.status ?? 'active',
@@ -843,7 +843,7 @@ const BODY = `
         <button id="theme" title="主题：跟随系统 / 深色 / 浅色">◐</button>
         <button id="zoom-in" title="放大">+</button>
         <button id="zoom-out" title="缩小">−</button>
-        <button id="zoom-fit" title="复位 (f)">fit</button>
+        <button id="zoom-fit" title="复位 (f)">复位</button>
       </div>
     </div>
   </header>
@@ -907,6 +907,11 @@ function clientScript(dataJson) {
   var selected = null;
   var view = { k: 1, x: 0, y: 0 };
   var GRADIENT_KINDS = ['decision', 'fact', 'open_question', 'preference', 'note', 'entity'];
+  var CONFIDENCE_LABELS = {
+    user_stated: '用户明说 user_stated',
+    verified: '已验证 verified',
+    inferred: '推断 inferred'
+  };
 
   /* ------------------------------------------------------------ theme */
 
@@ -1167,7 +1172,7 @@ function clientScript(dataJson) {
     if (node.type === 'entity') {
       var cards = Object.keys(neighbors[node.key]).filter(function (key) { return key.indexOf('c:') === 0; });
       tooltip.appendChild(h('div', 'tt-snip', cards.length + ' 张卡片 · ' + (node.projects.length ? node.projects.join(' / ') : '未归档')));
-      tooltip.appendChild(h('div', 'tt-meta', 'first ' + (node.firstSeen || '—') + ' · last ' + (node.lastSeen || '—')));
+      tooltip.appendChild(h('div', 'tt-meta', '首次 ' + (node.firstSeen || '—') + ' · 最近 ' + (node.lastSeen || '—')));
     } else {
       if (node.snippet) tooltip.appendChild(h('div', 'tt-snip', node.snippet));
       tooltip.appendChild(h('div', 'tt-meta', node.id + ' · ' + node.project + ' · ' + node.created));
@@ -1273,7 +1278,7 @@ function clientScript(dataJson) {
     if (node.status !== 'active') {
       badges.appendChild(badge('warn', node.status === 'superseded' ? '已替换 superseded' : '已撤回 retracted', true));
     }
-    badges.appendChild(badge('plain', node.confidence, true));
+    badges.appendChild(badge('plain', CONFIDENCE_LABELS[node.confidence] || node.confidence, true));
     panel.appendChild(badges);
 
     var meta = h('dl');
@@ -1560,7 +1565,7 @@ export function renderGraphHtml({ cards = [], entities = [], projects = [], gene
     generatedAt: generatedAt || stamp(),
   })
   const dataJson = escapeForScript(JSON.stringify(payload))
-  const title = `记忆图 · ${payload.counts.cards} cards / ${payload.counts.entities} entities`
+  const title = `记忆图 · ${payload.counts.cards} 张卡片 / ${payload.counts.entities} 个实体`
 
   return `<!doctype html>
 <html lang="zh-CN">

package/src/graphdata.js

@@ -462,7 +462,16 @@ export function createGraphHandler({ getVault, getConfig }) {
   return async function handle(request) {
     const url = new URL(request.url)
     const session = url.searchParams.get('session') ?? ''
-    if (session === '') return json({ ok: false, reason: 'missing-session' }, 400)
+    if (session === '') {
+      return json(
+        {
+          ok: false,
+          reason: 'missing-session',
+          message: '这个会话没有 id，画不出它的记忆图 · this session has no id, so there is no graph to draw',
+        },
+        400,
+      )
+    }
     try {
       const cfg = getConfig()
       const vault = getVault()

package/src/history.js

@@ -0,0 +1,440 @@
+/**
+ * History: read the sessions that ran before this plugin existed.
+ *
+ * Capture only sees turns that arrive while the host is running, so a vault
+ * installed today starts empty and the person's past is not in it. The harness
+ * keeps every closed session on disk as `session.v4.jsonl.zstd`; this module
+ * replays those files through the same turn assembler the live listener uses, so
+ * a backfilled episode and a captured one are the same kind of record.
+ *
+ * Two things make it safe to run twice:
+ *   - a turn is identified by `(session, turn)`, and turns already in the vault
+ *     are skipped, so re-running after a session grew imports only the new part;
+ *   - the timestamps come from the session file, not from now, so history lands
+ *     in the right place on the timeline instead of piling up under today.
+ */
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import zlib from 'node:zlib'
+import { Decompress } from 'fzstd'
+
+import { createTurnAssembler, projectOf } from './turns.js'
+
+const SESSION_FILE = 'session.v4.jsonl.zstd'
+/** zstd in, JSON out: a cap so one enormous session cannot pin the process. */
+export const DEFAULT_MAX_BYTES = 512 * 1024 * 1024
+/** No single event is this large; a longer line means the stream is corrupt. */
+const MAX_LINE = 4 * 1024 * 1024
+
+/**
+ * A session file is not one zstd frame: the writer appends one frame per batch,
+ * so the file is a *concatenated container*. Both decoders that matter — Node's
+ * and fzstd's — stop at a frame boundary, which is why the raw walk of these
+ * files used to yield a single header line and nothing else.
+ *
+ * Node grew a zstd codec in 22.15 / 23.8 and decodes frames with full fidelity;
+ * the pure-JS fallback below refuses some high-accuracy FSE tables that real
+ * session files here do contain ("FSE accuracy too high"). A plugin cannot choose
+ * the runtime it lands in, so both paths exist and the report names the one that
+ * ran.
+ */
+const ZSTD_MAGIC = 0xfd2fb528
+const hasNativeZstd = typeof zlib.zstdDecompressSync === 'function'
+export const decoderKind = hasNativeZstd ? 'node-zstd' : 'fzstd'
+
+export function defaultSessionsDir() {
+  const home = process.env.DSH_HOME
+  if (typeof home === 'string' && home.trim() !== '') return path.join(home.trim(), 'sessions')
+  return path.join(os.homedir(), '.dsh', 'sessions')
+}
+
+/** The profile's session store: every closed session, newest modified first. */
+export async function listSessions(dir) {
+  const out = []
+  let groups = []
+  try {
+    groups = await fsp.readdir(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const group of groups) {
+    if (!group.isDirectory()) continue
+    const groupDir = path.join(dir, group.name)
+    let entries = []
+    try {
+      entries = await fsp.readdir(groupDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const file = path.join(groupDir, entry.name, SESSION_FILE)
+      try {
+        const stat = await fsp.stat(file)
+        if (!stat.isFile()) continue
+        out.push({ file, size: stat.size, mtimeMs: stat.mtimeMs, group: group.name, dirName: entry.name })
+      } catch {
+        // A session directory without a log: the turn never produced anything.
+      }
+    }
+  }
+  // Newest first: with a limit, the recent past is what a person wants back.
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  return out
+}
+
+/**
+ * Cut the inflated byte stream into lines, with a ceiling on how much of one
+ * session is read at all.
+ *
+ * A session log is tens of megabytes compressed and hundreds as text, and a
+ * backfill walks a hundred of them: nothing here holds the whole plaintext.
+ */
+function lineCutter(onLine, { maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  let inflated = 0
+  let pending = ''
+  let stopped = false
+  let partial = false
+  return {
+    push(chunk) {
+      if (stopped || chunk.length === 0) return
+      inflated += chunk.length
+      pending += chunk.toString('utf8')
+      let cut = pending.indexOf('\n')
+      while (cut !== -1) {
+        const line = pending.slice(0, cut)
+        pending = pending.slice(cut + 1)
+        if (line.trim() !== '') onLine(line)
+        cut = pending.indexOf('\n')
+      }
+      if (pending.length > MAX_LINE || inflated > maxBytes) {
+        stopped = true
+        pending = ''
+      }
+    },
+    end() {
+      if (!stopped && pending.trim() !== '') onLine(pending)
+      pending = ''
+    },
+    /** The caller stopped early — a byte ceiling, not a corrupt file. */
+    markPartial() {
+      partial = true
+    },
+    get stopped() {
+      return stopped
+    },
+    get truncated() {
+      return stopped || partial
+    },
+    get inflated() {
+      return inflated
+    },
+  }
+}
+
+/**
+ * Frame boundaries, without decompressing: a correctness port of the scanner the
+ * harness itself uses for these files (zstd frame header, then 3-byte block
+ * headers, then an optional 4-byte checksum). A partial trailing frame is the
+ * normal state of a session that is still being written; its start is returned
+ * so the caller can ignore it rather than call it corruption.
+ */
+export function scanFrames(buffer) {
+  const frames = []
+  let offset = 0
+  while (offset < buffer.length) {
+    const start = offset
+    const torn = () => ({ frames, tornStart: start })
+    if (buffer.length - offset < 4) return torn()
+    if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) return torn()
+    offset += 4
+    if (offset === buffer.length) return torn()
+
+    const descriptor = buffer.readUInt8(offset)
+    offset += 1
+    // Reserved bits, or a window with no content size where one is required:
+    // reason enough to stop trusting the rest of the file.
+    if ((descriptor & 0b00011000) !== 0) return torn()
+    const contentSizeFlag = descriptor >>> 6
+    const singleSegment = (descriptor & 0b00100000) !== 0
+    const checksumFlag = (descriptor & 0b00000100) !== 0
+    const dictionaryFlag = descriptor & 0b11
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag
+    const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes
+    if (buffer.length - offset < remainingHeaderBytes) return torn()
+    offset += remainingHeaderBytes
+
+    for (;;) {
+      if (buffer.length - offset < 3) return torn()
+      const blockHeader = buffer.readUIntLE(offset, 3)
+      offset += 3
+      const lastBlock = (blockHeader & 1) !== 0
+      const blockType = (blockHeader >>> 1) & 0b11
+      const blockSize = blockHeader >>> 3
+      if (blockType === 3) return torn() // reserved block type
+      const payloadBytes = blockType === 1 ? 1 : blockSize // RLE blocks carry one byte
+      if (buffer.length - offset < payloadBytes) return torn()
+      offset += payloadBytes
+      if (lastBlock) break
+    }
+
+    if (checksumFlag) {
+      if (buffer.length - offset < 4) return torn()
+      offset += 4
+    }
+    frames.push({ start, end: offset })
+  }
+  return { frames }
+}
+
+async function readBytes(file, { maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  const handle = await fsp.open(file, 'r')
+  try {
+    const { size } = await handle.stat()
+    const want = Math.max(0, Math.min(size, maxBytes))
+    const buffer = Buffer.allocUnsafe(want)
+    let read = 0
+    while (read < want) {
+      const { bytesRead } = await handle.read(buffer, read, want - read, read)
+      if (bytesRead === 0) break
+      read += bytesRead
+    }
+    return { buffer: buffer.subarray(0, read), size, partial: want < size }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** The reference decoder: every frame zstd can produce, one frame at a time. */
+async function readLinesNative(file, onLine, options) {
+  const cutter = lineCutter(onLine, options)
+  const { buffer, partial } = await readBytes(file, options)
+  if (partial) cutter.markPartial()
+
+  let torn = false
+  let failed = 0
+  for (const { start, end } of scanFrames(buffer).frames) {
+    let plain
+    try {
+      plain = zlib.zstdDecompressSync(buffer.subarray(start, end))
+    } catch {
+      // One frame the codec refuses (a truncated append after a crash) should
+      // cost that batch, not the session.
+      failed += 1
+      continue
+    }
+    cutter.push(plain)
+    if (cutter.stopped) break
+  }
+  torn = failed > 0
+  cutter.end()
+  if (torn && cutter.inflated === 0) throw new Error('这个会话文件里没有可解码的 zstd 帧')
+  return cutter
+}
+
+/** The fallback for a Node without a zstd codec: pure JS, most frames. */
+async function readLinesFallback(file, onLine, options) {
+  const cutter = lineCutter(onLine, options)
+  const decoder = new Decompress((chunk) => cutter.push(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)))
+  const { buffer, partial } = await readBytes(file, options)
+  if (partial) cutter.markPartial()
+  decoder.push(new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength), true)
+  cutter.end()
+  return cutter
+}
+
+async function readLines(file, onLine, options) {
+  return hasNativeZstd ? readLinesNative(file, onLine, options) : readLinesFallback(file, onLine, options)
+}
+
+/** Every `(session, turn)` the vault already has, so a re-run imports nothing twice. */
+export async function existingTurns(vault) {
+  const seen = new Set()
+  let files = []
+  try {
+    files = typeof vault.episodeFiles === 'function' ? await vault.episodeFiles() : []
+  } catch {
+    return seen
+  }
+  const dir = vault.paths?.episodes
+  if (typeof dir !== 'string') return seen
+  for (const name of files) {
+    let text = ''
+    try {
+      text = await fsp.readFile(path.join(dir, name), 'utf8')
+    } catch {
+      continue
+    }
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue
+      try {
+        const record = JSON.parse(line)
+        if (typeof record?.session === 'string') seen.add(`${record.session}#${record.turn ?? ''}`)
+      } catch {
+        // A half-written last line from a crash; the next run sees it whole.
+      }
+    }
+  }
+  return seen
+}
+
+/**
+ * One replayed session, fed a line at a time.
+ *
+ * Kept separate from the file reading so the filter, the dedupe and the
+ * timestamps can be tested on hand-written events — the part that matters is the
+ * policy, not the decompressor.
+ */
+export function createReplay({ sessionId = '', project = '', cfg, redactor, seen }) {
+  const assembler = createTurnAssembler({ cfg, redactor })
+  const episodes = []
+  let id = sessionId
+  let cwd = ''
+  let closedTurns = 0
+  let duplicates = 0
+  let malformed = 0
+
+  const keep = (episode) => {
+    const key = `${episode.session}#${episode.turn ?? ''}`
+    if (seen.has(key)) {
+      duplicates += 1
+      return
+    }
+    seen.add(key)
+    episodes.push(episode)
+  }
+
+  return {
+    feed(line) {
+      let event
+      try {
+        event = JSON.parse(line)
+      } catch {
+        malformed += 1
+        return
+      }
+      if (event?.type === 'session') {
+        if (typeof event.id === 'string' && event.id !== '') id = event.id
+        if (typeof event.cwd === 'string') cwd = event.cwd
+        return
+      }
+      if (event?.type === 'turn/end') closedTurns += 1
+      for (const episode of assembler.push({
+        sessionId: id,
+        project: projectOf({ cwd }, cfg.defaultProject),
+        event,
+      })) {
+        keep(episode)
+      }
+    },
+
+    /** A session whose last turn never closed still holds a real message. */
+    finish() {
+      for (const episode of assembler.flushAll()) keep(episode)
+      return {
+        id,
+        project: projectOf({ cwd }, cfg.defaultProject),
+        cwd,
+        closedTurns,
+        episodes,
+        duplicates,
+        malformed,
+      }
+    },
+  }
+}
+
+/** Replay one session file, then write what the vault does not have. */
+export async function importSession({ entry, cfg, vault, redactor, seen, dryRun = false, maxBytes, collect = null }) {
+  const replay = createReplay({ sessionId: entry.dirName, cfg, redactor, seen })
+  let failure = null
+  let inflated = 0
+  let truncated = false
+  try {
+    const cutter = await readLines(entry.file, (line) => replay.feed(line), { maxBytes })
+    inflated = cutter.inflated
+    truncated = cutter.truncated
+  } catch (error) {
+    // One unreadable file must not end a backfill that has hundreds of others:
+    // the report says which one failed and the run carries on.
+    failure = error?.message ?? String(error)
+  }
+
+  const report = replay.finish()
+
+  if (Array.isArray(collect)) collect.push(...report.episodes)
+  if (!dryRun) {
+    for (const episode of report.episodes) await vault.appendEpisode(episode)
+  }
+
+  return {
+    ...report,
+    episodes: report.episodes.length,
+    truncated,
+    failure,
+    inflated,
+    file: entry.file,
+    size: entry.size,
+  }
+}
+
+/**
+ * Walk the store, newest session first, and import what the vault does not have.
+ *
+ * Returns a report rather than logging: the tool formats it, the tests assert on
+ * it, and a person reads the same numbers.
+ */
+export async function runBackfill({
+  cfg,
+  vault,
+  redactor,
+  dir = defaultSessionsDir(),
+  limit = 0,
+  dryRun = false,
+  maxBytes = DEFAULT_MAX_BYTES,
+  onProgress = null,
+  collect = null,
+}) {
+  const started = Date.now()
+  const seen = await existingTurns(vault)
+  const all = await listSessions(dir)
+  const selected = limit > 0 ? all.slice(0, limit) : all
+
+  const sessions = []
+  let imported = 0
+  let duplicates = 0
+  let budget = maxBytes
+  let exhausted = false
+
+  for (const entry of selected) {
+    if (budget <= 0) {
+      exhausted = true
+      break
+    }
+    const report = await importSession({ entry, cfg, vault, redactor, seen, dryRun, maxBytes: budget, collect })
+    budget -= entry.size
+    imported += report.episodes
+    duplicates += report.duplicates
+    sessions.push(report)
+    onProgress?.(report)
+  }
+
+  return {
+    dir,
+    dryRun,
+    decoder: decoderKind,
+    found: all.length,
+    scanned: sessions.length,
+    imported,
+    duplicates,
+    exhausted,
+    malformed: sessions.reduce((n, s) => n + s.malformed, 0),
+    failed: sessions.filter((s) => s.failure !== null).length,
+    ms: Date.now() - started,
+    sessions: sessions
+      .filter((s) => s.episodes > 0 || s.duplicates > 0 || s.closedTurns > 0 || s.failure !== null)
+      .sort((a, b) => b.episodes - a.episodes),
+  }
+}

package/src/pageapi.js

@@ -22,14 +22,14 @@ function failure(error) {
 <style>body{font:14px/1.6 system-ui,sans-serif;margin:0;display:grid;place-items:center;height:100vh;color:#333}
 main{max-width:34rem;padding:2rem}code{background:#f4f4f5;padding:.1rem .3rem;border-radius:4px}</style>
 <main><h1>记忆图没能画出来</h1><p><code>${escaped}</code></p>
-<p>The graph could not be rendered. The vault is still on disk; nothing was written.</p></main></html>`
+<p>图谱渲染失败了，但记忆库还在磁盘上，什么都没写 · The graph could not be rendered. The vault is still on disk; nothing was written.</p></main></html>`
 }
 
 export function createPageHandler({ getVault }) {
   return async function fetch() {
     const vault = getVault()
     if (!vault || typeof vault.graphPage !== 'function') {
-      return html(failure(new Error('vault unavailable')), 500)
+      return html(failure(new Error('记忆库不可用 · vault unavailable')), 500)
     }
     try {
       return html(await vault.graphPage())