@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/adapters/email-imap/templates/utils.js

@@ -0,0 +1,275 @@
+/**
+ * Shared regex extraction helpers for the 6 Phase 5.4 template extractors.
+ *
+ * Design notes:
+ *   - Regex-first. We aim to extract the high-value structured fields
+ *     (金额 / 日期 / 卡尾 4 位 / 订单号 / 快递单号) without paying LLM
+ *     tokens per email. Each helper returns ALL matches (an adapter can
+ *     pick the most plausible one when context is needed) and degrades
+ *     to [] / null for unrecognized input — never throws.
+ *   - LLM enrichment lives in per-template files when callers pass a
+ *     `llm` opt; this module stays free of LLM dependencies so it can
+ *     be unit-tested without mocks.
+ *   - Chinese-first patterns. ¥ and 元 are the primary currency
+ *     markers; CNY / RMB and $/USD/EUR are also handled for emails
+ *     from foreign vendors.
+ *   - Numbers can have thousands separators (1,234.50) and Chinese
+ *     decimals (1,234.50 元 / 1234元 / 1.5万 / 8千).
+ */
+
+"use strict";
+
+// ─── Currency / amount ──────────────────────────────────────────────────
+
+/**
+ * Match plausible monetary amounts and tag direction when adjacent
+ * "支出/支付/扣款" or "收入/退款/到账" markers surround them. Returns
+ * [{ value, currency, raw, direction?, index }, ...] sorted by source
+ * position. Always returns an array.
+ *
+ * Direction heuristics:
+ *   - text within 12 chars BEFORE or AFTER amount containing
+ *     "退款"/"返还"/"到账"/"收入"/"refund"/"credit" → "in"
+ *   - similar window with "扣款"/"支付"/"支出"/"消费"/"应还"/"还款"/"debit"/"charge"
+ *     → "out"
+ *   - default: undefined (caller decides)
+ *
+ * @param {string} text
+ * @returns {Array<{value:number,currency:string,raw:string,direction?:string,index:number}>}
+ */
+function extractAmounts(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const results = [];
+
+  // Pattern A: ¥1,234.50 / RMB 1,234 / CNY 99.00 / USD $100 / $99.99 / 100元
+  // Number group allows comma thousands + optional decimal. Currency can
+  // come before OR after the number.
+  const re = /(?:(?:[¥$€£]|RMB|CNY|USD|EUR|GBP|HKD)\s*([\d][\d,]*(?:\.\d{1,4})?)|([\d][\d,]*(?:\.\d{1,4})?)\s*(元|RMB|CNY|USD|EUR|HKD|港币|美元|欧元))/gi;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const numericStr = (m[1] || m[2] || "").replace(/,/g, "");
+    const value = Number(numericStr);
+    if (!Number.isFinite(value) || value <= 0) continue;
+    const currencyMarker = (m[0].match(/[¥$€£]|RMB|CNY|USD|EUR|GBP|HKD|元|港币|美元|欧元/i) || ["?"])[0];
+    const currency = normalizeCurrency(currencyMarker);
+    const direction = detectDirection(text, m.index, m[0].length);
+    results.push({
+      value,
+      currency,
+      raw: m[0],
+      direction,
+      index: m.index,
+    });
+  }
+
+  return results;
+}
+
+function normalizeCurrency(marker) {
+  const m = marker.toUpperCase();
+  if (m === "¥" || m === "元" || m === "RMB" || m === "CNY") return "CNY";
+  if (m === "$" || m === "USD" || m === "美元") return "USD";
+  if (m === "€" || m === "EUR" || m === "欧元") return "EUR";
+  if (m === "£" || m === "GBP") return "GBP";
+  if (m === "HKD" || m === "港币") return "HKD";
+  return "CNY"; // default — most Chinese emails
+}
+
+function detectDirection(text, idx, len) {
+  const winStart = Math.max(0, idx - 24);
+  const winEnd = Math.min(text.length, idx + len + 24);
+  const window = text.slice(winStart, winEnd);
+  if (/(退款|返还|到账|收入|入账|credit|refund|received)/i.test(window)) return "in";
+  if (/(扣款|支付|支出|消费|应还|还款|账单|debit|charge|paid|due)/i.test(window)) return "out";
+  return undefined;
+}
+
+// ─── Dates ──────────────────────────────────────────────────────────────
+
+/**
+ * Find date-like fragments. Recognizes:
+ *   - 2026-05-19 / 2026/05/19 / 2026.05.19 / 2026年5月19日
+ *   - 5/19/2026 / 19-05-2026 (Western)
+ *   - 5月19日 (current year inferred from now)
+ *
+ * Returns array of { raw, date: Date, index }. Year defaults to current
+ * year when only month+day is present (or last year if today's month is
+ * earlier than parsed month, suggesting "Christmas card sent in January").
+ * The default-year heuristic is intentionally conservative — callers
+ * needing strict semantics should rely on full YYYY-MM-DD forms.
+ *
+ * @param {string} text
+ * @param {number} [nowMs]
+ * @returns {Array<{raw:string,date:Date,index:number,hasYear:boolean}>}
+ */
+function extractDates(text, nowMs = Date.now()) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const out = [];
+  const now = new Date(nowMs);
+  const currentYear = now.getFullYear();
+
+  // YYYY-MM-DD / YYYY/MM/DD / YYYY.MM.DD / YYYY年M月D日
+  const reIso = /(\d{4})[-/.年](\d{1,2})[-/.月](\d{1,2})日?/g;
+  let m;
+  while ((m = reIso.exec(text)) !== null) {
+    const y = +m[1], mo = +m[2], d = +m[3];
+    if (isValidYMD(y, mo, d)) {
+      out.push({ raw: m[0], date: new Date(y, mo - 1, d), index: m.index, hasYear: true });
+    }
+  }
+
+  // M月D日 (Chinese, year-less)
+  const reMd = /(\d{1,2})月(\d{1,2})日?/g;
+  while ((m = reMd.exec(text)) !== null) {
+    if (out.some((o) => o.index === m.index)) continue; // already matched as YYYY-MM-DD
+    const mo = +m[1], d = +m[2];
+    if (isValidYMD(currentYear, mo, d)) {
+      // Heuristic: if parsed month is far before now's month, assume
+      // last year (e.g. a January-billed bill arriving in November).
+      const monthsAhead = mo - (now.getMonth() + 1);
+      const year = monthsAhead < -6 ? currentYear + 1 : (monthsAhead > 6 ? currentYear - 1 : currentYear);
+      out.push({ raw: m[0], date: new Date(year, mo - 1, d), index: m.index, hasYear: false });
+    }
+  }
+
+  // M/D/YYYY (Western shorthand)
+  const reUs = /\b(\d{1,2})\/(\d{1,2})\/(\d{4})\b/g;
+  while ((m = reUs.exec(text)) !== null) {
+    if (out.some((o) => o.index === m.index)) continue;
+    const mo = +m[1], d = +m[2], y = +m[3];
+    if (isValidYMD(y, mo, d)) {
+      out.push({ raw: m[0], date: new Date(y, mo - 1, d), index: m.index, hasYear: true });
+    }
+  }
+
+  return out.sort((a, b) => a.index - b.index);
+}
+
+function isValidYMD(y, m, d) {
+  return y >= 1970 && y <= 2099 && m >= 1 && m <= 12 && d >= 1 && d <= 31;
+}
+
+// ─── Account / card last-4 ──────────────────────────────────────────────
+
+/**
+ * Extract trailing 4-digit identifiers commonly used for card masking.
+ * Recognizes:
+ *   - 尾号 1234 / 卡号尾 1234 / **** 1234 / ending in 1234 / last 4 digits 1234
+ * Returns array of {raw, last4, index}. Always 4 digits exactly.
+ */
+function extractAccountTails(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const out = [];
+  const patterns = [
+    /(?:尾号|尾[四4]位|卡号尾|卡尾|账号尾)\s*[:：]?\s*(\d{4})\b/g,
+    /\*{2,}\s*(\d{4})\b/g,
+    /(?:ending in|last\s*4\s*digits|\bending\b)\s*(\d{4})\b/gi,
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      out.push({ raw: m[0], last4: m[1], index: m.index });
+    }
+  }
+  return out;
+}
+
+// ─── Order / tracking numbers ──────────────────────────────────────────
+
+/**
+ * Extract order-number candidates. Recognizes:
+ *   订单号: 12345678 / 订单 12345678 / Order # 12345-67 / Order Number 12345
+ *   订单编号: ABC1234567
+ * Returns array of {raw, orderNumber, index}.
+ */
+function extractOrderNumbers(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const out = [];
+  const patterns = [
+    /(?:订单(?:号|编号|号码)?|order(?:\s*number|\s*id|\s*#)?)\s*[:：]?\s*([A-Z0-9][-A-Z0-9]{4,30})\b/gi,
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      out.push({ raw: m[0], orderNumber: m[1], index: m.index });
+    }
+  }
+  return out;
+}
+
+/**
+ * Tracking-number candidates. Recognizes Chinese express keywords +
+ * generic "tracking number" markers. Sufficient for Phase 5.4; v2 may
+ * add carrier-specific format validation (SF / YT / ZTO regex).
+ */
+function extractTrackingNumbers(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const out = [];
+  const re = /(?:快递单号|运单号|物流单号|物流号|tracking\s*(?:number|#)|track(?:ing)?\s*id)\s*[:：]?\s*([A-Z0-9][-A-Z0-9]{6,30})\b/gi;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    out.push({ raw: m[0], trackingNumber: m[1], index: m.index });
+  }
+  return out;
+}
+
+// ─── Verification codes (REDACTED in extra; only field captured is "yes") ──
+
+/**
+ * Find OTP / verification code strings. Returns just the count + position
+ * — the code itself is NEVER returned to caller, since storing OTPs in
+ * vault is a compliance red flag (architecture-doc §9.2). Caller uses
+ * the count as a signal that this is a register email.
+ */
+function detectVerificationCodes(text) {
+  if (typeof text !== "string" || text.length === 0) return { count: 0, hits: [] };
+  const re = /(?:验证码|verification\s*code|otp|动态密码|安全码)\s*(?:为|是|:|：|is|为)?\s*\d{4,8}\b/gi;
+  const hits = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    hits.push({ raw: m[0].replace(/\d/g, "*"), index: m.index });
+  }
+  return { count: hits.length, hits };
+}
+
+// ─── Helpers shared by templates ────────────────────────────────────────
+
+/**
+ * Pick the most plausible amount given a list. Strategy:
+ *   1. If any amount has a `direction`, prefer those over directionless
+ *   2. Prefer larger amounts (statements tend to put the total prominently)
+ *   3. Tie-break by earliest position
+ */
+function selectPrimaryAmount(amounts) {
+  if (!Array.isArray(amounts) || amounts.length === 0) return null;
+  const directed = amounts.filter((a) => a.direction);
+  const pool = directed.length > 0 ? directed : amounts;
+  return pool.slice().sort((a, b) => {
+    if (b.value !== a.value) return b.value - a.value;
+    return a.index - b.index;
+  })[0];
+}
+
+/**
+ * Convert a Date to a ms epoch, falling back to null. Handy when
+ * templates emit dates into Event extra (vault stores ms-ints).
+ */
+function dateToMs(date) {
+  if (!(date instanceof Date)) return null;
+  const t = date.getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+module.exports = {
+  extractAmounts,
+  extractDates,
+  extractAccountTails,
+  extractOrderNumbers,
+  extractTrackingNumbers,
+  detectVerificationCodes,
+  selectPrimaryAmount,
+  dateToMs,
+  // exposed for tests
+  normalizeCurrency,
+  detectDirection,
+};

package/lib/adapters/email-imap/transactions.js

@@ -0,0 +1,234 @@
+/**
+ * Phase 5.5 — line-item transaction parser for Chinese bank-statement
+ * PDF text. Decrypted statements typically follow one of a few row
+ * formats; we go regex-first with a generic fallback.
+ *
+ * Output shape (per item):
+ *   {
+ *     occurredAtMs:  number,            // ms epoch of the transaction date
+ *     description:   string,            // merchant + memo, trimmed
+ *     amount:        { value, currency, direction },
+ *     balance?:      { value, currency }, // running balance when present
+ *     raw:           string,            // the original line for audit
+ *     index:         number,            // line index within the body
+ *   }
+ *
+ * Recognized formats (sample row patterns):
+ *
+ *   招商银行 / 中国银行 / 民生银行 (column-aligned with whitespace):
+ *     `2026-04-15  星巴克 上海中山公园店           ¥-39.00     1,234.56`
+ *
+ *   工商银行 / 建设银行 (slash dates + 借/贷 prefix):
+ *     `2026/04/15 借 39.00  星巴克 上海中山公园店  CNY 1,234.56`
+ *
+ *   交通银行 / 浦发银行 (Chinese date + tab/space):
+ *     `2026年04月15日  星巴克 上海中山公园店  支出 39.00  余额 1234.56`
+ *
+ * Strategy:
+ *   - One pass per line. Skip header / footer / legalese lines via
+ *     a denylist.
+ *   - Direction inferred from: explicit 借/贷 / 支出/收入 / + / - / 退款 keywords.
+ *   - Amount currency defaults to CNY (Chinese statements rarely
+ *     mix currencies); foreign-currency cards emit USD/EUR rows
+ *     which we detect via prefix.
+ *   - Returns an empty array when the text doesn't look like a
+ *     statement (e.g. marketing PDF). Callers should not assume
+ *     a non-empty list.
+ */
+
+"use strict";
+
+// Lines that look like statement chrome / legalese — skip outright.
+const SKIP_PATTERNS = [
+  /^[\s\d]*$/, // pure whitespace / numbers (page-number footers)
+  /^\s*第\s*\d+\s*页/, // 第 1 页 of 3
+  /^\s*page\s+\d+/i,
+  /声明|免责|提示|温馨提示|温馨提醒|请勿回复|本邮件由系统/,
+  /账单周期|账单日|还款日|信用额度|可用额度/,
+  /^\s*[-=]{3,}\s*$/,
+];
+
+// Direction keywords: ordered so "支出/借/-" wins over plain numbers.
+const DIRECTION_OUT = /(支出|借方|借|消费|扣款|paid|debit|charged?)/i;
+const DIRECTION_IN = /(收入|贷方|贷|退款|返还|到账|入账|credit|refund|received)/i;
+
+// ── Row patterns (each returns a SHARED capture-group layout via .exec()):
+//   m.groups = { date, dateY, dateM, dateD, sign?, currency?, amount, balance?, desc }
+// To keep regex sane we use a 2-pass approach: a "date-prefix" regex
+// rooted at line start, then a follow-up amount/balance regex on the rest.
+
+const DATE_PATTERNS = [
+  // 2026-04-15  /  2026/04/15  /  2026.04.15
+  /^\s*(?<dateY>\d{4})[-/.](?<dateM>\d{1,2})[-/.](?<dateD>\d{1,2})\s+/,
+  // 2026年04月15日
+  /^\s*(?<dateY>\d{4})年(?<dateM>\d{1,2})月(?<dateD>\d{1,2})日?\s+/,
+  // 04-15 (year-less, fall back to current year) — rare but BOC uses it
+  /^\s*(?<dateM>\d{1,2})[-/.](?<dateD>\d{1,2})\s+/,
+];
+
+// Amount: a signed (optional) currency-marked number. Negative or "-"
+// prefix means OUT. Currency optional; defaults to CNY.
+const AMOUNT_RE = /(?<sign>[+\-])?\s*(?:(?<cur>¥|RMB|CNY|USD|EUR|\$|€)\s*)?(?<amt>[\d][\d,]*(?:\.\d{1,4})?)\b/;
+
+/**
+ * Parse a bank-statement text body into transactions.
+ *
+ * @param {string} text         decrypted PDF text (or any plain-text body)
+ * @param {object} [opts]
+ * @param {number} [opts.maxRows=500]  cap to keep DoS-shaped statements bounded
+ * @param {number} [opts.nowMs=Date.now()] reference for year-less dates
+ * @returns {Array<object>}
+ */
+function extractTransactions(text, opts = {}) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const maxRows = Number.isFinite(opts.maxRows) && opts.maxRows > 0 ? opts.maxRows : 500;
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+  const now = new Date(nowMs);
+
+  const lines = text.split(/\r?\n/);
+  const out = [];
+
+  for (let i = 0; i < lines.length && out.length < maxRows; i++) {
+    const line = lines[i];
+    if (!line || line.length < 6) continue;
+    if (SKIP_PATTERNS.some((re) => re.test(line))) continue;
+
+    // ── 1. find date prefix ──
+    let dateMatch = null;
+    let dateConsumed = 0;
+    for (const re of DATE_PATTERNS) {
+      const m = re.exec(line);
+      if (m) {
+        dateMatch = m;
+        dateConsumed = m[0].length;
+        break;
+      }
+    }
+    if (!dateMatch) continue;
+
+    const y = +(dateMatch.groups.dateY || now.getFullYear());
+    const mo = +dateMatch.groups.dateM;
+    const d = +dateMatch.groups.dateD;
+    if (!validYMD(y, mo, d)) continue;
+    const occurredAtMs = new Date(y, mo - 1, d).getTime();
+
+    // ── 2. rest of line — find amount(s) ──
+    const rest = line.slice(dateConsumed);
+
+    // 借/贷 / 支出/收入 modifier may appear before the amount; capture
+    // its position so we can scope direction detection narrowly.
+    const directionWindow = rest;
+    let direction;
+    if (DIRECTION_OUT.test(directionWindow)) direction = "out";
+    else if (DIRECTION_IN.test(directionWindow)) direction = "in";
+
+    const amountMatches = collectAmounts(rest);
+    if (amountMatches.length === 0) continue;
+
+    // Heuristic: when 2+ numbers appear, the LAST is usually the
+    // running balance, the one BEFORE it is the transaction amount.
+    // Single number → that's the amount, no balance.
+    let amount, balance;
+    if (amountMatches.length >= 2) {
+      amount = amountMatches[amountMatches.length - 2];
+      balance = amountMatches[amountMatches.length - 1];
+    } else {
+      amount = amountMatches[0];
+    }
+
+    // sign / direction reconciliation: if amount.value had a "-" sign,
+    // force direction=out; "+" → in. Otherwise keep keyword-detected
+    // direction (default undefined → caller may treat as "out" for
+    // bills).
+    if (amount.sign === "-") direction = "out";
+    else if (amount.sign === "+") direction = "in";
+
+    // ── 3. description = rest minus the amount tokens ──
+    const description = cleanDescription(rest, amountMatches);
+    if (description.length === 0) continue;
+
+    const row = {
+      occurredAtMs,
+      description,
+      amount: {
+        value: amount.value,
+        currency: amount.currency,
+        ...(direction ? { direction } : {}),
+      },
+      ...(balance ? { balance: { value: balance.value, currency: balance.currency } } : {}),
+      raw: line.trim(),
+      index: i,
+    };
+    out.push(row);
+  }
+
+  return out;
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────
+
+function validYMD(y, m, d) {
+  return y >= 1970 && y <= 2099 && m >= 1 && m <= 12 && d >= 1 && d <= 31;
+}
+
+function collectAmounts(text) {
+  const out = [];
+  const re = new RegExp(AMOUNT_RE.source, "gi");
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const groups = m.groups || {};
+    const numericStr = (groups.amt || "").replace(/,/g, "");
+    const value = Number(numericStr);
+    if (!Number.isFinite(value) || value <= 0) continue;
+    // Skip pure-int matches that look like year/month numbers (e.g. "2026")
+    // when they are bare and < 100000 with no currency hint AND have 4
+    // digits exactly. False-positive guard for date-only rows.
+    if (!groups.cur && !groups.sign && /^\d{4}$/.test(numericStr) && value >= 1900 && value <= 2099) continue;
+    out.push({
+      value,
+      currency: normalizeCurrency(groups.cur),
+      sign: groups.sign,
+      raw: m[0],
+      index: m.index,
+      length: m[0].length,
+    });
+  }
+  return out;
+}
+
+function normalizeCurrency(marker) {
+  if (!marker) return "CNY";
+  const m = marker.toUpperCase();
+  if (m === "¥" || m === "元" || m === "RMB" || m === "CNY") return "CNY";
+  if (m === "$" || m === "USD") return "USD";
+  if (m === "€" || m === "EUR") return "EUR";
+  return "CNY";
+}
+
+/**
+ * Build the description by cutting amount tokens out of the line and
+ * collapsing whitespace. Also strips leading direction keywords (借/贷)
+ * — those belong in `amount.direction`, not the human-readable label.
+ */
+function cleanDescription(text, amountMatches) {
+  // Sort matches by descending start index so deletions don't shift
+  // earlier indices.
+  const sorted = amountMatches.slice().sort((a, b) => b.index - a.index);
+  let s = text;
+  for (const m of sorted) {
+    s = s.slice(0, m.index) + " " + s.slice(m.index + m.length);
+  }
+  // Strip direction keywords + standalone punctuation
+  s = s
+    .replace(/(支出|收入|借方|贷方|借|贷|debit|credit|paid|charged?|refunded?)/gi, " ")
+    .replace(/(余额|balance)\s*[:：]?/gi, " ")
+    .replace(/[¥$€]\s*/g, " ")
+    .replace(/[,，;；|]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return s;
+}
+
+module.exports = {
+  extractTransactions,
+};

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

@@ -0,0 +1,158 @@
+/**
+ * Phase 13.5 — QQ adapter.
+ *
+ * Per sjqz/parsers/qq.py QQParser. QQ DBs (msg.db / messages.db) are
+ * SQLCipher-encrypted with a per-installation key — Phase 13.5b will
+ * port the QQ key extractor; v0.5 accepts a `keyProvider` like WeChat.
+ *
+ * Tables:
+ *   - mr_friend            friend contacts
+ *   - mr_troop             groups
+ *   - mr_buddy_groupbuddy  group members
+ *   - msgcsr_friend_*      friend messages (per-buddy table sharding)
+ *   - msgcsr_troop_*       group messages
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const { newId } = require("../../ids");
+
+const NAME = "messaging-qq";
+const VERSION = "0.5.0";
+
+class QQAdapter {
+  constructor(opts = {}) {
+    if (!opts.account || !opts.account.qq) {
+      throw new Error("QQAdapter: opts.account.qq required");
+    }
+    this.account = opts.account;
+    this._dbPath = opts.dbPath || null;
+    this._keyProvider = opts.keyProvider || null;
+    this._dbDriverFactory = opts.dbDriverFactory || null;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = ["sync:sqlite", "parse:qq-messages", "decrypt:sqlcipher"];
+    this.extractMode = "device-pull";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "qq:friends (uin / nickname / remark)",
+        "qq:groups (troop_uin / name)",
+        "qq:messages (peer / content / time / type)",
+      ],
+      sensitivity: "high",
+      legalGate: true,
+    };
+  }
+
+  async authenticate() {
+    if (!this._dbPath || !fs.existsSync(this._dbPath)) {
+      return { ok: false, reason: "DB_NOT_PULLED" };
+    }
+    if (!this._keyProvider || typeof this._keyProvider.getKey !== "function") {
+      return { ok: false, reason: "NO_KEY_PROVIDER" };
+    }
+    return { ok: true, account: this.account.qq };
+  }
+
+  async healthCheck() {
+    const r = await this.authenticate();
+    return r.ok ? { ok: true, lastChecked: Date.now() } : r;
+  }
+
+  async *sync(opts = {}) {
+    const dbPath = opts.dbPath || this._dbPath;
+    if (!dbPath || !fs.existsSync(dbPath)) return;
+    if (!this._keyProvider) return;
+    const key = await this._keyProvider.getKey();
+    if (!key) return;
+
+    const Driver = this._dbDriverFactory
+      ? this._dbDriverFactory()
+      : require("better-sqlite3-multiple-ciphers");
+    const db = new Driver(dbPath, { readonly: true });
+    try {
+      db.pragma(`key = '${key}'`);
+      // Friends
+      const friends = trySelect(db, "SELECT * FROM mr_friend LIMIT 5000") || [];
+      for (const row of friends) {
+        yield { adapter: NAME, originalId: `friend-${row.uin}`, capturedAt: Date.now(), payload: { row, kind: "contact" } };
+      }
+      // Groups
+      const groups = trySelect(db, "SELECT * FROM mr_troop LIMIT 1000") || [];
+      for (const row of groups) {
+        yield { adapter: NAME, originalId: `group-${row.troop_uin}`, capturedAt: Date.now(), payload: { row, kind: "group" } };
+      }
+      // Messages — QQ shards by buddy. Iterate any msgcsr_friend_* table.
+      const tables = trySelect(db, "SELECT name FROM sqlite_master WHERE type='table' AND (name LIKE 'msgcsr_friend_%' OR name LIKE 'msgcsr_troop_%')") || [];
+      for (const t of tables) {
+        const msgs = trySelect(db, `SELECT * FROM ${t.name} ORDER BY time DESC LIMIT 1000`) || [];
+        for (const row of msgs) {
+          yield {
+            adapter: NAME,
+            originalId: `msg-${row.msgid || row._id}`,
+            capturedAt: parseTime(row.time),
+            payload: { row, kind: "message", table: t.name },
+          };
+        }
+      }
+    } finally {
+      try { db.close(); } catch (_e) {}
+    }
+  }
+
+  normalize(raw) {
+    const { kind, row } = raw.payload;
+    const now = Date.now();
+    const occurredAt = parseTime(row.time) || now;
+    const source = { adapter: NAME, adapterVersion: VERSION, originalId: raw.originalId, capturedAt: occurredAt, capturedBy: "sqlite" };
+    if (kind === "contact") {
+      return {
+        events: [], places: [], items: [], topics: [],
+        persons: [{
+          id: `person-qq-${row.uin}`,
+          type: "person", subtype: "contact",
+          names: [row.remark, row.nickname, String(row.uin)].filter((x) => typeof x === "string" && x.length > 0),
+          identifiers: { qqId: String(row.uin) },
+          ingestedAt: now, source,
+          extra: { fromAdapter: NAME, qq: row.uin },
+        }],
+      };
+    }
+    if (kind === "group") {
+      return {
+        events: [], places: [], items: [], persons: [],
+        topics: [{
+          id: `topic-qq-group-${row.troop_uin}`,
+          type: "topic", name: row.troop_name || String(row.troop_uin),
+          ingestedAt: now, source,
+          extra: { fromAdapter: NAME, troopUin: row.troop_uin },
+        }],
+      };
+    }
+    // message
+    const isGroup = (raw.payload.table || "").startsWith("msgcsr_troop_");
+    return {
+      events: [{
+        id: newId(), type: "event", subtype: "message",
+        occurredAt, actor: "person-self",
+        content: { title: (row.msg || "").slice(0, 80) || "(空)", text: row.msg || "" },
+        ingestedAt: now, source,
+        extra: { peer: row.frienduin || row.troopuin, isGroup, msgType: row.msgtype },
+      }],
+      persons: [], places: [], items: [], topics: [],
+    };
+  }
+}
+function trySelect(db, sql) { try { return db.prepare(sql).all(); } catch (_e) { return null; } }
+function parseTime(v) {
+  if (Number.isFinite(v)) return v > 1e12 ? v : v * 1000;
+  if (typeof v === "string") {
+    if (/^\d+$/.test(v)) { const n = parseInt(v, 10); return n > 1e12 ? n : n * 1000; }
+    return Date.parse(v) || null;
+  }
+  return null;
+}
+module.exports = { QQAdapter, NAME, VERSION };