@tikomni/skills 0.1.0

package/skills/single-work-analysis/scripts/writers/write_benchmark_card.py

@@ -0,0 +1,1402 @@
+#!/usr/bin/env python3
+
+if __package__ in {None, ""}:
+    import sys
+    from pathlib import Path
+
+    _self = Path(__file__).resolve()
+    for _parent in _self.parents:
+        if (_parent / "scripts").is_dir():
+            sys.path.insert(0, str(_parent))
+            break
+
+"""Write benchmark markdown cards into card root zones."""
+
+import argparse
+import datetime as dt
+import json
+import os
+import re
+import unicodedata
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from zoneinfo import ZoneInfo
+except Exception:  # pragma: no cover - py<3.9 fallback
+    ZoneInfo = None
+
+from scripts.core.analysis_pipeline import DEFAULT_MODULE_SECTIONS, build_analysis_sections
+from scripts.core.config_loader import load_tikomni_config
+from scripts.core.storage_router import build_card_output_path, normalize_card_type, resolve_effective_card_type
+from scripts.core.tikomni_common import normalize_text, read_json_file, write_json_stdout
+
+def resolve_default_card_root() -> str:
+    raw = os.getenv("TIKOMNI_CARD_ROOT", "").strip()
+    if not raw:
+        raise ValueError(
+            "missing_card_root: set --card-root or define TIKOMNI_CARD_ROOT in .env/.env.local"
+        )
+
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        raise ValueError("TIKOMNI_CARD_ROOT must be an absolute path")
+    return str(candidate.resolve())
+
+
+# Keep import-time compatibility for other scripts without crashing when env is absent.
+DEFAULT_CARD_ROOT = ""
+CARD_TYPES = ["work", "author", "author_sample_work"]
+
+
+def _normalize_lines(value: Any) -> List[str]:
+    if isinstance(value, list):
+        return [normalize_text(item) for item in value if normalize_text(item)]
+    if isinstance(value, str):
+        text = normalize_text(value)
+        return [text] if text else []
+    return []
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str):
+        text = value.strip()
+        if text.isdigit() or (text.startswith("-") and text[1:].isdigit()):
+            return int(text)
+    return default
+
+
+def _safe_optional_int(value: Any) -> Optional[int]:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        if text.isdigit() or (text.startswith("-") and text[1:].isdigit()):
+            return int(text)
+    return None
+
+
+def _to_unix_sec(value: Any) -> int:
+    if value is None:
+        return 0
+    parsed = _safe_int(value, default=0)
+    if parsed <= 0:
+        return 0
+    if parsed > 1_000_000_000_000:
+        parsed //= 1000
+    return parsed
+
+
+def _format_shanghai_datetime(value: Any) -> str:
+    ts = _to_unix_sec(value)
+    if ts <= 0:
+        return ""
+    try:
+        if ZoneInfo is not None:
+            dt_obj = dt.datetime.fromtimestamp(ts, tz=ZoneInfo("Asia/Shanghai"))
+        else:
+            dt_obj = dt.datetime.fromtimestamp(ts, tz=dt.timezone(dt.timedelta(hours=8)))
+        return dt_obj.strftime("%Y-%m-%d %H:%M:%S")
+    except Exception:
+        return ""
+
+
+def _resolve_publish_time(payload: Dict[str, Any], create_time_sec: int) -> Dict[str, str]:
+    publish_time_text = normalize_text(payload.get("publish_time_text"))
+    if publish_time_text:
+        return {"publish_time_text": publish_time_text, "publish_time_source": "payload.publish_time_text"}
+
+    source = _source_dict(payload)
+    candidates = [
+        ("payload.publish_time", payload.get("publish_time")),
+        ("payload.create_time", payload.get("create_time")),
+        ("source.publish_time", source.get("publish_time")),
+        ("source.create_time", source.get("create_time")),
+        ("source.time", source.get("time")),
+    ]
+    for source_key, raw in candidates:
+        text = normalize_text(raw)
+        if not text:
+            continue
+        ts_text = _format_shanghai_datetime(raw)
+        if ts_text:
+            return {"publish_time_text": ts_text, "publish_time_source": source_key}
+        return {"publish_time_text": text, "publish_time_source": source_key}
+
+    fallback_text = _format_shanghai_datetime(create_time_sec)
+    if fallback_text:
+        return {"publish_time_text": fallback_text, "publish_time_source": "create_time_sec"}
+
+    return {"publish_time_text": "未知", "publish_time_source": "unknown"}
+
+
+def _resolve_published_date(payload: Dict[str, Any], create_time_sec: int) -> str:
+    published_date = normalize_text(payload.get("published_date"))
+    if published_date:
+        return published_date
+    publish_time_info = _resolve_publish_time(payload, create_time_sec)
+    text = normalize_text(publish_time_info.get("publish_time_text"))
+    if not text or text == "未知":
+        return "N/A"
+    return text[:10]
+
+
+def _display_metric(value: Optional[int]) -> str:
+    if value is None:
+        return "N/A"
+    return str(value)
+
+
+def _source_dict(payload: Dict[str, Any]) -> Dict[str, Any]:
+    source = payload.get("source")
+    return source if isinstance(source, dict) else {}
+
+
+def _extract_duration_ms(payload: Dict[str, Any]) -> int:
+    source = _source_dict(payload)
+
+    def _pick_int(keys: List[str], from_source: bool = False) -> int:
+        base = source if from_source else payload
+        for key in keys:
+            value = _safe_int(base.get(key), default=0)
+            if value > 0:
+                return value
+        return 0
+
+    duration_ms = _pick_int(["duration_ms"])
+    if duration_ms <= 0:
+        duration_ms = _pick_int(["duration_ms"], from_source=True)
+
+    if duration_ms <= 0:
+        raw_duration = _pick_int(["duration", "duration_sec"])
+        if raw_duration <= 0:
+            raw_duration = _pick_int(["duration", "duration_sec"], from_source=True)
+        if raw_duration > 0:
+            duration_ms = raw_duration * 1000 if raw_duration < 10000 else raw_duration
+
+    return duration_ms
+
+
+def _ensure_sentence_end(text: str) -> str:
+    if not text:
+        return text
+    if text[-1] in "。！？!?" or text.endswith("..."):
+        return text
+    return f"{text}。"
+
+
+def _clean_asr_text(raw: str, provided_clean: str) -> str:
+    """ASR_CLEAN prompt-contracts/asr-clean.md@v1
+
+    Steps:
+    1) base select: provided_clean > raw
+    2) denoise: remove filler/repetition/whitespace noise
+    3) sentence split + punctuation restore
+    4) paragraphize: one sentence per line, 2-4 sentences per paragraph
+    """
+    base = normalize_text(provided_clean) or normalize_text(raw)
+    if not base:
+        return ""
+
+    # step2: 去噪（口头禅/重复）
+    base = re.sub(r"\b(嗯|啊|呃|额|那个|这个|然后|就是)\b", " ", base)
+    base = re.sub(r"(嗯+|啊+|呃+)", " ", base)
+    base = re.sub(r"(就是就是|然后然后|这个这个|那个那个)", " ", base)
+    base = re.sub(r"\s+", " ", base).strip()
+
+    # step3: 断句 + 句尾标点
+    units = [normalize_text(part) for part in re.split(r"[。！？!?；;\n]+", base)]
+    sentences = [_ensure_sentence_end(unit) for unit in units if unit]
+    if not sentences:
+        fallback = _ensure_sentence_end(base)
+        return fallback if fallback else ""
+
+    # step4: 每句一行；每段 2~4 句（默认 3 句）
+    paragraphs: List[str] = []
+    bucket: List[str] = []
+    for sentence in sentences:
+        bucket.append(sentence)
+        if len(bucket) >= 3:
+            paragraphs.append("\n".join(bucket))
+            bucket = []
+
+    if bucket:
+        if len(bucket) == 1 and paragraphs:
+            paragraphs[-1] = f"{paragraphs[-1]}\n{bucket[0]}"
+        else:
+            paragraphs.append("\n".join(bucket))
+
+    return "\n\n".join(paragraphs)
+
+
+def _pick_text(payload: Dict[str, Any], keys: List[str], source_keys: Optional[List[str]] = None) -> str:
+    source = _source_dict(payload)
+    for key in keys:
+        text = normalize_text(payload.get(key))
+        if text:
+            return text
+    for key in (source_keys or keys):
+        text = normalize_text(source.get(key))
+        if text:
+            return text
+    return ""
+
+
+def _extract_platform_work_id(payload: Dict[str, Any]) -> str:
+    return _pick_text(
+        payload,
+        ["platform_work_id", "aweme_id", "note_id", "item_id", "id"],
+        ["platform_work_id", "aweme_id", "note_id", "item_id", "id"],
+    )
+
+
+def _extract_author(payload: Dict[str, Any]) -> Dict[str, str]:
+    author_raw = payload.get("author")
+    author = author_raw if isinstance(author_raw, dict) else {}
+
+    source = _source_dict(payload)
+    source_author = source.get("author") if isinstance(source.get("author"), dict) else {}
+
+    author_text = normalize_text(author_raw) if isinstance(author_raw, str) else ""
+    nickname = (
+        normalize_text(author.get("nickname"))
+        or author_text
+        or normalize_text(source_author.get("nickname"))
+    )
+
+    author_handle = (
+        normalize_text(payload.get("author_handle"))
+        or normalize_text(author.get("author_handle"))
+        or normalize_text(source_author.get("author_handle"))
+        or nickname
+    )
+    platform_author_id = (
+        normalize_text(payload.get("platform_author_id"))
+        or normalize_text(payload.get("author_platform_id"))
+        or normalize_text(author.get("platform_author_id"))
+        or normalize_text(author.get("author_platform_id"))
+        or normalize_text(source_author.get("platform_author_id"))
+        or normalize_text(source_author.get("author_platform_id"))
+    )
+
+    xhs_user_id = (
+        normalize_text(payload.get("xhs_user_id"))
+        or normalize_text(author.get("xhs_user_id"))
+        or normalize_text(source_author.get("xhs_user_id"))
+    )
+    xhs_sec_token = (
+        normalize_text(payload.get("xhs_sec_token"))
+        or normalize_text(author.get("xhs_sec_token"))
+        or normalize_text(source_author.get("xhs_sec_token"))
+    )
+
+    douyin_sec_uid = (
+        normalize_text(payload.get("douyin_sec_uid"))
+        or normalize_text(author.get("douyin_sec_uid"))
+        or normalize_text(source_author.get("douyin_sec_uid"))
+    )
+    douyin_aweme_author_id = (
+        normalize_text(payload.get("douyin_aweme_author_id"))
+        or normalize_text(author.get("douyin_aweme_author_id"))
+        or normalize_text(source_author.get("douyin_aweme_author_id"))
+    )
+
+    return {
+        "nickname": nickname,
+        "author_handle": author_handle,
+        "platform_author_id": platform_author_id,
+        "xhs_user_id": xhs_user_id,
+        "xhs_sec_token": xhs_sec_token,
+        "douyin_sec_uid": douyin_sec_uid,
+        "douyin_aweme_author_id": douyin_aweme_author_id,
+    }
+
+
+def _is_cjk(char: str) -> bool:
+    code = ord(char)
+    return 0x4E00 <= code <= 0x9FFF
+
+
+def _clean_for_filename(text: str) -> str:
+    if not text:
+        return ""
+
+    normalized = unicodedata.normalize("NFKC", text)
+    normalized = re.sub(r"[#＃][^\s#＃]+", " ", normalized)
+    normalized = re.sub(r"\[[^\]]+\]", " ", normalized)
+    normalized = normalized.replace("\n", " ").replace("\r", " ")
+
+    kept: List[str] = []
+    for ch in normalized:
+        cat = unicodedata.category(ch)
+        if _is_cjk(ch) or ch.isalnum() or ch in {" ", "-", "_"}:
+            kept.append(ch)
+        elif cat.startswith("Z"):
+            kept.append(" ")
+
+    compact = "".join(kept)
+    compact = re.sub(r"\s+", "", compact)
+    compact = re.sub(r"[\\/:*?\"<>|]", "", compact)
+    return compact.strip("._-")
+
+
+def _clip_with_min(text: str, min_len: int, max_len: int, fallback: str) -> str:
+    candidate = _clean_for_filename(text)
+    fallback_clean = _clean_for_filename(fallback)
+
+    if not candidate:
+        candidate = fallback_clean
+    if len(candidate) < min_len:
+        candidate = (candidate + fallback_clean)[:max_len]
+    if len(candidate) < min_len:
+        candidate = (candidate + "内容速览")[:max_len]
+
+    candidate = candidate[:max_len]
+    if len(candidate) < min_len:
+        candidate = (candidate + "作品卡")[:max_len]
+    return candidate[:max_len] if candidate else fallback_clean[:max_len]
+
+
+def _pick_author_slug(payload: Dict[str, Any], author_hint: Optional[str] = None) -> str:
+    base = normalize_text(author_hint)
+    if not base:
+        author = _extract_author(payload)
+        base = author["nickname"] or author["author_handle"] or author["platform_author_id"] or "作者"
+    slug = _clip_with_min(base, min_len=2, max_len=18, fallback="作者")
+    return slug if len(slug) >= 2 else "作者"
+
+
+def _pick_title_source(payload: Dict[str, Any]) -> str:
+    for key in ("title", "desc", "summary"):
+        text = normalize_text(payload.get(key))
+        if text:
+            return text
+
+    source = _source_dict(payload)
+    for key in ("title", "desc"):
+        text = normalize_text(source.get(key))
+        if text:
+            return text
+
+    raw_content = normalize_text(payload.get("raw_content"))
+    if raw_content:
+        return raw_content[:48]
+
+    platform_work_id = _extract_platform_work_id(payload)
+    if platform_work_id:
+        return f"作品拆解{platform_work_id[-8:]}"
+
+    return "内容拆解速览"
+
+
+def _pick_title_slug(payload: Dict[str, Any]) -> str:
+    title_source = _pick_title_source(payload)
+    platform_work_id = _extract_platform_work_id(payload)
+    fallback = f"内容拆解{platform_work_id[-8:]}" if platform_work_id else "内容拆解速览"
+    slug = _clip_with_min(title_source, min_len=8, max_len=28, fallback=fallback)
+    return slug if slug else "内容拆解速览"
+
+
+def _extract_tags(payload: Dict[str, Any]) -> List[str]:
+    for key in ("tags", "tag_list", "hashtags"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            tags = [normalize_text(item).lstrip("#") for item in value if normalize_text(item)]
+            if tags:
+                return list(dict.fromkeys(tags))
+        if isinstance(value, str) and normalize_text(value):
+            parts = re.split(r"[,，\s]+", normalize_text(value))
+            tags = [part.lstrip("#") for part in parts if part]
+            if tags:
+                return list(dict.fromkeys(tags))
+
+    source = _source_dict(payload)
+    for key in ("tags", "tag_list", "hashtags"):
+        value = source.get(key)
+        if isinstance(value, list):
+            tags = [normalize_text(item).lstrip("#") for item in value if normalize_text(item)]
+            if tags:
+                return list(dict.fromkeys(tags))
+
+    return []
+
+
+def _extract_required_fields(payload: Dict[str, Any], platform: str) -> Dict[str, Any]:
+    author = _extract_author(payload)
+
+    title = _pick_text(payload, ["title", "desc"], ["title", "desc"])
+    caption_raw = normalize_text(payload.get("caption_raw") or payload.get("desc"))
+    platform_work_id = _extract_platform_work_id(payload)
+
+    source_url = _pick_text(
+        payload,
+        ["source_url", "share_url", "url"],
+        ["source_url", "share_url", "url", "share_text"],
+    )
+    share_url = _pick_text(
+        payload,
+        ["share_url", "canonical_share_url"],
+        ["share_url", "canonical_share_url", "url", "source_url", "share_text"],
+    ) or source_url
+
+    cover_image = _pick_text(
+        payload,
+        ["cover_image", "cover_url", "cover"],
+        ["cover_image", "cover_url", "cover", "origin_cover"],
+    )
+    selected_images = payload.get("selected_image_urls")
+    if not cover_image and isinstance(selected_images, list) and selected_images:
+        cover_image = normalize_text(selected_images[0])
+
+    video_download_url = _pick_text(
+        payload,
+        ["video_download_url", "video_down_url", "selected_video_url", "original_video_url", "video_url", "download_url"],
+        ["video_download_url", "video_down_url", "selected_video_url", "original_video_url", "video_url", "download_url"],
+    )
+
+    create_time_sec = _to_unix_sec(payload.get("create_time_sec"))
+    if create_time_sec <= 0:
+        create_time_sec = _to_unix_sec(payload.get("create_time"))
+    if create_time_sec <= 0:
+        create_time_sec = _to_unix_sec(_source_dict(payload).get("create_time"))
+
+    digg_count = _safe_int(payload.get("digg_count"), default=0)
+    comment_count = _safe_int(payload.get("comment_count"), default=0)
+    collect_count = _safe_int(payload.get("collect_count"), default=0)
+    share_count = _safe_int(payload.get("share_count"), default=0)
+    play_count = _safe_optional_int(payload.get("play_count"))
+
+    summary = normalize_text(payload.get("summary"))
+    raw_content = normalize_text(payload.get("raw_content"))
+    primary_text = normalize_text(payload.get("primary_text"))
+    provided_asr_clean = normalize_text(payload.get("asr_clean"))
+    asr_clean = _clean_asr_text(raw_content, provided_asr_clean)
+
+    duration_ms = _extract_duration_ms(payload)
+
+    category = normalize_text(payload.get("category"))
+    if not category:
+        category = "观点"
+
+    hot_score = _safe_int(payload.get("hot_score"), default=0)
+    if hot_score <= 0:
+        hot_score = digg_count + comment_count * 2 + collect_count * 3 + share_count * 4
+
+    work_modality = normalize_text(payload.get("work_modality"))
+    if not work_modality:
+        work_modality = "video" if video_download_url or raw_content else "text"
+
+    published_date = _resolve_published_date(payload, create_time_sec)
+    primary_text_source_raw = normalize_text(payload.get("primary_text_source"))
+    primary_text_source = (
+        primary_text_source_raw
+        if primary_text_source_raw in {"asr_clean", "caption_raw"}
+        else ("asr_clean" if work_modality == "video" else "caption_raw")
+    )
+    if not primary_text:
+        primary_text = asr_clean if primary_text_source == "asr_clean" else normalize_text(payload.get("desc"))
+
+    return {
+        "title": title,
+        "platform": platform,
+        "platform_work_id": platform_work_id,
+        "author": author.get("nickname") or "",
+        "author_handle": author.get("author_handle") or "",
+        "platform_author_id": author.get("platform_author_id") or "",
+        "caption_raw": caption_raw,
+        "share_url": share_url,
+        "source_url": source_url,
+        "cover_image": cover_image,
+        "video_download_url": video_download_url,
+        "published_date": published_date,
+        "duration_ms": duration_ms,
+        "digg_count": digg_count,
+        "comment_count": comment_count,
+        "collect_count": collect_count,
+        "share_count": share_count,
+        "play_count": play_count,
+        "tags": _extract_tags(payload),
+        "work_modality": work_modality,
+        "category": category,
+        "content_kind": normalize_text(payload.get("content_kind")),
+        "summary": summary,
+        "hot_score": hot_score,
+        "raw_content": raw_content,
+        "primary_text": primary_text,
+        "asr_clean": asr_clean,
+        "platform_native_refs": payload.get("platform_native_refs") if isinstance(payload.get("platform_native_refs"), dict) else {},
+        "request_id": payload.get("request_id"),
+        "confidence": normalize_text(payload.get("confidence")) or "low",
+        "error_reason": payload.get("error_reason"),
+        "extract_trace": payload.get("extract_trace", []),
+        "analysis_sections": payload.get("analysis_sections") if isinstance(payload.get("analysis_sections"), dict) else {},
+        "analysis_output": payload.get("analysis_output") if isinstance(payload.get("analysis_output"), dict) else {},
+        "author_analysis_v2": payload.get("author_analysis_v2") if isinstance(payload.get("author_analysis_v2"), dict) else {},
+        "author_analysis_input_v1": payload.get("author_analysis_input_v1") if isinstance(payload.get("author_analysis_input_v1"), dict) else {},
+        "sampled_work_explanations": payload.get("sampled_work_explanations") if isinstance(payload.get("sampled_work_explanations"), dict) else {},
+        "author_card_highlights": payload.get("author_card_highlights") if isinstance(payload.get("author_card_highlights"), dict) else {},
+        "validation": payload.get("validation") if isinstance(payload.get("validation"), dict) else {},
+        "business_score": _safe_int(payload.get("business_score"), default=0),
+        "benchmark_gap_score": _safe_int(payload.get("benchmark_gap_score"), default=0),
+        "style_radar": payload.get("style_radar") if isinstance(payload.get("style_radar"), dict) else {},
+        "core_contradictions": payload.get("core_contradictions") if isinstance(payload.get("core_contradictions"), list) else [],
+        "recommendations": payload.get("recommendations") if isinstance(payload.get("recommendations"), list) else [],
+        "business_analysis": normalize_text(payload.get("business_analysis")),
+        "benchmark_analysis": normalize_text(payload.get("benchmark_analysis")),
+        "nickname": normalize_text(payload.get("nickname")),
+        "ip_location": normalize_text(payload.get("ip_location")),
+        "signature": normalize_text(payload.get("signature")),
+        "avatar_url": normalize_text(payload.get("avatar_url")),
+        "fans_count": _safe_optional_int(payload.get("fans_count")),
+        "liked_count": _safe_optional_int(payload.get("liked_count")),
+        "collected_count": _safe_optional_int(payload.get("collected_count")),
+        "works_count": _safe_optional_int(payload.get("works_count")),
+        "verified": payload.get("verified") if isinstance(payload.get("verified"), bool) else None,
+        "snapshot_at": normalize_text(payload.get("snapshot_at")),
+    }
+
+
+def _format_create_time(create_time_sec: int) -> str:
+    text = _format_shanghai_datetime(create_time_sec)
+    if text:
+        return text
+    if create_time_sec <= 0:
+        return "未知"
+    return str(create_time_sec)
+
+
+def _format_duration(duration_ms: int) -> str:
+    if duration_ms <= 0:
+        return "未知"
+    total_sec = duration_ms // 1000
+    minute, second = divmod(total_sec, 60)
+    if minute:
+        return f"{minute}分{second:02d}秒"
+    return f"{second}秒"
+
+
+def _sentence_units(text: str) -> List[str]:
+    if not text:
+        return []
+    return [normalize_text(x) for x in re.split(r"[。！？!?；;\\n]+", text) if normalize_text(x)]
+
+
+def _first_sentence(text: str) -> str:
+    units = _sentence_units(text)
+    return units[0] if units else ""
+
+
+def _hit_count(text: str, keywords: List[str]) -> int:
+    if not text:
+        return 0
+    return sum(1 for token in keywords if token in text)
+
+
+def _top_keywords(text: str, candidates: List[str], topn: int = 3) -> List[str]:
+    if not text:
+        return []
+    scored = []
+    for token in candidates:
+        count = text.count(token)
+        if count > 0:
+            scored.append((count, token))
+    scored.sort(key=lambda x: (-x[0], len(x[1])))
+    return [token for _, token in scored[:topn]]
+
+
+def _score_from_hits(hits: int, full_score_hits: int = 4) -> int:
+    if hits <= 0:
+        return 2
+    if hits >= full_score_hits:
+        return 5
+    return min(5, hits + 2)
+
+
+
+def _analyze_topic(fields: Dict[str, Any]) -> Dict[str, Any]:
+    title = normalize_text(fields.get("title") or "")
+    asr = normalize_text(fields.get("asr_clean") or "")
+    category = normalize_text(fields.get("category") or "")
+    text = f"{title} {asr}"
+
+    if not text.strip():
+        return {
+            "score": 2,
+            "lines": ["- 类型：数据不足。", "- 细分主题：数据不足。", "- 受众痛点：数据不足，需补充标题或ASR。"],
+            "gaps": ["补齐标题或ASR文本，才能完成选题分类与主题归因"],
+            "evidence": "输入文本缺失",
+        }
+
+    type_rules = {
+        "流量型": ["热点", "挑战", "反转", "揭秘", "真相", "别再", "为什么", "踩坑", "3秒", "爆款"],
+        "人设型": ["我是", "我们", "日常", "系列", "分享", "经历", "成长", "复盘", "带你", "我"],
+        "营销型": ["领取", "私信", "咨询", "下单", "课程", "优惠", "链接", "报名", "合作", "购买"],
+    }
+    type_scores = {name: _hit_count(text, kws) for name, kws in type_rules.items()}
+
+    if category in ["教程", "知识", "方法"]:
+        type_scores["营销型"] += 1
+    if category in ["观点", "人设", "日常"]:
+        type_scores["人设型"] += 1
+
+    main_type = max(type_scores, key=lambda k: type_scores[k])
+    main_hits = type_scores[main_type]
+
+    theme_candidates = [
+        "AI", "智能体", "变现", "副业", "教程", "工作流", "流量", "涨粉", "投流", "口播", "脚本", "工具", "私域", "创业", "营销",
+    ]
+    themes = _top_keywords(text, theme_candidates, topn=3)
+    pain_candidates = ["不会", "焦虑", "卡住", "没流量", "转化", "不会写", "不会做", "时间不够", "担心", "风险"]
+    pains = _top_keywords(text, pain_candidates, topn=2)
+
+    lines = [
+        f"- 基础类型：{main_type}（命中信号 {main_hits} 个）。",
+        f"- 细分主题：{'、'.join(themes) if themes else '数据不足（未检测到显著主题词）'}。",
+        f"- 受众痛点：{'、'.join(pains) if pains else '以“快速落地/降低门槛”为主（显性痛点词不足）'}。",
+    ]
+
+    return {
+        "score": _score_from_hits(main_hits),
+        "lines": lines,
+        "gaps": [] if themes else ["补充更完整ASR，提高细分主题识别稳定性"],
+        "evidence": f"类型命中分布={type_scores}",
+    }
+
+
+def _analyze_style(fields: Dict[str, Any]) -> Dict[str, Any]:
+    asr = normalize_text(fields.get("asr_clean") or "")
+    title = normalize_text(fields.get("title") or "")
+    text = f"{title} {asr}".strip()
+    units = _sentence_units(asr)
+
+    if not text:
+        return {
+            "score": 2,
+            "lines": ["- 人设匹配：数据不足。", "- 句式结构：数据不足。", "- 语气与情绪：数据不足。"],
+            "gaps": ["补齐ASR文本后再做文风拆解"],
+            "evidence": "输入文本缺失",
+        }
+
+    avg_len = int(sum(len(u) for u in units) / max(1, len(units))) if units else 0
+    if avg_len <= 14:
+        length_type = "短句为主"
+    elif avg_len <= 24:
+        length_type = "中短句混合"
+    else:
+        length_type = "中长句为主"
+
+    q_count = text.count("?") + text.count("？")
+    e_count = text.count("!") + text.count("！")
+    statement_count = max(0, len(units) - q_count - e_count)
+    persona_hits = _hit_count(text, ["我", "我们", "你", "大家", "朋友们", "聪明的你"])
+    rhetoric_hits = _hit_count(text, ["不是", "而是", "其实", "真的", "一定", "必须", "先", "再"])
+
+    lines = [
+        f"- 句式结构：{length_type}，平均句长约 {avg_len} 字。",
+        f"- 语气分布：疑问 {q_count} / 感叹 {e_count} / 陈述 {statement_count}。",
+        f"- 人设与修辞：人设代词命中 {persona_hits} 次，强调/转折词命中 {rhetoric_hits} 次。",
+    ]
+
+    strength_hits = int(avg_len > 0) + int(persona_hits > 0) + int(rhetoric_hits > 0)
+    return {
+        "score": _score_from_hits(strength_hits, full_score_hits=3),
+        "lines": lines,
+        "gaps": [] if units else ["ASR分句失败，建议人工复核"],
+        "evidence": f"avg_len={avg_len}, persona_hits={persona_hits}, rhetoric_hits={rhetoric_hits}",
+    }
+
+
+def _analyze_hook(fields: Dict[str, Any]) -> Dict[str, Any]:
+    title = normalize_text(fields.get("title") or "")
+    asr = normalize_text(fields.get("asr_clean") or "")
+    first = _first_sentence(asr) or title
+    middle = _sentence_units(asr)[len(_sentence_units(asr)) // 2] if _sentence_units(asr) else ""
+
+    if not first:
+        return {
+            "score": 2,
+            "lines": ["- 开头钩子：数据不足。", "- 中段钩子：数据不足。", "- 结尾钩子：数据不足。"],
+            "gaps": ["缺少标题与ASR，无法提取钩子原话"],
+            "evidence": "开头句缺失",
+        }
+
+    hook_type = "陈述式"
+    if any(k in first for k in ["?", "？", "为什么", "怎么"]):
+        hook_type = "疑问式"
+    elif any(k in first for k in ["别再", "误区", "真相", "不是"]):
+        hook_type = "反常识式"
+    elif any(k in first for k in ["当你", "如果", "今天"]):
+        hook_type = "场景代入式"
+
+    end_candidates = [u for u in _sentence_units(asr) if _hit_count(u, ["关注", "评论", "私信", "收藏", "转发", "下次见", "领取"]) > 0]
+    end = end_candidates[-1] if end_candidates else "未检测到明确结尾钩子"
+
+    lines = [
+        f"- 开头钩子（{hook_type}）：{first}",
+        f"- 中段钩子：{middle or '数据不足（中段文本不足）'}",
+        f"- 结尾钩子：{end}",
+    ]
+
+    hook_hits = int(first != "") + int(bool(middle)) + int(end != "未检测到明确结尾钩子")
+    return {
+        "score": _score_from_hits(hook_hits, full_score_hits=3),
+        "lines": lines,
+        "gaps": [] if hook_hits >= 2 else ["建议补充中段转折钩子与结尾动作钩子"],
+        "evidence": f"hook_type={hook_type}, hook_hits={hook_hits}",
+    }
+
+
+def _analyze_structure(fields: Dict[str, Any]) -> Dict[str, Any]:
+    asr = normalize_text(fields.get("asr_clean") or "")
+    units = _sentence_units(asr)
+    if not units:
+        return {
+            "score": 2,
+            "lines": ["- 结构标签：数据不足。", "- 模板判定：数据不足。"],
+            "gaps": ["补充ASR后再进行结构标注"],
+            "evidence": "分句为空",
+        }
+
+    label_rules = {
+        "钩子": ["?", "？", "为什么", "怎么", "别再", "真相", "当你", "如果"],
+        "冲突": ["但是", "却", "问题", "误区", "卡住", "焦虑", "失败"],
+        "转折": ["所以", "于是", "然后", "接着", "这时候", "其实"],
+        "举证": ["数据", "案例", "比如", "步骤", "第一", "第二", "第三"],
+        "CTA": ["评论", "关注", "私信", "收藏", "转发", "点击", "领取", "报名"],
+    }
+    coverage = {k: 0 for k in label_rules}
+    for sent in units:
+        for label, kws in label_rules.items():
+            if any(kw in sent for kw in kws):
+                coverage[label] += 1
+
+    present = [k for k, v in coverage.items() if v > 0]
+    missing = [k for k, v in coverage.items() if v == 0]
+    template = "钩子→冲突→转折→举证→CTA" if len(present) >= 4 else "钩子→观点→补充说明"
+
+    lines = [
+        f"- 结构标签覆盖：{', '.join([f'{k}:{v}' for k, v in coverage.items()])}。",
+        f"- 模板判定：{template}。",
+        f"- 缺失模块：{'、'.join(missing) if missing else '无'}。",
+    ]
+
+    return {
+        "score": _score_from_hits(len(present), full_score_hits=5),
+        "lines": lines,
+        "gaps": [f"优先补齐结构模块：{'、'.join(missing)}"] if missing else [],
+        "evidence": f"coverage={coverage}",
+    }
+
+
+def _analyze_cta(fields: Dict[str, Any]) -> Dict[str, Any]:
+    asr = normalize_text(fields.get("asr_clean") or "")
+    units = _sentence_units(asr)
+    cta_tokens = ["评论", "关注", "私信", "收藏", "转发", "点击", "领取", "报名", "下单", "咨询", "试试"]
+    cta_sentences = [u for u in units if any(token in u for token in cta_tokens)]
+
+    if not units:
+        return {
+            "score": 2,
+            "lines": ["- CTA策略：数据不足。", "- 行动指令：数据不足。"],
+            "gaps": ["缺少ASR，无法识别CTA"],
+            "evidence": "分句为空",
+        }
+
+    if not cta_sentences:
+        return {
+            "score": 2,
+            "lines": ["- CTA策略：未检测到明确行动号召。", "- 行动指令：建议补一句“评论区/私信领取”。"],
+            "gaps": ["补充单一明确CTA，避免只有信息陈述"],
+            "evidence": "cta_sentences=0",
+        }
+
+    primary_cta = cta_sentences[-1]
+    cta_types = []
+    if any(k in asr for k in ["评论", "点赞", "收藏", "转发", "关注"]):
+        cta_types.append("互动型")
+    if any(k in asr for k in ["私信", "领取", "链接", "资料"]):
+        cta_types.append("线索型")
+    if any(k in asr for k in ["下单", "报名", "咨询", "购买"]):
+        cta_types.append("转化型")
+
+    lines = [
+        f"- CTA类型：{'、'.join(cta_types) if cta_types else '互动型（弱）'}。",
+        f"- 关键动作句：{primary_cta}",
+        f"- CTA密度：{len(cta_sentences)}/{len(units)} 句。",
+    ]
+
+    return {
+        "score": _score_from_hits(len(cta_types) + int(len(cta_sentences) > 0), full_score_hits=3),
+        "lines": lines,
+        "gaps": [] if len(cta_types) > 0 else ["补充线索型或转化型CTA，提高商业闭环"],
+        "evidence": f"cta_types={cta_types}, cta_count={len(cta_sentences)}",
+    }
+
+
+def _build_summary_module(results: Dict[str, Dict[str, Any]]) -> Dict[str, Any]:
+    ordered = ["选题", "文风", "Hook", "结构", "CTA"]
+    scored = [(name, results[name]["score"]) for name in ordered]
+    avg_score = round(sum(score for _, score in scored) / max(1, len(scored)), 2)
+    weakest = sorted(scored, key=lambda x: x[1])[:2]
+
+    if avg_score >= 4.2:
+        verdict = "可直接复用"
+    elif avg_score >= 3.4:
+        verdict = "可用，但需小幅优化"
+    else:
+        verdict = "需重写关键模块后再投放"
+
+    suggestions = []
+    for name, _ in weakest:
+        gaps = results[name].get("gaps") or []
+        if gaps:
+            suggestions.append(f"- [{name}] {gaps[0]}")
+    if not suggestions:
+        suggestions = ["- 保持当前结构，持续做A/B测试验证Hook与CTA。"]
+
+    return {
+        "score": int(round(avg_score)),
+        "lines": [
+            f"- 结论：综合评分 {avg_score}/5，判定为“{verdict}”。",
+            "- 建议：",
+            *suggestions[:3],
+        ],
+        "gaps": [],
+        "evidence": f"scores={dict(scored)}",
+    }
+
+
+def _insight_metric_snapshot(fields: Dict[str, Any]) -> Dict[str, Any]:
+    digg = _safe_int(fields.get("digg_count"), default=0)
+    comment = _safe_int(fields.get("comment_count"), default=0)
+    collect = _safe_int(fields.get("collect_count"), default=0)
+    share = _safe_int(fields.get("share_count"), default=0)
+    play = _safe_int(fields.get("play_count"), default=0)
+
+    interaction = digg + comment * 2 + collect * 3 + share * 4
+    interaction_rate = interaction / play if play > 0 else 0.0
+    return {
+        "interaction": interaction,
+        "interaction_rate": interaction_rate,
+        "digg": digg,
+        "comment": comment,
+        "collect": collect,
+        "share": share,
+    }
+
+
+def _build_local_analysis_sections(fields: Dict[str, Any]) -> Dict[str, Any]:
+    topic = _analyze_topic(fields)
+    style = _analyze_style(fields)
+    hook = _analyze_hook(fields)
+    structure = _analyze_structure(fields)
+    cta = _analyze_cta(fields)
+    summary = _build_summary_module(
+        {
+            "选题": topic,
+            "文风": style,
+            "Hook": hook,
+            "结构": structure,
+            "CTA": cta,
+        }
+    )
+    metrics = _insight_metric_snapshot(fields)
+    insight_lines = list(summary.get("lines") or [])
+    insight_lines.extend(
+        [
+            f"- 互动折算值：{metrics.get('interaction', 0)}。",
+            f"- 粗略互动率：{metrics.get('interaction_rate', 0.0):.4f}。",
+        ]
+    )
+    return {
+        "modules": {
+            "选题": topic.get("lines", ["数据不足"]),
+            "文风": style.get("lines", ["数据不足"]),
+            "Hook": hook.get("lines", ["数据不足"]),
+            "结构": structure.get("lines", ["数据不足"]),
+        },
+        "insight": insight_lines or ["数据不足"],
+    }
+
+
+def build_card_analysis_artifact(
+    *,
+    payload: Dict[str, Any],
+    platform: str,
+    card_type: str,
+) -> Dict[str, Any]:
+    fields = _extract_required_fields(payload, platform=platform)
+    precomputed = fields.get("analysis_sections") if isinstance(fields.get("analysis_sections"), dict) else {}
+    if precomputed:
+        analysis_sections = precomputed
+    elif card_type == "author":
+        analysis_sections = {}
+    else:
+        analysis_sections = build_analysis_sections(fields)
+    fields["analysis_sections"] = analysis_sections
+    return {
+        "fields": fields,
+        "analysis_sections": analysis_sections,
+    }
+
+
+def _build_output_path(
+    *,
+    card_root: str,
+    platform: str,
+    card_type: str,
+    payload: Dict[str, Any],
+    now: dt.datetime,
+    sample_author: Optional[str],
+    storage_config: Optional[Dict[str, Any]],
+) -> Dict[str, str]:
+    author_slug = _pick_author_slug(payload, author_hint=sample_author)
+    title_slug = _pick_title_slug(payload)
+
+    path, route_parts = build_card_output_path(
+        card_root=card_root,
+        platform=platform,
+        card_type=card_type,
+        author_slug=author_slug,
+        title_slug=title_slug,
+        year=now.strftime("%Y"),
+        year_month=now.strftime("%Y-%m"),
+        timestamp=now.strftime("%Y%m%d-%H%M%S"),
+        storage_config=storage_config,
+    )
+    return {
+        "path": path,
+        "route_parts": route_parts,
+        "author_slug": author_slug,
+        "title_slug": title_slug,
+        "target_type": card_type,
+    }
+
+
+def _render_author_markdown(
+    *,
+    card_id: str,
+    card_type: str,
+    fields: Dict[str, Any],
+    generated_at: str,
+) -> str:
+    analysis_output = fields.get("analysis_output") if isinstance(fields.get("analysis_output"), dict) else {}
+    author_analysis_v2 = fields.get("author_analysis_v2") if isinstance(fields.get("author_analysis_v2"), dict) else analysis_output.get("author_analysis_v2", {})
+    if not isinstance(author_analysis_v2, dict):
+        author_analysis_v2 = {}
+    sampled_work_explanations = fields.get("sampled_work_explanations") if isinstance(fields.get("sampled_work_explanations"), dict) else analysis_output.get("sampled_work_explanations", {})
+    if not isinstance(sampled_work_explanations, dict):
+        sampled_work_explanations = {}
+    author_card_highlights = fields.get("author_card_highlights") if isinstance(fields.get("author_card_highlights"), dict) else {}
+    if not isinstance(author_card_highlights, dict):
+        author_card_highlights = {}
+    validation = fields.get("validation") if isinstance(fields.get("validation"), dict) else analysis_output.get("validation", {})
+    if not isinstance(validation, dict):
+        validation = {}
+
+    business_score = _safe_int(fields.get("business_score"), default=_safe_int(analysis_output.get("business_score"), default=0))
+    benchmark_gap_score = _safe_int(fields.get("benchmark_gap_score"), default=_safe_int(analysis_output.get("benchmark_gap_score"), default=0))
+    style_radar = fields.get("style_radar") if isinstance(fields.get("style_radar"), dict) else analysis_output.get("style_radar", {})
+    if not isinstance(style_radar, dict):
+        style_radar = {}
+
+    core_contradictions = fields.get("core_contradictions") if isinstance(fields.get("core_contradictions"), list) else analysis_output.get("core_contradictions", [])
+    if not isinstance(core_contradictions, list):
+        core_contradictions = []
+
+    recommendations = fields.get("recommendations") if isinstance(fields.get("recommendations"), list) else analysis_output.get("recommendations", [])
+    if not isinstance(recommendations, list):
+        recommendations = []
+
+    business_analysis = normalize_text(fields.get("business_analysis")) or normalize_text(analysis_output.get("business_analysis"))
+    benchmark_analysis = normalize_text(fields.get("benchmark_analysis")) or normalize_text(analysis_output.get("benchmark_analysis"))
+    author_portrait = normalize_text(author_card_highlights.get("one_liner")) or normalize_text(fields.get("summary")) or normalize_text(analysis_output.get("author_portrait"))
+
+    fm = {
+        "card_id": card_id,
+        "card_type": card_type,
+        "platform": fields.get("platform"),
+        "generated_at": generated_at,
+        "updated_at": generated_at,
+        "title": fields.get("title"),
+        "platform_work_id": fields.get("platform_work_id"),
+        "author": fields.get("author"),
+        "author_handle": fields.get("author_handle"),
+        "platform_author_id": fields.get("platform_author_id"),
+        "nickname": fields.get("nickname"),
+        "ip_location": fields.get("ip_location"),
+        "avatar_url": fields.get("avatar_url"),
+        "signature": fields.get("signature"),
+        "fans_count": fields.get("fans_count"),
+        "liked_count": fields.get("liked_count"),
+        "collected_count": fields.get("collected_count"),
+        "works_count": fields.get("works_count"),
+        "verified": fields.get("verified"),
+        "snapshot_at": fields.get("snapshot_at"),
+        "business_score": business_score,
+        "benchmark_gap_score": benchmark_gap_score,
+        "request_id": fields.get("request_id"),
+    }
+
+    frontmatter = ["---"]
+    for key, value in fm.items():
+        frontmatter.append(f"{key}: {json.dumps(value, ensure_ascii=False)}")
+    frontmatter.append("---")
+
+    lines = [
+        *frontmatter,
+        "",
+        "## 基础事实",
+        f"- 平台：{fields.get('platform') or '未知'}",
+        f"- 作者ID：{fields.get('platform_author_id') or '未知'}",
+        f"- 账号标识：{fields.get('author_handle') or 'N/A'}",
+        f"- 昵称：{fields.get('nickname') or fields.get('author') or '未知'}",
+        f"- IP属地：{fields.get('ip_location') or 'N/A'}",
+        f"- 签名：{fields.get('signature') or 'N/A'}",
+        f"- 头像：{fields.get('avatar_url') or 'N/A'}",
+        f"- 粉丝数：{_display_metric(fields.get('fans_count'))}",
+        f"- 累计获赞：{_display_metric(fields.get('liked_count'))}",
+        f"- 累计收藏：{_display_metric(fields.get('collected_count'))}",
+        f"- 作品数：{_display_metric(fields.get('works_count'))}",
+        f"- 认证状态：{'是' if fields.get('verified') else '否'}" if fields.get('verified') is not None else "- 认证状态：N/A",
+        f"- 抓取时间：{fields.get('snapshot_at') or 'N/A'}",
+        "",
+        "## 作者画像",
+        author_portrait or "数据不足",
+        "",
+        "## 主页摘要卡",
+        f"- 核心价值：{normalize_text(author_card_highlights.get('core_value_proposition')) or '数据不足'}",
+        f"- 主要信任源：{normalize_text(author_card_highlights.get('primary_trust_source')) or '数据不足'}",
+        f"- 胜率结构：{('、'.join([normalize_text(x) for x in author_card_highlights.get('winning_content_structures', []) if normalize_text(x)])) or '数据不足'}",
+        f"- 可能产品：{('、'.join([normalize_text(x) for x in author_card_highlights.get('likely_products', []) if normalize_text(x)])) or '证据不足'}",
+        f"- 最大张力：{normalize_text(author_card_highlights.get('most_important_tension')) or '数据不足'}",
+        f"- 只学一件事：{normalize_text(author_card_highlights.get('if_only_learn_one_thing')) or '数据不足'}",
+        "",
+        "## 商业分析",
+        business_analysis or "数据不足",
+        "",
+        "## 对标分析",
+        benchmark_analysis or "数据不足",
+        "",
+        "## 评分",
+        f"- business_score: {business_score}",
+        f"- benchmark_gap_score: {benchmark_gap_score}",
+        "",
+        "## 风格雷达",
+        "```json",
+        json.dumps(style_radar, ensure_ascii=False, indent=2),
+        "```",
+        "",
+        "## 核心矛盾",
+    ]
+
+    if core_contradictions:
+        lines.extend([f"- {normalize_text(item)}" for item in core_contradictions if normalize_text(item)])
+    else:
+        lines.append("- 数据不足")
+
+    lines.extend(["", "## 建议动作"])
+    if recommendations:
+        lines.extend([f"- {normalize_text(item)}" for item in recommendations if normalize_text(item)])
+    else:
+        lines.append("- 数据不足")
+
+    lines.extend(
+        [
+            "",
+            "## author_analysis_v2",
+            "```json",
+            json.dumps(author_analysis_v2, ensure_ascii=False, indent=2),
+            "```",
+            "",
+            "## sampled_work_explanations",
+            "```json",
+            json.dumps(sampled_work_explanations, ensure_ascii=False, indent=2),
+            "```",
+            "",
+            "## 校验",
+            f"- validation_ok: {bool(validation.get('ok'))}",
+            f"- validation_error_count: {len(validation.get('errors') or [])}",
+            "",
+            "## 附录",
+            f"- confidence: {fields.get('confidence')}",
+            f"- error_reason: {fields.get('error_reason')}",
+            "",
+            "```json",
+            json.dumps(fields.get("extract_trace", []), ensure_ascii=False, indent=2),
+            "```",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _render_markdown(
+    *,
+    card_id: str,
+    card_type: str,
+    fields: Dict[str, Any],
+    generated_at: str,
+) -> str:
+    if card_type == "author":
+        return _render_author_markdown(
+            card_id=card_id,
+            card_type=card_type,
+            fields=fields,
+            generated_at=generated_at,
+        )
+    author_name = fields.get("author") or fields.get("author_handle") or fields.get("platform_author_id") or "未知作者"
+    title = fields.get("title") or "（标题缺失）"
+    metrics_line = (
+        f"赞 {_display_metric(fields.get('digg_count'))} / 评 {_display_metric(fields.get('comment_count'))} / "
+        f"藏 {_display_metric(fields.get('collect_count'))} / 转 {_display_metric(fields.get('share_count'))} / 播 {_display_metric(fields.get('play_count'))}"
+    )
+    precomputed_sections = fields.get("analysis_sections") if isinstance(fields.get("analysis_sections"), dict) else {}
+    if precomputed_sections:
+        analysis_sections = precomputed_sections
+    else:
+        analysis_sections = {} if card_type == "author_sample_work" else build_analysis_sections(fields)
+    creative_modules = analysis_sections.get("modules", {})
+    insight_lines = analysis_sections.get("insight", ["数据不足"])
+    extract_trace_json = json.dumps(fields.get("extract_trace", []), ensure_ascii=False, indent=2)
+
+    fm = {
+        "card_id": card_id,
+        "card_type": card_type,
+        "platform": fields.get("platform"),
+        "generated_at": generated_at,
+        "updated_at": generated_at,
+        "title": fields.get("title"),
+        "platform_work_id": fields.get("platform_work_id"),
+        "author": fields.get("author"),
+        "author_handle": fields.get("author_handle"),
+        "platform_author_id": fields.get("platform_author_id"),
+        "caption_raw": fields.get("caption_raw"),
+        "primary_text": fields.get("primary_text"),
+        "share_url": fields.get("share_url"),
+        "source_url": fields.get("source_url"),
+        "cover_image": fields.get("cover_image"),
+        "video_download_url": fields.get("video_download_url"),
+        "published_date": fields.get("published_date"),
+        "duration_ms": fields.get("duration_ms"),
+        "digg_count": fields.get("digg_count"),
+        "comment_count": fields.get("comment_count"),
+        "collect_count": fields.get("collect_count"),
+        "share_count": fields.get("share_count"),
+        "play_count": fields.get("play_count"),
+        "tags": fields.get("tags", []),
+        "work_modality": fields.get("work_modality"),
+    }
+
+    frontmatter = ["---"]
+    for key, value in fm.items():
+        frontmatter.append(f"{key}: {json.dumps(value, ensure_ascii=False)}")
+    frontmatter.append("---")
+
+    lines = [
+        *frontmatter,
+        "",
+        "## 基础信息",
+        f"- 作者：{author_name}",
+        f"- 标题：{title}",
+        f"- 原始文案：{fields.get('caption_raw') or 'N/A'}",
+        f"- 作品模态：{fields.get('work_modality') or '未知'}",
+        f"- 发布时间：{fields.get('published_date') or 'N/A'}",
+        f"- {'视频时长' if fields.get('work_modality') == 'video' else '阅读载体'}：{_format_duration(fields.get('duration_ms', 0)) if fields.get('work_modality') == 'video' else '文本'}",
+        f"- 互动：{metrics_line}",
+        f"- 链接：{fields.get('share_url') or '（未提供）'}",
+        f"- 下载链接：{fields.get('video_download_url') or 'N/A'}" if fields.get("work_modality") == "video" else "- 下载链接：N/A",
+    ]
+
+    for heading in DEFAULT_MODULE_SECTIONS:
+        lines.append("")
+        lines.append(f"## {heading}")
+        for item in creative_modules.get(heading, ["数据不足"]):
+            lines.append(item)
+
+    lines.append("")
+    lines.append("## 洞察分析")
+    for item in insight_lines:
+        lines.append(item)
+
+    transcript_heading = "## 主文本"
+    transcript_body = fields.get("primary_text")
+    transcript_fallback = "（无可用主文本）"
+
+    lines.extend(
+        [
+            "",
+            transcript_heading,
+            transcript_body or transcript_fallback,
+        ]
+    )
+
+    lines.extend(
+        [
+            "",
+            "## 附录",
+            "### ASR_RAW",
+            fields.get("raw_content") or "（无可用 ASR 原文）",
+            "",
+            "### trace",
+            f"- request_id: {fields.get('request_id')}",
+            f"- confidence: {fields.get('confidence')}",
+            f"- error_reason: {fields.get('error_reason')}",
+            "",
+            "<details>",
+            "<summary>extract_trace（点击展开）</summary>",
+            "",
+            "```json",
+            extract_trace_json,
+            "```",
+            "",
+            "</details>",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _write_file(path: str, content: str) -> None:
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(content)
+
+
+def _resolve_card_root(card_root: Optional[str]) -> str:
+    raw = (card_root or "").strip()
+    if not raw:
+        return resolve_default_card_root()
+
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        raise ValueError("card_root must be an absolute path")
+    return str(candidate.resolve())
+
+
+def write_benchmark_card(
+    *,
+    payload: Dict[str, Any],
+    platform: str,
+    card_type: str,
+    card_root: Optional[str],
+    sample_author: Optional[str] = None,
+    content_kind: Optional[str] = None,
+    storage_config: Optional[Dict[str, Any]] = None,
+    force_card_type: bool = False,
+) -> Dict[str, Any]:
+    now = dt.datetime.now()
+    generated_at = now.isoformat(timespec="seconds")
+
+    payload_content_kind = normalize_text(payload.get("content_kind"))
+    resolved_content_kind = normalize_text(content_kind) or payload_content_kind
+
+    normalized_card_type = normalize_card_type(card_type)
+    effective_card_type = resolve_effective_card_type(
+        card_type=normalized_card_type,
+        content_kind=resolved_content_kind,
+        storage_config=storage_config,
+        force_card_type=force_card_type,
+    )
+    fields = _extract_required_fields(payload, platform=platform)
+    resolved_card_root = _resolve_card_root(card_root)
+
+    primary_target = _build_output_path(
+        card_root=resolved_card_root,
+        platform=platform,
+        card_type=effective_card_type,
+        payload=payload,
+        now=now,
+        sample_author=sample_author,
+        storage_config=storage_config,
+    )
+    primary_path = primary_target["path"]
+
+    primary_card_id = os.path.basename(primary_path).replace(".md", "")
+    primary_markdown = _render_markdown(
+        card_id=primary_card_id,
+        card_type=effective_card_type,
+        fields=fields,
+        generated_at=generated_at,
+    )
+    _write_file(primary_path, primary_markdown)
+
+    return {
+        "ok": True,
+        "platform": platform,
+        "card_type": effective_card_type,
+        "requested_card_type": normalized_card_type,
+        "force_card_type": bool(force_card_type),
+        "content_kind": resolved_content_kind or None,
+        "primary_card_path": primary_path,
+        "routing": {
+            "primary_route_parts": primary_target["route_parts"],
+            "storage_routes_configured": bool(isinstance(storage_config, dict) and isinstance(storage_config.get("storage_routes"), dict)),
+        },
+        "required_fields": fields,
+    }
+
+
+def _read_payload_from_input(input_json: str) -> Dict[str, Any]:
+    if input_json == "-":
+        raw = os.read(0, 1024 * 1024).decode("utf-8", errors="replace").strip()
+        if not raw:
+            return {}
+        return json.loads(raw)
+    return read_json_file(input_json)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Write benchmark card markdown to card root")
+    parser.add_argument("--platform", required=True, help="Platform name, e.g. douyin or xiaohongshu")
+    parser.add_argument("--card-type", choices=CARD_TYPES, default="work", help="Primary card type")
+    parser.add_argument("--config", default=None, help="Runtime config YAML path")
+    parser.add_argument("--env-file", default=None, help="Shared env file path; defaults to <skills_root>/.env")
+    parser.add_argument("--allow-process-env", action="store_true", help="Allow process env to override .env/.env.local")
+    parser.add_argument("--sample-author", default=None, help="Optional author slug override for author_sample_work")
+    parser.add_argument("--content-kind", default=None, help="Optional workflow kind, e.g. single_video/author_home/author_analysis")
+    parser.add_argument("--force-card-type", action="store_true", help="Force manual --card-type to override content_kind mapping")
+    parser.add_argument("--card-root", default=None, help="Card root path (absolute); falls back to TIKOMNI_CARD_ROOT when omitted")
+    parser.add_argument(
+        "--input-json",
+        default="-",
+        help="Input JSON path or '-' to read from stdin",
+    )
+    args = parser.parse_args()
+
+    config, _ = load_tikomni_config(
+        args.config,
+        env_file=args.env_file,
+        allow_process_env=args.allow_process_env,
+    )
+    payload = _read_payload_from_input(args.input_json)
+    result = write_benchmark_card(
+        payload=payload,
+        platform=args.platform,
+        card_type=args.card_type,
+        card_root=args.card_root,
+        sample_author=args.sample_author,
+        content_kind=args.content_kind,
+        storage_config=config,
+        force_card_type=args.force_card_type,
+    )
+    write_json_stdout(result)
+
+
+if __name__ == "__main__":
+    main()