weflow-cli 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -17,6 +17,36 @@ purpose** - a hand-written "latest is X" is exactly the claim that goes stale he
 
 All notable user-facing changes are recorded here. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.19.0
+
+- **修复 issue #12：`local_type == 1` 的压缩正文导出为空，普通文本被截断到 200 字。**
+  `message_content` 若是 zstd 压缩的 BLOB，旧代码只认 `str`，正文被置空后落进
+  `non_text_display()`，最终输出 `[未识别的消息类型 1]`——**消息还在、正文没了**，
+  下游按 `parsedContent` 做的关键词 / `@所有人` 筛选于是漏掉这些通知。
+  现在类型 1 一律走已有的 `_decode_content()`（str / zstd frame / 普通 bytes 三种都处理），
+  且 `parsedContent` 对文本**不再截断**：末尾关键词正是筛选要用的，截掉等于静默漏消息。
+  非文本仍保留 200 字展示上限——那是标签与标题，不是正文。
+- **`media` — md5 直接对到本地文件（读 `hardlink.db`，本地只读）。** 图片、文件、视频三张表各记
+  `md5 → (dir1, dir2, file_name)`，`dir2id` 把 id 映射成目录名，路径是**确定的**，不用再扫整个
+  `msg/` 目录去猜。每一行都标 `✓/✗`：`✗` 是"库里有记录但文件已被微信清理"，不是路径算错。
+  **图片的 dir1/dir2 顺序与另两张表相反**：实测 image 行是 `dir1=会话hash, dir2=月份`
+  （`attach/<会话>/<月份>/Img/`），file/video 行是 `dir1=月份`。按统一顺序拼，4647 条图片会全指到
+  一个空目录，而文件/视频那条仍然正确——只看某一类能打开就会漏掉这个错。
+
+## 1.18.0
+
+- **`ledger` — 红包与转账流水（读 `general.db`，本地只读）。** 把两张表归一成一条按时间排的
+  流水：`kind`（红包/转账）、方向（我付/我收/我发/对方发/未知）、对方、`messageServerId`。
+  方向判定用前缀容忍的自己 id 比对，双方都是自己时如实给「未知」而不是猜一个。
+  **两处已知的"不猜"**：红包表**没有时间列也没有金额列**——真实时间与金额在消息正文的
+  `wcpayinfo` 里，这一步没做，所以红包按 `messageServerId` 排先后并标注"无时间列"；
+  `hb_status`/`receive_status`/`pay_sub_type` 的枚举语义**未逐值验证**，原样输出（本机观测
+  `hb_status ∈ {1,4}`、`receive_status ∈ {0,1,2}`），不给"已领取/已过期"这类翻译。
+- **测试隔离了两处会读真实数据的路径。** `qchat_import_test` 的 `build_index` 用例只把
+  `INDEX_DIR` 指到临时目录，`OUTPUT_ROOT` 仍是真实值，于是它扫到本机 10,981 篇日报文章，
+  `new` 断言 5 变成 10981；`wechat_ledger_test` 的红包 fixture 按 9 列建表却只给 7 个值，
+  `hb_status` 整体左移两格落进 `send_id`。两处都改成显式隔离/对齐，不是调期望值。
+
 ## 1.17.0
 
 - **`sync cursor-probe`：稳定游标从"一句 false"变成一条看得见的路径（D-027）。**

package/README.md

@@ -325,12 +325,15 @@ weflow-cli config set assistantGroupRequireMention true
 | 人脉图谱 | `weflow-cli network --groups` · `--with <名字>`（共同群）· `--intro <名字>`（谁能引荐；只读 contact.db）|
 | 某号观点演变 | `weflow-cli timeline --list` · `--source <公众号名>`（按时间看它说法的变化）|
 | 关系网络时间重放 | `weflow-cli replay`（按月展开，生成可播放的单文件 HTML；看哪条边断了，不只是图变大）|
