Skills 1688-product-search

Name: 1688-product-search
Author: openclaw

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/1688aiinfra/1688-product-search" ~/.claude/skills/openclaw-skills-1688-product-search && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/1688aiinfra/1688-product-search" ~/.openclaw/skills/openclaw-skills-1688-product-search && rm -rf "$T"

manifest: skills/1688aiinfra/1688-product-search/SKILL.md

1688商品搜索SKILL

通过1688开放平台官方API提供完整的商品搜索能力，包含9个核心接口。

鉴权说明

每个 Skill 内置独立的鉴权模块（

scripts/auth.py

），不依赖任何外部 Skill。

所有 1688 Skill 的 Token 缓存指向同一个固定路径，实现"独立运行 + 鉴权只发生一次"。

Token 缓存路径:
```
skills/.1688_token_cache.json
```
（所有 1688 Skill 共用）
任意一个 Skill 首次请求完成鉴权后，其他 Skill 直接复用缓存
Token 过期前自动用 refresh_token 刷新
支持
```
ALI1688_REFRESH_TOKEN
```
（自动刷新）和
```
ALI1688_ACCESS_TOKEN
```
（直接使用）两种模式

配置

在 OpenClaw config 中设置环境变量：

{
 skills: {
 entries: {
 "1688-product-search": {
 env: {
 ALI1688_APP_KEY: "your-app-key",
 ALI1688_APP_SECRET: "your-app-secret", 
 ALI1688_REFRESH_TOKEN: "your-refresh-token"
 }
 }
 }
 }
}

如何获取 AppKey / AppSecret / Token

如果遇到 Token 相关错误（如 401、签名失败、Token 过期），按以下步骤操作：

Step 1：注册开发者 & 创建应用 → 获取 AppKey + AppSecret

打开 1688开放平台，用1688账号登录
进入控制中心
点击「我的应用」→「创建应用」
填写应用信息，提交审核
审核通过后，在应用详情页可以看到 AppKey 和 AppSecret

Step 2：订购解决方案 → 获取 API 调用权限

打开跨境ERP/独立站SaaS数字化解决方案
点击「立即订购」，将解决方案绑定到你的应用
订购成功后，应用才有权限调用方案内的 API

Step 3：用户授权 → 获取 access_token + refresh_token

在浏览器中访问授权页面（替换 YOUR_APPKEY 和 YOUR_REDIRECT_URI）：

https://auth.1688.com/oauth/authorize?client_id=YOUR_APPKEY&site=1688&redirect_uri=YOUR_REDIRECT_URI

用1688账号登录并同意授权
页面会跳转到你的回调地址，URL 中带有
```
code
```
参数
用 code 换取 Token（有效期短，需在10分钟内使用）：

curl -X POST "https://gw.open.1688.com/openapi/param2/1/system.oauth2/getToken/YOUR_APPKEY" \
-d "grant_type=authorization_code" \
-d "need_refresh_token=true" \
-d "client_id=YOUR_APPKEY" \
-d "client_secret=YOUR_APPSECRET" \
-d "redirect_uri=YOUR_REDIRECT_URI" \
-d "code=授权码"

返回结果中包含：

```
access_token
```
— 用于调用 API（有效期约10小时）
```
refresh_token
```
— 用于刷新 access_token（有效期约半年）

Step 4：配置到环境变量

```
ALI1688_APP_KEY
```
= 应用的 AppKey
```
ALI1688_APP_SECRET
```
= 应用的 AppSecret
```
ALI1688_REFRESH_TOKEN
```
= 上一步获得的 refresh_token（推荐，支持自动刷新）
```
ALI1688_ACCESS_TOKEN
```
= 上一步获得的 access_token（备用，过期需手动换）

常见 Token 错误及解决

错误	原因	解决方案
`HTTP 400` 刷新失败	refresh_token 无效或已过期	重新走 Step 3 授权，获取新的 refresh_token
`HTTP 401` 未授权	access_token 过期或无效	设置 ALI1688_REFRESH_TOKEN 启用自动刷新
`签名错误(code=25)`	AppSecret 不正确	检查 ALI1688_APP_SECRET 是否与应用详情页一致
`无权限调用`	未订购解决方案	回到 Step 2 订购对应解决方案
`refresh_token 半年后过期`	Token 自然过期	重新走 Step 3 授权

