linkfox-sorftime-walmart-keyword-research

Walmart 关键词研究

使用一个 Sorftime 端点研究 Walmart US 关键词，或明确管理已保存的关键词库。

核心概念

• 每个请求只能发送一个 operation。绝不能将多个关键词操作串成自动发现链。
• 使用扁平 JSON 请求体。唯一的业务嵌套结构是 marketQuery 可选的 pattern 对象。
• operation 的值区分大小写。不同的操作、页面或筛选条件都属于另一次付费调用。
• favoriteAdd 和 favoriteChange 会修改外部账户数据，必须有明确、无歧义的用户请求。

操作路由

意图	operation	必需输入	Sorftime 请求数
筛选当前热门关键词	marketQuery	无；筛选条件可选	5
根据名称查找热门关键词	searchByName	name	1
查找热门关键词对应的商品	searchProducts	keyword	5
查看关键词指标	detail	keyword	1
查找与商品关联的关键词	productKeywords	productId	1
扩展相关关键词	relatedKeywords	keyword	5
添加已保存的关键词	favoriteAdd	keyword	1
删除或移动已保存的关键词	favoriteChange	keyword、command	0
列出已保存的关键词或文件夹	favoriteList	command	1

调用前，请阅读 references/api.md 了解完整的条件参数矩阵。

参数指南

• marketQuery：可选参数 pattern.keyword、pattern.rankCondition 和 pattern.searchVolumeCondition；pageIndex 默认为 1，pageSize 默认为 20（20–200）。
• 单值条件（如 [10000]）表示下限。[0,10000] 遵循 Sorftime 文档中“小于 10000”的语义。
• searchByName：name 是商品或类别名称；pageIndex 默认为 1，Sorftime 每页最多返回 200 条记录。
• searchProducts、productKeywords 和 relatedKeywords：分页默认从第 1 页开始，每页 20 条，最多 200 条。
• favoriteList 提供 pageIndex 参数（默认为 1）；后端会将其映射到 Sorftime 上游的 Page 字段。

调用方式

• API 端点：POST /sorftime/walmart/keywordResearch（完整参数、响应和错误码见 references/api.md）
• Python 脚本：python scripts/sorftime_walmart_keyword_research.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；只读研究操作对相同参数组合使用 24h 本地缓存，favoriteAdd、favoriteChange、favoriteList 始终绕过缓存。失败或结果为空时，不得自动更换关键词、翻页或更改邮编连续试探；需要继续检索时，先告知用户会产生额外消耗。

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

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

关键词库安全

• 添加到默认的“未分类”文件夹时，省略 dict；Sorftime 可能会创建指定的文件夹。
• 使用 command="del" 删除。省略 dict 时会操作默认的“未分类”文件夹；指定 dict 则从其他文件夹删除。
• 使用 command="move=<目标目录>" 移动。省略 dict 表示源文件夹为“未分类”。
• 列表查询时，command 设为 all、dict 或 dict=<目录>。
• 若外部状态已改变，确实需要重复已获明确授权的修改操作，请使用 --no-cache；绝不能用它绕过确认保护。
• favoriteAdd、favoriteChange 和 favoriteList 始终绕过本地缓存，因此修改操作不会被抑制，列表结果也会反映最新的上游状态。
• 已提供的操作不支持删除文件夹。删除最后一个关键词后，API 关键词库中可能会留下空文件夹。

使用示例

python scripts/sorftime_walmart_keyword_research.py '{"operation":"marketQuery","pattern":{"keyword":"wireless","searchVolumeCondition":[10000]},"pageIndex":1,"pageSize":20}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"detail","keyword":"wireless earbuds"}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"productKeywords","productId":"5169493923","pageIndex":1,"pageSize":20}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"favoriteList","command":"dict","pageIndex":1}'

仅在获得明确授权后执行变更操作。

展示规则

1. 说明所选操作，并在返回时展示 requestConsumed、costCredit 和 costToken。如果 _cache.hit=true，请明确说明缓存值描述的是原始实时请求，且未产生新的生产费用。
2. 保留指标的含义和观察窗口；不要将估算值说成有保证的需求或销量。
3. 报告用户请求的页面，并且只有在说明这会产生另一笔付费调用后，才提供其他页面。
4. 将产品 ID 和关键词视为字符串。
5. 对于变更操作，报告返回的数据代码；仅凭 HTTP 200 不能证明变更成功。

重要限制

• 此集成仅面向美国 Walmart。
• 当前热门关键词数据、15 天产品窗口和 30 天产品关键词窗口均受 Sorftime 限制。
• 单个已保存关键词文件夹最多支持 2,000 个关键词。
• API 已保存关键词库与 Sorftime Professional 收藏夹相互独立；两者之间不会同步数据。
• 从 data.value 读取 Sorftime 业务响应；其 JSON 结构因操作而异。
• 结果为空时，不得自动调用变体、分页或相关关键词。
• 此技能不包含 Sorftime Walmart“其他”API。

用户表达与场景快速参考

适用：Walmart 关键词发现、关键词指标、产品到关键词研究、相关词，或明确要求对已保存关键词库执行操作。

不适用：品类市场报告、产品详情／趋势分析，或任何 Sorftime Walmart“其他”功能。

边界判断：只选择一个与用户明确意图相符的操作；绝不要将一个关键词请求自动扩展为多步研究链。

算力消耗规则

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

用户会因算力消耗而支付费用。高消耗筛选、扩展词或连续分页前必须提醒用户；任何收藏变更都须明确授权。

反馈：

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

---

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