用途
linkfox-walmart-search 是一个沃尔玛商品搜索技能，用于检索和浏览 Walmart 商城上的商品 listing 数据。它面向电商卖家和研究者，帮助其从沃尔玛商城中获取可用于选品调研、价格对比、竞品分析的商品信息。
主要能力
该技能从沃尔玛商城检索实时商品 listing 数据，支持：
- 关键词搜索
- 按品类 ID 浏览
- 关键词与品类 ID 组合搜索
- 价格区间过滤（minPrice / maxPrice）
- 排序（best_seller、best_match、price_low、price_high）
- 分页（默认第 1 页，最大第 100 页）
- 指定门店（storeId）
- 指定设备类型（desktop、tablet、mobile）
- 筛选条件 facet（key:value 格式，使用 || 分隔）
- 仅显示次日达结果（nextDayEnabled）
- 拼写纠正（spelling，默认 true）
- 相关性排序开关（softSort，默认 true）
- 返回字段限制（jsonRestrictor）
搜索时 keyword 或 categoryId 至少提供一个。categoryId 使用 0 表示全部部门。未指定排序时，默认按相关性排序。
返回的商品数据字段
返回结果包含：productId、usItemId、title、description、price、wasPrice、currency、minPrice、pricePerUnitAmount、pricePerUnit、rating、reviews、sellerName、sellerId、imageUrl、productPageUrl、sponsored、outOfStock、freeShipping、twoDayShipping、freeShippingWithWalmartPlus、shippingPrice、multipleOptionsAvailable、variantSwatches。
使用方式
通过传入参数发起搜索，例如：
- 基础关键词搜索：{"keyword": "wireless earbuds"}
- 价格过滤：{"keyword": "laptop stand", "minPrice": 10, "maxPrice": 50}
- 品类畅销：{"keyword": "coffee maker", "sort": "best_seller"}
- 低价优先：{"keyword": "phone case", "sort": "price_low"}
- 品类分页浏览：{"categoryId": "976759_976787", "page": 2}
- 指定门店：{"keyword": "tent", "storeId": "1862"}
- 移动端结果模拟：{"keyword": "water bottle", "device": "mobile"}
- 组合过滤：{"keyword": "running shoes", "minPrice": 30, "maxPrice": 80, "sort": "best_match"}
展示时建议使用结构化表格呈现关键字段（标题、价格、评分、评论数、卖家），价格带货币符号，有 wasPrice 时同时显示当前价与原价，评分需与评论数同时呈现，缺货商品明确标注，广告商品需标记，结果量大时提示可用 page 参数翻页，并附上 productPageUrl 便于跳转。查询失败时应说明错误并建议调整参数。
适用场景
适用于以下沃尔玛商品 listing 查询场景：
- 在沃尔玛搜索某商品
- 查找沃尔玛上的低价商品
- 查看沃尔玛某类目畅销商品
- 对比沃尔玛上某商品的价格
- 判断某商品在沃尔玛是否有货
- 查看沃尔玛 50 美元以下的商品
- 查看沃尔玛高评分商品
- 沃尔玛竞品商品调研
当用户提到“选品调研”或“竞品分析”且需求涉及搜索当前商品 listing、价格、评分或卖家信息时，适用本技能。
限制
不适用于以下需求：
- 沃尔玛卖家账户管理或广告
- 沃尔玛订单跟踪或购买历史
- 商品评论文本分析（仅提供评分与数量）
- 历史价格跟踪或价格趋势分析
- 沃尔玛联盟或 API Key 管理
若用户询问广告策略、账户指标或历史销售数据，则不适用本技能。
认证与算力
使用前需配置 API Key：环境变量 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY。若未配置，或出现 401/402 状态码，或提示算力/余额不足（如“算力余额不足”“计费不足”“余额不足”“quota exceeded”“insufficient balance”“套餐到期”“需充值”“请充值”等），需按 references/onboarding.md 引导解决。
每次调用消耗 15 算力，用户会因算力消耗而支付费用。高频调用或用户对算力消耗预期不足时，应提醒用户并由用户决定是否继续。
反馈
当技能描述的功能与实际行为不符、结果与用户意图不符、用户表达不满或赞赏，或有可改进之处时，通过 Feedback API 自动检测并上报，不打断用户流程。具体调用方式见 references/api.md。