weflow-cli 1.15.1 → 1.17.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'
@@ -312,7 +315,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 +701,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 +2058,53 @@ 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('')
+  })
+
 // ==================== contacts ====================
 // contact-schema：读 contact.db 里**群**的 ext_buffer（本地只读：不联网、不调模型）
 //
@@ -5204,6 +5503,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 +5552,7 @@ program
         mode: opts.full ? 'full' : 'incremental',
         chatDays,
         articleDays,
+        includeImports: !!opts.includeImports,
         readsLocalData: true,
         usesCloudEmbedding: true,
         replacesExistingIndex: !!opts.full,
@@ -5289,6 +5590,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 +6275,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 +6289,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 +6315,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 +7760,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 +7844,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) {
@@ -7561,6 +7866,84 @@ program
     }
   })
 
+// ==================== leads（线索雷达）====================
+program
+  .command('leads')
+  .description('线索雷达：聊天里的报价/采购/合作/需求信号，带原话与跟进状态（规则判定，不调模型）')
+  .option('--days <number>', '看最近多少天', '30')
+  .option('--min-score <number>', '最低分，4 分以上更接近真实生意', '2')
+  .option('--limit <number>', '最多列几条', '20')
+  .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', 'leads.py')
+    const days = parseCliInteger(opts.days, 'days', 1, 3650, opts.json)
+    const minScore = parseCliInteger(opts.minScore, 'min-score', 1, 50, opts.json)
+    const limit = parseCliInteger(opts.limit, 'limit', 1, 500, opts.json)
+
+    try {
+      const args = [script, '--days', String(days), '--min-score', String(minScore),
+                    '--limit', String(limit)]
+      if (opts.json) args.push('--json')
+      const { stdout } = await execFileAsync(getPythonCommand(), args, {
+        timeout: 300_000,
+        maxBuffer: 10 * 1024 * 1024,
+        env: pythonProcessEnv(),
+      })
+      console.log(stdout)
+    } catch (e: any) {
+      if (opts.json) {
+        console.log(JSON.stringify({
+          success: false,
+          code: 'LEADS_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')