kd-engine 1.0.0__py3-none-any.whl

ytk/cli.py

@@ -0,0 +1,1281 @@
+"""Command-line interface (T43.1).
+
+Surface (v2.0)::
+
+    ytk extract URL [--format ...] [--config TOML] [--fixture-content JSON]
+                    [--fixture-transcript JSON] [--refresh] [--platform NAME]
+                    [--content-type video|image_note] [--out DIR] ...
+    ytk batch run --urls-file FILE [--format ...] [--resume] [--refresh] ...
+    ytk platforms [--json]
+    ytk probe URL [--json] [--platform NAME] [--content-type TYPE]
+    ytk doctor [--offline] [--platform all|NAME] [--strict]
+    ytk cache status|clear
+    ytk skill build ...
+    ytk merge ...
+
+Routing: a plain YouTube link (no ``--fixture-content``) keeps the historical
+v1 pipeline byte-for-byte (A01 compatibility); TikTok / Douyin / Bilibili /
+Xiaohongshu and every ``--fixture-content`` run use the v2 multi-platform
+pipeline.  Exit codes: 0 for COMPLETE / PARTIAL / NO_KNOWLEDGE, 1 for
+BLOCKED / FAILED / every-requested-format-not-applicable
+(``OUTPUTS_NOT_APPLICABLE``).
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+import typer
+from pydantic import ValidationError
+
+from ytk.config import AppSettings, ConfigFileError
+from ytk.doctor import DoctorService, format_doctor_report
+from ytk.dotenv import load_dotenv
+from ytk.errors import UserFacingError
+from ytk.logging import configure_logging
+from ytk.models.source import SUPPORTED_PLATFORMS, AccessContext, ContentRef
+from ytk.pipeline.orchestrator import build_default_pipeline, load_bundle
+from ytk.pipeline.state import ArtifactStore, derive_overall_status
+
+LOGGER = logging.getLogger(__name__)
+
+app = typer.Typer(
+    help="Knowledge Distiller (萃知): distill videos and image notes into "
+    "evidence-linked knowledge and reusable AI-agent skills."
+)
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            installed_version = version("kd-engine")
+        except PackageNotFoundError:
+            installed_version = "1.0.0"  # source checkout; synchronized with pyproject.toml
+        typer.echo(f"kd-engine {installed_version}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _bootstrap_env(
+    version: bool = typer.Option(
+        False, "--version", callback=_show_version, is_eager=True,
+        help="Show the installed kd-engine version and exit.",
+    ),
+) -> None:
+    """Load the project .env for every entry point (console script included).
+
+    ``python -m ytk`` loads it in ``__main__``; the installed ``ytk`` console
+    script calls ``app`` directly, so without this callback the two entry points
+    silently diverge (A32).  ``YTK_NO_DOTENV=1`` is honoured before any read.
+    """
+    try:
+        from ytk.dotenv import dotenv_disabled, load_dotenv
+
+        if dotenv_disabled():
+            return
+        load_dotenv(Path(__file__).resolve().parent.parent.parent / ".env")
+    except Exception:  # pragma: no cover - env loading must never break the CLI
+        return
+skill_app = typer.Typer(help="Build skills from extraction artifacts.")
+batch_app = typer.Typer(help="Batch-process content links from multiple platforms.")
+cache_app = typer.Typer(help="Manage caches (transcript v1 + layered v2).")
+
+app.add_typer(skill_app, name="skill")
+app.add_typer(batch_app, name="batch")
+app.add_typer(cache_app, name="cache")
+
+V2_VALIDATOR_VERSION = "v2-1"  # kept local: importing pipeline.v2 here would load v2 deps eagerly
+
+
+# --------------------------------------------------------------------------- #
+# Environment loading (historical behaviour preserved; NO_DOTENV honoured)
+# --------------------------------------------------------------------------- #
+def _load_env_file(path: Path) -> None:
+    """Load the project ``.env`` (best effort) before the CLI runs.
+
+    Root cause fix 2026-08-18: the ybs cron ran ``python -m ytk extract`` from an
+    arbitrary cwd where ``YTK_MINIMAX_API_KEY`` was NOT exported — the renderer
+    silently fell back to the deterministic document.  Loading the project
+    ``.env`` at CLI entry makes every caller get the same keys as the ``.env``
+    author intended.  The loader lives in :mod:`ytk.dotenv` so ``YTK_NO_DOTENV=1``
+    is honoured *before* the file is opened (offline tests / diagnostics).
+    """
+    load_dotenv(path)
+
+
+# --------------------------------------------------------------------------- #
+# Cache commands
+# --------------------------------------------------------------------------- #
+@cache_app.command("status")
+def cache_status() -> None:
+    """Show cache location, entry count, size, and per-video detail."""
+    from ytk.ingestion.transcript_cache import TranscriptCache
+
+    settings = AppSettings.load()
+    cache = TranscriptCache(
+        cache_dir=settings.transcript_cache_dir,
+        enabled=settings.transcript_cache_enabled,
+    )
+    stats = cache.stats()
+    size_kb = stats["total_bytes"] / 1024
+    print(f"cache dir:   {stats['dir']}")
+    print(f"enabled:     {settings.transcript_cache_enabled}")
+    print(f"entries:     {stats['entries']}  ({size_kb:.1f} KB)")
+    for entry in stats["detail"]:
+        langs = ",".join(entry["languages"]) or "?"
+        print(
+            f"  {entry['video_id']}  {entry['bytes'] / 1024:8.1f} KB  "
+            f"src={entry['source']}  lang={langs}  segments={entry['segments']}"
+        )
+    _print_v2_cache_stats(settings)
+
+
+def _print_v2_cache_stats(settings: AppSettings) -> None:
+    try:
+        from ytk.cache import LayeredCache
+
+        v2 = LayeredCache(root=settings.cache_dir)
+        stats = v2.stats()
+    except Exception:  # noqa: BLE001 - cache introspection must never break the CLI
+        return
+    size_mb = stats["total_bytes"] / (1024 * 1024)
+    print(f"v2 cache:    {stats['root']}")
+    print(f"v2 entries:  {stats['entries']}  ({size_mb:.2f} MB, max {stats['max_bytes']} bytes)")
+    for namespace, bucket in stats["namespaces"].items():
+        if bucket["entries"]:
+            print(f"  {namespace}: {bucket['entries']} entr(ies), {bucket['bytes'] / 1024:.1f} KB")
+
+
+@cache_app.command("clear")
+def cache_clear(
+    v2: bool = typer.Option(
+        False, "--v2", help="Also clear the v2 layered cache (media/subtitle/asr/ocr/generation)."
+    ),
+) -> None:
+    """Delete every cached transcript bundle (safe: cache is regenerable)."""
+    from ytk.ingestion.transcript_cache import TranscriptCache
+
+    settings = AppSettings.load()
+    cache = TranscriptCache(
+        cache_dir=settings.transcript_cache_dir,
+        enabled=settings.transcript_cache_enabled,
+    )
+    removed = cache.clear()
+    print(f"removed {removed} cached transcript(s)")
+    if v2:
+        from ytk.cache import LayeredCache
+
+        removed_v2 = LayeredCache(root=settings.cache_dir, enabled=True).clear()
+        print(f"removed {removed_v2} v2 cache entr(ies)")
+
+
+# --------------------------------------------------------------------------- #
+# extract
+# --------------------------------------------------------------------------- #
+@app.command()
+def extract(
+    url: str,
+    out: Path = typer.Option(Path("./outputs"), "--out"),
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        help="Comma-separated outputs. Omit for per-platform defaults "
+        "(YouTube keeps its legacy default: json,md,skill; new platforms: json,md).",
+    ),
+    fixture_transcript: Path | None = typer.Option(None, "--fixture-transcript"),
+    fixture_content: Path | None = typer.Option(
+        None,
+        "--fixture-content",
+        "--acquired-content",
+        help="JSON descriptor of recorded content or a measured browser video acquisition; browser media identity, bytes and streams are revalidated.",
+    ),
+    proxy: str | None = typer.Option(
+        None,
+        "--proxy",
+        help="HTTP/HTTPS proxy URL (e.g. http://127.0.0.1:7890)",
+    ),
+    cookies: Path | None = typer.Option(
+        None,
+        "--cookies",
+        help="Path to Netscape formatted YouTube cookies file for yt-dlp.",
+    ),
+    cookies_from_browser: str | None = typer.Option(
+        None,
+        "--cookies-from-browser",
+        help="Browser cookies source for yt-dlp, e.g. chrome:default",
+    ),
+    coarse_atoms: bool = typer.Option(
+        False,
+        "--coarse-atoms",
+        help="When a source yields no structured knowledge, emit explicitly "
+             "labelled low-confidence segment summaries instead of NO_KNOWLEDGE. "
+             "Off by default: never silently turns an empty ledger into a fake one.",
+    ),
+    doc_language: str | None = typer.Option(
+        None,
+        "--doc-language",
+        help="Output language for the 'doc' format. One of: zh, en, auto. "
+             "When 'auto' (or unset), the skill samples $LANG/$LC_ALL — defaults to 'zh'.",
+    ),
+    with_reviewer_scaffolding: bool = typer.Option(
+        False,
+        "--with-reviewer-scaffolding",
+        help="Append an A/B/C reference list, image-asset manifest, and "
+             "closing CTA to the `doc` output. Designed to lift the `doc` "
+             "across the 4-model review rubric when downstream penflow will "
+             "reuse the doc as a knowledge source.",
+    ),
+    skip_existing: bool = typer.Option(
+        False, "--skip-existing",
+        help="Exit 0 without reprocessing when the output dir already has "
+             "knowledge.json (cron idempotence for single-video reruns).",
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", help="Optional TOML config file (explicit field priority)."
+    ),
+    refresh: bool = typer.Option(
+        False, "--refresh",
+        help="Re-resolve the source and re-acquire only material whose digest changed; "
+             "never forgets an unresolved remote submission.",
+    ),
+    platform: str | None = typer.Option(
+        None, "--platform", help="Force the platform (youtube|tiktok|douyin|bilibili|xiaohongshu)."
+    ),
+    content_type: str | None = typer.Option(
+        None, "--content-type", help="Force the content type (video|image_note)."
+    ),
+    asr_model: str | None = typer.Option(None, "--asr-model", help="Explicitly prepared local faster-whisper model directory; never downloads during extraction."),
+    asr_language: str | None = typer.Option(None, "--asr-language", help="Audio language code, e.g. zh or en; auto enables language detection."),
+    asr_beam_size: int | None = typer.Option(None, "--asr-beam-size", min=1, max=20),
+    asr_hotwords: str | None = typer.Option(None, "--asr-hotwords", help="Optional domain vocabulary, not corrected answers or a transcript."),
+    asr_initial_prompt: str | None = typer.Option(None, "--asr-initial-prompt", help="Optional audio context; never a supplied reference transcript."),
+    debug: bool = typer.Option(False, "--debug"),
+) -> None:
+    try:
+        formats = _parse_formats(format) if format is not None else None
+        _validate_doc_language(doc_language)
+        platform_name = _normalise_platform(platform)
+        content_type_name = _normalise_content_type(content_type)
+        if fixture_transcript is not None and fixture_content is not None:
+            raise typer.BadParameter(
+                "--fixture-transcript and --fixture-content are mutually exclusive"
+            )
+        configure_logging(debug=debug)
+        settings = _build_settings(
+            config_path=config,
+            proxy=proxy,
+            cookies=cookies,
+            cookies_from_browser=cookies_from_browser,
+            debug=debug,
+            platform=platform_name,
+            asr_model=asr_model,
+            asr_language=asr_language,
+            asr_beam_size=asr_beam_size,
+            asr_hotwords=asr_hotwords,
+            asr_initial_prompt=asr_initial_prompt,
+        )
+        route = _extract_route(
+            url,
+            fixture_content=fixture_content,
+            platform=platform_name,
+            content_type=content_type_name,
+        )
+        if route == "v1":
+            _extract_legacy(
+                url=url,
+                out=out,
+                formats=formats,
+                fixture_transcript=fixture_transcript,
+                doc_language=doc_language,
+                with_reviewer_scaffolding=with_reviewer_scaffolding,
+                skip_existing=skip_existing,
+                settings=settings,
+            )
+            return
+        if fixture_transcript is not None:
+            raise typer.BadParameter(
+                "--fixture-transcript is only supported for YouTube; use --fixture-content "
+                "for the multi-platform pipeline"
+            )
+        _extract_v2(
+            url=url,
+            out=out,
+            settings=settings,
+            formats=formats,
+            fixture_content=fixture_content,
+            refresh=refresh,
+            doc_language=doc_language,
+            platform=platform_name,
+            content_type=content_type_name,
+            skip_existing=skip_existing,
+            coarse_atoms=coarse_atoms,
+        )
+    except typer.BadParameter:
+        raise
+    except typer.Exit:
+        raise
+    except (UserFacingError, ConfigFileError, ValidationError) as exc:
+        _exit_with_runtime_error(str(exc))
+    except Exception as exc:
+        _exit_with_runtime_error(f"Extraction failed: {exc}")
+
+
+def _extract_legacy(
+    *,
+    url: str,
+    out: Path,
+    formats: set[str] | None,
+    fixture_transcript: Path | None,
+    doc_language: str | None,
+    with_reviewer_scaffolding: bool,
+    skip_existing: bool,
+    settings: AppSettings,
+) -> None:
+    """The historical YouTube path — kept byte-for-byte (A01)."""
+    legacy_formats = formats if formats is not None else _parse_formats("json,md,skill")
+    if skip_existing:
+        if "json" not in legacy_formats:
+            # knowledge.json is only written when json ∈ formats; without it the
+            # flag would be a silent no-op forever (adversarial review 2026-08-15).
+            typer.echo(
+                "WARNING: --skip-existing requires the 'json' format "
+                "(knowledge.json is the completion marker); without it "
+                "nothing is ever skipped — add json to --format",
+                err=True,
+            )
+        elif _existing_output_matches(out, url) and (
+            "doc" not in legacy_formats or _verified_doc(out)
+        ):
+            typer.echo(f"skip-existing: {out / 'knowledge.json'} matches url — nothing to do")
+            return
+    pipeline = build_default_pipeline(settings=settings)
+    pipeline.run(
+        url=url,
+        output_dir=out,
+        formats=legacy_formats,
+        fixture_transcript=fixture_transcript,
+        doc_language=doc_language,
+        with_reviewer_scaffolding=with_reviewer_scaffolding,
+    )
+    if "doc" in legacy_formats and (out / ".knowledge-doc-status.json").exists() and not _verified_doc(out):
+        typer.echo(
+            "WARNING: knowledge document is FALLBACK or unverified; see .knowledge-doc-status.json",
+            err=True,
+        )
+
+
+def _extract_v2(
+    *,
+    url: str,
+    out: Path,
+    settings: AppSettings,
+    formats: set[str] | None,
+    fixture_content: Path | None,
+    refresh: bool,
+    doc_language: str | None,
+    platform: str | None,
+    content_type: str | None,
+    skip_existing: bool,
+    coarse_atoms: bool = False,
+) -> None:
+    # An external descriptor can change independently of its URL. Revalidate
+    # identity, copied bytes and streams before trusting any earlier outputs.
+    if skip_existing and fixture_content is None and not refresh and _v2_outputs_complete(
+        out, formats, expected_source_id=_requested_v2_source_id(url, fixture_content),
+        settings=settings, doc_language=doc_language,
+    ):
+        typer.echo(f"skip-existing: {out} already has verified outputs — nothing to do")
+        return
+    result = _run_v2(
+        url=url,
+        out=out,
+        settings=settings,
+        formats=formats,
+        fixture_content=fixture_content,
+        refresh=refresh,
+        doc_language=doc_language,
+        platform=platform,
+        content_type=content_type,
+        coarse_atoms=coarse_atoms,
+    )
+    outcome, reasons = _v2_outcome(result, out, formats)
+    if outcome == "COMPLETE":
+        return
+    if outcome == "PARTIAL":
+        message = "; ".join(reasons) if reasons else "some formats incomplete"
+        typer.echo(f"PARTIAL: {message}")
+        return
+    if outcome == "NO_KNOWLEDGE":
+        typer.echo("NO_KNOWLEDGE: content complete but no knowledge atoms were extracted")
+        return
+    for reason in reasons:
+        typer.echo(reason, err=True)
+    if outcome == "OUTPUTS_NOT_APPLICABLE":
+        typer.echo(f"{outcome}: no requested output format is applicable", err=True)
+    else:
+        typer.echo(f"{outcome or 'BLOCKED'}: extraction did not complete", err=True)
+    raise typer.Exit(code=1)
+
+
+def _build_v2_pipeline(*, settings: AppSettings | None = None,
+                       coarse_atoms: bool = False) -> Any:
+    """Factory used by the CLI; lazy so the v1-only path never imports v2."""
+    from ytk.pipeline.v2 import build_v2_pipeline
+
+    return build_v2_pipeline(settings=settings, coarse_atoms=coarse_atoms)
+
+
+def _run_v2(
+    *,
+    url: str,
+    out: Path,
+    settings: AppSettings,
+    formats: set[str] | None,
+    fixture_content: Path | None,
+    refresh: bool,
+    doc_language: str | None,
+    platform: str | None,
+    content_type: str | None,
+    coarse_atoms: bool = False,
+) -> Any:
+    pipeline = _build_v2_pipeline(settings=settings, coarse_atoms=coarse_atoms)
+    kwargs: dict[str, Any] = {
+        "output_dir": out,
+        "formats": formats,
+        "fixture_content": fixture_content,
+        "refresh": refresh,
+        "platform": platform,
+        "content_type": content_type,
+    }
+    if doc_language is not None:
+        parameters: Any
+        try:
+            parameters = inspect.signature(pipeline.run).parameters
+        except (TypeError, ValueError):  # pragma: no cover - exotic callables
+            parameters = {}
+        if "doc_language" in parameters:
+            kwargs["doc_language"] = doc_language
+    return pipeline.run(url, **kwargs)
+
+
+def _v2_outcome(
+    result: Any, out: Path, formats: set[str] | None
+) -> tuple[str, list[str]]:
+    """Map a V2RunResult (or manifest fallback) to the CLI outcome vocabulary."""
+    outcome_value = _result_field(result, "outcome")
+    reasons = [str(reason) for reason in (_result_field(result, "reasons") or [])]
+    format_status = dict(_result_field(result, "format_status") or {})
+    outcome = str(outcome_value).upper() if outcome_value is not None else ""
+    if not outcome:
+        store = ArtifactStore(out)
+        manifest = store.read_manifest()
+        if manifest is not None:
+            overall, derived_reasons = derive_overall_status(
+                manifest, requested=sorted(formats) if formats else None
+            )
+            outcome = overall
+            reasons = reasons or derived_reasons
+            format_status = format_status or {
+                fmt: manifest.outputs[fmt].status for fmt in manifest.outputs
+            }
+    if not outcome:
+        outcome = "COMPLETE"
+    if outcome == "NO_KNOWLEDGE":
+        return "NO_KNOWLEDGE", reasons
+    if format_status and all(status == "not_applicable" for status in format_status.values()):
+        return "OUTPUTS_NOT_APPLICABLE", reasons
+    return outcome, reasons
+
+
+def _result_field(result: Any, name: str) -> Any:
+    if isinstance(result, dict):
+        return result.get(name)
+    return getattr(result, name, None)
+
+
+def _requested_v2_source_id(url: str, fixture_content: Path | None) -> str | None:
+    try:
+        if fixture_content is not None:
+            from ytk.pipeline.v2 import MultiPlatformPipeline
+
+            return MultiPlatformPipeline._load_fixture_content(fixture_content).source.source_id
+        return resolve_source_safe(url).source_id
+    except (UserFacingError, OSError, ValueError):
+        return None
+
+
+def _v2_outputs_complete(
+    out: Path, formats: set[str] | None, *, expected_source_id: str | None = None,
+    settings: AppSettings | None = None, doc_language: str | None = None,
+) -> bool:
+    try:
+        store = ArtifactStore(out)
+        manifest = store.read_manifest()
+        if manifest is None:
+            return False
+        if expected_source_id is None or manifest.source_ids != [expected_source_id]:
+            return False
+        content_cache = getattr(manifest, "content_cache", None)
+        if settings is not None and isinstance(content_cache, dict):
+            from ytk.pipeline.v2 import MultiPlatformPipeline
+
+            if content_cache.get("processing_fingerprint") != MultiPlatformPipeline(settings=settings)._processing_fingerprint():
+                return False
+        requested = formats if formats is not None else set(manifest.outputs)
+        if not requested:
+            return False
+        for fmt in requested:
+            if settings is not None and fmt != "json" and fmt in manifest.outputs and manifest.outputs[fmt].status == "complete":
+                from ytk.pipeline.v2 import render_request_fingerprint
+
+                platform = expected_source_id.split(":", 1)[0]
+                if getattr(manifest, "render_fingerprints", {}).get(fmt) != render_request_fingerprint(fmt, settings, doc_language, platform):
+                    return False
+            skip, _reason = store.should_skip_format(
+                fmt,
+                request_fingerprint=manifest.request_fingerprint,
+                evidence_fingerprint=manifest.source_revision,
+                checker_version=(
+                    manifest.outputs[fmt].checker_version
+                    if fmt in manifest.outputs
+                    else None
+                ),
+                validator_version=V2_VALIDATOR_VERSION,
+                source_revision=manifest.source_revision,
+            )
+            if not skip:
+                return False
+        return True
+    except Exception:  # noqa: BLE001 - resume probe must degrade to "run it"
+        return False
+
+
+def _extract_route(
+    url: str,
+    *,
+    fixture_content: Path | None,
+    platform: str | None,
+    content_type: str | None,
+) -> str:
+    """``"v1"`` for legacy YouTube, ``"v2"`` for everything else."""
+    if fixture_content is not None:
+        return "v2"
+    if platform is not None:
+        return "v1" if platform == "youtube" else "v2"
+    try:
+        ref = resolve_source_safe(url, content_type=content_type)
+    except (UserFacingError, ValueError):
+        return "v2"  # let the v2 pipeline raise the actionable error
+    return "v1" if ref.platform == "youtube" else "v2"
+
+
+def resolve_source_safe(value: str, *, content_type: str | None = None) -> ContentRef:
+    from ytk.ingestion.resolver import resolve_source
+
+    return resolve_source(value, content_type=content_type)  # type: ignore[arg-type]
+
+
+@app.command("import-file")
+def import_file_cmd(
+    input_file: Path,
+    out: Path = typer.Option(..., "--out"),
+    source_url: str | None = typer.Option(None, "--source-url", help="Optional original video URL; pairing is user asserted, never live verification."),
+    subtitle_file: Path | None = typer.Option(None, "--subtitle-file", help="SRT/VTT/JSON3 subtitles accompanying a local video."),
+    visual_notes: Path | None = typer.Option(None, "--visual-notes", help="Observations bound to exported frame hashes and timestamps."),
+    format: str = typer.Option("json,md", "--format"),
+    resume: bool = typer.Option(False, "--resume", help="Explicitly resume an output owned by this same source."),
+    coarse_atoms: bool = typer.Option(False, "--coarse-atoms"),
+) -> None:
+    """Extract from an owned local video, audio or timed subtitle file without platform access."""
+    import tempfile
+    from ytk.ingestion.local_import import ImportInputError, check_output, prepare_import
+
+    try:
+        if not resume:
+            check_output(out)
+        payload = prepare_import(input_file, source_url=source_url, subtitle_file=subtitle_file, visual_notes=visual_notes)
+        source = ContentRef.model_validate(payload["source"])
+        check_output(out, resume=resume, source_id=source.source_id,
+                     import_fingerprint=payload["metadata"]["import_fingerprint"])
+        settings = _build_settings()
+        # A stored provider key is not consent to upload an imported private file.
+        settings = settings.model_copy(update={"cloud_text_enabled": False, "cloud_media_enabled": False})
+        formats = _parse_formats(format)
+        with tempfile.TemporaryDirectory(prefix="kd-user-import-") as directory:
+            descriptor = Path(directory) / "input.json"
+            descriptor.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+            result = _run_v2(url=source.canonical_url, out=out, settings=settings, formats=formats,
+                             fixture_content=descriptor, refresh=False, doc_language=None,
+                             platform=None, content_type="video", coarse_atoms=coarse_atoms)
+        outcome, reasons = _v2_outcome(result, out, formats)
+        typer.echo(json.dumps({"outcome": outcome, "source_id": source.source_id,
+                              "acquisition_mode": "user-import", "output": str(out),
+                              "reasons": reasons}, ensure_ascii=False))
+        if outcome not in {"COMPLETE", "PARTIAL", "NO_KNOWLEDGE"}:
+            raise typer.Exit(code=1)
+    except typer.Exit:
+        raise
+    except ImportInputError as exc:
+        typer.echo(json.dumps({"outcome": "BLOCKED", "reason_code": exc.code,
+                              "message": str(exc), "recovery": exc.action}, ensure_ascii=False))
+        raise typer.Exit(code=1) from None
+    except (OSError, ValueError, UserFacingError) as exc:
+        from ytk.logging import redact_payload
+        typer.echo(json.dumps({"outcome": "BLOCKED", "reason_code": getattr(exc, "reason_code", "IMPORT_FAILED"),
+                              "message": redact_payload(str(exc)),
+                              "recovery": "检查本地依赖与模型，保留原文件后用新目录重试；模型缺失时按连接器README显式准备。"}, ensure_ascii=False))
+        raise typer.Exit(code=1) from None
+
+
+@app.command("frames")
+def frames_cmd(
+    input_file: Path,
+    out: Path = typer.Option(..., "--out"),
+    max_frames: int = typer.Option(8, "--max-frames", min=1, max=12),
+    at: list[float] | None = typer.Option(None, "--at", help="Specific seconds to inspect; repeat up to 12 times in increasing order."),
+) -> None:
+    """Export real timestamped frames for a model/user to inspect; never invent frame observations."""
+    from ytk.ingestion.video_frames import export_frames
+    try:
+        manifest = export_frames(input_file, out, max_frames=max_frames, timestamps=at)
+        typer.echo(json.dumps({"outcome": "VISUAL_REVIEW_REQUIRED", "manifest": str(out / "frames-manifest.json"),
+                              "frames": len(manifest["frames"]),
+                              "next": "在WorkBuddy读取实际帧，写入含video_sha256、frames_manifest、reviewer与observations[{frame_index,text}]的JSON，然后 import-file --visual-notes；只代表抽样帧，不能声称看完全片。"}, ensure_ascii=False))
+    except (OSError, ValueError, UserFacingError) as exc:
+        from ytk.logging import redact_payload
+        typer.echo(json.dumps({"outcome": "BLOCKED", "reason_code": getattr(exc, "reason_code", "FRAME_EXPORT_FAILED"),
+                              "message": redact_payload(str(exc))}, ensure_ascii=False))
+        raise typer.Exit(code=1) from None
+
+
+# --------------------------------------------------------------------------- #
+# skill / merge (unchanged)
+# --------------------------------------------------------------------------- #
+
+def _load_bundle_for_skill(path: Path):
+    """Load a knowledge bundle of any supported schema version for `skill build`."""
+    from ytk.models.migrations import load_bundle_any
+
+    try:
+        return load_bundle_any(path)
+    except UserFacingError:
+        raise
+    except FileNotFoundError as exc:
+        raise UserFacingError(f"Knowledge bundle not found: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise UserFacingError(f"Knowledge bundle is not valid JSON: {path}") from exc
+
+
+@skill_app.command("build")
+def skill_build(
+    knowledge_json: Path,
+    out: Path = typer.Option(..., "--out"),
+    package_kind: str = typer.Option("generic", "--package-kind"),
+    target: str = typer.Option("workbuddy", "--target",
+        help="Output spec: 'workbuddy' (default) or 'generic'."),
+) -> None:
+    if target not in ("workbuddy", "generic"):
+        raise typer.BadParameter(f"--target 只接受 workbuddy|generic，收到 {target!r}")
+    try:
+        # v2-aware: the default pipeline writes schema_version 2 with atom_id /
+        # evidence_ids / topics, which the v1-only loader rejects outright.
+        # models.migrations.load_bundle_any already exists and the SkillBuilder
+        # coerces both shapes, so only the entry point was wired to the old one.
+        bundle = _load_bundle_for_skill(knowledge_json)
+        pipeline = build_default_pipeline()
+        pipeline.skill_builder.build(bundle, out, package_kind=package_kind, target=target)
+    except typer.BadParameter:
+        raise
+    except (UserFacingError, ValidationError) as exc:
+        _exit_with_runtime_error(str(exc))
+    except Exception as exc:
+        _exit_with_runtime_error(f"Skill build failed: {exc}")
+
+
+@app.command("merge")
+def merge_cmd(
+    input_dir: Path = typer.Argument(..., help="Directory containing video output subdirectories"),
+    output: Path = typer.Option("./merged/knowledge.json", "--out", help="Output path for merged knowledge.json"),
+) -> None:
+    try:
+        from ytk.commands.merge import merge_knowledge_directories
+
+        result = merge_knowledge_directories(input_dir, output)
+        typer.echo(f"Merged {result['source_count']} videos, {len(result['atoms'])} unique atoms → {output}")
+    except Exception as exc:
+        _exit_with_runtime_error(f"Merge failed: {exc}")
+
+
+# --------------------------------------------------------------------------- #
+# batch run
+# --------------------------------------------------------------------------- #
+@batch_app.command("run")
+def batch_run(
+    urls_file: Path | None = typer.Option(
+        None,
+        "--urls-file",
+        help="Path to file with one URL per line.",
+    ),
+    out: Path = typer.Option(Path("./outputs"), "--out"),
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        help="Comma-separated outputs applied to every source. Omit for per-source "
+        "defaults (YouTube: json,md,skill; other platforms: json,md).",
+    ),
+    fixture_transcript: Path | None = typer.Option(None, "--fixture-transcript"),
+    fixture_content: Path | None = typer.Option(
+        None, "--fixture-content", help="JSON descriptor of already-acquired content (offline v2 path)."
+    ),
+    proxy: str | None = typer.Option(
+        None,
+        "--proxy",
+        help="HTTP/HTTPS proxy URL (e.g. http://127.0.0.1:7890)",
+    ),
+    cookies: Path | None = typer.Option(
+        None,
+        "--cookies",
+        help="Path to Netscape formatted YouTube cookies file for yt-dlp.",
+    ),
+    cookies_from_browser: str | None = typer.Option(
+        None,
+        "--cookies-from-browser",
+        help="Browser cookies source for yt-dlp, e.g. chrome:default",
+    ),
+    search: str | None = typer.Option(
+        None,
+        "--search",
+        help="YouTube search query to generate URL list instead of reading from file.",
+    ),
+    doc_language: str | None = typer.Option(
+        None,
+        "--doc-language",
+        help="Output language for the 'doc' format. One of: zh, en, auto. "
+             "When 'auto' (or unset), the skill samples $LANG/$LC_ALL — defaults to 'zh'.",
+    ),
+    with_reviewer_scaffolding: bool = typer.Option(
+        False,
+        "--with-reviewer-scaffolding",
+        help="Append an A/B/C reference list, image-asset manifest, and "
+             "closing CTA to the `doc` output of every video in the batch. "
+             "Applied per-video (same flag as `extract`).",
+    ),
+    resume: bool = typer.Option(
+        False, "--resume",
+        help="Reuse verified outputs per format (fingerprint/revision/digest/validator) "
+             "and skip only what is genuinely complete. Interrupted batches resume.",
+    ),
+    refresh: bool = typer.Option(
+        False, "--refresh",
+        help="Re-resolve and re-acquire changed material; never forgets an unresolved "
+             "remote submission, never reuses stale outputs.",
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", help="Optional TOML config file (explicit field priority)."
+    ),
+    debug: bool = typer.Option(False, "--debug"),
+) -> None:
+    try:
+        if not urls_file and not search:
+            _exit_with_runtime_error("Provide --urls-file or --search.")
+            return
+        formats_explicit = format is not None
+        formats = _parse_formats(format) if format is not None else None
+        _validate_doc_language(doc_language)
+        if fixture_transcript is not None and fixture_content is not None:
+            raise typer.BadParameter(
+                "--fixture-transcript and --fixture-content are mutually exclusive"
+            )
+        configure_logging(debug=debug)
+        settings = _build_settings(
+            config_path=config,
+            proxy=proxy,
+            cookies=cookies,
+            cookies_from_browser=cookies_from_browser,
+            debug=debug,
+            platform="youtube",
+        )
+
+        if search:
+            from ytk.ingestion.search import YouTubeSearchService
+
+            svc = YouTubeSearchService()
+            results = svc.search(search, max_results=10)
+            raw_urls = svc.get_urls(results)
+            if not raw_urls:
+                typer.echo(f"No results found for: {search}", err=True)
+                raise typer.Exit(code=1)
+            typer.echo(f"Found {len(raw_urls)} videos for: {search}")
+        else:
+            try:
+                raw_urls = urls_file.read_text(encoding="utf-8").splitlines()  # type: ignore[union-attr]
+            except OSError as exc:
+                _exit_with_runtime_error(f"Failed to read URLs file: {exc}")
+                return
+
+        urls = [line.strip() for line in raw_urls if line.strip()]
+        report = _run_batch(
+            urls,
+            out=out,
+            settings=settings,
+            formats=formats,
+            formats_explicit=formats_explicit,
+            fixture_transcript=fixture_transcript,
+            fixture_content=fixture_content,
+            doc_language=doc_language,
+            with_reviewer_scaffolding=with_reviewer_scaffolding,
+            resume=resume,
+            refresh=refresh,
+        )
+        typer.echo("")
+        typer.echo("=" * 40)
+        for line in report.summary_lines():
+            typer.echo(line)
+        if report.exit_code:
+            raise typer.Exit(code=report.exit_code)
+    except typer.BadParameter:
+        raise
+    except typer.Exit:
+        raise
+    except (UserFacingError, ConfigFileError, ValidationError) as exc:
+        _exit_with_runtime_error(str(exc))
+    except Exception as exc:
+        _exit_with_runtime_error(f"Batch run failed: {exc}")
+
+
+def _run_batch(
+    urls: list[str],
+    *,
+    out: Path,
+    settings: AppSettings,
+    formats: set[str] | None,
+    formats_explicit: bool,
+    fixture_transcript: Path | None,
+    fixture_content: Path | None,
+    doc_language: str | None,
+    with_reviewer_scaffolding: bool,
+    resume: bool,
+    refresh: bool,
+):
+    from ytk.batch.runner import run_batch
+
+    return run_batch(
+        urls,
+        out_root=out,
+        settings=settings,
+        formats=formats,
+        formats_explicit=formats_explicit,
+        fixture_transcript=fixture_transcript,
+        fixture_content=fixture_content,
+        doc_language=doc_language,
+        with_reviewer_scaffolding=with_reviewer_scaffolding,
+        resume=resume,
+        refresh=refresh,
+        legacy_pipeline_factory=build_default_pipeline,
+        v2_pipeline_factory=_build_v2_pipeline,
+        doc_verifier=_verified_doc,
+        echo=typer.echo,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# platforms / probe
+# --------------------------------------------------------------------------- #
+@app.command("platforms")
+def platforms_cmd(
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON only."),
+    config: Path | None = typer.Option(None, "--config"),
+) -> None:
+    """Show the five platform capabilities and local configuration state."""
+    try:
+        settings = _build_settings(config_path=config)
+        payload = _platforms_payload(settings)
+        if json_output:
+            typer.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+            return
+        typer.echo(f"{'platform':14} {'enabled':8} {'provider':10} {'formats':16} notes")
+        for name, info in payload.items():
+            notes = []
+            if info["requires_service"]:
+                notes.append(
+                    "service configured" if info["service_configured"] else "service NOT configured"
+                )
+            if info["cookies_configured"]:
+                notes.append("cookies")
+            if info["proxy_configured"]:
+                notes.append("proxy")
+            typer.echo(
+                f"{name:14} {str(info['enabled']):8} {info['provider']:10} "
+                f"{','.join(info['default_formats']):16} {'; '.join(notes)}"
+            )
+    except typer.Exit:
+        raise
+    except (UserFacingError, ConfigFileError, ValidationError) as exc:
+        _exit_with_runtime_error(str(exc))
+    except Exception as exc:
+        _exit_with_runtime_error(f"platforms failed: {exc}")
+
+
+def _platforms_payload(settings: AppSettings) -> dict[str, dict[str, Any]]:
+    from ytk.ingestion.registry import PlatformRegistry
+    from ytk.pipeline.v2 import _builtin_adapters
+
+    # Reflect what this build can actually acquire with: YouTube/TikTok/Bilibili
+    # need no sidecar; Douyin needs DTK and XHS has an optional sidecar.
+    registry = PlatformRegistry.default(adapters=_builtin_adapters(settings))
+    payload: dict[str, dict[str, Any]] = {}
+    for name, capabilities in registry.capabilities_matrix().items():
+        ready = bool(capabilities.get("adapter_configured")) and (
+            not capabilities.get("requires_service") or bool(settings.base_url_for(name))  # type: ignore[arg-type]
+        )
+        payload[name] = {
+            **capabilities,
+            "acquisition_ready": ready,
+            "live_access_verified": False,
+            "readiness_scope": "local_configuration_only",
+            "enabled": settings.is_platform_enabled(name),  # type: ignore[arg-type]
+            "service_configured": bool(settings.base_url_for(name)),  # type: ignore[arg-type]
+            "cookies_configured": bool(settings.cookies_file_for(name)),  # type: ignore[arg-type]
+            "proxy_configured": bool(settings.proxy_for(name)),  # type: ignore[arg-type]
+            "cloud_text_enabled": settings.cloud_allowed(name, "text"),  # type: ignore[arg-type]
+            "cloud_media_enabled": settings.cloud_allowed(name, "media"),  # type: ignore[arg-type]
+        }
+    return payload
+
+
+@app.command("probe")
+def probe_cmd(
+    url: str,
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON only."),
+    platform: str | None = typer.Option(None, "--platform"),
+    content_type: str | None = typer.Option(
+        None, "--content-type", help="video|image_note"
+    ),
+    config: Path | None = typer.Option(None, "--config"),
+) -> None:
+    """Resolve a URL/share text to platform identity + capabilities (no download)."""
+    try:
+        platform_name = _normalise_platform(platform)
+        content_type_name = _normalise_content_type(content_type)
+        settings = _build_settings(config_path=config, platform=platform_name)
+        ref, identity_source = _probe_identity(
+            url,
+            settings=settings,
+            platform=platform_name,
+            content_type=content_type_name,
+        )
+        capabilities = _platforms_payload(settings).get(ref.platform, {})
+        payload = {
+            "platform": ref.platform,
+            "source_id": ref.source_id,
+            "content_type": ref.content_type,
+            "canonical_url": ref.canonical_url,
+            "variant_id": ref.variant_id,
+            "identity_source": identity_source,
+            "capabilities": capabilities,
+        }
+        if json_output:
+            typer.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+            return
+        typer.echo(f"platform:       {payload['platform']}")
+        typer.echo(f"source_id:      {payload['source_id']}")
+        typer.echo(f"content_type:   {payload['content_type']}")
+        typer.echo(f"canonical_url:  {payload['canonical_url']}")
+        typer.echo(f"identity:       {payload['identity_source']}")
+        typer.echo(
+            f"capabilities:   provider={capabilities.get('provider')} "
+            f"formats={','.join(capabilities.get('default_formats') or [])} "
+            f"subtitle={capabilities.get('subtitle')} asr={capabilities.get('asr')} "
+            f"ocr={capabilities.get('ocr')} service={capabilities.get('service_name')}"
+        )
+    except typer.BadParameter:
+        raise
+    except typer.Exit:
+        raise
+    except (UserFacingError, ConfigFileError, ValidationError) as exc:
+        _exit_with_runtime_error(str(exc))
+    except Exception as exc:
+        _exit_with_runtime_error(f"Probe failed: {exc}")
+
+
+def _probe_identity(
+    url: str,
+    *,
+    settings: AppSettings,
+    platform: str | None,
+    content_type: str | None,
+) -> tuple[ContentRef, str]:
+    """Resolve-only identity: adapter when configured, resolver otherwise."""
+    from ytk.ingestion.resolver import detect_platform, extract_urls
+
+    detected = platform
+    if detected is None:
+        try:
+            candidates = extract_urls(url)
+            detected = detect_platform(candidates[0]) if candidates else None
+        except Exception:  # noqa: BLE001 - detection is best-effort
+            detected = None
+    adapter = None
+    if detected is not None:
+        try:
+            registry = _registry_with_adapters(settings)
+            adapter = registry.get(detected).adapter
+        except Exception:  # noqa: BLE001 - missing adapter is not fatal
+            adapter = None
+    if adapter is not None:
+        context = AccessContext(
+            cookies_file=settings.cookies_file_for(detected),  # type: ignore[arg-type]
+            cookies_from_browser=settings.cookies_from_browser_for(detected),  # type: ignore[arg-type]
+            proxy=settings.proxy_for(detected),  # type: ignore[arg-type]
+        )
+        try:
+            return adapter.resolve(url, context), "adapter"
+        except Exception as exc:  # noqa: BLE001 - fall back to the pure resolver
+            LOGGER.debug("adapter resolve failed, falling back to resolver: %s", exc)
+    return resolve_source_safe(url, content_type=content_type), "resolver"
+
+
+def _registry_with_adapters(settings: AppSettings):
+    try:
+        from ytk.pipeline.v2 import build_v2_pipeline
+
+        return build_v2_pipeline(settings=settings).registry
+    except Exception:  # noqa: BLE001 - probe still works without adapters
+        from ytk.ingestion.registry import PlatformRegistry
+
+        return PlatformRegistry.default()
+
+
+# --------------------------------------------------------------------------- #
+# doctor
+# --------------------------------------------------------------------------- #
+@app.command()
+def doctor(
+    offline: bool = typer.Option(
+        False, "--offline", help="Local-only diagnostics: no network probe, no sidecar contact."
+    ),
+    platform: str = typer.Option(
+        "all", "--platform", help="all|youtube|tiktok|douyin|bilibili|xiaohongshu"
+    ),
+    strict: bool = typer.Option(
+        False, "--strict", help="Exit non-zero when offline local checks are incomplete."
+    ),
+) -> None:
+    try:
+        platform_filter = _normalise_platform(platform, allow_all=True) or "all"
+        report = _doctor_service(offline).run()
+        if offline or platform_filter != "all":
+            report["platforms"] = _platform_diagnostic(platform_filter)
+        typer.echo(format_doctor_report(report))
+        if offline and strict:
+            from ytk.doctor import doctor_report_failures
+
+            failures = doctor_report_failures(report)
+            if failures:
+                typer.echo(
+                    "offline checks incomplete: " + ", ".join(sorted(failures)), err=True
+                )
+                raise typer.Exit(code=1)
+    except typer.BadParameter:
+        raise
+    except typer.Exit:
+        raise
+    except Exception as exc:
+        _exit_with_runtime_error(f"Doctor failed: {exc}")
+
+
+def _doctor_service(offline: bool):
+    """Build DoctorService; tolerate older or monkeypatched constructors."""
+    try:
+        return DoctorService(offline=offline)
+    except TypeError:
+        return DoctorService()
+
+
+def _platform_diagnostic(platform_filter: str) -> dict[str, Any]:
+    settings = AppSettings.load()
+    payload = _platforms_payload(settings)
+    if platform_filter != "all":
+        payload = {platform_filter: payload[platform_filter]}
+    problems: list[str] = []
+    for name, info in payload.items():
+        if not info["enabled"]:
+            continue
+        # A service-backed platform whose sidecar is absent is not "ready": the
+        # adapter exists but every acquire would raise ServiceNotConfiguredError.
+        if not info.get("adapter_configured"):
+            problems.append(name)
+        elif info.get("requires_service") and not info.get("service_configured"):
+            problems.append(name)
+    section: dict[str, Any] = {
+        "status": "ok" if not problems else "partial",
+        "verification": "configured_only",
+        "mode": "offline_local",
+        "note": (
+            "local platform configuration only; no network call, no download. "
+            "A configured platform is NOT verified to be reachable."
+        ),
+        "platforms": payload,
+    }
+    if problems:
+        section["fix_hint"] = (
+            "not configured locally: "
+            + ", ".join(problems)
+            + " | install the optional dependency, set the sidecar base URL, or disable the platform"
+        )
+    return section
+
+
+# --------------------------------------------------------------------------- #
+# shared helpers
+# --------------------------------------------------------------------------- #
+def _existing_output_matches(out: Path, url: str) -> bool:
+    """True when out/knowledge.json exists AND metadata.json records the SAME
+    video as `url` — a different URL pointed at a populated out dir must NOT
+    exit 0 having processed nothing (adversarial review 2026-08-15 finding)."""
+    if not (out / "knowledge.json").exists():
+        return False
+    try:
+        meta = json.loads((out / "metadata.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    from ytk.ingestion.url_parser import parse_youtube_url
+
+    try:
+        want = parse_youtube_url(url).video_id
+    except Exception:
+        return False
+    return meta.get("video_id") == want
+
+
+def _batch_marker_covers(marker: Path, url: str, formats: set[str]) -> bool:
+    """True when the completion marker matches url AND covers all requested
+    formats (a subset marker means an artifact is still missing)."""
+    try:
+        payload = json.loads(marker.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(payload, dict) or payload.get("url") != url:
+        return False
+    return (set(payload.get("formats") or []) >= set(formats)
+            and ("doc" not in formats or _verified_doc(marker.parent)))
+
+
+def _verified_doc(output_dir: Path) -> bool:
+    from ytk.renderers.knowledge_doc_renderer import complete_doc_status
+
+    return complete_doc_status(output_dir)
+
+
+def _parse_formats(value: str) -> set[str]:
+    allowed = {"json", "jsonl", "md", "obsidian", "skill", "summary", "doc"}
+    formats = {item.strip() for item in value.split(",") if item.strip()}
+    if not formats:
+        raise typer.BadParameter("At least one output format is required.")
+    unsupported = formats - allowed
+    if unsupported:
+        supported = ", ".join(sorted(allowed))
+        unknown = ", ".join(sorted(unsupported))
+        raise typer.BadParameter(f"Unsupported format(s): {unknown}. Expected one of: {supported}")
+    return formats
+
+
+def _validate_doc_language(value: str | None) -> None:
+    """Reject obviously invalid --doc-language values early.
+
+    The renderer itself only knows "zh" and "en"; "auto" is a sentinel
+    meaning "use locale / env". Anything else is a user typo.
+    """
+    if value is None:
+        return
+    candidate = value.strip().lower()
+    if candidate in {"zh", "en", "auto"}:
+        return
+    raise typer.BadParameter(
+        f"--doc-language must be one of: zh, en, auto. Got: {value!r}"
+    )
+
+
+def _normalise_platform(value: str | None, *, allow_all: bool = False) -> str | None:
+    if value is None:
+        return None
+    candidate = value.strip().lower()
+    if allow_all and candidate == "all":
+        return "all"
+    if candidate not in SUPPORTED_PLATFORMS:
+        supported = ", ".join(SUPPORTED_PLATFORMS)
+        raise typer.BadParameter(f"--platform must be one of: all, {supported}. Got: {value!r}")
+    return candidate
+
+
+def _normalise_content_type(value: str | None) -> str | None:
+    if value is None:
+        return None
+    candidate = value.strip().lower()
+    if candidate not in {"video", "image_note"}:
+        raise typer.BadParameter(
+            f"--content-type must be one of: video, image_note. Got: {value!r}"
+        )
+    return candidate
+
+
+def _build_settings(
+    *,
+    config_path: Path | None = None,
+    proxy: str | None = None,
+    cookies: Path | None = None,
+    cookies_from_browser: str | None = None,
+    debug: bool = False,
+    platform: str | None = None,
+    asr_model: str | None = None,
+    asr_language: str | None = None,
+    asr_beam_size: int | None = None,
+    asr_hotwords: str | None = None,
+    asr_initial_prompt: str | None = None,
+) -> AppSettings:
+    """Build settings with CLI values as the highest-priority tier."""
+    overrides: dict[str, Any] = {}
+    if proxy:
+        overrides.update(
+            {
+                "transcript_proxy_mode": "generic",
+                "transcript_http_proxy_url": proxy,
+                "transcript_https_proxy_url": proxy,
+            }
+        )
+        if platform and platform != "all":
+            overrides[f"{platform}_proxy"] = proxy
+    if cookies is not None:
+        overrides["yt_dlp_cookies_file"] = str(cookies)
+        if platform and platform != "all":
+            overrides[f"{platform}_cookies_file"] = str(cookies)
+    if cookies_from_browser is not None:
+        overrides["yt_dlp_cookies_from_browser"] = cookies_from_browser
+    if debug:
+        overrides["debug"] = True
+    for key, value in {
+        "asr_model": asr_model,
+        "asr_language": asr_language,
+        "asr_beam_size": asr_beam_size,
+        "asr_hotwords": asr_hotwords,
+        "asr_initial_prompt": asr_initial_prompt,
+    }.items():
+        if value is not None:
+            overrides[key] = None if key == "asr_language" and value == "auto" else value
+    return AppSettings.load(config_path=config_path, overrides=overrides)
+
+
+def _exit_with_runtime_error(message: str) -> None:
+    typer.echo(message, err=True)
+    raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    _load_env_file(Path(__file__).resolve().parent.parent.parent / ".env")
+    app()