@chainlesschain/personal-data-hub 0.3.9 → 0.4.0

package/lib/adapter-readiness.js

@@ -0,0 +1,257 @@
+/**
+ * Adapter readiness — turn an adapter's `authenticate()` reason code into a
+ * human-facing "can I collect right now, and if not why" descriptor.
+ *
+ * Why this exists: `AdapterRegistry.list()` only reports static metadata
+ * (name / version / sensitivity). Every adapter's `healthCheck()` returns a
+ * lenient `{ ok: true }` (snapshot-mode adapters MUST stay healthy so the
+ * registry's pre-sync health gate doesn't block a legitimate
+ * `sync-adapter --input <path>` call — the inputPath only arrives at sync
+ * time, after the gate). The upshot: the UI showed "healthy" for adapters
+ * that in fact cannot collect a single row because no snapshot / cookie /
+ * device DB has been provided yet. Users saw "配置正常却采不到数据".
+ *
+ * The real readiness signal already lives in `authenticate()` — it returns
+ * `{ ok: false, reason: "NO_INPUT" | "DB_NOT_PULLED" | ... }`. This module
+ * is the lookup table that maps those reason codes to:
+ *   - status:     ready | needs_setup | unavailable | error
+ *   - category:   how this source is collected (local / snapshot / device / ...)
+ *   - message:    short Chinese explanation for the UI
+ *   - actionHint: what the user should do next
+ *
+ * `AdapterRegistry.readiness()` calls `authenticate({ readinessOnly: true })`
+ * (a cheap, no-network probe — adapters with expensive auth, e.g. email IMAP
+ * login / WeChat frida key extraction, short-circuit on that flag) and feeds
+ * the reason through `describeReadiness()`.
+ */
+
+"use strict";
+
+// Collection-strategy categories (drives the UI grouping + what action the
+// user must take). Distinct from extractMode, which is the adapter's
+// internal "where do bytes come from" classifier.
+const READINESS_CATEGORY = Object.freeze({
+  LOCAL: "local", // 本机直接读取（浏览器/VSCode/git/本地文件…）
+  SNAPSHOT: "snapshot", // 需手机端 App 内采集后回传快照
+  DEVICE: "device", // 需 root / 本地 DB 解密后拉取数据库
+  CREDENTIAL: "credential", // 需登录态 / 账号凭据
+  PLATFORM: "platform", // 平台或运行环境不支持
+});
+
+// status taxonomy
+const READINESS_STATUS = Object.freeze({
+  READY: "ready",
+  NEEDS_SETUP: "needs_setup",
+  UNAVAILABLE: "unavailable",
+  ERROR: "error",
+});
+
+/**
+ * reason code → descriptor. `appendDetail: true` means the caller may append
+ * the adapter's own `message`/`error` string in parentheses for extra context.
+ */
+const REASONS = Object.freeze({
+  // ── snapshot-mode (Android in-app capture) ──────────────────────────────
+  NO_INPUT: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.SNAPSHOT,
+    message: "尚无可采集的数据：需先在手机 App 内采集并回传快照",
+    actionHint: "在 Android 端打开对应平台采集页完成一次采集",
+  },
+  INPUT_PATH_UNREADABLE: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.SNAPSHOT,
+    message: "快照文件不可读（路径不存在或无权限）",
+    actionHint: "重新采集生成快照，或检查文件路径",
+    appendDetail: true,
+  },
+  INPUT_PATH_REQUIRED: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.SNAPSHOT,
+    message: "需要提供快照文件路径",
+    actionHint: "先在设备端采集生成快照",
+  },
+  NO_FILE: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.LOCAL,
+    message: "尚未选择文件：从来源导出数据后，选择文件即可采集",
+    actionHint: "点「选择文件采集」选中导出的文件",
+  },
+
+  // ── device-pull (root / local DB) ───────────────────────────────────────
+  DB_NOT_PULLED: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "尚未拉取到本地数据库：需 root 设备或本地解密后导入 DB",
+    actionHint: "通过 ADB / 本地 DB 解密导出数据库后再同步",
+    appendDetail: true,
+  },
+  NO_KEY_PROVIDER: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "缺少数据库解密密钥提供方",
+    actionHint: "配置密钥提取（frida / 本地密钥）后重试",
+  },
+  EMPTY_KEY: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "解密密钥为空，无法解密数据库",
+    actionHint: "重新提取数据库密钥",
+  },
+  KEY_PROVIDER_THREW: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "提取数据库密钥失败",
+    actionHint: "检查 frida / 设备连接 / 密钥来源",
+    appendDetail: true,
+  },
+  FRIDA_NEEDS_WXID: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "frida 模式需要 wxid 才能提取密钥",
+    actionHint: "提供登录账号的 wxid",
+  },
+
+  // ── credential (login / account config) ─────────────────────────────────
+  AUTH_FAILED: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message: "登录认证失败（账号或授权码错误）",
+    actionHint: "重新填写账号 / 授权码",
+    appendDetail: true,
+  },
+  CONNECTION_FAILED: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message: "连接服务器失败",
+    actionHint: "检查网络 / 服务器地址",
+    appendDetail: true,
+  },
+  INVALID_COOKIE: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message: "登录态 Cookie 无效或已过期",
+    actionHint: "重新在 App / 网页登录抓取 Cookie",
+  },
+  NO_ACCOUNT_PIN: accountReason("缺少账号标识（pin）"),
+  NO_ACCOUNT_USER_ID: accountReason("缺少账号标识（user id）"),
+  NO_ACCOUNT_USERID: accountReason("缺少账号标识（userId）"),
+  NO_ACCOUNT_UID: accountReason("缺少账号标识（uid）"),
+  NO_ACCOUNT_QQ: accountReason("缺少 QQ 账号标识"),
+  NO_ACCOUNT_USERNAME: accountReason("缺少账号用户名"),
+  NO_ACCOUNT_DEVICE_ID: accountReason("缺少设备标识（device id）"),
+
+  // ── local (host filesystem present?) ────────────────────────────────────
+  NO_DATA_ROOTS: localMissing("未配置可扫描的数据目录"),
+  NO_CODE_ROOTS: localMissing("未配置可扫描的代码目录"),
+  NO_GIT_REPOS: localMissing("未发现 git 仓库"),
+  NO_HISTORY_SOURCES: localMissing("未发现命令行历史文件"),
+  PROFILE_NOT_FOUND: localMissing("未找到浏览器配置（未安装或从未登录）"),
+  PROFILE_PATH_UNRESOLVED: localError("无法解析浏览器配置路径"),
+  VSCODE_NOT_FOUND: localMissing("未找到 VSCode 数据"),
+  VSCODE_ROOT_UNRESOLVED: localError("无法解析 VSCode 路径"),
+  RECENT_DIR_NOT_FOUND: localMissing("未找到最近使用记录目录"),
+
+  // ── platform / environment ──────────────────────────────────────────────
+  PLATFORM_UNSUPPORTED: {
+    status: READINESS_STATUS.UNAVAILABLE,
+    category: READINESS_CATEGORY.PLATFORM,
+    message: "当前操作系统不支持此数据源",
+    actionHint: null,
+  },
+  ENV_UNSUPPORTED: {
+    status: READINESS_STATUS.UNAVAILABLE,
+    category: READINESS_CATEGORY.PLATFORM,
+    message: "当前运行环境不支持此数据源",
+    actionHint: null,
+    appendDetail: true,
+  },
+
+  // ── probe-level (set by the registry, not adapters) ─────────────────────
+  PROBE_TIMEOUT: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message: "就绪检查超时（适配器可能已配置但探测无响应）",
+    actionHint: "稍后重试，或直接尝试一次同步",
+  },
+  PROBE_ERROR: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message: "就绪检查出错",
+    actionHint: "查看日志 / 直接尝试一次同步",
+    appendDetail: true,
+  },
+  UNKNOWN: {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message: "未就绪（未知原因）",
+    actionHint: "查看 lastError / 尝试一次同步以获取详细错误",
+    appendDetail: true,
+  },
+});
+
+function accountReason(message) {
+  return {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.CREDENTIAL,
+    message,
+    actionHint: "在数据源设置中补全账号信息",
+  };
+}
+
+function localMissing(message) {
+  return {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.LOCAL,
+    message,
+    actionHint: "在设置中指定路径，或确认数据源已在本机存在",
+  };
+}
+
+function localError(message) {
+  return {
+    status: READINESS_STATUS.ERROR,
+    category: READINESS_CATEGORY.LOCAL,
+    message,
+    actionHint: "检查本机路径配置",
+  };
+}
+
+// extractMode → category fallback for the "ready" case (no failure reason).
+const MODE_TO_CATEGORY = Object.freeze({
+  "file-import": READINESS_CATEGORY.LOCAL,
+  "device-pull": READINESS_CATEGORY.DEVICE,
+  "web-api": READINESS_CATEGORY.SNAPSHOT,
+});
+
+function categoryForMode(extractMode) {
+  return MODE_TO_CATEGORY[extractMode] || READINESS_CATEGORY.LOCAL;
+}
+
+/**
+ * Map an adapter `authenticate()` reason code to a UI descriptor.
+ * Unknown codes fall back to the UNKNOWN descriptor (so a new adapter
+ * reason never crashes the readiness report — it just shows generically).
+ *
+ * @param {string} reason  reason code from authenticate()
+ * @returns {{status: string, category: string, message: string, actionHint: string|null, appendDetail: boolean}}
+ */
+function describeReadiness(reason) {
+  const d = (reason && REASONS[reason]) || REASONS.UNKNOWN;
+  return {
+    status: d.status,
+    category: d.category,
+    message: d.message,
+    actionHint: d.actionHint || null,
+    appendDetail: !!d.appendDetail,
+  };
+}
+
+module.exports = {
+  READINESS_CATEGORY,
+  READINESS_STATUS,
+  describeReadiness,
+  categoryForMode,
+  // exposed for tests / introspection
+  READINESS_REASONS: REASONS,
+};