+| 红包与转账流水 | `weflow-cli ledger --days 365`（读 `general.db`；红包表无时间/金额列，只给先后与原始状态，不翻译语义）|
+| 媒体精确定位 | `weflow-cli media --md5 <前缀>` · `--type image\|file\|video`（读 `hardlink.db`，md5 直接对到本地路径，不扫目录）|
 | 本机判断层 | `weflow-cli decide --request <file> --dry-run` · `--yes` |
 | 导出聊天记录 | `weflow-cli export <联系人> <json\|txt\|html\|excel>` |
 | 同步检查点 | `weflow-cli sync run <联系人> --since <日期>` · `sync status` · `sync verify` · `sync cursor-probe`（离稳定增量游标还差什么，实测当前后端）|
 | QQ 聊天导入 | `weflow-cli import qchat <qchat导出>` · `import list` · `import show <会话>` （读 qchat-cli 的 JSON 导出；之后 `chat-notes --source qq` 产知识卡、`search-index --include-imports` 进搜索）|
 | 公众号日报与阅读器 | `weflow-cli daily` · `weflow-cli daily-server` · `weflow-cli review` |
 | 朋友圈缓存 | `weflow-cli sns timeline` · `weflow-cli sns users` · `weflow-cli sns stats` |
+| 联系人头像 | `weflow-cli avatar <联系人>` · `avatar --list` · `avatar --all`（读 head_image.db，头像本体在库里，缓存清理不丢） |
 | 微信收藏 | `weflow-cli fav list` · `weflow-cli fav export markdown` · `weflow-cli fav set-key` |
 | 微信读书 | `weflow-cli weread shelf` · `notes` · `search` · `stats`（key 从 https://weread.qq.com/r/weread-skills 拿，见 [OPERATIONS.md](./OPERATIONS.md)） |
 | 知识库 | `weflow-cli vault` · `weflow-cli wiki` · `weflow-cli search <query>` · `weflow-cli chat`（语义检索需先 `config set dashscopeApiKey`；`search --phrase <词> --line all` 连语音转写一起搜）|

package/bin/weflow-cli.ts

@@ -33,6 +33,7 @@ import type { ChatSession } from '../src/types.js'
 import { disabledIds, describeSkill, readSkillBody, scanSkills, skillRoots, skillState } from '../src/services/assistantSkills.js'
 import { assistantScenes, validateSceneId, type Scene } from '../src/services/assistantScenes.js'
 import { detectWechatClient, reportedDataDirs, samePath } from '../src/services/wechatClient.js'
+import { WECHAT_VERIFIED, compareWechatVersions, describeCompatVerdict } from '../src/services/wechatCompat.js'
 
 const program = new Command()
 
@@ -305,6 +306,14 @@ program
     const data = {
       schema: 'weflow-capabilities/v1',
       version: CLI_VERSION,
+      // D-130：本包最后用真实数据验证过的微信版本（单一事实源 wechatCompat.ts）。
+      // check 的判定也从同一处读；发布清单要求 CHANGELOG 每版记录（来源就是这里）。
+      compatibility: {
+        wechat: {
+          verifiedVersion: WECHAT_VERIFIED.version,
+          verifiedAt: WECHAT_VERIFIED.verifiedAt,
+        },
+      },
       read: {
         sessions: { cli: 'sessions --json', mcp: 'wechat.list_sessions' },
         messages: { cli: 'messages <talker> --json', mcp: 'wechat.export_messages' },
@@ -2105,6 +2114,108 @@ syncCmd
     console.log('')
   })
 
