辛泽俄罗斯选品专家skill · Seerfar Open API

> 技术标识：seerfar-open-api（与「辛泽俄罗斯选品专家」专家配套使用，两份副本内容一致）

直连 Seerfar 官方 Open API，覆盖 Ozon 与 Wildberries 双平台，无第三方网关中转。

🔑 第 0 步（强制）：先确认 API Key

任何取数动作之前，必须先确认 SEERFAR_API_KEY 是否已配置。 这是不可跳过的第一步。

检查顺序

1. 读本 skill 的 config/.env 中的 SEERFAR_API_KEY
2. 读用户级共享配置 ~/.workbuddy/seerfar.env
3. 读环境变量 SEERFAR_API_KEY
4. 若都未配置 → 立即向操作者索要，并停止后续动作

> 为什么有用户级共享配置：本 skill 可能同时存在两份副本——专家包内置副本（<专家包>/skills/seerfar-open-api/）与独立安装副本（~/.workbuddy/skills/seerfar-open-api/）。把 Key 写入 ~/.workbuddy/seerfar.env 可让两份副本共用同一份配置，只需配置一次。

索要话术（直接使用）

开始查询前，我需要你的 Seerfar API Key。

请在 Seerfar 官网 → 个人中心 → API Key 管理 中获取，
然后把它配置到以下任一位置：

  方式一（推荐，一次配置两处通用）：
    在 ~/.workbuddy/seerfar.env 中写入：
      SEERFAR_API_KEY=你的key

  方式二（仅本 skill 副本生效）：
    在本 skill 的 config/.env 中写入：
      SEERFAR_API_KEY=你的key

  方式三：设置环境变量 SEERFAR_API_KEY

配置好告诉我，我先调用 /open-api/quota 验证连通性并读取积分余额。

提醒：请勿把 Key 直接贴在对话里。Key 只写进配置文件，我不会把它写进任何输出或日志。

铁律

首调用示例

curl "http://api.seerfar.cn/open-api/quota" \
  -H "Authorization: Bearer $SEERFAR_API_KEY"

返回：

{"code":200,"msg":"SUCCESS","data":{"creditLimit":100,"creditUsed":23,"freeCreditLimitMonth":0,"freeCreditUsedMonth":0}}

报告格式：已连通。付费积分总量 100，已用 23，剩余 77。

接入信息

平台对称性：wb-* 端点与对应 ozon-* 端点请求体结构对称，字段名基本一致。

端点速查（29 个）

账户

店铺

商品

类目

榜单

关键词

调用规范（硬约束）

限流

• 统一 3 次/3 秒（quota 为 1 次/3 秒）
• 批量调用必须串行，每次间隔 ≥ 3 秒
• 收到 429 → 退避 ≥3 秒后重试，最多 2 次

积分

• 调用前先查 /open-api/quota
• 单任务预估 > 100 积分 → 先报告预估消耗并等待确认
• 收到 8000 → 立即停止，提示充值

分页

• page.pageSize 最大 100，默认 20
• page.pageNumber 从 1 开始
• 需要更多数据时按需翻页，不要盲目拉满

参数陷阱

排序字段速查（page.orders.field）

错误码处置

排障细节见 references/troubleshooting.md。

脚本用法

通用入口（推荐，跨平台）

Python 标准库实现，无需 curl，Windows / macOS / Linux 通用：

python scripts/seerfar.py <METHOD> <PATH> ['<JSON_BODY>']

示例：

# 查积分（无 body）
python scripts/seerfar.py GET /open-api/quota

# 查类目商品
python scripts/seerfar.py POST /open-api/category/detail/search/ozon '{
  "categoryId":"15621032_15621049_115951147",
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"revenue","direction":"DESC"}]}
}'

seerfar.py 的额外能力：

Windows 入口（.cmd）

Windows 原生入口，与 .py / .sh 一一对应、行为一致（先 chcp 65001 保证俄语与中文不乱码）：

