TikTok Live Commerce Intelligence

Use this skill to research public TikTok livestream commerce: discover live sessions with market filters, inspect one session and its performance metrics, or identify the products sold in that session.

Core Concepts

• This is read-only public-market research. It does not start, moderate, schedule, or manage a TikTok livestream.
• Search returns data.items[] plus data.total_count. Reuse a search item's string id for detail or related-product calls.
• Detail returns identity and creator context in data.items[]; include=core additionally returns performance metrics in data.core.items[].
• Related-product rows use tiktok_live_detail_product_* fields. Read references/api.md before interpreting them.
• Money fields are objects such as { "unit": "US", "value": 2015752.25 }. Preserve both fields and do not silently relabel or convert the unit.
• A requested country is query context; preserve the row-level country_code because it is authoritative for the returned record.

Data Fields

Endpoints

Call only the endpoint needed for the user's current question. Do not automatically drill from search to detail or products because each endpoint is billed independently.

Parameter Guide

• country: required lowercase marketplace code: br,de,es,fr,gb,id,it,jp,mx,my,ph,sg,th,us,vn.
• page: starts at 1. Search and related products accept pageSize up to 10.
• id: required for detail and related products. Pass 19-digit IDs as JSON strings to preserve precision.
• include: detail-only optional string; use core when normalized performance metrics are needed.
• Search supports keyword, category, productCategory, isLiving, isCommercial, sales/GMV/audience ranges, and sort in field:asc|desc form. The default sort is gmv:desc.
• Use the camelCase request fields documented in references/api.md; do not send the upstream snake_case aliases.

调用方式

• API 端点：POST /chuhaijiang/lives/search、POST /chuhaijiang/lives/detail 或 POST /chuhaijiang/lives/related-products（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/chuhaijiang_live_<entry>.py '<JSON 参数>' [--inline]，其中 <entry> 为 search、detail 或 related_products
• 成本约束：业务入口脚本默认只缓存成功响应 24 小时，业务成功的空结果也可缓存；缓存按当前工作目录、调用身份、网关、端点和完整请求参数隔离。相同组合命中时输出 Cache hit，不会发起新的付费请求。HTTP 或业务失败不缓存；--inline 不绕过缓存；--no-cache 会强制真实请求并可能再次消耗算力，仅在用户明确同意额外消耗或调试时使用。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-chuhaijiang-tiktok-live-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、业务总数、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

网关返回认证或余额错误时，读取 references/onboarding.md，按其中的 auth/billing 分流使用 scripts/onboarding.py。不要把 API Key、验证码、支付链接或原始用户消息写入反馈。

Usage Examples

python scripts/chuhaijiang_live_search.py '{"country":"us","isCommercial":true,"sort":"gmv:desc","page":1,"pageSize":3}'
python scripts/chuhaijiang_live_detail.py '{"country":"us","id":"7643101948819835678","include":"core"}'
python scripts/chuhaijiang_live_related_products.py '{"country":"us","id":"7643101948819835678","page":1,"pageSize":3}'

These examples were production-validated with non-empty semantic results on 2026-08-29. Public-market IDs are volatile; use a fresh search result if an example stops resolving.

Display Rules

1. State the requested marketplace, filters, sort, page, page size, and returned total.
2. For search, show title, room ID/link, host, time range, audience, products, units sold, GMV, GPM, and OPM when returned.
3. For detail, separate identity/host fields from optional core metrics; label follower_conversion_rate as a decimal unless explicitly formatting it as a percentage.
4. For related products, show product ID/title/image, country, price range, seller, units sold, GMV, commission rate, and conversion rate when present.
5. Preserve 19-digit IDs as strings. Preserve raw epoch-millisecond timestamps and add readable dates only as derived labels.
6. Report empty arrays honestly and never invent a product relationship or a currently-live status.

Important Limitations

1. Data reflects the provider's indexed public snapshot and can lag TikTok.
2. isLiving is a search filter, not proof that a returned room is still live when displayed later.
3. Related products are available only when the indexed live session has product relationships.
4. Search filters do not imply causality between audience, GMV, sales, and creator performance.
5. Do not expose internal tool identifiers, credentials, cache files, or unrelated response fields.

User Expression & Scenario Quick Reference

Use this skill: “用出海匠搜美国 TikTok 带货直播”, “用 Chuhaijiang 看这场直播详情”, “这场直播卖了哪些商品”, “出海匠 TikTok live analytics”.

Adjacent: General TikTok livestream rankings or detail requests without a named source should use linkfox-kalodata-tiktok-livestream. Product-first research, including finding livestreams associated with a product, uses linkfox-chuhaijiang-tiktok-product. Creator-first live research uses linkfox-chuhaijiang-tiktok-creator.

Not applicable: starting or scheduling livestreams, moderation, seller-backend operations, order handling, replay downloading, transcription, or media generation/editing.

算力消耗规则

按端点分别计费：直播详情 9 算力/次；直播搜索和直播关联商品 18 算力/次。

用户会因算力消耗而支付费用。高频调用或多端点钻取前，先说明预计调用次数与算力消耗。

Feedback: Use the Feedback API in references/api.md only when the user explicitly asks to submit feedback or authorizes it after an issue is identified. Sanitize the content and never include credentials, signed URLs, phone numbers, or unrelated task context.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.