Walmart 关键词研究

Use one Sorftime endpoint to research Walmart US keywords or explicitly manage the saved-keyword library.

Core Concepts

Send exactly one
```
operation
```
per request. Never run multiple keyword operations as an automatic discovery chain.
Use a flat JSON body. The only business nesting is the optional
```
pattern
```
object for
```
marketQuery
```
.
```
operation
```
values are case-sensitive. A different operation, page, or filter is another paid call.
```
favoriteAdd
```
and
```
favoriteChange
```
mutate external account data and require an explicit, unambiguous user request.

Operation Routing

Intent	operation	Required input	Sorftime Request
Filter current hot keywords	`marketQuery`	None; filters optional	5
Find hot keywords from a name	`searchByName`	`name`	1
Find products for a hot keyword	`searchProducts`	`keyword`	5
Inspect keyword metrics	`detail`	`keyword`	1
Find a product's associated keywords	`productKeywords`	`productId`	1
Expand related keywords	`relatedKeywords`	`keyword`	5
Add a saved keyword	`favoriteAdd`	`keyword`	1
Delete or move a saved keyword	`favoriteChange`	`keyword` , `command`	0
List saved keywords or folders	`favoriteList`	`command`	1

Read

references/api.md

for the complete conditional parameter matrix before calling.

Parameter Guide

marketQuery

: optional

pattern.keyword

pattern.rankCondition

, and

pattern.searchVolumeCondition

;

pageIndex

defaults to 1 and

pageSize

to 20 (20–200).

A one-value condition such as
```
[10000]
```
is a lower bound.
```
[0,10000]
```
follows Sorftime's documented less-than-10000 semantics.
```
searchByName
```
:
```
name
```
is a product or category name;
```
pageIndex
```
defaults to 1, and Sorftime returns at most 200 rows per page.
```
searchProducts
```
,
```
productKeywords
```
, and
```
relatedKeywords
```
: pagination defaults to page 1 and 20 rows, maximum 200.
```
favoriteList
```
exposes
```
pageIndex
```
(default 1); the backend maps it to Sorftime's upstream
```
Page
```
field.

调用方式

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/套餐到期/需充值/请充值”或类似含义

Keyword Library Safety

Add to the default “未分类” folder by omitting
```
dict
```
; a provided folder may be created by Sorftime.
Delete with
```
command="del"
```
. Omitting
```
dict
```
deletes the keyword from every folder, so explicitly confirm that scope.
Move with
```
command="move=<目标目录>"
```
. Omitting
```
dict
```
means the source is “未分类”.
List with
```
command
```
equal to
```
all
```
,
```
dict
```
, or
```
dict=<目录>
```
.
If an explicitly authorized mutation truly must be repeated after external state changed, use
```
--no-cache
```
; never use it to bypass the confirmation guard.
```
favoriteAdd
```
,
```
favoriteChange
```
, and
```
favoriteList
```
always bypass the local cache, so mutations are never suppressed and list results reflect the latest upstream state.

Usage Examples

bash

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}'

Run mutation operations only after explicit authorization.

Display Rules

State the selected operation and show
```
requestConsumed
```
and
```
costToken
```
when returned.
Preserve metric meanings and observation windows; do not turn estimates into guaranteed demand or sales.
Report the requested page and offer another only after explaining that it creates another paid call.
Treat product IDs and keywords as strings.
For mutations, report the returned data code; HTTP 200 alone does not prove mutation success.

Important Limitations

This integration targets Walmart US only.
Current-hot-keyword data, the 15-day product window, and the 30-day product-keyword window are Sorftime constraints.
A single saved-keyword folder supports at most 2,000 keywords.
The API saved-keyword library is separate from Sorftime Professional favorites; data is not synchronized between them.
Read the Sorftime business response from
```
data.value
```
; its JSON shape varies by operation.
Empty results must not trigger automatic variants, pagination, or related-keyword calls.
This skill excludes Sorftime Walmart “其他” APIs.

User Expression & Scenario Quick Reference

Applicable: Walmart keyword discovery, keyword metrics, product-to-keyword research, related terms, or an explicit saved-keyword-library action.

Not applicable: category-market reports, product detail/trend analysis, or any Sorftime Walmart “其他” capability.

Boundary judgment: Choose exactly one operation that matches the user's stated intent; never turn one keyword request into an automatic multi-step research chain.

积分消耗规则

按动态规则计费：消耗积分 = Sorftime内部查询次数 × 12。Sorftime内部查询次数：不同 operation 需要的查询次数可能不同，实际次数由 Sorftime 决定。

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

Feedback:

Auto-detect and report feedback via the Feedback API when behavior or results mismatch intent, the user expresses praise or dissatisfaction, or an improvement is apparent. Follow

references/api.md

without interrupting the user's flow.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.

linkfox-sorftime-walmart-keyword-research

NPX Install

Tags

SKILL.md Content