weflow-cli 1.16.0 → 1.19.0

package/scripts/run_hidden.vbs

@@ -0,0 +1,25 @@
+' Silent launcher for the WeFlow daily task.
+'
+' Why this file exists: a scheduled action that runs "powershell.exe -File ..." starts a
+' CONSOLE program, so Windows creates a console window before PowerShell can hide it - you
+' see a black box appear, and it is especially intrusive over a full-screen game. wscript.exe
+' is a GUI process with no console at all, and WshShell.Run with window style 0 keeps the
+' child hidden too.
+'
+' Arguments are forwarded verbatim, so "run_hidden.vbs noon" is the noon pass.
+'
+' ASCII only on purpose: Windows Script Host reads this file with the ANSI code page.
+
+Dim fso, here, script, cmd, sh
+Set fso = CreateObject("Scripting.FileSystemObject")
+here = fso.GetParentFolderName(WScript.ScriptFullName)
+script = fso.BuildPath(here, "daily_task.ps1")
+
+cmd = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File """ & script & """"
+If WScript.Arguments.Count > 0 Then
+    cmd = cmd & " " & WScript.Arguments(0)
+End If
+
+Set sh = CreateObject("WScript.Shell")
+' 0 = hidden window, True = wait for the child so the task's last result reflects the run.
+sh.Run cmd, 0, True

package/scripts/semantic_search.py

@@ -63,6 +63,7 @@ except:
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from _utils import load_config, decrypt_lock, get_dashscope_key, get_api_key, LINE_LABELS  # noqa: E402
+from nt_common import decode_content  # noqa: E402
 from jev_client import create_client
 
 OUTPUT_ROOT = 'output'
@@ -248,7 +249,10 @@ def collect_chat_messages(conns, name_map, days=90, per_talker=500):
             except Exception:
                 continue
             for rid, ts, sender, content in rows:
-                if not content or not isinstance(content, str) or len(content) < 10:
+                # 正文可能是 zstd 压缩的 BLOB（issue #12）：先解码再判断长度，
+                # 否则这些消息会被整条跳过、索引里永远缺一段。
+                content = decode_content(content)
+                if len(content) < 10:
                     continue
                 item_id = f"chat:{talker}:{ts}:{rid}"
                 if item_id in seen:
@@ -268,6 +272,36 @@ def collect_chat_messages(conns, name_map, days=90, per_talker=500):
     return items
 
 
+def collect_imported_chat_items(days=90):
+    """导入的 QQ 会话 → 与微信聊天同形状的索引记录（--include-imports）。
+
+    形状必须与 collect_chat_messages 逐字段一致（id/type/talker/sender/time/text），
+    否则同一条记录在两半索引里语义不同。id 带 qq: 段：与微信记录的
+    chat:<talker>:<ts>:<rid> 天然不撞，也永远可分辨来源。文本阈值（>=10 字）与
+    截断（500 字）同微信侧——索引是要花钱嵌的，两侧口径不同就是两种相关性。
+    """
+    import imported_chats
+
+    items = []
+    for sess in imported_chats.sessions():
+        meta = sess.get('session') or {}
+        talker = 'QQ-%s' % (meta.get('name') or meta.get('id') or '未命名')
+        for m in imported_chats.session_messages(sess, days=days):
+            text = (m.get('parsedContent') or '').strip()
+            if len(text) < 10:
+                continue
+            dt = datetime.fromtimestamp(m.get('createTime') or 0, tz=TZ)
+            items.append({
+                'id': 'chat:qq:%s:%s' % (meta.get('id') or '', m.get('serverId') or ''),
+                'type': 'chat',
+                'talker': talker,
+                'sender': m.get('senderName') or '',
+                'time': dt.strftime('%Y-%m-%d %H:%M'),
+                'text': text[:500],
+            })
+    return items
+
+
 _ARTICLE_BOILERPLATE = frozenset({
     '在小说阅读器读本章', '去阅读', '在公众号小说中沉浸阅读',
 })
@@ -396,7 +430,7 @@ def _save_index(base_vectors, base_meta, pairs):
     os.replace(tmp_m, META_FILE)
     return len(meta)
 
