@tikomni/skills 0.1.2 → 0.1.4

package/skills/social-media-crawl/references/contracts/work-fact-card-fields.md

@@ -0,0 +1,48 @@
+# Work Fact Card Fields
+
+## Required Fields
+
+- `platform`
+- `platform_work_id`
+- `platform_author_id`
+- `author_handle`
+- `author`
+- `title`
+- `caption_raw`
+- `work_modality`
+- `published_date`
+- `cover_image`
+- `source_url`
+- `share_url`
+- `primary_text`
+- `primary_text_source`
+- `request_id`
+- `completeness`
+- `missing_fields`
+- `error_reason`
+- `extract_trace`
+
+## Optional Fields
+
+- `digg_count`
+- `comment_count`
+- `collect_count`
+- `share_count`
+- `play_count`
+- `video_download_url`
+- `asr_raw`
+- `asr_clean`
+- `subtitle_raw`
+
+## Field Rules
+
+- `author` 是展示名，不是对象。
+- `primary_text` 为当前任务最适合阅读和索引的主文本。
+- 视频优先顺序：
+  - `subtitle_raw`
+  - `asr_clean`
+  - `caption_raw`
+- 文本作品优先顺序：
+  - `caption_raw`
+- 不允许出现分析字段。
+

package/skills/social-media-crawl/references/guides/generic-mcp-objects.md

@@ -0,0 +1,30 @@
+# Generic MCP Objects Guide
+
+以下对象在首期不冻结细粒度 schema：
+
+- 评论线程
+- 搜索结果
+- 榜单
+- 直播间
+- 商品页
+
+## Rules
+
+- 这些对象统一走 MCP 通用工作流。
+- agent 先做对象识别，再用 `catalog.search` 和 `endpoint.describe` 选最小工具链。
+- 输出必须满足统一 envelope。
+- 不要求首期落卡。
+- 不允许为了 schema 完整性去编造字段。
+
+## Minimum Deliverable
+
+- `object_type`
+- `platform`
+- `input`
+- `normalized`
+- `request_id`
+- `completeness`
+- `missing_fields`
+- `error_reason`
+- `extract_trace`
+

package/skills/social-media-crawl/references/mcp-usage-contract.md

@@ -0,0 +1,30 @@
+# MCP Usage Contract
+
+## Fixed Inputs
+
+- MCP URL: `https://mcp.tikomni.com/mcp`
+- Auth: `Authorization: Bearer <TIKOMNI_API_KEY>`
+- 不在工具参数中重复传 API key
+
+## Required Tool Order
+
+1. `tools/list`
+2. 识别是否命中固定 pipeline
+3. 若不命中固定 pipeline：
+   - `catalog.search`
+   - `endpoint.describe`
+   - `api.call`
+4. 若需要视频文本：
+   - `u2.submit`
+   - `u2.query`
+   - 超过 60 秒仍 `pending` 时进入 U3 fallback
+
+## Output Rules
+
+- 事实字段与派生元数据分离
+- 结果必须包含 `request_id`
+- 结果必须包含 `completeness`
+- 结果必须包含 `missing_fields`
+- 结果必须包含 `error_reason`
+- 结果必须包含 `extract_trace`
+

package/skills/social-media-crawl/references/pipelines/douyin-creator-home.md

@@ -0,0 +1,7 @@
+# Douyin Creator Home
+
+- 输入：主页链接或分享短链
+- 输出：`creator_profile.json`、`work_collection.json`、多张 `work_fact_card`
+- 实现脚本：`scripts/pipelines/run_douyin_creator_home.py`
+- 必测样例：计划冻结样例中的抖音主页链接
+

package/skills/social-media-crawl/references/pipelines/douyin-single-work.md

@@ -0,0 +1,7 @@
+# Douyin Single Work
+
+- 输入：作品链接或分享短链
+- 输出：统一 `work_fact_card`
+- 实现脚本：`scripts/pipelines/run_douyin_single_work.py`
+- 必测样例：计划冻结样例中的抖音作品链接
+

package/skills/social-media-crawl/references/pipelines/xiaohongshu-creator-home.md

@@ -0,0 +1,7 @@
+# Xiaohongshu Creator Home
+
+- 输入：主页链接或分享短链
+- 输出：`creator_profile.json`、`work_collection.json`、多张 `work_fact_card`
+- 实现脚本：`scripts/pipelines/run_xiaohongshu_creator_home.py`
+- 必测样例：计划冻结样例中的小红书主页链接
+

package/skills/social-media-crawl/references/pipelines/xiaohongshu-single-work.md

@@ -0,0 +1,7 @@
+# Xiaohongshu Single Work
+
+- 输入：作品链接或分享短链
+- 输出：统一 `work_fact_card`
+- 实现脚本：`scripts/pipelines/run_xiaohongshu_single_work.py`
+- 必测样例：计划冻结样例中的小红书作品链接
+

