weflow-cli 1.16.0 → 1.19.0

package/bin/weflow-cli.ts

@@ -7,6 +7,9 @@ import { existsSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { SYNC_SCHEMA, SYNC_SOURCE, syncStateStore } from '../src/services/syncState.js'
 import { SyncRangeRequiredError, runSync } from '../src/services/syncService.js'
+import { probeCursorReadiness } from '../src/services/cursorProbe.js'
+import { planSetup, runSetup } from '../src/services/setupVenv.js'
+import { planImportQchat, runImportQchat, listImports, readImportedSession } from '../src/services/qchatImport.js'
 import { dbPathService } from '../src/core/dbPathService.js'
 import { keyService } from '../src/core/keyService.js'
 import { NtCore } from '../src/core/ntCore.js'
@@ -30,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()
 
@@ -302,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' },
@@ -312,7 +324,30 @@ program
           versionedContract: 'weflow-message/v1',
           rawContractPreserved: true,
           coverage: ['requestedFrom', 'requestedTo', 'requestedLimit', 'returned', 'mayHaveMore', 'oldestCreateTime', 'newestCreateTime'],
-          incrementalRead: { mode: 'overlapping-time-window', stableCursor: false },
+          incrementalRead: {
+            mode: 'overlapping-time-window',
+            stableCursor: false,
+            // D-027 的另一半：光写 false 是句结论，这里把 false → true 的**路径**
+            // 摊开。probe 指向的那条命令会实测 NT 数据侧判据（采样有界、结果里
+            // 自带 exhaustive=false）；backends 里的字段是代码事实，改读取器时同步改。
+            cursorReadiness: {
+              probe: 'sync cursor-probe --json',
+              criteria: [
+                'stable-identity: 每条消息都有非零且不重复的 server_id（缺失时身份退化为按分片的 localId+createTime，不能跨分片续读）',
+                'globally-comparable-order: 跨分片合并的顺序键可比（现在是 createTime+localId，localId 不跨分片可比）',
+                'window-pushdown: 时间窗下推进读取（现在只有 NT 后端）',
+                'coverage-report: 后端能报告本次读取是否完整（现在只有 NT 的分片报告）',
+                'every-backend: 上述各项在所有消息后端同时成立（D-027 的总门）',
+              ],
+              backends: {
+                'nt': { identity: 'server_id（退化为 localId+createTime）', windowPushdown: true, coverageReport: true, liveProbe: true },
+                'raw-sqlite-4x': { identity: 'MsgSvrID 列被读取、覆盖率未实测', windowPushdown: false, coverageReport: false, liveProbe: false },
+                'wcdb-4x': { identity: 'server_id 随原生 API 返回、未实测', windowPushdown: false, coverageReport: false, liveProbe: false },
+                'legacy-3x': { identity: 'MsgSvrID 列被读取、覆盖率未实测', windowPushdown: false, coverageReport: false, liveProbe: false },
+              },
+              advertisedWhen: 'every backend reports true on every criterion above',
+            },
+          },
         },
         favorites: {
           cli: 'fav list --json',
@@ -675,6 +710,232 @@ program
     console.log(JSON.stringify(data, null, 2))
   })
 
