argo-search 1.0.1 → 2.9.8

package/scripts/digup_bridge.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""digup_bridge.py — DigUp 本地语义搜索的 CLI 桥（声明式引擎用，无网络）。
+
+DigUp（github.com/ARahim3/DigUp）在设备端用 EmbeddingGemma 2 给本地文件建
+多模态向量索引（照片/截图/PDF/文档/音频/视频，命中精确到页/秒/行）。它的
+`search --json` 输出的是 path/kind/score/excerpt 行，不是 argo 契约的
+title/url——本桥做一次纯本地映射，让 engines/specs/digup.yaml 走通用 cli
+builder，不新增 Python 特例分支（与 train/realtime_index 同形态）。
+
+用法（spec 调用形如）：
+  python3 scripts/digup_bridge.py "<query>" -n 5
+
+digup 二进制定位（先到先得）：
+  --bin 参数 > $DIGUP_BIN > PATH 里的 digup
+  > /Applications/DigUp.app/Contents/Helpers/digup（brew cask / DMG 装的 App）
+
+索引定位：--index 参数 > $DIGUP_INDEX > digup 默认
+（~/Library/Application Support/DigUp/index.noindex）。
+
+输出：单个 JSON {"results": [...]}（argo cli builder 的自动 JSON 路径）。
+任何失败都输出空 results 并 exit 0——引擎层语义：本源此刻无结果，而不是
+整次检索报错。诊断信息走 stderr。
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+# digup 自身首查要加载 ~250MB text-only 模型（冷启实测 0.4–0.8s），再留检索
+# 与进程开销。引擎层 spec timeout=30 兜底，这里取小于它的值，保证被卡时
+# 桥先返回结构化空结果而不是被引擎层整体杀掉。
+_DIGUP_TIMEOUT_S = 25
+
+_APP_HELPERS = (
+    "/Applications/DigUp.app/Contents/Helpers/digup",
+    os.path.expanduser("~/Applications/DigUp.app/Contents/Helpers/digup"),
+)
+
+_KIND_ZH = {
+    "screenshot": "截图",
+    "image": "图片",
+    "pdf": "PDF",
+    "doc": "文档",
+    "audio": "音频",
+    "video": "视频",
+    "code": "代码",
+}
+
+
+def resolve_bin(explicit: str | None = None) -> str:
+    """定位 digup 可执行文件（显式 > $DIGUP_BIN > PATH > App Helpers）；找不到返回空串。"""
+    candidates = []
+    if explicit:
+        candidates.append(explicit)
+    env_bin = os.environ.get("DIGUP_BIN", "").strip()
+    if env_bin:
+        candidates.append(env_bin)
+    for path in candidates:
+        if path and os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    found = shutil.which("digup")
+    if found:
+        return found
+    for path in _APP_HELPERS:
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    return ""
+
+
+def _clock(seconds: float) -> str:
+    total = int(seconds)
+    return f"{total // 60}:{total % 60:02d}"
+
+
+def _loc_hint(row: dict) -> str:
+    """digup 的命中位置（页/秒/段/行）转中文后缀；无定位返回空。"""
+    segment = row.get("segment") or ""
+    loc = row.get("loc")
+    if loc is None:
+        return " · 图内文字" if segment == "ocr" else ""
+    if segment in ("page", "pageImage"):
+        return f" · 第{int(loc)}页"
+    if segment == "audio":
+        return f" · {_clock(loc)}（声音）"
+    if segment == "frame":
+        return f" · {_clock(loc)}"
+    if segment == "chunk":
+        return f" · 第{int(loc)}段"
+    if segment == "lines":
+        end = row.get("loc_end")
+        return f" · 第{int(loc)}–{int(end)}行" if end else f" · 第{int(loc)}行"
+    if segment == "cells":
+        end = row.get("loc_end")
+        return f" · 单元格{int(loc)}–{int(end)}" if end else f" · 单元格{int(loc)}"
+    return ""
+
+
+def _url(row: dict) -> str:
+    """file:// 链接；PDF 带 #page=N、音视频带 #t=start,end（Preview/QuickTime
+    认这两个 fragment，也让同文件不同页/时刻的命中不被 argo 按 url 去重合并）。"""
+    path = row.get("path") or ""
+    if not path:
+        return ""
+    url = "file://" + path
+    segment = row.get("segment") or ""
+    loc = row.get("loc")
+    if loc is None:
+        return url
+    if segment in ("page", "pageImage"):
+        return f"{url}#page={int(loc)}"
+    if segment in ("audio", "frame"):
+        end = row.get("loc_end")
+        return f"{url}#t={int(loc)},{int(end if end is not None else loc)}"
+    return url
+
+
+def _snippet(row: dict) -> str:
+    """excerpt 优先（剥掉 digup 的高亮记号 «»）；无 excerpt（图像/纯名命中）
+    给「类型 · 位置描述」或所在目录，保证 snippet 永远不为空。"""
+    excerpt = str(row.get("excerpt") or "").replace("«", "").replace("»", "")
+    excerpt = " ".join(excerpt.split())
+    if excerpt:
+        return excerpt[:300]
+    kind = _KIND_ZH.get(row.get("kind") or "", "文件")
+    hint = _loc_hint(row)
+    if hint:
+        return f"{kind}{hint.lstrip(' ·')} · 内容语义匹配"
+    folder = os.path.dirname(row.get("path") or "")
+    home = os.path.expanduser("~")
+    if folder.startswith(home):
+        folder = "~" + folder[len(home):]
+    return f"{kind} · 关键词命中 · {folder or '本地文件'}"[:300]
+
+
+def map_row(row: dict, rank: int) -> dict:
+    """digup 结果行 → argo 结果契约（title/url/snippet/source 必需）。"""
+    path = row.get("path") or ""
+    title = (os.path.basename(path) if path else "") + _loc_hint(row)
+    result = {
+        "title": title[:200],
+        "url": _url(row),
+        "snippet": _snippet(row),
+        "source": "digup",
+        # 与其他 cli builder 一致的展示分（rrf_merge 按名次融合，score 只作展示）
+        "score": round(max(1.0 - 0.1 * rank, 0.1), 4),
+    }
+    # digup --json 不带 modified（SearchHit 序列化面没有它），桥自己 stat：
+    # 文件被移动/删除时拿不到就算了，不硬造日期。
+    if path:
+        try:
+            mtime = os.stat(path).st_mtime
+            result["published_at"] = datetime.datetime.fromtimestamp(mtime).strftime("%Y-%m-%d")
+        except OSError:
+            pass
+    return result
+
+
+def search(query: str, n: int, bin_path: str, index_dir: str | None) -> list[dict]:
+    cmd = [bin_path, "search", query, "--json", "-n", str(n)]
+    if index_dir:
+        cmd += ["--index", index_dir]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True,
+                              encoding="utf-8", errors="replace",
+                              timeout=_DIGUP_TIMEOUT_S)
+    except subprocess.TimeoutExpired:
+        print(f"digup_bridge: digup 超时(>{_DIGUP_TIMEOUT_S}s)", file=sys.stderr)
+        return []
+    except OSError as e:
+        print(f"digup_bridge: 无法执行 digup: {e}", file=sys.stderr)
+        return []
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[-200:]
+        print(f"digup_bridge: digup rc={proc.returncode}: {tail}", file=sys.stderr)
+        return []
+    try:
+        rows = json.loads(proc.stdout)
+    except (json.JSONDecodeError, ValueError):
+        print("digup_bridge: digup 输出不是 JSON", file=sys.stderr)
+        return []
+    if not isinstance(rows, list):
+        print("digup_bridge: digup 输出不是结果数组", file=sys.stderr)
+        return []
+    return [map_row(r, i) for i, r in enumerate(rows) if isinstance(r, dict)]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="DigUp → argo 结果契约（本地映射，无网络）")
+    parser.add_argument("query", help="搜索词（自然语言描述文件内容）")
+    parser.add_argument("-n", type=int, default=5, help="返回条数")
+    parser.add_argument("--bin", default=None, help="digup 可执行文件路径（默认自动定位）")
+    parser.add_argument("--index", default=None, help="索引目录（默认 digup 自身默认值）")
+    args = parser.parse_args(argv)
+
+    bin_path = resolve_bin(args.bin)
+    if not bin_path:
+        print("digup_bridge: 找不到 digup 可执行文件（装 App、放进 PATH，"
+              "或设 DIGUP_BIN / --bin），返回空结果", file=sys.stderr)
+        print(json.dumps({"results": []}))
+        return 0
+    index_dir = args.index or os.environ.get("DIGUP_INDEX", "").strip() or None
+    print(json.dumps({"results": search(args.query, max(1, args.n), bin_path, index_dir)},
+                     ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/dispatch_result.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""dispatch_result.py — 引擎编排的产出对象与墙钟记账（2026-10-21 从 engine_dispatch 拆出）。
+
+拆出原因：module size 门禁要求 engine_dispatch 只能减不能增，而 2026-10-21 的
+尾等待记账需要同时扩数据类与汇总逻辑。两者都是**纯数据**（无 IO、无调度依赖），
+放在调度器里只会让「调度策略」和「记账口径」继续互相遮挡。
+
+记账口径（为什么不是一个数）：
+  - `useful_ms`：最后一个**贡献结果**的引擎完成时刻（答案从这一刻起已在手里）。
+  - `first_sufficient_ms`：早停判据首次成立（结果够用）的时刻；no_early 域没有
+    这个时刻，保持 0。
+  - `tail_wait_ms`：结果已可交付后仍在等的时间。有早停时刻用它算，没有就用
+    「首条结果时刻」算——后者正是 no_early 域白等的来源。
+  - `abandoned_engine_ms`：被早停弃置的引擎已花的墙钟**之和**。它是并行资源
+    浪费，不等于用户多等的时间（两个引擎并行跑到最后，赢家交结果、输家被弃置，
+    用户没有任何额外等待）。`wasted_ms` 保留为它的别名，兼容旧读法。
+
+历史教训：旧 `wasted_ms` 口径换过三次，前两版分别是「非 ok 引擎 latency 之和」
+（并行时必然大于墙钟）与 `wall - useful`（有界并发下恒为 0）。两版都让仪表看
+起来正常、却无法指向任何动作。这次拆成两个互不重叠的量，各自对应一个旋钮：
+tail 指向收工时机，abandoned 指向并发/对冲预算。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["DispatchResult", "summarize_dispatch"]
+
+
+class DispatchResult:
+    """编排产出 + 两个钩子（融合后仍要补搜的路径用）。
+
+    `run_one` / `ingest` 必须外露：macro_data 域的 D6 证据下限补搜在融合之后，
+    它要跑单个引擎并把结果并进同一份账（raw_results / engine_outcomes /
+    engine_latency / abandoned 计数），另起一份会让 engines_used 与配额记账对不上。
+
+    `budget_used_ms` / `budget_total_ms`：本次编排的实际墙钟消耗与总预算
+    （deep 等无预算模式 total 为 None）。搜索输出把它挂进 timing.budget，
+    让「这次离预算上限还有多远」可观测，而不必反推 process_ms。
+
+    记账字段的语义与历史见模块 docstring；`wasted_ms` 仅为兼容别名。
+    """
+
+    __slots__ = ("raw_results", "engine_outcomes", "engine_latency",
+                 "wasted_ms", "early_stopped", "run_one", "ingest",
+                 "budget_used_ms", "budget_total_ms", "useful_ms",
+                 "first_sufficient_ms", "tail_wait_ms", "abandoned_engine_ms")
+
+    def __init__(self, raw_results: Any, engine_outcomes: Any,
+                 engine_latency: Any, wasted_ms: int, early_stopped: bool,
+                 run_one: Any, ingest: Any, budget_used_ms: int | None = None,
+                 budget_total_ms: int | None = None, useful_ms: int = 0,
+                 first_sufficient_ms: int = 0, tail_wait_ms: int = 0,
+                 abandoned_engine_ms: int | None = None) -> None:
+        self.raw_results = raw_results
+        self.engine_outcomes = engine_outcomes
+        self.engine_latency = engine_latency
+        self.wasted_ms = wasted_ms
+        self.early_stopped = early_stopped
+        self.run_one = run_one
+        self.ingest = ingest
+        self.budget_used_ms = budget_used_ms
+        self.budget_total_ms = budget_total_ms
+        self.useful_ms = useful_ms
+        self.first_sufficient_ms = first_sufficient_ms
+        self.tail_wait_ms = tail_wait_ms
+        # 旧调用方只传 wasted_ms：别名取同一值，不引入第二个真源。
+        self.abandoned_engine_ms = (wasted_ms if abandoned_engine_ms is None
+                                    else abandoned_engine_ms)
+
+
+def summarize_dispatch(*, wall_ms: int, contributed_ms: list[float],
+                       first_result_at: float | None,
+                       first_sufficient_at: float | None,
+                       base: float, abandoned_ms: list[float]) -> dict[str, int]:
+    """把调度器的事件时刻折算成对外记账字段（纯函数，便于单测）。
+
+    `base` 是本次编排的单调钟起点；两个 `*_at` 都是绝对时刻。没有可交付结果
+    （全失败）时尾等待记 0：没有东西可交付，那段等待不是「可省的」。
+    """
+    useful_ms = int(min(max(contributed_ms), wall_ms)) if contributed_ms else 0
+
+    def _rel(at: float | None) -> int:
+        if at is None:
+            return 0
+        return int(min(max(at - base, 0.0), wall_ms / 1000.0) * 1000)
+
+    first_result_ms = _rel(first_result_at)
+    first_sufficient_ms = _rel(first_sufficient_at)
+    anchor = first_sufficient_ms or first_result_ms
+    return {
+        "useful_ms": useful_ms,
+        "first_result_ms": first_result_ms,
+        "first_sufficient_ms": first_sufficient_ms,
+        "tail_wait_ms": max(0, wall_ms - anchor) if anchor else 0,
+        "abandoned_engine_ms": int(sum(abandoned_ms)),
+    }

package/scripts/engine_admission.py

@@ -0,0 +1,366 @@
+#!/usr/bin/env python3
+"""engine_admission.py — 引擎生产准入状态
+
+状态文件目录（由 argo_paths 派生，ARGO_ADMISSION_DIR 可覆盖）：
+  <状态目录>/admission/<engine_id>.json
+
+字段：
+  engine_id, admitted_at, stages_passed, quality_score,
+  avg_latency_ms, blocked, reason, updated_at
+
+路由规则：
+  - blocked=true → 自动路由跳过
+  - 用户 --engine 强制指定仍可调用（调试）
+  - 无 admission 文件 → 默认放行（向后兼容存量引擎）
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cli_io import dumps_pretty
+
+# 本地状态目录唯一来源（env ARGO_STATE_DIR → config cache.db_path 父目录 → 旧路径）
+import argo_paths as _paths
+
+# ARGO_ADMISSION_DIR 优先（测试隔离）；未设置时由唯一来源派生目录
+DEFAULT_ADMISSION_DIR = Path(
+    os.path.expanduser(os.environ.get(
+        "ARGO_ADMISSION_DIR",
+        str(_paths.state_path("admission")),
+    ))
+)
+
+
+def admission_dir() -> Path:
+    # 保持每次重复执行结果一致确保目录存在：状态目录会被测试用 ARGO_STATE_DIR 隔离，进程内也
+    # 可能切换，缓存目录反而容易写到已被清理的旧目录。exist_ok=True 在目录已存在
+    # 时只是一次很便宜的路径查询，真正的重复大头（读记录前先 exists 再 read）已在
+    # load_admission 里去掉。
+    d = DEFAULT_ADMISSION_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _admission_stem(engine_id: str) -> str:
+    """engine_id → 记录文件名（去 .json）。读写共用一处转义，不得各写各的。"""
+    return engine_id.replace("/", "_").replace("..", "_")
+
+
+def admission_path(engine_id: str) -> Path:
+    return admission_dir() / f"{_admission_stem(engine_id)}.json"
+
+
+def _read_path(engine_id: str) -> Path:
+    """读记录用的路径，不触发 mkdir。
+
+    读一个还不存在的记录根本不需要先建目录；此前 load_admission 经
+    admission_path 每次都 mkdir(parents=True)，一次搜索因此多出约两百次
+    路径查询。写记录（save_admission 等）仍走 admission_path 确保目录存在。
+    """
+    return DEFAULT_ADMISSION_DIR / f"{_admission_stem(engine_id)}.json"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+# 读缓存：一次 routable 扫描会对每个引擎问一次 is_blocked()，此前每次都裸读盘
+# （实测一次扫描 668 次 read_text / 41 ms；同一份记录被读 3 次——is_blocked、
+# is_admitted、引擎详情各来一遍）。按文件路径记忆，**写入路径立即失效**：同
+# 进程读己所写永远新鲜（record_validation → load_admission 的测试序列就靠这条
+# 保证）；别的进程改了记录则由 TTL 保底（默认 1 s，ARGO_ADMISSION_TTL_S 可调，
+# 设 0 关闭记忆、回到逐次读盘）。
+#
+# 键用路径字符串而非 engine_id：状态目录可被 ARGO_STATE_DIR / ARGO_ADMISSION_DIR
+# 在进程内切换（测试隔离的常规手段），按 engine_id 记忆会把「A 目录下没有记录」
+# 错认成「B 目录下也没有」。
+_admission_read_cache: dict[str, tuple[float, dict[str, Any] | None]] = {}
+
+# env 文件回退路径的记忆化：(单调钟读数, 解析值)。
+#
+# 只记忆「env 文件」这一条，不碰 os.environ 直读——后者是字典查找、本就免费，
+# 而且必须逐次生效（本旋钮的测试与 CI 都靠 setenv 控制，记忆化会把 setenv 吞掉，
+# 例如 test_ttl_zero_disables_cache）。贵的是回退路径：engine_env.get_env →
+# _envfile_load → 对候选密钥文件逐个 stat。
+_TTL_MEMO_S = 1.0
+_ttl_envfile_memo: tuple[float, float] | None = None
+
+
+def _parse_ttl(raw: str) -> float:
+    """TTL 字符串 → 秒。空值或非法值统一回落 1.0（唯一判据，两处共用）。"""
+    try:
+        return float(raw or 1.0)
+    except ValueError:
+        return 1.0
+
+
+def _envfile_ttl() -> float:
+    """从 env 文件解析 TTL，按 _TTL_MEMO_S 秒记忆化。
+
+    本函数在**每个引擎**的准入判定里都会被调用（实测一次路由决策 215 次），
+    而回退路径每次都要穿透到 engine_env.get_env → _envfile_load → 对候选密钥
+    文件逐个 stat。同一个进程级常量被解 215 遍，实测占准入扫描的三分之一
+    （2.79ms → 1.49ms，1.87×）。窗口取 1 秒与「本模块的读缓存默认 TTL」同量级：
+    改 env 文件最多 1 秒后生效，热更语义仍成立。
+    """
+    global _ttl_envfile_memo
+    now = time.monotonic()
+    hit = _ttl_envfile_memo
+    if hit is not None and now - hit[0] < _TTL_MEMO_S:
+        return hit[1]
+    try:
+        from engine_env import get_env
+        raw = get_env("ARGO_ADMISSION_TTL_S")
+    except Exception:
+        raw = ""
+    value = _parse_ttl(raw)
+    _ttl_envfile_memo = (now, value)
+    return value
+
+
+def _admission_ttl() -> float:
+    """读缓存的 TTL（秒）；未设置或非法值回落 1.0。
+
+    走 engine_env.get_env 而不是 os.environ 直读：开关写进 ~/.config/argo/env
+    也要生效——与 config._stamp_ttl 同一计算方式（同一个旋钮不该有两套可读位置）。
+
+    os.environ 命中时逐次直读（零成本、setenv 立即生效）；只有回退到 env 文件的
+    那条路径走记忆化，见 _envfile_ttl。
+    """
+    raw = os.environ.get("ARGO_ADMISSION_TTL_S", "")
+    if raw.strip():
+        return _parse_ttl(raw)
+    return _envfile_ttl()
+
+
+def _read_admission_file(path: Path) -> dict[str, Any] | None:
+    """裸读一份准入记录（无缓存）。"""
+    # 直接读、靠异常判断文件是否存在：既不先 exists()，也不先建目录。
+    # 文件/目录不存在时 read_text 抛 FileNotFoundError（OSError 子类），一并保底。
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else None
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+
+
+# 存在集合：一次 scandir 回答「哪些引擎有记录」，替代逐引擎 open 探测。
+# 动机（2026-10-01 实测）：261 引擎只有 99 份记录，全量清单/route 扫描的
+# 261 次准入 open 里 162 次注定 ENOENT（62%）——本机 SSD 全扫描 2.8ms 无感，
+# 但慢 IO 环境（沙箱/CI/网络盘）单次 syscall 可放大到毫秒级，同一清单 4s+。
+# 集合只回答「有没有」，记录内容仍走读缓存逐条读：集合内引擎的读取行为与
+# 旧实现逐位一致，减少的只有注定扑空的那部分 open。
+#
+# 语义与读缓存同一条 TTL（_admission_ttl，ARGO_ADMISSION_TTL_S=0 一并关闭、
+# 回到逐次精确读）：窗口内别的进程新建/删除记录最多晚 TTL 秒可见，与读缓存
+# 的跨进程新鲜度同一口径。键按目录字符串——状态目录可被测试在进程内切换，
+# A 目录扫出的「无记录」不得带进 B 目录。写路径 save_admission 写完即把本
+# 引擎并入集合：同进程读己所写不等 TTL。load_admission_fresh 不走集合——
+# 读-改-写必须看到磁盘真相，绕过一切记忆。
+_admission_dir_set_cache: dict[str, tuple[float, frozenset[str]]] = {}
+
+
+def _admission_exists_set() -> frozenset[str]:
+    """有记录的引擎文件名（去 .json）集合，按 TTL 重扫目录。"""
+    key = str(DEFAULT_ADMISSION_DIR)
+    now = time.monotonic()
+    hit = _admission_dir_set_cache.get(key)
+    if hit is not None and now - hit[0] < _admission_ttl():
+        return hit[1]
+    try:
+        stems = frozenset(
+            entry.name[: -len(".json")]
+            for entry in os.scandir(DEFAULT_ADMISSION_DIR)
+            if entry.name.endswith(".json")
+        )
+    except OSError:
+        stems = frozenset()
+    _admission_dir_set_cache[key] = (now, stems)
+    return stems
+
+
+def _admission_dir_set_add(dir_key: str, stem: str) -> None:
+    """把刚写入的记录并入已缓存的集合；无缓存则不动（下次扫描自然包含）。"""
+    hit = _admission_dir_set_cache.get(dir_key)
+    if hit is not None:
+        _admission_dir_set_cache[dir_key] = (hit[0], hit[1] | {stem})
+
+
+def load_admission(engine_id: str) -> dict[str, Any] | None:
+    """读一份准入记录（带进程内 TTL 缓存，见 _admission_read_cache）。
+
+    **只用于读路径**（路由判定、状态展示）。读-改-写的调用方要用
+    load_admission_fresh：TTL 窗口里的旧值会被原样写回，吞掉别的进程刚写入的
+    字段（审计实测：子进程写入 stages_passed 的 quality，父进程在 TTL 内读-改-写
+    后只剩 health，quality 丢失）。
+    """
+    path = _read_path(engine_id)
+    ttl = _admission_ttl()
+    now = time.monotonic()
+    if ttl > 0:
+        hit = _admission_read_cache.get(str(path))
+        if hit is not None and now - hit[0] < ttl:
+            return hit[1]
+        # 存在集合短路：目录里没有这个引擎的记录，连 open 都不做（62% 注定
+        # 扑空的那部分）。扑空结果与旧实现一样进读缓存，同 TTL 新鲜度。
+        if _admission_stem(engine_id) not in _admission_exists_set():
+            _admission_read_cache[str(path)] = (now, None)
+            return None
+    data = _read_admission_file(path)
+    if ttl > 0:
+        _admission_read_cache[str(path)] = (now, data)
+    return data
+
+
+def load_admission_fresh(engine_id: str) -> dict[str, Any] | None:
+    """读一份准入记录并刷新缓存——读-改-写序列的读端专用。
+
+    写路径必须看到磁盘上的最新状态：缓存的旧值会让「读旧 → 合并 → 写回」丢掉
+    别的进程刚写进去的字段，而准入记录是路由的输入，丢字段会直接改变路由结果。
+    """
+    path = _read_path(engine_id)
+    data = _read_admission_file(path)
+    if _admission_ttl() > 0:
+        _admission_read_cache[str(path)] = (time.monotonic(), data)
+    return data
+
+
+def save_admission(engine_id: str, record: dict[str, Any]) -> dict[str, Any]:
+    path = admission_path(engine_id)
+    out = {
+        "engine_id": engine_id,
+        "admitted_at": record.get("admitted_at"),
+        "stages_passed": list(record.get("stages_passed") or []),
+        "quality_score": record.get("quality_score"),
+        "avg_latency_ms": record.get("avg_latency_ms"),
+        "blocked": bool(record.get("blocked", False)),
+        "reason": record.get("reason") or "",
+        "updated_at": _now_iso(),
+        "health": record.get("health"),
+        "quality": record.get("quality"),
+    }
+    path.write_text(dumps_pretty(out), encoding="utf-8")
+    # 写完即失效：缓存与文件是一对状态，只更新一半会让本进程读到自己没写的旧值
+    _admission_read_cache.pop(str(path), None)
+    # 存在集合同步并入：新记录不等 TTL 就可读（读己所写）
+    _admission_dir_set_add(str(path.parent), path.stem)
+    return out
+
+
+def set_blocked(engine_id: str, blocked: bool, reason: str = "") -> dict[str, Any]:
+    # 读端用 fresh：这是读-改-写序列，缓存里的旧值会被原样写回，吞掉别的进程
+    # 刚写进去的字段（TTL 窗口内的丢更新）
+    current = load_admission_fresh(engine_id) or {"engine_id": engine_id, "stages_passed": []}
+    current["blocked"] = blocked
+    current["reason"] = reason
+    if not blocked and not current.get("admitted_at"):
+        current["admitted_at"] = _now_iso()
+    return save_admission(engine_id, current)
+
+
+def record_validation(
+    engine_id: str,
+    *,
+    stages_passed: list[str],
+    quality_score: float | None = None,
+    avg_latency_ms: float | None = None,
+    blocked: bool | None = None,
+    reason: str = "",
+    health: dict[str, Any] | None = None,
+    quality: dict[str, Any] | None = None,
+    admit: bool = False,
+) -> dict[str, Any]:
+    """写入验证结果；admit=True 且未 blocked 时标记准入时间。"""
+    # 读-改-写：读端必须 fresh，否则 TTL 内的旧值会把并发写入的字段吞掉
+    current = load_admission_fresh(engine_id) or {}
+    merged_stages = list(dict.fromkeys(
+        list(current.get("stages_passed") or []) + list(stages_passed or [])
+    ))
+    if blocked is None:
+        # 默认：health 失败则 block；通过则 unblock
+        blocked = "health" not in stages_passed and bool(stages_passed)
+        if "health" in (stages_passed or []):
+            blocked = False
+        if health is not None and not health.get("ok", False) and health.get("status") != "skipped":
+            blocked = True
+
+    admitted_at = current.get("admitted_at")
+    if admit and not blocked:
+        admitted_at = _now_iso()
+    elif blocked:
+        # 保持历史 admitted_at，但 blocked 生效
+        pass
+
+    # reason 必须反映**本次**判定，不得粘滞历史原因。
+    # 此前写 `reason or current.get("reason")`：先跑 `--stage health` 失败会留下
+    # `health_failed`；之后补跑 `--stage quality`（health 已并入 merged_stages、
+    # 本次 health.ok=true 且 blocked=False）时本次 reason 为空 → 回退到历史
+    # `health_failed`，与 blocked=False 自相矛盾。引擎详情页据此显示
+    # 「blocked=true / reason=health_failed」而 health.status=pass，导致
+    # routable=False——实测 24 个引擎（批次九全部 + realtime_index）因此被
+    # 错误拉黑、装了没通电。
+    if reason:
+        eff_reason = reason
+    elif blocked:
+        eff_reason = "validation_failed"
+    else:
+        # 本次未 block：清掉历史失败原因，避免与 blocked=False 矛盾
+        eff_reason = ""
+
+    record = {
+        "admitted_at": admitted_at,
+        "stages_passed": merged_stages,
+        "quality_score": quality_score if quality_score is not None else current.get("quality_score"),
+        "avg_latency_ms": avg_latency_ms if avg_latency_ms is not None else current.get("avg_latency_ms"),
+        "blocked": blocked,
+        "reason": eff_reason,
+        "health": health if health is not None else current.get("health"),
+        "quality": quality if quality is not None else current.get("quality"),
+    }
+    return save_admission(engine_id, record)
+
+
+def is_blocked(engine_id: str, default: bool = False) -> bool:
+    """是否被准入系统拉黑。无记录时 default=False（兼容存量）。"""
+    rec = load_admission(engine_id)
+    if rec is None:
+        return default
+    return bool(rec.get("blocked", False))
+
+
+def is_admitted(engine_id: str) -> bool:
+    rec = load_admission(engine_id)
+    if rec is None:
+        return False
+    return bool(rec.get("admitted_at")) and not bool(rec.get("blocked"))
+
+
+def list_admissions() -> dict[str, dict[str, Any]]:
+    result: dict[str, dict[str, Any]] = {}
+    d = admission_dir()
+    for path in sorted(d.glob("*.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict) and data.get("engine_id"):
+                result[data["engine_id"]] = data
+            else:
+                result[path.stem] = data if isinstance(data, dict) else {}
+        except Exception:
+            continue
+    return result
+
+
+def filter_routable(engine_ids: list[str] | set[str]) -> list[str]:
+    """过滤掉 blocked 引擎，保持原顺序。"""
+    out = []
+    for e in engine_ids:
+        if is_blocked(e):
+            continue
+        out.append(e)
+    return out