linkfox-sorftime-walmart-keyword-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Walmart 关键词研究

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

通过一个Sorftime端点研究Walmart美国站关键词，或明确管理已保存关键词库。

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
```
。切勿将多个关键词操作作为自动发现链运行。
使用扁平JSON请求体。唯一的业务嵌套是
```
marketQuery
```
可选的
```
pattern
```
对象。
```
operation
```
值区分大小写。不同的操作、页码或筛选条件会产生额外付费调用。
```
favoriteAdd
```
和
```
favoriteChange
```
会修改外部账户数据，需要用户明确、无歧义的请求。

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.

意图	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

获取完整的条件参数矩阵。

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.

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 进入上下文。

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

发生以下异常情况时，采用

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.

省略
```
dict
```
时，关键词会添加到默认的“未分类”文件夹；指定的文件夹可能由Sorftime创建。
使用
```
command="del"
```
进行删除操作。省略
```
dict
```
会从所有文件夹中删除该关键词，因此需明确确认操作范围。
使用
```
command="move=<目标目录>"
```
进行移动操作。省略
```
dict
```
表示源目录为“未分类”。
使用
```
command
```
值为
```
all
```
、
```
dict
```
或
```
dict=<目录>
```
进行列表查询。
如果外部状态变更后确实需要重复执行已授权的修改操作，请使用
```
--no-cache
```
；切勿用它绕过确认机制。
```
favoriteAdd
```
、
```
favoriteChange
```
和
```
favoriteList
```
始终绕过本地缓存，因此修改操作不会被抑制，列表结果会反映最新的上游状态。

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.

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

仅在获得明确授权后执行修改操作。

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.

说明所选操作，返回时显示
```
requestConsumed
```
和
```
costToken
```
。
保留指标含义和观察窗口；不要将估算值转化为确定的需求或销量。
报告请求的页码，仅在说明会产生额外付费调用后，才提供下一页的选项。
将商品ID和关键词视为字符串处理。
对于修改操作，报告返回的数据代码；仅HTTP 200状态码不能证明修改操作成功。

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.

本集成仅针对Walmart美国站。
当前热门关键词数据、15天商品窗口和30天商品关键词窗口是Sorftime的限制条件。
单个已保存关键词文件夹最多支持2000个关键词。
API已保存关键词库与Sorftime Professional收藏夹相互独立；两者数据不同步。
从
```
data.value
```
读取Sorftime业务响应；其JSON结构因操作而异。
空结果不得触发自动变体查询、分页或相关关键词调用。
本技能不包含Sorftime Walmart“其他”API。

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.

适用场景：Walmart关键词挖掘、关键词指标分析、商品到关键词的研究、相关术语查询，或明确的已保存关键词库操作。 不适用场景：分类市场报告、商品详情/趋势分析，或任何Sorftime Walmart“其他”功能。 边界判断：选择与用户明确意图完全匹配的一个操作；切勿将一个关键词请求转化为自动多步研究链。

积分消耗规则

按动态规则计费：消耗积分 = 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.

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

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

反馈机制：

当行为或结果与意图不符、用户表达赞扬或不满，或存在明显改进空间时，通过Feedback API自动检测并提交反馈。遵循

references/api.md

的要求，且不中断用户流程。

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