cortico-world-wechat 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+本文件的 `## <版本号>` 段落会显示在扩展市场的发布时间线上（索引仓的 Action 按同样规则切段）。
+
+## 0.1.0
+
+首个公开版本。
+
+- **World 扩展（主体）**：监听、解密、轮询、限流、推送全部在扩展内，随 Coopanion 启动，
+  没有独立常驻进程、没有 exe、没有开机自启任务。
+- **解密**：纯 `node:crypto` 按页解密微信 4.x 本地库（AES-256-CBC raw CBC），并合并 `-wal` 增量帧。
+- **轮询**：以 `sort_seq` 为水位（落盘），按会话增量读取新消息。
+- **限流**：全局最短间隔、同会话冷却、静默时段（被吞掉即丢弃、不补发）。
+- **取密钥**：微信的库密钥只存在于其进程内存中，由 `tools/fetch-keys.py` 按需取出
+  （短命进程，取完即退；失效时自动重取）。这是本项目唯一用到 Python 的地方。
+- 实测：真机库解密 `PRAGMA integrity_check = ok`；测试 26 例（7 监听逻辑 + 6 文本格式化 + 13 World 行为）。

package/describe.json

@@ -0,0 +1,24 @@
+{
+  "tools": [],
+  "events": [
+    {
+      "type": "wechat-notifier.notice",
+      "description": {
+        "zh": "微信里有人给你发消息了。",
+        "en": "Someone sent you a WeChat message."
+      },
+      "trigger": "flush",
+      "tags": [
+        "speak"
+      ]
+    }
+  ],
+  "prompts": [
+    {
+      "key": "wechat_notifier_duty",
+      "title": "微信消息提示的职责说明",
+      "role": "envPrompt",
+      "content": "微信消息提示是给你看的：微信里有人给你发消息了。看到要主动用 pet_say 简短汇报给胡闹（一句话说清\"谁在哪个会话说了什么\"，别念全文），不要只是记下来就结束这一轮。自己发的消息不用汇报。"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "cortico-world-wechat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "把 Windows 微信新消息播报给桌宠：扩展自己解密并轮询微信本地库，把新消息推进桌宠的事件流，由桌宠决定怎么汇报。",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "tools",
+    "describe.json",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3-multiple-ciphers": "^13.0.3",
+    "ws": "^8.21.3"
+  },
+  "keywords": [
+    "cortico-world",
+    "cortico",
+    "wechat",
+    "weixin",
+    "notifier"
+  ],
+  "cortico": {
+    "displayName": "微信消息提示",
+    "kind": "world",
+    "api": 6,
+    "describe": "describe.json",
+    "tags": [
+      "im",
+      "external-setup",
+      "experimental",
+      "sensitive-data"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/format.test.mjs test/world.test.mjs"
+  }
+}

package/src/format.js

@@ -0,0 +1,50 @@
+/**
+ * 微信事件帧 → 给桌宠看的一句人话。
+ *
+ * 刻意做成纯函数：不碰网络、不碰宿主，方便单测把"她会听到什么"钉死。
+ *
+ * 措辞原则（沿用 companion-bridge 的实测教训，2026-10-16）：
+ * 只陈述事实（"张三发了条消息"）会被她当成**状态信息**——她完整读到、跑一轮推理，
+ * 然后 end_turn 一声不吭。所以正文要**带上动作要求**，把"信息"变成"要回应的请求"。
+ */
+
+/** 单条文字上限，避免一帧把气泡撑爆。 */
+const TEXT_MAX = 160;
+
+/** 折叠空白并截断。 */
+function clip(text, max = TEXT_MAX) {
+  const s = String(text ?? '').replace(/\s+/g, ' ').trim();
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…`;
+}
+
+/**
+ * 事件帧 → 事件正文。
+ *
+ * 帧形状（Python 侧 ws_client.py 定义，字段全部来自微信库实测）：
+ *   { t:'notice', v:1, kind:'message', chat, chat_username, sender, is_group, preview, ts, local_id, shard }
+ *   { t:'hello', v:1, role:'wechat-listener' }
+ *
+ * @param {Record<string, unknown>} frame
+ * @returns {string | null} null = 这一帧不需要她知道
+ */
+export function frameToText(frame) {
+  if (!frame || typeof frame !== 'object') return null;
+  if (frame.t !== 'notice') return null; // hello 等控制帧不是给她听的内容
+  if (frame.kind && frame.kind !== 'message') return null;
+
+  const chat = clip(frame.chat, 40) || '某个会话';
+  const sender = clip(frame.sender, 24) || '某人';
+  const preview = clip(frame.preview, 100);
+
+  // 自己发的消息不催办：她不需要被提醒"你自己说了句话"
+  if (sender === '我') {
+    return `【微信】你在「${chat}」发了一条消息。`;
+  }
+
+  const where = frame.is_group === true ? `群「${chat}」里的 ${sender}` : sender;
+  const content = preview ? `：${preview}` : '（没有正文，可能是图片或文件）';
+  return `【微信】${where}发来消息${content}。跟胡闹说一声。`;
+}
+
+export { clip };

package/src/index.js

@@ -0,0 +1,49 @@
+/**
+ * cortico-world-wechat —— 包入口：默认导出就是 WorldDefinition。
+ *
+ * 契约要点（照本机 Coopanion 0.2.0 的 cortico-world-fatfish/types/cortico.d.ts 写，别凭记忆）：
+ *   definition = { id, label, defaults(), preflight?, create(ctx) }
+ *   create 返回的实例 = { id, envPromptVars(), tools(), console?(), start(host), stop() }
+ * 安装：包放进 Coopanion 的 data/extensions/node_modules/，
+ *      在 data/home/companion/config.json 的 worlds.wechat-notifier.enabled 打开，重启生效。
+ */
+import { WECHAT_ID, WechatWorld, wechatDefaults } from './world.js';
+
+/** 延迟取 ws 实现：顶层 import 会在她加载扩展时就解析依赖，失败会连累整个扩展。 */
+const loadWs = () => import('ws');
+
+/** World 定义。 */
+export const WECHAT_WORLD = {
+  id: WECHAT_ID,
+  label: '微信消息提示',
+  /** 每次返回新对象，避免框架深处的修改互相串台。 */
+  defaults: wechatDefaults,
+  preflight(ctx) {
+    const url = String(ctx?.cfg?.url ?? '');
+    if (!/^ws:\/\/127\.0\.0\.1:\d+\//.test(url)) {
+      throw new Error(`微信提示需要 ws://127.0.0.1:<port>/<path> 形式的地址，实际: ${url}`);
+    }
+  },
+  create(ctx) {
+    return new WechatWorld(WECHAT_ID, ctx?.cfg ?? {}, loadWs);
+  },
+  describe: {
+    tools: [],
+    events: [
+      {
+        // 必须是 pushEvent 实际用的类型（<worldId>.notice），否则框架会警告
+        // "事件 type 不在 describe.events 里"。已用运行时实测锁定，见 test/world.test.mjs。
+        type: `${WECHAT_ID}.notice`,
+        description: {
+          zh: '微信里有人给你发消息了。',
+          en: 'Someone sent you a WeChat message.',
+        },
+        tags: ['speak'],
+      },
+    ],
+  },
+};
+
+export default WECHAT_WORLD;
+export { WechatWorld, wechatDefaults, WECHAT_ID } from './world.js';
+export { frameToText } from './format.js';

