linkfox-xiyou-dongcha

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xiyou (西柚找词) — Amazon ASIN & Keyword Analytics

Xiyou（西柚找词）——亚马逊ASIN与关键词分析

This skill queries Xiyou Insights (西柚洞察 / 西柚找词) data for Amazon ASINs and search terms via the LinkFox tool gateway. The gateway forwards requests to Xiyou OpenAPI (

https://openapi.xiyouzhaoci.com

本skill通过LinkFox工具网关查询Xiyou Insights（西柚洞察/西柚找词）提供的亚马逊ASIN与搜索词数据。网关会将请求转发至西柚OpenAPI（

https://openapi.xiyouzhaoci.com

）。

Environment Variables (Required)

环境变量（必填）

本 skill 需要 三组凭证，缺一不可：

Variable	Required	Description
`LINKFOXAGENT_API_KEY`	Yes	LinkFox Agent API Key（与其它 LinkFox skill 相同）
`XIYOU_CLIENT_ID`	Yes	西柚 OpenAPI Client ID（16 位字符）
`XIYOU_CLIENT_SECRET`	Yes	西柚 OpenAPI Client Secret（24 位字符）

本skill需要三组凭证，缺一不可：

变量名	是否必填	描述
`LINKFOXAGENT_API_KEY`	是	LinkFox Agent API Key（与其他LinkFox skill通用）
`XIYOU_CLIENT_ID`	是	西柚OpenAPI Client ID（16位字符）
`XIYOU_CLIENT_SECRET`	是	西柚OpenAPI Client Secret（24位字符）

1. LinkFox API Key

前往 LinkFox API Key 申请文档获取 Key
写入环境变量
```
LINKFOXAGENT_API_KEY
```

前往 LinkFox API Key申请文档获取Key
将其写入环境变量
```
LINKFOXAGENT_API_KEY
```

2. 西柚找词 Client ID / Client Secret

2. 西柚找词Client ID / Client Secret

打开西柚洞察 OpenAPI 控制台
登录后在控制台创建或查看应用，复制 Client ID（16 位）与 Client Secret（24 位）
写入环境变量
```
XIYOU_CLIENT_ID
```
与
```
XIYOU_CLIENT_SECRET
```
请勿将 Secret 提交到 Git、写入 SKILL 参数或聊天记录；仅通过环境变量供本地脚本读取

打开西柚洞察OpenAPI控制台
登录后在控制台创建或查看应用，复制Client ID（16位）与Client Secret（24位）
将其写入环境变量
```
XIYOU_CLIENT_ID
```
与
```
XIYOU_CLIENT_SECRET
```
请勿将Secret提交到Git、写入SKILL参数或聊天记录；仅通过环境变量供本地脚本读取

3. 配置示例

macOS / Linux（当前终端会话）

bash

export LINKFOXAGENT_API_KEY="your-linkfox-api-key"
export XIYOU_CLIENT_ID="your-16-char-id"
export XIYOU_CLIENT_SECRET="your-24-char-secret"

macOS / Linux（持久化，写入
~/.zshrc
或
~/.bashrc
）

bash

echo 'export LINKFOXAGENT_API_KEY="your-linkfox-api-key"' >> ~/.zshrc
echo 'export XIYOU_CLIENT_ID="your-16-char-id"' >> ~/.zshrc
echo 'export XIYOU_CLIENT_SECRET="your-24-char-secret"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell（当前会话）

powershell

$env:LINKFOXAGENT_API_KEY = "your-linkfox-api-key"
$env:XIYOU_CLIENT_ID = "your-16-char-id"
$env:XIYOU_CLIENT_SECRET = "your-24-char-secret"

Windows（系统环境变量）：设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 新建上述三个用户变量。

Cursor / Agent 运行环境：在 IDE 或 Agent 所在环境的 env 配置中添加上述三个变量，否则脚本会报错并提示缺少哪一项。

脚本
scripts/xiyou.py
与
scripts/_xiyou_common.py
会自动把
XIYOU_CLIENT_ID
/
XIYOU_CLIENT_SECRET
注入请求 Body；调用时不要在
--params
里重复传
clientId
/
clientSecret
。

macOS / Linux（当前终端会话）

bash

export LINKFOXAGENT_API_KEY="your-linkfox-api-key"
export XIYOU_CLIENT_ID="your-16-char-id"
export XIYOU_CLIENT_SECRET="your-24-char-secret"

macOS / Linux（持久化，写入
~/.zshrc
或
~/.bashrc
）

bash

echo 'export LINKFOXAGENT_API_KEY="your-linkfox-api-key"' >> ~/.zshrc
echo 'export XIYOU_CLIENT_ID="your-16-char-id"' >> ~/.zshrc
echo 'export XIYOU_CLIENT_SECRET="your-24-char-secret"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell（当前会话）

powershell

$env:LINKFOXAGENT_API_KEY = "your-linkfox-api-key"
$env:XIYOU_CLIENT_ID = "your-16-char-id"
$env:XIYOU_CLIENT_SECRET = "your-24-char-secret"

Windows（系统环境变量）：设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 新建上述三个用户变量。

Cursor / Agent运行环境：在IDE或Agent所在环境的env配置中添加上述三个变量，否则脚本会报错并提示缺少哪一项。

脚本
scripts/xiyou.py
与
scripts/_xiyou_common.py
会自动把
XIYOU_CLIENT_ID
/
XIYOU_CLIENT_SECRET
注入请求Body；调用时不要在
--params
里重复传
clientId
/
clientSecret
。

Core Concepts

核心功能

西柚找词提供亚马逊 ASIN 维度 与 关键词维度 的流量、排名、ABA、竞争度等数据，典型用途：

ASIN 反查关键词：看某 ASIN 近 7 天或指定月份带来流量的搜索词
关键词分析：看某词下哪些 ASIN 占流量、排名与获得率
趋势分析：ASIN 流量得分、BSR、广告变动、词排名/流量随时间变化
选词辅助：关键词 ABA 周搜索量、竞争难度、建议 CPC

西柚找词提供亚马逊ASIN维度与关键词维度的流量、排名、ABA、竞争度等数据，典型用途：

ASIN反查关键词：查看某ASIN近7天或指定月份带来流量的搜索词
关键词分析：查看某词下哪些ASIN占据流量、排名与获得率
趋势分析：ASIN流量得分、BSR、广告变动、关键词排名/流量随时间变化
选词辅助：关键词ABA周搜索量、竞争难度、建议CPC

Supported Marketplaces

支持的站点

country

常用 2 位大写代码：

US

、

CA

、

MX

、

BR

、

UK

、

DE

、

ES

、

IT

、

FR

、

JP

、

AU

、

SA

、

AE

。默认

US

。

例外：

asinSearchTermRankTrendHourly

仅支持

US

、

UK

、

DE

。

country

常用2位大写代码：

US

、

CA

、

MX

、

BR

、

UK

、

DE

、

ES

、

IT

、

FR

、

JP

、

AU

、

SA

、

AE

。默认值为

US

。

例外：

asinSearchTermRankTrendHourly

仅支持

US

、

UK

、

DE

。

API Usage

API使用方法

完整参数与响应结构：references/api.md
命令行（在本 skill 根目录执行）：

bash

python scripts/xiyou.py --list-apis
python scripts/xiyou.py --api asinResearchPeriod --params '{"country":"US","asin":"B06XZTZ7GB","page":1,"pageSize":50}'
python scripts/xiyou.py --api searchTermInfo --params '{"country":"US","searchTerms":"yoga mat,fitness mat"}'

网关路径：

POST https://tool-gateway.linkfox.com/xiyou/<apiName>

完整参数与响应结构：references/api.md
命令行（在本skill根目录执行）：

bash

python scripts/xiyou.py --list-apis
python scripts/xiyou.py --api asinResearchPeriod --params '{"country":"US","asin":"B06XZTZ7GB","page":1,"pageSize":50}'
python scripts/xiyou.py --api searchTermInfo --params '{"country":"US","searchTerms":"yoga mat,fitness mat"}'

网关路径：

POST https://tool-gateway.linkfox.com/xiyou/<apiName>

API Quick Index

API快速索引

`--api`	用途
`asinTraffic`	批量 ASIN 近 7 天流量得分
`asinInfo`	批量 ASIN 商品信息
`asinResearchPeriod`	ASIN 反查关键词（最近天）
`asinResearchMonthly`	ASIN 反查关键词（月）
`searchTermAnalysisPeriod`	关键词下 ASIN 分析列表
`searchTermInfo`	关键词信息（ABA、竞争度、CPC）
`searchTermAbaWeeklyTrend`	关键词 ABA 周趋势
`asinSearchTermTrafficTrend`	ASIN+词流量趋势（天）
`asinSearchTermRankTrendDaily`	ASIN+词排名趋势（天）
`asinSearchTermRankTrendHourly`	ASIN+词排名趋势（小时）
`asinTrafficScoreTrend`	ASIN 流量得分趋势（天）
`asinBsrTrend`	ASIN BSR 趋势（天）
`asinOrdersTrend`	ASIN 订单量趋势（月）
`asinVariations`	ASIN 变体关系
其它	见 `--list-apis` 与 `references/api.md`

`--api` 参数	用途
`asinTraffic`	批量ASIN近7天流量得分
`asinInfo`	批量ASIN商品信息
`asinResearchPeriod`	ASIN反查关键词（最近7天）
`asinResearchMonthly`	ASIN反查关键词（月度）
`searchTermAnalysisPeriod`	关键词下ASIN分析列表
`searchTermInfo`	关键词信息（ABA、竞争度、CPC）
`searchTermAbaWeeklyTrend`	关键词ABA周趋势
`asinSearchTermTrafficTrend`	ASIN+关键词流量趋势（按天）
`asinSearchTermRankTrendDaily`	ASIN+关键词排名趋势（按天）
`asinSearchTermRankTrendHourly`	ASIN+关键词排名趋势（按小时）
`asinTrafficScoreTrend`	ASIN流量得分趋势（按天）
`asinBsrTrend`	ASIN BSR趋势（按天）
`asinOrdersTrend`	ASIN订单量趋势（按月）
`asinVariations`	ASIN变体关系
其它	详见 `--list-apis` 与 `references/api.md`

How to Build Queries

查询构建指南

选接口：反查词 →

asinResearchPeriod

asinResearchMonthly

；查词下竞品 →

searchTermAnalysisPeriod

；词属性 →

searchTermInfo

searchTermAbaWeeklyTrend

站点：用户说「美国站」→
```
country: "US"
```
；未指定默认
```
US
```

ASIN：10 位，如

B06XZTZ7GB

；批量接口用

entities: [{"country":"US","asin":"..."}]

日期：天趋势用

startDate

endDate

（

YYYY-MM-DD

）；月趋势用

startMonth

endMonth

（

YYYY-MM

）

分页：列表类接口用
```
page
```
、
```
pageSize
```
（最大 10000）
排序：
```
sortField
```
+
```
sortOrder
```
（
```
asc
```
/
```
desc
```
），可选值见
```
references/api.md
```
各接口说明

选择接口：反查关键词 →

asinResearchPeriod

asinResearchMonthly

；查询词下竞品 →

searchTermAnalysisPeriod

；关键词属性 →

searchTermInfo

searchTermAbaWeeklyTrend

站点设置：用户说「美国站」→
```
country: "US"
```
；未指定则默认
```
US
```

ASIN格式：10位字符，如

B06XZTZ7GB

；批量接口使用

entities: [{"country":"US","asin":"..."}]

日期参数：按天趋势使用
```
startDate
```
/
```
endDate
```
（格式
```
YYYY-MM-DD
```
）；按月趋势使用
```
startMonth
```
/
```
endMonth
```
（格式
```
YYYY-MM
```
）
分页设置：列表类接口使用
```
page
```
、
```
pageSize
```
（最大10000）
排序设置：
```
sortField
```
+
```
sortOrder
```
（
```
asc
```
/
```
desc
```
），可选值见
```
references/api.md
```
各接口说明

Example Scenarios

示例场景

反查 ASIN 近 7 天流量词（按流量降序）

json

{"country": "US", "asin": "B06XZTZ7GB", "page": 1, "pageSize": 100, "sortField": "traffic", "sortOrder": "desc"}

查关键词下 Top ASIN

json

{"searchTerm": "yoga mat", "country": "US", "page": 1, "pageSize": 50}

批量查 ASIN 流量得分

json

{"entities": [{"country": "US", "asin": "B06XZTZ7GB"}, {"country": "US", "asin": "B0XXXXXXXX"}]}

反查ASIN近7天流量词（按流量降序）

json

{"country": "US", "asin": "B06XZTZ7GB", "page": 1, "pageSize": 100, "sortField": "traffic", "sortOrder": "desc"}

查询关键词下Top ASIN

json

{"searchTerm": "yoga mat", "country": "US", "page": 1, "pageSize": 50}

批量查询ASIN流量得分

json

{"entities": [{"country": "US", "asin": "B06XZTZ7GB"}, {"country": "US", "asin": "B0XXXXXXXX"}]}

Display Rules

展示规则

列表类结果优先表格展示：关键词/ASIN、流量、排名、占比等核心字段
趋势类结果建议时间序列展示，标注峰值与变化方向
失败时根据
```
error
```
/ 网关响应说明原因；常见：环境变量未配置、ASIN 格式错误、日期区间无效、站点不支持

列表类结果优先以表格展示：关键词/ASIN、流量、排名、占比等核心字段
趋势类结果建议以时间序列展示，标注峰值与变化方向
调用失败时根据
```
error
```
/网关响应说明原因；常见原因：环境变量未配置、ASIN格式错误、日期区间无效、站点不支持

Important Limitations

重要限制

须同时配置 LinkFox Key 与西柚 Client 凭证
```
asinSearchTermRankTrendHourly
```
仅 US/UK/DE
批量 ASIN 接口
```
entities
```
最多 100 个；
```
searchTerms
```
逗号分隔最多 100 个词
大结果集优先用下方 Large Response 模式落盘读取

必须同时配置LinkFox Key与西柚Client凭证
```
asinSearchTermRankTrendHourly
```
仅支持US/UK/DE站点
批量ASIN接口
```
entities
```
最多支持100个；
```
searchTerms
```
用逗号分隔最多支持100个关键词
大结果集优先使用下方大响应处理模式落地读取

User Expression & Scenario Quick Reference

用户表述与场景速查

User Says	API / Scenario
「这个 ASIN 有哪些流量词」	`asinResearchPeriod`
「这个词下哪些 ASIN 在抢流量」	`searchTermAnalysisPeriod`
「关键词搜索量/ABA 趋势」	`searchTermAbaWeeklyTrend` / `searchTermInfo`
「ASIN 流量得分多少」	`asinTraffic`
「某个词排名怎么变」	`asinSearchTermRankTrendDaily`
「BSR 历史」	`asinBsrTrend`

Not applicable: 非亚马逊平台、Jungle Scout/卖家精灵等其它数据源、SP-API 订单/库存、Temu/Shopee 选品。

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

The functionality or purpose described in this skill does not match actual behavior
The skill's results do not match the user's intent
The user expresses dissatisfaction or praise about this skill
Anything you believe could be improved

Call the feedback API as specified in

references/api.md

. Do not interrupt the user's flow.

用户表述	API/场景
「这个ASIN有哪些流量词」	`asinResearchPeriod`
「这个词下哪些ASIN在抢流量」	`searchTermAnalysisPeriod`
「关键词搜索量/ABA趋势」	`searchTermAbaWeeklyTrend` / `searchTermInfo`
「ASIN流量得分多少」	`asinTraffic`
「某个词排名怎么变」	`asinSearchTermRankTrendDaily`
「BSR历史数据」	`asinBsrTrend`

不适用场景：非亚马逊平台、Jungle Scout/卖家精灵等其它数据源、SP-API订单/库存、Temu/Shopee选品。

反馈机制：

当出现以下任一情况时，通过Feedback API自动检测并提交反馈：

本skill描述的功能或用途与实际行为不符
skill的结果不符合用户意图
用户表达对本skill的不满或赞赏
任何你认为可以改进的地方

请按照

references/api.md

中的说明调用反馈API，请勿打断用户的操作流程。

Handling Large Responses

大响应处理

To avoid overflowing the agent context, persist the response to disk and extract only the fields you need:

python scripts/response_io.py run --script scripts/xiyou.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

Pick
--out-dir
outside any git working tree (e.g.
/tmp/...
on Unix,
%TEMP%/...
on Windows). Persisted responses may contain PII, pricing, or auth-sensitive data — do not commit them. Files are not auto-deleted; clean up when the task is done.

run

writes the full response to a file and emits only a schema preview + file path.

read

projects specific fields, with

--limit/--offset

for slicing and

--format json|jsonl|csv|table

for output.

When to prefer this pattern — apply your judgment based on the response characteristics, e.g.:

High field count per record, or fields you don't need
Batch/paginated results (multiple items per call)
Long-text fields (descriptions, reviews, HTML, time series)
Output reused across later steps rather than consumed immediately

For small, single-use responses, calling the main script directly is fine.

⚠️ The preview is a truncated schema + sample, not the full data. Any field-level decision must read from the persisted file via

read

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

为避免超出Agent上下文限制，可将响应持久化到磁盘并仅提取所需字段：

python scripts/response_io.py run --script scripts/xiyou.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # 或使用 --path "<JMESPath>"

请将
--out-dir
设置在Git工作区之外（例如Unix系统的
/tmp/...
，Windows系统的
%TEMP%/...
）。持久化的响应可能包含个人身份信息、定价或敏感认证数据——请勿提交到Git。文件不会自动删除，任务完成后请自行清理。

run

命令会将完整响应写入文件，并仅输出模式预览+文件路径。

read

命令会提取指定字段，支持

--limit/--offset

进行切片，以及

--format json|jsonl|csv|table

设置输出格式。

何时优先使用该模式——根据响应特征判断，例如：

每条记录字段数量多，或包含不需要的字段
批量/分页结果（单次调用返回多个条目）
长文本字段（描述、评论、HTML、时间序列）
输出结果需在后续步骤复用而非立即使用

对于小型、单次使用的响应，直接调用主脚本即可。

⚠️ 预览内容是截断的模式+示例，并非完整数据。任何字段级的决策必须通过

read

命令从持久化文件读取。

如需更多高质量的专业跨境电商skill，请访问LinkFox Skills。