@nightpainters/dsh-ling 1.5.1

package/lib/host/archive.js

@@ -0,0 +1,194 @@
+// dsh-ling host — 改动前的归档落盘(Part G · G2,2026-09-25)
+//
+// **原则(用户定):永远不做彻底删除。**
+// 任何"清除/覆盖"类的操作,动手之前先把原数据**完整写到磁盘上的历史目录**,并附一份
+// 人可读的改动日志 —— 谁、什么时候、为什么、以及怎么还原。
+//
+// 为什么单独成模块:遗忘与回灌是这套系统里仅有的两个"会让人后悔"的操作。
+// 库内标记(`forgotten` 表)与磁盘归档是**两条独立的还原路径**:库里没删行,所以撤销标记即可;
+// 就算库没了,归档文件还在。任何一条断了都还有另一条。
+
+import { writeFileSync, mkdirSync, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/** 本地时间戳(目录名用;不用 toISOString —— 那是 UTC,会和主人的钟差 8 小时)。 */
+function localStamp(d = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/** 人看的时间(写进日志)。 */
+function humanTime(d = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+/** 短 id(目录名用;完整 id 太长,而归档目录要能一眼看出对应哪一条)。 */
+function shortId(s) {
+  return String(s || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 12) || 'unknown';
+}
+
+/** 归档根目录:与 memory.db 同级,便于整体搬走/备份。 */
+export function archiveRootOf(memory) {
+  const dbPath = String(memory?.dbPath || '');
+  const base = dbPath ? dirname(dbPath) : '.';
+  return join(base, 'forgotten');
+}
+
+/**
+ * 把一条记忆的**全部数据**归档落盘。
+ *
+ * @param {object} memory  MemoryStore(需要 exportEntry / dbPath)
+ * @param {object} opts
+ * @param {string} opts.source    来源域(dsh / dsweb / import)
+ * @param {string} opts.convId    条目 id
+ * @param {string} opts.kind      'forget' | 'backfill'(决定目录前缀与日志措辞)
+ * @param {string} opts.reason    为什么动它(人写的话)
+ * @param {string} opts.actor     'user' | 'ling'
+ * @returns {{ok:boolean, dir?:string, turns?:number, empty?:boolean, isForget?:boolean, reason?:string, message?:string}}
+ *   `ok:true` 只代表"文件写下去了";**`empty:true` 代表这份归档什么都没保住**(0 轮原文 + 无正文
+ *   + 无会话元数据)。会"按归档放行"的破坏性调用方(forget 那种 fail-closed 纪律)必须同时看
+ *   `ok && !empty` —— 否则空归档会把"没有备份"伪装成"备份好了"(B-05)。
+ */
+export function archiveBefore(memory, { source, convId, kind = 'forget', reason = '', actor = 'user' } = {}) {
+  const s = String(source || '').trim();
+  const c = String(convId || '').trim();
+  if (!s || !c) return { ok: false, reason: 'bad-key' };
+  let data;
+  try {
+    data = memory.exportEntry(s, c);
+  } catch (e) {
+    return { ok: false, reason: 'export-failed', message: String(e?.message ?? e).slice(0, 160) };
+  }
+  const at = new Date();
+  const stem = `${localStamp(at)}-${kind}-${shortId(c)}`;
+  let dir = join(archiveRootOf(memory), stem);
+  // ⚠️ B-07(1.5.1 红蓝对抗,实测踩到):同一秒内对**同一对象**归档两次会撞上同一个目录名,
+  //   而 `mkdirSync({recursive:true})` 对已存在的目录**不报错**、随后的 `writeFileSync` 直接覆盖
+  //   ⇒ 上一份归档**静默消失**。归档的全部价值就在于"它还在那儿",所以名字必须唯一。
+  //   (A-01 的"备份并覆盖"尤其吃这一条:连续采纳两次候选完全可能落在同一秒。)
+  for (let i = 2; existsSync(dir) && i < 1000; i += 1) dir = join(archiveRootOf(memory), `${stem}-${i}`);
+  const isForget = kind === 'forget';
+  // ── B-05(1.5.1 红蓝对抗):归档**空不空**必须如实回报 ────────────────────────────
+  // 此前只回 `ok` + `turns`,而 `ok:true` 只说明"文件写下去了":对一条不存在的条目
+  // (或概述行在、原文已被硬删的条目)归档出来是 0 轮 —— 文件系统上**确实有**一个目录,
+  // 所以判据「归档成功」为真,可它什么都没保住。调用方(fail-closed 的那条纪律)因此
+  // 无法区分"备份好了"与"备份了一份空的",就会接着打遗忘标记:
+  // 标记永久留下、id 永不召回、界面还显示"忘过了",而回执写着"原文与概述已归档"。
+  // 这里把判据**显式化**:`empty` 看的是**归档内容**(原文轮数 + 正文有无),
+  // **不是**目标是否存在 —— 目的就是让"还打不打得动标记"这件事有据可依。
+  const empty = (data.turns || []).length === 0
+    && !String(data.overview?.summary || '').trim()
+    && !data.sessionMeta;
+  try {
+    mkdirSync(dir, { recursive: true });
+    // 原文逐行 JSONL —— 能 grep、能逐行还原,比一个大 JSON 数组更耐损
+    const turnsText = (data.turns || []).map((t) => JSON.stringify(t)).join('\n');
+    writeFileSync(join(dir, 'turns.jsonl'), turnsText ? turnsText + '\n' : '', 'utf8');
+    writeFileSync(join(dir, 'overview.json'), JSON.stringify(data.overview || null, null, 2), 'utf8');
+    writeFileSync(join(dir, 'session-meta.json'), JSON.stringify(data.sessionMeta || null, null, 2), 'utf8');
+    writeFileSync(join(dir, 'README.md'), readme({
+      at, s, c, kind, reason, actor, turns: (data.turns || []).length,
+    }), 'utf8');
+  } catch (e) {
+    return { ok: false, reason: 'write-failed', message: String(e?.message ?? e).slice(0, 160) };
+  }
+  if (!existsSync(join(dir, 'README.md'))) return { ok: false, reason: 'write-failed' };
+  return { ok: true, dir, turns: (data.turns || []).length, empty, isForget };
+}
+
+/** 改动日志 —— 这份文件是给**将来的人**看的,所以写全:是什么、为什么、怎么还原。 */
+function readme({ at, s, c, kind, reason, actor, turns }) {
+  const who = actor === 'ling' ? '器灵(工具通道)' : '主人(界面通道)';
+  // A-01(1.5.1):第三种 kind —— 主脉记忆覆盖(同一主脉再次采纳提炼结果;用户裁决"备份并覆盖")。
+  const what = kind === 'forget' ? '遗忘(软标记 —— **库里的行没有删**)'
+    : kind === 'vein-overwrite' ? '主脉记忆**覆盖**(同一主脉再次采纳 —— **上一版正文完整存在这里**)'
+    : '回灌(用归档恢复一条记忆 —— **覆盖前的状态已存这里**)';
+  const title = kind === 'forget' ? '遗忘前' : kind === 'vein-overwrite' ? '主脉记忆覆盖前' : '回灌前';
+  // 「怎么还原」按 kind 分三档。用**字符串拼接**而不是嵌套模板,免得外层模板里的反引号打架。
+  const restoreBlock = kind === 'forget'
+    ? '**库里没有删任何行** —— 只是多了一条 `forgotten` 标记,召回路径不再选它。撤销方式二选一:\n\n'
+      + '1. 让器灵调工具撤销(`memory_forget` 的 `undo`),或\n'
+      + '2. 直接删标记:\n   ```sql\n   DELETE FROM forgotten WHERE source=\'' + s + '\' AND conv_id=\'' + c + '\';\n   ```'
+    : kind === 'vein-overwrite'
+      ? '覆盖只动了 `conv_overview` 里那一行(主脉自己的记忆),原文与会话元数据不受影响。要把上一版换回去:\n\n'
+        + '1. 让器灵按本目录 `overview.json` 的 `summary` **再采纳一次**旧正文,或\n'
+        + '2. 直接写回:\n   ```sql\n   UPDATE conv_overview SET summary=\'<overview.json 的 summary>\'\n    WHERE source=\'' + s + '\' AND conv_id=\'' + c + '\';\n   ```'
+      : '回灌只是把归档写回去,而**它覆盖之前的状态存在这里**。要退回去:\n\n'
+        + '1. 让器灵再回灌一次旧档(`memory_backfill`),或\n'
+        + '2. 按下面「万一库本身没了」的步骤写回。';
+  return `# 归档:${title}的原始数据
+
+| | |
+|---|---|
+| 操作 | ${what} |
+| 对象 | \`source=${s}\` · \`conv_id=${c}\` |
+| 时间 | ${humanTime(at)} |
+| 操作者 | ${who} |
+| 原因 | ${reason || '(未填写)'} |
+
+## 这里有什么
+
+- \`turns.jsonl\` —— 原文 **${turns}** 轮(每行一条 JSON,字段与库表 \`dsh_turns_raw\` 同构)
+- \`overview.json\` —— 概述行(标题 / 摘要 / 关键词 / 权重 / 置顶 …)
+- \`session-meta.json\` —— 会话元数据(模式 / 枝归属 …)
+
+## 怎么还原
+
+${restoreBlock}
+
+万一库本身没了(换机 / 误删),用这里的文件重建:
+
+- 原文:\`turns.jsonl\` 逐行 \`INSERT INTO dsh_turns_raw (session_id,seq,role,ts,model,text) VALUES (…)\`
+- 概述:按 \`overview.json\` 写回 \`conv_overview\`
+
+## 为什么保留
+
+忘错了要能回头。这是用户定的规矩:**永远不做彻底删除** ——
+所以这个目录是"曾经发生过什么"的证据,不是垃圾。不要随手清。
+
+> 生成于 dsh-ling · Part G(器灵侧正规通道)
+`;
+}
+
+/** 列出归档目录(最近的在前)—— 回答"这里能回灌什么"。 */
+export function listArchives(memory, { limit = 50 } = {}) {
+  const root = archiveRootOf(memory);
+  let names = [];
+  try {
+    names = readdirSync(root).filter((n) => /^\d{8}-\d{6}-/.test(n));
+  } catch {
+    return [];
+  }
+  names.sort().reverse();
+  const n = Math.max(1, Math.min(500, Number(limit) || 50));
+  return names.slice(0, n).map((name) => {
+    const dir = join(root, name);
+    let turns = 0;
+    try {
+      turns = readFileSync(join(dir, 'turns.jsonl'), 'utf8').split('\n').filter((l) => l.trim()).length;
+    } catch { /* 没有原文的归档也算一条记录 */ }
+    return { name, dir, turns };
+  });
+}
+
+/** 读回一个归档目录(名字取自 listArchives)。 */
+export function readArchive(memory, name) {
+  const safe = String(name || '').replace(/[^A-Za-z0-9_-]/g, '');
+  if (!safe) return { ok: false, reason: 'bad-name' };
+  const dir = join(archiveRootOf(memory), safe);
+  const out = { ok: true, name: safe, dir, turns: [], overview: null, note: '' };
+  try {
+    out.turns = readFileSync(join(dir, 'turns.jsonl'), 'utf8')
+      .split('\n').filter((l) => l.trim())
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch { /* 允许无原文 */ }
+  try { out.overview = JSON.parse(readFileSync(join(dir, 'overview.json'), 'utf8')); } catch { /* ignore */ }
+  try {
+    // 日志里的"对象/操作者/原因"三行 —— 回灌之前让人先看一眼:当初为什么把它忘掉的
+    const md = readFileSync(join(dir, 'README.md'), 'utf8');
+    out.note = md.split('\n').filter((l) => /操作者|原因|对象/.test(l)).join(' ').replace(/\s+/g, ' ').slice(0, 300);
+  } catch { /* ignore */ }
+  return out;
+}

package/lib/host/autotree.js

@@ -0,0 +1,131 @@
+// dsh-ling host — 一键生成记忆树(D9-b,2026-09-20 与用户定案)。
+//
+// 主干 1593 条太粗,需要先把树"初步划一遍"。分两阶段:
+//   ① 机械分段  —— 按时序相邻性把全库概述切成若干簇(零成本、确定、可复现);
+//   ② 小助手命名 —— 每簇一次调用,起一个主题名(模型只做"命名"这一件语义活)。
+//   ③ 主人审核后落库(apply 在 api.js 侧) —— 建枝/主脉 + 挂会话。
+//
+// 为什么不把 1593 条直接丢给模型:装不进上下文,而且"按时序切段"本就是机械活。
+// 模型擅长的是"给一段对话起主题名",不是"在 1593 条里做聚类"(设计稿 §8 / 用户 2026-09-20)。
+//
+// 不变量:本模块**只读概述索引**、只产出候选,**从不改写任何记忆内容**。
+
+export const AUTOTREE_SYS = [
+  '你是记忆整理助手。用户会给你一组同期的对话标题(按时间先后排列)。',
+  '请判断这组对话共同围绕的主题,并起一个简短的中文名字。',
+  '要求:',
+  '1) 名字 2~10 个字,是主题(如「工程力学」「记忆系统设计」「装修与工具」),不要用时间或"对话记录"这类空话;',
+  '2) 若这组对话主题分散、看不出共同主题,名字就写「零散记录」;',
+  '3) 只输出一行,格式:名字|一句话说明',
+  '不要输出任何其他内容。',
+].join('\n');
+
+const DAY = 86400000;
+
+/** 宽松时间解析(取不到记 0 —— 0 视为"无时间",不参与间隔切分)。 */
+export function tsOf(s) {
+  const t = Date.parse(String(s || ''));
+  return Number.isFinite(t) ? t : 0;
+}
+
+/**
+ * 机械分段:先按源分组,组内按时序排序,相邻间隔 > gapDays(或单簇超过 maxSize)即切一刀。
+ * 返回 [{ id, source, count, from, to, items:[{source,convId,title,at,ts,hasSummary}] }]。
+ * ⚠️ 时间缺失(ts=0)的条目不会触发切分,只受 maxSize 约束 —— 避免"无时间"被误当成"间隔巨大"。
+ */
+export function bucketize(rows, { gapDays = 14, maxSize = 40 } = {}) {
+  const bySource = new Map();
+  for (const r of rows || []) {
+    const src = String((r && r.source) || '');
+    if (!bySource.has(src)) bySource.set(src, []);
+    bySource.get(src).push({
+      source: src,
+      convId: String((r && r.convId) || ''),
+      title: String((r && r.title) || ''),
+      at: String((r && r.at) || ''),
+      ts: tsOf(r && r.at),
+      hasSummary: !!(r && r.hasSummary),
+    });
+  }
+  const gap = Math.max(1, Number(gapDays) || 14) * DAY;
+  const cap = Math.max(5, Math.min(200, Number(maxSize) || 40));
+  const out = [];
+  for (const [src, list] of bySource) {
+    list.sort((a, b) => (a.ts || 0) - (b.ts || 0) || a.convId.localeCompare(b.convId));
+    let cur = [];
+    const flush = () => {
+      if (!cur.length) return;
+      out.push({
+        id: 'bk:' + src + ':' + out.length,
+        source: src,
+        count: cur.length,
+        from: cur[0].at,
+        to: cur[cur.length - 1].at,
+        items: cur,
+      });
+      cur = [];
+    };
+    for (const it of list) {
+      const prev = cur[cur.length - 1];
+      if (prev && it.ts && prev.ts && it.ts - prev.ts > gap) flush();
+      else if (cur.length >= cap) flush();
+      cur.push(it);
+    }
+    flush();
+  }
+  return out;
+}
+
+/** 把一簇压成给模型看的标题清单(只给标题,不给摘要 —— 省 token 且够用)。 */
+export function bucketDigest(bucket, { maxTitles = 40 } = {}) {
+  const items = (bucket && bucket.items) || [];
+  return items
+    .slice(0, Math.max(1, Number(maxTitles) || 40))
+    .map((it) => '- ' + (it.title || it.convId))
+    .join('\n');
+}
+
+/** 解析模型输出的一行「名字|说明」。宽容:去掉前缀符号/引号/编号。 */
+export function parseName(text) {
+  const first = String(text || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)[0] || '';
+  const clean = first.replace(/^[#*\-•\d.、\s]+/, '').trim();
+  if (!clean) return { name: '', note: '' };
+  const parts = clean.split(/[|｜]/);
+  const name = String(parts[0] || '').replace(/[「」"']/g, '').trim().slice(0, 30);
+  const note = String(parts.slice(1).join(' ') || '').trim().slice(0, 120);
+  return { name, note };
+}
+
+/**
+ * 给一簇起名。call 注入 summarizeWithRetry(便于测试与替换)。
+ * 返回 { ok, name, note, ms } 或 { ok:false, error }。
+ */
+export async function nameBucket(baseUrl, model, bucket, { maxTokens = 512, timeoutMs = 90000, call = null } = {}) {
+  if (typeof call !== 'function') return { ok: false, error: 'no-call' };
+  const digest = bucketDigest(bucket);
+  if (!digest) return { ok: false, error: 'empty-bucket' };
+  const text = '来源:' + String((bucket && bucket.source) || '') + '\n'
+    + '时间:' + String((bucket && bucket.from) || '?') + ' ~ ' + String((bucket && bucket.to) || '?') + '\n'
+    + '共 ' + Number((bucket && bucket.count) || 0) + ' 条,标题如下:\n' + digest;
+  const r = await call(baseUrl, model, { text, system: AUTOTREE_SYS, maxTokens, timeoutMs });
+  if (!r || !r.ok) return { ok: false, error: String((r && r.error) || 'failed') };
+  const { name, note } = parseName(r.summary);
+  if (!name) return { ok: false, error: 'empty-name' };
+  return { ok: true, name, note, ms: Number(r.ms || 0) };
+}
+
+/** 把若干命名结果合并成"应用计划"的默认形态(每簇一枝,挂在指定父下)。 */
+export function planFromNamed(named, { parentId = 'trunk' } = {}) {
+  return (named || [])
+    .filter((n) => n && n.ok && n.bucketId)
+    .map((n) => ({
+      bucketId: String(n.bucketId),
+      mode: 'branch',
+      name: String(n.name || ''),
+      parentId: String(parentId || 'trunk'),
+      note: String(n.note || ''),
+    }));
+}

package/lib/host/backfill.js

@@ -0,0 +1,267 @@
+// dsh-ling host — DSH 存量会话回溯(把捕捉上线前的磁盘会话纳入记忆)。
+// 语义与 tools/backfill-dsh.mjs 一致,读侧独立为模块供 API 使用;
+// 写侧走传入的 MemoryStore(与运行中实例同库,免并发双开)。
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { categorizeTitle } from './classify.js';
+import { keywordsFrom } from './inject-common.js';
+import { decodeAll } from './zstd.js';
+
+/**
+ * 会话转储文件名(代次可变)。
+ * DSH 升级会改写文件名:session.jsonl.zstd → session.v3.jsonl.zstd → session.v4.jsonl.zstd …
+ * 旧的写死匹配漏掉 v3/v4(本机实测 204 个会话只看见 53 个),故一律按此正则认。
+ */
+export const SESSION_FILE_RE = /^session(?:\.v(\d+))?\.jsonl\.zstd$/;
+
+/**
+ * 在一个会话目录里挑出会话转储文件。
+ * 规则:匹配 SESSION_FILE_RE → 取版本号最高的一代(无版本号视为 0,即最低)→ 跳过 0 字节文件(写盘未完成)。
+ * @returns {{f:string,name:string,ver:number,size:number}|null} 无匹配返回 null
+ */
+export function pickSessionFile(dir) {
+  let names;
+  try { names = readdirSync(dir); } catch { return null; }
+  let best = null;
+  for (const name of names.slice().sort()) { // 排序:同代次多文件时结果稳定
+    const m = SESSION_FILE_RE.exec(name);
+    if (!m) continue;
+    const ver = m[1] ? Number(m[1]) : 0;
+    let st;
+    try { st = statSync(join(dir, name)); } catch { continue; }
+    if (!st.isFile() || st.size === 0) continue;
+    if (!best || ver > best.ver) best = { f: join(dir, name), name, ver, size: st.size };
+  }
+  return best;
+}
+
+/**
+ * DSH 会话根目录的默认位置 —— **单一来源**:`candidateSessionFiles` 的默认值与
+ * `scanDshHistory` 的入口解析共用它,不允许各写一份。
+ * 为什么必须是一个显式函数:不传 root 时,扫描侧有默认值照常工作,而归因探针侧
+ * 拿到 `undefined` → `readdirSync(undefined)` 抛错被吞 → 恒判 `no-sessions-root`,
+ * 界面渲染成「未找到 DSH 会话目录:undefined」(BUG-2 归因几乎不可达)。
+ */
+export function defaultSessionsRoot() {
+  return join(homedir(), '.dsh', 'sessions');
+}
+
+/** 候选会话文件: ~/.dsh/sessions/<workspace>/<sid>/{session[.vN].jsonl.zstd} */
+export function candidateSessionFiles(root = defaultSessionsRoot()) {
+  const jobs = [];
+  let ws;
+  try { ws = readdirSync(root, { withFileTypes: true }); } catch { return jobs; }
+  for (const w of ws) {
+    if (!w.isDirectory()) continue;
+    const wsDir = join(root, w.name);
+    let subs;
+    try { subs = readdirSync(wsDir, { withFileTypes: true }); } catch { continue; }
+    for (const d of subs) {
+      if (!d.isDirectory()) continue;
+      const hit = pickSessionFile(join(wsDir, d.name));
+      if (hit) jobs.push({ f: hit.f, ws: w.name, sid: d.name, file: hit.name, ver: hit.ver });
+    }
+  }
+  return jobs;
+}
+
+/**
+ * 「0 候选」的归因探针(仅在扫到 0 时调用,代价可忽略)。
+ * 让「一个会话文件都没匹配上」与「这台机器根本没历史」可区分(BUG-2)。
+ */
+function emptyScanInfo(root) {
+  const info = { root, rootExists: false, sessionDirs: 0, emptyFiles: 0, fileNames: [] };
+  let ws;
+  try { ws = readdirSync(root, { withFileTypes: true }); } catch { return withNote(info); }
+  info.rootExists = true;
+  for (const w of ws) {
+    if (!w.isDirectory()) continue;
+    let subs;
+    try { subs = readdirSync(join(root, w.name), { withFileTypes: true }); } catch { continue; }
+    for (const d of subs) {
+      if (!d.isDirectory()) continue;
+      info.sessionDirs += 1;
+      let names;
+      try { names = readdirSync(join(root, w.name, d.name)); } catch { continue; }
+      for (const n of names) {
+        if (!/\.jsonl(\.zst|\.zstd)?$/.test(n)) continue;
+        if (info.fileNames.length < 8 && !info.fileNames.includes(n)) info.fileNames.push(n);
+        if (!SESSION_FILE_RE.test(n)) continue;
+        try { if (statSync(join(root, w.name, d.name, n)).size === 0) info.emptyFiles += 1; } catch {}
+      }
+    }
+  }
+  return withNote(info);
+}
+
+function withNote(info) {
+  if (!info.rootExists) {
+    info.reason = 'no-sessions-root';
+    info.note = `未找到 DSH 会话目录:${info.root}(这台机器可能没跑过 DSH,或用 DSH_HOME 指到了别处)`;
+  } else if (info.sessionDirs === 0) {
+    info.reason = 'no-session-dirs';
+    info.note = `会话目录存在但没有任何会话子目录:${info.root}`;
+  } else if (info.emptyFiles > 0) {
+    info.reason = 'empty-session-files';
+    info.note = `${info.emptyFiles} 个会话文件是 0 字节(已跳过,可能是写盘未完成):${info.root}`;
+  } else if (info.fileNames.length) {
+    info.reason = 'no-session-files';
+    info.note = `未找到会话文件(可能是 DSH 会话格式版本变化);目录里见到的相关文件:${info.fileNames.join('、')}`;
+  } else {
+    info.reason = 'no-session-files';
+    info.note = `未找到会话文件(可能是 DSH 会话格式版本变化):${info.root}`;
+  }
+  return info;
+}
+
+function parseHeader(firstLine) {
+  try {
+    const j = JSON.parse(firstLine);
+    return {
+      deleg: Number(j.delegationDepth ?? 0),
+      origin: j.origin,
+      parent: !!j.parentSession,
+      id: j.id || '',
+      cwd: j.cwd || '',
+      preset: j.agentPreset || '',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** 对单个会话文件:判定顶层、抽取真实消息 → 概述行(不写库)。 */
+export function overviewRowFromFile(file, ws, sid) {
+  let text;
+  try {
+    text = decodeAll(readFileSync(file));
+  } catch {
+    return { skip: 'failed', row: null };
+  }
+  // 顶层判定:从解码全文找 header 行(type=session)
+  let isChild = false;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    if (line.includes('"type":"session"')) {
+      const h = parseHeader(line);
+      if (h) isChild = !!(h.parent || h.origin === 'subagent' || h.deleg > 0);
+      break;
+    }
+    if (!line.includes('"type"')) continue;
+    break;
+  }
+  if (isChild) return { skip: 'child', row: null };
+
+  let firstUser = '';
+  let nUser = 0;
+  let nAsst = 0;
+  let totalChars = 0;
+  let t0 = null;
+  let t1 = null;
+  for (const line of text.split('\n')) {
+    if (!line.includes('"type":"user/message"') && !line.includes('"type":"assistant/message"')) continue;
+    let ev;
+    try { ev = JSON.parse(line); } catch { continue; }
+    const kind = ev?.data?.source?.kind;
+    const t = Number(ev?.time);
+    if (t) { if (t0 === null || t < t0) t0 = t; if (t1 === null || t > t1) t1 = t; }
+    if (ev.type === 'user/message') {
+      if (kind !== 'user') continue; // 只留真人
+      const body = ev?.data?.content;
+      const u = Array.isArray(body)
+        ? body.filter((b) => b?.type !== 'reasoning' && b?.type !== 'tool-call').map((b) => b?.text || b?.content || '').join('\n')
+        : '';
+      if (!u) continue;
+      nUser += 1;
+      totalChars += u.length;
+      if (!firstUser) firstUser = u.trim();
+    } else {
+      const msg = ev?.data?.message;
+      const body = msg?.content;
+      const a = Array.isArray(body)
+        ? body.filter((b) => b?.type === 'text' || !b?.type).map((b) => b?.text || b?.content || '').join('\n')
+        : '';
+      if (!a) continue;
+      nAsst += 1;
+      totalChars += a.length;
+    }
+  }
+  if (!firstUser) return { skip: 'no-user', row: null };
+  const oneLine = firstUser.replace(/\s+/g, ' ').trim();
+  const weak = nUser < 1 || nUser + nAsst < 2 || totalChars < 40;
+  const trivial = nUser <= 2 && /^(hello|hi|test|你好|嗨|哈喽|在吗|还在吗|嗯|哈哈|测试|123)/i.test(oneLine);
+  if (weak || trivial) return { skip: 'weak', row: null };
+  const cat = categorizeTitle(oneLine);
+  return {
+    skip: null,
+    row: {
+      conv_id: sid,
+      source: 'dsh',
+      title: oneLine.slice(0, 46) || '(未命名会话)',
+      started_at: t0 ? new Date(t0).toISOString() : null,
+      updated_at: t1 ? new Date(t1).toISOString() : null,
+      domain_tags: [cat === 'knowledge' ? '知识' : cat === 'feeling' ? '生活' : '日常'],
+      category: cat,
+      keywords: keywordsFrom((oneLine + ' ' + firstUser).slice(0, 400)),
+      summary: `${oneLine.slice(0, 140)} — ${nUser + nAsst} 条消息`,
+      heat: 0,
+      importance: 0,
+      last_hit_at: null,
+      hit_count: 0,
+      overview_ok: 1,
+      origin: 'dsh-backfill-v1',
+    },
+  };
+}
+
+/**
+ * 全量扫描:枚举 → 解码 → 顶层/弱会话过滤 → (可选)写入 memory。
+ * @param {object} opts { memory?: MemoryStore(提供则写入), root?, limit? }
+ * @returns {{report, rows}} report 字段与 CLI 版一致;rows 为本次新增行。
+ */
+export async function scanDshHistory({ memory = null, root, limit = 0 } = {}) {
+  // BUG-2:入口处**一次解析** root,扫描与归因共用同一个值。
+  // 旧写法把 `root`(可能是 undefined)直接交给 emptyScanInfo,而 api.js 的
+  // `/dsh/backfill` 只传 `{ memory, limit }` ⇒ 归因恒判 no-sessions-root、note 里
+  // 打印 undefined,并被 client 显示给用户。此处解析后,任何调用方(HTTP / CLI / 工具)
+  // 不传 root 都能拿到真实根目录。
+  const sessionsRoot = root ?? defaultSessionsRoot();
+  const jobs = candidateSessionFiles(sessionsRoot);
+  const report = { scanned: 0, topLevel: 0, decoded: 0, eligible: 0, created: 0, skippedExists: 0, skippedWeak: 0, failed: 0 };
+  // BUG-2:「0 候选」必须给出原因,否则和「这台机器没历史」在界面上长得一模一样
+  if (!jobs.length) Object.assign(report, emptyScanInfo(sessionsRoot));
+  const rows = [];
+  const seen = new Set();
+  if (memory) {
+    for (const r of memory.listOverviews({ source: 'dsh' })) seen.add(String(r.conv_id));
+  }
+  for (const job of jobs) {
+    report.scanned += 1;
+    const { skip, row } = overviewRowFromFile(job.f, job.ws, job.sid);
+    if (skip === 'failed') { report.failed += 1; continue; }
+    report.decoded += 1;
+    if (skip === 'child') continue;
+    report.topLevel += 1;
+    if (skip) { report.skippedWeak += 1; continue; }
+    if (seen.has(job.sid)) { report.skippedExists += 1; continue; }
+    report.eligible += 1;
+    rows.push(row);
+    if (limit > 0 && rows.length >= limit) break;
+  }
+  if (memory && rows.length) {
+    memory.db.exec('BEGIN');
+    try {
+      for (const r of rows) memory.upsertOverview(r);
+      memory.db.exec('COMMIT');
+    } catch (e) {
+      try { memory.db.exec('ROLLBACK'); } catch {}
+      throw e;
+    }
+    report.created = rows.length;
+    memory.kvSet('backfill.last', JSON.stringify({ at: new Date().toISOString(), ...report, inserted: rows.length }));
+  } else if (memory) {
+    memory.kvSet('backfill.last', JSON.stringify({ at: new Date().toISOString(), ...report, inserted: 0 }));
+  }
+  return { report, rows };
+}

package/lib/host/classify.js

@@ -0,0 +1,10 @@
+// dsh-ling host — 会话概述分类/类别词表(供概述器与导入共用)。
+// v0 启发式;词表后续可在设置里校准。
+const KNOW_RE = /物理|模拟|材料|合金|金属|固溶|热处理|退火|淬火|SLM|激光|3D|打印|工艺|实验|力学|运动|弹簧|电|磁|机械|轴承|齿轮|螺栓|公差|图纸|仿真|计算|推导|方程|函数|算法|代码|编程|程序|开发|设计|架构|编辑器|工具|软件|系统|虚拟机|显示|显卡|显示器|网络|协议|数据|数据库|安全|加密|AI|GPT|LLM|模型|HTML|CSS|插件|开源|文献|论文|综述|研究|分析|优化|参数|标准|工程|电路|噪声|声学|光学|流体|温度|硬度|刚度|强度|疲劳|失效|锈|腐蚀|焊接|铸造|粉末|显微|衍射|晶体|电池|半导体|传感器|嵌入式|单片机|遥控|信号|放大器|扬声器|摄像头|滚珠|丝杆|导轨|减速|电机|驱动|stm|arduino|树莓派|统计|概率|几何|代数|微积分|复变|傅里叶|拉普拉斯|微分方程|数值|离散|随机|目检|示波器|万用表|稳压|逆变|拓扑|算法/;
+const FEEL_RE = /失眠|睡眠|睡不着|焦虑|烦躁|抑郁|emo|情绪|心情|感情|关系|朋友|家人|父母|孤独|迷茫|人生|困惑|害怕|恐惧|压力|疲惫|累|休息|放松|静心|呼吸|梦境|梦|倾诉|共鸣|温暖|鼓励|安慰|不安|内耗|自我|意义|幸福|遗憾|夜|月亮|散文|随想|杂感|闲聊|谈心|牢骚|吐槽|习惯|拖延|自律|动力|目标感|虚无|发呆|感性|告别|怀念|感谢|感动|爱|牵挂|想你了|晚安|早安|活着/;
+
+export function categorizeTitle(title) {
+  if (FEEL_RE.test(title)) return 'feeling';
+  if (KNOW_RE.test(title)) return 'knowledge';
+  return 'daily';
+}