weflow-cli 1.12.0 → 1.13.1

package/scripts/pipeline.py

@@ -13,6 +13,7 @@
   python scripts/pipeline.py --date 2026-06-09 --skip-classify
 """
 import sys, os, subprocess, time, shutil
+from datetime import datetime, timedelta
 from pathlib import Path
 
 SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -40,6 +41,10 @@ def main():
     parser.add_argument('--engine', default='deepseek',
                         help='AI 引擎: deepseek(默认) / claude / ollama / local')
     parser.add_argument('--date', help='日期 YYYY-MM-DD')
+    parser.add_argument('--yesterday', action='store_true',
+                        help='跑**昨天**（等价于 --date 昨天）。给计划任务用的：公众号发到 24:00 才停，'
+                             '当晚跑的那一天永远不全；而"跑昨天"与时刻无关 —— 机器当时在睡觉、'
+                             '起来补跑，结果完全相同（见 OPERATIONS「让它每天自己跑」）')
     parser.add_argument('--interest', default='AI', help='兴趣主题（默认 AI）')
     parser.add_argument('--wiki-limit', type=int, default=20, help='概念编译数量（默认 20）')
     parser.add_argument('--skip-classify', action='store_true', help='跳过后处理')
@@ -57,10 +62,20 @@ def main():
                              '注意：下游步骤（行动建议/概念编译/AI 报告）仍会用 LLM，'
                              '要全关请再加 --skip-classify --skip-ai-report')
     parser.add_argument('--ai-report-range', type=int, default=1, help='AI 报告覆盖最近 N 天（默认 1=仅当天）')
+    parser.add_argument('--prefetch-bodies', nargs='?', type=int, const=8, default=0, metavar='N',
+                        help='只转发给 biz_daily：Phase 1 之前先并发把这一天的正文抓进缓存'
+                             '（N=并发数，默认 8），让 Phase 1 走缓存命中、不再逐篇 sleep。'
+                             '450 篇约 75 分钟 → 秒级；对上游的请求次数不变（见 biz_daily.prefetch_bodies）')
     parser.add_argument('--source', action='append', default=[], metavar='NAME',
                         help='仅处理指定公众号，可重复或用逗号分隔')
     args = parser.parse_args()
 
+    if args.yesterday:
+        if args.date:
+            print('[ERROR] --date 与 --yesterday 不能同时给（前者是明确的一天，后者是"昨天"）')
+            sys.exit(1)
+        args.date = (datetime.now() - timedelta(days=1)).strftime('%Y-%m-%d')
+
     sys.path.insert(0, SCRIPTS_DIR)
     from _utils import load_config, get_api_key
     config = load_config()
@@ -109,6 +124,12 @@ def main():
                   % '、'.join(n for n, skipped in (('classify_daily（行动建议）', args.skip_classify),
                                                    ('compile_wiki（概念编译）', not args.with_wiki))
                               if not skipped))
+    if args.prefetch_bodies:
+        # 原样转发：`--prefetch-bodies` 不带数字时 biz_daily 用自己的默认并发数，
+        # 所以这里不加数字（免得两处默认值各写一份、迟早漂移）。
+        step1_args += ['--prefetch-bodies']
+        if args.prefetch_bodies != 8:            # 显式给了数字才转发数字
+            step1_args += [str(args.prefetch_bodies)]
     if not run_step('biz_daily — 抓取+摘要', step1_args):
         sys.exit(1)
 

package/scripts/repro_customer_init.cmd

@@ -0,0 +1,86 @@
+@echo off
+chcp 65001 >nul
+setlocal
+rem ============================================================================
+rem  Reproduce the customer's failing scenario on YOUR machine, safely.
+rem
+rem  What he hit (2026-10-18):
+rem      init     -> "NT scan failed (exit 9009)"  ...  then "初始化完成!"
+rem      sessions -> "未找到会话"
+rem  The tool could not read the database but still reported success.
+rem
+rem  This window recreates it:
+rem    * throw-away HOME (D:\tmp\wf-test) - your real config is never touched
+rem    * PATH with node + system tools but NO python (the "Store placeholder" case)
+rem    * init / sessions / check --report, in that order
+rem  Read-only. No network, no API key, no cost.
+rem
+rem  PREREQUISITE: open WeChat and log in first.
+rem ============================================================================
+
+cd /d "%~dp0.."
+if not exist "dist\bin\weflow-cli.js" (
+  echo [ERROR] dist\bin\weflow-cli.js not found. Run "npm run build" in this repo first.
+  pause
+  exit /b 1
+)
+
+set "SCOPE=D:\tmp\wf-test"
+if not exist "%SCOPE%" mkdir "%SCOPE%"
+set "USERPROFILE=%SCOPE%"
+set "HOME=%SCOPE%"
+
+set "NODEDIR="
+for /f "delims=" %%i in ('where node 2^>nul') do if not defined NODEDIR set "NODEDIR=%%~dpi"
+if not defined NODEDIR (
+  echo [ERROR] node.exe not found on PATH.
+  pause
+  exit /b 1
+)
+set "PATH=%NODEDIR%;C:\Windows\System32;C:\Windows\System32\WindowsPowerShell\v1.0"
+
+set "DATA=D:\微信\xwechat_files"
+
+echo ==========================================================================
+echo  A) Environment: python MUST fail here - that is the whole point
+echo ==========================================================================
+python --version
+echo.
+echo   ^(error / "not recognized" above = correct^)
+echo.
+
+echo ==========================================================================
+echo  B1) init with an explicit path - guarantees we reach the key step
+echo ==========================================================================
+if exist "%DATA%" (
+  node dist\bin\weflow-cli.js init --path "%DATA%"
+) else (
+  echo   [WARN] %DATA% not found - running init without a path instead
+  node dist\bin\weflow-cli.js init
+)
+echo.
+echo --------------------------------------------------------------------------
+echo  B2) init again WITHOUT a path - does auto-discovery still work?
+echo --------------------------------------------------------------------------
+node dist\bin\weflow-cli.js init
+echo.
+
+echo ==========================================================================
+echo  C) sessions - should point you at check --report
+echo ==========================================================================
+node dist\bin\weflow-cli.js sessions
+echo.
+
+echo ==========================================================================
+echo  D) check --report - should blame Python, NOT the WeChat version
+echo ==========================================================================
+node dist\bin\weflow-cli.js check --report
+echo.
+
+echo ==========================================================================
+echo  DONE.
+echo    - If every section matches what you expected, the bug is fixed.
+echo    - Otherwise send a screenshot of this window (or the lines that differ).
+echo    - Close this window when done: HOME/PATH were changed inside it only.
+echo ==========================================================================
+pause

package/scripts/semantic_search.py

@@ -344,6 +344,10 @@ def collect_articles(article_days=30):
                             break
                     # 有 `## 正文` 就用它（最精确的标记）；没有就按真实结构取正文，
                     # 不再退回到 YAML 头 —— 那正是"文章线只能靠标题排"的原因。
+                    # 索引这一路**只用日报 md 那份**（`## 正文` 标记优先，否则按真实结构提取）。
+                    # 2026-10-16 试过改成「与正文缓存取更长的那份」，实测**没有增益**（DECISIONS D-118）：
+                    # 100 条自造题里唯一中立的一组（标题）持平；两组碎片题各自跟着「题是从谁的文本里
+                    # 抠的」走，方向相反 —— 自造题裁判不了这件事。正文缓存留给 `--with-text`，索引不吃它。
                     body = ('\n'.join(lines[body_start:body_start + 50]) if body_start
                             else extract_article_body(content))
                     if title:
@@ -622,6 +626,13 @@ def build_rerank_questions(count):
 # 原来的写法里"重排失败"只往 stderr 打一行 WARN，而 CLI 不转发子进程 stderr，
 # 于是"没报错"会被读成"重排过了"。状态放这里，主流程把它塞进 JSON。
 RERANK_STATE = {'provider': None, 'degraded': False, 'error': None, 'scored': 0}
+# 向量那条腿这次到底跑了没有、没跑是为什么、以及顺手算出的每线条数（省一次 13.5 MB 的解析）。
+# 与 `RERANK_STATE` 同一个形状：`search()` 开头重置、`main()` 把它带进返回的 envelope。
+#
+# 为什么要这个：`search()` 原来有一个**裸 `except: pass`**，于是"向量路径任何异常"都会变成
+# "静默只搜关键词"，而返回里照样写着 `hybrid: true` —— 这是最难看出来的一种失效，
+# 也让所有"快慢/好坏"的对比都可能落在不同路径上（2026-10-18 审阅时确认）。
+VECTOR_STATE = {'used': False, 'fallback': None, 'counts': None}
 
 _RERANK_LLM_RUBRIC = (
     '给每条候选打 0-100 分，判据是**它是否直接回答了问题**（"话题相近"不算）：'
@@ -720,11 +731,16 @@ def rerank_dispatch(query, results, client=None, pool_size=RERANK_CANDIDATES):
 
     两个都失败时返回原序，并把 `RERANK_STATE` 留在"降级"上 —— 别让"没重排"看起来像"重排过了"。
     """