package/lib/adapters/_local-im-db-reader.js

@@ -0,0 +1,218 @@
+"use strict";
+
+/**
+ * Generic "honest" local IM-database reader — shared by device-pull desktop
+ * IM adapters whose schema we CAN'T verify without a real device (钉钉 /
+ * 飞书). Ported from the qq-pc honest pattern:
+ *
+ *   - open plaintext OR SQLCipher-with-key
+ *   - DISCOVER message-like tables via sqlite_master + a name pattern
+ *     (proprietary clients shard / rename tables across versions, so we
+ *     never hardcode one table name)
+ *   - per table, resolve time/sender/peer/content via candidate lists
+ *     (readable names first, then version-specific guesses)
+ *   - extract text ONLY when the resolved content column is a real string;
+ *     otherwise text=null but the FULL raw row is preserved in `rawRow`
+ *   - LOUD diagnostic: which tables matched, which columns resolved, counts
+ *     — so the user/UI sees what worked instead of silently getting 0 rows
+ *
+ * This is deliberately best-effort. The reliable part is "open + discover +
+ * preserve everything + report"; exact text extraction for encrypted /
+ * protobuf bodies is real-device tuning (extend colCandidates per platform).
+ *
+ * Test seam: inject `_databaseClass`.
+ */
+
+function loadDatabaseClass() {
+  for (const mod of ["better-sqlite3-multiple-ciphers", "better-sqlite3"]) {
+    let cls;
+    try {
+      // eslint-disable-next-line global-require
+      cls = require(mod);
+    } catch (_e) {
+      continue;
+    }
+    try {
+      const probe = new cls(":memory:");
+      probe.close();
+      return cls;
+    } catch (_e) {
+      // ABI mismatch — try next
+    }
+  }
+  throw new Error(
+    "local-im-db-reader: neither better-sqlite3-multiple-ciphers nor better-sqlite3 loaded — both ABI-mismatched",
+  );
+}
+
+function trySelect(db, sql) {
+  try {
+    return db.prepare(sql).all();
+  } catch (_e) {
+    return null;
+  }
+}
+
+function pickCol(columns, candidates) {
+  for (const c of candidates) {
+    if (columns.has(c)) return c;
+  }
+  return null;
+}
+
+function normalizeEpochMs(v) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return null;
+  if (v > 1e15) return Math.floor(v / 1000); // µs
+  if (v > 1e12) return Math.floor(v); // ms
+  return Math.floor(v * 1000); // seconds
+}
+
+/**
+ * Open a local IM DB. Plaintext when no key; SQLCipher (try compat 4 then 3)
+ * when a key is supplied.
+ */
+function openLocalDb(dbPath, opts = {}) {
+  const Database = opts._databaseClass || loadDatabaseClass();
+  const key = typeof opts.key === "string" && opts.key.length > 0 ? opts.key : null;
+  if (!key) {
+    const db = new Database(dbPath, { readonly: true });
+    try {
+      db.prepare("SELECT count(*) AS n FROM sqlite_master").get();
+      return { db, mode: "plaintext" };
+    } catch (err) {
+      try { db.close(); } catch (_e) { /* ignore */ }
+      const e = new Error(
+        `local-im-db-reader: not plaintext SQLite (decrypt first, or pass key): ${err.message}`,
+      );
+      e.code = "IM_DB_NEEDS_KEY";
+      throw e;
+    }
+  }
+  const keyExpr = /^[0-9a-fA-F]{64}$/.test(key) ? `"x'${key}'"` : `'${key}'`;
+  for (const compat of [4, 3]) {
+    let db;
+    try {
+      db = new Database(dbPath, { readonly: true });
+      db.pragma(`key = ${keyExpr}`);
+      db.exec(`PRAGMA cipher_compatibility = ${compat}`);
+      db.prepare("SELECT count(*) AS n FROM sqlite_master").get();
+      return { db, mode: `sqlcipher-v${compat}` };
+    } catch (_err) {
+      if (db) { try { db.close(); } catch (_e) { /* ignore */ } }
+    }
+  }
+  const e = new Error("local-im-db-reader: SQLCipher open failed (key wrong, or decrypt first)");
+  e.code = "IM_DB_DECRYPT_FAILED";
+  throw e;
+}
+
+const DEFAULT_COL_CANDIDATES = Object.freeze({
+  msgId: ["msgId", "msg_id", "messageId", "message_id", "localId", "id", "_id"],
+  time: ["msgTime", "createTime", "create_time", "timestamp", "time", "sendTime", "send_time", "ctime"],
+  sender: ["senderId", "sender_id", "senderUid", "fromId", "from_id", "from", "sender", "uid"],
+  peer: ["peerId", "peer_id", "conversationId", "conversation_id", "chatId", "chat_id", "sessionId", "talker"],
+  content: ["content", "text", "msgContent", "message", "body", "summary"],
+});
+
+/**
+ * Discover + read message-like tables.
+ *
+ * @param {string} dbPath
+ * @param {object} opts
+ * @param {string} [opts.key]
+ * @param {any}    [opts._databaseClass]
+ * @param {RegExp} [opts.tablePattern]  matches candidate table names (default /msg|message|chat|conversation/i)
+ * @param {object} [opts.colCandidates] merged over DEFAULT_COL_CANDIDATES
+ * @param {number} [opts.limitMessages]
+ * @returns {{messages: Array, diagnostic: object}}
+ */
+function readLocalImDb(dbPath, opts = {}) {
+  if (typeof dbPath !== "string" || dbPath.length === 0) {
+    throw new TypeError("readLocalImDb: dbPath must be a non-empty string");
+  }
+  const limit =
+    Number.isInteger(opts.limitMessages) && opts.limitMessages > 0 ? opts.limitMessages : 20_000;
+  const tablePattern = opts.tablePattern || /msg|message|chat|conversation/i;
+  const cand = { ...DEFAULT_COL_CANDIDATES };
+  if (opts.colCandidates) {
+    for (const k of Object.keys(opts.colCandidates)) {
+      // platform-specific candidates take priority, then the generic list
+      cand[k] = [...opts.colCandidates[k], ...(DEFAULT_COL_CANDIDATES[k] || [])];
+    }
+  }
+
+  const { db, mode } = openLocalDb(dbPath, opts);
+  const diagnostic = {
+    mode,
+    messageCount: 0,
+    textCount: 0,
+    tablesScanned: 0,
+    messageTables: [],
+    skippedTables: [],
+    resolvedColumns: {},
+  };
+  const messages = [];
+  try {
+    const allTables =
+      trySelect(db, "SELECT name FROM sqlite_master WHERE type='table'") || [];
+    diagnostic.tablesScanned = allTables.length;
+    const candidateTables = allTables
+      .map((r) => r.name)
+      .filter((n) => typeof n === "string" && tablePattern.test(n) && !n.startsWith("sqlite_"));
+
+    for (const tableName of candidateTables) {
+      if (messages.length >= limit) break;
+      const info = trySelect(db, `PRAGMA table_info("${tableName}")`);
+      if (!Array.isArray(info) || info.length === 0) continue;
+      const cols = new Set(info.map((r) => r.name));
+      const resolved = {
+        msgId: pickCol(cols, cand.msgId),
+        time: pickCol(cols, cand.time),
+        sender: pickCol(cols, cand.sender),
+        peer: pickCol(cols, cand.peer),
+        content: pickCol(cols, cand.content),
+      };
+      // Need at least a content or time column to consider it a real message
+      // table; otherwise it's likely metadata (record + report, don't ingest).
+      if (!resolved.content && !resolved.time) {
+        diagnostic.skippedTables.push(tableName);
+        continue;
+      }
+      diagnostic.messageTables.push(tableName);
+      diagnostic.resolvedColumns[tableName] = resolved;
+
+      const orderBy = resolved.time ? ` ORDER BY "${resolved.time}" DESC` : "";
+      const remaining = limit - messages.length;
+      const rows =
+        trySelect(db, `SELECT * FROM "${tableName}"${orderBy} LIMIT ${remaining}`) || [];
+      rows.forEach((row, idx) => {
+        const rawTime = resolved.time ? row[resolved.time] : null;
+        const contentVal = resolved.content ? row[resolved.content] : null;
+        const text = typeof contentVal === "string" ? contentVal : null;
+        if (text && text.length > 0) diagnostic.textCount += 1;
+        messages.push({
+          msgId:
+            (resolved.msgId && row[resolved.msgId] != null && String(row[resolved.msgId])) ||
+            `${tableName}-${idx}`,
+          table: tableName,
+          createdTimeMs: typeof rawTime === "number" ? normalizeEpochMs(rawTime) : null,
+          senderId: resolved.sender && row[resolved.sender] != null ? String(row[resolved.sender]) : null,
+          peerId: resolved.peer && row[resolved.peer] != null ? String(row[resolved.peer]) : null,
+          text,
+          rawRow: row,
+        });
+      });
+    }
+    diagnostic.messageCount = messages.length;
+  } finally {
+    try { db.close(); } catch (_e) { /* ignore */ }
+  }
+  return { messages, diagnostic };
+}
+
+module.exports = {
+  readLocalImDb,
+  openLocalDb,
+  DEFAULT_COL_CANDIDATES,
+  _internals: { loadDatabaseClass, pickCol, normalizeEpochMs },
+};