package/skills/social-media-crawl/references/schemas/creator-profile.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "social-media-crawl/creator-profile.schema.json",
+  "type": "object",
+  "required": [
+    "platform",
+    "platform_author_id",
+    "author_handle",
+    "nickname",
+    "request_id",
+    "extract_trace"
+  ],
+  "properties": {
+    "platform": { "type": "string" },
+    "platform_author_id": { "type": "string" },
+    "author_handle": { "type": "string" },
+    "nickname": { "type": "string" },
+    "signature": { "type": "string" },
+    "avatar_url": { "type": "string" },
+    "fans_count": { "type": "integer" },
+    "liked_count": { "type": "integer" },
+    "collected_count": { "type": "integer" },
+    "works_count": { "type": "integer" },
+    "verified": { "type": "boolean" },
+    "request_id": { "type": ["string", "null"] },
+    "extract_trace": {
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  },
+  "additionalProperties": true
+}
+

package/skills/social-media-crawl/references/schemas/output-envelope.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "social-media-crawl/output-envelope.schema.json",
+  "type": "object",
+  "required": [
+    "object_type",
+    "platform",
+    "input",
+    "normalized",
+    "completeness",
+    "missing_fields",
+    "extract_trace",
+    "request_id"
+  ],
+  "properties": {
+    "object_type": { "type": "string" },
+    "platform": { "type": "string" },
+    "input": {},
+    "normalized": {},
+    "completeness": {
+      "type": "string",
+      "enum": ["complete", "partial", "incomplete"]
+    },
+    "missing_fields": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "error_reason": {
+      "type": ["string", "null"]
+    },
+    "extract_trace": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "request_id": {
+      "type": ["string", "null"]
+    }
+  },
+  "additionalProperties": true
+}
+

package/skills/social-media-crawl/references/schemas/work-collection.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "social-media-crawl/work-collection.schema.json",
+  "type": "object",
+  "required": [
+    "platform",
+    "platform_author_id",
+    "count",
+    "items",
+    "request_id",
+    "extract_trace"
+  ],
+  "properties": {
+    "platform": { "type": "string" },
+    "platform_author_id": { "type": "string" },
+    "count": { "type": "integer" },
+    "items": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "request_id": { "type": ["string", "null"] },
+    "extract_trace": {
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  },
+  "additionalProperties": true
+}
+

package/skills/social-media-crawl/references/schemas/work-fact-card.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "social-media-crawl/work-fact-card.schema.json",
+  "type": "object",
+  "required": [
+    "platform",
+    "platform_work_id",
+    "platform_author_id",
+    "author_handle",
+    "author",
+    "title",
+    "caption_raw",
+    "work_modality",
+    "published_date",
+    "source_url",
+    "share_url",
+    "primary_text",
+    "primary_text_source",
+    "request_id",
+    "completeness",
+    "missing_fields",
+    "extract_trace"
+  ],
+  "properties": {
+    "platform": { "type": "string" },
+    "platform_work_id": { "type": "string" },
+    "platform_author_id": { "type": "string" },
+    "author_handle": { "type": "string" },
+    "author": { "type": "string" },
+    "title": { "type": "string" },
+    "caption_raw": { "type": "string" },
+    "subtitle_raw": { "type": "string" },
+    "work_modality": { "type": "string" },
+    "published_date": { "type": "string" },
+    "digg_count": { "type": "integer" },
+    "comment_count": { "type": "integer" },
+    "collect_count": { "type": "integer" },
+    "share_count": { "type": "integer" },
+    "play_count": { "type": "integer" },
+    "cover_image": { "type": "string" },
+    "source_url": { "type": "string" },
+    "share_url": { "type": "string" },
+    "video_download_url": { "type": "string" },
+    "primary_text": { "type": "string" },
+    "primary_text_source": { "type": "string" },
+    "asr_raw": { "type": "string" },
+    "asr_clean": { "type": "string" },
+    "request_id": { "type": ["string", "null"] },
+    "completeness": {
+      "type": "string",
+      "enum": ["complete", "partial", "incomplete"]
+    },
+    "missing_fields": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "error_reason": {
+      "type": ["string", "null"]
+    },
+    "extract_trace": {
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  },
+  "additionalProperties": false
+}
+

package/skills/social-media-crawl/references/service-guides/u2-u3-mandatory-fallback.md

@@ -0,0 +1,21 @@
+# U2 U3 Mandatory Fallback
+
+## Hard Rule
+
+- 视频文本优先尝试平台原生字幕。
+- 无原生字幕时先走 U2。
+- `u2.submit` 成功后，最多轮询 60 秒。
+- 如果 60 秒后仍是 `pending`，必须进入 U3 fallback。
+- U3 成功后继续完成 ASR 链路。
+- 若最终失败，保留事实卡并标记 `completeness=incomplete`。
+
+## Trace Requirement
+
+至少记录：
+
+- U2 submit
+- U2 poll
+- 触发 U3 的原因
+- U3 调用步骤
+- 最终文本来源
+

package/skills/social-media-crawl/scripts/__init__.py

@@ -0,0 +1,2 @@
+"""social-media-crawl scripts package."""
+

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

@@ -0,0 +1,2 @@
+"""Core helpers for social-media-crawl."""
+