@tikomni/skills 0.1.0

package/skills/meta-capability/references/config-templates/defaults.yaml

@@ -0,0 +1,18 @@
+schema_version: v1
+profile: default
+
+runtime:
+  base_url: "https://api.tikomni.com"
+  auth_env_key: "TIKOMNI_API_KEY"
+  timeout_ms: 60000
+
+storage_routes:
+  default:
+    root_dir: ""
+    runs_dir: "_runs"
+    results_dir: "results"
+    errors_dir: "_errors"
+
+naming_rules:
+  card_filename_pattern: "{prefix}-{author_slug}-{title_slug}{ext}"
+  json_filename_pattern: "{timestamp}-{platform}-{identifier}{ext}"

package/skills/meta-capability/references/dispatch.md

@@ -0,0 +1,27 @@
+# Dispatch Guidance
+
+## Dispatch Principle
+
+- `meta-capability` can always complete general TikOmni tasks on its own.
+- If a more specialized skill exists in the current skill workspace and clearly matches the task, prefer handing off to that skill.
+- If the better specialized skill is missing, not installed, not checked out, or otherwise unavailable, stay in `meta-capability` and complete the task here.
+
+## When To Prefer `single-work-analysis`
+
+- The target object is a single video, single post, single note, single article, or another single content item.
+- The user wants a work card, single-item structured analysis, or transcription for one content item.
+- `single-work-analysis` is available in the current skill workspace.
+
+## When To Prefer `creator-analysis`
+
+- The target object is a creator, account, profile page, or a creator-level content collection.
+- The user wants an author card, a full content set, bucketed sampling, sampled explanations, or creator-level conclusions.
+- `creator-analysis` is available in the current skill workspace.
+
+## When To Stay In `meta-capability`
+
+- The object boundary is still unclear.
+- The platform is unfamiliar and the task first needs route confirmation, parameter confirmation, or media-entry discovery.
+- The task first needs capability checking before a stricter work-card or author-card contract can be satisfied.
+- The user is asking what is available, what route to use, or what fields are required.
+- A better specialized skill is not currently available.

package/skills/meta-capability/references/execution-guidelines.md

@@ -0,0 +1,25 @@
+# Execution Guidelines
+
+## Goal
+
+Within a shared cross-platform execution flow, finish capability discovery, route selection, input confirmation, and field-availability checks before moving into extraction or analysis.
+
+## Minimum Checklist
+
+- Confirm the platform and object type: single content item, comments, profile, or content collection.
+- Read `api-capability-index.md` and lock onto the relevant platform tag.
+- Read the relevant routes in `api-tags/*.md` for auth requirements, key inputs, and key success responses.
+- If exact field definitions, defaults, examples, or full success-response structures are needed, continue into the relevant `api-contracts/*.md`.
+- Decide whether the task can use a validated route chain from this repository or needs an ad hoc route choice from the broader catalog.
+- For video ASR, decide whether `service-guides/asr-u2-u3-fallback.md` is needed for the 90-second soft observation window and the 120-second hard fallback.
+- Identify the usable entry points: share URL, landing-page URL, platform ID, profile URL, download URL, or raw text.
+- Identify the retrievable resources: title, caption, subtitles, comments, media download URLs, author metadata, and engagement metrics.
+- Confirm the output expectation: raw facts, structured fields, analysis conclusions, or a combination.
+- Confirm missing-field and degradation behavior: which fields are stable, which need fallback, and which are currently unavailable.
+
+## Output Requirements
+
+- Return concrete routes, inputs, and results rather than generic advice.
+- Make field origin, stability, and missing reasons explicit.
+- Ground every analysis conclusion in retrieved facts only.
+- Prefer platform-neutral output structures when possible so the results remain reusable.

package/skills/meta-capability/references/implemented-route-map.md

