weflow-cli 1.17.0 → 1.19.1

package/scripts/watch_mail.py

@@ -1,131 +1,131 @@
-#!/usr/bin/env python3
-"""Queue instructions the user sends to the agent mailbox.
-
-A pure script - no model, no tokens. It runs from Windows Task Scheduler and
-its only job is to notice new mail from an allowlisted sender and append it to
-a local queue file. Acting on those instructions happens later, from a normal
-session, which is when a model is running anyway.
-
-That split matters: waking a model every few minutes just to discover there is
-no mail costs tokens for nothing. This script does the waiting for free.
-
-    ~/.weflow-mail-queue.jsonl   one JSON object per pending instruction
-    ~/.weflow-mail-state.json    message ids already queued
-
-Only mail whose From address is exactly the allowlisted one is ever read or
-queued. Mail from anyone else is left untouched - not read, not marked, not
-queued.
-"""
-import json
-import os
-import subprocess
-import sys
-
-STATE_PATH = os.path.join(os.path.expanduser('~'), '.weflow-mail-state.json')
-QUEUE_PATH = os.path.join(os.path.expanduser('~'), '.weflow-mail-queue.jsonl')
-
-# Exact address, not a display name: a sender name can say anything.
-ALLOWED_SENDERS = {'1473517806@qq.com'}
-
-AGENTLY_CANDIDATES = [
-    # The npm shim is a .cmd on Windows; subprocess needs the extension spelled
-    # out, since a bare `agently-cli` is not an executable image.
-    r'C:\Users\Administrator\AppData\Roaming\npm\agently-cli.cmd',
-    'agently-cli.cmd',
-    'agently-cli',
-]
-
-
-def _runnable(candidate):
-    if os.path.isabs(candidate):
-        return os.path.isfile(candidate)
-    from shutil import which
-    return which(candidate) is not None
-
-
-def agently(args):
-    """Run agently-cli and return its parsed JSON, or None."""
-    executable = next((c for c in AGENTLY_CANDIDATES if _runnable(c)), None)
-    if not executable:
-        print('未找到 agently-cli，跳过。')
-        return None
-    try:
-        result = subprocess.run(
-            [executable, *args], capture_output=True, timeout=90, encoding='utf-8')
-    except (OSError, subprocess.SubprocessError) as error:
-        print(f'agently-cli 调用失败: {type(error).__name__}')
-        return None
-    # agently-cli pretty-prints its JSON across many lines, so parse the whole
-    # payload from the first brace rather than looking for a single-line blob.
-    text = result.stdout.strip()
-    start = text.find('{')
-    if start < 0:
-        return None
-    try:
-        return json.JSONDecoder().raw_decode(text[start:])[0]
-    except ValueError:
-        return None
-
-
-def load_json(path, fallback):
-    try:
-        with open(path, encoding='utf-8') as handle:
-            return json.load(handle)
-    except (OSError, ValueError):
-        return fallback
-
-
-def main():
-    state = load_json(STATE_PATH, {'seen': []})
-    seen = set(state.get('seen', []))
-
-    listing = agently(['message', '+list', '--limit', '20'])
-    if not listing or not listing.get('ok'):
-        print('读取邮箱失败（未授权或网络不通），本次跳过。')
-        return 0
-
-    messages = (listing.get('data') or {}).get('data') or []
-    queued = 0
-    for summary in messages:
-        sender = (summary.get('from') or {}).get('email', '')
-        if sender not in ALLOWED_SENDERS:
-            continue
-        message_id = summary.get('message_id', '')
-        if not message_id or message_id in seen:
-            continue
-
-        detail = agently(['message', '+read', '--id', message_id])
-        body = ''
-        if detail and detail.get('ok'):
-            body = ((detail.get('data') or {}).get('text')
-                    or (detail.get('data') or {}).get('body') or '')
-        if not body:
-            body = summary.get('snippet', '')
-
-        entry = {
-            'message_id': message_id,
-            'from': sender,
-            'subject': summary.get('subject', ''),
-            'created_at': summary.get('created_at', ''),
-            'body': body,
-        }
-        with open(QUEUE_PATH, 'a', encoding='utf-8') as handle:
-            handle.write(json.dumps(entry, ensure_ascii=False) + '\n')
-        seen.add(message_id)
-        queued += 1
-
-    if queued:
-        with open(STATE_PATH, 'w', encoding='utf-8') as handle:
-            json.dump({'seen': sorted(seen)}, handle, ensure_ascii=False, indent=2)
-        print(f'已排队 {queued} 封来自授权发件人的邮件。')
-    else:
-        # Still persist first-run state so the backlog is not queued later.
-        if not os.path.exists(STATE_PATH):
-            with open(STATE_PATH, 'w', encoding='utf-8') as handle:
-                json.dump({'seen': sorted(seen)}, handle, ensure_ascii=False, indent=2)
-        print('无新指令邮件。')
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())
+#!/usr/bin/env python3
+"""Queue instructions the user sends to the agent mailbox.
+
+A pure script - no model, no tokens. It runs from Windows Task Scheduler and
+its only job is to notice new mail from an allowlisted sender and append it to
+a local queue file. Acting on those instructions happens later, from a normal
+session, which is when a model is running anyway.
+
+That split matters: waking a model every few minutes just to discover there is
+no mail costs tokens for nothing. This script does the waiting for free.
+
+    ~/.weflow-mail-queue.jsonl   one JSON object per pending instruction
+    ~/.weflow-mail-state.json    message ids already queued
+
+Only mail whose From address is exactly the allowlisted one is ever read or
+queued. Mail from anyone else is left untouched - not read, not marked, not
+queued.
+"""
+import json
+import os
+import subprocess
+import sys
+
+STATE_PATH = os.path.join(os.path.expanduser('~'), '.weflow-mail-state.json')
+QUEUE_PATH = os.path.join(os.path.expanduser('~'), '.weflow-mail-queue.jsonl')
+
+# Exact address, not a display name: a sender name can say anything.
+ALLOWED_SENDERS = {'1473517806@qq.com'}
+
+AGENTLY_CANDIDATES = [
+    # The npm shim is a .cmd on Windows; subprocess needs the extension spelled
+    # out, since a bare `agently-cli` is not an executable image.
+    r'C:\Users\Administrator\AppData\Roaming\npm\agently-cli.cmd',
+    'agently-cli.cmd',
+    'agently-cli',
+]
+
+
+def _runnable(candidate):
+    if os.path.isabs(candidate):
+        return os.path.isfile(candidate)
+    from shutil import which
+    return which(candidate) is not None
+
+
+def agently(args):
+    """Run agently-cli and return its parsed JSON, or None."""
+    executable = next((c for c in AGENTLY_CANDIDATES if _runnable(c)), None)
+    if not executable:
+        print('未找到 agently-cli，跳过。')
+        return None
+    try:
+        result = subprocess.run(
+            [executable, *args], capture_output=True, timeout=90, encoding='utf-8')
+    except (OSError, subprocess.SubprocessError) as error:
+        print(f'agently-cli 调用失败: {type(error).__name__}')
+        return None
+    # agently-cli pretty-prints its JSON across many lines, so parse the whole
+    # payload from the first brace rather than looking for a single-line blob.
+    text = result.stdout.strip()
+    start = text.find('{')
+    if start < 0:
+        return None
+    try:
+        return json.JSONDecoder().raw_decode(text[start:])[0]
+    except ValueError:
+        return None
+
+
+def load_json(path, fallback):
+    try:
+        with open(path, encoding='utf-8') as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return fallback
+
+
+def main():
+    state = load_json(STATE_PATH, {'seen': []})
+    seen = set(state.get('seen', []))
+
+    listing = agently(['message', '+list', '--limit', '20'])
+    if not listing or not listing.get('ok'):
+        print('读取邮箱失败（未授权或网络不通），本次跳过。')
+        return 0
+
+    messages = (listing.get('data') or {}).get('data') or []
+    queued = 0
+    for summary in messages:
+        sender = (summary.get('from') or {}).get('email', '')
+        if sender not in ALLOWED_SENDERS:
+            continue
+        message_id = summary.get('message_id', '')
+        if not message_id or message_id in seen:
+            continue
+
+        detail = agently(['message', '+read', '--id', message_id])
+        body = ''
+        if detail and detail.get('ok'):
+            body = ((detail.get('data') or {}).get('text')
+                    or (detail.get('data') or {}).get('body') or '')
+        if not body:
+            body = summary.get('snippet', '')
+
+        entry = {
+            'message_id': message_id,
+            'from': sender,
+            'subject': summary.get('subject', ''),
+            'created_at': summary.get('created_at', ''),
+            'body': body,
+        }
+        with open(QUEUE_PATH, 'a', encoding='utf-8') as handle:
+            handle.write(json.dumps(entry, ensure_ascii=False) + '\n')
+        seen.add(message_id)
+        queued += 1
+
+    if queued:
+        with open(STATE_PATH, 'w', encoding='utf-8') as handle:
+            json.dump({'seen': sorted(seen)}, handle, ensure_ascii=False, indent=2)
+        print(f'已排队 {queued} 封来自授权发件人的邮件。')
+    else:
+        # Still persist first-run state so the backlog is not queued later.
+        if not os.path.exists(STATE_PATH):
+            with open(STATE_PATH, 'w', encoding='utf-8') as handle:
+                json.dump({'seen': sorted(seen)}, handle, ensure_ascii=False, indent=2)
+        print('无新指令邮件。')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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())