linkfox-kalodata-tiktok-livestream

Kalodata - TikTok 直播搜索与详情

此技能通过 Kalodata 数据源支持两步 TikTok 直播工作流：

1. 浏览 TikTok Shop 直播排行榜，发现表现出色的带货直播。
2. 通过 livestreamId 获取某场直播的完整表现详情。

当用户需要排行榜、热门直播或发现直播时，使用搜索（排名）端点。当用户已有 livestreamId，或已从排行榜结果中选定某场直播时，使用详情端点。

核心概念

直播排名端点会返回分页排行榜，可按 region、dateRange、language、currency 和可选的 sortField 进行筛选。默认按 revenue（GMV）降序排列。每条直播记录包含身份、时间、规模和创作者字段。结果通过 pageNumber（1-5）和 pageSize（5-100）分页。响应不包含总数——请持续翻页，直到某页返回的条目数少于 pageSize。排名端点的金额字段（revenue、unit_price）以字符串形式返回。

直播详情端点通过 livestreamId 获取一场 TikTok 带货直播的数据。它会返回一个包含该场直播完整详情（12 个字段）的单元素数组，其中包括 viewers、数值类型的 revenue、gpm 和 product_number。该端点不分页，也没有 total。livestreamId 通常来自排名响应中的 livestream_id 字段。

两个端点的字段名称／类型有所不同：详情端点使用 viewers（排名端点使用 views）；详情端点的 revenue 是数值（排名端点的 revenue 是字符串）；详情端点有 gpm，但没有 unit_price（排名端点有 unit_price，但没有 gpm）。不要假设两个端点的字段名称／类型相同。

两个端点的数据都可能存在统计延迟（T+1）。完整的请求和响应详情请参阅 references/api.md。

数据字段

排名行（data 中的每个条目，来自 /kalodata/livestream/rank）：

字段	类型	描述
livestream_id	string	直播唯一 ID；将其作为 livestreamId 传入以查询详情
livestream_title	string	直播标题
creator_id	string	创作者唯一 ID（使用字符串以保留精度）
creator_handle	string	创作者账号名／用户名
livestream_start_time	integer	开始时间，Unix 纪元毫秒
livestream_end_time	integer	结束时间，Unix 纪元毫秒
livestream_duration	integer	时长，秒
revenue	string	所请求 currency 中的总收入／GMV——以字符串形式返回，例如 "185590.52"
unit_price	string	所请求 currency 中的平均单价——以字符串形式返回，例如 "265.89"
views	integer	总观看次数（注意：排名接口使用 views）
record_type	string	记录类型（例如 SHORT）

详情行（data 中的单个条目，来自 /kalodata/livestream/detail）：

字段	类型	描述
livestream_id	string	直播唯一 ID（与请求的 livestreamId 匹配）
livestream_title	string	直播标题（例如 24 HOUR STREAM）
creator_id	string	创作者唯一 ID（使用字符串以保留精度）
creator_handle	string	创作者账号名／用户名（例如 pokepiglt）
livestream_start_time	integer	开始时间，Unix 纪元毫秒
livestream_end_time	integer	结束时间，Unix 纪元毫秒
livestream_duration	integer	时长，秒
record_type	string	记录类型（例如 SHORT）
viewers	integer	总观众数（注意：详情接口使用 viewers，而非 views）
revenue	number	所请求 currency 中的直播收入／GMV，类型为数字（例如 185590.52）——这里是数字，排名接口中则是字符串
gpm	number	千次展示 GMV（每 1,000 次展示带来的收入）——仅详情接口提供，排名接口中不存在
product_number	integer	直播期间售出／推广的商品数量

**排名接口中的金额字段为字符串，详情接口中则为数字。**在进行数值比较或格式化之前，先将排名接口的 revenue／unit_price（使用 float()、Number() 或 ConvertFrom-Json）转换为数字。请使用所读取接口对应的确切字段名称（排名接口使用 views，详情接口使用 viewers）。

参数指南

直播排名（/kalodata/livestream/rank）——所有参数均为可选：

参数	类型	必填	描述
region	string	否	市场区域代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
pageNumber	integer	否	页码，1-5
pageSize	integer	否	每页数量，5-100
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	金额指标所用的币种，例如 USD
category_id	string	否	分类 ID 筛选条件
shop_id	string	否	店铺 ID 筛选条件
creator_id	string	否	创作者 ID 筛选条件
product_id	string	否	商品 ID 筛选条件
followers_range	string	否	创作者粉丝数范围筛选条件
sortField	object	否	排序规范；传入 {} 可使用默认排名顺序

直播详情（/kalodata/livestream/detail）：

参数	类型	必填	描述
livestreamId	string	是	目标直播的唯一 ID（驼峰命名），例如 7661409374878878494。通常从排名字段 livestream_id 获取
region	string	否	市场区域代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	金额指标所用的币种，例如 USD

调用方式

• API 端点：POST /kalodata/livestream/rank（榜单）或 POST /kalodata/livestream/detail（详情）（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/kalodata_livestream_search.py '<JSON 参数>' [--inline]（榜单）或 python scripts/kalodata_livestream_detail.py '<JSON 参数>' [--inline]（详情）
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

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

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

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

