- name
SKILL.md
Файл навыка остаётся в репозитории издателя.
Вставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a cursor -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a claude-code -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a codex -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a grok -yОтправьте скопированное сообщение в чат Grok Bot. Бот загрузит этот SKILL.md с GitHub и добавит его к навыкам, общим для всех ваших ботов.
Install this skill: https://github.com/LeoYeAI/agent-master-skills/tree/HEAD/skills/1688-product-searchОт издателя
通过1688开放平台官方API提供完整的商品搜索能力,包含9个核心接口。
每个 Skill 内置独立的鉴权模块(scripts/auth.py),不依赖任何外部 Skill。
所有 1688 Skill 的 Token 缓存指向同一个固定路径,实现"独立运行 + 鉴权只发生一次"。
skills/.1688_token_cache.json(所有 1688 Skill 共用)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"
}
}
}
}
}
如果遇到 Token 相关错误(如 401、签名失败、Token 过期),按以下步骤操作:
https://auth.1688.com/oauth/authorize?client_id=YOUR_APPKEY&site=1688&redirect_uri=YOUR_REDIRECT_URI
code 参数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(有效期约半年)ALI1688_APP_KEY = 应用的 AppKeyALI1688_APP_SECRET = 应用的 AppSecretALI1688_REFRESH_TOKEN = 上一步获得的 refresh_token(推荐,支持自动刷新)ALI1688_ACCESS_TOKEN = 上一步获得的 access_token(备用,过期需手动换)# 查询所有一级类目(英语)
python3 scripts/product_search.py category 0
# 查询中文类目
python3 scripts/product_search.py category 0 --language en
# 英文关键词搜索
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"}'
图片搜索支持三种方式,优先级:本地图片文件 > 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")。
推荐处理策略:
alicdn.com,直接用 imageAddress 字段图搜(已验证有效)alicdn.com,先下载到本地,再 base64 上传尝试获取 imageId;若 imageId 仍为 "0",降级用 imageAddress 图搜本地文件 base64 上传流程(仅供参考,成功率有限):
product.image.upload 接口(uploadImageParam 字段包装,内含 imageBase64)上传"0"),用 imageId 图搜;否则降级用 imageAddress 图搜当用户提供图片 URL 时的处理流程:
alicdn.com 域名(如 cbu01.alicdn.com、img.alicdn.com 等):直接用 imageAddress 字段传入图搜接口,无需下载alicdn.com 域名(如用户上传的图片、其他电商平台图片等):先将图片下载到本地临时文件,再走本地文件图搜流程(压缩 → base64 → 上传 → imageId → 图搜)⚠️ 注意:该接口每次只支持查询 1 个商品,不支持批量查询多个商品ID。
# 查询单个商品详情
python3 scripts/product_search.py product-detail "offer_id"
# 根据商家ID搜索商品
python3 scripts/product_search.py shop-search "seller_open_id" --country en
# 基于关键词的商品推荐
python3 scripts/product_search.py offer-recommend "keyword" --country en
从业务定制的品池中拉取商品列表,需要有品池访问权限。分页查询时需固定同一个 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
请求参数:
返回结果结构:
{
"result": {
"success": "true",
"code": "200",
"result": [
{
"offerId": 111111,
"bizCategoryId": "111111",
"offerPoolTotal": 122211
}
]
}
}
# 基于商品ID的相关推荐
python3 scripts/product_search.py related-recommend "offer_id" --country en
# 上传本地图片获取imageId
python3 scripts/product_search.py upload-image "/path/to/image.jpg"
智能图片压缩功能:当上传的图片文件大于300KB时,系统会自动进行智能压缩,确保图片大小符合1688 API的要求。压缩过程会:
这确保了无论用户提供的图片大小如何,都能成功获取有效的imageId用于后续的图片搜索操作。
当接收到"图搜同款"、"找同款"、"以图搜款"、"图片搜同款"等图片搜索相关指令时, 系统会自动调用图片搜索接口(product.search.imageQuery)而非关键词搜索接口。
所有商品查询接口(关键词搜索、图片搜索、店铺搜索、商品推荐等)的返回结果,必须向用户展示以下两个核心字段:
offerId(商品ID):商品的唯一标识符,可用于后续查询商品详情、相关推荐等操作promotionURL(含追踪参数的推广链接),若无则使用 https://detail.1688.com/offer/{offerId}.html展示格式示例(Markdown 表格或列表均可):
商品ID: 683381849222
链接: https://detail.1688.com/offer/683381849222.html?fromkv=...(promotionURL)
禁止只展示商品标题和价格而不透出商品ID和链接,用户需要通过商品ID进行后续操作。
注意:当接口参数中包含 beginPage 时,默认传 1;包含 pageSize 时,默认传 20;包含 country 或 language 时,默认传 en。
⚠️ 重要:
country和language参数均不支持zh(中文)。无论用户用中文还是英文提问,都必须传en(英语)作为默认值。传zh会导致接口报错或返回异常结果。
支持多种筛选条件,多个条件用英文逗号分割:
shipIn24Hours - 24小时发货shipIn48Hours - 48小时发货certifiedFactory - 认证工厂isOnePsale - 支持一件代发new7 - 7天上新1688Selection - 1688严选示例:--filter "shipIn48Hours,certifiedFactory,isOnePsale"
支持按不同维度排序:
price - 批发价rePurchaseRate - 复购率monthSold - 月销量示例:--sort '{"price":"asc"}' 或 --sort '{"monthSold":"desc"}'
JSON 格式,直接返回1688 API 的原始响应数据。
重要提示:所有商品查询结果都会包含商品ID(offerId字段),这是商品的唯一标识符,可用于后续的商品详情查询或其他操作。
{"error": "具体的错误信息"}所有商品列表类接口(词搜、图搜、店铺搜索、商品推荐等)查询结果,必须展示以下所有可用字段:
country=en,但返回字段包含中英双语
subjectsubjectTranscountry 和 language 参数均不支持 zh,可选值为 en / ja / ko / ru / vi / es 等,无论何种情况默认传 ensendGoods24H → 24小时发货sendGoods48H → 48小时发货完整的 API 接口和数据结构文档请参阅 references/api.md。
>-
---name: 1688-product-searchdescription: >----# skills/1688-product-search/SKILL.mdFAQ
Скачайте skills/1688-product-search/SKILL.md у издателя или скопируйте путь и откройте репозиторий. PlugMCP только показывает навык в каталоге и не хранит файл.
Издатель хранит его в https://github.com/LeoYeAI/agent-master-skills.
Claude, Cursor, Codex и Grok Build могут читать SKILL.md, который вы добавляете из репозитория издателя. Grok Bot устанавливает его, когда вы отправляете в чат ссылку на папку навыка на GitHub.