@@ -0,0 +1,177 @@
+# Validated Route Chains
+
+## Contents
+
+- [Purpose](#purpose)
+- [Single Content](#single-content)
+- [Creator Profiles](#creator-profiles)
+- [Other Platforms](#other-platforms)
+
+## Purpose
+
+- This file records only the preferred route chains that already have script support and have been validated in this repository.
+- It does not replace `api-capability-index.md` + `api-tags/*.md` + `api-contracts/*.md`. The first two provide discovery and route summaries, the third provides full contracts, and this file answers the narrower question: which chain should be tried first.
+- When the user target is already clear, prefer the chains listed here. Only go back to the index and tag files when the validated chain is insufficient.
+
+## Single Content
+
+### Douyin Single Content
+
+1. `GET /api/u1/v1/douyin/app/v3/fetch_one_video_by_share_url`
+   - Required input: `share_url`
+2. `GET /api/u1/v1/douyin/web/fetch_one_video_by_share_url`
+   - Required input: `share_url`
+3. `POST /api/u2/v1/services/audio/asr/transcription`
+   - Key request-body field: `input.file_urls[]`
+4. `POST /api/u2/v1/tasks/{task_id}`
+   - Path parameter: `task_id`
+
+ASR timeout fallback:
+
+- After 90 seconds, stay in soft observation only.
+- After 120 seconds, if there is still no result, do not declare failure immediately. Follow `service-guides/asr-u2-u3-fallback.md`, use U3 fallback, and then retry U2.
+
+Required output targets:
+
+- `platform_work_id`
+- `platform_author_id`
+- `author_handle`
+- `title`
+- `caption_raw`
+- `work_modality`
+- `published_date`
+- `digg_count`
+- `comment_count`
+- `collect_count`
+- `share_count`
+- `play_count`
+- `cover_image`
+- `source_url`
+- `share_url`
+- `video_download_url`
+- `asr_raw`
+
+### Xiaohongshu Single Content
+
+1. `GET /api/u1/v1/xiaohongshu/app_v2/get_video_note_detail`
+2. `GET /api/u1/v1/xiaohongshu/app_v2/get_image_note_detail`
+3. `GET /api/u1/v1/xiaohongshu/app_v2/get_mixed_note_detail`
+   - Typical input: `note_id` or `share_text`
+4. `GET /api/u1/v1/xiaohongshu/app/get_note_info`
+5. `GET /api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v2`
+   - Required input: `note_id`
+6. `GET /api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v3`
+   - Required input: `short_url`
+7. `GET /api/u1/v1/xiaohongshu/web/get_note_info_v7`
+8. `POST /api/u2/v1/services/audio/asr/transcription`
+9. `POST /api/u2/v1/tasks/{task_id}`
+
+ASR timeout fallback:
+
+- After 90 seconds, stay in soft observation only.
+- After 120 seconds, if there is still no result, do not declare failure immediately. Follow `service-guides/asr-u2-u3-fallback.md`, use U3 fallback, and then retry U2.
+
+Required output targets:
+
+- `platform_work_id`
+- `platform_author_id`
+- `author_handle`
+- `title`
+- `caption_raw`
+- `work_modality`
+- `published_date`
+- `digg_count`
+- `comment_count`
+- `collect_count`
+- `share_count`
+- `play_count`
+- `cover_image`
+- `source_url`
+- `share_url`
+- `video_download_url`
+- `asr_raw`
+
+## Creator Profiles
+
+### Douyin Creator Profile
+
+1. `GET /api/u1/v1/douyin/web/get_sec_user_id`
+   - OpenAPI-required input: `url`
+2. `GET /api/u1/v1/douyin/app/v3/handler_user_profile`
+   - Required input: `sec_user_id`
+3. `GET /api/u1/v1/douyin/app/v3/fetch_user_post_videos`
+   - Required input: `sec_user_id`
+   - Common pagination parameters: `max_cursor`, `count`, `sort_type`
+
+Required author-card fields:
+
+- `platform_author_id`
+- `author_handle`
+- `nickname`
+- `ip_location`
+- `signature`
+- `avatar_url`
+- `fans_count`
+- `liked_count`
+- `works_count`
+- `verified`
+
+Required profile-post fields:
+
+- `platform_work_id`
+- `title`
+- `caption_raw`
+- `published_date`
+- `digg_count`
+- `comment_count`
+- `collect_count`
+- `share_count`
+- `play_count`
+- `video_download_url`
+
+### Xiaohongshu Creator Profile
+
+1. `GET /api/u1/v1/xiaohongshu/app/get_user_id_and_xsec_token`
+   - OpenAPI-required input: `share_link`
+2. Profile cascade:
+   - `GET /api/u1/v1/xiaohongshu/app_v2/get_user_info`
+   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_user_info_app`
+   - `GET /api/u1/v1/xiaohongshu/app/get_user_info`
+3. Posts cascade:
+   - `GET /api/u1/v1/xiaohongshu/app_v2/get_user_posted_notes`
+   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_home_notes_app`
+   - `GET /api/u1/v1/xiaohongshu/app/get_user_notes`
+
+Required author-card fields:
+
+- `platform_author_id`
+- `author_handle`
+- `nickname`
+- `ip_location`
+- `signature`
+- `avatar_url`
+- `fans_count`
+- `liked_count`
+- `collected_count`
+- `works_count`
+- `verified`
+
+Required profile-post fields:
+
+- `platform_work_id`
+- `title`
+- `caption_raw`
+- `published_date`
+- `digg_count`
+- `comment_count`
+- `collect_count`
+- `share_count`
+- `play_count`
+- `video_download_url`
+
+## Other Platforms
+
+- Start with `api-capability-index.md` to find the relevant platform tag, then read the relevant `api-tags/*.md`. If the field definitions are still not precise enough, continue into the relevant `api-contracts/*.md`.
+- For a single content item, prefer a detail route first, then add media, subtitle, or comment routes as needed.
+- For a creator profile, prefer a profile route plus a posts route. Do not stop at a single segment of data.
+- Declare a platform or object infeasible only when the full catalog still cannot provide routes that satisfy the required output fields.

package/skills/meta-capability/references/service-guides/asr-u2-u3-fallback.md

@@ -0,0 +1,75 @@
+# U2 ASR and U3 Public URL Fallback
+
+## Purpose
+
+- This guide defines the primary ASR path and timeout fallback for video tasks. It does not apply to text-only works.
+- Always try U2 ASR first. U3 is fallback-only and must not bypass U2 by default.
+- If a U1 detail route returns a no-watermark download link or another download URL that may not be publicly readable, use this guide to decide when to switch to U3.
+- Source: `https://app.tikomni.com/openapi/tikomni-openapi.full.with-u2.public.latest.json`
+- Fetched at: `2026-03-08T06:54:04+00:00`
+
+## Fixed Policy
+
+1. Call a U1 detail route first and collect `video_download_url`, a no-watermark download URL, or another directly downloadable media URL.
+2. Submit that URL to U2 ASR directly. Do not start with U3.
+3. If there is still no complete result after 90 seconds, stay in soft observation and keep the primary path unchanged.
+4. If there is still no result or still no complete result after 120 seconds, treat the source URL as likely not publicly readable and only then allow U3 fallback.
+5. After U3 completes, obtain a public URL and submit it to U2 ASR again.
+6. If U3 or the second U2 attempt still fails, keep the fact card and return `incomplete`. Do not fabricate the main text or any analysis conclusion.
+
+## Scenario Notes
+
+- Single content task: run this flow only for the current item.
+- Creator batch task: apply U3 fallback only to the subset that still has no result after 120 seconds. Do not re-upload items that already succeeded.
+
+## Route Facts
+
+### Submit U2 ASR job
+
+- Purpose: Default primary path. Submit the no-watermark or download URL returned by U1 directly to U2 ASR. Do not start with U3.
+- Tag: [`ASR-API`](../api-tags/asr-api.md)
+- Route: `POST /api/u2/v1/services/audio/asr/transcription`
+- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
+- Parameters: None
+- Request body: application/json: `input*`{`file_urls*`[string(uri)]}
+- Success response: 200 application/json: `request_id*`:string, `output*`{`task_id*`:string, `task_status*`:string, `submit_time`:string, `scheduled_time`:string, `end_time`:string, `task_metrics`{...}, `results`[object]}, `usage`{...}
+- Full contract: [`api-contracts/asr-api.md#post-api-u2-v1-services-audio-asr-transcription`](../api-contracts/asr-api.md#post-api-u2-v1-services-audio-asr-transcription)
+
+### Poll U2 job status
+
+- Purpose: Observe job completion. Stay in soft observation after 90 seconds. Trigger U3 fallback only if there is still no result after 120 seconds.
+- Tag: [`ASR-API`](../api-tags/asr-api.md)
+- Route: `POST /api/u2/v1/tasks/{task_id}`
+- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
+- Parameters: path: `task_id*`
+- Request body: None
+- Success response: 200 application/json: `time*`:string, `time_stamp*`:integer, `time_zone*`:string, `params*`{`task_id*`:string}, `data*`{`task_id*`:string, `task_status*`:string | null, `platform_task_status*`:string, `is_fully_succeeded*`:boolean, `submit_time`:string, `scheduled_time`:string, `end_time`:string, `task_metrics`{...}, ...}, `code*`:integer, `request_id*`:string, `message*`:string, ...
+- Full contract: [`api-contracts/asr-api.md#post-api-u2-v1-tasks-task-id`](../api-contracts/asr-api.md#post-api-u2-v1-tasks-task-id)
+
+### Request U3 upload / relay
+
+- Purpose: Use only if U2 still has no result after 120 seconds. Its purpose is to convert a private or non-publicly-readable source link into a public URL.
+- Tag: [`Media-Ingest-API`](../api-tags/media-ingest-api.md)
+- Route: `POST /api/u3/v1/uploads`
+- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
+- Parameters: None
+- Request body: application/json: `provider*`:string, `file_name*`:string, `content_type*`:string, `size_bytes*`:integer
+- Success response: 200 application/json: `time*`:string, `time_stamp*`:integer, `time_zone*`:string, `params*`{`provider*`:string, `file_name*`:string, `content_type*`:string, `size_bytes*`:integer}, `data*`{`upload_id*`:string, `provider*`:string, `upload_method*`:string, `upload_url*`:string, `upload_headers*`{...}, `upload_expires_at*`:string, `file_ttl_seconds*`:integer}, `code*`:integer, `request_id*`:string, `message*`:string, ...
+- Full contract: [`api-contracts/media-ingest-api.md#post-api-u3-v1-uploads`](../api-contracts/media-ingest-api.md#post-api-u3-v1-uploads)
+
+### Complete U3 upload and get a public URL
+
+- Purpose: Completion should return a public URL. Submit that URL to U2 ASR again. If it still fails, keep the fact card and return incomplete.
+- Tag: [`Media-Ingest-API`](../api-tags/media-ingest-api.md)
+- Route: `POST /api/u3/v1/uploads/{upload_id}/complete`
+- Auth: Header `Authorization: Bearer {token}`; docs also allow Cookie `Authorization` as fallback (`HTTPBearer`)
+- Parameters: path: `upload_id*`
+- Request body: application/json: dynamic object
+- Success response: 200 application/json: `time*`:string, `time_stamp*`:integer, `time_zone*`:string, `params*`{`upload_id*`:string}, `data*`{`upload_id*`:string, `provider*`:string, `file_url*`:string, `file_expires_at*`:string}, `code*`:integer, `request_id*`:string, `message*`:string, ...
+- Full contract: [`api-contracts/media-ingest-api.md#post-api-u3-v1-uploads-upload-id-complete`](../api-contracts/media-ingest-api.md#post-api-u3-v1-uploads-upload-id-complete)
+
+## Execution Notes
+
+- This guide only defines route order and fallback order. It does not replace platform-specific detail-route selection.
+- The U1 source route depends on the platform, for example a Douyin or Xiaohongshu detail route. This guide only requires using the returned download URL first.
+- If the platform already returns usable `subtitle_raw`, map it directly to `asr_raw` instead of calling U2 or U3.

package/skills/meta-capability/scripts/__init__.py

@@ -0,0 +1 @@
+"""Meta capability runtime scripts."""

package/skills/meta-capability/scripts/call_route.py

@@ -0,0 +1,141 @@
+#!/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" / "core" / "bootstrap_env.py").is_file():
+            sys.path.insert(0, str(_parent))
+            break
+
+"""Call any TikOmni route with Authorization for meta-capability."""
+
+from scripts.core.bootstrap_env import bootstrap_for_direct_run
+
+bootstrap_for_direct_run(__file__, __package__)
+
+import argparse
+import json
+from typing import Any, Dict, Optional
+
+from scripts.core.config_loader import load_tikomni_config, resolve_runtime_settings
+from scripts.core.tikomni_common import call_json_api, resolve_runtime, write_json_stdout
+
+
+def _parse_json_arg(name: str, raw_value: Optional[str]) -> Optional[Any]:
+    if raw_value is None or not str(raw_value).strip():
+        return None
+    try:
+        return json.loads(raw_value)
+    except Exception as error:
+        raise ValueError(f"invalid_json:{name}") from error
+
+
+def _require_mapping(name: str, payload: Optional[Any]) -> Optional[Dict[str, Any]]:
+    if payload is None:
+        return None
+    if not isinstance(payload, dict):
+        raise ValueError(f"{name}_must_be_json_object")
+    return payload
+
+
+def _normalize_headers(payload: Optional[Any]) -> Optional[Dict[str, str]]:
+    mapping = _require_mapping("headers", payload)
+    if mapping is None:
+        return None
+    normalized: Dict[str, str] = {}
+    for key, value in mapping.items():
+        normalized[str(key)] = str(value)
+    return normalized
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Call a TikOmni route with meta-capability auth")
+    parser.add_argument("method", help="HTTP method, for example GET or POST")
+    parser.add_argument("path", help="Route path, for example /api/u1/v1/health/check")
+    parser.add_argument("--params-json", default=None, help='JSON object for query params, for example {"id":"123"}')
+    parser.add_argument("--body-json", default=None, help='JSON payload for request body')
+    parser.add_argument(
+        "--headers-json",
+        default=None,
+        help='Optional extra headers JSON, for example {"X-Debug":"1"}',
+    )
+    parser.add_argument("--config", default=None, help="Optional YAML config path")
+    parser.add_argument("--env-file", default=None, help="Optional env file path under skills root")
+    parser.add_argument("--api-key-env", default=None, help="Optional API key env variable name override")
+    parser.add_argument("--base-url", default=None, help="Optional TikOmni API base URL override")
+    parser.add_argument("--timeout-ms", type=int, default=None, help="Optional timeout override in milliseconds")
+    parser.add_argument("--allow-process-env", action="store_true", help="Allow process env to override env files")
+    args = parser.parse_args()
+
+    try:
+        params = _require_mapping("params", _parse_json_arg("params", args.params_json))
+        body = _parse_json_arg("body", args.body_json)
+        extra_headers = _normalize_headers(_parse_json_arg("headers", args.headers_json))
+
+        config, config_path = load_tikomni_config(
+            cli_config_path=args.config,
+            env_file=args.env_file,
+            allow_process_env=args.allow_process_env,
+        )
+        runtime_settings = resolve_runtime_settings(
+            config=config,
+            cli_base_url=args.base_url,
+            cli_timeout_ms=args.timeout_ms,
+            cli_api_key_env=args.api_key_env,
+        )
+        runtime = resolve_runtime(
+            env_file=args.env_file,
+            api_key_env=runtime_settings["api_key_env"],
+            base_url=runtime_settings["base_url"],
+            timeout_ms=runtime_settings["timeout_ms"],
+            allow_process_env=args.allow_process_env,
+        )
+    except Exception as error:
+        write_json_stdout(
+            {
+                "ok": False,
+                "method": args.method.upper(),
+                "path": args.path,
+                "error_reason": str(error),
+                "request_id": None,
+            }
+        )
+        raise SystemExit(2) from error
+
+    result = call_json_api(
+        base_url=runtime["base_url"],
+        path=args.path,
+        token=runtime["token"],
+        method=args.method.upper(),
+        timeout_ms=runtime["timeout_ms"],
+        params=params,
+        body=body,
+        extra_headers=extra_headers,
+    )
+
+    write_json_stdout(
+        {
+            "ok": result["ok"],
+            "method": args.method.upper(),
+            "path": args.path,
+            "base_url": runtime["base_url"],
+            "params": params,
+            "body": body,
+            "extra_headers": extra_headers,
+            "status_code": result.get("status_code"),
+            "request_id": result.get("request_id"),
+            "error_reason": result.get("error_reason"),
+            "auth_env_key": runtime_settings["api_key_env"],
+            "config_path": config_path,
+            "env_bootstrap": runtime.get("env_bootstrap", {}),
+            "data": result.get("data", {}),
+        }
+    )
+    raise SystemExit(0 if result["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/meta-capability/scripts/core/__init__.py

@@ -0,0 +1 @@
+"""Core helpers for meta capability runtime."""

package/skills/meta-capability/scripts/core/bootstrap_env.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Shared bootstrap utilities for direct script execution."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def _locate_repo_root(file_path: str) -> Optional[Path]:
+    current = Path(file_path).resolve()
+    for parent in current.parents:
+        if (parent / "scripts").is_dir():
+            return parent
+    return None
+
+
+def bootstrap_for_direct_run(file_path: str, package: Optional[str] = None) -> Optional[str]:
+    """Inject repo root into sys.path when executed as a direct script path."""
+
+    if package not in {None, ""}:
+        return None
+
+    repo_root = _locate_repo_root(file_path)
+    if repo_root is None:
+        return None
+
+    repo_root_str = str(repo_root)
+    if repo_root_str not in sys.path:
+        sys.path.insert(0, repo_root_str)
+    return repo_root_str