@chainlesschain/personal-data-hub 0.4.1 → 0.4.3

package/__tests__/adapters/wechat-pc-direct-read.test.js

@@ -89,14 +89,52 @@ async function collect(iter) {
 }
 
 describe("WeChatPcAdapter — readiness + construction", () => {
-  it("constructs no-arg and reports DB_NOT_PULLED via readinessOnly", async () => {
+  // Synthetic "nothing installed" filesystem so auto-discovery is
+  // deterministic regardless of what's on the host running the tests.
+  const EMPTY_FS = {
+    existsSync: () => false,
+    readdirSync: () => [],
+    statSync: () => ({ size: 0 }),
+    constants: { R_OK: 4 },
+  };
+
+  it("constructs no-arg and reports APP_NOT_INSTALLED when nothing is discoverable", async () => {
     const a = new WeChatPcAdapter();
+    a._deps.discoveryDeps = { fs: EMPTY_FS, home: "/no-home", env: {} };
     expect(a.name).toBe("wechat-pc");
     expect(a.extractMode).toBe("device-pull");
     expect(a.dataDisclosure.legalGate).toBe(true);
     const r = await a.authenticate({ readinessOnly: true });
     expect(r.ok).toBe(false);
-    expect(r.reason).toBe("DB_NOT_PULLED");
+    expect(r.reason).toBe("APP_NOT_INSTALLED");
+  });
+
+  it("auto-discovers an installed WeChat 4.x DB → DB_FOUND_NEEDS_KEY", async () => {
+    // Minimal synthetic 4.x layout: ~/Documents/xwechat_files/<wxid>_N/db_storage/message/message_0.db
+    const dirs = {
+      "/h/Documents/xwechat_files": [{ name: "wxid_abc_1", isDirectory: () => true, isFile: () => false }],
+      "/h/Documents/xwechat_files/wxid_abc_1/db_storage/message": [
+        { name: "message_0.db", isDirectory: () => false, isFile: () => true },
+      ],
+    };
+    const exist = new Set([
+      "/h/Documents/xwechat_files",
+      "/h/Documents/xwechat_files/wxid_abc_1/db_storage",
+      "/h/Documents/xwechat_files/wxid_abc_1/db_storage/contact/contact.db",
+    ]);
+    const fakeFs = {
+      existsSync: (p) => exist.has(p.replace(/\\/g, "/")),
+      readdirSync: (p) => dirs[p.replace(/\\/g, "/")] || [],
+      statSync: () => ({ size: 1234 }),
+      constants: { R_OK: 4 },
+    };
+    const a = new WeChatPcAdapter();
+    a._deps.discoveryDeps = { fs: fakeFs, home: "/h", env: {}, path: require("node:path").posix };
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("DB_FOUND_NEEDS_KEY");
+    expect(r.discovered.installed).toBe(true);
+    expect(r.discovered.primaryDb).toContain("message_0.db");
   });
 
   it("readinessOnly with a configured dbPath reports configured (no DB open)", async () => {
@@ -205,3 +243,123 @@ describe("WeChatPcAdapter — options + edge cases", () => {
     );
   });
 });
+
+describe("WeChatPcAdapter — WeChat 4.x sidecar path", () => {
+  function fakeCollector(result) {
+    return async (_opts) => result;
+  }
+
+  it("opts.mode='v4' routes through the injected collector and yields messages", async () => {
+    const a = new WeChatPcAdapter({
+      v4Collector: fakeCollector({
+        account: "wxid_me",
+        messageCount: 2,
+        dbs: [{ db: "message_0.db", messageCount: 2, hmacFailures: 0 }],
+        messages: [
+          {
+            conversation: "wxid_friend",
+            sender: "wxid_friend",
+            type: 1,
+            createTime: 1700000002,
+            text: "hello from 4.0",
+            originalId: "wechat-pc:wxid_friend:1001",
+          },
+          {
+            conversation: "39354004187@chatroom",
+            sender: "wxid_other",
+            type: 1,
+            createTime: 1700000003,
+            text: "group line",
+            originalId: "wechat-pc:39354004187@chatroom:1002",
+          },
+        ],
+      }),
+    });
+    const raws = await collect(a.sync({ mode: "v4" }));
+    expect(raws).toHaveLength(2);
+    expect(raws[0].originalId).toBe("wechat-pc:wxid_friend:1001");
+    expect(raws[0].payload.text).toBe("hello from 4.0");
+    expect(raws[0].payload.isGroup).toBe(false);
+    // group message: peer is the chatroom, sender preserved
+    expect(raws[1].payload.isGroup).toBe(true);
+    expect(raws[1].payload.senderWxid).toBe("wxid_other");
+
+    // normalize reuses the 3.x path → produces a valid message event
+    const merged = { events: [], persons: [], places: [], items: [], topics: [] };
+    for (const r of raws) {
+      const n = a.normalize(r);
+      for (const k of Object.keys(merged)) if (Array.isArray(n[k])) merged[k].push(...n[k]);
+    }
+    const { valid } = partitionBatch(merged);
+    expect(valid.events.length).toBe(2);
+    const texts = valid.events.map((e) => e.content && e.content.text);
+    expect(texts).toContain("hello from 4.0");
+    expect(texts).toContain("group line");
+  });
+
+  it("v4 self-sent message marks isSend=1 when sender == account", async () => {
+    const a = new WeChatPcAdapter({
+      v4Collector: fakeCollector({
+        account: "wxid_me",
+        messages: [
+          { conversation: "wxid_friend", sender: "wxid_me", type: 1, createTime: 1700000004, text: "mine", originalId: "id-3" },
+        ],
+      }),
+    });
+    const raws = await collect(a.sync({ mode: "v4" }));
+    expect(raws[0].payload.isSend).toBe(1);
+  });
+
+  it("v4 forwards limit to the sidecar collector (sidecar owns the cap)", async () => {
+    const msgs = Array.from({ length: 5 }, (_v, i) => ({
+      conversation: "wxid_f", sender: "wxid_f", type: 1, createTime: 1700000000 + i, text: "m" + i, originalId: "id-" + i,
+    }));
+    let seenLimit = null;
+    // Collector that honors the limit, like the real Python sidecar does.
+    const collector = async (opts) => {
+      seenLimit = opts.limit;
+      return { account: "wxid_me", messages: msgs.slice(0, opts.limit || msgs.length), contacts: [] };
+    };
+    const a = new WeChatPcAdapter({ v4Collector: collector });
+    const raws = await collect(a.sync({ mode: "v4", limit: 3 }));
+    expect(seenLimit).toBe(3);
+    expect(raws.filter((r) => r.kind === "message")).toHaveLength(3);
+  });
+
+  it("v4 yields contacts from contact.db as Person entities", async () => {
+    const a = new WeChatPcAdapter({
+      v4Collector: fakeCollector({
+        account: "wxid_me",
+        messages: [
+          { conversation: "wxid_friend", sender: "wxid_friend", type: 1, createTime: 1700000002, text: "hi", originalId: "m-1" },
+        ],
+        contacts: [
+          { wxid: "wxid_friend", nickname: "昵称", remark: "备注名", alias: "alias1", type: 3 },
+          { wxid: "12345@chatroom", nickname: "群", remark: null, alias: null, type: 2 }, // skipped (chatroom)
+        ],
+      }),
+    });
+    const raws = await collect(a.sync({ mode: "v4" }));
+    const contactRaws = raws.filter((r) => r.kind === "contact");
+    expect(contactRaws).toHaveLength(1); // chatroom filtered out
+    expect(contactRaws[0].payload.wxid).toBe("wxid_friend");
+    expect(contactRaws[0].payload.remark).toBe("备注名");
+
+    // normalize → Person entity
+    const n = a.normalize(contactRaws[0]);
+    expect(n.persons.length).toBeGreaterThanOrEqual(1);
+    expect(n.persons[0].identifiers.wechatId).toBe("wxid_friend");
+  });
+
+  it("v4 can opt out of contacts via include.contact=false", async () => {
+    const a = new WeChatPcAdapter({
+      v4Collector: fakeCollector({
+        account: "wxid_me",
+        messages: [],
+        contacts: [{ wxid: "wxid_x", nickname: "n", remark: null, alias: null, type: 3 }],
+      }),
+    });
+    const raws = await collect(a.sync({ mode: "v4", include: { contact: false } }));
+    expect(raws.filter((r) => r.kind === "contact")).toHaveLength(0);
+  });
+});

package/__tests__/adapters/wechat-pc-v4-sidecar.test.js

@@ -0,0 +1,72 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { collectWeChatV4, _internals } = require("../../lib/adapters/wechat-pc/v4-sidecar");
+
+// Fake SidecarSupervisor: scripted per python exe (command[0]).
+function makeFactory(behaviorByPython, calls) {
+  return (command, _cwd) => {
+    const py = command[0];
+    calls.push(py);
+    const behavior = behaviorByPython[py] || { throwOn: "start", error: new Error("ENOENT spawn " + py) };
+    return {
+      async start() {
+        if (behavior.throwOn === "start") throw behavior.error;
+      },
+      async invoke(_method, _params, _opts) {
+        if (behavior.throwOn === "invoke") throw behavior.error;
+        return behavior.result;
+      },
+      async stop() {},
+    };
+  };
+}
+
+describe("collectWeChatV4 — python fallback + error routing", () => {
+  it("falls through to the next python when the first lacks cryptography", async () => {
+    const calls = [];
+    const result = await collectWeChatV4({
+      pythonExe: "python", // tried first
+      _supervisorFactory: makeFactory(
+        {
+          python: { throwOn: "invoke", error: new Error("ModuleNotFoundError: No module named 'cryptography'") },
+          python3: { throwOn: null, result: { account: "wxid_x", messages: [{ text: "ok" }] } },
+        },
+        calls,
+      ),
+    });
+    expect(result.account).toBe("wxid_x");
+    expect(calls[0]).toBe("python");
+    expect(calls).toContain("python3");
+  });
+
+  it("surfaces a WeChat data error immediately (no fallback)", async () => {
+    const calls = [];
+    await expect(
+      collectWeChatV4({
+        pythonExe: "python",
+        _supervisorFactory: makeFactory(
+          { python: { throwOn: "invoke", error: new Error("KEY_NOT_FOUND: key not found in Weixin.exe memory") } },
+          calls,
+        ),
+      }),
+    ).rejects.toThrow(/KEY_NOT_FOUND/);
+    expect(calls).toEqual(["python"]); // did NOT try other pythons
+  });
+
+  it("throws SIDECAR_UNAVAILABLE when no python works", async () => {
+    const calls = [];
+    await expect(
+      collectWeChatV4({
+        _supervisorFactory: makeFactory({}, calls), // all spawn-fail
+      }),
+    ).rejects.toThrow(/SIDECAR_UNAVAILABLE|could not run/);
+  });
+
+  it("pythonCandidates dedupes + honors explicit/env order", () => {
+    const list = _internals.pythonCandidates("my-python");
+    expect(list[0]).toBe("my-python");
+    expect(new Set(list).size).toBe(list.length);
+  });
+});

package/__tests__/registry-readiness.test.js

@@ -231,3 +231,62 @@ describe("AdapterRegistry.readiness()", () => {
     expect(byName(reports, "messaging-telegram").reason).toBe("DB_NOT_PULLED");
   });
 });
+
+describe("AdapterRegistry.readiness() — ADB one-click (social)", () => {
+  const oneClick = { oneClickNames: new Set(["social-bilibili"]) };
+
+  it("device connected → ready via adb-oneclick", async () => {
+    const reg = new AdapterRegistry({
+      vault: stubVault(),
+      adbReadiness: { ...oneClick, probe: async () => ({ deviceConnected: true, serial: "ABC123" }) },
+    });
+    reg.register(new BilibiliAdapter());
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(true);
+    expect(r.status).toBe(READINESS_STATUS.READY);
+    expect(r.mode).toBe("adb-oneclick");
+    expect(r.category).toBe(READINESS_CATEGORY.DEVICE);
+    expect(r.message).toMatch(/一键采集/);
+  });
+
+  it("no device → ADB_DEVICE_NEEDED (actionable, not the snapshot message)", async () => {
+    const reg = new AdapterRegistry({
+      vault: stubVault(),
+      adbReadiness: { ...oneClick, probe: async () => ({ deviceConnected: false }) },
+    });
+    reg.register(new BilibiliAdapter());
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("ADB_DEVICE_NEEDED");
+    expect(r.category).toBe(READINESS_CATEGORY.DEVICE);
+    expect(r.message).toMatch(/root|USB|手机/);
+  });
+
+  it("a probe that throws degrades to ADB_DEVICE_NEEDED (never crashes)", async () => {
+    const reg = new AdapterRegistry({
+      vault: stubVault(),
+      adbReadiness: { ...oneClick, probe: async () => { throw new Error("adb missing"); } },
+    });
+    reg.register(new BilibiliAdapter());
+    const [r] = await reg.readiness();
+    expect(r.reason).toBe("ADB_DEVICE_NEEDED");
+  });
+
+  it("non-one-click adapter is unaffected by ADB readiness", async () => {
+    const reg = new AdapterRegistry({
+      vault: stubVault(),
+      adbReadiness: { oneClickNames: new Set(["social-bilibili"]), probe: async () => ({ deviceConnected: true }) },
+    });
+    reg.register(new TelegramAdapter());
+    const [r] = await reg.readiness();
+    expect(r.name).toBe("messaging-telegram");
+    expect(r.reason).toBe("DB_NOT_PULLED"); // unchanged
+  });
+
+  it("without adbReadiness config, social adapter still reports NO_INPUT", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new BilibiliAdapter());
+    const [r] = await reg.readiness();
+    expect(r.reason).toBe("NO_INPUT");
+  });
+});

