weflow-cli 1.12.0 → 1.13.0

package/bin/weflow-cli.ts

@@ -11,6 +11,7 @@ import { dbPathService } from '../src/core/dbPathService.js'
 import { keyService } from '../src/core/keyService.js'
 import { NtCore } from '../src/core/ntCore.js'
 import { configService } from '../src/services/configService.js'
+import { renderDiagnosticReport } from '../src/services/diagnosticReport.js'
 import { chatService } from '../src/services/chatService.js'
 import { emptyMessagesNote, looksLikeTalkerId } from '../src/services/messageQuery.js'
 import { exportService } from '../src/services/exportService.js'
@@ -341,7 +342,9 @@ program
         // 只读、纯本地、不调模型。**故意没有 mcp 那一栏**（D-062）：它给的是关于第三方的推断
         // ——谁在被冷落、你会失去谁 —— 所以不进助手、不进 MCP、不喂模型。
         bonds: { cli: 'bonds --json', mcp: null, leavesTheMachine: false },
-        diagnostics: { cli: 'check --json' },
+        // `check --report` 是同一份事实的**给人版**（已脱敏、可直接贴给 AI 或 issue），
+        // 所以它跟 `--json` 并列在这里：外部程序按这条能力去找"怎么拿诊断"，不该只知道 JSON 那条。
+        diagnostics: { cli: 'check --json', report: 'check --report', leavesTheMachine: false },
         todos: { cli: 'todos list --json' },
         // 2026-09-29 三个界面对齐时新开的读取能力（D-058）。逐个写清它会不会出境，
         // 因为其中两个会——`fetch_article` 白名单 + 逐跳复检，`search_public` 没有任何守卫。
@@ -855,6 +858,26 @@ program
       // Step 3: 提取密钥
       console.log(chalk.yellow('\n步骤 3/3: 提取数据库解密密钥...'))
 
+      // **先看 Python 在不在**（Windows）：它决定"读库"这一整步能不能做。
+      // 以前不看，于是 Python 不可用时还要先等 120 秒 hook 超时，然后把用户引向
+      // "退出微信重试"——而真正的原因（商店占位程序 / 缺 sqlcipher3）一个字都没提。
+      // 2026-10-19 用一台"PATH 里没有 python"的机器实测，2 分钟换来一条误导性建议。
+      let pythonUsable = process.platform !== 'win32'
+      if (process.platform === 'win32' && !opts.testMissingKeys) {
+        try {
+          const { execFileSync } = await import('node:child_process')
+          execFileSync(getPythonCommand(), ['--version'], { windowsHide: true, stdio: 'ignore', timeout: 5000 })
+          pythonUsable = true
+        } catch {
+          pythonUsable = false
+          console.log(chalk.red('  ✗ 没有可用的 Python —— 读微信库这一步跑不起来'))
+          console.log(chalk.gray('    NT 数据库扫描与密钥派生都靠它（需要 Python 3.10+ 且能 import sqlcipher3）。'))
+          console.log(chalk.gray('    Windows 上最常见的原因是只装了应用商店的 python 占位程序：'))
+          console.log(chalk.gray('    在终端里运行 `python --version`，能打出版本号才算装对。'))
+          console.log(chalk.gray('    跑 `weflow-cli check --report` 可以看到完整判定（那段话可直接贴给 AI）。'))
+        }
+      }
+
       // 优先尝试从 WeFlow 配置读取
       console.log(chalk.gray('  尝试从 WeFlow 桌面版配置读取...'))
       let extractedKey = opts.testMissingKeys ? '' : tryReadWeFlowKey()
@@ -922,6 +945,22 @@ program
             process.exit(1)
           }
         }
