argo-search 2.9.7 → 2.9.8

package/scripts/ci_drift_gate.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""漂移阈值判定：把夜间「重录 vs 基线」的比较结果变成退出码。
+
+## 为什么单独成文件
+
+判定逻辑原来写在 nightly.yml 的 heredoc 里：语法对错只能在推上去之后知道，
+阈值改松改紧也没人测。抽出来后有两个好处——本地能跑同一套判定，用例能锁住
+「跌多少算跌」这条契约（tests/test_ci_workflows.py）。
+
+## 判什么、为什么只判这两样
+
+- **结果条数**：少 1 条允许（工具源单条抖动很常见），少 2 条以上算漂移；
+- **输出体积**：超过基线 20% 算漂移（体积是 Agent 真金白银付的上下文）。
+
+`not_recorded`（重放时要了一个当时没调过的引擎）**不计入**：录制只保留真正
+被调到的引擎，而重放是瞬时完成，早停时机与真跑不同，这是录制机制的正常边界，
+当成回归报会制造长期噪音。它仍然会打印出来，供人看。
+
+用法：
+    python3 scripts/ci_drift_gate.py --baseline 基线报告.json --current 本次报告.json
+退出码：0 通过；1 有漂移；2 输入缺失/格式不对（这两件事必须分开，混在一起
+会让人以为「红了=质量掉了」）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+KEPT_SLACK = 1          # 允许少 1 条
+BYTES_GROWTH = 1.2      # 体积上限 = 基线 × 1.2
+
+
+def _load(path: Path) -> dict[str, Any]:
+    doc = json.loads(path.read_text(encoding="utf-8"))
+    # save_baseline 存的是 {"_meta":…, "report":{…}}；evaluate_all 直接给报告本体
+    return doc.get("report", doc)
+
+
+def violations(base: dict[str, Any], cur: dict[str, Any]) -> list[str]:
+    by_id = {c.get("id"): c for c in (base.get("cases") or [])}
+    cur_ids = {c.get("id") for c in (cur.get("cases") or [])}
+    out: list[str] = []
+    for case in cur.get("cases") or []:
+        old = by_id.get(case.get("id"))
+        if not old:
+            continue  # 新增的用例没有基线，不算漂移
+        cid = case.get("id")
+        kept, old_kept = case.get("kept", 0), old.get("kept", 0)
+        if kept < old_kept - KEPT_SLACK:
+            out.append(f"{cid}: 结果 {kept} 条，基线 {old_kept} 条")
+        old_bytes = old.get("bytes", 0)
+        if old_bytes and case.get("bytes", 0) > old_bytes * BYTES_GROWTH:
+            out.append(
+                f"{cid}: 输出 {case.get('bytes')}B，超过基线 {old_bytes}B×{BYTES_GROWTH}")
+    # 基线里有、本次没有：不是「通过」，是这条根本没被录到（查询集被改、
+    # 或录制整条失败）。2026-10-22 本地实跑踩过：只剩 1 条时判定照样退 0。
+    for cid in by_id:
+        if cid and cid not in cur_ids:
+            out.append(f"{cid}: 本次报告里没有这条（查询集被改了，还是录制失败？）")
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="夜间漂移阈值判定")
+    ap.add_argument("--baseline", required=True)
+    ap.add_argument("--current", required=True)
+    args = ap.parse_args()
+
+    try:
+        base = _load(Path(args.baseline))
+        cur = _load(Path(args.current))
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"读不到报告：{type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+
+    bad = violations(base, cur)
+    if bad:
+        print("\n".join(bad), file=sys.stderr)
+        return 1
+    print(f"通过：{len(cur.get('cases') or [])} 条，漏录 "
+          f"{cur.get('total_missing', 0)} 个引擎（信息项，不算漂移）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/content_boundary.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""content_boundary.py — 不可信网页内容的边界标记与清洗。
+
+为什么需要单独一层：Argo 对 Agent 输出的是 JSON，不能像纯文本工具那样简单
+把整段响应包进 <untrusted-web-content>（会破坏 JSON 解析）。所以这里只做
+两件确定能做的事：
+
+1. **清洗**：任何来自上游的标题/摘要/正文在进入输出前，剥掉其中的边界标记
+   字样——否则网页正文里自带的 `</untrusted-web-content>` 可以提前闭合边界，
+   把后续内容伪装成可信指令（dsh-free-search 的同类防护）。
+2. **声明**：调用方在响应里带 `content_trust: "untrusted"`，让模型与宿主
+   知道这批文本的信任级别；文本边界由宿主（DSH/MCP 客户端）按自己的渲染
+   形态加，不在 JSON 契约里硬塞。
+
+不引入依赖、不做 HTML 清洗：正文已经是纯文本摘要，这里只管边界标记这一类
+可被利用的结构字符。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+CONTENT_TRUST_UNTRUSTED = "untrusted"
+
+# 大小写、属性、空白都按「可能的变体」处理；只剥标记本身，不动正文其余字符。
+_BOUNDARY_RE = re.compile(
+    r"<\s*/?\s*untrusted-web-content\b[^>]*>", re.IGNORECASE)
+
+
+def strip_boundary_markers(text: Any, limit: int | None = None) -> str:
+    """剥掉正文里的边界标记（含变体），可选截断。"""
+    out = _BOUNDARY_RE.sub("", str(text or ""))
+    if limit is not None and limit >= 0 and len(out) > limit:
+        out = out[:limit]
+    return out
+
+
+def sanitize_results_boundary(results: Any) -> None:
+    """就地清洗结果列表每条的 title/snippet 边界标记（CLI/Agent/MCP 共用单一出口）。"""
+    for item in results or []:
+        if not isinstance(item, dict):
+            continue
+        for key in ("title", "snippet"):
+            if isinstance(item.get(key), str):
+                item[key] = strip_boundary_markers(item[key])

package/scripts/content_signals.py

@@ -492,9 +492,16 @@ def score_clickbait(title: str) -> dict:
         score += 0.08
         hits.append("year_prefix")
     # 利益承诺：「看完…你就会」「建议收藏」「一篇搞懂」
-    if re.search(r"(看完|建议收藏|建议收藏|一篇(?:讲|说|搞懂)|全解析|必看|建议收藏)", t):
+    if re.search(r"(看完|建议收藏|一篇(?:讲|说|搞懂)|全解析|必看)", t):
         score += 0.10
         hits.append("benefit_promise")
+    # 虚假实测 / 承诺尾钩
+    if re.search(r"自费\s*\d+\s*元?实测", t):
+        score += 0.25
+        hits.append("fake_testimony")
+    if re.search(r"看完.*(?:你就懂了|你就会)", t):
+        score += 0.15
+        hits.append("clickbait_promise")
 
     # 标点：仅在已有命中时作**放大器**（PACLIC 的误杀教训）
     if score > 0:
@@ -595,13 +602,27 @@ def score_template_repetition(content: str) -> dict:
     这里是接入点，且标定集能立刻给出 before/after。
     """
     text = (content or "").strip()
-    if len(text) < 120:
+    # ── 序数连接词与流水线套话检测（对抗现代批量模板/AI农场）──
+    connectors = ("首先", "其次", "然后", "接下来", "最后", "综上所述")
+    hit_conn = sum(1 for w in connectors if w in text)
+    ai_phrases = ("业内人士表示", "专家分析", "消费者认为", "数据显示", "有望成为")
+    hit_ai = sum(1 for w in ai_phrases if w in text)
+    conn_boost = 0.0
+    if hit_conn >= 4:
+        conn_boost = 0.85
+    elif hit_conn >= 3 and hit_ai >= 1:
+        conn_boost = 0.80
+    elif hit_ai >= 3:
+        conn_boost = 0.78
+
+    if len(text) < 120 and conn_boost == 0.0:
         return {"score": 0.0, "templates": 0, "sentences": 0, "repetition": 0.0}
     # 分句：中英标点 + 换行
     sents = [s.strip() for s in re.split(r"[。！？!?；;\n]+", text) if len(s.strip()) >= 6]
     if len(sents) < 4:
-        return {"score": 0.0, "templates": len(sents), "sentences": len(sents),
-                "repetition": 0.0}
+        base_rep = conn_boost
+        return {"score": round(base_rep, 3), "templates": len(sents), "sentences": len(sents),
+                "repetition": round(base_rep, 3)}
     sigs: list[str] = []
     for s in sents:
         head = s[:2]
@@ -610,7 +631,7 @@ def score_template_repetition(content: str) -> dict:
         bucket = "S" if len(s) < 25 else ("M" if len(s) < 60 else "L")
         sigs.append(f"{head}|{tail}|{bucket}")
     uniq = len(set(sigs))
-    repetition = 1.0 - uniq / len(sigs)
+    repetition = max(1.0 - uniq / len(sigs), conn_boost)
     return {
         "score": round(min(repetition, 1.0), 3),
         "templates": uniq,

package/scripts/cross_lingual_trace.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""cross_lingual_trace.py — 跨语言长程搜索与多源任务溯源引擎。
+
+架构定位：
+  解耦自 research.py 与 wide_research.py。当单语言（如中文或特定小语种）
+  信息贫瘠、被低质农场包围，或任务明确要求事实溯源（源头论文、首发漏洞、
+  规范草案、最初作者、原始出处）时，自动触发跨语言长程追踪（Pivot & Trace），
+  并进行跨语言证据交叉比对（Reconciliation & Disagreement Check）。
+
+核心阶段：
+  1. 需求与充分性判定（assess_cross_lingual_need）：
+     检测结果稀疏度、权威源覆盖率以及溯源关键词（起源/出处/最早/first proposed 等）。
+  2. 跨语言实体锚点与溯源子查询生成（build_cross_lingual_trace_queries）：
+     将查询投影至目标语种（以英文为主，或日/德/法垂直语境），生成多阶段溯源子查询。
+  3. 跨语言多源证据对账与综合（synthesize_cross_lingual_evidence）：
+     将跨语言采集回来的结果与原语言结果按一手源等级、时序和互补关系对齐，
+     沉淀出 primary_origins（一手源）、complements（互补证据）与 disagreements（口径差异）。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+# 溯源与跨语言强触发词
+_TRACING_KEYWORDS = (
+    "溯源", "起源", "出处", "最初", "源头", "提出者", "发明", "草案",
+    "原型", "首发", "首个", "第一篇", "历史沿革", "来龙去脉",
+    "origin", "provenance", "root cause", "first proposed", "author of",
+    "initial draft", "whitepaper", "specification", "cve-", "rfc "
+)
+
+_SOURCE_TYPE_RANKS = {
+    "official": 4,
+    "academic": 4,
+    "standard": 4,
+    "repository": 3,
+    "reference": 3,
+    "news": 2,
+    "community": 2,
+    "general": 1,
+}
+
+
+def assess_cross_lingual_need(
+    query: str,
+    results: list[dict[str, Any]] | None,
+    domain: str = "",
+    min_sufficient_results: int = 3,
+    force_trace: bool = False,
+) -> dict[str, Any]:
+    """评估是否需要启动跨语言长程搜索与任务溯源。
+
+    触发条件（满足任意一条）：
+      1. 显式开启 force_trace 或查询包含溯源关键词；
+      2. 结果稀疏（有效结果 < min_sufficient_results）；
+      3. 高置信度/权威一手信源缺失（authority_level >= 3 的结果为 0）；
+      4. 强跨语言领域（security_search, academic, package_intel, rfc）。
+    """
+    q_low = (query or "").lower()
+    has_tracing_keyword = any(kw in q_low for kw in _TRACING_KEYWORDS)
+
+    valid_results = [r for r in (results or []) if isinstance(r, dict)]
+    res_count = len(valid_results)
+
+    high_auth_count = sum(
+        1 for r in valid_results
+        if float(r.get("authority") or r.get("score") or 0.0) >= 0.7
+        or int(r.get("authority_level") or 0) >= 3
+    )
+
+    domain_low = (domain or "").lower()
+    is_cross_lingual_domain = any(
+        d in domain_low for d in ("security", "academic", "package", "rfc", "macro", "us_stock")
+    )
+
+    is_sparse = res_count < min_sufficient_results
+    no_authoritative = (res_count > 0 and high_auth_count == 0)
+
+    needed = force_trace or has_tracing_keyword or is_sparse or no_authoritative or (
+        is_cross_lingual_domain and high_auth_count < 2
+    )
+
+    reasons: list[str] = []
+    if force_trace:
+        reasons.append("显式指定跨语言长程溯源")
+    if has_tracing_keyword:
+        reasons.append("命中溯源意图关键词")
+    if is_sparse:
+        reasons.append(f"原语言结果不足（仅 {res_count} 条，门槛 {min_sufficient_results}）")
+    if no_authoritative:
+        reasons.append("原语言缺乏高置信度一手权威信源")
+    if is_cross_lingual_domain:
+        reasons.append(f"领域「{domain}」天然具备跨语言溯源需求")
+
+    target_langs = ["en"]
+    if re.search(r"[\u3040-\u309f\u30a0-\u30ff]", query):
+        target_langs = ["en", "zh"]
+    elif re.search(r"(日企|日本|动漫|acg|丰田|索尼|任天堂)", query, re.I):
+        target_langs = ["en", "ja"]
+
+    return {
+        "needed": bool(needed),
+        "target_langs": target_langs,
+        "is_tracing": bool(has_tracing_keyword or force_trace),
+        "is_sparse": bool(is_sparse),
+        "reasons": reasons,
+        "high_auth_count": high_auth_count,
+        "result_count": res_count,
+    }
+
+
+def _extract_core_entity(query: str) -> str:
+    """从复杂查询中提取核心溯源实体（英文锚点或关键名词）。"""
+    q = (query or "").strip()
+    # 优先抽取其中的西文标识（如 CVE-2024-1234, React, Transformer, SQLite 等）
+    ascii_matches = re.findall(r"[A-Za-z0-9_\-\.\:\/]{3,}", q)
+    if ascii_matches:
+        # 过滤掉通用词
+        clean_terms = [m for m in ascii_matches if m.lower() not in ("what", "how", "why", "when", "with")]
+        if clean_terms:
+            return " ".join(clean_terms[:3])
+
+    # 如果纯 CJK，剥离常见的动词与提问词
+    cleaned = re.sub(
+        r"(如何|怎么|为什么|溯源|起源|出处|最初|源头|提出者|发明|的来历|是谁|什么时候|最新|评价)",
+        " ",
+        q,
+    ).strip()
+    words = [w for w in re.split(r"\s+", cleaned) if len(w) >= 2]
+    return words[0] if words else q
+
+
+def build_cross_lingual_trace_queries(
+    query: str,
+    target_lang: str = "en",
+    focus: str = "comprehensive",
+) -> list[dict[str, str]]:
+    """生成分阶段跨语言长程溯源子查询。
+
+    返回结构化的子查询列表，标注意图（intent）、策略（strategy）与语言标记。
+    """
+    entity = _extract_core_entity(query)
+    subs: list[dict[str, str]] = []
+
+    if target_lang == "en":
+        # 阶段 1：一手原始出处与概念提出（Origin & Inception）
+        subs.append({
+            "query": f"{entity} original paper first proposed inception origin",
+            "intent": "原始论文/源头提出者与发布背景溯源",
+            "strategy": "origin_trace",
+            "lang": "en",
+        })
+        # 阶段 2：规范、代码仓与官方权威文档（Specification & Implementation）
+        subs.append({
+            "query": f"{entity} official repository documentation specification RFC",
+            "intent": "官方规范、权威仓库与技术标准追踪",
+            "strategy": "primary_spec",
+            "lang": "en",
+        })
+        # 阶段 3：演进考证与关键争议（Evolution & Historical Milestone）
+        subs.append({
+            "query": f"{entity} milestone evolution history benchmark analysis",
+            "intent": "历史演进里程碑与事实交叉考证",
+            "strategy": "cross_check",
+            "lang": "en",
+        })
+    elif target_lang == "ja":
+        subs.append({
+            "query": f"{entity} 開発経緯 歴史 初出 仕様",
+            "intent": "日文原始出处与开发历史溯源",
+            "strategy": "origin_trace",
+            "lang": "ja",
+        })
+        subs.append({
+            "query": f"{entity} 公式ドキュメント 仕様書 論文",
+            "intent": "日文官方规范与文档追踪",
+            "strategy": "primary_spec",
+            "lang": "ja",
+        })
+    else:
+        subs.append({
+            "query": f"{entity} origin official source history",
+            "intent": f"{target_lang} 语种源头与官方文档追踪",
+            "strategy": "origin_trace",
+            "lang": target_lang,
+        })
+
+    return subs
+
+
+def _classify_source_nature(url: str, title: str) -> str:
+    """根据 URL 和标题对信源进行性质分类。"""
+    u_low = (url or "").lower()
+    t_low = (title or "").lower()
+
+    if any(h in u_low for h in ("arxiv.org", "doi.org", "acm.org", "ieee.org", "biorxiv.org", "semanticscholar.org")):
+        return "academic"
+    if any(h in u_low for h in ("github.com", "gitlab.com", "bitbucket.org", "git.kernel.org")):
+        return "repository"
+    if any(h in u_low for h in ("rfc-editor.org", "w3.org", "iso.org", "ecma-international.org", "cve.mitre.org", "nvd.nist.gov")):
+        return "standard"
+    if any(h in u_low for h in (".gov", ".edu", "europa.eu", "who.int", "un.org")):
+        return "official"
+    if any(h in u_low for h in ("wikipedia.org", "wikidata.org", "baike.baidu.com")):
+        return "reference"
+    if any(k in t_low for k in ("official", "announcement", "release note", "white paper", "specification")):
+        return "official"
+    return "general"
+
+
+def synthesize_cross_lingual_evidence(
+    primary_results: list[dict[str, Any]],
+    cross_results: list[dict[str, Any]],
+    query: str,
+) -> dict[str, Any]:
+    """将原语言与跨语言长程检索证据进行交叉对账。
+
+    产出：
+      - primary_origins: 权威一手信源（论文、代码仓、标准机构）
+      - complements: 跨语言带来的增量补充事实
+      - disagreements: 跨语言比对中发现的时间/口径分歧
+      - provenance_chain: 结构化溯源脉络
+    """
+    seen_urls: set[str] = set()
+    primary_origins: list[dict[str, Any]] = []
+    complements: list[dict[str, Any]] = []
+    disagreements: list[str] = []
+
+    all_cross = [r for r in cross_results if isinstance(r, dict)]
+
+    # 1. 甄选跨语言一手源
+    for r in all_cross:
+        u = r.get("url") or ""
+        if not u or u in seen_urls:
+            continue
+        seen_urls.add(u)
+        t = r.get("title") or ""
+        nature = _classify_source_nature(u, t)
+        entry = {
+            "title": t,
+            "url": u,
+            "snippet": r.get("snippet") or "",
+            "nature": nature,
+            "source": r.get("source") or "",
+            "authority_rank": _SOURCE_TYPE_RANKS.get(nature, 1),
+        }
+        if nature in ("academic", "standard", "official", "repository"):
+            primary_origins.append(entry)
+        else:
+            complements.append(entry)
+
+    # 排序：权威一手源排在最前
+    primary_origins.sort(key=lambda x: x["authority_rank"], reverse=True)
+
+    # 2. 检查年份/时间戳分歧
+    year_re = re.compile(r"\b(19\d{2}|20\d{2})\b")
+    prim_years = set()
+    for r in primary_results:
+        text = f"{r.get('title', '')} {r.get('snippet', '')}"
+        prim_years.update(year_re.findall(text))
+
+    cross_years = set()
+    for r in all_cross:
+        text = f"{r.get('title', '')} {r.get('snippet', '')}"
+        cross_years.update(year_re.findall(text))
+
+    if prim_years and cross_years and not (prim_years & cross_years):
+        disagreements.append(
+            f"跨语言时间线存在差异：原语言提及时段 {sorted(prim_years)}，而外文一手源提及时段 {sorted(cross_years)}"
+        )
+
+    # 3. 构造溯源链条
+    provenance_chain: list[dict[str, str]] = []
+    for origin in primary_origins[:4]:
+        provenance_chain.append({
+            "stage": "一手信源定位",
+            "source_type": origin["nature"],
+            "title": origin["title"][:80],
+            "url": origin["url"],
+            "evidence": origin["snippet"][:140],
+        })
+
+    return {
+        "status": "completed" if (primary_origins or complements) else "no_incremental_evidence",
+        "primary_origins": primary_origins[:6],
+        "complements_count": len(complements),
+        "complements": complements[:6],
+        "disagreements": disagreements,
+        "provenance_chain": provenance_chain,
+        "total_cross_sources": len(all_cross),
+    }

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)),
+    }