linkfox-shopee-product-detail

Shopee 商品详情查询

从受支持的市场站点 URL 获取一件 Shopee 商品当前公开的详情。

核心概念

• 每次调用查询一件商品：productUrl 标识一个商品列表；这不是关键词搜索工具。
• 市场由 URL 决定：根据 URL 推断店面、货币和地区设置。
• 直接商品列表模式：工具会自动识别提供的商品 URL，并且只请求一条匹配的商品列表。
• 当前快照：可用的价格、库存、销量、评分和店铺信息反映请求时的公开页面内容。

数据字段

data 中的每个对象都可能包含：

分组	代表性字段
标识信息	itemId、shopId、url、name、brand、categoryId、categoryBreadcrumb
媒体	image、images、videos
定价	price、priceBeforeDiscount、priceMin、priceMax、discountPercent、currency
需求	sold、soldDisplayed、rating、ratingCount、ratingDistribution、likedCount
库存	stock、tierVariations、models
店铺	shopName、shopRating、shopLocation、isMall、官方和验证标记、嵌套的 shop 数据
内容	description、attributes、类目数据，以及提供时的可售状态和商品状况

返回的商品对象会保留较少见及新增的顶层字段。字段可能缺失或为 null。

参数指南

参数	必需	默认值	描述
productUrl	是	-	Shopee HTTPS 商品 URL，其路径以 -i.<numeric shopId>.<numeric itemId> 结尾

支持的主机：shopee.sg、shopee.co.id、shopee.com.my、shopee.ph、shopee.co.th、shopee.tw、shopee.vn 和 shopee.com.br。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-shopee-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 引导解决问题：

• LINKFOX_AGENT_API_KEY 与 LINKFOXAGENT_API_KEY 均未配置。
• 响应状态为 401 或 402。
• 响应提示算力、余额、套餐或配额不足。

使用示例

python scripts/shopee_product_detail.py '{"productUrl":"https://shopee.sg/%28LENECT-OFFICIAL-STORE%29-Flash-I-Aurora-Dual-Highlighter-7.2g-COCOMO-i.9641401.29691169956"}'

显示规则

1. 首先显示商品名称、商品 ID、店铺、市场站点、当前价格、货币、库存和公开销量。
2. 按照返回结果原样显示当前价、原价和折扣；除非用户提出要求，否则不要转换货币。
3. 如果有 SKU 型号和各规格库存，请用简洁的表格呈现。
4. 适用时内嵌少量图片，避免展示过多图片。
5. 分别处理 Shopee Mall、官方店铺和已验证卖家标记。
6. 说明描述、型号、库存、销量或其他扩充字段何时不可用。
7. 只有用户需要时，才从保存的 JSON 中读取大型嵌套部分的完整内容。

重要限制

1. URL 必须使用文档中说明的 -i.<shopId>.<itemId> 路径；此工具不接受规范的 /product/<shopId>/<itemId> URL。
2. 不会返回客户评价行。ratingCount 和 ratingDistribution 仅在来源提供这些信息时作为汇总指标。
3. 公开字段因市场、商品上架状态、卖家和来源页面完整度而异。印度尼西亚、新加坡、马来西亚、泰国和菲律宾的云端来源通常会提供更丰富的详情；越南、巴西和台湾可能只返回较精简的记录。
4. models 提供变体库存，但可能无法获取每个单独变体的价格。
5. 无效、已下架或与市场不匹配的商品会返回错误，而不是成功返回空列表。
6. 此工具不会搜索 Shopee、提供历史趋势或管理授权卖家账户。

用户表达与场景速查

适用 — 已知的单个 Shopee 商品：

用户说	场景
“查这个虾皮商品链接”	商品详情查询
“看一下价格、销量和库存”	当前商品信息核查
“提取变体、图片和品牌”	SKU 和内容提取
“这个店铺是不是官方店？”	公开店铺信号检查

不适用：

• 关键词搜索、排名或批量商品筛选
• 完整收集客户评价或进行情感分析
• 历史价格和库存监控
• 授权卖家商品上架、订单、促销或账户操作

算力消耗规则

消耗 53 算力。

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

反馈：

当所描述的能力与实际行为不符、结果未能满足用户意图、用户表达赞许或不满，或此技能有改进空间时，通过 Feedback API 自动检测并提交反馈。遵循 references/api.md，不要打断用户流程。

---

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