argo-search 1.0.1 → 2.9.7

package/scripts/local_seek.py

@@ -0,0 +1,366 @@
+#!/usr/bin/env python3
+"""local_seek.py — 本地文件命中（--include-local 用）。
+
+从 search.py 拆出：本地搜索的宽泛根守卫、子进程调用、结果缓存。
+search.py 的 _run_local_seek 调用点改为从本模块导入。
+
+三个边界（2026-09-27 实测补齐，此前会拖垮整次搜索）：
+
+1. **宽泛根 / 自身安装树直接不查**（见 `_local_seek_dir`）：cwd 是 home、
+    根目录，或落在 argo 自身安装树内时返回 None 并跳过。前者是 22.6 s 事故
+    的根因修复（「显式传 --path」解决不了：子进程继承 cwd，显式传与默认
+    等价）；后者治「常驻 MCP 进程 cwd = 技能目录」导致结果被自身源码污染。
+2. **超时从 20 s 收到 _LOCAL_SEEK_TIMEOUT_S**。本地命中是增强项，不是
+   主结果；它的等待上限必须显著小于用户对一次搜索的耐心。
+3. **TimeoutExpired 必须在这里吞掉**。此前没有 try，该异常一路冒泡到
+   CLI/MCP 调用方（实测栈打到 `subprocess.py:1268`）；上层虽有兜底，
+   但本地命中失败本就不该让整次搜索承担异常路径。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+# 本机文件命中子进程超时（秒）。**必须显著小于 fast/auto 的总预算**：
+# 本地命中是尾部增强项，不是主结果，它的等待不配与搜索引擎同等。
+_LOCAL_SEEK_TIMEOUT_S = 3.0
+
+# 「宽泛根」判定：这些目录**不能**当作本地检索范围。
+# 跨平台补齐（2026-09-29）：/mnt（WSL 挂载根）、/cygdrive（Cygwin）——
+# 此前是 macOS 视角清单，Windows/WSL 的等价宽根漏网。
+_BROAD_LOCAL_ROOTS = ("/", "/tmp", "/private/tmp", "/var", "/usr", "/System",
+                      "/Library", "/Applications", "/Volumes", "/Network",
+                      "/mnt", "/cygdrive")
+
+# Windows 盘符根（C:\ / C:/ / C:）：与上面清单同义，但形态是「字母+冒号」，
+# 用模式判而不用枚举（盘符有 26 个）。
+_WIN_DRIVE_ROOT_RE = re.compile(r"^[A-Za-z]:[\\/]?$")
+
+# argo 自身安装树的根。常驻 MCP 进程的 cwd 就是它（宿主在技能目录里启动
+# 服务），而 `--include-local`（fast/budget 默认开）按 cwd 取范围——于是
+# 每次搜索都把本项目自己的源码与测试当作「本机命中」拼进结果。实测一次
+# 查询 10 条里 5 条是 `tests/*.py`，score 0.9。它不是「宽泛根」而是
+# 「自己的树」：对任何真实查询都只是噪声，故与宽泛根同等跳过。要搜本机
+# 文件仍可 cd 到目标目录，或用 local-seek 的 seek.py --path <目录>。
+_OWN_INSTALL_ROOT = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+
+# 本地文件命中缓存：key = (query, max_n, target) → (写入时间, 结果列表)。
+# 文件修改后 TTL 内可能返回旧结果，对本地文件搜索可接受（文件不频繁修改）。
+# 容量上限 64 条，超出时整表清空（低频增强项，LRU 的简单替代）。
+#
+# TTL 300s → 3600s（2026-10-15，B-4）：本地文件命中是「同一台机器上重复问
+# 同一件事」的增强项，5 分钟的窗在日常用法里几乎等于没有缓存——改一次笔记
+# 之后再问同一个问题，命中率主要被 TTL 而不是被内容变化决定。代价是文件改
+# 动后最长 1 小时可能返回旧命中，本地文件搜索可接受（与落盘缓存同一取舍，
+# 两者共用这个常量才不会再分叉）。
+_LOCAL_SEEK_CACHE: dict[str, tuple[float, list[dict[str, Any]]]] = {}
+_LOCAL_SEEK_TTL_S = 3600.0
+_LOCAL_SEEK_CACHE_MAX = 64
+
+# H2：seek 模块按解析后真实路径缓存（importlib 显式文件定位，不占通用
+# 模块名、不污染 sys.path），进程内只加载一次（实测 0.5ms）。
+_SEEK_MODULE_CACHE: dict[str, Any] = {}
+
+# include-local 的本地搜索 worker 单例（住在被导入模块而非 search.py 顶层，
+# 防 daemon runpy.run_module 重跑 search 顶层时覆写泄漏线程池）。
+_LOCAL_SEEK_EXECUTOR = None
+
+
+def get_local_seek_executor():
+    global _LOCAL_SEEK_EXECUTOR
+    if _LOCAL_SEEK_EXECUTOR is None:
+        import concurrent.futures
+        _LOCAL_SEEK_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="local-seek")
+    return _LOCAL_SEEK_EXECUTOR
+
+# H3：跨进程落盘缓存。CLI 每次新进程，进程内缓存救不了 CLI 重复查询；
+# 落盘缓存让 TTL 内的重复查询（同 query+dir+max）零成本。陈旧语义与
+# 进程内缓存一致，**共用 `_LOCAL_SEEK_TTL_S`（现 3600s）**——两处各写一个字
+# 面量正是它们会分叉的原因。写侧原子替换 + 全异常吞掉：缓存永不破坏搜索。
+_SEEK_DISK_CACHE_MAX = 64
+# 条目形状版本：跨版本改 results 条目字段时，TTL 内的旧形状条目按 miss 处理
+_SEEK_DISK_SCHEMA = 1
+
+
+def _seek_disk_cache_path() -> Path:
+    try:
+        import argo_paths
+        return Path(argo_paths.state_path("local_seek_cache.json"))
+    except Exception:
+        return Path(os.path.expanduser(
+            "~/.cache/unified-search/local_seek_cache.json"))
+
+
+def _seek_disk_cache_get(key: str) -> list[dict[str, Any]] | None:
+    try:
+        p = _seek_disk_cache_path()
+        if not p.is_file():
+            return None
+        with p.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        rec = data.get(key) if isinstance(data, dict) else None
+        if not isinstance(rec, dict):
+            return None
+        if rec.get("v") != _SEEK_DISK_SCHEMA:
+            return None
+        if time.time() - rec.get("ts", 0) >= _LOCAL_SEEK_TTL_S:
+            return None
+        results = rec.get("results")
+        if not isinstance(results, list):
+            return None
+        # 返回拷贝：缓存持有所有权，调用方就地改写（_engine 标记等）不得污染缓存
+        return [dict(r) if isinstance(r, dict) else r for r in results]
+    except Exception:
+        return None
+
+
+def _seek_disk_cache_put(key: str, results: list[dict[str, Any]]) -> None:
+    try:
+        p = _seek_disk_cache_path()
+        now = time.time()
+        try:
+            with p.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+            data = data if isinstance(data, dict) else {}
+        except Exception:
+            data = {}  # 损坏文件：整表重建（缓存可牺牲，搜索不可牺牲）
+        data = {k: v for k, v in data.items()
+                if isinstance(v, dict) and now - v.get("ts", 0) < _LOCAL_SEEK_TTL_S}
+        data[key] = {"v": _SEEK_DISK_SCHEMA, "ts": now, "results": results}
+        if len(data) > _SEEK_DISK_CACHE_MAX:
+            for k in sorted(data, key=lambda k: data[k].get("ts", 0)
+                            )[:len(data) - _SEEK_DISK_CACHE_MAX]:
+                data.pop(k, None)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            import argo_paths
+            argo_paths.atomic_write_json(p, data, indent=None)  # mkstemp 唯一 tmp，失败自清理
+        except (ImportError, AttributeError, OSError):
+            tmp = p.with_name(f"{p.name}.{os.getpid()}.tmp")
+            with tmp.open("w", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False)
+            os.replace(tmp, p)  # 原子替换：并发写不会留下半截文件
+    except Exception:
+        pass
+
+
+def _is_broad_local_root(path: str) -> bool:
+    """path 是否是「不能当作本地检索范围」的宽泛根。
+
+    判据从 _local_seek_dir 提取为可复用函数：MCP 的 argo_local_search
+    默认 path="~"，与 CLI 的 cwd 缺省是同一类事故形态（2026-09-27 实测
+    MCP 侧对整个 home 跑 rg，30 s 后报错返回），两侧必须共用同一判据。
+    """
+    try:
+        real = os.path.realpath(path)
+    except OSError:
+        return True
+    home = os.path.realpath(os.path.expanduser("~"))
+    if real == home:
+        return True
+    # 盘符根同时查原始与 realpath 形态：realpath 在 POSIX 上会把 "C:\"
+    # 当相对路径拼接（cwd + "/C:\"），只有 raw 形态还能保住判据。
+    if _WIN_DRIVE_ROOT_RE.match(path) or _WIN_DRIVE_ROOT_RE.match(real):
+        return True
+    for root in _BROAD_LOCAL_ROOTS:
+        if real == root or real == os.path.realpath(root):
+            return True
+    return False
+
+
+def _is_own_install_root(path: str) -> bool:
+    """path 是否落在 argo 自身安装树内（含其根目录本身）。"""
+    try:
+        real = os.path.realpath(path)
+    except OSError:
+        return False
+    return real == _OWN_INSTALL_ROOT or real.startswith(_OWN_INSTALL_ROOT + os.sep)
+
+
+def _local_seek_dir() -> str | None:
+    """本地检索的适用范围；宽泛根或自身安装树返回 None（据此跳过本地命中）。
+
+    宁可返回 None 也不返回一个「象征性收窄」的路径：本地命中是增强项，
+    在范围不合理时**不产出**比产出噪音 + 20 s 等待更符合用户预期。
+    用户想搜特定树时 cd 到目标目录，或用 local-seek 的 seek.py 显式给
+    --path（网络类查询另有 argo search --local-first 走本地引擎聚合），
+    那条路径不受此守卫影响。
+    """
+    cwd = os.getcwd()
+    if _is_broad_local_root(cwd) or _is_own_install_root(cwd):
+        return None
+    return cwd
+
+
+def _run_local_seek(query: str, max_n: int = 5,
+                    search_dir: str | None = None) -> list[dict[str, Any]]:
+    """本机文件命中（include-local 用）：进程内调 seek.run_query，JSON 并入。
+
+    fast/budget 模式下由 super_search 自动调用（_resolve_include_local），
+    auto/deep 需显式 --include-local / MCP include_local。评分与
+    MCP argo_local_search 同口径（0.9 精确 / 0.7 扩展）。
+    进程内失败回退子进程形态（_seek_query_subprocess），能力不回退。
+    """
+    target = search_dir or _local_seek_dir()
+    if not target:
+        # 宽泛根：不查，但必须留下可归因的痕迹（docstring 第 1 条）。
+        # 「跳过」与「查了没有」在返回值上都是空列表，但含义完全不同——
+        # 静默跳过会让用户以为本地没匹配，而事实是根本没查。返回一个
+        # 占位「结果」又会污染 results（它只是个说明，不是命中），所以
+        # 说明走 stderr：与 CLI 既有的 include-local 异常提示同一条通道。
+        sys.stderr.write(
+            "  [include-local] 当前目录不适合本地检索（home / 根目录过宽，或位于 argo "
+            "自身安装树内——只会命中自身源码），已跳过；"
+            "要搜本机文件请 cd 到目标目录后重试，或用 local-seek 的 seek.py --path <目录>\n")
+        return []
+
+    # 缓存：同 query+target 在 TTL 内直接命中，避免重复冷启动 seek.py 子进程。
+    # 文件修改后 TTL 内可能返回旧结果，对本地文件搜索可接受（文件不频繁修改）。
+    cache_key = f"{query}|{max_n}|{target}"
+    cached = _LOCAL_SEEK_CACHE.get(cache_key)
+    if cached is not None and time.time() - cached[0] < _LOCAL_SEEK_TTL_S:
+        return cached[1]
+
+    # H3：跨进程落盘缓存（CLI 每次新进程，进程内缓存救不了 CLI 重复查询；
+    # MCP 常驻进程通常在内存层就命中，落盘层对它是兜底）。命中后回填内存层。
+    disk_hit = _seek_disk_cache_get(cache_key)
+    if disk_hit is not None:
+        if len(_LOCAL_SEEK_CACHE) >= _LOCAL_SEEK_CACHE_MAX:
+            _LOCAL_SEEK_CACHE.clear()
+        _LOCAL_SEEK_CACHE[cache_key] = (time.time(), disk_hit)
+        return disk_hit
+
+    # 安装感知 + 唯一来源：委托 seek_locator 统一发现 local-seek/scripts/seek.py
+    # （打包子技能优先，ARGO_LOCAL_SEEK_PATH / ARGO_LOCAL_SEEK_ROOTS 承载自定义/遗留）。
+    # 不硬编码 ~/.agents/skills|~/.claude/skills 主机路径（SKILL.md 明令禁止）。
+    from seek_locator import resolve_seek_py
+    seek_py = resolve_seek_py()
+    if not seek_py or not os.path.isfile(seek_py):
+        return []
+
+    # H2（2026-09-29）：进程内直调 seek.run_query——省掉子进程解释器启动
+    # （实测 30-110ms/次，子进程总成本 60-140ms vs 进程内 ~30ms，落点即 rg
+    # 本体）。seek 模块 stdlib-only，import 实测 0.5ms；time_budget 下传到
+    # 内部 rg/fd 子进程（子进程可硬杀，线程不可杀——不传会占死单线程 executor）。
+    # 进程内失败（模块加载/执行异常）回退子进程路径：能力不回退，只是慢。
+    payload = None
+    try:
+        payload = seek_query_payload(query, target, max_n,
+                                     time_budget=_LOCAL_SEEK_TIMEOUT_S)
+    except Exception:
+        payload = None
+    if payload is None:
+        payload = _seek_query_subprocess(seek_py, query, target, max_n)
+    if payload is None:
+        return []
+    out = _payload_to_hits(payload, max_n, cache_key)
+    _seek_disk_cache_put(cache_key, out)  # H3：写穿到落盘层
+    return out
+
+
+def _load_seek_module(seek_py: str):
+    """按解析后真实路径加载 seek 模块（importlib 显式文件定位，不污染
+    sys.path、不占通用模块名），按路径缓存——ARGO_LOCAL_SEEK_PATH 指向
+    不同文件时各自独立加载。失败返回 None。"""
+    mod = _SEEK_MODULE_CACHE.get(seek_py)
+    if mod is not None:
+        return mod
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("argo_seek_impl", seek_py)
+    if spec is None or spec.loader is None:
+        return None
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    _SEEK_MODULE_CACHE[seek_py] = mod
+    return mod
+
+
+def seek_query_payload(query: str, target: str, max_n: int,
+                       exact: bool = False, time_budget: float | None = None
+                       ) -> dict[str, Any] | None:
+    """H2 公共入口：进程内调 seek.run_query 取 JSON payload。
+
+    include-local（_run_local_seek）与 MCP argo_local_search 共用——两条
+    调用路径同一实现（单一来源）。失败/无匹配返回 None，调用方自行回退
+    （子进程形态或直接报无结果）。
+    """
+    from seek_locator import resolve_seek_py
+    seek_py = resolve_seek_py()
+    if not seek_py or not os.path.isfile(seek_py):
+        return None
+    mod = _load_seek_module(seek_py)
+    if mod is None:
+        return None
+    argv = [query, "--json", "--max", str(max(max_n, 1)), "--path", target]
+    if exact:
+        argv.append("--exact")
+    text, rc = mod.run_query(argv, time_budget=time_budget)
+    if rc != 0:
+        # rc=1 是「搜了没命中」，不是「真失败」——区分两者避免子进程回退
+        # 把同一搜索再跑一遍（实测 787ms vs 命中路径 12ms，双跑税 ~775ms）。
+        # 无命中返回空结果（不回退）；真失败返回 None（调用方回退子进程）。
+        if rc == 1 and not text.strip():
+            return {"results": [], "total": 0}
+        return None
+    if not text.strip():
+        return None
+    return json.loads(text)
+
+
+def _seek_query_subprocess(seek_py: str, query: str, target: str,
+                           max_n: int) -> dict[str, Any] | None:
+    """子进程形态取 payload（H2 前的唯一路径，现为进程内失败的回退）。"""
+    import subprocess as _sp
+    cmd = [sys.executable, seek_py, query, "--json", "--max", str(max(max_n, 1)),
+           "--path", target]
+    try:
+        r = _sp.run(
+            cmd, capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=_LOCAL_SEEK_TIMEOUT_S,
+            env={**os.environ, "PYTHONUTF8": "1"},  # 子进程是自家 seek.py，双向显式 UTF-8
+        )
+    except _sp.TimeoutExpired:
+        return None  # 本地命中是增强项：超时即弃，不冒泡（docstring 第 2、3 条）
+    except OSError:
+        return None  # 解释器/脚本不可执行等环境问题：同样不该拖垮主搜索
+    if r.returncode != 0 or not r.stdout.strip():
+        return None
+    try:
+        return json.loads(r.stdout)
+    except ValueError:
+        return None
+
+
+def _payload_to_hits(payload: dict[str, Any], max_n: int,
+                     cache_key: str) -> list[dict[str, Any]]:
+    """seek payload → include-local 结果条目（评分与 MCP argo_local_search
+    同口径：0.9 精确命中 / 0.7 扩展召回），并写入进程内缓存。"""
+    hits = payload.get("results") or payload.get("files") or []
+    seek_mode = payload.get("mode", "fast")
+    hit_score = 0.9 if seek_mode == "fast" else 0.7
+    out = []
+    for h in hits[:max_n]:
+        if not isinstance(h, dict):
+            continue
+        path = h.get("path") or h.get("file") or ""
+        line = h.get("line") or h.get("lineno") or 1
+        url = f"file://{path}" + (f"#{line}" if str(line).isdigit() else "")
+        out.append({
+            "title": path,
+            "url": url,
+            "snippet": (h.get("snippet") or h.get("text") or h.get("line_text") or "")[:160],
+            "source": "local_files",
+            "score": hit_score,
+            "kind": "local",
+        })
+    if len(_LOCAL_SEEK_CACHE) >= _LOCAL_SEEK_CACHE_MAX:
+        _LOCAL_SEEK_CACHE.clear()
+    _LOCAL_SEEK_CACHE[cache_key] = (time.time(), out)
+    return out

package/scripts/macro_countries.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""macro_countries.py — 宏观域的「国家词」判定与国名/代码表。
+
+## 为什么单独成模块
+
+这张表 + 两个纯文本谓词原先住在 `engines_builders_data_macro.py` 里，而那个
+模块会连带来整条 HTTP 栈（`engines_base` → `http_client` → urllib/ssl/cookiejar）。
+`route.py` 为了调用 `is_foreign_macro_query` 就得在模块顶层 import 它——实测
+**36 ms**，占 `import route` 的绝大部分（路由总耗时约 42 ms）。
+
+路由是每次调用的必经路径（连缓存命中也要走一遍），而 HTTP 栈只有真正打网时
+才需要。把纯逻辑与网络栈拆开，路由路径就再也不付这笔钱；顺带也不用为了省它
+而引入「首次调用才 import」的惰性包装（那会带来隐藏状态与首调用毛刺）。
+
+依赖只有 `re`。本模块必须保持零重依赖——这是它能被路由层直接引用的前提。
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["WORLDBANK_COUNTRIES", "match_country", "is_foreign_macro_query"]
+
+# 国家名/别名 → ISO 代码。worldbank 引擎解析国家、fred 引擎国家词守卫、
+# route 层分流的唯一来源（此前注释里写着「共用」，但三处都在同一个模块里，
+# 拆出来之后这句话才真正成立）。
+WORLDBANK_COUNTRIES: dict[str, str] = {
+    "中国": "CHN", "china": "CHN", "美国": "USA", "usa": "USA", "us": "USA",
+    "united states": "USA", "america": "USA", "日本": "JPN", "japan": "JPN",
+    "德国": "DEU", "germany": "DEU", "英国": "GBR", "uk": "GBR",
+    "united kingdom": "GBR", "britain": "GBR", "法国": "FRA", "france": "FRA",
+    "印度": "IND", "india": "IND", "巴西": "BRA", "brazil": "BRA",
+    "俄罗斯": "RUS", "russia": "RUS", "韩国": "KOR", "korea": "KOR",
+    "south korea": "KOR", "加拿大": "CAN", "canada": "CAN",
+    "澳大利亚": "AUS", "australia": "AUS", "意大利": "ITA", "italy": "ITA",
+    "西班牙": "ESP", "spain": "ESP", "世界": "WLD", "world": "WLD",
+    "global": "WLD", "欧元区": "EMU", "eurozone": "EMU", "香港": "HKG",
+    "hong kong": "HKG", "台湾": "TWN", "taiwan": "TWN", "新加坡": "SGP",
+    "singapore": "SGP",
+}
+
+
+def match_country(query: str, mapping: dict[str, str]) -> str:
+    """大小写不敏感国家匹配（中文原名 + 英文别名）。
+
+    短别名（us/uk/eu 等 ≤3 字符）用词边界匹配，避免 'focus'/'consensus'
+    之类包含子串的普通词误判为国家。
+    """
+    low = query.lower()
+    for name, code in mapping.items():
+        # 中文/长英文名直接子串匹配；短别名（≤3 字符）必须走词边界分支
+        if name in query and (not name.isascii() or len(name) > 3):
+            return code
+        if name.isascii():
+            if len(name) <= 3:
+                if re.search(rf"(?<![a-z]){re.escape(name)}(?![a-z])", low):
+                    return code
+            elif name in low:
+                return code
+    return ""
+
+
+# 非美国国家/地区子集：FRED 是美国计算方式，只有「明确指向别国」时才让位。
+# 从主表派生而非另抄一份，避免两张表漂移。
+_NON_US_COUNTRIES: dict[str, str] = {
+    name: code for name, code in WORLDBANK_COUNTRIES.items() if code != "USA"
+}
+
+
+def is_foreign_macro_query(query: str) -> bool:
+    """查询是否明确指向非美国国家/地区。
+
+    FRED 序列均为美国或全球计算方式，遇到「中国GDP」「日本通胀」这类查询时
+    应放弃响应（返回 True），由 worldbank 按国家参数接管，避免美国数据冒充。
+
+    判定复用 `match_country` 的词边界逻辑，而不是自己写一遍朴素子串匹配。
+    此前这里是 `name in query`：`us` 这类 ≤3 字符别名会命中任何含该子串的
+    英文词——实测 `focus on growth`、`consensus 预测`、`business survey`
+    全被判成「外国宏观查询」，FRED 因而被无谓地排除。同一个概念（国家词识别）
+    在同一模块里有两套行为不同的实现，正是这类漏判的来源。
+    """
+    return bool(match_country(query, _NON_US_COUNTRIES))