+// ==================== ledger（资金流水：红包/转账，读 general.db） ====================
+// 2026-10-26 NT 普查产物（docs/NT_DATABASES.md）。如实边界写在脚本头：红包表无
+// 时间/金额列（在消息正文里，按 messageServerId 溯源是后续工作）；状态枚举语义
+// 未逐值验证，原样输出不翻译。本地只读、不联网。
+program
+  .command('ledger')
+  .description('资金流水：红包与转账（读 general.db；本地只读）')
+  .option('--talker <contact>', '只看某个会话（id 或备注/昵称子串）')
+  .option('--days <n>', '只看最近 N 天（按转账时间；红包无时间列不受此限）')
+  .option('--json', '输出 JSON 格式')
+  .action(async (opts) => {
+    const { execFile } = await import('child_process')
+    const { promisify } = await import('util')
+    const execFileAsync = promisify(execFile)
+    const script = join(resolvePackageRoot(), 'scripts', 'wechat_ledger.py')
+    const args = [script, '--json']
+    if (opts.days !== undefined) {
+      const days = parseCliInteger(opts.days, 'days', 1, 36_500, opts.json)
+      args.push('--days', String(days))
+    }
+    try {
+      const { stdout } = await execFileAsync(getPythonCommand(), args, {
+        timeout: 120_000, maxBuffer: 10 * 1024 * 1024,
+        // D-020：会话标识走环境变量，不进 argv
+        env: createPythonProcessEnv(opts.talker ? { WEFLOW_TALKER: String(opts.talker) } : {}),
+      })
+      const payload = JSON.parse(stdout.slice(stdout.indexOf('{')))
+      if (opts.json) { console.log(JSON.stringify(payload)); if (!payload.success) process.exit(1); return }
+      if (!payload.success) { console.error(chalk.red(`✗ ${payload.error}`)); process.exit(1) }
+      console.log(chalk.cyan(`
+资金流水：红包 ${payload.redEnvelopes} 笔、转账 ${payload.transfers} 笔`))
+      console.log(chalk.gray('  （红包无时间/金额列——在消息正文里，按 messageServerId 看先后；状态枚举原样，语义未验证）'))
+      for (const r of payload.rows.slice(0, 40)) {
+        const when = r.time ? new Date(r.time * 1000).toLocaleString('zh-CN', { hour12: false }) : '（无时间列）'
+        const extra = r.kind === '红包'
+          ? `status=${r.hbStatus}/${r.receiveStatus}`
+          : `对方=${r.counterpartyDisplay || r.counterparty || '?'}${r.invalidTime ? ` invalid=${r.invalidTime}` : ''}`
+        console.log(`  [${when}] ${r.kind} · ${r.sessionDisplay} · ${r.direction} · ${extra}`)
+      }
+      if (payload.rows.length > 40) console.log(chalk.gray(`  …共 ${payload.rows.length} 行（--json 看全表）`))
+      console.log('')
+    } catch (e: any) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'LEDGER_FAILED', error: safeSubprocessError(e) })); process.exit(1) }
+      console.error(chalk.red(`✗ ${safeSubprocessError(e)}`))
+      process.exit(1)
+    }
+  })
+
+// ==================== avatar（联系人头像，读 head_image.db） ====================
+// 2026-10-26 NT 数据库普查的直接产物（docs/NT_DATABASES.md）：头像本体内嵌在
+// head_image.db 里（JPEG/PNG 完整字节，按 username 键控，一人多行=变更历史），
+// 比文件缓存可靠（清理不丢）。本地只读、不联网。
+program
+  .command('avatar [contact]')
+  .description('导出联系人头像（读 head_image.db；--list 看谁有头像，--all 批量导出最新头像）')
+  .option('--list', '只列出有头像的 username 与头像数')
+  .option('--all', '导出所有 username 的最新头像到 --out 目录')
+  .option('--out <path>', '输出文件（单联系人）或目录（--all），默认 output/avatars/')
+  .option('--json', '输出 JSON 格式')
+  .action(async (contact: string | undefined, opts) => {
+    if (!contact && !opts.list && !opts.all) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '要给联系人，或用 --list / --all' })); process.exit(1) }
+      console.error(chalk.red('✗ 要给联系人，或用 --list / --all'))
+      process.exit(1)
+    }
+    if (contact && (opts.list || opts.all)) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '联系人与 --list/--all 互斥' })); process.exit(1) }
+      console.error(chalk.red('✗ 联系人与 --list/--all 互斥'))
+      process.exit(1)
+    }
+    const { execFile } = await import('child_process')
+    const { promisify } = await import('util')
+    const execFileAsync = promisify(execFile)
+    const script = join(resolvePackageRoot(), 'scripts', 'wechat_avatar.py')
+    const args = [script, ...(opts.list ? ['--list'] : opts.all ? ['--all'] : []), '--json']
+    // D-020：联系人标识走环境变量，不进 argv；输出路径同理（脚本 --out 缺省读它）
+    const env = {
+      ...(contact ? { WEFLOW_TALKER: String(contact) } : {}),
+      ...(opts.out ? { WEFLOW_AVATAR_OUT: String(opts.out) } : {}),
+    }
+    try {
+      const { stdout } = await execFileAsync(getPythonCommand(), args, {
+        timeout: 120_000, maxBuffer: 10 * 1024 * 1024,
+        env: createPythonProcessEnv(env),
+      })
+      const payload = JSON.parse(stdout.slice(stdout.indexOf('{')))
+      if (opts.json) { console.log(JSON.stringify(payload)); if (!payload.success) process.exit(1); return }
+      if (!payload.success) { console.error(chalk.red(`✗ ${payload.error}`)); process.exit(1) }
+      if (payload.action === 'avatar.export') {
+        console.log(chalk.green(`✓ 已导出「${payload.username}」的最新头像（${payload.bytes} 字节，历史 ${payload.historyCount} 张）→ ${payload.out}`))
+      } else if (payload.action === 'avatar.export-all') {
+        console.log(chalk.green(`✓ 已导出 ${payload.written} 个最新头像 → ${payload.dir}`))
+      } else {
+        console.log(payload.error || `共 ${payload.users?.length ?? '?'} 个 username 有头像（用 --json 看全表）`)
+      }
+    } catch (e: any) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'AVATAR_FAILED', error: safeSubprocessError(e) })); process.exit(1) }
+      console.error(chalk.red(`✗ ${safeSubprocessError(e)}`))
+      process.exit(1)
+    }
+  })
+
 // ==================== contacts ====================
 // contact-schema：读 contact.db 里**群**的 ext_buffer（本地只读：不联网、不调模型）
 //