-    RERANK_STATE.update(provider=None, degraded=False, error=None, scored=0)
+    RERANK_STATE.update(provider=None, degraded=False, error=None, scored=0, transport=None)
     if client is not None:
         out = rerank(query, results, client, pool_size=pool_size)
+        # **`provider` 记的是"哪套契约"**（`typesafe`），不是"谁在服务"：`judgeProvider=chat` 时
+        # 契约是由 DeepSeek 类客户端满足的，只看 `provider` 会读成"原生通了"（2026-10-18 实测踩到：
+        # 同一批查询里有时 provider=typesafe 其实走的是 deepseek-flash）。所以再记一个 `transport`。
+        RERANK_STATE['transport'] = getattr(client, 'provider', 'typesafe')
         if not RERANK_STATE['degraded'] and RERANK_STATE['scored']:
             return out
+    RERANK_STATE['transport'] = 'llm'
     return llm_rerank(query, results, pool_size=pool_size)
 def rerank(query, results, client=None, pool_size=RERANK_CANDIDATES):
     """用**一次**决策请求给检索结果重排。
@@ -1037,6 +1053,39 @@ def _fetch_body(url):
 
 FULL_TEXT_LIMIT = 4000          # `--with-text` 默认给多少字（够一篇公众号全文）
 
+_FETCH_CACHE_DIR_NAME = ('.cache', 'fetch')
+
+
+def _fetch_cache_path(url):
+    return Path(OUTPUT_ROOT) / '.cache' / 'fetch' / (hashlib.md5(url.encode('utf-8')).hexdigest() + '.md')
+
+
+def best_article_body(content, limit=None, md_body=None):
+    """**展示路径**用：文章正文取**更长的那份** —— 日报 md，或它旁边那份正文缓存。
+
+    日报 md 里正文中位只有 259 汉字，而日报**自己抓到的**完整正文缓存里是 2,063 汉字 ——
+    内容早就抓回来了，只写进 md 一小段。`--with-text` 要给人看的那份，所以取全的。
+    ⚠️ **建索引不用这个函数**:实测吃完整正文对检索没有增益（DECISIONS D-118），
+    索引只吃 md 那份摘录（`collect_articles` 里 500 字）。
+    返回 `(body, url)`；url 从 frontmatter 取，取不到就是 None（那时只能用 md 那份）。
+    `md_body` 由调用方给时就用它（例如调用方已按自己的规则切出正文 —— 调用方的切法优先）。
+    """
+    body = (md_body if md_body is not None
+            else extract_article_body(content, limit or FULL_TEXT_LIMIT))
+    url = None
+    match = re.search(r'^url:\s*"?([^"\n]+)"?', content, re.M)
+    if match:
+        url = match.group(1).strip()
+        cached = _fetch_cache_path(url)
+        if cached.exists():
+            try:
+                full = cached.read_text(encoding='utf-8', errors='replace').strip()
+                if len(full) > len(body):
+                    body = full
+            except OSError:
+                pass                      # 读不了缓存就当没有，别让这一篇失败
+    return (body[:limit] if limit else body), url
+
 
 def load_record_text(item, limit=FULL_TEXT_LIMIT):
     """把命中的记录还原成本地那份**正文** —— 索引里存的只是"用来匹配的摘录"。
