@tikomni/skills 0.1.3 → 0.1.4

package/skills/social-media-crawl/scripts/writers/write_work_fact_card.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""Write work fact cards and normalized envelopes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from scripts.core.completeness import ensure_request_id, evaluate_work_fact_card, normalize_missing_fields
+from scripts.core.config_loader import resolve_storage_paths
+from scripts.core.storage_router import (
+    build_work_fact_card_paths,
+    render_output_filename,
+    resolve_card_root,
+    resolve_json_filename_pattern,
+)
+
+SHANGHAI_TZ = timezone(timedelta(hours=8))
+
+
+def _safe_text(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _safe_int(value: Any) -> int:
+    if value is None:
+        return 0
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    text = _safe_text(value)
+    if not text:
+        return 0
+    try:
+        return int(float(text.replace(",", "")))
+    except Exception:
+        return 0
+
+
+def _source_dict(payload: Dict[str, Any]) -> Dict[str, Any]:
+    source = payload.get("source")
+    return source if isinstance(source, dict) else {}
+
+
+def _author_dict(payload: Dict[str, Any]) -> Dict[str, Any]:
+    author = payload.get("author")
+    return author if isinstance(author, dict) else {}
+
+
+def _resolve_platform(payload: Dict[str, Any], platform: Optional[str]) -> str:
+    return _safe_text(platform or payload.get("platform")) or "unknown"
+
+
+def _resolve_work_id(payload: Dict[str, Any]) -> str:
+    for key in ("platform_work_id", "note_id", "aweme_id", "id"):
+        hit = _safe_text(payload.get(key))
+        if hit:
+            return hit
+    source = _source_dict(payload)
+    for key in ("note_id", "platform_work_id"):
+        hit = _safe_text(source.get(key))
+        if hit:
+            return hit
+    return ""
+
+
+def _resolve_author_display(payload: Dict[str, Any]) -> str:
+    author_raw = payload.get("author")
+    author_obj = _author_dict(payload)
+    if isinstance(author_raw, str) and _safe_text(author_raw):
+        return _safe_text(author_raw)
+    for key in ("nickname", "author_handle", "platform_author_id"):
+        hit = _safe_text(author_obj.get(key))
+        if hit:
+            return hit
+    for key in ("nickname", "author_handle", "platform_author_id"):
+        hit = _safe_text(payload.get(key))
+        if hit:
+            return hit
+    return ""
+
+
+def _resolve_author_handle(payload: Dict[str, Any]) -> str:
+    author_obj = _author_dict(payload)
+    source = _source_dict(payload)
+    for key in ("author_handle", "short_id", "red_id"):
+        for container in (payload, author_obj, source):
+            hit = _safe_text(container.get(key))
+            if hit:
+                return hit
+    return _resolve_author_display(payload)
+
+
+def _resolve_platform_author_id(payload: Dict[str, Any]) -> str:
+    author_obj = _author_dict(payload)
+    source = _source_dict(payload)
+    for key in (
+        "platform_author_id",
+        "author_platform_id",
+        "xhs_user_id",
+        "douyin_aweme_author_id",
+        "uid",
+    ):
+        for container in (payload, author_obj, source):
+            hit = _safe_text(container.get(key))
+            if hit:
+                return hit
+    return ""
+
+
+def _resolve_title(payload: Dict[str, Any]) -> str:
+    for key in ("title", "display_title", "name"):
+        hit = _safe_text(payload.get(key))
+        if hit:
+            return hit
+    caption = _resolve_caption(payload)
+    return caption[:60] if caption else ""
+
+
+def _resolve_caption(payload: Dict[str, Any]) -> str:
+    source = _source_dict(payload)
+    for key in ("caption_raw", "desc", "content", "raw_content", "summary"):
+        for container in (payload, source):
+            hit = _safe_text(container.get(key))
+            if hit:
+                return hit
+    return ""
+
+
+def _to_timestamp(value: Any) -> Optional[int]:
+    raw = _safe_int(value)
+    if raw <= 0:
+        return None
+    if raw > 1_000_000_000_000:
+        raw //= 1000
+    return raw if raw > 0 else None
+
+
+def _resolve_published_date(payload: Dict[str, Any]) -> str:
+    for key in ("published_date", "publish_time_text"):
+        hit = _safe_text(payload.get(key))
+        if hit:
+            return hit[:10] if len(hit) >= 10 else hit
+    for key in ("publish_time", "create_time_sec", "create_time", "time"):
+        ts = _to_timestamp(payload.get(key))
+        if ts:
+            return datetime.fromtimestamp(ts, tz=SHANGHAI_TZ).strftime("%Y-%m-%d")
+    return ""
+
+
+def _resolve_work_modality(payload: Dict[str, Any]) -> str:
+    modality = _safe_text(payload.get("work_modality")).lower()
+    if modality:
+        return modality
+    content_type = _safe_text(payload.get("note_content_type") or payload.get("content_type")).lower()
+    if content_type in {"video", "single_video", "video_note"}:
+        return "video"
+    if content_type in {"image", "photo", "text", "note"}:
+        return "text"
+    if payload.get("is_video") is True:
+        return "video"
+    return "video" if _safe_text(payload.get("video_download_url") or payload.get("video_down_url")) else "text"
+
+
+def _resolve_source_url(payload: Dict[str, Any], platform: str, work_id: str) -> str:
+    source = _source_dict(payload)
+    for key in ("source_url", "url", "note_url"):
+        for container in (payload, source):
+            hit = _safe_text(container.get(key))
+            if hit:
+                return hit
+    if platform == "douyin" and work_id:
+        return f"https://www.douyin.com/video/{work_id}"
+    if platform == "xiaohongshu" and work_id:
+        return f"https://www.xiaohongshu.com/explore/{work_id}"
+    return ""
+
+
+def _resolve_share_url(payload: Dict[str, Any], source_url: str) -> str:
+    source = _source_dict(payload)
+    for key in ("share_url", "share_link", "share_text"):
+        for container in (payload, source):
+            hit = _safe_text(container.get(key))
+            if hit:
+                return hit
+    return source_url
+
+
+def _resolve_primary_text(payload: Dict[str, Any], caption_raw: str) -> Dict[str, str]:
+    subtitle_raw = _safe_text(payload.get("subtitle_raw"))
+    asr_clean = _safe_text(payload.get("asr_clean"))
+    asr_raw = _safe_text(payload.get("asr_raw"))
+    if subtitle_raw:
+        return {"primary_text": subtitle_raw, "primary_text_source": "subtitle_raw"}
+    if asr_clean:
+        return {"primary_text": asr_clean, "primary_text_source": "asr_clean"}
+    if asr_raw:
+        return {"primary_text": asr_raw, "primary_text_source": "asr_raw"}
+    if caption_raw:
+        return {"primary_text": caption_raw, "primary_text_source": "caption_raw"}
+    return {"primary_text": "", "primary_text_source": "missing"}
+
+
+def build_work_fact_card(payload: Dict[str, Any], platform: Optional[str] = None) -> Dict[str, Any]:
+    platform_name = _resolve_platform(payload, platform)
+    work_id = _resolve_work_id(payload)
+    caption_raw = _resolve_caption(payload)
+    source_url = _resolve_source_url(payload, platform_name, work_id)
+    share_url = _resolve_share_url(payload, source_url)
+    author_handle = _resolve_author_handle(payload)
+    platform_author_id = _resolve_platform_author_id(payload)
+    primary_text_bundle = _resolve_primary_text(payload, caption_raw)
+
+    card: Dict[str, Any] = {
+        "platform": platform_name,
+        "platform_work_id": work_id,
+        "platform_author_id": platform_author_id,
+        "author_handle": author_handle,
+        "author": _resolve_author_display(payload),
+        "title": _resolve_title(payload),
+        "caption_raw": caption_raw,
+        "subtitle_raw": _safe_text(payload.get("subtitle_raw")),
+        "work_modality": _resolve_work_modality(payload),
+        "published_date": _resolve_published_date(payload),
+        "digg_count": _safe_int(payload.get("digg_count")),
+        "comment_count": _safe_int(payload.get("comment_count")),
+        "collect_count": _safe_int(payload.get("collect_count")),
+        "share_count": _safe_int(payload.get("share_count")),
+        "play_count": _safe_int(payload.get("play_count")),
+        "cover_image": _safe_text(payload.get("cover_image")),
+        "source_url": source_url,
+        "share_url": share_url,
+        "video_download_url": _safe_text(payload.get("video_download_url") or payload.get("video_down_url")),
+        "primary_text": primary_text_bundle["primary_text"],
+        "primary_text_source": primary_text_bundle["primary_text_source"],
+        "asr_raw": _safe_text(payload.get("asr_raw")),
+        "asr_clean": _safe_text(payload.get("asr_clean")),
+        "request_id": ensure_request_id(_safe_text(payload.get("request_id")), fallback_seed=share_url or work_id or caption_raw),
+        "missing_fields": normalize_missing_fields(payload.get("missing_fields")),
+        "error_reason": _safe_text(payload.get("error_reason")) or None,
+        "extract_trace": payload.get("extract_trace") if isinstance(payload.get("extract_trace"), list) else [],
+    }
+    existing_missing = {(entry.get("field"), entry.get("reason")) for entry in card["missing_fields"]}
+    if (
+        card["work_modality"] == "video"
+        and not card["asr_clean"]
+        and not card["asr_raw"]
+        and not card["subtitle_raw"]
+        and ("asr_clean", "caption_fallback") not in existing_missing
+    ):
+        card["missing_fields"].append({"field": "asr_clean", "reason": "caption_fallback"})
+    evaluation = evaluate_work_fact_card(card)
+    card["completeness"] = evaluation["completeness"]
+    card["missing_fields"] = evaluation["missing_fields"]
+    return card
+
+
+def build_work_output_envelope(payload: Dict[str, Any], platform: Optional[str] = None) -> Dict[str, Any]:
+    card = build_work_fact_card(payload, platform=platform)
+    source = _source_dict(payload)
+    input_value = source.get("share_url") or source.get("share_text") or source.get("source_url") or source
+    return {
+        "object_type": "work",
+        "platform": card["platform"],
+        "input": input_value,
+        "normalized": card,
+        "completeness": card["completeness"],
+        "missing_fields": card["missing_fields"],
+        "error_reason": card.get("error_reason"),
+        "extract_trace": card.get("extract_trace", []),
+        "request_id": card["request_id"],
+    }
+
+
+def _markdown_lines(card: Dict[str, Any]) -> List[str]:
+    lines = [
+        f"# {card.get('title') or card.get('platform_work_id') or 'Work'}",
+        "",
+        "## Facts",
+        f"- platform: {card.get('platform') or ''}",
+        f"- platform_work_id: {card.get('platform_work_id') or ''}",
+        f"- platform_author_id: {card.get('platform_author_id') or ''}",
+        f"- author_handle: {card.get('author_handle') or ''}",
+        f"- author: {card.get('author') or ''}",
+        f"- published_date: {card.get('published_date') or ''}",
+        f"- work_modality: {card.get('work_modality') or ''}",
+        f"- digg_count: {card.get('digg_count')}",
+        f"- comment_count: {card.get('comment_count')}",
+        f"- collect_count: {card.get('collect_count')}",
+        f"- share_count: {card.get('share_count')}",
+        f"- play_count: {card.get('play_count')}",
+        f"- source_url: {card.get('source_url') or ''}",
+        f"- share_url: {card.get('share_url') or ''}",
+        f"- video_download_url: {card.get('video_download_url') or ''}",
+        "",
+        "## Text",
+        card.get("primary_text") or "",
+        "",
+        "## Meta",
+        f"- primary_text_source: {card.get('primary_text_source') or ''}",
+        f"- completeness: {card.get('completeness') or ''}",
+        f"- request_id: {card.get('request_id') or ''}",
+        f"- error_reason: {card.get('error_reason') or ''}",
+    ]
+    if card.get("missing_fields"):
+        lines.extend(["", "## Missing Fields"])
+        for entry in card["missing_fields"]:
+            lines.append(f"- {entry.get('field')}: {entry.get('reason')}")
+    return lines
+
+
+def write_work_fact_card(
+    *,
+    payload: Dict[str, Any],
+    platform: Optional[str] = None,
+    card_root: Optional[str] = None,
+    storage_config: Optional[Dict[str, Any]] = None,
+    **_: Any,
+) -> Dict[str, Any]:
+    card = build_work_fact_card(payload, platform=platform)
+    resolved_card_root = resolve_card_root(storage_config, explicit_card_root=card_root)
+    fallback_identifier = card["share_url"] or card["source_url"] or card["title"] or card["request_id"]
+    paths = build_work_fact_card_paths(
+        card_root=resolved_card_root,
+        platform=card["platform"],
+        platform_work_id=card["platform_work_id"],
+        author_handle=card["author_handle"],
+        platform_author_id=card["platform_author_id"],
+        storage_config=storage_config,
+        fallback_identifier=fallback_identifier,
+    )
+
+    Path(paths["json_path"]).write_text(json.dumps(card, ensure_ascii=False, indent=2), encoding="utf-8")
+    Path(paths["markdown_path"]).write_text("\n".join(_markdown_lines(card)).strip() + "\n", encoding="utf-8")
+
+    return {
+        "enabled": True,
+        "ok": True,
+        "count": 1,
+        "path": paths["markdown_path"],
+        "json_path": paths["json_path"],
+        "markdown_path": paths["markdown_path"],
+        "route": paths["route"],
+        "identifier": paths["identifier"],
+        "card": card,
+    }
+
+
+def persist_output_envelope(
+    *,
+    envelope: Dict[str, Any],
+    storage_config: Optional[Dict[str, Any]],
+    platform: str,
+    fallback_identifier: str,
+) -> Dict[str, Any]:
+    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 = _safe_text(envelope.get("normalized", {}).get("platform_work_id")) or fallback_identifier
+    status = "error" if envelope.get("error_reason") else "success"
+
+    target_root = Path(paths["errors_root"] if status == "error" else paths["results_root"]) / date_key
+    target_root.mkdir(parents=True, exist_ok=True)
+    file_name = render_output_filename(
+        pattern=resolve_json_filename_pattern(storage_config),
+        context={
+            "platform": platform,
+            "identifier": identifier,
+            "timestamp": timestamp,
+            "date": date_key,
+            "ext": ".json",
+        },
+        default_filename=f"{timestamp}-{platform}-{identifier}.json",
+        default_ext=".json",
+    )
+    file_path = target_root / file_name
+    file_path.write_text(json.dumps(envelope, ensure_ascii=False, indent=2), encoding="utf-8")
+    return {"enabled": True, "ok": True, "status": status, "path": str(file_path)}

package/skills/creator-analysis/SKILL.md

@@ -1,95 +0,0 @@
----
-name: creator-analysis
-description: Use this skill for creator, account profile, and content-collection retrieval, benchmarking, breakdown, and analysis. Trigger when the user asks to analyze creator / analyze account / profile analysis / creator benchmark / creator breakdown, or 创作者分析 / 账号分析 / 主页分析 / 博主分析 / 博主对标 / 账号拆解 / 作者卡 / 主页作品汇总, and the target is a creator, account profile, channel, or content collection rather than one content item.
----
-
-# Creator Analysis
-
-## When To Use
-
-- Use this skill when the target is a creator, account, profile page, channel, or content collection rather than a single content item.
-- Use this skill when the user wants a creator card, author sample cards, sampled explanations, or aggregated creator-level conclusions.
-- Use this skill when multiple videos under one profile should go through batch ASR first.
-- Use this skill when the user provides a profile URL, creator handle, account identifier, channel entry, or another creator-level entry point.
-
-## What It Can Do
-
-- Fetch and normalize creator-side fact fields.
-- Fetch and normalize the full content collection under a profile.
-- Produce author sample cards for the retrieved items.
-- Run batch ASR for video items when needed.
-- Complete bucketing, sampling, sampled explanations, and creator-level analysis.
-- Return creator cards, author sample cards, sampled enhanced cards, and aggregated conclusions.
-
-## Core Workflow Rules
-
-- Keep the task scoped to a creator, account profile, or content collection.
-- Prefer the platform guide first. Only go back to API discovery references when the guide is insufficient.
-- Keep fact cards for all retrieved works, but do not run per-work deep LLM analysis.
-- Prefer batch ASR for video items, with up to 100 links per batch.
-- Let sampled-work explanation fields come from one batch LLM step only.
-- Treat `author_analysis_v2` as the formal creator-level analysis object.
-- If `analysis_eligibility=incomplete`, keep the fact card but exclude the item from sampling, sampled explanations, and creator-level analysis.
-
-## Shared Layer Boundaries
-
-- Shared layer owns orchestration order, status semantics, output contracts, sampled-work explanation constraints, and final card-writing rules.
-- Platform layer owns route strategy, collector behavior, platform-field compatibility, adapter normalization, and platform-specific cleaning rules.
-- Keep sampled explanations as a batch-stage artifact. Do not reintroduce per-work deep analysis in the creator path.
-- Treat `author`, `author_sample_work`, and sampled enhanced cards as separate output roles with explicit routing semantics.
-
-## Platform Navigation
-
-- Start with the platform guide:
-  - Douyin: `references/platform-guides/douyin.md`
-  - Xiaohongshu: `references/platform-guides/xiaohongshu.md`
-  - Other platforms: `references/platform-guides/generic.md`
-- Route strategy, collector behavior, and raw payload retrieval:
-  - First stop: `scripts/author_home/collectors/homepage_collectors.py`
-- Platform-field compatibility and normalization:
-  - First stop: `scripts/author_home/adapters/platform_adapters.py`
-- Orchestration order, stage status, degradation, persistence, and final result assembly:
-  - First stop: `scripts/author_home/orchestrator/run_author_analysis.py`
-- Work-analysis artifacts, cache behavior, and structural labels:
-  - First stop: `scripts/author_home/orchestrator/work_analysis_artifacts.py`
-- Sampled explanations and creator-level analysis logic:
-  - First stop: `scripts/author_home/analyzers/`
-- Card writing and markdown rendering:
-  - First stop: `scripts/writers/write_author_homepage_samples.py`
-  - Supporting renderer: `scripts/writers/write_benchmark_card.py`
-
-## Do Not
-
-- Do not paste sampled explanations directly into every work-card body.
-- Do not expose platform process fields directly in the final card body.
-- Do not introduce per-work LLM explanations inside the creator path.
-- Do not bypass the platform guide and jump straight into local helpers without understanding the route and contract expectations first.
-
-## Workflow
-
-1. Identify the platform and confirm that the target is a creator, account profile, channel, or content collection.
-2. Read `references/contracts/creator-card-fields.md` to confirm required creator-card fields.
-3. Read `references/contracts/work-card-fields.md` to confirm required work-card fields for the collected items.
-4. Read the platform guide first and then the first-stop implementation file for the problem type you are solving.
-5. If video items are involved, read `references/service-guides/asr-u2-u3-fallback.md` and then `references/asr-orchestration.md` to run batch ASR and fallback.
-6. Read `references/api-capability-index.md`, `references/api-tags/`, and `references/api-contracts/` only when the platform guide does not provide enough route or field detail.
-7. Read `references/workflow.md` to complete bucketing, sampling, sampled explanations, and `author_analysis_v2`.
-8. Return the creator card, author sample cards, sampled enhanced cards, and aggregated conclusions.
-
-## References
-
-- API capability index: `references/api-capability-index.md`
-- Tag-level route summaries: `references/api-tags/`
-- Tag-level full contracts: `references/api-contracts/`
-- U2/U3 ASR fallback: `references/service-guides/asr-u2-u3-fallback.md`
-- Creator-card fields: `references/contracts/creator-card-fields.md`
-- Work-card fields: `references/contracts/work-card-fields.md`
-- ASR orchestration: `references/asr-orchestration.md`
-- Creator workflow: `references/workflow.md`
-- Author-analysis prompt contract: `references/prompt-contracts/author-analysis-v2.md`
-- Sampled-explanations prompt contract: `references/prompt-contracts/sampled-work-batch-explanations.md`
-- Author-analysis schema: `references/schemas/author-analysis-v2.schema.json`
-- Sampled-explanations schema: `references/schemas/sampled-work-batch-explanations.schema.json`
-- Generic platform guide: `references/platform-guides/generic.md`
-- Douyin guide: `references/platform-guides/douyin.md`
-- Xiaohongshu guide: `references/platform-guides/xiaohongshu.md`

package/skills/creator-analysis/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Creator Analysis"
-  short_description: "Creator, profile, and collection benchmark analysis"
-  default_prompt: "Use $creator-analysis to analyze a creator, account profile, or content collection and return the creator card, work cards, creator benchmark breakdown, and aggregated conclusions."

package/skills/creator-analysis/env.example

@@ -1,36 +0,0 @@
-# [ZH] 本文件是 creator-analysis 的环境变量示例。
-# [EN] This file is the env example for creator-analysis.
-#
-# [ZH] 正常情况下，请先把仓库根 env.example 复制到 skills/.env。
-# [EN] In normal use, copy the repo-root env.example to skills/.env first.
-#
-# [ZH] 只有当 creator-analysis 需要局部覆盖时，才把下面字段复制到本目录的 .env.local。
-# [EN] Only copy selected keys into this folder's .env.local when creator-analysis needs local overrides.
-
-# [ZH] 输出根目录。默认值：继承 skills/.env；如需局部覆盖，必须是绝对路径。
-# [EN] Output root. Default: inherited from skills/.env; must be absolute when overridden locally.
-# TIKOMNI_OUTPUT_ROOT="/absolute/path/to/tikomni-output"
-
-# [ZH] 卡片根目录。默认值：继承 skills/.env；如需局部覆盖，必须是绝对路径。
-# [EN] Card root. Default: inherited from skills/.env; must be absolute when overridden locally.
-# TIKOMNI_CARD_ROOT="/absolute/path/to/tikomni-cards"
-
-# [ZH] 路由语言预设。默认值：zh
-# [EN] Route locale preset. Default: zh
-TIKOMNI_PATH_LOCALE="zh"
-
-# [ZH] 作者级 LLM 分析超时，单位秒。默认值：45
-# [EN] Timeout for creator-level LLM analysis in seconds. Default: 45
-TIKOMNI_AUTHOR_ANALYSIS_TIMEOUT_SEC="45"
-
-# [ZH] sampled works 少于该阈值时跳过作者级 LLM 分析。默认值：5
-# [EN] Skip creator-level LLM analysis when sampled works are below this threshold. Default: 5
-TIKOMNI_AUTHOR_ANALYSIS_SMALL_SAMPLE_SKIP="5"
-
-# [ZH] sampled works 批量解释超时，单位秒。默认值：45
-# [EN] Timeout for sampled-work batch explanations in seconds. Default: 45
-TIKOMNI_SAMPLED_EXPLANATION_TIMEOUT_SEC="45"
-
-# [ZH] 显式配置文件路径。默认值：空；留空时自动使用本模块 defaults.yaml
-# [EN] Explicit config file path. Default: empty; when empty the module uses its own defaults.yaml
-# TIKOMNI_CONFIG_FILE=""

package/skills/creator-analysis/references/api-capability-index.md

@@ -1,92 +0,0 @@
-# TikOmni API Capability Index
-
-## Purpose
-
-- This auto-generated lightweight entry point helps identify the right tag, capability area, and auth pattern first.
-- Source mode: `remote`
-- Source: `https://app.tikomni.com/openapi/tikomni-openapi.full.with-u2.public.latest.json`
-- Fetched at: `2026-03-08T06:54:04+00:00`
-- Start route selection here. Read `api-tags/` and `api-contracts/` only when you need field definitions, defaults, examples, or full response structures.
-- If the task involves ASR timeout, non-public media URLs, or U3 media relay, also read `service-guides/asr-u2-u3-fallback.md`.
-
-## Global Auth
-
-- Default auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
-- If a route overrides or disables the default auth requirement, trust the corresponding `api-tags/` and `api-contracts/` entries.
-
-## Read Order
-
-1. Choose a tag by platform and object type.
-2. Open `api-tags/<tag>.md` for route summaries, auth requirements, and key fields.
-3. Open `api-contracts/<tag>.md` only when you need exact field definitions, defaults, examples, or full success-response structures.
-4. If the task involves transcription, the 90-second soft observation window, or the 120-second hard fallback, read the U2/U3 guide.
-
-## Stats
-
-- Tag groups: `53`
-- Routes: `991`
-- Generated targets: `3` skill reference sets
-
-## Special Flows
-
-- ASR and U3 fallback: [`service-guides/asr-u2-u3-fallback.md`](./service-guides/asr-u2-u3-fallback.md)
-- ASR tag: [`api-tags/asr-api.md`](./api-tags/asr-api.md)
-- U3 media relay tag: [`api-tags/media-ingest-api.md`](./api-tags/media-ingest-api.md)
-
-## Tag Overview
-
-| Tag | File | Contract | Ops | Auth | Common Capabilities | Common Inputs |
-| --- | --- | --- | ---: | --- | --- | --- |
-| `ASR-API` | [`api-tags/asr-api.md`](./api-tags/asr-api.md) | [`api-contracts/asr-api.md`](./api-contracts/asr-api.md) | 2 | Header `Authorization` Bearer | ASR / transcription / audio / media / general | `input`, `task_id` |
-| `Bilibili-App-API` | [`api-tags/bilibili-app-api.md`](./api-tags/bilibili-app-api.md) | [`api-contracts/bilibili-app-api.md`](./api-contracts/bilibili-app-api.md) | 11 | Header `Authorization` Bearer | general / profiles / accounts / content details / search | `av_id`, `bv_id`, `page`, `idx`, `next_offset`, `ps`, `keyword`, `page_size`, `order`, `user_id` |
-| `Bilibili-Web-API` | [`api-tags/bilibili-web-api.md`](./api-tags/bilibili-web-api.md) | [`api-contracts/bilibili-web-api.md`](./api-contracts/bilibili-web-api.md) | 30 | Header `Authorization` Bearer | content details / profiles / accounts / livestream / details | `bv_id`, `uid`, `pn`, `cid`, `dynamic_id`, `order`, `room_id`, `a_id`, `c_id`, `url` |
-| `Demo-API` | [`api-tags/demo-api.md`](./api-tags/demo-api.md) | [`api-contracts/demo-api.md`](./api-contracts/demo-api.md) | 9 | Header `Authorization` Bearer | content details / profiles / accounts / general / search | None |
-| `Douyin-App-V3-API` | [`api-tags/douyin-app-v3-api.md`](./api-tags/douyin-app-v3-api.md) | [`api-contracts/douyin-app-v3-api.md`](./api-contracts/douyin-app-v3-api.md) | 47 | Header `Authorization` Bearer | content details / search / profiles / accounts / details | `count`, `cursor`, `keyword`, `aweme_id`, `sec_user_id`, `offset`, `sort_type`, `publish_time`, `filter_duration`, `aweme_ids` |
-| `Douyin-Billboard-API` | [`api-tags/douyin-billboard-api.md`](./api-tags/douyin-billboard-api.md) | [`api-contracts/douyin-billboard-api.md`](./api-contracts/douyin-billboard-api.md) | 31 | Header `Authorization` Bearer | trends / rankings / search / topics / details | `page_size`, `date_window`, `page`, `keyword`, `tags`, `sec_uid`, `option`, `page_num`, `end_date`, `start_date` |
-| `Douyin-Creator-API` | [`api-tags/douyin-creator-api.md`](./api-tags/douyin-creator-api.md) | [`api-contracts/douyin-creator-api.md`](./api-contracts/douyin-creator-api.md) | 16 | Header `Authorization` Bearer | creators / trends / rankings / topics / details | `billboard_tag`, `order_key`, `time_filter`, `limit`, `offset`, `category_id`, `order`, `activity_id`, `start_time`, `end_time` |
-| `Douyin-Creator-V2-API` | [`api-tags/douyin-creator-v2-api.md`](./api-tags/douyin-creator-v2-api.md) | [`api-contracts/douyin-creator-v2-api.md`](./api-contracts/douyin-creator-v2-api.md) | 14 | Header `Authorization` Bearer | creators / media / download / search / trends / rankings | `cookie`, `item_id`, `start_date`, `end_date`, `genres`, `primary_verticals`, `fields`, `need_long_article`, `metric_type`, `count` |
-| `Douyin-Search-API` | [`api-tags/douyin-search-api.md`](./api-tags/douyin-search-api.md) | [`api-contracts/douyin-search-api.md`](./api-contracts/douyin-search-api.md) | 20 | Header `Authorization` Bearer | search / topics / profiles / accounts / content details | `keyword`, `cursor`, `search_id`, `sort_type`, `publish_time`, `filter_duration`, `content_type`, `backtrace`, `douyin_user_fans`, `douyin_user_type` |
-| `Douyin-Web-API` | [`api-tags/douyin-web-api.md`](./api-tags/douyin-web-api.md) | [`api-contracts/douyin-web-api.md`](./api-contracts/douyin-web-api.md) | 76 | Header `Authorization` Bearer | profiles / accounts / content details / general / livestream | `count`, `cookie`, `refresh_index`, `keyword`, `sec_user_id`, `cursor`, `room_id`, `offset`, `aweme_id`, `max_cursor` |
-| `Douyin-Xingtu-API` | [`api-tags/douyin-xingtu-api.md`](./api-tags/douyin-xingtu-api.md) | [`api-contracts/douyin-xingtu-api.md`](./api-contracts/douyin-xingtu-api.md) | 22 | Header `Authorization` Bearer | general / content details / comments / trends / rankings | `kolId`, `platformChannel`, `_range`, `page`, `onlyAssign`, `keyword`, `uri`, `durationTS`, `format`, `sec_user_id` |
-| `Douyin-Xingtu-V2-API` | [`api-tags/douyin-xingtu-v2-api.md`](./api-tags/douyin-xingtu-v2-api.md) | [`api-contracts/douyin-xingtu-v2-api.md`](./api-contracts/douyin-xingtu-v2-api.md) | 21 | Header `Authorization` Bearer | creators / general / trends / rankings / comments | `o_author_id`, `platform_source`, `limit`, `platform_channel`, `author_id`, `only_assign`, `flow_type`, `page`, `qualifier`, `period` |
-| `Health-Check` | [`api-tags/health-check.md`](./api-tags/health-check.md) | [`api-contracts/health-check.md`](./api-contracts/health-check.md) | 1 | Header `Authorization` Bearer | general | None |
-| `Hybrid-Parsing` | [`api-tags/hybrid-parsing.md`](./api-tags/hybrid-parsing.md) | [`api-contracts/hybrid-parsing.md`](./api-contracts/hybrid-parsing.md) | 1 | Header `Authorization` Bearer | content details | `url`, `minimal`, `base64_url` |
-| `Instagram-V1-API` | [`api-tags/instagram-v1-api.md`](./api-tags/instagram-v1-api.md) | [`api-contracts/instagram-v1-api.md`](./api-contracts/instagram-v1-api.md) | 29 | Header `Authorization` Bearer | profiles / accounts / content details / general / comments | `user_id`, `max_id`, `count`, `end_cursor`, `media_id`, `username`, `page`, `min_id`, `location_id`, `post_url` |
-| `Instagram-V2-API` | [`api-tags/instagram-v2-api.md`](./api-tags/instagram-v2-api.md) | [`api-contracts/instagram-v2-api.md`](./api-contracts/instagram-v2-api.md) | 27 | Header `Authorization` Bearer | profiles / accounts / content details / search / comments | `pagination_token`, `user_id`, `username`, `keyword`, `code_or_url`, `comment_id`, `feed_type`, `highlight_id`, `location_id`, `audio_canonical_id` |
-| `Instagram-V3-API` | [`api-tags/instagram-v3-api.md`](./api-tags/instagram-v3-api.md) | [`api-contracts/instagram-v3-api.md`](./api-contracts/instagram-v3-api.md) | 26 | Header `Authorization` Bearer | profiles / accounts / content details / comments / search | `user_id`, `username`, `url`, `first`, `after`, `query`, `media_id`, `code`, `max_id`, `comment_id` |
-| `Kuaishou-App-API` | [`api-tags/kuaishou-app-api.md`](./api-tags/kuaishou-app-api.md) | [`api-contracts/kuaishou-app-api.md`](./api-contracts/kuaishou-app-api.md) | 20 | Header `Authorization` Bearer | content details / trends / rankings / profiles / accounts / search | `pcursor`, `user_id`, `subTabId`, `subTabName`, `keyword`, `magic_face_id`, `photo_id`, `page`, `boardType`, `boardId` |
-| `Kuaishou-Web-API` | [`api-tags/kuaishou-web-api.md`](./api-tags/kuaishou-web-api.md) | [`api-contracts/kuaishou-web-api.md`](./api-contracts/kuaishou-web-api.md) | 13 | Header `Authorization` Bearer | content details / profiles / accounts / trends / rankings / comments | `pcursor`, `photo_id`, `user_id`, `share_link`, `board_type`, `share_text`, `url`, `root_comment_id` |
-| `Lemon8-App-API` | [`api-tags/lemon8-app-api.md`](./api-tags/lemon8-app-api.md) | [`api-contracts/lemon8-app-api.md`](./api-contracts/lemon8-app-api.md) | 16 | Header `Authorization` Bearer | general / profiles / accounts / content details / search | `user_id`, `item_id`, `cursor`, `share_text`, `group_id`, `media_id`, `offset`, `query`, `max_cursor`, `filter_type` |
-| `LinkedIn-Web-API` | [`api-tags/linkedin-web-api.md`](./api-tags/linkedin-web-api.md) | [`api-contracts/linkedin-web-api.md`](./api-contracts/linkedin-web-api.md) | 25 | Header `Authorization` Bearer | profiles / accounts / general / content details / search | `page`, `urn`, `company_id`, `pagination_token`, `sort_by`, `company`, `username`, `date_posted`, `experience_level`, `remote` |
-| `Media-Ingest-API` | [`api-tags/media-ingest-api.md`](./api-tags/media-ingest-api.md) | [`api-contracts/media-ingest-api.md`](./api-contracts/media-ingest-api.md) | 2 | Header `Authorization` Bearer | media upload / public URL | `provider`, `file_name`, `content_type`, `size_bytes`, `upload_id` |
-| `PiPiXia-App-API` | [`api-tags/pipixia-app-api.md`](./api-tags/pipixia-app-api.md) | [`api-contracts/pipixia-app-api.md`](./api-contracts/pipixia-app-api.md) | 17 | Header `Authorization` Bearer | content details / profiles / accounts / search / details | `cursor`, `cell_id`, `user_id`, `cell_type`, `hashtag_id`, `feed_count`, `offset`, `hashtag_request_type`, `hashtag_sort_type`, `page` |
-| `Reddit-APP-API` | [`api-tags/reddit-app-api.md`](./api-tags/reddit-app-api.md) | [`api-contracts/reddit-app-api.md`](./api-contracts/reddit-app-api.md) | 24 | Header `Authorization` Bearer | general / profiles / accounts / content details / comments | `need_format`, `after`, `sort`, `username`, `subreddit_name`, `subreddit_id`, `post_id`, `filter_posts`, `include_comment_id`, `comment_id` |
-| `Sora2-API` | [`api-tags/sora2-api.md`](./api-tags/sora2-api.md) | [`api-contracts/sora2-api.md`](./api-contracts/sora2-api.md) | 17 | Header `Authorization` Bearer | content details / profiles / accounts / general / comments | `cursor`, `user_id`, `post_id`, `post_url`, `task_id`, `prompt`, `orientation`, `media_id`, `comment_id`, `eager_views` |
-| `Temp-Mail-API` | [`api-tags/temp-mail-api.md`](./api-tags/temp-mail-api.md) | [`api-contracts/temp-mail-api.md`](./api-contracts/temp-mail-api.md) | 3 | Header `Authorization` Bearer | general | `token`, `message_id` |
-| `Threads-Web-API` | [`api-tags/threads-web-api.md`](./api-tags/threads-web-api.md) | [`api-contracts/threads-web-api.md`](./api-contracts/threads-web-api.md) | 11 | Header `Authorization` Bearer | profiles / accounts / content details / search / details | `end_cursor`, `user_id`, `post_id`, `query`, `url`, `username` |
-| `TikHub-Downloader-API` | [`api-tags/tikhub-downloader-api.md`](./api-tags/tikhub-downloader-api.md) | [`api-contracts/tikhub-downloader-api.md`](./api-contracts/tikhub-downloader-api.md) | 2 | Header `Authorization` Bearer | media / download | None |
-| `TikHub-User-API` | [`api-tags/tikhub-user-api.md`](./api-tags/tikhub-user-api.md) | [`api-contracts/tikhub-user-api.md`](./api-contracts/tikhub-user-api.md) | 6 | Header `Authorization` Bearer | profiles / accounts | `endpoint`, `request_per_day` |
-| `TikTok-Ads-API` | [`api-tags/tiktok-ads-api.md`](./api-tags/tiktok-ads-api.md) | [`api-contracts/tiktok-ads-api.md`](./api-contracts/tiktok-ads-api.md) | 31 | Header `Authorization` Bearer | ads / search / details / creators | `limit`, `page`, `country_code`, `period`, `keyword`, `period_type`, `industry`, `order_by`, `rank_type`, `material_id` |
-| `TikTok-Analytics-API` | [`api-tags/tiktok-analytics-api.md`](./api-tags/tiktok-analytics-api.md) | [`api-contracts/tiktok-analytics-api.md`](./api-contracts/tiktok-analytics-api.md) | 4 | Header `Authorization` Bearer | analytics / comments / creators / content details | `item_id`, `content_category`, `user_id` |
-| `TikTok-App-V3-API` | [`api-tags/tiktok-app-v3-api.md`](./api-tags/tiktok-app-v3-api.md) | [`api-contracts/tiktok-app-v3-api.md`](./api-contracts/tiktok-app-v3-api.md) | 75 | Header `Authorization` Bearer | content details / commerce / profiles / accounts / search | `count`, `offset`, `keyword`, `sort_type`, `cursor`, `region`, `sec_user_id`, `user_id`, `room_id`, `seller_id` |
-| `TikTok-Creator-API` | [`api-tags/tiktok-creator-api.md`](./api-tags/tiktok-creator-api.md) | [`api-contracts/tiktok-creator-api.md`](./api-contracts/tiktok-creator-api.md) | 14 | Header `Authorization` Bearer | creators / content details / analytics / commerce | `cookie`, `proxy`, `start_date`, `item_id`, `page`, `product_id`, `end_date`, `count`, `offset`, `item_ids` |
-| `TikTok-Interaction-API` | [`api-tags/tiktok-interaction-api.md`](./api-tags/tiktok-interaction-api.md) | [`api-contracts/tiktok-interaction-api.md`](./api-contracts/tiktok-interaction-api.md) | 7 | Header `Authorization` Bearer | general / comments / content details / comment replies | `cookie`, `device_id`, `iid`, `proxy`, `aweme_id`, `text`, `api_key`, `invite_code`, `user_id`, `sec_user_id` |
-| `TikTok-Shop-Web-API` | [`api-tags/tiktok-shop-web-api.md`](./api-tags/tiktok-shop-web-api.md) | [`api-contracts/tiktok-shop-web-api.md`](./api-contracts/tiktok-shop-web-api.md) | 15 | Header `Authorization` Bearer | commerce / search / details / trends / rankings | `region`, `product_id`, `offset`, `seller_id`, `search_word`, `page_token`, `lang`, `count`, `sort_type`, `filter_id` |
-| `TikTok-Web-API` | [`api-tags/tiktok-web-api.md`](./api-tags/tiktok-web-api.md) | [`api-contracts/tiktok-web-api.md`](./api-contracts/tiktok-web-api.md) | 58 | Header `Authorization` Bearer | general / profiles / accounts / livestream / content details | `count`, `cursor`, `cookie`, `secUid`, `url`, `keyword`, `search_id`, `user_agent`, `offset`, `coverFormat` |
-| `Toutiao-App-API` | [`api-tags/toutiao-app-api.md`](./api-tags/toutiao-app-api.md) | [`api-contracts/toutiao-app-api.md`](./api-contracts/toutiao-app-api.md) | 5 | Header `Authorization` Bearer | content details / profiles / accounts / comments | `group_id`, `offset`, `user_profile_url`, `user_id` |
-| `Toutiao-Web-API` | [`api-tags/toutiao-web-api.md`](./api-tags/toutiao-web-api.md) | [`api-contracts/toutiao-web-api.md`](./api-contracts/toutiao-web-api.md) | 2 | Header `Authorization` Bearer | content details | `aweme_id` |
-| `Twitter-Web-API` | [`api-tags/twitter-web-api.md`](./api-tags/twitter-web-api.md) | [`api-contracts/twitter-web-api.md`](./api-contracts/twitter-web-api.md) | 13 | Header `Authorization` Bearer | profiles / accounts / content details / comments / search | `cursor`, `screen_name`, `tweet_id`, `rest_id`, `keyword`, `search_type`, `country`, `userId`, `count` |
-| `WeChat-Channels-API` | [`api-tags/wechat-channels-api.md`](./api-tags/wechat-channels-api.md) | [`api-contracts/wechat-channels-api.md`](./api-contracts/wechat-channels-api.md) | 9 | Header `Authorization` Bearer | profiles / accounts / search / comments / trends / rankings | `keywords`, `id`, `username`, `lastBuffer`, `comment_id`, `session_buffer`, `last_buffer`, `page`, `exportId` |
-| `WeChat-Media-Platform-Web-API` | [`api-tags/wechat-media-platform-web-api.md`](./api-tags/wechat-media-platform-web-api.md) | [`api-contracts/wechat-media-platform-web-api.md`](./api-contracts/wechat-media-platform-web-api.md) | 10 | Header `Authorization` Bearer | content details / comments / details / comment replies | `url`, `comment_id`, `offset`, `buffer`, `content_id`, `ghid`, `sogou_url` |
-| `Weibo-App-API` | [`api-tags/weibo-app-api.md`](./api-tags/weibo-app-api.md) | [`api-contracts/weibo-app-api.md`](./api-contracts/weibo-app-api.md) | 20 | Header `Authorization` Bearer | profiles / accounts / content details / search / details | `uid`, `page`, `since_id`, `status_id`, `query`, `count`, `max_id`, `category`, `search_type`, `sort_type` |
-| `Weibo-Web-API` | [`api-tags/weibo-web-api.md`](./api-tags/weibo-web-api.md) | [`api-contracts/weibo-web-api.md`](./api-contracts/weibo-web-api.md) | 11 | Header `Authorization` Bearer | profiles / accounts / search / content details / comments | `page`, `max_id`, `post_id`, `uid`, `channel_name`, `cid`, `mid`, `max_id_type`, `keyword`, `search_type` |
-| `Weibo-Web-V2-API` | [`api-tags/weibo-web-v2-api.md`](./api-tags/weibo-web-v2-api.md) | [`api-contracts/weibo-web-v2-api.md`](./api-contracts/weibo-web-v2-api.md) | 33 | Header `Authorization` Bearer | search / profiles / accounts / content details / general | `page`, `uid`, `query`, `id`, `max_id`, `count`, `since_id`, `q`, `keyword`, `cursor` |
-| `Xiaohongshu-App-API` | [`api-tags/xiaohongshu-app-api.md`](./api-tags/xiaohongshu-app-api.md) | [`api-contracts/xiaohongshu-app-api.md`](./api-contracts/xiaohongshu-app-api.md) | 12 | Header `Authorization` Bearer | content details / profiles / accounts / comments / commerce | `note_id`, `session_id`, `share_link`, `start`, `share_text`, `sort`, `user_id`, `keyword`, `page`, `search_id` |
-| `Xiaohongshu-App-V2-API` | [`api-tags/xiaohongshu-app-v2-api.md`](./api-tags/xiaohongshu-app-v2-api.md) | [`api-contracts/xiaohongshu-app-v2-api.md`](./api-contracts/xiaohongshu-app-v2-api.md) | 21 | Header `Authorization` Bearer | content details / commerce / search / details | `source`, `share_text`, `cursor`, `note_id`, `page`, `keyword`, `search_id`, `sku_id`, `user_id`, `tab` |
-| `Xiaohongshu-Web-API` | [`api-tags/xiaohongshu-web-api.md`](./api-tags/xiaohongshu-web-api.md) | [`api-contracts/xiaohongshu-web-api.md`](./api-contracts/xiaohongshu-web-api.md) | 17 | Header `Authorization` Bearer | content details / profiles / accounts / search / comments | `note_id`, `share_text`, `cookie`, `proxy`, `lastCursor`, `user_id`, `keyword`, `page`, `xsec_token`, `sort` |
-| `Xiaohongshu-Web-V2-API` | [`api-tags/xiaohongshu-web-v2-api.md`](./api-tags/xiaohongshu-web-v2-api.md) | [`api-contracts/xiaohongshu-web-v2-api.md`](./api-contracts/xiaohongshu-web-v2-api.md) | 18 | Header `Authorization` Bearer | content details / profiles / accounts / general / comments | `note_id`, `user_id`, `cursor`, `page`, `keywords`, `short_url`, `sort_type`, `note_type`, `comment_id` |
-| `Xigua-App-V2-API` | [`api-tags/xigua-app-v2-api.md`](./api-tags/xigua-app-v2-api.md) | [`api-contracts/xigua-app-v2-api.md`](./api-contracts/xigua-app-v2-api.md) | 7 | Header `Authorization` Bearer | content details / profiles / accounts / comments / search | `item_id`, `user_id`, `offset`, `max_behot_time`, `count`, `keyword`, `order_type`, `min_duration`, `max_duration` |
-| `YouTube-Web-API` | [`api-tags/youtube-web-api.md`](./api-tags/youtube-web-api.md) | [`api-contracts/youtube-web-api.md`](./api-contracts/youtube-web-api.md) | 21 | Header `Authorization` Bearer | content details / profiles / accounts / search / comments | `continuation_token`, `language_code`, `country_code`, `channel_id`, `video_id`, `need_format`, `search_query`, `sort_by`, `lang`, `time_zone` |
-| `YouTube-Web-V2-API` | [`api-tags/youtube-web-v2-api.md`](./api-tags/youtube-web-v2-api.md) | [`api-contracts/youtube-web-v2-api.md`](./api-contracts/youtube-web-v2-api.md) | 16 | Header `Authorization` Bearer | content details / profiles / accounts / search / livestream | `continuation_token`, `need_format`, `language_code`, `country_code`, `video_id`, `channel_id`, `video_url`, `sort_by`, `channel_url`, `search_query` |
-| `Zhihu-Web-API` | [`api-tags/zhihu-web-api.md`](./api-tags/zhihu-web-api.md) | [`api-contracts/zhihu-web-api.md`](./api-contracts/zhihu-web-api.md) | 32 | Header `Authorization` Bearer | search / profiles / accounts / content details / general | `offset`, `limit`, `keyword`, `user_url_token`, `search_hash_id`, `article_id`, `order_by`, `message_content`, `message_id`, `show_all_topics` |
-| `iOS-Shortcut` | [`api-tags/ios-shortcut.md`](./api-tags/ios-shortcut.md) | [`api-contracts/ios-shortcut.md`](./api-contracts/ios-shortcut.md) | 1 | Header `Authorization` Bearer | general | None |