weflow-cli 1.11.1 → 1.13.0

package/dist/bin/weflow-cli.js

@@ -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';
@@ -324,7 +325,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` 没有任何守卫。
@@ -829,6 +832,26 @@ program
         configService.set('wxid', selectedWxid.wxid);
         // 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();
@@ -898,6 +921,24 @@ program
                 }
             }
         }
+        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）'));
@@ -909,16 +950,24 @@ program
             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: 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;
                 keyCaptured = true;
@@ -936,12 +985,13 @@ program
                     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 派生 —— 这是新版本主要的取密钥方式...'));
                 }
             }
         }
@@ -949,17 +999,27 @@ program
             configService.set('decryptKey', extractedKey);
             if (keyCaptured)
                 console.log(chalk.green('\n✓ 密钥获取成功!'));
-            else
+            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)
         // 即使检测到传统路径，也可能存在 NT 格式数据库
         // 进入这里已经确认是 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('  正在从微信内存中匹配数据库密钥...'));
@@ -974,6 +1034,7 @@ program
                     primaryDb = ntResult.matched.sort((a, b) => b.size - a.size)[0];
                 }
                 if (primaryDb) {
+                    ntReady = true;
                     configService.set('ntDbPath', primaryDb.path);
                     configService.set('ntKey', primaryDb.key);
                     configService.set('ntSalt', primaryDb.salt);
@@ -1019,6 +1080,7 @@ program
                     derivedMessage = await applyDerivedNtKeys(passphrase, deriveDbs, (l) => console.log(l));
                 }
                 if (derivedMessage) {
+                    ntReady = true;
                     console.log(chalk.green('  ✓ 派生模式初始化成功 (聊天/联系人/朋友圈库已配置)'));
                 }
                 else {
@@ -1037,22 +1099,38 @@ 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 ====================
 const configCmd = program
@@ -1063,6 +1141,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',
@@ -1326,6 +1405,12 @@ program
             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;
     }
     if (opts.json) {
@@ -1902,8 +1987,12 @@ program
     }
     // 图片要靠 Python 那条路匹配（缓存缩略图、资源 md5、原图那档）。`--media` 就是"先抽一次"，
     // 抽完 json/txt/excel 各自消费同一份清单 —— 匹配只跑一遍，也不会在 TS 里重写一遍。
+    // 抽取那一步的媒体摘要留在这里：`--media` 的调用者（机器调用）应当能从结果里直接读到
+    // "各状态多少条、报告叫什么"，而不必去翻 Python 的 stdout。
+    let extracted;
     if (opts.media && (format === 'json' || format === 'txt' || format === 'excel')) {
         const media = await exportService.extractMedia(talker, opts.output, !!opts.json, { fullImages: opts.fullImages === true }, limit, opts.date || '');
+        extracted = media;
         if (!media.success) {
             if (opts.json)
                 console.log(JSON.stringify({ success: false, code: 'MEDIA_EXPORT_FAILED', error: media.error || '媒体抽取失败' }));
@@ -1940,7 +2029,16 @@ program
     }
     if (result?.success) {
         if (opts.json)
-            console.log(JSON.stringify({ success: true, format, contract: format === 'json' ? opts.contract : null, path: result.path, count: result.count ?? null }, null, 2));
+            console.log(JSON.stringify({
+                success: true,
+                format,
+                contract: format === 'json' ? opts.contract : null,
+                path: result.path,
+                count: result.count ?? null,
+                // 媒体摘要：html/md 那条由导出自己产出（Python 的 media_json_summary），
+                // json/txt/excel 的 `--media` 则由上面那次抽取产出 —— 两条都是同一份词汇。
+                media: result.media ?? extracted?.media ?? null,
+            }, null, 2));
         else
             console.log(chalk.green(`✓ 导出成功: ${result.path}`));
     }
@@ -5200,6 +5298,14 @@ program
     .option('--top-k <n>', '返回数量', '10')
     .option('--line <line>', 'wiki=文章线(默认) / chat=聊天记录 / all=两条都搜', 'wiki')
     .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('--from <account>', '只查这个公众号的文章（按文件名匹配，不走语义）')
+    .option('--phrase', '把这串当**原样短语**在本地定位（FTS5/trigram，不走向量、不出境、不花钱）：回答"哪个号在哪天原样写过它"')
     .option('--api-key <key>', 'DashScope embedding API key')
     .option('--dry-run', '仅预览，不读取索引或调用向量服务')
     .option('--yes', '确认执行可能调用云端向量服务的搜索')
@@ -5211,25 +5317,70 @@ 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
+        ? 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 = [];
+        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,
+        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('预览：将读取本地语义索引，并可能把查询发送到已配置的向量服务。'));
+            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);
@@ -5249,7 +5400,16 @@ program
     // 接这条通道之前，`OPERATIONS.md` 一直在教用户敲 `search --no-rerank`，而 CLI 会答 `unknown option`
     // —— 同一份文档里 `--line` 是通的，所以它看起来像"能用的旗标"（2026-10-11 由文档命令面那道检查发现）。
     const args = [script, 'search', '--top-k', String(topK), '--line', opts.line,
-        ...(opts.rerank === false ? ['--no-rerank'] : [])];
+        ...(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'] : [])];
     try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
             timeout: 60_000, maxBuffer: 10 * 1024 * 1024,
@@ -5269,6 +5429,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）')
@@ -5276,6 +5437,36 @@ 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) {
+            console.error(chalk.red(`\n✗ ${safeSubprocessError(e, '建短语索引失败')}`));
+            process.exit(1);
+        }
+        return;
+    }
     // 窗口的**运行值由这里说了算**：默认值 + 校验 + 透传都在这一处，预览报的就是真跑的那些
     // （脚本文档里另有自己的默认值，只供手动直接跑脚本时用；CLI 这条路永远显式传参，
     // 所以两边万一漂了也不会影响实际行为）。
@@ -5333,7 +5524,10 @@ program
         args.push('--full');
     try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
-            timeout: 300_000, maxBuffer: 10 * 1024 * 1024,
+            // 30 分钟：全量重建实测要跑二十分钟以上（16k 条 / 1500+ 批），而这里原来给的是 5 分钟 --
+            // 那个值让 `--full` 在真实索引上**从来没跑完过**（超时被杀；且脚本改成了边嵌边落盘之前，
+            // 中途被杀等于连已经嵌好的那部分也一起丢）。
+            timeout: 1_800_000, maxBuffer: 10 * 1024 * 1024,
             env: pythonProcessEnv(opts.apiKey, 'DASHSCOPE_API_KEY'),
         });
         if (opts.json)
@@ -6424,12 +6618,14 @@ program
     .option('--source <name>', '仅处理指定公众号，可重复或用逗号分隔', (value, previous = []) => [...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');
@@ -6439,7 +6635,18 @@ program
     const bizDaily = join(pkgRoot, 'scripts', 'biz_daily.py');
     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) => `${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) => opts.json ? console.error(...values) : console.log(...values);
@@ -6472,6 +6679,14 @@ program
             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, {
             windowsHide: true,
@@ -7664,6 +7879,7 @@ program
     .command('check')
     .description('检查运行环境（Python、pip 依赖、数据库配置）')
     .option('--json', '输出 JSON 格式，不包含数据库路径或密钥')
+    .option('--report', '输出一段可直接粘贴给 AI / 贴进 issue 的诊断结论（已脱敏：用户名与 wxid 换占位符，不含密钥与聊天内容）')
     .action(async (opts) => {
     // 微信客户端的**版本**与它自报的**数据目录**：两个分支都要用，所以在这里算一次。
     // 判据见 `wechatClient.ts`（版本取活进程的 `--user-lib-dir`；取不到就是"未知"，不是"没问题"）。
@@ -7687,7 +7903,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'];
@@ -7765,7 +7983,43 @@ 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'));
@@ -7842,6 +8096,17 @@ 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 命令配置)' : '';