+      } else if (!pythonUsable) {
+        // Python 不可用时**不去等 hook**：就算 hook 抓到了密钥，Step 4 的扫描/派生照样跑不起来，
+        // 而那 120 秒的等待只会把用户引向"退出微信重试"这种无效动作。
+        const fallback = configService.get('favPassphrase') || configService.get('decryptKey') || ''
+        if (fallback) {
+          console.log(chalk.gray('  跳过 hook 等待：已配置的密钥会原样保留，但要先修好 Python 才读得动'))
+          extractedKey = fallback
+        } else {
+          console.log(chalk.red('\n✗ 这台机器现在无法读取微信数据库（缺 Python），因此没有可用密钥'))
+          console.log(chalk.gray('\n按顺序做：'))
+          console.log(chalk.gray('  1) 装一个真正的 Python 3.10+，确认 `python --version` 能打出版本号'))
+          console.log(chalk.gray('  2) `pip install sqlcipher3`'))
+          console.log(chalk.gray('  3) 重新 `weflow-cli init`'))
+          console.log(chalk.gray('  卡住时跑 `weflow-cli check --report`，那段文字可直接贴给 AI 或贴到 issue'))
+          process.exit(1)
+        }
       } else if (process.platform !== 'win32') {
         // macOS：自动提取不可用，引导手动提供密钥
         console.log(chalk.yellow('  ⚠ 当前平台无法自动提取密钥（自动提取支持 Windows/Linux）'))
@@ -932,17 +971,23 @@ program
         console.log(chalk.gray('  4. 数据目录与账号已完成配置，设置密钥后即可使用 sessions/messages 等命令'))
         process.exit(1)
       } else {
-        // 如果微信未运行，提示启动
-        if (!version) {
-          console.log(chalk.cyan('\n  ══════════════════════════════════════'))
-          console.log(chalk.cyan('  请现在启动微信 4.x 并登录！'))
-          console.log(chalk.cyan('  ══════════════════════════════════════\n'))
+        // hook 只在**登录那一瞬**触发。所以要不要等，取决于微信现在在不在跑：
+        //   · 已在运行  → 用户早就登录了，hook 永远不会再触发，等满 2 分钟纯属浪费
+        //                 （2026-10-19 用一个空配置实测：每次 init 都白等）
+        //   · 没在运行  → 这正是 README「三分钟上手」第 2 步要求的姿势（关掉微信再 init，
+        //                 然后按提示启动并登录）。人要打开客户端、等它起来、扫码/点确认，
+        //                 30 秒根本不够，**必须留足**，否则按文档操作的人会被那句
+        //                 "hook 没抓到" 误导。所以就按文档给满 120 秒。
+        let keyResult: { success: boolean; key?: string; error?: string } = { success: false }
+        if (version) {
+          console.log(chalk.gray('  微信已在运行：hook 只在登录那一瞬触发，不再等待，直接尝试扫描/派生'))
+        } else {
+          console.log(chalk.cyan('\n  请现在启动微信并登录（登录那一瞬会自动抓取密钥）'))
+          console.log(chalk.cyan('  最多等 2 分钟；不启动也没关系，之后会继续尝试 NT 扫描 / passphrase 派生\n'))
+          keyResult = await keyService.waitForKey(120000, (msg) => {
+            console.log(chalk.gray(`  ${msg}`))
+          })
         }
-        console.log(chalk.gray('  等待微信进程出现（启动后会自动 hook）...'))
-
-        const keyResult = await keyService.waitForKey(120000, (msg) => {
-          console.log(chalk.gray(`  ${msg}`))
-        })
 
         if (keyResult.success && keyResult.key) {
           extractedKey = keyResult.key
@@ -959,12 +1004,13 @@ program
             console.log(chalk.gray('  检测到已配置的密钥, 沿用它并重新验证各库...'))
             extractedKey = fallback
           } else {
-            console.log(chalk.red(`\n✗ 密钥提取失败: ${keyResult.error}`))
-            console.log(chalk.gray('\n解决方案:'))
-            console.log(chalk.gray('  1. 退出微信后重新运行 init (hook 需在微信登录瞬间触发, init 会自动等待)'))
-            console.log(chalk.gray('  2. 或用第三方工具提取全库 passphrase 后: weflow-cli fav set-key --passphrase <64位hex>, 再重新 init 自动派生'))
-            console.log(chalk.gray('  3. 或手动指定密钥: weflow-cli config set decryptKey <64位密钥>'))
-            process.exit(1)
+            // **不退出**：hook 只在"登录那一瞬"触发，而一个正常用户装完工具时微信早就登录了，
+            // 于是这条 120 秒的等待**必然**超时。以前这里 process.exit(1)，用户就被卡在
+            // 「退出微信后重新运行 init」——而下一步（Step 4 的 NT 扫描 / 从 passphrase 派生）
+            // 才是新版本真正能拿到密钥的地方，却永远不会被执行（2026-10-19 用空配置实测）。
+            // 现在改成继续往下走：拿得到就成功，拿不到由结尾统一判"未完成"。
+            console.log(chalk.yellow('\n  Hook 没抓到密钥（它只在登录那一瞬触发，已登录时不会再有）'))
+            console.log(chalk.gray('  继续尝试 NT 扫描 / passphrase 派生 —— 这是新版本主要的取密钥方式...'))
           }
         }
       }
