@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/video-recap-production/upstream/skills/video-script/scripts/evidence_bundle.py

@@ -0,0 +1,440 @@
+"""Select, validate, and render bounded review evidence."""
+
+import math
+
+import re
+
+
+EVIDENCE_CONTRACT_VERSION = 1
+
+COVERAGE_POLICY_VERSION = "coverage_policy_v1"
+
+
+def _safe_time(item, key, default=0.0):
+    try:
+        value = float(item.get(key, default))
+    except (AttributeError, TypeError, ValueError):
+        return default
+    return value if math.isfinite(value) else default
+
+
+def _overall_duration(scenes, asr, narration):
+    ends = []
+    for seq in (scenes or [], asr or [], narration or []):
+        for item in seq:
+            if isinstance(item, dict):
+                ends.append(_safe_time(item, "end", _safe_time(item, "start", 0.0)))
+    return max(ends or [0.0])
+
+
+def _range(start, end, reason, priority=2):
+    start = max(0.0, float(start))
+    end = max(start, float(end))
+    return {
+        "start": round(start, 3),
+        "end": round(end, 3),
+        "selection_reason": reason,
+        "priority": priority,
+    }
+
+
+def _merge_ranges(ranges):
+    merged = []
+    for r in sorted(
+        (r for r in ranges if r["end"] > r["start"]),
+        key=lambda x: (x["start"], x["end"]),
+    ):
+        if not merged or r["start"] > merged[-1]["end"]:
+            merged.append(dict(r))
+            continue
+        merged[-1]["end"] = max(merged[-1]["end"], r["end"])
+        reasons = {
+            part
+            for part in str(merged[-1].get("selection_reason", "")).split("+")
+            if part
+        }
+        reasons.update(
+            part for part in str(r.get("selection_reason", "")).split("+") if part
+        )
+        order = {
+            "beginning": 0,
+            "middle": 1,
+            "end": 2,
+            "longest_gap": 3,
+            "narration_window": 4,
+        }
+        merged[-1]["selection_reason"] = "+".join(
+            sorted(reasons, key=lambda x: order.get(x, 99))
+        )
+        merged[-1]["priority"] = min(
+            merged[-1].get("priority", 2), r.get("priority", 2)
+        )
+    return merged
+
+
+def coverage_policy_v1(
+    scenes,
+    asr_result,
+    narration,
+    *,
+    max_coverage_ranges=12,
+    min_baseline_ranges=6,
+    window_seconds=30.0,
+):
+    """Deterministic B/M/E floor → longest-gap fill → narration-window coverage."""
+    duration = _overall_duration(scenes, asr_result, narration)
+    if duration <= 0:
+        return {
+            "coverage_policy_version": COVERAGE_POLICY_VERSION,
+            "selected_ranges": [],
+            "dropped_ranges": [],
+            "dropped_range_count": 0,
+            "duration": 0.0,
+            "baseline_range_count_before_narration": 0,
+        }
+    width = min(float(window_seconds), max(5.0, duration / 8.0))
+    ranges = [
+        _range(0.0, min(duration, width), "beginning", 0),
+        _range(
+            max(0.0, duration / 2.0 - width / 2.0),
+            min(duration, duration / 2.0 + width / 2.0),
+            "middle",
+            0,
+        ),
+        _range(max(0.0, duration - width), duration, "end", 0),
+    ]
+    ranges = _merge_ranges(ranges)
+    while len(ranges) < min_baseline_ranges:
+        ranges = _merge_ranges(ranges)
+        gaps = []
+        cursor = 0.0
+        for r in ranges:
+            if r["start"] > cursor:
+                gaps.append((r["start"] - cursor, cursor, r["start"]))
+            cursor = max(cursor, r["end"])
+        if cursor < duration:
+            gaps.append((duration - cursor, cursor, duration))
+        if not gaps:
+            break
+        gap_len, gs, ge = max(gaps, key=lambda g: (g[0], -g[1]))
+        if gap_len <= 0.001:
+            break
+        center = (gs + ge) / 2.0
+        half = min(width / 2.0, gap_len / 2.0)
+        ranges.append(_range(center - half, center + half, "longest_gap", 2))
+    before_narration = len(ranges)
+    for i, seg in enumerate(narration or []):
+        if not isinstance(seg, dict):
+            continue
+        start = _safe_time(seg, "start", None)
+        end = _safe_time(seg, "end", start)
+        if start is None or end <= start:
+            continue
+        priority = 1 if str(seg.get("narration", "")).strip() else 2
+        r = _range(
+            max(0.0, start - 3.0),
+            min(duration, end + 3.0),
+            "narration_window",
+            priority,
+        )
+        r["narration_segment"] = i
+        ranges.append(r)
+    merged = _merge_ranges(ranges)
+    dropped = []
+    if len(merged) > max_coverage_ranges:
+        protected = [
+            r
+            for r in merged
+            if any(x in r["selection_reason"] for x in ("beginning", "middle", "end"))
+        ]
+        candidates = [r for r in merged if r not in protected]
+        candidates.sort(
+            key=lambda r: (
+                r.get("priority", 2),
+                -float(r["end"] - r["start"]),
+                r["start"],
+            )
+        )
+        keep = protected + candidates[: max(0, max_coverage_ranges - len(protected))]
+        keep_ids = {id(r) for r in keep}
+        dropped = [r for r in merged if id(r) not in keep_ids]
+        merged = sorted(keep, key=lambda r: (r["start"], r["end"]))
+    for r in merged + dropped:
+        r.pop("priority", None)
+    return {
+        "coverage_policy_version": COVERAGE_POLICY_VERSION,
+        "selected_ranges": merged,
+        "dropped_ranges": dropped,
+        "dropped_range_count": len(dropped),
+        "duration": round(duration, 3),
+        "baseline_range_count_before_narration": before_narration,
+    }
+
+
+def _in_ranges(start, end, ranges):
+    return any(
+        float(r["start"]) < end and float(r["end"]) > start for r in ranges or []
+    )
+
+
+def _scene_evidence_text(scene):
+    desc = str(scene.get("description", "")).strip().replace("\n", " ")
+    facts = scene.get("frame_facts")
+    picks = []
+    if isinstance(facts, dict):
+
+        def fact_sort_key(value):
+            try:
+                return (0, float(value))
+            except (TypeError, ValueError):
+                return (1, str(value))
+
+        for ts in sorted(facts.keys(), key=fact_sort_key):
+            vals = facts[ts]
+            picks.extend(vals if isinstance(vals, list) else [str(vals)])
+    elif isinstance(facts, list):
+        for f in facts:
+            picks.append(
+                str(f.get("fact", f.get("text", ""))).strip()
+                if isinstance(f, dict)
+                else str(f).strip()
+            )
+    fact_txt = "；".join(p for p in picks[:4] if p)
+    return (desc + (" | 帧实: " + fact_txt if fact_txt else "")).strip()
+
+
+def _research_context_items(research):
+    if not isinstance(research, dict) or not research:
+        return []
+    items = []
+    for key in ("synopsis", "episode_context", "worldbuilding"):
+        value = _clip_text(research.get(key), 400)
+        if value:
+            items.append(
+                {
+                    "id": f"research:{key}",
+                    "source": "research",
+                    "clock": None,
+                    "source_id": "context",
+                    "start": None,
+                    "end": None,
+                    "text": value,
+                    "support": "context_only",
+                    "confidence": "medium",
+                }
+            )
+    for name, desc in (
+        list((research.get("characters") or {}).items())[:12]
+        if isinstance(research.get("characters"), dict)
+        else []
+    ):
+        text = f"{_clip_text(name, 80)}：{_clip_text(desc, 200)}"
+        items.append(
+            {
+                "id": f"research:character:{len(items)}",
+                "source": "research",
+                "clock": None,
+                "source_id": "context",
+                "start": None,
+                "end": None,
+                "text": text,
+                "support": "context_only",
+                "confidence": "medium",
+            }
+        )
+    details = research.get("character_details")
+    if isinstance(details, dict):
+        for name, info in list(details.items())[:8]:
+            if not isinstance(info, dict):
+                continue
+            aliases = (
+                info.get("aliases") if isinstance(info.get("aliases"), list) else []
+            )
+            bits = []
+            if aliases:
+                bits.append(
+                    "aliases=" + "/".join(_clip_text(a, 40) for a in aliases[:4])
+                )
+            role = _clip_text(info.get("role"), 120)
+            if role:
+                bits.append(role)
+            if bits:
+                items.append(
+                    {
+                        "id": f"research:detail:{len(items)}",
+                        "source": "research",
+                        "clock": None,
+                        "source_id": "context",
+                        "start": None,
+                        "end": None,
+                        "text": f"{name}: {'; '.join(bits)}",
+                        "support": "context_only",
+                        "confidence": "medium",
+                    }
+                )
+    return items
+
+
+def filter_evidence_by_ranges(vlm_analysis, asr_result, ranges, *, timeline="source"):
+    """Pure compatibility seam: collect visual/ASR evidence items inside ranges."""
+    clock = "output" if timeline == "cut_output" else "source"
+    items = []
+    dropped = {"visual": 0, "asr": 0}
+    for i, scene in enumerate(vlm_analysis or []):
+        if not isinstance(scene, dict):
+            continue
+        start = _safe_time(scene, "start")
+        end = _safe_time(scene, "end", start)
+        if end <= start or not _in_ranges(start, end, ranges):
+            dropped["visual"] += 1
+            continue
+        item = {
+            "id": f"visual:{i}",
+            "source": "visual",
+            "clock": clock,
+            "source_id": str(scene.get("source_id", "0")),
+            "start": round(start, 3),
+            "end": round(end, 3),
+            "text": _scene_evidence_text(scene),
+            "support": "direct",
+            "confidence": "high",
+        }
+        for k in (
+            "source_start",
+            "source_end",
+            "source_clip_id",
+            "output_segment_index",
+        ):
+            if k in scene:
+                item[k] = scene.get(k)
+        items.append(item)
+    for i, seg in enumerate(asr_result or []):
+        if not isinstance(seg, dict):
+            continue
+        text = str(seg.get("text", "")).strip()
+        if not text:
+            continue
+        start = _safe_time(seg, "start")
+        end = _safe_time(seg, "end", start)
+        if end <= start or not _in_ranges(start, end, ranges):
+            dropped["asr"] += 1
+            continue
+        item = {
+            "id": f"asr:{i}",
+            "source": "asr",
+            "clock": clock,
+            "source_id": str(seg.get("source_id", "0")),
+            "start": round(start, 3),
+            "end": round(end, 3),
+            "text": text,
+            "support": "direct",
+            "confidence": "high",
+        }
+        for k in (
+            "source_start",
+            "source_end",
+            "source_clip_id",
+            "output_segment_index",
+        ):
+            if k in seg:
+                item[k] = seg.get(k)
+        items.append(item)
+    return {
+        "items": items,
+        "dropped_visual_count": dropped["visual"],
+        "dropped_asr_count": dropped["asr"],
+    }
+
+
+def build_review_coverage_metadata(bundle):
+    """Summarize a build_evidence_bundle() bundle's coverage contract."""
+    coverage = bundle["coverage"]
+    metadata = bundle["metadata"]
+    return {
+        "coverage_policy_version": coverage["coverage_policy_version"],
+        "time_ranges": coverage["selected_ranges"],
+        "dropped_ranges": coverage["dropped_ranges"],
+        "dropped_range_count": coverage["dropped_range_count"],
+        "scene_count": metadata["reviewed_scene_count"],
+        "asr_count": metadata["reviewed_asr_count"],
+        "dropped_scene_count": metadata["dropped_scene_count"],
+        "dropped_asr_count": metadata["dropped_asr_count"],
+    }
+
+
+def build_evidence_bundle(
+    vlm_analysis,
+    asr_result,
+    narration,
+    *,
+    timeline="source",
+    research=None,
+    warnings=None,
+):
+    clock = "output" if timeline == "cut_output" else "source"
+    coverage = coverage_policy_v1(vlm_analysis, asr_result, narration)
+    ranges = coverage.get("selected_ranges", [])
+    filtered = filter_evidence_by_ranges(
+        vlm_analysis, asr_result, ranges, timeline=timeline
+    )
+    items = filtered["items"]
+    dropped_scenes = filtered["dropped_visual_count"]
+    dropped_asr = filtered["dropped_asr_count"]
+    context_items = _research_context_items(research)
+    return {
+        "schema_version": EVIDENCE_CONTRACT_VERSION,
+        "timeline": timeline,
+        "clock": clock,
+        "items": items,
+        "context_items": context_items,
+        "coverage": coverage,
+        "warnings": list(warnings or []),
+        "metadata": {
+            "reviewed_scene_count": sum(1 for x in items if x["source"] == "visual"),
+            "reviewed_asr_count": sum(1 for x in items if x["source"] == "asr"),
+            "dropped_scene_count": dropped_scenes,
+            "dropped_asr_count": dropped_asr,
+        },
+    }
+
+
+def render_evidence_bundle(bundle, *, limit_items=220):
+    clock = bundle["clock"].upper()
+    lines = [f"## Timeline evidence (clock={clock}; source=visual/asr)"]
+    items = bundle["items"]
+    if not items:
+        lines.append("(无 timeline evidence)")
+    for item in items[:limit_items]:
+        label = "画面" if item["source"] == "visual" else "对白"
+        backref = ""
+        # Remapped cut_output evidence carries its source-time provenance.
+        if "source_start" in item:
+            backref = f" ← SOURCE {item['source_start']:.1f}-{item['source_end']:.1f}s"
+            if "output_segment_index" in item:
+                backref += f" clip#{item['output_segment_index']}"
+        lines.append(
+            f"[{clock} {item['start']:.1f}-{item['end']:.1f}s {label} id={item['id']}{backref}] {item['text']}"
+        )
+    if len(items) > limit_items:
+        lines.append(
+            f"... dropped from prompt: {len(items) - limit_items} items (artifact metadata keeps counts)"
+        )
+    context = bundle["context_items"]
+    lines.extend(
+        [
+            "",
+            "## Context-only evidence (clock=null; source=research/user_context; advisory, not current-timeline fact)",
+        ]
+    )
+    if not context:
+        lines.append("(无 context-only evidence)")
+    for item in context[:40]:
+        lines.append(
+            f"[clock=null {item['source']} support=context_only id={item['id']}] {item['text']}"
+        )
+    return "\n".join(lines)
+
+
+def _clip_text(text, limit):
+    value = re.sub(r"\s+", " ", str(text or "")).strip()
+    return value[:limit]