package/src/keys.js

@@ -0,0 +1,109 @@
+/**
+ * 密钥来源（key oracle）：向"短命取密钥工具"要密钥，并缓存到本地 JSON。
+ *
+ * 职责边界：
+ *   - 它**不做**内存扫描（那部分由 tools/fetch-keys.py 完成，见该文件头注释解释原因）；
+ *   - 它只负责：按需拉起工具、读回 keys.json、判断缓存是否可用、密钥失效时重新取。
+ *
+ * 失效判定：解密时若某库的页 HMAC 校验不过，说明微信重新登录/升级导致密钥变了，
+ * 此时调用 refresh() 重取一次即可（用户无感）。
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(here, '..');
+
+/** 默认输出位置：与安装目录无关，换版本不丢（keys.json 含密钥，切勿入库） */
+export function defaultKeysPath() {
+  const base = process.env.LOCALAPPDATA ?? process.env.HOME ?? '.';
+  return join(base, 'WeChatNotifier', 'keys.json');
+}
+
+/** 找一个能跑取密钥脚本的 Python：优先工作区外的 venv，其次 PATH 里的 python。 */
+function resolvePython(explicit) {
+  if (explicit) return explicit;
+  const candidates = [];
+  if (process.env.WECHAT_NOTIFIER_PYTHON) candidates.push(process.env.WECHAT_NOTIFIER_PYTHON);
+  if (process.env.LOCALAPPDATA) {
+    candidates.push(join(process.env.LOCALAPPDATA, 'wechat-notifier-venv', 'Scripts', 'python.exe'));
+  }
+  candidates.push('python');
+  return candidates;
+}
+
+export class KeyOracle {
+  /**
+   * @param {{ keysPath?: string, python?: string, timeoutMs?: number, logger?: object }} [options]
+   */
+  constructor(options = {}) {
+    this.keysPath = options.keysPath ?? defaultKeysPath();
+    this.pythonCandidates = resolvePython(options.python);
+    this.timeoutMs = options.timeoutMs ?? 120000;
+    this.log = options.logger ?? { info: () => {}, warn: () => {} };
+    this.cache = null;
+  }
+
+  /** 读缓存（不触发取密钥）；文件不存在或非法返回 null */
+  loadCache() {
+    try {
+      if (!existsSync(this.keysPath)) return null;
+      const payload = JSON.parse(readFileSync(this.keysPath, 'utf8'));
+      if (!payload?.keys || typeof payload.keys !== 'object') return null;
+      this.cache = payload;
+      return payload;
+    } catch (error) {
+      this.log.warn?.(`[keys] 读缓存失败：${error.message}`);
+      return null;
+    }
+  }
+
+  /** 密钥对象：{ 'contact\\contact.db': Buffer } */
+  keys() {
+    const payload = this.cache ?? this.loadCache();
+    if (!payload) return new Map();
+    const out = new Map();
+    for (const [rel, hex] of Object.entries(payload.keys)) {
+      out.set(rel, Buffer.from(hex, 'hex'));
+    }
+    return out;
+  }
+
+  /** 强制重新取密钥（拉起短命 Python）；成功返回 payload，失败抛错并带上原因 */
+  async refresh() {
+    const script = join(packageRoot, 'tools', 'fetch-keys.py');
+    if (!existsSync(script)) throw new Error(`找不到取密钥脚本: ${script}`);
+
+    let lastError = null;
+    for (const python of this.pythonCandidates) {
+      try {
+        this.log.info?.(`[keys] 用 ${python} 取密钥…`);
+        const { stdout, stderr } = await execFileAsync(
+          python,
+          [script, this.keysPath],
+          { timeout: this.timeoutMs, windowsHide: true, env: { ...process.env, PYTHONUTF8: '1' } },
+        );
+        if (stdout?.trim()) this.log.info?.(`[keys] ${stdout.trim()}`);
+        if (stderr?.trim()) this.log.warn?.(`[keys] ${stderr.trim()}`);
+        const payload = this.loadCache();
+        if (payload) return payload;
+        lastError = new Error('脚本执行成功但没有产出 keys.json');
+      } catch (error) {
+        lastError = error;
+        this.log.warn?.(`[keys] ${python} 失败：${error.message}`);
+      }
+    }
+    throw new Error(`取密钥失败（已试 ${this.pythonCandidates.length} 个解释器）：${lastError?.message ?? '未知原因'}`);
+  }
+
+  /** 保证有可用密钥：缓存有就用，没有就取一次。 */
+  async ensure() {
+    const payload = this.loadCache();
+    if (payload) return payload;
+    return this.refresh();
+  }
+}

