codebee 0.1.69 → 0.1.71

package/app/core/dispatch.py

@@ -1,173 +1,190 @@
-# -*- coding: utf-8 -*-
-"""统一调度评分：任务画像、CLI 亲和度与模型链排序。
-
-调用方先完成协议、启停、健康、密钥等硬约束过滤，再把可用候选交给这里评分；
-静态能力与近期用量台账只提供软信号，相同分数保持用户原顺序。
-"""
-from __future__ import annotations
-
-import math
-
-
-TYPE_DIMENSIONS = {
-    "direct": "reasoning",
-    "code": "coding",
-    "novel": "writing",
-    "serial_novel": "writing",
-    "article": "writing",
-    "video_script": "writing",
-    "doc": "writing",
-    "translation": "writing",
-    "rank_scan": "reasoning",
-    "research": "reasoning",
-    "speech": "writing",
-    "weekly_report": "writing",
-    "email": "writing",
-    "tech_proposal": "reasoning",
-    "resume": "writing",
-    "bid_doc": "writing",   # 标书：正文应答写作量大（合规判断由契约规则约束）
-    "zentao": "coding",
-}
-
-_KIND_AFFINITY = {
-    "coding": {"codex": 10, "aider": 8, "opencode": 7, "qwen": 6,
-               "claude": 5, "generic": 2},
-    "writing": {"claude": 10, "qwen": 7, "generic": 5, "codex": 3,
-                "opencode": 2, "aider": 0},
-    "reasoning": {"claude": 9, "codex": 8, "qwen": 6, "opencode": 4,
-                  "generic": 3, "aider": 1},
-    "vision": {"codex": 10, "claude": 8, "qwen": 5, "opencode": 2,
-               "generic": 1, "aider": 0},
-}
-
-_TIER_SCORE = {
-    "easy": {"budget": 18.0, "standard": 8.0, "premium": -6.0},
-    "default": {"budget": 2.0, "standard": 6.0, "premium": 5.0},
-    "hard": {"budget": -8.0, "standard": 4.0, "premium": 12.0},
-}
-
-
-def task_dimension(task_type, role=""):
-    """把预置任务与步骤角色归一为 writing/coding/reasoning/vision。"""
-    ttype = str(task_type or "").strip().lower()
-    role = str(role or "").strip().lower()
-    if ttype in ("writing", "coding", "reasoning", "vision"):
-        return ttype
-    if role in ("plan", "review", "critique", "selector", "qa") \
-            or "review" in role or "critique" in role:
-        return "reasoning"
-    return TYPE_DIMENSIONS.get(ttype, "reasoning")
-
-
-def agent_affinity(kind, task_type, role=""):
-    """CLI 类型对任务维度的温和偏好；只作加分，不覆盖健康与历史信号。"""
-    dim = task_dimension(task_type, role)
-    score = float((_KIND_AFFINITY.get(dim) or {}).get(kind, 0))
-    if role == "review" or "critique" in str(role or ""):
-        score += {"claude": 4, "codex": 3, "qwen": 2}.get(kind, 0)
-    return score, "%s 匹配 %+.1f" % (dim, score)
-
-
-def _model_meta(provider, model):
-    for item in (provider or {}).get("models") or []:
-        if isinstance(item, dict) and item.get("name") == model:
-            return item
-    return {}
-
-
-def _price_score(pricing, model, difficulty):
-    price = (pricing or {}).get(model) or {}
-    try:
-        # 输出通常比输入贵且更影响整步成本，按 2 倍权重估算。
-        blended = max(0.0, float(price.get("in") or 0.0)
-                      + 2.0 * float(price.get("out") or 0.0))
-    except (TypeError, ValueError):
-        return 0.0, "价格未知"
-    if blended <= 0:
-        return 0.0, "价格未知"
-    magnitude = max(0.0, math.log10(blended + 1.0))
-    score = -min(18.0, magnitude * (7.0 if difficulty == "easy" else 2.0))
-    return score, "估算价 %.3g（%+.1f）" % (blended, score)
-
-
-def _online_model_bonus(entry, task_type, role):
-    """把真实运行指标作为模型链软信号，硬约束仍由调用方负责。"""
-    try:
-        from . import usage
-        metrics = usage.routing_stats(
-            task_type=task_type, role=role,
-            provider=entry.get("provider_id") or "",
-            model=entry.get("model") or "")
-        samples = int(metrics.get("samples") or 0)
-        if not samples:
-            return 0.0, ""
-        rate = float(metrics.get("success_rate") or 0.0)
-        success_score = max(-6.0, min(6.0, (rate - 0.75) * 18.0))
-        p95 = max(0.0, float(metrics.get("p95_duration_s") or 0.0))
-        # 模型链也必须让真实延迟影响排序，不能让 P95 数分钟的链靠静态质量分
-        # 长期压在十几秒的健康链前面。
-        latency_score = -min(12.0, max(0.0, (p95 - 30.0) / 8.0))
-        cost = max(0.0, float(metrics.get("avg_cost_usd") or 0.0))
-        cost_score = -min(3.0, max(0.0, (cost - 0.01) / 0.01))
-        total = round(success_score + latency_score + cost_score, 2)
-        success_samples = int(metrics.get("success_samples") or samples)
-        reason = ("在线 %d/%d 验收成功（%+.1f），P95 %.1fs（%+.1f），均价 $%.4f（%+.1f）"
-                  % (int(metrics.get("successes") or 0), success_samples,
-                     success_score, p95, latency_score, cost, cost_score))
-        return total, reason
-    except Exception:
-        return 0.0, ""
-
-
-def score_model_entry(entry, providers, pricing, difficulty, task_type="", role=""):
-    """给已通过硬约束的模型链条目评分，返回 (score, explanation)。"""
-    provider = (providers or {}).get(entry.get("provider_id")) \
-        or entry.get("provider") or {}
-    model = entry.get("model") or ""
-    meta = _model_meta(provider, model)
-    try:
-        priority = max(1, int(meta.get("priority") or 99))
-    except (TypeError, ValueError):
-        priority = 99
-    quality = 0.0 if priority == 99 else max(-8.0, 20.0 - (priority - 1) * 4.0)
-    tier = meta.get("tier") or provider.get("tier") or "standard"
-    tier_score = (_TIER_SCORE.get(difficulty) or {}).get(tier, 0.0)
-    price_score, price_reason = _price_score(pricing, model, difficulty)
-    dim = task_dimension(task_type, role)
-    strengths = provider.get("strengths") if isinstance(provider.get("strengths"), list) else []
-    strength_score = 10.0 if dim in strengths else 0.0
-    if difficulty == "easy":
-        quality *= 0.25
-    elif difficulty != "hard":
-        # 普通任务兼顾质量、成本与能力匹配；是否真的重排由调用方决定，
-        # 因而手工链仍可保持原顺序，自动推荐则能使用这组平衡分。
-        quality *= 0.65
-    vision_score = 0.0
-    if dim == "vision":
-        vision_score = 24.0 if meta.get("image_in") else -24.0
-    online_score, online_reason = _online_model_bonus(entry, task_type, role)
-    total = quality + tier_score + price_score + strength_score + vision_score + online_score
-    reason = ("质量 %+.1f，档位 %s %+.1f，%s，能力 %s %+.1f%s%s"
-              % (quality, tier, tier_score, price_reason, dim,
-                 strength_score + vision_score,
-                 "，" if online_reason else "", online_reason))
-    return round(total, 2), reason
-
-
-def rank_model_entries(entries, providers, pricing, difficulty,
-                       task_type="", role="", force=False):
-    """稳定排序模型链并返回脱敏决策明细；default 难度保持人工顺序。"""
-    rows = []
-    for index, entry in enumerate(entries or []):
-        score, reason = score_model_entry(
-            entry, providers, pricing, difficulty, task_type, role)
-        rows.append((score, index, entry, reason))
-    if difficulty in ("easy", "hard") or force:
-        rows.sort(key=lambda row: (-row[0], row[1]))
-    ranked = [row[2] for row in rows]
-    decisions = [{"provider_id": row[2].get("provider_id") or "",
-                  "provider": (row[2].get("provider") or {}).get("name") or "",
-                  "model": row[2].get("model") or "",
-                  "score": row[0], "reason": row[3]}
-                 for row in rows]
-    return ranked, decisions
+# -*- coding: utf-8 -*-
+"""统一调度评分：任务画像、CLI 亲和度与模型链排序。
+
+调用方先完成协议、启停、健康、密钥等硬约束过滤，再把可用候选交给这里评分；
+静态能力与近期用量台账只提供软信号，相同分数保持用户原顺序。
+"""
+from __future__ import annotations
+
+import math
+
+
+TYPE_DIMENSIONS = {
+    "direct": "reasoning",
+    "code": "coding",
+    "novel": "writing",
+    "serial_novel": "writing",
+    "article": "writing",
+    "video_script": "writing",
+    "doc": "writing",
+    "translation": "writing",
+    "rank_scan": "reasoning",
+    "research": "reasoning",
+    "speech": "writing",
+    "weekly_report": "writing",
+    "email": "writing",
+    "tech_proposal": "reasoning",
+    "resume": "writing",
+    "bid_doc": "writing",   # 标书：正文应答写作量大（合规判断由契约规则约束）
+    "zentao": "coding",
+}
+
+_KIND_AFFINITY = {
+    "coding": {"codex": 10, "aider": 8, "opencode": 7, "qwen": 6,
+               "claude": 5, "generic": 2},
+    "writing": {"claude": 10, "qwen": 7, "generic": 5, "codex": 3,
+                "opencode": 2, "aider": 0},
+    "reasoning": {"claude": 9, "codex": 8, "qwen": 6, "opencode": 4,
+                  "generic": 3, "aider": 1},
+    "vision": {"codex": 10, "claude": 8, "qwen": 5, "opencode": 2,
+               "generic": 1, "aider": 0},
+}
+
+_TIER_SCORE = {
+    "easy": {"budget": 18.0, "standard": 8.0, "premium": -6.0},
+    "default": {"budget": 2.0, "standard": 6.0, "premium": 5.0},
+    "hard": {"budget": -8.0, "standard": 4.0, "premium": 12.0},
+}
+
+
+def task_dimension(task_type, role=""):
+    """把预置任务与步骤角色归一为 writing/coding/reasoning/vision。"""
+    ttype = str(task_type or "").strip().lower()
+    role = str(role or "").strip().lower()
+    if ttype in ("writing", "coding", "reasoning", "vision"):
+        return ttype
+    if role in ("plan", "review", "critique", "selector", "qa") \
+            or "review" in role or "critique" in role:
+        return "reasoning"
+    return TYPE_DIMENSIONS.get(ttype, "reasoning")
+
+
+def agent_affinity(kind, task_type, role=""):
+    """CLI 类型对任务维度的温和偏好；只作加分，不覆盖健康与历史信号。"""
+    dim = task_dimension(task_type, role)
+    score = float((_KIND_AFFINITY.get(dim) or {}).get(kind, 0))
+    if role == "review" or "critique" in str(role or ""):
+        score += {"claude": 4, "codex": 3, "qwen": 2}.get(kind, 0)
+    return score, "%s 匹配 %+.1f" % (dim, score)
+
+
+def _model_meta(provider, model):
+    for item in (provider or {}).get("models") or []:
+        if isinstance(item, dict) and item.get("name") == model:
+            return item
+    return {}
+
+
+def _price_score(pricing, model, difficulty):
+    price = (pricing or {}).get(model) or {}
+    try:
+        # 输出通常比输入贵且更影响整步成本，按 2 倍权重估算。
+        blended = max(0.0, float(price.get("in") or 0.0)
+                      + 2.0 * float(price.get("out") or 0.0))
+    except (TypeError, ValueError):
+        return 0.0, "价格未知"
+    if blended <= 0:
+        return 0.0, "价格未知"
+    magnitude = max(0.0, math.log10(blended + 1.0))
+    score = -min(18.0, magnitude * (7.0 if difficulty == "easy" else 2.0))
+    return score, "估算价 %.3g（%+.1f）" % (blended, score)
+
+
+def _online_model_bonus(entry, task_type, role):
+    """把真实运行指标作为模型链软信号，硬约束仍由调用方负责。"""
+    try:
+        from . import usage
+        metrics = usage.routing_stats(
+            task_type=task_type, role=role,
+            provider=entry.get("provider_id") or "",
+            model=entry.get("model") or "")
+        samples = int(metrics.get("samples") or 0)
+        if not samples:
+            return 0.0, ""
+        rate = float(metrics.get("success_rate") or 0.0)
+        success_score = max(-6.0, min(6.0, (rate - 0.75) * 18.0))
+        p95 = max(0.0, float(metrics.get("p95_duration_s") or 0.0))
+        # 模型链也必须让真实延迟影响排序，不能让 P95 数分钟的链靠静态质量分
+        # 长期压在十几秒的健康链前面。
+        latency_score = -min(12.0, max(0.0, (p95 - 30.0) / 8.0))
+        cost = max(0.0, float(metrics.get("avg_cost_usd") or 0.0))
+        cost_score = -min(3.0, max(0.0, (cost - 0.01) / 0.01))
+        total = round(success_score + latency_score + cost_score, 2)
+        success_samples = int(metrics.get("success_samples") or samples)
+        reason = ("在线 %d/%d 验收成功（%+.1f），P95 %.1fs（%+.1f），均价 $%.4f（%+.1f）"
+                  % (int(metrics.get("successes") or 0), success_samples,
+                     success_score, p95, latency_score, cost, cost_score))
+        return total, reason
+    except Exception:
+        return 0.0, ""
+
+
+def _bench_bonus(entry):
+    """评测基准台实测分软信号（promptfoo 式样题榜单；14 天新鲜度，过期记 0）。
+
+    与在线信号同理念：软加减分，硬约束（健康/冷却/协议）仍由调用方负责；
+    无数据不猜分——没上过评测台的候选保持原排序。
+    """
+    try:
+        from . import benchstore
+        return benchstore.bonus_for(entry.get("provider_id") or "",
+                                    entry.get("model") or "")
+    except Exception:
+        return 0.0, ""
+
+
+def score_model_entry(entry, providers, pricing, difficulty, task_type="", role=""):
+    """给已通过硬约束的模型链条目评分，返回 (score, explanation)。"""
+    provider = (providers or {}).get(entry.get("provider_id")) \
+        or entry.get("provider") or {}
+    model = entry.get("model") or ""
+    meta = _model_meta(provider, model)
+    try:
+        priority = max(1, int(meta.get("priority") or 99))
+    except (TypeError, ValueError):
+        priority = 99
+    quality = 0.0 if priority == 99 else max(-8.0, 20.0 - (priority - 1) * 4.0)
+    tier = meta.get("tier") or provider.get("tier") or "standard"
+    tier_score = (_TIER_SCORE.get(difficulty) or {}).get(tier, 0.0)
+    price_score, price_reason = _price_score(pricing, model, difficulty)
+    dim = task_dimension(task_type, role)
+    strengths = provider.get("strengths") if isinstance(provider.get("strengths"), list) else []
+    strength_score = 10.0 if dim in strengths else 0.0
+    if difficulty == "easy":
+        quality *= 0.25
+    elif difficulty != "hard":
+        # 普通任务兼顾质量、成本与能力匹配；是否真的重排由调用方决定，
+        # 因而手工链仍可保持原顺序，自动推荐则能使用这组平衡分。
+        quality *= 0.65
+    vision_score = 0.0
+    if dim == "vision":
+        vision_score = 24.0 if meta.get("image_in") else -24.0
+    online_score, online_reason = _online_model_bonus(entry, task_type, role)
+    bench_score, bench_reason = _bench_bonus(entry)
+    total = (quality + tier_score + price_score + strength_score + vision_score
+             + online_score + bench_score)
+    reason = ("质量 %+.1f，档位 %s %+.1f，%s，能力 %s %+.1f%s%s%s%s"
+              % (quality, tier, tier_score, price_reason, dim,
+                 strength_score + vision_score,
+                 "，" if online_reason else "", online_reason,
+                 "，" if bench_reason else "", bench_reason))
+    return round(total, 2), reason
+
+
+def rank_model_entries(entries, providers, pricing, difficulty,
+                       task_type="", role="", force=False):
+    """稳定排序模型链并返回脱敏决策明细；default 难度保持人工顺序。"""
+    rows = []
+    for index, entry in enumerate(entries or []):
+        score, reason = score_model_entry(
+            entry, providers, pricing, difficulty, task_type, role)
+        rows.append((score, index, entry, reason))
+    if difficulty in ("easy", "hard") or force:
+        rows.sort(key=lambda row: (-row[0], row[1]))
+    ranked = [row[2] for row in rows]
+    decisions = [{"provider_id": row[2].get("provider_id") or "",
+                  "provider": (row[2].get("provider") or {}).get("name") or "",
+                  "model": row[2].get("model") or "",
+                  "score": row[0], "reason": row[3]}
+                 for row in rows]
+    return ranked, decisions