scripts\seerfar.cmd GET /open-api/quota
scripts\quota.cmd
scripts\ozon-category.cmd --body-file body.json

解释器优先取 SEERFAR_PYTHON，其次 PYTHON，最后用 PATH 上的 python。
JSON 里含双引号时，用 --body-file 传文件最稳（cmd 的转义规则极易出错）。

> ⚠️ .cmd 不进 SkillHub 分发包（平台不接受该扩展名）。若你的副本里没有 .cmd，
> 直接 python scripts/<name>.py ... 即可，功能完全一致；确需 .cmd 时按下面模板自行生成
> （把 <NAME> 换成 seerfar / quota / ozon-category / ozon-shop 等）：

@echo off
setlocal
chcp 65001 >nul
set "DIR=%~dp0"
set "PY=%SEERFAR_PYTHON%"
if "%PY%"=="" set "PY=%PYTHON%"
if "%PY%"=="" set "PY=python"
"%PY%" "%DIR%<NAME>.py" %*
exit /b %ERRORLEVEL%

语义化快捷脚本

python scripts/quota.py

python scripts/ozon-product-report.py '{
  "monthlySales":{"min":500},
  "price":{"max":2000},
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"sales","direction":"DESC"}]}
}'

python scripts/ozon-category.py '{
  "categoryId":"15621032_15621049_115951147",
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"revenue","direction":"DESC"}]}
}'

python scripts/ozon-shop.py '{
  "id":118364,
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"revenue","direction":"DESC"}]}
}'

python scripts/ozon-product-detail.py '{"sku":"175924376","dateRange":"past_30_days"}'

python scripts/ozon-keyword-mining.py '{
  "keyword":"наушники беспроводные",
  "matchType":0,
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"relevancy","direction":"DESC"}]}
}'

python scripts/ozon-keyword-back.py '{
  "skuIds":[175924376,149222760],
  "hasVariant":1,
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"exposure","direction":"DESC"}]}
}'

python scripts/ozon-market-keyword.py '{
  "searchVolume":{"min":30000},
  "page":{"pageNumber":1,"pageSize":20,"orders":[{"field":"searchVolume","direction":"DESC"}]}
}'

> 每个快捷脚本都是 seerfar.py 的薄包装，支持透传 --pretty / --save / --field / --no-throttle。
> .sh 版本等价于 python <name>.py "$@"，仅作为习惯用 bash 时的入口。
> 需要 WB 数据时，把路径末段 /ozon 换成 /wb，参数结构不变。

脚本行为约定

• 自动从 config/.env → 环境变量 读取 SEERFAR_API_KEY
• Key 缺失时报错退出并打印索要话术，不发起请求
• 自动节流（两次调用间隔 ≥3 秒）
• 统一输出格式化 JSON 到 stdout
• 非 200 响应以非零退出码返回，并打印错误码含义
• 不把 Key 写入 stdout、stderr、日志或文件
• pageSize 超过 100 时在发请求前直接拦截（不发请求、不消耗积分），对应「红线」第 6 条

退出码

场景 → 端点映射（选了就用）

分平台参数差异（避坑）

> WB 数据集以 Ozon 为主干，WB 行在可用时返回；部分端点无平台过滤入参，需客户端侧过滤。

输出规范

1. 金额单位：₽（卢布）
2. 指标标注：必须写英文 API 字段名 + 中文释义
3. 关键词：俄语原文 + 中文释义双列，不允许只给中文
4. 时间口径：注明数据月份或「近 30 天」
5. 置信度：每次输出标注 高/中/低
6. 风险提示：第三方估算数据，与平台后台可能有偏差

红线

1. 不把 API Key 写入任何输出、日志或交付文件
2. 未配置 Key 时不发起业务请求
3. 不编造 API 未返回的数值
4. 不做收益承诺（不说「必赚」「稳赚」）
5. 不协助侵权、仿品、违禁品类
6. pageSize 不超过 100
7. 批量调用不并发

References