weflow-cli 1.9.0 → 1.10.0

package/dist/bin/weflow-cli.js

@@ -12,6 +12,7 @@ import { keyService } from '../src/core/keyService.js';
 import { NtCore } from '../src/core/ntCore.js';
 import { configService } from '../src/services/configService.js';
 import { chatService } from '../src/services/chatService.js';
+import { emptyMessagesNote, looksLikeTalkerId } from '../src/services/messageQuery.js';
 import { exportService } from '../src/services/exportService.js';
 import { writeEvidencePackage } from '../src/services/evidenceService.js';
 import { resolveTalker as resolveTalkerCore } from '../src/utils/talkerUtils.js';
@@ -25,6 +26,7 @@ import { authorizeOutbound, parseOutboundPolicy, performOutbound } from '../src/
 import { applyDerivedNtKeys, enableFavorites, detectFavDbPath } from '../src/services/initKeyService.js';
 import { disabledIds, readSkillBody, scanSkills, skillRoots, skillState } from '../src/services/assistantSkills.js';
 import { assistantScenes, validateSceneId } from '../src/services/assistantScenes.js';
+import { detectWechatClient, reportedDataDirs, samePath } from '../src/services/wechatClient.js';
 const program = new Command();
 function resolvePackageRoot() {
     return resolvePackageRootFrom(import.meta.url);
@@ -62,6 +64,24 @@ function parseCliInteger(value, field, minimum, maximum, json = false) {
         console.log(chalk.red(error));
     process.exit(1);
 }
+/** 校验一个"只能是这几个值之一"的参数。与 `parseCliInteger` / `requireCliDate` 同一约定：
+ * `--json` 时错误也得是一份 JSON —— 否则机器调用方在 stdout 上拿到的是彩色散文，解析不了。
+ *
+ * 抽成一个是有理由的：`--line` 的校验原本在四个命令里各写了一遍，其中三处只打散文（`vault rag`、
+ * 顶层 `search`、`chat`）—— 同一份判断写四遍，就有三遍漏掉了 `--json` 分支。
+ * 错误文案由 choices 生成，保证与原来逐字一致（'line 必须是 wiki、chat 或 all'）。
+ */
+function requireCliChoice(value, choices, field, json = false) {
+    const text = String(value);
+    if (choices.includes(text))
+        return text;
+    const error = `${field} 必须是 ${choices.slice(0, -1).join('、')} 或 ${choices[choices.length - 1]}`;
+    if (json)
+        console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', field, error }));
+    else
+        console.log(chalk.red(error));
+    process.exit(1);
+}
 function requireCliDate(value, json = false) {
     try {
         parseLocalDateOrIso(value);
@@ -611,9 +631,11 @@ program
             // 读这一位的调用方按 false 走保守分支即可。
             mcpDefaultReadOnly: false,
             mcpSurface: {
-                // 原文只写了 "minus save_memory" —— 而那张表也排除了 `look_at_image`（MCP 只取文本，
-                // 它挂进侧信道的图没人接）。机器可读字段少说一句同样算不准，如实写全。
-                derivedFrom: 'assistant tools minus save_memory and look_at_image',
+                // 这句话**手工补过两回**：先是只写 save_memory，后来补上 `look_at_image`，第三次加
+                // `set_todo_status` 时又漏了 —— 每次都是"表变了、这句话没变"，而且没有任何东西会红。
+                // 现在名字**逐个与 `MCP_EXCLUDED` 对齐**，并由 `test/assistant-tools.test.ts` 从源码里核：
+                // 那张表再加一项而这里没跟，测试就红（同下面 requiresConfirm 的处理方式）。
+                derivedFrom: 'assistant tools minus save_memory, look_at_image and set_todo_status',
                 writesFiles: ['export_chat'],
                 // 逐个核实过（脚本里确实调云端模型的那些）：
                 // who_owes_reply/search_chats → Jev；search_semantic → 阿里云百炼嵌入 + Jev 重排；draft_reply → Jev + DeepSeek。
@@ -758,8 +780,13 @@ program
             console.log(chalk.gray('  目录名未命中时将继续进行深度结构扫描，过程可能需要较长时间...'));
         }
         const detected = configuredDataRoot
-            ? { success: true, path: configuredDataRoot }
-            : await dbPathService.autoDetect({ searchDrives: opts.searchDrives, fullScan: opts.fullScan });
+            ? { success: true, path: configuredDataRoot, source: 'known' }
+            : await dbPathService.autoDetect({
+                searchDrives: opts.searchDrives, fullScan: opts.fullScan,
+                // **先问客户端自己**（它命令行上带着 `--wechat-files-path`）：这是唯一"来自
+                // 客户端自己"的来源，其余都是按目录名猜。取不到就是空数组，走老路。
+                hintedRoots: await reportedDataDirs(),
+            });
         if (!detected.success || !detected.path) {
             console.log(chalk.red('✗ 未检测到微信数据目录'));
             if (!opts.searchDrives && !opts.fullScan) {
@@ -779,7 +806,10 @@ program
             }
             process.exit(1);
         }
-        console.log(chalk.green(`✓ 检测到数据目录: ${detected.path}`));
+        // **说清是怎么找到的**：来源不同，可信度与后续排查都不同（"客户端自己说的"最硬）
+        const howFound = detected.source === 'client' ? '（客户端自己报的）'
+            : detected.source === 'scan' ? '（全盘扫描找到的）' : '';
+        console.log(chalk.green(`✓ 检测到数据目录: ${detected.path}${howFound}`));
         configService.set('dbPath', detected.path);
         configService.set('dataVersion', '4.x');
         // Step 2: 扫描账号
@@ -1039,6 +1069,7 @@ const configurableKeys = [
     'skillDirs', 'skillDisabled',
     'dailySources', 'dailySourceCategories',
     'dailyExcludeTopics', 'dailyAiEnabled',
+    'wechatMediaDownload',
     'emoticonSeed',
 ];
 function setConfigValue(key, value, quiet = false) {
@@ -1349,11 +1380,26 @@ program
         ? (await chatService.getMessagesInRange(talker, limit + offset, start, end)).slice(offset, offset + limit)
         : await chatService.getMessages(talker, limit, offset);
     if (messages.length === 0) {
+        // 拼错的 ID 会被 resolveTalker 原样放行 ⇒ 取不到消息。这里补一句话把两种情况分开，
+        // 但**不改退出码、也不改 success**（"没有消息"不是错误，脚本与 MCP 依赖这一点）。
+        let note = '';
+        if (looksLikeTalkerId(talkerInput)) {
+            const [sessions, contacts] = await Promise.all([
+                chatService.listSessions(talkerInput, 5),
+                chatService.listContacts(talkerInput, 5),
+            ]);
+            note = emptyMessagesNote(talkerInput, {
+                sessionUsernames: sessions.map(s => s.username),
+                contactUsernames: contacts.map(c => c.username),
+            });
+        }
         if (opts.json) {
-            console.log(JSON.stringify({ success: true, talker, messages: [] }));
+            console.log(JSON.stringify({ success: true, talker, messages: [], ...(note ? { note } : {}) }));
             return;
         }
         console.log(chalk.gray('未找到消息'));
+        if (note)
+            console.log(chalk.yellow(note));
         return;
     }
     if (opts.json) {
@@ -1699,6 +1745,53 @@ syncCmd
         process.exit(1);
 });
 // ==================== contacts ====================
+// contact-schema：读 contact.db 里**群**的 ext_buffer（本地只读：不联网、不调模型）
+//
+// 只解**实测验证过**的那几个字段（成员 userName/displayName/status/inviter + `#5`）；
+// `#5` 曾经叫"附加参与者 id"，实测是**成员 status 位 11 置位的那批 id**（本机 77/77 集合相等），
+// 所以输出改用 `statusBit11Ids`、不再说"额外参与者"（见 D-070）。
+// 顶层 `#3`/`#4` 的语义在本机被三次证伪（不是成员 id / 房间 id / 消息侧 id），所以脚本把它们
+// 原样放进 `unrecognized`，**不猜名字** —— 拿猜出来的名字写逻辑，就是拿不确定当事实。
+// 结构笔记见 `docs/CONTACT_DB_SCHEMA.md`，取舍见 D-067 / D-068 / D-070。
+//
+// `--contacts`（2026-10-07 加）：同一个命令改读**联系人**的 `contact.extra_buffer`，输出这一轮验证的
+// 三个字段 —— `#5` 国家/地区码（ISO 3166-1 alpha-2）、`#13` = 该行 `biz_info.type`、`#41` = 资料最近更新时间。
+// `#4`/`#9` 已定性为"账号自身资料文本的汇集"，是**内容**不是字段名，**故意不打印**（见 D-088）。
+program
+    .command('contact-schema')
+    .description('读 contact.db 的 ext_buffer：默认读群（成员 + #5）；--contacts 读联系人（#5 地区码 / #13 服务类型 / #41 更新时间）—— 只解已验证字段，未识别的原样标注（本地、只读）')
+    .option('-n, --limit <n>', '最多看几个（群 / 联系人）', '20')
+    .option('--room <which>', '只看某个（群 / 联系人 的 username 或 id）')
+    .option('--contacts', '改读联系人的 extra_buffer，而不是群')
+    .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', 'contact_schema.py');
+    const limit = parseCliInteger(opts.limit, 'limit', 1, 100000, !!opts.json);
+    const args = [script, '--limit', String(limit),
+        ...(opts.room ? ['--room', opts.room] : []),
+        ...(opts.contacts ? ['--contacts'] : []),
+        ...(opts.json ? ['--json'] : [])];
+    try {
+        const { stdout, stderr } = await execFileAsync(getPythonCommand(), args, {
+            timeout: 300_000, maxBuffer: 64 * 1024 * 1024, env: pythonProcessEnv(),
+        });
+        process.stdout.write(stdout);
+        if (stderr && !opts.json)
+            process.stderr.write(stderr);
+    }
+    catch (error) {
+        if (opts.json) {
+            console.log(JSON.stringify({ success: false, code: 'CONTACT_SCHEMA_FAILED', action: 'contact-schema', error: safeSubprocessError(error) }));
+        }
+        else {
+            console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`));
+        }
+        process.exit(1);
+    }
+});
 program
     .command('contacts')
     .description('查看联系人列表')
@@ -2065,7 +2158,10 @@ program
         }
     }
     else {
-        const timeout = parseCliInteger(opts.timeout, 'timeout', 1000, 600000);
+        // `opts.json` 也要传：这一行在 `--json` 下**不可达**（上面就 `INTERACTIVE_REQUIRED` 退出了），
+        // 但少传一个是安静的 —— 规则统一成"校验 helper 一律带上它"，判据才写得出来
+        // （`test/json-error-surface.test.ts` 末尾那条静态检查）。
+        const timeout = parseCliInteger(opts.timeout, 'timeout', 1000, 600000, opts.json);
         const result = await keyService.autoGetDbKey(timeout, (msg) => {
             console.log(chalk.gray(`  ${msg}`));
         });
@@ -2288,7 +2384,7 @@ whitelistCmd
     }
     else {
         try {
-            wxid = await resolveTalker(target);
+            wxid = await resolveTalker(target, !!opts.json, !!opts.json);
             const sessions = await chatService.listSessions(undefined, 50);
             const match = sessions.find(s => s.username === wxid);
             if (match)
@@ -2497,7 +2593,7 @@ blacklistCmd
     }
     else {
         try {
-            wxid = await resolveTalker(target);
+            wxid = await resolveTalker(target, !!opts.json, !!opts.json);
             const sessions = await chatService.listSessions(undefined, 50);
             const match = sessions.find(s => s.username === wxid);
             if (match)
@@ -3958,6 +4054,7 @@ program
     .option('-o, --output <dir>', '概念页输出目录', './output/wechat-vault/Wiki/Concepts')
     .option('--api-key <key>', 'DeepSeek API key')
     .option('--refresh-sources', '只把已有概念页的"来源"段补齐成当前全部来源（本地重写，**不调用模型**）')
+    .option('--qualify-links', '把跨线同名的概念链接改成带路径的形式（本地重写，**不调用模型**）')
     .option('--cards <dir...>', '产卡目录，可写多个；默认所有 output/*-notes（与索引的引用数同一口径）')
     .option('--dry-run', '仅预览，不读取文章、调用 AI 或写入概念页')
     .option('--yes', '确认调用 AI 并生成概念页')
@@ -3981,6 +4078,22 @@ program
         });
         return;
     }
+    if (opts.qualifyLinks) {
+        // 本地消歧：两条线同名的那些链接按名字带路径（`Chat/Concepts/DeepSeek|DeepSeek`），
+        // 免得 Obsidian 里那条裸链接命中另一条线的那张。**不调模型**，重跑幂等。
+        await runConfirmedPythonMutation({
+            action: 'wiki.qualifyLinks',
+            script,
+            args: ['--qualify-links', '--output', opts.output],
+            cliOptions: opts,
+            preview: { readsLocalKnowledge: true, rewritesExistingPages: true, usesAi: false },
+            confirmationMessage: `确认把 ${opts.output} 里跨线同名的概念链接改成带路径的形式？`
+                + '（本地重写，不调用 AI）',
+            apiKey: opts.apiKey,
+            timeout: 300_000,
+        });
+        return;
+    }
     const limit = parseCliInteger(opts.limit, 'limit', 1, 1000, opts.json);
     const minRefs = parseCliInteger(opts.minRefs ?? '1', 'min-refs', 1, 50, opts.json);
     await runConfirmedPythonMutation({
@@ -4008,8 +4121,9 @@ program
     .option('--wiki-limit <n>', '概念编译数', '20')
     .option('--source <name>', '仅处理指定公众号，可重复使用', (value, previous) => [...previous, value], [])
     .option('--skip-classify', '跳过 AI 后处理')
-    .option('--skip-wiki', '跳过概念编译')
-    .option('--skip-vault', '跳过 Vault 副本同步')
+    // 这两个**默认不做**：Obsidian 自带的图谱视图是实时的，写一次 vault 图谱就重画一次。
+    .option('--with-wiki', '把概念页写进 Obsidian Vault（默认不写：图谱只在你说了才变）')
+    .option('--with-vault', '把当天内容副本同步进 Obsidian Vault（默认不写）')
     .option('--skip-html', '跳过 HTML 阅读器生成')
     .option('--skip-ai-report', '跳过 AI 深度阅读报告')
     .option('--no-ai', '关闭全部 AI 调用，保留抓取和本地输出')
@@ -4101,10 +4215,10 @@ program
         args.push('--source', source);
     if (opts.skipClassify)
         args.push('--skip-classify');
-    if (opts.skipWiki)
-        args.push('--skip-wiki');
-    if (opts.skipVault)
-        args.push('--skip-vault');
+    if (opts.withWiki)
+        args.push('--with-wiki');
+    if (opts.withVault)
+        args.push('--with-vault');
     if (opts.skipHtml)
         args.push('--skip-html');
     if (opts.skipAiReport)
@@ -4346,16 +4460,30 @@ program.commands
     .description('Vault 搜索 — 文章+概念+笔记')
     .argument('<query>', '搜索关键词')
     .option('--type <type>', 'all / article / concept / note', 'all')
+    .option('--line <line>', 'wiki=文章线(默认) / chat=聊天线 / all=两条都搜', 'wiki')
     .option('--top-k <n>', '返回数量', '10')
+    // `vault_search.py` 一直有 `--days`（它的 docstring 自己就举 `--days 30`），CLI 从来没接 ——
+    // 于是"只搜最近一周"这件事在这条路上做不到，窗口被脚本默认值（90）钉死。与 `search-index --days`
+    // 同形：窗口的运行值由 CLI 说了算，默认值与脚本一致。
+    .option('--days <n>', '日报文章取最近多少天（默认 90）', '90')
+    // 这条 `--json` 曾经**不存在，而 JSON 又是唯一的输出**：参数里硬编码着 `'--json'`，
+    // 人类模式虽然脚本里写着（`vault_search.py` 不带 `--json` 时打印带相关度的可读列表）
+    // 却没有任何入口能到达，用户显式敲 `--json` 还会拿到 `unknown option` —— 与
+    // `docs/EXTENDING.md` 那条"脚本或 AI 会驱动的命令都有 `--json` 模式"正相反。
+    // 现在按兄弟命令（`vault rag`、顶层 `search`）的形状来：默认人类可读，`--json` 才转发。
+    .option('--json', '输出 JSON 格式（含本地路径与标题，供本机脚本/AI 使用）')
     .action(async (query, opts) => {
     const pkgRoot = resolvePackageRoot();
     const script = join(pkgRoot, 'scripts', 'vault_search.py');
-    if (!['all', 'article', 'concept', 'note'].includes(opts.type)) {
-        console.log(chalk.red('type 必须是 all、article、concept 或 note'));
-        process.exit(1);
-    }
-    const topK = parseCliInteger(opts.topK, 'top-k', 1, 100);
-    await runPythonCmd(script, [query, '--type', opts.type, '--top-k', String(topK), '--json']);
+    // 校验分支也要认 `--json`（`requireCliChoice` 里就带着这条约定）：
+    // 否则 JSON 模式下 stdout 是一行彩色散文，脚本解析不了。
+    requireCliChoice(opts.type, ['all', 'article', 'concept', 'note'], 'type', opts.json);
+    requireCliChoice(opts.line, ['wiki', 'chat', 'all'], 'line', opts.json);
+    const topK = parseCliInteger(opts.topK, 'top-k', 1, 100, opts.json);
+    const days = parseCliInteger(opts.days, 'days', 1, 3650, opts.json);
+    await runPythonCmd(script, [query, '--type', opts.type, '--line', opts.line,
+        '--top-k', String(topK), '--days', String(days),
+        ...(opts.json ? ['--json'] : [])]);
 }));
 // vault rag — RAG dialog over Vault
 program.commands
@@ -4364,6 +4492,7 @@ program.commands
     .description('Vault 问答 — 基于知识库的 AI 对话')
     .argument('<question>', '问题')
     .option('--top-k <n>', '检索条数', '8')
+    .option('--line <line>', 'wiki=文章线(默认) / chat=聊天线 / all=两条都搜', 'wiki')
     .option('--api-key <key>', 'DeepSeek API key')
     .option('--dry-run', '仅预览，不读取知识库或调用 AI')
     .option('--yes', '确认读取本地知识并发送筛选后的上下文到 AI')
@@ -4372,11 +4501,13 @@ program.commands
     const pkgRoot = resolvePackageRoot();
     const script = join(pkgRoot, 'scripts', 'vault_rag.py');
     const topK = parseCliInteger(opts.topK, 'top-k', 1, 100, opts.json);
+    requireCliChoice(opts.line, ['wiki', 'chat', 'all'], 'line', opts.json);
     const preview = {
         success: true,
         dryRun: true,
         action: 'vault.rag',
         topK,
+        line: opts.line,
         readsLocalKnowledge: true,
         usesAi: true,
         sendsSelectedContextToAi: true,
@@ -4404,7 +4535,7 @@ program.commands
             return;
         }
     }
-    const args = ['--top-k', String(topK)];
+    const args = ['--top-k', String(topK), '--line', opts.line];
     if (opts.json)
         args.push('--json');
     const { execFile } = await import('child_process');
@@ -4724,6 +4855,26 @@ program
     }));
 });
 // ==================== weread ====================
+/** 微信读书服务失败时的统一出口。
+ *
+ * 9 个调用点（shelf / stats / notes×2 / search / book / review / discover / profile）原来都是一行式
+ * 分支：把彩色散文打在 stdout 上再 `process.exit(1)`，**没有** json 支，而各命令的 `if (opts.json)`
+ * 分支在它后面 ⇒ `weread shelf --json` 失败时 stdout 上只有一行 `✗ …`，调用方解析不了，也不知道
+ * 是哪个命令失败了。全库其余同类出口都是"机器支发 JSON + exit"。
+ *
+ * （这里刻意**不**把那行旧代码原样抄出来：`test/json-error-surface.test.ts` 有一条绊线在扫那个形状，
+ * 而注释里留一份字面量会让判据读到它 —— 今晚已经在另一条判据上踩过这个坑。）
+ *
+ * 人看的那一支保持原样（`console.log`，不动它的落点）：把 CLI 的**错误**统一改走 stderr 是另一件事，
+ * 现在库里两种都有（多数 `console.error`、少数 `console.log`），不在这条修复里顺手改。
+ */
+function failWeread(res, json = false) {
+    if (json)
+        console.log(JSON.stringify({ success: false, code: 'WEREAD_FAILED', error: res.error }));
+    else
+        console.log(chalk.red(`✗ ${res.error}`));
+    process.exit(1);
+}
 const wereadCmd = program
     .command('weread')
     .description('微信读书助手 — 书架、统计、笔记、搜索、书评、推荐');
@@ -4734,10 +4885,8 @@ wereadCmd
     .action(async (opts) => {
     const weread = await getWereadService();
     const res = await weread.shelf();
-    if (!res.ok) {
-        console.log(chalk.red(`✗ ${res.error}`));
-        process.exit(1);
-    }
+    if (!res.ok)
+        failWeread(res, !!opts.json);
     const d = res.data;
     if (opts.json) {
         console.log(JSON.stringify(d, null, 2));
@@ -4768,10 +4917,8 @@ wereadCmd
     .action(async (opts) => {
     const weread = await getWereadService();
     const res = await weread.readData(opts.mode);
-    if (!res.ok) {
-        console.log(chalk.red(`✗ ${res.error}`));
-        process.exit(1);
-    }
+    if (!res.ok)
+        failWeread(res, !!opts.json);
     const d = res.data;
     if (opts.json) {
         console.log(JSON.stringify(d, null, 2));
@@ -4820,10 +4967,8 @@ wereadCmd
     const limit = parseCliInteger(opts.limit, 'limit', 1, 100, opts.json);
     if (opts.bookId) {
         const res = await weread.bookmarks(opts.bookId, limit);
-        if (!res.ok) {
-            console.log(chalk.red(`✗ ${res.error}`));
-            process.exit(1);
-        }
+        if (!res.ok)
+            failWeread(res, !!opts.json);
         const d = res.data;
         if (opts.json) {
             console.log(JSON.stringify(d, null, 2));
@@ -4841,10 +4986,8 @@ wereadCmd
     }
     else {
         const res = await weread.notebooks(50);
-        if (!res.ok) {
-            console.log(chalk.red(`✗ ${res.error}`));
-            process.exit(1);
-        }
+        if (!res.ok)
+            failWeread(res, !!opts.json);
         const d = res.data;
         if (opts.json) {
             console.log(JSON.stringify(d, null, 2));
@@ -4869,10 +5012,8 @@ wereadCmd
     const weread = await getWereadService();
     const limit = parseCliInteger(opts.limit, 'limit', 1, 100, opts.json);
     const res = await weread.search(keyword, limit);
-    if (!res.ok) {
-        console.log(chalk.red(`✗ ${res.error}`));
-        process.exit(1);
-    }
+    if (!res.ok)
+        failWeread(res, !!opts.json);
     const d = res.data;
     if (opts.json) {
         console.log(JSON.stringify(d, null, 2));
@@ -4899,10 +5040,8 @@ wereadCmd
         weread.bookInfo(bookId),
         weread.getProgress(bookId),
     ]);
-    if (!infoRes.ok) {
-        console.log(chalk.red(`✗ ${infoRes.error}`));
-        process.exit(1);
-    }
+    if (!infoRes.ok)
+        failWeread(infoRes, !!opts.json);
     const b = infoRes.data;
     if (opts.json) {
         console.log(JSON.stringify(b, null, 2));
@@ -4935,10 +5074,8 @@ wereadCmd
     const weread = await getWereadService();
     const limit = parseCliInteger(opts.limit, 'limit', 1, 100, opts.json);
     const res = await weread.reviews(bookId, limit);
-    if (!res.ok) {
-        console.log(chalk.red(`✗ ${res.error}`));
-        process.exit(1);
-    }
+    if (!res.ok)
+        failWeread(res, !!opts.json);
     const d = res.data;
     if (opts.json) {
         console.log(JSON.stringify(d, null, 2));
@@ -4967,10 +5104,8 @@ wereadCmd
     const res = opts.bookId
         ? await weread.similar(opts.bookId, limit)
         : await weread.recommend(limit);
-    if (!res.ok) {
-        console.log(chalk.red(`✗ ${res.error}`));
-        process.exit(1);
-    }
+    if (!res.ok)
+        failWeread(res, !!opts.json);
     const d = res.data;
     if (opts.json) {
         console.log(JSON.stringify(d, null, 2));
@@ -4994,10 +5129,8 @@ wereadCmd
     .action(async (opts) => {
     const weread = await getWereadService();
     const res = await weread.profile();
-    if (!res.ok) {
-        console.log(chalk.red(`✗ ${res.error}`));
-        process.exit(1);
-    }
+    if (!res.ok)
+        failWeread(res, !!opts.json);
     const p = res.data;
     if (opts.json) {
         console.log(JSON.stringify(p, null, 2));
@@ -5040,6 +5173,8 @@ program
     .description('语义搜索知识库（聊天记录 + 文章）')
     .argument('<query>', '搜索关键词')
     .option('--top-k <n>', '返回数量', '10')
+    .option('--line <line>', 'wiki=文章线(默认) / chat=聊天记录 / all=两条都搜', 'wiki')
+    .option('--no-rerank', '不调用决策模型重排，只按向量/关键词相似度返回（回退到引入重排之前）')
     .option('--api-key <key>', 'DashScope embedding API key')
     .option('--dry-run', '仅预览，不读取索引或调用向量服务')
     .option('--yes', '确认执行可能调用云端向量服务的搜索')
@@ -5051,11 +5186,14 @@ program
     const pkgRoot = resolvePackageRoot();
     const script = join(pkgRoot, 'scripts', 'semantic_search.py');
     const topK = parseCliInteger(opts.topK, 'top-k', 1, 100, opts.json);
+    requireCliChoice(opts.line, ['wiki', 'chat', 'all'], 'line', opts.json);
     const preview = {
         success: true,
         dryRun: true,
         action: 'semantic-search.query',
         topK,
+        line: opts.line,
+        noRerank: opts.rerank === false,
         readsLocalIndex: true,
         mayUseCloudEmbedding: true,
     };
@@ -5082,7 +5220,11 @@ program
             return;
         }
     }
-    const args = [script, 'search', '--top-k', String(topK)];
+    // `--no-rerank` 是**旗标**（不是密钥）⇒ 可以走 argv；查询本身仍然只走 env（见 `privacy-paths` 那条规矩）。
+    // 接这条通道之前，`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'] : [])];
     try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
             timeout: 60_000, maxBuffer: 10 * 1024 * 1024,
@@ -5185,6 +5327,7 @@ program
     .description('RAG 智能助手 — 基于聊天记录和公众号的对话式问答')
     .argument('[question]', '要问的问题（不传则进入交互模式）')
     .option('--top-k <n>', '检索数量', '10')
+    .option('--line <line>', 'wiki=文章/文章概念(默认) / chat=聊天记录 / all=两条都搜', 'wiki')
     .option('--talker <name>', '限定联系人/群聊')
     .option('--api-key <key>', 'AI API key')
     .option('--dry-run', '仅预览，不读取知识库或调用 AI')
@@ -5197,11 +5340,13 @@ program
     const pkgRoot = resolvePackageRoot();
     const script = join(pkgRoot, 'scripts', 'rag_chat.py');
     const topK = parseCliInteger(opts.topK, 'top-k', 1, 100, opts.json);
+    requireCliChoice(opts.line, ['wiki', 'chat', 'all'], 'line', opts.json);
     const preview = {
         success: true,
         dryRun: true,
         action: 'rag-chat.query',
         topK,
+        line: opts.line,
         interactiveRequired: !question,
         readsLocalKnowledge: true,
         usesCloudEmbedding: true,
@@ -5238,7 +5383,7 @@ program
     }
     const args = [script];
     if (question) {
-        args.push('--top-k', String(topK));
+        args.push('--top-k', String(topK), '--line', opts.line);
         if (opts.json)
             args.push('--json');
         try {
@@ -5259,7 +5404,7 @@ program
     }
     else {
         // 交互模式：使用 spawn 保持终端交互
-        args.push('--interactive', '--top-k', String(topK));
+        args.push('--interactive', '--top-k', String(topK), '--line', opts.line);
         const child = spawn(getPythonCommand(), args, {
             windowsHide: true,
             stdio: 'inherit',
@@ -5533,7 +5678,7 @@ program
 // draft：判断在前、起草在后、**绝不发送**
 program
     .command('draft <talker>')
-    .description('帮我起草回复：先判断（意图/风险/该不该给实质），再起草候选 —— **只产出文本，不发送**')
+    .description('帮我起草回复：先判断（意图/风险/该不该给实质），再起草候选 —— **默认只产出文本；给了 --pick N --send 才会替你发送**')
     .option('--count <n>', '要几条候选', '3')
     .option('--pick <n>', '选第几条（从 1 数）；不带 --send 时只把那条的完整原文打出来')
     .option('--send', '把选中的那条发出去 —— **必须同时给 --pick**（不允许"自己挑一条发"），仍需 --yes/--dry-run')
@@ -5778,17 +5923,87 @@ program
         process.exit(1);
     }
 });
+// wiki graph：把概念图谱导成一张**自包含**的 3D 页面（全本地：只读 Vault、不联网、不调用模型）
+//
+// 自包含是硬要求，不是顺手：页面用 `file://` 双击打开，那时 `fetch` 会被 CORS 挡死，
+// 所以库、数据、坐标全部内联进去 —— 也因此三个库随 npm 包发（见 resources/js/graph3d/NOTICE.txt）。
+// 布局（250 tick 实测 55 秒）在构建期用 Node 算完并缓存，打开页面即用。
+program.commands.find(c => c.name() === 'wiki')?.addCommand(new Command('graph')
+    .description('把概念图谱导成一张自包含的图谱页面（只读本地、不联网；生成的 HTML 双击就能逛）。--flat 出 2D 版')
+    .option('--vault <dir>', 'Vault 根目录（默认 output/wechat-vault）')
+    .option('-o, --out <file>', '页面写到哪（默认 output/knowledge-graph-3d.html）')
+    .option('--ticks <n>', '力导向迭代次数（默认 250，越多越舒展也越慢）')
+    .option('--cache <dir>', '布局缓存目录（派生数据；测试/多份图分开放时用）')
+    .option('--flat', '2D 版：平面图（更像 Obsidian 那种），canvas 渲染，输出默认 knowledge-graph-2d.html')
+    .option('--min-degree <n>', '只画在原图里连接数 ≥N 的概念（去掉细枝看骨架；0 = 全画）')
+    .option('--line <which>', '只画一条线：all / wiki / chat')
+    .option('--dry-run', '只报概念与链接数：不写文件、也不算布局（本地，零改动）')
+    .option('--open', '生成后用默认浏览器打开它')
+    .option('--json', '输出机器可读结果')
+    .action(async (opts) => {
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    // 2D 与 3D 是**两个入口脚本**：图怎么建共用（graph_2d 直接 import graph_3d），
+    // 换的是布局维度与渲染器 —— 两套渲染器塞一个文件就没人看得完了。
+    const script = join(resolvePackageRoot(), 'scripts', opts.flat ? 'graph_2d.py' : 'graph_3d.py');
+    const ticks = opts.ticks === undefined ? undefined : parseCliInteger(opts.ticks, 'ticks', 1, 100000, !!opts.json);
+    // `--json` 一律要：CLI 要拿到 out 路径与计数，才决定怎么印。开关只决定**给谁看**。
+    const minDegree = opts.minDegree === undefined
+        ? undefined : parseCliInteger(opts.minDegree, 'min-degree', 0, 100000, !!opts.json);
+    const args = [script,
+        ...(opts.vault ? ['--vault', opts.vault] : []),
+        ...(opts.out ? ['--out', opts.out] : []),
+        ...(opts.cache ? ['--cache', opts.cache] : []),
+        ...(ticks === undefined ? [] : ['--ticks', String(ticks)]),
+        ...(minDegree === undefined || minDegree === 0 ? [] : ['--min-degree', String(minDegree)]),
+        ...(opts.line ? ['--line', opts.line] : []),
+        ...(opts.dryRun ? ['--dry-run'] : []),
+        '--json'];
+    try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+            timeout: 900_000, maxBuffer: 64 * 1024 * 1024, env: pythonProcessEnv(),
+        });
+        const body = JSON.parse(stdout.slice(stdout.indexOf('{')));
+        if (opts.json) {
+            console.log(JSON.stringify(body));
+        }
+        else if (body.dryRun) {
+            console.log(`概念 ${body.nodes} 个、链接 ${body.links} 条（--dry-run：没有写文件）`);
+        }
+        else {
+            console.log(chalk.green(`✓ 已生成 ${body.out}`));
+            console.log(chalk.gray(`  概念 ${body.nodes} / 链接 ${body.links} / ${body.mb} MB · ${opts.flat ? '2D' : '3D'} · 双击就能逛，不需要服务器`));
+        }
+        if (!opts.dryRun && opts.open && body.out)
+            await openLocalUrl(body.out);
+    }
+    catch (error) {
+        if (opts.json) {
+            console.log(JSON.stringify({ success: false, code: 'GRAPH_FAILED', action: 'graph-3d', error: safeSubprocessError(error) }));
+        }
+        else {
+            console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`));
+        }
+        process.exit(1);
+    }
+}));
 // wiki lint：知识库体检（全本地：不联网、不调用模型）
 program.commands.find(c => c.name() === 'wiki')?.addCommand(new Command('lint')
     .description('知识库体检：断链、孤儿、空页、同名（本地，不联网）')
-    .option('--dir <dir>', '概念页目录', './output/wechat-vault/Wiki/Concepts')
+    // 不给默认值：不传 `--dir` 时体检脚本自己的默认（清单里的**全部线**）。
+    // 这里曾经默认只给文章线，而脚本默认两条线都体检 ⇒"半开半合"：命令行跑出来
+    // 与脚本跑出来口径不同，而两边都不报错。
+    .option('--dir <dirs...>', '概念页目录（可重复；不传则体检清单里的全部线）')
     .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', 'wiki_lint.py');
-    const args = [script, '--dir', String(opts.dir), ...(opts.json ? ['--json'] : [])];
+    const dirs = Array.isArray(opts.dir) ? opts.dir : (opts.dir ? [opts.dir] : []);
+    const args = [script, ...dirs.flatMap((d) => ['--dir', String(d)]),
+        ...(opts.json ? ['--json'] : [])];
     try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
             timeout: 120_000, maxBuffer: 20 * 1024 * 1024, env: pythonProcessEnv(),
@@ -5812,6 +6027,7 @@ program
     .option('--limit <n>', '最多处理几个会话', '40')
     .option('--dry-run', '仅预览：几个会话、多少字符会发给生成模型（只读本地，零出境）')
     .option('--yes', '确认把对话发送给生成模型')
+    .option('--transcribe-voice', '把缺转写的语音**本机**识别掉再产卡（本地 whisper，慢、吃 CPU、不出网；配合 --dry-run 就是只补转写、不调模型）')
     .option('--json', '输出机器可读结果；执行仍需 --yes')
     .action(async (opts) => {
     const { execFile } = await import('child_process');
@@ -5847,6 +6063,7 @@ program
     }
     const args = [script, '--days', String(days), '--limit', String(limit),
         ...(confirmed ? ['--yes'] : []),
+        ...(opts.transcribeVoice ? ['--transcribe-voice'] : []),
         ...(opts.json ? ['--json'] : []),
         ...(opts.dryRun ? ['--dry-run'] : [])];
     try {
@@ -6220,7 +6437,7 @@ program
     };
     const isComplete = (targetDate) => Object.values(artifactStatus(targetDate)).every(Boolean);
     const runPipeline = (targetDate) => new Promise((resolve) => {
-        const args = [pipeline, '--date', targetDate, '--engine', noAi ? 'local' : 'deepseek', '--interest', 'AI', '--skip-wiki'];
+        const args = [pipeline, '--date', targetDate, '--engine', noAi ? 'local' : 'deepseek', '--interest', 'AI'];
         if (noAi)
             args.push('--no-ai');
         // 与 --no-ai 不同：这一条保留判断（Jev），只关掉 LLM 的文字生成。
@@ -7380,6 +7597,11 @@ program
     }
     else {
         console.log(json);
+        // 机器模式到这里就结束：下面那段工具清单与"复制以上 JSON…"是**给人看的**，原来无条件打在
+        // stdout 上 ⇒ `mcp-config --json-result | jq` 断在第 14 行（2026-10-12 由只读驱动扫描发现；
+        // 写路径本来就早退发 JSON，所以只有读路径这一处漏）。
+        if (opts.jsonResult)
+            return;
     }
     console.log(chalk.cyan('\n可用的 MCP 工具：'));
     const STATIC_TOOLS = [
@@ -7418,6 +7640,28 @@ program
     .description('检查运行环境（Python、pip 依赖、数据库配置）')
     .option('--json', '输出 JSON 格式，不包含数据库路径或密钥')
     .action(async (opts) => {
+    // 微信客户端的**版本**与它自报的**数据目录**：两个分支都要用，所以在这里算一次。
+    // 判据见 `wechatClient.ts`（版本取活进程的 `--user-lib-dir`；取不到就是"未知"，不是"没问题"）。
+    const client = await detectWechatClient();
+    // 客户端自报的数据目录 vs 配置里那个数据库推出来的根：**只比是不是同一份**，
+    // 路径本身不进机器可读输出（`wechat-check/v1` 一直是不含路径的）。
+    //
+    // **只在 4.x 上比**：这个根是从 `ntDbPath`（4.x 的库）推的，而客户端自报的那条来自 4.x 客户端
+    // —— 只用 3.x 的用户（`dbPath3x`）比出来的"不是同一份"没有意义，而这句话**只在 false 时打印**
+    // ⇒ 那就是一条假警告。判据不成立时给 null（"不知道"），不是 false。
+    const { dirname } = await import('node:path');
+    // **四层**：`…/xwechat_files/<wxid>/db_storage/message/message_0.db`
+    // → message → db_storage → <wxid> → xwechat_files。少一层就退到 `<wxid>` 目录，
+    // 于是两个路径永远不相等、永远报"不是同一份"（一个看着很合理的假警告）。
+    const dbPathConfigured = String(configService.get('dataVersion') || '') === '4.x'
+        ? String(configService.get('ntDbPath') || '')
+        : '';
+    const configuredRoot = dbPathConfigured
+        ? dirname(dirname(dirname(dirname(dbPathConfigured))))
+        : '';
+    const dataDirMatchesConfig = (client.dataDirs.length && configuredRoot)
+        ? client.dataDirs.some(dir => samePath(dir, configuredRoot))
+        : null;
     if (opts.json) {
         const { execFileSync } = await import('child_process');
         const requiredDependencies = ['sqlcipher3', 'html2text', 'zstandard', 'cryptography'];
@@ -7475,6 +7719,26 @@ program
                 messageChannelLoggedIn: !!configService.get('wechatOcToken'),
                 daemonRunning: daemonAlive,
             },
+            // `version` 只从活进程取；取不到就是 null + 一句 `note`（**不是**"没问题"）。
+            // `unusableVersionDirs` 是磁盘上的残留版本目录（没有 `Weixin.dll`）—— 指向它们的加载会失败。
+            wechatClient: {
+                running: client.running,
+                version: client.version,
+                loadedDirs: client.loadedDirs,
+                // 客户端自报的构建 token（并列的第二来源；**不拿它推版本号**，编码规则没解出来）
+                versionTokens: client.versionTokens,
+                note: client.note,
+                unusableVersionDirs: client.unusableVersionDirs,
+                // 客户端**自己说**数据目录在哪（与配置不一致时说明两边不是同一份库）
+                dataDirs: client.dataDirs,
+                // 只报结论（true/false/null），**不带路径** —— 这条 schema 一直是不含路径的
+                dataDirMatchesConfig,
+                // `update.data` 在场 ⇒ 加载路径可能不由命令行决定：这条不确定必须跟着版本一起出去
+                updateData: client.updateData,
+                // 只报条数与最近时间（不读崩溃内容）
+                crashRecords: client.crashRecords,
+                caveats: client.caveats,
+            },
         };
         console.log(JSON.stringify(data, null, 2));
         return;
@@ -7559,7 +7823,38 @@ program
             console.log(chalk.gray(`  ${label}: 未配置${hint}`));
         }
     }
-    // 6. Assistant (第二大脑)
+    // 6. 微信客户端版本（`client` / `dataDirMatchesConfig` 在 action 开头已经算过）
+    console.log(chalk.white('\n微信客户端:'));
+    if (client.version) {
+        // 并列报上客户端自报的构建 token：这是"哪个构建"的第二个来源（**不用它推版本号**）
+        const token = client.versionTokens.length ? chalk.gray(`  · 自报构建 ${client.versionTokens.join('、')}`) : '';
+        console.log(chalk.green(`  ✓ 运行时加载 ${client.version}`) + chalk.gray(` (${client.loadedDirs[0]})`) + token);
+    }
+    else {
+        // **说"未知"而不是"没问题"**：取不到就说取不到，别给人一个假的安心
+        console.log(chalk.gray(`  ○ 版本未知 — ${client.note}`));
+    }
+    for (const dead of client.unusableVersionDirs) {
+        console.log(chalk.yellow(`  ! 残留版本目录 ${dead.dir}：只剩 ${dead.files} 个文件（没有 Weixin.dll）`));
+        console.log(chalk.gray('    指向它的加载会失败；如果客户端起不来，先看这里'));
+    }
+    // `update.data` 在场时上面那个版本**未必**是加载的那个 —— 这句话要跟着它一起出现
+    for (const caveat of client.caveats) {
+        console.log(chalk.yellow(`  ⚠ ${caveat}`));
+    }
+    if (client.dataDirs.length) {
+        console.log(chalk.gray(`  · 客户端自报数据目录: ${client.dataDirs.join('、')}`));
+        if (dataDirMatchesConfig === false) {
+            // 不一致 = 两边可能不是同一份库（本机数据目录还有 D 盘软链，这条已经按真身比过）
+            console.log(chalk.yellow('    ⚠ 与配置里那个数据库推出来的根**不是同一份** —— 先确认你在读的是客户端正在写的那份'));
+        }
+    }
+    const crashes = client.crashRecords.reports + client.crashRecords.records;
+    if (crashes > 0) {
+        const when = client.crashRecords.newest ? client.crashRecords.newest.slice(0, 16).replace('T', ' ') : '时间读不到';
+        console.log(chalk.gray(`  · 客户端崩溃记录 ${crashes} 份（最近 ${when}）—— 客户端崩过时数据读不出来，先看这条`));
+    }
+    // 7. Assistant (第二大脑)
     console.log(chalk.white('\n第二大脑 Agent:'));
     const aiKey = configService.get('deepseekApiKey');
     const aiBase = configService.get('aiBaseUrl');
@@ -7780,7 +8075,7 @@ async function showInteractiveMenu() {
             const { spawn } = await import('child_process');
             const pipeline = join(resolvePackageRoot(), 'scripts', 'pipeline.py');
             console.log(chalk.cyan(`\n📰 正在生成 ${dateStr} 公众号日报...\n`));
-            const child = spawn(getPythonCommand(), [pipeline, '--date', dateStr, '--interest', 'AI', '--skip-wiki'], {
+            const child = spawn(getPythonCommand(), [pipeline, '--date', dateStr, '--interest', 'AI'], {
                 windowsHide: true,
                 stdio: 'inherit',
                 env: pythonProcessEnv(apiKey),