SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场linkfox-echotik-batch-product-detail

linkfox-echotik-batch-product-detail

营销与增长

查看项目

更新于 10-15 09:29

技能介绍

用途

本技能面向 TikTok Shop 卖家与运营人员，用于对一批已知商品做并排对比。当用户需要查看若干 TikTok 商品的销量、GMV、直播、视频与达人表现时，可通过商品 ID 或商品链接批量获取详情指标，从而比较候选商品的表现差异。

需要注意的是，这是针对已知商品的详情查询工具：使用前用户应已持有具体的商品 ID 或 TikTok Shop 商品链接。若要按关键词或品类发现商品，或查看新品/热品榜单，应改用对应的搜索类与榜单类技能。

主要能力

批量查询：单次调用最多可处理 1000 个 TikTok Shop 商品。商品可通过 ID、可通过 TikTok Shop 商品链接，或两者组合来指定；后端会从每个链接中提取 productId，并与用户提交的 ID 合并，然后返回逐个商品的分析数据。

多周期指标：销量、GMV、直播场次、视频数、达人数量与播放量均按 1 天、7 天、15 天、30 天、60 天、90 天窗口以及累计总量分别给出，便于同时读取近期动能与长期总量。

价格信息：最低价（minPrice）、最高价（maxPrice）与 SPU 均价（spuAvgPrice）均为美元（USD）计价值。

状态标记（整数值）：

  • salesTrendFlag：0 稳定、1 上升、2 下降
  • isSShop：是否全托管店铺
  • offMark：是否下架
  • freeShipping：是否包邮

对比辅助：返回的商品名称、价格、总销量、30 天销量、总 GMV、评分、评论数、佣金比例与带货达人数等，可用于生成并排对比表。

参数说明

参数 类型 必填 说明 默认
productIds array<string> 否* TikTok 商品 ID（最多 1000 项） -
productUrls array<string> 否* TikTok Shop 商品链接，会从中提取 productId 并与 productIds 合并（最多 1000 项） -

* productIds 与 productUrls 至少需提供其一，也可以同时传入。

使用方式

API 端点：POST /echotik/batchProductDetail（完整参数、响应与错误码见 references/api.md）。

Python 脚本：python scripts/echotik_batch_product_detail.py '<JSON 参数>' [--inline]

算力与成本约束：该工具会消耗算力（单次消耗 5 算力，用户会因此支付费用）。同一会话中相同参数组合默认只调用一次，脚本带 24 小时本地缓存。在失败或返回空结果时，不应自动更换关键词、翻页或修改邮编连续试探；如需继续检索，应先向用户说明会产生额外消耗。高频调用或用户对算力消耗预期不足时，应提醒用户并由其决定是否继续。

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

  • 始终将完整响应写入 <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/套餐到期/需充值/请充值”或类似含义内容

调用示例

按商品 ID 批量查询：

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

按商品链接批量查询：

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

ID 与链接混用（服务端合并）：

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

展示规则

  • 以对比表呈现：每个商品一行，关键列包括名称、价格（USD）、总销量、30 天销量、总 GMV、评分、评论数、佣金比例与带货达人数
  • 多周期上下文：比较动能时，应同时给出相关窗口（如 7 天/30 天）与累计总量，而非只给总量
  • 货币：价格均为美元，需标注为 USD
  • 佣金格式：productCommissionRate 以百分比展示（如 0.05 → “5%”）
  • 趋势标记：将 salesTrendFlag 渲染为稳定/上升/下降，便于快速浏览
  • 状态徽标：对 isSShop（全托管）、offMark（下架）与 freeShipping 加以标注，避免用户在不知情的情况下对比已下架商品
  • 图片引用：若存在 imageUrl / productImageUrls，说明有图片可用
  • 长描述：descDetail 可能为较长的 HTML/文本，应做摘要或说明其可获取，而非原样倾倒
  • 缺失商品处理：若请求的某商品无记录，列出哪些 ID/链接没有数据，便于用户核对
  • 错误处理：查询失败时，依据 errmsg/error 字段说明原因，并建议检查 ID/链接

适用场景

  • “查一下这些 TikTok 商品的详情”——按商品 ID 批量查详情
  • “拉一下这些 TikTok 链接的销售数据”——按商品链接批量查详情
  • “对比这些 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 链接（使用本技能），还是想按关键词/品类找商品（使用搜索技能）。若用户粘贴了一串 ID/链接并想要销量/GMV/直播数据，本技能适用；若用户问“在 TikTok 上该卖什么”或“找热门商品”，则不适用。

限制

  • 批量上限：单次最多 1000 个商品
  • 计价货币：所有价格字段均为美元
  • 估算数据：销量、GMV 与归因数据为分析估算值，并非平台精确数据
  • 仅限查询：本工具不支持按关键词或品类搜索，只能解析用户已持有的具体 ID/链接

反馈

在以下情形应通过 Feedback API 自动检测并上报反馈（不打断用户流程，调用方式见 references/api.md）：

  • 技能描述的功能或目的与实际行为不符
  • 技能结果与用户意图不符
  • 用户对本技能表达不满或赞赏
  • 任何你认为可以改进的地方