@tikomni/skills 0.1.3 → 0.1.4

package/skills/creator-analysis/scripts/platform/douyin/run_douyin_single_video.py

@@ -1,1208 +0,0 @@
-#!/usr/bin/env python3
-"""Douyin single-video low-quality runner (APP first, WEB fallback)."""
-
-from __future__ import annotations
-
-if __package__ in {None, ""}:
-    import sys
-    from pathlib import Path
-
-    _self = Path(__file__).resolve()
-    for _parent in _self.parents:
-        if (_parent / "scripts" / "core" / "bootstrap_env.py").is_file():
-            sys.path.insert(0, str(_parent))
-            break
-
-
-import argparse
-
-from scripts.core.bootstrap_env import bootstrap_for_direct_run
-
-bootstrap_for_direct_run(__file__, __package__)
-import hashlib
-import json
-import re
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from scripts.core.config_loader import config_get, load_tikomni_config, resolve_storage_paths
-from scripts.core.extract_pipeline import resolve_trace_error_context
-from scripts.core.progress_report import ProgressReporter
-from scripts.core.storage_router import render_output_filename, resolve_json_filename_pattern
-from scripts.platform.douyin.douyin_video_type_matrix import normalize_douyin_video_type
-from scripts.pipeline.asr.asr_pipeline import submit_u2_asr_with_retry
-from scripts.pipeline.asr.poll_u2_task import poll_u2_task
-from scripts.platform.douyin.select_low_quality_video_url import select_low_quality_video_url
-from scripts.core.tikomni_common import (
-    call_json_api,
-    deep_find_all,
-    normalize_text,
-    resolve_runtime,
-    summarize_content,
-    write_json_stdout,
-)
-from scripts.writers.write_benchmark_card import write_benchmark_card
-
-APP_ENDPOINT = "/api/u1/v1/douyin/app/v3/fetch_one_video_by_share_url"
-WEB_ENDPOINT = "/api/u1/v1/douyin/web/fetch_one_video_by_share_url"
-U2_SUBMIT_ENDPOINT = "/api/u2/v1/services/audio/asr/transcription"
-
-
-
-
-def _safe_slug(value: Optional[str], fallback: str = "unknown") -> str:
-    text = normalize_text(value)
-    if not text:
-        return fallback
-    lowered = text.lower()
-    slug = re.sub(r"[^a-z0-9_-]+", "-", lowered).strip("-")
-    return slug[:64] or fallback
-
-
-def _traceable_identifier(source_input: Dict[str, Optional[str]], platform_work_id: Optional[str]) -> str:
-    if platform_work_id:
-        return _safe_slug(platform_work_id)
-
-    share_url = normalize_text(source_input.get("share_url"))
-    if not share_url:
-        return "missing_input"
-
-    digest = hashlib.sha1(share_url.encode("utf-8")).hexdigest()[:10]
-    return f"url-{digest}"
-
-
-def _build_persist_payload(
-    *,
-    result: Dict[str, Any],
-    source_input: Dict[str, Optional[str]],
-    platform_work_id: Optional[str],
-    status: str,
-    written_at: datetime,
-) -> Dict[str, Any]:
-    summary = {
-        "summary": result.get("summary", ""),
-        "insights": result.get("insights", []),
-        "confidence": result.get("confidence"),
-        "error_reason": result.get("error_reason"),
-    }
-    normalized = {
-        "platform": result.get("platform", "douyin"),
-        "content_kind": result.get("content_kind", "single_video"),
-        "platform_work_id": result.get("platform_work_id"),
-        "title": result.get("title"),
-        "duration_ms": result.get("duration_ms"),
-        "is_video": result.get("is_video"),
-        "u2_task_id": result.get("u2_task_id"),
-        "u2_task_status": result.get("u2_task_status"),
-        "request_id": result.get("request_id"),
-        "source": source_input,
-    }
-    return {
-        "meta": {
-            "written_at": written_at.isoformat(timespec="seconds"),
-            "status": status,
-            "platform": "douyin",
-            "identifier": _traceable_identifier(source_input, platform_work_id),
-        },
-        "summary": summary,
-        "normalized": normalized,
-        "raw": result,
-    }
-
-
-def _persist_output_artifact(
-    *,
-    result: Dict[str, Any],
-    source_input: Dict[str, Optional[str]],
-    platform_work_id: Optional[str],
-    storage_config: Optional[Dict[str, Any]],
-    persist_output: bool,
-) -> Dict[str, Any]:
-    if not persist_output:
-        return {"enabled": False, "skipped": True, "reason": "disabled_by_flag"}
-
-    try:
-        paths = resolve_storage_paths(storage_config or {})
-    except Exception as error:
-        return {"enabled": True, "ok": False, "error": f"resolve_storage_paths_failed:{error}"}
-
-    now = datetime.now()
-    date_key = now.strftime("%Y%m%d")
-    timestamp = now.strftime("%Y%m%dT%H%M%S")
-    identifier = _traceable_identifier(source_input, platform_work_id)
-    has_error = bool(result.get("error_reason"))
-    status = "error" if has_error else "success"
-
-    if has_error:
-        target_dir = Path(paths.get("errors_root", "")) / date_key
-    else:
-        target_dir = Path(paths.get("results_root", "")) / date_key
-
-    target_dir.mkdir(parents=True, exist_ok=True)
-    file_name = render_output_filename(
-        pattern=resolve_json_filename_pattern(storage_config),
-        context={
-            "prefix": status,
-            "platform": "douyin",
-            "card_type": "single_work_result",
-            "author_slug": identifier,
-            "title_slug": identifier,
-            "identifier": identifier,
-            "timestamp": timestamp,
-            "date": date_key,
-            "ext": ".json",
-        },
-        default_filename=f"{timestamp}-douyin-{identifier}.json",
-        default_ext=".json",
-    )
-    file_path = target_dir / file_name
-
-    payload = _build_persist_payload(
-        result=result,
-        source_input=source_input,
-        platform_work_id=platform_work_id,
-        status=status,
-        written_at=now,
-    )
-    file_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
-
-    return {
-        "enabled": True,
-        "ok": True,
-        "status": status,
-        "path": str(file_path),
-    }
-
-
-def _finalize_result(
-    *,
-    result: Dict[str, Any],
-    source_input: Dict[str, Optional[str]],
-    platform_work_id: Optional[str],
-    storage_config: Optional[Dict[str, Any]],
-    persist_output: bool,
-) -> Dict[str, Any]:
-    result["output_persist"] = _persist_output_artifact(
-        result=result,
-        source_input=source_input,
-        platform_work_id=platform_work_id,
-        storage_config=storage_config,
-        persist_output=persist_output,
-    )
-    return result
-
-def _normalize_input(
-    input_value: Optional[str],
-    share_url: Optional[str],
-) -> Dict[str, Optional[str]]:
-    normalized_share = (share_url or "").strip() or None
-
-    if input_value and not normalized_share:
-        candidate = input_value.strip()
-        if candidate.startswith("http://") or candidate.startswith("https://"):
-            normalized_share = candidate
-
-    return {"share_url": normalized_share}
-
-
-def _extract_aweme_detail(payload: Any) -> Optional[Dict[str, Any]]:
-    if isinstance(payload, dict):
-        direct = payload.get("aweme_detail")
-        if isinstance(direct, dict):
-            return direct
-
-        for list_key in ("aweme_details", "aweme_list", "item_list", "items"):
-            values = payload.get(list_key)
-            if isinstance(values, list) and values:
-                first = values[0]
-                if isinstance(first, dict):
-                    return first
-
-        nested_data = payload.get("data")
-        if nested_data is not None:
-            hit = _extract_aweme_detail(nested_data)
-            if hit:
-                return hit
-
-        for value in payload.values():
-            hit = _extract_aweme_detail(value)
-            if hit:
-                return hit
-
-    elif isinstance(payload, list):
-        for item in payload:
-            hit = _extract_aweme_detail(item)
-            if hit:
-                return hit
-
-    return None
-
-
-def _safe_int(value: Any) -> Optional[int]:
-    if value is None:
-        return None
-    if isinstance(value, bool):
-        return 1 if value else 0
-    if isinstance(value, int):
-        return value
-    if isinstance(value, float):
-        return int(value)
-    if isinstance(value, str):
-        text = value.strip()
-        if text.startswith("-"):
-            sign = -1
-            text = text[1:]
-        else:
-            sign = 1
-        if text.isdigit():
-            return sign * int(text)
-    return None
-
-
-def _normalize_duration_ms(item: Dict[str, Any]) -> Optional[int]:
-    raw = item.get("duration")
-    if raw is None:
-        video = item.get("video")
-        if isinstance(video, dict):
-            raw = video.get("duration")
-
-    value = _safe_int(raw)
-    if value is None:
-        return None
-
-    # Douyin commonly uses ms; convert obvious second-level durations.
-    if 0 < value < 10000:
-        return value * 1000
-    return value
-
-
-def _pick_title(item: Dict[str, Any]) -> str:
-    for key in ("item_title", "title", "desc", "preview_title"):
-        value = item.get(key)
-        text = normalize_text(value)
-        if text:
-            return text
-    return ""
-
-
-def _pick_desc(item: Dict[str, Any]) -> str:
-    for key in ("desc", "item_title", "title", "preview_title"):
-        value = item.get(key)
-        text = normalize_text(value)
-        if text:
-            return text
-    return ""
-
-
-def _extract_author(item: Dict[str, Any]) -> Dict[str, Optional[str]]:
-    author = item.get("author")
-    if not isinstance(author, dict):
-        author = {}
-
-    author_platform_id = normalize_text(author.get("uid")) or normalize_text(author.get("id")) or normalize_text(item.get("author_user_id"))
-    author_handle = normalize_text(author.get("short_id")) or normalize_text(author.get("nickname"))
-    douyin_sec_uid = normalize_text(author.get("sec_uid"))
-    douyin_aweme_author_id = normalize_text(item.get("author_user_id")) or author_platform_id
-
-    return {
-        "author_handle": author_handle or None,
-        "platform_author_id": author_platform_id or None,
-        "author_platform_id": author_platform_id or None,
-        "douyin_sec_uid": douyin_sec_uid or None,
-        "douyin_aweme_author_id": douyin_aweme_author_id or None,
-        "nickname": normalize_text(author.get("nickname")) or None,
-        "signature": normalize_text(author.get("signature")) or None,
-    }
-
-
-def _extract_metrics(item: Dict[str, Any]) -> Dict[str, int]:
-    statistics = item.get("statistics")
-    if not isinstance(statistics, dict):
-        statistics = {}
-
-    def metric(*keys: str) -> int:
-        for key in keys:
-            value = _safe_int(statistics.get(key))
-            if value is not None:
-                return value
-            value = _safe_int(item.get(key))
-            if value is not None:
-                return value
-        return 0
-
-    return {
-        "digg_count": metric("digg_count"),
-        "comment_count": metric("comment_count"),
-        "collect_count": metric("collect_count"),
-        "share_count": metric("share_count", "forward_count"),
-        "play_count": metric("play_count"),
-    }
-
-
-def _extract_platform_work_id(item: Dict[str, Any]) -> Optional[str]:
-    for key in ("aweme_id", "item_id", "id"):
-        value = item.get(key)
-        if value is None:
-            continue
-        text = normalize_text(value)
-        if text:
-            return text
-
-    statistics = item.get("statistics")
-    if isinstance(statistics, dict):
-        value = statistics.get("aweme_id")
-        text = normalize_text(value)
-        if text:
-            return text
-    return None
-
-
-def _extract_create_time_sec(item: Dict[str, Any]) -> Optional[int]:
-    for key in ("create_time", "aweme_create_time"):
-        value = _safe_int(item.get(key))
-        if value is not None and value > 0:
-            return value
-    return None
-
-
-def _pick_first_url(value: Any) -> Optional[str]:
-    if isinstance(value, str):
-        text = value.strip()
-        return text or None
-    if isinstance(value, list):
-        for item in value:
-            if isinstance(item, str) and item.strip():
-                return item.strip()
-    if isinstance(value, dict):
-        for key in ("url_list", "url", "uri"):
-            hit = _pick_first_url(value.get(key))
-            if hit:
-                return hit
-    return None
-
-
-def _extract_cover_image(item: Dict[str, Any]) -> Optional[str]:
-    # prefer video-level covers
-    video = item.get("video") if isinstance(item.get("video"), dict) else {}
-    for key in ("cover", "origin_cover", "dynamic_cover"):
-        hit = _pick_first_url(video.get(key))
-        if hit:
-            return hit
-
-    # fallback to item-level covers
-    for key in ("cover", "origin_cover", "dynamic_cover"):
-        hit = _pick_first_url(item.get(key))
-        if hit:
-            return hit
-
-    return None
-
-
-def _clean_tag_text(value: Any) -> str:
-    text = normalize_text(value)
-    if not text:
-        return ""
-    text = text.strip().strip("#")
-    return text
-
-
-def _append_tag(raw: Any, output: List[str], seen: set) -> None:
-    tag = _clean_tag_text(raw)
-    if not tag or tag in seen:
-        return
-    seen.add(tag)
-    output.append(tag)
-
-
-def _extract_tags_from_container(value: Any, output: List[str], seen: set) -> None:
-    if isinstance(value, str):
-        text = value.strip()
-        if not text:
-            return
-        if text.startswith("{") or text.startswith("["):
-            try:
-                parsed = json.loads(text)
-                _extract_tags_from_container(parsed, output, seen)
-                return
-            except Exception:
-                pass
-        for part in re.split(r"[,，\s]+", text):
-            _append_tag(part, output, seen)
-        return
-
-    if isinstance(value, list):
-        for item in value:
-            _extract_tags_from_container(item, output, seen)
-        return
-
-    if isinstance(value, dict):
-        for key in ("hashtag_name", "cha_name", "name", "tag_name", "topic_name", "hashtag"):
-            _append_tag(value.get(key), output, seen)
-
-
-def _extract_douyin_tags(item: Dict[str, Any]) -> List[str]:
-    tags: List[str] = []
-    seen: set = set()
-
-    for value in deep_find_all(item, ["text_extra"]):
-        _extract_tags_from_container(value, tags, seen)
-
-    for value in deep_find_all(item, ["cha_list"]):
-        _extract_tags_from_container(value, tags, seen)
-
-    for value in deep_find_all(item, ["hashtag"]):
-        _extract_tags_from_container(value, tags, seen)
-
-    for common_flags in deep_find_all(item, ["common_flags"]):
-        if not isinstance(common_flags, str):
-            continue
-        try:
-            parsed = json.loads(common_flags)
-        except Exception:
-            continue
-        _extract_tags_from_container(parsed.get("hashtag"), tags, seen)
-
-    for text_field in (normalize_text(item.get("caption")), normalize_text(item.get("desc"))):
-        if not text_field:
-            continue
-        for match in re.findall(r"#([^#\s]+)", text_field):
-            _append_tag(match, tags, seen)
-
-    return tags
-
-
-def _u1_fetch_one_video(
-    *,
-    base_url: str,
-    token: str,
-    share_url: str,
-    app_timeout_ms: int,
-    web_timeout_ms: int,
-) -> Dict[str, Any]:
-    app_response = call_json_api(
-        base_url=base_url,
-        path=APP_ENDPOINT,
-        token=token,
-        method="GET",
-        timeout_ms=app_timeout_ms,
-        params={"share_url": share_url},
-    )
-    app_response["_endpoint"] = APP_ENDPOINT
-    if app_response.get("ok"):
-        return app_response
-
-    app_response["fallback_trigger_reason"] = (
-        "primary_timeout_retry_exhausted" if app_response.get("timeout_retry_exhausted") else "primary_non_timeout_failure"
-    )
-    web_response = call_json_api(
-        base_url=base_url,
-        path=WEB_ENDPOINT,
-        token=token,
-        method="GET",
-        timeout_ms=web_timeout_ms,
-        params={"share_url": share_url},
-    )
-    web_response["_endpoint"] = WEB_ENDPOINT
-    web_response["_app_failed"] = app_response
-    web_response["fallback_trigger_reason"] = app_response.get("fallback_trigger_reason")
-    return web_response
-
-
-def _trace_step(
-    *,
-    step: str,
-    endpoint: Optional[str] = None,
-    response: Optional[Dict[str, Any]] = None,
-    extra: Optional[Dict[str, Any]] = None,
-) -> Dict[str, Any]:
-    payload: Dict[str, Any] = {"step": step}
-    if endpoint:
-        payload["endpoint"] = endpoint
-    if response is not None:
-        payload.update(
-            {
-                "ok": response.get("ok"),
-                "status_code": response.get("status_code"),
-                "request_id": response.get("request_id"),
-                "error_reason": response.get("error_reason"),
-                "rate_limit_wait_ms": response.get("rate_limit_wait_ms", 0),
-                "retry_attempt": response.get("retry_attempt", 0),
-                "fallback_trigger_reason": response.get("fallback_trigger_reason"),
-            }
-        )
-    if extra:
-        payload.update(extra)
-    return payload
-
-
-def _build_missing_fields(
-    *,
-    title: str,
-    desc: str,
-    platform_work_id: Optional[str],
-    video_down_url: Optional[str],
-    author: Dict[str, Optional[str]],
-) -> List[Dict[str, str]]:
-    missing: List[Dict[str, str]] = []
-
-    def _append(field: str) -> None:
-        missing.append({"field": field, "reason": "missing_metadata"})
-
-    if not normalize_text(title):
-        _append("title")
-    if not normalize_text(desc):
-        _append("desc")
-    if not normalize_text(platform_work_id):
-        _append("platform_work_id")
-    if not normalize_text(video_down_url):
-        _append("video_down_url")
-
-    author_key_map = {
-        "author_handle": ("author_handle",),
-        "platform_author_id": ("platform_author_id", "author_platform_id"),
-        "douyin_sec_uid": ("douyin_sec_uid",),
-        "douyin_aweme_author_id": ("douyin_aweme_author_id",),
-    }
-    for field, aliases in author_key_map.items():
-        if not any(normalize_text(author.get(alias)) for alias in aliases):
-            _append(field)
-
-    return missing
-
-
-def _build_result(
-    *,
-    source_input: Dict[str, Optional[str]],
-    platform_work_id: Optional[str],
-    title: str,
-    desc: str,
-    duration_ms: Optional[int],
-    video_down_url: Optional[str],
-    author: Dict[str, Optional[str]],
-    metrics: Dict[str, int],
-    tags: List[str],
-    is_video: bool,
-    video_type_reason: str,
-    raw_content: str,
-    confidence: str,
-    error_reason: Optional[str],
-    extract_trace: List[Dict[str, Any]],
-    fallback_trace: List[Dict[str, Any]],
-    request_id: Optional[str],
-    u2_task_id: Optional[str],
-    u2_task_status: str,
-    u2_gate_reason: str,
-    create_time_sec: Optional[int] = None,
-    cover_image: Optional[str] = None,
-    asr_source: str = "fallback_none",
-) -> Dict[str, Any]:
-    summary_block = summarize_content(raw_content, source="douyin:single-video-low-quality")
-    insights = list(summary_block.get("insights", []))
-    insights.extend(
-        [
-            f"platform_work_id={platform_work_id or ''}",
-            f"is_video={is_video}",
-            f"video_type_reason={video_type_reason}",
-            f"u2_gate_reason={u2_gate_reason}",
-        ]
-    )
-
-    endpoint_list = [
-        step.get("endpoint")
-        for step in extract_trace
-        if isinstance(step, dict) and isinstance(step.get("endpoint"), str)
-    ]
-
-    payload: Dict[str, Any] = {
-        "platform": "douyin",
-        "content_kind": "single_video",
-        "source": source_input,
-        "platform_work_id": platform_work_id,
-        "title": title,
-        "desc": desc,
-        "duration_ms": duration_ms,
-        "create_time_sec": create_time_sec,
-        "cover_image": cover_image,
-        "video_down_url": video_down_url,
-        "author": author,
-        "author_handle": author.get("author_handle"),
-        "platform_author_id": author.get("platform_author_id") or author.get("author_platform_id"),
-        "douyin_sec_uid": author.get("douyin_sec_uid"),
-        "douyin_aweme_author_id": author.get("douyin_aweme_author_id"),
-        "digg_count": metrics.get("digg_count", 0),
-        "comment_count": metrics.get("comment_count", 0),
-        "collect_count": metrics.get("collect_count", 0),
-        "share_count": metrics.get("share_count", 0),
-        "play_count": metrics.get("play_count", 0),
-        "tags": tags or [],
-        "is_video": is_video,
-        "video_type_reason": video_type_reason,
-        "u2_task_id": u2_task_id,
-        "u2_task_status": u2_task_status,
-        "raw_content": raw_content,
-        "asr_source": asr_source,
-        "summary": summary_block.get("summary", ""),
-        "insights": insights,
-        "confidence": confidence,
-        "error_reason": error_reason,
-        "missing_fields": _build_missing_fields(
-            title=title,
-            desc=desc,
-            platform_work_id=platform_work_id,
-            video_down_url=video_down_url,
-            author=author,
-        ),
-        "extract_trace": extract_trace,
-        "fallback_trace": fallback_trace,
-        "request_id": request_id,
-        "endpoint_list": endpoint_list,
-    }
-    return payload
-
-
-def run_douyin_single_video(
-    *,
-    input_value: Optional[str],
-    share_url: Optional[str],
-    env_file: Optional[str],
-    api_key_env: str,
-    base_url: Optional[str],
-    timeout_ms: Optional[int],
-    app_timeout_ms: Optional[int],
-    web_timeout_ms: Optional[int],
-    poll_interval_sec: float,
-    max_polls: int,
-    u2_submit_max_retries: int,
-    u2_submit_backoff_ms: int,
-    write_card: bool,
-    card_type: str,
-    card_root: Optional[str],
-    content_kind: str = "single_video",
-    storage_config: Optional[Dict[str, Any]] = None,
-    allow_process_env: bool = False,
-    persist_output: bool = True,
-    progress: Optional[ProgressReporter] = None,
-) -> Dict[str, Any]:
-    if not write_card or not persist_output:
-        raise ValueError(
-            f"fixed_pipeline_requires_full_persistence:douyin:{content_kind}:write_card={bool(write_card)}:persist_output={bool(persist_output)}"
-        )
-
-    source_input = _normalize_input(input_value, share_url)
-    if progress is not None:
-        progress.started(stage="single_video.workflow", message="douyin single_video workflow started")
-    if not source_input.get("share_url"):
-        result = _build_result(
-            source_input=source_input,
-            platform_work_id=None,
-            title="",
-            desc="",
-            duration_ms=None,
-            video_down_url=None,
-            author={"author_handle": None, "author_platform_id": None, "douyin_sec_uid": None, "douyin_aweme_author_id": None, "nickname": None, "signature": None},
-            metrics={
-                "digg_count": 0,
-                "comment_count": 0,
-                "collect_count": 0,
-                "share_count": 0,
-                "play_count": 0,
-            },
-            tags=[],
-            is_video=False,
-            video_type_reason="missing_share_url",
-            raw_content="",
-            confidence="low",
-            error_reason="missing_share_url",
-            extract_trace=[],
-            fallback_trace=[],
-            request_id=None,
-            u2_task_id=None,
-            u2_task_status="UNKNOWN",
-            u2_gate_reason="not_started",
-        )
-        if write_card:
-            result["card_write"] = write_benchmark_card(
-                payload=result,
-                platform="douyin",
-                card_type=card_type,
-                card_root=card_root,
-                content_kind=content_kind,
-                storage_config=storage_config,
-            )
-        return _finalize_result(
-            result=result,
-            source_input=source_input,
-            platform_work_id=None,
-            storage_config=storage_config,
-            persist_output=persist_output,
-        )
-
-    runtime = resolve_runtime(
-        env_file=env_file,
-        api_key_env=api_key_env,
-        base_url=base_url,
-        timeout_ms=timeout_ms,
-        allow_process_env=allow_process_env,
-    )
-
-    app_timeout = int(app_timeout_ms or runtime["timeout_ms"])
-    web_timeout = int(web_timeout_ms or runtime["timeout_ms"])
-
-    trace: List[Dict[str, Any]] = []
-
-    if progress is not None:
-        progress.progress(stage="single_video.fetch", message="fetching douyin single_video payload")
-    one_video_response = _u1_fetch_one_video(
-        base_url=runtime["base_url"],
-        token=runtime["token"],
-        share_url=source_input["share_url"] or "",
-        app_timeout_ms=app_timeout,
-        web_timeout_ms=web_timeout,
-    )
-
-    app_failed = one_video_response.get("_app_failed")
-    if app_failed:
-        trace.append(
-            _trace_step(
-                step="u1_fetch_one_video_primary",
-                endpoint=APP_ENDPOINT,
-                response=app_failed,
-                extra={"timeout_ms": app_timeout},
-            )
-        )
-
-    trace.append(
-        _trace_step(
-            step="u1_fetch_one_video_effective",
-            endpoint=one_video_response.get("_endpoint"),
-            response=one_video_response,
-            extra={
-                "app_timeout_ms": app_timeout,
-                "web_timeout_ms": web_timeout,
-            },
-        )
-    )
-
-    if not one_video_response.get("ok"):
-        error_ctx = resolve_trace_error_context(
-            responses=[one_video_response],
-            extract_trace=trace,
-            default_error_reason="u1_fetch_one_video_failed",
-        )
-        result = _build_result(
-            source_input=source_input,
-            platform_work_id=None,
-            title="",
-            desc="",
-            duration_ms=None,
-            video_down_url=None,
-            author={"author_handle": None, "author_platform_id": None, "douyin_sec_uid": None, "douyin_aweme_author_id": None, "nickname": None, "signature": None},
-            metrics={
-                "digg_count": 0,
-                "comment_count": 0,
-                "collect_count": 0,
-                "share_count": 0,
-                "play_count": 0,
-            },
-            tags=[],
-            is_video=False,
-            video_type_reason="u1_failed",
-            raw_content="",
-            confidence="low",
-            error_reason=error_ctx.get("error_reason"),
-            extract_trace=trace,
-            fallback_trace=error_ctx.get("fallback_trace", []),
-            request_id=error_ctx.get("request_id"),
-            u2_task_id=None,
-            u2_task_status="UNKNOWN",
-            u2_gate_reason="u1_failed",
-        )
-        if write_card:
-            result["card_write"] = write_benchmark_card(
-                payload=result,
-                platform="douyin",
-                card_type=card_type,
-                card_root=card_root,
-                content_kind=content_kind,
-                storage_config=storage_config,
-            )
-        return _finalize_result(
-            result=result,
-            source_input=source_input,
-            platform_work_id=None,
-            storage_config=storage_config,
-            persist_output=persist_output,
-        )
-
-    aweme_detail = _extract_aweme_detail(one_video_response.get("data"))
-    if not aweme_detail:
-        error_ctx = resolve_trace_error_context(
-            responses=[one_video_response],
-            extract_trace=trace,
-            default_error_reason="aweme_detail_missing",
-        )
-        result = _build_result(
-            source_input=source_input,
-            platform_work_id=None,
-            title="",
-            desc="",
-            duration_ms=None,
-            video_down_url=None,
-            author={"author_handle": None, "author_platform_id": None, "douyin_sec_uid": None, "douyin_aweme_author_id": None, "nickname": None, "signature": None},
-            metrics={
-                "digg_count": 0,
-                "comment_count": 0,
-                "collect_count": 0,
-                "share_count": 0,
-                "play_count": 0,
-            },
-            tags=[],
-            is_video=False,
-            video_type_reason="aweme_detail_missing",
-            raw_content="",
-            confidence="low",
-            error_reason=error_ctx.get("error_reason"),
-            extract_trace=trace,
-            fallback_trace=error_ctx.get("fallback_trace", []),
-            request_id=error_ctx.get("request_id"),
-            u2_task_id=None,
-            u2_task_status="UNKNOWN",
-            u2_gate_reason="aweme_detail_missing",
-        )
-        if write_card:
-            result["card_write"] = write_benchmark_card(
-                payload=result,
-                platform="douyin",
-                card_type=card_type,
-                card_root=card_root,
-                content_kind=content_kind,
-                storage_config=storage_config,
-            )
-        return _finalize_result(
-            result=result,
-            source_input=source_input,
-            platform_work_id=None,
-            storage_config=storage_config,
-            persist_output=persist_output,
-        )
-
-    video_type_info = normalize_douyin_video_type(aweme_detail)
-    duration_ms = _normalize_duration_ms(aweme_detail)
-    platform_work_id = _extract_platform_work_id(aweme_detail)
-    title = _pick_title(aweme_detail)
-    desc = _pick_desc(aweme_detail)
-    author = _extract_author(aweme_detail)
-    metrics = _extract_metrics(aweme_detail)
-    tags = _extract_douyin_tags(aweme_detail)
-    create_time_sec = _extract_create_time_sec(aweme_detail)
-    cover_image = _extract_cover_image(aweme_detail)
-
-    video_obj = aweme_detail.get("video") if isinstance(aweme_detail.get("video"), dict) else {}
-    down_url_selection = select_low_quality_video_url(video_obj)
-    video_down_url = down_url_selection.get("video_down_url")
-
-    trace.append(
-        {
-            "step": "video_type_normalization",
-            "is_video": video_type_info.get("is_video"),
-            "video_type_reason": video_type_info.get("video_type_reason"),
-            "matched_field": video_type_info.get("matched_field"),
-            "duration_ms": duration_ms,
-        }
-    )
-
-    trace.append(
-        {
-            "step": "select_low_quality_video_url",
-            "selection_reason": down_url_selection.get("selection_reason"),
-            "selected_from": down_url_selection.get("selected_from"),
-            "video_down_url": video_down_url,
-            "min_bit_rate": down_url_selection.get("min_bit_rate"),
-            "download_url_count": down_url_selection.get("download_url_count"),
-            "bit_rate_count": down_url_selection.get("bit_rate_count"),
-        }
-    )
-
-    can_u2 = bool(video_type_info.get("is_video")) and bool(duration_ms and duration_ms > 13000 and duration_ms <= 1800000)
-    can_u2 = can_u2 and bool(video_down_url)
-
-    if not video_type_info.get("is_video"):
-        gate_reason = "skip:not_video"
-    elif not duration_ms:
-        gate_reason = "skip:duration_missing"
-    elif duration_ms <= 13000:
-        gate_reason = "skip:duration_too_short"
-    elif duration_ms > 1800000:
-        gate_reason = "skip:duration_too_long"
-    elif not video_down_url:
-        gate_reason = "skip:video_down_url_missing"
-    else:
-        gate_reason = "pass"
-
-    trace.append(
-        {
-            "step": "u2_gate",
-            "can_u2": can_u2,
-            "gate_reason": gate_reason,
-            "rule": "is_video && 13000<duration_ms<=1800000 && video_down_url_present",
-            "is_video": bool(video_type_info.get("is_video")),
-            "video_type_reason": video_type_info.get("video_type_reason"),
-            "duration_ms": duration_ms,
-            "video_down_url_present": bool(video_down_url),
-        }
-    )
-
-    raw_content = ""
-    error_reason: Optional[str] = None
-    u2_task_id: Optional[str] = None
-    u2_task_status = "SKIPPED"
-    submit_response: Dict[str, Any] = {}
-    poll_result: Dict[str, Any] = {}
-
-    if can_u2 and video_down_url:
-        if progress is not None:
-            progress.progress(
-                stage="single_video.u2",
-                message="starting douyin u2 submit",
-                data={"video_down_url_present": True},
-            )
-        submit_bundle = submit_u2_asr_with_retry(
-            base_url=runtime["base_url"],
-            token=runtime["token"],
-            timeout_ms=runtime["timeout_ms"],
-            video_url=video_down_url,
-            max_retries=u2_submit_max_retries,
-            backoff_ms=u2_submit_backoff_ms,
-        )
-        submit_response = submit_bundle["submit_response"]
-        u2_task_id = submit_bundle.get("task_id")
-
-        trace.append(
-            _trace_step(
-                step="u2_submit_transcription",
-                endpoint=U2_SUBMIT_ENDPOINT,
-                response=submit_response,
-                extra={
-                    "task_id": u2_task_id,
-                    "video_down_url": video_down_url,
-                    "final_submit_status": submit_bundle.get("final_submit_status"),
-                },
-            )
-        )
-
-        trace.append(
-            {
-                "step": "u2_submit_retry_chain",
-                "final_submit_status": submit_bundle.get("final_submit_status"),
-                "retries_config": {
-                    "u2_submit_max_retries": max(0, int(u2_submit_max_retries)),
-                    "u2_submit_backoff_ms": max(0, int(u2_submit_backoff_ms)),
-                },
-                "attempts": submit_bundle.get("retry_chain", []),
-            }
-        )
-
-        if not submit_response.get("ok") or not u2_task_id:
-            if progress is not None:
-                progress.failed(
-                    stage="single_video.u2",
-                    message="douyin u2 submit failed",
-                    data={"error_reason": submit_response.get("error_reason") or "u2_submit_failed_or_missing_task_id"},
-                )
-            error_reason = submit_response.get("error_reason") or "u2_submit_failed_or_missing_task_id"
-            u2_task_status = "UNKNOWN"
-        else:
-            if progress is not None:
-                progress.progress(stage="single_video.u2", message="polling douyin u2 task", data={"task_id": u2_task_id})
-            poll_result = poll_u2_task(
-                base_url=runtime["base_url"],
-                token=runtime["token"],
-                timeout_ms=runtime["timeout_ms"],
-                task_id=u2_task_id,
-                poll_interval_sec=poll_interval_sec,
-                max_polls=max_polls,
-            )
-            u2_task_status = poll_result.get("task_status") or "UNKNOWN"
-            raw_content = poll_result.get("transcript_text", "") if poll_result.get("ok") else ""
-            error_reason = poll_result.get("error_reason")
-
-            trace.append(
-                {
-                    "step": "u2_poll_task",
-                    "endpoint": "/api/u2/v1/tasks/{task_id}",
-                    "task_id": u2_task_id,
-                    "ok": poll_result.get("ok"),
-                    "task_status": u2_task_status,
-                    "request_id": poll_result.get("request_id"),
-                    "error_reason": poll_result.get("error_reason"),
-                    "attempts": len(poll_result.get("trace", [])),
-                }
-            )
-            if progress is not None:
-                (progress.done if poll_result.get("ok") else progress.failed)(
-                    stage="single_video.u2",
-                    message="douyin u2 polling finished" if poll_result.get("ok") else "douyin u2 polling failed",
-                    data={"task_id": u2_task_id, "task_status": u2_task_status, "attempts": len(poll_result.get("trace", []))},
-                )
-
-    error_ctx = resolve_trace_error_context(
-        responses=[poll_result, submit_response, one_video_response],
-        extract_trace=trace,
-        explicit_error_reason=error_reason,
-        explicit_request_id=poll_result.get("request_id") or submit_response.get("request_id") or one_video_response.get("request_id"),
-    )
-    error_reason = error_ctx.get("error_reason")
-
-    if error_reason:
-        confidence = "low"
-    elif can_u2 and raw_content:
-        confidence = "high"
-    elif can_u2 and not raw_content:
-        confidence = "medium"
-    else:
-        confidence = "medium"
-
-    result = _build_result(
-        source_input=source_input,
-        platform_work_id=platform_work_id,
-        title=title,
-        desc=desc,
-        duration_ms=duration_ms,
-        create_time_sec=create_time_sec,
-        cover_image=cover_image,
-        video_down_url=video_down_url,
-        author=author,
-        metrics=metrics,
-        tags=tags,
-        is_video=bool(video_type_info.get("is_video")),
-        video_type_reason=str(video_type_info.get("video_type_reason") or ""),
-        raw_content=raw_content,
-        confidence=confidence,
-        error_reason=error_reason,
-        extract_trace=trace,
-        fallback_trace=error_ctx.get("fallback_trace", []),
-        request_id=error_ctx.get("request_id"),
-        u2_task_id=u2_task_id,
-        u2_task_status=u2_task_status,
-        u2_gate_reason=gate_reason,
-        asr_source="u2" if raw_content else "fallback_none",
-    )
-
-    if write_card:
-        if progress is not None:
-            progress.progress(stage="single_video.card_write", message="writing douyin single_video card")
-        result["card_write"] = write_benchmark_card(
-            payload=result,
-            platform="douyin",
-            card_type=card_type,
-            card_root=card_root,
-            content_kind=content_kind,
-            storage_config=storage_config,
-        )
-
-    finalized = _finalize_result(
-        result=result,
-        source_input=source_input,
-        platform_work_id=platform_work_id,
-        storage_config=storage_config,
-        persist_output=persist_output,
-    )
-    if progress is not None:
-        final_event = progress.failed if finalized.get("error_reason") else progress.done
-        final_event(
-            stage="single_video.workflow",
-            message="douyin single_video workflow finished" if not finalized.get("error_reason") else "douyin single_video workflow failed",
-            data={
-                "request_id": finalized.get("request_id"),
-                "card_write_ok": bool((finalized.get("card_write") or {}).get("ok")),
-                "output_persist_ok": bool((finalized.get("output_persist") or {}).get("ok")),
-            },
-        )
-    return finalized
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Run Douyin single-video low-quality extraction")
-    parser.add_argument("input", nargs="?", default=None, help="Douyin share URL")
-    parser.add_argument("--share-url", default=None, help="Douyin share URL")
-    parser.add_argument("--config", default=None, help="Runtime config YAML path")
-    parser.add_argument("--env-file", default=None, help="Optional env file path")
-    parser.add_argument("--allow-process-env", action="store_true", help="Allow process env to override .env/.env.local")
-    parser.add_argument("--api-key-env", default=None, help="API key env variable name")
-    parser.add_argument("--base-url", default=None, help="Tikomni base URL")
-    parser.add_argument("--timeout-ms", type=int, default=None, help="Global timeout ms")
-    parser.add_argument("--app-timeout-ms", type=int, default=None, help="APP endpoint timeout ms (optional)")
-    parser.add_argument("--web-timeout-ms", type=int, default=None, help="WEB endpoint timeout ms (optional)")
-    parser.add_argument("--poll-interval-sec", type=float, default=3.0, help="U2 poll interval seconds")
-    parser.add_argument("--max-polls", type=int, default=30, help="Max U2 polls")
-    parser.add_argument(
-        "--u2-submit-max-retries",
-        type=int,
-        default=2,
-        help="Max retries for retriable U2 submit failures",
-    )
-    parser.add_argument(
-        "--u2-submit-backoff-ms",
-        type=int,
-        default=1500,
-        help="Base backoff ms for retriable U2 submit failures (exponential)",
-    )
-    parser.add_argument("--card-type", choices=["work", "author", "author_sample_work"], default="work", help="Primary card type")
-    parser.add_argument("--content-kind", default="single_video", help="Routing kind, e.g. single_video/author_home/author_analysis")
-    parser.add_argument("--card-root", default=None, help="Card root (absolute); falls back to TIKOMNI_CARD_ROOT when writing cards")
-    args = parser.parse_args()
-
-    config, _ = load_tikomni_config(
-        args.config,
-        env_file=args.env_file,
-        allow_process_env=args.allow_process_env,
-    )
-    resolved_env_file = args.env_file or config_get(config, "runtime.env_file", None)
-    api_key_env = args.api_key_env or config_get(config, "runtime.auth_env_key", "TIKOMNI_API_KEY")
-    base_url = args.base_url or config_get(config, "runtime.base_url", None)
-    timeout_ms = args.timeout_ms if args.timeout_ms is not None else config_get(config, "runtime.timeout_ms", None)
-
-    try:
-        result = run_douyin_single_video(
-            input_value=args.input,
-            share_url=args.share_url,
-            env_file=resolved_env_file,
-            api_key_env=api_key_env,
-            base_url=base_url,
-            timeout_ms=timeout_ms,
-            app_timeout_ms=args.app_timeout_ms,
-            web_timeout_ms=args.web_timeout_ms,
-            poll_interval_sec=args.poll_interval_sec,
-            max_polls=args.max_polls,
-            u2_submit_max_retries=args.u2_submit_max_retries,
-            u2_submit_backoff_ms=args.u2_submit_backoff_ms,
-            write_card=True,
-            card_type=args.card_type,
-            card_root=args.card_root,
-            content_kind=args.content_kind,
-            storage_config=config,
-            allow_process_env=args.allow_process_env,
-            persist_output=True,
-        )
-    except ValueError as error:
-        result = {
-            "platform": "douyin",
-            "raw_content": "",
-            "summary": "",
-            "insights": ["source=douyin:single-video-low-quality", "runtime_not_ready"],
-            "confidence": "low",
-            "error_reason": str(error),
-            "missing_fields": [],
-            "extract_trace": [],
-            "fallback_trace": [],
-            "request_id": None,
-            "endpoint_list": [],
-        }
-
-    write_json_stdout(result)
-    raise SystemExit(0 if not result.get("error_reason") else 1)
-
-
-if __name__ == "__main__":
-    main()