@@ -972,9 +1018,13 @@ program
       if (extractedKey) {
         configService.set('decryptKey', extractedKey)
         if (keyCaptured) console.log(chalk.green('\n✓ 密钥获取成功!'))
-        else console.log(chalk.green('\n✓ 已沿用配置中的密钥 (本次未重新捕获)'))
+        else if (pythonUsable) console.log(chalk.green('\n✓ 已沿用配置中的密钥 (本次未重新捕获)'))
+        // 缺 Python 时**不能说"已沿用"**：那句话在这里会被读成"密钥没问题"，
+        // 而下面紧接着就会说"密钥未就绪"，两句自相矛盾（2026-10-19 实跑看到）。
+        else console.log(chalk.yellow('\n· 配置里的密钥原样保留，但**这次验证不了**（缺 Python）——它可能仍然可用'))
       } else {
-        console.log(chalk.green('\n✓ NT 密钥配置完成!'))
+        // 空密钥时不能说"配置完成"：下一句就是"密钥未就绪"，两句打架。
+        console.log(chalk.yellow('\n· 本次没有拿到密钥，继续尝试 NT 扫描 / passphrase 派生'))
       }
 
       // Step 4: 尝试扫描 NT 格式数据库 (xwechat_files)
@@ -982,6 +1032,11 @@ program
       // 进入这里已经确认是 4.x 初始化流程。不要依赖步骤 0 的 version：
       // 微信可能是在 init 等待期间才启动，初始 version 会保持为 null。
       // Linux 分支已在步骤 3 完成配置，跳过。
+      // 这次 init 到底有没有**取得可用的密钥** —— 只有它决定结尾能不能说"初始化完成"。
+      // 扫描失败 + 沿用旧密钥 = 一次看着成功、实际什么也读不到的初始化：2026-10-18 一位用户
+      // 的 init 打在 "NT scan failed (exit 9009)" 上（Python 是商店占位程序），结尾照样报
+      // "初始化完成！"、"密钥: 已安全保存"，然后 sessions 一条都没有。
+      let ntReady = process.platform === 'linux'   // Linux 分支已在步骤 3 配好
       if (process.platform !== 'linux') {
         console.log(chalk.yellow('\n步骤 4/4: 扫描 NT 格式数据库...'))
         console.log(chalk.gray('  正在从微信内存中匹配数据库密钥...'))
@@ -999,6 +1054,7 @@ program
           }
 
           if (primaryDb) {
+            ntReady = true
             configService.set('ntDbPath', primaryDb.path)
             configService.set('ntKey', primaryDb.key)
             configService.set('ntSalt', primaryDb.salt)
@@ -1048,6 +1104,7 @@ program
           }
 
           if (derivedMessage) {
+            ntReady = true
             console.log(chalk.green('  ✓ 派生模式初始化成功 (聊天/联系人/朋友圈库已配置)'))
           } else {
             // 即使密钥未匹配，仍尝试自动发现 sns.db 路径和盐值
@@ -1066,23 +1123,40 @@ program
       }
 
       console.log(chalk.cyan('\n=============================='))
-      console.log(chalk.cyan('初始化完成! (4.x 模式)'))
+      // 只有**这次真的拿到可用密钥**才叫"完成"。否则说清楚"没就绪"以及下一步做什么 ——
+      // 报"完成"再让 sessions 空着，是最费用户时间的失败方式（他会以为是自己微信的问题）。
+      console.log(chalk[ntReady ? 'cyan' : 'yellow'](
+        ntReady ? '初始化完成! (4.x 模式)' : '初始化未完成：数据库密钥没有就绪'))
       console.log(chalk.cyan('=============================='))
       console.log(chalk.white(`数据目录: ${detected.path}`))
       console.log(chalk.white(`账号: ${selectedWxid.wxid}${selectedWxid.nickname ? ` (${selectedWxid.nickname})` : ''}`))
-      const displayKey = extractedKey || linuxNtKey
-      console.log(chalk.white('密钥: 已安全保存'))
+      console.log(chalk.white(`密钥: ${ntReady ? '已安全保存' : '未就绪（配置里的旧密钥未必能解开这个库）'}`))
       const ntDbPath = configService.get('ntDbPath')
       if (ntDbPath) {
         console.log(chalk.white(`NT 数据库: ${ntDbPath}`))
       }
