@tikomni/skills 1.0.5 → 1.0.7

package/skills/social-media-crawl/references/api-catalog/overrides.json

@@ -0,0 +1,10 @@
+{
+  "capability_overrides": {},
+  "notes": [
+    "endpoint_id is generated automatically and must not be manually overridden.",
+    "Overrides may adjust platform, capability, recommended endpoint, alternatives, and aliases only."
+  ],
+  "platform_overrides": {},
+  "recommendation_overrides": {},
+  "schema_version": "v1"
+}

package/skills/social-media-crawl/references/api-catalog/platforms.json

@@ -0,0 +1,463 @@
+[
+  {
+    "aliases": [
+      "b23.tv",
+      "bilibili",
+      "b站",
+      "哔哩哔哩"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "hot_search",
+      "livestream",
+      "media_upload",
+      "search",
+      "transcription",
+      "user_posts",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 41,
+    "slug": "bilibili"
+  },
+  {
+    "aliases": [
+      "demo"
+    ],
+    "capabilities": [
+      "general"
+    ],
+    "operation_count": 1,
+    "slug": "demo"
+  },
+  {
+    "aliases": [
+      "douyin",
+      "dy",
+      "iesdouyin.com",
+      "v.douyin.com",
+      "抖音"
+    ],
+    "capabilities": [
+      "article_detail",
+      "comments",
+      "general",
+      "hot_search",
+      "livestream",
+      "media_upload",
+      "music",
+      "note_detail",
+      "product_detail",
+      "ranking",
+      "search",
+      "user_posts",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 292,
+    "slug": "douyin"
+  },
+  {
+    "aliases": [
+      "douyin_search"
+    ],
+    "capabilities": [
+      "search"
+    ],
+    "operation_count": 1,
+    "slug": "douyin_search"
+  },
+  {
+    "aliases": [
+      "health"
+    ],
+    "capabilities": [
+      "general"
+    ],
+    "operation_count": 1,
+    "slug": "health"
+  },
+  {
+    "aliases": [
+      "hybrid"
+    ],
+    "capabilities": [
+      "video_detail"
+    ],
+    "operation_count": 1,
+    "slug": "hybrid"
+  },
+  {
+    "aliases": [
+      "ig",
+      "ins",
+      "instagram"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "music",
+      "ranking",
+      "search",
+      "user_posts",
+      "user_profile"
+    ],
+    "operation_count": 89,
+    "slug": "instagram"
+  },
+  {
+    "aliases": [
+      "ios_shortcut"
+    ],
+    "capabilities": [
+      "general"
+    ],
+    "operation_count": 1,
+    "slug": "ios_shortcut"
+  },
+  {
+    "aliases": [
+      "ks",
+      "kuaishou",
+      "快手"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "hot_search",
+      "livestream",
+      "note_detail",
+      "product_detail",
+      "search",
+      "transcription",
+      "user_posts",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 34,
+    "slug": "kuaishou"
+  },
+  {
+    "aliases": [
+      "lemon8"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "hot_search",
+      "search",
+      "user_profile"
+    ],
+    "operation_count": 16,
+    "slug": "lemon8"
+  },
+  {
+    "aliases": [
+      "linkedin",
+      "领英"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "search",
+      "user_posts",
+      "user_profile"
+    ],
+    "operation_count": 25,
+    "slug": "linkedin"
+  },
+  {
+    "aliases": [
+      "pipixia",
+      "皮皮虾"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "hot_search",
+      "search",
+      "user_posts",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 17,
+    "slug": "pipixia"
+  },
+  {
+    "aliases": [
+      "reddit"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "livestream",
+      "note_detail",
+      "ranking",
+      "search",
+      "user_profile"
+    ],
+    "operation_count": 24,
+    "slug": "reddit"
+  },
+  {
+    "aliases": [
+      "sora2"
+    ],
+    "capabilities": [
+      "comments",
+      "media_upload",
+      "note_detail",
+      "search",
+      "user_profile"
+    ],
+    "operation_count": 17,
+    "slug": "sora2"
+  },
+  {
+    "aliases": [
+      "temp_mail"
+    ],
+    "capabilities": [
+      "general",
+      "user_profile"
+    ],
+    "operation_count": 3,
+    "slug": "temp_mail"
+  },
+  {
+    "aliases": [
+      "threads"
+    ],
+    "capabilities": [
+      "comments",
+      "search",
+      "user_posts",
+      "user_profile"
+    ],
+    "operation_count": 11,
+    "slug": "threads"
+  },
+  {
+    "aliases": [
+      "tik tok",
+      "tiktok"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "livestream",
+      "media_upload",
+      "music",
+      "note_detail",
+      "product_detail",
+      "ranking",
+      "search",
+      "user_posts",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 208,
+    "slug": "tiktok"
+  },
+  {
+    "aliases": [
+      "toutiao",
+      "今日头条",
+      "头条"
+    ],
+    "capabilities": [
+      "article_detail",
+      "comments",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 7,
+    "slug": "toutiao"
+  },
+  {
+    "aliases": [
+      "twitter",
+      "x",
+      "x.com",
+      "推特"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "ranking",
+      "search",
+      "user_posts",
+      "user_profile"
+    ],
+    "operation_count": 13,
+    "slug": "twitter"
+  },
+  {
+    "aliases": [
+      "asr",
+      "transcription",
+      "u2",
+      "语音转写",
+      "转文案"
+    ],
+    "capabilities": [
+      "transcription"
+    ],
+    "operation_count": 2,
+    "slug": "u2"
+  },
+  {
+    "aliases": [
+      "media upload",
+      "u3",
+      "upload",
+      "中转",
+      "媒体上传"
+    ],
+    "capabilities": [
+      "media_upload"
+    ],
+    "operation_count": 2,
+    "slug": "u3"
+  },
+  {
+    "aliases": [
+      "wechat"
+    ],
+    "capabilities": [
+      "article_url"
+    ],
+    "operation_count": 1,
+    "slug": "wechat"
+  },
+  {
+    "aliases": [
+      "wechat channels",
+      "wechat_channels",
+      "微信视频号",
+      "视频号"
+    ],
+    "capabilities": [
+      "comments",
+      "hot_search",
+      "livestream",
+      "search",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 10,
+    "slug": "wechat_channels"
+  },
+  {
+    "aliases": [
+      "mp.weixin.qq.com",
+      "wechat official accounts",
+      "wechat_mp",
+      "公众号",
+      "微信公众号"
+    ],
+    "capabilities": [
+      "article_detail",
+      "article_list",
+      "article_url",
+      "comments"
+    ],
+    "operation_count": 10,
+    "slug": "wechat_mp"
+  },
+  {
+    "aliases": [
+      "weibo",
+      "微博"
+    ],
+    "capabilities": [
+      "article_list",
+      "comments",
+      "general",
+      "hot_search",
+      "music",
+      "note_detail",
+      "ranking",
+      "search",
+      "transcription",
+      "user_posts",
+      "user_profile"
+    ],
+    "operation_count": 64,
+    "slug": "weibo"
+  },
+  {
+    "aliases": [
+      "xhs",
+      "xhslink.com",
+      "xiaohongshu",
+      "xiaohongshu.com",
+      "小红书"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "note_detail",
+      "product_detail",
+      "ranking",
+      "search",
+      "user_posts",
+      "user_profile"
+    ],
+    "operation_count": 78,
+    "slug": "xiaohongshu"
+  },
+  {
+    "aliases": [
+      "xigua",
+      "西瓜视频"
+    ],
+    "capabilities": [
+      "comments",
+      "search",
+      "user_posts",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 7,
+    "slug": "xigua"
+  },
+  {
+    "aliases": [
+      "youtu.be",
+      "youtube",
+      "yt"
+    ],
+    "capabilities": [
+      "comments",
+      "general",
+      "livestream",
+      "media_upload",
+      "note_detail",
+      "ranking",
+      "search",
+      "transcription",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 44,
+    "slug": "youtube"
+  },
+  {
+    "aliases": [
+      "zhihu",
+      "知乎"
+    ],
+    "capabilities": [
+      "article_detail",
+      "comments",
+      "general",
+      "search",
+      "user_profile",
+      "video_detail"
+    ],
+    "operation_count": 34,
+    "slug": "zhihu"
+  }
+]

package/skills/social-media-crawl/references/api-routing-contract.md

@@ -0,0 +1,73 @@
+# API Routing Contract
+
+## Scope
+
+This skill calls TikOmni API only and does not require any external server configuration.
+
+Supported social-media tasks include single works, posts, creator homepages, comments, search results, rankings, livestreams, products, subtitles, transcripts, and structured fields.
+
+## Required Inputs
+
+- Auth: `TIKOMNI_API_KEY`.
+- Default API base URL: `https://api.tikomni.com`.
+- Optional override: `TIKOMNI_BASE_URL`.
+
+Do not repeat the API key inside tool parameters.
+
+## Required Route Order
+
+1. Detect platform and capability.
+2. If a fixed pipeline matches, run that fixed pipeline.
+3. Otherwise resolve a TikOmni API endpoint:
+
+```text
+python scripts/core/resolve_api_endpoint.py --platform <platform> --capability <capability> --json '<context>'
+```
+
+4. Call the API by `endpoint_id`:
+
+```text
+python scripts/core/call_tikomni_api.py --endpoint-id <endpoint_id> --params '<json>'
+```
+
+5. For common tasks, the one-shot entry is allowed:
+
+```text
+python scripts/run_task.py --platform <platform> --capability <capability> --params '<json>'
+```
+
+## Hard Rules
+
+- Do not construct TikOmni API paths manually.
+- Do not pass arbitrary `path` or `method` values to callers.
+- Do not call endpoint paths that are absent from `references/api-catalog/operations.json`.
+- Resolve `endpoint_id` first, then call the API.
+- Return recommended endpoint and alternatives to the user or agent.
+- Do not automatically call alternatives; alternatives are explicit next choices.
+- If platform or capability is ambiguous, return a clarification request instead of guessing.
+
+## Variant Priority
+
+For endpoints under the same platform and capability, default priority is:
+
+```text
+app_v3 > app_v2 > app_v1/app > web_v3 > web_v2 > web_v1/web
+```
+
+The catalog generator may apply deterministic specificity rules for common tasks such as hot search or article detail. All alternatives must remain visible.
+
+## U2/U3
+
+U2 and U3 stay inside this skill because they support video-to-text workflows:
+
+- U2 handles ASR / transcription.
+- U3 handles media upload or relay when a source media URL is not directly usable.
+
+Use them only as TikOmni API service capabilities.
+
+## Output Rules
+
+- Keep factual fields separate from derived metadata.
+- Include `request_id` when the API returns one.
+- Include `endpoint_id`, `platform`, `capability`, `variant`, and `alternatives`.
+- Include `completeness`, `missing_fields`, `error_reason`, and `extract_trace` in normalized task outputs.

package/skills/social-media-crawl/references/contracts/output-envelope.md

@@ -18,4 +18,4 @@
 - `completeness` allows `complete`, `partial`, and `incomplete`.
 - `missing_fields` is the list of missing fields.
 - `error_reason` may be an empty string or `null` on success.
-- `extract_trace` records the fixed-pipeline or MCP dispatch steps. If the flow ends in browser/CDP fallback, it must also record the earlier MCP attempts and the fallback reason.
+- `extract_trace` records fixed-pipeline steps or API-only resolver/caller steps, including `endpoint_id`, selected variant, alternatives, and request status when available.

package/skills/social-media-crawl/scripts/core/api_catalog.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Skill-local API catalog helpers."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+SKILL_ROOT = Path(__file__).resolve().parents[2]
+CATALOG_ROOT = SKILL_ROOT / "references" / "api-catalog"
+
+
+def normalize_key(value: Any) -> str:
+    text = str(value or "").strip().lower()
+    text = re.sub(r"\s+", " ", text)
+    return text
+
+
+def load_json(path: Path) -> Any:
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def load_operations() -> List[Dict[str, Any]]:
+    payload = load_json(CATALOG_ROOT / "operations.json")
+    if not isinstance(payload, list):
+        raise ValueError("api_catalog_operations_must_be_list")
+    return [item for item in payload if isinstance(item, dict)]
+
+
+def load_aliases() -> Dict[str, Any]:
+    payload = load_json(CATALOG_ROOT / "aliases.json")
+    if not isinstance(payload, dict):
+        raise ValueError("api_catalog_aliases_must_be_object")
+    return payload
+
+
+def build_alias_index(alias_map: Dict[str, Iterable[Any]]) -> Dict[str, str]:
+    index: Dict[str, str] = {}
+    for slug, aliases in alias_map.items():
+        index[normalize_key(slug)] = str(slug)
+        for alias in aliases or []:
+            normalized = normalize_key(alias)
+            if normalized:
+                index[normalized] = str(slug)
+    return index
+
+
+def resolve_alias(value: Optional[str], alias_map: Dict[str, Iterable[Any]]) -> str:
+    if not value:
+        return ""
+    normalized = normalize_key(value)
+    index = build_alias_index(alias_map)
+    return index.get(normalized, normalized.replace("-", "_").replace(" ", "_"))
+
+
+def _has_non_ascii(value: str) -> bool:
+    return any(ord(char) > 127 for char in value)
+
+
+def _alias_in_text(alias: str, normalized_text: str) -> bool:
+    if not alias:
+        return False
+    if _has_non_ascii(alias):
+        return alias in normalized_text
+    pattern = rf"(?<![a-z0-9_]){re.escape(alias)}(?![a-z0-9_])"
+    return re.search(pattern, normalized_text) is not None
+
+
+def infer_alias_from_text(text: str, alias_map: Dict[str, Iterable[Any]]) -> str:
+    normalized_text = normalize_key(text)
+    if not normalized_text:
+        return ""
+    index = build_alias_index(alias_map)
+    hits: List[tuple[int, str, str]] = []
+    for alias, slug in index.items():
+        if not alias:
+            continue
+        if _alias_in_text(alias, normalized_text):
+            hits.append((len(alias), alias, slug))
+    if not hits:
+        return ""
+    hits.sort(reverse=True)
+    return hits[0][2]
+
+
+def operation_by_endpoint_id(operations: Iterable[Dict[str, Any]], endpoint_id: str) -> Optional[Dict[str, Any]]:
+    for operation in operations:
+        if operation.get("endpoint_id") == endpoint_id:
+            return operation
+    return None
+
+
+def sorted_operations(operations: Iterable[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    return sorted(
+        operations,
+        key=lambda item: (
+            not bool(item.get("recommended")),
+            str(item.get("variant") or ""),
+            str(item.get("path") or ""),
+        ),
+    )