feat(wcdb): 扩展实时 WCDB 原生查询接口

- 增加 native message cursor 的 open/fetch/close 封装，用于跨 message_*.db 分片读取消息

- 增加 wcdb_get_contact 封装，用于按 username 读取 contact 表资料

- 同步 Electron sidecar 的 FFI 声明和 action 分发

Author: 2977094657

desktop/src/wcdb-sidecar.cjs

@@ -169,6 +169,18 @@ function loadNative() {
   funcs.wcdb_get_messages = tryFunc(
     "int32 wcdb_get_messages(int64 handle, const char* username, int32 limit, int32 offset, _Out_ void** outJson)"
   );
+  funcs.wcdb_open_message_cursor = tryFunc(
+    "int32 wcdb_open_message_cursor(int64 handle, const char* sessionId, int32 batchSize, int32 ascending, int32 beginTimestamp, int32 endTimestamp, _Out_ int64* cursor)"
+  );
+  funcs.wcdb_open_message_cursor_lite = tryFunc(
+    "int32 wcdb_open_message_cursor_lite(int64 handle, const char* sessionId, int32 batchSize, int32 ascending, int32 beginTimestamp, int32 endTimestamp, _Out_ int64* cursor)"
+  );
+  funcs.wcdb_fetch_message_batch = tryFunc(
+    "int32 wcdb_fetch_message_batch(int64 handle, int64 cursor, _Out_ void** outJson, _Out_ int32* hasMore)"
+  );
+  funcs.wcdb_close_message_cursor = tryFunc(
+    "int32 wcdb_close_message_cursor(int64 handle, int64 cursor)"
+  );
   funcs.wcdb_get_message_count = tryFunc(
     "int32 wcdb_get_message_count(int64 handle, const char* username, _Out_ int32* count)"
   );
@@ -178,6 +190,9 @@ function loadNative() {
   funcs.wcdb_get_avatar_urls = tryFunc(
     "int32 wcdb_get_avatar_urls(int64 handle, const char* usernamesJson, _Out_ void** outJson)"
   );
+  funcs.wcdb_get_contact = tryFunc(
+    "int32 wcdb_get_contact(int64 handle, const char* username, _Out_ void** outJson)"
+  );
   funcs.wcdb_get_group_member_count = tryFunc(
     "int32 wcdb_get_group_member_count(int64 handle, const char* chatroomId, _Out_ int32* count)"
   );
@@ -362,6 +377,48 @@ function handleAction(action, payload) {
         ]),
       };
 
+    case "open_message_cursor":
+    case "open_message_cursor_lite": {
+      const fnName = action === "open_message_cursor_lite" ? "wcdb_open_message_cursor_lite" : "wcdb_open_message_cursor";
+      const out = [0];
+      const rc = Number(
+        requireFunc(fnName)(
+          normalizeHandle(data.handle),
+          String(data.session_id || "").trim(),
+          Number.parseInt(String(data.batch_size || 0), 10) || 1,
+          data.ascending ? 1 : 0,
+          Number.parseInt(String(data.begin_timestamp || 0), 10) || 0,
+          Number.parseInt(String(data.end_timestamp || 0), 10) || 0,
+          out
+        )
+      );
+      const cursor = Number(out[0] || 0);
+      if (rc !== 0 || cursor <= 0) throw new ApiError(`${fnName} failed`, rc);
+      return { cursor, rc };
+    }
+
+    case "fetch_message_batch": {
+      const fn = requireFunc("wcdb_fetch_message_batch");
+      const out = [null];
+      const outHasMore = [0];
+      const rc = Number(fn(normalizeHandle(data.handle), normalizeHandle(data.cursor), out, outHasMore));
+      try {
+        if (rc !== 0 || !out[0]) throw new ApiError("wcdb_fetch_message_batch failed", rc);
+        return {
+          payload: ptrToString(out[0]),
+          hasMore: Number(outHasMore[0] || 0) === 1,
+          rc,
+        };
+      } finally {
+        freeStringPtr(out[0]);
+      }
+    }
+
+    case "close_message_cursor": {
+      const rc = Number(requireFunc("wcdb_close_message_cursor")(normalizeHandle(data.handle), normalizeHandle(data.cursor)));
+      return { closed: rc === 0, rc };
+    }
+
     case "get_message_count": {
       const out = [0];
       const rc = Number(
@@ -386,6 +443,14 @@ function handleAction(action, payload) {
         ]),
       };
 