package/app/core/dispatch_log.py

@@ -1,128 +1,128 @@
-# -*- coding: utf-8 -*-
-"""调度事件台账：记录脱敏的候选、决策和结果，支持按运行回放。"""
-from __future__ import annotations
-
-import json
-import hashlib
-import threading
-import time
-
-from . import paths
-from .redact import scrub_text
-
-LOCK = threading.RLock()
-
-
-def _dispatch_dir():
-    # 读取动态 DATA_DIR，测试和多实例运行可在启动后重定向数据目录。
-    return paths.DATA_DIR / "dispatch"
-
-
-def _month_file(day):
-    return _dispatch_dir() / ("dispatch-%s.jsonl" % day[:7].replace("-", ""))
-
-
-def _text(value, limit=240):
-    value = str(value or "").replace("\r", " ").replace("\n", " ")
-    return scrub_text(value, limit=limit)
-
-
-def _candidate(row):
-    if not isinstance(row, dict):
-        return {}
-    return {"agent_id": _text(row.get("agent_id"), 64),
-            "label": _text(row.get("label"), 80),
-            "kind": _text(row.get("kind"), 32),
-            "score": row.get("score", 0),
-            "reason": _text(row.get("reason"), 240),
-            "order": row.get("order", 0)}
-
-
-def record_event(run_id="", task_id="", task_type="", difficulty="", role="",
-                 phase="selected", selected="", participants=(), candidates=(),
-                 fallback=(), selection_reason="", result="", verify_pass=None,
-                 review_pass=None, trace_id="", span_id="", parent_event_id=""):
-    """追加一条事件；仅保存路由元数据，不保存正文、提示词、密钥或文件内容。"""
-    try:
-        day = time.strftime("%Y-%m-%d")
-        event = {
-            "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
-            "run_id": _text(run_id, 64), "task_id": _text(task_id, 64),
-            "task_type": _text(task_type, 32), "difficulty": _text(difficulty, 16),
-            "role": _text(role, 40), "phase": _text(phase, 16),
-            "selected": _text(selected, 64),
-            "participants": [_text(x.get("id") if isinstance(x, dict) else x, 64)
-                             for x in (participants or ())],
-            "candidates": [_candidate(x) for x in (candidates or ()) if isinstance(x, dict)],
-            "fallback": [_text(x, 64) for x in (fallback or ())],
-            "selection_reason": _text(selection_reason, 400),
-            "result": _text(result, 32),
-        }
-        # Trace identifiers are routing metadata only.  They deliberately do
-        # not carry prompt/output contents and remain optional for old callers.
-        if run_id:
-            from . import tracing
-            event["trace_id"] = _text(trace_id or tracing.trace_id(run_id), 64)
-        if span_id:
-            event["span_id"] = _text(span_id, 32)
-        if parent_event_id:
-            event["parent_event_id"] = _text(parent_event_id, 64)
-        event["event_id"] = hashlib.sha256(
-            ("%s|%s|%s|%s|%s|%s" % (
-                time.time_ns(), run_id, phase, role, selected, result
-            )).encode("utf-8")
-        ).hexdigest()[:24]
-        if verify_pass is not None:
-            event["verify_pass"] = bool(verify_pass)
-        if review_pass is not None:
-            event["review_pass"] = bool(review_pass)
-        with LOCK:
-            _dispatch_dir().mkdir(parents=True, exist_ok=True)
-            with open(_month_file(day), "a", encoding="utf-8") as fh:
-                fh.write(json.dumps(event, ensure_ascii=False) + "\n")
-        return event
-    except Exception:
-        return None
-
-
-def _iter_events(run_id="", task_type="", limit=100):
-    """从新到旧读取，满足 limit 即停，避免回放请求解析全部历史。"""
-    try:
-        directory = _dispatch_dir()
-        files = sorted(directory.glob("dispatch-*.jsonl"), reverse=True) \
-            if directory.is_dir() else []
-    except Exception:
-        return []
-    events = []
-    for path in files:
-        try:
-            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
-            for line in reversed(lines):
-                if not line.strip().startswith("{"):
-                    continue
-                try:
-                    item = json.loads(line)
-                except Exception:
-                    continue
-                if not isinstance(item, dict):
-                    continue
-                if run_id and item.get("run_id") != run_id:
-                    continue
-                if task_type and item.get("task_type") != task_type:
-                    continue
-                events.append(item)
-                if len(events) >= limit:
-                    return events
-        except Exception:
-            continue
-    return events
-
-
-def replay(run_id="", task_type="", limit=100):
-    """返回最新的脱敏调度事件，支持按 run_id/task_type 筛选。"""
-    try:
-        limit = max(1, min(1000, int(limit)))
-    except (TypeError, ValueError):
-        limit = 100
-    rid, ttype = _text(run_id, 64), _text(task_type, 32)
-    return _iter_events(rid, ttype, limit)
+# -*- coding: utf-8 -*-
+"""调度事件台账：记录脱敏的候选、决策和结果，支持按运行回放。"""
+from __future__ import annotations
+
+import json
+import hashlib
+import threading
+import time
+
+from . import paths
+from .redact import scrub_text
+
+LOCK = threading.RLock()
+
+
+def _dispatch_dir():
+    # 读取动态 DATA_DIR，测试和多实例运行可在启动后重定向数据目录。
+    return paths.DATA_DIR / "dispatch"
+
+
+def _month_file(day):
+    return _dispatch_dir() / ("dispatch-%s.jsonl" % day[:7].replace("-", ""))
+
+
+def _text(value, limit=240):
+    value = str(value or "").replace("\r", " ").replace("\n", " ")
+    return scrub_text(value, limit=limit)
+
+
+def _candidate(row):
+    if not isinstance(row, dict):
+        return {}
+    return {"agent_id": _text(row.get("agent_id"), 64),
+            "label": _text(row.get("label"), 80),
+            "kind": _text(row.get("kind"), 32),
+            "score": row.get("score", 0),
+            "reason": _text(row.get("reason"), 240),
+            "order": row.get("order", 0)}
+
+
+def record_event(run_id="", task_id="", task_type="", difficulty="", role="",
+                 phase="selected", selected="", participants=(), candidates=(),
+                 fallback=(), selection_reason="", result="", verify_pass=None,
+                 review_pass=None, trace_id="", span_id="", parent_event_id=""):
+    """追加一条事件；仅保存路由元数据，不保存正文、提示词、密钥或文件内容。"""
+    try:
+        day = time.strftime("%Y-%m-%d")
+        event = {
+            "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "run_id": _text(run_id, 64), "task_id": _text(task_id, 64),
+            "task_type": _text(task_type, 32), "difficulty": _text(difficulty, 16),
+            "role": _text(role, 40), "phase": _text(phase, 16),
+            "selected": _text(selected, 64),
+            "participants": [_text(x.get("id") if isinstance(x, dict) else x, 64)
+                             for x in (participants or ())],
+            "candidates": [_candidate(x) for x in (candidates or ()) if isinstance(x, dict)],
+            "fallback": [_text(x, 64) for x in (fallback or ())],
+            "selection_reason": _text(selection_reason, 400),
+            "result": _text(result, 32),
+        }
+        # Trace identifiers are routing metadata only.  They deliberately do
+        # not carry prompt/output contents and remain optional for old callers.
+        if run_id:
+            from . import tracing
+            event["trace_id"] = _text(trace_id or tracing.trace_id(run_id), 64)
+        if span_id:
+            event["span_id"] = _text(span_id, 32)
+        if parent_event_id:
+            event["parent_event_id"] = _text(parent_event_id, 64)
+        event["event_id"] = hashlib.sha256(
+            ("%s|%s|%s|%s|%s|%s" % (
+                time.time_ns(), run_id, phase, role, selected, result
+            )).encode("utf-8")
+        ).hexdigest()[:24]
+        if verify_pass is not None:
+            event["verify_pass"] = bool(verify_pass)
+        if review_pass is not None:
+            event["review_pass"] = bool(review_pass)
+        with LOCK:
+            _dispatch_dir().mkdir(parents=True, exist_ok=True)
+            with open(_month_file(day), "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(event, ensure_ascii=False) + "\n")
+        return event
+    except Exception:
+        return None
+
+
+def _iter_events(run_id="", task_type="", limit=100):
+    """从新到旧读取，满足 limit 即停，避免回放请求解析全部历史。"""
+    try:
+        directory = _dispatch_dir()
+        files = sorted(directory.glob("dispatch-*.jsonl"), reverse=True) \
+            if directory.is_dir() else []
+    except Exception:
+        return []
+    events = []
+    for path in files:
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+            for line in reversed(lines):
+                if not line.strip().startswith("{"):
+                    continue
+                try:
+                    item = json.loads(line)
+                except Exception:
+                    continue
+                if not isinstance(item, dict):
+                    continue
+                if run_id and item.get("run_id") != run_id:
+                    continue
+                if task_type and item.get("task_type") != task_type:
+                    continue
+                events.append(item)
+                if len(events) >= limit:
+                    return events
+        except Exception:
+            continue
+    return events
+
+
+def replay(run_id="", task_type="", limit=100):
+    """返回最新的脱敏调度事件，支持按 run_id/task_type 筛选。"""
+    try:
+        limit = max(1, min(1000, int(limit)))
+    except (TypeError, ValueError):
+        limit = 100
+    rid, ttype = _text(run_id, 64), _text(task_type, 32)
+    return _iter_events(rid, ttype, limit)