linkfox-youying-shopee-product-search

友鹰-Shopee 商品选品

This skill guides you on how to query and filter Shopee product data across 11 marketplaces, helping cross-border sellers discover trending products and market opportunities on Shopee.

Core Concepts

友鹰（YouYing）Shopee 商品选品工具提供 Shopee 全站商品的结构化查询能力。卖家可通过关键词、价格区间、销量、上架时间、店铺属性等多维度条件灵活组合筛选，发现爆款货源与市场机会。

核心数据维度：

• 销量数据：前30天销售件数（sold）、估算前30天销售件数（estimateSold）、商品总销售件数（historicalSold）、前30天销售额（payment）
• 价格数据：默认价（price）、最低价（minPrice）、最高价（maxPrice）
• 店铺数据：店铺名称、是否官方店铺、虾皮优选、本地/海外、跨境/本土
• 商品属性：评分、评分数、收藏数、浏览数、SKU 数量、上架时间、类目结构

Data Fields

Product Fields (Output)

Field	API Name	Description	Example
商品ID	pid	商品唯一标识	12345678
商品标题	title	商品名称	Storage Box Organizer
商品描述	description	商品详细描述	...
商品主图	imageUrl	商品主图URL	https://...
商品链接	productUrl	Shopee商品页面链接	https://...
默认价	price	商品默认价格（当地货币）	29.90
最低价	minPrice	SKU最低价	19.90
最高价	maxPrice	SKU最高价	39.90
前30天销售件数	sold	近30天实际销量	1500
估算前30天销量	estimateSold	估算的近30天销量	1200
总销售件数	historicalSold	商品累计总销量	50000
前30天销售额	payment	近30天销售金额（当地货币）	45000
商品评分	rating	0-5分	4.8
评分数	ratings	收到的评分总数	320
收藏数	favorite	被收藏次数	2800
浏览数	viewCount	浏览次数	15000
库存	stock	当前库存数量	500
SKU数量	skuNumber	SKU变体数量	8
上架时间	genTime	商品首次上架日期	2025-06-01
类目结构	categoryStructure	所属类目层级路径	Home & Living > Storage
店铺名称	shopName	所属店铺名称	BestHome Official
店铺链接	shopUrl	店铺页面链接	https://...
是否官方店铺	isOfficialShop	1=是, 0=否	1
虾皮优选	isShopeeVerified	1=优选, 0=非优选	1
发货类型	cbOption	1=跨境, 0=本土	0
店铺所在地类型	shippingIconType	0=本地, 1=海外	0
商品状态	status	1=正常, 0=下架	1

Supported Marketplaces

站点	station 值	代码
马来西亚	malaysia	MY
中国台湾	taiwan_china	Taiwan_CHN
印度尼西亚	indonesia	ID
泰国	thailand	TH
菲律宾	philippines	PH
新加坡	singapore	SG
越南	vietnam	VN
巴西	brazil	BR
墨西哥	mexico	MX
智利	chile	CL
哥伦比亚	columbia	CO

station 为必填参数，可传站点名（如 malaysia）或代码（如 MY）。当用户未指定站点时，需要询问用户想查询哪个站点。

API Usage

This tool calls the LinkFox tool gateway API. See references/api.md for calling conventions, request parameters, and response structure. You can also execute scripts/youying_shopee_search.py directly to run queries.

How to Build Queries

根据用户需求，将自然语言转换为 API 参数组合。核心原则是精确映射用户的筛选条件到对应参数。

Principles for Building API Calls

1. 必填站点：每次调用必须指定 station。用户说"马来""马来西亚"→ malaysia；"中国台湾"→ taiwan_china；"印尼"→ indonesia 等
2. 关键词搜索：keyword 为标题关键词，搭配 keywordType 控制匹配模式（1=整句匹配，2=多词AND，3=多词OR）
3. 数值范围：大多数筛选条件使用 Start/End 或 Min/Max 成对参数，按需设置单侧或双侧
4. 排序：orderBy 指定排序字段，orderByType 指定升/降序（默认 DESC 降序）
5. 分页：page 从 1 开始，pageSize 范围 1-1000，默认 1000
6. 排除逻辑：notExistKeyword 可排除包含特定词的商品，notExistShopIdList 可排除特定店铺

Common Query Scenarios

1. 关键词选品 — 按销量筛选热销商品

station: malaysia
keyword: Storage Box
keywordType: 2
soldMin: 100
orderBy: sold
orderByType: DESC
pageSize: 100

2. 新品发现 — 近期上架且有一定销量的商品

station: thailand
keyword: Phone Case
listingDateFrom: 2025-06-01
soldMin: 50
orderBy: gen_time
orderByType: DESC

3. 高潜力商品 — 低价高销量

station: indonesia
keyword: LED Light
priceMax: 50000
soldMin: 500
orderBy: payment
orderByType: DESC

4. 跨境卖家商品筛选