@@ -7907,6 +8018,47 @@ program
     }
   })
 
+// ==================== media（媒体精确匹配）====================
+program
+  .command('media')
+  .description('媒体精确匹配：用 hardlink.db 把 md5 直接对到本地文件（图片/文件/视频；本地只读）')
+  .option('--md5 <prefix>', '按 md5 前缀查')
+  .option('--type <kind>', 'image | file | video | all', 'all')
+  .option('--limit <n>', '最多列几条', '20')
+  .option('--missing-only', '只列文件已不在本地的（微信会清理）')
+  .option('--json', '输出 JSON 格式')
+  .action(async (opts) => {
+    const { execFile } = await import('child_process')
+    const { promisify } = await import('util')
+    const execFileAsync = promisify(execFile)
+    const script = join(resolvePackageRoot(), 'scripts', 'media_index.py')
+    const limit = parseCliInteger(opts.limit, 'limit', 1, 5000, opts.json)
+
+    try {
+      const args = [script, '--type', String(opts.type || 'all'), '--limit', String(limit)]
+      if (opts.md5) args.push('--md5', String(opts.md5))
+      if (opts.missingOnly) args.push('--missing-only')
+      if (opts.json) args.push('--json')
+      const { stdout } = await execFileAsync(getPythonCommand(), args, {
+        timeout: 300_000,
+        maxBuffer: 16 * 1024 * 1024,
+        env: pythonProcessEnv(),
+      })
+      console.log(stdout)
+    } catch (e: any) {
+      if (opts.json) {
+        console.log(JSON.stringify({
+          success: false,
+          code: 'MEDIA_FAILED',
+          error: '媒体索引不可用，请运行 check --json 检查配置和依赖',
+        }))
+        process.exit(1)
+      }
+      console.error(chalk.red(`\n${safeSubprocessError(e, '查询失败')}`))
+      process.exit(1)
+    }
+  })
+
 // ==================== replay（关系时间重放）====================
 program
   .command('replay')
@@ -8263,6 +8415,12 @@ program
           // 只报条数与最近时间（不读崩溃内容）
           crashRecords: client.crashRecords,
           caveats: client.caveats,
+          // D-130：本机实际加载的版本 vs 本包验证过的版本（判定只有这一份实现）
+          compatibility: {
+            verifiedVersion: WECHAT_VERIFIED.version,
+            verifiedAt: WECHAT_VERIFIED.verifiedAt,
+            verdict: compareWechatVersions(client.version, WECHAT_VERIFIED.version),
+          },
         },
       }
       return data
@@ -8302,6 +8460,7 @@ program
           dataDirMatchesConfig: data.wechatClient.dataDirMatchesConfig,
           dataDirs: data.wechatClient.dataDirs,
           unusableVersionDirs: data.wechatClient.unusableVersionDirs,
