weflow-cli 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -17,6 +17,48 @@ 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.17.0
+
+- **`sync cursor-probe`：稳定游标从"一句 false"变成一条看得见的路径（D-027）。**
+  `capabilities --json` 新增 `cursorReadiness`（五条判据 × 四个消息后端的代码事实），
+  `sync cursor-probe --json` 实测 NT 数据侧——schema 全量检查、身份有界采样（自带
+  `exhaustive: false`）。本机实测：211 张表 0 缺列、采样 5,398 行全部带非零 server_id 且
+  0 重复；`stableCursor` 仍为 false，差的在哪、下一块是什么，逐条摊开给下游看。
+
+- **`weflow-cli setup`：一条命令装好 Python 环境（自管 venv）。** 在 `~/.weflow-cli/venv`
+  建虚拟环境并安装依赖，之后所有 Python 工作流优先用它——PATH 上只有商店占位 python
+  （exit 9009）的那类 issue 从根上消掉。Windows 上自动用 `sqlcipher3-wheels` 预编译轮
+  （`sqlcipher3-binary` 根本没有 Windows 发行版）；两段式（`--dry-run` 计划 / `--yes` 执行），
+  pip 瞬时网络失败重试一次，装完验证 `import sqlcipher3` 与运行时确实优先 venv。
+
+- **2D 概念图谱：点一条边看它凭什么连着。** 每条边算出两页 `## 来源` 的交集（共同来源卡片），
+  点边高亮并列出；没有共同来源的边如实说明"来自页面正文里的 [[链接]]"。每边最多带 2 个名字
+  （页面体积有界），证据只进页面载荷——布局缓存键不变，旧坐标不作废。3D 不带。
+
+- **助手能看对方发来的图片了（D-128，决策先行）。** 开了 `wechatMediaDownload` 的来信图片
+  从"整条忽略"变成一轮：模型可用 `look_at_image` 的 `#信1` 直接看落盘文件。门与看聊天图片
+  同构（strict 双层拦截、每轮两张上限、审计照记）；超过 4 MB 不缩放直接说明（证据形态）；
+  语音/视频/文件不在本轮。未开下载或没落盘的图片消息行为不变。
+
+- **修了主分支上四处红的回归测试**（`npm test` 在 master 上本来就挂着 4 条，stash 验证过与
+  新特性无关）：`today` / `promises` 曾把 `--talker` 放进子进程 argv（进程列表可见），改走
+  `WEFLOW_TALKER` 环境变量（D-020，`test/privacy-paths` 转绿）；`dailyMailTo` 补齐默认值三处
+  登记（`test/config-keys` 三条转绿）；`scripts/**/*.vbs` 进 npm 包——`run_hidden.vbs` 之前被
+  files allowlist 漏掉（`test/pack-contents` 转绿）。
+
+- **`weflow-cli import qchat`：QQ 聊天进知识库与搜索（qchat-cli 一行不用改，D-129）。**
+  读 `qce export --format json` 的导出（单文件或目录），按全局唯一的 messageId 去重合并、
+  重复导入安全；两段式命令面。落盘后两条管道各开一个显式开关：`chat-notes --source qq|all`
+  产 QQ 知识卡（`QQ-` 前缀，与微信卡同形状、同下游），`search-index --include-imports` 把
+  QQ 会话收进语义与短语索引（id 带 `chat:qq:` 段）。没有微信库的机器也能用（纯 QQ 场景，
+  端到端有测试）。字段映射表见 `docs/DATA_CONTRACT.md`。
+
+- **`replay`：关系网络的时间重放。** `weflow-cli replay` 出按月文本回放（哪些边断了、
+  哪些新长出来、哪些最持久），`--out out.html` 出可播放的单文件动画：按天推进、边用 30 天
+  滚动窗口、节点标签自动避让、播放速度可调；守恒校验内建，稀薄月份显式标注而非假装数据
+  完整；另带静态总结页（断了哪些 / 最持久 / 新出现 + 月度柱状图）。数据全部来自本地库，
+  不联网、不调模型。
+
 ## 1.16.0
 
 - **`leads` - the offers and asks buried in chat, with the sentence that said them.** Scans recent

package/README.md

@@ -107,7 +107,7 @@ Linux 的自动初始化能力取决于微信发行版、Python 依赖和当前
 | --- | --- |
 | 聊天记录 | 查询会话、联系人和消息；导出 **Markdown / JSON / TXT / HTML / Excel**。Markdown 导出把图片**落盘**到 `<会话>_assets/`、正文用相对路径引用（喂给编辑器或别的工具时这才是能用的形态）；**文档本体**（微信里的 Word/Excel/PDF/PPT 等）按原名与扩展名拷进 `<会话>_assets/files/`，正文里按原名链接到 `files/` 下；HTML 导出内嵌图片并给出一份媒体覆盖报告（哪些没嵌上、为什么）。**匹配只做一遍**：Markdown 导出写下清单，之后 JSON/TXT/Excel 导出（或 `--media`）会自动带上同样的图片与文档路径。 |
 | 公众号日报 | 抓取文章、AI 摘要与分类、生成本地阅读页，保留收藏和已读状态。 |
