argo-search 1.0.1 → 2.9.7

package/scripts/link_source.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+"""
+link_source.py — 把「消费者入口」指回本仓库来源（符号链接，不复制）。
+
+标准化原则：
+  1. 磁盘上只应有一份 argo 代码：本仓库（scripts/ 的上一级）。
+  2. Skill 目录 / 文档入口若需要出现在主机约定位置，用 **symlink** 指向来源，
+     禁止 rsync/cp 出第二份业务树。
+  3. **链接必须直连来源（1 跳）**。宿主入口挂到另一个入口上（如
+     `~/.workbuddy/skills/argo -> ~/.claude/skills/argo -> 来源`）语义上能解析，
+     但多出一环依赖：中间那环被删改或指偏，入口就成断链，而工具此前对此
+     完全无感。间接链接会被本脚本**重建为直连**（只替换 symlink 本身）。
+  4. **目标路径绝不写死在代码里**。来源优先级：
+       CLI `--to PATH`（可重复）
+       → 环境变量 `ARGO_LINK_TARGETS`（os.pathsep 分隔，如 `:` / `;`）
+       → 来源根目录下的 `installs.local.yaml`（本机声明，应 gitignore）
+  5. 注册表派生仍只走 `sync_backends.py`（config.yaml → backends/*），与链接无关。
+
+用法：
+  # 本机 installs.local.yaml 示例见 installs.local.yaml.example
+  python3 scripts/link_source.py
+  python3 scripts/link_source.py --to /any/consumer/path/argo
+  ARGO_LINK_TARGETS="$HOME/.claude/skills/argo:$HOME/.agents/skills/argo" \\
+    python3 scripts/link_source.py
+  python3 scripts/link_source.py --check        # 只校验；间接链接记 warn 并非零退出
+  python3 scripts/link_source.py --dry-run
+
+退出码：0 成功；1 无目标 / 链接失败 / 校验不一致（含「只经多跳间接指向来源」）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SOURCE = Path(__file__).resolve().parent.parent
+LOCAL_INSTALLS = SOURCE / "installs.local.yaml"
+
+
+def _load_local_targets() -> list[Path]:
+    if not LOCAL_INSTALLS.exists():
+        return []
+    try:
+        from yaml_load import load as _yaml_load
+    except ImportError:
+        print("[warn] 需要 PyYAML 才能读 installs.local.yaml", file=sys.stderr)
+        return []
+    data = _yaml_load(LOCAL_INSTALLS) or {}
+    raw = data.get("link_targets") or data.get("targets") or []
+    if not isinstance(raw, list):
+        return []
+    out: list[Path] = []
+    for item in raw:
+        if not item:
+            continue
+        p = Path(str(item)).expanduser()
+        # 相对路径相对来源根；规范化但不跟随符号链接（见 _normalize_target）
+        out.append(_normalize_target(SOURCE / p if not p.is_absolute() else p))
+    return out
+
+
+def _normalize_target(p: Path) -> Path:
+    """规范化目标路径：展开 ~、补成绝对路径、消掉 . 与 ..，**但不跟随符号链接**。
+
+    为什么不用 resolve()：宿主入口本来就应该是一条 symlink。resolve() 会先把
+    「已经指向来源的链接」折叠成来源路径，于是 link_one 看到的目标是「来源本体」
+    而直接跳过重建，check_targets 也无法区分「直连」与「隔了一层的间接链接」——
+    校验常年报 ok，实际入口却挂在中转链接上（2026-09-14 实测踩到）。
+    """
+    p = Path(p).expanduser()
+    if not p.is_absolute():
+        p = Path.cwd() / p
+    return Path(os.path.normpath(str(p)))
+
+
+def _hops_to_source(target: Path) -> int:
+    """目标到来源的符号链接跳数。
+
+    0 = 目标就是来源本体；1 = 直连；>1 = 间接链接（可解析但多一跳依赖）；
+    -1 = 未指向来源 / 断链 / 成环（超过 8 跳按未指向处理，避免死循环）。
+    """
+    src = SOURCE.resolve()
+    cur = target
+    for hops in range(8):
+        try:
+            resolved = cur.resolve()
+        except (OSError, RuntimeError):
+            # 断链 / 符号链接成环（py3.13 的 resolve() 对环抛 RuntimeError）
+            return -1
+        if resolved != src:
+            return -1
+        if not cur.is_symlink():
+            return hops
+        try:
+            raw = os.readlink(cur)
+        except OSError:
+            return -1
+        nxt = Path(raw)
+        if not nxt.is_absolute():
+            nxt = cur.parent / nxt
+        cur = Path(os.path.normpath(str(nxt)))
+    return -1
+
+
+def _env_targets() -> list[Path]:
+    raw = os.environ.get("ARGO_LINK_TARGETS", "").strip()
+    if not raw:
+        return []
+    return [_normalize_target(p) for p in raw.split(os.pathsep) if p.strip()]
+
+
+def resolve_targets(cli: list[Path] | None) -> list[Path]:
+    """无默认路径：没有 CLI / env / local 文件则空列表。"""
+    seen: set[str] = set()
+    ordered: list[Path] = []
+    for group in (cli or [], _env_targets(), _load_local_targets()):
+        for p in group:
+            key = _normalize_target(p)
+            if str(key) in seen:
+                continue
+            seen.add(str(key))
+            ordered.append(key)
+    return ordered
+
+
+# 判定「目录像 argo 来源/旧副本」的特征文件。用于 --force 迁走目录前的软校验，
+# 防止用户把 --to 错指到任意数据目录，--force 下整目录被 rename 迁走的误伤。
+_ARGO_MARKERS = ("scripts/search.py", "SKILL.md")
+
+
+def _looks_like_argo_copy(path: Path) -> bool:
+    """路径是否为 argo 来源/旧副本（含脚本与 SKILL 文档），而非任意数据目录。"""
+    if not path.is_dir():
+        return False
+    return any((path / marker).exists() for marker in _ARGO_MARKERS)
+
+
+def link_one(target: Path, *, dry_run: bool, force: bool) -> int:
+    """将 target 设为指向 SOURCE 的 symlink（间接链接会被重建为直连）。"""
+    source = SOURCE.resolve()
+    depth = _hops_to_source(target)
+
+    if depth == 0:
+        print(f"[skip] 目标就是真源本体: {target}")
+        return 0
+
+    if depth == 1:
+        print(f"[ok]   已指向真源: {target} -> {source}")
+        return 0
+
+    if depth > 1:
+        # 间接链接：能解析到来源，但中间还挂了一环。重建为直连只替换符号链接
+        # 本身（不触碰任何目录内容），因此无需 --force。
+        if dry_run:
+            print(f"[dry]  将把 {depth} 跳间接链接重建为直连: {target}")
+            return 0
+        # 先建同目录临时链接再原子替换：避免「已 unlink、symlink 又失败」的
+        # 窗口里宿主入口凭空消失（入口消失会让 Skill/工具调用直接找不到 argo）。
+        tmp = target.with_name(target.name + ".relink-tmp")
+        try:
+            if tmp.is_symlink() or tmp.exists():
+                tmp.unlink()
+            os.symlink(source, tmp, target_is_directory=True)
+            os.replace(tmp, target)
+        except OSError as e:
+            try:
+                if tmp.is_symlink() or tmp.exists():
+                    tmp.unlink()
+            except OSError:
+                pass
+            print(f"[fail] 重建直连失败: {target} ({e})", file=sys.stderr)
+            return 1
+        print(f"[relink] {target} -> {source}（原为 {depth} 跳间接链接，已重建为直连）")
+        return 0
+
+    if target.exists() or target.is_symlink():
+        if not force:
+            print(
+                f"[fail] 目标已存在且不是指向真源的链接: {target}\n"
+                f"       若确认可替换，加 --force（会先移走/删除该路径）",
+                file=sys.stderr,
+            )
+            return 1
+        # 软校验（dry-run 与实际执行都触发）：目录若不像 argo 来源/旧副本
+        # （无 scripts/search.py 或 SKILL.md），拒绝 --force 迁走，防止 --to
+        # 误指用户数据目录被整目录 rename 的误伤。
+        if target.is_dir() and not _looks_like_argo_copy(target):
+            print(
+                f"[fail] 目录不像 argo 真源/旧副本，拒绝 --force 迁走: {target}\n"
+                f"       若确要替换，先手动备份该目录，或删掉后再执行。",
+                file=sys.stderr,
+            )
+            return 1
+        if dry_run:
+            print(f"[dry]  将替换已有路径: {target}")
+        else:
+            if target.is_symlink() or target.is_file():
+                target.unlink()
+            elif target.is_dir():
+                # 旧多副本：整目录移走备份，避免误删用户未入库文件
+                bak = target.with_name(target.name + ".bak-before-link")
+                if bak.exists():
+                    shutil.rmtree(bak) if bak.is_dir() and not bak.is_symlink() else bak.unlink(missing_ok=True)
+                target.rename(bak)
+                print(f"[bak]  旧副本已移至 {bak}")
+            else:
+                target.unlink(missing_ok=True)
+
+    parent = target.parent
+    if dry_run:
+        print(f"[dry]  ln -sfn {source} {target}")
+        return 0
+    parent.mkdir(parents=True, exist_ok=True)
+    # atomic-ish: symlink in place
+    try:
+        os.symlink(source, target, target_is_directory=True)
+    except OSError:
+        # Windows 无开发者模式/管理员权限时 symlink 会失败：
+        # 目录链接退化为 junction（mklink /J，不需要管理员权限），
+        # 语义与 symlink 基本一致（resolve() 同样指向来源）。
+        if os.name == "nt":
+            r = subprocess.run(
+                ["cmd", "/c", "mklink", "/J", str(target), str(source)],
+                capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=30,
+            )
+            # junction 不是 symlink（is_symlink() 为 False，_hops_to_source 会
+            # 把它当普通目录），此处按「解析后是否等于来源」独立判定。
+            try:
+                linked = target.resolve() == SOURCE.resolve()
+            except OSError:
+                linked = False
+            if r.returncode == 0 and linked:
+                print(f"[link] {target} -> {source} (junction)")
+                return 0
+        print(f"[fail] 创建链接失败: {target} -> {source}", file=sys.stderr)
+        return 1
+    print(f"[link] {target} -> {source}")
+    return 0
+
+
+def check_targets(targets: list[Path]) -> int:
+    bad = 0
+    print(f"真源: {SOURCE.resolve()}")
+    if not targets:
+        print("[fail] 无校验目标（请 --to / ARGO_LINK_TARGETS / installs.local.yaml）")
+        return 1
+    for t in targets:
+        depth = _hops_to_source(t)
+        if depth == 0:
+            print(f"[ok]   {t} 即真源本体")
+        elif depth == 1:
+            print(f"[ok]   {t} -> {SOURCE.resolve()}")
+        elif depth > 1:
+            # 间接链接仍能解析到来源，但多了一环依赖——按「校验不一致」计失败，
+            # 提示直接重跑（不带 --check）即可重建为直连。
+            print(f"[warn] {t} 经 {depth} 跳间接指向真源（非直连）；"
+                  f"去掉 --check 重跑即可重建为直连")
+            bad += 1
+        else:
+            print(f"[miss] {t} 未指向真源（exists={t.exists()} symlink={t.is_symlink()}）")
+            bad += 1
+    return 1 if bad else 0
+
+
+def maybe_sync_backends() -> int:
+    script = SOURCE / "scripts" / "sync_backends.py"
+    if not script.exists():
+        return 0
+    # timeout（2026-09-29 补）：sync_backends 是纯本地文件操作，正常秒回；
+    # 但无 timeout 的 subprocess 一旦被挂住（NFS/锁/杀软扫描），本命令会
+    # 无限期卡死。60s 对本地脚本是极宽裕的上界。
+    r = subprocess.run([sys.executable, str(script)], cwd=str(SOURCE), timeout=60)
+    if r.returncode != 0:
+        return r.returncode
+    return subprocess.run(
+        [sys.executable, str(script), "--check"], cwd=str(SOURCE),
+        timeout=60).returncode
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        description="将消费者入口 symlink 到 argo 真源（无内置默认路径）",
+    )
+    p.add_argument(
+        "--to",
+        action="append",
+        type=Path,
+        default=None,
+        help="链接目标路径（可重复）。无内置默认值。",
+    )
+    p.add_argument("--check", action="store_true", help="只校验目标是否指向真源")
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="目标已存在时替换：symlink/file 删除；目录改名为 *.bak-before-link",
+    )
+    p.add_argument(
+        "--with-backends",
+        action="store_true",
+        help="链接前先跑 sync_backends.py 派生 backends",
+    )
+    args = p.parse_args(argv)
+
+    targets = resolve_targets(args.to)
+    if not targets:
+        print(
+            "未指定任何链接目标。\n"
+            "  方式 1: python3 scripts/link_source.py --to <path> [--to <path2>]\n"
+            "  方式 2: export ARGO_LINK_TARGETS='path1:path2'\n"
+            f"  方式 3: 在真源写 {LOCAL_INSTALLS.name}（见 installs.local.yaml.example）\n"
+            "代码内不固化任何主机 skill/MCP 路径。",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.check:
+        return check_targets(targets)
+
+    if args.with_backends:
+        print(f"== sync_backends @ {SOURCE} ==")
+        rc = maybe_sync_backends()
+        if rc != 0:
+            return rc
+
+    code = 0
+    for t in targets:
+        code = link_one(t, dry_run=args.dry_run, force=args.force) or code
+    if args.dry_run:
+        return code
+    return check_targets(targets) if code == 0 else code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/local_engines.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""本地个性化引擎插件 — 不随公开仓库提交。
+
+包含漏洞查询类引擎（OSV.dev + CISA KEV），因启发式杀毒检测
+（HEUR:HackTool/VulnScan）从公开构建器中移出。
+本地文件，不提交 git；删除后对应引擎自动消失，不影响其他功能。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+import urllib.request
+from typing import Any
+
+from engines_base import safe_search, rank_score, http_open, note_failure
+
+
+# ── OSV.dev 开源漏洞库（免 key，必须 POST）─────────────────────────────────
+
+_OSV_ECOSYSTEM_PREFIX: dict[str, str] = {
+    "pypi": "PyPI", "npm": "npm", "go": "Go", "crates": "crates.io",
+    "cargo": "crates.io", "maven": "Maven", "nuget": "NuGet",
+    "packagist": "Packagist", "composer": "Packagist",
+    "rubygems": "RubyGems", "gem": "RubyGems", "hex": "Hex",
+}
+
+_OSV_NPM_HINTS: frozenset[str] = frozenset({
+    "lodash", "react", "vue", "express", "axios", "next", "webpack",
+    "typescript", "eslint", "vite", "jest", "moment", "jquery", "angular",
+    "svelte", "nuxt", "rollup", "babel", "prettier", "cheerio", "socket.io",
+})
+
+_OSV_GO_HINTS: frozenset[str] = frozenset({
+    "golang.org/x/net", "golang.org/x/crypto", "golang.org/x/text",
+    "github.com/gin-gonic/gin", "github.com/gorilla/websocket",
+})
+
+
+def _osv_resolve_ecosystem(query: str) -> tuple[str, str]:
+    q = (query or "").strip()
+    if ":" in q:
+        head, _, tail = q.partition(":")
+        eco = _OSV_ECOSYSTEM_PREFIX.get(head.strip().lower())
+        if eco and tail.strip():
+            return tail.strip(), eco
+    name = q
+    if name.startswith("@") or "/" in name:
+        if name.startswith("@"):
+            return name, "npm"
+        if name.startswith(("github.com/", "gitlab.com/", "golang.org/")):
+            return name, "Go"
+        return name, "npm"
+    if name.lower() in _OSV_NPM_HINTS:
+        return name, "npm"
+    if name.lower() in _OSV_GO_HINTS:
+        return name, "Go"
+    return name, "PyPI"
+
+
+def _build_osv_engine(spec: dict[str, Any]) -> Any:
+    """OSV.dev 漏洞查询（按包名，POST /v1/query；免 key、免限次）。"""
+    timeout = spec.get("timeout", 15)
+
+    @safe_search
+    def _engine(query: str, n: int = 5, _timeout: float | None = None,
+                **kwargs) -> list[dict[str, Any]]:
+        to = _timeout or timeout
+        q = (query or "").strip()
+        if not q:
+            return []
+        if re.match(r"^CVE-\d{4}-\d{4,}$", q, re.I):
+            return []
+        pkg, eco = _osv_resolve_ecosystem(q)
+        body = json.dumps({"package": {"name": pkg, "ecosystem": eco}}).encode("utf-8")
+        req = urllib.request.Request(
+            "https://api.osv.dev/v1/query", data=body,
+            headers={"Content-Type": "application/json"})
+        eng_name = spec.get("_name") or "osv"
+        try:
+            with http_open(req, timeout=to, engine=eng_name) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except Exception as e:
+            if isinstance(e, (json.JSONDecodeError, UnicodeDecodeError)):
+                note_failure(eng_name, "parse", "json_decode", str(e))
+            import logging
+            logging.getLogger("unified_search.engines").warning(f"OSV 失败: {e}")
+            return []
+        results = []
+        for i, v in enumerate((data.get("vulns") or [])[:n]):
+            vid = str(v.get("id") or "").strip()
+            if not vid:
+                continue
+            summary = str(v.get("summary") or "").strip()
+            affected_bits = []
+            for aff in (v.get("affected") or [])[:2]:
+                if not isinstance(aff, dict):
+                    continue
+                for rng in (aff.get("ranges") or [])[:2]:
+                    if not isinstance(rng, dict):
+                        continue
+                    events = rng.get("events") or []
+                    introduced = next((e.get("introduced") for e in events
+                                       if isinstance(e, dict) and e.get("introduced")), "")
+                    fixed = next((e.get("fixed") for e in events
+                                  if isinstance(e, dict) and e.get("fixed")), "")
+                    if introduced or fixed:
+                        affected_bits.append(
+                            f"{introduced or '?'} ≤ 受影响 < {fixed or '未修复'}")
+            aliases = [a for a in (v.get("aliases") or []) if a][:3]
+            snippet = " · ".join(p for p in (
+                summary, f"生态 {eco}",
+                affected_bits[0] if affected_bits else "",
+                " ".join(aliases),
+            ) if p)[:300]
+            results.append({
+                "title": f"{vid} [{eco}] {summary}"[:500] or vid,
+                "url": f"https://osv.dev/vulnerability/{vid}",
+                "snippet": snippet,
+                "source": "osv",
+                "published_at": str(v.get("published") or "")[:10],
+                "score": rank_score(0.85, i),
+            })
+        return results
+    return _engine
+
+
+# ── CISA KEV 已知在野利用漏洞（免 key，全量文件 + 本地过滤）──────────────
+
+_KEV_CACHE: dict[str, Any] = {"at": 0.0, "items": None}
+_KEV_TTL_S = 6 * 3600
+
+
+def _kev_disk_path():
+    try:
+        from argo_paths import state_path
+        return state_path("cisa_kev_cache.json")
+    except Exception:
+        return None
+
+
+def _kev_load(timeout: float) -> list[dict[str, Any]]:
+    now = time.time()
+    cached = _KEV_CACHE.get("items")
+    if cached and (now - float(_KEV_CACHE.get("at") or 0)) < _KEV_TTL_S:
+        return cached
+    disk_p = _kev_disk_path()
+    if disk_p is not None and disk_p.exists():
+        try:
+            st = disk_p.stat()
+            if (now - st.st_mtime) < _KEV_TTL_S:
+                disk_items = json.loads(disk_p.read_text(encoding="utf-8"))
+                if isinstance(disk_items, list) and disk_items:
+                    _KEV_CACHE["items"] = disk_items
+                    _KEV_CACHE["at"] = st.st_mtime
+                    return disk_items
+        except Exception:
+            pass
+    req = urllib.request.Request(
+        "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json",
+        headers={"User-Agent": "argo-search/1.0 (+cisa-kev)", "Accept": "application/json"})
+    try:
+        with http_open(req, timeout=timeout, engine="cisa_kev") as resp:
+            data = json.loads(resp.read().decode("utf-8", "replace"))
+    except Exception as e:
+        if isinstance(e, (json.JSONDecodeError, UnicodeDecodeError)):
+            note_failure("cisa_kev", "parse", "json_decode", str(e))
+        import logging
+        logging.getLogger("unified_search.engines").warning(f"CISA KEV 失败: {e}")
+        return cached or []
+    items = data.get("vulnerabilities") or []
+    if not isinstance(items, list):
+        return cached or []
+    _KEV_CACHE["items"] = items
+    _KEV_CACHE["at"] = now
+    if disk_p is not None and items:
+        try:
+            from argo_paths import atomic_write_json
+            atomic_write_json(disk_p, items)
+        except Exception:
+            pass
+    return items
+
+
+def _build_cisa_kev_engine(spec: dict[str, Any]) -> Any:
+    """CISA KEV 在野利用漏洞目录（本地过滤全量目录）。"""
+    timeout = spec.get("timeout", 30)
+
+    @safe_search
+    def _engine(query: str, n: int = 5, _timeout: float | None = None,
+                **kwargs) -> list[dict[str, Any]]:
+        to = _timeout or timeout
+        q = (query or "").strip()
+        if not q:
+            return []
+        items = _kev_load(to)
+        if not items:
+            return []
+        cve_q = q.upper() if re.match(r"^CVE-\d{4}-\d{4,}$", q.strip(), re.I) else ""
+        matched = []
+        for v in items:
+            if not isinstance(v, dict):
+                continue
+            if cve_q:
+                if str(v.get("cveID") or "").strip().upper() == cve_q:
+                    matched.append(v)
+                continue
+            terms = [t for t in re.split(r"[\s,]+", q.lower()) if t]
+            hay = " ".join(str(v.get(k) or "") for k in (
+                "cveID", "vendorProject", "product", "vulnerabilityName",
+                "shortDescription", "requiredAction", "cwes")).lower()
+            if all(t in hay for t in terms):
+                matched.append(v)
+        matched.sort(key=lambda x: str(x.get("dateAdded") or ""), reverse=True)
+        results = []
+        for i, v in enumerate(matched[:n]):
+            cve = str(v.get("cveID") or "").strip()
+            if not cve:
+                continue
+            vendor = str(v.get("vendorProject") or "").strip()
+            product = str(v.get("product") or "").strip()
+            name = str(v.get("vulnerabilityName") or "").strip()
+            desc = str(v.get("shortDescription") or "").strip()
+            due = str(v.get("dueDate") or "").strip()
+            ransom = str(v.get("knownRansomwareCampaignUse") or "").strip()
+            bits = [b for b in (
+                f"{vendor} {product}".strip(),
+                f"修复期限 {due}" if due else "",
+                "已知勒索软件利用" if ransom.lower() == "known" else "",
+                desc,
+            ) if b]
+            results.append({
+                "title": f"{cve} — {name or product or vendor}"[:500],
+                "url": "https://www.cisa.gov/known-exploited-vulnerabilities-catalog",
+                "snippet": " · ".join(bits)[:300],
+                "source": "cisa_kev",
+                "published_at": str(v.get("dateAdded") or "")[:10],
+                "score": rank_score(0.9, i),
+            })
+        return results
+    return _engine
+
+
+# ── 引擎声明（本地个性化配置，不提交公开仓库）────────────────────────────────
+#
+# 字段与原 engines/specs/osv.yaml、engines/specs/cisa_kev.yaml 逐项对齐——
+# 那两个声明已加 _ 前缀改名停用（公开仓每次启动刷两行「未知引擎类型」warning），
+# 元数据随之并入本文件，本机路由行为（explicit_only / family / priority / qps
+# 等）与改名前完全一致。
+
+_LOCAL_ENGINE_SPECS: dict[str, dict[str, Any]] = {
+    "osv": {
+        "type": "osv",
+        "enabled": True,
+        "explicit_only": True,
+        "cost_tier": "free",
+        "label": "OSV 开源漏洞库",
+        "family": "security",
+        "priority": 44,
+        "qps": 2,
+        "period": "second",
+        "cost_per_call": 0.0,
+        "cost_unit": "free",
+        "method": "POST",
+        "url": "https://api.osv.dev/v1/query",
+        "timeout": 15,
+        "canary_query": "requests",
+        "desc": "OSV.dev 开源软件漏洞库（按包查已知漏洞与影响版本区间，免 key；生态 PyPI/npm/Go/crates 等）",
+        "description": "OSV.dev 开源漏洞查询（按包名）",
+        "coverage": ["security", "package"],
+        "recommended": False,
+        "latency_ms": 1500,
+        "headers": {"Content-Type": "application/json"},
+        "quality_queries": [
+            {"query": "requests"},
+            {"query": "lodash"},
+            {"query": "log4j-core"},
+        ],
+    },
+    "cisa_kev": {
+        "type": "cisa_kev",
+        "enabled": True,
+        "explicit_only": True,
+        "cost_tier": "free",
+        "label": "CISA KEV 在野利用漏洞",
+        "family": "security",
+        "priority": 47,
+        "qps": 1,
+        "period": "second",
+        "cost_per_call": 0.0,
+        "cost_unit": "free",
+        "timeout": 30,
+        "canary_query": "chrome",
+        "desc": "CISA 已知被在野利用漏洞目录（官方确认已被实际攻击利用的 CVE；全量 1.35MB 本地过滤）",
+        "description": "CISA KEV 在野利用漏洞目录",
+        "coverage": ["security"],
+        "recommended": False,
+        "latency_ms": 4000,
+        "quality_queries": [
+            {"query": "chrome"},
+            {"query": "CVE-2021-44228"},
+        ],
+    },
+}
+
+
+def register(builders: dict[str, Any], engine_specs: dict[str, Any]) -> None:
+    """将本地引擎注册到全局 builders 和 engine_specs 中。
+
+    在 engines.py 的 _load_registry() 中、构建 registry 之前调用。
+    文件不存在时 engines.py 跳过 import，不影响公开仓库。
+    外置 spec（engines/specs/*.yaml）已有的字段保留，不抹除 explicit_only/family 等元数据。
+    """
+    builders["osv"] = _build_osv_engine
+    builders["cisa_kev"] = _build_cisa_kev_engine
+    for name, spec in _LOCAL_ENGINE_SPECS.items():
+        base = dict(engine_specs.get(name) or {})
+        for k, v in spec.items():
+            base.setdefault(k, v)
+        engine_specs[name] = base