linkfox-etsy-product-query
按关键词或商品 URL 搜索 Etsy 商品,并按价格、销量、收藏、评论、上架时间、类目、发货国家、手工或复古等商品类型和 Pick、Bestsell、Raving 标签筛选。适用于 Etsy 选品、爆款发现、商品价格与销售表现比较;即使未提及工具名,只要用户希望在 Etsy 上搜商品或筛品,也可使用。不适用于店铺查询、单品完整详情或店铺商品维护。
SKILL.mdskills/linkfox-etsy-product-query/SKILL.md
GitHubEtsy 商品查询
适用范围
适用
搜索和筛选 Etsy 商品,比较商品的价格、销量、收藏、评论及标签表现。
场景速查
| 用户表达 | 查询场景 |
|---|---|
| 找 Etsy 上的海报或查这个商品链接 | 按关键词或商品 URL 查询。 |
| 找这个价格区间内的畅销商品 | 结合价格、总销量与周销量筛选。 |
| 找最近上架、收藏增长快的手工商品 | 结合上架时间、商品类型和周新增收藏筛选。 |
| 看这个类目有哪些 Pick 或畅销商品 | 按类目与 Pick、Bestsell、Raving 标签筛选。 |
前置条件
先确定用户的查询目标和筛选条件;关键词或商品链接 searchKey 为可选项,也可仅按价格、销量、商品类型等条件筛品。按类目查询时,如用户只有类目名称,先从可用的类目数据源取得类目编号。
查询流程
- 确认搜索目标和筛选条件,按需取得类目编号;参数定义与限制见 接口说明。
- 根据预期返回商品数估算本次算力,说明可能一次性产生较大消耗,由用户决定是否继续。
- 执行一次查询,优先复用相同条件下的本地缓存;先查看摘要,再从已保存的完整响应提取所需商品信息。
- 展示本页商品及匹配总量;需要翻页或调整条件时,先说明额外算力消耗,再按用户确定的范围继续。
执行方式
- 直接调用接口:接口端点、完整参数、响应和错误码见
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。