@chainlesschain/personal-data-hub 0.4.1 → 0.4.3

package/lib/adapters/social-douyin-adb/db-extension.js

@@ -37,8 +37,29 @@ const crypto = require("node:crypto");
 const DOUYIN_DB_REMOTE_DIR =
   "/data/data/com.ss.android.ugc.aweme/databases";
 
+// Legacy plaintext social-DM IM db (Brignoni 2018 TikTok era, `<19-digit-uid>_im.db`).
 const IM_DB_PATTERN = /^(\d{19})_im\.db$/;
 
+// Real-device verification 2026-06-08 (Xiaomi chopin / MIUI 13, Douyin
+// v??-2026 logged in) found CURRENT Douyin no longer ships a plaintext
+// social-DM IM db. Two new on-disk shapes coexist in databases/:
+//
+//   encrypted_<uid>_im.db   — the social DM store, now SQLCipher-ENCRYPTED
+//                             (header is NOT `SQLite format 3`). Reading it
+//                             needs the per-user key, which only the frida
+//                             key-hook path (Phase 2b, libmsaoaidsec.so
+//                             anti-debug bypass) can recover — the plaintext
+//                             C-path here cannot.
+//   im_database_<uid>       — a Room db, but it is the in-app 豆包/Doubao AI
+//                             ASSISTANT chat (tables im_message / im_conversation
+//                             / im_bot), NOT person-to-person social DMs.
+//
+// We classify all three so the handler can emit a precise, actionable error
+// instead of a misleading DOUYIN_NO_IM_DB. See memory
+// [[pdh_douyin_c_path_phase_2a]] / [[pdh_social_cookie_endpoint_drift_2026_05]].
+const ENCRYPTED_IM_DB_PATTERN = /^encrypted_(\d+)_im\.db$/;
+const DOUBAO_IM_DB_PATTERN = /^im_database_(\d{6,})$/;
+
 /**
  * List candidate IM db filenames + uid via `adb shell su -c "ls databases/"`.
  *
@@ -64,15 +85,27 @@ async function listImDbs(adb, serial, opts) {
     return { candidates: [], dirMissing: true };
   }
   const candidates = [];
+  const encryptedCandidates = [];
+  const doubaoCandidates = [];
   for (const line of lines) {
     const fileName = line.trim();
     if (!fileName) continue;
     const m = fileName.match(IM_DB_PATTERN);
     if (m) {
       candidates.push({ uid: m[1], fileName });
+      continue;
+    }
+    const enc = fileName.match(ENCRYPTED_IM_DB_PATTERN);
+    if (enc) {
+      encryptedCandidates.push({ uid: enc[1], fileName });
+      continue;
+    }
+    const doubao = fileName.match(DOUBAO_IM_DB_PATTERN);
+    if (doubao) {
+      doubaoCandidates.push({ uid: doubao[1], fileName });
     }
   }
-  return { candidates, dirMissing: false };
+  return { candidates, encryptedCandidates, doubaoCandidates, dirMissing: false };
 }
 
 /**
@@ -159,9 +192,10 @@ function createDouyinDbExtension(factoryOpts = {}) {
     }
 
     // Step 1: discover candidate IM dbs.
-    const { candidates, dirMissing } = await listImDbs(ctx.adb, serial, {
-      timeoutMs,
-    });
+    const { candidates, encryptedCandidates, doubaoCandidates, dirMissing } =
+      await listImDbs(ctx.adb, serial, {
+        timeoutMs,
+      });
     if (dirMissing) {
       throw new Error(
         "DOUYIN_NOT_INSTALLED: " +
@@ -170,6 +204,32 @@ function createDouyinDbExtension(factoryOpts = {}) {
       );
     }
     if (candidates.length === 0) {
+      // No legacy plaintext IM db. Distinguish the modern layouts so the UI
+      // can tell the user the truth instead of "no db found". Real-device
+      // verification 2026-06-08 — see ENCRYPTED_IM_DB_PATTERN comment above.
+      if (encryptedCandidates && encryptedCandidates.length > 0) {
+        throw new Error(
+          "DOUYIN_IM_DB_ENCRYPTED: this Douyin version stores its social DM db as " +
+            `\`encrypted_<uid>_im.db\` (SQLCipher) — found ${encryptedCandidates
+              .map((c) => c.fileName)
+              .join(", ")}. The plaintext C-path can't read it; the per-user ` +
+            "key must be recovered via the frida key-hook path (Phase 2b, " +
+            "libmsaoaidsec.so anti-debug bypass). Plaintext direct-read is no " +
+            "longer possible on current Douyin.",
+        );
+      }
+      if (doubaoCandidates && doubaoCandidates.length > 0) {
+        throw new Error(
+          "DOUYIN_ONLY_DOUBAO_AI_CHAT: the only readable `im_database_<uid>` db " +
+            `(${doubaoCandidates
+              .map((c) => c.fileName)
+              .join(", ")}) is the in-app 豆包/Doubao AI ASSISTANT chat ` +
+            "(tables im_message / im_conversation / im_bot), not person-to-person " +
+            "social DMs. Social DMs live in the SQLCipher `encrypted_<uid>_im.db` " +
+            "and need the frida key path. (Collecting Doubao AI chat would be a " +
+            "separate, net-new adapter.)",
+        );
+      }
       throw new Error(
         "DOUYIN_NO_IM_DB: no `<19-digit-uid>_im.db` found in databases/. Open the Douyin App + log in once + open any chat thread to materialize the IM database, then retry.",
       );
@@ -273,6 +333,8 @@ module.exports = {
   createDouyinDbExtension,
   DOUYIN_DB_REMOTE_DIR,
   IM_DB_PATTERN,
+  ENCRYPTED_IM_DB_PATTERN,
+  DOUBAO_IM_DB_PATTERN,
   // Exposed for tests
   _internals: {
     listImDbs,

package/lib/adapters/social-weibo-adb/cookies-extension.js

@@ -53,6 +53,22 @@ const {
 const WEIBO_COOKIES_REMOTE_PATH =
   "/data/data/com.sina.weibo/app_webview/Default/Cookies";
 
+/**
+ * Glob the WebView profile dir at pull time. Real-device verification
+ * (2026-06-08, Xiaomi chopin / MIUI 13 / Weibo logged in) showed current
+ * Weibo stores cookies under a SUFFIXED profile dir
+ * `app_webview_com.sina.weibo/Default/Cookies`, NOT the standard
+ * `app_webview/Default/Cookies` — so the old hardcoded path made the
+ * collector throw WEIBO_NOT_INSTALLED even though Weibo was installed and
+ * logged in. Chromium names the WebView data dir after the WebView
+ * `dataDirectorySuffix` the host app sets; Weibo sets it to its own
+ * package name. We glob `app_webview*` and take the first match (Default
+ * profile) so both the legacy and suffixed layouts resolve. See memory
+ * [[pdh_social_cookie_endpoint_drift_2026_05]].
+ */
+const WEIBO_COOKIES_REMOTE_GLOB =
+  "/data/data/com.sina.weibo/app_webview*/Default/Cookies";
+
 const WEIBO_COOKIE_HOST_DOMAIN = "m.weibo.cn";
 
 /** Minimum required cookie name — without SUB, /api/config returns login=false. */