package/lib/adapters/_local-im-pc-adapter.js

@@ -0,0 +1,162 @@
+"use strict";
+
+/**
+ * Factory for "honest best-effort" desktop IM adapters (钉钉 / 飞书) built on
+ * the generic local-im-db-reader. Both platforms have proprietary, possibly
+ * encrypted, version-volatile local SQLite — so the adapter:
+ *   - opens a (decrypted-or-keyed) local DB
+ *   - discovers message tables + resolves columns defensively
+ *   - emits MESSAGE events with the FULL raw row preserved + a loud
+ *     diagnostic (textResolved flag tells the UI when bodies are still
+ *     opaque / need real-device tuning)
+ *
+ * Same shape as qq-pc. Mirrors its honest contract so the UI / guide can
+ * treat all device-pull desktop IM sources uniformly.
+ */
+
+const fs = require("node:fs");
+const { newId } = require("../ids");
+const { ENTITY_TYPES, EVENT_SUBTYPES, CAPTURED_BY } = require("../constants");
+
+const KIND_MESSAGE = "message";
+
+/**
+ * @param {object} cfg
+ * @param {string} cfg.name              adapter name (e.g. "dingtalk-pc")
+ * @param {string} cfg.platform          extra.platform tag (e.g. "dingtalk")
+ * @param {string} [cfg.version]
+ * @param {RegExp} [cfg.tablePattern]    message-table name matcher
+ * @param {object} [cfg.colCandidates]   platform-specific column candidates
+ * @param {string} cfg.needHint          readiness/DB_NOT_PULLED message
+ */
+function createLocalImPcAdapter(cfg) {
+  const NAME = cfg.name;
+  const VERSION = cfg.version || "0.1.0";
+  const PLATFORM = cfg.platform;
+
+  function stableOriginalId(id) {
+    const safe =
+      (typeof id === "string" && id.length > 0 && id) ||
+      `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    return `${NAME}:message:${safe}`;
+  }
+
+  class LocalImPcAdapter {
+    constructor(opts = {}) {
+      this._dbPath = opts.dbPath || null;
+      this._key = opts.key || null;
+      this.name = NAME;
+      this.version = VERSION;
+      this.capabilities = ["sync:sqlite", "parse:local-im-message"];
+      this.extractMode = "device-pull";
+      this.rateLimits = {};
+      this.dataDisclosure = {
+        fields: [`${PLATFORM}:messages (time / sender / peer / best-effort text; raw row preserved)`],
+        sensitivity: "high",
+        legalGate: true,
+      };
+      this._deps = { fs, dbDriverFactory: opts.dbDriverFactory || null };
+    }
+
+    async authenticate(ctx = {}) {
+      if (ctx && ctx.readinessOnly) {
+        if (this._dbPath) return { ok: true, mode: "configured" };
+        return { ok: false, reason: "DB_NOT_PULLED", message: cfg.needHint };
+      }
+      const dbPath = (ctx && ctx.inputPath) || (ctx && ctx.dbPath) || this._dbPath;
+      if (dbPath) {
+        try {
+          this._deps.fs.accessSync(dbPath, this._deps.fs.constants.R_OK);
+        } catch (err) {
+          return { ok: false, reason: "INPUT_PATH_UNREADABLE", message: `${NAME}: db not readable at ${dbPath}: ${err.message}` };
+        }
+        return { ok: true, mode: "sqlite" };
+      }
+      return { ok: false, reason: "DB_NOT_PULLED", message: `${NAME}.authenticate: needs opts.dbPath / inputPath` };
+    }
+
+    async healthCheck() {
+      return { ok: true, lastChecked: Date.now() };
+    }
+
+    async *sync(opts = {}) {
+      const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
+      if (!dbPath) throw new Error(`${NAME}.sync: needs opts.dbPath / opts.inputPath`);
+      if (!this._deps.fs.existsSync(dbPath)) return;
+
+      // eslint-disable-next-line global-require
+      const { readLocalImDb } = require("./_local-im-db-reader");
+      const readOpts = {
+        key: opts.key || this._key || null,
+        tablePattern: cfg.tablePattern,
+        colCandidates: cfg.colCandidates,
+      };
+      if (Number.isInteger(opts.limitMessages)) readOpts.limitMessages = opts.limitMessages;
+      if (this._deps.dbDriverFactory) readOpts._databaseClass = this._deps.dbDriverFactory();
+
+      const { messages, diagnostic } = readLocalImDb(dbPath, readOpts);
+      if (typeof opts.onProgress === "function") {
+        try { opts.onProgress({ phase: "local-im-read", adapter: NAME, ...diagnostic }); } catch (_e) { /* best-effort */ }
+      }
+
+      const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+      const fallback = Date.now();
+      let emitted = 0;
+      for (const m of messages) {
+        if (emitted >= limit) return;
+        if (!m || typeof m !== "object") continue;
+        yield {
+          adapter: NAME,
+          kind: KIND_MESSAGE,
+          originalId: stableOriginalId(m.msgId),
+          capturedAt: (typeof m.createdTimeMs === "number" && m.createdTimeMs > 0) ? m.createdTimeMs : fallback,
+          payload: { kind: KIND_MESSAGE, ...m },
+        };
+        emitted += 1;
+      }
+    }
+
+    normalize(raw) {
+      if (!raw || !raw.payload) throw new Error(`${NAME}.normalize: payload missing`);
+      const kind = raw.kind || raw.payload.kind;
+      if (kind !== KIND_MESSAGE) throw new Error(`${NAME}.normalize: unknown kind ${kind}`);
+      const p = raw.payload;
+      const ingestedAt = Date.now();
+      const occurredAt = (typeof p.createdTimeMs === "number" && p.createdTimeMs) || raw.capturedAt || ingestedAt;
+      const source = {
+        adapter: NAME,
+        adapterVersion: VERSION,
+        originalId: raw.originalId,
+        capturedAt: raw.capturedAt || occurredAt,
+        capturedBy: CAPTURED_BY.SQLITE,
+      };
+      const text = typeof p.text === "string" ? p.text : "";
+      return {
+        events: [{
+          id: newId(),
+          type: ENTITY_TYPES.EVENT,
+          subtype: EVENT_SUBTYPES.MESSAGE,
+          occurredAt,
+          actor: "person-self",
+          content: { title: text ? text.slice(0, 80) : "(待解析消息体)", text },
+          ingestedAt,
+          source,
+          extra: {
+            platform: PLATFORM,
+            source: "pc",
+            table: p.table || null,
+            senderId: p.senderId || null,
+            peerId: p.peerId || null,
+            rawRow: p.rawRow || null,
+            textResolved: typeof p.text === "string" && p.text.length > 0,
+          },
+        }],
+        persons: [], places: [], items: [], topics: [],
+      };
+    }
+  }
+
+  return LocalImPcAdapter;
+}
+
+module.exports = { createLocalImPcAdapter };