package/lib/adapter-guide.js

@@ -95,6 +95,34 @@ function localImPcGuide(platform) {
   };
 }
 
+// Shared guide for the social platforms that have a dedicated one-click ADB
+// sync (B站/微博/小红书/头条/快手) — root 手机 + USB → 界面一键按钮直接采集。
+function socialAdbGuide(platform, dataDesc) {
+  return {
+    summary: `采集${platform}的${dataDesc}。最快路径：插上已 root 的安卓手机（USB 调试）→ 在中台点该平台的「一键采集」按钮，自动从手机抓登录态并拉取数据入库——无需在网页端手动操作。`,
+    methods: [
+      {
+        label: `方式一：root 手机 + USB 一键采集（推荐）`,
+        recommended: true,
+        steps: [
+          "手机已 root，开启「开发者选项 → USB 调试」，用数据线连接电脑。",
+          "确保电脑能看到设备（命令行 `adb devices` 列出你的手机）。",
+          `手机上已登录${platform} App。`,
+          `在中台点该平台的「一键采集」按钮（或对应的 *AdbSync 操作），自动抓取登录态 + 拉取数据入库。`,
+        ],
+        note: "登录态 / cookie 仅在本地处理，不上传服务器。纯个人使用。",
+      },
+      {
+        label: "方式二：手机 App 内采集快照",
+        steps: [
+          "在手机 ChainlessChain App 内进入「数据源」，找到该平台点「采集」。",
+          "按提示在内置浏览器登录，App 采完生成快照并同步到中台。",
+        ],
+      },
+    ],
+  };
+}
+
 function displayName(name) {
   return DISPLAY_NAMES[name] || name;
 }
