linkfox-kalodata-tiktok-product

Kalodata - TikTok 商品搜索与详情

此技能通过 Kalodata 数据源支持两步 TikTok Shop 商品工作流：

1. 浏览 TikTok Shop 商品排行榜，发现排名靠前和热销商品。
2. 通过 productId 获取单个商品的完整详情。

当用户想查看畅销商品排名、热门商品或发现商品时，使用排名接口。当用户已提供 productId，或已从排名结果中选定商品时，使用详情接口。

核心概念

商品排名接口返回一个分页排行榜，可按 region、dateRange、currency、language 和可选的 sortField 筛选。每行商品包含标识、价格、销量、收入（按视频、直播和橱窗渠道细分）、收入增长率、佣金率和上架日期。结果使用 pageNumber（1-5）和 pageSize（5-100）分页。

商品详情接口通过 productId 获取一个 TikTok Shop 商品的信息。返回商品价格范围、销量、收入（按渠道细分）、佣金率、上架日期、评价数量、类别层级、所属店铺，以及相关视频／直播／创作者数量。productId 通常来自排名响应中的 product_id 字段。

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

数据字段

排名行包含：

字段	描述
product_id	商品唯一 ID；查询详情时将其作为 productId 传入
product_name	商品标题
unit_price	单价（货币取决于地区，例如美国地区使用 USD）
sales_volumn	销量（字段拼写为 volumn）
revenue	总收入／GMV；等于视频、直播和橱窗收入之和
video_revenue	视频渠道收入
live_revenue	直播渠道收入
showcase_revenue	橱窗渠道收入
revenue_growth_rate	收入增长率（%）
commission_rate	佣金率，以百分比数值表示（25.0 = 25%）
launch_date	商品上架日期（YYYY-MM-DD）

详情行还包含：

字段	描述
product_region	商品市场地区（例如 us）
product_shop_id	商品所属店铺的 ID
pri_cate_id / sec_cate_id / ter_cate_id	一级／二级／三级类别 ID
min_price / max_price	请求货币下的最低／最高价格
product_review_count	商品评价数量
delivery_type	配送类型（例如 local）
video_number / live_number / creator_number	相关视频／直播／创作者数量
shopping_mall_revenue	商城渠道收入

详情中的收入渠道细分：revenue = video_revenue + live_revenue + shopping_mall_revenue。

参数指南

商品排名（/kalodata/product/rank）

参数	类型	必填	描述
region	string	否	TikTok Shop 市场区域代码，例如 US。未指定时默认为 US
dateRange	string	否	相对时间范围，例如 last7Day、last30Day
currency	string	否	货币指标使用的币种，例如 USD
language	string	否	响应语言，例如 zh-CN、en-US
category_ids	array	否	类别 ID 列表筛选条件
shop_id	string	否	店铺 ID 筛选条件
creator_id	string	否	创作者 ID 筛选条件
video_id	string	否	返回与指定视频相关的商品
livestream_id	string	否	返回与指定直播相关的商品
revenue_range	string	否	营收 / GMV 范围筛选条件
is_affiliate	string	否	联盟筛选条件：PUBLIC_PLAN 或 NON_AFFILIATE
commission_rate	number	否	联盟佣金率，例如 0.15
is_tts_product	integer	否	全托管商品筛选条件：1 或 0
unit_price_range	string	否	商品单价范围筛选条件
sortField	object	否	排序规则；省略时使用默认排名
pageNumber	integer	否	页码，1-5
pageSize	integer	否	每页条数，5-100

商品详情（/kalodata/product/detail）

参数	类型	必填	描述
productId	string	是	排名字段 product_id 中的 TikTok 商品 ID（使用字符串以保留精度）
region	string	否	市场区域代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	货币指标使用的币种，例如 USD

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-product-<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/套餐到期/需充值/请充值”，或类似含义的内容。

使用示例

1. 浏览美国 TikTok 热门商品（最近 7 天）

{"region":"US","dateRange":"last7Day","pageSize":20,"pageNumber":1,"currency":"USD"}

2. 获取某个商品的详情

{"productId":"1729508370969629931","region":"US","dateRange":"last7Day","currency":"USD"}

3. 从发现到详情的工作流

Run kalodata_product_search.py first, choose a row's product_id, then pass that value as productId to kalodata_product_detail.py.

展示规则

1. 将排名结果以表格形式呈现，包含产品名称、产品 ID、价格、销量、营收（按渠道拆分）、增长率、佣金率和上架日期。
2. 将详情结果呈现为一个分组档案：身份信息、价格范围、销量、营收（按渠道拆分）、佣金、类别层级、所属店铺，以及关联的视频／直播／创作者数量。
3. 展示货币指标时，始终标注 dateRange、region 和 currency。
4. 使用准确的字段名 sales_volumn。
5. commission_rate 是直接百分比（25.0 = 25%），不是基点——请加上 % 符号显示。
6. revenue_growth_rate 是百分比——请加上 % 符号显示。
7. 营收渠道拆分：排名中的 revenue = video_revenue + live_revenue + showcase_revenue；详情中的 revenue = video_revenue + live_revenue + shopping_mall_revenue。适用时呈现拆分数据。
8. 保持排名顺序，除非用户明确要求使用受支持的 sortField。

重要限制

• 排名不是关键词搜索；它会按地区和时间范围浏览排行榜。
• 详情查询需要 productId；无法仅凭名称查找产品。请先从排名的 product_id 获取 productId。
• 排名响应不包含 total 或页数；结果数量为 data.length。
• pageNumber 限定为 1-5，pageSize 限定为 5-100。
• 有效但无结果的请求（例如不受支持的 region）可能返回 errcode 200，没有 data 字段，且仍会计费。
• 上游临时错误可能以 errcode 501 和 Kalodata HTTP 5xx 消息的形式出现（例如 522/554）。请使用相同参数重试一到两次；不要自动更改参数。
• 对于非产品类实体，请使用匹配的 Kalodata 视频／创作者／店铺／直播技能。

用户表达与场景快速参考

适用 -- TikTok 产品排名或产品详情查询：

用户说法	场景
“TikTok商品榜单”、“TikTok商品排行”	产品排名查询
“TikTok热销榜”、“TikTok爆品排行”、“TikTok选品榜单”	畅销／热门产品排名
“kalodata商品榜”、“kaloda排行”	直接引用数据来源
“TikTok商品详情”、“TikTok商品资料”	单个产品详情查询
“商品价格”、“商品销量”	产品价格／销量
“kalodata product rank/detail”、“product analytics”	直接引用产品详情

不适用 -- 需求超出 TikTok 产品范围：

• TikTok 视频／创作者／店铺／直播排名或详情
• 基于关键词的产品搜索
• Amazon／Shopify／1688 产品研究（请使用平台专属技能）
• TikTok 广告／广告活动管理或内容创作

算力消耗规则

每次调用消耗 7.0 算力。

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

反馈：

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

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

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

---

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