虾多拉-Shopee选品和关键词分析工具

概述

通过 Shopdora OpenAPI 帮助用户在 Shopee 各站点进行跨境电商数据分析，覆盖关键词挖掘、选产品、评论抓取、类目浏览、余额查询等场景。

重要前提：使用此 Skill 需要先在 Shopdora 官网 注册帐号并开通 API 服务。该服务为付费服务，具体价格请联系官网的企业微信获取。

典型使用场景

你可以直接用自然语言提问，例如：

• "泰国站美妆类目最热卖的产品有哪些？"
• "帮我看新加坡站手机壳的热门关键词"
• "我账号还剩多少配额？"
• "查一下台湾站这个商品的评论，商品 ID 是 xxx"
• "马来西亚站有哪些类目？"

前置条件：凭证配置

检查配置文件

在执行任何 API 调用之前，先检查本地是否存在凭证配置文件 ~/.shopdora/config.json：

cat ~/.shopdora/config.json 2>/dev/null

首次使用 — 引导用户配置

如果配置文件不存在，直接回复用户：

> 当前服务为付费服务，请在官网 https://www.shopdora.com 联系官方客服，获取 token。获取后将 clientId 和 clientSecret 告诉我，我会帮你配置好。

收到凭证后，创建配置文件：

mkdir -p ~/.shopdora

然后写入含凭证的 JSON（clientId 和 clientSecret 由用户提供）。

配置文件格式

{
  "clientId": "std_xxxxxxxx",
  "clientSecret": "your_secret_here"
}

站点名称映射

用户可能用中文名而非代码表示站点。收到用户输入后，按以下映射自动转换为 API 所需的站点代码：

如果用户没有指定站点，主动询问需要在哪个站点查询。

核心工作流

标准调用链路：无论用户请求什么功能，统一按以下顺序执行：

1. 检查凭证 → 读取 ~/.shopdora/config.json
2. 获取 token → 检查 ~/.shopdora/token.json 是否有效，无效则重新获取
3. 检查本地缓存 → 24 小时内相同请求优先从缓存读取，不扣费（见下方「本地缓存」章节）
4. 确认关键参数 → 调用计费接口前，必须向用户确认站点、关键词、时间范围等输入（见下方「调用前确认」章节）
5. 可选：查询余额 → 执行前可选查询余额确认配额充足
6. 执行用户请求 → 根据用户意图调用对应接口（关键词/产品/评论/类目）
7. 存入缓存并展示结果 → 成功后写入缓存，以表格或结构化格式清晰呈现

知识缺失时自动提问

遇到以下未对齐或不明确的情况，必须先向用户提问确认，不得自行推断：

调用前确认（防止无效消耗）

调用付费接口（关键词、选产品、评论）前，必须先向用户确认关键参数，避免参数不对导致浪费。

确认示例：

> 即将调用关键词挖掘接口（计费）：
> - 站点：新加坡（sg）
> - 关键词：phone case
> - 搜索量范围：1000 ~ 50000
> - 排序：按搜索量降序
>
> 确认执行吗？

用户确认后再调用 API。

失败/空结果处理规则（严禁自动重试）

计费接口返回失败或空结果时，严禁以下行为：

• ❌ 自动更换关键词重新搜索
• ❌ 自动翻页拉取更多数据
• ❌ 自动修改站点、价格区间、时间范围等参数重试
• ❌ 更换排序方式重新请求

正确做法：

• 空结果 → 告知用户当前条件下未找到数据，建议用户调整条件后告知你
• 失败（code ≠ 0000）→ 按错误码表处理，仅在 token 失效（9990）时自动重试
• 用户要求翻页或继续检索 → 先告知会产生额外消耗，确认后再执行

例如用户说"再看看下一页"时回复：

> 翻页会消耗 1 次配额（当前剩余 X 次），确认继续吗？

本地缓存（24h）

为减少重复消耗，所有计费接口的成功响应写入本地缓存。

缓存位置：~/.shopdora/cache/

缓存文件命名：{接口名}_{site}_{参数MD5}.json
- 示例：keyword_sg_a1b2c3d4.json、product_th_e5f6g7h8.json

缓存逻辑：

1. 调用 API 前，先计算请求参数的 MD5（site + 各查询参数序列化为 JSON 字符串后取 MD5）
2. 检查 ~/.shopdora/cache/ 下是否存在对应文件
3. 如存在且修改时间在 24 小时内 → 直接读取缓存，告知用户"来自缓存（X 小时前）"，不调用 API
4. 如不存在或已过期 → 调用 API，成功后写入/更新缓存文件
5. 查询余额（不限流不计费）和获取 token（不计费）不缓存

工作流 1：获取 access_token

所有计费接口调用前必须先获取有效的 access_token。

token 持久化机制：

token 存储在 ~/.shopdora/token.json，格式为：

{
  "accessToken": "a1b2c3d4e5f6...",
  "tokenType": "Bearer",
  "expiresIn": 2678400,
  "obtainedAt": 1753718400
}

token 获取与验证流程：

1. 先尝试读取 ~/.shopdora/token.json
2. 如果文件存在，检查 obtainedAt + expiresIn > 当前时间戳，有效则直接使用
3. 如果文件不存在或已过期，从 ~/.shopdora/config.json 读取凭证，调用 token 接口
4. 将新 token 和获取时间写入 ~/.shopdora/token.json
5. 后续所有 API 请求都从 token.json 读取 accessToken

调用 API：

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/token' \
  -H 'Content-Type: application/json' \
  -d '{"clientId":"<从配置文件读取>","clientSecret":"<从配置文件读取>"}'

token 续期规则：