+          compatibility: data.wechatClient.compatibility,
         },
       }))
       return
@@ -8360,6 +8519,14 @@ program
       }
     }
 
+    // 3.5 微信版本兼容（D-130）：本机加载的 vs 本包验证过的
+    {
+      const verdict = compareWechatVersions(client.version, WECHAT_VERIFIED.version)
+      const mark = verdict === 'verified' ? chalk.green('✓') : verdict === 'newer-than-verified' ? chalk.yellow('⚠') : chalk.gray('·')
+      console.log(chalk.white('\n微信版本兼容:'))
+      console.log(`  ${mark} ${client.version ?? '未知（微信没在运行）'} · ${describeCompatVerdict(verdict, WECHAT_VERIFIED.version)}`)
+    }
+
     // 4. Config
     console.log(chalk.white('\n配置状态:'))
     const configured = configService.isConfigured()

package/dist/bin/weflow-cli.js

@@ -31,6 +31,7 @@ import { applyDerivedNtKeys, enableFavorites, detectFavDbPath } from '../src/ser
 import { disabledIds, readSkillBody, scanSkills, skillRoots, skillState } from '../src/services/assistantSkills.js';
 import { assistantScenes, validateSceneId } from '../src/services/assistantScenes.js';
 import { detectWechatClient, reportedDataDirs, samePath } from '../src/services/wechatClient.js';
+import { WECHAT_VERIFIED, compareWechatVersions, describeCompatVerdict } from '../src/services/wechatCompat.js';
 const program = new Command();
 function resolvePackageRoot() {
     return resolvePackageRootFrom(import.meta.url);
@@ -288,6 +289,14 @@ program
     const data = {
         schema: 'weflow-capabilities/v1',
         version: CLI_VERSION,
+        // D-130：本包最后用真实数据验证过的微信版本（单一事实源 wechatCompat.ts）。
+        // check 的判定也从同一处读；发布清单要求 CHANGELOG 每版记录（来源就是这里）。
+        compatibility: {
+            wechat: {
+                verifiedVersion: WECHAT_VERIFIED.version,
+                verifiedAt: WECHAT_VERIFIED.verifiedAt,
+            },
+        },
         read: {
             sessions: { cli: 'sessions --json', mcp: 'wechat.list_sessions' },
             messages: { cli: 'messages <talker> --json', mcp: 'wechat.export_messages' },
@@ -2160,6 +2169,139 @@ syncCmd
     }
     console.log('');
 });