@@ -1062,22 +1111,7 @@ def load_record_text(item, limit=FULL_TEXT_LIMIT):
     except OSError:
         return None, str(path), None
 
-    url = None
-    match = re.search(r'^url:\s*"?([^"\n]+)"?', content, re.M)
-    if match:
-        url = match.group(1).strip()
-
-    body = extract_article_body(content, limit)
-    if url:
-        cached = Path(OUTPUT_ROOT) / '.cache' / 'fetch' / (
-            hashlib.md5(url.encode('utf-8')).hexdigest() + '.md')
-        if cached.exists():
-            try:
-                full = cached.read_text(encoding='utf-8', errors='replace').strip()
-                if len(full) > len(body):      # 缓存那份才是完整正文
-                    body = full[:limit]
-            except OSError:
-                pass
+    body, url = best_article_body(content, limit)
     return readable_body(body), str(path), url
 
 
@@ -1108,6 +1142,165 @@ def attach_full_text(results, limit=FULL_TEXT_LIMIT, fetch_missing=0):
     return results, missing, fetched
 
 
+# ===== 精确短语定位（D-121）=====
+#
+# **为什么单独有一条腿**：现有两条腿都是"相似"——bigram+BM25 按词项计分、向量按语义近似。
+# 于是"哪个号在哪天**原样**写过这句话"这类问句（专有名词、代码名、政策原文、引文核对）
+# 它们答不了，也不该硬答：把"查不到原样"混进相似度排序里，用户看不出区别。
+#
+# 实现用 SQLite **FTS5 + trigram**，标准库自带的，不需要新依赖。四个实测结论决定了这个形状
+# （2026-10-17 本机 sqlite 3.45.1，8 次探针）：
+#   1. 默认分词 `unicode61` 对中文**完全不可用**（整句一个 token：`沙箱逃逸` 命中 0）⇒ 必须 trigram；
+#   2. trigram 是**连续子串**匹配，不是词项 AND（`光伏补贴政策` 只命中原样连续的，
+#      而 `补贴政策` 命中"的补贴政策"/"补贴政策解读"）⇒ 正好是"原样定位"要的语义，
+#      也正是它**不能**替我们那条关键词腿的原因（那条要的是"分开出现也能排上分"）；
+#   3. trigram 有 **3 字下限**：`光伏`（2 字）恒空 ⇒ 短查询必须**明说**，绝不能回报"0 命中"；
+#   4. 查询里的标点会被当**语法**（`PM2.5` → `syntax error near "."`、`GPT-4` → `no such column: 4`）
+#      ⇒ 整串加引号当字面量（内部 `"` 翻倍）；加引号后 `PM2.5`/`C++`/`GPT-4` 全部正常，
+#      且 ASCII 大小写不敏感（`"pm2.5"` 能命中 `PM2.5`）。全角/半角不互认。
+#
+# **语料只从 `meta.json` 来**（语义索引的记录清单）：再写一套记录枚举，两个索引的语料迟早分叉，
+# 而"两个索引覆盖的不是同一批"这种错不会报，只会让结果看起来少。
+PHRASE_INDEX_DIR = Path(OUTPUT_ROOT) / '.phrase_index'
+PHRASE_DB = PHRASE_INDEX_DIR / 'phrase.sqlite'
+PHRASE_MIN_CHARS = 3
+PHRASE_TEXT_LIMIT = FULL_TEXT_LIMIT
+
+
+def escape_phrase(query):
+    """把整串当**字面量**（而不是 FTS 语法）：外层加引号，内部 `"` 翻倍。"""
+    return '"' + str(query or '').replace('"', '""') + '"'
+
+
+def phrase_chars(query):
+    """"有效字符数"：去掉所有空白再数。trigram 的下限按字符算，空格不参与。"""
+    return len(''.join(str(query or '').split()))
+
+
+def _phrase_label(item):
+    """「哪个号」：文章取文件名里第一个 `-` 前那段（`<账号>-<标题>.md`），聊天取会话名。
+
+    与 `--from` 的口径保持一致：那条路也是靠 `id`（文件名）里含账号名来找号的
+    （2026-10-15 修正文提取时 `source:` 随 YAML 头离开了嵌入文本，见 `search()` 里的注释）。
+    """
+    if str(item.get('type')) == 'chat':
+        return str(item.get('talker') or '')
+    rid = str(item.get('id') or '')
+    stem = rid.split(':', 1)[-1].replace('\\', '/').rsplit('/', 1)[-1]
+    if stem.endswith('.md'):
+        stem = stem[:-3]
+    return stem.split('-', 1)[0] if '-' in stem else stem
+
+
+def build_phrase_index(line: str = 'all', db_path=None, meta_path=None):
+    """从 `meta.json` **全量重建**短语索引（不调用任何模型，所以重建便宜到可以每次都全量）。
+
+    返回 `{'records', 'byLine', 'textMissing', 'db', 'bytes'}`；没有语义索引时返回 error ——
+    它是**派生**产物，不自己去找语料。
+    """
+    import sqlite3
+    meta_file = Path(meta_path or META_FILE)
+    if not meta_file.exists():
+        return {'error': '还没有语义索引，短语索引由它派生',
+                'hint': 'weflow-cli search-index --yes'}
+    meta = json.loads(meta_file.read_text(encoding='utf-8'))
+    types = line_types(line)
+    rows = []
+    text_missing = 0
+    by_line = {}
+    for item in meta:
+        if types is not None and str(item.get('type') or '') not in types:
+            continue
+        text, _source_file, _url = load_record_text(item, PHRASE_TEXT_LIMIT)
+        if not text:
+            # 读不到正文（md 被删/移动）：退回索引里那段摘录，并**数出来**告诉用户，
+            # 而不是让这篇悄悄从短语索引里消失。
+            text = item.get('text') or ''
+            text_missing += 1
+        if not text:
+            continue
+        key = str(item.get('type') or '')
+        by_line[key] = by_line.get(key, 0) + 1
+        rows.append((text, str(item.get('id') or ''), key, _phrase_label(item),
+                     str(item.get('date') or item.get('time') or ''),
+                     str(item.get('title') or '')))
+    path = Path(db_path or PHRASE_DB)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    try:
+        conn.execute('DROP TABLE IF EXISTS hits')
+        conn.execute("CREATE VIRTUAL TABLE hits USING fts5("
+                     "body, rid UNINDEXED, line UNINDEXED, label UNINDEXED,"
+                     " date UNINDEXED, title UNINDEXED, tokenize='trigram')")
+        conn.executemany('INSERT INTO hits(body, rid, line, label, date, title)'
+                         ' VALUES (?, ?, ?, ?, ?, ?)', rows)
+        conn.commit()
+        conn.execute('VACUUM')
+    finally:
+        conn.close()
+    return {'records': len(rows), 'byLine': by_line, 'textMissing': text_missing,
+            'line': line, 'db': str(path), 'bytes': path.stat().st_size}
+
+
+def _phrase_where(line, from_source):
+    """拼过滤条件。**与向量那条路同一口径**：`--from` 按 `id` 子串或标签精确匹配。"""
+    clauses, params = [], []
+    if line_types(line) is not None:
+        clauses.append('line IN (%s)' % ','.join('?' * len(sorted(line_types(line)))))
+        params.extend(sorted(line_types(line)))
+    if from_source:
+        want = from_source.strip().lower()
+        clauses.append('(lower(rid) LIKE ? OR lower(label) = ?)')
+        params.extend(['%' + want + '%', want])
+    return (' AND ' + ' AND '.join(clauses) if clauses else ''), params
+
+
+def phrase_search(query, limit: int = 20, line: str = 'all', from_source: str = None,
+                  db_path=None, group_limit: int = 20):
+    """原样定位：返回命中行 + 按（账号/会话 × 日期）的分组。
+
+    **两条不许静默**：查不到索引 → 报错并给建索引的命令；查询短于下限 → 明说"查不了"
+    （而不是 0 命中）。把这两种说成"没有"是这条腿最坏的失效方式。
+    """
+    import sqlite3
+    path = Path(db_path or PHRASE_DB)
+    result = {'query': query, 'escaped': escape_phrase(query), 'line': line,
+              'from': from_source, 'total': 0, 'hits': [], 'groups': []}
+    if not path.exists():
+        result.update({'error': '短语索引还没建',
+                       'hint': 'weflow-cli search-index --phrase（本地、不花钱）'})
+        return result
+    chars = phrase_chars(query)
+    if chars < PHRASE_MIN_CHARS:
+        result.update({'tooShort': True, 'chars': chars, 'minChars': PHRASE_MIN_CHARS,
+                       'note': 'trigram 分词有 %d 字下限，更短的串它切不出任何词项 —— '
+                               '这里**不报"0 命中"**，因为那是把"查不了"说成"没有"'
+                               % PHRASE_MIN_CHARS})
+        return result
+    where, params = _phrase_where(line, from_source)
+    conn = sqlite3.connect(str(path))
+    try:
+        total = conn.execute('SELECT count(*) FROM hits WHERE hits MATCH ?' + where,
+                             [result['escaped']] + params).fetchone()[0]
+        result['total'] = total
+        for label, day, n in conn.execute(
+                'SELECT label, substr(date, 1, 10) AS day, count(*) AS n FROM hits '
+                'WHERE hits MATCH ?' + where +
+                ' GROUP BY label, day ORDER BY n DESC, day DESC LIMIT ?',
+                [result['escaped']] + params + [group_limit]):
+            result['groups'].append({'label': label, 'date': day, 'count': n})
+        for rid, kind, label, date, title, ctx in conn.execute(
+                'SELECT rid, line, label, date, title, '
+                "snippet(hits, 0, '【', '】', '…', 14) FROM hits "
+                'WHERE hits MATCH ?' + where + ' ORDER BY date DESC LIMIT ?',
+                [result['escaped']] + params + [limit]):
+            result['hits'].append({'id': rid, 'type': kind, 'label': label,
+                                   'date': date, 'title': title, 'context': ctx})
+    finally:
+        conn.close()
+    return result
+
+
 def search(query: str, api_key: str, top_k: int = 10, rerank_results: bool = True,
            line: str = 'all', hybrid: bool = True, from_source: str = None,
            rerank_pool: int = RERANK_CANDIDATES,
@@ -1124,6 +1317,9 @@ def search(query: str, api_key: str, top_k: int = 10, rerank_results: bool = Tru
     "静默少搜一半"——后者在这个仓库里是最贵的那类 bug。
     """
     types = line_types(line)   # 认不出的线在这里就报错，不静默当 all
+    VECTOR_STATE.update(used=False, fallback=None, counts=None)
+    # `--mmr` 在 fallback 里也要用 `vectors`；只在 try 里赋值会让它**未绑定**（NameError）。
+    vectors = None
     # Try embedding-based search first
     if VECTORS_FILE.exists() and META_FILE.exists():
         try:
@@ -1138,6 +1334,8 @@ def search(query: str, api_key: str, top_k: int = 10, rerank_results: bool = Tru
                 meta = meta[:rows]
             elif rows < int(vectors.shape[0]):
                 vectors = vectors[:rows]
+            # 顺手把每线条数算掉：`main()` 原来会再解析一遍同一份 meta（69 + 56 ms/次）
+            VECTOR_STATE['counts'] = _counts_from_meta(meta)
             query_embeddings = get_embeddings([query], api_key)
             if query_embeddings and not all(v == 0 for v in query_embeddings[0]):
                 query_vec = np.array(query_embeddings[0], dtype=np.float32)
@@ -1193,9 +1391,17 @@ def search(query: str, api_key: str, top_k: int = 10, rerank_results: bool = Tru
                     results = mmr_select(results, vectors, top_k)
                 for _item in results:                 # `_row` 只是内部用的，别漏进输出
                     _item.pop('_row', None)
+                VECTOR_STATE['used'] = True
                 return results[:top_k]
-        except:
-            pass
+        except Exception as error:
+            # **显式降级**，原因留下来。原来是裸 `except: pass`：向量路径任何异常都会变成
+            # "静默只搜关键词"，而返回里照样写着 `hybrid: true` —— 那是最难看出来的一种失效，
+            # 也让"快慢/好坏"的对比可能落在不同路径上。另外裸 except 会吞掉 KeyboardInterrupt。
+            VECTOR_STATE['fallback'] = '%s: %s' % (type(error).__name__, error)
+
+    if not VECTOR_STATE['used'] and VECTOR_STATE['fallback'] is None:
+        # 没异常也没返回 —— 最常见的原因是 embedding 拿到空/全零（上游失败）。
+        VECTOR_STATE['fallback'] = '未做向量检索（embedding 为空或全零）'
 
     # Fallback: keyword search
     results = keyword_search(query, max(top_k, RERANK_CANDIDATES) if rerank_results else top_k,
@@ -1209,7 +1415,8 @@ def search(query: str, api_key: str, top_k: int = 10, rerank_results: bool = Tru
     if with_text:
         results, _missing, _fetched = attach_full_text(results, with_text,
                                                       fetch_missing=fetch_missing)
-    if mmr:
+    if mmr and vectors is not None:
+        # 向量没拿到时**不能**做 MMR（它需要矩阵）；以前这里会 NameError。
         results = mmr_select(results, vectors, top_k)
     for _item in results:                 # `_row` 只是内部用的，别漏进输出
         _item.pop('_row', None)
@@ -1230,6 +1437,17 @@ def line_counts() -> dict:
         meta = json.loads(META_FILE.read_text(encoding='utf-8'))
     except Exception:
         return counts
+    return _counts_from_meta(meta)
+
+
+def _counts_from_meta(meta) -> dict:
+    """从**已经解析好**的 meta 算每线条数（`line_counts` 与 `search()` 共用这一份）。
+
+    抽出来是让 `search()` 复用自己刚解析的那份：它原来在返回之后又被 `main()` 调
+    `line_counts()` **再解析一遍**同一个 13.5 MB 文件（实测 69 + 56 ms）。两份实现分开
+    写更糟 —— 两处解析同一份文件迟早会漂，而漂的表现是"条数对不上但谁都不报错"。
+    """
+    counts = {line: 0 for line in LINE_CHOICES}
     for item in meta:
         t = str(item.get('type', ''))
         for line, types in LINE_TYPES.items():
@@ -1295,6 +1513,13 @@ def main():
                    help='不融合本地 BM25 名次（默认融合：加门控后实测三个台子都只增不减）')
     p.add_argument('--from', dest='from_source',
                    help='只查某个公众号（按 id/文件名的子串匹配，不走语义）')
+    p.add_argument('--phrase', action='store_true',
+                   help='把这串当**原样短语**在本地定位（FTS5/trigram；不走向量、不出境、不花钱）：'
+                        '回答"哪个号在哪天原样写过它"。查不到原样不等于查不到语义，收窄了问题范围')
+
+    pp = subparsers.add_parser('phrase-build',
+                               help='构建/重建精确短语索引（本地，不调用任何模型）')
+    add_line_arg(pp)
 
     add_line_arg(p)
 
@@ -1304,17 +1529,49 @@ def main():
     if getattr(args, 'days', 90) < 1 or getattr(args, 'article_days', 30) < 1:
         json_output({'error': '--days 与 --article-days 都要 ≥ 1（0 天等于索引一个空库）'})
         return
-    config = load_config()
-    api_key = args.api_key or os.environ.get('DASHSCOPE_API_KEY', '') or get_dashscope_key(config)
+    # 读不到配置不该让**不需要配置**的子命令崩：`phrase-build` 与 `search --phrase` 只读本地索引，
+    # 它们没有任何理由要求 `~/.weflow-cli/config.json` 存在（CI 上没有那个文件、本地有，于是这条
+    # 会"本地绿、CI 红"）。需要 key 的那条路会在下面自己报"缺 key"。
+    try:
+        config = load_config()
+    except Exception:
+        config = {}
+    # `getattr`：不是每个子命令都有 `--api-key`（`phrase-build` 不需要 key —— 它不调模型）。
+    # 无条件读会让"建本地短语索引"直接崩在一个**与它无关**的参数上。
+    api_key = (getattr(args, 'api_key', '') or os.environ.get('DASHSCOPE_API_KEY', '')
+               or get_dashscope_key(config))
 
     if args.command == 'build':
         result = build_index(api_key, full=args.full, days=args.days, article_days=args.article_days)
     elif args.command == 'update':
         result = build_index(api_key, full=False, days=args.days, article_days=args.article_days)
+    elif args.command == 'phrase-build':
+        result = build_phrase_index(line=args.line)
+        result['success'] = 'error' not in result
     elif args.command == 'search':
         query = args.query or os.environ.get('WEFLOW_SEARCH_QUERY', '')
         if not query:
             result = {"error": "missing search query"}
+        elif args.phrase:
+            # 原样定位：**本地、无 key、不出境**。所以它不校验 `api_key`，
+            # 也不该被当成"向量搜索的降级版"——两者问的是不同的问题。
+            # 向量检索的那些旗标在这条路上不生效。CLI 会直接拒绝这种组合；这里兜住
+            # **直接调脚本**的人：静默忽略会让人把默认行为当成"调过的结果"。
+            ignored_flags = [name for name, on in (
+                ('--mmr', getattr(args, 'mmr', False)),
+                ('--no-rerank', getattr(args, 'no_rerank', False)),
+                ('--no-hybrid', getattr(args, 'no_hybrid', False)),
+                ('--no-dedup', getattr(args, 'no_dedup', False)),
+                ('--with-text', getattr(args, 'with_text', 0)),
+                ('--fetch-missing', getattr(args, 'fetch_missing', 0)),
+                ('--rerank-pool', getattr(args, 'rerank_pool', RERANK_CANDIDATES) != RERANK_CANDIDATES),
+            ) if on]
+            if ignored_flags:
+                print('[WARN] --phrase only locates verbatim text; ignored: %s'
+                      % ', '.join(ignored_flags), file=sys.stderr)
+            result = phrase_search(query, limit=args.top_k, line=args.line,
+                                   from_source=args.from_source)
+            result['success'] = 'error' not in result
         else:
             # **输出带上是哪条线**（`--line` 默认文章线）。少了这一层，`--line chat`
             # 空成一片时读的人分不清"没命中"和"这条线根本没进索引"——而两者的下一步
@@ -1325,14 +1582,19 @@ def main():
                           rerank_pool=args.rerank_pool,
                           dedup=not args.no_dedup,
                           with_text=args.with_text,
-                          fetch_missing=args.fetch_missing,
+                          fetch_missing=args.fetch_missing,
                           mmr=args.mmr)
-            counts = line_counts()
+            # `search()` 本来就解析过 meta，顺手把每线条数算在 `VECTOR_STATE['counts']` 里；
+            # 只有它没算（走了关键词 fallback）时才重新解析。省掉一次 13.5 MB 的解析。
+            counts = VECTOR_STATE.get('counts') or line_counts()
             result = {
                 'success': True,
                 'line': args.line,
                 'lineLabel': line_label(args.line),
                 'hybrid': not args.no_hybrid,
+                # **这次到底走没走向量**：没走时把原因写出来。缺了它，"只搜到关键词结果"
+                # 与"关键词结果就是这样"在返回里长得一模一样。
+                'vector': {'used': VECTOR_STATE['used'], 'fallback': VECTOR_STATE['fallback']},
                 'rerank': dict(RERANK_STATE),
                 'from': args.from_source,
                 'dedup': not args.no_dedup,

package/src/core/dbPathService.ts

@@ -70,6 +70,11 @@ export class DbPathService {
     return [
       '$recycle.bin', 'node_modules', 'windows', 'program files',
       'program files (x86)', 'programdata', 'system volume information',
+      // 临时目录不是微信数据的合理位置，但**测试夹具**就建在这下面
+      // （`%LOCALAPPDATA%\Temp\weflow-custom-nt-*\xwechat_files`）。不排除的话，
+      // 空配置下的"自动发现"会把一个测试残留当成用户的微信目录 ——
+      // 2026-10-19 模拟新用户时实测命中，然后一路对着假数据初始化。
+      'temp', 'tmp',
     ].includes(name.toLowerCase())
   }
 

package/src/core/ntCore.ts

@@ -21,6 +21,17 @@ function getPackageRoot(): string {
   return resolvePackageRoot(import.meta.url)
 }
 
+/**
+ * `scan` 的执行器。默认就是真的 `execFile`；测试注入假执行器来钉住**错误映射**。
+ *
+ * 为什么需要这个口子：Windows 上"找不到命令"的表现是子进程以 **9009** 退出，
+ * 而它没有可移植的造假方式（要有真 exe / 真 shell 行为，Linux CI 上做不出来）。
+ * 少了这条测试，`9009` 那段用户提示就会在以后的改动里悄悄退回
+ * `NT scan failed (exit 9009)` —— 2026-10-18 那位用户卡住时看到的就是这句。
+ */
+export type NtExecRunner =
+  (file: string, args: string[], options: Record<string, unknown>) => Promise<{ stdout: string }>
+
 export interface NtResult {
   success: boolean
   error?: string
@@ -191,11 +202,11 @@ export class NtCore {
    * Scan memory for NT keys and match to databases.
    * Requires WeChat to be running.
    */
-  static async scan(root?: string): Promise<NtScanResult> {
+  static async scan(root?: string, run: NtExecRunner = execFileAsync as unknown as NtExecRunner): Promise<NtScanResult> {
     try {
       const scriptPath = join(getPackageRoot(), 'scripts', 'nt_decrypt.py')
       const scanArgs = ['scan', '--json']
-      const { stdout } = await execFileAsync(getPythonCommand(), [scriptPath, ...scanArgs], {
+      const { stdout } = await run(getPythonCommand(), [scriptPath, ...scanArgs], {
         timeout: 300_000,
         maxBuffer: 10 * 1024 * 1024,
         env: createPythonProcessEnv(root ? { WEFLOW_SCAN_ROOT: root } : {}),
@@ -234,7 +245,27 @@ export class NtCore {
       return { success: false, error: 'Scan produced no valid output' }
     } catch (e: any) {
       if (e?.code === 'ENOENT') {
-        return { success: false, error: 'Python not found. Install Python and add to PATH.' }
+        // 与 9009 那条**同一件事、同一句话**：一条是"命令名解析不到"，一条是"解析到了但跑不起来"，
+        // 对用户来说都是"这台机器没有可用的 Python"。以前这里留的是英文
+        // `Python not found. Install Python and add to PATH.`，于是同一个 init 里
+        // 上面刚用中文解释完"商店占位程序"，下面又冒出一句英文（2026-10-19 实测）。
+        return {
+          success: false,
+          error: '没有可用的 Python：NT 扫描需要 Python 3.10+ 且能 `import sqlcipher3`。'
+            + '在终端里运行 `python --version`，能打出版本号才算装对',
+        }
+      }
+      if (e?.code === 9009) {
+        // Windows 的 9009 是"找不到命令"。最常见的原因是 PATH 上只有**微软商店的 python
+        // 占位程序**：`getPythonCommand()` 在所有候选都不过（没有真 Python / 没有 sqlcipher3）
+        // 时兜底返回裸名 `python`，正好交给那个占位程序，它一跑就以 9009 退出。
+        // 不把这条翻译出来，用户看到的是"NT scan failed (exit 9009)"，而下一步该做什么完全没有线索
+        // （2026-10-18 一位用户就是这么卡住的）。
+        return {
+          success: false,
+          error: '没有可用的 Python：NT 扫描需要 Python 3.10+ 且能 `import sqlcipher3`。'
+            + 'exit 9009 在 Windows 上通常意味着只装了商店的 python 占位程序，装一个真正的 Python 后重试',
+        }
       }
       return { success: false, error: safeSubprocessError(e, 'NT scan failed') }
     }