@@ -60,21 +76,31 @@ const WEIBO_REQUIRED_COOKIE = "SUB";
 
 async function pullCookiesViaSu(adb, serial, opts) {
   const adbOpts = { serial, timeoutMs: opts?.timeoutMs || 60_000 };
+  // Resolve the actual Cookies path — glob `app_webview*` so the suffixed
+  // profile dir (app_webview_com.sina.weibo, observed on real devices) is
+  // found as well as the legacy `app_webview`. `ls -d <glob>` prints every
+  // match; we take the first (Default profile). When nothing matches the
+  // shell prints the unexpanded glob, so we sentinel-guard NOT_FOUND.
   const lsOut = await adb(
     [
       "shell",
       "su",
       "-c",
-      `ls ${WEIBO_COOKIES_REMOTE_PATH} 2>/dev/null || echo NOT_FOUND`,
+      `ls -d ${WEIBO_COOKIES_REMOTE_GLOB} 2>/dev/null | head -n1 || echo NOT_FOUND`,
     ],
     adbOpts,
   );
   const lsLine = lsOut.replace(/\r+$/gm, "").trim();
-  if (lsLine === "NOT_FOUND" || lsLine === "") {
+  const remotePath =
+    lsLine && lsLine !== "NOT_FOUND" && !lsLine.includes("*") ? lsLine : null;
+  if (!remotePath) {
     throw new Error(
-      "WEIBO_NOT_INSTALLED: " +
-        WEIBO_COOKIES_REMOTE_PATH +
-        " not found. Install Weibo App + log in once on the phone, then retry. (Some Weibo App versions store cookies in a non-default WebView profile dir; if Weibo is installed but the path is missing, file a bug to track the actual path.)",
+      "WEIBO_NOT_INSTALLED: no Cookies DB under " +
+        WEIBO_COOKIES_REMOTE_GLOB +
+        " (globbed `app_webview*` to cover both the legacy and the suffixed " +
+        "`app_webview_com.sina.weibo` profile layouts). Install Weibo App + " +
+        "log in once on the phone, then retry. If Weibo is installed but no " +
+        "match exists, the WebView dataDirectorySuffix changed again — file a bug.",
     );
   }
   // Probe root.
@@ -93,7 +119,7 @@ async function pullCookiesViaSu(adb, serial, opts) {
       "shell",
       "su",
       "-c",
-      `base64 ${WEIBO_COOKIES_REMOTE_PATH} | tr -d '\\n\\r'`,
+      `base64 ${remotePath} | tr -d '\\n\\r'`,
     ],
     { ...adbOpts, timeoutMs: opts?.timeoutMs || 60_000 },
   );
@@ -241,6 +267,7 @@ function createWeiboCookiesExtension(factoryOpts = {}) {
 module.exports = {
   createWeiboCookiesExtension,
   WEIBO_COOKIES_REMOTE_PATH,
+  WEIBO_COOKIES_REMOTE_GLOB,
   WEIBO_COOKIE_HOST_DOMAIN,
   WEIBO_REQUIRED_COOKIE,
   assembleWeiboCookieHeader,

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

@@ -81,21 +81,52 @@ class WeChatPcAdapter {
       fs,
       // DI seam: tests inject a fake SQLite driver class via dbDriverFactory.
       dbDriverFactory: opts.dbDriverFactory || null,
+      // DI seam: tests inject a fake WeChat 4.x collector; default lazy-loads
+      // the forensics-bridge sidecar invoker.
+      v4Collector: opts.v4Collector || null,
+      // DI seam for discovery (see _autoDiscover).
+      discoveryDeps: opts.discoveryDeps || undefined,
     };
   }
 
+  // Auto-discover PC WeChat's local DB on the host (3.x + 4.x layouts) so the
+  // UI never needs a manually typed path. Lazy-required + cached per instance.
+  _autoDiscover() {
+    if (this._discovered !== undefined) return this._discovered;
+    try {
+      // eslint-disable-next-line global-require
+      const { discover } = require("../_pc-local-discovery");
+      this._discovered = discover("wechat-pc", this._deps.discoveryDeps || {});
+    } catch (_e) {
+      this._discovered = null;
+    }
+    return this._discovered;
+  }
+
   async authenticate(ctx = {}) {
     // Cheap readiness probe — never opens / decrypts a DB.
     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: `已找到本机微信库（${disc.layout || ""} ${disc.accounts.length} 个账号，主库 ${disc.primaryDb}）`,
+          discovered: disc,
+        };
+      }
       return {
         ok: false,
-        reason: "DB_NOT_PULLED",
-        message:
-          "wechat-pc: 需提供 PC 微信本地数据库路径（MSG*.db / MicroMsg.db），加密库需先解密或提供 key",
+        reason: "APP_NOT_INSTALLED",
+        message: (disc && disc.note) || "未检测到本机微信数据（可能未安装或未登录）",
       };
     }