+      if (!ntReady) {
+        console.log(chalk.yellow('\n现在 sessions / messages 会读不到数据。按顺序做这三步：'))
+        console.log(chalk.yellow('  1) 在这个终端里运行 `python --version`，要能打出版本号'))
+        console.log(chalk.yellow('     （Windows 上最常见的问题是只装了商店的 python 占位程序）'))
+        console.log(chalk.yellow('  2) `pip install sqlcipher3`'))
+        console.log(chalk.yellow('  3) `weflow-cli config forget-keys`，然后重新 `weflow-cli init`'))
+        // 这三步是"最常见的原因"，不是诊断结论。真卡住时让用户拿到一份**已经判定过**的事实，
+        // 而不是再让他把现象口头描述一遍（那正是 issue #3/#9/#10 每次都要重来一遍的原因）。
+        console.log(chalk.yellow('\n想先看清到底卡在哪一步，运行：'))
+        console.log(chalk.cyan('  weflow-cli check --report'))
+        console.log(chalk.gray('  它会给出结论（Python / sqlcipher3 / 密钥 / 数据目录），那段文字可以直接复制给 AI 或贴到 issue。'))
+      }
+
+      // 未就绪时说"现在可以使用"是骗人的：那几条命令都会返回空。
+      console.log(chalk.gray(ntReady
+        ? '\n现在可以使用以下命令:'
+        : '\n修好上面那几步之后，这些命令才会返回数据:'))
+      console.log(chalk.gray('  weflow-cli sessions        查看会话列表'))
+      console.log(chalk.gray('  weflow-cli messages <talker> 查看消息'))
+      console.log(chalk.gray('  weflow-cli contacts        查看联系人'))
+      console.log(chalk.gray('  weflow-cli export <talker> <format> 导出聊天记录'))
     }
-
-    console.log(chalk.gray('\n现在可以使用以下命令:'))
-    console.log(chalk.gray('  weflow-cli sessions        查看会话列表'))
-    console.log(chalk.gray('  weflow-cli messages <talker> 查看消息'))
-    console.log(chalk.gray('  weflow-cli contacts        查看联系人'))
-    console.log(chalk.gray('  weflow-cli export <talker> <format> 导出聊天记录'))
   })
 
 // ==================== config ====================
