modelstage 0.5.28 → 0.6.1

package/src/server/data/manifest-jsonl.mjs

@@ -0,0 +1,264 @@
+// data/manifest-jsonl.mjs —— 模型清单的 JSONL 存储（P1）
+//
+// 为什么换格式：旧实现把整份清单 `JSON.stringify` 后一次写盘，于是
+//   ① 扫描期间**一条都写不出去**（必须等全部扫完）—— 中途被杀就全丢，用户重来一次还是几十秒；
+//   ② 大根的清单是单个巨大字符串，解析时要整份 materialize 到内存；
+//   ③ 想"边扫边写"根本没法做（JSON 不是流式可写的格式）。
+//   JSONL 每行一个独立对象：可以逐条 append、可以逐行解析、坏一行不影响其它行。
+//
+// 三个必须理解的约束（每条都对应一个实测踩过的坑，详见设计 §4.3）：
+//   ① 句柄声明在**能执行到的外层**：曾经把 fd 声明在 try 内，catch/finally 里访问不到 ⇒ 从未关闭 ⇒
+//      遍历大目录后句柄耗尽，且 rename 时目标仍有未关闭读句柄 ⇒ CIFS 上 EACCES
+//   ② rename 前必须已关句柄，且**不用 copyFile 绕开**（覆盖已存在文件在 CIFS 上 EPERM，且丢原子性）
+//   ③ 打开一次 + writeSync 多次，不要每条 open/close（431 条模型 = 431 次 open 是不可接受的开销）
+//
+// 行格式（设计 §4.2）：
+//   首行 meta   {"_":"meta","rootId","ts","generator","dirStamps","complete":false}
+//   数据行       {"t":"m","k":"<模型 id>","v":{…}}
+//   末行 complete {"t":"meta","k":"complete","v":{"count":N,"ts":T}}   ← last-wins
+// 同一 key 重复出现 ⇒ 后写覆盖先写（重扫时不必先删旧行）
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 同一进程内的 tmp 序号：保证"每次扫描的 tmp 唯一" */
+let tmpSeq = 0;
+
+/** 坏行占比超过这个阈值 ⇒ 判整体损坏（设计 §4.4）。千分之一：少量截断尾巴能容忍，成片坏说明文件本身废了。 */
+const BAD_LINE_RATIO_LIMIT = 0.01;
+
+/**
+ * 打开一个清单写入器。
+ *
+ * @param {string} base 不带扩展名的路径（如 `…/config/models/spine.<rootId>`）
+ * @param {object} meta 首行要写的元信息：{rootId, ts, generator, dirStamps}
+ *   （**不含 kind**：清单是可分发数据，渲染器类型由读取方按来源判断）
+ * @returns {{
+ *   append: (model: object) => void,
+ *   finish: (count: number) => {bytes: number, file: string},
+ *   abort: () => void,
+ *   bytesWritten: number,
+ *   tmpFile: string,
+ *   finalFile: string,
+ * }}
+ */
+export function openManifestWriter(base, meta) {
+  // tmp 文件名**每次扫描唯一**：<base>.<pid>.<seq>.jsonl.tmp
+  //   为什么不能固定名：并发场景下（另一个根的 refresh、或任何一次 invalidate）会清理"看起来像残留"的 tmp，
+  //   固定名的话它会把**正在写**的那份删掉 ⇒ finish 时 rename ENOENT（实测踩到：
+  //   `rename 'spine.<rootId>.jsonl.tmp' -> 'spine.<rootId>.jsonl'` ENOENT）。
+  //   唯一名让"两个扫描互不干扰"，也让"清理残留"能安全地只删老的。
+  const tmpFile = `${base}.${process.pid}.${(tmpSeq += 1)}.jsonl.tmp`;
+  const finalFile = `${base}.jsonl`;
+  fs.mkdirSync(path.dirname(base), { recursive: true });
+
+  // ① 自己这个唯一名理论上不该已存在（seq 单调递增）；存在说明进程内序号被复用（极罕见），覆盖即可。
+  try {
+    if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+  } catch { /* 删不掉也无所谓：下面 'w' 会截断它 */ }
+
+  // ② 句柄声明在**外层**（见文件头约束①）：finish/abort 都要能访问到
+  let fd = null;
+  let closed = false;
+  let bytesWritten = 0;
+
+  function writeLine(obj) {
+    const line = `${JSON.stringify(obj)}\n`;
+    fs.writeSync(fd, line);
+    bytesWritten += Buffer.byteLength(line);
+  }
+
+  fd = fs.openSync(tmpFile, 'w');
+  // 首行 meta：complete:false 起始 —— 读侧看到 false 就知道"这份还没写完"
+  // meta 行**不写 kind**：清单是可分发的数据，不应该带"这是哪种渲染器"的标签；
+  //   前端需要的类型由 catalog 读取时按来源盖章（值域仍是 'spine' / 'live2d'）。
+  writeLine({
+    _: 'meta',
+    rootId: meta.rootId,
+    ts: meta.ts,
+    generator: meta.generator,
+    dirStamps: meta.dirStamps,
+    complete: false,
+  });
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    try {
+      if (fd !== null) fs.closeSync(fd);
+    } catch { /* 已关闭/句柄失效：忽略 */ }
+    fd = null;
+  }
+
+  return {
+    /**
+     * 追加一条模型。**同步写**：单条几十~几百字节，一次 writeSync 是微秒级，
+     *   不会像目录遍历那样长时间占住事件循环（进度帧仍能正常发出）。
+     * @param {object} model 与旧格式 models[i] **逐字段一致**
+     */
+    append(model) {
+      if (closed) return;
+      const key = model && model.id ? String(model.id) : '';
+      writeLine({ t: 'm', k: key, v: model });
+    },
+    /**
+     * 收尾：写 complete 行 → 关句柄 → rename 覆盖正式文件。
+     * @param {number} count 最终模型数（读侧据此做一致性自检）
+     * @returns {{bytes: number, file: string}}
+     */
+    finish(count) {
+      if (closed) return { bytes: bytesWritten, file: finalFile };
+      writeLine({ t: 'meta', k: 'complete', v: { count, ts: Date.now() } });
+      const bytes = bytesWritten;
+      close();
+      // ② rename 前已关句柄（见约束②）
+      //    tmp 不在 ⇒ 明确说是"被并发清理删掉了"而不是抛一个裸 ENOENT 让人猜
+      if (!fs.existsSync(tmpFile)) {
+        throw new Error(
+          `清单 tmp 在收尾前消失：${tmpFile}`
+          + `（可能被并发的失效清理删掉了；正式文件 ${path.basename(finalFile)} 未受影响，下次请求会重建）`,
+        );
+      }
+      fs.renameSync(tmpFile, finalFile);
+      return { bytes, file: finalFile };
+    },
+    /** 失败：只关句柄，**不动正式文件**（它保持上一次的完整版本）；自己的 tmp 留着供排查 */
+    abort() {
+      close();
+    },
+    get bytesWritten() { return bytesWritten; },
+    tmpFile,
+    finalFile,
+  };
+}
+
+/** 当前优先的存储格式：默认 json（原行为）；env MODELSTAGE_MANIFEST_FORMAT=jsonl 才用 JSONL */
+export function preferredManifestFormat() {
+  return String(process.env.MODELSTAGE_MANIFEST_FORMAT || 'json').toLowerCase() === 'jsonl' ? 'jsonl' : 'json';
+}
+
+/** JSONL 单文件解析（文件必须存在） */
+function readJsonlFile(jsonlFile) {
+  let text = '';
+  let bytes = 0;
+  try {
+    text = fs.readFileSync(jsonlFile, 'utf8');
+    bytes = Buffer.byteLength(text);
+  } catch (e) {
+    return { format: 'jsonl', meta: null, models: [], complete: false, badLines: 0, bytes: 0, error: e.message };
+  }
+  const lines = text.split('\n');
+  let metaRow = null;
+  /** @type {Map<string, object>} key → model（last-wins 靠 Map.set 天然实现） */
+  const byKey = new Map();
+  let badLines = 0;
+  let totalLines = 0;
+  let completeRow = null;
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    totalLines += 1;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      badLines += 1;      // 坏行跳过（进程被杀时常留下半行）—— 不影响其它行
+      continue;
+    }
+    if (obj && obj._ === 'meta') { metaRow = obj; continue; }
+    if (obj && obj.t === 'meta' && obj.k === 'complete') { completeRow = obj; continue; }
+    if (obj && obj.t === 'm') {
+      // last-wins：同 key 后写覆盖先写（重扫追加时不需先删旧行）
+      byKey.set(String(obj.k), obj.v);
+      continue;
+    }
+    badLines += 1;        // 结构不认识的行也计坏行
+  }
+
+  // 坏行过多 ⇒ 判损坏（设计 §4.4）。少量坏行（截断尾巴）可容忍。
+  const tooManyBad = totalLines > 0 && badLines / totalLines > BAD_LINE_RATIO_LIMIT;
+  // 认头条件（**不再有版本字段**）：`_ === 'meta'` 且带 rootId / generator / dirStamps。
+  //   缺任一 ⇒ 判不完整、走重建（宁可重扫，不拿来历不明的结构当结果）。
+  const meta = (metaRow && metaRow._ === 'meta' && metaRow.rootId
+    && metaRow.generator !== undefined && metaRow.dirStamps !== undefined)
+    ? {
+      rootId: metaRow.rootId,
+      ts: metaRow.ts,
+      generator: metaRow.generator,
+      dirStamps: metaRow.dirStamps,
+      complete: true,   // 头部自洽；整体完整性由下面的三条件判定
+    }
+    : null;
+
+  // complete 判定 = **三条件**：meta 头存在 + complete 末行存在 + 末行 count === 实际条数
+  const countMatches = completeRow && completeRow.v && Number(completeRow.v.count) === byKey.size;
+  const complete = Boolean(meta && countMatches && !tooManyBad);
+
+  return {
+    format: 'jsonl',
+    meta,
+    models: [...byKey.values()],
+    complete,
+    badLines,
+    bytes,
+    ...(tooManyBad ? { error: `坏行过多（${badLines}/${totalLines}），判为损坏` } : {}),
+  };
+}
+
+/** 单个历史 JSON 清单解析（文件必须存在）：**视为 complete=true**（历史文件都是完整写出的） */
+function readJsonFile(jsonFile) {
+  try {
+    const text = fs.readFileSync(jsonFile, 'utf8');
+    const payload = JSON.parse(text);
+    return {
+      format: 'json',
+      meta: {
+        rootId: payload.rootId || null,
+        ts: payload.ts || null,
+        generator: payload.generator || null,
+        dirStamps: payload.dirStamps || null,
+        complete: true,
+      },
+      models: Array.isArray(payload.models) ? payload.models : [],
+      complete: true,
+      badLines: 0,
+      bytes: Buffer.byteLength(text),
+    };
+  } catch (e) {
+    return { format: 'json', meta: null, models: [], complete: false, badLines: 0, bytes: 0, error: e.message };
+  }
+}
+
+/**
+ * 读清单：先按**当前优先格式**读，缺失再回落另一种。
+ *
+ * 默认优先 `.json`（保持原有行为）；`MODELSTAGE_MANIFEST_FORMAT=jsonl` 时优先 `.jsonl`。
+ * 两种格式都能读，切换格式不需要迁移历史文件。
+ *
+ * @param {string} base 不带扩展名的路径
+ * @returns {{
+ *   format: 'jsonl'|'json'|'none',
+ *   meta: object|null,
+ *   models: object[],
+ *   complete: boolean,
+ *   badLines: number,
+ *   bytes: number,
+ *   error?: string,
+ * }}
+ */
+export function readManifest(base) {
+  const jsonlFile = `${base}.jsonl`;
+  const jsonFile = `${base}.json`;
+  const order = preferredManifestFormat() === 'jsonl' ? ['jsonl', 'json'] : ['json', 'jsonl'];
+  for (const fmt of order) {
+    if (fmt === 'jsonl') {
+      if (fs.existsSync(jsonlFile)) return readJsonlFile(jsonlFile);
+      continue;
+    }
+    if (fs.existsSync(jsonFile)) return readJsonFile(jsonFile);
+  }
+  return { format: 'none', meta: null, models: [], complete: false, badLines: 0, bytes: 0 };
+}
+
+export { BAD_LINE_RATIO_LIMIT };

