@tikomni/skills 0.1.3 → 0.1.4

package/skills/single-work-analysis/references/asr-and-fallback.md

@@ -1,20 +0,0 @@
-# Single-Item ASR and Failure Handling
-
-## Video ASR
-
-1. Read `references/service-guides/asr-u2-u3-fallback.md` first and follow the shared flow: U2 primary path -> 90-second soft observation -> 120-second hard fallback -> U3 -> back to U2.
-2. If the route already returns `subtitle_raw`, map it to `asr_raw` first.
-3. If `subtitle_raw` is unavailable, call ASR with `video_download_url`.
-4. Derive `asr_clean` only from `asr_raw` through the cleaning rules.
-
-## Timeout and Fallback
-
-- 90 seconds: soft observation threshold.
-- 120 seconds: hard fallback threshold.
-- If there is still no complete `asr_raw` after 120 seconds, use the upload-media -> public URL -> ASR retry fallback path.
-
-## Failure End State
-
-- If the upstream media-upload route is unavailable, or if `asr_raw` is still unavailable after fallback, keep the fact card.
-- Return `incomplete` in that state.
-- Do not fabricate `primary_text`, and do not output analysis conclusions that depend on missing main text.

package/skills/single-work-analysis/references/config-templates/defaults.yaml

@@ -1,47 +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"
-  content_kind_card_type:
-    single_video: work
-    note: work
-    work: work
-  card_type_routes:
-    work:
-      prefix: "CBV"
-      parts:
-        - "内容系统"
-        - "对标研究"
-        - "作品卡"
-
-naming_rules:
-  card_filename_pattern: "{prefix}-{platform}-{author_slug}-{title_slug}{ext}"
-  json_filename_pattern: "{timestamp}-{platform}-{identifier}{ext}"
-
-analysis:
-  provider: auto
-  timeout_sec: 90
-
-asr_strategy:
-  poll_interval_sec: 3.0
-  max_polls: 10
-  submit_retry:
-    douyin_video:
-      max_retries: 2
-      backoff_ms: 1500
-    xiaohongshu_note:
-      max_retries: 0
-      backoff_ms: 0
-  u2_timeout_retry:
-    enabled: true
-    max_retries: 0

package/skills/single-work-analysis/references/contracts/work-card-fields.md

@@ -1,41 +0,0 @@
-# Work Card Fields
-
-## Final Display Fields
-
-- `platform`
-- `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`
-- `primary_text`
-
-## Video-Only Additional Fields
-
-- `asr_raw`
-- `video_download_url`
-
-## Key Semantics
-
-- `caption_raw` is the author-written description, caption, or body text. It is not subtitles and it is not raw ASR.
-- `primary_text` is the main display text and the main analysis text:
-  - video: `primary_text = asr_clean`
-  - text: `primary_text = caption_raw`
-- `video_download_url` is a required field for video items and should default to the no-watermark download URL when available.
-- `subtitle_raw` is a collection-layer source field and should not appear in the final work-card body.
-
-## Missing-Value Rules
-
-- Missing numeric fields should be rendered as `N/A` in the display layer.
-- Preserve `0` when the platform explicitly returns `0`.
-- Generate `published_date` in the display timezone, with `Asia/Shanghai` as the default.

package/skills/single-work-analysis/references/platform-guides/douyin.md

@@ -1,47 +0,0 @@
-# Douyin Single Content Guide
-
-## Read This First
-
-- Use this guide first for Douyin single-item tasks.
-- The validated chain in this repository currently covers share URL -> single-video detail -> ASR when needed.
-
-## Preferred Resources
-
-- title: `title`
-- caption: `desc`
-- work ID: `aweme_id`
-- author ID: stable author identifier
-- author handle: `short_id` / `unique_id`
-- video download URL: prefer the no-watermark download URL
-
-## Preferred Route Chain
-
-1. Primary route: `GET /api/u1/v1/douyin/app/v3/fetch_one_video_by_share_url`
-   - Required input: `share_url`
-   - Purpose: fetch single-item detail, basic author fields, engagement metrics, and media resources.
-2. Fallback route: `GET /api/u1/v1/douyin/web/fetch_one_video_by_share_url`
-   - Required input: `share_url`
-   - Purpose: fallback when the app route fails or returns insufficient fields.
-3. Video transcription:
-   - `POST /api/u2/v1/services/audio/asr/transcription`
-   - polling: `POST /api/u2/v1/tasks/{task_id}`
-   - key request-body field: `input.file_urls[]`
-   - Purpose: produce `asr_raw` when the platform does not return usable subtitles.
-
-## Unified Fields To Fill
-
-- required fields: `platform`, `platform_work_id`, `platform_author_id`, `author_handle`, `title`, `caption_raw`, `work_modality`
-- engagement metrics: `digg_count`, `comment_count`, `collect_count`, `share_count`, `play_count`
-- source links: `source_url`, `share_url`, `cover_image`
-- video-only fields: `video_download_url`, `asr_raw`
-
-## Route Rules
-
-- If the user provides only a share URL, use the primary route chain directly instead of searching for other detail routes first.
-- Prefer platform-native subtitles for video items. Call U2 ASR only when usable `subtitle_raw` or `asr_raw` is missing.
-- If U2 still has no result after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback.
-- If the target is comments, search, rankings, or another non-single-item task, leave this guide and go back to `references/api-capability-index.md` for route discovery.
-
-## Current Runnable Implementation
-
-- `skills/single-work-analysis/scripts/platform/douyin/`