-def build_index(api_key: str, full: bool = False, days: int = 90, article_days: int = 30):
+def build_index(api_key: str, full: bool = False, days: int = 90, article_days: int = 30, include_imports: bool = False):
     """Build or update the semantic index.
 
     `days` / `article_days` 决定这个索引**记多久**：它们原先写死在两处调用里
@@ -421,8 +455,12 @@ def build_index(api_key: str, full: bool = False, days: int = 90, article_days:
     # Load DB
     config = load_config()
     nt_db = config.get('ntDbPath', '')
-    if not nt_db:
+    # --include-imports 时没有微信库也能建索引（纯 QQ 用户是真实场景）；
+    # 但要说出"聊天半边只有导入的"，不然窗口行读起来像微信也收了。
+    if not nt_db and not include_imports:
         return {"error": "未初始化，请先运行 weflow-cli init"}
+    if not nt_db and include_imports:
+        print('[WARN] 未配置微信库：聊天半边只用导入的会话', file=sys.stderr)
 
     nt_key = decrypt_lock(config.get('ntKey', ''))
     nt_salt = config.get('ntSalt', '')
@@ -439,6 +477,16 @@ def build_index(api_key: str, full: bool = False, days: int = 90, article_days:
     # Collect items
     items = []
     shards_failed = []
+    if not nt_db:
+        # 没有微信库：跳过 NT 那半（name_map/分片都不存在），导入与文章照收。
+        # 收完直接走同一个收尾（嵌入与写盘），不在这里复制粘贴后半段。
+        if include_imports:
+            items.extend(collect_imported_chat_items(days=days))
+        items.extend(collect_articles(article_days=article_days))
+        new_items = [item for item in items if item['id'] not in existing_ids]
+        print(f"总数据: {len(items)} 条, 新数据: {len(new_items)} 条", file=sys.stderr)
+        return _build_embed_and_write(api_key, items, new_items, existing_ids,
+                                   full, days, article_days, shards_failed=[])
     try:
         import nt_decrypt  # 懒加载：纯逻辑路径（关键词/重排/测试）不该被它拖住
         passphrase = decrypt_lock(config.get('favPassphrase') or config.get('decryptKey') or '')
@@ -460,13 +508,29 @@ def build_index(api_key: str, full: bool = False, days: int = 90, article_days:
     except Exception as e:
         print(f"[WARN] 聊天消息收集失败: {e}", file=sys.stderr)
 
+    if include_imports:
+        imported = collect_imported_chat_items(days=days)
+        items.extend(imported)
+        print(f"导入会话: +{len(imported)} 条", file=sys.stderr)
+
     article_items = collect_articles(article_days=article_days)
     items.extend(article_items)
 
-    # Filter new items
     new_items = [item for item in items if item['id'] not in existing_ids]
     print(f"总数据: {len(items)} 条, 新数据: {len(new_items)} 条", file=sys.stderr)
 
+    return _build_embed_and_write(api_key, items, new_items, existing_ids,
+                                   full, days, article_days, shards_failed)
+
+
+
+def _build_embed_and_write(api_key, items, new_items, existing_ids, full,
+                           days, article_days, shards_failed):
+    """build_index 的收尾：去重过滤在调用方做完了，这里管嵌入、断点落盘与返回。
+
+    抽出来是因为聊天半边现在有两条收集路（微信库 / 导入会话），尾巴必须只有一份——
+    复制一份的代价是断点续跑、全零批次不落盘这些坑只在一半路径上修过。
+    """
     if not new_items:
         return {"status": "up_to_date", "total": len(items),
                 "chatDays": days, "articleDays": article_days,
@@ -1522,11 +1586,15 @@ def main():
     p = subparsers.add_parser('build')
     p.add_argument('--api-key', help='DeepSeek API key（优先从 config 读取）')
     p.add_argument('--full', action='store_true', help='全量重建')
+    p.add_argument('--include-imports', action='store_true',
+                   help='把 weflow-cli import qchat 导入的 QQ 会话也收进索引（聊天半边；id 带 qq: 段）')
     add_window_args(p)
 
     # update
     p = subparsers.add_parser('update')
     p.add_argument('--api-key', help='DeepSeek API key（优先从 config 读取）')
+    p.add_argument('--include-imports', action='store_true',
+                   help='同 build：把导入的 QQ 会话收进增量')
     add_window_args(p)
 
     # search
@@ -1582,9 +1650,13 @@ def main():
                or get_dashscope_key(config))
 
     if args.command == 'build':
-        result = build_index(api_key, full=args.full, days=args.days, article_days=args.article_days)
+        result = build_index(api_key, full=args.full, days=args.days,
+                             article_days=args.article_days,
+                             include_imports=getattr(args, 'include_imports', False))
     elif args.command == 'update':
-        result = build_index(api_key, full=False, days=args.days, article_days=args.article_days)
+        result = build_index(api_key, full=False, days=args.days,
+                             article_days=args.article_days,
+                             include_imports=getattr(args, 'include_imports', False))
     elif args.command == 'phrase-build':
         result = build_phrase_index(line=args.line)
         result['success'] = 'error' not in result

package/scripts/wechat_avatar.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+"""读 head_image.db：联系人的头像（JPEG/PNG 完整字节内嵌库里，按 username 键控）。
+
+为什么从库里拿而不是文件缓存：缓存在 resource 下按 md5 命名、随清理消失，
+而库里永远在、按 username 键控、带 update_time——**一人多行 = 头像变更历史**
+（2026-10-26 普查：本机 1083 行，见 docs/NT_DATABASES.md）。
+
+只读、本地、不联网。输出元数据不含图片内容（--json 也只报路径与字节数）。
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import nt_common  # noqa: E402
+import nt_decrypt  # noqa: E402
+from _utils import decrypt_lock, load_config  # noqa: E402
+
+
+def head_image_db_path(message_db):
+    """message_0.db 同级的 head_image/head_image.db（与 contact.db 同一层推导）。"""
+    msg_dir = Path(message_db).parent.parent
+    return msg_dir / 'head_image' / 'head_image.db'
+
+
+def connect(db_path, key_hex, salt_hex, passphrase=''):
+    import sqlcipher3
+    derived_key, derived_salt = nt_common.derive_database_key(
+        str(db_path), key_hex, salt_hex, passphrase)
+    conn = sqlcipher3.connect(str(db_path))
+    c = conn.cursor()
+    c.execute("PRAGMA key = \"x'%s%s'\"" % (derived_key, derived_salt))
+    # 探测解密是否真的成功（读 sqlite_master 才触发解密；错误钥匙在这里报 file is not a database）
+    c.execute("SELECT COUNT(*) FROM sqlite_master WHERE type='table'").fetchone()
+    return conn
+
+
+def avatar_rows(conn, username):
+    """一个 username 的全部头像，新→旧。返回 [(update_time, bytes)]。"""
+    c = conn.cursor()
+    rows = c.execute(
+        'SELECT update_time, image_buffer FROM head_image WHERE username = ? '
+        'ORDER BY update_time DESC', (username,)).fetchall()
+    return [(r[0], bytes(r[1])) for r in rows if r[1]]
+
+
+def user_rows(conn):
+    """全部 username：[(username, 头像数, 最新 update_time)]，最新在前。"""
+    c = conn.cursor()
+    return c.execute(
+        'SELECT username, COUNT(*), MAX(update_time) FROM head_image '
+        'GROUP BY username ORDER BY MAX(update_time) DESC').fetchall()
+
+
+def resolve_username(conn, query, name_map):
+    """查询词 → head_image 里的 username。精确 id 命中优先；否则用 contact 名字反查，
+    歧义/找不到都报错并给候选——不猜（同 resolveTalker 的纪律）。"""
+    usernames = {r[0] for r in user_rows(conn)}
+    if query in usernames:
+        return query
+    hits = [u for u, display in name_map.items()
+            if display == query and u in usernames]
+    if len(hits) == 1:
+        return hits[0]
+    if len(hits) > 1:
+        raise SystemExit('「%s」匹配到多个头像所有者（%s）——请用完整 id 指定'
+                         % (query, '、'.join(hits[:5])))
+    raise SystemExit('没有「%s」的头像（head_image 库里共 %d 个 username；'
+                     '没有头像或名字对不上都可能是原因）' % (query, len(usernames)))
+
+
+def ext_of(buf):
+    return '.png' if buf[:4] == b'\x89PNG' else '.jpg'
+
+
+def main():
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    ap = argparse.ArgumentParser(
+        description='联系人头像（读 head_image.db；本地只读，不联网）')
+    ap.add_argument('--db', default=os.environ.get('WEFLOW_DB_PATH'),
+                    help='head_image.db 路径（默认从 WEFLOW_DB_PATH/message 库推导）')
+    ap.add_argument('--talker', default=os.environ.get('WEFLOW_TALKER'),
+                    help='联系人（id 或备注/昵称；--all 时不需要）')
+    ap.add_argument('--all', action='store_true',
+                    help='导出所有 username 的最新头像到 --out 目录')
+    ap.add_argument('--out', default=os.environ.get('WEFLOW_AVATAR_OUT') or '',
+                    help='输出文件（单联系人）或目录（--all）')
+    ap.add_argument('--list', action='store_true', help='只列出 username 与头像数')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args()
+
+    config = load_config()
+    message_db = config.get('ntDbPath', '')
+    # --db / WEFLOW_DB_PATH 两种都认：直接给 head_image.db，或给 message 库（推导同级）
+    if args.db:
+        p = Path(args.db)
+        db = p if p.name == 'head_image.db' else head_image_db_path(p)
+    elif message_db:
+        db = head_image_db_path(message_db)
+    else:
+        db = None
+    if not db or not db.exists():
+        print(json.dumps({'success': False, 'error': '找不到 head_image.db（先 weflow-cli init）'}))
+        return 1
+    passphrase = decrypt_lock(config.get('favPassphrase') or config.get('decryptKey') or '')
+    try:
+        conn = connect(db, decrypt_lock(config.get('ntKey') or ''),
+                       config.get('ntSalt') or '', passphrase)
+    except Exception as e:
+        print(json.dumps({'success': False, 'error': 'head_image.db 打不开：%s' % str(e)[:80]}))
+        return 1
+
+    try:
+        if args.list:
+            rows = user_rows(conn)
+            if args.json:
+                print(json.dumps({'success': True, 'users': [
+                    {'username': u, 'avatars': n, 'newestUpdateTime': t}
+                    for u, n, t in rows]}, ensure_ascii=False))
+            else:
+                print('共 %d 个 username 有头像' % len(rows))
+                for u, n, t in rows[:20]:
+                    print('  %s（%d 张，最新 %s）' % (u, n, t))
+            return 0
+
+        if args.all:
+            out_dir = Path(args.out or 'output/avatars')
+            out_dir.mkdir(parents=True, exist_ok=True)
+            written = 0
+            for username, _n, _t in user_rows(conn):
+                rows = avatar_rows(conn, username)
+                if not rows:
+                    continue
+                _ts, buf = rows[0]
+                safe = ''.join(ch if ch.isalnum() or ch in '_-@.' else '_'
+                               for ch in username)[:80]
+                path = out_dir / (safe + ext_of(buf))
+                path.write_bytes(buf)
+                written += 1
+            result = {'success': True, 'action': 'avatar.export-all',
+                      'dir': str(out_dir), 'written': written,
+                      'readsLocalData': True, 'invokesAI': False, 'sendsNothing': True}
+            print(json.dumps(result, ensure_ascii=False) if args.json
+                  else '已导出 %d 个最新头像到 %s' % (written, out_dir))
+            return 0
+
+        if not args.talker:
+            print(json.dumps({'success': False, 'error': '缺 --talker（或 WEFLOW_TALKER）' }))
+            return 1
+        name_map = {}
+        contact_db = nt_decrypt.find_contact_db_path(str(message_db)) if message_db else None
+        if contact_db:
+            name_map = nt_decrypt.load_contact_names(
+                contact_db, decrypt_lock(config.get('contactKey') or ''),
+                config.get('contactSalt') or '')
+        username = resolve_username(conn, args.talker, name_map)
+        rows = avatar_rows(conn, username)
+        if not rows:
+            print(json.dumps({'success': False, 'error': '「%s」在库里但头像字节为空' % username},
+                             ensure_ascii=False))
+            return 1
+        out = Path(args.out or ('output/avatars/' + username + ext_of(rows[0][1])))
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_bytes(rows[0][1])
+        result = {
+            'success': True, 'action': 'avatar.export', 'username': username,
+            'out': str(out), 'bytes': len(rows[0][1]),
+            'historyCount': len(rows),
+            'newestUpdateTime': rows[0][0],
+            'readsLocalData': True, 'invokesAI': False, 'sendsNothing': True,
+        }
+        if args.json:
+            print(json.dumps(result, ensure_ascii=False))
+        else:
+            print('已导出「%s」的最新头像（%d 字节，历史 %d 张）→ %s'
+                  % (username, len(rows[0][1]), len(rows), out))
+        return 0
+    finally:
+        conn.close()
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/scripts/wechat_ledger.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""读 general.db 的资金流水：红包（redEnvelopeTable）与转账（transferTable）。
+
+2026-10-26 普查产物（docs/NT_DATABASES.md）。两个如实的限制（不猜、不补）：
+  · 红包表**没有时间列、没有金额列**——时间/金额都在消息正文里。行按
+    message_server_id 排序（服务端 id 单调增，可看先后），溯源字段随行输出，
+    关联消息分片是后续工作。
+  · 状态枚举（hb_status/receive_status/pay_sub_type）的语义**未逐值验证**，
+    原样输出数字并注明，不翻译成没有根据的词。
+只读、本地、不联网；方向判定按 wxid 前缀匹配（配置 wxid 可能带 Name2Id 没有的
+后缀，1.15.1 的教训）。
+"""
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import nt_common  # noqa: E402
+import nt_decrypt  # noqa: E402
+from _utils import decrypt_lock, load_config  # noqa: E402
+
+
+def general_db_path(message_db):
+    """message_0.db 同级的 general/general.db。"""
+    return Path(message_db).parent.parent / 'general' / 'general.db'
+
+
+def connect(db_path, key_hex, salt_hex, passphrase=''):
+    import sqlcipher3
+    derived_key, derived_salt = nt_common.derive_database_key(
+        str(db_path), key_hex, salt_hex, passphrase)
+    conn = sqlcipher3.connect(str(db_path))
+    c = conn.cursor()
+    c.execute("PRAGMA key = \"x'%s%s'\"" % (derived_key, derived_salt))
+    c.execute("SELECT COUNT(*) FROM sqlite_master WHERE type='table'").fetchone()
+    return conn
+
+
+def is_own(name, own_wxid):
+    if not name or not own_wxid:
+        return False
+    return name == own_wxid or name.startswith(own_wxid) or own_wxid.startswith(name)
+
+
+def ledger_rows(conn, name_map=None, session_filter=None, own_wxid=''):
+    """两表 → 归一化行（原样字段 + 方向 + 显示名），新→旧。
+
+    红包没有时间列，用 message_server_id 兜底排序（服务端 id 单调增）；
+    转账按 begin_transfer_time 排。两表合并后统一按 sortKey 降序。
+    """
+    name_map = name_map or {}
+    c = conn.cursor()
+    rows = []
+    for sid, session, sender, send_id, hb_status, hb_type, receive_status in c.execute(
+            'SELECT message_server_id, session_name, sender_user_name, send_id, '
+            'hb_status, hb_type, receive_status FROM redEnvelopeTable'):
+        if session_filter and session_filter not in (session, name_map.get(session, session)):
+            continue
+        rows.append({
+            'kind': '红包',
+            'session': session,
+            'sessionDisplay': name_map.get(session, session),
+            'direction': '我发' if is_own(sender, own_wxid) else '对方发',
+            # 状态原样：语义未逐值验证（本机观测 hb_status ∈ {1,4}、receive_status ∈ {0,1,2}）
+            'hbStatus': hb_status, 'hbType': hb_type, 'receiveStatus': receive_status,
+            'time': None,  # 库内无时间列——要时间得按 messageServerId 关联消息分片（未实现）
+            'messageServerId': str(sid or ''),
+            'sortKey': int(sid or 0),
+        })
+    for tid, _txn, sid, session, sub_type, receiver, payer, begin_ts, invalid_ts in c.execute(
+            'SELECT transfer_id, transcation_id, message_server_id, session_name, '
+            'pay_sub_type, pay_receiver, pay_payer, begin_transfer_time, invalid_time '
+            'FROM transferTable'):
+        if session_filter and session_filter not in (session, name_map.get(session, session)):
+            continue
+        direction = '未知'
+        if is_own(payer, own_wxid) and not is_own(receiver, own_wxid):
+            direction = '我付'
+        elif is_own(receiver, own_wxid) and not is_own(payer, own_wxid):
+            direction = '我收'
+        rows.append({
+            'kind': '转账',
+            'session': session,
+            'sessionDisplay': name_map.get(session, session),
+            'direction': direction,
+            'paySubType': sub_type,          # 本机观测全为 3；语义未验证
+            'counterparty': (receiver if direction == '我付'
+                             else payer if direction == '我收' else ''),
+            'counterpartyDisplay': name_map.get(
+                receiver if direction == '我付' else payer if direction == '我收' else '', ''),
+            'time': int(begin_ts or 0),
+            'invalidTime': int(invalid_ts or 0),   # >0 的语义（过期/退还）未验证，原样给出
+            'messageServerId': str(sid or ''),
+            'transferId': str(tid or ''),
+            'sortKey': int(begin_ts or 0) or int(sid or 0),
+        })
+    rows.sort(key=lambda r: r['sortKey'], reverse=True)
+    return rows
+
+
+def keep_within_days(rows, cutoff):
+    """--days 过滤：只滤**有时间戳**的行；红包无时间列不受限（如实保留）。
+
+    独立成函数以便测试钉住"红包不被时间窗误杀"——那是把两类行的可用字段
+    混为一谈的错误。
+    """
+    return [r for r in rows if r['time'] is None or r['time'] >= cutoff]
+
+
+def main():
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    ap = argparse.ArgumentParser(
+        description='资金流水：红包与转账（读 general.db；本地只读，不联网）')
+    ap.add_argument('--db', default=os.environ.get('WEFLOW_DB_PATH'),
+                    help='general.db 路径（默认从 message 库推导同级）')
+    ap.add_argument('--talker', default=os.environ.get('WEFLOW_TALKER'),
+                    help='可选：只看某个会话（id 或备注/昵称子串）')
+    ap.add_argument('--days', type=int, default=0,
+                    help='只看最近 N 天（按转账时间过滤；红包无时间列不受此限）')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args()
+
+    config = load_config()
+    message_db = config.get('ntDbPath', '')
+    if args.db:
+        p = Path(args.db)
+        db = p if p.name == 'general.db' else general_db_path(p)
+    elif message_db:
+        db = general_db_path(message_db)
+    else:
+        db = None
+    if not db or not db.exists():
+        print(json.dumps({'success': False, 'error': '找不到 general.db（先 weflow-cli init）'}))
+        return 1
+    passphrase = decrypt_lock(config.get('favPassphrase') or config.get('decryptKey') or '')
+    try:
+        conn = connect(db, decrypt_lock(config.get('ntKey') or ''),
+                       config.get('ntSalt') or '', passphrase)
+    except Exception as e:
+        print(json.dumps({'success': False, 'error': 'general.db 打不开：%s' % str(e)[:80]}))
+        return 1
+
+    try:
+        name_map = {}
+        contact_db = nt_decrypt.find_contact_db_path(message_db) if message_db else None
+        if contact_db:
+            name_map = nt_decrypt.load_contact_names(
+                contact_db, decrypt_lock(config.get('contactKey') or ''),
+                config.get('contactSalt') or '')
+        rows = ledger_rows(conn, name_map, args.talker or None,
+                           config.get('wxid', ''))
+        if args.days and args.days > 0:
+            rows = keep_within_days(rows, int(time.time()) - args.days * 86400)
+        red = [r for r in rows if r['kind'] == '红包']
+        transfers = [r for r in rows if r['kind'] == '转账']
+        result = {
+            'success': True, 'action': 'ledger',
+            'redEnvelopes': len(red), 'transfers': len(transfers),
+            'notes': [
+                '红包表无时间/金额列：时间与金额在消息正文里，行按 messageServerId 排序（可看先后）',
+                '状态枚举（hbStatus/receiveStatus/paySubType）语义未逐值验证，原样输出',
+            ],
+            'rows': rows,
+            'readsLocalData': True, 'invokesAI': False, 'sendsNothing': True,
+        }
+        if args.json:
+            print(json.dumps(result, ensure_ascii=False))
+        else:
+            print('红包 %d 笔、转账 %d 笔（状态原样，语义未验证）' % (len(red), len(transfers)))
+            for r in rows[:40]:
+                when = (time.strftime('%Y-%m-%d %H:%M', time.localtime(r['time']))
+                        if r.get('time') else '（无时间列）')
+                extra = ('status=%s/%s' % (r['hbStatus'], r['receiveStatus'])
+                         if r['kind'] == '红包' else
+                         ('对方=%s invalid=%s' % (r.get('counterpartyDisplay') or r.get('counterparty') or '?',
+                                                   r.get('invalidTime') or 0)))
+                print('  [%s] %s · %s · %s · %s' % (
+                    when, r['kind'], r['sessionDisplay'], r['direction'], extra))
+            if len(rows) > 40:
+                print('  …共 %d 行（--json 看全表）' % len(rows))
+        return 0
+    finally:
+        conn.close()
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/src/core/ntCore.ts

@@ -75,6 +75,42 @@ export interface NtMessagesResult extends NtResult {
   shards?: ShardReport
 }
 
+/** One shard's outcome in a `cursor-probe` run (nt_decrypt.py cursor-probe). */
+export interface NtCursorProbeShard {
+  /** basename only - the child never reports a full path */
+  name: string
+  opened: boolean
+  reason: string | null
+  /** number of Msg_* tables; null when the shard could not be read at all */
+  tables: number | null
+  tablesSampled?: number
+  /** per-table missing anchor-column sets, deduplicated; empty = every table has all three */
+  anchorColumnsMissing?: string[][]
+  rowsSampled?: number
+  /** sampled rows whose server_id was 0 or NULL (identity degrades for them) */
+  serverIdMissing?: number
+}
+
+export interface NtCursorProbeSample {
+  tablesPerShard: number
+  rowsPerTable: number
+  exhaustive: boolean
+  tablesTotal: number
+  tablesSampled: number
+  rowsSampled: number
+  serverIdMissing: number
+  /** sampled nonzero server ids seen in more than one (shard, table) location */
+  duplicateServerIds: number
+  duplicateServerIdSamples?: Array<{ serverId: string; locations: string[] }>
+}
+
+export interface NtCursorProbeResult extends NtResult {
+  shards?: NtCursorProbeShard[]
+  /** shards with at least one message table missing an anchor column */
+  schemaAnchorMissingTables?: number
+  sample?: NtCursorProbeSample
+}
+
 export interface NtContactsResult extends NtResult {
   contacts?: Contact[]
 }
@@ -392,6 +428,29 @@ export class NtCore {
     return { success: true, contacts: result.contacts || [] }
   }
 
+  /**
+   * The NT backend's data-side answer to D-027's stable-cursor question:
+   * anchor columns per message table (exhaustive) and a bounded sample of
+   * `server_id` coverage at both rowid ends of a few tables per shard.
+   * Read-only; the sampling bounds are labelled `exhaustive: false` in the
+   * result because they are a measurement, not a guarantee.
+   */
+  async cursorProbe(opts: { tablesPerShard?: number; rowsPerTable?: number } = {}): Promise<NtCursorProbeResult> {
+    const args: string[] = ['cursor-probe']
+    if (opts.tablesPerShard != null) args.push('--tables-per-shard', String(opts.tablesPerShard))
+    if (opts.rowsPerTable != null) args.push('--rows-per-table', String(opts.rowsPerTable))
+    const result = await this.callPython(args)
+    if (result.error) {
+      return { success: false, error: result.error }
+    }
+    return {
+      success: true,
+      shards: result.shards || [],
+      schemaAnchorMissingTables: result.schemaAnchorMissingTables,
+      sample: result.sample,
+    }
+  }
+
   // ====== SNS (朋友圈) ======
 
   /** 查询 SNS 朋友圈时间线 */