argo-search 1.0.1 → 2.9.7

package/scripts/adaptive.py

@@ -9,117 +9,262 @@ adaptive.py — Unified Search v2 自适应学习引擎
   - 预算模式感知（高 cost 引擎在 budget 模式下降权）
 
 评分公式：
-  score = success_rate × latency_factor × cost_factor
+  score = success_rate × latency_factor × cost_factor × quality_factor
   latency_factor = min(1.0, 2000 / avg_latency_ms)  # 2s 内满分
   cost_factor = free=1.0, low=0.85, paid=0.6
+  quality_factor = clamp(0.75 + 0.5 × avg_quality, 0.75, 1.25)  # 无质量数据时 = 1.0
+
+quality（2026-09-27 接通）：结果相关度代理 ∈ [0,1]，由 search 层用查询词元
+覆盖率零成本算好后回写。修复「只学快慢、不学好坏」盲区——`engine_perf`
+的 `quality` 列自建库起就存在、却全仓无人写入也无人读取，1978 行实测数据
+全为 0.0：反馈信号只有 success/latency/cost，于是「成功返回一堆无关结果」
+与「成功返回精准结果」在评分上完全等价，而这是多数免密钥源的常态。
 """
 
 from __future__ import annotations
 
-import json
+import contextlib
 import os
 import sqlite3
 import threading
 import time
 from pathlib import Path
 from typing import Optional
+from cli_io import dumps
 
 # ── 路径 ──────────────────────────────────────────────────────────────────────
 
-DB_DIR = Path.home() / ".cache" / "unified-search"
+def _state_dir() -> Path:
+    """状态目录（惰性派生，支持 ARGO_STATE_DIR 覆盖）。"""
+    import argo_paths
+    return argo_paths.ensure_state_dir()
+
+
+DB_DIR = _state_dir()  # 兼容旧引用
 DB_PATH = DB_DIR / "adaptive.db"
 WINDOW_DAYS = 7
 
+# 数据过时阈值：窗口内有历史数据但最近一次调用距今超过该值，
+# 视为历史快照失效（引擎可能已恢复健康），返回中性分让其重新进入组合。
+# 被降权引擎不会出现在组合里 → 没有新记录 → 分数永远卡低（死锁），
+# 此机制类似熔断器的 half-open 探测，是自适应学习的标准恢复通道。
+STALE_AFTER_SECONDS = 24 * 3600
+
 # ── 成本分级因子 ─────────────────────────────────────────────────────────────
 
 COST_FACTORS = {"free": 1.0, "low": 0.85, "paid": 0.6}
 
+# 质量因子的取值域：±25%。刻意不放大——质量是四个维度里最噪的一个
+# （词元覆盖率只是相关度代理），让它单独颠覆 success×latency×cost 的
+# 既有排序会把「一次词面巧合」变成引擎生死。先降权，不封杀。
+QUALITY_FACTOR_MIN = 0.75
+QUALITY_FACTOR_MAX = 1.25
+
+
+def quality_factor(avg_quality: float | None, sum_quality: float | int | None) -> float:
+    """质量因子：把窗口内平均相关度映射到 ±25% 的乘数。
+
+    `sum_quality` 是**判定「有没有数据」的口径**，不是冗余参数：它取
+    `SUM(quality)`，而空结果/未回写的行 quality=0（列的 DEFAULT 0.0），
+    于是「平均值的分母」与「有数据的行数」并不一致——只有 sum>0 才能
+    说明确有质量回写。若改用 `avg > 0` 判定，窗口内全是未回写的老数据时
+    avg 恰为 0.0，会被误读成「质量极差」而把全仓引擎一次性降权
+    （本次升级前正是这个状态：1978 行 quality 全 0.0）。故一律看 sum。
+
+    - 无任何质量记录（sum=0）→ 1.0，中性，不惩罚存量数据
+    - 差结果（avg≈0.1）→ 0.80
+    - 好结果（avg≥0.8）→ 1.15
+    """
+    if not sum_quality:
+        return 1.0
+    avg = float(avg_quality or 0.0)
+    return max(QUALITY_FACTOR_MIN,
+               min(QUALITY_FACTOR_MAX, 0.75 + 0.5 * avg))
+
 
 class AdaptiveLearner:
     """自适应学习引擎：追踪引擎表现并输出推荐分数。"""
 
+    # get_score 在 route 热路径上可能每请求多次调用；内存缓存 + 复用连接
+    SCORE_CACHE_TTL = 30.0
+
     def __init__(self):
         self._lock = threading.Lock()
+        self._local = threading.local()
+        self._score_cache: dict[str, tuple[float, float]] = {}  # engine -> (score, expires_at)
+        self._batch_depth = 0
+        self._batch_dirty = False
         DB_DIR.mkdir(parents=True, exist_ok=True)
         self._init_db()
 
+    @contextlib.contextmanager
+    def batch(self):
+        """合并多次 record 为单次 SQLite commit，保持 record 调用面不变。"""
+        with self._lock:
+            self._batch_depth = getattr(self, "_batch_depth", 0) + 1
+        try:
+            yield
+        finally:
+            with self._lock:
+                self._batch_depth = max(0, getattr(self, "_batch_depth", 1) - 1)
+                if self._batch_depth == 0 and getattr(self, "_batch_dirty", False):
+                    self._connect().commit()
+                    self._batch_dirty = False
+
     def _connect(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(str(DB_PATH), timeout=10)
-        conn.execute("PRAGMA journal_mode=WAL")
+        """线程本地复用连接，避免 route 每次 open/close SQLite。"""
+        conn = getattr(self._local, "conn", None)
+        if conn is not None:
+            return conn
+        conn = sqlite3.connect(str(DB_PATH), timeout=10, check_same_thread=False)
+        import argo_paths
+        argo_paths.apply_state_pragmas(conn)
+        self._local.conn = conn
         return conn
 
     def _init_db(self):
-        with self._connect() as conn:
-            conn.execute("""
-                CREATE TABLE IF NOT EXISTS engine_perf (
-                    engine TEXT NOT NULL,
-                    success INTEGER NOT NULL,
-                    latency_ms REAL NOT NULL,
-                    cost REAL NOT NULL DEFAULT 0.0,
-                    created_at REAL NOT NULL
-                )
-            """)
-            # 检查列是否存在（迁移）
-            cols = [r[1] for r in conn.execute("PRAGMA table_info(engine_perf)")]
-            if "created_at" not in cols:
-                conn.execute("ALTER TABLE engine_perf ADD COLUMN created_at REAL DEFAULT 0")
-            if "cost" not in cols:
-                conn.execute("ALTER TABLE engine_perf ADD COLUMN cost REAL DEFAULT 0.0")
-            # 检查索引
-            conn.execute("CREATE INDEX IF NOT EXISTS idx_perf_engine_time ON engine_perf(engine, created_at)")
-            # 清理过期数据
-            cutoff = time.time() - WINDOW_DAYS * 86400
-            conn.execute("DELETE FROM engine_perf WHERE created_at < ?", (cutoff,))
+        conn = self._connect()
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS engine_perf (
+                engine TEXT NOT NULL,
+                success INTEGER NOT NULL,
+                latency_ms REAL NOT NULL,
+                cost REAL NOT NULL DEFAULT 0.0,
+                created_at REAL NOT NULL,
+                empty INTEGER NOT NULL DEFAULT 0
+            )
+        """)
+        cols = [r[1] for r in conn.execute("PRAGMA table_info(engine_perf)")]
+        if "created_at" not in cols:
+            conn.execute("ALTER TABLE engine_perf ADD COLUMN created_at REAL DEFAULT 0")
+        if "cost" not in cols:
+            conn.execute("ALTER TABLE engine_perf ADD COLUMN cost REAL DEFAULT 0.0")
+        if "empty" not in cols:
+            # 老库补列：历史行 empty=0，等价于旧口径（空结果也算失败），
+            # 不做回溯改写——我们无法知道那些行当时到底是「空」还是「错」。
+            conn.execute("ALTER TABLE engine_perf ADD COLUMN empty INTEGER DEFAULT 0")
+        if "quality" not in cols:
+            # 同理补列。历史行 quality=0 表示「当时没回写质量」，不是「质量为零」——
+            # 评分侧以 SUM(quality) > 0 判定有无数据，故这批行不会拉低任何引擎。
+            conn.execute("ALTER TABLE engine_perf ADD COLUMN quality REAL DEFAULT 0.0")
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_perf_engine_time ON engine_perf(engine, created_at)"
+        )
+        cutoff = time.time() - WINDOW_DAYS * 86400
+        conn.execute("DELETE FROM engine_perf WHERE created_at < ?", (cutoff,))
+        conn.commit()
+
+    def record(self, engine: str, success: bool, latency_ms: float, cost: float = 0.0,
+               empty: bool = False, quality: float | None = None):
+        """记录一次引擎调用结果。
 
-    def record(self, engine: str, success: bool, latency_ms: float, cost: float = 0.0):
-        """记录一次引擎调用结果。"""
+        ``empty=True`` 表示「引擎正常，但这次查询它没有结果」——与「失败」是
+        两回事，见 `get_score` 的说明。默认 False 保持旧调用方行为不变。
+
+        ``quality`` 是本次结果的相关度代理 ∈ [0,1]（调用方用词元覆盖率算好
+        回写，见 search_pipeline 的回填点）。None = 拿不到质量信号，此时
+        落 0.0 而**不是**当作「质量为零」参与评分——`quality_factor` 以
+        `SUM(quality) > 0` 判定有无数据，故未回写的行不会拖累任何引擎。
+        """
+        q = 0.0 if quality is None else max(0.0, min(1.0, float(quality)))
         with self._lock:
-            with self._connect() as conn:
-                conn.execute(
-                    "INSERT INTO engine_perf (engine, success, latency_ms, cost, created_at) VALUES (?, ?, ?, ?, ?)",
-                    (engine, 1 if success else 0, latency_ms, cost, time.time()),
-                )
+            conn = self._connect()
+            conn.execute(
+                "INSERT INTO engine_perf "
+                "(engine, success, latency_ms, cost, created_at, empty, quality) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (engine, 1 if success else 0, latency_ms, cost, time.time(),
+                 1 if empty else 0, q),
+            )
+            if getattr(self, "_batch_depth", 0) > 0:
+                self._batch_dirty = True
+            else:
                 conn.commit()
+            self._score_cache.pop(engine, None)
 
     def get_score(self, engine: str) -> float:
-        """获取引擎的综合推荐分数（0.0 ~ 1.0）。"""
+        """获取引擎的综合推荐分数（0.0 ~ 1.0）。
+
+        **只按「有明确结果」的调用算成功率**（`empty=0`）。
+
+        为什么要把空结果排除：分数被用来决定「这个源该不该继续用」，
+        而「这次查询它没东西」说明的是**查询与源不匹配**，不是源坏了。
+        两者混在一起会误杀：实测 github 在窗口内 63 次调用、成功率 6%，
+        失败归因全是 empty——它被用来回答各种查询，只有少数落进它的覆盖范围；
+        而它却在 `local_code` / `package_search` 这些**声明要用它**的域里
+        因分数低于 0.3 被整个剔除。同类还有 wikipedia(0.17)、
+        openalex(0.29)、hackernews(0.10)、twitter(0.17)、open_library(0.17)。
+
+        延迟与成本仍按全部调用统计——空结果也是真实开销。
+        """
+        now = time.time()
+        cached = self._score_cache.get(engine)
+        if cached and cached[1] > now:
+            return cached[0]
+
         with self._lock:
-            cutoff = time.time() - WINDOW_DAYS * 86400
-            with self._connect() as conn:
-                row = conn.execute(
-                    "SELECT COUNT(*), AVG(success), AVG(latency_ms), AVG(cost) FROM engine_perf WHERE engine = ? AND created_at > ?",
-                    (engine, cutoff),
-                ).fetchone()
-        total, avg_success, avg_latency, avg_cost = row
-        if not total or total == 0:
-            return 0.5  # 无数据时中性分
-
-        success_rate = avg_success or 0.5
-        latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
-        # 成本因子：平均成本越低越好
-        cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
-
-        return round(success_rate * latency_factor * cost_factor, 4)
+            cached = self._score_cache.get(engine)
+            if cached and cached[1] > now:
+                return cached[0]
+            cutoff = now - WINDOW_DAYS * 86400
+            conn = self._connect()
+            row = conn.execute(
+                "SELECT COUNT(*), "
+                "       SUM(CASE WHEN empty = 0 THEN 1 ELSE 0 END), "
+                "       SUM(CASE WHEN empty = 0 THEN success ELSE 0 END), "
+                "       AVG(latency_ms), AVG(cost), "
+                "       AVG(quality), SUM(quality), MAX(created_at) "
+                "FROM engine_perf WHERE engine = ? AND created_at > ?",
+                (engine, cutoff),
+            ).fetchone()
+        total, judged, judged_ok, avg_latency, avg_cost, avg_q, sum_q, last_ts = row
+        total = int(total or 0)
+        judged = int(judged or 0)
+        if not total:
+            score = 0.5  # 无数据时中性分
+        else:
+            # 数据过时恢复：最后一次调用距今过久 → 中性分，给恢复探测机会
+            last_ts = float(last_ts or 0)
+            if last_ts and (now - last_ts) > STALE_AFTER_SECONDS:
+                score = 0.5
+            elif judged == 0:
+                # 窗口内全是空结果：没有任何可判定健康与否的调用 → 中性分。
+                # 给中性分而不是 0：否则「每次都只是没搜到」会把源打死。
+                score = 0.5
+            else:
+                success_rate = (judged_ok or 0) / judged
+                latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
+                cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
+                q_factor = quality_factor(avg_q, sum_q)
+                score = round(success_rate * latency_factor * cost_factor
+                              * q_factor, 4)
+
+        self._score_cache[engine] = (score, now + self.SCORE_CACHE_TTL)
+        return score
 
     def get_ranking(self) -> list[tuple[str, float]]:
-        """获取所有引擎的推荐排名（降序）。"""
+        """获取所有引擎的推荐排名（降序）。空结果的排除口径同 `get_score`。"""
         with self._lock:
             cutoff = time.time() - WINDOW_DAYS * 86400
-            with self._connect() as conn:
-                rows = conn.execute(
-                    "SELECT engine, COUNT(*), AVG(success), AVG(latency_ms), AVG(cost) "
-                    "FROM engine_perf WHERE created_at > ? GROUP BY engine",
-                    (cutoff,),
-                ).fetchall()
+            conn = self._connect()
+            rows = conn.execute(
+                "SELECT engine, "
+                "       SUM(CASE WHEN empty = 0 THEN 1 ELSE 0 END), "
+                "       SUM(CASE WHEN empty = 0 THEN success ELSE 0 END), "
+                "       AVG(latency_ms), AVG(cost), AVG(quality), SUM(quality) "
+                "FROM engine_perf WHERE created_at > ? GROUP BY engine",
+                (cutoff,),
+            ).fetchall()
 
         results = []
-        for engine, total, avg_success, avg_latency, avg_cost in rows:
-            if not total:
+        for engine, judged, judged_ok, avg_latency, avg_cost, avg_q, sum_q in rows:
+            if not judged:
                 continue
-            success_rate = avg_success or 0.5
+            success_rate = (judged_ok or 0) / judged
             latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
             cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
-            score = round(success_rate * latency_factor * cost_factor, 4)
+            score = round(success_rate * latency_factor * cost_factor
+                          * quality_factor(avg_q, sum_q), 4)
             results.append((engine, score))
 
         results.sort(key=lambda x: -x[1])
@@ -127,22 +272,28 @@ class AdaptiveLearner:
 
     def get_stats(self) -> dict:
         """获取所有引擎的统计信息。"""