-    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);
@@ -108,22 +139,54 @@ class WeChatPcAdapter {
       }
       return { ok: true, mode: "sqlite" };
     }
+    const disc = this._autoDiscover();
+    if (disc && disc.installed) {
+      return {
+        ok: false,
+        reason: "DB_FOUND_NEEDS_KEY",
+        message: `已找到本机微信库（主库 ${disc.primaryDb}），需解密密钥`,
+        discovered: disc,
+      };
+    }
     return {
       ok: false,
-      reason: "DB_NOT_PULLED",
-      message: "wechat-pc.authenticate: needs opts.dbPath / inputPath (MSG*.db or MicroMsg.db)",
+      reason: "APP_NOT_INSTALLED",
+      message: "wechat-pc.authenticate: 未检测到本机微信库，也未提供 dbPath / inputPath",
     };
   }
 
+  // Resolve the auto-discovered primary message DB path (null if none).
+  _resolveDiscoveredDbPath() {
+    const disc = this._autoDiscover();
+    return disc && disc.installed && disc.primaryDb ? disc.primaryDb : null;
+  }
+
   async healthCheck() {
     return { ok: true, lastChecked: Date.now() };
   }
 
   async *sync(opts = {}) {
-    const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
+    // WeChat 4.x path: encrypted SQLCipher-4 DBs whose key lives in Weixin.exe
+    // memory. Route through the Python sidecar (memory key + decrypt + parse)
+    // and yield the decrypted messages. Triggered when the user gives no
+    // explicit plaintext path AND discovery sees the 4.x layout, or opts.mode.
+    const disc = this._autoDiscover();
+    const noExplicitPath = !opts.dbPath && !opts.inputPath && !this._dbPath;
+    const useV4 =
+      opts.mode === "v4" ||
+      (noExplicitPath && disc && disc.installed && disc.layout === "4.x");
+    if (useV4) {
+      yield* this._syncV4(opts, disc);
+      return;
+    }
+
+    // One-click: when no explicit path is given, fall back to the
+    // auto-discovered primary message DB on this host (3.x plaintext/keyed).
+    const dbPath =
+      opts.dbPath || opts.inputPath || this._dbPath || this._resolveDiscoveredDbPath();
     if (!dbPath) {
       throw new Error(
-        "wechat-pc.sync: needs opts.dbPath / opts.inputPath pointing to a PC WeChat DB (MSG*.db or MicroMsg.db)",
+        "wechat-pc.sync: 未找到本机微信库且未提供 opts.dbPath / opts.inputPath",
       );
     }
     if (!this._deps.fs.existsSync(dbPath)) return;
@@ -186,6 +249,114 @@ class WeChatPcAdapter {
     }
   }
 
