linkfox-etsy-store-query
按销量、收藏、评论、开店时间、国家、主营类目、Raving 和星标等条件筛选 Etsy 店铺,查看总量与周增量、商品数量、评分和店铺链接。适用于 Etsy 店铺查询、卖家发现、店铺排行和表现对比;用户未提及工具名但希望在 Etsy 找店或筛选店铺时也适用。不适用于商品搜索、单个商品详情或店铺运营写入。
SKILL.mdskills/linkfox-etsy-store-query/SKILL.md
GitHubEtsy 店铺查询
适用范围
适用
在 Etsy 上按关键词、店铺名称、店铺链接或多维条件发现店铺,并比较店铺表现。
场景速查
| 用户表达 | 查询场景 |
|---|---|
| 帮我找卖陶瓷的 Etsy 店铺 | 店铺发现:结合关键词、国家和主营类目筛选。 |
| 看 Etsy 周销量高的店铺 | 店铺排行:按周销量排序并展示总销量与周销量。 |
| 查这个店铺的收藏和评论增长 | 店铺表现:查看累计数和周新增指标。 |
| 找新开的星标或 Raving 店铺 | 特征筛选:结合开店时间和店铺标记。 |
前置条件
先明确用户希望查找的店铺特征、排序目标与查询范围。完整参数及限制见 references/api.md。
查询流程
- 将用户的关键词、店铺名称或链接及筛选意图整理为查询条件,按接口定义核对区间、排序和分页规则。
- 先说明按返回店铺数动态计费的预估,由用户决定是否继续;在已确定的范围内调用查询脚本。
- 根据保存的完整响应展示店铺数据,区分本页条数与符合条件的总数。需要继续查询时,按成本约束说明额外消耗。
执行方式
- 直接调用接口:接口端点、完整参数、响应和错误码见
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。