Usage Examples

1. Browse top TikTok livestreams in the US

{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1}

2. Fetch one livestream's detail

{"livestreamId":"7661409374878878494","region":"US","dateRange":"last7Day"}

3. Discovery-to-detail workflow

Run kalodata_livestream_search.py first, choose a row's livestream_id, then pass that value as livestreamId to kalodata_livestream_detail.py.

Display Rules

1. Present data only: Show the ranking in a clear table (livestream title, creator handle, revenue, views, duration, unit price, start/end times) and the detail as one grouped profile, without subjective business advice.
2. Ranking order: The default order is revenue (GMV) descending; there is no explicit rank field — position is implied by order. Preserve it unless the user explicitly requests a supported sortField.
3. Currency awareness: Display the requested currency alongside revenue/unit_price (rank) or revenue/gpm (detail).
4. Money as strings on RANK: RANK revenue and unit_price are returned as strings (e.g. "185590.52") — parse them before numeric comparison or formatting. DETAIL revenue is a number. Use the exact field name when extracting with jq / ConvertFrom-Json.
5. Viewers vs views: Use views for ranking rows and viewers for detail rows — do not mix them.
6. GPM: gpm is GMV per mille (detail-only) — present with appropriate precision (e.g. 903.79), not as a percentage.
7. Time fields: livestream_start_time/livestream_end_time are epoch milliseconds; livestream_duration is seconds. Format human-readable local times when displaying.
8. Time window: Always label which dateRange the data covers (e.g. "last 7 days").
9. Pagination hint: The ranking response has no total/page count; if a full page is returned, suggest the user can request the next page (up to pageNumber 5).
10. Single entity: The detail is one livestream — do not present it as a ranking or leaderboard.

重要限制

• 排行榜不是关键词搜索：它会浏览按地区／时间筛选的直播排行榜；不会按关键词搜索直播。
• 详情查询需要 livestreamId：无法仅凭标题查找直播。请从排行榜的 livestream_id 字段获取 livestreamId。
• 最多 5 页，每页 5-100 条：pageNumber 限定为 1-5；超出范围时会返回 errcode 501, errmsg "page_number 范围为 1-5，当前: <n>"。pageSize 必须介于 5 和 100 之间。
• 不提供总数／页数：两个接口的响应都不包含 total 或页数相关字段；请继续翻页查询排行榜，直到某页返回的条目数少于 pageSize。
• 不同接口的字段名称／类型不同：DETAIL 使用 viewers（RANK 使用 views）；DETAIL 的 revenue 是数字（RANK 的 revenue 是字符串）；DETAIL 有 gpm，但没有 unit_price（RANK 有 unit_price，但没有 gpm）。请勿假设字段名称／类型可以通用。
• 数据延迟：两个接口都可能存在统计延迟（T+1）。
• 上游暂时性错误：网关偶尔可能返回 errcode 501, errmsg "调用 Kalodata 接口失败: Kalodata API HTTP 554: "（Kalodata API 上游暂时性错误）。请使用相同参数重试一次或两次；不要更改参数。
• 不支持的排序／筛选：如果网关不接受所请求的 sortField，请勿尝试变通；告知用户，并退回默认排行榜顺序。
• 非直播实体请使用对应的 Kalodata 技能：创作者／商品／视频／店铺排行榜或详情。

用户表达与场景速查

适用——TikTok 直播排行榜或直播详情查询：

用户表达	场景
"TikTok直播排行榜", "TikTok直播排行"	直播排行榜查询
"TikTok热销直播", "top TikTok livestreams"	按地区筛选的直播排行榜
"近7天TikTok直播榜", "美国TikTok直播排名"	按时间范围／地区筛选的排行榜
"Kalodata直播榜"	直接指定数据源
"TikTok直播详情", "TikTok直播数据"	单场直播详情查询
"这场直播的观看人数", "这场直播卖了多少钱"	查询特定直播的观看人数／收入／GPM
"TikTok livestream detail", "kalodata livestream search/detail"	直接获取详情／排行榜数据

不适用——需求超出 TikTok 直播范围：

• TikTok 创作者／商品／视频／店铺排行榜或详情（请使用对应的 Kalodata 技能）
• 未知 livestreamId 的直播详情（请先通过排行榜接口获取 ID）
• Amazon／Shopify／1688／其他平台的直播数据
• TikTok 广告活动管理或内容创作

边界判断：当用户在 TikTok Shop／TikTok 电商语境中提到“直播榜”或“直播排行”时，请使用排行榜接口。当用户询问某场特定直播的详细指标（收入、观看人数、时长、GPM），且已有 livestreamId（或可从排行榜中获取）时，请使用详情接口。

算力消耗规则

每次调用消耗 7.0 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

在以下任一情况出现时，通过 Feedback API 自动检测并提交反馈：

1. 本技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户表达对本技能的不满或赞赏
4. 你认为有任何可改进之处

请按照 references/api.md 中的说明调用反馈 API。不要打断用户的操作流程。

---

如需了解更多优质、专业的跨境电商技能，请访问 LinkFox Skills。