linkfox-kalodata-tiktok-shop

Kalodata - TikTok Shop 搜索与详情

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

1. 浏览 TikTok Shop 店铺排行榜，发现表现出色的店铺。
2. 通过 shopId 获取一家店铺的完整详情。

当用户需要查看排名、发现店铺或比较店铺时，使用搜索（排名）端点。当用户已有 shopId，或已从排名结果中选定一家店铺时，使用详情端点。

核心概念

店铺排名端点会返回分页排行榜，可按 region、dateRange、language 和 currency 筛选。默认按 revenue（GMV）降序排列，每行都带有明确的 rank 排名。每家店铺的信息包括身份、规模、收入渠道拆分和增长情况。

店铺详情端点通过 shopId 获取一家店铺的信息。返回内容包括店铺身份、规模、收入渠道拆分，以及创作者、视频和直播数量。shopId 通常来自排名响应字段 shop_id。

⚠️ 店铺 RANK 和店铺 DETAIL 端点的字段名称有所不同。 详情端点使用 self_account_revenue（排名端点使用 self_promotion_revenue）、不带内部下划线的 shoppingmall_revenue（排名端点使用 shopping_mall_revenue），以及 seller_type（排名端点使用 shop_type）。详情端点会返回 creator_number/video_number/live_number/product_number（排名端点不返回），且不会返回 rank/revenue_growth_rate/on_sell_product_count。务必使用各端点对应的准确字段名称。

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

数据字段

排名行包括：

字段	说明
rank	排名位置（1 = 收入最高）
shop_name	店铺显示名称
shop_id	店铺唯一 ID；查询详情时将此值传入 shopId
shop_type	店铺类型（例如 BRAND）
revenue	按所请求币种计算的 GMV 总额
sales_volumn	销量；字段拼写为 volumn
on_sell_product_count	当前在售商品数量
unit_price	按所请求币种计算的平均单价
revenue_growth_rate	收入增长率（%），可能为负数
self_promotion_revenue	自营收入（店铺自营/自播自推）
affiliate_revenue	达人分销收入
shopping_mall_revenue	商城收入

详情行包括：

字段	说明
shop_id	店铺唯一 ID（字符串，以保留精度）
shop_name	店铺显示名称
seller_type	卖家/店铺类型（例如 BRAND）——注意：是 seller_type，不是 shop_type
region	市场区域（例如 US）
revenue	按所请求币种计算的收入总额 / GMV
sales_volumn	销量；字段拼写为 volumn
product_number	在售商品数量
unit_price	按所请求币种计算的平均单价
self_account_revenue	自营账户收入（店铺自营/自播自推）——注意：是 self_account_revenue，不是 self_promotion_revenue
affiliate_revenue	达人分销收入
shoppingmall_revenue	商城收入——注意：shopping 和 mall 之间没有下划线
creator_number	与店铺合作的创作者数量（达人合作数）
video_number	相关视频数量
live_number	相关直播数量

收入渠道拆分：排名端点中，revenue = self_promotion_revenue + affiliate_revenue + shopping_mall_revenue；详情端点中，revenue ≈ self_account_revenue + affiliate_revenue + shoppingmall_revenue。各组成项可能会独立于 revenue 进行舍入（例如，详情端点的 shoppingmall_revenue 为 10431.0，而排名端点为 10431.39），因此应将拆分值视为近似值，而非严格相等。

参数指南

店铺排名（/kalodata/shop/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_ids	array	否	类别 ID 列表筛选条件
revenue_range	string	否	收入 / GMV 范围筛选条件
shop_type	string	否	店铺类型筛选条件：BRAND 或 RETAILER
sortField	object	否	排序设置；传入 {} 可使用默认收入排名

店铺详情（/kalodata/shop/detail）

参数	类型	必填	描述
shopId	string	是	排名字段 shop_id 中的店铺唯一 ID
category_id	string	否	可选的类别 ID 维度
region	string	否	市场区域代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	货币指标使用的币种，例如 USD

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-shop-<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. 美国过去 7 天内排名靠前的 TikTok 店铺

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

2. 获取某家店铺的详情

{"shopId":"7495514739648989419","region":"US","dateRange":"last7Day","currency":"USD"}

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

Run kalodata_shop_search.py first, choose a row's shop_id, then pass that value as shopId to kalodata_shop_detail.py.

展示规则

1. 将排名结果以表格呈现，包含排名、店铺名称、店铺类型、收入、销量、商品数量、单价和增长率。
2. 将详情结果作为一个分组档案呈现：身份信息、规模、收入渠道构成，以及创作者 / 视频 / 直播数量。
3. 展示指标时，始终标注 dateRange、region 和 currency。
4. 收入渠道拆分为近似值（见“数据字段”说明）；应将其作为构成拆分呈现，而非精确等式。
5. 使用确切字段名 sales_volumn。详情中使用 shoppingmall_revenue（无下划线）和 self_account_revenue；排名中使用 shopping_mall_revenue 和 self_promotion_revenue。不得混用两个端点的字段名。
6. 将 creator_number、video_number、live_number、product_number 显示为普通整数计数。
7. 除非用户明确要求使用受支持的 sortField，否则保留排名顺序。

重要限制

• 排名不是关键词搜索；它会按地区和时间范围浏览排行榜。
• 查询详情需要 shopId；仅凭店铺名称无法查找店铺。请从排名的 shop_id 字段或用户处获取 shopId。
• 排名响应不包含总数／页数；请持续翻页，直到某页返回的项目少于 pageSize。
• pageNumber 限制为 1-5，pageSize 限制为 5-100。
• 详情没有分页；单个店铺的 data 是一个包含 1 个元素的数组，且没有 total。
• 排名和详情端点的字段名称不同（见“数据字段”）——提取数据时请使用准确的字段名称。
• 上游的暂时性错误可能显示为 errcode 501，并附带 Kalodata HTTP 554 消息。请使用相同参数重试一两次；不要自动更改参数。
• 对于非店铺实体，请使用对应的 Kalodata 产品／视频／创作者／直播技能。

用户表达与场景快速参考

适用 —— TikTok Shop 店铺排名或单店详情：

用户表达	场景
"TikTok店铺排行榜", "TikTok小店排行"	查询店铺排名
"TikTok热销店铺", "top TikTok shops"	按地区查看店铺排行榜
"近7天TikTok店铺榜", "美国TikTok店铺排名"	按时间范围／地区筛选排名
"TikTok店铺详情", "TikTok小店资料"	查询单店详情
"店铺销售额", "店铺销量", "店铺达人合作数"	店铺营收／销量／创作者数量
"kalodata shop search/detail"	直接引用数据源

不适用 —— 需求超出 TikTok Shop 店铺范围：

• TikTok 创作者／产品／视频／直播排名或详情
• Amazon / Shopify / 1688 / 其他平台的店铺数据
• TikTok 广告活动管理或内容创作

算力消耗规则

每次调用消耗 7.0 算力。

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

反馈：

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

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

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

---

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