argo-search 2.9.7 → 2.9.8

package/scripts/search_pipeline.py

@@ -30,7 +30,7 @@ http_client / engines_base / engine_dispatch。
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field, replace
+from search_types import slot_record as dataclass, slot_field as field, slot_replace as replace
 from typing import Any
 
 # 模块级曾有一行 `import logging`，而本模块 7 处 `logging.getLogger(...)`
@@ -56,8 +56,9 @@ from variant_recall import augment_with_variants
 from phrase_filter import apply_phrase_filter, extract_phrases
 from except_sets import OPT_IMPORT, SHAPE_BENIGN
 from postprocess_signals import apply_tfidf_polish, detect_number_conflict
-from search_attribution import usage_log_attribution
+from search_attribution import usage_log_attribution, is_synthetic_run
 from search_output import _collect_errors, _slow_query_ttl, build_funnel
+from serp_kill_log import clean_engine_lists
 from search_rank import (
     _LANG_SCRIPT,
     _RERANK_DEGRADED_STATUSES,
@@ -153,6 +154,7 @@ class _SearchRun:
     engine_latency: dict[str, float] = field(default_factory=dict)
     wasted_ms: int = 0
     useful_ms: int = 0
+    dispatch_tail: dict[str, int] = field(default_factory=dict)
     early_stopped: bool = False
     budget_used_ms: int | None = None
     budget_total_ms: int | None = None
@@ -236,16 +238,8 @@ def postprocess(req: _SearchRequest, run: _SearchRun, hooks: Any) -> _SearchRun:
     merged = run.merged
 
     # 融合输入派生（原先在 execute_search 里，属于加工的第一步）
-    valid_lists = [
-        res for res in raw_results.values()
-        if res and any(isinstance(r, dict) and "error" not in r for r in res)
-    ]
-    # 去掉 error-only 列表中的 error 条目
-    clean_lists = []
-    for res in valid_lists:
-        clean = [r for r in res if isinstance(r, dict) and "error" not in r]
-        if clean:
-            clean_lists.append(clean)
+    # 去 error 与 SERP 守卫同源：缓存命中的结果也要过同一道门（issue #18）。
+    clean_lists = clean_engine_lists(raw_results, query)
 
     # 查询主语言：噪声门与语言能力加权共用同一个判定（唯一来源，
     # 避免两处各自算导致行为漂移）。
@@ -387,8 +381,8 @@ def postprocess(req: _SearchRequest, run: _SearchRun, hooks: Any) -> _SearchRun:
     _funnel_deduped = len(merged)
     if merged:
         try:
-            from serp_guard import is_serp_or_jump_url as _is_serp  # 轻依赖，锁见 test_hotpath_import_lint.py
-            merged = [r for r in merged if not _is_serp(r.get("url", ""))]
+            from serp_guard import is_unusable_url as _is_unusable  # SERP + 内容农场，标定见 test_content_farm_guard.py
+            merged = [r for r in merged if not _is_unusable(r.get("url", ""), r.get("title", ""), r.get("snippet", ""))]
         except ImportError:
             pass  # serp_guard 不可用时跳过（本地五维 rerank 已对 SERP 降权）
 
@@ -515,176 +509,33 @@ def postprocess(req: _SearchRequest, run: _SearchRun, hooks: Any) -> _SearchRun:
     except OPT_IMPORT + SHAPE_BENIGN:  # 守卫不可用不设卡（fail-open）
         _echo_triggered = False
     if not merged or _echo_triggered:
-        # ── 恢复链 L0：early-stop 误判时补跑被跳过的同域引擎 ──
-        # （同域优先于 L3 换跨域引擎；实现在 recovery_l0）。死线 = 用户
-        # 声明的整体超时扣掉 dispatch 已耗墙钟——补跑不得把总时长推出
-        # 用户预算（语义见 recovery_l0 模块 docstring 的死线约束）。
-        try:
-            import time as _time
-            from recovery_l0 import maybe_retry_skipped
-            try:
-                _l0_deadline = _time.monotonic() + max(
-                    0.0, float(req.timeout or 0)
-                    - float(run.budget_used_ms or 0) / 1000.0)
-            except (TypeError, ValueError):
-                _l0_deadline = None
-            _l0_merged, _l0_info = maybe_retry_skipped(
-                run.early_stopped, engines_combo, raw_results,
-                available_engines, query, _run_one, _ingest,
-                max_results, _emit_usage, deadline=_l0_deadline)
-        except SHAPE_BENIGN:
-            _l0_merged, _l0_info = [], None
-        if _l0_merged and _l0_info:
-            recovery_info = _l0_info
-            merged = _l0_merged
-    if not merged or _echo_triggered:
-        try:
-            from recovery import run_recovery
-            tried = list(raw_results.keys()) or list(engines)
-            fallback_engines = decision.get("engines_fallback") or []
-            # 域路由零结果：恢复链放行 L3 换引擎。复杂度门此前把简单查询
-            # 压到 L2——L3 被禁 + 全域零结果 = 域命中查询无解（实测
-            # macro_data「中国GDP」零结果、恢复链空转）。engines_fallback
-            # 里是路由的定向保底声明（域未试成员优先），代价可控。
-            rec_level = _max_rec_level
-            if _echo_triggered:
-                # 退化是「引擎选错了」而非「查询写得不好」：L1 放宽 / L2 换词
-                # 都救不了「上游把整句当单词查」，必须换引擎（L3）。
-                rec_level = "L3"
-            elif fallback_engines and decision.get("domain") not in (
-                    None, "", "general", "general_search") \
-                    and (rec_level is None or rec_level < "L3"):
-                rec_level = "L3"
-            try:
-                enabled_set = set(available_engines())
-            except Exception:
-                enabled_set = None
-
-            def _recovery_executor(rq: str, rengines: list[str]) -> list[dict[str, Any]]:
-                """恢复执行器：对冲竞速跑候选引擎，取首个非空。跳过缓存避免污染。
-
-                并行形态（2026-09-29）：原为严格串行——域查询零结果时 recovery
-                段占 process_ms 的 79–86%（实测中位 906ms；「黄金价格」2019ms、
-                「比特币行情」1989ms），是体感「有时特别慢」的直接原因。改为
-                「起步间隔 = grace 的有界并发」（bounded_run.run_bounded 的
-                stagger 语义，与 dispatch 串行路径同一套对冲哲学，见
-                engine_dispatch._run_engines_bounded）：首引擎先跑，grace 内
-                交付仍只付一次调用，超时才补发下一匹；任一引擎交付非空即收工。
-                grace 复用 hooks.primary_grace_s（标定依据见 search._PRIMARY_GRACE_S），
-                不新增开关面。总等待上限 = grace×(n-1) + timeout + 1s ≤ 串行版
-                n×timeout，最坏情况也不慢于改造前。消融：把 primary_grace 调到
-                大于引擎超时上限即完全退回严格串行（与 ARGO_SERIAL_STAGGER_S
-                同思路）。daemon 线程不 join，卡住的 HTTP 读拖不垮止损。
-                """
-                def _fire(eng: str) -> list[dict[str, Any]]:
-                    _dk = {k: v for k in ("domain", "sub_domain") if (v := getattr(req, "engine_" + k, None))}
-                    # 记下真正发出的调用：恢复段走的不是 dispatch，若不单独记账，
-                    # 漏斗会算出「routed 2 → called 2 → returned 5」这种自相矛盾的
-                    # 账（实测「python 怎么读csv」），而这正是最需要被看见的路径。
-                    _recovery_engines.add(eng)
-                    try:
-                        # 恢复路径同样携带时间窗，避免恢复时丢弃用户约束；
-                        # --no-cache 也要透传：本函数的契约是「跳过缓存避免污染」，
-                        # 不透传会让恢复段既读到用户明确拒绝的旧缓存，又把自己的
-                        # 临时查询写进缓存（dispatch 那条路径是透传的，两处不一致）。
-                        res = engine_search(rq, eng, n=max_results,
-                                            timeout=timeout, depth=depth, mode=mode,
-                                            since=since_iso, until=until_iso,
-                                            skip_cache=skip_cache, **_dk)
-                    except Exception as e:
-                        import sys
-                        sys.stderr.write(
-                            f"[recovery] 恢复链异常（{type(e).__name__}）: {e}\n")
-                        res = []
-                    goods = [r for r in (res or [])
-                             if isinstance(r, dict) and "error" not in r]
-                    # 恢复段同样进配额账：它真的打了引擎（engine_search），
-                    # 而 quota_batch.add 的全仓唯一常规入口在 dispatch 的
-                    # _run_one 里——恢复链不走那条路，不在这里补一行，
-                    # 这批消耗就落在本地账本之外（见下方 flush 处注释）。
-                    # add 是 list.append（GIL 下原子），对冲线程并发调用安全。
-                    quota_batch.add(eng, bool(goods))
-                    if goods:
-                        for r in goods:
-                            r.setdefault("_engine", eng)
-                            r.setdefault("_recovered", True)
-                        # 回声不算「恢复成功」（判据与理由见
-                        # postprocess_signals.drop_echo_items）：不拦则 L1 放宽
-                        # 查询后收工，L3 换引擎永不执行。
-                        try:
-                            from postprocess_signals import drop_echo_items as _drop_echo
-                            goods = _drop_echo(goods, rq)
-                        except OPT_IMPORT + SHAPE_BENIGN:
-                            pass
-                    return goods
-
-                if len(rengines) <= 1:
-                    return _fire(rengines[0]) if rengines else []
-                grace = max(0.0, float(hooks.primary_grace_s or 0.0))
-                wait_s = grace * (len(rengines) - 1) \
-                    + max(1.0, float(timeout)) + 1.0
-
-                def _enough(finished: list[tuple[str, Any]]) -> bool:
-                    # 任一引擎交付非空即收工：不再起排队中的引擎（省调用），
-                    # 已在跑的归 unfinished（daemon，结果丢弃但配额已如实记）。
-                    return any(isinstance(v, list) and v for _i, v in finished)
-
-                finished, _unfinished = run_bounded(
-                    rengines, _fire, wait_s, max_workers=3,
-                    enough=_enough, stagger_s=grace)
-                # finished 按完成先后排列：首个非空即「最快非空」。与串行版
-                # 「首个非空」的差别只在来源引擎——恢复候选都过 run_recovery
-                # 的 query-signal 门，质量由它把关。
-                for _item, value in finished:
-                    if isinstance(value, list) and value:
-                        return value
-                return []
-
-            rec_results, rec_result = run_recovery(
-                query, tried, _recovery_executor,
-                engines_fallback=fallback_engines, enabled=enabled_set, mode=mode,
-                max_level=rec_level)
-            recovery_info = rec_result.to_dict()
-            # P2-6：恢复使用日志——query 截断脱敏，只记概览不记明细
-            if _emit_usage is not None:
-                try:
-                    _emit_usage("recovery", {
-                        "query": (query[:60] if query else query),
-                        "triggered": recovery_info.get("triggered"),
-                        "recovered": recovery_info.get("recovered"),
-                        "level_used": recovery_info.get("level_used"),
-                        "strategy_used": recovery_info.get("strategy_used"),
-                        "steps_tried": len(recovery_info.get("steps_tried") or []),
-                        "final_query": (recovery_info.get("final_query") or "")[:60],
-                        "note": recovery_info.get("note", ""),
-                    })
-                except SHAPE_BENIGN:  # 使用日志记录失败不影响恢复结果本身
-                    pass
-            if rec_results:
-                # 恢复结果复检壳口径：主链的壳过滤跑在恢复链之前，恢复产出
-                # 是唯一可能把壳带回最终输出的入口（唯一出口在
-                # serp_guard.drop_shell_urls，L0/L3/充分性三处共用）。
-                try:
-                    from recovery_l0 import finalize_l3_results
-                    merged = finalize_l3_results(rec_results, max_results)
-                except ImportError:
-                    merged = deduplicate_by_url(rec_results)[:max_results]
-                # 恢复引擎按引擎分组记回 raw_results：engines_used 此前不含
-                # 救援引擎（provenance 断链，实测恢复成功后 engines_used 仍
-                # 只列原 combo），自适应学习也看不到恢复成功信号。
-                _rec_by_eng: dict[str, list] = {}
-                for r in merged:
-                    eng = r.get("_engine") or r.get("source") or ""
-                    if eng:
-                        r.setdefault("consensus_engines", [eng])
-                        _rec_by_eng.setdefault(eng, []).append(r)
-                for _eng, _lst in _rec_by_eng.items():
-                    raw_results.setdefault(_eng, _lst)
-        except ImportError:
-            pass  # recovery 模块不可用
-        except Exception as e:
-            _log(
-                f"错误恢复跳过: {type(e).__name__}")
+        from recovery_runner import run_pipeline_recovery
+        _dk = {k: v for k in ("domain", "sub_domain") if (v := getattr(req, "engine_" + k, None))}
+        merged, _rec_info = run_pipeline_recovery(
+            query=query,
+            merged=merged,
+            raw_results=raw_results,
+            decision=decision,
+            engines=engines,
+            available_engines_fn=available_engines,
+            max_results=max_results,
+            max_rec_level=_max_rec_level,
+            echo_triggered=_echo_triggered,
+            primary_grace_s=float(hooks.primary_grace_s or 0.0),
+            timeout=timeout,
+            depth=depth,
+            mode=mode,
+            since_iso=since_iso,
+            until_iso=until_iso,
+            skip_cache=skip_cache,
+            quota_batch=quota_batch,
+            engine_search_fn=engine_search,
+            emit_usage_fn=_emit_usage,
+            recovery_engines_set=_recovery_engines,
+            engine_domain_extra=_dk,
+        )
+        if _rec_info:
+            recovery_info = _rec_info
 
     # 配额记账落盘：整批一次写入文件（同一次搜索的 N 个引擎合并为一次写）。
     # 位置是契约：必须在**最后一个 quota add 点**之后。D6 补搜走后，
@@ -886,6 +737,7 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
     funnel = run.funnel
     result_payload = run.result_payload
     wasted_ms, useful_ms = run.wasted_ms, run.useful_ms
+    dispatch_tail = run.dispatch_tail
     early_stopped = run.early_stopped
     budget_used_ms, budget_total_ms = run.budget_used_ms, run.budget_total_ms
     elapsed = run.elapsed
@@ -979,15 +831,15 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
     # 字符（与 recovery 流同一脱敏纪律）；记录失败静默，绝不拖累主路径。
     # 取自 req 而非局部别名：_emit_usage 是 postprocess 的局部变量，
     # 本函数（finalize）不在其作用域内，直接引用会 NameError。
-    if req.emit_usage_log is not None:
+    if req.emit_usage_log is not None and not is_synthetic_run(raw_results):
         try:
-            # 引擎级耗时归因（2026-10-15 起）：写在 search_attribution，本处只接线。
+            # 归因走 search_attribution；合成引擎（基准/混沌）整条不入日志。
             req.emit_usage_log("query", {
                 "query": (query[:60] if query else query),
                 "count": len(merged),
                 "elapsed_ms": round(elapsed),
                 "engines_used": list(raw_results.keys())[:8],
-                **usage_log_attribution(engine_latency),
+                **usage_log_attribution(engine_latency, engine_outcomes=engine_outcomes),
                 "errors": len(_collect_errors(raw_results, engine_outcomes)),
                 "recovered": bool(recovery_info.get("recovered")) if recovery_info else False,
                 "early_stopped": bool(early_stopped),
@@ -1054,19 +906,16 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
         out["timing"] = timing.summary()
         out["timing"]["elapsed_ms"] = elapsed
         out["timing"]["dispatch"] = {
-            # 用 dispatch 自己那口单调钟量出来的墙钟（budget_used_ms），不用外层
-            # 这笔 time.time() 差值：useful/wasted 都是单调钟算的，混用两种钟会
-            # 对不上账。注意 2026-10-10 记账改版起 useful + wasted 与 wall 没有
-            # 恒等式关系，别再按恒等式读仪表（口径真源：engine_dispatch 记账注释）。
+            # 墙钟/尾等待/弃置的口径真源见 dispatch_result.py；useful + wasted 与
+            # wall 没有恒等式（2026-10-10 起），不要再按恒等式读仪表。
             "wall_ms": budget_used_ms,
             "engines_run": len(engine_latency),
             "engine_sum_ms": eng_sum,
             "parallel_efficiency": (round(eng_sum / budget_used_ms, 2)
                                     if budget_used_ms else None),
-            # useful = 最后一个贡献结果引擎的完成时刻；wasted = 被编排主动弃置
-            # 的引擎已花墙钟之和。与 wall 无恒等式（真源：engine_dispatch 记账注释）。
             "useful_ms": useful_ms,
             "wasted_ms": wasted_ms,
+            **dispatch_tail,
             "early_stopped": early_stopped,
         }
         if budget_total_ms is not None:

package/scripts/search_types.py

@@ -1,20 +1,118 @@
 #!/usr/bin/env python3
-"""search_types.py — 统一类型系统（已废弃，勿接入）
+"""search_types.py — 统一类型系统（轻量记录 + 零依赖 dataclass 替代）。
 
-早期设计声明的统一 schema 层，从未被任何模块 import（grep 全仓库无引用）：
-  - 引擎输出直接透传 dict，运行时防御在 engines_base/safe_search 与
-    search.py 的 execute_search 里完成
-  - 保留本文件仅避免旧版外部脚本 import 断裂；新代码禁止使用
+`slot_record` / `slot_field` / `slot_replace` 是为热路径准备的
+`@dataclass` / `field` / `replace` 零依赖替代：`dataclasses` 的导入链是
+`dataclasses → inspect → tokenize → dis`（实测 ~8ms），而 `SearchResult`
+这类记录在每次搜索都要构造，导入成本全落在固定开销上。
+
+兼容面：挂 `__dataclass_fields__`，标准库的 `dataclasses.replace` /
+`is_dataclass` / `fields` 对实例照常工作（`_field_type` 惰性解析）。
+
+仍不建议新代码接入本模块的 `SearchResult`（引擎输出直接透传 dict，运行时
+防御在 engines_base/safe_search 里）；这里的价值在**替代实现本身**。
 """
 from __future__ import annotations
 
+import sys
 from enum import Enum
-
-from dataclasses import dataclass, field, asdict
 from typing import Any
 
 
-@dataclass
+class _FieldMeta:
+    """`__dataclass_fields__` 的兼容描述子。
+
+    `dataclasses.replace` 只读 `.init`；`dataclasses.fields` 会按
+    `_field_type is dataclasses._FIELD` 过滤，所以 `_field_type` 做成**惰性
+    属性**：dataclasses 已被 import 时（也就是有人真去调 `fields()` 时）
+    返回真哨兵，没 import 时返回 None。热路径因此仍然零导入——`_FIELD`
+    只在 dataclasses 已经进场后才去取它。
+    """
+
+    __slots__ = ("name", "init")
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.init = True
+
+    @property
+    def _field_type(self) -> Any:
+        dc = sys.modules.get("dataclasses")
+        return getattr(dc, "_FIELD", None) if dc is not None else None
+
+
+class _SlotField:
+    __slots__ = ("factory",)
+
+    def __init__(self, default_factory: Any) -> None:
+        self.factory = default_factory
+
+
+def slot_field(*, default_factory: Any) -> Any:
+    """零依赖 field(default_factory=...) 替代。"""
+    return _SlotField(default_factory)
+
+
+def _class_annotations(cls: Any) -> dict:
+    """读类的注解，兼容 PEP 649 惰性注解。
+
+    `cls.__dict__["__annotations__"]` 在 3.14 的惰性注解下**可能根本不存在**
+    （注解由 `__annotate__` 描述子按需计算，不进类字典）——此时取到的是
+    `{}`，类会静默变成「零字段」，实例化时报一个与真因毫不相干的
+    TypeError。必须走 `getattr` 触发描述子。
+    """
+    return getattr(cls, "__annotations__", None) or {}
+
+
+def slot_record(_cls: Any = None, *, frozen: bool = False) -> Any:
+    """零依赖 @dataclass 替代（省去 import dataclasses→inspect→tokenize→dis ~8ms）。
+
+    挂上 `__dataclass_fields__` 兼容描述子，标准库 `dataclasses.replace` /
+    `dataclasses.is_dataclass` / `dataclasses.fields` 对实例照常工作，但热
+    路径自身零导入（`_field_type` 惰性解析，只在 dataclasses 已进场时取哨兵）。
+    """
+    def _wrap(cls: Any) -> Any:
+        ann = list(_class_annotations(cls).keys())
+        defaults = {k: cls.__dict__[k] for k in ann if k in cls.__dict__}
+
+        def __init__(self: Any, *args: Any, **kwargs: Any) -> None:
+            if len(args) > len(ann):
+                raise TypeError(f"{cls.__name__}.__init__() takes {len(ann)} positional arguments but {len(args)} were given")
+            for i, val in enumerate(args):
+                object.__setattr__(self, ann[i], val)
+            for k in ann[len(args):]:
+                if k in kwargs:
+                    val = kwargs.pop(k)
+                elif k in defaults:
+                    d = defaults[k]
+                    val = d.factory() if isinstance(d, _SlotField) else d
+                else:
+                    raise TypeError(f"{cls.__name__}.__init__() missing required argument: {k!r}")
+                object.__setattr__(self, k, val)
+            if kwargs:
+                bad = next(iter(kwargs))
+                raise TypeError(f"{cls.__name__}.__init__() got an unexpected keyword argument {bad!r}")
+
+        cls._slot_fields = tuple(ann)
+        cls.__dataclass_fields__ = {k: _FieldMeta(k) for k in ann}
+        cls.__init__ = __init__
+        if frozen:
+            def __setattr__(self: Any, name: str, value: Any) -> None:
+                raise AttributeError(f"cannot assign to field {name!r}")
+            cls.__setattr__ = __setattr__
+        return cls
+
+    return _wrap if _cls is None else _wrap(_cls)
+
+
+def slot_replace(obj: Any, **changes: Any) -> Any:
+    """零依赖 replace(obj, **changes) 替代。"""
+    kw = {k: getattr(obj, k) for k in obj._slot_fields}
+    kw.update(changes)
+    return type(obj)(**kw)
+
+
+@slot_record
 class SearchResult:
     """统一的搜索结果数据类。"""
     title: str
@@ -22,7 +120,7 @@ class SearchResult:
     snippet: str = ""
     score: float = 0.5
     source: str = ""
-    metadata: dict = field(default_factory=dict)
+    metadata: dict = slot_field(default_factory=dict)
     social_meta: dict | None = None
 
     def to_dict(self) -> dict[str, Any]:

package/scripts/semantic_evidence.py

@@ -43,6 +43,31 @@ logger = logging.getLogger("unified_search.semantic_evidence")
 
 DEFAULT_ENDPOINT = "https://classifier.dev"
 DEFAULT_TIMEOUT_S = 5.0
+# 未声明 transport 时的默认通道。jev = TypeSafe System One（当前唯一可用）；
+# classifier.dev 的匿名路径 2026-10-22 起回 403 proxy_requires_payment。
+DEFAULT_TRANSPORT = "jev"
+
+# ── JEV / System One 通道（TypeSafe）──────────────────────────────────────
+# 官方 API：POST https://api.typesafe.ai/v1/systemone，Bearer 鉴权
+# （docs.typesafe.ai/api/system-one）。与 classifier.dev 的 /v1/classify 是
+# **两种形状**：那边一次发 N 条文本 + 一组标签；这边一次发一个 state + 若干
+# 具名问题，每题独立作答（文档原话：questions are evaluated in parallel and
+# in isolation）。所以接过来要做的是形状转换，不是换个 URL。
+DEFAULT_JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone"
+DEFAULT_JEV_MODEL = "jev-latest"
+# key 候选链：argo 推荐名在前；TYPESAFE_API_KEY 是官方 SDK 与 JEV 插件
+# （dsh-verbatim-compaction）用的名字，照文档配的人直接可用。
+JEV_KEY_ENV = ("ARGO_JEV_API_KEY", "TYPESAFE_API_KEY")
+# state 超过这个长度就带长上下文头。实测（2026-10-22 本机）：
+#   不带 TypeSafe-Danger-Zone-Long-Context：32K tokens 通过（32350）、
+#     40K 中文字（≈40K tokens）回 `max_tokens_exceeded`（400）
+#   带上：40K 字（40358 tokens）与 80K 字（80358 tokens）均通过
+# 24000 字是保守拐点（正常路径不带头也稳），不是实测上限。
+JEV_LONG_CONTEXT_CHARS = 24000
+# 并发上限。官方 cookbook（classifying_rag_passages）取 4，理由是端点限流；
+# 429/529 要求指数退避，所以不铺大。
+JEV_MAX_WORKERS = 4
+
 # conf ≥ 0.7 才给结论：低于此值的判定不可信（B 实测 4 个严格错误全部 ≤0.67）
 SUPPORT_THRESHOLD = 0.7
 # 单条文本上限：核验链路取回的正文 ≤8000 字，再高无收益（A 实测 400→7798 字
@@ -100,20 +125,167 @@ def _timeout() -> float:
         return DEFAULT_TIMEOUT_S
 
 
+def jev_api_key() -> str:
+    """JEV（TypeSafe）key：os.environ 优先，~/.config/argo/env 热读保底。"""
+    try:
+        from engine_env import get_env
+        return (get_env(list(JEV_KEY_ENV)) or "").strip()
+    except Exception:  # pragma: no cover - 环境层不可用时不冒险
+        import os
+        for _n in JEV_KEY_ENV:
+            _v = (os.environ.get(_n) or "").strip()
+            if _v:
+                return _v
+        return ""
+
+
+def _transport() -> str:
+    """通道选择：`jev`（TypeSafe System One）或 `classify`（classifier.dev）。
+
+    **纯配置驱动，不做「按键就绪自动选」**。初版按 jev_api_key() 是否就绪自动
+    选，结果是通道取决于本机 ~/.config/argo/env 里有没有那把 key——同一份代码
+    在开发机与 CI 上走不同分支，既有测试在开发机上会静默改道（实测：写进 key
+    后 test_semantic_evidence 的 5 条 HttpClient 桩里 1 条改走 JEV 路径而挂）。
+    机器状态不该改变代码路径。
+
+    未声明时的默认是 jev：classifier.dev 的匿名路径 2026-10-22 起回 403
+    proxy_requires_payment，JEV 是当前可用的那条。
+    """
+    declared = str(_config().get("transport") or "").strip().lower()
+    return declared if declared in ("jev", "classify") else DEFAULT_TRANSPORT
+
+
+def _jev_endpoint() -> str:
+    """JEV 端点：**独立于 classify 通道的 endpoint 字段**。
+
+    不共用是刻意的坑修：config.yaml 里 `endpoint` 长期写的是
+    https://classifier.dev，JEV 通道若读同一个字段，就会把 System One 的
+    请求体发到 classifier.dev，拿回「Invalid API key / Create a workspace
+    key at /app/keys」这种指向完全错误方向的 401（2026-10-22 实测踩中）。
+    每个通道自带端点，杜绝「换 transport 忘了换 endpoint」。
+    """
+    return str(_config().get("jev_endpoint") or DEFAULT_JEV_ENDPOINT).rstrip("/")
+
+
+def _jev_model() -> str:
+    return str(_config().get("jev_model") or _config().get("model")
+               or DEFAULT_JEV_MODEL)
+
+
+def _jev_post(path_state: Any, questions: dict[str, Any], *,
+              timeout: float) -> Optional[dict[str, Any]]:
+    """一次 System One 请求；失败返回 None（fail-open 的全部出口都在这里）。"""
+    key = jev_api_key()
+    if not key:
+        logger.debug("JEV key 未配置（%s），语义层跳过", " / ".join(JEV_KEY_ENV))
+        return None
+    body = {
+        "model": _jev_model(),
+        "state": path_state,
+        "questions": questions,
+    }
+    # Content-Type 必须显式给：HttpClient.post 会把 dict 做 json.dumps，
+    # 但**从不设 Content-Type**（头只来自浏览器 UA 模板 + extra_headers）。
+    # 缺它时 FastAPI 侧把 body 当字符串，回
+    #   422 {"loc":["body"],"msg":"Input should be a valid dictionary…"}
+    # ——报错指向「请求体不是对象」，而真因是少了一个头（2026-10-22 实测踩中）。
+    headers = {"Authorization": f"Bearer {key}",
+               "Content-Type": "application/json"}
+    # 长上下文要显式带头，否则 state 一过 32K tokens 就 400 max_tokens_exceeded
+    if len(json.dumps(path_state, ensure_ascii=False)) > JEV_LONG_CONTEXT_CHARS:
+        headers["TypeSafe-Danger-Zone-Long-Context"] = "true"
+    try:
+        from http_client import HttpClient
+        resp = HttpClient(timeout=timeout, max_retries=1, jitter=False).post(
+            _jev_endpoint(), body, extra_headers=headers)
+        if resp.get("status") != 200:
+            logger.debug("JEV 非 200: %s %s", resp.get("status"),
+                         str(resp.get("text") or resp.get("error") or "")[:200])
+            return None
+        return json.loads(resp.get("text") or "{}")
+    except Exception as e:  # fail-open：语义层任何问题都不阻断核验
+        logger.debug("JEV 请求失败: %s", type(e).__name__)
+        return None
+
+
+def _jev_choice(text: str, labels: tuple[str, ...] | list[str],
+                instructions: str | None, timeout: float
+                ) -> Optional[dict[str, Any]]:
+    """单条文本 → 一个 Choice 问题。
+
+    **每条一个请求**，不是「多段一个 state、每段一问」。理由在官方文档里：
+    jaggedness 那篇明写「state 里塞与决策无关的细节会降低准确率（context
+    rot）」，而判第 i 段时其余各段就是无关细节；cookbook 的
+    classifying_rag_passages 也是「One request per passage」。（我们试过 3 段
+    合一，结果全对，但样本太小，不拿它赌准确率。）
+    """
+    out = _jev_post(text, {
+        "cls": {
+            "type": "choice",
+            "instructions": instructions or "Classify the state into one of the criteria.",
+            # criteria 的**值**是描述：jaggedness 说 instructions 与 criteria
+            # 不一致时模型会困惑，所以两边用同一句话，不给它两个版本。
+            "criteria": {str(lab): str(lab) for lab in labels},
+        },
+    }, timeout=timeout)
+    if not isinstance(out, dict):
+        return None
+    ans = (out.get("answers") or {}).get("cls")
+    if not isinstance(ans, dict) or not ans.get("choice"):
+        if isinstance(ans, dict):
+            logger.debug("JEV 答案缺 choice: %s", str(ans)[:120])
+        return None
+    return {
+        "label": str(ans.get("choice")),
+        "confidence": ans.get("confidence"),
+        "scores": ans.get("probabilities"),
+    }
+
+
+def _classify_jev(texts: list[str], labels: tuple[str, ...] | list[str], *,
+                  instructions: str | None, keep: list[tuple[int, str]],
+                  timeout: float) -> Optional[list[dict[str, Any]]]:
+    """JEV 通道：每条文本一个请求，并发 4。
+
+    任一条失败就在该位留 None（与 classifier.dev 通道「整批失败即 None」
+    不同）：一次核验有几条正文，坏一条不该把其余判定的价值也丢掉。全部失败
+    时仍返回 None，调用方行为与未开启时一致。
+    """
+    from concurrent.futures import ThreadPoolExecutor
+    texts_kept = [t[:MAX_TEXT_CHARS] for _i, t in keep]
+    with ThreadPoolExecutor(max_workers=min(JEV_MAX_WORKERS, len(texts_kept))) as pool:
+        results = list(pool.map(
+            lambda t: _jev_choice(t, labels, instructions, timeout), texts_kept))
+    if not any(r for r in results):
+        return None
+    out: list[Optional[dict[str, Any]]] = [None] * len(texts)
+    for (idx, _t), r in zip(keep, results):
+        if isinstance(r, dict):
+            out[idx] = r
+    return out  # type: ignore[return-value]
+
+
 def classify(texts: list[str], labels: tuple[str, ...] | list[str], *,
              instructions: str | None = None,
              timeout: float | None = None,
              tier: str | None = None) -> Optional[list[dict[str, Any]]]:
-    """一次批量分类（≤1000 条）。任何异常/非 200/条数不匹配 → None。
+    """一次批量分类。任何异常/非 200/条数不匹配 → None。
 
     返回按输入顺序排列的 [{label, confidence, scores}]；调用方负责判定阈值。
     空文本会被过滤后再发（空串会让整批 400），返回列表与输入等长、空缺位为 None。
+
+    两个通道的实现分居 _classify_jev（TypeSafe，每条一请求）与下方内联的
+    classifier.dev 路径（一次发 N 条）；开关判定见 _transport。
     """
     if not texts or len(labels) < 2:
         return None
     keep = [(i, t) for i, t in enumerate(texts) if (t or "").strip()]
     if not keep:
         return None
+    to = timeout or _timeout()
+    if _transport() == "jev":
+        return _classify_jev(texts, labels, instructions=instructions,
+                             keep=keep, timeout=to)
     body: dict[str, Any] = {
         "labels": [str(x) for x in labels],
         "inputs": [t[:MAX_TEXT_CHARS] for _i, t in keep],
@@ -123,8 +295,12 @@ def classify(texts: list[str], labels: tuple[str, ...] | list[str], *,
         body["instructions"] = instructions
     try:
         from http_client import HttpClient
-        resp = HttpClient(timeout=timeout or _timeout(), max_retries=1,
-                          jitter=False).post(_endpoint(), body)
+        # Content-Type 同 JEV 通道：HttpClient.post 不设它，缺了会被服务端
+        # 当字符串解析。这条路径此前只在 403（匿名要付费 key）处止步，没走到
+        # body 校验，所以同一个坑没暴露——配了有效 workspace key 就会现形。
+        resp = HttpClient(timeout=to, max_retries=1, jitter=False).post(
+            _endpoint(), body,
+            extra_headers={"Content-Type": "application/json"})
         if resp.get("status") != 200:
             logger.debug(f"语义分类非 200: {resp.get('status')} {resp.get('error')}")
             return None