- name
SKILL.md
Tệp skill vẫn nằm trong kho mã của nhà phát hành.
Dán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a cursor -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a claude-code -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a codex -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add LeoYeAI/agent-master-skills --skill 1688-product-search -a grok -yGửi tin nhắn đã sao chép trong cuộc trò chuyện Grok Bot. Bot sẽ lấy tệp SKILL.md này từ GitHub và thêm vào bộ skill mà mọi Bot của bạn dùng chung.
Install this skill: https://github.com/LeoYeAI/agent-master-skills/tree/HEAD/skills/1688-product-searchTừ nhà phát hành
通过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.mdCâu hỏi thường gặp
Tải skills/1688-product-search/SKILL.md từ nhà phát hành, hoặc sao chép đường dẫn và mở kho mã. PlugMCP chỉ liệt kê skill và không lưu trữ tệp này.
Nhà phát hành duy trì nó tại https://github.com/LeoYeAI/agent-master-skills.
Claude, Cursor, Codex và Grok Build có thể đọc tệp SKILL.md mà bạn thêm từ kho mã của nhà phát hành. Grok Bot cài đặt skill khi bạn gửi liên kết thư mục GitHub của skill trong cuộc trò chuyện.