-        ranking = self.get_ranking()
         cutoff = time.time() - WINDOW_DAYS * 86400
-        with self._connect() as conn:
-            rows = conn.execute(
-                "SELECT engine, COUNT(*), AVG(success), AVG(latency_ms), AVG(cost) "
-                "FROM engine_perf WHERE created_at > ? GROUP BY engine",
-                (cutoff,),
-            ).fetchall()
+        conn = self._connect()
+        rows = conn.execute(
+            "SELECT engine, COUNT(*), AVG(success), AVG(latency_ms), AVG(cost), "
+            "       AVG(quality), SUM(quality) "
+            "FROM engine_perf WHERE created_at > ? GROUP BY engine",
+            (cutoff,),
+        ).fetchall()
 
         stats = {}
-        for engine, total, avg_success, avg_latency, avg_cost in rows:
+        for engine, total, avg_success, avg_latency, avg_cost, avg_q, sum_q in rows:
+            # 质量相关度：avg 是窗口内均值；`quality_tracked` 标明这批数据
+            # 里是否真的有质量回写——没有时 avg_q 恒为 0，看数会误读成
+            # 「这个源质量极差」，而实际是「一直没测过」。
             stats[engine] = {
                 "calls": total,
                 "success_rate": round(avg_success or 0, 3),
                 "avg_latency_ms": round(avg_latency or 0, 1),
                 "avg_cost": round(avg_cost or 0, 6),
+                "avg_quality": round(avg_q or 0, 3),
+                "quality_tracked": bool(sum_q),
+                "quality_factor": round(quality_factor(avg_q, sum_q), 3),
                 "score": self.get_score(engine),
             }
         return stats
@@ -151,6 +302,56 @@ class AdaptiveLearner:
         """判断引擎是否值得使用（分数高于阈值）。"""
         return self.get_score(engine) >= threshold
 
+    def latency_percentile(self, engine: str, p: float = 0.75,
+                           min_samples: int = 5) -> Optional[float]:
+        """窗口内「正常交付」延迟的分位数（毫秒）；样本不足/过时/无数据 → None。
+
+        口径比 `get_score` 的 judged 更严（judged 仅 empty=0，这里是
+        其子集）：只统计 **success=1 且 empty=0** 的
+        行——「这个源在它能回答的查询上多快」。空结果的低延迟会把分位数拉低，
+        但空结果并不解决对冲竞速（sufficiency 判据不放行），把它算进来会让
+        宽限窗对「只会秒回空结果」的源收得过紧，反而多发对冲调用。
+
+        用途（2026-10-11，调度微手术）：给对冲宽限窗一个「快引擎收窄、慢引擎
+        不动」的自适应窗，见 engine_dispatch._adaptive_grace。只做读侧，不缓存
+        ——每次编排至多一次查询（窗口内样本量小，全量取回后本地排序，免去依赖
+        SQLite 版本的 percentile 扩展）。
+
+        调用次数说明（2026-10-16 修订）：此处原文写「每次编排至多一次」，
+        随 straggler_policy.straggler_tail 接入后不再成立——分层尾宽会在
+        每次交付时刻对「还没回来的引擎」逐个取值（2 引擎编排约 1 次，多引
+        擎编排最坏 ≈ 各次交付的 waiting 数之和）。默认关（ARGO_ADAPTIVE_TAIL）
+        时不发生；开启后每引擎每次约 0.07ms（实测 200 次调用 warm），代价
+        相对引擎 RTT 可忽略，但判「多不多」时按这个口径，别按旧句子。
+        """
+        if not engine:
+            return None
+        try:
+            q = float(p)
+        except (TypeError, ValueError):
+            return None
+        if not 0.0 < q < 1.0:
+            return None
+        now = time.time()
+        cutoff = now - WINDOW_DAYS * 86400
+        with self._lock:
+            conn = self._connect()
+            rows = conn.execute(
+                "SELECT latency_ms, created_at FROM engine_perf "
+                "WHERE engine = ? AND created_at > ? "
+                "  AND success = 1 AND empty = 0",
+                (engine, cutoff),
+            ).fetchall()
+        if not rows or len(rows) < max(1, int(min_samples)):
+            return None
+        # 数据过时恢复：与 get_score 同判据——窗口内有行但最近一次调用距今
+        # 过久，说明这张快照已不能代表引擎现状（可能已恢复/已换网络环境）。
+        if (now - max(float(ts) for _, ts in rows)) > STALE_AFTER_SECONDS:
+            return None
+        lats = sorted(float(lat) for lat, _ in rows)
+        idx = min(len(lats) - 1, max(0, int(round(q * (len(lats) - 1)))))
+        return lats[idx]
+
 
 # ── 模块级单例 ─────────────────────────────────────────────────────────────────
 
