linkfox-ebay-search

eBay 产品搜索

此技能将指导你如何搜索和获取 eBay 商品刊登数据，帮助电商卖家和买家在 eBay 全球市场中查找商品、比较价格并分析市场趋势。

核心概念

eBay 产品搜索可访问 eBay 前端的商品刊登数据。它支持基于关键词的搜索，并提供丰富的筛选选项，包括价格范围、商品状况、购买形式、排序方式、卖家所在地等。搜索结果包含商品详情，例如标题、价格、配送信息、卖家评级、已售数量和商品状况。

市场逻辑：ebayDomain 参数控制要搜索的 eBay 区域站点。默认值为 ebay.com（美国）。当用户提及某个国家或地区时，将其映射到对应的 eBay 域名（例如，英国 -> ebay.co.uk，德国 -> ebay.de）。

购买形式：eBay 支持多种购买形式——Auction 表示竞价刊登，BIN（立即购买）表示固定价格刊登，BO（最佳报价）表示可议价刊登。

参数指南

参数	类型	必填	描述	默认值
keyword	string	否	搜索关键词，最多 1024 个字符	-
ebayDomain	string	否	eBay 市场域名	ebay.com
page	integer	否	分页页码	1
pageSize	integer	否	每页结果数：25、50、100 或 200	50
orderBy	string	否	排序方式（见下方排序选项）	12（最佳匹配）
priceMin	number	否	最低价格筛选	-
priceMax	number	否	最高价格筛选	-
itemCondition	string	否	商品状况代码，多个代码以竖线分隔（例如，1000|3000）	-
buyingFormat	string	否	购买形式：Auction、BIN 或 BO	-
showOnly	string	否	显示筛选条件，以逗号分隔（例如，Sold,Complete）	-
location	integer	否	卖家所在地国家代码	-
prefLoc	string	否	首选地区范围：1=国内，2=区域内，3=全球	-
zipCode	string	否	用于区域配送筛选的 ZIP/邮政编码	-
categoryId	integer	否	eBay 分类 ID	-
noCache	boolean	否	绕过缓存以获取最新结果	false

排序选项

代码	含义
12	最佳匹配（默认）
1	时间：即将结束
10	时间：最新刊登
15	价格 + 运费：从低到高
16	价格 + 运费：从高到低
2	价格：从低到高
3	价格：从高到低
7	距离：从近到远
18	商品状况：新品优先
19	商品状况：二手商品优先

商品状况代码

代码	状况
1000	全新
1500	其他新品（详见详情）
1750	有瑕疵的新品
2000	认证翻新
2010	极佳 - 翻新
2020	很好 - 翻新
2030	良好 - 翻新
2500	卖家翻新 / 再制造
2750	近乎全新
3000	二手 / 曾经使用
7000	仅供拆件或无法正常工作

showOnly 筛选值

值	含义
Complete	已结束的刊登
Sold	仅显示已售出的刊登
FR	免费退货
RPA	接受退货
AS	授权卖家
Savings	优惠与折扣
SaleItems	特价商品
Lots	批量商品
FS	免运费
LPickup	本地自提

支持的 eBay 域名

域名	国家/地区
ebay.com	美国（默认）
ebay.co.uk	英国
ebay.de	德国
ebay.fr	法国
ebay.it	意大利
ebay.es	西班牙
ebay.ca	加拿大
ebay.com.au	澳大利亚
ebay.nl	荷兰
ebay.at	奥地利
ebay.ch	瑞士
ebay.pl	波兰
ebay.ie	爱尔兰
ebay.com.hk	中国香港
ebay.com.my	马来西亚
ebay.com.sg	新加坡

调用方式

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

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

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

使用示例

1. 基本关键词搜索 在 eBay 美国站点搜索“wireless earbuds”：

{"keyword": "wireless earbuds"}

2. 搜索已售商品以研究价格 查找“iPhone 15 Pro”的已售商品，了解市场价格：

{"keyword": "iPhone 15 Pro", "showOnly": "Sold,Complete", "orderBy": "10"}

3. 在指定站点按价格范围搜索 在 eBay 英国站点查找价格在 $500 至 $1000 之间的新笔记本电脑：

{"keyword": "laptop", "ebayDomain": "ebay.co.uk", "priceMin": 500, "priceMax": 1000, "itemCondition": "1000"}

4. 即将结束的拍卖商品 查找即将结束的“vintage watch”在拍卖中的商品：

{"keyword": "vintage watch", "buyingFormat": "Auction", "orderBy": "1"}

5. 查找最便宜的新商品 查找提供免费配送的最便宜的“USB-C cable”新品：

{"keyword": "USB-C cable", "itemCondition": "1000", "orderBy": "15", "showOnly": "FS"}

6. 分页结果 获取“running shoes”搜索结果的第 3 页，每页 100 件商品：

{"keyword": "running shoes", "page": 3, "pageSize": 100}

7. 按类别搜索 在指定的 eBay 类别中搜索：

{"keyword": "mechanical keyboard", "categoryId": 33963}

8. 按所在地筛选搜索 在德国 eBay 站点查找位于德国的商品：

{"keyword": "Kopfhoerer", "ebayDomain": "ebay.de", "location": 77}

显示规则

1. 清晰呈现数据：使用格式清晰的表格展示搜索结果，包括标题、价格、商品状况、卖家信息和配送等关键字段
2. 价格格式：始终显示带货币符号的价格。显示价格范围（minPrice 至 maxPrice）时，应格式化为范围
3. 已售/已完成数据：显示已售商品时，突出显示成交价和数量，帮助用户研究价格
4. 卖家信誉指标：如有数据，显示卖家反馈百分比和评价数量，帮助用户评估卖家可靠性
5. 分页提示：如果结果总数超出当前页，应告知用户结果总数，并建议分页查看更多
6. 赞助商品：清楚标记赞助商品，方便用户区分自然搜索结果和推广结果
7. 错误处理：查询失败时，说明问题并建议调整搜索参数
8. 链接呈现：提供商品链接，方便用户在 eBay 查看完整详情

重要限制

• 无历史数据：本工具仅返回当前的在售商品，不提供历史价格趋势
• 结果上限：每页最多 200 条结果
• 速率限制：请求过多可能会受到限制；请谨慎使用 noCache: true
• 货币：返回的价格使用所搜索 eBay 域名对应的当地货币

用户表达与场景速查

适用——eBay 商品搜索和商品列表数据：

用户说	场景
“在 eBay 上搜索 XX”	基本商品搜索
“XX 在 eBay 上卖多少钱”	已售商品价格调研
“在 eBay 上找最便宜的 XX”	价格比较／最低价格
“eBay 上 XX 的拍卖”	拍卖商品列表搜索
“eBay 英国／德国站上什么商品卖得好”	浏览地区市场
“在 eBay 上找 50 美元以下的全新 XX”	按商品状况和价格筛选搜索
“eBay 上 XX 的已售价格”	已结束／已售商品列表分析
“在 eBay 上找翻新 XX”	按商品状况搜索

不适用——需求超出 eBay 商品列表范围：

• eBay 卖家账户管理或店铺分析
• 创建或编辑 eBay 商品列表
• eBay 订单跟踪或购买历史
• 跨平台价格比较（eBay、Amazon 等）
• eBay 广告或推广商品管理

算力消耗规则

消耗 15 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

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

1. 此技能描述的功能或用途与实际行为不符
2. 技能结果不符合用户意图
3. 用户表达对该技能的不满或赞扬
4. 任何你认为可以改进的地方

请按照 references/api.md 中的说明调用 feedback API。不要打断用户的使用流程。

---

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