参考链接

使用方法

1. 类目查询

# 查询所有一级类目（英语）
python3 scripts/product_search.py category 0

# 查询中文类目
python3 scripts/product_search.py category 0 --language en

2. 多语言关键词搜索

# 英文关键词搜索
python3 scripts/product_search.py keyword-search "dress" --country en

# 中文关键词搜索
python3 scripts/product_search.py keyword-search "连衣裙" --country en

# 带筛选条件的搜索
python3 scripts/product_search.py keyword-search "dress" --country en --filter "shipIn48Hours,shipIn24Hours" --sort '{"price":"asc"}'

3. 多语言图片搜索

图片搜索支持三种方式，优先级：本地图片文件 > imageId > 图片URL

# 方式一：本地图片文件（推荐）
# 自动压缩（>300KB）→ base64编码 → 上传获取imageId → 图搜
python3 scripts/product_search.py image-search --image-path "/path/to/your/image.jpg" --country en

# 方式二：图片URL（直接用 imageAddress 字段图搜，无需上传）
python3 scripts/product_search.py image-search --image-url "https://example.com/image.jpg" --country en

# 方式三：已有 imageId（由 upload-image 接口返回）
python3 scripts/product_search.py image-search "your_image_id" --country en

# 上传图片获取imageId（单独使用）
python3 scripts/product_search.py upload-image "/path/to/your/image.jpg"

当用户发送图片文件或截图时的处理流程：

⚠️ 注意：1688图片上传接口（
product.image.upload
）的
imageBase64
方式仅支持1688平台自身的图片，对本地截图/外部图片会返回无效 imageId（
"0"
）。

推荐处理策略：

询问用户图片的原始来源 URL
若 URL 包含
```
alicdn.com
```
，直接用
```
imageAddress
```
字段图搜（已验证有效）
若 URL 不包含
```
alicdn.com
```
，先下载到本地，再 base64 上传尝试获取 imageId；若 imageId 仍为
```
"0"
```
，降级用
```
imageAddress
```
图搜

本地文件 base64 上传流程（仅供参考，成功率有限）：

若图片大于 300KB，先用 Pillow 压缩（先调质量，再缩分辨率），再 base64 编码

调用

product.image.upload

接口（

uploadImageParam

字段包装，内含

imageBase64

）上传

若返回有效 imageId（非
```
"0"
```
），用 imageId 图搜；否则降级用
```
imageAddress
```
图搜

当用户提供图片 URL 时的处理流程：

判断图片 URL 的域名：
- 是
  alicdn.com
  域名（如
```
cbu01.alicdn.com
```
  、
```
img.alicdn.com
```
  等）：直接用
```
imageAddress
```
  字段传入图搜接口，无需下载
- 非
  alicdn.com
  域名（如用户上传的图片、其他电商平台图片等）：先将图片下载到本地临时文件，再走本地文件图搜流程（压缩 → base64 → 上传 → imageId → 图搜）

4. 多语言商品详情

⚠️ 注意：该接口每次只支持查询 1 个商品，不支持批量查询多个商品ID。

# 查询单个商品详情
python3 scripts/product_search.py product-detail "offer_id"

5. 多语言商品店铺搜索

# 根据商家ID搜索商品
python3 scripts/product_search.py shop-search "seller_open_id" --country en

6. 多语言商品推荐

# 基于关键词的商品推荐
python3 scripts/product_search.py offer-recommend "keyword" --country en

7. 品池商品拉取

从业务定制的品池中拉取商品列表，需要有品池访问权限。分页查询时需固定同一个

taskId

。

# 拉取品池商品（offerPoolId 和 taskId 为必填）
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --page-no 1 --page-size 10

# 指定类目和排序
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --cate-id 11 --sort-field order1m --sort-type DESC --page-no 1 --page-size 10

请求参数：