package/skills/single-work-analysis/references/platform-guides/generic.md

@@ -1,43 +0,0 @@
-# Generic Single-Content Guide
-
-## Goal
-
-Map an unfamiliar platform's single content item into the unified work-card field dictionary and then complete the single-item analysis.
-
-## Read Order
-
-- Start with `references/api-capability-index.md` to find the relevant platform tag.
-- Read the matching `references/api-tags/<tag>.md` for route summaries, inputs, request bodies, and success-response summaries.
-- Prioritize routes related to `detail / post / note / video / article / comment / download / subtitle`.
-- Decide whether extra comment, subtitle, media-download, or author-supplement routes are needed.
-
-## Minimum Mapping Checklist
-
-- `work_modality`
-- `title`
-- `caption_raw`
-- `platform_work_id`
-- `platform_author_id`
-- `author_handle`
-- `source_url`
-- `share_url`
-- for video items: `video_download_url`
-- engagement metrics: digg, comment, collect, share, play
-
-## Route Rules
-
-- The detail route must reliably provide `platform_work_id`, main text, author identity, and at least one of media URL or cover image.
-- If the detail route does not return subtitles for a video item, keep searching for a subtitle route or a usable download URL before entering ASR.
-- If the platform offers App / Web / V2 / V3 variants at the same time, prefer the version with fuller fields and more stable behavior, and keep a recorded fallback.
-- Do not skip required-field validation just because one route returns some usable data.
-- If U2 still has no result after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback.
-
-## Additional Video Requirements
-
-- If platform subtitles exist, map them to `subtitle_raw` first and then normalize into `asr_raw`.
-- If subtitles do not exist, ensure `video_download_url` first and then call ASR.
-
-## Current Runnable Implementation
-
-- `skills/single-work-analysis/scripts/platform/`
-- `skills/single-work-analysis/scripts/core/`

package/skills/single-work-analysis/references/platform-guides/xiaohongshu.md