+// ==================== ledger（资金流水：红包/转账，读 general.db） ====================
+// 2026-10-26 NT 普查产物（docs/NT_DATABASES.md）。如实边界写在脚本头：红包表无
+// 时间/金额列（在消息正文里，按 messageServerId 溯源是后续工作）；状态枚举语义
+// 未逐值验证，原样输出不翻译。本地只读、不联网。
+program
+    .command('ledger')
+    .description('资金流水：红包与转账（读 general.db；本地只读）')
+    .option('--talker <contact>', '只看某个会话（id 或备注/昵称子串）')
+    .option('--days <n>', '只看最近 N 天（按转账时间；红包无时间列不受此限）')
+    .option('--json', '输出 JSON 格式')
+    .action(async (opts) => {
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    const script = join(resolvePackageRoot(), 'scripts', 'wechat_ledger.py');
+    const args = [script, '--json'];
+    if (opts.days !== undefined) {
+        const days = parseCliInteger(opts.days, 'days', 1, 36_500, opts.json);
+        args.push('--days', String(days));
+    }
+    try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+            timeout: 120_000, maxBuffer: 10 * 1024 * 1024,
+            // D-020：会话标识走环境变量，不进 argv
+            env: createPythonProcessEnv(opts.talker ? { WEFLOW_TALKER: String(opts.talker) } : {}),
+        });
+        const payload = JSON.parse(stdout.slice(stdout.indexOf('{')));
+        if (opts.json) {
+            console.log(JSON.stringify(payload));
+            if (!payload.success)
+                process.exit(1);
+            return;
+        }
+        if (!payload.success) {
+            console.error(chalk.red(`✗ ${payload.error}`));
+            process.exit(1);
+        }
+        console.log(chalk.cyan(`
+资金流水：红包 ${payload.redEnvelopes} 笔、转账 ${payload.transfers} 笔`));
+        console.log(chalk.gray('  （红包无时间/金额列——在消息正文里，按 messageServerId 看先后；状态枚举原样，语义未验证）'));
+        for (const r of payload.rows.slice(0, 40)) {
+            const when = r.time ? new Date(r.time * 1000).toLocaleString('zh-CN', { hour12: false }) : '（无时间列）';
+            const extra = r.kind === '红包'
+                ? `status=${r.hbStatus}/${r.receiveStatus}`
+                : `对方=${r.counterpartyDisplay || r.counterparty || '?'}${r.invalidTime ? ` invalid=${r.invalidTime}` : ''}`;
+            console.log(`  [${when}] ${r.kind} · ${r.sessionDisplay} · ${r.direction} · ${extra}`);
+        }
+        if (payload.rows.length > 40)
+            console.log(chalk.gray(`  …共 ${payload.rows.length} 行（--json 看全表）`));
+        console.log('');
+    }
+    catch (e) {
+        if (opts.json) {
+            console.log(JSON.stringify({ success: false, code: 'LEDGER_FAILED', error: safeSubprocessError(e) }));
+            process.exit(1);
+        }
+        console.error(chalk.red(`✗ ${safeSubprocessError(e)}`));
+        process.exit(1);
+    }
+});
+// ==================== avatar（联系人头像，读 head_image.db） ====================
+// 2026-10-26 NT 数据库普查的直接产物（docs/NT_DATABASES.md）：头像本体内嵌在
+// head_image.db 里（JPEG/PNG 完整字节，按 username 键控，一人多行=变更历史），
+// 比文件缓存可靠（清理不丢）。本地只读、不联网。
+program
+    .command('avatar [contact]')
+    .description('导出联系人头像（读 head_image.db；--list 看谁有头像，--all 批量导出最新头像）')
+    .option('--list', '只列出有头像的 username 与头像数')
+    .option('--all', '导出所有 username 的最新头像到 --out 目录')
+    .option('--out <path>', '输出文件（单联系人）或目录（--all），默认 output/avatars/')
+    .option('--json', '输出 JSON 格式')
+    .action(async (contact, opts) => {
+    if (!contact && !opts.list && !opts.all) {
+        if (opts.json) {
+            console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '要给联系人，或用 --list / --all' }));
+            process.exit(1);
+        }
+        console.error(chalk.red('✗ 要给联系人，或用 --list / --all'));
+        process.exit(1);
+    }
+    if (contact && (opts.list || opts.all)) {
+        if (opts.json) {
+            console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '联系人与 --list/--all 互斥' }));
+            process.exit(1);
+        }
+        console.error(chalk.red('✗ 联系人与 --list/--all 互斥'));
+        process.exit(1);
+    }
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    const script = join(resolvePackageRoot(), 'scripts', 'wechat_avatar.py');
+    const args = [script, ...(opts.list ? ['--list'] : opts.all ? ['--all'] : []), '--json'];
+    // D-020：联系人标识走环境变量，不进 argv；输出路径同理（脚本 --out 缺省读它）
+    const env = {
+        ...(contact ? { WEFLOW_TALKER: String(contact) } : {}),
+        ...(opts.out ? { WEFLOW_AVATAR_OUT: String(opts.out) } : {}),
+    };
+    try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+            timeout: 120_000, maxBuffer: 10 * 1024 * 1024,
+            env: createPythonProcessEnv(env),
+        });
+        const payload = JSON.parse(stdout.slice(stdout.indexOf('{')));
+        if (opts.json) {
+            console.log(JSON.stringify(payload));
+            if (!payload.success)
+                process.exit(1);
+            return;
+        }
+        if (!payload.success) {
+            console.error(chalk.red(`✗ ${payload.error}`));
+            process.exit(1);
+        }
+        if (payload.action === 'avatar.export') {
+            console.log(chalk.green(`✓ 已导出「${payload.username}」的最新头像（${payload.bytes} 字节，历史 ${payload.historyCount} 张）→ ${payload.out}`));
+        }
+        else if (payload.action === 'avatar.export-all') {
+            console.log(chalk.green(`✓ 已导出 ${payload.written} 个最新头像 → ${payload.dir}`));
+        }
+        else {
+            console.log(payload.error || `共 ${payload.users?.length ?? '?'} 个 username 有头像（用 --json 看全表）`);
+        }
+    }
+    catch (e) {
+        if (opts.json) {
+            console.log(JSON.stringify({ success: false, code: 'AVATAR_FAILED', error: safeSubprocessError(e) }));
+            process.exit(1);
+        }
+        console.error(chalk.red(`✗ ${safeSubprocessError(e)}`));
+        process.exit(1);
+    }
+});
 // ==================== contacts ====================
 // contact-schema：读 contact.db 里**群**的 ext_buffer（本地只读：不联网、不调模型）
 //