+// ==================== setup（自管 Python venv） ====================
+// Issues 里最大的两类环境噪音（PowerShell 策略 / 商店占位 python 的 9009）里，
+// 后者的根因是"没有能 import sqlcipher3 的 Python"。这条命令一次性解决：
+// 在 ~/.weflow-cli/venv 建 venv 并装 requirements，之后 getPythonCommand() 优先用它。
+program
+  .command('setup')
+  .description('创建自管 Python 虚拟环境 (~/.weflow-cli/venv) 并安装依赖；之后所有 Python 工作流优先用它')
+  .option('--dry-run', '只看计划：venv 位置、用哪个 Python 建、装哪些包（不动任何东西）')
+  .option('--yes', '跳过交互确认（机器执行路径）')
+  .option('--recreate', '删除现有 venv 后重建（默认已存在则复用）')
+  .option('--with-3x', '同时安装 requirements-3x.txt（微信 3.x 旧版密钥提取）')
+  .option('--with-voice', '同时安装 requirements-voice.txt（本机语音转写）')
+  .option('--non-interactive', '禁止交互提问；与 --yes 配合用于脚本')
+  .option('--json', '输出 JSON 格式')
+  .action(async (opts) => {
+    let plan
+    try {
+      plan = await planSetup({ recreate: !!opts.recreate, with3x: !!opts.with3x, withVoice: !!opts.withVoice })
+    } catch (error: any) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SETUP_PLAN_FAILED', error: String(error?.message || error).slice(0, 200) })); process.exit(1) }
+      console.error(chalk.red(`✗ 计划失败: ${error?.message || error}`))
+      process.exit(1)
+    }
+
+    if (opts.dryRun || !opts.yes) {
+      const preview = {
+        success: true,
+        dryRun: true,
+        action: 'setup.venv',
+        venvDir: plan.venvDir,
+        venvExists: existsSync(plan.venvDir),
+        creator: plan.creator,
+        requirementFiles: plan.requirementFiles,
+        packages: plan.packages,
+        substitutions: plan.substitutions,
+        recreate: plan.recreate,
+        createsUnder: plan.createsUnder,
+        network: plan.network,
+        // 密钥/数据库一个都不碰：这条命令只写 ~/.weflow-cli/venv
+        readsLocalData: false,
+      }
+      if (opts.dryRun) {
+        if (opts.json) { console.log(JSON.stringify(preview)); return }
+        console.log(chalk.cyan('\nsetup 计划（--dry-run，不执行）'))
+        console.log(chalk.gray(`  venv: ${plan.venvDir}${existsSync(plan.venvDir) ? '（已存在，默认复用）' : ''}`))
+        console.log(chalk.gray(`  创建者: ${plan.creator ?? '未找到可运行的 Python（先装 Python 3.10+）'}`))
+        console.log(chalk.gray(`  安装: ${plan.packages.join(' ')}`))
+        for (const sub of plan.substitutions) console.log(chalk.gray(`  替换: ${sub}`))
+        console.log(chalk.gray('  网络请求: pip 访问 PyPI；不读聊天数据、不碰密钥\n'))
+        return
+      }
+      if (opts.json) {
+        console.log(JSON.stringify({ ...preview, success: false, dryRun: false, code: 'CONFIRMATION_REQUIRED' }))
+        process.exit(1)
+      }
+      if (process.env.WEFLOW_NON_INTERACTIVE || opts.nonInteractive) {
+        console.error(chalk.red('✗ 非交互模式需要 --yes'))
+        process.exit(1)
+      }
+      const { confirmed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirmed',
+        message: `将在 ${plan.venvDir} 创建虚拟环境并安装 ${plan.packages.length} 个包（pip 需要访问 PyPI）。继续吗？`,
+        default: false,
+      }])
+      if (!confirmed) {
+        console.log(chalk.gray('已取消'))
+        return
+      }
+    }
+
+    const result = await runSetup(plan, (line) => console.log(chalk.gray(`  ${line}`)))
+    if (opts.json) {
+      console.log(JSON.stringify(result))
+      if (!result.success) process.exit(1)
+      return
+    }
+    console.log(chalk.cyan('\nPython 环境 setup'))
+    for (const step of result.steps) {
+      console.log(`  ${step.ok ? '✓' : '✗'} ${step.name}${step.detail ? chalk.gray(` — ${step.detail}`) : ''}`)
+    }
+    if (result.success) {
+      console.log(chalk.green(`\n完成。之后的 Python 工作流会优先用: ${result.venvPython}`))
+      console.log(chalk.gray('  下一步: weflow-cli check 验证环境，weflow-cli init 初始化本地数据'))
+    } else {
+      console.log(chalk.red(`\n失败（${result.error ?? '见上方步骤'}）。把 --json 输出贴到 issue 里最好排查。`))
+      process.exit(1)
+    }
+  })
+
+// ==================== import（外部 IM 数据导入，D-129） ====================
+// 边界是**文件契约**：读 qchat-cli `qce export --format json` 的产物，归一化落到
+// output/imports/qq/，之后 chat-notes / search-index 就能把 QQ 会话当普通聊天线处理。
+const importCmd = program
+  .command('import')
+  .description('导入外部 IM 的聊天记录（当前支持 qchat-cli 的 JSON 导出），并入本地知识管道')
+
+importCmd
+  .command('qchat <path>')
+  .description('导入 qchat-cli 的 JSON 导出（单文件或目录；按 messageId 去重，重复导入安全）')
+  .option('--dry-run', '只看会导入什么：文件、会话、条数（不写任何东西）')
+  .option('--yes', '确认执行（写本地存储 output/imports/qq/）')
+  .option('--own-id <qq>', '可选：自己的 QQ 号，用来标 isSend（不给则该字段缺省为未知）')
+  .option('--json', '输出 JSON 格式')
+  .action(async (inputPath: string, opts) => {
+    let plan
+    try {
+      plan = planImportQchat(inputPath)
+    } catch (error: any) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'IMPORT_PLAN_FAILED', error: String(error?.message || error).slice(0, 200) })); process.exit(1) }
+      console.error(chalk.red(`✗ 计划失败: ${error?.message || error}`))
+      process.exit(1)
+    }
+
+    const preview = {
+      success: true,
+      dryRun: true,
+      action: 'import.qchat',
+      input: inputPath,
+      files: plan.files.map(f => ({
+        file: basename(f.file), ok: f.ok,
+        ...(f.reason ? { reason: f.reason } : {}),
+        sessions: f.sessions.map(s => ({ id: s.id, name: s.name, type: s.type, messages: s.messages })),
+      })),
+      sessionsFound: plan.sessionsFound,
+      messagesTotal: plan.messagesTotal,
+      storeRoot: plan.storeRoot,
+      ownIdProvided: Boolean(opts.ownId),
+      readsLocalData: true,
+      writesLocalStore: true,
+      invokesAI: false,
+      network: false,
+    }
+    if (opts.dryRun) {
+      if (opts.json) { console.log(JSON.stringify(preview)); return }
+      console.log(chalk.cyan('\nimport qchat 计划（--dry-run，不执行）'))
+      console.log(chalk.gray(`  存储: ${plan.storeRoot}`))
+      for (const f of plan.files) {
+        if (f.ok) {
+          for (const sess of f.sessions) {
+            console.log(chalk.gray(`  ✓ ${basename(f.file)} → 会话「${sess.name}」（${sess.type}，${sess.messages} 条）`))
+          }
+        } else {
+          console.log(chalk.yellow(`  ✗ ${basename(f.file)} — ${f.reason}`))
+        }
+      }
+      if (opts.ownId) console.log(chalk.gray(`  isSend 判定: 按自己的 QQ 号 ${String(opts.ownId).slice(0, 4)}…`))
+      console.log('')
+      return
+    }
+    if (!opts.yes) {
+      if (opts.json) {
+        console.log(JSON.stringify({ ...preview, success: false, dryRun: false, code: 'CONFIRMATION_REQUIRED' }))
+        process.exit(1)
+      }
+      console.error(chalk.red(`✗ 需要确认：将把 ${plan.messagesTotal} 条消息写入本地存储 ${plan.storeRoot}。加 --yes 执行`))
+      process.exit(1)
+    }
+
+    const result = runImportQchat(inputPath, opts.ownId ? String(opts.ownId) : undefined)
+    if (opts.json) {
+      console.log(JSON.stringify(result))
+      if (!result.success) process.exit(1)
+      return
+    }
+    if (!result.success) {
+      console.error(chalk.red(`✗ 没有可导入的文件（${result.filesSkipped} 个被跳过，原因见 --dry-run）`))
+      process.exit(1)
+    }
+    console.log(chalk.cyan('\n导入完成'))
+    for (const sess of result.sessions) {
+      console.log(chalk.green(`  ✓ 「${sess.name}」共 ${sess.total} 条（新增 ${sess.added}、更新 ${sess.updated}、原样 ${sess.unchanged}）`))
+    }
+    if (result.filesSkipped) console.log(chalk.yellow(`  ⚠ 跳过 ${result.filesSkipped} 个不认识的文件`))
+    console.log(chalk.gray(`  存储: ${result.storeRoot}`))
+    console.log(chalk.gray('  下一步: weflow-cli import list 查看；chat-notes --source qq 产知识卡；search-index --include-imports 进搜索'))
+  })
+
+importCmd
+  .command('list')
+  .description('列出已导入的会话')
+  .option('--json', '输出 JSON 格式')
+  .action((opts) => {
+    const entries = listImports()
+    if (opts.json) { console.log(JSON.stringify({ success: true, sessions: entries })); return }
+    if (!entries.length) {
+      console.log(chalk.gray('\n还没有导入任何会话。先跑 weflow-cli import qchat <qchat 导出文件>'))
+      return
+    }
+    console.log(chalk.cyan(`\n已导入 ${entries.length} 个会话`))
+    for (const e of entries) {
+      const span = e.newestCreateTime
+        ? `${new Date((e.oldestCreateTime ?? 0) * 1000).toLocaleDateString('zh-CN')} ~ ${new Date(e.newestCreateTime * 1000).toLocaleDateString('zh-CN')}`
+        : '（无消息）'
+      console.log(`  「${e.name}」（${e.type}，${e.messages} 条，${span}）`)
+    }
+    console.log('')
+  })
+
+importCmd
+  .command('show <sessionId>')
+  .description('读回一个已导入会话的消息（验证导入）')
+  .option('-n, --limit <n>', '只看最近 N 条（0 = 全部）', '20')
+  .option('--json', '输出 JSON 格式')
+  .action((sessionId: string, opts) => {
+    const limit = Number(opts.limit)
+    if (!Number.isInteger(limit) || limit < 0) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: 'limit 必须是 ≥ 0 的整数' })); process.exit(1) }
+      console.error(chalk.red('✗ limit 必须是 ≥ 0 的整数'))
+      process.exit(1)
+    }
+    const data = readImportedSession(sessionId, limit)
+    if (!data) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'IMPORT_SESSION_NOT_FOUND' })); process.exit(1) }
+      console.error(chalk.red(`✗ 没有会话 ${sessionId} 的导入记录`))
+      process.exit(1)
+    }
+    if (opts.json) { console.log(JSON.stringify({ success: true, ...data })); return }
+    console.log(chalk.cyan(`\n「${data.session.name}」共 ${data.messages.length} 条（存储里全部 ${listImports().find(e => e.id === sessionId)?.messages ?? '?'} 条）`))
+    for (const m of data.messages) {
+      const who = m.isSend === undefined ? m.senderName : (m.isSend ? '我' : m.senderName)
+      console.log(chalk.gray(`[${new Date(m.createTime * 1000).toLocaleString('zh-CN')}] ${who}(${m.messageType}): `) + m.parsedContent.slice(0, 80))
+    }
+    console.log('')
+  })
+
 // ==================== init ====================
 program
   .command('init')
