@chainlesschain/personal-data-hub 0.4.1 → 0.4.3

package/lib/adapters/_pc-local-discovery.js

@@ -0,0 +1,362 @@
+"use strict";
+
+/**
+ * PC local-data auto-discovery — find a desktop App's local SQLite database(s)
+ * on the host WITHOUT the user having to type a path.
+ *
+ * Why this exists: every device-pull desktop IM adapter (wechat-pc / qq-pc /
+ * dingtalk-pc / feishu-pc) used to require an explicit `opts.dbPath`. With no
+ * path the readiness probe reported `DB_NOT_PULLED` and the UI offered no way
+ * to start — so "一键采集" was impossible for these sources even though the
+ * database sits at a well-known location on the very machine running cc.
+ *
+ * This module scans the known default install / data directories for each
+ * supported App and returns the discovered database files, grouped by the
+ * login account, with an `encrypted` flag and the *primary* message DB picked
+ * out. Adapters call it from `authenticate()` (readiness) and `sync()` (auto
+ * path) so the common case becomes truly one-click: install the App, log in,
+ * click 采集.
+ *
+ * Layout knowledge is version-aware where it matters:
+ *   - WeChat 4.x:  ~/Documents/xwechat_files/<wxid>_<n>/db_storage/...
+ *   - WeChat 3.x:  ~/Documents/WeChat Files/<wxid>/Msg/...
+ *   - QQ NT:       ~/Documents/Tencent Files/<uin>/nt_qq/nt_db/nt_msg.db
+ *   - DingTalk:    %APPDATA%/DingTalk/**, ~/Documents/DingTalk/**  (best-effort)
+ *   - Feishu/Lark: %APPDATA%/Feishu | Lark /**                     (best-effort)
+ *
+ * Pure + dependency-injectable: pass { fs, path, platform, home, env } so the
+ * whole thing is unit-testable against a synthetic filesystem with no real
+ * Apps installed. Defaults read the real host.
+ *
+ * Everything is best-effort and defensive: a missing directory, a permission
+ * error, or an unexpected layout yields `{ installed: false }` rather than
+ * throwing — discovery must never break a readiness probe.
+ */
+
+const nodeFs = require("node:fs");
+const nodePath = require("node:path");
+const nodeOs = require("node:os");
+
+/** App keys this module knows how to discover. */
+const SUPPORTED_APPS = Object.freeze([
+  "wechat-pc",
+  "qq-pc",
+  "dingtalk-pc",
+  "feishu-pc",
+]);
+
+// ─── injectable host accessors ─────────────────────────────────────────────
+
+function makeDeps(deps = {}) {
+  const fs = deps.fs || nodeFs;
+  const path = deps.path || nodePath;
+  const platform = deps.platform || process.platform;
+  const home =
+    deps.home || (deps.os && deps.os.homedir ? deps.os.homedir() : nodeOs.homedir());
+  const env = deps.env || process.env;
+  return { fs, path, platform, home, env };
+}
+
+function safeReaddir(fs, dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_e) {
+    return [];
+  }
+}
+
+function safeExists(fs, p) {
+  try {
+    return fs.existsSync(p);
+  } catch (_e) {
+    return false;
+  }
+}
+
+function safeSize(fs, p) {
+  try {
+    return fs.statSync(p).size;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+/** List immediate subdirectory names of `dir` (empty array on any error). */
+function listSubdirs(fs, path, dir) {
+  return safeReaddir(fs, dir)
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+}
+
+/**
+ * Recursively collect *.db / *.sqlite / *.sqlite3 files under `root` up to
+ * `maxDepth`. Used for best-effort Apps (DingTalk / Feishu) whose internal
+ * layout is proprietary and version-volatile. Bounded so a huge tree can't
+ * stall a readiness probe.
+ */
+function collectDbFiles(fs, path, root, maxDepth, out, depth) {
+  if (depth > maxDepth) return out;
+  for (const e of safeReaddir(fs, root)) {
+    const fp = path.join(root, e.name);
+    if (e.isFile() && /\.(db|sqlite|sqlite3)$/i.test(e.name)) {
+      out.push(fp);
+    } else if (e.isDirectory()) {
+      collectDbFiles(fs, path, fp, maxDepth, out, depth + 1);
+    }
+  }
+  return out;
+}
+
+// ─── per-App discovery ─────────────────────────────────────────────────────
+
+/**
+ * WeChat desktop — handles BOTH the 4.x (`xwechat_files`) and 3.x
+ * (`WeChat Files`) layouts. Both store SQLCipher-encrypted DBs.
+ */
+function discoverWeChat({ fs, path, home, env }) {
+  const accounts = [];
+  let layout = null;
+
+  // ── 4.x: ~/Documents/xwechat_files/<wxid>_<n>/db_storage/ ──
+  const v4Root = path.join(home, "Documents", "xwechat_files");
+  if (safeExists(fs, v4Root)) {
+    for (const name of listSubdirs(fs, path, v4Root)) {
+      // account dirs look like wxid_xxx_1234 ; skip all_users / login etc.
+      if (!/^wxid_/.test(name)) continue;
+      const storage = path.join(v4Root, name, "db_storage");
+      if (!safeExists(fs, storage)) continue;
+      const dbs = [];
+      const msgDir = path.join(storage, "message");
+      for (const e of safeReaddir(fs, msgDir)) {
+        if (e.isFile() && /^message_\d+\.db$/i.test(e.name)) {
+          dbs.push(mkDb(path.join(msgDir, e.name), "message", "私聊/群聊消息", true, fs));
+        }
+        if (e.isFile() && /^biz_message_\d+\.db$/i.test(e.name)) {
+          dbs.push(mkDb(path.join(msgDir, e.name), "biz-message", "公众号消息", true, fs));
+        }
+      }
+      const contactDb = path.join(storage, "contact", "contact.db");
+      if (safeExists(fs, contactDb)) {
+        dbs.push(mkDb(contactDb, "contact", "联系人", true, fs));
+      }
+      const snsDb = path.join(storage, "sns", "sns.db");
+      if (safeExists(fs, snsDb)) dbs.push(mkDb(snsDb, "sns", "朋友圈", true, fs));
+      const favDb = path.join(storage, "favorite", "favorite.db");
+      if (safeExists(fs, favDb)) dbs.push(mkDb(favDb, "favorite", "收藏", true, fs));
+      if (dbs.length > 0) {
+        layout = "4.x";
+        accounts.push({ id: name.replace(/_\d+$/, ""), root: path.join(v4Root, name), dbs });
+      }
+    }
+  }
+
+  // ── 3.x: ~/Documents/WeChat Files/<wxid>/Msg/ ──
+  const v3Roots = [
+    path.join(home, "Documents", "WeChat Files"),
+    env.APPDATA ? path.join(env.APPDATA, "Tencent", "WeChat", "WeChat Files") : null,
+  ].filter(Boolean);
+  for (const root of v3Roots) {
+    if (!safeExists(fs, root)) continue;
+    for (const name of listSubdirs(fs, path, root)) {
+      if (name === "All Users" || name === "Applet" || name === "WMPF") continue;
+      const msgDir = path.join(root, name, "Msg");
+      const multiDir = path.join(msgDir, "Multi");
+      const dbs = [];
+      for (const e of safeReaddir(fs, multiDir)) {
+        if (e.isFile() && /^MSG\d+\.db$/i.test(e.name)) {
+          dbs.push(mkDb(path.join(multiDir, e.name), "message", "私聊/群聊消息", true, fs));
+        }
+      }
+      const microMsg = path.join(msgDir, "MicroMsg.db");
+      if (safeExists(fs, microMsg)) {
+        dbs.push(mkDb(microMsg, "contact", "联系人", true, fs));
+      }
+      if (dbs.length > 0) {
+        layout = layout || "3.x";
+        accounts.push({ id: name, root: path.join(root, name), dbs });
+      }
+    }
+  }
+
+  return finalize("wechat-pc", accounts, {
+    layout,
+    encryptedNote:
+      "微信本地库为 SQLCipher 加密，需提取数据库密钥后才能解密读取（见 wechat 密钥提取）",
+  });
+}
+
+/** QQ NT desktop — ~/Documents/Tencent Files/<uin>/nt_qq/nt_db/nt_msg.db */
+function discoverQQ({ fs, path, home, env }) {
+  const accounts = [];
+  const roots = [
+    path.join(home, "Documents", "Tencent Files"),
+    env.APPDATA ? path.join(env.APPDATA, "Tencent", "QQ") : null,
+  ].filter(Boolean);
+  for (const root of roots) {
+    if (!safeExists(fs, root)) continue;
+    for (const name of listSubdirs(fs, path, root)) {
+      // per-uin dirs are all-digit; skip nt_qq (global) etc.
+      if (!/^\d+$/.test(name)) continue;
+      const ntDb = path.join(root, name, "nt_qq", "nt_db", "nt_msg.db");
+      if (safeExists(fs, ntDb)) {
+        const dbs = [mkDb(ntDb, "message", "私聊/群聊消息", true, fs)];
+        const grpInfo = path.join(root, name, "nt_qq", "nt_db", "group_info.db");
+        if (safeExists(fs, grpInfo)) dbs.push(mkDb(grpInfo, "group-info", "群信息", true, fs));
+        const profile = path.join(root, name, "nt_qq", "nt_db", "profile_info.db");
+        if (safeExists(fs, profile)) dbs.push(mkDb(profile, "profile", "好友资料", true, fs));
+        accounts.push({ id: name, root: path.join(root, name, "nt_qq"), dbs });
+      }
+    }
+  }
+  return finalize("qq-pc", accounts, {
+    encryptedNote:
+      "QQ NT 本地库为 SQLCipher 加密（数字混淆列 + protobuf 消息体），需密钥解密",
+  });
+}
+
+/** DingTalk / Feishu — proprietary layout, best-effort recursive scan. */
+function discoverGenericIm(appName, roots, { fs, path }) {
+  const accounts = [];
+  for (const root of roots) {
+    if (!safeExists(fs, root)) continue;
+    const files = collectDbFiles(fs, path, root, 5, [], 0);
+    // Heuristic: message DBs are the larger files whose name hints at chat.
+    const dbs = files
+      .filter((fp) => !/\b(fts|index|cache|emoji|emoticon|head_image)\b/i.test(fp))
+      .map((fp) => {
+        const base = path.basename(fp);
+        const isMsg = /msg|message|chat|conversation|im_/i.test(base);
+        return mkDb(fp, isMsg ? "message" : "other", base, /* encrypted */ false, fs);
+      })
+      .sort((a, b) => b.sizeBytes - a.sizeBytes);
+    if (dbs.length > 0) {
+      accounts.push({ id: "default", root, dbs });
+    }
+  }
+  return finalize(appName, accounts, {
+    encryptedNote:
+      "桌面本地库为私有结构、可能加密、随版本变化；优先尝试明文直读，必要时先解密",
+    bestEffort: true,
+  });
+}
+
+function discoverDingTalk({ fs, path, home, env }) {
+  const roots = [
+    env.APPDATA ? path.join(env.APPDATA, "DingTalk") : null,
+    path.join(home, "Documents", "DingTalk"),
+  ].filter(Boolean);
+  return discoverGenericIm("dingtalk-pc", roots, { fs, path });
+}
+
+function discoverFeishu({ fs, path, home, env }) {
+  const roots = [
+    env.APPDATA ? path.join(env.APPDATA, "Feishu") : null,
+    env.APPDATA ? path.join(env.APPDATA, "Lark") : null,
+  ].filter(Boolean);
+  return discoverGenericIm("feishu-pc", roots, { fs, path });
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────────
+
+function mkDb(p, purpose, label, encrypted, fs) {
+  return {
+    path: p,
+    purpose, // message | biz-message | contact | sns | favorite | group-info | profile | other
+    label,
+    encrypted: !!encrypted,
+    sizeBytes: safeSize(fs, p),
+  };
+}
+
+/**
+ * Common tail: pick the primary message DB (largest message-purpose file
+ * across all accounts) and compute the installed flag + summary.
+ */
+function finalize(app, accounts, extra = {}) {
+  const allDbs = accounts.flatMap((a) => a.dbs);
+  const messageDbs = allDbs
+    .filter((d) => d.purpose === "message")
+    .sort((a, b) => b.sizeBytes - a.sizeBytes);
+  const primaryDb = (messageDbs[0] || allDbs[0] || null);
+  const anyEncrypted = allDbs.some((d) => d.encrypted);
+  return {
+    app,
+    installed: accounts.length > 0,
+    accounts,
+    primaryDb: primaryDb ? primaryDb.path : null,
+    primaryDbInfo: primaryDb,
+    encrypted: anyEncrypted,
+    dbCount: allDbs.length,
+    layout: extra.layout || null,
+    bestEffort: !!extra.bestEffort,
+    note: accounts.length > 0 ? extra.encryptedNote || null : "未检测到本地数据（可能未安装或未登录）",
+  };
+}
+
+const DISCOVERERS = Object.freeze({
+  "wechat-pc": discoverWeChat,
+  "qq-pc": discoverQQ,
+  "dingtalk-pc": discoverDingTalk,
+  "feishu-pc": discoverFeishu,
+});
+
+/**
+ * Discover one App's local databases.
+ *
+ * @param {string} appKey  one of SUPPORTED_APPS
+ * @param {object} [deps]  { fs, path, platform, home, env } — inject for tests
+ * @returns {DiscoveryResult}
+ *
+ * @typedef {object} DiscoveryResult
+ * @property {string}  app
+ * @property {boolean} installed       any account+DB found?
+ * @property {Array}   accounts        [{ id, root, dbs: [{path,purpose,label,encrypted,sizeBytes}] }]
+ * @property {string|null} primaryDb   best message DB path to point sync at
+ * @property {object|null} primaryDbInfo
+ * @property {boolean} encrypted       any discovered DB is encrypted?
+ * @property {number}  dbCount
+ * @property {string|null} layout      version layout hint (wechat: "4.x"/"3.x")
+ * @property {boolean} bestEffort      heuristic discovery (dingtalk/feishu)?
+ * @property {string|null} note
+ */
+function discover(appKey, deps = {}) {
+  const fn = DISCOVERERS[appKey];
+  if (!fn) {
+    return {
+      app: appKey,
+      installed: false,
+      accounts: [],
+      primaryDb: null,
+      primaryDbInfo: null,
+      encrypted: false,
+      dbCount: 0,
+      layout: null,
+      bestEffort: false,
+      note: `不支持的 App: ${appKey}`,
+    };
+  }
+  try {
+    return fn(makeDeps(deps));
+  } catch (err) {
+    // Discovery must never throw into a readiness probe.
+    return {
+      app: appKey,
+      installed: false,
+      accounts: [],
+      primaryDb: null,
+      primaryDbInfo: null,
+      encrypted: false,
+      dbCount: 0,
+      layout: null,
+      bestEffort: false,
+      note: `自动发现出错：${err && err.message ? err.message : String(err)}`,
+    };
+  }
+}
+
+module.exports = {
+  discover,
+  SUPPORTED_APPS,
+  // exported for unit tests
+  _internals: { collectDbFiles, finalize, mkDb },
+};

package/lib/adapters/qq-pc/index.js

@@ -37,6 +37,9 @@ class QQPcAdapter {
   constructor(opts = {}) {
     this._dbPath = opts.dbPath || null;
     this._key = opts.key || null;
+    // QQ NT passphrase (16-char ASCII from qq-win-db-key). When present, sync
+    // routes through the Python sidecar (decrypt + protobuf parse).
+    this._passphrase = opts.passphrase || null;
 
     this.name = NAME;
     this.version = VERSION;
@@ -58,20 +61,53 @@ class QQPcAdapter {
     this._deps = {
       fs,
       dbDriverFactory: opts.dbDriverFactory || null,
+      // DI seam: tests inject a fake QQ sidecar collector; default lazy-loads
+      // the forensics-bridge invoker.
+      qqCollector: opts.qqCollector || null,
+      discoveryDeps: opts.discoveryDeps || undefined,
     };
   }
 
+  _autoDiscover() {
+    if (this._discovered !== undefined) return this._discovered;
+    try {
+      // eslint-disable-next-line global-require
+      const { discover } = require("../_pc-local-discovery");
+      this._discovered = discover("qq-pc", this._deps.discoveryDeps || {});
+    } catch (_e) {
+      this._discovered = null;
+    }
+    return this._discovered;
+  }
+
+  _resolveDiscoveredDbPath() {
+    const disc = this._autoDiscover();
+    return disc && disc.installed && disc.primaryDb ? disc.primaryDb : null;
+  }
+
   async authenticate(ctx = {}) {
     if (ctx && ctx.readinessOnly) {
       if (this._dbPath) return { ok: true, mode: "configured" };
+      const disc = this._autoDiscover();
+      if (disc && disc.installed) {
+        return {
+          ok: false,
+          reason: "DB_FOUND_NEEDS_KEY",
+          message: `已找到本机 QQ 库（${disc.accounts.length} 个账号，主库 ${disc.primaryDb}）`,
+          discovered: disc,
+        };
+      }
       return {
         ok: false,
-        reason: "DB_NOT_PULLED",
-        message:
-          "qq-pc: 需提供电脑版 QQ 的 nt_msg.db 路径（加密库需先解密或提供 key）",
+        reason: "APP_NOT_INSTALLED",
+        message: (disc && disc.note) || "未检测到本机 QQ NT 数据（可能未安装或未登录）",
       };
     }
-    const dbPath = (ctx && ctx.inputPath) || (ctx && ctx.dbPath) || this._dbPath;
+    const dbPath =
+      (ctx && ctx.inputPath) ||
+      (ctx && ctx.dbPath) ||
+      this._dbPath ||
+      this._resolveDiscoveredDbPath();
     if (dbPath) {
       try {
         this._deps.fs.accessSync(dbPath, this._deps.fs.constants.R_OK);
@@ -84,10 +120,19 @@ class QQPcAdapter {
       }
       return { ok: true, mode: "sqlite" };
     }
+    const disc = this._autoDiscover();
+    if (disc && disc.installed) {
+      return {
+        ok: false,
+        reason: "DB_FOUND_NEEDS_KEY",
+        message: `已找到本机 QQ 库（主库 ${disc.primaryDb}），需解密密钥`,
+        discovered: disc,
+      };
+    }
     return {
       ok: false,
-      reason: "DB_NOT_PULLED",
-      message: "qq-pc.authenticate: needs opts.dbPath / inputPath (nt_msg.db)",
+      reason: "APP_NOT_INSTALLED",
+      message: "qq-pc.authenticate: 未检测到本机 QQ NT 库，也未提供 dbPath / inputPath",
     };
   }
 
@@ -96,9 +141,18 @@ class QQPcAdapter {
   }
 
   async *sync(opts = {}) {
-    const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
+    // Sidecar path: with a QQ NT passphrase (from qq-win-db-key), decrypt +
+    // parse the encrypted nt_msg.db in Python and yield readable messages.
+    const passphrase = opts.passphrase || this._passphrase || null;
+    if (passphrase || opts.mode === "sidecar") {
+      yield* this._syncViaSidecar(opts, passphrase);
+      return;
+    }
+
+    const dbPath =
+      opts.dbPath || opts.inputPath || this._dbPath || this._resolveDiscoveredDbPath();
     if (!dbPath) {
-      throw new Error("qq-pc.sync: needs opts.dbPath / opts.inputPath (nt_msg.db)");
+      throw new Error("qq-pc.sync: 未找到本机 QQ NT 库且未提供 opts.dbPath / opts.inputPath（或提供 opts.passphrase 走 sidecar 解密）");
     }
     if (!this._deps.fs.existsSync(dbPath)) return;
 
@@ -139,6 +193,60 @@ class QQPcAdapter {
     }
   }
 
+  // Sidecar path: forensics-bridge qq_nt.collect decrypts nt_msg.db (with the
+  // qq-win-db-key passphrase) + parses c2c/group protobuf bodies → readable
+  // messages, which we map into the same payload normalizeMessage consumes.
+  async *_syncViaSidecar(opts = {}, passphrase) {
+    let collect = this._deps.qqCollector;
+    if (!collect) {
+      // eslint-disable-next-line global-require
+      collect = require("./qqnt-sidecar").collectQqNt;
+    }
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : undefined;
+    const result = await collect({
+      passphrase,
+      key: opts.key || this._key || undefined,
+      dbPath: opts.dbPath || this._dbPath || this._resolveDiscoveredDbPath() || undefined,
+      limit,
+      pythonExe: opts.pythonExe,
+      bridgeDir: opts.bridgeDir,
+      timeoutMs: opts.timeoutMs,
+      onProgress:
+        typeof opts.onProgress === "function"
+          ? (m) => { try { opts.onProgress({ phase: "qq-nt", adapter: NAME, ...m }); } catch (_e) { /* best-effort */ } }
+          : undefined,
+      _supervisorFactory: opts._supervisorFactory,
+    });
+    const messages = (result && Array.isArray(result.messages)) ? result.messages : [];
+    const fallbackCapturedAt = Date.now();
+    let emitted = 0;
+    for (const m of messages) {
+      if (!m || typeof m !== "object") continue;
+      const isGroup = m.kind === "group";
+      const createdTimeMs =
+        typeof m.createTime === "number" && m.createTime > 0 ? m.createTime * 1000 : null;
+      const payload = {
+        kind: KIND_MESSAGE,
+        text: typeof m.text === "string" ? m.text : "",
+        peerUin: m.peer != null ? String(m.peer) : null,
+        peerName: m.conversationName || null,   // group name / c2c peer nickname (best-effort)
+        senderUin: m.senderUin != null ? String(m.senderUin) : null,
+        senderName: m.senderName || null,
+        isGroup,
+        type: typeof m.type === "number" ? m.type : null,
+        createdTimeMs,
+      };
+      yield {
+        adapter: NAME,
+        kind: KIND_MESSAGE,
+        originalId: m.originalId || stableOriginalId(`${m.peer}-${createdTimeMs}-${emitted}`),
+        capturedAt: createdTimeMs || fallbackCapturedAt,
+        payload,
+      };
+      emitted += 1;
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) {
       throw new Error("QQPcAdapter.normalize: payload missing");
@@ -176,7 +284,9 @@ class QQPcAdapter {
           platform: "qq",
           source: "pc-nt",
           peerUin: p.peerUin || null,
+          ...(p.peerName ? { peerName: p.peerName } : {}),
           senderUin: p.senderUin || null,
+          ...(p.senderName ? { senderName: p.senderName } : {}),
           isGroup: !!p.isGroup,
           qqMsgType: typeof p.type === "number" ? p.type : null,
           // Full raw row preserved — protobuf bodies + unknown columns — so a

package/lib/adapters/qq-pc/qqnt-sidecar.js

@@ -0,0 +1,109 @@
+"use strict";
+
+/**
+ * QQ NT collection bridge — invokes the forensics-bridge Python sidecar's
+ * `qq_nt.collect` method (skip 1024-byte preamble + SQLCipher-4 decrypt with
+ * the qq-win-db-key passphrase + parse c2c/group protobuf message bodies) and
+ * returns the decrypted, readable messages to the node adapter.
+ *
+ * The key is the QQ NT passphrase (a 16-char ASCII string like "5{sww#,6aq=)8=A@"
+ * extracted by qq-win-db-key). Pass it as opts.passphrase. Decryption + protobuf
+ * text extraction run in Python (cryptography), sidestepping the host-node
+ * bs3mc ABI problem (node never opens the encrypted DB).
+ *
+ * Resolution (overridable for tests / packaging):
+ *   - python exe:  opts.pythonExe → env CC_PDH_PYTHON → "python" / "python3"
+ *   - bridge dir:  opts.bridgeDir → env CC_PDH_BRIDGE_DIR → sibling package
+ */
+
+const path = require("node:path");
+const { existsSync } = require("node:fs");
+
+function resolveBridgeDir(explicit) {
+  if (explicit) return explicit;
+  if (process.env.CC_PDH_BRIDGE_DIR) return process.env.CC_PDH_BRIDGE_DIR;
+  // lib/adapters/qq-pc → up to packages/, then sibling bridge package.
+  return path.resolve(__dirname, "../../../../personal-data-hub-bridge");
+}
+
+function pythonCandidates(explicit) {
+  const list = [];
+  if (explicit) list.push(explicit);
+  if (process.env.CC_PDH_PYTHON) list.push(process.env.CC_PDH_PYTHON);
+  list.push(process.platform === "win32" ? "python" : "python3");
+  list.push(process.platform === "win32" ? "python3" : "python");
+  return [...new Set(list)];
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.passphrase]  QQ NT key (ASCII passphrase from qq-win-db-key)
+ * @param {string} [opts.key]         alternatively a hex key
+ * @param {string} [opts.dbPath]      nt_msg.db path (sidecar auto-discovers if omitted)
+ * @param {number} [opts.limit]
+ * @param {string} [opts.pythonExe]
+ * @param {string} [opts.bridgeDir]
+ * @param {number} [opts.timeoutMs]
+ * @param {(msg:object)=>void} [opts.onProgress]
+ * @param {object} [opts._supervisorFactory]  test seam
+ * @returns {Promise<{account:string,messageCount:number,c2c:number,group:number,messages:object[]}>}
+ */
+async function collectQqNt(opts = {}) {
+  const bridgeDir = resolveBridgeDir(opts.bridgeDir);
+  const makeSupervisor =
+    opts._supervisorFactory ||
+    ((command, cwd) => {
+      // eslint-disable-next-line global-require
+      const { SidecarSupervisor } = require("../../sidecar");
+      return new SidecarSupervisor({
+        command,
+        cwd,
+        defaultTimeoutMs: opts.timeoutMs || 120_000,
+        healthCheckIntervalMs: 0,
+      });
+    });
+
+  if (!opts._supervisorFactory && !existsSync(bridgeDir)) {
+    const e = new Error(
+      `qq-pc: forensics-bridge not found at ${bridgeDir} (set CC_PDH_BRIDGE_DIR)`,
+    );
+    e.code = "BRIDGE_NOT_FOUND";
+    throw e;
+  }
+
+  const params = {};
+  if (Number.isInteger(opts.limit) && opts.limit > 0) params.limit = opts.limit;
+  if (opts.passphrase) params.passphrase = opts.passphrase;
+  else if (opts.key) params.key = opts.key;
+  if (opts.dbPath) params.db_path = opts.dbPath;
+
+  let lastErr = null;
+  for (const py of pythonCandidates(opts.pythonExe)) {
+    const sup = makeSupervisor([py, "-m", "forensics_bridge.ipc_server"], bridgeDir);
+    try {
+      await sup.start({ readyTimeoutMs: opts.readyTimeoutMs || 15_000 });
+      const result = await sup.invoke("qq_nt.collect", params, {
+        timeoutMs: opts.timeoutMs || 120_000,
+        onProgress: opts.onProgress,
+      });
+      try { await sup.stop(); } catch (_e) { /* best-effort */ }
+      return result;
+    } catch (err) {
+      lastErr = err;
+      try { await sup.stop(); } catch (_e) { /* best-effort */ }
+      const msg = (err && err.message) || "";
+      // Real QQ-side failures (key/db) surface immediately; sidecar-availability
+      // problems (missing python / cryptography / spawn death) → try next python.
+      const isDataError = /KEY_REQUIRED|KEY_VERIFY|APP_NOT|DB_TOO|BAD_LAYOUT/i.test(msg);
+      if (isDataError) throw err;
+    }
+  }
+  const e = new Error(
+    `qq-pc: could not run forensics-bridge sidecar (tried ${pythonCandidates(opts.pythonExe).join(", ")}). ` +
+      `Install Python 3.11+ with 'cryptography', or set CC_PDH_PYTHON. Last error: ${lastErr && lastErr.message}`,
+  );
+  e.code = "SIDECAR_UNAVAILABLE";
+  throw e;
+}
+
+module.exports = { collectQqNt, _internals: { resolveBridgeDir, pythonCandidates } };