package/resources/skills/video-recap-production/upstream/skills/video-script/scripts/lib.py

@@ -0,0 +1,254 @@
+"""Self-contained config + utilities for this skill (no cross-skill imports).
+Merged from the shared core; reads the same env vars as the rest of the bundle."""
+import json
+import math
+import os
+import re
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+
+
+# ── 配置 ──────────────────────────────────────────────────────────────
+
+DEFAULT_MIMO_API_URL = "https://api.xiaomimimo.com/v1"
+DEFAULT_MIMO_TOKEN_PLAN_CLUSTER = "cn"
+MIMO_TOKEN_PLAN_API_URLS = {
+    "cn": "https://token-plan-cn.xiaomimimo.com/v1",
+    "sgp": "https://token-plan-sgp.xiaomimimo.com/v1",
+    "ams": "https://token-plan-ams.xiaomimimo.com/v1",
+}
+DEFAULT_MIMO_MODEL = "mimo-v2.5"          # VLM / chat (vision understanding)
+
+
+def normalize_api_url(raw_url):
+    """Normalize a MiMo (OpenAI-compatible) base URL or chat/completions endpoint."""
+    url = (raw_url or DEFAULT_MIMO_API_URL).rstrip("/")
+    if url.endswith("/chat/completions"):
+        return url
+    return f"{url}/chat/completions"
+
+
+def is_mimo_token_plan_key(api_key):
+    """Return True for Xiaomi MiMo Token Plan keys, which use token-plan base URLs."""
+    return str(api_key or "").strip().startswith("tp-")
+
+
+def default_mimo_api_url(is_token_plan, cluster=None):
+    """Pick the correct MiMo base URL for pay-as-you-go vs Token Plan keys.
+
+    MiMo uses independent credentials for pay-as-you-go (`sk-*`) and Token Plan
+    (`tp-*`). Token Plan keys must be sent to the Token Plan cluster base URL,
+    not the pay-as-you-go `api.xiaomimimo.com` endpoint.
+
+    The caller classifies its own key with `is_mimo_token_plan_key` and passes only
+    that bit: a credential never reaches a function whose return value is logged.
+    """
+    if is_token_plan:
+        cluster_name = (cluster or os.environ.get("MIMO_TOKEN_PLAN_CLUSTER") or DEFAULT_MIMO_TOKEN_PLAN_CLUSTER)
+        cluster_name = str(cluster_name).strip().lower()
+        if cluster_name not in MIMO_TOKEN_PLAN_API_URLS:
+            raise ValueError(
+                f"MiMo token-plan cluster must be one of {sorted(MIMO_TOKEN_PLAN_API_URLS)}; "
+                f"got {cluster_name!r}"
+            )
+        return MIMO_TOKEN_PLAN_API_URLS[cluster_name]
+    return DEFAULT_MIMO_API_URL
+
+
+def _env_number(name, default, cast, minimum):
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = cast(raw)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be a {cast.__name__}; got {raw!r}") from exc
+    if isinstance(value, float) and not math.isfinite(value):
+        raise ValueError(f"{name} must be finite; got {raw!r}")
+    if minimum is not None and value < minimum:
+        raise ValueError(f"{name} must be >= {minimum}; got {value}")
+    return value
+
+
+def env_int(name, default, *, minimum=None):
+    """Read an integer env var, rejecting malformed or below-minimum values."""
+    return _env_number(name, default, int, minimum)
+
+
+def env_bool(name, default=False):
+    """Read common boolean env var forms."""
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+def env_float(name, default, *, minimum=None):
+    """Read a float env var, rejecting malformed or below-minimum values."""
+    return _env_number(name, default, float, minimum)
+
+
+# Single MiMo credential powers ASR + VLM + TTS. Per-capability overrides
+# (MIMO_VIDEO_API_KEY / MIMO_TTS_API_KEY / MIMO_ASR_API_KEY and their *_API_URL forms)
+# are optional and fall back to MIMO_API_KEY / MIMO_API_URL. Token-Plan keys (tp-*) auto-
+# route to the Token-Plan cluster base URL; pay-as-you-go keys use api.xiaomimimo.com.
+_mimo_api_key = os.environ.get("MIMO_API_KEY", "")
+_raw_api_url = os.environ.get("MIMO_API_URL") or default_mimo_api_url(is_mimo_token_plan_key(_mimo_api_key))
+
+CONFIG = {
+    "api_url": normalize_api_url(_raw_api_url),
+    "api_key": _mimo_api_key,
+    "api_env_var": "MIMO_API_KEY",
+    "vlm_model": os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
+    "mimo_disable_thinking": env_bool("MIMO_DISABLE_THINKING", True),
+    # TTS 语速（字符/秒）。实测 mimo-tts 冰糖音色中位 ~3.9 字/秒，可用 SPEECH_RATE 覆盖
+    # 生成解说时使用 speech_rate * safety_margin 作为约束
+    "speech_rate": env_float("SPEECH_RATE", 3.9, minimum=0.5),  # 旧值 3.5 系统性偏低 ~10-17%
+    "speech_safety_margin": env_float("SPEECH_SAFETY_MARGIN", 0.85, minimum=0.1),  # 保守系数：TTS 实际语速有 ±20% 波动
+    # Block-coverage lint thresholds — promoted from inline .get() literals to real CONFIG keys (tunable; defaults unchanged)
+    "narration_coverage_target": 0.7,   # rough first-draft/diagnostic fallback; content-led audio decisions may differ (not a quota)
+    "narration_coverage_max": 0.85,     # above this coverage → no_original_blocks (narration is wall-to-wall)
+    "narration_coverage_min": 0.5,      # below this coverage → under_narrated
+    "original_block_min_seconds": 2.5,  # a deliberate original-audio gap must be at least this long
+    "narration_block_min_chars": 16,    # below this avg block size → fragmented_beats
+    "breath_ms": 250,  # 段间呼吸空间(ms)；block recap 块内连贯、块间留原声呼吸
+    "narration_speed": env_float("NARRATION_SPEED", 1.15, minimum=0.5),  # 解说整体提速(atempo)，默认回到可懂区间；长片可设 1.0
+    "narration_tail_pad_seconds": 0.1,  # 解说尾部最少留白；短 slot 会自动压低 delay 避免截断
+    "quiet_overlap_min_ratio": 0.8,  # 解说段至少多少比例落在安静窗口内才标记为非对白重叠
+    "visual_beat_max_seconds": 18.0,  # 单段解说超过该时长且跨多个帧锚点时给 lint 提醒
+    "visual_beat_max_facts": 3,  # 单段解说最多建议覆盖的 frame_facts 锚点数量
+    "asr_chunk_min_chars": env_int("ASR_CHUNK_MIN_CHARS", 500, minimum=1),  # brief 中 ASR 写作分块最小字数/词数
+    "asr_chunk_max_chars": env_int("ASR_CHUNK_MAX_CHARS", 800, minimum=1),  # brief 中 ASR 写作分块最大字数/词数
+    "edit_mode": os.environ.get("EDIT_MODE", "full"),  # full | cut
+}
+
+def log(msg):
+    print(f"[video-recap] {msg}", flush=True)
+
+def file_identity(path):
+    """{size, mtime_ns} of an input file: the identity brief consumers compare against
+    the provenance a producer stored, instead of re-hashing bytes."""
+    st = os.stat(os.fspath(path))
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
+
+
+def _retry_after_seconds(value, fallback):
+    """Parse Retry-After seconds or HTTP-date; return fallback on malformed input."""
+    if not value:
+        return fallback
+    try:
+        return max(fallback, max(0, int(value)))
+    except (TypeError, ValueError):
+        pass
+    try:
+        retry_at = parsedate_to_datetime(value)
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=timezone.utc)
+        return max(fallback, max(0, int((retry_at - datetime.now(timezone.utc)).total_seconds())))
+    except (TypeError, ValueError, IndexError, OverflowError):
+        return fallback
+
+
+_ERROR_DATA_URL_RE = re.compile(
+    r"data:(?:audio|video|image)/[^;,\s\"'<>]+;base64,[A-Za-z0-9+/=]+",
+    re.IGNORECASE,
+)
+_ERROR_KEY_RE = re.compile(r"\b(?:tp|sk)-[A-Za-z0-9_-]{8,}\b")
+
+
+def _sanitize_api_error(value, limit=500):
+    """Bound transport diagnostics without echoing request media or credentials."""
+    text = _ERROR_DATA_URL_RE.sub("<redacted-data-url>", str(value or ""))
+    text = _ERROR_KEY_RE.sub("<redacted-key>", text)
+    return text[:limit]
+
+def _api_headers(api_provider=None, api_url=None, api_key=None):
+    """Build MiMo auth headers (OpenAI-compatible chat/completions with an api-key header)."""
+    del api_provider, api_url  # MiMo is the only provider; signature kept for call sites
+    key = CONFIG["api_key"] if api_key is None else api_key
+    return {
+        "Content-Type": "application/json",
+        "User-Agent": "video-recap/1.0",
+        "api-key": key,
+    }
+
+def _prepare_api_payload(payload, api_provider=None, api_url=None):
+    """Normalize payload fields for MiMo's OpenAI-compatible chat/completions API."""
+    del api_provider, api_url
+    normalized = dict(payload)
+    if "max_tokens" in normalized and "max_completion_tokens" not in normalized:
+        normalized["max_completion_tokens"] = normalized.pop("max_tokens")
+    model = normalized["model"]
+    if (
+        CONFIG["mimo_disable_thinking"]
+        and not model.endswith(("-tts", "-asr"))
+        and "thinking" not in normalized
+    ):
+        # MiMo V2.5 may spend small max_completion_tokens budgets on reasoning_content.
+        # The recap pipeline needs visible text, so disable thinking unless set explicitly.
+        normalized["thinking"] = {"type": "disabled"}
+    return normalized
+
+def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key=None, api_env_var=None):
+    """调用 OpenAI-compatible API，带重试。
+
+    集群的 429 限流是常态而非错误，所以重试更耐心（更多次数 + 退避封顶 60s + 遵从 Retry-After），
+    避免一次瞬时限流就中止整个阶段。配额窗口常以分钟计，所以 429 在没有 Retry-After 时也至少等 10s。
+    """
+    endpoint = normalize_api_url(api_url if api_url is not None else CONFIG["api_url"])
+    headers = _api_headers(api_provider=api_provider, api_url=endpoint, api_key=api_key)
+    data = json.dumps(_prepare_api_payload(payload, api_provider=api_provider, api_url=endpoint)).encode("utf-8")
+
+    for attempt in range(max_retries):
+        try:
+            req = urllib.request.Request(endpoint, data=data, headers=headers)
+            with urllib.request.urlopen(req, timeout=300) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body = _sanitize_api_error(e.read().decode("utf-8", errors="replace"))
+            wait = min(2 ** attempt, 60)
+            if e.code == 429:
+                retry_after = e.headers.get("Retry-After")
+                wait = _retry_after_seconds(retry_after, max(wait, 10))
+                log(f"API 速率限制 (尝试 {attempt+1}/{max_retries}), 等待 {wait}s")
+            elif e.code == 401:
+                key_name = api_env_var or CONFIG["api_env_var"]
+                raise RuntimeError(f"API 认证失败 (401)。请检查 {key_name} 和 API URL 是否匹配。")
+            elif e.code == 403:
+                hint = "API 访问被拒绝 (403)。"
+                if "1010" in body or "cloudflare" in body.lower():
+                    hint += "IP 被 Cloudflare 限流，请等待几分钟后重试。"
+                    raise RuntimeError(hint)
+                hint += "请检查 API key 权限和 API URL 设置。"
+                raise RuntimeError(hint)
+            elif e.code == 405:
+                raise RuntimeError("API 端点不可用 (405)，可能被 WAF 拦截。请检查 MIMO_API_URL 或稍后重试。")
+            elif e.code == 503:
+                log(f"API 服务暂不可用 (503)，等待 {wait}s (尝试 {attempt+1}/{max_retries})")
+            elif e.code == 524:
+                # Cloudflare 超时：服务端处理超时，需要更长退避
+                wait = max(wait, 4 * (attempt + 1))
+                log(f"API 超时 (524)，等待 {wait}s (尝试 {attempt+1}/{max_retries})")
+            else:
+                log(f"API 调用失败 (尝试 {attempt+1}/{max_retries}): HTTP {e.code} — {body}")
+            if attempt < max_retries - 1:
+                time.sleep(wait)
+            else:
+                raise RuntimeError(f"API 调用失败 {max_retries} 次: HTTP {e.code} — {body}")
+        except Exception as e:  # noqa: BLE001 - transport/decode faults are all retryable here
+            # (Deliberately broad, but no longer written as `(URLError, Exception)`, which
+            # read as a tuple while `Exception` already subsumed the first member.)
+            wait = min(2 ** attempt, 60)
+            safe_error = _sanitize_api_error(e)
+            log(f"API 调用失败 (尝试 {attempt+1}/{max_retries}): {safe_error}")
+            if attempt < max_retries - 1:
+                log(f"等待 {wait}s 后重试...")
+                time.sleep(wait)
+            else:
+                raise RuntimeError(f"API 调用失败 {max_retries} 次: {safe_error}")
+    # Unreachable for max_retries >= 1; guards against a silent `None` return (and the
+    # TypeError it would cause at the caller's resp["choices"]) if a caller passes 0.
+    raise ValueError(f"max_retries must be >= 1, got {max_retries}")