weflow-cli 1.11.0 → 1.12.0

package/scripts/export_chat_html.py

@@ -14,6 +14,7 @@ import re
 import base64
 import urllib.request
 import urllib.error
+import urllib.parse
 import concurrent.futures
 import shutil
 import struct
@@ -110,10 +111,13 @@ _FILE_ASSET_SUBDIR = 'files'
 # 文档那半的计数（图片那半的计数在写盘时现算）。放在模块级是为了不改 `write_assets` 的返回形状 ——
 # 它已经有两个调用方（markdown 导出与 `--media`），与 COVER_STATE/VOICE_STATE 是同一套写法。
 #
-# `exported` 与 `written` 是两件事：`written` 只数**这次新拷**的，`exported` 数"这条消息的文档确实在
-# assets 里"。分开是因为第二次跑同一个目录时新拷贝是 0 —— 只报 `written` 会打印成"0 document(s)"，
-# 而实际上 67 份都在，那是给自己制造假象（2026-10-13 真的这么打印过一次）。
-FILE_ASSET_STATE = {'exported': 0, 'written': 0, 'unavailable': 0}
+# **三个词各管一件事，别混**（媒体状态统一后，报告/清单/JSON 三处都按这套说法）：
+#   `written`     = 现在躺在导出目录里的份数（"可用数"，同一目录跑第二遍时它不为 0）
+#   `copied`      = **这一轮**新拷进去的份数（第二遍跑就是 0）
+#   `unavailable` = 没能落盘的份数（本地没有那份文件 / 太大 / 拷贝失败）
+# 分开是因为只报 `copied` 会把第二遍打印成"0 document(s)"，而实际上 67 份都在 —— 那是给自己制造
+# 假象（2026-10-13 真这么打印过一次）。
+FILE_ASSET_STATE = {'written': 0, 'copied': 0, 'unavailable': 0}
 
 # Off by default: full-resolution originals are 5-24MB / 3000-5700px each, and
 # downscaling ~500 of them costs minutes (PIL decode dominates). The cache's
@@ -539,6 +543,10 @@ def scan_account_file_index(account_dir):
             except OSError:
                 continue
             index.setdefault((normalize_asset_name(fname), size), []).append(path)
+    # 排序是为了**可复现**：多候选且消息没带 md5 时取 `[0]`，而 `os.walk` 的顺序不保证稳定 ——
+    # 不排的话，同一次导出在两台机器上可能落到不同名字的副本上。
+    for paths in index.values():
+        paths.sort()
     return index
 
 
