argo-search 1.0.1 → 2.9.8

package/scripts/search_types.py

@@ -1,25 +1,118 @@
 #!/usr/bin/env python3
-"""
-search_types.py — 统一类型系统
-
-定义 SearchResult 数据类和 normalize_result 统一转换，
-将所有引擎的原始输出统一为结构化格式。
-
-字段规范：
-  - title: 结果标题（必填，截断到 200 字符）
-  - url: 结果链接（可选）
-  - snippet: 摘要/片段（截断到 300 字符）
-  - score: 相关性评分（默认 0.5）
-  - source: 引擎来源
-  - metadata: 元数据字典
+"""search_types.py — 统一类型系统（轻量记录 + 零依赖 dataclass 替代）。
+
+`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
 
-from dataclasses import dataclass, field, asdict
+import sys
+from enum import Enum
 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
@@ -27,7 +120,8 @@ 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]:
         """转为字典，省略空值/默认值字段。"""
@@ -42,6 +136,8 @@ class SearchResult:
             d["source"] = self.source
         if self.metadata:
             d["metadata"] = self.metadata
+        if self.social_meta:
+            d["social_meta"] = self.social_meta
         return d
 
 
@@ -69,4 +165,21 @@ def normalize_result(item: dict, engine: str, default_score: float = 0.5) -> Sea
         score=score,
         source=item.get("source", engine),
         metadata=item.get("metadata", {}),
+        social_meta=item.get("social_meta"),
     )
+
+
+class Stage(str, Enum):
+    """进度回调的阶段名（on_progress 契约）。
+
+    从 search.py 搬来这里：执行层与加工层（search_pipeline）都要发进度事件，
+    枚举放在任何一侧都会让另一侧反向依赖；search_types 是本仓共享类型的家。
+    """
+
+    START = "start"
+    CACHE_HIT = "cache_hit"
+    ROUTING = "routing"
+    SEARCHING = "searching"
+    MERGING = "merging"
+    DONE = "done"
+    ERROR = "error"

package/scripts/seek_locator.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""seek_locator.py — local-seek 子技能的「安装感知」定位（唯一来源，不写死主机路径）。
+
+本地搜索（argo_local_search / --include-local）需要 local-seek/scripts/seek.py。
+local-seek 随 argo 打包在 sub-skills/ 下（安装感知：寻址锚点是本文件的真实安装位置），
+也可能作为独立 skill 装在别处。此模块把发现逻辑收紧到一处，供 search.py 与
+mcp_handlers.py 共用，消除两处各自硬编码 __file__ 相对路径与 ~/.agents/skills 等
+主机路径的重复（Fowler: Duplicated Code 反面却是各自为政、易漂移）。
+
+保持一致 SKILL.md 纪律「禁止在产品代码写死主机 skill 路径」：不再出现
+~/.agents/skills / ~/.claude/skills 这类字面量，改由环境变量承载自定义/遗留位置。
+
+查找顺序（命中即返回，全部未命中则返回打包位置，由调用方据此 fail 提示）：
+  1. ARGO_LOCAL_SEEK_PATH      显式指定 seek.py 的绝对/相对路径（任意自定义位置）
+  2. <ARGO_ROOT>/sub-skills/local-seek/scripts/seek.py
+                               —— 打包子技能，锚点为本模块的安装位置（symlink 会解析回来源）
+  3. ARGO_LOCAL_SEEK_ROOTS     os.pathsep 分隔的候选根目录，逐个检查
+                               <根>/local-seek/scripts/seek.py（承载遗留/独立装法）
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator
+
+ARGO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_BUNDLED = os.path.join(ARGO_ROOT, "sub-skills", "local-seek", "scripts", "seek.py")
+
+
+def _candidates() -> Iterator[str]:
+    """按优先级产出候选 seek.py 路径（仅路径，未校验存在性）。
+
+    优先级：显式文件覆盖 > 显式候选根 > 打包位置（默认）。
+    显式配置（ARGO_LOCAL_SEEK_PATH / ARGO_LOCAL_SEEK_ROOTS）代表用户点名了
+    装在哪，理应先于总是存在的打包子技能；打包位置只作保底。
+    """
+    override = (os.environ.get("ARGO_LOCAL_SEEK_PATH") or "").strip()
+    if override:
+        yield os.path.realpath(os.path.expanduser(override))
+    roots = (os.environ.get("ARGO_LOCAL_SEEK_ROOTS") or "").strip()
+    if roots:
+        for root in roots.split(os.pathsep):
+            root = root.strip()
+            if not root:
+                continue
+            base = os.path.realpath(os.path.expanduser(root))
+            candidate = os.path.join(base, "local-seek", "scripts", "seek.py")
+            if os.path.isfile(candidate):
+                yield candidate
+    yield _BUNDLED
+
+
+def resolve_seek_py() -> str:
+    """返回 local-seek/scripts/seek.py 的绝对路径（命中即返回，未命中返回打包位置）。"""
+    for cand in _candidates():
+        if cand and os.path.isfile(cand):
+            return cand
+    return _BUNDLED
+
+
+def seek_py_exists() -> bool:
+    """本地搜索能力是否可用（seek.py 实际存在）。"""
+    return os.path.isfile(resolve_seek_py())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import sys
+    print(resolve_seek_py())

package/scripts/semantic_evidence.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""semantic_evidence.py — 可选的语义证据层（classifier.dev，默认关闭）。
+
+## 为什么存在
+
+argo 的正文吸收分是**正则密度**（has_numbers / has_definition / …），它测的是
+「这段文本长得像不像证据块」，不测「它是否支持这条查询的主张」。2026-09-19 的
+实测（reports/classifier-dev-argo/A、B）：密度最高页判 neutral、密度最低页判
+supports 0.99，两者近乎反向；而假前提主张（查询预设「降息」、现实是「加息」）
+密度分在结构上无法表达，语义判定 5/5 判 contradicts（conf 0.95~1.00）。
+
+## 定位（与热路径解耦）
+
+- **只在显式核验链路调用**（`search --verify` / `research --verify`），不进搜索
+  热路径：热命中 78~82ms 且网络为零，一次分类调用 200~680ms，放进热路径是净损失
+- **默认关闭**：config.yaml `semantic_evidence.enabled: false`；显式开启用环境变量
+  `ARGO_SEMANTIC_EVIDENCE=1`（env 优先于 config）
+- **fail-open**：超时 / HTTP 错误 / 429 / 解析失败 / 条数不匹配 → 返回 None，
+  调用方行为与未开启时逐位一致（不加字段、不改排序、不改公式）
+- **只加并列字段**：`semantic_support` 挂在结果与 verified 条目上，可信度公式
+  （selection 0.40 / absorption 0.35 / freshness 0.15 / original 0.10）不动
+
+## 外部服务约束（2026-09-19 实测，见 reports/classifier-dev-argo/D）
+
+- 无密钥、HTTP 通道稳定（1000 条 1.83s、顺序严格保真）；CLI 与 MCP 通道当前不可用
+  （npm/PyPI 404、MCP tools/call 返回 not_found），因此只走 HTTP
+- 必须带真实 User-Agent（python urllib 默认 UA 被边缘 403）——复用 HttpClient 的
+  UA 轮换与 429 退避
+- 标签集必须显式含「none of these」：服务永远返回给定标签之一，不加会把无关文本
+  硬塞进某个标签
+- 同输入置信度有 ±0.08 漂移（标签稳定），所以只做 ≥0.7 的粗门控；实测 conf ≥0.7
+  时严格错误为 0（51 条 entailment 样本）
+- 限额按出口 IP：fast 3000 次/分钟、20000 次/天；空串输入会让整批 400，调用前过滤
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Optional
+
+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 字
+# 置信度反而从 0.73 升到 0.98，说明长文不劣化，但也没必要超发）
+MAX_TEXT_CHARS = 8000
+
+SUPPORT_LABELS = (
+    "supports the query",
+    "contradicts the query",
+    "neutral",
+    "none of these",
+)
+SOURCE_TYPE_LABELS = (
+    "primary data or official announcement",
+    "secondary reporting",
+    "analysis or opinion",
+    "social narrative",
+    "none of these",
+)
+
+
+def _config() -> dict[str, Any]:
+    """读 config.yaml 的 semantic_evidence 段（缺失时用内置默认）。"""
+    try:
+        from config import load_config
+        cfg = load_config().get("semantic_evidence")
+        return cfg if isinstance(cfg, dict) else {}
+    except Exception:  # pragma: no cover - 配置不可用按默认关处理
+        return {}
+
+
+def enabled() -> bool:
+    """开关判定：环境变量优先，其次 config.yaml；两者都缺省 → 关闭。
+
+    用 engine_env.get_env/env_flag 读（全仓唯一的布尔解析），所以
+    `ARGO_SEMANTIC_EVIDENCE=off`、写进 ~/.config/argo/env 的写法都生效。
+    """
+    try:
+        from engine_env import env_flag, get_env
+        if get_env("ARGO_SEMANTIC_EVIDENCE").strip():
+            return env_flag("ARGO_SEMANTIC_EVIDENCE", default=False)
+    except Exception:  # pragma: no cover - 环境层不可用时不冒险开启
+        return False
+    return bool(_config().get("enabled", False))
+
+
+def _endpoint() -> str:
+    return str(_config().get("endpoint") or DEFAULT_ENDPOINT).rstrip("/")
+
+
+def _timeout() -> float:
+    try:
+        return float(_config().get("timeout_s") or DEFAULT_TIMEOUT_S)
+    except (TypeError, ValueError):
+        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]]]:
+    """一次批量分类。任何异常/非 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],
+        "tier": tier or str(_config().get("tier") or "fast"),
+    }
+    if instructions:
+        body["instructions"] = instructions
+    try:
+        from http_client import HttpClient
+        # 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
+        data = json.loads(resp.get("text") or "{}")
+        results = data.get("results")
+        if not isinstance(results, list) or len(results) != len(keep):
+            logger.debug("语义分类返回条数与输入不匹配，按失败处理")
+            return None
+    except Exception as e:  # fail-open：语义层任何问题都不阻断核验
+        logger.debug(f"语义分类失败: {type(e).__name__}")
+        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 assess_support(query: str, items: list[dict[str, Any]]) -> Optional[dict[str, dict]]:
+    """对已抓取的正文批量判定「是否支持查询隐含的主张」。
+
+    items: [{"url": str, "title": str, "text": str}]
+    返回 {url: {label, confidence, supports, contradicts}}；未达阈值时
+    supports/contradicts 均为 False（原始 label 与 confidence 仍原样保留，
+    调用方可自行换阈值）。失败返回 None。
+    """
+    usable = [it for it in items if (it.get("text") or "").strip() and it.get("url")]
+    if not usable:
+        return None
+    texts = [f"{it.get('title') or ''}\n{(it.get('text') or '')[:MAX_TEXT_CHARS]}"
+             for it in usable]
+    instructions = (
+        f"Judge whether each passage supports the claim implied by this query: {query!r}. "
+        "Answer 'supports the query' when the passage backs the claim, "
+        "'contradicts the query' when it states the opposite or a conflicting figure, "
+        "'neutral' when it is on-topic but neither supports nor contradicts, "
+        "and 'none of these' when it is unrelated to the query."
+    )
+    results = classify(texts, SUPPORT_LABELS, instructions=instructions)
+    if results is None:
+        return None
+    out: dict[str, dict] = {}
+    for it, r in zip(usable, results):
+        if not r:
+            continue
+        label = str(r.get("label") or "")
+        conf = r.get("confidence")
+        conf_f = float(conf) if isinstance(conf, (int, float)) else 0.0
+        out[str(it["url"])] = {
+            "label": label,
+            "confidence": conf_f,
+            "supports": label == "supports the query" and conf_f >= SUPPORT_THRESHOLD,
+            "contradicts": label == "contradicts the query" and conf_f >= SUPPORT_THRESHOLD,
+        }
+    return out or None
+
+
+def assess_source_types(items: list[dict[str, Any]]) -> Optional[dict[str, dict]]:
+    """来源类型分级（研究取证链路用）：一手数据 / 二手报道 / 分析观点 / 社交叙事。
+
+    items: [{"url": str, "title": str, "text": str}]（text 可为摘要）
+    """
+    usable = [it for it in items if it.get("url") and
+              ((it.get("text") or "").strip() or (it.get("title") or "").strip())]
+    if not usable:
+        return None
+    texts = [f"{it.get('title') or ''}\n{(it.get('text') or '')[:MAX_TEXT_CHARS]}"
+             for it in usable]
+    instructions = (
+        "Classify each source by its nature: 'primary data or official announcement' "
+        "for original datasets, filings, official releases; 'secondary reporting' for "
+        "news coverage of someone else's work; 'analysis or opinion' for commentary; "
+        "'social narrative' for forum/social posts."
+    )
+    results = classify(texts, SOURCE_TYPE_LABELS, instructions=instructions)
+    if results is None:
+        return None
+    out: dict[str, dict] = {}
+    for it, r in zip(usable, results):
+        if not r:
+            continue
+        label = str(r.get("label") or "")
+        conf = r.get("confidence")
+        out[str(it["url"])] = {
+            "label": label,
+            "confidence": float(conf) if isinstance(conf, (int, float)) else 0.0,
+        }
+    return out or None