@@ -8226,6 +8368,49 @@ program
         process.exit(1);
     }
 });
+// ==================== media（媒体精确匹配）====================
+program
+    .command('media')
+    .description('媒体精确匹配：用 hardlink.db 把 md5 直接对到本地文件（图片/文件/视频；本地只读）')
+    .option('--md5 <prefix>', '按 md5 前缀查')
+    .option('--type <kind>', 'image | file | video | all', 'all')
+    .option('--limit <n>', '最多列几条', '20')
+    .option('--missing-only', '只列文件已不在本地的（微信会清理）')
+    .option('--json', '输出 JSON 格式')
+    .action(async (opts) => {
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    const script = join(resolvePackageRoot(), 'scripts', 'media_index.py');
+    const limit = parseCliInteger(opts.limit, 'limit', 1, 5000, opts.json);
+    try {
+        const args = [script, '--type', String(opts.type || 'all'), '--limit', String(limit)];
+        if (opts.md5)
+            args.push('--md5', String(opts.md5));
+        if (opts.missingOnly)
+            args.push('--missing-only');
+        if (opts.json)
+            args.push('--json');
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+            timeout: 300_000,
+            maxBuffer: 16 * 1024 * 1024,
+            env: pythonProcessEnv(),
+        });
+        console.log(stdout);
+    }
+    catch (e) {
+        if (opts.json) {
+            console.log(JSON.stringify({
+                success: false,
+                code: 'MEDIA_FAILED',
+                error: '媒体索引不可用，请运行 check --json 检查配置和依赖',
+            }));
+            process.exit(1);
+        }
+        console.error(chalk.red(`\n${safeSubprocessError(e, '查询失败')}`));
+        process.exit(1);
+    }
+});
 // ==================== replay（关系时间重放）====================
 program
     .command('replay')
@@ -8598,6 +8783,12 @@ program
                 // 只报条数与最近时间（不读崩溃内容）
                 crashRecords: client.crashRecords,
                 caveats: client.caveats,
+                // D-130：本机实际加载的版本 vs 本包验证过的版本（判定只有这一份实现）
+                compatibility: {
+                    verifiedVersion: WECHAT_VERIFIED.version,
+                    verifiedAt: WECHAT_VERIFIED.verifiedAt,
+                    verdict: compareWechatVersions(client.version, WECHAT_VERIFIED.version),
+                },
             },
         };
         return data;
@@ -8635,6 +8826,7 @@ program
                 dataDirMatchesConfig: data.wechatClient.dataDirMatchesConfig,
                 dataDirs: data.wechatClient.dataDirs,
                 unusableVersionDirs: data.wechatClient.unusableVersionDirs,
+                compatibility: data.wechatClient.compatibility,
             },
         }));
         return;
@@ -8692,6 +8884,13 @@ program
             }
         }
     }
+    // 3.5 微信版本兼容（D-130）：本机加载的 vs 本包验证过的
+    {
+        const verdict = compareWechatVersions(client.version, WECHAT_VERIFIED.version);
+        const mark = verdict === 'verified' ? chalk.green('✓') : verdict === 'newer-than-verified' ? chalk.yellow('⚠') : chalk.gray('·');
+        console.log(chalk.white('\n微信版本兼容:'));
+        console.log(`  ${mark} ${client.version ?? '未知（微信没在运行）'} · ${describeCompatVerdict(verdict, WECHAT_VERIFIED.version)}`);
+    }
     // 4. Config
     console.log(chalk.white('\n配置状态:'));
     const configured = configService.isConfigured();