---
name: inspect-etsy-listing
description: 读取一个 Etsy 商品直链的公开详情，整理标题、描述、图片、价格区间、变体、配送、店铺与评论概况，支持竞品 Listing 拆解。不用于关键词搜索、逐条评论获取或卖家账户操作。
compatibility: Requires the oo CLI and access to OOMOL Marketplace LinkFox capabilities.
metadata:
  title: Etsy 商品详情
  icon: ':lucide:shopping-bag:'
  packageName: "@leina/inspect-etsy-listing"
  version: "0.1.0"
---
# Etsy 商品详情

## 固定使用内置市场

所有业务动作明确使用 `--connection-name marketplace_oomol`，不能省略，也不能替换为用户自建 LinkFox 连接。首次在当前账户/团队执行时，读取 `oo connector apps linkfox --json`，确认 `connectionName=marketplace_oomol`、`authType=marketplace` 且状态可用；用户指定团队时，连接列表和业务命令使用同一个 `--team`。

未找到该市场连接或无权使用时，停止并报告内置市场不可用。不得改用户默认连接，不得退回无选择器命令、其它连接或直连来源接口。`oo file upload/download` 是文件中转命令，不属于 LinkFox 连接选择。

## 检查链接

一次查询一个 `productUrl`。用 URL 解析器检查 HTTPS、无嵌入账号密码、端口省略或 443、主机是 `etsy.com` 或其真正的子域。路径为 `/listing/<数字ID>`，可再带一个标题段，允许尾斜杠及查询参数。搜索页、店铺页、非 Etsy 主机和短链都不能当作已确认的商品直链。不能仅因字符串包含 etsy.com 就接受它。

## 查询与读取

把用户的完整链接写入 `listing-query.json` 的 `productUrl` 字符串字段：

```bash
oo connector run linkfox --connection-name marketplace_oomol --action get_etsy_product --data @listing-query.json --json
```

业务列表位于 `response.data.data`，条数为 `response.data.total`。一次请求一个 Listing，确认得到一个有效记录后再读取 `response.data.data[0]`，不要默默取多个结果的第一条；空列表或多个记录都应报告为与单商品预期不符。返回 `productId` 或 `productUrl` 可用时，与输入链接的 listing ID 核对；无法确认时说明身份核对限制。

商品记录内预期字段：

| 内容 | 字段 |
| --- | --- |
| 商品身份与文案 | productId、productUrl、title、description（段落数组）、category |
| 图片 | image、images |
| 价格 | price、lowPrice、highPrice、oldPrice、currency |
| 变体与数量 | variants、maxQuantity |
| 发货与送达 | countryShippingFrom、deliveryDaysMin、deliveryDaysMax |
| 店铺 | shopId、shopName、shopUrl、shopSales、yearsOnEtsy |
| 评论概况 | reviews、star、shopReviews、highlightsTags、reviewsTags、reviewsScores |
| 服务标志 | hasRatingsBadge、hasConvosBadge、hasShippingBadge |

## 整理和交付

1. 先给标题、Listing ID、店铺、类目、价格区间和返回币种，附原商品链接。
2. 图片可显示主图，说明其他图片数量；长描述先摘要，需要时再从保存的响应提取完整段落。
3. 价格按原字符串展示，未经用户要求不换汇或强制转数值；不要默认 USD。变体空数组是有效情况；`maxQuantity` 是页面报告的最大可购数量，不等于已验证的真实库存。
4. `reviews` 是商品评论数，`shopReviews` 是店铺评论数，`shopSales` 是店铺公开销量文本。不得把后两者用于证明该 Listing 的销量。
5. 评论标签和分项分数是聚合信号，不能伪造成逐条买家原话。`reviewsScores` 的键不固定，不假定统一评分维度。
6. 送达区间仅在上下界都有效且顺序合理时展示；不把配送估算当承诺。空白或明显矛盾的店铺、评分、价格、徽章字段标注提取不确定性，不静默修复。
7. 可按文案、视觉、价格、变体与配送组织竞品页面拆解，但每个判断须依赖实际返回内容。该接口不能证明历史价格、关键词排名或精确商品销量。
8. 用户需要文件时保存 Markdown 报告或结构化 JSON，并提供可点击路径；图片 URL 作为媒体链接，不把商品页、店铺页下载为文件。

## 调用与证据边界

业务调用需要 oo CLI 和当前 OOMOL 账户/团队的市场访问权限。用 JSON 文件传参，保留成功响应和查询时间到本次任务输出目录，不覆盖其他任务文件。CLI 业务结果在 `response.data`，执行标识在 `response.meta.executionId`。

本技能已静态核对，未真实试跑。公开 schema 声明的结果容器之内，业务字段依据来源包说明和 Connector 透传实现，不能当作每次必定返回的字段。读值前检查类型，缺失或 null 显示“未提供”，不补零、不猜路径，也不把缺少字段解释为业务事实不存在。

命令失败时报告实际错误并保留已取得的数据。鉴权、权限或余额阻塞时按 OOMOL 错误指引处理；不索取来源平台密钥，不调用充值、余额检查或反馈接口。空结果或超时不自动改参数连续试探。当前结果不足以支持用户结论时，明确说明缺少什么。

## 读取业务字段

解释结果和构造后续请求前，读取 [结果字段与业务衔接](references/result-fields.md)，按端点保留关键输出、嵌套指标和关联 ID。