linkfox-echotik-batch-product-detail

EchoTik TikTok 批量商品详情

此技能将指导你如何获取一批 TikTok Shop 商品的详细表现指标，帮助卖家和运营人员通过销售额、GMV、直播、视频和达人数据并排比较候选商品。

核心概念

此工具可在单次调用中获取最多 1000 个 TikTok Shop 商品的完整详细指标。你可以通过商品 ID 和/或 TikTok Shop 商品 URL 指定商品；后端会从每个 URL 中提取 productId，并与您提供的 ID 合并，然后返回每件商品的分析数据。

输入选项（至少需要一个；也可同时使用）：

• productIds — TikTok 商品 ID 数组
• productUrls — TikTok Shop 商品 URL 数组（例如 https://shop.tiktok.com/us/pdp/<slug>/<productId>?...）；系统会从每个 URL 中提取末尾的 productId

多时间段指标：销售额、GMV、直播数量、视频数量、达人数量和观看次数分别按 1d / 7d / 15d / 30d / 60d / 90d 时间段及累计总量报告，因此你可以同时查看近期势头和长期总量。

价格以 USD 计：minPrice、maxPrice 和 spuAvgPrice 的值均以 USD 计。

状态标记（整数）：salesTrendFlag — 0=稳定，1=上升，2=下降；isSShop — 全托管店铺；offMark — 已下架；freeShipping — 免运费。

与搜索的区别：此工具用于查询已知商品的详细信息（你已经有商品 ID/URL）。如需通过关键词发现商品，请使用 linkfox-echotik-product-search；如需查看新品排行榜，请使用 linkfox-echotik-new-product-rank。

参数指南

参数	类型	必填	描述	默认值
productIds	array<string>	否*	TikTok 商品 ID（最多 1000 项）	-
productUrls	array<string>	否*	TikTok Shop 商品 URL；系统会从每个 URL 中提取 productId，并与 productIds 合并（最多 1000 项）	-

* 必须提供 productIds / productUrls 中的至少一项；两者可以同时传入。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-batch-product-detail-<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. 按商品 ID 批量查询

{
  "productIds": ["1729382310407603945", "1729382310407603946"]
}

2. 按商品 URL 批量查询

{
  "productUrls": [
    "https://shop.tiktok.com/us/pdp/phone-case/1729382310407603945",
    "https://shop.tiktok.com/us/pdp/case-for-phone/1729382310407603946"
  ]
}

3. 混合使用 ID 和 URL（由服务端合并）

{
  "productIds": ["1729382310407603945"],
  "productUrls": ["https://shop.tiktok.com/us/pdp/phone-case/1729382310407603946"]
}

展示规则

1. 展示对比表：每个产品占一行，包含关键列——名称、价格（USD）、总销量、近 30 天销量、总 GMV、评分、评价数、佣金率和推广该产品的达人数量
2. 多周期背景：比较趋势时，同时展示相关时间范围（例如 7 天／30 天）和累计总量，而不是只展示总量
3. 货币：价格以 USD 计价；请标明 USD
4. 佣金格式：将 productCommissionRate 显示为百分比（例如，0.05 → “5%”）
5. 趋势标记：将 salesTrendFlag 显示为稳定／上升／下降，便于快速查看
6. 状态徽标：在相关情况下标记 isSShop（全托管）、offMark（已下架）和 freeShipping，避免用户在不知情的情况下比较已下架产品
7. 图片引用：如果存在 imageUrl / productImageUrls，请说明有图片可用
8. 长描述：descDetail 可能包含很长的 HTML／文本内容——请概述或注明其可用，而不是直接完整输出
9. 产品缺失处理：如果查询的产品没有返回记录，请列出无数据的 ID／URL，方便用户核实
10. 错误处理：查询失败时，说明 errmsg／error 字段中的原因，并建议检查 ID／URL

重要限制

• 批次上限：每次请求最多查询 1000 个产品
• 定价货币：所有价格字段均以 USD 计价
• 估算数据：销量、GMV 和归因数据均为分析估算值，并非平台精确数据
• 仅支持查找：此工具不能按关键词或类别搜索——只能查询已有的特定 ID／URL

用户表达与场景快速参考

适用场景

用户说	场景
“查询这些 TikTok 产品的详情”	按产品 ID 批量查询详情
“获取这些 TikTok 链接的销售数据”	按产品 URL 批量查询详情
“比较这些 TikTok 产品的 GMV”	批量查询并展示 GMV 列
“这些 TikTok 产品中，哪些趋势正在上升？”	批量查询并读取 salesTrendFlag
“这些 TikTok 产品中有下架／全托管的吗？”	批量查询并读取 offMark / isSShop
“获取这些 TikTok 产品的直播销售数据”	批量查询并展示直播销量／GMV

不适用场景

• 按关键词发现产品（请使用 linkfox-echotik-product-search）
• 新品／热门产品排行榜（请使用 linkfox-echotik-new-product-rank）
• 与产品关联的推广视频（请使用 linkfox-echotik-product-video）
• 获取 TikTok 视频下载链接（请使用 linkfox-echotik-get-video-download-url）
• TikTok 创作者／达人资料分析
• 非 TikTok 平台的产品数据

边界判断

当用户说“分析这些 TikTok 产品”时，请确认他们是否已有特定产品 ID 或 TikTok Shop URL（适用此技能），还是想按关键词／类别查找产品（适用搜索技能）。如果他们粘贴了一组 ID／URL，并希望获取销量／GMV／直播详情，则适用此技能。如果他们询问“在 TikTok 上卖什么好”或“查找热门产品”，则不适用。

算力消耗规则

消耗 5 算力。

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

反馈：

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

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

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

---

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