@tikomni/skills 0.1.2 → 0.1.4

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

@@ -1,18 +0,0 @@
-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

@@ -1,27 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-# 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

@@ -1,177 +0,0 @@
-# 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

@@ -1,75 +0,0 @@
-# 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

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

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

@@ -1,141 +0,0 @@
-#!/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

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

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

@@ -1,32 +0,0 @@
-#!/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