package/src/wechat-crypto.js

@@ -0,0 +1,84 @@
+/**
+ * 微信 4.x 本地加密库解密器（Node 实现，已验证）。
+ *
+ * 依据：wechatauto-replica 的 db.py（_decrypt_page / _verify_enc_key）。
+ * 本方已实测验证：contact.db 1867 页、message_3.db 5224 页，解密后
+ * `PRAGMA integrity_check` 均为 ok，并能读出真实消息行。
+ *
+ * ⚠️ 四个踩过的坑（任一错都得乱码或 bad decrypt）：
+ *   ① Node 的 AES 必须 setAutoPadding(false)：SQLCipher 页是 raw CBC，无 PKCS#7 填充；
+ *   ② IV 在页内偏移 [4016:4032]（保留区前 16 字节），不是文件头盐、也不是页尾；
+ *   ③ 第 1 页密文是 [16:4016)，且明文头 16 字节是硬编码的 "SQLite format 3\0"；
+ *   ④ 第 2 页起密文从 offset 0 开始（即 [0:4016)）。
+ */
+import { createDecipheriv, createHmac, pbkdf2Sync } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mkdirSync } from 'node:fs';
+
+export const PAGE_SIZE = 4096;
+export const RESERVE = 80;
+/** 第 1 页明文头：SQLCipher 加密盐不参与明文，明库里是标准 SQLite 魔数 */
+export const SQLITE_MAGIC = Buffer.from('SQLite format 3\0', 'latin1');
+
+/** 解密一页（与上游 _decrypt_page 逐行等价） */
+export function decryptPage(key, page, pageNumber) {
+  const reserveStart = PAGE_SIZE - RESERVE;
+  const iv = page.subarray(reserveStart, reserveStart + 16);
+  const cipherText = pageNumber === 1 ? page.subarray(16, reserveStart) : page.subarray(0, reserveStart);
+  const decipher = createDecipheriv('aes-256-cbc', key, iv);
+  decipher.setAutoPadding(false);
+  const plain = Buffer.concat([decipher.update(cipherText), decipher.final()]);
+  const head = pageNumber === 1 ? SQLITE_MAGIC : Buffer.alloc(0);
+  return Buffer.concat([head, plain, Buffer.alloc(RESERVE)]).subarray(0, PAGE_SIZE);
+}
+
+/** 整库解密到目标文件；返回页数 */
+export function decryptFile(srcPath, dstPath, key) {
+  const data = readFileSync(srcPath);
+  const pages = Math.ceil(data.length / PAGE_SIZE);
+  const out = Buffer.alloc(pages * PAGE_SIZE);
+  for (let pageNumber = 1; pageNumber <= pages; pageNumber += 1) {
+    const start = (pageNumber - 1) * PAGE_SIZE;
+    const page = Buffer.alloc(PAGE_SIZE);
+    data.copy(page, 0, start, Math.min(start + PAGE_SIZE, data.length));
+    decryptPage(key, page, pageNumber).copy(out, start);
+  }
+  mkdirSync(dirname(dstPath), { recursive: true });
+  writeFileSync(dstPath, out);
+  return pages;
+}
+
+/** 读第一页（取不到返回 null） */
+export function readPage1(filePath) {
+  try {
+    const data = readFileSync(filePath);
+    return data.length < PAGE_SIZE ? null : data.subarray(0, PAGE_SIZE);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * SQLCipher4 页 1 的 HMAC 校验 —— 用来判断"这把密钥能不能开这个库"。
+ * 细节：mac_salt = salt ^ 0x3a，KDF 迭代 2，HMAC 输入末尾追加小端 4 字节页号。
+ */
+export function verifyDbKey(dbKey, page1, explicitSalt = null) {
+  let key = dbKey;
+  let salt = explicitSalt ?? page1.subarray(0, 16);
+  if (dbKey.length === 48 && !explicitSalt) {
+    key = dbKey.subarray(0, 32);
+    salt = dbKey.subarray(32, 48);
+  } else if (dbKey.length === 48) {
+    key = dbKey.subarray(0, 32);
+  }
+  const macSalt = Buffer.from(salt);
+  for (let i = 0; i < macSalt.length; i += 1) macSalt[i] ^= 0x3a;
+  const macKey = pbkdf2Sync(key, macSalt, 2, 32, 'sha512');
+  const hmacData = page1.subarray(16, PAGE_SIZE - RESERVE + 16);
+  const stored = page1.subarray(PAGE_SIZE - 64, PAGE_SIZE);
+  const pageNo = Buffer.alloc(4);
+  pageNo.writeUInt32LE(1, 0);
+  const actual = createHmac('sha512', macKey).update(hmacData).update(pageNo).digest();
+  return actual.equals(stored);
+}

package/src/wechat-db.js

@@ -0,0 +1,274 @@
+/**
+ * 微信本地库读取器（Node）：解密 + WAL 增量合并 + 按会话增量读新消息。
+ *
+ * 与 Python 侧（wechatauto-replica）的关系：本文件是它的**读库子集**在 Node 的等价实现。
+ * 算法依据全部来自 db.py 的对应函数，并已在本机实测：
+ *   - contact.db / message_3.db 解密后 PRAGMA integrity_check = ok
+ *   - 能读出真实消息行（local_id / create_time / local_type / message_content）
+ *
+ * 只读：不写微信库、不动微信进程；解密产物落在自己的缓存目录。
+ */
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, openSync, readSync, closeSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+import { PAGE_SIZE, decryptPage, decryptFile, readPage1, verifyDbKey } from './wechat-crypto.js';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * 惰性加载 sqlite 绑定。
+ *
+ * 为什么不在顶层 require：该模块是原生扩展（.node），顶层加载会让
+ * **纯逻辑使用方**（例如只想测 previewText/限流的单测）也被迫依赖它，
+ * 一旦运行环境没装原生模块就整体 ImportError。改成用到时才加载。
+ */
+let Database = null;
+function getDatabase() {
+  if (!Database) Database = require('better-sqlite3-multiple-ciphers');
+  return Database;
+}
+
+const WAL_HEADER_SIZE = 32;
+const WAL_FRAME_SIZE = 24 + PAGE_SIZE;
+
+/** 递归列出 db_storage 下所有 .db（跳过 -wal/-shm） */
+export function listDbFiles(dbStorage) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (entry.name.endsWith('.db') && !/-wal$|-shm$/.test(entry.name)) out.push(full);
+    }
+  };
+  walk(dbStorage, 0);
+  return out;
+}
+
+/** 相对 db_storage 的键名（与上游 keys.json 的键一致，统一用反斜杠） */
+export function relKey(dbStorage, filePath) {
+  return filePath.slice(dbStorage.length).replace(/^[\\/]/, '').replace(/\//g, '\\');
+}
+
+/** 消息分片：message\message_N.db */
+export function listMessageShards(dbStorage) {
+  return listDbFiles(join(dbStorage, 'message'))
+    .filter((p) => /^message_\d+\.db$/.test(basename(p)))
+    .sort();
+}
+
+/**
+ * 把 -wal 里的加密帧合并进已解密的主库（与上游 _merge_wal 等价）。
+ * 帧：24 字节头 + 4096 页，数值全为**大端**；只合并 salt 与 WAL 头一致的帧
+ * （checkpoint 会重置 WAL，旧世代帧合并会用过期页覆盖新数据 → 库损坏）。
+ */
+export function mergeWal(decryptedPath, walPath, key, fromFrame = 0) {
+  if (!existsSync(decryptedPath) || !existsSync(walPath)) return { applied: 0, frames: 0 };
+  const walFd = openSync(walPath, 'r');
+  const dstFd = openSync(decryptedPath, 'r+');
+  let applied = 0;
+  let last = fromFrame;
+  try {
+    const walSize = statSync(walPath).size;
+    const header = Buffer.alloc(WAL_HEADER_SIZE);
+    readSync(walFd, header, 0, WAL_HEADER_SIZE, 0);
+    const walSalt = header.subarray(16, 24);
+    const totalFrames = Math.floor((walSize - WAL_HEADER_SIZE) / WAL_FRAME_SIZE);
+    let maxPgno = 0;
+    for (let i = fromFrame; i < totalFrames; i += 1) {
+      const frame = Buffer.alloc(WAL_FRAME_SIZE);
+      const read = readSync(walFd, frame, 0, WAL_FRAME_SIZE, WAL_HEADER_SIZE + i * WAL_FRAME_SIZE);
+      if (read < WAL_FRAME_SIZE) break;
+      last = i + 1;
+      if (!frame.subarray(8, 16).equals(walSalt)) continue; // 旧世代帧：跳过
+      const pgno = frame.readUInt32BE(0);
+      const page = frame.subarray(24);
+      const plain = decryptPage(key, page, pgno);
+      if (pgno === 1) {
+        if (!plain.subarray(0, 16).equals(Buffer.from('SQLite format 3\0', 'latin1'))) continue;
+      } else if (![0, 2, 5, 10, 13].includes(plain[0])) {
+        continue;
+      }
+      writeFileSync(dstFd, plain, { offset: (pgno - 1) * PAGE_SIZE });
+      if (pgno > maxPgno) maxPgno = pgno;
+      applied += 1;
+    }
+    // 把实际的页数写回 header（+28，大端）；不写会让 sqlite 认为库比实际短
+    if (maxPgno > 0) {
+      const page1 = Buffer.alloc(PAGE_SIZE);
+      readSync(dstFd, page1, 0, PAGE_SIZE, 0);
+      const fileSize = statSync(decryptedPath).size;
+      const dbPages = Math.ceil(fileSize / PAGE_SIZE);
+      const headerPages = page1.readUInt32BE(28);
+      const newPages = Math.max(headerPages, maxPgno, dbPages);
+      if (newPages !== headerPages) {
+        const patched = Buffer.from(page1);
+        patched.writeUInt32BE(newPages, 28);
+        writeFileSync(dstFd, patched, { offset: 0 });
+      }
+    }
+    return { applied, frames: last };
+  } finally {
+    closeSync(walFd);
+    closeSync(dstFd);
+  }
+}
+
+/** 读取器：管理"密钥 + 解密缓存 + 增量读消息" */
+export class WeChatReader {
+  /**
+   * @param {{ dbStorage: string, keys: Map<string, Buffer>, cacheDir: string, logger?: object }} options
+   */
+  constructor(options) {
+    this.dbStorage = options.dbStorage;
+    this.keys = options.keys;           // Map<'contact\\contact.db', Buffer>
+    this.cacheDir = options.cacheDir;
+    this.log = options.logger ?? { info: () => {}, warn: () => {}, debug: () => {} };
+    this._stamps = new Map();            // rel -> { mtimeMs, size, walFrames }
+    mkdirSync(this.cacheDir, { recursive: true });
+  }
+
+  keyFor(rel) {
+    return this.keys.get(rel) ?? null;
+  }
+
+  /** 按需解密（含 WAL 合并）；主库或 WAL 变化时增量重做 */
+  ensureDecrypted(rel) {
+    const srcPath = join(this.dbStorage, rel);
+    const walPath = `${srcPath}-wal`;
+    const dstPath = join(this.cacheDir, rel.replace(/[\\/]/g, '__'));
+    const key = this.keyFor(rel);
+    if (!key) throw new Error(`没有该库的密钥: ${rel}`);
+    const srcStat = statSync(srcPath);
+    const walStat = existsSync(walPath) ? statSync(walPath) : null;
+    const stamp = this._stamps.get(rel);
+
+    const sameMain = stamp && stamp.mtimeMs === srcStat.mtimeMs && stamp.size === srcStat.size;
+    const sameWal = stamp && (stamp.walSize ?? 0) === (walStat?.size ?? 0);
+    if (sameMain && sameWal && existsSync(dstPath)) return dstPath;
+
+    if (!sameMain || !existsSync(dstPath)) {
+      const pages = decryptFile(srcPath, dstPath, key);
+      this.log.debug?.(`[reader] 解密 ${rel}（${pages} 页）`);
+      this._stamps.set(rel, { mtimeMs: srcStat.mtimeMs, size: srcStat.size, walSize: 0, walFrames: 0 });
+      this._verifyOrThrow(rel, dstPath);
+    }
+    if (walStat) {
+      const prevFrames = this._stamps.get(rel)?.walFrames ?? 0;
+      const { frames } = mergeWal(dstPath, walPath, key, prevFrames);
+      const current = this._stamps.get(rel) ?? {};
+      this._stamps.set(rel, { ...current, walSize: walStat.size, walFrames: frames });
+    }
+    return dstPath;
+  }
+
+  /** 解密结果是否真是这个库（防止拿错密钥时静默读出垃圾） */
+  _verifyOrThrow(rel, dstPath) {
+    const page1 = readPage1(dstPath);
+    if (!page1) throw new Error(`解密产物读不到首页: ${rel}`);
+    if (!page1.subarray(0, 16).equals(Buffer.from('SQLite format 3\0', 'latin1'))) {
+      throw new Error(`解密结果不是 SQLite 库（密钥可能已失效）: ${rel}`);
+    }
+    const probe = join(this.dbStorage, rel);
+    const enc = readPage1(probe);
+    if (enc && !verifyDbKey(this.keyFor(rel), enc)) {
+      throw new Error(`密钥已失效（微信可能重新登录过）: ${rel}`);
+    }
+  }
+
+  open(rel) {
+    const path = this.ensureDecrypted(rel);
+    const Sqlite = getDatabase();
+    return new Sqlite(path, { readonly: true, fileMustExist: true });
+  }
+
+  /** 会话列表：username + 显示名 + 未读（用于"会话名 → wxid"解析） */
+  listSessions(limit = 200) {
+    const db = this.open('session\\session.db');
+    try {
+      const rows = db.prepare('SELECT * FROM SessionTable ORDER BY last_timestamp DESC LIMIT ?').all(limit);
+      return rows.map((row) => ({
+        username: row.username,
+        unread: row.unread_count ?? 0,
+        summary: row.summary ?? '',
+        lastTime: row.last_timestamp ?? 0,
+      }));
+    } finally {
+      db.close();
+    }
+  }
+
+  /** 昵称/备注表：wxid → 显示名 */
+  listContacts() {
+    const db = this.open('contact\\contact.db');
+    try {
+      const rows = db.prepare('SELECT username, local_type, remark, nick_name FROM contact').all();
+      const map = new Map();
+      for (const row of rows) {
+        const name = row.remark || row.nick_name || row.username;
+        if (row.username) map.set(row.username, name);
+      }
+      return map;
+    } finally {
+      db.close();
+    }
+  }
+
+  /**
+   * 分片内所有 Msg_* 表的 sort_seq 最大值（毫秒）——水位基线用。
+   *
+   * ⚠️ 为什么不用 local_id：**local_id 在每个会话表内部各自计数**，不同 Msg_* 表之间不单调。
+   * 实测踩过：message_3.db 里一条 4 分钟前的新消息 local_id=2392 < 该分片"最大 local_id" 2564，
+   * 用 local_id 当水位会把它永久跳过。sort_seq（毫秒时间戳）才是可比的增量键。
+   */
+  maxSortSeq(shardRel) {
+    const db = this.open(shardRel);
+    try {
+      const tables = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'Msg_%'")
+        .all()
+        .map((t) => t.name);
+      let max = 0;
+      for (const table of tables) {
+        const row = db.prepare(`SELECT MAX(sort_seq) AS m FROM ${table}`).get();
+        if (row?.m && row.m > max) max = row.m;
+      }
+      return { max, tables };
+    } finally {
+      db.close();
+    }
+  }
+
+  /** 读某个分片里 sort_seq > since 的新消息（按会话分组前的原始行） */
+  readNewRows(shardRel, since) {
+    const db = this.open(shardRel);
+    try {
+      const tables = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'Msg_%'")
+        .all()
+        .map((t) => t.name);
+      const rows = [];
+      for (const table of tables) {
+        const list = db
+          .prepare(
+            `SELECT local_id, server_id, local_type, sort_seq, real_sender_id, create_time, message_content
+             FROM ${table} WHERE sort_seq > ? ORDER BY sort_seq ASC LIMIT 200`,
+          )
+          .all(since);
+        for (const row of list) rows.push({ ...row, table, shard: shardRel });
+      }
+      rows.sort((a, b) => (a.sort_seq ?? 0) - (b.sort_seq ?? 0));
+      return rows;
+    } finally {
+      db.close();
+    }
+  }
+}