@@ -318,46 +346,47 @@ const ADAPTER_OVERRIDES = Object.freeze({
 
   "qq-pc": {
     summary:
-      "采集电脑版 QQ（NT 新版）的聊天记录（来自本地 nt_msg.db）。⚠️ v0.1 实验性：QQ NT 用数字化列名 + protobuf 消息体且 schema 随版本变化，文本解析为尽力而为，原始行会完整保留以便后续解析。",
+      "采集电脑版 QQ（NT 新版）的聊天记录（来自本地 nt_msg.db）。中台已支持自动解密 + 解析：取一次密钥后，自动解密 SQLCipher 库、解析 c2c/群消息的 protobuf 正文为可读文本（含发送者昵称、群号）。",
     methods: [
       {
-        label: "方式一：解密 nt_msg.db 后本地直读（推荐）",
+        label: "方式一：取密钥后一键采集（推荐）",
         recommended: true,
         steps: [
-          "登录电脑版 QQ，定位数据目录（默认 文档\\Tencent Files 或 %APPDATA%\\Tencent\\QQ\\nt_qq_*\\nt_db\\）。",
-          "用工具（如 QQNTDecrypt / PyQQ 等）解密 nt_msg.db 为明文 SQLite。",
-          "执行 `cc hub sync-adapter qq-pc --input <解密后的 nt_msg.db>`。",
-          "中台读取 c2c_msg_table / group_msg_table 入库（文本尽力解析，原始数据保留）。",
+          "在电脑上打开并登录 QQ（NT 新版，数据在 文档\\Tencent Files\\<QQ号>\\nt_qq\\nt_db\\nt_msg.db）。",
+          "下载并运行 qq-win-db-key（github.com/QQBackup/qq-win-db-key 的 windows_ntqq_get_key.ps1）。它会全关 QQ → 以调试器启动 QQ → 你登录后自动抓出 16 位密钥（形如 5{sww#,6aq=)8=A@）。",
+          "回到中台执行 `cc hub sync-adapter qq-pc --passphrase \"<那串密钥>\"`（或点该行「一键采集」并粘贴密钥）。",
+          "中台自动解密 + 解析 c2c_msg_table / group_msg_table → 可读消息入库（私聊 + 群聊，含昵称/群号）。",
         ],
-        note: "QQ NT 消息正文为 protobuf BLOB，部分类型文本可能需后续在真机上微调列/解码。诊断会显示找到了哪些表/列。",
+        note: "QQ 每次重启密钥会变，重采时重新跑 qq-win-db-key 取一次即可。纯个人使用、全程本地；首次会要求法律确认。依赖随中台分发的 Python（含 cryptography）。",
       },
       {
-        label: "方式二：提供密钥让中台尝试直接解密（试验性）",
-        steps: ["附带 `--key <hex>`，中台用 SQLCipher 尝试打开；失败则回退方式一。"],
+        label: "方式二：已解密为明文库则直接导入",
+        steps: [
+          "若已用工具把 nt_msg.db 解密为明文 SQLite，执行 `cc hub sync-adapter qq-pc --input <明文 nt_msg.db>`。",
+        ],
       },
     ],
   },
 
   "wechat-pc": {
     summary:
-      "采集电脑版微信的聊天记录 + 联系人（来自本地 MSG*.db 与 MicroMsg.db）。数据库经 SQLCipher 加密，需先解密成明文或提供 32 字节密钥再本地直读。",
+      "采集电脑版微信的聊天记录 + 公众号 + 朋友圈 + 收藏 + 联系人。微信 4.0（xwechat_files）已支持全自动一键采集：中台自动发现本机数据库、从运行中的微信进程提取密钥、解密入库——无需手动解密或装第三方工具。",
     methods: [
       {
-        label: "方式一：先解密成明文再直读（推荐，最可靠）",
+        label: "方式一：一键采集（微信 4.0，推荐，全自动）",
         recommended: true,
         steps: [
-          "在电脑登录微信 PC 版，定位数据目录（默认 文档\\WeChat Files\\<wxid>\\Msg\\）。",
-          "用工具（如 PyWxDump）从运行中的微信进程提取 32 字节密钥并解密 MSG0.db / MicroMsg.db 为明文 SQLite。",
-          "执行 `cc hub sync-adapter wechat-pc --input <解密后的 MSG0.db>` 采集聊天记录；再对 MicroMsg.db 跑一次采集联系人。",
-          "中台直接读取消息 + 联系人入库（明文 SQLite，无需再解密）。",
+          "在这台电脑上打开并登录微信（4.0 版，数据在 文档\\xwechat_files\\）。",
+          "回到中台，点 wechat-pc 这一行的「一键采集」（或 `cc hub sync-adapter wechat-pc`）。",
+          "中台自动定位各数据库 → 从微信进程内存按库取密钥 → 解密 → 聊天/公众号/朋友圈/收藏/联系人全部入库。",
         ],
-        note: "纯个人使用、全程本地。聊天记录敏感，首次会要求法律确认。多个 MSG*.db 逐个采集即可累积。",
+        note: "需要微信保持登录运行（密钥在内存里）。聊天记录含压缩消息与图片/文件/链接/引用等均会解析成可读文本。纯个人使用、全程本地，首次会要求法律确认。依赖随中台分发的 Python（含 cryptography）。",
       },
       {
-        label: "方式二：提供密钥让中台直接解密（试验性）",
+        label: "方式二：旧版微信 3.x / 手动解密",
         steps: [
-          "提取到 64 位十六进制密钥后，采集时附带 `--key <64位hex>`。",
-          "中台用 SQLCipher 配置尝试直接打开加密库；部分微信版本可直接读，失败则回退方式一。",
+          "微信 3.x（文档\\WeChat Files\\<wxid>\\Msg\\）用工具（如 PyWxDump）解密 MSG0.db / MicroMsg.db 为明文。",
+          "执行 `cc hub sync-adapter wechat-pc --input <解密后的 .db>`（或附 `--key <64位hex>` 让中台尝试直接解密）。",
         ],
       },
     ],
@@ -366,6 +395,12 @@ const ADAPTER_OVERRIDES = Object.freeze({
   "dingtalk-pc": localImPcGuide("钉钉"),
   "feishu-pc": localImPcGuide("飞书"),
 
+  "social-bilibili": socialAdbGuide("哔哩哔哩", "观看历史 / 收藏 / 动态 / 关注"),
+  "social-weibo": socialAdbGuide("微博", "微博 / 收藏 / 关注"),
+  "social-xiaohongshu": socialAdbGuide("小红书", "笔记 / 点赞收藏 / 关注"),
+  "social-toutiao": socialAdbGuide("今日头条", "阅读 feed / 收藏 / 搜索历史"),
+  "social-kuaishou": socialAdbGuide("快手", "作品 / 推荐 / 个人主页"),
+
   "social-douyin": {
     summary:
       "采集抖音私信 + 联系人（来自 App 本地明文数据库 <uid>_im.db）。明文 SQLite、无加密、无 X-Bogus 签名——本地直读是最可靠的方式。",

package/lib/adapter-readiness.js

@@ -86,6 +86,29 @@ const REASONS = Object.freeze({
     actionHint: "通过 ADB / 本地 DB 解密导出数据库后再同步",
     appendDetail: true,
   },
+  // 自动发现：已在本机找到 App 的加密数据库，只差解密密钥即可一键采集。
+  DB_FOUND_NEEDS_KEY: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "已自动找到本机数据库（已加密），仅需解密密钥即可一键采集",
+    actionHint: "提取该 App 的数据库密钥后点「一键采集」（密钥可从运行中的 App 提取）",
+    appendDetail: true,
+  },
+  // ADB 一键平台：后端支持 root 手机 USB 一键采集，但当前未检测到设备。
+  ADB_DEVICE_NEEDED: {
+    status: READINESS_STATUS.NEEDS_SETUP,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "可一键采集：请插上已 root 的安卓手机并开启 USB 调试（adb 可见后点「一键采集」）",
+    actionHint: "连接手机后刷新，即可一键拉取",
+  },
+  // 自动发现：未检测到 App 的本机数据（未安装 / 未登录 / 非默认目录）。
+  APP_NOT_INSTALLED: {
+    status: READINESS_STATUS.UNAVAILABLE,
+    category: READINESS_CATEGORY.DEVICE,
+    message: "未检测到该 App 的本机数据（可能未安装、未登录或装在非默认目录）",
+    actionHint: "在本机安装并登录该 App 后重试，或改用手机端采集",
+    appendDetail: true,
+  },
   NO_KEY_PROVIDER: {
     status: READINESS_STATUS.NEEDS_SETUP,
     category: READINESS_CATEGORY.DEVICE,

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

@@ -58,12 +58,41 @@ function createLocalImPcAdapter(cfg) {
       this._deps = { fs, dbDriverFactory: opts.dbDriverFactory || null };
     }
 
+    _autoDiscover() {
+      if (this._discovered !== undefined) return this._discovered;
+      try {
+        // eslint-disable-next-line global-require
+        const { discover } = require("./_pc-local-discovery");
+        this._discovered = discover(NAME, 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" };
-        return { ok: false, reason: "DB_NOT_PULLED", message: cfg.needHint };
+        const disc = this._autoDiscover();
+        if (disc && disc.installed) {
+          // best-effort plaintext DB → one-click ready; encrypted → needs key
+          if (!disc.encrypted) return { ok: true, mode: "auto-discovered" };
+          return {
+            ok: false,
+            reason: "DB_FOUND_NEEDS_KEY",
+            message: `已找到本机 ${PLATFORM} 库（主库 ${disc.primaryDb}），可能需解密`,
+            discovered: disc,
+          };
+        }
+        return { ok: false, reason: "APP_NOT_INSTALLED", message: (disc && disc.note) || cfg.needHint };
       }
-      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);
@@ -72,7 +101,7 @@ function createLocalImPcAdapter(cfg) {
         }
         return { ok: true, mode: "sqlite" };
       }
-      return { ok: false, reason: "DB_NOT_PULLED", message: `${NAME}.authenticate: needs opts.dbPath / inputPath` };
+      return { ok: false, reason: "APP_NOT_INSTALLED", message: `${NAME}.authenticate: 未检测到本机 ${PLATFORM} 库，也未提供 dbPath / inputPath` };
     }
 
     async healthCheck() {
@@ -80,8 +109,8 @@ function createLocalImPcAdapter(cfg) {
     }
 
     async *sync(opts = {}) {
-      const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
-      if (!dbPath) throw new Error(`${NAME}.sync: needs opts.dbPath / opts.inputPath`);
+      const dbPath = opts.dbPath || opts.inputPath || this._dbPath || this._resolveDiscoveredDbPath();
+      if (!dbPath) throw new Error(`${NAME}.sync: 未找到本机 ${PLATFORM} 库且未提供 opts.dbPath / opts.inputPath`);
       if (!this._deps.fs.existsSync(dbPath)) return;
 
       // eslint-disable-next-line global-require