-| 个人知识库 | 同步微信读书笔记、构建 Obsidian Vault、语义搜索、RAG 问答和概念 Wiki，以及**双击就能打开**的概念图谱页面（`weflow-cli wiki graph --open` 出 3D、加 `--flat` 出 2D；自包含、不联网、不需要服务器；`--min-degree N` 只看枢纽、`--line wiki\|chat` 只看一条线）。 |
+| 个人知识库 | 同步微信读书笔记、构建 Obsidian Vault、语义搜索、RAG 问答和概念 Wiki，以及**双击就能打开**的概念图谱页面（`weflow-cli wiki graph --open` 出 3D、加 `--flat` 出 2D；自包含、不联网、不需要服务器；`--min-degree N` 只看枢纽、`--line wiki\|chat` 只看一条线；**2D 页里点一条边能看到它凭什么连着**——两页的共同来源卡片，没有共同来源的边也会如实说来自正文链接）。 |
 | AI 协作 | 通过 MCP 把文章、知识库、日报和受控的本地数据能力交给兼容客户端；工具清单以 `weflow-cli mcp-config` 和 `docs/MCP.md` 为准。 |
 | 个人回顾 | 聊天月报、年度报告、待办提取与朋友圈本地缓存查询。 |
 | 微信收藏 | 读取微信"收藏"内容（公众号文章、文字、图片、视频、聊天记录），支持类型过滤、关键词搜索与 Markdown/JSON 导出。 |
@@ -137,7 +137,15 @@ weflow-cli check
 > - 马上能用：换成 `weflow-cli.cmd check`（`.cmd` 那份包装不走 PowerShell 策略）；
 > - 一次性解决：`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`，然后重开终端。
 
-安装标准 Windows 4.x 工作流所需的 Python 依赖：
+一条命令装好 Python 依赖（推荐）——它会在 `~/.weflow-cli/venv` 建一个本工具**自管**的虚拟环境
+并安装依赖，之后的 Python 工作流会优先用它，不用再管 PATH 上哪个 Python 可用
+（Windows 上自动改用 `sqlcipher3-wheels` 预编译轮，省去装编译器的麻烦）：
+
+```powershell
+weflow-cli setup
+```
+
+也可以手动安装（效果相同；从源码运行时在仓库根目录执行）：
 
 ```powershell
 python -m pip install -r requirements.txt
@@ -278,6 +286,8 @@ weflow-cli panel               # 打开本机面板窗口 (不扫码也能用)
 - 「知识库里怎么讲 RAG 的？」— 概念 Wiki 检索
 - 「帮我回老王那句话」— 起草回复：先判断对方要什么、风险和该不该给实质内容，再给几条候选。
   **只产出文本，不会替你发送**；涉钱或风险很高时不给草稿，只说明该先确认什么
+- 「（对方直接发来一张图片）」— 开了 `wechatMediaDownload` 后图片会落盘，助手能直接看图回答
+  （隐私模式 strict 下不出境，见下段与 D-128）
 - 「记住：我的项目叫 weflow-cli」— 写入长期记忆
 
 运行机制：守护进程通过微信官方 Bot 通道（iLink）长轮询收发消息，Agent 循环、三层记忆（工作窗口 / 滚动摘要 / 长期事实）、数据库查询全部在本机执行；仅最终提问与回复文本会发送给所配置的 LLM，新装默认就是 `assistantPrivacy=strict`：工具输出中的电话/邮箱/链接等 PII 自动脱敏，且第三方聊天正文不出境（`balanced` 放宽到正文可出境、只对 PII 打码，`open` 全不打码；`ollama` 本地引擎则完全不出网）。会话 24 小时未活跃需重新扫码，单窗口内主动回复有官方条数限制。
@@ -303,7 +313,7 @@ weflow-cli config set assistantGroupRequireMention true
 
 | 目标 | 命令 |
 | --- | --- |
-| 检查环境与配置 | `weflow-cli check` · `weflow-cli config show` |
+| 检查环境与配置 | `weflow-cli check` · `weflow-cli setup`（自管 Python venv，一条命令装依赖） · `weflow-cli config show` |
 | 初始化或手动指定路径 | `weflow-cli init [--path <目录>]` |
 | 浏览聊天数据 | `weflow-cli sessions` · `weflow-cli messages <联系人>` · `weflow-cli contacts` |
 | 谁在等我回话 | `weflow-cli awaiting --dry-run` · `weflow-cli awaiting --yes` |
@@ -314,9 +324,11 @@ weflow-cli config set assistantGroupRequireMention true
 | 那年今日 | `weflow-cli today --years 1,3,5`（几年前的今天在聊什么）|
 | 人脉图谱 | `weflow-cli network --groups` · `--with <名字>`（共同群）· `--intro <名字>`（谁能引荐；只读 contact.db）|
 | 某号观点演变 | `weflow-cli timeline --list` · `--source <公众号名>`（按时间看它说法的变化）|
+| 关系网络时间重放 | `weflow-cli replay`（按月展开，生成可播放的单文件 HTML；看哪条边断了，不只是图变大）|
 | 本机判断层 | `weflow-cli decide --request <file> --dry-run` · `--yes` |
 | 导出聊天记录 | `weflow-cli export <联系人> <json\|txt\|html\|excel>` |
-| 同步检查点 | `weflow-cli sync run <联系人> --since <日期>` · `sync status` · `sync verify` |
+| 同步检查点 | `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 fav list` · `weflow-cli fav export markdown` · `weflow-cli fav set-key` |

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) {
@@ -7602,6 +7907,43 @@ program
     }
   })
 
+// ==================== 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')