@@ -1806,6 +2067,155 @@ syncCmd
     if (!success) process.exit(1)
   })
 
+// 稳定游标的"路径可见"探针（D-027）。只读、本地、无确认门——与 `check` 同一副姿态：
+// 它是诊断，不是副作用。`stableCursor` 的结论**不会**因为它翻 true；它做的是把
+// "还差什么"逐条摊开给下游（she-love-me、MCP 客户端）看。
+syncCmd
+  .command('cursor-probe')
+  .description('探测当前消息后端离稳定增量游标还差什么（只读，NT 后端带实测采样）')
+  .option('--json', '输出 JSON 格式')
+  .option('--tables-per-shard <n>', '每分片采样的会话表数量（schema 检查始终全量）', '5')
+  .option('--rows-per-table <n>', '每张表两端各采样的行数', '500')
+  .action(async (opts) => {
+    const parseBound = (raw: string, label: string): number | undefined => {
+      const n = Number(raw)
+      if (!Number.isInteger(n) || n < 1 || n > 10_000) {
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: `${label} 必须是 1-10000 的整数` })); process.exit(1) }
+        console.error(chalk.red(`✗ ${label} 必须是 1-10000 的整数`))
+        process.exit(1)
+      }
+      return n
+    }
+    let report
+    try {
+      report = await probeCursorReadiness({
+        tablesPerShard: parseBound(opts.tablesPerShard, '--tables-per-shard'),
+        rowsPerTable: parseBound(opts.rowsPerTable, '--rows-per-table'),
+      })
+    } catch (error: any) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'CURSOR_PROBE_FAILED', error: error?.message || '探测失败' })); process.exit(1) }
+      console.error(chalk.red(`✗ 探测失败: ${error?.message || error}`))
+      process.exit(1)
+    }
+    if (opts.json) { console.log(JSON.stringify(report)); return }
+
+    console.log(chalk.cyan('\n稳定游标探针（结论不变：stableCursor = false，D-027）'))
+    console.log(chalk.gray(`  后端: ${report.backend ?? '（未配置）'} — ${report.backendNote}`))
+    console.log(chalk.gray(`  实测: ${report.probedLive ? `已采样（exhaustive=false）` : '未运行（该后端无实测探针或未初始化）'}`))
+    for (const c of report.criteria) {
+      const mark = c.met === null ? '?' : c.met ? '✓' : '✗'
+      console.log(`  ${mark} ${c.id}`)
+      console.log(chalk.gray(`      ${c.detail}`))
+    }
+    if (report.sample) {
+      const sm = report.sample
+      console.log(chalk.gray(`  采样: ${sm.rowsSampled} 行 / ${sm.tablesSampled} 表（共 ${sm.tablesTotal} 表，每表两端各 ${sm.rowsPerTable} 行）`))
+    }
+    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（本地只读：不联网、不调模型）
 //