package/src/server/data/manifest-stamp.mjs

@@ -99,7 +99,57 @@ const GENERATOR_FILES = [
 let generatorCache = { sig: null, value: '0' };
 
 /**
- * 生成者指纹：解析器文件内容哈希的前 8 位。
+ * 去掉注释与多余空白后再参与哈希。
+ *
+ * 为什么不能直接哈希整份文件：指纹一变就**全部清单作废、所有根重扫**（每个根几十秒）。
+ *   而注释、缩进、换行都属于"改字不改行为"的编辑，不该有这种代价。
+ *   所以这里按语法位置剥掉 `//` 与 `/* *​/`（跳过字符串/模板字面量里的同形字符），再压掉空白，
+ *   只让**真正会改变解析结果的改动**影响指纹。
+ * @param {string} text
+ * @returns {string}
+ */
+function stripCommentsAndSpace(text) {
+  let out = '';
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const ch = text[i];
+    const next = text[i + 1];
+    // 行注释
+    if (ch === '/' && next === '/') {
+      while (i < n && text[i] !== '\n') i += 1;
+      continue;
+    }
+    // 块注释
+    if (ch === '/' && next === '*') {
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i += 2;
+      continue;
+    }
+    // 字符串 / 模板字面量：整段原样保留（里面的 // 不是注释）
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const quote = ch;
+      out += ch;
+      i += 1;
+      while (i < n) {
+        const c = text[i];
+        out += c;
+        if (c === '\\') { out += text[i + 1] || ''; i += 2; continue; }
+        i += 1;
+        if (c === quote) break;
+      }
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  // 压空白：换行也统一成单空格，避免"重排代码"改指纹
+  return out.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * 生成者指纹：解析器文件**去掉注释与空白后**内容哈希的前 8 位。
  * @param {string} [root] 项目根（缺省按本文件位置推，不写死绝对路径）
  * @returns {string} 8 位十六进制（一个文件都读不到时为 '0'）
  */
@@ -125,7 +175,7 @@ export function generatorFingerprint(root = PROJECT_ROOT) {
     if (!ok) continue;
     try {
       h.update(rel);
-      h.update(fs.readFileSync(path.join(root, rel)));
+      h.update(stripCommentsAndSpace(fs.readFileSync(path.join(root, rel), 'utf8')));
       used += 1;
     } catch { /* 单个文件读不了不影响其它文件 */ }
   }

package/src/server/data/scan-progress.mjs

@@ -0,0 +1,305 @@
+// data/scan-progress.mjs —— 扫描进度的单飞表 + NDJSON 帧写出（P0）
+//
+// 解决两个独立问题，放在一起是因为它们共享同一份"扫描生命周期"：
+//   ① **单飞**：同一个资源的并发请求不该触发多次扫描（用户狂点刷新 / 两个标签页同时开）
+//      —— 设计 §4.6。这张表 P1 的 JSONL 存储会原样复用。
+//   ② **进度可见**：一次扫描在 CIFS 上可能要几十秒，没有进度用户只能猜"是不是卡死了"
+//      —— 设计 §5/§6。P0 只发**进度**，模型数据仍走原 JSON 接口（不在这里塞数据行）。
+//
+// 为什么不复用项目的 SSE（/api/ready/stream）：
+//   扫描是**一次性、单向、有明确终点**的。SSE 自带重连语义，前端一重连就会重复触发扫描
+//   （即便有单飞也会多一次订阅与快照），反而制造问题。NDJSON 读 fetch().body.getReader() 即可，
+//   断线就是断线，不会自己重来。
+
+import { EventEmitter } from 'node:events';
+
+/** 进度节流的三个触发条件（设计 §5.1：三者先到先发） */
+const PROGRESS_EVERY_MODELS = 50;
+const PROGRESS_HEARTBEAT_MS = 2000;
+/** 扫描结束后 emitter 的保留期：让"迟到的订阅者"还能拿到 done 帧（设计 §4.6） */
+const EMITTER_RETAIN_MS = 5000;
+
+/**
+ * 造一个进度节流器。walk 里调用 `bump(...)`，它自己决定这一条要不要真的发出去。
+ *
+ * 为什么要节流：一个大根有几万个目录，每条都发帧会把连接打满、前端也跟不上；
+ *   但**不能只按条数节流** —— 遇到一个"空目录树"可能几十秒不新增模型，那样前端会以为卡死。
+ *   所以心跳是独立的一条：即使 scanned 没变，每 2s 也要发一帧证明"还活着"。
+ *
+ * @param {object} opts
+ * @param {(snap: object) => void} opts.onProgress 真正发帧的回调
+ * @param {string} opts.kind 'spine' | 'live2d'
+ * @param {string} opts.rootId 资源根 id
+ * @param {() => number} [opts.now] 取时间（测试可注入）
+ * @returns {{bump: (p: {scanned: number, dirs: number, currentPath: string}) => void, flush: () => void, snapshot: () => object}}
+ */
+export function createProgressThrottle({ onProgress, kind, rootId, now = Date.now }) {
+  const startedAt = now();
+  let lastSentAt = 0;
+  let lastScannedSent = 0;
+  let latest = { scanned: 0, dirs: 0, currentPath: '' };
+
+  function buildSnapshot() {
+    return {
+      kind,
+      rootId,
+      scanned: latest.scanned,
+      dirs: latest.dirs,
+      currentPath: latest.currentPath,
+      elapsedMs: now() - startedAt,
+      phase: 'scan',
+    };
+  }
+
+  function send() {
+    lastSentAt = now();
+    lastScannedSent = latest.scanned;
+    onProgress(buildSnapshot());
+  }
+
+  /**
+   * walk 里每完成一个目录 / 每累计若干模型调用一次。
+   * @param {{scanned: number, dirs: number, currentPath: string, dirCompleted?: boolean}} p
+   */
+  function bump(p) {
+    latest = { scanned: p.scanned, dirs: p.dirs, currentPath: p.currentPath || latest.currentPath };
+    // 三者先到先发：目录完成 / 每 50 条 / 心跳到期
+    const byDir = p.dirCompleted === true;
+    const byCount = latest.scanned - lastScannedSent >= PROGRESS_EVERY_MODELS;
+    const byHeartbeat = now() - lastSentAt >= PROGRESS_HEARTBEAT_MS;
+    if (byDir || byCount || byHeartbeat) send();
+  }
+
+  /** 扫描结束前补发最后一帧（保证前端拿到最终计数，而不是停在某个中间值） */
+  function flush() {
+    if (latest.scanned !== lastScannedSent) send();
+  }
+
+  return { bump, flush, snapshot: buildSnapshot };
+}
+
+/**
+ * 扫描单飞表。
+ *
+ * 语义（设计 §4.6）：
+ *   · 第一个请求创建任务并广播事件
+ *   · 后续请求**不新建任务**，挂到同一 emitter，并立刻收到一条 progress 快照
+ *   · force=1 时若已有扫描在跑 ⇒ 复用（用户在 UI 上重复点重试不该变成双重扫描）
+ *   · 任务结束 5s 后从表里摘掉（保留期给迟到订阅者）
+ */
+export function createScanRunner() {
+  /** @type {Map<string, {emitter: EventEmitter, progress: object|null, done: boolean, startedAt: number}>} */
+  const inflight = new Map();
+
+  function keyOf(kind, rootId) {
+    return `${kind}:${rootId}`;
+  }
+
+  /**
+   * 加入或启动一次扫描。
+   * @param {object} p
+   * @param {string} p.kind
+   * @param {string} p.rootId
+   * @param {(onProgress: (snap: object) => void, onStart: () => void) => Promise<object>} p.run
+   *   真正的扫描函数；它拿到的 onProgress 会转发到 emitter
+   * @returns {{emitter: EventEmitter, progress: object|null, joined: boolean}}
+   */
+  function startOrJoin({ kind, rootId, run }) {
+    const key = keyOf(kind, rootId);
+    const existing = inflight.get(key);
+    if (existing && !existing.done) {
+      // 加入已有扫描：立刻给一条当前快照，前端不必等下一次节流触发
+      return { emitter: existing.emitter, progress: existing.progress, joined: true };
+    }
+
+    const emitter = new EventEmitter();
+    // 订阅者可能随时来去；默认上限 10 会在大并发时告警，调高避免噪音（真正泄漏由结尾 destroy 兜住）
+    emitter.setMaxListeners(64);
+    const entry = { emitter, progress: null, done: false, startedAt: Date.now() };
+    inflight.set(key, entry);
+
+    Promise.resolve()
+      .then(() => run(
+        (snap) => {
+          entry.progress = snap;
+          emitter.emit('progress', snap);
+        },
+        // onStart：让扫描函数在"确认要扫、但还没开始走目录"时就能把首帧推出去
+        () => emitter.emit('start'),
+        // onModel：每产出一条模型就广播（真正的"首模型早出现"靠这一条）
+        (model) => emitter.emit('model', model),
+      ))
+      .then((result) => {
+        entry.done = true;
+        emitter.emit('done', result);
+      })
+      .catch((error) => {
+        entry.done = true;
+        emitter.emit('error', error);
+      })
+      .finally(() => {
+        // 保留期：让"扫描刚结束才连上来"的订阅者也能拿到 done（否则它会永远等不到结束帧）
+        setTimeout(() => {
+          if (inflight.get(key) === entry) inflight.delete(key);
+          emitter.removeAllListeners();
+        }, EMITTER_RETAIN_MS).unref?.();
+      });
+
+    return { emitter, progress: null, joined: false };
+  }
+
+  /** 仅供测试/诊断：当前在跑的扫描 key 列表 */
+  function activeKeys() {
+    return [...inflight.keys()].filter((k) => !inflight.get(k).done);
+  }
+
+  return { startOrJoin, activeKeys, keyOf };
+}
+
+/**
+ * 把一次扫描的生命周期写成 NDJSON 帧（设计 §6.2/6.3/6.4）。
+ *
+ * 三件事按这个顺序做，且都**不能抛错把连接搞崩**：
+ *   · 写头（Content-Type: application/x-ndjson）
+ *   · 先发 start（或 cached），再转发 progress，最后 done/error
+ *   · 客户端断开 ⇒ 停止写帧，但**不取消扫描**（扫描继续跑完并落盘，下次请求就能命中缓存）
+ *
+ * @param {object} p
+ * @param {import('node:http').ServerResponse} p.res
+ * @param {object} p.startFrame 首帧（start 或 cached）
+ * @param {EventEmitter} p.emitter 扫描事件的 emitter
+ * @param {() => object} [p.buildDoneFrame] 把 run 的结果转成 done 帧
+ * @returns {Promise<void>} 连接结束（正常写完或客户端断开）时 resolve
+ */
+export function streamScanFrames({ res, buildStartFrame, emitter, buildDoneFrame, buildCachedFrame }) {
+  res.writeHead(200, {
+    'Content-Type': 'application/x-ndjson',
+    // 进度流不能被任何中间层缓存，否则第二个用户会看到第一个人的旧进度
+    'Cache-Control': 'no-store',
+    // nginx 一类反代默认会缓冲响应体，缓冲后前端就看不到"逐帧到达"了 —— 显式关掉
+    'X-Accel-Buffering': 'no',
+  });
+
+  let clientGone = false;
+  let settled = false;
+
+  function writeFrame(frame) {
+    if (clientGone) return;
+    try {
+      res.write(`${JSON.stringify(frame)}\n`);
+    } catch {
+      // 写到已断开的 socket 会抛（EPIPE）——按"客户端走了"处理，静默停写
+      clientGone = true;
+    }
+  }
+
+  function finish(finalFrame) {
+    if (settled) return;
+    flushModels();
+    settled = true;
+    if (finalFrame) writeFrame(finalFrame);
+    if (!clientGone) {
+      try { res.end(); } catch { /* 已断开：忽略 */ }
+    }
+  }
+
+  // 客户端断开：只标记并清理监听，**不动扫描**
+  res.on('close', () => {
+    clientGone = true;
+    if (modelFlushTimer) { clearTimeout(modelFlushTimer); modelFlushTimer = null; }
+    modelBuffer = [];   // 断开后不再攒（扫描继续，但没人收）
+    emitter.removeListener('start', onStart);
+    emitter.removeListener('progress', onProgress);
+    emitter.removeListener('model', onModel);
+    emitter.removeListener('done', onDone);
+    emitter.removeListener('error', onError);
+    // 扫描本身由单飞表驱动，与这条连接无关 ⇒ 这里什么都不做就是"扫描继续"
+  });
+
+  // start 帧**不在开头预发**：因为"缓存命中"时根本没有扫描发生，先发 start 再发 cached 会自相矛盾
+  //   （设计 §5.3 要求"start 必有 progress 跟随"）。改为在**第一条 progress 到来时**补发 ——
+  //   那时扫描一定真的在跑。
+  let startSent = false;
+
+  // ── model 帧的批量 flush ──
+  // 为什么不每条都 res.write：一帧 ~200~500 字节，431 条就是 431 次 write；
+  //   而 res.write 每次都有 JS↔C++ 往返与 socket 缓冲开销。攒一小批再写，次数降到 1/20。
+  // 为什么还要 200ms 上限：只有"攒够 20 条"的话，扫到一个小目录（3 条）后如果 5 秒没新模型，
+  //   首模型就要再等 5 秒 —— 计时器保证"最多晚 200ms 就发出去"。
+  const MODEL_FLUSH_COUNT = 20;
+  const MODEL_FLUSH_MS = 200;
+  let modelBuffer = [];
+  let modelFlushTimer = null;
+  let modelFramesSent = 0;
+
+  function flushModels() {
+    if (modelFlushTimer) { clearTimeout(modelFlushTimer); modelFlushTimer = null; }
+    if (!modelBuffer.length) return;
+    const batch = modelBuffer;
+    modelBuffer = [];
+    for (const model of batch) {
+      writeFrame({ type: 'model', model });
+      modelFramesSent += 1;
+    }
+  }
+
+  function onModel(model) {
+    if (clientGone) return;
+    modelBuffer.push(model);
+    if (modelBuffer.length >= MODEL_FLUSH_COUNT) {
+      flushModels();
+      return;
+    }
+    if (!modelFlushTimer) modelFlushTimer = setTimeout(flushModels, MODEL_FLUSH_MS);
+  }
+
+  // start 的**首选**触发点：调用方在"确认缓存未命中、马 上要开始扫描"时主动 emit('start')。
+  //   为什么不能只靠"第一条 progress 才发"：扫描前还有一步 `indexRootFiles`（建全根索引）是同步的，
+  //   建全根索引这一步在实测中占了数秒 —— 那样首帧仍然要等数秒，达不到"<2s 可见"的目标。
+  function onStart() {
+    if (startSent) return;
+    startSent = true;
+    if (buildStartFrame) writeFrame(buildStartFrame());
+  }
+  function onProgress(snap) {
+    if (!startSent) {
+      startSent = true;
+      if (buildStartFrame) writeFrame(buildStartFrame());
+    }
+    writeFrame({ type: 'progress', ...snap });
+  }
+  function onDone(result) {
+    flushModels();   // 收尾前把缓冲里的模型全部发出（否则最后 <20 条会丢）
+    // 缓存命中：一条 cached 帧后结束（不逐条发，也不发 start/progress）
+    if (result && result.cached) {
+      finish(buildCachedFrame ? buildCachedFrame(result) : { type: 'cached', count: result.models ? result.models.length : 0, ts: result.ts });
+      return;
+    }
+    if (!startSent) {
+      startSent = true;
+      if (buildStartFrame) writeFrame(buildStartFrame());
+    }
+    finish(buildDoneFrame ? buildDoneFrame(result) : { type: 'done', count: result && result.models ? result.models.length : 0, cached: false });
+  }
+  function onError(error) {
+    flushModels();
+    finish({
+      type: 'error',
+      message: (error && error.message) || String(error),
+      // 出错时把"扫到哪了"一并带上，便于用户/我们自己判断是卡在某个路径
+      scanned: null,
+      currentPath: null,
+    });
+  }
+
+  emitter.on('start', onStart);
+  emitter.on('progress', onProgress);
+  emitter.on('model', onModel);
+  emitter.on('done', onDone);
+  emitter.on('error', onError);
+
+  return new Promise((resolve) => {
+    res.on('close', resolve);
+    res.on('finish', resolve);
+  });
+}