@@ -1,54 +0,0 @@
-# Xiaohongshu Single Content Guide
-
-## Read This First
-
-- Use this guide first for Xiaohongshu single-item tasks.
-- The validated route chain in this repository is `APP_V2 -> APP_V1 -> WEB_V2 -> WEB_V7`, with the detail route chosen by note type.
-
-## Preferred Resources
-
-- title: `title`
-- caption: `desc` / `content`
-- work ID: `note_id`
-- author ID: platform author identifier
-- author handle: readable account identifier
-- for video notes, check platform-native subtitles before deciding whether ASR is needed
-
-## Preferred Route Chain
-
-1. Primary routes:
-   - `GET /api/u1/v1/xiaohongshu/app_v2/get_video_note_detail`
-   - `GET /api/u1/v1/xiaohongshu/app_v2/get_image_note_detail`
-   - `GET /api/u1/v1/xiaohongshu/app_v2/get_mixed_note_detail`
-   - Typical input: `note_id` or `share_text`
-   - Purpose: fetch the most complete note detail based on note type.
-2. Fallback 1: `GET /api/u1/v1/xiaohongshu/app/get_note_info`
-   - Typical input: `note_id` or `share_text`
-3. Fallback 2:
-   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v2`
-     - Required input: `note_id`
-   - `GET /api/u1/v1/xiaohongshu/web_v2/fetch_feed_notes_v3`
-     - Required input: `short_url`
-4. Fallback 3: `GET /api/u1/v1/xiaohongshu/web/get_note_info_v7`
-   - Typical input: `note_id` or `share_text`
-5. Video transcription:
-   - `POST /api/u2/v1/services/audio/asr/transcription`
-   - `POST /api/u2/v1/tasks/{task_id}`
-
-## Unified Fields To Fill
-
-- required fields: `platform`, `platform_work_id`, `platform_author_id`, `author_handle`, `title`, `caption_raw`, `work_modality`
-- engagement metrics: `digg_count`, `comment_count`, `collect_count`, `share_count`, `play_count`
-- source links: `source_url`, `share_url`, `cover_image`
-- video-only fields: `video_download_url`, `asr_raw`
-
-## Route Rules
-
-- If the user provides only a short link, try parsing `note_id` from `share_text` first. Use the `short_url`-specific WEB_V2 route only when parsing fails.
-- If `note_id` is already known, query by `note_id` directly instead of going through the share-link path.
-- Prefer platform-native subtitles for video notes. Trigger U2 ASR only when subtitles are missing and a usable `video_download_url` exists.
-- If U2 still has no result after 120 seconds, follow `references/service-guides/asr-u2-u3-fallback.md` and use U3 fallback.
-
-## Current Runnable Implementation
-
-- `skills/single-work-analysis/scripts/platform/xiaohongshu/`

package/skills/single-work-analysis/references/prompt-contracts/analysis-bundle.md

@@ -1,82 +0,0 @@
-# Prompt Contract · 单次结构化作品分析（analysis-bundle）
-
-## User Prompt (Verbatim)
-
-```text
-=== 你的身份 ===
-一位见证了无数内容起落的观察者，曾亲手打造过刷屏级作品，也经历过石沉大海的落寞。
-你能透过表象看到人性的涌动，理解为什么有些内容能击中集体潜意识。
-=== 核心信念 ===
-爆款不是运气的产物，而是人性规律的必然显现。
-真正的洞察者不追逐热点，而是理解热点背后的情感暗流。
-=== 分析维度 ===
-- 情绪共振点：触发了哪根集体心弦
-- 认知势能差：创造了怎样的信息落差
-- 社交货币值：给了人们什么谈资筹码
-- 行动驱动力：激发了哪种传播冲动
-=== 洞察深度 ===
-像考古学家解读文物，你要揭示：
-- 表层吸引力（第一眼为什么会停留）
-- 中层粘性（为什么会看完）
-- 深层共鸣（为什么会转发）
-- 底层动机（满足了什么心理需求）
-=== 表达方式 ===
-如同品酒师描述佳酿——既有专业的解构，也有诗意的感受。
-用清晰的逻辑拆解成功密码，用生动的类比让洞察可感知。
-=== 独特价值 ===
-不做事后诸葛亮式的解释，而是提炼可复用的原理。
-让创作者读完后恍然大悟："原来爆款的秘密藏在这里。"
-=== 分析美学 ===
-呈现如解剖图般精准，又如水墨画般留有想象空间。
-既见树木（具体技巧），也见森林（传播规律）。
-=== 终极使命 ===
-帮助创作者建立"爆款直觉"——
-不是教他们追逐每一个热点，而是理解什么样的内容天生具有传播基因。
-
-任务：
-基于输入数据，一次性输出 5 个字段：
-- topic
-- style
-- hook
-- structure
-- insight
-
-输出要求：
-1. 只输出一个 JSON 对象，不要输出 markdown，不要输出解释。
-2. 每个字段的值必须是字符串数组。
-3. 中文输出。
-4. 缺少数据时直接写“数据不足”。
-5. 只能基于输入字段推断，不得臆造事实。
-
-JSON schema:
-{
-  "topic": ["..."],
-  "style": ["..."],
-  "hook": ["..."],
-  "structure": ["..."],
-  "insight": ["..."]
-}
-
-字段约束：
-- topic：聚焦选题类型、细分主题、受众痛点
-- style：聚焦句式、语气、人设表达
-- hook：聚焦开头、中段、结尾钩子
-- structure：聚焦结构标签、模板、缺失模块
-- insight：聚焦情绪共振点/认知势能差/社交货币值/行动驱动力
-必须保证表达方式和分析美学的要求，而不是因为格式约束为了精炼而精炼
-```
-
-## Inputs
-- `platform`
-- `title`
-- `caption_raw`
-- `asr_raw`
-- `asr_clean`
-- `work_modality`
-- `tags`
-- `metrics`
-
-## Constraints
-- 不得输出思维链。
-- 不得引用未提供的外部知识。
-- 若输入文本稀缺，允许多处返回“数据不足”。

package/skills/single-work-analysis/references/schemas/work-card.schema.json

@@ -1,39 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "single-work-analysis work card",
-  "type": "object",
-  "required": [
-    "platform",
-    "platform_work_id",
-    "platform_author_id",
-    "author_handle",
-    "caption_raw",
-    "work_modality",
-    "published_date",
-    "primary_text",
-    "primary_text_source"
-  ],
-  "properties": {
-    "platform": { "type": "string", "minLength": 1 },
-    "platform_work_id": { "type": "string", "minLength": 1 },
-    "platform_author_id": { "type": "string", "minLength": 1 },
-    "author_handle": { "type": "string" },
-    "title": { "type": "string" },
-    "caption_raw": { "type": "string" },
-    "work_modality": { "type": "string", "enum": ["video", "text"] },
-    "published_date": { "type": "string" },
-    "digg_count": { "type": "integer", "minimum": 0 },
-    "comment_count": { "type": "integer", "minimum": 0 },
-    "collect_count": { "type": "integer", "minimum": 0 },
-    "share_count": { "type": "integer", "minimum": 0 },
-    "play_count": { "type": ["integer", "null"], "minimum": 0 },
-    "cover_image": { "type": "string" },
-    "source_url": { "type": "string" },
-    "share_url": { "type": "string" },
-    "primary_text": { "type": "string" },
-    "primary_text_source": { "type": "string", "enum": ["asr_clean", "caption_raw"] },
-    "asr_raw": { "type": "string" },
-    "video_download_url": { "type": "string" }
-  },
-  "additionalProperties": true
-}

package/skills/single-work-analysis/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.