linkfox-sorftime-walmart-product-analysis

Walmart 产品分析

使用 Sorftime，通过自然语言名称查找 Walmart US 产品，或查看某个产品的详情、历史趋势或每日销量序列。

核心概念

• 每个请求恰好发送一个 operation。切勿默认调用全部四个操作。
• 使用 searchByName 查找相关产品，使用 detail 获取当前产品摘要，使用 trend 查看产品历史变化，使用 salesVolume 获取按日期列出的销量数据。
• 每个请求都使用扁平 JSON 请求体。searchByName 必须提供 name；其他操作必须提供字符串类型的 productId。operation 的值区分大小写。
• 后续操作或不同的日期范围都属于另一次付费调用。相同 JSON 可复用 24 小时缓存。

操作路由

意图	operation	参数	Sorftime 请求次数
按名称查找相关产品	searchByName	name、可选的 pageIndex	2
当前产品详情	detail	productId	1
产品历史趋势	trend	productId	2
每日／变体销量数据	salesVolume	productId、可选日期／页码	1

调用前请阅读 references/api.md，了解准确的日期和分页规则。

参数指南

• 始终将 productId 视为字符串，即使其中只包含数字也是如此。
• searchByName 接受自然语言产品名称，每页最多返回 100 个相关产品；pageIndex 默认为 1。
• salesVolume 接受可选的 queryDate 和 queryEndDate，格式为 yyyy-MM-dd。两者均未提供时，将返回最近 30 天的范围；仅提供 queryDate 时，结束日期默认为当天。
• pageIndex 适用于 searchByName 和 salesVolume，从 1 开始，默认为 1。
• 当前可查询的历史范围由 Sorftime 控制；不要承诺固定的最早日期。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sorftime-walmart-product-analysis-<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／套餐到期／需充值／请充值”或类似含义

使用示例

python scripts/sorftime_walmart_product_analysis.py '{"operation":"searchByName","name":"wireless earbuds","pageIndex":1}'
python scripts/sorftime_walmart_product_analysis.py '{"operation":"detail","productId":"5169493923"}'
python scripts/sorftime_walmart_product_analysis.py '{"operation":"trend","productId":"5169493923"}'
python scripts/sorftime_walmart_product_analysis.py '{"operation":"salesVolume","productId":"5169493923","queryDate":"2026-07-01","queryEndDate":"2026-07-31","pageIndex":1}'

展示规则

1. 说明操作类型以及提供的产品名称或产品 ID，并显示返回的 requestConsumed、costCredit 和 costToken。如果 _cache.hit=true，请明确说明缓存值描述的是原始实时请求，且没有产生新的生产费用。
2. 对于 searchByName，将结果标注为相关产品，而非精确匹配，并报告请求的页码。
3. 对于 detail，仅展示 ProductSummeryObject 返回的字段；不得推断缺失的属性。
4. 对于 trend，先根据响应确认时间字段及单位，再总结变化。
5. 对于 salesVolume，将数据行解释为 [date, sales, type]；type=2 表示昨日的销量记录。
6. 准确标注估算值或观测值；不得将其说成有保证的 Walmart 交易数据。

重要限制

• 此集成仅适用于 Walmart 美国站。
• 每次调用 API 只能接受一个产品名称或一个产品 ID，并执行一项操作。
• 历史数据覆盖范围和数据可用性由 Sorftime 控制。
• 翻页或执行第二项操作都会产生另一次付费调用，并需要用户授权。
• searchByName 用于通过自然语言发现相关产品，而不是多筛选条件产品数据库或品类市场查询。

用户表达与场景速查

适用：根据自然语言产品名称查找 Walmart 产品，或围绕已知 ProductId 查询其详情、趋势或销售历史。

不适用：品类市场研究、关键词指标／反向查找，或多条件产品筛选。

边界判断：仅当用户需要根据名称查找相关产品时使用 searchByName；使用 detail 获取当前快照，使用 trend 获取历史属性，仅在需要带日期的销售数据行时使用 salesVolume。

算力消耗规则

按动态规则计费：当前单个 Sorftime Request 显示为 6 算力；多 Request 操作由网关按整单计算并取整，最终以入口脚本返回的 costCredit 为准，不要简单用 requestConsumed × 6 代替实际账单。

用户会因算力消耗而支付费用。未经确认，不要补调另一 operation 或下一页。

反馈：

当行为或结果与用户意图不符、用户表达赞赏或不满，或发现可改进之处时，通过 Feedback API 自动检测并报告反馈。遵循 references/api.md，不要打断用户流程。

---

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