weflow-cli 1.16.0 → 1.19.0

package/dist/bin/weflow-cli.js

@@ -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';
@@ -28,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);
@@ -285,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' },
@@ -295,7 +307,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',
@@ -657,6 +692,256 @@ 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) {
+        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, opts) => {
+    let plan;
+    try {
+        plan = planImportQchat(inputPath);
+    }
+    catch (error) {
+        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, 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')
@@ -1829,6 +2114,194 @@ 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, label) => {
+        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) {
+        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) {
+        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（本地只读：不联网、不调模型）
 //
@@ -5433,6 +5906,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 格式')
@@ -5482,6 +5956,7 @@ program
         mode: opts.full ? 'full' : 'incremental',
         chatDays,
         articleDays,
+        includeImports: !!opts.includeImports,
         readsLocalData: true,
         usesCloudEmbedding: true,
         replacesExistingIndex: !!opts.full,
@@ -5522,6 +5997,8 @@ program
         '--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 分钟 --
@@ -6244,6 +6721,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', '把缺转写的语音**本机**识别掉再产卡（本地 whisper，慢、吃 CPU、不出网；配合 --dry-run 就是只补转写、不调模型）')
@@ -6256,12 +6734,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) {
@@ -6281,6 +6760,7 @@ program
         }
     }
     const args = [script, '--days', String(days), '--limit', String(limit),
+        '--source', String(opts.source),
         ...(confirmed ? ['--yes'] : []),
         ...(opts.transcribeVoice ? ['--transcribe-voice'] : []),
         ...(opts.json ? ['--json'] : []),
@@ -7737,14 +8217,13 @@ program
     const limit = parseCliInteger(opts.limit, 'limit', 1, 200, opts.json);
     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);
     }
@@ -7825,14 +8304,13 @@ program
     const limit = parseCliInteger(opts.limit, 'limit', 1, 500, opts.json);
     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);
     }
@@ -7890,6 +8368,86 @@ 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')
+    .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) {
+        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')
@@ -8225,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;
@@ -8262,6 +8826,7 @@ program
                 dataDirMatchesConfig: data.wechatClient.dataDirMatchesConfig,
                 dataDirs: data.wechatClient.dataDirs,
                 unusableVersionDirs: data.wechatClient.unusableVersionDirs,
+                compatibility: data.wechatClient.compatibility,
             },
         }));
         return;
@@ -8319,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();