linkfox-etsy-store-query

按销量、收藏、评论、开店时间、国家、主营类目、Raving 和星标等条件筛选 Etsy 店铺,查看总量与周增量、商品数量、评分和店铺链接。适用于 Etsy 店铺查询、卖家发现、店铺排行和表现对比;用户未提及工具名但希望在 Etsy 找店或筛选店铺时也适用。不适用于商品搜索、单个商品详情或店铺运营写入。

SKILL.md

GitHub

Etsy 店铺查询

适用范围

适用

在 Etsy 上按关键词、店铺名称、店铺链接或多维条件发现店铺,并比较店铺表现。

场景速查

用户表达 查询场景
帮我找卖陶瓷的 Etsy 店铺 店铺发现:结合关键词、国家和主营类目筛选。
看 Etsy 周销量高的店铺 店铺排行:按周销量排序并展示总销量与周销量。
查这个店铺的收藏和评论增长 店铺表现:查看累计数和周新增指标。
找新开的星标或 Raving 店铺 特征筛选:结合开店时间和店铺标记。

前置条件

先明确用户希望查找的店铺特征、排序目标与查询范围。完整参数及限制见 references/api.md。

查询流程

  1. 将用户的关键词、店铺名称或链接及筛选意图整理为查询条件,按接口定义核对区间、排序和分页规则。
  2. 先说明按返回店铺数动态计费的预估,由用户决定是否继续;在已确定的范围内调用查询脚本。
  3. 根据保存的完整响应展示店铺数据,区分本页条数与符合条件的总数。需要继续查询时,按成本约束说明额外消耗。

执行方式

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

输出策略

  • 完整响应写入 <linkfox-root>/<YYYY-MM-DD>/<session>/data/linkfox-etsy-store-query-<timestamp>.json。<linkfox-root> 按 ACPX_WORKSPACES 的第一个路径、当前工作目录、用户目录、系统临时目录的顺序选择可写位置下的 linkfox/;正常运行应选择可写的项目工作目录。<session> 优先取环境变量 SESSION_ID,未配置时生成进程内稳定标识,用于聚合同一任务的数据。响应文件写入失败时脚本向标准错误输出提示,仍继续输出响应;应检查实际保存路径和错误提示。
  • 响应体不超过 8 KB(8000 字节,按 UTF-8 编码计算):保存后,将完整 JSON 打印到标准输出。
  • 响应体超过 8 KB(8000 字节):保存后,标准输出仅展示摘要,包括顶层字段、常见计数(如 total、costToken)、最大列表字段的长度和前 3 条样本。
  • 添加 --inline 可强制全量打印到标准输出,同时仍保存文件。

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

执行规则

算力消耗预估

消耗算力 = 本页返回的店铺数 × 1.8。翻到下一页会重新请求,并按下一页返回条数另计;例如本页返回 20 家店铺,预估消耗 36 算力。

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

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

解决认证和算力问题

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

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

约束与建议

  • 清晰展示数据:以表格展示店铺名称、链接、国家、主营类目、总销量、周销量、收藏、周新增收藏、评论、周新增评论、商品数、评分与开店日期;仅展示实际返回的数据。
  • 区分本页与总量:total 是本页返回条数,storeNum 是符合条件的店铺总数。不要将本页店铺的销量或数量推断为整个市场规模。
  • 保留指标含义:累计销量与周销量、累计收藏与周新增收藏、累计评论与周新增评论分别展示;Raving 与星标是店铺标记,不代替评分。
  • 说明分页情况:告知本次返回范围;空结果先解释为当前条件下无匹配店铺,核对筛选条件,后续检索遵守成本约束。
  • 解释响应:依据接口参考的公共响应码规则及业务消息说明结果,保留完整错误信息,不假定根级 code 的成功取值。

使用示例

查找陶瓷店铺

用户:帮我找美国的 Etsy 陶瓷店铺,先看一页。

明确关键词、国家和查询范围,说明动态算力预估,再展示返回店铺的主营类目、销量、收藏、评论和链接。

对比近期店铺表现

用户:看看这些店铺最近的销量和收藏增长。

按用户指定的店铺及范围查询,用表格并列展示累计与周指标,标明缺失项和本次查询范围。

使用反馈

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


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