参数	类型	必填	描述	示例值
`--pool-id`	Long	✅	品池ID（业务定制且有权限控制，从对接的业务获取，随便传会报错，寻源通代采建议走词搜接口）	111
`--task-id`	String	✅	查询任务ID，分页查询时需固定同一个 taskId（如货盘有10000商品，每页1000个查询10次，这10次都需传同一个 taskId）	1
`--page-no`	Integer	✅	页码	1
`--page-size`	Integer	✅	每页数量	10
`--cate-id`	Long	❌	类目ID	11
`--language`	String	❌	语言，默认 en	en
`--sort-field`	String	❌	排序字段： `order1m` （最近1个月销售额）/ `buyer1m` （最近1个月买家数）	order1m
`--sort-type`	String	❌	排序规则： `ASC` / `DESC`	DESC

返回结果结构：

{
  "result": {
    "success": "true",
    "code": "200",
    "result": [
      {
        "offerId": 111111,
        "bizCategoryId": "111111",
        "offerPoolTotal": 122211
      }
    ]
  }
}

字段	类型	描述	示例值
`result.success`	String	是否成功	true
`result.code`	String	错误码	200
`result.result[].offerId`	Long	商品ID	111111
`result.result[].bizCategoryId`	String	机构的类目ID	111111
`result.result[].offerPoolTotal`	Integer	商品池总数（每个offer都返回）	122211

8. 相关性商品推荐

# 基于商品ID的相关推荐
python3 scripts/product_search.py related-recommend "offer_id" --country en

9. 上传图片获取imageId

# 上传本地图片获取imageId
python3 scripts/product_search.py upload-image "/path/to/image.jpg"

智能图片压缩功能：当上传的图片文件大于300KB时，系统会自动进行智能压缩，确保图片大小符合1688 API的要求。压缩过程会：

自动检测图片格式并转换为JPEG（如果需要）
保持最佳画质的同时将文件大小控制在300KB以内
临时生成压缩后的图片用于上传，完成后自动清理临时文件
输出详细的压缩日志（原大小 → 压缩后大小）

这确保了无论用户提供的图片大小如何，都能成功获取有效的imageId用于后续的图片搜索操作。

重要提示

图片搜索触发

当接收到"图搜同款"、"找同款"、"以图搜款"、"图片搜同款"等图片搜索相关指令时，系统会自动调用图片搜索接口（product.search.imageQuery）而非关键词搜索接口。

接口触发规则

用户意图	调用接口	说明
图搜同款、找同款、以图搜款	`product.search.imageQuery`	图片搜索
同店商品、同商家商品	`product.search.querySellerOfferList`	需从商品详情取 `sellerOpenId`
相似品、相关品、相关性推荐	`product.related.recommend`	基于商品ID推荐，部分商品可能返回空
商品推荐	`product.search.offerRecommend`	基于关键词推荐
拉取xx货盘、拉取商品货盘、拉取品池商品	`pool.product.pull`	需提供 offerPoolId 和 taskId

商品查询结果必须透出商品ID和链接

所有商品查询接口（关键词搜索、图片搜索、店铺搜索、商品推荐等）的返回结果，必须向用户展示以下两个核心字段：

offerId
（商品ID）：商品的唯一标识符，可用于后续查询商品详情、相关推荐等操作
商品链接：优先使用
```
promotionURL
```
（含追踪参数的推广链接），若无则使用
```
https://detail.1688.com/offer/{offerId}.html
```

展示格式示例（Markdown 表格或列表均可）：

商品ID: 683381849222
链接: https://detail.1688.com/offer/683381849222.html?fromkv=...（promotionURL）

禁止只展示商品标题和价格而不透出商品ID和链接，用户需要通过商品ID进行后续操作。

参数说明

通用参数

参数说明默认值可选值

--country

--language

语言代码

en

en

ja

ko

ru

vi

es

等，不支持
zh

--beginPage

起始页码

数字

--pageSize

每页数量

数字，最大50

注意：当接口参数中包含

beginPage

时，默认传

；包含

pageSize

时，默认传

；包含

country

或

language

时，默认传

en

。

⚠️ 重要：
country
和
language
参数均不支持
zh
（中文）。无论用户用中文还是英文提问，都必须传
en
（英语）作为默认值。传
zh
会导致接口报错或返回异常结果。

筛选条件 (filter)

支持多种筛选条件，多个条件用英文逗号分割：

```
shipIn24Hours
```
- 24小时发货
```
shipIn48Hours
```
- 48小时发货
```
certifiedFactory
```
- 认证工厂
```
isOnePsale
```
- 支持一件代发
```
new7
```
- 7天上新
```
1688Selection
```
- 1688严选