• token 有效约 31 天，过期前需重新获取
• 任何 API 返回 9990 时，自动删除 token.json 并重新获取 token，然后重试原请求
• 通过 /standard/queryBalance 的 tokenExpiresIn 字段可查看精确到期时间

工作流 2：查询余额

在用户要求查询余额、开始大量调用前、或会话开始时主动查询。

调用 API：

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/queryBalance' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>'

结果展示格式（必须清晰呈现以下关键信息）：

📊 账户信息
- 客户名称：{clientName}
- 账户状态：{accountStatus}
- Token 到期：{tokenExpiresIn}

💰 配额使用情况
- 周期：{periodStart} ~ {periodEnd}
- 已用 / 上限：{quotaUsed} / {quotaLimit}（剩余 {quotaRemaining} 次）

⚡ 限流状态
- 分钟限流：{rateLimitPerMinute} 次/分钟
- 当前分钟已用：{rateLimitUsedThisMinute} 次

工作流 3：关键词挖掘

当用户要查找某个品类或产品的热门搜索词时使用。

执行前检查：先查 24h 缓存，再向用户确认参数（站点、关键词、筛选条件），确认后再调用 API。失败/空结果不得自动重试。

必传参数：site
常用可选参数：keyword、cateIds、searchVolume、sortBy

调用 API：

先根据「站点名称映射」确定 site 代码，确认用户需要的筛选条件，然后调用：

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/keyword/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
    "site": "<site>",
    "keyword": "<keyword>",
    "searchVolume": {"min": <min>, "max": <max>},
    "sortBy": "<sortBy>",
    "orderBy": 1,
    "pageNum": 1,
    "pageSize": 20
  }'

结果展示：以表格形式列出关键词，包含 searchVolume、searchVolumeIncRate、productNum、avgPrice、avgRating 等关键指标。若结果较多，提示用户可翻页查看。

工作流 4：选产品

当用户要发现和分析 Shopee 上的热门产品、竞品时使用。

执行前检查：先查 24h 缓存，再向用户确认参数（站点、关键词/类目、价格区间、时间范围），确认后再调用 API。失败/空结果不得自动重试。

必传参数：site、month
常用可选参数：keyword、cateIds、price、salesM、shelfTimeRange、sortBy

month 参数说明：
- 30 → 近 30 天视图（最常用）
- 202603 → 指定月份视图

price 参数说明：
- 值为实际价格 × 100000，例如 9.9 元填 990000

调用 API：

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/product/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
    "site": "<site>",
    "month": 30,
    "keyword": "<keyword>",
    "sortBy": "salesM",
    "orderBy": 1,
    "pageNum": 1,
    "pageSize": 20
  }'

结果展示：
- 以表格列出商品，包含 name、price（需除以 100000 显示本土货币）、salesM、salesGrowthRateM、cateRank、shopType 等
- price 字段需要除以 100000 后展示为当地货币价格
- salesGrowthRateM 需要除以 100 展示为百分比
- ratingScore 需要除以 10 展示为星级
- shopType 转换：0→普通店铺，1→优选店铺，2→MALL

工作流 5：评论抓取与分析

当用户要查看某个商品的买家评价、分析用户反馈时使用。

执行前检查：先查 24h 缓存，再向用户确认参数（站点、shopId、itemId），确认后再调用 API。失败/空结果不得自动重试。

必传参数：site、shopId、itemId、limit、offset

调用 API：

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/comment/get' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
    "site": "<site>",
    "shopId": <shopId>,
    "itemId": <itemId>,
    "limit": 20,
    "offset": 0
  }'

分页逻辑：
- 每页最多 20 条，offset 从 0 开始，上限 3000
- 读取响应 data.data.has_more，为 true 时 offset += limit 继续拉取
- 用户要求"更多"时自动翻页

结果展示：
- 先展示评价汇总：总评价数、综合星级、各星级分布
- 以列表展示每条评价：星级、用户名、评价内容（截取前 150 字）、点赞数、是否有图片
- ctime 为 Unix 秒，需转换为可读时间
- 若评价含 template_tags，展示标签信息

工作流 6：类目查询

当用户需要浏览某个站点的商品类目树时使用。

调用 API：

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/cate/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{"site":"<site>","cateId":0}'

注意：响应 data 为 JSON 字符串，需要先 JSON.parse 再展示。

结果展示：以缩进层级展示类目树结构，标注叶子节点。

站点代码速查

错误处理

重要提醒

1. 付费服务：关键词挖掘、选产品、评论抓取三个接口每次成功调用（返回非空数据）扣 1 次配额。查询余额和类目浏览不扣费。
2. 调用前确认：任何计费接口调用前，必须先向用户确认站点、关键词、时间范围等关键参数，不得自动推断。
3. 禁止自动重试：失败或空结果时严禁自动更换关键词、翻页、修改参数重试。仅在 token 失效（9990）时可自动刷新 token 后重试。
4. 翻页/继续检索需告知：用户要求翻页或补充检索时，必须先告知会产生额外配额消耗，确认后再执行。
5. 24h 本地缓存：所有计费接口成功响应缓存到 ~/.shopdora/cache/，24 小时内相同请求直接读缓存，不消耗配额。
6. 配额意识：调用计费接口后告知用户本次消耗和剩余配额。
7. 价格字段：product/search 中的 price 系列字段需除以 100000 才为本土货币价格。
8. 数据刷新：关键词数据非实时，依赖平台的刷新周期。
9. 分页上限：评论 offset 上限 3000。

参考资料

详细的 API 字段说明和请求/响应示例，见 references/api_docs.md。在需要精确字段定义、参数边界、或完整的响应 JSON 结构时，通过 Read 工具加载该文件。