@@ -170,7 +371,7 @@ if __name__ == "__main__":
     import sys
     learner = get_learner()
     if len(sys.argv) > 1 and sys.argv[1] == "stats":
-        print(json.dumps(learner.get_stats(), ensure_ascii=False, indent=2))
+        print(dumps(learner.get_stats()))
     elif len(sys.argv) > 1 and sys.argv[1] == "rank":
         ranking = learner.get_ranking()
         for engine, score in ranking:

package/scripts/answer.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""answer.py — 直答端点（Answer 形态）：带引用的合成答案。
+
+吸纳自 2026-09 对标研究：Brave Answers / Perplexity Sonar / Seltz Answer
+三家同形态，行业已收紧为「搜索的 Answer 端点」标配。当前通道：
+Seltz POST /v1/answer（x-api-key 鉴权，注册赠 20000 次）。
+
+**scope 决定语料，不传默认 news**：上游只支持 news / wikipedia / people /
+companies 四个语料。2026-09-16 实测：不传 scope 时技术查询（「RRF 融合算法」）
+拿到的是 news 语料里的时政与播客条目，看上去像「引用跑偏」，实为语料选错
+而非上游坏了。实测四个语料——companies 查公司概况最好（Apple / 台积电 答得
+准且完整）；news 在真新闻查询上可用但覆盖窄；wikipedia 干净；people 不可用
+（10 条全 linkedin.com，人名查不到），故不对外推荐。
+
+置信计算方式：上游响应无置信度标量（2026-09-14 实测），故输出诚实计数——
+引用条数 + 唯一引用域名数；上游若日后提供 confidence 字段则原样透传。
+不造模拟精确度的单一分数。
+
+用法：
+  argo answer "query"                     # --json 由 bin/argo 默认注入
+  argo answer "query" --scope companies    # 查公司概况
+  argo answer "query" --model seltz-pro    # 模型自己发起检索，更慢更贵
+  python3 answer.py "query" --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from urllib.parse import urlparse
+from cli_io import dumps
+from engine_env import get_env
+
+_SELTZ_ANSWER_URL = "https://api.seltz.ai/v1/answer"
+_SELTZ_SCOPES = ("news", "wikipedia", "people", "companies")
+_SELTZ_MODELS = ("seltz-base", "seltz-pro")
+
+
+def _unique_domains(citations: list) -> int:
+    hosts = set()
+    for c in citations or []:
+        if isinstance(c, dict):
+            u = str(c.get("url") or "")
+        else:
+            u = str(c or "")
+        if u:
+            hosts.add(urlparse(u).hostname or "")
+    return len(hosts - {""})
+
+
+def seltz_answer(query: str, timeout: float = 40.0, *,
+                 scope: str | None = None, model: str | None = None) -> tuple[dict | None, str]:
+    """调 Seltz Answer；返回 (响应 dict, 错误串)。响应含 answer/citations。
+
+    scope / model 不传就由上游取默认（news / seltz-base）。scope 传错值时上游
+    返回 404，故此处先按白名单挡掉，错误信息比 HTTP 404 好读。
+    """
+    scope = (scope or "").strip().lower()
+    model = (model or "").strip().lower()
+    if scope and scope not in _SELTZ_SCOPES:
+        return None, f"未知 scope {scope!r}（可选：{'/'.join(_SELTZ_SCOPES)}）"
+    if model and model not in _SELTZ_MODELS:
+        return None, f"未知 model {model!r}（可选：{'/'.join(_SELTZ_MODELS)}）"
+    key = get_env(["ARGO_SELTZ_API_KEY", "SELTZ_API_KEY"])
+    if not key:
+        return None, "SELTZ_API_KEY 未设置（写入 ~/.config/argo/env 后重试）"
+    body: dict = {"query": query}
+    if scope:
+        body["scope"] = scope
+    if model:
+        body["model"] = model
+    try:
+        from http_client import HttpClient
+        # max_retries=0：合成答案一次计费一次调用，引擎内重试会双倍烧赠额
+        client = HttpClient(timeout=timeout, max_retries=0, jitter=False)
+        resp = client.post(_SELTZ_ANSWER_URL, body=body, extra_headers={
+            "x-api-key": key, "Content-Type": "application/json",
+        })
+    except Exception as e:
+        return None, f"seltz answer 请求失败: {e}"
+    if resp.get("status", 0) != 200 or not resp.get("text"):
+        return None, f"seltz answer HTTP {resp.get('status')}"
+    try:
+        data = json.loads(resp["text"])
+    except (ValueError, TypeError):
+        return None, "seltz answer 响应非 JSON"
+    if not isinstance(data, dict) or "answer" not in data:
+        return None, f"seltz answer 响应缺 answer 字段: {str(data)[:200]}"
+    return data, ""
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="直答：带引用的合成答案（Seltz）")
+    ap.add_argument("query", help="要回答的问题")
+    ap.add_argument("--json", action="store_true", help="JSON 输出（bin/argo 默认注入）")
+    ap.add_argument("--scope", choices=list(_SELTZ_SCOPES), default=None,
+                    help="语料：companies 查公司概况最好；news 覆盖窄；"
+                         "people 实测不可用。不传由上游取默认 news")
+    ap.add_argument("--model", choices=list(_SELTZ_MODELS), default=None,
+                    help="seltz-base（默认，一次检索）或 seltz-pro（模型自己发起检索）")
+    ap.add_argument("--timeout", type=float, default=40.0)
+    args = ap.parse_args()
+
+    t0 = time.monotonic()
+    data, err = seltz_answer(args.query, timeout=args.timeout,
+                             scope=args.scope, model=args.model)
+    elapsed_ms = int((time.monotonic() - t0) * 1000)
+
+    if err:
+        envelope = {"status": "error", "query": args.query, "error": err,
+                    "elapsed_ms": elapsed_ms}
+        print(dumps(envelope))
+        sys.exit(1)
+
+    citations = data.get("citations") or []
+    # 上游无置信度标量：诚实计数计算方式；有则透传（前向兼容）
+    confidence = {"citations": len(citations),
+                  "unique_domains": _unique_domains(citations)}
+    if isinstance(data.get("confidence"), (int, float)):
+        confidence["upstream"] = data["confidence"]
+
+    envelope = {
+        "status": "completed",
+        "query": args.query,
+        # scope 如实回填实际生效值（未传即上游默认 news），便于排查语料选错
+        "scope": args.scope or "news",
+        "model": args.model or "seltz-base",
+        "answer": str(data.get("answer") or ""),
+        "citations": citations,
+        "confidence": confidence,
+        "engine": "seltz",
+        "elapsed_ms": elapsed_ms,
+    }
+    if args.json:
+        print(dumps(envelope))
+        return
+    # 人类可读：答案正文 + 引用清单
+    print(envelope["answer"])
+    if citations:
+        print("\n引用:")
+        for i, c in enumerate(citations, 1):
+            if isinstance(c, dict):
+                print(f"  [{i}] {str(c.get('url') or '')}")
+            else:
+                print(f"  [{i}] {c}")
+    print(f"\n语料: {envelope['scope']} · 模型: {envelope['model']}")
+    print(f"置信口径: {dumps(envelope['confidence'])}")
+
+
+if __name__ == "__main__":
+    main()