@tikomni/skills 0.1.2 → 0.1.4

package/skills/{single-work-analysis/scripts/platform/xiaohongshu/run_xiaohongshu_extract.py → social-media-crawl/scripts/pipelines/run_xiaohongshu_single_work.py}

@@ -20,16 +20,16 @@ import argparse
 import hashlib
 import json
 import re
+import time
 import urllib.parse
 import urllib.request
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from scripts.pipeline.asr.asr_pipeline import run_u2_asr_candidates_with_timeout_retry
-from scripts.core.config_loader import config_get, load_tikomni_config, resolve_storage_paths
-from scripts.core.progress_report import ProgressReporter
-from scripts.core.storage_router import render_output_filename, resolve_json_filename_pattern
+from scripts.core.asr_pipeline import derive_asr_clean_text, run_u2_asr_candidates_with_timeout_retry
+from scripts.core.config_loader import config_get, load_tikomni_config
+from scripts.core.progress_report import ProgressReporter, build_progress_reporter
 from scripts.core.extract_pipeline import build_api_trace, resolve_trace_error_context
 from scripts.core.tikomni_common import (
     call_json_api,
@@ -40,7 +40,11 @@ from scripts.core.tikomni_common import (
     summarize_content,
     write_json_stdout,
 )
-from scripts.writers.write_benchmark_card import write_benchmark_card
+from scripts.writers.write_work_fact_card import (
+    build_work_output_envelope,
+    persist_output_envelope,
+    write_work_fact_card,
+)
 
 APP_V2_VIDEO_ENDPOINT = "/api/u1/v1/xiaohongshu/app_v2/get_video_note_detail"
 APP_V2_IMAGE_ENDPOINT = "/api/u1/v1/xiaohongshu/app_v2/get_image_note_detail"
@@ -49,6 +53,7 @@ APP_V1_ENDPOINT = "/api/u1/v1/xiaohongshu/app/get_note_info"
 WEB_V2_V2_ENDPOINT = "/api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v2"
 WEB_V2_V3_ENDPOINT = "/api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v3"
 WEB_ENDPOINT = "/api/u1/v1/xiaohongshu/web/get_note_info_v7"
+U2_REQUEST_TIMEOUT_CAP_MS = 15000
 U2_GATE_MIN_DURATION_MS = 13000
 U2_GATE_MAX_DURATION_MS = 1800000
 U2_GATE_RULE = "is_video && 13000<duration_ms<=1800000 && video_download_url_present"
@@ -80,6 +85,43 @@ def _to_int_or_none(value: Any) -> Optional[int]:
         return None
 
 
+def _resolve_u2_timeout_ms(timeout_ms: Any) -> int:
+    parsed = _to_int_or_none(timeout_ms)
+    if parsed is None or parsed <= 0:
+        return U2_REQUEST_TIMEOUT_CAP_MS
+    return max(5000, min(parsed, U2_REQUEST_TIMEOUT_CAP_MS))
+
+
+def _report_u2_progress(progress: Optional[ProgressReporter], *, stage: str, event: Dict[str, Any], label: str) -> None:
+    if progress is None:
+        return
+
+    phase = normalize_text(event.get("phase")).lower()
+    state = normalize_text(event.get("state")).lower()
+    payload = {
+        "phase": phase or "poll",
+        "state": state or "",
+        "task_id": event.get("task_id"),
+        "attempt": event.get("attempt"),
+        "task_status": event.get("task_status"),
+        "platform_task_status": event.get("platform_task_status"),
+        "pending_count": event.get("pending_count"),
+        "status_code": event.get("status_code"),
+        "batch_progress": event.get("batch_progress"),
+        "wait_ms": event.get("wait_ms"),
+        "candidate_count": event.get("candidate_count"),
+        "ok": event.get("ok"),
+        "error_reason": event.get("error_reason"),
+        "retriable": event.get("retriable"),
+        "request_id": event.get("request_id"),
+    }
+    message = f"{label} u2 {phase or 'poll'} {state or 'progress'}"
+    if phase == "submit" and state == "heartbeat":
+        progress.heartbeat(stage=stage, message=message, data=payload)
+        return
+    progress.progress(stage=stage, message=message, data=payload)
+
+
 def _evaluate_u2_gate_for_xhs(*, note_content_type: str, duration_ms: Any, video_down_url: Optional[str]) -> Dict[str, Any]:
     content_type = normalize_text(note_content_type).lower()
     is_video = content_type in {"video", "mixed"}
@@ -128,106 +170,6 @@ def _traceable_identifier(source_input: Dict[str, Optional[str]], note_id: Optio
     return f"url-{digest}"
 
 
-def _build_persist_payload(
-    *,
-    result: Dict[str, Any],
-    source_input: Dict[str, Optional[str]],
-    note_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": "xiaohongshu",
-        "content_kind": result.get("content_kind", "note"),
-        "note_id": result.get("note_id") or note_id,
-        "note_content_type": result.get("note_content_type"),
-        "text_source": result.get("text_source"),
-        "request_id": result.get("request_id"),
-        "source": source_input,
-    }
-    return {
-        "meta": {
-            "written_at": written_at.isoformat(timespec="seconds"),
-            "status": status,
-            "platform": "xiaohongshu",
-            "identifier": _traceable_identifier(source_input, note_id),
-        },
-        "summary": summary,
-        "normalized": normalized,
-        "raw": result,
-    }
-
-
-def _persist_output_artifact(
-    *,
-    result: Dict[str, Any],
-    source_input: Dict[str, Optional[str]],
-    note_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, note_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": "xiaohongshu",
-            "card_type": "single_work_result",
-            "author_slug": identifier,
-            "title_slug": identifier,
-            "identifier": identifier,
-            "timestamp": timestamp,
-            "date": date_key,
-            "ext": ".json",
-        },
-        default_filename=f"{timestamp}-xiaohongshu-{identifier}.json",
-        default_ext=".json",
-    )
-    file_path = target_dir / file_name
-
-    payload = _build_persist_payload(
-        result=result,
-        source_input=source_input,
-        note_id=note_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],
@@ -236,14 +178,19 @@ def _finalize_result(
     storage_config: Optional[Dict[str, Any]],
     persist_output: bool,
 ) -> Dict[str, Any]:
-    result["output_persist"] = _persist_output_artifact(
-        result=result,
-        source_input=source_input,
-        note_id=note_id,
+    envelope = build_work_output_envelope(result, platform="xiaohongshu")
+    if "card_write" in result:
+        envelope["card_write"] = result.get("card_write")
+    if not persist_output:
+        envelope["output_persist"] = {"enabled": False, "skipped": True, "reason": "disabled_by_flag"}
+        return envelope
+    envelope["output_persist"] = persist_output_envelope(
+        envelope=envelope,
         storage_config=storage_config,
-        persist_output=persist_output,
+        platform="xiaohongshu",
+        fallback_identifier=note_id or _traceable_identifier(source_input, note_id),
     )
-    return result
+    return envelope
 
 
 def _normalize_input(input_value: Optional[str], share_text: Optional[str], note_id: Optional[str]) -> Dict[str, Optional[str]]:
@@ -760,6 +707,70 @@ def _append_missing_metadata_fields(missing_fields: List[Dict[str, str]], metada
             _append(key)
 
 
+def _empty_timings() -> Dict[str, int]:
+    return {
+        "url_parse_ms": 0,
+        "u1_total_ms": 0,
+        "u2_submit_ms": 0,
+        "u2_poll_ms": 0,
+        "card_write_ms": 0,
+        "llm_analysis_ms": 0,
+        "total_ms": 0,
+    }
+
+
+def _elapsed_ms(started_at: float) -> int:
+    return int((time.perf_counter() - started_at) * 1000)
+
+
+def _http_summary_for_note(response: Dict[str, Any], source_input: Dict[str, Optional[str]]) -> Dict[str, Any]:
+    completeness = response.get("_field_completeness") if isinstance(response.get("_field_completeness"), dict) else {}
+    payload = response.get("data")
+    metadata = _extract_xhs_metadata(
+        payload=payload,
+        source_input=source_input,
+        selected_video_url=None,
+        selected_image_urls=[],
+    ) if response.get("ok") else {}
+    return {
+        "note_id": normalize_text(metadata.get("note_id")) or normalize_text(source_input.get("note_id")),
+        "title_hit": bool(normalize_text(metadata.get("title"))),
+        "author_hit": bool(normalize_text(metadata.get("author"))),
+        "media_present": bool(normalize_text(metadata.get("video_down_url")) or metadata.get("cover_image")),
+        "filled_count": completeness.get("filled_count"),
+        "ratio": completeness.get("ratio"),
+    }
+
+
+def _emit_http_progress(
+    progress: Optional[ProgressReporter],
+    *,
+    stage: str,
+    response: Dict[str, Any],
+    route_label: str,
+    source_input: Dict[str, Optional[str]],
+) -> None:
+    if progress is None:
+        return
+    progress.http_event(
+        stage=stage,
+        endpoint=str(response.get("_endpoint") or route_label),
+        response=response,
+        route_label=route_label,
+        summary=_http_summary_for_note(response, source_input),
+    )
+
+
+def _update_pipeline_status(result: Dict[str, Any]) -> None:
+    card_write = result.get("card_write") if isinstance(result.get("card_write"), dict) else {}
+    deep_analysis = result.get("deep_analysis") if isinstance(result.get("deep_analysis"), dict) else {}
+    result["pipeline_status"] = {
+        "facts_ready": True,
+        "card_ready": bool(card_write.get("ok")),
+        "deep_analysis": deep_analysis.get("status") or "skipped",
+    }
+
+
 def _fetch_sparse_metadata_enrich(
     *,
     base_url: str,
@@ -767,6 +778,7 @@ def _fetch_sparse_metadata_enrich(
     timeout_ms: int,
     source_input: Dict[str, Optional[str]],
     note_id: Optional[str],
+    progress: Optional[ProgressReporter] = None,
 ) -> Dict[str, Any]:
     share_text = source_input.get("share_text")
     resolved_note_id = note_id or source_input.get("note_id") or _extract_note_id_from_share(share_text)
@@ -782,6 +794,7 @@ def _fetch_sparse_metadata_enrich(
         )
         response["_endpoint"] = WEB_V2_V3_ENDPOINT
         response["_route_label"] = "web_v2_v3_sparse_enrich"
+        _emit_http_progress(progress, stage="note.fetch", response=response, route_label="web_v2_v3_sparse_enrich", source_input=source_input)
         return response
 
     if resolved_note_id:
@@ -795,6 +808,7 @@ def _fetch_sparse_metadata_enrich(
         )
         response["_endpoint"] = WEB_V2_V2_ENDPOINT
         response["_route_label"] = "web_v2_v2_sparse_enrich"
+        _emit_http_progress(progress, stage="note.fetch", response=response, route_label="web_v2_v2_sparse_enrich", source_input=source_input)
         return response
 
     return {
@@ -805,7 +819,14 @@ def _fetch_sparse_metadata_enrich(
     }
 
 
-def _fetch_note_info(*, base_url: str, token: str, timeout_ms: int, source_input: Dict[str, Optional[str]]) -> Dict[str, Any]:
+def _fetch_note_info(
+    *,
+    base_url: str,
+    token: str,
+    timeout_ms: int,
+    source_input: Dict[str, Optional[str]],
+    progress: Optional[ProgressReporter] = None,
+) -> Dict[str, Any]:
     attempts: List[Dict[str, Any]] = []
 
     share_text = source_input.get("share_text")
@@ -832,6 +853,7 @@ def _fetch_note_info(*, base_url: str, token: str, timeout_ms: int, source_input
             "missing_core": ["note_id", "title_or_desc", "media"],
             "core_ready": False,
         }
+        _emit_http_progress(progress, stage="note.fetch", response=response, route_label=label, source_input=source_input)
         attempts.append({"label": label, "endpoint": path, "response": response})
         return response
 
@@ -1323,6 +1345,7 @@ def _build_result(
     missing_fields: Optional[List[Dict[str, str]]] = None,
     metadata_fields: Optional[Dict[str, Any]] = None,
     asr_source: Optional[str] = None,
+    timings: Optional[Dict[str, int]] = None,
 ) -> Dict[str, Any]:
     metadata = metadata_fields or {}
     summary_block = summarize_content(raw_content, source=f"xiaohongshu:{text_source}")
@@ -1344,7 +1367,8 @@ def _build_result(
 
     work_modality = "video" if normalize_text(note_content_type).lower() in {"video", "mixed"} else "text"
     caption_raw = normalize_text(metadata.get("caption_raw"))
-    primary_text = raw_content if work_modality == "video" else (caption_raw or raw_content)
+    asr_clean = derive_asr_clean_text(raw_content)
+    primary_text = asr_clean if work_modality == "video" else (caption_raw or raw_content)
     primary_text_source = "asr_clean" if work_modality == "video" else "caption_raw"
     analysis_eligibility = "eligible" if primary_text else "incomplete"
     analysis_exclusion_reason = "" if analysis_eligibility == "eligible" else ("video_asr_unavailable" if work_modality == "video" else "caption_raw_missing")
@@ -1389,6 +1413,8 @@ def _build_result(
         "xhs_sec_token": metadata.get("xhs_sec_token"),
         "downloaded_assets": downloaded_assets,
         "raw_content": raw_content,
+        "asr_raw": raw_content,
+        "asr_clean": asr_clean,
         "primary_text": primary_text,
         "primary_text_source": primary_text_source,
         "analysis_eligibility": analysis_eligibility,
@@ -1401,6 +1427,7 @@ def _build_result(
         "extract_trace": extract_trace,
         "fallback_trace": fallback_trace,
         "request_id": request_id,
+        "timings": dict(timings or {}),
     }
 
 
@@ -1421,6 +1448,7 @@ def run_xiaohongshu_extract(
     u2_timeout_retry_max_retries: int,
     force_u2_fallback: bool,
     write_card: bool,
+    analysis_mode: str,
     card_type: str,
     card_root: Optional[str],
     storage_config: Optional[Dict[str, Any]] = None,
@@ -1428,14 +1456,17 @@ def run_xiaohongshu_extract(
     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:xiaohongshu:note:write_card={bool(write_card)}:persist_output={bool(persist_output)}"
-        )
-
+    workflow_started_at = time.perf_counter()
+    timings = _empty_timings()
+    parse_started_at = time.perf_counter()
     source_input = _normalize_input(input_value, share_text, note_id)
+    timings["url_parse_ms"] = _elapsed_ms(parse_started_at)
     if progress is not None:
-        progress.started(stage="note.workflow", message="xiaohongshu note workflow started")
+        progress.started(
+            stage="note.workflow",
+            message="xiaohongshu note workflow started",
+            data={"analysis_mode": analysis_mode, "write_card": bool(write_card), "persist_output": bool(persist_output)},
+        )
     metadata_fields: Dict[str, Any] = {}
     if not source_input["share_text"] and not source_input["note_id"]:
         result = _build_result(
@@ -1452,23 +1483,32 @@ def run_xiaohongshu_extract(
             u2_task_id=None,
             u2_task_status="UNKNOWN",
             note_content_type="unknown",
-            analysis_mode="none",
+            analysis_mode=analysis_mode,
             selected_video_url=None,
             selected_video_candidates=[],
             selected_image_urls=[],
             downloaded_assets=[],
             missing_fields=[{"field": "share_text_or_note_id", "reason": "missing_input"}],
             metadata_fields=metadata_fields,
+            timings=timings,
         )
         if write_card:
-            result["card_write"] = write_benchmark_card(
+            card_started_at = time.perf_counter()
+            result["card_write"] = write_work_fact_card(
                 payload=result,
                 platform="xiaohongshu",
                 card_type=card_type,
                 card_root=card_root,
                 content_kind="note",
                 storage_config=storage_config,
+                analysis_mode=analysis_mode,
+                progress=progress.child(scope="card_write") if progress is not None else None,
             )
+            timings["card_write_ms"] = _elapsed_ms(card_started_at)
+            timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+        timings["total_ms"] = _elapsed_ms(workflow_started_at)
+        result["timings"] = dict(timings)
+        _update_pipeline_status(result)
         return _finalize_result(
             result=result,
             source_input=source_input,
@@ -1487,6 +1527,7 @@ def run_xiaohongshu_extract(
 
     trace: List[Dict[str, Any]] = []
 
+    u1_started_at = time.perf_counter()
     if progress is not None:
         progress.progress(stage="note.fetch", message="fetching xiaohongshu note payload")
     note_response = _fetch_note_info(
@@ -1494,7 +1535,9 @@ def run_xiaohongshu_extract(
         token=runtime["token"],
         timeout_ms=runtime["timeout_ms"],
         source_input=source_input,
+        progress=progress,
     )
+    timings["u1_total_ms"] = _elapsed_ms(u1_started_at)
 
     attempts = note_response.get("_attempts") or []
     for index, attempt in enumerate(attempts, start=1):
@@ -1548,23 +1591,32 @@ def run_xiaohongshu_extract(
             u2_task_id=None,
             u2_task_status="UNKNOWN",
             note_content_type="unknown",
-            analysis_mode="none",
+            analysis_mode=analysis_mode,
             selected_video_url=None,
             selected_video_candidates=[],
             selected_image_urls=[],
             downloaded_assets=[],
             missing_fields=[{"field": "u1_note_info", "reason": "all_routes_failed"}],
             metadata_fields=metadata_fields,
+            timings=timings,
         )
         if write_card:
-            result["card_write"] = write_benchmark_card(
+            card_started_at = time.perf_counter()
+            result["card_write"] = write_work_fact_card(
                 payload=result,
                 platform="xiaohongshu",
                 card_type=card_type,
                 card_root=card_root,
                 content_kind="note",
                 storage_config=storage_config,
+                analysis_mode=analysis_mode,
+                progress=progress.child(scope="card_write") if progress is not None else None,
             )
+            timings["card_write_ms"] = _elapsed_ms(card_started_at)
+            timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+        timings["total_ms"] = _elapsed_ms(workflow_started_at)
+        result["timings"] = dict(timings)
+        _update_pipeline_status(result)
         return _finalize_result(
             result=result,
             source_input=source_input,
@@ -1589,13 +1641,16 @@ def run_xiaohongshu_extract(
     enrich_payload: Any = None
 
     if sparse_metadata_detected:
+        enrich_started_at = time.perf_counter()
         enrich_response = _fetch_sparse_metadata_enrich(
             base_url=runtime["base_url"],
             token=runtime["token"],
             timeout_ms=runtime["timeout_ms"],
             source_input=source_input,
             note_id=source_input.get("note_id"),
+            progress=progress,
         )
+        timings["u1_total_ms"] += _elapsed_ms(enrich_started_at)
         trace.append(
             build_api_trace(
                 step="u1_sparse_metadata_enrich",
@@ -1710,23 +1765,32 @@ def run_xiaohongshu_extract(
                 u2_task_id=None,
                 u2_task_status="SKIPPED",
                 note_content_type=note_content_type,
-                analysis_mode="video_full",
+                analysis_mode=analysis_mode,
                 selected_video_url=selected_video_url,
                 selected_video_candidates=video_candidates,
                 selected_image_urls=image_candidates,
                 downloaded_assets=[],
                 missing_fields=missing_fields,
                 metadata_fields=metadata_fields,
+                timings=timings,
             )
             if write_card:
-                result["card_write"] = write_benchmark_card(
+                card_started_at = time.perf_counter()
+                result["card_write"] = write_work_fact_card(
                     payload=result,
                     platform="xiaohongshu",
                     card_type=card_type,
                     card_root=card_root,
                     content_kind="single_video",
                     storage_config=storage_config,
+                    analysis_mode=analysis_mode,
+                    progress=progress.child(scope="card_write") if progress is not None else None,
                 )
+                timings["card_write_ms"] = _elapsed_ms(card_started_at)
+                timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+            timings["total_ms"] = _elapsed_ms(workflow_started_at)
+            result["timings"] = dict(timings)
+            _update_pipeline_status(result)
             return _finalize_result(
                 result=result,
                 source_input=source_input,
@@ -1766,23 +1830,32 @@ def run_xiaohongshu_extract(
                 u2_task_id=None,
                 u2_task_status="SKIPPED",
                 note_content_type=note_content_type,
-                analysis_mode="video_full",
+                analysis_mode=analysis_mode,
                 selected_video_url=u2_gate.get("video_down_url") or selected_video_url,
                 selected_video_candidates=video_candidates,
                 selected_image_urls=image_candidates,
                 downloaded_assets=[],
                 missing_fields=missing_fields,
                 metadata_fields=metadata_fields,
+                timings=timings,
             )
             if write_card:
-                result["card_write"] = write_benchmark_card(
+                card_started_at = time.perf_counter()
+                result["card_write"] = write_work_fact_card(
                     payload=result,
                     platform="xiaohongshu",
                     card_type=card_type,
                     card_root=card_root,
                     content_kind="single_video",
                     storage_config=storage_config,
+                    analysis_mode=analysis_mode,
+                    progress=progress.child(scope="card_write") if progress is not None else None,
                 )
+                timings["card_write_ms"] = _elapsed_ms(card_started_at)
+                timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+            timings["total_ms"] = _elapsed_ms(workflow_started_at)
+            result["timings"] = dict(timings)
+            _update_pipeline_status(result)
             return _finalize_result(
                 result=result,
                 source_input=source_input,
@@ -1792,16 +1865,18 @@ def run_xiaohongshu_extract(
             )
 
         u2_candidates = _dedupe_keep_order([u2_gate.get("video_down_url")] + list(video_candidates))
+        u2_timeout_ms = _resolve_u2_timeout_ms(runtime["timeout_ms"])
         if progress is not None:
             progress.progress(
                 stage="note.u2",
                 message="starting xiaohongshu u2 flow",
-                data={"candidate_count": len(u2_candidates)},
+                data={"candidate_count": len(u2_candidates), "timeout_ms": u2_timeout_ms},
             )
+        u2_started_at = time.perf_counter()
         u2_bundle = run_u2_asr_candidates_with_timeout_retry(
             base_url=runtime["base_url"],
             token=runtime["token"],
-            timeout_ms=runtime["timeout_ms"],
+            timeout_ms=u2_timeout_ms,
             candidates=u2_candidates,
             submit_max_retries=u2_submit_max_retries,
             submit_backoff_ms=u2_submit_backoff_ms,
@@ -1809,7 +1884,13 @@ def run_xiaohongshu_extract(
             max_polls=max_polls,
             timeout_retry_enabled=u2_timeout_retry_enabled,
             timeout_retry_max_retries=u2_timeout_retry_max_retries,
+            pending_timeout_sec=int(config_get(storage_config or {}, "runtime.u2_pending_timeout_sec", 60) or 60),
+            progress_callback=(
+                lambda event: _report_u2_progress(progress, stage="note.u2", event=event, label="xiaohongshu")
+            ) if progress is not None else None,
         )
+        timings["u2_submit_ms"] = _to_int_or_none(u2_bundle.get("submit_duration_ms")) or 0
+        timings["u2_poll_ms"] = _to_int_or_none(u2_bundle.get("poll_duration_ms")) or _elapsed_ms(u2_started_at)
         submit_bundle = u2_bundle.get("submit_bundle", {})
         submit_response = submit_bundle.get("submit_response", {})
         task_id = submit_bundle.get("task_id")
@@ -1818,6 +1899,19 @@ def run_xiaohongshu_extract(
         if selected_video_url and not normalize_text(metadata_fields.get("video_down_url")):
             metadata_fields["video_down_url"] = selected_video_url
 
+        if progress is not None:
+            progress.http_event(
+                stage="note.u2",
+                endpoint="/api/u2/v1/services/audio/asr/transcription",
+                response=submit_response,
+                route_label="u2_submit",
+                summary={
+                    "task_id": task_id,
+                    "retry_count": len(submit_bundle.get("retry_chain", [])),
+                    "candidate_count": len(u2_candidates),
+                },
+            )
+
         trace.append(
             {
                 "step": "u2_asr_timeout_retry",
@@ -1830,6 +1924,7 @@ def run_xiaohongshu_extract(
                     "u2_submit_backoff_ms": max(0, int(u2_submit_backoff_ms)),
                 },
                 "timeout_retry": u2_bundle.get("timeout_retry", {}),
+                "u3_fallback": u2_bundle.get("u3_fallback", {}),
                 "rounds": u2_bundle.get("rounds", []),
                 "final_task_id": poll_result.get("task_id") or task_id,
                 "final_task_status": poll_result.get("task_status"),
@@ -1879,23 +1974,32 @@ def run_xiaohongshu_extract(
                 u2_task_id=poll_result.get("task_id") or task_id,
                 u2_task_status=poll_result.get("task_status") or "UNKNOWN",
                 note_content_type=note_content_type,
-                analysis_mode="video_full",
+                analysis_mode=analysis_mode,
                 selected_video_url=selected_video_url,
                 selected_video_candidates=u2_candidates,
                 selected_image_urls=image_candidates,
                 downloaded_assets=[],
                 missing_fields=missing_fields,
                 metadata_fields=metadata_fields,
+                timings=timings,
             )
             if write_card:
-                result["card_write"] = write_benchmark_card(
+                card_started_at = time.perf_counter()
+                result["card_write"] = write_work_fact_card(
                     payload=result,
                     platform="xiaohongshu",
                     card_type=card_type,
                     card_root=card_root,
                     content_kind="single_video",
                     storage_config=storage_config,
+                    analysis_mode=analysis_mode,
+                    progress=progress.child(scope="card_write") if progress is not None else None,
                 )
+                timings["card_write_ms"] = _elapsed_ms(card_started_at)
+                timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+            timings["total_ms"] = _elapsed_ms(workflow_started_at)
+            result["timings"] = dict(timings)
+            _update_pipeline_status(result)
             return _finalize_result(
                 result=result,
                 source_input=source_input,
@@ -1911,38 +2015,57 @@ def run_xiaohongshu_extract(
             explicit_error_reason=poll_result.get("error_reason"),
             explicit_request_id=poll_result.get("request_id") or submit_response.get("request_id") or note_response.get("request_id"),
         )
+        text_source = "u2"
+        confidence = "high" if poll_result.get("ok") and raw_content else "low"
+        error_reason = final_ctx.get("error_reason")
+        if not raw_content and caption_text:
+            missing_fields.append({"field": "asr_transcript", "reason": f"u2_failed:{error_reason or 'u2_poll_timeout'}"})
+            raw_content = caption_text
+            text_source = "caption_fallback"
+            confidence = "medium"
+            error_reason = None
         result = _build_result(
             source_input=source_input,
             raw_content=raw_content,
-            confidence="high" if poll_result.get("ok") and raw_content else "low",
-            error_reason=final_ctx.get("error_reason"),
+            confidence=confidence,
+            error_reason=error_reason,
             extract_trace=trace,
             fallback_trace=final_ctx.get("fallback_trace", []),
             request_id=final_ctx.get("request_id"),
-            text_source="u2",
+            text_source=text_source,
             note_id=str(resolved_note_id) if resolved_note_id else source_input.get("note_id"),
             subtitle_hit=False,
             u2_task_id=poll_result.get("task_id") or task_id,
             u2_task_status=poll_result.get("task_status"),
             note_content_type=note_content_type,
-            analysis_mode="video_full",
+            analysis_mode=analysis_mode,
             selected_video_url=selected_video_url,
             selected_video_candidates=u2_candidates,
             selected_image_urls=image_candidates,
             downloaded_assets=[],
             missing_fields=missing_fields,
             metadata_fields=metadata_fields,
+            timings=timings,
         )
 
         if write_card:
-            result["card_write"] = write_benchmark_card(
+            card_started_at = time.perf_counter()
+            result["card_write"] = write_work_fact_card(
                 payload=result,
                 platform="xiaohongshu",
                 card_type=card_type,
                 card_root=card_root,
                 content_kind="single_video",
                 storage_config=storage_config,
+                analysis_mode=analysis_mode,
+                progress=progress.child(scope="card_write") if progress is not None else None,
             )
+            timings["card_write_ms"] = _elapsed_ms(card_started_at)
+            timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+
+        timings["total_ms"] = _elapsed_ms(workflow_started_at)
+        result["timings"] = dict(timings)
+        _update_pipeline_status(result)
 
         return _finalize_result(
             result=result,
@@ -1989,24 +2112,34 @@ def run_xiaohongshu_extract(
         u2_task_id=None,
         u2_task_status="SKIPPED",
         note_content_type="image" if note_content_type == "unknown" else note_content_type,
-        analysis_mode="image_light_analysis",
+        analysis_mode=analysis_mode,
         selected_video_url=None,
         selected_video_candidates=video_candidates,
         selected_image_urls=image_candidates,
         downloaded_assets=downloaded_assets,
         missing_fields=missing_fields,
         metadata_fields=metadata_fields,
+        timings=timings,
     )
 
     if write_card:
-        result["card_write"] = write_benchmark_card(
+        card_started_at = time.perf_counter()
+        result["card_write"] = write_work_fact_card(
             payload=result,
             platform="xiaohongshu",
             card_type=card_type,
             card_root=card_root,
             content_kind="note",
             storage_config=storage_config,
+            analysis_mode=analysis_mode,
+            progress=progress.child(scope="card_write") if progress is not None else None,
         )
+        timings["card_write_ms"] = _elapsed_ms(card_started_at)
+        timings["llm_analysis_ms"] = _to_int_or_none((result.get("card_write") or {}).get("llm_analysis_ms")) or 0
+
+    timings["total_ms"] = _elapsed_ms(workflow_started_at)
+    result["timings"] = dict(timings)
+    _update_pipeline_status(result)
 
     finalized = _finalize_result(
         result=result,
@@ -2025,6 +2158,7 @@ def run_xiaohongshu_extract(
                 "card_write_ok": bool((finalized.get("card_write") or {}).get("ok")),
                 "output_persist_ok": bool((finalized.get("output_persist") or {}).get("ok")),
                 "text_source": finalized.get("text_source"),
+                "deep_analysis_status": ((finalized.get("deep_analysis") or {}).get("status")),
             },
         )
     return finalized
@@ -2069,7 +2203,14 @@ def main() -> None:
         help="Conservative max retries for U2 timeout-only retry (0~3)",
     )
     parser.add_argument("--force-u2-fallback", action="store_true", help="Skip subtitle usage and force U2 fallback (test)")
-    parser.add_argument("--card-type", choices=["work", "author", "author_sample_work"], default="work", help="Primary card type")
+    parser.add_argument("--card-type", choices=["work"], default="work", help="Primary card type")
+    parser.add_argument("--card-mode", dest="analysis_mode", choices=["standard", "auto", "local"], default="standard", help="Fact-card mode")
+    parser.add_argument("--analysis-mode", dest="analysis_mode", choices=["standard", "auto", "local"], help=argparse.SUPPRESS)
+    parser.set_defaults(write_card=True, persist_output=True)
+    parser.add_argument("--write-card", dest="write_card", action="store_true", help="Write final work card")
+    parser.add_argument("--no-write-card", dest="write_card", action="store_false", help="Skip card writing")
+    parser.add_argument("--persist-output", dest="persist_output", action="store_true", help="Persist result JSON")
+    parser.add_argument("--no-persist-output", dest="persist_output", action="store_false", help="Skip result JSON persist")
     parser.add_argument("--card-root", default=None, help="Card root (absolute); falls back to TIKOMNI_CARD_ROOT when writing cards")
     args = parser.parse_args()
 
@@ -2109,6 +2250,12 @@ def main() -> None:
         if args.u2_timeout_retry_max_retries is not None
         else config_get(config, "asr_strategy.u2_timeout_retry.max_retries", 3)
     )
+    progress = build_progress_reporter(
+        workflow="social-media-crawl",
+        platform="xiaohongshu",
+        content_kind="note",
+        input_value=args.share_text or args.note_id or args.input,
+    )
 
     try:
         result = run_xiaohongshu_extract(
@@ -2126,12 +2273,14 @@ def main() -> None:
             u2_timeout_retry_enabled=bool(u2_timeout_retry_enabled),
             u2_timeout_retry_max_retries=int(u2_timeout_retry_max_retries),
             force_u2_fallback=args.force_u2_fallback,
-            write_card=True,
+            write_card=bool(args.write_card),
+            analysis_mode=args.analysis_mode,
             card_type=args.card_type,
             card_root=args.card_root,
             storage_config=config,
             allow_process_env=args.allow_process_env,
-            persist_output=True,
+            persist_output=bool(args.persist_output),
+            progress=progress,
         )
     except ValueError as error:
         result = {