argo-search 1.0.1 → 2.9.8

package/sub-skills/local-search/smart_router.py

@@ -3,7 +3,7 @@
 
 根据查询特征将请求路由到最优本地引擎组合，覆盖：
 - 中文通用 / 中文新闻 / 代码 / 学术 / 参考百科 / 事实问答 / 垂直实体
-- 与 unified-search 的 route.py 解耦，local-search 内部使用
+- 与 unified-search 的 route.py 拆开，local-search 内部使用
 """
 
 from __future__ import annotations
@@ -22,6 +22,8 @@ if not logger.handlers:
 
 # 查询特征正则
 _RE_CHINESE = re.compile(r"[一-鿿]")
+_RE_KANA = re.compile(r"[\u3040-\u30ff]")
+_RE_HANGUL = re.compile(r"[\uac00-\ud7af]")
 _RE_ACADEMIC = re.compile(
     r"\b(paper|arxiv|preprint|doi|citation|abstract|journal|conference|"
     r"peer[-\s]?review|research|survey|review|thesis|dissertation)\b|"
@@ -60,10 +62,23 @@ CATEGORY_PRIORITY = {
     "academic": ["local_arxiv", "local_semantic_scholar", "local_crossref", "local_pubmed"],
     "code": ["local_github", "local_stackoverflow", "local_gitlab", "local_npm"],
     "news": ["local_bing_news", "local_google_news", "local_duckduckgo_news"],
-    "chinese": ["local_baidu", "local_sogou", "local_bing", "local_duckduckgo"],
+    # chinese 与主路径 route_combo._select_sub_engines 中文支对齐（2026-10-06 实测）：
+    # baidu 直连 0 结果移出；sogou（~1s 相关）/360（~1s）实测可用；yandex 殿后。
+    "chinese": ["local_sogou", "local_360", "local_yandex", "local_bing", "local_duckduckgo"],
+    # ja：yandex 实测覆盖最好；bing text 后端已被 ddgs 9.14.4 移除（auto 降级）
+    "japanese": ["local_yandex", "local_duckduckgo", "local_bing"],
+    # ko 同 ja
+    "korean": ["local_yandex", "local_duckduckgo"],
     "reference": ["local_wikipedia", "local_wiktionary", "local_wikiquote"],
     "vertical": ["local_openstreetmap", "local_imdb", "local_goodreads"],
-    "web_general": ["local_bing", "local_duckduckgo", "local_mojeek", "local_startpage"],
+    # web_general 顺序 = 实测可用性（2026-10-06 重排）：
+    # ddgs 9.14.4 起 text 后端仅 brave/duckduckgo/google/grokipedia/
+    # mojeek/startpage/wikipedia/yahoo/yandex——没有 bing，local_bing 的
+    # `-b bing` 已静默降级 auto（1.6-6s 随机波动，拖早停第二引擎的尾），
+    # 故移出 web_general（chinese 域仍保留作第 4 备选）。
+    # brave 对真实查询稳定 0 结果；yandex 是唯一稳定后端（~1.9s）置首，
+    # ddg/yahoo 次之（限流时 1s 级快速失败，不拖墙钟）。
+    "web_general": ["local_yandex", "local_duckduckgo", "local_yahoo", "local_brave", "local_bing"],
 }
 
 
@@ -71,9 +86,29 @@ def extract_features(query: str) -> dict[str, Any]:
     """提取查询特征向量。"""
     total = max(len(query), 1)
     chinese = len(_RE_CHINESE.findall(query))
+    # 主语言判定：优先复用 scripts/lang_detect 单来源
+    primary_lang = "en"
+    try:
+        from lang_detect import detect_language
+        primary_lang = detect_language(query)
+    except ImportError:
+        kana = len(_RE_KANA.findall(query))
+        hangul = len(_RE_HANGUL.findall(query))
+        if kana / total >= 0.15 or (kana and chinese / total >= 0.3):
+            primary_lang = "ja"
+        elif hangul / total >= 0.15:
+            primary_lang = "ko"
+        elif chinese / total >= 0.3:
+            primary_lang = "zh"
+        else:
+            primary_lang = "en"
     return {
         "chinese_ratio": chinese / total,
-        "is_chinese": chinese / total > 0.3,
+        # is_chinese：仅当真主语言为 zh 时标中文（日文汉字查询不再误入 chinese 分类）
+        "is_chinese": primary_lang == "zh" or (
+            primary_lang not in ("ja", "ko") and chinese / total > 0.3
+        ),
+        "primary_lang": primary_lang,
         "is_academic": bool(_RE_ACADEMIC.search(query)),
         "is_code": bool(_RE_CODE.search(query)),
         "is_news": bool(_RE_NEWS.search(query)),
@@ -116,6 +151,11 @@ def route_query(
 
     # 特征 → 候选分类
     candidates: list[tuple[str, float]] = []
+    # 日/韩主语言：优先对应语言的本地引擎分类
+    if features.get("primary_lang") == "ja":
+        candidates.append(("japanese", 1.0))
+    elif features.get("primary_lang") == "ko":
+        candidates.append(("korean", 1.0))
     if features["is_academic"]:
         candidates.append(("academic", 1.0))
     if features["is_code"]:
@@ -130,13 +170,13 @@ def route_query(
         # 事实查询优先百科与通用搜索
         candidates.append(("reference", 0.85))
         candidates.append(("web_general", 0.7))
-    if features["is_chinese"]:
+    if features["is_chinese"] and features.get("primary_lang") != "ja":
         candidates.append(("chinese", 0.85))
         # 中文新闻类查询增强
         if features["is_news"]:
             candidates.append(("news", 0.9))
 
-    # 兜底
+    # 保底
     if not candidates:
         candidates.append(("web_general", 0.5))
 
@@ -168,7 +208,7 @@ def route_query(
         if len(selected) >= max_engines:
             break
 
-    # 兜底：如果都没选到，返回前几个启用的可用引擎
+    # 保底：如果都没选到，返回前几个启用的可用引擎
     if not selected:
         selected = reg.list_engines(available_only=require_available, enabled_only=True)[:max_engines]
         reasons = [f"{e}(fallback)" for e in selected]

package/sub-skills/local-seek/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: local-seek
+version: 1.6.0
+description: 本机文件与代码内容搜索（rg/fd/mdfind/grep 统一入口 seek.py，工具输出即答案）。与 argo 联网搜索互补：搜本机目录、代码符号、文件名、文档全文、文件结构。触发：搜本地、找文件、找代码、本机搜 xx、代码在哪、统计本地命中。
+---
+
+# local-seek — 本地高效搜索（v1.6.0）
+
+搜本机文件和内容就从这里开始。**工具的输出就是答案**，不用再自己翻一遍。
+与 Argo（联网搜索）分工：Argo 搜网络，本技能搜本机。
+
+## 三层递进：先定位、再看上下文、最后精读
+
+不要一上来就读文件。一层层往里走，每层的结果都不多：
+
+| 层 | 干什么 | 命令 | 输出量 |
+|----|--------|------|--------|
+| L1 定位 | 找到「在哪个文件」 | seek.py "词" --count 或 --filename | 每文件一行 |
+| L2 上下文 | 看命中位置附近 | seek.py "词" --context 2 | 每命中 3 行 |
+| L3 精读 | 读关键段落 | read_file 按行号局部读取 | 按需 |
+
+每次搜索先想清楚停在哪一层，默认只做第一层。
+
+## 统一入口
+
+统一走 `scripts/seek.py`（相对 argo 根：`sub-skills/local-seek/scripts/seek.py`），
+由它选工具，不要自己拼 rg/fd 参数：
+
+```bash
+# 以下以 argo 安装根为 cwd；或写死 $ARGO_HOME/sub-skills/local-seek/scripts/seek.py
+python3 sub-skills/local-seek/scripts/seek.py "查询词"                 # 默认：当前目录全文
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --path ~/notes   # 指定目录
+python3 sub-skills/local-seek/scripts/seek.py "词" --path ~/.agents --dot  # 连 . 开头目录与软链一起搜；搜 ~/.agents、~/.zcode 要加（Spotlight 收不到）
+python3 sub-skills/local-seek/scripts/seek.py "词" --path . --include-noise  # repos/、tests/ 等与真源平权（默认排真源之后，仍搜得到）
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --count          # 先数命中，再决定是否深入
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --filename       # 按文件名
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --spotlight      # 全盘兜底（PDF/邮件/笔记）
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --type py,ts
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --json           # 结构化输出
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --exact          # 关闭中文扩展，精确匹配
+python3 sub-skills/local-seek/scripts/seek.py "查询词" --exclude 某文件 # 额外排除（可重复）
+python3 sub-skills/local-seek/scripts/seek.py --outline 文件路径        # 文件结构（def/class/标题/顶层key）
+python3 sub-skills/local-seek/scripts/seek.py --lines 10-50 文件路径    # 按行读取，替代 read_file 全文
+python3 sub-skills/local-seek/scripts/seek.py "裸except" --structural   # 结构搜索（空catch/裸except/装饰函数等）
+python3 sub-skills/local-seek/scripts/seek.py --git-log 文件路径        # 文件的最近提交历史
+python3 sub-skills/local-seek/scripts/seek.py --git-blame 12 文件路径   # 第 12 行的提交归属
+```
+
+内置智能行为（固定字符串回退、中文 2-gram 扩展、PCRE2 检测、结构搜索、
+git 联动等）自动生效，明细见 references/auto-behaviors.md。
+
+## 工具选择（何时换工具）
+
+| 场景 | 用 | 为什么 |
+|------|-----|--------|
+| 搜代码/正文关键词 | rg（默认） | 毫秒级，尊重 .gitignore，自动排除 node_modules 等 |
+| 只记得文件名 | --filename（fd） | 按文件名模糊匹配 |
+| 搜 PDF/邮件/已归档内容 | --spotlight（mdfind） | 用系统已建好的索引，不额外花时间（Windows/Linux 无此工具，改用 rg） |
+| 找代码模式（裸except/空catch等） | --structural | 按语义不按字符串 |
+| 追文件历史/单行归属 | --git-log / --git-blame | 免开终端敲 git |
+| 当前目录搜不到 | 先扩大 --path，再 --spotlight | 先窄后宽 |
+| 大仓库担心输出爆炸 | --count + --max 20 | 先看分布再深入 |
+
+## 执行纪律
+
+1. **先窄后宽**：先限定目录/扩展名，搜不到再扩大。禁止一开始就全盘扫。
+2. **先数后看**：--count 看分布，--context 0（默认）看命中行，最后才读文件。
+3. **指定类型**：代码场景加 --type（py,ts,go…），文档场景用 --scope doc。
+4. **绝对路径优先**：涉及读文件时用 read_file + 绝对路径。
+5. **不读整个文件**：L3 精读用行号偏移局部读取，命中上下文不够再扩。
+6. **结果为空先换词**：换同义词/拆词/去大小写，再换工具（fd→mdfind），
+   不要重复同一查询。
+7. **先结构后正文**：大文件先 --outline 看结构，再 --lines N-M 按需读取，
+   禁止直接 read_file 整个文件。
+8. **结构搜索按语义**：找「是不是有裸 except」这类问题用 --structural，
+   不要手写正则碰运气；可用语义清单见 references/structural-search.md。
+9. **git 只读标题**：--git-log 只给标题，够用就停；要看具体改动再手动 git show。
+
+## 排序与性能（v1.6.0）
+
+内容命中按 **BM25F 相关度重排**（实现文件不再被文档顺带提及淹没），池子按
+**文件轮转配额**（每文件 ≤8 行）；文件名场景用 **fzf FuzzyMatchV2** 评分。
+确定性不变：与 rg 发射序无关，并列分按 (路径,行号)。
+
+大树上的内容搜索可开 **FTS5 索引快路**：`ARGO_LOCAL_FTS=1`（默认关），
+首次对该目录先跑 `scripts/seek_fts.py rebuild <目录>` 预热，之后毫秒级返回；
+rg 永远兜底（索引未建成/带正则/零命中时自动回退）。明细见
+references/auto-behaviors.md。
+
+逃生门（默认行为已是最优，仅在回退/实验时用）：
+- `ARGO_SEEK_CONTENT_RERANK=0` 关闭内容重排，恢复 (路径,行号) 原序
+- `ARGO_SEEK_FRECENCY=1` 开启访问频次加成（实验项，默认关）
+- 排序质量用 `scripts/eval_rank.py` 评测（MRR/耗时，支持 --compare）
+
+## 配置
+
+排除规则与知识域：`sub-skills/local-seek/config/domains.yaml`
+查看当前规则：`python3 sub-skills/local-seek/scripts/seek.py --domains`
+
+## 参考
+
+按场景的完整命令配方（进阶，非常规操作再读）：
+
+- references/rg-recipes.md — rg 分场景配方（函数定义/跨文件引用/多词/正则）
+- references/auto-behaviors.md — 自动行为明细（重排/FTS/中文扩展/PCRE2/git）
+- references/fd-mdfind-recipes.md — fd 与 Spotlight 配方
+- references/strategies.md — 三层做法的详细说明，以及怎么少花 token
+- references/structural-search.md — 结构搜索手册（语义规则表/别名/扩展新规则）
+- references/git-integration.md — git 联动用法、场景与边界
+- references/remote-handoff.md — 本地搜不到时的扩大与联网交接清单

package/sub-skills/local-seek/config/domains.yaml

@@ -0,0 +1,20 @@
+# local-seek 搜索配置
+# 修改后即时生效，无需重启。
+
+# 附加排除规则（追加到内置默认排除之后）
+# 内置默认排除：node_modules .git __pycache__ .venv dist build target 等
+exclude:
+  - "*.min.js"
+  - "*.map"
+  - "*.lock"
+  - ".turbo"
+  - ".nyc_output"
+  - "*.egg-info"
+
+# 知识域：经常要搜的目录，填在这里可被 --domains 查询
+# 示例：- ~/Documents/notes
+knowledge_domains: []
+
+# 输出控制
+max_results: 30        # 默认最大结果数
+snippet_chars: 120     # 命中行截断长度

package/sub-skills/local-seek/scripts/eval_rank.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""eval_rank.py — local-seek 排序质量分级评测 + 计时基准（离线，零依赖）。
+
+与 eval_seek.py 的分工：eval_seek 检查「有没有命中」（hit/no-hit 契约），
+本文件回答「命中的**排序**对不对」——内容重排（BM25F）与文件名 fzf V2 的
+改动前后用同一批用例对比，产出两类指标：
+
+  质量  每个用例记录 top-N (path, line) 实况，并按期望文件集算
+        topk_hit（期望文件进 top-K 的用例占比）与 MRR（倒数排名均值）。
+  速度  固定查询集在固定语料上跑 run_query 的中位耗时（毫秒）。
+
+期望值来自「实现所在文件」这一弱真值（改动前用 rg -l 逐一核实过），
+不是人工标注的全序金标——它的用途是**守护不退步 + 观察位移**，
+不是证明绝对质量。绝对质量请配合 eval_seek.py 的命中契约一起读。
+
+用法：
+  python3 eval_rank.py                        # 人读报告（stdout）
+  python3 eval_rank.py --json out.json        # 同时写 JSON（供 A/B 对比）
+  python3 eval_rank.py --compare a.json b.json  # 对比两份报告，给出逐用例位移
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+import time
+from pathlib import Path
+
+SCRIPTS = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPTS))
+
+import seek as s  # noqa: E402
+
+# 语料根从本文件位置推导（scripts/ → local-seek/ → sub-skills/ → 仓根），
+# 此前硬编码 ~/.agents/skills/argo：换机器/克隆路径不同就全 miss（MRR 全 0
+# 却看不出是路径病）。SKILLS_ROOT 保留给「跨仓搜索」类用例的常见安装位，
+# 不存在时相关用例自然 0 命中（诚实反映环境，不伪造）。
+_ARGO_ROOT = Path(__file__).resolve().parents[3]
+ARGO_ROOT = str(_ARGO_ROOT)
+SKILLS_ROOT = str(_ARGO_ROOT.parent)
+
+# ── 分级用例 ─────────────────────────────────────────────────────────────────
+# expect：文件路径后缀集合，任一命中即算该用例 top 命中（MRR 取最高排名）。
+#   期望文件在改动前经 rg -l 核实确实包含查询词。
+CASES = [
+    # 锚点用例（topk=5）：实现文件是该查询的明确最优，排名恶化即回归
+    {"name": "文件级-噪声档实现", "argv": ["噪声档 降权", "--path", ARGO_ROOT],
+     "expect": ["sub-skills/local-seek/scripts/seek.py"], "topk": 8},
+    {"name": "文件级-pinyin实现", "argv": ["pinyin_initials 拼音", "--path", ARGO_ROOT],
+     "expect": ["sub-skills/local-seek/scripts/seek.py"], "topk": 5},
+    {"name": "文件级-rg_search定义", "argv": ["def rg_search", "--path", ARGO_ROOT],
+     "expect": ["sub-skills/local-seek/scripts/seek.py"], "topk": 5},
+    {"name": "文件级-cache键域隔离", "argv": ["cache_key_vdom", "--path", ARGO_ROOT],
+     "expect": ["scripts/cache_key_vdom.py"], "topk": 5},
+    {"name": "文件级-hash_token实现", "argv": ["def _hash_token", "--path", ARGO_ROOT],
+     "expect": ["scripts/cache.py"], "topk": 5},
+    # 守卫用例（topk=8）：行级语义下文档密集行同样合法，只守「实现文件仍在
+    # top-8 内可被看见」，防实现被彻底挤出视野的回归
+    {"name": "守卫-语义缓存minhash", "argv": ["语义缓存 minhash 软命中", "--path", ARGO_ROOT],
+     "expect": ["scripts/cache.py", "scripts/search_rank.py"], "topk": 8},
+    {"name": "守卫-BM25实现", "argv": ["BM25Okapi k1", "--path", SKILLS_ROOT],
+     "expect": ["sub-skills/local-search/bm25.py"], "topk": 8},
+    {"name": "守卫-中文聚合", "argv": ["本地搜索 聚合", "--path", SKILLS_ROOT],
+     "expect": ["sub-skills/local-search/search_v3.py"], "topk": 8},
+    {"name": "守卫-混排查询", "argv": ["性能 asyncio 教程", "--path", ARGO_ROOT],
+     "expect": ["sub-skills"], "topk": 8},
+    # 行级用例：期望「定义块」而非首次提及出现在 top 行
+    {"name": "行级-NOISE_TIER定义", "argv": ["NOISE_TIER = [", "--path", ARGO_ROOT],
+     "expect_line_range": ("sub-skills/local-seek/scripts/seek.py", 70, 130), "topk": 5},
+    {"name": "行级-K1常数", "argv": ["_K1 = 1.5", "--path", SKILLS_ROOT],
+     "expect_line_range": ("bm25.py", 40, 90),
+     "expect_alt_line_range": ("seek_rank.py", 40, 90), "topk": 5},
+]
+
+# ── 计时用例（中位数，含 1 次预热不计入）─────────────────────────────────────
+TIMING = [
+    {"name": "中文短词", "argv": ["噪声档", "--path", ARGO_ROOT]},
+    {"name": "英文高频词", "argv": ["import", "--path", ARGO_ROOT]},
+    {"name": "多词混排", "argv": ["def run_query timeout", "--path", ARGO_ROOT]},
+    {"name": "skills根宽查询", "argv": ["search", "--path", SKILLS_ROOT, "--dot"]},
+    {"name": "文件名查询", "argv": ["seek", "--path", ARGO_ROOT, "--filename"]},
+]
+
+N_RUNS = 5
+TOP_N = 8
+
+
+def _run_case(argv: list[str]) -> tuple[list[dict], int]:
+    """跑一次 run_query --json，返回 (results 原序, elapsed_ms)。
+
+    自污染防护（与 eval_seek.py 同款）：用例词会命中本文件与 eval_seek.py
+    的用例定义行，统一注入 --exclude 排除自身。
+    """
+    text, rc = s.run_query(argv + ["--exclude", "eval_rank.py",
+                                   "--exclude", "eval_seek.py",
+                                   "--json", "--max", str(TOP_N)], time_budget=10)
+    try:
+        payload = json.loads(text)
+        return payload.get("results", []), int(payload.get("elapsed_ms", 0))
+    except (json.JSONDecodeError, TypeError):
+        return [], rc
+
+
+def run_cases() -> dict:
+    out = {}
+    for case in CASES:
+        results, _ = _run_case(case["argv"])
+        top = [(r.get("path", ""), r.get("line", 0)) for r in results[:TOP_N]]
+        entry: dict = {"top": top}
+        if "expect" in case:
+            rank = 0
+            for i, (p, _ln) in enumerate(top, 1):
+                if any(p.endswith(e) or e in p for e in case["expect"]):
+                    rank = i
+                    break
+            entry["expect_rank"] = rank        # 0 = 未进 top-N
+        elif "expect_line_range" in case:
+            ranges = [case["expect_line_range"]]
+            alt = case.get("expect_alt_line_range")
+            if alt:
+                ranges.append(alt)
+            rank = 0
+            for i, (p, ln) in enumerate(top, 1):
+                if any(p.endswith(fp) and lo <= int(ln or 0) <= hi
+                       for fp, lo, hi in ranges):
+                    rank = i
+                    break
+            entry["expect_rank"] = rank
+        out[case["name"]] = entry
+    return out
+
+
+def run_timing() -> dict:
+    out = {}
+    for case in TIMING:
+        _run_case(case["argv"])                       # 预热（页缓存/解释器路径）
+        samples = []
+        for _ in range(N_RUNS):
+            t0 = time.perf_counter()
+            _run_case(case["argv"])
+            samples.append((time.perf_counter() - t0) * 1000)
+        out[case["name"]] = round(statistics.median(samples), 1)
+    return out
+
+
+def summarize(cases: dict) -> dict:
+    """topk_hit 按每用例自己的 topk 门槛计（锚点 5 / 守卫 8）。"""
+    by_name = {c["name"]: c for c in CASES}
+    hits, total, mrr = 0, 0, 0.0
+    for name, v in cases.items():
+        rank = v.get("expect_rank", 0)
+        topk = by_name.get(name, {}).get("topk", 5)
+        total += 1
+        if 0 < rank <= topk:
+            hits += 1
+        if rank:
+            mrr += 1.0 / rank
+    return {"topk_hit": hits, "n_cases": total, "MRR": round(mrr / total, 4) if total else 0.0}
+
+
+def compare(a: dict, b: dict) -> None:
+    """对比两份 JSON 报告：b 相对 a 的逐用例位移（负 = 排名变好）。"""
+    ca, cb = a.get("cases", {}), b.get("cases", {})
+    print(f"{'用例':24s} {'before':>8s} {'after':>8s}  位移")
+    for name in ca:
+        ra = ca[name].get("expect_rank", 0)
+        rb = cb.get(name, {}).get("expect_rank", 0)
+        delta = (rb - ra) if (ra and rb) else 0
+        mark = "↑" if rb and (not ra or rb < ra) else ("↓" if rb and ra and rb > ra
+                                                       else ("=" if rb == ra else "!"))
+        print(f"{name:24s} {ra or '—':>8} {rb or '—':>8}  {mark} {delta:+d}")
+    ta, tb = a.get("timing", {}), b.get("timing", {})
+    print("\n计时（中位 ms，after / before，比值）：")
+    for k in ta:
+        va, vb = ta[k], tb.get(k, 0)
+        ratio = f"{vb / va:.2f}x" if va else "—"
+        print(f"  {k:16s} {vb:8.1f} / {va:8.1f}  ({ratio})")
+    print(f"\n质量汇总 before: {summarize(ca)}")
+    print(f"质量汇总 after : {summarize(cb)}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="local-seek 排序质量分级评测")
+    ap.add_argument("--json", metavar="PATH", help="同时写 JSON 报告")
+    ap.add_argument("--compare", nargs=2, metavar=("A", "B"),
+                    help="对比两份 JSON 报告后退出")
+    args = ap.parse_args()
+    if args.compare:
+        a = json.loads(Path(args.compare[0]).read_text(encoding="utf-8"))
+        b = json.loads(Path(args.compare[1]).read_text(encoding="utf-8"))
+        compare(a, b)
+        return 0
+    cases = run_cases()
+    timing = run_timing()
+    report = {"cases": cases, "timing": timing, "summary": summarize(cases),
+              "top_n": TOP_N, "n_runs": N_RUNS}
+    print(f"质量汇总: {report['summary']}")
+    for name, v in cases.items():
+        rank = v.get("expect_rank", 0)
+        print(f"  [{rank if rank else '—':>2}] {name}")
+        for p, ln in v["top"][:5]:
+            print(f"        {p}:{ln}")
+    print("\n计时（中位 ms）:")
+    for k, v in timing.items():
+        print(f"  {k:16s} {v:8.1f}")
+    if args.json:
+        Path(args.json).write_text(
+            json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(f"\nJSON 已写 {args.json}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())