@oh-story/dsh 0.1.4 → 0.1.6

package/lib/video-recap/skills/video-script/scripts/lib.py

@@ -0,0 +1,327 @@
+"""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 hashlib
+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)
+DEFAULT_MIMO_ASR_MODEL = "mimo-v2.5-asr"  # speech-to-text
+DEFAULT_MIMO_TTS_MODEL = "mimo-v2.5-tts"  # text-to-speech
+
+
+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(api_key="", 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.
+    """
+    if is_mimo_token_plan_key(api_key):
+        cluster_name = (cluster or os.environ.get("MIMO_TOKEN_PLAN_CLUSTER") or DEFAULT_MIMO_TOKEN_PLAN_CLUSTER)
+        cluster_name = str(cluster_name).strip().lower()
+        return MIMO_TOKEN_PLAN_API_URLS.get(cluster_name, MIMO_TOKEN_PLAN_API_URLS[DEFAULT_MIMO_TOKEN_PLAN_CLUSTER])
+    return DEFAULT_MIMO_API_URL
+
+
+def env_int(name, default, *, minimum=None):
+    """Read an integer env var; ignore malformed values instead of crashing import."""
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return default
+    if minimum is not None:
+        value = max(minimum, value)
+    return value
+
+
+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; ignore malformed values instead of crashing import."""
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return default
+    if minimum is not None:
+        value = max(minimum, value)
+    return value
+
+
+# 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", "")
+_mimo_video_api_key = os.environ.get("MIMO_VIDEO_API_KEY", "") or _mimo_api_key
+_raw_api_url = os.environ.get("MIMO_API_URL") or default_mimo_api_url(_mimo_api_key)
+_raw_mimo_video_api_url = (
+    os.environ.get("MIMO_VIDEO_API_URL")
+    or os.environ.get("MIMO_API_URL")
+    or default_mimo_api_url(_mimo_video_api_key)
+)
+
+CONFIG = {
+    "api_url": normalize_api_url(_raw_api_url),
+    "api_key": _mimo_api_key,
+    "api_key_source": "MIMO_API_KEY",
+    "mimo_video_api_url": normalize_api_url(_raw_mimo_video_api_url),
+    "mimo_model": os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
+    "mimo_video_model": os.environ.get("MIMO_VIDEO_MODEL") or os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
+    "vlm_model": os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
+    "mimo_media_resolution": os.environ.get("MIMO_MEDIA_RESOLUTION", "default"),
+    "mimo_video_overview": env_bool("MIMO_VIDEO_OVERVIEW", False),  # opt-in (--mimo-video-overview / =1); when on it becomes the PRIMARY per-scene description, frames stay the anchor/fallback
+    "mimo_video_fps": env_float("MIMO_VIDEO_FPS", 3.0, minimum=0.1),
+    "mimo_video_chunk_max_seconds": env_float("MIMO_VIDEO_CHUNK_MAX_SECONDS", 20.0, minimum=1.0),
+    "mimo_video_chunk_min_seconds": env_float("MIMO_VIDEO_CHUNK_MIN_SECONDS", 1.0, minimum=0.2),
+    "mimo_video_base64_max_mb": env_float("MIMO_VIDEO_BASE64_MAX_MB", 45.0, minimum=1.0),
+    "mimo_video_prompt": os.environ.get(
+        "MIMO_VIDEO_PROMPT",
+        "请用中文分析这个视频分片的主要人物、场景变化、关键动作、情绪走向和剧情冲突，"
+        "重点提取适合写短视频解说的故事线索。不要泛泛复述画面，要标出对后续写稿有用的信息。",
+    ),
+    "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
+    "narration_block_seconds": 9.0,     # block cadence used to derive target block count
+    "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 写作分块最大字数/词数
+    "context_info": "",              # 额外上下文（节目名、角色名等）
+    "edit_mode": os.environ.get("EDIT_MODE", "full"),  # full | cut
+    "target_duration": os.environ.get("TARGET_DURATION", ""),  # cut 模式目标成片时长，如 10m
+}
+
+def narration_tempo_budget(tts_rate_offset=0.0, *, config=None):
+    """Return the canonical tempo budget shared by voiceover and assemble."""
+    cfg = config or CONFIG
+    global_speed = max(0.01, float(cfg.get("narration_speed", 1.0) or 1.0))
+    rate_factor = max(0.01, 1.0 + float(tts_rate_offset or 0.0))
+    cumulative_max = max(1.0, float(cfg.get("narration_cumulative_tempo_max", 1.35) or 1.35))
+    hard_max = max(cumulative_max, float(cfg.get("narration_cumulative_tempo_hard_max", 1.40) or 1.40))
+    legacy_segment_cap = max(1.0, float(cfg.get("tts_segment_tempo_max", 1.20) or 1.20))
+    segment_tempo_max = max(1.0, min(legacy_segment_cap, cumulative_max / (global_speed * rate_factor)))
+    return {
+        "global_narration_speed": global_speed,
+        "tts_rate_factor": rate_factor,
+        "cumulative_tempo_max": cumulative_max,
+        "cumulative_tempo_hard_max": hard_max,
+        "segment_tempo_max": segment_tempo_max,
+        "max_raw_duration_factor": global_speed * segment_tempo_max,
+    }
+
+def log(msg):
+    print(f"[video-recap] {msg}", flush=True)
+
+def stable_json_dumps(value):
+    """Serialize values deterministically for non-secret cache fingerprints."""
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
+
+def stable_hash(value):
+    """Return an md5 digest for deterministic JSON-serializable values."""
+    return hashlib.md5(stable_json_dumps(value).encode("utf-8")).hexdigest()
+
+_FILE_FINGERPRINT_MEMO = {}
+
+
+def _file_identity(path):
+    """(device, inode, size, mtime_ns) — changes whenever the bytes could have changed."""
+    st = os.stat(os.fspath(path))
+    return (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
+
+
+def file_fingerprint(path, chunk_size=1024 * 1024):
+    """Return a full-content fingerprint for cache-correct identity checks.
+
+    The digest covers CONTENT only — never the path or mtime — so a copied video or
+    artifact is still recognised as the same asset, while any byte change invalidates
+    the cache even if timestamps, size, head, or tail bytes are misleading.
+
+    Identity metadata is used ONLY to memoize within a single process. One understanding
+    run fingerprints the same source video 8-10 times and the whole extracted frame set
+    2-3 times; on a 40-minute video at fps=1 that is gigabytes of redundant reads before
+    any real work starts. A file rewritten in place gets a new (size, mtime_ns) and is
+    re-hashed, so the memo can never serve a stale digest.
+    """
+    key = _file_identity(path)
+    memoized = _FILE_FINGERPRINT_MEMO.get(key)
+    if memoized is not None:
+        return memoized
+    h = hashlib.sha256()
+    with open(os.fspath(path), "rb") as f:
+        for chunk in iter(lambda: f.read(chunk_size), b""):
+            h.update(chunk)
+    digest = h.hexdigest()
+    _FILE_FINGERPRINT_MEMO[key] = digest
+    return digest
+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.get("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 = str(normalized.get("model") or "")
+    if (
+        CONFIG.get("mimo_disable_thinking", True)
+        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_key_source=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:
+                result = json.loads(resp.read().decode("utf-8"))
+                return result
+        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_key_source or CONFIG.get("api_key_source", "MIMO_API_KEY")
+                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}")

package/lib/video-recap/skills/video-script/scripts/narration.py

@@ -0,0 +1,12 @@
+"""Public narration-brief API for this self-contained skill."""
+
+from agent_brief import build_agent_brief
+from brief_context import assess_understanding_substrate
+from narration_lint import lint_narration, validate_narration_or_raise
+
+__all__ = [
+    "assess_understanding_substrate",
+    "build_agent_brief",
+    "lint_narration",
+    "validate_narration_or_raise",
+]