@@ -5204,6 +5614,7 @@ program
     .option('--api-key <key>', 'DashScope embedding API key')
     .option('--days <n>', '聊天记录收最近多少天（默认 90）')
     .option('--article-days <n>', '日报文章收最近多少个日期目录（默认 30）')
+    .option('--include-imports', '把 weflow-cli import qchat 导入的 QQ 会话也收进索引（聊天半边）')
     .option('--dry-run', '仅预览，不读取数据库、调用网络或写入索引')
     .option('--yes', '确认构建或重建索引')
     .option('--json', '输出 JSON 格式')
@@ -5252,6 +5663,7 @@ program
         mode: opts.full ? 'full' : 'incremental',
         chatDays,
         articleDays,
+        includeImports: !!opts.includeImports,
         readsLocalData: true,
         usesCloudEmbedding: true,
         replacesExistingIndex: !!opts.full,
@@ -5289,6 +5701,7 @@ program
       const args: string[] = [script, 'build', '--days', String(chatDays),
                               '--article-days', String(articleDays)]
       if (opts.full) args.push('--full')
+      if (opts.includeImports) args.push('--include-imports')
       try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
           // 30 分钟：全量重建实测要跑二十分钟以上（16k 条 / 1500+ 批），而这里原来给的是 5 分钟 --