@@ -1095,6 +1169,7 @@ const configurableKeys = [
   'ntDbPath', 'ntKey', 'ntSalt', 'contactDbPath', 'contactKey', 'contactSalt',
   'vaultRepo', 'aiEngine', 'aiBaseUrl', 'aiModel', 'deepseekApiKey', 'typesafeApiKey',
   'dashscopeApiKey', 'favPassphrase',
+  'judgeProvider', 'openrouterApiKey', 'openrouterJudgeModel',
   'wereadApiKey',
   'assistantPrivacy', 'assistantWhitelist', 'assistantGroupWhitelist',
   'assistantGroupRequireMention', 'assistantFastRoute', 'assistantPanelUser', 'quickReplyContacts',
@@ -1344,6 +1419,12 @@ program
     if (sessions.length === 0) {
       if (opts.json) { console.log(JSON.stringify({ success: true, sessions: [] })); return }
       console.log(chalk.gray('未找到会话'))
+      // "0 条"有两种完全不同的原因：真的没有会话，和**初始化/密钥坏了读不出来**。
+      // 后者以前只显示这一句，用户就去猜"是不是我微信坏了 / 版本太新"（issue #3/#9/#10 的老路：
+      // 同一个根因被描述成三种现象）。给一条能立刻分清的动作，比让他猜有用。
+      console.log(chalk.yellow('\n如果微信里明明有聊天记录，那多半是读取这一步没成功。运行这条看结论：'))
+      console.log(chalk.cyan('  weflow-cli check --report'))
+      console.log(chalk.gray('  它会指出卡在哪一步（Python / sqlcipher3 / 密钥 / 数据目录），那段文字可直接复制给 AI 或贴到 issue。'))
       return
     }
 
@@ -5001,11 +5082,12 @@ program
     .option('--no-rerank', '不调用决策模型重排，只按向量/关键词相似度返回（回退到引入重排之前）')
     .option('--no-hybrid', '不融合本地 BM25 名次（默认融合；门控后实测只增不减）')
     .option('--rerank-pool <n>', '重排看多少条候选（默认 100；越大越准也越贵）')
-    .option('--no-dedup', '不折叠同文本的多号转载（默认折叠，结果里带 duplicateCount）')
-    .option('--with-text [n]', '给每条命中挂上本地正文（fullText / sourceFile / url）；n 为每条最多多少字')
-    .option('--fetch-missing [n]', '正文太薄时按 url 抓一次（最多 n 条，默认 3；复用日报缓存）')
-    .option('--mmr', '对结果做 MMR 去冗余（压掉近似的同领域邻居，可能牺牲单点召回）')
+    .option('--no-dedup', '不折叠同文本的多号转载（默认折叠，结果里带 duplicateCount）')
+    .option('--with-text [n]', '给每条命中挂上本地正文（fullText / sourceFile / url）；n 为每条最多多少字')
+    .option('--fetch-missing [n]', '正文太薄时按 url 抓一次（最多 n 条，默认 3；复用日报缓存）')
+    .option('--mmr', '对结果做 MMR 去冗余（压掉近似的同领域邻居，可能牺牲单点召回）')
     .option('--from <account>', '只查这个公众号的文章（按文件名匹配，不走语义）')
+    .option('--phrase', '把这串当**原样短语**在本地定位（FTS5/trigram，不走向量、不出境、不花钱）：回答"哪个号在哪天原样写过它"')
     .option('--api-key <key>', 'DashScope embedding API key')
     .option('--dry-run', '仅预览，不读取索引或调用向量服务')
     .option('--yes', '确认执行可能调用云端向量服务的搜索')
@@ -5017,34 +5099,59 @@ program
     const pkgRoot = resolvePackageRoot()
       const script = join(pkgRoot, 'scripts', 'semantic_search.py')
       const topK = parseCliInteger(opts.topK, 'top-k', 1, 100, opts.json)
-      // 没传就**不转发**（默认值只在 Python 侧定义一处）：commander 对未提供的选项给 undefined，
-      // 直接 parseCliInteger 会被自己的校验判成非法参数 —— 实测就是这么红的。
-      const rerankPool = opts.rerankPool
+      // 没传就**不转发**（默认值只在 Python 侧定义一处）：commander 对未提供的选项给 undefined，
+      // 直接 parseCliInteger 会被自己的校验判成非法参数 —— 实测就是这么红的。
+      const rerankPool = opts.rerankPool
         ? parseCliInteger(opts.rerankPool, 'rerank-pool', 5, 500, opts.json) : null
       requireCliChoice(opts.line, ['wiki', 'chat', 'all'], 'line', opts.json)
+      // `--phrase` 走的是**纯本地**那条路（FTS5）：不出境、不花钱，所以它既不需要向量 key，
+      // 也不需要确认门。把它当成"向量搜索的降级"会让人以为它也花钱、也发数据。
+      const phrase = opts.phrase === true
+      // 下面这些旗标只属于**向量检索**那条路；`--phrase`（FTS5 原样定位）一个都用不上。
+      // 以前它们会被原样转发，然后在 Python 的 phrase 分支里被**静默忽略** —— 用户以为自己在调参，
+      // 实际上什么都没发生。这类"接受但不生效"的开关比报错更贵：它会让人把默认行为当成调过的结果。
+      if (phrase) {
+        const irrelevant: string[] = []
+        if (opts.rerank === false) irrelevant.push('--no-rerank')
+        if (opts.hybrid === false) irrelevant.push('--no-hybrid')
+        if (rerankPool != null) irrelevant.push('--rerank-pool')
+        if (opts.dedup === false) irrelevant.push('--no-dedup')
+        if (opts.withText) irrelevant.push('--with-text')
+        if (opts.fetchMissing) irrelevant.push('--fetch-missing')
+        if (opts.mmr) irrelevant.push('--mmr')
+        if (irrelevant.length) {
+          const error = `--phrase 只做原样定位，不接受 ${irrelevant.join('、')}（它们只对向量检索有意义）`
+          if (opts.json) console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error }))
+          else console.log(chalk.red(error))
+          process.exit(1)
+        }
+      }
       const preview = {
         success: true,
         dryRun: true,
         action: 'semantic-search.query',
+        phrase,
         topK,
         line: opts.line,
         noRerank: opts.rerank === false,
         noHybrid: opts.hybrid === false,
         rerankPool,
-        noDedup: opts.dedup === false,
-        withText: opts.withText || null,
-        fetchMissing: opts.fetchMissing || null,
-        mmr: opts.mmr === true,
+        noDedup: opts.dedup === false,
+        withText: opts.withText || null,
+        fetchMissing: opts.fetchMissing || null,
+        mmr: opts.mmr === true,
         from: opts.from || null,
         readsLocalIndex: true,
-        mayUseCloudEmbedding: true,
+        mayUseCloudEmbedding: !phrase,
       }
       if (opts.dryRun) {
         if (opts.json) console.log(JSON.stringify(preview))
-        else console.log(chalk.cyan('预览：将读取本地语义索引，并可能把查询发送到已配置的向量服务。'))
+        else console.log(chalk.cyan(phrase
+          ? '预览：原样短语定位 —— 只读本地短语索引，不联网、不花钱。'
+          : '预览：将读取本地语义索引，并可能把查询发送到已配置的向量服务。'))
         return
       }