+  // WeChat 4.x: invoke the sidecar collector, then re-shape each decrypted
+  // message into the SAME payload the 3.x normalizeMessage() understands, so
+  // both layouts share one normalization path.
+  async *_syncV4(opts = {}, disc) {
+    let collect = this._deps.v4Collector;
+    if (!collect) {
+      // eslint-disable-next-line global-require
+      collect = require("./v4-sidecar").collectWeChatV4;
+    }
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : undefined;
+    const result = await collect({
+      limit,
+      key: opts.key || this._key || undefined,
+      pythonExe: opts.pythonExe,
+      bridgeDir: opts.bridgeDir,
+      timeoutMs: opts.timeoutMs,
+      onProgress:
+        typeof opts.onProgress === "function"
+          ? (m) => {
+              try { opts.onProgress({ phase: "wechat-v4", adapter: NAME, ...m }); } catch (_e) { /* best-effort */ }
+            }
+          : undefined,
+      _supervisorFactory: opts._supervisorFactory,
+    });
+    if (typeof opts.onProgress === "function") {
+      try {
+        opts.onProgress({
+          phase: "wechat-v4-done",
+          adapter: NAME,
+          account: result && result.account,
+          messageCount: result && result.messageCount,
+          dbs: result && result.dbs,
+        });
+      } catch (_e) { /* best-effort */ }
+    }
+    const selfWxid =
+      (result && result.account) ||
+      (disc && disc.accounts && disc.accounts[0] && disc.accounts[0].id) ||
+      null;
+    const fallbackCapturedAt = Date.now();
+    const messages = (result && Array.isArray(result.messages)) ? result.messages : [];
+    let emitted = 0;
+    // The sidecar already applied `limit` across all sources (chat/biz/sns/
+    // favorite). Yield everything it returned — do NOT re-cap here, or the
+    // trailing 朋友圈/收藏 entries and the contacts block would be skipped.
+    for (const m of messages) {
+      if (!m || typeof m !== "object") continue;
+      const conv = typeof m.conversation === "string" ? m.conversation : null;
+      const isGroup = !!conv && conv.endsWith("@chatroom");
+      const createdTimeMs =
+        typeof m.createTime === "number" && m.createTime > 0 ? m.createTime * 1000 : null;
+      // Map → 3.x payload shape consumed by normalizeMessage().
+      const payload = {
+        kind: KIND_MESSAGE,
+        msgSvrId: m.originalId || null,
+        talker: conv,
+        isSend: selfWxid && m.sender && m.sender === selfWxid ? 1 : 0,
+        type: typeof m.type === "number" ? m.type : null,
+        createdTimeMs,
+        text: typeof m.text === "string" ? m.text : "",
+        senderWxid: isGroup ? (m.sender || null) : null,
+        isGroup,
+        contentBlob: typeof m.text === "string" ? m.text : null,
+        // provenance: chat | biz(公众号) | sns(朋友圈) | favorite(收藏)
+        wechatSource: typeof m.source === "string" ? m.source : "chat",
+        appType: typeof m.appType === "number" ? m.appType : null,  // appmsg subtype (type 49)
+        appUrl: typeof m.appUrl === "string" ? m.appUrl : null,     // link/article url
+      };
+      const idPart =
+        m.originalId ||
+        (conv && createdTimeMs ? `${conv}-${createdTimeMs}` : `v4-${emitted}`);
+      yield {
+        adapter: NAME,
+        kind: KIND_MESSAGE,
+        originalId: m.originalId || stableOriginalId(KIND_MESSAGE, idPart),
+        capturedAt: createdTimeMs || fallbackCapturedAt,
+        payload,
+      };
+      emitted += 1;
+    }
+
+    // Contacts (from contact.db) → Person entities. Not bound by the message
+    // `limit` (that caps messages, not the address book). Opt out via
+    // opts.include.contact === false.
+    const include = opts.include || {};
+    if (include[KIND_CONTACT] !== false) {
+      const contacts = (result && Array.isArray(result.contacts)) ? result.contacts : [];
+      for (const c of contacts) {
+        if (!c || typeof c !== "object" || !c.wxid) continue;
+        if (typeof c.wxid === "string" && c.wxid.endsWith("@chatroom")) continue;
+        yield {
+          adapter: NAME,
+          kind: KIND_CONTACT,
+          originalId: stableOriginalId(KIND_CONTACT, c.wxid),
+          capturedAt: fallbackCapturedAt,
+          payload: {
+            kind: KIND_CONTACT,
+            wxid: c.wxid,
+            alias: c.alias || null,
+            nickname: c.nickname || null,
+            remark: c.remark || null,
+            type: typeof c.type === "number" ? c.type : null,
+          },
+        };
+      }
+    }
+  }
+
   normalize(raw) {
     if (!raw || !raw.payload) {
       throw new Error("WeChatPcAdapter.normalize: payload missing");
@@ -282,6 +453,9 @@ function normalizeMessage(p, raw, ingestedAt) {
         isSend,
         isGroup,
         wechatType: typeof p.type === "number" ? p.type : null,
+        wechatSource: typeof p.wechatSource === "string" ? p.wechatSource : "chat",
+        ...(p.appType != null ? { wechatAppType: p.appType } : {}),
+        ...(p.appUrl ? { url: p.appUrl } : {}),
         senderWxid: p.senderWxid || null,
         contentBlob: typeof p.contentBlob === "string" ? p.contentBlob : null,
         ...(topics.length ? { topicId: topics[0].id } : {}),

package/lib/adapters/wechat-pc/v4-sidecar.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/**
+ * WeChat 4.x collection bridge — invokes the forensics-bridge Python sidecar's
+ * `wechat_v4.collect` method (memory key extraction + SQLCipher-4 decryption +
+ * Msg_<md5> parsing) and returns the decrypted messages to the node adapter.
+ *
+ * Why a sidecar: WeChat 4.0 DBs are SQLCipher-4 encrypted with a key cached in
+ * Weixin.exe process memory. Recovering it needs ReadProcessMemory (Windows)
+ * and AES/PBKDF2 — done in Python (`cryptography`), which also sidesteps the
+ * host-node bs3mc ABI problem (the node side never opens the encrypted DB).
+ *
+ * Resolution (all 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
+ *
+ * Returns the sidecar result `{ account, messageCount, dbs, messages }`.
+ * Throws a typed Error (code on .code) the adapter maps to a sync failure.
+ */
+
+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/wechat-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);
+  // Windows commonly ships `python`; *nix `python3`. Try both.
+  list.push(process.platform === "win32" ? "python" : "python3");
+  list.push(process.platform === "win32" ? "python3" : "python");
+  return [...new Set(list)];
+}
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.limit]        max messages
+ * @param {string} [opts.key]          pre-extracted 64-hex key (skips memory scan)
+ * @param {string} [opts.pythonExe]
+ * @param {string} [opts.bridgeDir]
+ * @param {number} [opts.timeoutMs]    collect timeout (default 120s)
+ * @param {(msg:object)=>void} [opts.onProgress]
+ * @param {object} [opts._supervisorFactory]  test seam → returns a SidecarSupervisor-like
+ * @returns {Promise<{account:string,messageCount:number,dbs:object[],messages:object[]}>}
+ */
+async function collectWeChatV4(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(
+      `wechat-pc v4: 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.key) params.key = opts.key;
+
+  let lastErr = null;
+  for (const py of pythonCandidates(opts.pythonExe)) {
+    const command = [py, "-m", "forensics_bridge.ipc_server"];
+    const sup = makeSupervisor(command, bridgeDir);
+    try {
+      await sup.start({ readyTimeoutMs: opts.readyTimeoutMs || 15_000 });
+      const result = await sup.invoke("wechat_v4.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 WeChat-side failures (key/app/db) must surface immediately — the
+      // sidecar ran fine, the data just isn't there. Everything else (python
+      // missing, wrong python without `cryptography`, import errors, spawn
+      // death, handshake timeout) → try the next python candidate.
+      const isDataError = /KEY_NOT_FOUND|KEY_VERIFY|APP_NOT|DB_NOT|APP_NOT_RUNNING|EXTRACT_PERMISSION/i.test(msg);
+      if (isDataError) throw err;
+      // otherwise fall through to the next candidate
+    }
+  }
+  const e = new Error(
+    `wechat-pc v4: could not run forensics-bridge sidecar (tried ${pythonCandidates(opts.pythonExe).join(", ")}). ` +
+      `Install Python 3.11+ with the 'cryptography' package, or set CC_PDH_PYTHON. Last error: ${lastErr && lastErr.message}`,
+  );
+  e.code = "SIDECAR_UNAVAILABLE";
+  throw e;
+}
+
+module.exports = { collectWeChatV4, _internals: { resolveBridgeDir, pythonCandidates } };

package/lib/registry.js

@@ -65,6 +65,26 @@ class AdapterRegistry {
     // depend on it).
     this.entityResolver = opts.entityResolver || null;
 
+    // ADB one-click readiness (Phase: social platforms). When supplied by the
+    // wiring, readiness() treats the named adapters as "collectable via a
+    // rooted-phone USB one-click" — flipping their NO_INPUT / DB_NOT_PULLED
+    // status to "ready (device connected)" or "ADB_DEVICE_NEEDED" depending on
+    // whether a device is currently attached. Keeps the registry generic: the
+    // platform list + the actual `adb devices` probe come from the host wiring.
+    //   opts.adbReadiness = {
+    //     probe: async () => ({ deviceConnected: boolean, serial?: string }),
+    //     oneClickNames: Set<string>,  // adapter names with an *AdbSync path
+    //   }
+    this._adbReadiness =
+      opts.adbReadiness && typeof opts.adbReadiness.probe === "function"
+        ? {
+            probe: opts.adbReadiness.probe,
+            oneClickNames: opts.adbReadiness.oneClickNames instanceof Set
+              ? opts.adbReadiness.oneClickNames
+              : new Set(opts.adbReadiness.oneClickNames || []),
+          }
+        : null;
+
     this._adapters = new Map();
     this._activeSync = null; // name of currently-running adapter, or null
   }
@@ -158,9 +178,24 @@ class AdapterRegistry {
       Number.isInteger(opts.timeoutMs) && opts.timeoutMs > 0
         ? opts.timeoutMs
         : DEFAULT_READINESS_TIMEOUT_MS;
+    // Probe the host's ADB device state ONCE (best-effort) so all ADB
+    // one-click adapters share a single `adb devices` call this round.
+    let adbState = null;
+    if (this._adbReadiness) {
+      try {
+        adbState = await this._withTimeout(
+          Promise.resolve().then(() => this._adbReadiness.probe()),
+          timeoutMs,
+          "adb-probe"
+        );
+      } catch (_e) {
+        adbState = { deviceConnected: false };
+      }
+    }
+
     const reports = [];
     for (const adapter of this._adapters.values()) {
-      const report = await this._probeReadiness(adapter, timeoutMs);
+      const report = await this._probeReadiness(adapter, timeoutMs, adbState);
       // Attach the step-by-step import guide (how to get this source's data
       // into the vault) keyed off the resolved category. Single source of
       // truth in adapter-guide.js — reused by every shell.
@@ -170,7 +205,7 @@ class AdapterRegistry {
     return reports;
   }
 
-  async _probeReadiness(adapter, timeoutMs) {
+  async _probeReadiness(adapter, timeoutMs, adbState) {
     const dd = adapter.dataDisclosure || {};
     const extractMode = adapter.extractMode || "web-api";
     const base = {
@@ -240,6 +275,47 @@ class AdapterRegistry {
     }
 
     const reason = (auth && auth.reason) || "UNKNOWN";
+
+    // ADB one-click platforms (social): the adapter itself has no snapshot yet
+    // (NO_INPUT / INPUT_PATH_REQUIRED / DB_NOT_PULLED), but the platform CAN be
+    // collected in one click from a rooted phone over USB. Reflect the real
+    // device state instead of the misleading "采集需先在手机 App 内…".
+    if (
+      this._adbReadiness &&
+      this._adbReadiness.oneClickNames.has(adapter.name) &&
+      (reason === "NO_INPUT" || reason === "INPUT_PATH_REQUIRED" || reason === "DB_NOT_PULLED")
+    ) {
+      if (adbState && adbState.deviceConnected) {
+        return {
+          ...base,
+          ready: true,
+          status: "ready",
+          category: "device",
+          reason: null,
+          message: "已连接 root 手机，点「一键采集」即可拉取",
+          actionHint: null,
+          mode: "adb-oneclick",
+          lastSyncedAt,
+          lastStatus,
+          lastError,
+        };
+      }
+      const adbDesc = describeReadiness("ADB_DEVICE_NEEDED");
+      return {
+        ...base,
+        ready: false,
+        status: adbDesc.status,
+        category: adbDesc.category,
+        reason: "ADB_DEVICE_NEEDED",
+        message: adbDesc.message,
+        actionHint: adbDesc.actionHint,
+        mode: null,
+        lastSyncedAt,
+        lastStatus,
+        lastError,
+      };
+    }
+
     const desc = describeReadiness(reason);
     const detail = auth && (auth.message || auth.error);
     const message =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlesschain/personal-data-hub",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Personal Data Hub — UnifiedSchema + validators + KG ingest helpers for the data-back-to-the-individual middleware",
   "type": "commonjs",
   "main": "lib/index.js",