示例：

--filter "shipIn48Hours,certifiedFactory,isOnePsale"

排序参数 (sort)

支持按不同维度排序：

```
price
```
- 批发价
```
rePurchaseRate
```
- 复购率
```
monthSold
```
- 月销量

示例：

--sort '{"price":"asc"}'

或

--sort '{"monthSold":"desc"}'

输出格式

JSON 格式，直接返回1688 API 的原始响应数据。

重要提示：所有商品查询结果都会包含商品ID（offerId字段），这是商品的唯一标识符，可用于后续的商品详情查询或其他操作。

错误处理

失败时不会返回mock数据：当API调用失败、参数错误或网络异常时，会直接返回错误信息JSON并退出
错误格式：
```
{"error": "具体的错误信息"}
```
退出码：失败时返回退出码1，成功时返回0

商品结果字段说明

所有商品列表类接口（词搜、图搜、店铺搜索、商品推荐等）查询结果，必须展示以下所有可用字段：

字段	说明	是否必显
`offerId`	商品ID，唯一标识符	✅ 必显
`subject`	商品标题（中文）	✅ 必显
`subjectTrans`	商品标题（英文翻译）	有则显示
`imageUrl`	商品主图URL	✅ 必显
`priceInfo.price`	批发价	✅ 必显
`priceInfo.promotionPrice`	促销价	有则显示
`priceInfo.consignPrice`	代发价	有则显示
`monthSold`	月销量	✅ 必显
`repurchaseRate`	复购率	✅ 必显
`minOrderQuantity`	最小起订量	有则显示
`tradeScore`	店铺评分	有则显示
`sellerDataInfo.tradeMedalLevel`	商家等级（星级）	有则显示
`sellerDataInfo.compositeServiceScore`	综合服务分	有则显示
`productSimpleShippingInfo.shippingTimeGuarantee`	发货时效（24h/48h）	有则显示
`isOnePsale`	是否支持一件代发	为true时显示
`isSelect`	是否1688严选	为true时显示
`offerIdentities`	商品标签列表	有则显示
`sellerIdentities`	商家标签列表	有则显示

标签值含义说明（offerIdentities / sellerIdentities）

标签值含义

tp_member

诚信通会员

createDate

modifyDate

上架/更新时间

商品链接

优先用

promotionURL

，无则用

https://detail.1688.com/offer/{offerId}.html

API 接口地址

接口	完整URL
类目查询	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/category.translation.getById/${APPKEY}`
关键词搜索	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.keywordQuery/${APPKEY}`
图片搜索	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.imageQuery/${APPKEY}`
商品详情	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.queryProductDetail/${APPKEY}`
店铺搜索	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.querySellerOfferList/${APPKEY}`
商品推荐	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.offerRecommend/${APPKEY}`
品池商品拉取	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/pool.product.pull/${APPKEY}`
相关推荐	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.related.recommend/${APPKEY}`
图片上传	`POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.image.upload/${APPKEY}`

1688接口通用说明

API接入要点

语言支持: 默认使用
```
country=en
```
，但返回字段包含中英双语
- 中文字段示例:
```
subject
```
- 英文字段示例:
```
subjectTrans
```
- ⚠️ country
  和
  language
  参数均不支持
  zh
  ，可选值为
```
en
```
  /
```
ja
```
  /
```
ko
```
  /
```
ru
```
  /
```
vi
```
  /
```
es
```
  等，无论何种情况默认传
  en
Access Token: 当前解决方案产生的access_token是长久有效的
筛选条件: 支持多种商品筛选条件（发货时效、认证工厂、一件代发等）
排序功能: 支持按价格/复购率/月销量排序，但仅对当前页有效

重要限制

数据量限制: 每个查询最多返回2000个商品
图片搜索: 仅推荐使用1688图片地址，其他域名成功率不稳定
价格显示: API返回的是原价，下单时会享受营销价格

服务列表映射

```
sendGoods24H
```
→ 24小时发货
```
sendGoods48H
```
→ 48小时发货

API 参考文档

完整的 API 接口和数据结构文档请参阅 references/api.md。