-      if (!opts.yes) {
+      if (!phrase && !opts.yes) {
         if (opts.json) {
           console.log(JSON.stringify({ ...preview, success: false, dryRun: false, code: 'CONFIRMATION_REQUIRED' }))
           process.exit(1)
@@ -5064,15 +5171,16 @@ program
       // 接这条通道之前，`OPERATIONS.md` 一直在教用户敲 `search --no-rerank`，而 CLI 会答 `unknown option`
       // —— 同一份文档里 `--line` 是通的，所以它看起来像"能用的旗标"（2026-10-11 由文档命令面那道检查发现）。
       const args: string[] = [script, 'search', '--top-k', String(topK), '--line', opts.line,
+        ...(phrase ? ['--phrase'] : []),
         ...(opts.rerank === false ? ['--no-rerank'] : []),
         ...(opts.hybrid === false ? ['--no-hybrid'] : []),
         ...(opts.from ? ['--from', opts.from] : []),
-        ...(rerankPool ? ['--rerank-pool', String(rerankPool)] : []),
-        ...(opts.dedup === false ? ['--no-dedup'] : []),
-        ...(opts.withText ? ['--with-text', opts.withText === true ? '4000' : String(opts.withText)] : []),
-        ...(opts.fetchMissing ? ['--fetch-missing',
-          opts.fetchMissing === true ? '3' : String(opts.fetchMissing)] : []),
-        ...(opts.mmr ? ['--mmr'] : [])]
+        ...(rerankPool ? ['--rerank-pool', String(rerankPool)] : []),
+        ...(opts.dedup === false ? ['--no-dedup'] : []),
+        ...(opts.withText ? ['--with-text', opts.withText === true ? '4000' : String(opts.withText)] : []),
+        ...(opts.fetchMissing ? ['--fetch-missing',
+          opts.fetchMissing === true ? '3' : String(opts.fetchMissing)] : []),
+        ...(opts.mmr ? ['--mmr'] : [])]
       try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
           timeout: 60_000, maxBuffer: 10 * 1024 * 1024,
@@ -5092,6 +5200,7 @@ program
     .command('search-index')
     .description('构建语义搜索索引')
     .option('--full', '全量重建')
+    .option('--phrase', '只建**精确短语索引**（本地 FTS5/trigram，不调用向量服务、不花钱、不出境）')
     .option('--api-key <key>', 'DashScope embedding API key')
     .option('--days <n>', '聊天记录收最近多少天（默认 90）')
     .option('--article-days <n>', '日报文章收最近多少个日期目录（默认 30）')
@@ -5099,6 +5208,35 @@ program
     .option('--yes', '确认构建或重建索引')
     .option('--json', '输出 JSON 格式')
     .action(async (opts) => {
+      // `--phrase`：短语索引那条路完全不碰向量服务（也不碰聊天库——它从语义索引的 meta.json
+      // 派生），所以它不走窗口参数、不需要确认门，也不校验 key。混进下面那条路会让用户以为
+      // "建个本地的检索也要花 vector 的钱"。
+      if (opts.phrase) {
+        const phrasePreview = {
+          success: true, dryRun: true, action: 'search-index.build-phrase',
+          readsLocalData: true, usesCloudEmbedding: false, rebuildsPhraseIndex: true,
+        }
+        if (opts.dryRun) {
+          if (opts.json) console.log(JSON.stringify(phrasePreview))
+          else console.log(chalk.cyan('短语索引预览：全量重建本地 FTS5 索引（含两条线），不联网、不花钱。'))
+          return
+        }
+        const { execFile } = await import('child_process')
+        const { promisify } = await import('util')
+        const execFileAsync = promisify(execFile)
+        const pkgRoot = resolvePackageRoot()
+        const script = join(pkgRoot, 'scripts', 'semantic_search.py')
+        try {
+          const { stdout } = await execFileAsync(getPythonCommand(),
+            [script, 'phrase-build', '--line', 'all'],
+            { timeout: 600_000, maxBuffer: 10 * 1024 * 1024, env: pythonProcessEnv() })
+          console.log(opts.json ? stdout.trim() : stdout)
+        } catch (e: any) {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(e, '建短语索引失败')}`))
+          process.exit(1)
+        }
+        return
+      }
       // 窗口的**运行值由这里说了算**：默认值 + 校验 + 透传都在这一处，预览报的就是真跑的那些
       // （脚本文档里另有自己的默认值，只供手动直接跑脚本时用；CLI 这条路永远显式传参，
       // 所以两边万一漂了也不会影响实际行为）。
@@ -6212,12 +6350,14 @@ program
   .option('--source <name>', '仅处理指定公众号，可重复或用逗号分隔', (value, previous: string[] = []) => [...previous, value], [])
   .description('一键生成公众号日报（抓取 + AI 摘要 + HTML 阅读器 + 行动建议）')
   .option('-d, --date <YYYY-MM-DD>', '日期')
+  .option('--yesterday', '跑昨天（等价于 --date 昨天）。公众号发到 24:00 才停，所以当晚跑的那一天永远不全；"跑昨天"与时刻无关，计划任务用这个')
   .option('--api-key <key>', 'DeepSeek API key（或设环境变量 DEEPSEEK_API_KEY）')
   .option('--skip-classify', '跳过后处理')
   .option('--dry-run', '仅预览文章，不调用 AI 或写入日报')
   .option('--yes', '确认执行日报生成；JSON 模式需要此选项')
   .option('--no-ai', '关闭本次日报的所有 AI 处理')
   .option('--no-summary', '只判断不生成：不调 LLM 写摘要/标签/简报（主题与相关度仍由 Jev 判断），无需 DeepSeek key')
+  .option('--prefetch-bodies [n]', '抓取之前先并发把当天正文抓进缓存（n=并发数，默认 8）：抓取阶段于是全部命中缓存、不再逐篇 sleep 8-12 秒（450 篇约 75 分钟 → 秒级）。对上游的请求次数不变，只是压进更短的时间窗')
   .option('--json', '输出机器可读的最终结果；运行日志写入 stderr')
   .action(async (opts) => {
     const { spawn } = await import('child_process')
@@ -6228,7 +6368,16 @@ program
 
     const now = new Date()
     const localDate = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
-    const date = opts.date || localDate
+    const isoDate = (when: Date) => `${when.getFullYear()}-${String(when.getMonth() + 1).padStart(2, '0')}-${String(when.getDate()).padStart(2, '0')}`
+    if (opts.date && opts.yesterday) {
+      const error = '--date 与 --yesterday 不能同时给（前者是明确的一天，后者是"昨天"）'
+      if (opts.json) console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', field: 'date', error }))
+      else console.log(chalk.red(error))
+      process.exit(1)
+    }
+    const date = opts.date || (opts.yesterday
+      ? isoDate(new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1))
+      : localDate)
     const apiKey = opts.apiKey || process.env.DEEPSEEK_API_KEY || ''
     const noAi = opts.ai === false || configService.get('dailyAiEnabled') === 'false'
     const dailyLog = (...values: any[]) => opts.json ? console.error(...values) : console.log(...values)
@@ -6254,6 +6403,14 @@ program
       if (opts.noSummary && !noAi) args.push('--no-summary')
       for (const source of opts.source || []) args.push('--source', source)
       if (opts.skipClassify) args.push('--skip-classify')
+      // 只在**给了**这个旗标时才解析数字：`--prefetch-bodies`（不带数字）是合法的，
+      // 而默认并发数只在 python 侧写一份（这里再写一份迟早漂移）。
+      if (opts.prefetchBodies !== undefined) {
+        args.push('--prefetch-bodies')
+        if (opts.prefetchBodies !== true) {
+          args.push(String(parseCliInteger(opts.prefetchBodies, 'prefetch-bodies', 1, 64, !!opts.json)))
+        }
+      }
 
       dailyLog(chalk.cyan(`\n📰 正在生成 ${targetDate} 公众号日报${noAi ? '（AI 已关闭）' : ''}...\n`))
       const child = spawn(getPythonCommand(), args, {
@@ -7433,6 +7590,7 @@ program
   .command('check')
   .description('检查运行环境（Python、pip 依赖、数据库配置）')
   .option('--json', '输出 JSON 格式，不包含数据库路径或密钥')
+  .option('--report', '输出一段可直接粘贴给 AI / 贴进 issue 的诊断结论（已脱敏：用户名与 wxid 换占位符，不含密钥与聊天内容）')
   .action(async (opts) => {
     // 微信客户端的**版本**与它自报的**数据目录**：两个分支都要用，所以在这里算一次。
     // 判据见 `wechatClient.ts`（版本取活进程的 `--user-lib-dir`；取不到就是"未知"，不是"没问题"）。
@@ -7456,7 +7614,9 @@ program
     const dataDirMatchesConfig = (client.dataDirs.length && configuredRoot)
       ? client.dataDirs.some(dir => samePath(dir, configuredRoot))
       : null
-    if (opts.json) {
+    // `--json`（给机器）与 `--report`（给人/AI）用的是**同一份事实**，所以只探测一次：
+    // 两个分支各写一份探测，迟早会出现"JSON 说 Python 可用、报告说不可用"这种自相矛盾。
+    const collectCheckData = async () => {
       const { execFileSync } = await import('child_process')
       const requiredDependencies = ['sqlcipher3', 'html2text', 'zstandard', 'cryptography']
       const optionalDependencies = ['scrapling']
@@ -7530,9 +7690,48 @@ program
           caveats: client.caveats,
         },
       }
-      console.log(JSON.stringify(data, null, 2))
+      return data
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(await collectCheckData(), null, 2))
+      return
+    }
+
+    // `--report`：一段**可整段复制**的诊断块（脱敏后）。这是"用户说不清、我们又猜不准"
+    // 那个循环的出口 —— issue #3/#9/#10 与 2026-10-18 那封邮件都是同一个根因被描述成四种现象。
+    if (opts.report) {
+      const data = await collectCheckData()
+      console.log(renderDiagnosticReport({
+        cliVersion: CLI_VERSION,
+        // 本地时间：用户对照日志/截图时要能直接对上，UTC 会多一步换算
+        generatedAt: new Date().toLocaleString('zh-CN', { hour12: false }),
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.versions.node,
+        python: {
+          command: getPythonCommand(),
+          available: !!data.runtime.python.available,
+          version: String(data.runtime.python.version || ''),
+        },
+        dependencies: data.dependencies,
+        configuration: data.configuration,
+        keys: {
+          messageKeyConfigured: !!configService.get('ntKey') || !!configService.get('decryptKey'),
+          passphraseConfigured: !!configService.get('favPassphrase'),
+        },
+        wechatClient: {
+          running: data.wechatClient.running,
+          version: data.wechatClient.version,
+          note: data.wechatClient.note,
+          dataDirMatchesConfig: data.wechatClient.dataDirMatchesConfig,
+          dataDirs: data.wechatClient.dataDirs,
+          unusableVersionDirs: data.wechatClient.unusableVersionDirs,
+        },
+      }))
       return
     }
+
     console.log(chalk.cyan('🔍 WeFlow CLI 环境检查\n'))
 
     // 1. Node.js
@@ -7607,6 +7806,16 @@ program
         const stat = (await import('fs')).statSync(path)
         const mb = (stat.size / 1024 / 1024).toFixed(0)
         console.log(chalk.white(`  ${label}: ${path} (${mb}MB)`))
+        // 微信"存储位置"设到别的盘时，用户目录下那个是**junction**：显示的是 C 盘路径，
+        // 数据其实在 D 盘。不点出来的话，用户会以为配置指错了地方（2026-10-19 实测：
+        // `C:\Users\…\xwechat_files` → `D:\微信\xwechat_files`）。
+        try {
+          const { realpathSync } = await import('fs')
+          const real = realpathSync(path)
+          if (real.toLowerCase() !== path.toLowerCase()) {
+            console.log(chalk.gray(`    ↳ 软链指向 ${real}`))
+          }
+        } catch { /* 解析不了就不说，别拿它当错误 */ }
       } else {
         const hint = keyRequired ? ' (可选, init 或 sns/fav 命令配置)' : ''
         console.log(chalk.gray(`  ${label}: 未配置${hint}`))