station: malaysia
keyword: Wireless Earbuds
cbOption: 1
soldMin: 200
orderBy: sold
orderByType: DESC

5. 品类选品 — 按类目 + 销售额筛选

station: vietnam
pL1Id: 11036379
paymentStart: 10000000
orderBy: payment
orderByType: DESC
pageSize: 200

6. 竞品店铺分析 — 查看特定店铺的商品

station: malaysia
shopIdList: 123456789
orderBy: sold
orderByType: DESC

7. 优选商品筛选 — 虾皮优选 + 高评分

station: philippines
keyword: Beauty
isShopeeVerified: 1
ratingMin: 4.5
soldMin: 100
orderBy: rating
orderByType: DESC

8. 大卖排除 — 发现中小卖家机会

station: taiwan_china
keyword: 收纳盒
notExistShopIdList: 111111,222222,333333
soldMin: 50
soldMax: 500
orderBy: sold
orderByType: DESC

展示规则

1. 仅展示数据：以清晰的表格展示查询结果，不提供主观的商业建议
2. 货币提示：不同市场使用不同货币（MYR、TWD、IDR、THB、PHP、SGD、VND、BRL、MXN、CLP、COP）。展示价格或付款数据时，始终提醒用户注意货币背景
3. 数据量提示：结果较多时，展示核心数据（标题、价格、销量、销售额、评分），并提醒用户可通过分页查看更多内容
4. 突出关键指标：优先展示 sold（前 30 天销量）、payment（前 30 天销售额）、price、rating，这些是最有助于决策的指标
5. 错误处理：查询失败时，根据错误响应说明原因，并建议调整查询条件
6. 图片展示：如果有 imageUrl，则附上商品图片，帮助用户进行直观评估

重要限制

• 结果上限：每次请求的 pageSize 最多为 1000 条记录
• 必填字段：始终需要提供 station——如果缺少该字段，请询问用户要查询哪个市场
• 价格货币：价格采用所选市场的当地货币，而非 USD
• 数据时效性：数据取决于友鹰的抓取计划，请通过 lastModiTime 查看上次更新时间

用户表述与场景速查

适用 - Shopee 商品搜索和筛选：

用户说法	场景
"虾皮上什么好卖" "Shopee爆款"	热销商品发现
"帮我在Shopee上搜xx商品"	关键词商品搜索
"马来站最近上架的新品"	按上架日期发现新品
"销量过千的商品有哪些"	按销量筛选商品
"东南亚哪些品类有机会"	品类级机会扫描
"帮我看看这个店铺的商品"	竞品店铺分析
"跨境商品和本土商品对比"	跨境商品与本土商品对比
"Shopee优选商品筛选"	Shopee 优选商品筛选
"低价高销量的商品"	价格与销量机会挖掘

不适用 - 超出 Shopee 商品搜索范围的需求：

• Amazon、TikTok、eBay、1688 等其他平台的商品搜索
• Shopee 广告投放策略
• Shopee 店铺运营建议
• Shopee 物流／仓储方案
• 处理已有的本地 Shopee 数据文件

边界判断：当用户提到“东南亚选品”“虾皮市场分析”或“跨境电商选品”时，如果归根结底是在 Shopee 上按各种条件搜索和筛选商品，则适用此技能。如果用户询问的是物流规划、广告策略或店铺运营，则不适用。

反馈：

出现以下任一情况时，通过 Feedback API 自动检测并提交反馈：

1. 此技能描述的功能或用途与实际行为不符
2. 此技能的结果与用户意图不符
3. 用户对这项技能表示不满或赞扬
4. 你认为有任何可以改进之处

按照 references/api.md 中的说明调用反馈 API。不要打断用户的操作流程。

处理大型响应

为避免 Agent 上下文溢出，请将响应持久化到磁盘，并仅提取所需字段：

python scripts/response_io.py run --script scripts/youying_shopee_search.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

将 --out-dir 指定在任何 Git 工作树之外（例如 Unix 上的 /tmp/...，Windows 上的 %TEMP%/...）。持久化的响应可能包含个人身份信息、定价或身份验证敏感数据，请勿提交这些文件。文件不会自动删除；任务完成后请清理。

run 会将完整响应写入文件，并仅输出架构预览和文件路径。read 会筛选特定字段，并支持使用 --limit/--offset 切片，以及使用 --format json|jsonl|csv|table 指定输出格式。

何时优先采用此模式 — 请根据响应特征自行判断，例如：

• 每条记录的字段数量较多，或包含不需要的字段
• 批量/分页结果（每次调用返回多项）
• 长文本字段（描述、评论、HTML、时间序列）
• 输出会在后续步骤中重复使用，而非立即处理

对于较小且仅使用一次的响应，直接调用主脚本即可。

⚠️ 预览内容是经过截断的架构和样例，并非完整数据。任何字段级决策都必须通过 read 从持久化文件中读取。

---

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