argo-search 1.0.1 → 2.9.8

package/scripts/config.py

@@ -7,19 +7,62 @@ config.py — Unified Search v2 配置加载器
   - 支持热加载（按 mtime 缓存）
   - 使用 PyYAML 解析（缺失时给出明确安装提示）
   - 将 ~ 展开为实际用户目录
+  - 合并 engines/*.yaml 外置引擎声明
+  - 合并 config.local.yaml 本机覆盖层（gitignore，本机状态不进公开仓）
   - 提供类型化访问接口（引擎列表、域规则、成本分级、预算配置）
 """
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
+import time
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
 # ── 路径 ──────────────────────────────────────────────────────────────────────
 
+# logging 延迟导入（已实施）：config.py 的 import 链实测 23ms，其中 logging 占 ~10ms。
+# 全文件仅 1 处 warning 使用（routable_only 过滤降级留痕），在该函数内 import，
+# 模块级导入会让所有 import config 的路径白付 ~10ms/次。
+# shutil 同样惰性化：唯一用点是 _validate_engine_paths 的 shutil.which（裸命令
+# PATH 探测），模块级 import 会让每个进程（含纯缓存命中的搜索）白付 ~3ms，
+# 且拖着 zlib/bz2/lzma。测试对 patch.object(config_mod.shutil, ...) 的依赖
+# 由模块 __getattr__ 保持（见文件末尾）——惰性导入与可打桩性不再二选一。
+
 CONFIG_PATH = Path(__file__).parent.parent / "config.yaml"
+# 本机覆盖层：与 config.yaml 同目录的 config.local.yaml（**gitignore**）。
+# 只写「要改的键」，深度合并进最终配置——本机状态（账户欠费临时停用某引擎、
+# 本机路径、本机调优）落在这里，不随公开仓发版。详见 _merge_local_config。
+LOCAL_CONFIG_PATH = Path(__file__).parent.parent / "config.local.yaml"
+# 外置引擎声明目录：engines/*.yaml（不含 plugins/、templates/、_ 前缀）
+ENGINES_DIR = Path(__file__).parent.parent / "engines"
+
+# 本地状态目录唯一来源。argo_paths 只在函数体内反向 import config，
+# 因此此处模块级导入不会成环（config 未就绪时 argo_paths 会回落到历史目录）。
+import argo_paths  # noqa: E402
+
+# 跨进程配置磁盘缓存（性能层）住在 config_cache；这里同名转出：load_config /
+# peek_cache_db_path / _cli 与既有测试（config._config_content_digest …）无需改。
+# 打桩点若落在这些符号上，必须打在**读取处**（config_cache）。
+from config_cache import (  # noqa: E402
+    _CONFIG_DISK_CACHE_SCHEMA,
+    _config_disk_cache_enabled,
+    _config_disk_cache_path,
+    _config_disk_cache_key,
+    _config_db_path_key,
+    _config_content_digest,
+    _disk_cache_payload,
+    _json_round_trip_safe,
+    _load_config_disk_cache,
+    _looks_like_config,
+    _loader_sig,
+    _peek_disk_cache_db_path,
+    _save_config_disk_cache,
+    _sweep_orphan_cache_slots,
+)
+from cli_io import dumps
 
 
 # ── 默认配置 ──────────────────────────────────────────────────────────────────
@@ -28,8 +71,10 @@ DEFAULT_CONFIG: dict[str, Any] = {
     "version": 2,
     "engines": {
         "anysearch": {
-            "enabled": True, "type": "cli",
-            "cmd": ["python3", "~/.agents/skills/anysearch-skill/scripts/anysearch_cli.py"],
+            "enabled": True, "type": "anysearch",
+            # 进程内 JSON-RPC builder（保持一致 config.yaml 来源）；不调用主机上的
+            # anysearch-skill CLI，避免写死 ~/.agents/skills 主机路径（纪律：禁止）。
+            "label": "AnySearch", "cost_tier": "free",
             "search_args": ["search", "{query}", "--max_results", "{n}"],
             "env": {},
         },
@@ -41,9 +86,10 @@ DEFAULT_CONFIG: dict[str, Any] = {
             "fallback": "anysearch", "parallel": True,
         },
     ],
-    "cache": {"enabled": True, "db_path": "~/.cache/unified-search/cache.db", "ttl": 3600, "max_size_mb": 200},
-    "execution": {"default_timeout": 8, "parallel_timeout": 6, "max_parallel_engines": 3, "retry_count": 0},
-    "cost_tiers": {"free": ["anysearch"], "low": [], "paid": []},
+    # db_path 由 argo_paths 唯一来源派生，不再字面量拼 ~/.cache/unified-search。
+    # 无 ARGO_STATE_DIR 时展开结果与历史默认一致，存量缓存不失效。
+    "cache": {"enabled": True, "db_path": str(argo_paths.db_path()), "ttl": 3600, "max_size_mb": 200},
+    "execution": {"default_timeout": 8, "max_parallel_engines": 6, "retry_count": 0},
     "budget": {
         "fast": {"max_cost_per_query": 0.0, "allow_paid": False},
         "auto": {"max_cost_per_query": 0.01, "allow_paid": True},
@@ -65,8 +111,14 @@ def _require_yaml():
 
 
 def _load_yaml(text: str) -> dict[str, Any]:
-    yaml = _require_yaml()
-    parsed = yaml.safe_load(text)
+    """解析 YAML —— 统一走 yaml_load（优先 libyaml C 版 loader）。
+
+    此前直接调 `yaml.safe_load`，走的是纯 Python 扫描器：解析 123 KB 的
+    config.yaml 实测 79 ms，C 版同内容 10 ms。冷启动链上同一份配置会被解析
+    多次，差距被成倍放大。详见 yaml_load.py。
+    """
+    from yaml_load import loads
+    parsed = loads(text)
     return parsed if isinstance(parsed, dict) else {}
 
 
@@ -115,9 +167,16 @@ def _resolve_relative_paths(config: dict[str, Any]) -> dict[str, Any]:
 
 
 def _validate_engine_paths(config: dict[str, Any]) -> dict[str, Any]:
-    """验证引擎 CLI 路径，不存在则标记为 disabled。"""
-    import logging as _logging
-    _log = _logging.getLogger("unified_search.config")
+    """验证引擎 CLI 路径，不存在则标记为 disabled。
+
+    相对路径一律以 config.yaml 所在目录为基准解析（不是进程 CWD）。外置 spec
+    （engines/specs/*.yaml）的 cmd 是相对路径，而 _resolve_relative_paths 在
+    合并外置声明之前就已执行，故这些路径不会被转成绝对路径。若这里用
+    Path(cmd[-1]).exists() 判定，结果就随 CWD 变——实测同一份配置在仓库根
+    目录下 165 个引擎可用、在 /tmp 下只剩 163（train/weather 被静默停用），
+    一致性检查也随之红/绿漂移。
+    """
+    base = CONFIG_PATH.parent
     for name, spec in config.get("engines", {}).items():
         if not isinstance(spec, dict) or spec.get("type") != "cli":
             continue
@@ -128,60 +187,507 @@ def _validate_engine_paths(config: dict[str, Any]) -> dict[str, Any]:
         if cmd_path_str.startswith("--"):
             continue
         cmd_path = Path(cmd_path_str).expanduser()
-        if not cmd_path.exists():
+        if not cmd_path.is_absolute():
+            cmd_path = base / cmd_path
+        if cmd_path.exists():
+            continue
+        # 裸命令（如 PATH 中的可执行文件）：用 shutil.which 查 PATH，查不到才禁用
+        import shutil  # 惰性导入：见顶部注释；__getattr__ 保持 config_mod.shutil 可打桩
+        if not (shutil.which(cmd_path_str) or shutil.which(cmd_path.name)):
             spec["enabled"] = False
     return config
 
 
-def load_config(force: bool = False) -> dict[str, Any]:
-    """加载配置，支持热加载。"""
-    global _config_cache, _config_mtime, _config_load_error
+def _load_external_engine_specs() -> dict[str, dict[str, Any]]:
+    """加载 engines/*.yaml 与 engines/specs/*.yaml 外置声明。
+
+    文件名（去后缀）默认为 engine_id；文件内 engine_id / name 可覆盖。
+    跳过：_ 前缀文件。
+    """
+    result: dict[str, dict[str, Any]] = {}
+    if not ENGINES_DIR.is_dir():
+        return result
+    try:
+        yaml = _require_yaml()
+    except ImportError:
+        return result
+    from yaml_load import loads as _yaml_loads
+
+    def _load_dir(directory: Path) -> None:
+        if not directory.is_dir():
+            return
+        for path in sorted(directory.glob("*.yaml")):
+            if path.name.startswith("_"):
+                continue
+            try:
+                data = _yaml_loads(path.read_text(encoding="utf-8")) or {}
+            except Exception:
+                continue
+            if not isinstance(data, dict):
+                continue
+            # 允许 {engine_id, ...} 或直接是 engine spec
+            engine_id = data.get("engine_id") or data.get("name") or path.stem
+            if not isinstance(engine_id, str) or not engine_id:
+                continue
+            spec = dict(data)
+            spec.pop("engine_id", None)
+            # name 字段若是展示名且与 id 不同，保留；type 必须有
+            if "type" not in spec and "url" in spec:
+                spec["type"] = "http"
+            if "enabled" not in spec:
+                spec["enabled"] = True
+            spec["_external_spec"] = str(path)
+            result[engine_id] = spec
+
+    _load_dir(ENGINES_DIR)
+    _load_dir(ENGINES_DIR / "specs")
+    return result
+
+
+def _merge_external_engines(config: dict[str, Any]) -> dict[str, Any]:
+    """外置 YAML 覆盖/新增引擎；cost_tiers 可选追加。"""
+    external = _load_external_engine_specs()
+    if not external:
+        return config
+    engines = config.setdefault("engines", {})
+    if not isinstance(engines, dict):
+        engines = {}
+        config["engines"] = engines
+    for eid, spec in external.items():
+        # 外置优先覆盖同名（便于本地试验）
+        base = dict(engines.get(eid) or {})
+        base.update(spec)
+        engines[eid] = base
+    # 注：不再维护独立的 cost_tiers 段。成本分级由 get_cost_tiers() 从 engines
+    # 段的 cost_tier 字段聚合，独立段是第二份计算方式（曾与声明矛盾：zhihu_global
+    # 列在 free 而声明 api、tavily 列在 paid 而声明 api），且无任何读取方。
+    return config
+
+
+def _load_local_config() -> dict[str, Any]:
+    """读本机覆盖层 config.local.yaml；不存在 / 读不动 / 损坏一律返回 {}。
+
+    fail-open 是刻意的：覆盖层是可选的加速器，它的缺失或损坏不该让整条配置链
+    崩掉（与 cache 的降级、config 的 DEFAULT_CONFIG 回退同一口径）。损坏时
+    静默忽略而不是抛，是为了不把「本机一个手滑的 YAML」升级成「所有命令都跑
+    不了」——真要排查时看 last_load_error 之外没有提示，所以这里连告警都不发，
+    保持与「覆盖层不存在」完全同一条路径（区分它们没有运维价值）。
+    """
+    if not LOCAL_CONFIG_PATH.is_file():
+        return {}
+    try:
+        text = LOCAL_CONFIG_PATH.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        data = _load_yaml(text)
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """override **深度**覆盖 base：dict 逐键递归，其余（含 list）整体替换。
+
+    与 _merge_external_engines 的**浅**覆盖（`base.update(spec)`）刻意不同：
+    外置 spec 是「整份引擎声明」（浅覆盖才能整份换掉），本机覆盖层是「只写要
+    改的键」（深合并才能让 `engines.parallel.enabled: false` 只翻一个布尔而不
+    把整个 parallel 声明换成三行）。两种覆盖语义不同，各留一处实现，别合并。
+    """
+    out = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def _merge_local_config(config: dict[str, Any]) -> dict[str, Any]:
+    """把本机覆盖层并进配置；无覆盖层时原样返回（不复制，省一份 220 引擎的拷贝）。"""
+    local = _load_local_config()
+    return _deep_merge(config, local) if local else config
+
+
+_ext_scan_cache: tuple[float, tuple[float, int, int, str]] | None = None  # (monotonic 时刻, 指纹)
+
+
+def _external_engines_scan_uncached() -> tuple[float, int, int, str]:
+    """扫一遍外置声明目录 → (最新 mtime, 文件数, 总字节, 声明集摘要)。
+
+    为什么不能只报 mtime：**max 对「删除」与「回填旧时间」是盲的**——删掉一个
+    不是最新的声明（engines/specs/train.yaml 之类），max 不变；`cp -p` 拷进来
+    一个新声明（mtime 被保留成旧值），max 也不变。两者都会让写入文件配置缓存继续
+    命中，表现为「引擎删了还在 / 加了不生效」（审计实测）。文件数与总字节对
+    集合变化敏感；摘要按**每个文件**的 (相对路径, 大小, mtime_ns, ctime_ns)
+    聚合成一个值，能识别「总量不变但换了文件」这类集合替换。
+
+    这里刻意**不读文件内容**：65 个声明逐个 read_bytes 实测 9.5 ms，等于把省下
+    的时间吃掉一半。跨平台语义保底交给 config.yaml 的内容摘要（它是决定状态
+    目录的那份文件，见 _config_content_digest）：Windows 上 st_ctime 是创建
+    时间而非元数据变更时间，本摘要因此退化为「路径集 + 大小 + mtime」，仍能
+    覆盖编辑器改文件（mtime 变）与增删声明；只有「改写内容并还原 mtime」这种
+    刻意手法在 Windows 上漏检，而 POSIX 上 ctime 仍然兜着。
+    """
+    latest = 0.0
+    count = 0
+    total = 0
+    digest = hashlib.blake2b(digest_size=16)
+    if not ENGINES_DIR.is_dir():
+        return latest, count, total, digest.hexdigest()
+    for path in sorted(ENGINES_DIR.rglob("*.yaml")):
+        if "plugins" in path.parts:
+            continue
+        try:
+            st = path.stat()
+            rel = path.relative_to(ENGINES_DIR)
+        except (OSError, ValueError):
+            continue
+        count += 1
+        total += st.st_size
+        latest = max(latest, st.st_mtime)
+        digest.update(f"{rel}\0{st.st_size}\0{st.st_mtime_ns}\0{st.st_ctime_ns}\n".encode())
+    return latest, count, total, digest.hexdigest()
+
+
+def _ttl_memo(cache: tuple[float, float] | None, ttl: float,
+              compute: Callable[[], float]) -> tuple[tuple[float, float] | None, float]:
+    """TTL 记忆化的唯一实现：TTL 内复用 cache，否则调 compute 并回填。
+
+    同一个形状（`if ttl>0 and cache and now-cache[0]<ttl: return cache[1]`）
+    此前在外置引擎 mtime 与 config_stamp 各写一遍，失效语义靠人工保持一致——
+    一处改了 force 语义、另一处没改，就是这类漂移的温床（review 实测点出）。
+    返回 (新 cache, 取值)：ttl<=0 时不写记忆（关闭记忆化的逃生门）。
+    """
+    now = time.monotonic()
+    if ttl > 0 and cache is not None and now - cache[0] < ttl:
+        return cache, cache[1]
+    value = compute()
+    if ttl > 0:
+        return (now, value), value
+    return cache, value
+
+
+def _remember_ext_scan(scan: tuple[float, int, int, str]) -> None:
+    """把刚测到的外置声明指纹回填记忆——force 重读后不必立刻再扫一遍。"""
+    global _ext_scan_cache
+    if _stamp_ttl() > 0:
+        _ext_scan_cache = (time.monotonic(), scan)
+
+
+def _external_engines_scan() -> tuple[float, int, int, str]:
+    """外置声明目录指纹，按与 config_stamp 相同的 TTL 记忆。"""
+    global _ext_scan_cache
+    _ext_scan_cache, value = _ttl_memo(
+        _ext_scan_cache, _stamp_ttl(), _external_engines_scan_uncached)
+    return value
+
+
+def _external_engines_mtime() -> float:
+    """外置引擎声明目录的最新 mtime，按与 config_stamp 相同的 TTL 记忆。
+
+    扫一遍要 rglob 并 stat 全部外置声明（约 60 个文件、60 多次系统调用）。
+    load_config() 与 config_stamp() 在一次搜索里会被调用十几次，此前每次都
+    重新扫盘，实测一次搜索因此产生约 900 次 stat，绝大多数是在重复读不会变
+    的文件。外置声明新增/改动晚 1 秒生效没有实际影响，所以在 TTL 内只扫一次
+    （TTL 由 ARGO_CONFIG_STAMP_TTL_S 控制，设 0 即关闭记忆、每次即时扫描）。
+    """
+    return _external_engines_scan()[0]
+
+
+_stamp_cache: tuple[float, float] | None = None  # (monotonic 时刻, stamp)
+
+
+def _stamp_ttl() -> float:
+    """stamp 记忆化的 TTL（秒）。每次读，便于测试与现场调参。
+
+    走 engine_env.get_env 而非 os.environ 直读：开关写进 ~/.config/argo/env
+    （密钥与开关的规范位置）也要生效——这正是 env_flag 统一布尔计算方式时定下的
+    契约，同一个旋钮不该有两套可读位置。engine_env 只依赖标准库，懒导入避免
+    与 config 成环；导入或读取失败一律回落到 os.environ 与默认值。
+    """
+    name = "ARGO_CONFIG_STAMP_TTL_S"
+    raw = os.environ.get(name, "")
+    if not raw.strip():
+        try:
+            from engine_env import get_env
+            raw = get_env(name)
+        except Exception:
+            raw = ""
+    try:
+        return float(raw or 1.0)
+    except ValueError:
+        return 1.0
+
+
+def config_stamp() -> float:
+    """config.yaml + 外置引擎声明的综合 mtime（供 registry 等热加载判断）。
+
+    按 TTL 记忆化（默认 1 s，`ARGO_CONFIG_STAMP_TTL_S` 可调，设 0 即关闭）：
+    取值要 stat 全部 63 个外置声明文件，而 `engines.get_registry()` **每访问
+    一次**注册表就会调它一次——实测一次搜索触发 28 次调用 = 1764 次 stat，
+    99% 是重复劳动。热加载不要求亚秒级感知（配置改动晚 1 秒生效无实际影响），
+    故折叠到 TTL 内一次。
+    """
+    global _stamp_cache
+    _stamp_cache, value = _ttl_memo(_stamp_cache, _stamp_ttl(),
+                                    _stamp_uncached)
+    return value
+
+
+def _local_config_mtime() -> float:
+    """本机覆盖层 config.local.yaml 的 mtime（不存在 → 0.0）。
+
+    与 config_stamp 的 TTL 记忆同一口径：覆盖层也是「会变的输入」，不进 stamp
+    就会出现「改了本机覆盖层、1 秒内不生效」（load_config 的 _config_mtime 与
+    config_stamp 是两条独立的失效判据，都必须认它）。
+    """
+    try:
+        return LOCAL_CONFIG_PATH.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def _stamp_uncached() -> float:
+    try:
+        combined = CONFIG_PATH.stat().st_mtime
+    except OSError:
+        combined = 0.0
+    return max(combined, _external_engines_mtime(), _local_config_mtime())
+
+
+
+
+def _load_config_public(force: bool = False) -> dict[str, Any]:
+    """加载**公共**配置（config.yaml + engines/*.yaml 外置声明），含全部缓存逻辑。
+
+    刻意不含本机覆盖层：公共配置要能被「派生随公开仓发版的产物」复用
+    （sync_backends 生成 engine_registry.yaml / quota_profiles.json），本机状态
+    不该进那两份派生件——否则本机跑一次 sync 就把本地覆盖层写进了公开仓。
+    本机覆盖层由 load_config 按需并入（见那边的说明）。
+    """
+    global _config_cache, _config_mtime, _config_load_error, _stamp_cache
     try:
-        mtime = CONFIG_PATH.stat().st_mtime
+        st = CONFIG_PATH.stat()
+        mtime = st.st_mtime
     except OSError:
         if _config_cache is None:
-            _config_cache = _validate_engine_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG))))
+            base = _validate_engine_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG))))
+            _config_cache = _merge_external_engines(base)
         return _config_cache
 
-    if not force and _config_cache is not None and mtime == _config_mtime:
+    # force=True 表示调用方明确要立即重读（如 --check、测试改写配置后），
+    # 此时绕过 TTL 记忆直接扫盘，保证强制刷新语义不被记忆化延迟。
+    scan = (_external_engines_scan_uncached() if force
+            else _external_engines_scan())
+    ext_mtime = scan[0]
+    combined_mtime = max(mtime, ext_mtime, _local_config_mtime())
+
+    if force:
+        # force 语义必须贯穿**所有**同级缓存，否则重读与快照脱节：外置声明
+        # 指纹记忆留着旧值 → 本函数下一次非 force 调用按旧值判定「没变」；
+        # stamp 记忆留着旧值 → 1 秒内 get_registry() 仍按旧 stamp 决定要不要
+        # 重建，于是「--check 之后立刻搜索」拿到的注册表与刚重读的配置不是
+        # 一个版本。两者都已在本函数里算出来了，直接回填，不额外扫盘。
+        _remember_ext_scan(scan)
+        if _stamp_ttl() > 0:
+            _stamp_cache = (time.monotonic(), combined_mtime)
+
+    if not force and _config_cache is not None and combined_mtime == _config_mtime:
         return _config_cache
 
+    # 跨进程缓存：force 不读（调用方明确要求重读，不许拿旧结论）。
+    # 整段包 try：缓存是加速器不是依赖，结构被外部改写之类的问题必须退化成
+    # 「走一遍完整解析」，绝不能把异常抛给每个调用方（那种表现是「CLI 每次都崩、
+    # 且看不出跟缓存有关」，用户无从知道要删哪个文件）。
+    if not force:
+        try:
+            # 内容摘要也在缓存判断之前算：它是唯一的强判据（见 _config_content_digest）
+            disk = _load_config_disk_cache(st, scan, _config_content_digest(st))
+            if disk is not None:
+                _config_cache = _validate_engine_paths(disk)
+                _config_mtime = combined_mtime
+                _config_load_error = None
+                return _config_cache
+        except Exception:
+            pass
+
     try:
-        text = CONFIG_PATH.read_text(encoding="utf-8")
-        parsed = _load_yaml(text)
+        # 与 peek_cache_db_path 共享同一次解析（同一份 123 KB 文本此前各解析
+        # 一遍，纯属重复劳动）
+        _ok, parsed, err = _read_config_yaml()
+        if err:
+            _config_load_error = err
         if parsed:
             expanded = _expand_value(parsed)
             resolved = _resolve_relative_paths(expanded)
+            resolved = _merge_external_engines(resolved)
+            # 外置 spec 的 cmd 是相对路径 → 合并后必须再解析一次
+            resolved = _resolve_relative_paths(resolved)
+            _save_config_disk_cache(st, scan, _config_content_digest(st), resolved)
             _config_cache = _validate_engine_paths(resolved)
-            _config_mtime = mtime
-            _config_load_error = None
+            _config_mtime = combined_mtime
+            _config_load_error = err
         elif _config_cache is None:
-            _config_cache = _validate_engine_paths(_resolve_relative_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG)))))
+            base = _validate_engine_paths(_resolve_relative_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG)))))
+            _config_cache = _merge_external_engines(base)
     except ImportError as e:
         _config_load_error = str(e)
         import sys as _sys
         print(f"[unified-search] PyYAML 未安装，使用内置默认配置。安装：pip install pyyaml。原因：{e}", file=_sys.stderr)
         if _config_cache is None:
-            _config_cache = _validate_engine_paths(_resolve_relative_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG)))))
+            base = _validate_engine_paths(_resolve_relative_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG)))))
+            _config_cache = _merge_external_engines(base)
         return _config_cache
     except Exception as e:
         _config_load_error = str(e)
         if _config_cache is None:
-            _config_cache = _validate_engine_paths(_resolve_relative_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG)))))
+            base = _validate_engine_paths(_resolve_relative_paths(_expand_value(json.loads(json.dumps(DEFAULT_CONFIG)))))
+            _config_cache = _merge_external_engines(base)
     return _config_cache
 
 
+def load_config(force: bool = False, *, include_local: bool = True) -> dict[str, Any]:
+    """加载配置；默认并入 config.local.yaml 本机覆盖层（见该文件与 _merge_local_config）。
+
+    include_local=False 用于派生**随公开仓发版**的产物（sync_backends 生成
+    engine_registry.yaml / quota_profiles.json）：本机状态不该进那两份派生件。
+
+    覆盖层在缓存**之后**并入：磁盘/进程缓存存的是公共配置（本机状态不进缓存
+    键），覆盖层每次调用现并——它是小文件、深合并只碰重叠键，代价可忽略。这样
+    「本机状态」与「可缓存的公共配置」两层彻底分开，缓存才能被派生件安全复用。
+    """
+    cfg = _load_config_public(force)
+    return _merge_local_config(cfg) if include_local else cfg
+
+
 def last_load_error() -> str | None:
     return _config_load_error
 
 
 # ── 类型化访问接口 ─────────────────────────────────────────────────────────────
 
-def get_engines(config: dict[str, Any] | None = None) -> dict[str, dict[str, Any]]:
-    """返回启用的引擎配置字典。"""
+# routable_only 过滤结果的进程内记忆化。背景（2026-09-30 route 回归修复）：
+# route_query 每 query 连调 get_engines(routable_only=True) 多次（主路径一次、
+# 语言引擎回退可能再一次），每次对全部引擎逐个跑 env_ready/is_blocked——
+# cProfile 实测 50 query 触发 ~12k 次 env_ready + ~12k 次 is_blocked，占 route
+# 耗时约一半，基准捕获回归 6.5→8.8 ms/query。过滤结果的输入只有四类：
+# config 内容、env 文件（密钥）、进程内 ENABLE/DISABLE 开关、admission 文件。
+# 前三类已有现成签名/时刻可查，admission 读缓存默认 1s TTL——于是把 memo
+# 时窗也定在 1s：进程内其他写路径改 admission（如熔断拉黑）最迟 1s 反映，
+# 与底层读缓存同一口径，不引入新的陈旧度。
+#
+# 失效/关闭语义：
+#   - 键不匹配（config 改写 / env 文件变 / 开关变 / 跨时窗）→ 重算；
+#   - ARGO_ADMISSION_TTL_S=0（admission 缓存关闭）→ memo 一并关闭，
+#     同一旋钮控制同一语义层的两处缓存，无侵入回滚；
+#   - 显式传 config 的调用方不走 memo——那类调用方（契约测试、自定义配置）
+#   - 明确要「这份 config 的精确过滤」，memo 键里没有它的位置。
+# memo 值浅拷贝返回：route 只读，但防御调用方就地改写污染缓存。
+_routable_memo: tuple[tuple, float, dict[str, dict[str, Any]]] | None = None
+
+
+def _routable_memo_key(envfile_sig: tuple, stamp: float) -> tuple:
+    """memo 失效键：config 综合 mtime + env 文件签名 + 进程内引擎开关。"""
+    return (
+        stamp,
+        envfile_sig,
+        os.environ.get("ARGO_ENABLE_ENGINES", ""),
+        os.environ.get("ARGO_DISABLE_ENGINES", ""),
+    )
+
+
+def get_engines(config: dict[str, Any] | None = None,
+                *,
+                routable_only: bool = False) -> dict[str, dict[str, Any]]:
+    """返回启用的引擎配置字典。
+
+    routable_only=True 时额外过滤：
+      - ARGO_ENABLE/DISABLE_ENGINES
+      - 缺 API Key
+      - admission blocked
+
+    不带 config 调用时结果按 1s 时窗记忆化（键含 config_stamp / env 文件
+    签名 / 进程内引擎开关，详见 _routable_memo 注释）；显式传 config 则
+    逐次精确过滤。ARGO_ADMISSION_TTL_S=0 时 memo 一并关闭。
+    """
     cfg = config if config is not None else load_config()
     engines = cfg.get("engines", {})
-    return {name: spec for name, spec in engines.items() if spec.get("enabled", True)}
+    result = {name: spec for name, spec in engines.items() if spec.get("enabled", True)}
+    if not routable_only:
+        return result
+    try:
+        from engine_env import is_engine_allowed_by_env, env_ready, _envfile_sig  # noqa: F401
+        from engine_admission import is_blocked  # noqa: F401
+        ttl = _admission_ttl_mirror()
+    except ImportError as e:
+        # 单机可选依赖（engine_env / engine_admission）缺失时按历史语义返回
+        # 未过滤集，但**必须留痕**：静默返回意味着 blocked 与 env 未就绪的
+        # 引擎重新可路由，是最难查的一类故障。注意这里与上面两处不同——
+        # 上面两处是同一仓内的死回退（已删），这里是真会发生的降级（保留）。
+        # 守卫必须在一切过滤路径（含 _routable_filter）之前：拆函数时把守卫
+        # 留在原调用点，显式 config 路径就会裸抛 ModuleNotFoundError。
+        import logging
+        logging.getLogger("unified_search.config").warning(
+            "routable_only 过滤不可用（%s），本次返回未过滤引擎集", e)
+        return result
+    if config is not None:
+        return _routable_filter(result)
+    global _routable_memo
+    if ttl <= 0:
+        return _routable_filter(result)  # 同一旋钮关 memo：回滚无侵入
+    now = time.monotonic()
+    key = _routable_memo_key(_envfile_sig, config_stamp())
+    if _routable_memo is not None:
+        m_key, m_at, m_val = _routable_memo
+        if m_key == key and now - m_at < 1.0:
+            return dict(m_val)
+    filtered = _routable_filter(result)
+    _routable_memo = (key, now, filtered)
+    return dict(filtered)
+
+
+def _routable_filter(result: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    """逐引擎可路由过滤（env 白黑名单 → 密钥就绪 → 未被准入拉黑 → explicit_only）。
+
+    explicit_only 这道是 2026-10-19 补的契约收口：spec 声明「不进自动路由，
+    只等显式 --engine」，engine_status 的 routable 判定一直排除它，两边注释
+    写的同一口径；但本函数不过滤，route_query 的 enabled 候选池因此躺着全部
+    18 个 explicit_only 引擎，TF-IDF 注入 / catch-all 注入 / backfill /
+    breaker_filter / tfidf_lead_combo / 通用兜底 sorted(enabled)[:2] 都能选中
+    它们。此前没爆只因它们都不在 domain_profiles.json 语料里（数据兜底）——
+    补一条语料词条，auto 档就会把唯一 cost_tier=paid 的 deepseek_search
+    并行调起来扣费。声明是 spec 对路由器的承诺，在候选池的生产者一处兑现，
+    好过在每个消费路径各判一次（漏一条就是一个新泄漏路径）。
+    显式 --engine 路径不经 enabled，不受影响。
+    """
+    from engine_env import is_engine_allowed_by_env, env_ready
+    from engine_admission import is_blocked
+    filtered: dict[str, dict[str, Any]] = {}
+    for name, spec in result.items():
+        if not is_engine_allowed_by_env(name):
+            continue
+        if not env_ready(name, spec):
+            continue
+        if is_blocked(name):
+            continue
+        if spec.get("explicit_only"):
+            continue
+        filtered[name] = spec
+    return filtered
+
+
+def _admission_ttl_mirror() -> float:
+    """读 admission 读缓存 TTL（ARGO_ADMISSION_TTL_S），import 失败回落 1.0。
+
+    config 不 import engine_env 顶层（依赖方向：engine 层引用 config，反过来
+    会在 import 期成环），这里函数内窄 import；拿不到就按默认 1.0 走 memo。
+    """
+    try:
+        from engine_admission import _admission_ttl
+        return _admission_ttl()
+    except Exception:
+        return 1.0
 
 
 def get_domains(config: dict[str, Any] | None = None) -> list[dict[str, Any]]:
@@ -190,6 +696,101 @@ def get_domains(config: dict[str, Any] | None = None) -> list[dict[str, Any]]:
     return cfg.get("domains", [])
 
 
+# 解析结果记忆化：key = config.yaml 的 (mtime_ns, size)。
+# import 期的状态目录派发会连调 4 次（quota / adaptive / argo_engine_registry /
+# cache 各自的模块级常量），此前每次重解析一遍 123 KB 配置——实测 4×~79 ms。
+# 配置被改写（mtime 或 size 变）即失效，语义与逐次读盘一致。
+#
+# 这份解析结果是 peek 与 load_config **共用**的：两处此前各解析一遍同一份
+# 123 KB 文本（C 版 loader 实测约 20 ms/遍），等于每个进程白等一遍。
+_parsed_yaml_cache: tuple[tuple[int, int], dict[str, Any] | None] | None = None
+
+
+def _read_config_yaml() -> tuple[bool, dict[str, Any] | None, str | None]:
+    """读并解析 config.yaml，按 (mtime_ns, size) 记忆化。
+
+    返回 (可记忆, 解析结果, 错误信息)：
+
+    - 可记忆=False 表示读取/解析链不可用（文件缺失、配置损坏），调用方不得
+      写记忆——一次瞬时故障不该固化成本进程的永久 None（原 peek 契约）。
+    - 解析结果按原样缓存，**调用方只读**：load_config 先 _expand_value 出副本
+      再归一化，所以缓存对象不会被就地改写。
+    - PyYAML 缺失仍抛 ImportError，由 load_config 给出安装提示（原先它对
+      ImportError 与 YAMLError 是两种处置）。
+    """
+    global _parsed_yaml_cache
+    try:
+        st = CONFIG_PATH.stat()
+    except OSError as e:
+        return False, None, f"config.yaml 不可读：{e}"
+    key = (st.st_mtime_ns, st.st_size)
+    if _parsed_yaml_cache is not None and _parsed_yaml_cache[0] == key:
+        return True, _parsed_yaml_cache[1], None
+    try:
+        text = CONFIG_PATH.read_text(encoding="utf-8")
+    except OSError as e:
+        return False, None, f"config.yaml 读取失败：{e}"
+    try:
+        parsed = _load_yaml(text)
+    except ImportError:
+        raise
+    except Exception as e:
+        # 含 yaml.YAMLError（ParserError 等）——它不是 ValueError 的子类。
+        # 此前只 catch (ImportError, ValueError) 会让「配置损坏」直接抛出，
+        # 与 fail-open 契约不符（2026-09-15 实测确认）。
+        return False, None, f"config.yaml 解析失败：{type(e).__name__}: {e}"
+    if not isinstance(parsed, dict):
+        parsed = None
+    _parsed_yaml_cache = (key, parsed)
+    return True, parsed, None
+
+
+def peek_cache_db_path() -> str | None:
+    """轻量读取 config.yaml 的 cache.db_path，**不合并外置引擎 spec**。
+
+    专用场景：import 期的路径派生（argo_paths._config_db_path → cache.py 的
+    DEFAULT_DB_PATH）。load_config() 会合并 engines/*.yaml 的全部外置声明，
+    而这里只需要一个标量——为它付整轮合并不值得。
+
+    （勘误 2026-09-15：本文档与 65e6d2e 提交信息曾记「load_config 实测约
+    1.7s」，该数字无法复现。同一台机器实测 load_config() 为纯 Python loader
+    107 ms / C 版 15 ms（含 63 个 yaml、220 个引擎），因此当时的真实成本是
+    「一次合并约 0.1 s，而 import 链上被连调 4 次」而非单次 1.7 s。数字已按
+    可复现计算方式改写。）
+    语义与 get_cache_config() 的 db_path 字段保持一致：用户未配置返回 None
+    （由调用方回退 state_path）。返回值统一是**展开后的形式**（`~` 已展开）：
+    缓存命中与走解析两条分支必须同一计算方式，调用方再 expanduser 一次也无副作用。
+    PyYAML 缺失 / 配置损坏时 fail-open 返回 None，与 _config_db_path 契约一致。
+
+    结果按 config.yaml 的 (mtime_ns, size, ctime_ns) 记忆化：同一进程内多次
+    调用只解析一次（与 load_config 共享同一份解析结果，见 _read_config_yaml）。
+    解析链不可用时（PyYAML 缺失 / 配置损坏）不写记忆，下次调用仍会重试，避免
+    把一次瞬时故障固化成本进程的永久 None。
+
+    写入文件缓存命中时**连 YAML 都不解析**：db_path 只取决于 config.yaml 本身，
+    而缓存键里已经记着这份文件的 stat，与逐次读盘语义一致。缓存未命中或停用
+    （ARGO_CONFIG_CACHE=0）则照旧走解析链。
+    """
+    try:
+        st = CONFIG_PATH.stat()
+    except OSError:
+        return None
+    hit, db_path = _peek_disk_cache_db_path(st, _config_content_digest(st))
+    if hit:
+        return db_path
+    try:
+        ok, parsed, _err = _read_config_yaml()
+    except ImportError:
+        return None
+    if not ok or not isinstance(parsed, dict):
+        return None
+    cache_cfg = parsed.get("cache")
+    if not isinstance(cache_cfg, dict):
+        return None
+    db_path = cache_cfg.get("db_path")
+    return os.path.expanduser(str(db_path)) if db_path else None
+
+
 def get_cache_config(config: dict[str, Any] | None = None) -> dict[str, Any]:
     cfg = config if config is not None else load_config()
     return cfg.get("cache", DEFAULT_CONFIG["cache"])
@@ -206,9 +807,19 @@ def get_output_config(config: dict[str, Any] | None = None) -> dict[str, Any]:
 
 
 def get_cost_tiers(config: dict[str, Any] | None = None) -> dict[str, list[str]]:
-    """返回成本分级配置。"""
+    """返回成本分级：从引擎声明的 cost_tier 字段聚合（唯一来源 config.yaml engines 段）。
+
+    自 v2.6 起 cost_tiers 不再是独立配置段，新增引擎只需在 engines 段声明
+    cost_tier 字段，此处自动归入对应分级。
+    """
     cfg = config if config is not None else load_config()
-    return cfg.get("cost_tiers", {})
+    tiers: dict[str, list[str]] = {}
+    for name, spec in cfg.get("engines", {}).items():
+        if not isinstance(spec, dict):
+            continue
+        tier = spec.get("cost_tier", "free")
+        tiers.setdefault(tier, []).append(name)
+    return tiers
 
 
 def get_budget_config(mode: str = "auto") -> dict[str, Any]:
@@ -218,16 +829,28 @@ def get_budget_config(mode: str = "auto") -> dict[str, Any]:
     return budgets.get(mode, budgets.get("auto", {}))
 
 
-def get_cost_factor(engine: str) -> float:
-    """获取引擎的 cost_factor：free=1.0, low=0.7, paid=0.3。"""
+def cost_tier_of(engine: str) -> str:
+    """引擎的成本档位：free / low / api / paid（未声明按 free 保底）。"""
     tiers = get_cost_tiers()
-    if engine in tiers.get("free", []):
-        return 1.0
-    if engine in tiers.get("low", []):
-        return 0.7
-    if engine in tiers.get("paid", []):
-        return 0.3
-    return 1.0  # 未分级默认为 free
+    for tier in ("free", "low", "api", "paid"):
+        if engine in tiers.get(tier, []):
+            return tier
+    return "free"
+
+
+# 成本因子唯一来源：越低越少被优先选中。
+# 语义打分（tfidf_router）与 n 桶化判定（engines）都从这里取，不再各维护一套表
+# ——此前 config 是 {free 1.0, low 0.7, paid 0.3}、tfidf_router 是
+# {free 1.0, low 0.85, paid 0.6}，同一个概念两个值。
+# api 档（需密钥、按量计费，如 exa/octen/tavily/zhihu_global）保持 1.0：
+# 额度消耗由配额表按 limit/period 跟踪并降权，这里不叠加惩罚；但**它们不参与
+# n 桶化**（见 engines._free_engine）——按量计费的源把 n 从 5 放大到 10 是直接放大账单。
+_COST_FACTOR_BY_TIER = {"free": 1.0, "low": 0.85, "api": 1.0, "paid": 0.6}
+
+
+def get_cost_factor(engine: str) -> float:
+    """获取引擎的 cost_factor（按 cost_tier 查表，见上）。"""
+    return _COST_FACTOR_BY_TIER.get(cost_tier_of(engine), 1.0)
 
 
 # ── CLI 调试用 ─────────────────────────────────────────────────────────────────
@@ -242,21 +865,36 @@ def _cli():
     args = parser.parse_args()
     cfg = load_config(force=True)
     if args.engines:
-        print(json.dumps(get_engines(cfg), ensure_ascii=False, indent=2))
+        print(dumps(get_engines(cfg)))
     elif args.domains:
-        print(json.dumps(get_domains(cfg), ensure_ascii=False, indent=2))
+        print(dumps(get_domains(cfg)))
     elif args.cost_tiers:
-        print(json.dumps(get_cost_tiers(cfg), ensure_ascii=False, indent=2))
+        print(dumps(get_cost_tiers(cfg)))
     elif args.check:
         err = last_load_error()
-        print(json.dumps({
+        print(dumps({
             "path": str(CONFIG_PATH), "ok": err is None, "error": err,
             "engines": list(get_engines(cfg).keys()),
             "domains": [d.get("name") for d in get_domains(cfg)],
-        }, ensure_ascii=False, indent=2))
+        }))
     else:
-        print(json.dumps(cfg, ensure_ascii=False, indent=2))
+        print(dumps(cfg))
 
 
 if __name__ == "__main__":
     _cli()
+
+
+def __getattr__(name: str) -> Any:
+    """惰性属性：`config.shutil` 不再常驻，但保持可被 patch.object 打桩。
+
+    PEP 562：模块 __getattr__ 只在属性缺失时触发。测试的
+    `patch.object(config_mod.shutil, "which", ...)` 解析 config_mod.shutil 时
+    由此导入真实 shutil 模块并返回；patch 落在 shutil 模块对象的 which 属性上，
+    函数级 `import shutil` 的用点（_validate_engine_paths）看到同一模块对象，
+    打桩语义与模块级导入时完全一致。
+    """
+    if name == "shutil":
+        import shutil
+        return shutil
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")