+    case "get_contact":
+      return {
+        payload: callOutJson("wcdb_get_contact", [
+          normalizeHandle(data.handle),
+          String(data.username || "").trim(),
+        ]),
+      };
+
     case "get_group_members":
       return {
         payload: callOutJson("wcdb_get_group_members", [

src/wechat_decrypt_tool/wcdb_realtime.py

@@ -609,6 +609,13 @@ def _load_wcdb_lib() -> ctypes.CDLL:
         lib.wcdb_get_avatar_urls.argtypes = [ctypes.c_int64, ctypes.c_char_p, ctypes.POINTER(ctypes.c_char_p)]
         lib.wcdb_get_avatar_urls.restype = ctypes.c_int
 
+        # Optional (newer DLLs): wcdb_get_contact(handle, username, out_json)
+        try:
+            lib.wcdb_get_contact.argtypes = [ctypes.c_int64, ctypes.c_char_p, ctypes.POINTER(ctypes.c_char_p)]
+            lib.wcdb_get_contact.restype = ctypes.c_int
+        except Exception:
+            pass
+
         lib.wcdb_get_group_member_count.argtypes = [ctypes.c_int64, ctypes.c_char_p, ctypes.POINTER(ctypes.c_int32)]
         lib.wcdb_get_group_member_count.restype = ctypes.c_int
 
@@ -640,6 +647,50 @@ def _load_wcdb_lib() -> ctypes.CDLL:
         except Exception:
             pass
 
+        # Optional (newer DLLs): native message cursor used by WeFlow for stable
+        # latest/history paging across message_*.db shards.
+        try:
+            lib.wcdb_open_message_cursor.argtypes = [
+                ctypes.c_int64,
+                ctypes.c_char_p,
+                ctypes.c_int32,
+                ctypes.c_int32,
+                ctypes.c_int32,
+                ctypes.c_int32,
+                ctypes.POINTER(ctypes.c_int64),
+            ]
+            lib.wcdb_open_message_cursor.restype = ctypes.c_int
+        except Exception:
+            pass
+        try:
+            lib.wcdb_open_message_cursor_lite.argtypes = [
+                ctypes.c_int64,
+                ctypes.c_char_p,
+                ctypes.c_int32,
+                ctypes.c_int32,
+                ctypes.c_int32,
+                ctypes.c_int32,
+                ctypes.POINTER(ctypes.c_int64),
+            ]
+            lib.wcdb_open_message_cursor_lite.restype = ctypes.c_int
+        except Exception:
+            pass
+        try:
+            lib.wcdb_fetch_message_batch.argtypes = [
+                ctypes.c_int64,
+                ctypes.c_int64,
+                ctypes.POINTER(ctypes.c_char_p),
+                ctypes.POINTER(ctypes.c_int32),
+            ]
+            lib.wcdb_fetch_message_batch.restype = ctypes.c_int
+        except Exception:
+            pass
+        try:
+            lib.wcdb_close_message_cursor.argtypes = [ctypes.c_int64, ctypes.c_int64]
+            lib.wcdb_close_message_cursor.restype = ctypes.c_int
+        except Exception:
+            pass
+
         # Optional (newer DLLs): update a single message content in message db.
         # Signature: wcdb_update_message(handle, sessionId, localId, createTime, newContent, outError)
         try:
@@ -1086,6 +1137,31 @@ def get_avatar_urls(handle: int, usernames: list[str]) -> dict[str, str]:
     return {}
 
 
+def get_contact(handle: int, username: str) -> dict[str, Any]:
+    _ensure_initialized()
+    u = str(username or "").strip()
+    if not u:
+        return {}
+
+    if _sidecar_enabled():
+        out_json = _sidecar_payload(
+            "get_contact",
+            {"handle": int(handle), "username": u},
+            timeout=30.0,
+        )
+        decoded = _safe_load_json(out_json)
+        return decoded if isinstance(decoded, dict) else {}
+
+    lib = _load_wcdb_lib()
+    fn = getattr(lib, "wcdb_get_contact", None)
+    if not fn:
+        raise WCDBRealtimeError("Current wcdb_api.dll does not support get_contact.")
+
+    out_json = _call_out_json(fn, ctypes.c_int64(int(handle)), u.encode("utf-8"))
+    decoded = _safe_load_json(out_json)
+    return decoded if isinstance(decoded, dict) else {}
+
+
 def get_group_members(handle: int, chatroom_id: str) -> list[dict[str, Any]]:
     _ensure_initialized()
     cid = str(chatroom_id or "").strip()
@@ -1200,6 +1276,138 @@ def exec_query(handle: int, *, kind: str, path: Optional[str], sql: str) -> list
     return []
 
 
+def open_message_cursor(
+    handle: int,
+    session_id: str,
+    *,
+    batch_size: int,
+    ascending: bool = False,
+    begin_timestamp: int = 0,
+    end_timestamp: int = 0,
+    lite: bool = False,
+) -> int:
+    """Open the native WeFlow-style message cursor.
+
+    The cursor API is important for live chat paging because the native layer
+    owns cross-`message_*.db` discovery/merge and can see the same live view
+    WeFlow uses instead of a single explicit SQL table.
+    """
+
+    _ensure_initialized()
+    sid = str(session_id or "").strip()
+    if not sid:
+        return 0
+    size = max(1, int(batch_size or 1))
+    asc = 1 if ascending else 0
+    begin = max(0, int(begin_timestamp or 0))
+    end = max(0, int(end_timestamp or 0))
+
+    action = "open_message_cursor_lite" if lite else "open_message_cursor"
+    if _sidecar_enabled():
+        result = _sidecar_call(
+            action,
+            {
+                "handle": int(handle),
+                "session_id": sid,
+                "batch_size": int(size),
+                "ascending": bool(ascending),
+                "begin_timestamp": int(begin),
+                "end_timestamp": int(end),
+            },
+            timeout=30.0,
+        )
+        try:
+            return int(result.get("cursor") or 0)
+        except Exception:
+            return 0
+
+    lib = _load_wcdb_lib()
+    fn = getattr(lib, "wcdb_open_message_cursor_lite" if lite else "wcdb_open_message_cursor", None)
+    if not fn:
+        if lite:
+            fn = getattr(lib, "wcdb_open_message_cursor", None)
+        if not fn:
+            return 0
+
+    out_cursor = ctypes.c_int64(0)
+    rc = int(
+        fn(
+            ctypes.c_int64(int(handle)),
+            sid.encode("utf-8"),
+            ctypes.c_int32(int(size)),
+            ctypes.c_int32(int(asc)),
+            ctypes.c_int32(int(begin)),
+            ctypes.c_int32(int(end)),
+            ctypes.byref(out_cursor),
+        )
+    )
+    if rc != 0 or int(out_cursor.value) <= 0:
+        return 0
+    return int(out_cursor.value)
+
+
+def fetch_message_batch(handle: int, cursor: int) -> tuple[list[dict[str, Any]], bool]:
+    _ensure_initialized()
+    cur = int(cursor or 0)
+    if cur <= 0:
+        return [], False
+
+    if _sidecar_enabled():
+        result = _sidecar_call(
+            "fetch_message_batch",
+            {"handle": int(handle), "cursor": int(cur)},
+            timeout=30.0,
+        )
+        decoded = _safe_load_json(str(result.get("payload") or ""))
+        rows = [x for x in decoded if isinstance(x, dict)] if isinstance(decoded, list) else []
+        return rows, bool(result.get("hasMore"))
+
+    lib = _load_wcdb_lib()
+    fn = getattr(lib, "wcdb_fetch_message_batch", None)
+    if not fn:
+        return [], False
+
+    out_json = ctypes.c_char_p()
+    out_has_more = ctypes.c_int32(0)
+    rc = int(fn(ctypes.c_int64(int(handle)), ctypes.c_int64(cur), ctypes.byref(out_json), ctypes.byref(out_has_more)))
+    try:
+        if rc != 0 or not out_json.value:
+            return [], False
+        payload = out_json.value.decode("utf-8", errors="replace")
+    finally:
+        try:
+            if out_json.value:
+                lib.wcdb_free_string(out_json)
+        except Exception:
+            pass
+    decoded = _safe_load_json(payload)
+    rows = [x for x in decoded if isinstance(x, dict)] if isinstance(decoded, list) else []
+    return rows, bool(int(out_has_more.value or 0) == 1)
+
+
+def close_message_cursor(handle: int, cursor: int) -> None:
+    _ensure_initialized()
+    cur = int(cursor or 0)
+    if cur <= 0:
+        return
+
+    if _sidecar_enabled():
+        try:
+            _sidecar_call("close_message_cursor", {"handle": int(handle), "cursor": int(cur)}, timeout=5.0)
+        except Exception:
+            pass
+        return
+
+    lib = _load_wcdb_lib()
+    fn = getattr(lib, "wcdb_close_message_cursor", None)
+    if not fn:
+        return
+    try:
+        fn(ctypes.c_int64(int(handle)), ctypes.c_int64(cur))
+    except Exception:
+        return
+
+
 def update_message(handle: int, *, session_id: str, local_id: int, create_time: int, new_content: str) -> None:
     """Update a single message content in the live encrypted db_storage via WCDB.