linkfox-etsy-product-query

按关键词或商品 URL 搜索 Etsy 商品,并按价格、销量、收藏、评论、上架时间、类目、发货国家、手工或复古等商品类型和 Pick、Bestsell、Raving 标签筛选。适用于 Etsy 选品、爆款发现、商品价格与销售表现比较;即使未提及工具名,只要用户希望在 Etsy 上搜商品或筛品,也可使用。不适用于店铺查询、单品完整详情或店铺商品维护。

SKILL.md

GitHub

Etsy 商品查询

适用范围

适用

搜索和筛选 Etsy 商品,比较商品的价格、销量、收藏、评论及标签表现。

场景速查

用户表达 查询场景
找 Etsy 上的海报或查这个商品链接 按关键词或商品 URL 查询。
找这个价格区间内的畅销商品 结合价格、总销量与周销量筛选。
找最近上架、收藏增长快的手工商品 结合上架时间、商品类型和周新增收藏筛选。
看这个类目有哪些 Pick 或畅销商品 按类目与 Pick、Bestsell、Raving 标签筛选。

前置条件

先确定用户的查询目标和筛选条件;关键词或商品链接 searchKey 为可选项,也可仅按价格、销量、商品类型等条件筛品。按类目查询时,如用户只有类目名称,先从可用的类目数据源取得类目编号。

查询流程

  1. 确认搜索目标和筛选条件,按需取得类目编号;参数定义与限制见 接口说明。
  2. 根据预期返回商品数估算本次算力,说明可能一次性产生较大消耗,由用户决定是否继续。
  3. 执行一次查询,优先复用相同条件下的本地缓存;先查看摘要,再从已保存的完整响应提取所需商品信息。
  4. 展示本页商品及匹配总量;需要翻页或调整条件时,先说明额外算力消耗,再按用户确定的范围继续。

执行方式

  • 直接调用接口:接口端点、完整参数、响应和错误码见 references/api.md。
  • 脚本调用(推荐):python scripts/etsy_product_query.py '<JSON 参数>' [--inline]。
  • 成本约束:本工具按本页实际返回商品数 × 1.8 消耗算力。同一会话、同一参数组合默认只调用一次,脚本提供 24 小时本地缓存。失败或空结果时,不得自动更换关键词、翻页或修改筛选条件连续试探;需要继续检索时,先向用户说明额外消耗。

输出策略

  • 始终保存完整响应,目标路径为 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-etsy-product-query-<timestamp>.json。<cwd> 为脚本运行时的工作目录,<session> 优先取环境变量 SESSION_ID,用于聚合同一任务的数据。禁止写入 /tmp,当前目录不可写时应报错。
  • 序列化后的响应按 UTF-8 编码不超过 8,000 字节:保存后,将完整 JSON 打印到标准输出。
  • 序列化后的响应按 UTF-8 编码超过 8,000 字节:保存后,标准输出仅展示摘要,包括顶层字段、常见计数(如 total、costToken)、最大列表字段的长度和前 3 条样本。
  • 添加 --inline 可强制全量打印到标准输出,同时仍保存文件。

先通过摘要判断数据是否足够。需要具体字段时,优先使用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需提取,避免将整份响应载入上下文。

执行规则

算力消耗预估

消耗算力 = 本页返回商品数 × 1.8。翻页是新的请求,按下一页实际返回条数重新计费。例如返回 20 条约消耗 36 算力,返回 100 条约消耗 180 算力;实际结果可能少于请求条数。

重要:本技能的服务按倍数动态计算,可能一次性消耗大量算力,必须提醒用户,由用户决定是否继续。

声明:算力消耗以实际扣除为准;如因需要调整算力消耗标准,恕不另行通知。最终解释权归 LinkFox 官方所有。

用户会因算力消耗而支付费用。需要高频调用或用户对消耗量预期不足时,提醒用户,并由用户决定是否继续。

解决认证和算力问题

出现以下情况时,按 references/onboarding.md 的指引处理:

  • 未配置接口密钥:LINKFOX_AGENT_API_KEY 和 LINKFOXAGENT_API_KEY 均为空。
  • 响应状态码为 401 或 402。
  • 响应提示算力或余额不足、计费不足、配额超限、套餐到期或需要充值。英文错误消息也按其含义判断。

约束与建议

  • 区分本页与总体:total 是本页返回条数,productNum 是符合条件的商品总数,不能混用。
  • 区分累计与增长:总销量、周销量、收藏数及周新增收藏、评论数及周新增评论分别展示,保留其统计含义。
  • 清晰展示商品:用表格展示标题、商品链接、价格与币种、总销量、周销量、收藏、评论、店铺、发货国家和可用标签;仅展示实际返回的数据,不补造缺失值。
  • 解释筛选与空结果:价格区间、商品类型、排序编码和其他参数的约定以接口说明为准;空结果不等于请求失败,先展示已返回的信息,不自动扩大检索范围。
  • 保留完整响应:缓存与输出的运行约定见 接口说明,先读本地文件,避免重复付费查询。

使用示例

按关键词查商品

用户:帮我找 Etsy 上的 poster。

确认关键词和筛选目标,告知预计消耗并由用户决定是否继续,再查询并展示本页商品、匹配总量及可用指标。

按多维条件筛品

用户:找美国发货、价格适中、周销量较好的手工商品。

确认价格与销量范围,结合发货国家和商品类型筛选,解释本页返回范围;继续检索前说明额外消耗。

使用反馈

当技能有BUG,或技能描述有错误/疏漏/歧义/表述模糊,或技能结果与用户预期不符,或用户表达不满/赞扬,或发现其他可改进之处时,按 references/api.md#Feedback 的指引反馈,不要打断用户当前流程。


更多优质、专业的跨境电商技能,请访问 LinkFox Skill。