在 eBay 多站点搜索商品 listing 时用：查商品…

需要按关键词、价格、成色、购买形式、卖家所在地等条件搜索 eBay 多站点商品 listing 并分析当前市场数据时使用。

适用场景

解决思路

1. 通过 API 端点 `POST /ebay/search` 调用，完整参数、响应和错误码见 `references/api.md`。
2. 或运行 Python 脚本：`python scripts/ebay_search.py '<JSON 参数>' [--inline]`。
3. 根据用户提到的国家或地区映射 `ebayDomain`：英国 -> `ebay.co.uk`，德国 -> `ebay.de`；默认 `ebay.com`（美国）。
4. 支持并可按需选择以下 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` 新加坡。
5. 使用 `keyword` 传搜索关键词，最多 1024 字符。
6. 使用 `page` 控制分页，默认 1。
7. 使用 `pageSize` 控制每页结果数，只可取 25、50、100 或 200，默认 50；结果上限每页 200。
8. 使用 `orderBy` 控制排序，默认 `12`（Best Match）；可选 `1` 结束时间最近、`10` 最新上架、`15` 价格+运费最低、`16` 价格+运费最高、`2` 价格最低、`3` 价格最高、`7` 距离最近、`18` 成色新优先、`19` 成色旧优先。
9. 使用 `priceMin` 和 `priceMax` 过滤价格范围。
10. 使用 `itemCondition` 过滤商品成色，多个成色用竖线分隔，如 `1000|3000`；可用代码：`1000` New、`1500` New other (see details)、`1750` New with defects、`2000` Certified Refurbished、`2010` Excellent - Refurbished、`2020` Very Good - Refurbished、`2030` Good - Refurbished、`2500` Seller refurbished / Remanufactured、`2750` Like New、`3000` Used / Pre-owned、`7000` For parts or not working。
11. 使用 `buyingFormat` 过滤购买形式：`Auction`（竞价）、`BIN`（Buy It Now/固定价）、`BO`（Best Offer/可议价）。
12. 使用 `showOnly` 做展示过滤，多个值用逗号分隔，如 `Sold,Complete`；可用值：`Complete` Completed listings、`Sold` Sold listings only、`FR` Free returns、`RPA` Returns accepted、`AS` Authorized seller、`Savings` Deals & savings、`SaleItems` Sale items、`Lots` Lots、`FS` Free shipping、`LPickup` Local pickup。
13. 使用 `location` 传卖家所在国家代码进行过滤。
14. 使用 `prefLoc` 控制偏好位置范围：`1`=Domestic、`2`=Regional、`3`=Worldwide。
15. 使用 `zipCode` 按 ZIP/postal code 做区域配送过滤。
16. 使用 `categoryId` 限定 eBay 分类搜索。
17. 使用 `noCache` 绕过缓存获取最新结果，默认 false；应少用。
18. 基本关键词搜索示例：`{"keyword": "wireless earbuds"}`。
19. 已售 listing 价格研究示例：`{"keyword": "iPhone 15 Pro", "showOnly": "Sold,Complete", "orderBy": "10"}`。
20. 指定站点加价格区间示例：`{"keyword": "laptop", "ebayDomain": "ebay.co.uk", "priceMin": 500, "priceMax": 1000, "itemCondition": "1000"}`。
21. 即将结束的拍卖示例：`{"keyword": "vintage watch", "buyingFormat": "Auction", "orderBy": "1"}`。
22. 最便宜的新品且免邮示例：`{"keyword": "USB-C cable", "itemCondition": "1000", "orderBy": "15", "showOnly": "FS"}`。
23. 分页结果示例：`{"keyword": "running shoes", "page": 3, "pageSize": 100}`。
24. 分类限定搜索示例：`{"keyword": "mechanical keyboard", "categoryId": 33963}`。
25. 按所在地过滤示例：`{"keyword": "Kopfhoerer", "ebayDomain": "ebay.de", "location": 77}`。
26. 始终把完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-ebay-search-<timestamp>.json`；`<cwd>` 为脚本执行时工作目录（Claude Code 中即当前项目目录），`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；禁止写入 `/tmp`，当前目录不可写则报错。
27. 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout。
28. 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）。
29. 加 `--inline` 强制全量打印到 stdout，同时也落盘。
30. 读数据时先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
31. 未配置 API Key：环境变量 `LINKFOX_AGENT_API_KEY` 和 `LINKFOXAGENT_API_KEY` 均未配置时，采用 `references/onboarding.md` 引导解决。
32. 响应 401 或 402 时，采用 `references/onboarding.md` 引导解决。
33. 响应提示算力或余额不足（消息含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义）时，采用 `references/onboarding.md` 引导解决。
34. 遵守成本约束：本工具消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存；失败或空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。
35. 算力消耗为 15 算力；当需要高频调用本技能，或用户对算力消耗量预期不足时，提醒用户并由用户决定是否继续。
36. 展示结果时用格式良好的表格包含 title、price、condition、seller info、shipping 等关键字段。
37. 价格始终显示货币符号；显示价格范围时按 minPrice 到 maxPrice 格式化为区间。
38. 展示已售商品时突出 sold price 和 quantity，辅助定价研究。
39. 可用时显示卖家反馈百分比和评论数，帮助评估卖家可靠性。
40. 当总结果超过当前页时，告知用户 total count 并建议分页查看更多。
41. 明确标记 sponsored listings，便于区分自然结果和推广结果。
42. 查询失败时解释问题并建议调整搜索参数。
43. 提供 product links，让用户可在 eBay 查看完整详情。
44. 在解释结果时说明：只返回当前 live listings，不提供历史定价趋势。
45. 在解释结果时说明：每页最多 200 条结果。
46. 在解释结果时说明：过度请求可能被限流，少用 `noCache: true`。
47. 在解释结果时说明：价格使用所搜索 eBay 域名的本地货币。
48. 遇到以下情况通过 Feedback API 上报反馈：技能功能或目的与实际行为不符、结果不符合用户意图、用户表达不满或表扬、认为有可改进之处；按 `references/api.md` 调用，不要打断用户流程。

适用边界 · 注意事项

• 不适用于 eBay 卖家账号管理、店铺分析、listing 创建/编辑、订单跟踪或购买历史。
• 不适用于跨平台价格比较（如 eBay vs Amazon vs 其他平台）。
• 不适用于 eBay 广告或 promoted listing 管理；也不提供历史定价趋势，仅返回当前 live listings。