argo-search 1.0.1 → 2.9.7

package/scripts/stats_cli.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""stats_cli.py — `argo stats`：使用日志与反馈状态的读出口。
+
+数据源 = usage_log.py 的本地 JSONL 日志流（<状态目录>/usage_log/，总开关
+ARGO_USAGE_LOG=0 可关，目录 ARGO_USAGE_LOG_DIR 可注入）：
+  query    每次非缓存搜索一条总账（次数/引擎/命中数/时延/救援）
+  recovery 救援链触发概览
+  route    路由采样
+  merge    融合去重概览
+
+纪律：只读不写；本地数据不出本机（隐私判据见 references/usage.md「日志与反馈」）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import usage_log  # noqa: E402
+from cli_io import dumps  # noqa: E402
+from search_attribution import aggregate_slow_engines  # noqa: E402
+
+
+def _query_summary(n: int) -> dict:
+    rows = usage_log.tail("query", n)
+    if not rows:
+        return {"samples": 0}
+    counts = [r.get("count", 0) for r in rows]
+    lat = [r.get("elapsed_ms") for r in rows if isinstance(r.get("elapsed_ms"), (int, float))]
+    engines: Counter = Counter()
+    # 引擎级耗时归因（2026-10-15）：query 流新增 engine_latency_top，
+    # 这里按「慢源累计耗时」排序，把「长期是谁在拖」直接摆到 stats 上——
+    # 此前只能离线重算日志（local_search 独跑占 369s 就是这么翻出来的）。
+    # 聚合是纯函数，住 search_attribution（与写侧同一份口径真源）。
+    for r in rows:
+        for e in (r.get("engines_used") or [])[:8]:
+            engines[e] += 1
+    return {
+        "samples": len(rows),
+        # 2026-10-18 改名：原字段叫 hit_rate，实际算的是「有结果的查询比例」
+        # （count>0），与 SearchCache.stats 的缓存命中率同名不同义——实测被
+        # 读成「缓存全命中」（=1.0）。保留语义，换掉会误导的名字。
+        "result_rate": round(sum(1 for c in counts if c) / len(rows), 3),
+        "avg_elapsed_ms": round(sum(lat) / len(lat)) if lat else None,
+        "recovered": sum(1 for r in rows if r.get("recovered")),
+        "top_engines": engines.most_common(5),
+        "slowest_engines": aggregate_slow_engines(rows),
+        "recent": [
+            {"query": r.get("query"), "count": r.get("count"),
+             "elapsed_ms": r.get("elapsed_ms")}
+            for r in rows[-5:]
+        ],
+    }
+
+
+def _stream_summary(name: str, n: int) -> dict:
+    rows = usage_log.tail(name, n)
+    return {"samples": len(rows), "recent": rows[-3:]}
+
+
+def build_report(n: int) -> dict:
+    return {
+        "data_dir": str(usage_log.stream_dir()),
+        "privacy": "本地使用日志 JSONL，仅本机不外发；ARGO_USAGE_LOG=0 可整体关闭",
+        "query": _query_summary(n),
+        "recovery": _stream_summary("recovery", n),
+        "route": _stream_summary("route", n),
+        "merge": _stream_summary("merge", n),
+        "hints": [
+            "流量回放/审计：argo search --archive（完整候选归档）",
+            "引擎健康：argo preflight --probe / --list-engines --detail",
+            "关闭日志：ARGO_USAGE_LOG=0",
+        ],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="argo stats", description="使用日志与反馈状态（本地使用日志只读出口）")
+    ap.add_argument("-n", type=int, default=50, help="回看最近 N 条（默认 50）")
+    ap.add_argument("--json", action="store_true", help="JSON 输出")
+    args = ap.parse_args(argv)
+    report = build_report(max(1, min(args.n, 500)))
+    out = dumps(report)
+    print(out if args.json else out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/straggler_policy.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""straggler_policy.py — 收尾尾宽的取值策略（2026-10-16 从 search.py 拆出）。
+
+拆出原因：取值函数是**纯策略**（读开关 + 读自适应学习器 + 分档表），不
+依赖 search.py 的任何东西；放在 search.py 里只为「和其他旋钮常量做邻居」。
+search.py 是被 module size 门禁盯着的文件（1000 行硬限），本次拆出顺带
+把尾宽策略的判据（为什么是 0.7/0.4、fail-open 契约、默认关的理由）集中到
+一处，调用侧只留一行接线。
+
+默认关（ARGO_ADAPTIVE_TAIL=1 开启）：理由是**本开关自己的**交错 A/B 未证实
+收益——2026-10-16 三轮对拍见
+docs-local/调度对拍_尾宽分层与并发_2026-10-16.md：墙钟有改善但统计不显著，
+按「调度旋钮的收益必须由 A/B 证明后才转默认开」的规矩保持关闭。
+别拿 ARGO_ADAPTIVE_GRACE 的现状作类比：那个 2026-10-19（c52b7d4）已转默认
+开，两者的 A/B 结论不同，各自独立判断。
+"""
+
+from __future__ import annotations
+
+__all__ = ["straggler_tail"]
+
+
+def straggler_tail(engine: str, base: float) -> float:
+    """尾宽按 backup 引擎历史 P75 分层（ARGO_ADAPTIVE_TAIL 覆盖，默认关）。
+
+    固定 1.5s 尾宽对一切 backup 一视同仁，而 backup 的 P75 差异极大：
+    redskill 236ms、eastmoney 258ms 这类等 1.5s 几乎必到（耐心有回报），
+    anysearch P75 2.6s 等 1.5s 只有约五成概率——等不到就是纯墙钟。消融实测
+    （2026-10-15，ARGO_STRAGGLER_GRACE_S 1.5 → 0.5 → 0）：样本墙钟
+    2581 → 2260 → 1873ms（-12% / -27%），证明尾宽是有效杠杆且当前值是
+    拍的常数。分层让「值得等的等满、不值得等的早收工」：
+      P75 ≤ ½·base（快源）  → base       尾窗内几乎必到，等满不损质量
+      ½·base < P75 ≤ 1.5·base → 0.7·base 中速略收
+      P75 > 1.5·base（慢源） → 0.4·base（下限 0.3s）大概率白等，早收工
+
+    P75 取 adaptive.latency_percentile（7 天窗、仅 success 且非空交付，
+    与 engine_dispatch._adaptive_grace 同源同口径）；样本不足/过时/任何
+    异常 → 原样返回 base（fail-open，观测层不阻断调度主路径）。
+    """
+    if base <= 0 or not engine:
+        return base
+    try:
+        from engine_env import env_flag
+        if not env_flag("ARGO_ADAPTIVE_TAIL", False):
+            return base
+    except Exception:
+        return base
+    try:
+        from adaptive import get_learner
+        p75_ms = get_learner().latency_percentile(engine, 0.75)
+    except Exception:
+        return base
+    if not p75_ms or p75_ms <= 0:
+        return base
+    p75 = float(p75_ms) / 1000.0
+    if p75 <= base * 0.5:
+        return base
+    if p75 <= base * 1.5:
+        return base * 0.7
+    return max(0.3, base * 0.4)

package/scripts/stylometry_detector.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""stylometry_detector.py — 文体特征检测器
+
+基于 EMNLP 2019 论文《The Limitations of Stylometry for Detecting
+Machine-Generated Fake News》的文体特征方法，识别 AI 生成/内容农场文本。
+
+核心思想：
+  AI 生成文本与人类写作在文体特征上有显著差异：
+  - 词汇丰富度（Type-Token Ratio）：AI 文本词汇多样性低
+  - 句长分布：AI 文本句长方差小（过于均匀）
+  - 标点使用模式：AI 文本标点使用过于规范
+  - 功能词频率：AI 文本功能词（the/is/and）频率异常
+  - 重复 n-gram 比例：AI 文本重复模式多
+
+设计原则：
+  - 纯 stdlib，零依赖，微秒级
+  - 与 content_signals 集成，作为低质内容检测的补充信号
+  - 输出 0-1 分数，越高越像 AI 生成
+
+参考文献：
+  - Shu et al. "The Limitations of Stylometry for Detecting Machine-Generated
+    Fake News" EMNLP 2019
+  - NewsGuard + Pangram Labs AI Content Farm Detection (2025)
+"""
+from __future__ import annotations
+
+import re
+import math
+from typing import Any
+
+
+# ── 常量 ────────────────────────────────────────────────────────────
+
+# 功能词列表（中英文）
+_FUNCTION_WORDS = frozenset([
+    # 英文功能词
+    "the", "be", "to", "of", "and", "a", "in", "that", "have", "i",
+    "it", "for", "not", "on", "with", "he", "as", "you", "do", "at",
+    "this", "but", "his", "by", "from", "they", "we", "say", "her", "she",
+    "or", "an", "will", "my", "one", "all", "would", "there", "their",
+    "what", "so", "up", "out", "if", "about", "who", "get", "which", "go",
+    "me", "when", "make", "can", "like", "time", "no", "just", "him", "know",
+    "take", "people", "into", "year", "your", "good", "some", "could", "them",
+    "see", "other", "than", "then", "now", "look", "only", "come", "its", "over",
+    "think", "also", "back", "after", "use", "two", "how", "our", "work",
+    "first", "well", "way", "even", "new", "want", "because", "any", "these",
+    "give", "day", "most", "us",
+    # 中文功能词
+    "的", "了", "在", "是", "我", "有", "和", "就", "不", "人", "都", "一",
+    "一个", "上", "也", "很", "到", "说", "要", "去", "你", "会", "着",
+    "没有", "看", "好", "自己", "这", "他", "她", "它", "们", "那", "些",
+    "什么", "怎么", "为什么", "多少", "几", "谁", "哪", "哪个", "哪些",
+])
+
+# 模板词（AI 生成文本高频）
+_TEMPLATE_WORDS = frozenset([
+    "综上所述", "值得注意的是", "总而言之", "首先", "其次", "最后",
+    "in conclusion", "it is worth noting", "in summary", "firstly", "secondly",
+    "moreover", "furthermore", "additionally", "consequently", "therefore",
+    "nevertheless", "nonetheless", "in addition", "as a result", "in fact",
+])
+
+# 句子分割模式
+_SENTENCE_RE = re.compile(r'[.!?。！？]+')
+# 单词分割
+_WORD_RE = re.compile(r'[a-zA-Z]+|\u4e00-\u9fff')
+
+
+def _split_sentences(text: str) -> list[str]:
+    """分割句子"""
+    if not text:
+        return []
+    parts = _SENTENCE_RE.split(text)
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _tokenize(text: str) -> list[str]:
+    """分词（中英文混合）"""
+    if not text:
+        return []
+    return _WORD_RE.findall(text.lower())
+
+
+def _variance(data: list[float]) -> float:
+    """计算方差"""
+    if len(data) < 2:
+        return 0.0
+    mean = sum(data) / len(data)
+    return sum((x - mean) ** 2 for x in data) / len(data)
+
+
+def _quantile(data: list[float], q: float) -> float:
+    """计算分位数"""
+    if not data:
+        return 0.0
+    sorted_data = sorted(data)
+    idx = int(len(sorted_data) * q)
+    return sorted_data[min(idx, len(sorted_data) - 1)]
+
+
+class StylometryDetector:
+    """文体特征检测器 — 识别 AI 生成/内容农场文本"""
+
+    def extract_features(self, text: str) -> dict[str, float]:
+        """提取文体特征
+
+        返回:
+            type_token_ratio: 词汇丰富度（0-1，越高越丰富）
+            sentence_length_variance: 句长方差（越大越自然）
+            punctuation_density: 标点密度
+            function_word_ratio: 功能词比例
+            repeated_ngram_ratio: 重复 n-gram 比例
+            template_word_ratio: 模板词比例
+        """
+        if not text or len(text.strip()) < 10:
+            return {
+                "type_token_ratio": 0.0,
+                "sentence_length_variance": 0.0,
+                "punctuation_density": 0.0,
+                "function_word_ratio": 0.0,
+                "repeated_ngram_ratio": 0.0,
+                "template_word_ratio": 0.0,
+            }
+
+        sentences = _split_sentences(text)
+        words = _tokenize(text)
+
+        # 1. 词汇丰富度（Type-Token Ratio）
+        unique_words = len(set(words))
+        total_words = len(words)
+        type_token_ratio = unique_words / max(total_words, 1)
+
+        # 2. 句长方差（AI 文本方差小）
+        sentence_lengths = [len(s) for s in sentences]
+        sentence_length_variance = _variance(sentence_lengths)
+
+        # 3. 标点密度
+        punctuation_count = text.count(',') + text.count('，') + text.count('、')
+        punctuation_density = punctuation_count / max(len(text), 1)
+
+        # 4. 功能词比例
+        function_word_count = sum(1 for w in words if w in _FUNCTION_WORDS)
+        function_word_ratio = function_word_count / max(total_words, 1)
+
+        # 5. 重复 n-gram 比例（3-gram）
+        repeated_ngram_ratio = self._repeated_ngram_ratio(words, n=3)
+
+        # 6. 模板词比例
+        template_word_count = sum(1 for w in words if w in _TEMPLATE_WORDS)
+        template_word_ratio = template_word_count / max(total_words, 1)
+
+        return {
+            "type_token_ratio": round(type_token_ratio, 4),
+            "sentence_length_variance": round(sentence_length_variance, 2),
+            "punctuation_density": round(punctuation_density, 4),
+            "function_word_ratio": round(function_word_ratio, 4),
+            "repeated_ngram_ratio": round(repeated_ngram_ratio, 4),
+            "template_word_ratio": round(template_word_ratio, 4),
+        }
+
+    def _repeated_ngram_ratio(self, words: list[str], n: int = 3) -> float:
+        """计算重复 n-gram 比例"""
+        if len(words) < n:
+            return 0.0
+        ngrams = [tuple(words[i:i+n]) for i in range(len(words) - n + 1)]
+        unique_ngrams = len(set(ngrams))
+        total_ngrams = len(ngrams)
+        if total_ngrams == 0:
+            return 0.0
+        return 1.0 - (unique_ngrams / total_ngrams)
+
+    def score(self, text: str) -> dict[str, Any]:
+        """计算文体异常分数
+
+        返回:
+            score: 0-1，越高越像 AI 生成
+            features: 原始特征
+            is_suspicious: 是否可疑（score > 0.6）
+        """
+        if not text or len(text.strip()) < 20:
+            return {
+                "score": 0.0,
+                "features": {},
+                "is_suspicious": False,
+            }
+
+        features = self.extract_features(text)
+
+        # 基于数据分析的权重设计
+        # 实测数据：
+        #   AI 文本：TTR=0.17-0.55, Var=38-61, Rep=0.03-0.75, Tpl=0.04-0.06
+        #   人类文本：TTR=0.50-0.87, Var=106-875, Rep=0.00, Tpl=0.01-0.02
+        #   内容农场：TTR=0.37, Var=312, Rep=0.32, Tpl=0.04
+
+        # 1. 句长方差（区分度最高：AI=38-61, Human=106-875）
+        #    AI 文本方差通常 < 100，人类文本 > 100
+        variance_score = 1.0 - min(features["sentence_length_variance"] / 100, 1.0)
+
+        # 2. 词汇丰富度（区分度低，因为中文人类 TTR 也低）
+        #    仅当 TTR < 0.3 时才算异常（AI 生成中文 TTR=0.17）
+        lexical_score = max(0, 1.0 - features["type_token_ratio"] / 0.3)
+
+        # 3. 模板词比例（区分度高：AI=0.04-0.06, Human=0.01-0.02）
+        template_score = min(max(features["template_word_ratio"] - 0.02, 0) / 0.02, 1.0)
+
+        # 4. 功能词比例（区分度低，作为辅助信号）
+        function_score = max(0, (0.38 - features["function_word_ratio"]) / 0.08)
+
+        # 5. 重复 n-gram 比例（区分度最高：AI=0.03-0.75, Human=0.00）
+        repetition_score = min(features["repeated_ngram_ratio"] * 2, 1.0)
+
+        # 加权组合（重复 n-gram 和句长方差是强信号）
+        score = (
+            variance_score * 0.25 +
+            lexical_score * 0.15 +
+            template_score * 0.20 +
+            function_score * 0.10 +
+            repetition_score * 0.30
+        )
+
+        return {
+            "score": round(min(score, 1.0), 3),
+            "features": features,
+            "is_suspicious": score > 0.35,
+        }
+
+
+def detect_ai_generated(text: str) -> dict[str, Any]:
+    """便捷函数：检测文本是否 AI 生成"""
+    detector = StylometryDetector()
+    return detector.score(text)