@@ -5973,6 +6386,7 @@ program
     .description('把最近一段时间的会话整理成知识卡（之后用 wiki compile 聚成概念页）—— **只写本地文件，不发送**')
     .option('--days <n>', '看最近多少天', '30')
     .option('--limit <n>', '最多处理几个会话', '40')
+    .option('--source <source>', '聊天来源：wechat（默认）/ qq（只读 import qchat 导入的会话，不碰微信库）/ all（都要）', 'wechat')
     .option('--dry-run', '仅预览：几个会话、多少字符会发给生成模型（只读本地，零出境）')
     .option('--yes', '确认把对话发送给生成模型')
     .option('--transcribe-voice',
@@ -5986,12 +6400,13 @@ program
       const script = join(pkgRoot, 'scripts', 'chat_notes.py')
       const days = parseCliInteger(opts.days, 'days', 1, 3650, opts.json)
       const limit = parseCliInteger(opts.limit, 'limit', 1, 200, opts.json)
+      requireCliChoice(opts.source, ['wechat', 'qq', 'all'], 'source', opts.json)
       // 与 `draft` 同一条纪律：**"确认过了"只用一个变量**，参数在确认之后才拼
       let confirmed = !!opts.yes
       if (!opts.dryRun && !confirmed) {
         const preview = {
           success: false, dryRun: false, action: 'chat-notes',
-          code: 'CONFIRMATION_REQUIRED', days, limit,
+          code: 'CONFIRMATION_REQUIRED', days, limit, source: opts.source,
           readsLocalChat: true, invokesAI: true, writesLocalFiles: true, sendsNothing: true,
         }
         if (opts.json) {
@@ -6011,6 +6426,7 @@ program
         }
       }
       const args = [script, '--days', String(days), '--limit', String(limit),
+                    '--source', String(opts.source),
                     ...(confirmed ? ['--yes'] : []),
                     ...(opts.transcribeVoice ? ['--transcribe-voice'] : []),
                     ...(opts.json ? ['--json'] : []),
@@ -7455,12 +7871,12 @@ program
 
     try {
       const args = [script, '--years', String(opts.years || '1,3,5'), '--limit', String(limit)]
-      if (opts.talker) args.push('--talker', String(opts.talker))
       if (opts.json) args.push('--json')
+      // D-020：会话标识不进子进程 argv（进程列表里看得见），走 WEFLOW_TALKER。
       const { stdout } = await execFileAsync(getPythonCommand(), args, {
         timeout: 300_000,
         maxBuffer: 10 * 1024 * 1024,
-        env: pythonProcessEnv(),
+        env: createPythonProcessEnv(opts.talker ? { WEFLOW_TALKER: String(opts.talker) } : {}),
       })
       console.log(stdout)
     } catch (e: any) {
@@ -7539,12 +7955,12 @@ program
 
     try {
       const args = [script, '--days', String(days), '--limit', String(limit)]
-      if (opts.talker) args.push('--talker', String(opts.talker))
       if (opts.json) args.push('--json')
+      // D-020：同 today——会话标识走 WEFLOW_TALKER，不进 argv。
       const { stdout } = await execFileAsync(getPythonCommand(), args, {
         timeout: 300_000,
         maxBuffer: 10 * 1024 * 1024,
-        env: pythonProcessEnv(),
+        env: createPythonProcessEnv(opts.talker ? { WEFLOW_TALKER: String(opts.talker) } : {}),
       })
       console.log(stdout)
     } catch (e: any) {
@@ -7602,6 +8018,84 @@ 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')
+  .description('关系网络时间重放：按月展开，生成可播放的单文件 HTML（本地、离线、不调模型）')
+  .option('--out <file>', '输出路径', 'output/replay.html')
+  .option('--min-weight <number>', '当月互动量门槛，低于此不计入', '10')
+  .option('--json', '只输出聚合结果（验收用）')
+  .action(async (opts) => {
+    const { execFile } = await import('child_process')
+    const { promisify } = await import('util')
+    const execFileAsync = promisify(execFile)
+    const script = join(resolvePackageRoot(), 'scripts', 'replay.py')
+    const minWeight = parseCliInteger(opts.minWeight, 'min-weight', 1, 10000, opts.json)
+
+    try {
+      const args = [script, '--min-weight', String(minWeight), '--out', String(opts.out)]
+      if (opts.json) args.push('--json')
+      const { stdout } = await execFileAsync(getPythonCommand(), args, {
+        timeout: 600_000,
+        maxBuffer: 64 * 1024 * 1024,
+        env: pythonProcessEnv(),
+      })
+      console.log(stdout)
+    } catch (e: any) {
+      if (opts.json) {
+        console.log(JSON.stringify({
+          success: false,
+          code: 'REPLAY_FAILED',
+          error: '时间重放不可用，请运行 check --json 检查配置和依赖',
+        }))
+        process.exit(1)
+      }
+      console.error(chalk.red(`\n${safeSubprocessError(e, '生成失败')}`))
+      process.exit(1)
+    }
+  })
+
 // ==================== timeline（某号观点演变）====================
 program
   .command('timeline')
@@ -7921,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
@@ -7960,6 +8460,7 @@ program
           dataDirMatchesConfig: data.wechatClient.dataDirMatchesConfig,
           dataDirs: data.wechatClient.dataDirs,
           unusableVersionDirs: data.wechatClient.unusableVersionDirs,
+          compatibility: data.wechatClient.compatibility,
         },
       }))
       return
@@ -8018,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()