@@ -2140,10 +2148,15 @@ def build_media_record(local_type, image_b64, image_map, local_id, create_time,
     if file_info is not None:
         # 文档本体（appmsg type 6）走的是另一条路：没有缩略图、也不在图片索引里，能不能导出只看
         # 本地 `msg/file/` 有没有那份文件。不并入图片那条链，否则报告会把"文件没下载"写成"没有可靠标识"。
+        #
+        # 状态词是 `found` 而**不是** `exported`：这份报告是在**写 assets 之前**生成的，它答的是
+        # "能不能在源数据里定位到"（`found` / `missing`），答不了"有没有写进导出目录"。
+        # 后者由清单的 `documents.written` 回答（`write_assets` 写的）。两件事用两个词，
+        # 免得"这份文件已导出"这种话在拷贝失败时变成假的。
         record['kind'] = 'file'
         record['bytes'] = file_info.get('bytes') or None
         if file_hit:
-            record['status'] = 'exported'
+            record['status'] = 'found'
             record['mediaKey'] = 'file'
         else:
             record['status'] = 'missing'
@@ -2448,19 +2461,77 @@ p {{ margin:8px 0; font-size:14px; }}
 </html>'''
 
 
+_WINDOWS_RESERVED_NAMES = frozenset(
+    ['con', 'prn', 'aux', 'nul']
+    + ['com%d' % index for index in range(1, 10)]
+    + ['lpt%d' % index for index in range(1, 10)])
+
+
+def _clean_asset_component(text):
+    """把一段文件名清洗到"任何 Windows 上都能创建"。
+
+    在 `sanitize_filename` 之外多管一件会**静默改结果**的事：首尾的空白与点（Windows 会把 `a .` 存成 `a`，
+    于是清单里的名字和磁盘上的名字对不上）。
+    """
+    return sanitize_filename(text).strip().strip('.')
+
+
 def _asset_file_name(title, used_names, source, md5):
     """落盘的文档文件名：保持原样（只清洗非法字符），重名才加 md5 前 8 位。
 
     不改名是刻意的 —— 那是用户自己的文件名，读者要靠它认东西；微信自己也会加 `(1)`。但两个不同来源
     的文件可能同名，那种情况必须区分，否则后来者会覆盖先到者、清单指错文件。
+
+    **截断要在扩展名之前**：真机实测过一个超长标题，80 字符上限把 `.pdf` 一起切掉了，落盘成没有扩展名的
+    文件 —— 系统与编辑器都不知道该用什么打开它。
     """
-    safe = sanitize_filename(title).strip().strip('.') or 'file'
+    stem, ext = os.path.splitext(str(title or ''))
+    # 扩展名单独保留（也过一遍清洗），但不参与"给主干剩下的额度"；异常长的"扩展名"当没扩展名处理
+    ext = _clean_asset_component(ext).replace('.', '')
+    if len(ext) > 16:
+        stem, ext = str(title or ''), ''
+    stem = _clean_asset_component(stem)
+    room = max(1, 80 - (len(ext) + 1 if ext else 0))
+    base = stem[:room] or 'file'
+    if base.lower() in _WINDOWS_RESERVED_NAMES:
+        # `CON.pdf` 这类在 Windows 上打不开（会被当成设备名）—— 加个前缀就正常了
+        base = '_' + base
+    safe = base + ('.' + ext if ext else '')
     if used_names.get(safe) in (None, source):
         return safe
     stem, ext = os.path.splitext(safe)
     return '%s_%s%s' % (stem, (md5 or 'copy')[:8], ext)
 
 
+def _load_existing_manifest(manifest_path, out_dir):
+    """读回同目录里已有的清单条目（v1 的裸字符串也认），丢掉**已经不在磁盘上**的那些。
+
+    为什么不是直接覆盖：清单住在 `<会话>_assets/` 这个**共享**目录里，而导出可以分批做
+    （`--limit 200` 一次、整段再一次；md 一次、`json --media` 再一次）。覆盖会让窄窗口那次的清单把宽窗口
+    那次的条目**删掉**，而 md 正文里的链接还在 —— 之后任何"读清单带媒体"的导出都会少一批，
+    且两边都不报错。2026-10-13 真机就是这么撞上的：整段导出的 585 条被 `--limit 600` 那次的 150 条盖掉。
+    """
+    try:
+        with open(manifest_path, 'r', encoding='utf-8') as handle:
+            data = json.load(handle)
+    except (OSError, ValueError):
+        return {}
+    messages = data.get('messages') if isinstance(data, dict) else None
+    if not isinstance(messages, dict):
+        return {}
+    kept = {}
+    for key, value in messages.items():
+        if isinstance(value, str):
+            record = {'path': value, 'kind': 'image'}
+        elif isinstance(value, dict) and isinstance(value.get('path'), str):
+            record = value
+        else:
+            continue
+        if os.path.isfile(os.path.join(out_dir, record['path'].replace('/', os.sep))):
+            kept[key] = record
+    return kept
+
+
 def write_assets(out_dir, file_prefix, formatted, assets_dir=''):
     """把媒体**落盘**并把 `manifest.json` 写好；返回 `(assets 目录名, manifest, 新写文件数)`。
 
@@ -2477,7 +2548,9 @@ def write_assets(out_dir, file_prefix, formatted, assets_dir=''):
     assets = assets_dir or os.path.join(out_dir, file_prefix + '_assets')
     os.makedirs(assets, exist_ok=True)
 
-    manifest = {}
+    # 与已有清单**合并**：分批导出时，窄窗口那一次不该把宽窗口那次的条目删掉（见 `_load_existing_manifest`）。
+    manifest_path = os.path.join(assets, 'manifest.json')
+    manifest = _load_existing_manifest(manifest_path, out_dir)
     written = 0
     for item in formatted:
         blob = item.get('image_b64')
@@ -2502,7 +2575,6 @@ def write_assets(out_dir, file_prefix, formatted, assets_dir=''):
             'kind': 'image',
         }
 
-    file_exported = 0
     file_written = 0
     file_unavailable = 0
     files_dir = os.path.join(assets, _FILE_ASSET_SUBDIR)
@@ -2526,13 +2598,18 @@ def write_assets(out_dir, file_prefix, formatted, assets_dir=''):
                                 info.get('md5'))
         target = os.path.join(files_dir, name)
         if used_names.get(name) != source:
-            os.makedirs(files_dir, exist_ok=True)
-            if not os.path.exists(target):
-                with open(target, 'wb') as dst, open(source, 'rb') as src:
-                    shutil.copyfileobj(src, dst)
-                file_written += 1
+            try:
+                os.makedirs(files_dir, exist_ok=True)
+                if not os.path.exists(target):
+                    with open(target, 'wb') as dst, open(source, 'rb') as src:
+                        shutil.copyfileobj(src, dst)
+                    file_written += 1
+            except OSError:
+                # 一个文件拷不进去（名字太怪、路径过长、目标被占用）不能让**整次导出**在最后一步崩掉 ——
+                # 前面几分钟的解析与图片抽取都在，代价只是这一份文档缺失，且它会计入 unavailable。
+                file_unavailable += 1
+                continue
         used_names[name] = source
-        file_exported += 1
         manifest['%s:%s' % (item.get('local_id'), item.get('create_time'))] = {
             'path': os.path.relpath(target, out_dir).replace('\\', '/'),
             'kind': 'file',
@@ -2540,16 +2617,67 @@ def write_assets(out_dir, file_prefix, formatted, assets_dir=''):
             'bytes': size,
         }
 
-    FILE_ASSET_STATE['exported'] = file_exported
-    FILE_ASSET_STATE['written'] = file_written
+    # `written` 数的是**合并后清单里真实存在的文档条目**（第二遍跑同一目录时它不为 0，而新拷贝是 0）；
+    # `copied` 才是"这次新拷了几个"。两个都写出来，免得读清单的人把后者当前者。
+    file_written_total = sum(1 for record in manifest.values() if record.get('kind') == 'file')
+    FILE_ASSET_STATE['written'] = file_written_total
+    FILE_ASSET_STATE['copied'] = file_written
     FILE_ASSET_STATE['unavailable'] = file_unavailable
-    with open(os.path.join(assets, 'manifest.json'), 'w', encoding='utf-8') as fh:
+    with open(manifest_path, 'w', encoding='utf-8') as fh:
         json.dump({'schema': 'weflow-media-manifest/v2', 'messages': manifest,
-                   'documents': {'exported': file_exported, 'unavailable': file_unavailable}},
+                   'documents': {'written': file_written_total, 'copied': file_written,
+                                 'unavailable': file_unavailable}},
                   fh, ensure_ascii=False, indent=2)
     return os.path.basename(os.path.normpath(assets)), manifest, written + file_written
 
 
+def _markdown_link_target(rel):
+    """把相对路径转成 markdown 链接目标：只编码会**截断链接**的那些字符。
+
+    真机实测（2026-10-13，重导咸鱼梦想家时核对产物才发现）：文件名叫
+    `…研究生学位（毕业）论文开题报告(2).pdf`，写出来是 `[名字](…报告(2).pdf)` —— 任何 markdown 渲染器
+    都在第一个半角 `)` 处结束目标，链接指向 `…报告(2`，点开是空的。带空格的文件名同理（目标在空白处结束）。
+    所以按段编码这几个字符（括号、空白、`<`、`>`、`[`、`]`、`#`、`?`、`%`、引号、反斜杠），
+    **中文保持原样**：本地预览器都按 UTF-8 解路径，编码成 `%E5%…` 反而让人看不懂。
+    """
+    out = []
+    for ch in str(rel or '').replace('\\', '/'):
+        if ch.isspace() or ch in '()[]<>#"\'%?\\':
+            out.append('%%%02X' % ord(ch))
+        else:
+            out.append(ch)
+    return ''.join(out)
+
+
+def media_json_summary(media_items, media_report_path=None, manifest=None, asset_new=0, assets_dir=''):
+    """命令行最后那行 JSON 里的媒体摘要 —— **三种格式共用同一份词汇与同一份计数逻辑**。
+
+    每个词只回答一个问题，互不覆盖：
+
+    * `reportStatus`：按**能不能在源数据里定位到**分类（图片是 `embedded`/`remote-fetched`/`missing`，
+      文档是 `found`/`missing`）。这是"这份媒体在源数据里有没有"。
+    * `assets.written / copied`：**有没有写进导出目录**（written 是现在那里的总数，copied 是这一轮新写的）。
+      与上一条是两回事：源数据里找得到的，可能因为太大或拷贝失败而没写进去。
+    * `documents.unavailable`：没能落盘的份数（没找到 / 太大 / 拷贝失败）。
+
+    三处原本各拼一份 JSON（还各写了不同的键名），同一个事实就有三种说法；这里收成一份，
+    顺带把**报告文件名**一起给出来（此前只有 HTML 那条给）。不含路径、正文或密钥。
+    """
+    counts = {}
+    for item in media_items or []:
+        status = item.get('status') or 'unknown'
+        counts[status] = counts.get(status, 0) + 1
+    return {
+        'report': os.path.basename(media_report_path) if media_report_path else None,
+        'reportItems': len(media_items or []),
+        'reportStatus': counts,
+        'assets': {'items': len(manifest or {}), 'new': asset_new, 'dir': assets_dir or None},
+        'documents': {'written': FILE_ASSET_STATE['written'],
+                      'copied': FILE_ASSET_STATE['copied'],
+                      'unavailable': FILE_ASSET_STATE['unavailable']},
+    }
+
+
 def write_markdown(out_dir, file_prefix, formatted, assets_dir=''):
     """markdown 正文 + 媒体落盘（落盘那半在 `write_assets`，两者共用同一份清单）。"""
     assets_name, manifest, written = write_assets(out_dir, file_prefix, formatted, assets_dir)
@@ -2573,9 +2701,15 @@ def write_markdown(out_dir, file_prefix, formatted, assets_dir=''):
             if rel and kind == 'file':
                 # 文档不是图片：`![](…)` 会被当成坏图，要写成链接，链接文字用原始文件名。
                 keep = '' if (not body or body.startswith('[文件]')) else body + chr(10) + chr(10)
-                body = keep + '[%s](%s)' % (label or os.path.basename(rel), rel)
+                # 链接文字用原始文件名；`[`/`]` 换成实体（`[草稿] 方案.docx` 会把链接本身的结构打断），
+                # 控制字符去掉（标题里可能带换行/制表符，落盘名已去掉，文字也得跟上，否则渲染出来断开）
+                text = ''.join(ch for ch in (label or os.path.basename(rel))
+                               if ord(ch) >= 32 and ord(ch) != 127)
+                text = text.replace('[', '&#91;').replace(']', '&#93;')
+                body = keep + '[%s](%s)' % (text, _markdown_link_target(rel))
             elif rel:
-                body = ('' if (not body or body == '[图片]') else body + chr(10) + chr(10)) + '![图片](%s)' % rel
+                body = ('' if (not body or body == '[图片]') else body + chr(10) + chr(10)) \
+                    + '![图片](%s)' % _markdown_link_target(rel)
         lines.extend(['**%s** %s' % (who, stamp), '', body.strip() or '（空）', ''])
 
     md_path = os.path.join(out_dir, file_prefix + '.md')
@@ -2820,35 +2954,39 @@ def main():
     if args.assets_only:
         # 只抽媒体：其它格式的 `--media` 会先跑这一步，再各自消费清单。
         assets_name, manifest, asset_new = write_assets(args.out, file_prefix, formatted, args.assets_dir)
-        print(f"Assets: {len(manifest)} media item(s), {FILE_ASSET_STATE['exported']} document(s) "
-              f"({FILE_ASSET_STATE['unavailable']} unavailable, {FILE_ASSET_STATE['written']} new) "
+        # 这一步也写媒体报告：三种形态的调用方应当拿到同一份东西（状态计数 + 报告文件名），
+        # 少写这一份的话，`--media` 的调用者只能看到文档计数、看不到"哪些媒体没嵌上、为什么"。
+        media_report_path = None
+        if media_items:
+            media_report_path = os.path.join(args.out, f'{file_prefix}_media.json')
+            with open(media_report_path, 'w', encoding='utf-8') as handle:
+                json.dump(build_media_report(media_items, display_name, args.talker, len(formatted)),
+                          handle, ensure_ascii=False, indent=2)
+        print(f"Assets: {len(manifest)} media item(s), {FILE_ASSET_STATE['written']} document(s) "
+              f"({FILE_ASSET_STATE['unavailable']} unavailable, {FILE_ASSET_STATE['copied']} new) "
               f"({asset_new} new) -> {assets_name}")
         print(json.dumps({"success": True, "total": len(formatted),
                           "files": [os.path.join(args.out, assets_name)], "format": "assets",
-                          "assets": len(manifest), "assetsNew": asset_new,
-                          "documents": FILE_ASSET_STATE['exported'],
-                          "documentsNew": FILE_ASSET_STATE['written'],
-                          "documentsUnavailable": FILE_ASSET_STATE['unavailable'],
-                          "assetsDir": assets_name}, ensure_ascii=False))
+                          "media": media_json_summary(media_items, media_report_path, manifest,
+                                                      asset_new, assets_name)},
+                         ensure_ascii=False))
         conn.close()
         return
     if args.format == 'md':
         md_path, asset_total, asset_new, assets_name = write_markdown(args.out, file_prefix, formatted, args.assets_dir)
+        media_report_path = None      # 没有媒体时下面那段不跑，但 JSON 里仍要如实给出 None
         if media_items:
             media_report_path = os.path.join(args.out, f'{file_prefix}_media.json')
             with open(media_report_path, 'w', encoding='utf-8') as handle:
                 json.dump(build_media_report(media_items, display_name, args.talker, len(formatted)),
                           handle, ensure_ascii=False, indent=2)
         print(f"Markdown: {len(formatted)} message(s), {asset_total} media item(s), "
-              f"{FILE_ASSET_STATE['exported']} document(s) ({FILE_ASSET_STATE['unavailable']} unavailable, "
-              f"{FILE_ASSET_STATE['written']} new) ({asset_new} new) -> {os.path.basename(md_path)}")
+              f"{FILE_ASSET_STATE['written']} document(s) ({FILE_ASSET_STATE['unavailable']} unavailable, "
+              f"{FILE_ASSET_STATE['copied']} new) ({asset_new} new) -> {os.path.basename(md_path)}")
         print(json.dumps({"success": True, "total": len(formatted), "parts": 1,
                           "files": [md_path], "format": "md",
-                          "assets": asset_total, "assetsNew": asset_new,
-                          "documents": FILE_ASSET_STATE['exported'],
-                          "documentsNew": FILE_ASSET_STATE['written'],
-                          "documentsUnavailable": FILE_ASSET_STATE['unavailable'],
-                          "assetsDir": assets_name},
+                          "media": media_json_summary(media_items, media_report_path, manifest=None,
+                                                      asset_new=asset_new, assets_dir=assets_name)},
                          ensure_ascii=False))
         conn.close()
         return
@@ -2898,17 +3036,13 @@ def main():
     # Print JSON summary for CLI integration.
     # The four original keys are untouched; `media` is purely additive and the
     # one existing consumer (src/services/exportService.ts) ignores it.
+    # 三种格式（html/md/assets）用**同一个** media_json_summary，词汇与计数不再各说各话。
     print(json.dumps({
         "success": True,
         "total": total,
         "parts": len(html_files),
         "files": html_files,
-        "media": ({
-            "schema": "weflow-media-report/v1",
-            "records": len(media_items),
-            "status": media_report['counts'],
-            "report": os.path.basename(media_report_path) if media_report_path else None,
-        } if media_report else None),
+        "media": media_json_summary(media_items, media_report_path),
     }))
 
 
@@ -2924,8 +3058,13 @@ def _phase(label):
 
 
 def sanitize_filename(name: str) -> str:
-    """Remove characters unsafe for filenames."""
-    return re.sub(r'[\\/:*?"<>|]', '_', name)[:80]
+    """Remove characters unsafe for filenames.
+
+    控制字符也要去掉：它们不在"非法字符"那张表里，但 Windows 创建时会直接
+    `OSError: Invalid argument`（2026-10-13 实测到一个带制表符的标题把整个导出搞崩）。
+    """
+    kept = ''.join(ch for ch in str(name or '') if ord(ch) >= 32 and ord(ch) != 127)
+    return re.sub(r'[\\/:*?"<>|]', '_', kept)[:80]
 
 
 if __name__ == '__main__':

package/scripts/recall_eval.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""语义索引的**召回/排序评价**（可复跑、可对比的评测台）。
+
+为什么要有它：2026-10-15 之前，检索质量的结论都来自"手工试问 + 看前几条"——那种判据查不出
+"改完是变好还是变坏"，也复现不了。指标一律用业界标准口径，不自创：
+
+  · Recall@1/5/10   —— 该回来的回来没有（RAG 真正在乎的是 @5/@10）
+  · MRR@10          —— 第一条正确结果的倒数名次（单答案查询的主指标，MS MARCO 口径）
+  · nDCG@10         —— 排序质量（BEIR / MTEB 的主指标；这里是二值相关性、单条标准答案，
+                        所以 nDCG@10 = 1/log2(1+rank)，命中在第 10 名之外记 0）
+  · Hit@1           —— 与 Recall@1 同义，单列是因为中文规范（《人工智能 检索增强生成系统测评
+                        规范》2024003631）里用的是"命中率"这个词
+  · 覆盖（coverage）—— **这一条是我们这类语料特有的**：答案在库里根本不存在时，任何排序都救不了，
+                        把它算进召回率是在诬赖排序。所以每题先判"库里有没有"。
+
+两套标准答案（都不依赖人工标注、也不把用户数据写进仓库）：
+  · `frag`  —— 从记录**自己正文中段**取 12 字干净片段当问句（唯一性已校验）。测"局部能不能召回整条"。
+  · `title` —— 文章用它的标题、聊天用它开头 30 字。这是用户最常干的事（记得那句话）。
+  · `question`（可选）—— 你手写的真问题 + 一个"答案里必然出现的字面量"当锚，走 `--queries-file`
+                        （TSV：问题<TAB>锚<TAB>线）。**该文件请放在仓库外**：锚串取自你的语料。
+
+`--dedup` 会先把**同文本**的记录合并再排名（多号转载同一篇时，top-k 里塞满同一份内容会虚高
+召回、掏空信息量）。它与不合并的两种名次都报，差多少一眼能看出来。
+
+用法（调 embedding 服务，需 --yes）：
+  python scripts/recall_eval.py --records 30 --yes
+  python scripts/recall_eval.py --records 30 --dedup --json --yes
+  python scripts/recall_eval.py --queries-file D:/tmp/q.tsv --records 0 --yes
+"""
+
+import argparse
+import importlib.util
+import json
+import math
+import os
+import random
+import re
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+spec = importlib.util.spec_from_file_location('semantic_search', HERE / 'semantic_search.py')
+ss = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(ss)
+
+CJK = lambda ch: '\u4e00' <= ch <= '\u9fff'
+BANNED = set(' \t\n\r:/\\"\'|<>（）()【】[],;○●·、。！？，')
+JUNK = set('=_&%/.?#@~^`$*+{}[]')
+
+
+def clean_window(text, mid, length=12):
+    """取一段干净的中文片段（≥60% 汉字、不含标点/URL 残片/长数字）——否则会拿 URL 碎片当问句。"""
+    for start in range(max(0, mid), max(0, min(len(text) - length, mid + 60))):
+        w = text[start:start + length]
+        if len(w) < length or set(w) & BANNED or set(w) & JUNK:
+            continue
+        if sum(1 for c in w if CJK(c)) / len(w) < 0.6 or re.search(r'\d{5,}', w):
+            continue
+        return w
+    return None
+
+
+def rank_of(order, target_group):
+    """目标（或其同文本组）在结果里的名次；不在表里返回 None。"""
+    for i, idx in enumerate(order, 1):
+        if idx in target_group:
+            return i
+    return None
+
+
+def metrics(rank, k=10):
+    hit = rank is not None and rank <= k
+    return {
+        'hit@1': 1.0 if rank == 1 else 0.0,
+        'recall@1': 1.0 if rank == 1 else 0.0,
+        'recall@5': 1.0 if rank is not None and rank <= 5 else 0.0,
+        'recall@10': 1.0 if hit else 0.0,
+        'mrr@10': (1.0 / rank) if hit else 0.0,
+        'ndcg@10': (1.0 / math.log2(1 + rank)) if hit else 0.0,
+    }
+
+
+def build_cases(meta, texts, per_line, seed):
+    """自动造题：每线抽 per_line 条记录，各出 frag / title 两种问句。"""
+    groups = {}
+    for i, t in enumerate(texts):
+        groups.setdefault(hash(t), []).append(i)
+
+    rng = random.Random(seed)
+    cases = []
+    for kind, line, minlen in (('article', 'wiki', 220), ('chat', 'chat', 70)):
+        pool = [i for i, m in enumerate(meta) if m.get('type') == kind and len(texts[i]) >= minlen]
+        rng.shuffle(pool)
+        picked = 0
+        for i in pool:
+            if picked >= per_line:
+                break
+            t = texts[i]
+            body = t[t.find('\n') + 1:] if kind == 'article' and t.find('\n') >= 0 else t
+            frag = clean_window(body, len(body) // 3) or clean_window(body, len(body) // 2)
+            title = (meta[i].get('title') or '').strip() or clean_window(t, 0, 30)
+            if not frag or not title:
+                continue
+            group = set(groups[hash(t)])
+            cases.append({'form': 'frag', 'line': line, 'idx': i, 'group': group, 'query': frag})
+            cases.append({'form': 'title', 'line': line, 'idx': i, 'group': group, 'query': title})
+            picked += 1
+    return cases, groups
+
+
+def load_questions(path, texts):
+    """TSV：问题<TAB>锚<TAB>线 → 标准答案 = 含锚的记录集合（覆盖为 0 的题单独列出，不计入召回）。"""
+    cases = []
+    for raw in Path(path).read_text(encoding='utf-8').splitlines():
+        raw = raw.strip()
+        if not raw or raw.startswith('#') or '\t' not in raw:
+            continue
+        parts = raw.split('\t')
+        q, anchor = parts[0].strip(), parts[1].strip()
+        line = parts[2].strip() if len(parts) > 2 else 'all'
+        truth = {i for i, t in enumerate(texts) if anchor.lower() in t.lower()}
+        cases.append({'form': 'question', 'line': line, 'idx': -1, 'group': truth or set(),
+                      'query': q, 'anchor': anchor, 'covered': bool(truth)})
+    return cases
+
+
+def main():
+    ap = argparse.ArgumentParser(description='语义索引召回/排序评测台')
+    ap.add_argument('--records', type=int, default=30, help='每条线抽多少条记录造题（默认 30）')
+    ap.add_argument('--queries-file', help='手写问句 TSV（问题<TAB>锚<TAB>线）；请放仓库外')
+    ap.add_argument('--top-k', type=int, default=10)
+    ap.add_argument('--seed', type=int, default=7)
+    ap.add_argument('--dedup', action='store_true', help='排名前把同文本记录合并')
+    ap.add_argument('--rerank', action='store_true',
+                    help='调真正的重排（先试 Jev 契约，再退到已配置的对话模型）')
+    ap.add_argument('--mmr', action='store_true', help='排名后做 MMR 去冗余（λ=0.7）')
+    ap.add_argument('--rerank-pool', type=int, default=ss.RERANK_CANDIDATES,
+                    help='重排看多少条候选（默认 %d）' % ss.RERANK_CANDIDATES)
+    ap.add_argument('--json', action='store_true')
+    ap.add_argument('--yes', action='store_true', help='确认调用云端 embedding（每条约十几 tokens）')
+    args = ap.parse_args()
+
+    if not args.yes:
+        raise SystemExit('这一步会调用 embedding 服务（花钱、且问句出境）。确认后加 --yes。')
+
+    meta = json.loads(ss.META_FILE.read_text(encoding='utf-8'))
+    vectors = None
+    import numpy as np
+    vectors = np.load(ss.VECTORS_FILE, mmap_mode='r')
+    texts = [m.get('text') or '' for m in meta]
+
+    cases, groups = build_cases(meta, texts, args.records, args.seed) if args.records else ([], {})
+    if args.queries_file:
+        cases += load_questions(args.queries_file, texts)
+    if not cases:
+        raise SystemExit('没有题（--records 0 且没给 --queries-file）')
+
+    key = ss.get_dashscope_key(ss.load_config())
+    embs = ss.get_embeddings([c['query'] for c in cases], key)
+    if any(all(v == 0 for v in e) for e in embs):
+        raise SystemExit('embedding 服务返回全零 —— 先查 key/网络，别拿这个结果下结论')
+
+    rows = []
+    for c, emb in zip(cases, embs):
+        v = np.array(emb, dtype=np.float32)
+        v = v / np.linalg.norm(v)
+        sims = np.asarray(vectors @ v)
+        types = ss.line_types(c['line'])
+        if types is not None:
+            sims = np.where(np.array([str(m.get('type', '')) in types for m in meta]), sims, -np.inf)
+        order = [int(i) for i in np.argsort(sims)[::-1]]
+        order = [i for i in order if np.isfinite(sims[i])]
+        if args.rerank:
+            # 与 `search()` 同一条路：先按原契约（Jev）排，失败再退到已配置的对话模型
+            pool = [{**meta[i], '_idx': i, 'score': float(sims[i])}
+                    for i in order[:args.rerank_pool]]
+            ranked = ss.rerank_dispatch(c['query'], pool, ss.create_client(),
+                                         pool_size=args.rerank_pool)
+            order = [it['_idx'] for it in ranked] + list(order[args.rerank_pool:])
+        if args.mmr:
+            pool2 = [{**meta[i], '_row': i, 'rerankScore': r.get('rerankScore')}
+                     for i, r in zip(order[:args.rerank_pool], ranked)]
+            order = [it['_row'] for it in ss.mmr_select(pool2, vectors, args.top_k)]
+        if args.dedup:
+            seen, keep = set(), []
+            for i in order:
+                h = hash(texts[i])
+                if h in seen:
+                    continue
+                seen.add(h)
+                keep.append(i)
+            order = keep
+        rank = rank_of(order, c['group'])
+        # 多样性：最终 top-k 里两两余弦的均值 —— 越低说明结果越不重复。
+        # 加它是因为 MMR 这类去冗余与「单答案召回」是相冲的，只看召回会误判。
+        top = [i for i in order[:args.top_k] if i < len(texts)]
+        div = None
+        if len(top) >= 2:
+            mat = np.asarray(vectors[top], dtype=np.float32)
+            sims = mat @ mat.T
+            n = len(top)
+            div = float((sims.sum() - np.trace(sims)) / (n * (n - 1)))
+        rows.append({**c, 'group': None, 'rank': rank, 'div': div,
+                     'metrics': metrics(rank, args.top_k)})
+
+    def agg(sel):
+        covered = [r for r in sel if r['rank'] is not None or (r.get('covered') is not False)]
+        scored = [r for r in covered if r['rank'] is not None]
+        out = {'n': len(sel), 'n_covered': len(covered),
+               'n_coverage_gap': sum(1 for r in sel if r.get('covered') is False)}
+        for k in ('hit@1', 'recall@1', 'recall@5', 'recall@10', 'mrr@10', 'ndcg@10'):
+            out[k] = (sum(r['metrics'][k] for r in covered) / len(covered)) if covered else 0.0
+        out['n_recalled'] = len(scored)
+        divs = [r['div'] for r in sel if r.get('div') is not None]
+        out['pairwiseDiversity'] = (sum(divs) / len(divs)) if divs else None
+        return out
+
+    report = {'config': {'records': args.records, 'seed': args.seed, 'dedup': args.dedup,
+                         'rerank': args.rerank, 'rerankPool': args.rerank_pool, 'mmr': args.mmr, 'rerankState': dict(ss.RERANK_STATE),
+                         'topK': args.top_k, 'indexCounts': ss.line_counts()},
+              'overall': agg(rows), 'byGroup': {}, 'cases': [
+                  {'form': r['form'], 'line': r['line'], 'query': r['query'], 'rank': r['rank']}
+                  for r in rows]}
+    for form in sorted({r['form'] for r in rows}):
+        for line in sorted({r['line'] for r in rows if r['form'] == form}):
+            sel = [r for r in rows if r['form'] == form and r['line'] == line]
+            if sel:
+                report['byGroup']['%s/%s' % (form, line)] = agg(sel)
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return
+    print('题数 %d（覆盖缺口 %d）  dedup=%s' % (report['overall']['n'],
+                                          report['overall']['n_coverage_gap'], args.dedup))
+    print('%-16s %6s %8s %8s %8s %8s %8s %9s'
+          % ('组', 'n', 'hit@1', 'recall@5', 'recall@10', 'mrr@10', 'ndcg@10', '多样性'))
+    for name, m in [('overall', report['overall'])] + list(report['byGroup'].items()):
+        div = m.get('pairwiseDiversity')
+        print('%-16s %6d %8.2f %8.2f %8.2f %8.2f %8.2f %9s'
+              % (name, m['n'], m['hit@1'], m['recall@5'], m['recall@10'], m['mrr@10'],
+                 m['ndcg@10'], ('%.3f' % div) if div is not None else '-'))
+
+
+if __name__ == '__main__':
+    main()