linkfox-etsy-product-detail

Etsy 商品详情查询

通过 Etsy 商品直达 URL 获取单个商品当前公开详情，用于商品信息研究和竞品页面审查。

核心概念

• 必须提供商品直达 URL：使用 Etsy HTTPS URL，路径为 /listing/<numeric-id> 或 /listing/<numeric-id>/<one-slug-segment>，可带可选的尾部斜杠和查询字符串。
• 每次调用查询一个商品：这是详情查询，不是 Etsy 关键词搜索或批量筛选。
• 结构化公开页面数据：响应按商品、价格、媒体、店铺、配送和评价摘要字段分组。
• 当前快照：值反映查询时公开商品页面展示的信息，可能缺失或不一致。

数据字段

字段	说明
productId / productUrl	Etsy 商品 ID 和规范/商品 URL
title / description	商品标题和描述部分
image / images	主图和完整图片列表
price / lowPrice / highPrice / oldPrice	当前价格、价格区间和之前的价格字符串（如有）
currency	返回的货币代码
maxQuantity / variants	报告的最大数量和变体选项
category	Etsy 类目路径
countryShippingFrom	发货国家/地区
deliveryDaysMin / deliveryDaysMax	预计配送时长范围；可能为 null 或省略
shopId / shopName / shopUrl / shopSales	店铺身份信息和公开销量数据
reviews / star / shopReviews	商品评价数、评分和店铺评价数
highlightsTags / reviewsTags	买家反馈亮点和标签频次
reviewsScores	动态评价评分细分；键因商品而异
yearsOnEtsy	店铺公开经营年限
hasRatingsBadge / hasConvosBadge / hasShippingBadge	店铺/商品公开徽章标记
moreLikeUrl / searchPosition	相关链接或来源位置字段（如有）

该工具返回汇总评价信号，不返回单条评价记录。

参数指南

参数	必填	默认值	说明
productUrl	是	-	Etsy 公开 HTTPS 商品页面 URL，域名为 etsy.com 或其子域名，不含嵌入式凭据，使用默认 HTTPS 端口；路径为 /listing/<numeric-id>，最多带一个 slug 段，可带可选的尾部斜杠/查询字符串

搜索页面、店铺页面、非 Etsy 主机，以及不含数字商品 ID 的商品 URL 均为无效输入。

调用方式

• API 端点：POST /etsy/product/detail（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/etsy_product_detail.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-etsy-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/套餐到期/需充值/请充值”或类似含义。

使用示例

python scripts/etsy_product_detail.py '{"productUrl":"https://www.etsy.com/listing/1710567856/its-okay-to-make-some-mistakes-shirt"}'

展示规则

1. 首先展示标题、商品刊登 ID、店铺名称、类别、价格范围和货币。
2. 内嵌展示主图，并提供其余图片的数量，默认不渲染所有图片。
3. 仅在返回变体和数量时展示；变体列表为空也是有效结果。
4. 区分商品刊登评论和店铺评论，并将买家反馈标签标注为汇总信号。
5. 仅当两个来源值都有意义时才展示配送预估；保留 null 值并将其视为不可用。
6. 除非用户明确要求，否则不要规范化或转换价格字符串。
7. 将缺失、为空或不合理的店铺字段视为提取不确定性；不要默默修正。
8. 对较长的描述和图片数组先进行概述，并根据需要从保存的 JSON 中提取准确内容。

重要限制

1. Etsy 公开页面结构的变化可能导致字段缺失、为空或偶尔被误识别。
2. 并非每个商品刊登都会提供 star、价格字段、配送预估、店铺元数据和徽章。
3. 响应包含评论数量、标签和汇总评分，但不包含买家的个人评论。
4. 此工具不提供历史价格、Etsy 关键词排名或有保证的销售预估。
5. 此工具不会搜索 Etsy；用户需要按关键词或多个筛选条件查找时，请使用 Etsy 商品查询技能。

用户表达与场景速查

适用 — 一个已知的 Etsy 商品刊登 URL：

用户说	场景
“查这个 Etsy 商品链接的详情”	商品刊登详情查询
“提取这个 Etsy Listing 的标题、描述和图片”	商品刊登内容提取
“看看它的价格区间、变体和发货信息”	商品报价与配送审核
“这个 Etsy 商品的店铺和评论概况如何？”	店铺与评论概况查询

不适用：

• Etsy 关键词搜索、类别发现或多商品筛选
• 不带特定商品刊登 URL 的 Etsy 店铺搜索或排名查询
• 获取个人评论，或基于完整评论文本进行情感分析
• 商品刊登创建、编辑、订单管理或其他卖家账户操作

算力消耗规则

消耗 6 算力。

用户会因算力消耗而支付费用。重复查询其他 Listing 会分别计费；继续调用前应让用户知晓额外消耗。

反馈：

当所述能力与实际行为不符、结果未满足用户意图、用户表达赞扬或不满，或技能可以改进时，通过 Feedback API 自动检测并报告反馈。遵循 references/api.md，不要打断用户的操作流程。

---

如需了解更多高质量、专业的跨境电商技能，请访问 LinkFox Skills。